Atari 400 Use and care manual

'.
ATARI" HOME COMPUTER SYSTEM
/'
TECHNICAL
REFERENCE NOTES
includes:
Operating System User's Manual
Operating System Source Listing
and
Hardware Manual
TO All PERSONS RECEIVING THIS DOCUMENT
Re produ c tion is forbidd en without th e spec ifi c writt en permi ss ion of
ATARI, IN C. Sunnyval e, CA 94086. No rig ht to re produ ce thi s do c ument ,
nor th e s ubj ect matt er th ere of , is gra nt ed unl ess by writt en agreeme nt with ,
or w
ritt en pe rmi ss ion fr om th e Co rp ora ti on.
)I\.®
ATAR I A Warner Communications Company ~
C0 16555 R ev. A

ATARI® HOME COMPUTER SYSTEM
OPE RA TI NG SYSTEM
USER'S MANUAL
)I~@
ATARI A Warner Communications Company ~

COPYRIGHT 1982, ATARI, INC.
ALL RIGHTS RESERVED
TO All PERSONS RECEIVING THIS DOCUMENT
Reproduction is forbidden without the specific written permission of
ATARI, INC. Sunnyvale, CA 94086. No right to reproduce this document,
nor the subject matter thereof,
is granted unless by written agreement with,
or written permission from the Corporation.
Every effort has been made to ensure that this manual accurately
documents this product of the ATARI Home Computer Division.
However, due to the ongoing improvement and update of the computer
software and hardware, ATARI, INC. cannot guarantee the accuracy
of printed material after the date of publication and disclaims
liability for changes, errors, or omissions.

PREFACE
ATARI Home Computer
Operating System USER'S MANUAL
17
1 INTRODUCTION
18
GENERAL DESCRIPTION
OF THE ATARI COMPUTER SYSTEM 18
Conventions Used in This Manual 20
HEXADECIMAL NUMBERS 20
MEMORY ADDRESSES 20
KILOBYTES OF MEMORY 20
PASCAL AS AN ALGORITHM-SPECIFICATION LANGUAGE 20
MEMORY LAYOUTS 20
BACKUS-NAUR FORM (BNF) 21
OS-EQUATE FILENAMES 21
3

2 OPERATING SYSTEM FUNCTIONAL ORGANIZATION 22
Input/Output Subsystem
22
Interrupt Processing
22
Initialization
22
Power-Up 22
System Reset 23
Floating Point
Arithmetic
Package
24
3
CONFIGURATIONS 25
Program Environments 25
Blackboard Mode 25
Cartridge
26
Diskette-Boot 26
Cassette-Boot 26
RAM
Expansion
27
Peripheral Devices 27
Game Controllers
27
Program Recorder 27
Serial Bus Devices
28
4
SYSTEM MEMORY
UTILIZATION
29
RAM Region
29
Page 0 30
Page
1
30
OS Data
Base
30
User Workspace 31
Boot .~eg ion 31
Screen Display List and Data
31
Free Memory Region 31
4

