400/800™

ATARI HOME COMPUTER SYSTEM

OPERATING SYSTEM
USER MANUAL

GENERAL DESCRlPTION OF THE ATARI COMPUTER SYSTEM

CONVENTIONS USED IN THIS MANUAL
HEXADECIMAL NUMBERS
MEMORY ADDRESSES
KILOBYTES OF MEMORY
PASCAL AS AN ALGORITHM-SPECIFICATION LANGUAGE
MEMORY LAYOUTS
BACKUS-NAUR FORM (BNF)
OS-EQUATE FILENAMES

2 OPERATING SYSTEM FUNCTIONAL ORGANIZATION

Input/Output Subsystem
Interrupt Processing
Initialization

Power-Up
System Reset

Floating Point Arithmetic Package

3 CONFIGURATIONS

Program Environments

Blackboard Mode
Cartridge
Diskette-Boot
Cassette-Boot

RAM Expansion
Peripheral Devices

Game Controllers
Program Recorder
Serial Bus Devices

4 SYSTEM MEMORY UTILIZATION

RAM Region

Page 0
Page 1
OS Data Base
User Workspace
Boot Region
Screen Display List and Data
Free Memory Region

Cartridges A and B
Mapped I/O
Resident OS and Floating Point Package ROM
Central Data Base Description
Memory Dynamics

System Initialization Process
Changing Screen Modes

5 I/O SUBSYSTEM

Central I/O Utility

CIO Design Philosophy

DEVICE INDEPENDENCE
DATA ACCESS METHODS
MULTIPLE DEVICE/FILE CONCURRENCY
UNIFIED ERROR HANDLING
DEVICE EXPANSION

CIO CALLING MECHANISM

HANDLER ID -- ICHID [0340]
DEVICE NUMBER -- ICDNO [0341]
COMMAND BYTE -- ICCMD [0342]
STATUS -- ICSTA [0343]
BUFFER ADDRESS ICBAL [0344] AND ICBAH [0345]
PUT ADDRESS -- ICPTL [0346] AND ICPTH [0347]
BUFFER LENGTH/BYTE COUNT -- ICBLL [0348] and LCBLH [0349]
AUXILIARY INFORMATION -- ICAX1 [034A] and ICAX2 [0348]
REMAINlNG BYTES (ICAX3-ICAX6)

CIO Functions

OPEN -- Assign Device/Filename to IOCB and Ready for Access
CLOSE -- Terminate Access to Device/File and Release IOCB
GET CHARACTERS -- Read n Characters (Byte-Aligned Access)
PUT CHARACTERS -- Write n Characters (Byte-Aligned Access)
GET RECORD -- Read Up To n Characters (Record-Aligned Access)
PUT RECORD -- Write Up To n Characters (Record-Aligned Access)
GET STATUS -- Return Device-Dependent Status Bytes
SPECIAL -- Special Function

Device/Filename Specification
I/O Example

Device Specific Information

Keyboard Handler (K:)

CIO Function Descriptions
Theory of Operation

Display Handler (S:)

Screen Modes
TEXT MODE 0
TEXT MODES 1 AND 2
GRAPHICS MODES (Modes 3 Through 11)
SPLIT-SCREEN CONFIGURATIONS
CIO Function Descriptions
User-Alterable Data Base Variables
Theory of Operation

Screen Editor (E:)

CIO Function Descriptions
User-Alterable Data Base Variables
Cassette Handler (C:)
CIO Function Descriptions
Theory of Operation
File Structure

Printer Handler (P:)

CIO Function Descriptions
Theory of Operation

Disk File Manager (D:)

CIO Function Descriptions
Device/Filename Specification
Filename Wildcarding
Special CIO functions
Theory of Operation
FMS Diskette Utilization

FMS BOOT RECORD FORMAT
BOOT PROCESS MEMORY MAP
VOLUME TABLE OF CONTENTS
FILE DIRECTORY FORMAT
FMS FILE SECTOR FORMAT

Non-CIO I/O
Resident Device Handler Vectors

Resident Diskette Handler
Diskette Handler Commands

Serial Bus I/O

6 INTERRUPT PROCESSING

