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.

o	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.

o	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.

o	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 white

All 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:

(1)	It must not try to set the screen base address in
	alternative RAM, or play DMA sound from there.

(2)	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.

(3)	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 use

Returns 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.

