THE TT COMPANION: DEVELOPER'S NOTES FOR THE ATARI TT030
THE TT COMPANION: DEVELOPER'S NOTES FOR THE ATARI TT030
This document (hopefully) contains all the information a developer should have concerning the TT030, in addition to the existing ST and STe documentation. Complete TT030 documentation will be available in the future.
OVERVIEW
A TT is an ST running on a 16MHz 68030, with the following changes (in broad terms):
- Additional RAM expandability, with fast, nybble-mode RAM.
- SCSI DMA for SCSI hard disks and other devices.
- DMA digital stereo sound (as found in the STe).
- Addition of a 68881/68882 floating-point coprocessor.
- Additional video modes (details later).
- Addition of an 8530 SCC (serial communications controller), giving a Localtalk connector (with DMA) and one extra serial port, or two extra serial ports.
- Internal speaker.
All this new hardware required some changes to the internal software, particularly in the BIOS. GEMDOS changed a little. Changes to AES and VDI are only those required to support the new resolutions, and changes to the desktop to allow cache control.
THE NEW HARDWARE
THE 68030
You should get the 68030 user's manual by Motorola: MC68030UM/AD REV 1, "Enhanced 32-Bit Microprocessor User's Manual, Second Edition" is the book we use at Atari. The 68030 will run user-mode-only 68000 programs without trouble, with one slight hitch: the move from SR instruction is now privileged. Some compilers, notably Alcyon C 4.14, use this instruction. The BIOS has a handler for the privilege violation exception, which checks for this instruction: it replaces the instruction with a move from CCR and tries running it again. This is sufficient for most programs.
Authors of programs which perform supervisory operations (e.g. respond to traps) need to know about one other, crucial change: the exception stack frame format is changed. There is an extra word on the stack after the return SR and PC. That means that if a trap was made from supervisor mode, the arguments the caller pushed are one word farther away from the top of the stack than they are on a 68000. This is the case for all 680x0 processors except 68000. There is a new system variable, _longframe, at $59e: if this word is nonzero, you are running on a CPU which uses the long stack frame format. (See the Cookie Jar documentation for the way to tell what CPU you're running on.)
The 68030 also has two caches: an instruction cache and a data cache. Details on them are available in the 68030 documentation. TOS boots with the cache off, but there is an option on the Desktop to enable it (just like the Blitter switch on a Mega). Programs normally do not notice the presence of the cache (except that they run faster!), but programs which modify memory, then execute it (e.g. self-modifying code) will need examination, and any program which uses DMA directly (as opposed to making the BIOS or XBIOS calls) needs to invalidate the caches after the DMA operation completes, before accessing the memory which may have been changed by the DMA.
The 68030 has a full 32-bit address bus, not the 24-bit bus of the 68000. Programs using the high 8 bits of addresses for any reason (e.g. a type field for a pointer) will not run on the TT.
Naturally, the 16MHz 68030 with a 32-bit data bus runs faster than the 8MHz 68000 with a 16-bit data bus. Programs which rely on instruction timing will not run correctly.
MEMORY
There are three kinds of memory in a TT.
- ST RAM is dual-purpose RAM, shared between the CPU and all the ST devices (video, ACSI DMA, DMA sound). The machine comes with 2MB of this kind of RAM, and in the future will be expandable with another 2MB of this RAM.
- TT RAM is single-purpose RAM: it is not shared among the ST-compatible devices. Accesses to it are faster because the CPU never has to wait for its turn. It's also faster because it is "nybble mode" RAM, meaning the 68030 can use "burst fill" accesses to rapidly fill its caches. It is not visible to ACSI DMA, DMA sound, or video. It is visible to the CPU and to SCSI DMA. The TT030 has room for one TT RAM board containing 4MB.
- VME RAM is memory which exists on the VME bus. Because it goes through the VME bus, and because the VME bus data path is only 16 bits wide, it is about the same speed as ST RAM. It is visible only to the CPU. (It's not even visible to SCSI DMA, because that requires a 32-bit data path.)
SCSI DMA
A SCSI (Small Computer System Interface) bus is available on the TT. What this means to developers and purchasers is that almost any SCSI hard disk drive can be connected to a TT with a minimum of trouble. The Atari hard-disk utilities can recognize, format, partition, and install (make bootable) almost any SCSI drive. (SCSI, though a standard, is not always implemented the same way by all vendors, and it is possible that some nominally SCSI drives won't work with the TT.)
There are other types of SCSI devices than hard disks. Streaming tapes, 9-track tapes, and network node connection devices are available, along with other types of devices. These will connect just fine to the TT, but the vendor, a value-added reseller, or the user will have to come up with the drivers for them.
There is one internal SCSI connection in the TT; it's a 50-pin connector for a ribbon cable, and there's room for a 3-1/2" drive inside. In addition, there is a 25-pin external SCSI connector which is compatible with the other 25-pin SCSI connectors in the industry (read "Mac"). You should be able to buy such a hard drive "off the shelf" and plug it right in to a TT.
DMA SOUND, INTERNAL SPEAKER
The DMA sound features of the TT are just like those of the STe series. The hardware registers are at the same addresses and have the same functions. The audio signal from the DMA sound system and the ST-compatible sound generator are (optionally) mixed in the volume/tone controller and sent to the internal speaker and to the left/right RCA jacks on the back of the machine. A software switch is provided to disable the internal speaker: it's bit 6 in Port A of the PSG's general-purpose output registers.
68881
The TT comes with a Motorola 68881 floating-point coprocessor. This can be used by programs to do floating-point computations very quickly. No provision is made for sharing this, however, so it should not be used by accessories or from interrupts. (Multitasking systems will have to save and restore the state of the 68881 just like they save and restore the state of the CPU registers when changing from one process to another.)
VIDEO
The TT supports all three of the ST video modes, plus three new ones.
The modes are as follows:
ST LOW 320x200 16 colors
ST MEDIUM 640x200 4 colors
ST HIGH 640x400 2 colors (not just black & white)
TT LOW 320x480 256 colors
TT MEDIUM 640x480 16 colors
TT HIGH 1280x960 black and whiteAll the ST resolutions, and the two color TT resolutions, are displayable on the same kind of monitor. TT HIGH resolution (1280x960) is available only on special monitors; appropriate monitors or a list of vendors and models which are compatible will be available from Atari.
The color palette is like the STe: four bits each for red, green, and blue, giving a total of 4096 colors. In the ST-compatible color look-up table (CLUT) at $ffff8240 (same as on the ST and STe), the high bit of each nybble is the _low_ bit of the corresponding gun value for red, green, and blue. In addition, at a new address ($ffff8400), there is a 256-entry CLUT with the bits in the more natural order. In the 16-color modes (and the 4-color mode), the 256-color CLUT is divided into 16 "banks," and only one of these "banks" is active at any time. It is the active bank which is visible in the 16-entry ST-compatible CLUT. Changing banks requires only one write to the video chip, so you can use the bank system to change all 16 colors at once. There are new XBIOS calls for accessing the color tables and shifter mode registers.
ST HIGH resolution is now called "duochrome" on the TT because you can display any two colors, not just black and white. The two colors which are displayed are the last two in the 256-entry CLUT. In addition, a bit is used to invert the display, just like the ST's high-resolution mode. The bit in question is bit 1 (not bit 0) of the first entry in either CLUT.
The existence of the new video modes will reveal the lazy programming practices of developers who make assumptions about the screen, like its resolution, the number of colors available, and the size of the screen image in memory. It has always been possible to use the VDI enquire functions, or even examine the Line-A variable space, to determine the characteristics of the display. Even writing "resolution-independent" code which calls Getrez() is not good enough, since Getrez() will return values for the new modes which were impossible (and therefore unanticipated) on an ST.
In general, only the most careful programmers have avoided all assumptions in this area. Programs which use AES/VDI exclusively will often work in the new modes, allowing their users to take advantage of the larger screen space, colors, etc. Other programs will need to be modified, or will be restricted to running in the ST-compatible modes.
SCC AND OTHER SERIAL PORTS
The TT has three new serial ports. Two of them come from the 8530 SCC (Serial communications Controller): these have all the modem control signals. One of those shares the hardware with the Localtalk-compatible LAN (local-area network) connector: you can use either LAN or that serial port, but not both at the same time.
The other new port comes from the new 68901 MFP. It works just like the ST-compatible port, except that it only has transmit, receive and ground signals: there are no modem control signals on that port.
The BIOS has support for all of these ports, including XON/XOFF or RTS/CTS flow control, and provisions for compatiblity with existing programs. See the documentation for the Bconmap call for more. (Naturally, the new 68901 port doesn't support RTS/CTS, since these signals are not available.)
TOS CHANGES
The TOS version number for the first release of TT TOS is TOS 3.0. Until that ROM is finalized, all TT ROMs will have TOS version number 3.0, and finer distinctions will be made with the date code in the OS header. The first release of TOS ROMs for the TT (called TTOS) has the date 03011990 (March 1, 1990).
GEMDOS CHANGES
TWO KINDS OF RAM
This section will discuss the concept of "alternative RAM" in general first, and gets to the specifics as the relate to the TT later.
In the TT and other ST-like machines planned for the future, there are two general kinds of RAM: there is ST RAM, which is ST-compatible, and there is "alternative RAM," which is not. Exactly how it is not varies by machine and type of RAM. Primarily, the video chip can only display screen data from ST RAM, and the DMA sound chip can only play data stored in ST RAM. Secondarily, other chips which access memory, like ACSI DMA (for ST hard disks and other devices) and SCSI DMA (for SCSI devices), may not be able to get at alternative memory directly. This affects most programs not at all, since they use BIOS and GEMDOS calls to accomplish this kind of transfer, and the device driver is responsible for getting the data from here to there transparently, no matter where "here" and "there" are.
The "rules for eligibility" for a program running in alternate RAM are:
- It must not try to set the screen base address in alternative RAM, or play DMA sound from there.
- It must not try to make a device driver do DMA from or to there, unless the device driver knows about the differences between ST RAM and alternative RAM.
- It must not try to do DMA itself from or to there (only specialized device drivers do this).
The second point is a bit sticky: it refers to the fact that existing DMA device drivers don't know about the restrictions on alternative RAM. Atari, of course, has come out or will come out with hard-disk, laser printer, and CD-ROM drivers which do understand the distinctions.
Since programs written before there was any concept of alternative RAM don't know if they break the rules or not, you, the user, must inform GEMDOS as to whether a program is eligible to use alternative RAM, or must use ST RAM. As a finer distinction, you can select the eligibility for program loading and Malloc() calls separately. A program which Malloc's a screen buffer might still be eligible to _load_ into alternative RAM, but its Malloc() calls must be satisfied from ST RAM.
THE SPECIFICS ON TWO KINDS OF RAM
As of TOS 1.4, one of the reserved longwords in the header of executable files (PRG, TTP, TOS) acquired a meaning: the bits there control the way GEMDOS treats that program. (The least-significant bit of that longword (bit 0), when set, means GEMDOS need not clear all of RAM when loading that program, only the program's declared BSS. This makes programs load faster.)
The next two bits have been assigned meanings relating to alternative RAM. Bit 1, when clear, means that the program must be loaded into ST RAM; bit 2, when clear, means that Malloc calls by that program must be satisfied using ST RAM.
When one of these bits is set, the corresponding operation (program load, Malloc call) may be satisfied from "alternative" RAM. In general, alternative is considered preferable to ST RAM. If a program doesn't break any of the rules for eligibility in alternative RAM, it is desirable to set those bits in its header.
If TT RAM is eligible to satisfy a request, but there isn't enough of it available, the request will come from ST RAM. If there isn't enough of _that_, the request fails.
For loading programs, "enough" RAM is a relative thing. For one program, it's more important to run fast than it is to have a lot of memory, so "enough" RAM is, say, 64K more than its own declared requirements (that is, 64K for stack+heap). For another, having lots of RAM is more important, even if it means not running as fast as possible.
The current solution is provisional, and might change: a program which is eligible for TT RAM will be loaded there if there's more room in TT RAM than in ST RAM, or if there's more than 512K of TT RAM available. This means that if there's less than 512K available in TT RAM and more than 512K available in ST RAM, the program gets loaded in ST RAM. This can be changed by the parent (that is, the program calling Pexec): a new field in the basepage, p_minfast, has been defined as the number of bytes to consider a "big enough" space to load a program in TT RAM. The field is one byte long, at offset 0x36 in the basepage, and represents the minimum acceptable size for program loading _divided by 64K_. That is, a value of 2 means 128K is acceptable; a value of 16 means at least a megabyte must be available in TT RAM to make it acceptable. As mentioned above, this is not necessarily the final implementation: it is subject to change.
NEW XBIOS CALLS
XBIOS 0x2a: DMAread
0x2b: DMAwrite
long DMAread(sector,count,buffer,devno)
long sector;
word count;
void *buffer;
word devno;Reads sectors from the device into memory. Works for ACSI and SCSI devices. For SCSI, does not actually use DMA: handshakes the bytes across. Device numbers are:
$0-$7 ACSI devices $0-$7
$8-$f SCSI devices $8-$f
other reserved for future useReturns a BIOS error code.
DMAwrite is the same, but writes sectors. These calls assume that the memory at 'buffer' can actually be accessed by the bus the device is on. Therefore, DMAread from an ACSI device into alternative RAM won't work.
Also, see the Bconmap documentation, on a separate sheet.
Also, see the documentation for the new video calls EsetShift, EsetPalette, etc., on still another sheet.
OTHER IMPORTANT NOTES
The Line-A graphics interface is maintained for backward compatibility with existing ST programs only. It should not be used for new programs. It will not keep pace with future hardware or software improvements. The VDI should be used.