Chip-Reset
Nonmaskable Interrupts

Stage 1 VBLANK Process
Stage 2 VBLANK Process

Maskable Interrupts
Interrupt Initialization
System Timers
Usage Notes

POKEY Interrupt Mask
Setting Interrupt and Timer Vectors
Stack Content at Interrupt Vector Points
Miscellaneous Considerations

Flowcharts

7 SYSTEM INITIALIZATION

Power-Up Initialization (Coldstart) Procedure
System Reset Initialization (Warmstart) Procedure

8 FLOATING POlNT ARITHMETIC PACKAGE

Functions/Calling Sequences

ASCII to Floating Point Conversion (AFP)
Floating Point to ASCII Conversion (FASC)
Integer to Floating Point Conversion (IFP)
Floating Point to Integer Conversion (FPI)
Floating Point Addition (FADD)
Floating Point Subtraction (FSUB)
Floating Point Multiplication (FMUL)
Floating Point Division (FDIV)
Floating Point Logarithms (LOG and LOG10)
Floating Point Expanentiation (EXP and EXP10)
Floating Point Polynomial Evaluation (PLYEVL)
Clear FR0 (ZFR0)
Clear Page-Zero Floating Point Number (ZF1)
Load Floating Point Number to FR0 (FLD0R and FLD0P)
Load Floating Point Number to FR1 (FLD1R and FLD1P)
Store Floating Point Numbat From FR0 (FSTOR and FSTOP)
Move Floating Point Number From FR0 to FR1 (FMOVE)

Resource Utilization
Implementation Details

9 ADDING NEW DEVICE HANDLERS/PERIPHERALS

Device Table
CIO/Handler Interface
Calling Mechanism

Handler Initialization
Functions Supported
Error Handling
Resource Allocation
ZERO-PAGE RAM
NONZERO-PAGE RAM
STACK SPACE

Handler/SIO Interface
Calling Mechanism
Functions Supported
Error Handling

Serial I/O Bus Characteristics and Protocol

Hardware/Electrical Characteristics
Serial Port Electrical Specifications
Bus Commands

COMMAND FRAME
COMMAND FRAME ACKNOWLEDGE
DATA FRAME
OPERATION COMPLETE

Bus Timing

Handler Environment

Bootable Handler
Cartridge Resident Handler

Flowcharts

10 PROGRAM ENVIRONMENT AND INITIALIZATION

Cartridge

Cartridge Without Booted Support Package
Cartridge With Booted Support Package

Diskette-Booted Software

Diskette-Boot File Format
Diskette-Boot Process
Sample Diskette-Bootable Program Listing
Program to Create Diskette-Boot Files

Cassette-Booted Software

Cassette-Root File Format
Cassette-Boot Process
Sample Cassette-Bootable Program Listing
Program to Create Cassette-Boot Files

11 ADVANCED TECHNIQUES AND APPLICATION NOTES

Sound Generation

Capabilities
Conflicts With OS

Screen Graphics

Hardware Capabilities
OS Capabilities
Cursor Control
Color Control
Alternate Character Sets

Player/Missile Graphics

Hardware Capabilities
Conflicts With OS

Reading Game Controllers

Keyboard Controller Sensing
Front Panel Connectors as I/O Ports

Hardware Information:
Software Information:
Other Miscellaneous Software Information:

APPENDICES

Appendix A -- CIO COMMAND BYTE VALUES

Appendix B -- CIO STATUS BYTE VALUES

Appendix C -- SIO STATUS BYTE VALUES

Appendix D -- ATASCII CODES

Appendix E -- DISPLAY CODES (ATASCII)

Appendix F -- KEYBOARD CODES (ATASCII)

Appendix G -- PRINTER CODES (ATASCII)

Appendix H -- SCREEN MODE CHARACTERISTICS

Appendix I -- SERIAL BUS ID AND COMMAND SUMMARY

Appendix J -- ROM VECTORS

Appendix K -- DEVICE CHARACTERISTICS

Keyboard
Display
ATARI 410™ Program Recorder
ATARI 820™ 40-Column Impact Printer
ATARI 810™ Disk Drive

