The Atari™ Compendium - Atari Documentation Archive

842 Pages·2007·2.56 MB·English

atariforge.org
dev-docs.atariforge.org
The Atari™ Compendium
©1992 Software Development Systems
Written by Scott Sanders
Not for Public Distribution
Introduction
The following pages are a work in progress. The Atari™ Compendium (working title) is designed to be a
comprehensive reference manual for Atari software and hardware designers of all levels of expertise. At the
very least, it will (hopefully) be the first book available that documents all operating system functions,
including any modifications or bugs that were associated with them, from TOS 1.00 to whatever the final
release version of Falcon TOS ends up being. GEMDOS, BIOS, XBIOS (including sound and DSP calls),
VDI, GDOS, LINE-A, FSM, AES, MetaDOS, AHDI and MiNT will be documented. Hardware
information to the extent that information is useful to a software programmer will also be covered. This
volume will not include hardware specifications used in the creation of hardware add-ons, a programming
introduction designed for beginners, or an application style guide. All of the aforementioned exclusions will
be created separately as demand for them arise. In addition, I also plan to market a comprehensive spiral-
bound mini-reference book to complement this volume.
By providing early copies of the text of this volume I hope to accomplish several goals:
1. Present a complete, error-free, professionally written and typeset document of reference.
2. Encourage compatible and endorsed programming practices.
3. Clear up any misunderstandings or erroneous information I may have regarding the information
contained within.
4. Avoid any legal problems stemming from non-disclosure or copyright questions.
A comprehensive Bibliograpy will be a part of this volume. For now you should know that I have mainly
relied on five major sources of information:
1. Atari Developer Documentation, including, but not limited to, original OS docs, release notes,
newsletters, and technical support.
2. Compute’s AES/TOS/VDI series. This series seems to be the most complete English reference
available, however, its usage is limited by the fact it is only current as of TOS 1.02
3. Lattice C Atari Library Manual and Addendum
4. Atari Profibuch - Excellent German text.
5. Developer Roundtable on GEnie and Compuserve.
How to Edit...
Below are some simple suggestions as to how to notate any changes you would like to see made. I understand
you are probably just as busy as I usually am so if you can’t take the time to follow these steps, ragged
handwriting in the corner would be just as appreciated.
Included in your package should be seven items:
1. This introduction letter.
2. A binder.
3. Revision notes
4. Looseleaf notebook paper.
5. Two highlighter pens
6. Dividers
7. The latest revision of the text
If you are missing any items, please contact me.
Each revision will be accompanied by a set of revision notes. These will highlight what to look for, what I
already know is wrong and am planning to change, and what has changed since last time.
The looseleaf notebook paper should be used to make general suggestions as to content, style
(writing/typesetting), and so on....
When proofing the text use the blue highlighter to circle spelling, grammar, or style errors (any typo). The
green highlighter is for blatant errors or misunderstandings where an explanation is necessary. Please notate
the error and correction in the margins. If it is a very large misunderstanding beyond simply writing it down,
please call me or E-Mail me.
Also, as a part of the volume will be a listing of standard conventions. The following is a brief listing of
conventions used in the book:
Typestyle Meaning
The quick brown fox.... Normal Text
WORD appl_init(VOID) Function Definitions
mode, flag, ap_id program/system variables
WORD, TOS, WM_CLOSED macros, typedef’s, define’s, OS components
typedef struct { Program listings/bindings
A basic explanation is listed... Text in tables
CTRL-G Keyboard keys
OPCODE Headings
Any questionable stray from the conventions should be notated as a possible error.
Revision Schedule
I would like to swap edited text with new revisions about every two weeks. The final revision should be
approved by November 15th to try for a release date of December 15th. This schedule is not fixed and I will
be in contact to find out what’s best for you.
Thank You...
Thank you for your time and effort. Your name will be credited if you desire and you should check for it in a
final revision.
SCOTT D. SANDERS, OWNER
SOFTWARE DEVELOPMENT SYSTEMS
i
C
O NTENTS
Foreword vii
Chapter 1: Introduction to Atari Programming.........1.1
Atari Computer Hardware.............................................................................1.3
Atari Computer Software...............................................................................1.6
Atari GEM.....................................................................................................1.7
Third-Party System Software.........................................................................1.8
Programming Languages...............................................................................1.9
Conventions..................................................................................................1.10
Chapter 2: GEMDOS....................................................2.1
Overview........................................................................................................2.3
The TOS File System.....................................................................................2.3
Memory Management....................................................................................2.8
GEMDOS Processes......................................................................................2.9
GEMDOS Vectors.......................................................................................2.13
MiNT............................................................................................................2.14
MiNT Interprocess Communication............................................................2.27
MiNT Debugging.........................................................................................2.31
The MINT.CNF File.....................................................................................2.33
GEMDOS Character Functions..................................................................2.34
GEMDOS Time & Date Functions..............................................................2.35
GEMDOS Function Calling Procedure......................................................2.35
GEMDOS Function Reference....................................................................2.37
Chapter 3: BIOS...........................................................3.1
Overview........................................................................................................3.3
System Startup................................................................................................3.3
OS-Header.....................................................................................................3.4
Cookie Jar......................................................................................................3.8
BIOS Devices...............................................................................................3.14
Media Change..............................................................................................3.15
BIOS Vectors...............................................................................................3.18
T HE AT ARI COMP ENDI UM
ii – Contents
The XBRA Protocol......................................................................................3.20
BIOS Function Calling Procedure..............................................................3.22
BIOS Function Reference............................................................................3.24
Chapter 4: XBIOS.........................................................4.1
Overview.........................................................................................................4.3
Video Control.................................................................................................4.3
The Falcon030 Sound System.........................................................................4.6
The DSP..........................................................................................................4.8
User/Supervisor Mode..................................................................................4.12
MetaDOS.......................................................................................................4.12
Keyboard and Mouse Control......................................................................4.12
Disk Functions..............................................................................................4.14
The Serial Port.............................................................................................4.16
Printer Control.............................................................................................4.18
Other XBIOS Functions...............................................................................4.18
XBIOS Function Calling Procedure............................................................4.19
XBIOS Function Reference.........................................................................4.21
Chapter 5: Hardware....................................................5.1
Overview.........................................................................................................5.3
The 680x0 Processor......................................................................................5.3
The 68881/882 Floating Point Coprocessor..................................................5.4
Cartridges.......................................................................................................5.7
Game Controllers...........................................................................................5.8
The IKBD Controller....................................................................................5.10
STe/TT DMA Sound.......................................................................................5.20
The MICROWIRE Interface.........................................................................5.22
Video Hardware............................................................................................5.24
Chapter 6: AES.............................................................6.1
Overview.........................................................................................................6.3
Process Handling............................................................................................6.3
Applications....................................................................................................6.4
Desk Accessories.............................................................................................6.7
The Environment String..................................................................................6.9
The Event Dispatcher.....................................................................................6.9
Resources......................................................................................................6.13
Objects..........................................................................................................6.13
T HE AT ARI COMP ENDI UM
iii
Dialogs.........................................................................................................6.24
Menus...........................................................................................................6.25
Windows.......................................................................................................6.29
The Graphics Library..................................................................................6.33
The File Selector Library............................................................................6.34
The Scrap Library........................................................................................6.34
The Shell Library.........................................................................................6.35
The GEM.CNF File......................................................................................6.36
AES Function Calling Procedure...............................................................6.37
AES Function Reference.............................................................................6.43
Chapter 7: VDI..............................................................7.1
Overview........................................................................................................7.3
VDI Workstations...........................................................................................7.3
Workstation Specifics....................................................................................7.5
Using Color....................................................................................................7.8
VDI Raster Forms..........................................................................................7.9
Vector Handling...........................................................................................7.10
GDOS...........................................................................................................7.11
GDOS 1.x.....................................................................................................7.12
FONTGDOS................................................................................................7.13
FSM-GDOS.................................................................................................7.13
SpeedoGDOS...............................................................................................7.14
Device Drivers.............................................................................................7.16
VDI Function Calling Procedure................................................................7.18
VDI/GDOS Function Reference..................................................................7.21
Chapter 8: Line-A........................................................8.1
Overview........................................................................................................8.3
The Line-A Variable Table............................................................................8.3
Line-A Font Headers.....................................................................................8.7
Line-A Function Calling Procedure.............................................................8.8
Line-A Function Reference...........................................................................8.9
Chapter 9: The Desktop..............................................9.1
Overview........................................................................................................9.3
MultiTOS Considerations.............................................................................9.3
Desktop Files.................................................................................................9.4
T HE AT ARI COMP ENDI UM
iv – Contents
Chapter 10: XCONTROL............................................10.1
Overview.......................................................................................................10.3
XCONTROL Structures...............................................................................10.4
CPX Flavors.................................................................................................10.6
CPX File Formats.......................................................................................10.12
XCONTROL Function Calling Procedure................................................10.13
XCONTROL Function Reference..............................................................10.15
Chapter 11: GEM User Interface Guidelines...........11.1
Overview.......................................................................................................11.3
The Basics.....................................................................................................11.3
Windows........................................................................................................11.4
Dialog Boxes.................................................................................................11.8
Alerts...........................................................................................................11.10
The File Selector........................................................................................11.12
Progress Indicators....................................................................................11.12
Toolboxes....................................................................................................11.13
Toolbars......................................................................................................11.14
Menus..........................................................................................................11.15
Keyboard Equivalents................................................................................11.20
Device Independence..................................................................................11.22
Globalization..............................................................................................11.23
Colors..........................................................................................................11.23
Sound...........................................................................................................11.24
Application Software..................................................................................11.24
Installation Software..................................................................................11.25
Entertainment Software..............................................................................11.25
Appendix A: Functions by Opcode...........................A.1
GEMDOS Functions by Opcode....................................................................A.3
BIOS Functions by Opcode...........................................................................A.7
XBIOS Functions by Opcode.........................................................................A.9
AES Functions by Opcode...........................................................................A.13
VDI Functions by Opcode...........................................................................A.15
Appendix B: Memory Map..........................................B.1
Usage.............................................................................................................B.3
Memory Map..................................................................................................B.4
T HE AT ARI COMP ENDI UM
v
Appendix C: Native File Formats..............................C.1
The .GEM File Format..................................................................................C.3
The .IMG File Format...................................................................................C.5
The .FNT File Format....................................................................................C.7
The .RSC File Format....................................................................................C.9
Appendix D: Error Codes...........................................D.1
Appendix E: Atari ASCII Table...................................E.1
Appendix F: IKBD Scan Codes..................................F.1
Appendix G: Speedo Fonts.......................................G.1
The Speedo Font Header...............................................................................G.3
The Bitstream International Character Set...................................................G.7
Appendix H: The Drag & Drop Protocol...................H.1
Overview........................................................................................................H.3
The Originator...............................................................................................H.3
The Recipient.................................................................................................H.5
Appendix I: The Programmable Sound Generator..H.1
Bibliography
Index
T HE AT ARI COMP ENDI UM
vii
F
O REWO RD
About eight months have passed since The Atari Compendium® was first released, and I must
admit to being amazed with the amount of attention the book has received from Atari developers
worldwide. When I started writing the first draft of the book I didn’t know enough about Atari
computers to write half of the 860 pages it eventually became. The learning process that I went
through to see the book to its completion was responsible for a great deal of personal growth
and a greater understanding of computer science in general.
It was inevitable, of course, that there would be errors in a book this big. I didn’t want to revise
the book simply to correct those errors, however. I was determined to add some missing topics
as well. This first revision now adds about 60 pages to the original and led me back to the
on-the-job learning process and several phone calls and E-mail letters to Sunnyvale.
The Compendium now covers almost every conceivable topic a software programmer needs to
know about Atari computers. You still won’t find timing diagrams, pinouts, and hardware
specifications simply because my level of competence in those matters is unfortunately minor.
The only other topics you won’t find discussed are those covered completely in separate
volumes (referenced in the Bibliography). These include hardware-direct ACSI/SCSI/IDE
programming, SCC programming, DSP programming, and direct BLiTTER chip usage. In every
case except for DSP programming, almost all functions of these devices may be accessed by the
average programmer through the use of OS calls, which are, of course, documented. The basics
of DSP programming, like assembly or ‘C’ is left to the reader to explore in other books
dedicated to their teaching.
New to this revision you will find an enhanced style guide and memory map (the two most
popular sections of the book, it seems), information on programming MiNT device drivers and
file systems, and a section documenting the XBRA protocol. Most importantly, though, almost
every conceivable parameter and return value has been listed with a corresponding definition
name. These names may be used with any language that supports constant naming, and, when
used, improve program readability dramatically. The TOS.H and TOSDEFS.H include files will
be available from SDS upon the release of this revision. To find out how to obtain them, be sure
to send in your registration card.
I owe thanks to Mike Fulton, Eric Smith, and Jay Patton were very helpful in ensuring that the
new material was correct and old errors were eliminated. Many independent readers of the book
also deserve thanks for taking the time to report errors and submit their comments.
In addition, my close friends Dennis, Mike, Keith, Cathryn, Shawn, Cathy, Shaun, and Kristýna
provided moral support and dragged me away from work when I needed a break badly. Also, as
always, my mom supported me tremendously and continues to proudly display a plastic-wrap’d
copy of the book to friends and relatives even though to her its about as useful as a phone book
for some remote city in Alaska.
THE AT A RI C OM PENDIUM
viii
Thanks to you, especially, the Atari developers and users who made this book a reality. Enjoy!
—Scott D. Sanders, April 1994
THE AT A RI C OM PENDIUM