Atari ST Use and care manual

COMPUTED
Technical Reference Guide
ATARLST
VOLUME THREE
------------------------------------------------ Sheldon Leemon
our passport to TOS, the input/output and fast
graphics operating systems underlying GEM.
Includes fully commented C and machine language
programming examples. For the intermediate-to-
advanced-level Atari ST programmer.
COMPUTE! Books

COMPUTED
Technical Reference Guide
ATART ST
VOLUME THREE
TOS
Sheldon Leemon
COMPUTE! Books
Greensboro, North Carolina
Radnor, Pennsylvania

Editor: Robert Bixby
Copyright 1988, COMPUTE! P blications, Inc. All rights reserved.
Reprod ction or translation of any part of this work beyond that permitted
by Sections 107 and 108 of the United States Copyright Act witho t the
permission of the copyright owner is nlawf l.
Printed in the United States of America
10 987654321
Library of Congress Cataloging-in-P blication Data
(Revised for vol me 3)
Leemon, Sheldon.
Comp ters technical reference g ide, Atari ST.
Incl des indexes.
Contents: v. 1. VDI — v. 2. GEM, AES — v. 3. TOS.
1. Atari ST comp ters. I. Title. II. Title:
Atari ST.
QA76.8.A824L44 1987 004.165 87-401655
ISBN 0-87455-149-8 (pbk. : v. 3)
The a thor and p blisher have made every effort in the preparation of this book to
ins re the acc racy of the information and programs. However, the information and
programs in this book are sold witho t warranty, either express or implied. Neither
the a thor nor COMPUTE! P blications, Inc. will be liable for any damages ca sed
or alleged to be ca sed directly, indirectly, incidentally, or conseq entially by the
information or programs in this book.
The opinions expressed in this book are solely those of the a thor and are not nec
essarily those of COMPUTE! P blications, Inc.
COMPUTE! Books, Post Office Box 5406, Greensboro, North Carolina
27403, [phone], is a Capital Cities/ABC, Inc. company and is not as
sociated with any man fact rer of personal comp ters. Atari, ST, ST
BASIC, 520ST, 1040ST, and TOS are trademarks or registered trademarks
of Atari Corporation. GEM is a trademark of Digital Research, Inc.

Contents
Foreword .................................................................................... v
Chapters
1. The ST Operating System: An Overview .......................... 1
2. BIOS .........................................................................................
3. XBIOS Device and System Functions .............................. 27
4. XBIOS Graphics and Sound Functions ............................ 61
5. GEMDOS Device I/O and Process Control ................... 85
6. GEMDOS File System Functions ................................... 10
7. Line A Routines ................................................................. 133
Appendices
A. BIOS Functions ................................................................. 171
B. XBIOS Functions............................................................... 187
C. GEMDOS Functions ........................................................ 235
D. Error Codes ........................................................................ 2 1
E. VT-52 Console Escape Sequences ................................. 2 6
F. The MFP C hip................................................................... 2
G. System Characters............................................................. 30
H. The Line A Variable Table .............................................. 317
I. The Intelligent Keyboard Controller ............................ 337
J. Keycodes ............................................................................ 381
K. ST Memory Map ............................................................... 387
Function Index ..................................................................... 403
Index .........................................................................................407

Fore ord
C O M P U T E ! ’ S Technical Reference Guide, Atari
ST—V lume Three: TOS is the third information-packed ST
book from noted Atari ST author Sheldon Leemon. Inside
you'll find complete information on the Basic Input/Output
System (BIOS), the GEM Disk Operating System (GEMDOS),
extended Basic Input/Output System (XBIOS), and Low-level
(line A) graphics, as well as an exhaustive reference section
explaining each BIOS function, program examples in C and
machine language, and a complete memory map.
You may recall with what fanfare the ST was introduced.
It was widely called the "Jackintosh," a nickname combining
the name of the Macint sh (they have similar user interfaces)
with Jack, for Jack Trammiel, its creator. Despite its promise,
early applications for the machine were simply games and
programs ported over from lesser machines.
Over the years, however, programmers have come to
recognize that the ST is not only lightning fast and highly so
phisticated, but it is also programmable on several tiers of its
operating system.
At the heart of the ST is the same famed Motorola 68000
microprocessor that drives the Macintosh, and the Amiga.
Over the chip is BIOS, XBIOS, and TOS (collectively known
as TOS, or the Trammiel Operating System). Above these are
the AES and the VDI, the high-level interfaces that make up
the GEM interface from Digitial Research. The AES and VDI
were the subjects of the first two books in this series. Most
programmers prefer to program through GEM. It's fast and
friendly. With a minimum of fuss, it provides the maximum
of features, such as reading the mouse position and provid
ing menus and other services.
But faster still, and not lagging far behind in ease of use,
is TOS. You can use it to provide your own creative uses of
graphics, printer functions, and the disk operating system,