Appendix L -- OS DATA BASE VARIABLE FUNCTIONAL DESCRIPTIONS

Central Data Base Description
FUNCTIONAL INDEX TO DATA BASE VARIABLE DESCRIPTIONS

A. MEMORY CONFIGURATION

B. TEXT/GRAPHICS SCREEN

Cursor Control
Screen Margins
Text Scrolling
Attract Mode
Tabbing
Logical Text Lines
Split Screen
Displaying Control Characters
Escape (Display Following Control Character)
Display Control Characters Mode
Bit-Mapped Graphics
Internal Working Variables
Internal Character Code Conversion

C. DISKETTE HANDLER

D. CASSETTE

Baud Rate Determination
Cassette Mode
Cassette Buffer
Internal Working Variables

E. KEYBOARD

Key Reading and Debouncing
Special Functions
Start/Stop
Autorepeat
Inverse Video Control
Console Keys: [SELECT], [START], and [OPTION]

F. PRINTER

Printer Buffer
Internal Working Variables

G. CENTRAL I/O ROUTINE (CIO)

User Call Parameters
I/O Control Block
Device Status
Device Table
CIO/Handler Interface Parameters
Zero-Page IOCB
lnternal Working Variables

H. SERIAL I/O 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
Receive/Transmit Data Buffering
SIO Timeout
Internal Working Variables

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

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
IRQ Interrupt Vectors
Hardware Register Updates
Internal Working Variables

R. USER AREAS

Alphabetical List of Data Base Variables
Memory Address Ordered List of Data Base
Variables
Floating Point Package Variables

INDEX

TABLE OF ILLUSTRATIONS

Figure 1-1. ATARI Home Computer Block Diagram
Figure 1-2. Memory Layout Chart
Figure 4-1. 6502 System Memory Map
Figure 4-2. Mapped I/O
Figure 5-1. I/O Subsystem Structure Flow Diagram
Figure 5-2. CIO Calling Mechanism
Figure 5-3. An I/O Example
Figure 5-4. Keycodes to ATASCII Conversion Table
Figure 5-5. Text Modes 1 and 2 Data Form
Figure 5-6. Graphics Modes 3-11 GET Data Form
Figure 5-7. Graphics Modes 3-11 PUT Data Form
Figure 5-8. Screen Display Block Diagram
Figure 5-9. Cassette Handler Record Format
Figure 5-10. Device/Filename Syntax
Figure 5-11. File Management Subsystem Diskette Sector Utilization Map
Figure 5-12. File Management Subsystem Boot Record Format
Figure 5-13. File Management Subsystem Boot Process Memory Map
Figure 5-14. File Management Subsystem Volume Table of Contents
Figure 5-15. File Management Subsystem Volume Bit Map
Figure 5-16. File Directory Format
Figure 5-17. File Management Subsystem File Sector Format
Figure 5-18. Resident Device Handler Vectors
Figure 5-19. DVSTAT 4-Byte Operation Status Format
Figure 6-1. List of System Interrupt 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. I/O Subsystem Flow Diagram
Figure 9-2. Device Table Format
Figure 9-3. Handler Vector Table
Figure 9-4. Serial Bus Connector Pin Descriptions
Figure 9-5. Serial Bus Command Frame Format
Figure 9-6. Serial Bus Timing Diagram
Figure 10-1. Cartridge Header Format
Figure 10-2. Diskette Boot File Format
Figure 10-3. Diskette-Bootable Program Listing Example
Figure 10-4. Sample Cassette-Bootable Program
Figure 11-1. User-Defined Character Set Bit Memory Address
Figure 11-2. User-Defined 8 x 8 Character Matrix Bit Table
Figure 11-3. Character Base Diagram
Figure 11-4. Reading Data From an ATARI Keyboard Controller
Figure 11-5. ATARI Keyboard Controller Variable/Register Value Table
Figure 11-6. Using Front Panel Connectors As I/OPorts: Pin Function Tables

400/800™

ATARI HOME COMPUTER SYSTEM

OPERATING SYSTEM USER MANUAL

OPERATING SYSTEM
USER MANUAL