The Atari™ Compendium ©1992 Software Development Systems Written by Scott Sanders Not for Public Distribution
Total Page:16
File Type:pdf, Size:1020Kb
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 CONTENTS 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 ATARI COMPENDIUM 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