just as GEM does, but with true 68000 speed and with no
intermediary levels of operating systems.
If you're a serious ST programmer, you probably already
own highlighted, dogeared copies of the first two books in
this series. This book will complete your collection and lead
you into hitherto unsuspected levels of programming. If you
are only beginning to explore the world inside your ST, this
book is an excellent starting point.

\
Chapter 1
The ST Operating
System: An
Overvie

A comp ter’s operating system is an orga
nized collection of small built-in programs that enables the
computer to communicate with external devices, such as the
keyboard, display screen, and disk drive, and to perform
fundamental tasks like loading and running an application
program. While most people regard GEM as the ST's operat
ing system, it's just a friendly user interface on top of a more
conventional operating system to make the computer easier
to program and to operate. While GEM provides higher level
functions like support for drop-down menus, dialogs, and
icons, it still must rely on a set of low-level operating system
routines for tasks such as reading a file from the disk drive.
It is this set of low-level routines that shall be referred to as
TOS.
TOS Organization
The ST operating system is contained in a set of TOS ROM
(Read-Only Memory) chips that contain a total of 1 2 kilob
ytes of program code and data. The name TOS may have at
one time stood for The Operating System, but is now more
commonly thought of as an acronym for Tramiel Operating
System, named after the Tramiel family that now owns Atari.
The TOS ROMs contain all of the ST's system software. This
includes:
GEM This software provides ST applications
with a consistent user interface, fea
turing drop-down menus, multiple
windows, icons, and dialog boxes.
GEM is divided into the VDI (which
provides low-level graphics calls), AES
(which provides user services like
menus), and the GEM Desktop pro-

CHAPTER 1
gram, (which provides the desktop
metaphor for working with the disk
filing system). The VDI and GEM AES
were subjects of earlier books in this
series by the same author. These
books are also available from COM
PUTE! Books.
BIOS The Basic Input/Output System (BIOS)
is a collection of low-level I/O routines
that are not necessarily specific to the
ST hardware. They include routines to
communicate with character-oriented
devices like the keyboard, screen, and
printer, and to communicate with disk
drives on the sector level. They also
include routines to check which disk
drives are available, if a disk has been
removed from the drive, and so on.
XBIOS XBIOS, the extended Basic Input/Out
put System is a set of hardware-spe
cific I/O-related routines. There are
routines for finding and changing the
address of screen display memory, for
setting the hardware color registers,
for waiting for the vertical blanking
interval, and for accessing the sound
chip. There are also routines for com
municating with the 68 01 Multi-Func
tion Peripheral (MFP) chip.
GEMDOS (or BDOS) This is a set of functions used to im
plement the higher level disk filing
system, which closely follows the
model of MS-DOS. These routines al
low the user to access the disk device
on the file level, rather than directly
reading specific physical sectors on
the disk. They allow the user to per
form functions like reading the disk
directory, creating or deleting a subdi
rectory, deleting a file, renaming a
file, and so on. The GEMDOS also
contains miscellaneous routines for
4