Cartridges A and B
Mapped 1/0
Resident OS and Floating Point Package ROM
Central Data Base Description
Memory Dynamics
System Initialization Proce'ss
Changing Screen Modes
5 1/0 SUBSYSTEM
Central 1/0 Utility
CIO Design Philosophy
DEVICE INDEPENDENCE
DATA ACCESS METHODS
MULTIPLE DEVICEIFILE CONCURRENCY
UNIFIED ERROR HANDLING
DEVICE EXPANSION
CIO CALLING MECHANISM
HANDLER ID -- ICHID [0340]
DEVICE NUMBER -- ICDNO [0341]
COMMAND BYTE -- ICCMD [0342J
STATUS -- ICSTA [0343J
BUFFER ADDRESS
ICBAL[0344J AND ICBAH [0345]
PUT ADDRESS --
ICPTL [0346] AND ICPTH [0347]
BUFFER LENGTHIBYTE COUNT --
ICBLL [0348] and ICBLH [0349]
AUXILIARY INFORMATION --
ICAX1 [034AJ and ICAX2 [034B]
REMAINING BYTES (ICAX3-ICAX6)
31
32
32
32
32
33
33
34
36
37
37
37
38
38
38
38
39
39
40
40
40
40
40
40
41
5

6
CIa Functions 41
OPEN -- Assign Device/Filename to IOCB
and Ready for Access 41
CLOSE -- Terminate Access to Device/File
and Release IOCB 42
GET CHARACTERS -- Read n Characters
(Byte-Aligned Access) 43
PUT CHARACTERS -- Write n Characters
(Byte-Aligned Access) 43
GET RECORD -- Read Up To n Characters
(Record-Aligned Access) 44
PUT RECORD -- Write Up To n Characters
(Record-Aligned Access) 44
GET STATUS -- Return Device-Dependent
Status Bytes 45
SPECIAL -- Special Function 45
Device/Filename Specification 46
I/O Example 47
Device Specific Information 50
Keyboard Handler 50
CIa Function Descriptions 51
Theory of Operation 51
Dis PI a y Han die r ( S: ) 54
Screen Modes 54
TEXT MODE 0 54
TEXT MODES 1 AND 2 55
GRAPHICS MODES <Modes 3 Through 11) 56
SPLIT-SCREEN CONFIGURATIONS 56
cto Function Descriptions
User-Alterable Data Base Variables
Theory of Operation
Screen Editor (E:)
CIa Function Descriptions
User-Alterable Data Base Variables
Cassette Handler (C:)
CIa Function Descriptions
Theory of Operation
File Structure
57
61
62
66
67
70
72
72
74
75

Pr in t er Hand 1e r ( P: )
CIa Function Descriptions
Theory of Operation
Dis k F i 1e Ma nag er ( D: )
CIa Function Descriptions
DevicelFilename Specification
Filename Wildcarding
Special CIa functions
Theory of Operation
FMS Diskette Utilization
Non-CIa 110
FMS BOOT RECORD FORMAT
BOOT PROCESS MEMORY MAP
VOLUME TABLE OF CONTENTS
FILE DIRECTORY FORMAT
FMS FILE SECTOR FORMAT
Resident Device Handler Vectors
Resident Diskette Handler
Diskette Handler Commands
Serial Bus 1/0
6 INTERRUPT PROCESSING
76
76
78
78
79
81
82
84
87
89
90
92
93
94
95
96
96
97
99
101
102
Chip-Reset 103
Nonmaskable Interrupts 103
Stage 1 VBLANK Process 104
Stage 2 VBLANK Process 105
Maskable Interrupts 107
Interrupt Initialization 108
System Timers 109
Usage Notes 109
POKEY Interrupt Mask 110
Setting Interrupt and Timer Vectors 110
Stack Content at Interrupt Vector Points 111
Miscellaneous Considerations 112
Flowcharts 113
7

7 SYSTEM INITIALIZATION
116
Power-Up Initialization (Coldstart) Procedure 116
System Reset Initialization (Warmstart) Procedure 119
8 FLOATING POINT ARITHMETIC PACKAGE 121
9
8
Functions/Calling Sequences 122
ASCII to Floating Point Conversion (AFP) 122
Floating Point to ASCII Conversion (FASC) 122
Integer to Floating Point Conversion (IFP) 123
Floating Point to Integer Conversion (FPI) 123
Floating Point Addition (FADD) 124
Floating Point Subtraction (FSUB) 124
Floating Point Multiplication (FMUL) 124
Floating Point Division (FDIV) 125
Floating Point Logarithms (LOG and LOG10) 125
Floating Point Exponentiation (EXP and EXP10) 126
Floating Point Polynomial Evaluation (PLVEVL) 126
Clear FRO (ZFRO) 127
Clear Page-Zero Floating Point Number (ZF1) 127
Load Floating Point Number to FRO
(FLDOR and FLDOP) 127
Load Floating Point Number to FRl
(FLD1R and FLD1P) 128
Store Floating Point Number From FRO
(FSTOR and FSTOP) 128
Move Floating Point Number From FRO to FRl
(FMOVE) 128
Resource Utilization 128
Implementation Details 129
ADDING
NEW DEVICE HANDLERS/PERIPHERALS
131
Device Table
134
CID/Handler
Interface
134
Calling Mechanism
135
Handler
Initialization
136
Functions Supported
136
Error Handling
140
Resource Allocation
140
ZERO-PAGE RAM
141
NONZERO-PAGE RAM
141
STACK SPACE
142
Handler/SID Interface
142

Calling Mechanism
Functions Supported
Error Handling
Serial 1/0 Bus Characteristics and Protocol
HardwarelElectrical Characteristics
Serial Port Electrical Specifications
Bus Commands
COMMAND FRAME
COMMAND FRAME ACKNOWLEDGE
DATA FRAME
OPERATION COMPLETE
Bus Timing
Handler Environment
Boatable Handler
Cartridge Resident Handler
Flowcharts
10 PROGRAM ENVIRONMENT AND INITIALIZATION
142
144
144
145
145
147
147
148
148
149
149
150
152
153
153
153
157
Cartridge 157
Cartridge Without Booted Support Package 158
Cartridge With Booted Support Package 158
Diskette-Booted Software 159
Diskette-Boot File Format 159
Diskette-Boot Process 160
Sample Diskette-Bootable Program Listing 161
Program to Create Diskette-Boot Files 162
Cassette-Booted Software 164
Cassette-Boot File Format 165
Cassette-Boot Process 165
Sample Cassette-Boatable Program Listing 167
Program to Create Cassette-Boot Files 168
9

11 ADVANCED TECHNIGUES AND APPLICATION NOTES
170
Sound Generation 170
Capabilities 170
Conflicts With as 170
Screen Graphics 171
Hardware Capabilities 171
as Capabilities 171
Cursor Control 171
Color Control 171
Alternate Character Sets 172
Player/Missile Graphics 174
Hardware Capabilities 174
Conflicts With as 174
Reading Game Controllers 174
Keyboard Controller Sensing 174
Front Panel Connectors as 110 Ports 176
Hardware Information: 176
Software Information: 177
Other Miscellaneous Software Information: 179
10

APPENDICES
Appendix A CIO
COMMAND BYTE VALUES
180
Appendix B CIO STATUS BYTE VALUES.
181
Appendix C SIO STATUS BYTE VALUES
182
Appendi x D"
ATASCII CODES
183
Appendix E DISPLAY
CODES (ATASCII)
184
Appendix F KEYBOARD CODES (ATASCII)
185
Appendix G PRINTER CODES (ATASCII)
186
Appendix H SCREEN
MODE CHARACTERISTICS
188
Appendix I SERIAL
BUS ID AND COMMAND SUMMARY
191
Appendix J
ROM VECTORS
192
Appendix K DEVICE CHARACTERISTICS
194
Keyboard 194
Display 194
ATARI 410CTMJ Program Recorder 194
ATARI 820CTMJ 40-Column Impact Printer 195
ATARI 810CTMJ Disk Drive 197
Appendix L -- OS DATA BASE VARIABLE
FUNCTIONAL DESCRIPTIONS 200
Central Data Base Description 200
FUNCTIONAL INDEX TO DATA BASE VARIABLE DESCRIPTIONS 201
A. MEMORY CONFIGURATION 211
11

B. TEXT/GRAPHICS SCREEN 212
Cursor Control 212
Screen Margins 213
Text Scrolling 215
Attract Mode 215
Tabbing 216
Logical Text Lines 217
Split Screen 218
Displaying Control Characters 220
Escape (Displa~ Following Control Character) 221
Display Control Characters Mode 221
Bit-Mapped Graphics 221
Internal Working Variables 222
Internal Character Code Conversion 224
C. DISKETTE HANDLER 225
D. CASSETTE 225
Baud Rate Determination 226
Cassette Mode 227
Cassette Buffer 227
Internal Working Variables 228
E. KEYBOARD 229
Key Reading and Debouncing 229
Special Functions 230
Start/Stop 230
Autorepeat 231
Inverse Video Control 232
Console Keys: (SELECT], [START], and [OPTION] 232
F. PRINTER 232
Printer-Buffer 233
Internal Working Variables 233
12

Q. CENTRAL lID ROUTINE (CIO)
User Call Parameters
lID Control Block
Device Status
Device Table
CIOIHandier Interface Parameters
Zero-Page IOCB
Internal Working Variables
H. SERIAL 110 ROUTINE (SIO)
User Call Parameters
Device Control Block
Bus Sound Control
Serial Bus Control
Retry Logic
Checksum
Data Buffering
General Buffer Control
Command Frame Output Buffer
ReceivelTransmit Data Buffering
SID Timeout
Internal Working Variables
~. ATARI CONTROLLERS
Joysticks
Paddles
Light Pen
Driving Controllers
K. DISK FILE MANAGER
L. DISK UTILITY POINTER
M. FLOATING POINT PACKAGE
N. Power-Up and System Reset
RAM Sizing
Diskette/Cassette-Boot
Environment Control
233
.233
233
234
235
235
235
236
237
237
237
238
238
238
239
240
240
240
241
241
242
243
243
244
245
246
247
248
248
249
249
250
251
13

P. INTERRUPTS
System Timers
Real Time Clock
System Timer 1
System Timer 2
System Timers 3, 4 and 5
RAM Interrupt Vectors
NMI Interrupt Vectors
IRG Interrupt Vectors
Hardware Register Updates
Internal Working Variables
R. USER AREAS
Alphabetical List of Data Base Variables
Memory AddTess Ordered List oT Data Base
Variables
Floating Point Package Variables
INDEX
14
252
253
253
253
254
254
255
255
255
256
258
258
259
266
270
271

TABLE OF ILLUSTRATIONS
Figure 1-1.
Figure 1-2.
Figure 4-1.
Figure 4-2.
Figure 5-1.
Figure 5-2.
Figure 5-3.
Figure 5-4.
Figure 5-5.
Figure 5-6.
Figure 5-7.
Figure 5-8.
Figure 5-9.
Fi gure 5-10.
Figure 5-11.
Utilization
Fi gure 5-12.
Fi gure 5-13.
Memor'l Map
Fi gure 5-14.
of Contents
Figure 5-15.
Figure 5-16.
Figure 5-17.
Fi gure 5-18.
Figure 5-19.
ATARI Home Computer Block Diagram
Memor'l La'lout Chart
6502 System Memory Map
Mapped 110
110 Subs'lstem Structure Flow Diagram
CIa Calling Mechanism
An I/O Example
Keycode to ATASCII Conversion Table
Text Modes 1 and 2 Data Form
Graphics Modes 3-11 GET Data Form
Graphics Modes 3-11 PUT Data Form
Screen Display Block Diagram
Cassette Handler Record Format
Device/Filename Syntax
File Management Subsystem Diskette Sector
Map
File Management Subsystem Boot Record Format
File Management Subsystem Boot P~ocess
File Management Subsystem Volume Table
File Management Subsystem Volume Bit Map
File Directory Format
File Management Subsystem File Sector Format
Resident Device Handler Vectors
DVSTAT 4-Byte Operation Status Format
19
20
29
32
35
38
49
53
56
58
59
64
74
81
89
90
92
93
93
94
95
96
100
15

Figure 6-1. List of System Inter~upt Events
Figure 6-2. Interrupt RAM Vector Initialization
Figure 6-3. POKEY Interrupt Mask Example
Figure 6-4. Interrupt and Timer Vector RAM Stack
Content Table
Figure 9-1.
Figure 9-2.
Figure 9-3.
Figure 9-4.
Figure 9-5.
Figure 9-6.
I/O Subsystem Flow Diagram
Device Table Format
Handler Vector Table
Serial Bus Connector Pin Descriptions
Serial Bus Command Frame Format
Serial Bus Timing Diagram
102
108
110
112
133
134
135
146
148
151
Figure 10-1. Cartridge Header Format 157
Figure 10-2. Diskette Boot File Format 159
Figure 10-3. Diskette-Boatable Program Listing Example 162
Figure 10-4. Sample Cassette-Bootable Program 168
Figure 11-1. User-Defined Character Set Bit Memory Address 172
Figure 11-2. User-Defined 8 x 8 Character Matrix Bit Table 173
Figure 11-3. Character Base Diagram 173
Figure 11-4. Reading Data From an ATARI Keyboard Controller 176
Figure 11-5. ATARI Keyboard Controller Variable/Register
Value Table 176
Figure 11-6. Using Front Panel Connectors As 1/0 Ports: Pin
Function Tables 179
16

PREFACE
This manual describes the resident Operating System (aS) for the
ATARI@ Home Computer, for readers who are familiar with the
internal behavior of the system. It discusses:
o System functions and utilization techni~ues
o Subsystem relationships and organization
o Characteristics of the ATARI peripheral devices that can
be attached to the ATARI400[TMJ and ATARI 800[TMJ Home
Computer
o Advanced techniques for going beyond the basic as
capabilities
o The general features of the computer system hardware used
by the as.
It would be helpful to have a familiarity with programming concepts
and terminology, assembly language programming in gene~al, the
Synertek 6502 in particular, and digital hardware concepts and
terminology. you will be provided with the information you need to
use the as resources, without resorting to trial-and-error techniques
or the as listing. Supporting information for tasks that involve as
listing references is also provided.
This manual does not present a comprehensive description of the
hardware used to provide as capabilites. The programmer who needs to
go beyond the capabilities described should consult the ATARI Home
Computer Hardware Manual.
OPERATING SYSTEM C016555 -- Section 1
17

1 INTRODUCTION
OENERAL
DESCRIPTION OF THE ATARI HOME COMPUTER SYSTEM
Operating systems in the ATARI@ 400[TM] and ATARI 800[TM] Home
Computer are identical. The primary differences between the two are:
o Physical packaging
o The ATARI 400 Computer console has one cartridge slot, the
ATARI 800 Computer console has two cartridge slots
o The ATARI 400 Home Computer contains 16K RAM and cannot be
expanded. The ATARI 800 Home Computer can be expanded to a
maximum of 48K RAM.
o The ATARI 800 Computer has a monitor Jack; the ATARI 400
Computer does not.
The Hardware Circuit~y
o Produces both character and point graphics for black and
white (B/W) or color television.
o Produces four independent audio channels (frequency
controlled) which use the television sound system.
o Provides one bi-level audio output in the base unit.
o Interfaces with up to four Joysticks and eight Paddle
Controllers.
o Interfaces with a serial lID bus for expansion.
o Contains a built-in keyboard
Figure 1-1 presents a simplified block diagram of the hardware.
See the hardware manual for supporting documentation.
OPERATING SYSTEM C016555 -- Section 1
18

+---------+
6502
Iprocessorl
+----+----+ +---------+
processor
external
bus
OS
+---------+ ROM
ID80Q-FFFFI
+---------+
+---------+
+---------+
+---------+ : I
RAM I I I
+------------------------+
: :-+
+---------+
ICartridgel
+---------+slots A&SI
1800Q-BFFFI
+---------+
IOOQQ-xxxxl-+
+---------+
+---------+
+---------+ Joysticks Icontrol- I
PIA +--------+----------+ler ports:
+---------+ +--------t-------+
: ......... ID30Q-D31F+--------:-----+ +---------+
IRG +---------+
+---------+ pots
POKEY +--------+
c
•
+---------+ +--------:-----t-
L ........ ID20Q-D21F+--------t---+
IRG +----+----+ audio
+---------+
Ikeyboard I
Idata keysl
--+ + BREAK :
+---------+
on/off
+-------------t-+
+---------+
+----+----+ trigs +--+cassette :
CTIA +--------+: I : interface:
+---------+ +-----+ t +-1-:----+
tDOOQ-D01F+-----t--:-+ +---------+
I +----+----+ I +----+ serial
: I video I/O
: DMA +----+----+ litpen +------+ bus
t •..••.... I ANTIC +--------+ +---------+
+---------+
t •••••.••. ID400-D41FI
NMI +---------+
composite +----+
audio/video
+----+----+
TV
+---------+
+---------+
from console
CTIA -+ speaker :
+---------+
+---------+
START,
+--------+ SELECT,
: OPTION
+---------+
Figure 1-1. ATARI Home Computer Block Diagram
OPERATING SYSTEM C016555 -- Section 1
19