The ST Operating System: An Overview
Line A routines
Exception Handlers
Startup Code
communicating with the character de
vices like the screen, keyboard,
printer, and serial port.
Line A routines are the low-level
graphics routines the GEM VDI calls
for basic graphics functions. These
functions include setting and reading
individual pixels, drawing lines and
filled polygons, and moving s ftware
sprites, like the mouse pointer. Since
the ST screen is bitmapped, the line A
routines are also used for drawing all
text characters on the screen. Using
the line A routines for graphics and
text provides greater compatibility
than accessing the ST graphics hard
ware directly, because such programs
will continue to function correctly
even if the ST graphics hardware
changes. For example, programs that
use the line A routines can take ad
vantage of the blitter chip used by
later ST models, while programs that
write to screen memory directly can
not.
Many of the Operating System rou
tines are invoked by interrupts and
trap instructions, which in 68000 par
lance are referred to as excepti ns. For
example, the BIOS routines are called
via the TRAP #13 instruction, GEM
DOS routines via the TRAP #1 in
struction, and GEM AES and VDI rou
tines are called via the TRAP #2
instruction. In addition to the han
dlers that route these calls, there are a
number of lower-level interrupt han
dlers, such as the vertical blank inter
rupt handler, which are of interest to
programmers.
The startup code is a short piece of
program code that is called when the
/

CHAPTER 1
computer is first turned on, or the re
set button is pushed. It checks for
ROM cartridges, configures the I/O
ports and the screen, tests memory
size, sets the exception handler vec
tors, executes the programs in the
AUTO folder, and jumps to the GEM
Desktop program.
Since all of the GEM code is included in the ROMs, it
will be considered as part of TOS. For purposes of this book,
however, TOS will be considered to be everything in the
ROMs except GEM.
Calling TOS from Machine Language
The various TOS routines are called via the exception vec
tors. When programming in machine language, the general
procedure is to push the function number and other function
parameters on the stack, issue a TRAP instruction, and then
remove the parameters from the stack. The specific TRAP in
struction depends on the type of TOS routine you're calling.
The BIOS routines are called with a TRAP #13 instruction,
the XBIOS with a TRAP #14, and the GEMDOS routines
with TRAP #1. A call to the BIOS routine Bconstat() would
look like this:
move.w #2, — (sp) * p sh device n mber for console device
move.w #1, — (sp) * p sh f nction n mber for Bconstat
trap #13 * call BIOS
addq.l #4,sp * p ll the parameters off the stack
Note that if you plan to use GEM calls in your machine
language application, you'll need to do some preparatory
work at the beginning of the program. When GEMDOS
starts an application program (but not a desk accessory), it
allocates all of the system memory to that program. There
fore, if a program uses the system memory-management
calls, or any of the GEM AES calls that themselves allocate
memory, or runs another program using the Pexec() func
tion, at startup time it must deallocate all of the memory it
isn't actually using. This is done using the GEMDOS
Mshrink() function. Complete details and some sample code
can be found in Chapter 5 in the section dealing with
6

The ST Operating System: An Overview
Mshrink(). For now, it is sufficient to know that this step is
necessary for programs using GEM or memory-management
calls, and not for programs that only use TOS function calls.
Calling the TOS Routines from C
It's much simpler to call the TOS routines from C than from
machine language, since most C compilers for the ST include
library routines for the BIOS, XBIOS, and GEMDOS calls.
These library routines make calling TOS routines exactly like
calling any other kind of C routines. For example, the library
call bios() issues the TRAP #13 command after the parame
ters have been pushed on the stack. To call the BIOS routine
Bconin() to get a character from the console device (device
2), you need only use the statement:
bios(l,2);
Many C compilers include a header file called OS-
BIND.H. This header file contains C macro definitions for the
various BIOS, XBIOS, and GEMDOS commands. For exam
ple, the macro Bconstat(a) is defined as follows:
#define Bconstat(a) bios(l,a)
Therefore, if you've #included the OSBIND.H file in
your program, you could replace the bios(l,2); statement
with:
Bconstat(2);
Since this is more readable than the bios() call, the ma
cro format will be used wherever possible. Just remember
that in order for the compiler and linker to understand these
macros, you must use the #include directive to add the OS
BIND.H file first.
C programmers usually don't have to worry about re
leasing extra memory with the Mshrink() command, or set
ting the program stack, since this work is done for them by
the compiler's own startup code. This code is found in the
GEMSTART.O or APPSTART.O module linked in by Alcy n
C programmers, and in the INIT.O module of the SYSLIB li
brary of Megamax C. You should note, however, that in some
extreme cases, you may have to recompile the startup mod
ule to give back more or less memory than the default mod
7

CHAPTER 1
ule. Again, more details about the Mshrink() function are
provided in Chapter 5.
About the Examples
Because it's easy to make GEM calls from C, and because the
language produces programs that are relatively small in size
and quick in execution for a high-level language, it has be
come the language of choice for software development on
the ST. For this reason, most of the examples in this book
will be written in C. On occasion, however, machine lan
guage examples will be included as well, to show how the C
examples may be translated to that environment. The macro
names for the C functions will be used here as they appear
in the official Digital Research GEM header files, since they
have been adopted by the manufacturers of other C compi
lers as well.
The C programs in this book are designed to work specif
ically with the Alcy n C compiler, the compiler officially sup
ported by Atari, and with Megamax C, which also provides a
very complete development environment. For these compi
lers, the int data type refers to a 16-bit word of data. Some
other compilers, such as the Lattice C compiler, use a 32-bit
integer as the default data type. When compiling the pro
grams in this book with such compilers, substitute sh rt for
each reference to int, and keep in mind that the default size
for function returns and constants may be 32 bits instead of
16. For the sake of simplicity, the portability macros such as
WORD were not used. These macros use the C preprocessor
to define a 16-bit data type that will be valid for any compi
ler. The reader is free to use the macros if they are seen as
more convenient.
The machine language examples were all created with
the assembler included in the Atari development package,
but they should be so generic as to assemble unchanged with
almost any good 68000 assembler.
8

Chapter 2
BIOS

The lowest-level ST Input/Output routines
are in the section of the operation system known as the BIOS
(Basic Input/Output System). The BIOS contains three basic
types of I/O routines.
The first group of I/O routines contains routines for com
munication with character-oriented I/O devices like the
printer, the screen, the serial port, and MIDI port. The sec
ond group contains the basic functions used to communicate
with the disk drive at the hardware level. These allow you
determine how many drives are connected, whether a disk
has been changed in a drive, and where to find the BIOS pa
rameter block for a drive, which gives information about the
drive configuration. They also let you read or write to the
disk at the sector level, which is a lower level of organization
than the normal disk filing system. Finally, the BIOS con
tains some miscellaneous routines that perform various sys
tem functions, such as reading or setting the exception vec
tors and returning information about the memory
management system and the precision level of the system
clock.
The ST BIOS routines can be called from user mode, and
are reentrant to three levels. They use registers A0-A2 and
D0-D2 as scratch registers, which means if you're program
ming in machine language and using these registers to store
important information, you must save their contents before
making a BIOS call and restore them after the BIOS call.
Each of the BIOS routines has a command number associated
with it. It may also be associated with command parameters
that specify more precisely what the function should do.
For example, the BIOS function to output a character to
a device is command number 3. It requires two command pa
rameters: One tells the function which character to print and
the other specifies the output device to use.
11

CHAPTER 2
To call a BIOS function from machine language, you
must push the command parameters onto the stack, followed
by the command number, and execute a TRAP #13 state
ment. The TRAP #13 instruction puts the program into su
pervisor mode and begins executing the instructions found at
the address stored in exception vector 45, whose address is
180 ($B4). This exception vector contains the address of the
BIOS handler, which reads the command number on the top
of the stack and directs program execution to the appropriate
function. When the function terminates, the program returns
to user mode, and the results, if any, are returned in register
DO. When a BIOS function call is completed, the calling pro
gram is responsible for adjusting the stack to remove the
command parameters and command number. You should
note that the BIOS changes the command number and return
address on the stack.
The following program fragment demonstrates sending
the character X to the console device using BIOS command
number 3:
move.w # /X/, — (sp) * p sh character val e on stack
move.w #2, —(sp) * p sh console device n mber on stack
move.w #3, — (sp) * p sh BIOS command n mber on stack
trap #13 * call BIOS handler
addq.l #6,sp * pop parameters (6 bytes) off stack
Calling the BIOS routines from C is much simpler. Most
C compilers come with a library routine called bios(), which
stacks the parameters and executes the TRAP #13 instruc
tion. For example, the sample call illustrated above could be
accomplished in C by the single statement
bios(3,2/X');
Since it's easier to remember a command name than a
command number, most C compilers include a header file
called OSBIND.H which defines macros for all of the BIOS
functions. For example, the macro definition for BIOS com
mand 3 is
#defme Bcono t(a,b) bios(3,a,b)
Therefore, after you #include OSBINDS.H in your pro
gram, call your sample function like this:
Bcono t(2,'X');
12