Atari* System Reference manual (c) 1987 By Bob DuHamel Bob Duhamel 6915 Casselberry Way San Diego, CA 92119 *Atari is a registered trademark of Atari Corp. This manual contains highly technical information. Such information is provided for those who know how to use it. To understand the advanced information you are expected to know 6502 assembly language. If you are new to programming, concentrate on the parts which discuss BASIC commands. Addresses are usually given in both hexadecimal and decimal numbers. The operating system equate names are given in capital letters with the address following in brackets. The decimal address is in parenthsis within the brackets. For example: DOSVEC [$000A,2 (10)] name hex dec The ",2" after the hexadecimal number means that this address requires two bytes to hold its' information. Any address called a "vector" uses two bytes whether noted or not. Control registers and some other bytes of memory are shown in the following format Register format 7 6 5 4 3 2 1 0 ----------------- | | ----------------- 1 6 3 1 8 4 2 1 2 4 2 6 8 The numbers on top are the bit numbers. Bit 7 is the Most Significant Bit (MSB) and bit 0 is the Least Significant bit (LSB). The numbers on the bottom are the bit weights. These are useful when changing memory with decimal numbers, as you would in BASIC. For example, to set bit 4 of a register to 1, without changing any other bits you would add 16 to the decimal number already in the register. To reset the same bit to 0, you would subtract 16 from the number in the register. This is exactly what the command GRAPHICS 8+16 does. It sets bits 3 and 4 of a graphics mode control register. MSB and LSB may also mean Most Significant Byte or Least Significant Byte, depending on context. CONTENTS 1 THE CENTRAL INPUT/OUTPUT UTILITY, (CIO) 2 THE DISK OPERATING SYSTEM (D:) 3 USING THE DOS 2 UTILITIES (DUP.SYS) 4 THE CASSETTE HANDLER (C:) 5 THE KEYBOARD HANDLER (K:) 6 PRINTER HANDLER (P:) 7 SCREEN EDITOR (E:) 8 THE DISPLAY HANDLER (S:) 9 THE RESIDENT DISK HANDLER 10 SYSTEM INTERRUPTS 11 THE FLOATING POINT ARITHMETIC PACKAGE 12 BOOT SOFTWARE FORMATS 13 THE SERIAL INPUT/OUTPUT INTERFACE (SIO) 14 THE HARDWARE CHIPS 15 DISPLAY LISTS 16 PLAYER AND MISSILE (PM) GRAPHICS 17 SOUND 18 THE JOYSTICK PORTS 19 MISC 20 THE XL AND XE MODELS CHAPTER 1 THE CENTRAL INPUT/OUTPUT UTILITY, (CIO) The ATARI computer uses a very easy-to-use input and output system called the Central Input/Output utility, or CIO. Nearly all input or output passes through this utility. CIO uses eight "channels" as paths for I/O. There are not really separate channels for I/O but the computer acts as if there were. Each channel is controlled by a 16 byte block of memory called an Input/Output Control Block or IOCB. The channels are used by putting the proper numbers in the proper IOCB bytes then jumping to the CIO routine. In BASIC, complete I/O operations can be as easy as typing a command such as LPRINT. In this case BASIC does all the work for you. THE CIO CHANNELS There are eight CIO channels, numbered from 0 to 7. In BASIC some channels are reserved for BASIC's use. BASIC CIO channel assignments Channel 0 Permanently assigned to the screen editor 6 Used for graphics commands 7 Used for the Cassette, disk and printer Channels 6 and 7 are free to use when they are not being used by BASIC. With machine language, all of the channels are available to the programmer. THE IOCB STRUCTURE The IOCB for channel zero starts at address $0340 (decimal 832). This is the only address you need to know. Indexing from this address is used to find all of the other bytes. Below are the names and uses of the IOCB bytes. IOCB bytes and uses: ADDRESS NAME EXPLANATION $0340 ICHID handler Identifier $0341 ICDNO device number (disk) $0342 ICCOM command $0343 ICSTA status $0344 ICBAL buffer address (low byte) $0345 ICBAH buffer address (high byte) $0346 ICPTL address of put byte $0347 ICPTH routine (used by BASIC) $0348 ICBLL buffer length (low byte) $0349 ICBLH buffer length (high byte) $034A ICAX1 auxiliary information $034B ICAX2 - $034C ICAX3 the remaining auxiliary $034D ICAX4 bytes are rarely used $034E ICAX5 - $034F ICAX6 - ICHID When a channel is open, the handler I.D. contains an index to the handler table. The handler table (to be discussed later) holds the address of the device handling routines. When the channel is closed ICHID contains $FF. ICDNO The device number is used to distinguish between multiple devices with the same name, such as disk drives. ICCOM The command byte tells CIO what operation to perform. CIO command codes HEX DEC +Open $03 3 +close $0C 12 get $07 7 put $09 11 input $05 5 print $09 9 +status request $0D 13 +*special >$0D >13 + command may be made to a closed channel * device specific commands ICSTA The status byte contains an error code if something goes wrong. If bit 7 is 0 there have been no errors. ICBAL and ICBAH Before a channel is opened, the buffer address bytes are set point to the block of memory which contains the name of the device the channel is to be opened to. Before actual input or output these bytes are set to point to the block of memory where the I/O data is stored or is to be stored. ICPTL and ICPTH The put routine pointer is set by CIO to point to the handlers' put-byte routine. When the channel is closed the pointer points to the IOCB-closed routine. This pointer is only used by BASIC. ICBLL and ICBLH The buffer length bytes show the number of bytes in the block of memory used to store the input or output data. (See ICBAL and ICBAH.) If the amount of data read during an input operation is less than the length of the buffer, the number of bytes actually read will be put in ICBLL and ICBLH by CIO. ICAX1 through ICAX6 The auxiliary information bytes are used to give CIO or the device any special information needed. OPENNING A CIO CHANNEL Before using a CIO channel it must be assigned to an I/O device. In machine language you start by putting the channel number in the four high bits of the 6502 X register (X = $30 for channel three). Next you place the necessary codes (parameters) into IOCB 0 indexed by X. The X register will cause the numbers to be offset in memory by 16 times the channel number. This puts the numbers into the correct IOCB instead of IOCB 0. Below are the parameters used to open a channel. Channel-open parameters: ICCOM open code ICBAL address of device name ICBAH in memory ICAX1 direction code ICAX2 zero The direction code byte in ICAX1 takes on the following format: ICAX1 format for opening a channel 7 6 5 4 3 2 1 0 ----------------- ICAX1 | W R | ----------------- 8 4 2 1 W 1 = open for output (write) R 1 = open for input (read) ICAX1 may have the following data CIO direction codes HEX DEC operation $04 4 input $08 8 output $0C 12 input and output (cannot change the length of a disk file) ICBAL and ICBAH point to the device name stored in memory. The device and file name must be followed by 0 or $9B (decimal 155). Once the parameters are set, jumping (JSR) to the CIO vector (CIOV) at address $E456 (58454) will cause the channel to be opened. In the following example a basic knowledge of assembly language is assumed. Routine to open channel 1 to the keyboard: ICHID = $0340 ICCOM = ICHID+2 ICAX1 = ICHID+10 ICAX2 = ICHID+11 IOCB1 = $10 channel in four high bits CIOV = $E456 OPEN = $03 OREAD = $04 ;open for input ERROR = (address of error handling routine) ; START LDX IOCB1 LDA OPEN STA ICCOM,X LDA NAME STA ICBAH,X LDA OREAD STA ICAX1,X LDA #0 STA ICAX2,X JSR CIOV BPL OK JMP ERROR ; NAME .BYTE "K:",$9B OK (program continues here) To open a CIO channel in BASIC the OPEN command is used. BASIC OPEN command format: OPEN #channel,aux1,aux2,device:file name aux1 = direction code aux2 = special code To open channel 1 to the keyboard in BASIC Type: OPEN #1,4,0,"K:" The third parameter, aux2, is a rarely used special parameter. One use is to keep the screen from erasing when changing graphics modes. The fourth parameter is the device to open the channel to. It may be either a string in quotes or a string variable. CIO device names C cassette recorder *D disk drive E screen editor K Keyboard P printer *R RS 232 I/O port S screen handler * Uses a non-resident handler loaded by the device at power-up. The device name must usually be followed by a colon. With the disk drive a file name is expected after the device name. The screen handler is used for graphics. The screen editor uses both the keyboard handler and the screen handler to work between the keyboard and screen. USING AN OPEN CHANNEL Once a channel is opened to a device you have several options: INPUT: (ICCOM = $05) The computer reads data from the device until a carriage-return is read (decimal number 155, hex $9B) or the end of the file (EOF) is reached. A carriage return is also known as an End-Of-Line or EOL. The IOCB input parameters are: IOCB input parameters: ICCOM get record code ICBAL address of buffer to ICBAH store the data in ICBLL length of the data ICALH buffer The following routine demonstrates the input command in assembly language. Some of the equates are in the channel openning example above. Input routine: GETREC = $05 BUFF = (address to store data at) BUFLEN = (number of bytes available at storage address) : LDX IOCB1 LDA GETREC STA ICCOM,X LDA < BUFF STA ICBAL,X LDA > BUFF STA ICBAH,X LDA < BUFLEN STA ICBLL,X LDA > BUFLEN STA ICBLH,X JSR CIOV BPL OK2 JMP ERROR : OK2 (continues if no errors) If the data retrieved is shorter than the prepared buffer, the number of bytes actually read will be put into ICBLL and ICBLH. In BASIC, the INPUT command is used. BASIC INPUT command format: INPUT #channel,string variable or INPUT #channel,arithmetic variable For example: INPUT #1,IN$ The above commands will cause the data from the device to be put into the specified buffer (IN$ in the BASIC example) until an EOL is reached. If the INPUT statement is used again, without closing the channel, the computer will get more data from the device until another EOL is read or the end of the file is reached. The new data will write over the old data in the input string or buffer. If an arithmetic variable is used, only numbers can be input. PRINT: (ICCOM = $09) In assembly language the print command is identical to the input command. The only difference is that the PUTREC code ($09) is stored in ICCOM. Of course the buffer bytes of the IOCB then specify the block of memory to be output from rather than input to. With the print command, EOLs within the string or buffer are ignored but an EOL is placed at the end of the data when sent to the device. In BASIC, the PRINT command is used like INPUT except you want to use a semicolon instead of a comma to separate parameters. For example: PRINT #1;OUT$ or PRINT #1;"HELLO" If you use a comma, ten space characters will be sent before the string. If the print command is used again, without closing the channel, the new data will be appended to the end of the data previously sent. Old data will not be written over. GET: (ICCOM = $07) In BASIC this command inputs a single byte of data from the device. EOLs are ignored. In BASIC, GET is used like INPUT except an arithmetic variable must be used. For example: GET #1,IN If the get command is used again the next byte from the device will be read. If the end of a file is reached an error will occur. There is no command in BASIC to input an entire file without stopping at each EOL. If you wish to ignore EOLs while reading a file to a string, you must use the GET command. Each byte of data is then put into the string by the program. EXAMPLE: 10 OPEN #1,4,0,"D:TEST" 20 TRAP 60:REM GOES TO LINE 60 WHEN END OF FILE ERROR OCCURS 30 GET #1,IN 40 IN$(LEN(IN$)+1)=CHR$(IN) 50 GOTO 30 60 CLOSE #1 In assembly language, the get command can be used to get any number of bytes from the device. It works just as INPUT does except EOLs are ignored. IOCB get-byte parameters: ICCOM get-character (single byte) code ICBAL \ ICBAH same as in input ICBLL ICBAH / Other than the ICCOM code (GETCHR = $07) this command is identical to the input command. PUT: (ICCOM = $0B) In BASIC, PUT is the opposite of GET. It outputs a single byte from a variable to the device. PUT is used the same as GET. For example: PUT #1,OUT In assembly language, the command byte of the IOCB is loaded with the put-character code (PUTCHR = $0B). Otherwise the PUT command is identical to GET. CLOSING A CHANNEL Closing a channel frees it for use by another device or for changing parameters. In assembly language the close code is put into the command byte of the IOCB then the CIOV call is made. IOCB close command: CLOSE = $0C : LDX IOCB1 LDA CLOSE STA ICCOM,X JSR CIOV In BASIC, use the CLOSE command followed by the channel number. CLOSE #1 With the disk drive, the file name is not put into the directory until the channel is closed. THE DEVICE TABLE CIO uses a jump table located at $031A (794). When a CIO call is made, CIO searches the table for the one-byte device name. The two bytes following the device name contain the address of the device handler's vector table. CIO searches the device table from the end, $033D (829) to the beginning. This way, if a custom handler has ben substituted for a resident handler, the custom handler will be found first. (custom handlers cannot be inserted directly in the place of resident handlers in the device table.) Each handler has its' own vector table. This vector table is 16 bytes long. The two-byte vectors point to the various handler routines. The vectors are stored in the vector table in the following order: Handler vector table order open close get byte put byte get stat special JMP init code (3 bytes) The open routine should validate the ICAX parameters and check for illegal commands. The close routine should send any remaining data in the buffer to the device, mark the End-Of-File and update any directories, etc. The get byte routine should get a byte from the device or the handler buffer and put it in the 6502 A register. Handlers with long timouts must monitor the break key flag and put a $80 in the 6502 Y register if the [BREAK] key is pressed. The put byte routine should send the byte in the 6502 A register to the device or handler buffer. If the buffer fills, it should be sent to the device. BASIC can call the put byte routine without using CIO. The get status routine may get 4 bytes of status information from the device and put them in DVSTAT [$02EA] to DVSTAT+3. For special commands the handler must examine the command byte and find the proper routine entry point. In all cases the status (error code) of the operation should be put in the 6502 Y register. To be compatible with all versions of the operating system, the handler must redirect DOSINI [$000C,2 (12)] for initialization upon reset. This initialization must restore the vectors in the handler vector table and jump to the origional DOSINI vector. SPECIAL COMMANDS Some devices have special CIO commands. These are known as device specific commands. In assembly language these commands are executed just as any other CIO command is. In BASIC the XIO command is used. An example of the XIO command is: XIO command code #channel,aux1,aux2,device:file name To open a channel with the XIO command instead of the OPEN command use: XIO 3 #1,4,0,"K:" Note that the above command is identical to the OPEN command except "XIO 3" is used instead of "OPEN". Also note that $03 is the IOCB open code for ICCOM. Useful database variables and OS equates DOSINI $000C,2 (12): initialization vector BRKKEY $0011 (17): break key flag ICHID $0340 (832): start of IOCBs ICDNO $0341 (833): ICCOM $0342 (834): ICSTA $0343 (835): ICBAL $0344 (836): ICBAH $0345 (837): ICPTL $0346 (838): ICPTH $0347 (839): ICBLL $0348 (840): ICBLH $0349 (841): ICAX1 $034A (842): ICAX2 $034B (843): HATABS $031A,16 (794): device handler table CIOV $E456 (58454): CIO entry vector CHAPTER 2 THE DISK OPERATING SYSTEM (D:) The disk operating system program (DOS) is also called the file management system (FMS). DOS is not a permanent part of the computer, it is loaded in upon power-up if a disk drive is attached to the computer. When the computer is turned on, one of the first things it does is send a request to the disk drive to load DOS into the computer. This startup operation is called booting. The word boot is short for bootstrapping -- the start-up process of early computers. The term comes from "lifting one's self by one's boot straps". Anytime the disk boots, the computer tries to read a program starting at sector 1 and continuing in sequence. If the disk has DOS on it, the first three sectors, called the boot record, have a program which loads the DOS.SYS file. If there is no DOS.SYS file on the disk the computer will display: -------------------- | BOOT ERROR | | BOOT ERROR | | BOOT ERROR | | BOOT ERROR | | BOOT ERROR | | BOOT ERROR | | (etc.) | | | | | -------------------- When a disk is formatted, the drive read/write head passes over the entire disk and puts magnetic marks on it. These marks divide the disk into 32 concentric tracks. With DOS 2.0 each track is divided into 18 sectors, each holding 128 bytes of data. With DOS 2.5 there are 32 sectors per track giving a total of 1,024 sectors. Each sector on the disk is marked with a reference number from 1 to 720. Unfortunately, the writers of DOS 2.0 didn't know this so they wrote the DOS to use sectors numbered from 0 to 719. As a result, DOS 2.0 cannot access sector 720. The designers of the disk drive were the guilty party in this case. It is normal to number from 0 in computers. With DOS 2.5, sectors 720 - 1,024 can be accessed normally. Sector 720 can be accessed using the computer's resident disk handler. Some software writers use sector 720 to hide special information to make their programs difficult to copy. DOS 2 SECTOR ASSIGNMENTS Sectors 1 through 3 are called the boot record. They contain a program which loads the DOS.SYS file into memory. Sector 360 is called the Volume Table of Contents or VTOC. The main purpose of the VTOC is to keep track of what sectors are occupied. Bytes 3 and 4 of the VTOC tell how many sectors are available. Starting at byte 10 is the Volume Bit Map. Each byte in the VBM tells the status of eight sectors. If a bit is a 1 the sector is available. If a bit is a 0 the sector is occupied. Sectors 361 through 368 contain the disk directory. Each directory sector holds eight file names. The first byte of a file name is called the flag byte. It tells the status of that file. Directory flag byte. 7 6 5 4 3 2 1 0 ----------------- | flag byte | ----------------- Bits: 7 1 = file deleted 6 1 = file in use 5 1 = file locked 0 1 = open for output The next two bytes tell how many sectors are in the file. The two bytes after them tell the starting sector of the file. The last 11 bytes contain the file name. Sector 720 cannot be accessed with DOS 2.0. The boot record, VTOC, directory and sector 720 use 13 sectors. This leaves 707 sectors for storing files with DOS 2.0. Each file sector has 125 bytes of data. The last three bytes tell how many bytes of the sector are used, what directory entry the sector belongs to and which sector is next in the file. File sector structure 7 6 5 4 3 2 1 0 ----------------- | data | byte 0 - - - - | bytes | byte 124 ----------------- | Dir. No. |hi | byte 125 ----------------- |forward pointer| byte 126 ----------------- |S| byte count | byte 127 ----------------- hi = high 2 bits of forward pointer S = Short sector flag. 1 = short sector (End Of File) If the directory number does not match the order of the file name in the directory, an error 167 (file number mismatch) will occur. As a file is written to an empty disk it is put in consecutive sectors, 125 bytes at a time. After the file is written, the VTOC and directory are updated. When new files are written they also use consecutive sectors. When a file is deleted the status bit of the directory is changed to show that the file has been deleted. DOS then tracks the file, sector by sector, to find what sectors are used. Finally the VTOC is updated to show that the deleted file's sectors are available for new files. The file is not erased from the disk; only the VTOC and directory are changed. When a file is deleted, an "island" of free sectors may be left on the disk. When a new file is then written to the disk it will first use these new free sectors. When the island is used up, DOS will skip over the occupied sectors to the next free sector. This is the reason for the sector link. A file can end up with it's sectors scattered all over a disk. It can be complicated but it's efficient. DISK FILE STRUCTURE The first few bytes of a file may tell DOS or another program what kind of file it is. These information bytes are called a header. A text file is any file which has no header. A listed BASIC program is a type of text file. A letter from a word processor is another. A binary load file is a file intended to load to a specific address in memory. The first two bytes of a binary load file are decimal 255. The next two bytes hold the address at which the file is to load. The last two header bytes tell the ending address for the file. If the file is a program and is to run automatically, the initialization and run address are appended to the end of the file. binary load file header Decimal Hexadecimal 255 identifier FF 255 FF 0 start 00 7 07 15 end FF 8 08 The above file would load at address $0700 (1792 decimal) and end at address $08FF (2063). If a binary load file has initialization and run address appended to it they take on the following format: Init and run tailer CHR Decimal Hexadecimal init address format [b] 226 identifier E2 | 2 02 [c] 227 E3 | 2 02 n address nn n nn run address format [diamond] 224 identifier E0 | 2 02 [a] 225 E1 | 2 02 n address nn n nn [ ]=inverse video A program which doesn't need special initialization can be run at the init address. Otherwise, an RTS instruction is expected at the end of the initialization section. The computer will then jump to the run address if specified. INSIDE THE COMPUTER DOS uses the computer's CIO utility. When a DOS disk is booted a non-resident handler is loaded into memory. A new handler name, D, is then added to the handler table. When CIO is called with a device name of D: or Dn:, CIO will search the handler table for that device name. If the 'D' is found, the next two bytes in the table point to the DOS entry address. DOS FILE NAME CONVENTIONS DOS is unique among CIO handlers in that it requires an eight character file name to follow the device name. This file name may be followed by a period and then a three character extender. EXAMPLES: D:TEST, D2:FIREMAN, D:VENTURE.EXE, D:CHAPTER.001 The D2: is used for drive number two if present. The file name must use upper-case letters or numbers. The first character must always be a letter. WILD CARDS The characters * and ? may be used as wild cards. * means any combination of characters and ? means any single character. EXAMPLES: D:P* any file beginning with P and without an extender D:*.EXE any file with the extender .EXE D:*.* any file. D:F?REMAN one unknown character, FIREMAN or FOREMAN will match Wild cards can only be used to load, delete, lock and unlock files. When loading a file using wild cards, only the first matching file will be loaded. When renaming a file, both the new and old names are expected after the device name. EXAMPLE: D:OLDNAME.BAS,NEWNAME.BAS To format a disk, only the device name (D: or Dn:) is needed. USING DOS When a CIO channel is opened to the disk drive it must actually be opened to a specific file on the disk. The device name in the open command must be followed by a file name. When a channel is opened to the disk, two special parameters may be used in ICAX1. ICAX1 for disk open: 7 6 5 4 3 2 1 0 ----------------- | W R D A| ----------------- D 1 = open to read the directory instead of a file A 1 = append data to the end of the file This gives the following extra ICAX1 options. Disk specific ICAX1 options: HEX DEC $06 6 open to read directory $09 9 output, append to the end of an existing file READING THE DIRECTORY When the directory is read, each file name is treated as if it were followed by an EOL. A loop must be used to read all of the file names in the directory. The last entry read is the free sector count. After it is read, another read operation will result in an End-Of-File error. The disk drive has a number of device specific commands other than the regular CIO commands. From BASIC the XIO command is used to access these commands. The XIO command allows you to directly load the IOCBs from BASIC. Each parameter of the XIO command places values in certain bytes of an IOCB. XIO command format: XIO command channel,aux1,aux2,device:file name Note that the parameters resemble the BASIC OPEN command. The BASIC OPEN command is identical to it's equivalent XIO command. XIO commands specific to the disk drive. RENAME XIO $20 (32) DELETE XIO $21 (33) LOCK XIO $23 (35) UNLOCK XIO $24 (36) POINT XIO $25 (37) NOTE XIO $26 (38) FORMAT XIO $FE (254) EXAMPLES: XIO 33 #1,0,0,"D:JUNK" = delete file named D:JUNK XIO 32 #1,0,0,"D:OLD,NEW" = change name of D:OLD to D:NEW NOTE and POINT can also be used directly from BASIC. NOTE finds the current position of the read/write head on the disk. POINT moves the read/write head to the desired position. USING NOTE AND POINT The command format for NOTE and POINT is as follows: NOTE \ channel,sector,byte POINT/ EXAMPLE: NOTE #1,SECT,BYTE BASIC requires the sector and byte parameters in both commands to be variables. Fixed numbers cannot be used. If you try to do a POINT to a sector outside the file the channel is open to, a point error will occur. Care may need to be taken to be sure the file being accessed is in contiguous sectors on the disk. If it is not, it will be difficult to know where to do points to. One use of NOTE is to use the command immediately after opening a channel to a disk file. After the NOTE command, the parameter variables contain the coordinates of the first byte of the file. They can then be used as a reference for the POINT command. In assembly language, ICAX3 and ICAX4 are used for the sector number (lsb,msb). ICAX5 is used for the byte number. STATUS REQUEST If the status request command is used, one of the following values will be found in ICSTA and the 6502 Y register. HEX DEC $01 1 OK $A7 167 file locked $AA 170 file not found CHAPTER 3 USING THE DOS 2 UTILITIES (DUP.SYS) If you boot a DOS disk with no cartridge in the slot or with BASIC disabled (by holding the OPTION key), DOS will try to load the file named DUP.SYS. This is the disk utility file. When using BASIC, typing DOS [RETURN] will load the DUP.SYS file. When the utilities are loaded the menu will appear on the screen. THE DOS UTILITIES MENU DISK OPERATING SYSTEM II VERSION 2.0S COPYRIGHT 1980 ATARI A. DISK DIRECTORY I. FORMAT DISK B. RUN CARTRIDGE J. DUPLICATE DISK C. COPY FILE K. BINARY SAVE D. DELETE FILE(S) L. BINARY LOAD E. RENAME FILE M. RUN AT ADDRESS F. LOCK FILE N. CREATE MEM.SAV G. UNLOCK FILE O. DUPLICATE DISK H. WRITE DOS FILES SELECT ITEM OR [RETURN] FOR MENU [A] DIRECTORY After pressing [A] [RETURN] you will get the prompt: DIRECTORY--SEARCH SPEC,LIST FILE? If you want to see the entire directory just press [RETURN] again. If you wish, you may type in a specific file name (D: is optional) or wild cards to search for. If you specify a search spec only matching files will be displayed. If you want, you can have the directory sent to another device. To do this type a comma and the device name. For example, if you type ,P: the directory will be sent to the printer. [B] RUN CARTRIDGE If a cartridge was inserted or BASIC was not disabled when the computer was turned on, [B] [RETURN] will run that cartridge or BASIC. [C] COPY FILE This option will copy a file to another part of the same disk (with a different file name) or copy from one disk drive to another. When you press [C] [RETURN] you will be given the prompt: COPY--FROM,TO Type the devices and file names separated by a comma. EXAMPLES: FOREMAN,FIREMAN or D1:TEST,D2:TEST The first example will copy to the same disk. The second example will copy from disk drive one to disk drive two. If you want to have the first file appended to the end of the second file type /A after the file names. EXAMPLE: RUNMENU.EXE,AUTORUN.SYS/A If the files are binary load files, this will cause both files to be saved as one file. When the load command is used they will both be loaded and run. [D] DELETE FILE(S) After pressing [D] [RETURN] you will get the prompt: DELETE FILE SPEC After typing the file name you will be asked to confirm the file to delete. DELETE FILE SPEC DELETE-D1:JUNK ARE YOU SURE? Press [Y] if the correct file is displayed. If you use wild cards you will be asked to confirm each matching file. [E] RENAME Upon typing [E] [RETURN] you will be given the prompt: RENAME-GIVE OLD NAME,NEW Type the file name you want to change and the new name separated by a comma. EXAMPLE: COLT,HORSE WARNING! Do not rename a file to a name which already exists on the disk. You will end up with a duplicate file name and will not be able to access one of them. Attempting to rename or delete one of them will rename or delete both. The only way to fix a duplicate file name is with a sector editor or other special utility. [F] LOCK FILE A locked file cannot be written to, renamed or deleted. To lock a file type [F] [RETURN]. You will get the prompt: WHAT FILE TO LOCK? Type the file name you want to lock. Wild cards will cause all matching files to be locked. [G] UNLOCK FILE Used the same as lock. [H] WRITE DOS FILES This option will write the DOS.SYS and DUP.SYS files to a formatted disk. When you type [H] [RETURN] you will receive the prompt: DRIVE TO WRITE DOS FILES TO? Type the number of the drive. If the drive contains a formatted disk the dos files will be written to it. [I] FORMAT DISK This option formats a new disk or erases a disk with files on it. Typing [I] [RETURN] will get you the prompt: WHICH DRIVE TO FORMAT Be sure you have the correct disk in the proper drive then type the drive number. It is impossible to recover files on a disk formatted by accident. While the disk is being formatted the drive will check to be sure the disk is formatted correctly. If not, the drive attempt to format the disk again. If the disk is defective the drive will not finish the formatting process. [J] DUPLICATE DISK This option will copy an entire disk except for sectors listed as free in the VTOC. Some programs are copy-proofed by changing the VTOC to show that some occupied sectors are empty. For such disks, a program which copies the entire disk is needed. When you press [J] [RETURN] you will be given the prompt: DUP DISK--SOURCE,DEST DRIVES? If you are using only one disk drive, type 1,1. If you have only one drive you will be told when to swap disks. [K] BINARY SAVE This option saves a block of memory as a binary load file. When you type [K] [RETURN] you will be given the prompt: SAVE-GIVE FILE,START,END(,INIT,RUN) Type the desired file name and a comma. Now type the start and end addresses of the memory block to be saved, in hexadecimal numbers, separated by commas. If the file is a program which is to automatically run when loaded, give the initialization address, if needed, then the run address. EXAMPLE: CHASE.EXE,0700,09FF,,0700 This will save the block of memory from address 0700 to 09FF. The program is not initialized before running so there is no address typed after the third comma. When the program is loaded the computer will jump to address 0700, as specified in the last parameter, to run the program. [L] BINARY LOAD To load a binary file type [L] [RETURN]. You will get the Prompt: LOAD FROM WHAT FILE? Type the file name and the file will be loaded. If wild cards are used, only the first matching file will be loaded. [M] RUN AT ADDRESS Typing [M] [RETURN] will get the prompt: RUN FROM WHAT ADDRESS? Type the hexadecimal address of the program you want to run. [N] CREATE MEM.SAV A MEM.SAV file is used by BASIC and some other programs to save the part of memory which the DUP.SYS file loads into. If there is no MEM.SAV file on the disk when you go to the DOS utilities, you will loose that part of memory. With BASIC you will loose your program. When you type [N] [RETURN] you will get the prompt: TYPE Y TO CREATE MEM.SAV Typing [Y] [RETURN] will create a MEM.SAV file on the disk in drive one. [O] DUPLICATE FILE This option is used to copy a file from one disk to another, using only one disk drive. When you type [O] [RETURN] you will get the prompt: NAME OF FILE TO MOVE? If you use wild cards you will be asked to swap disks for each matching file. DOS 2.5 also has option: [P] FORMAT SINGLE DOS 2.5 normally formats disks to use "enhanced" density. This option will format a disk in single density for use with the 810 drive. DOS 2.5 also has some special utilities on the master disk. Use the binary load option to run them. RAMDISK.SYS This program will cause the extra bank of memory in the 130XE to act like a disk drive (called D8:). If this program is on the disk it will automatically run. It need not be renamed to AUTORUN.SYS. COPY32.COM Copies DOS 3 files to DOS 2. DISKFIX.COM Can make certain "repairs" to a disk, such as restoring deleted files. SETUP.COM Used to change the default configuration of DOS. AUTORUN.SYS (DOS 2.0 and 2.5) This program is needed to operate the RS-232 ports on the 850 interface. If you don't want this program to automatically load when you boot with the master disk, rename the file to RS232. SPECIAL DOS INFORMATION When DOS is in memory, changes can be made to the DOS program. These changes can be made by poking the changes into memory. If you want to make the changes permanent, you can type DOS [RETURN] to load the utilities. From the utilities menu you can use the write DOS files option to save the changes on disk. Some of the useful changes you can make follow. POKE 1913,80 This turns off the write verify and speeds up disk writing. POKE 1913,87 This turns write verify on POKE 5903,42 POKE 5904,46 POKE 5905,82 POKE 5906,85 POKE 5907,78 POKE 5908,155 This causes any binary file with the extender .RUN to be loaded automatically when the computer is turned on. POKE 5903,65 POKE 5904,85 POKE 5905,84 POKE 5906,79 POKE 5907,82 POKE 5908,85 This returns the DOS to normal, Automatically loading files named AUTORUN.SYS. DOS 2.0 DOS 2.5 POKE 3772,255 POKE 3818,64 POKE 3774,64 POKE 3822,123 POKE 3778,123 This will cause DOS to accept lower-case as well as upper-case letters in file names. It will also now accept @,[,\,],^ and _ . POKE 3772,223 POKE 3818,65 POKE 3774,65 POKE 3822,91 POKE 3778,91 This will change DOS back to normal, accepting only upper-case letters and numbers. CHAPTER 4 THE CASSETTE HANDLER (C:) The cassette handler sends data to the cassette recorder in blocks of 128 bytes each. The blocks are sent in the following format: Cassette record format ----------------- |0 1 0 1 0 1 0 1| speed measurement bytes ----------------- |0 1 0 1 0 1 0 1| ----------------- | control byte | ----------------- | 128 | = data = | bytes | ----------------- | checksum | handled by SIO ----------------- The control byte may have one of the following values. $FC (252) record is full. $FA (250) partly full, next record is EOF. $FE (254) EOF record, data section is all zeroes. The cassette handler has two modes of operation. The first mode uses only a short gap between records. It is called the no IRG (interrecord gaps) mode. The second mode uses longer gaps between records and is called the IRG mode. In the IRG mode the computer may stop the cassette recorder between records for processing data. When a channel is opened to the cassette recorder, bit 7 of ICAUX2 may be set to 1 (ICAX2 = $80 (128)). This will cause the cassette to use the no IRG mode. A cassette file starts with a 20 second mark tone. This tone is followed by the file records with 128 data bytes each. The final record is an End-Of-File record. The cassette is a straight-forward read/write device. There are no special functions other than those common to other CIO devices. The cassette motor is controlled by one of the controller port control registers. If bit 3 of PACTL [$D302 (54018)] is 0 then the cassette motor is on. The following BASIC commands will turn the cassette motor on and off. Cassette motor control. POKE 54018,PEEK(54018)-8 motor on POKE 54018,PEEK(54018)+8 motor off Useful data base variables and OS equates PACTL $D302 (54018): port A control register, bit 4 controls cassette motor CHAPTER 5 THE KEYBOARD HANDLER (K:) The keyboard is a read only device and therefore the keyboard handler has no output functions. The keyboard handler reads the keys as ATASCII codes. Each key is represented by one byte of data. Therefore, each time a key is pressed the data is treated as a byte of data just as data from any other device is. The only difference is that the computer must wait for the operator to press the keys as it reads the data. Whenever a key is pressed an IRQ interrupt is generated by the keyboard reading hardware. The internal code (not ATASCII) for the key just pressed is then stored in CH [$02FC (764)]. The code is then compared with the prior key code in CH1 [$02F2 (754)]. If the code in CH1 is different from the code in CH, the key is accepted. The code is then converted to ATASCII, and placed in the database variable ATACHR [$02FB (763)]. On XL and XE models, KEYDEF [$0079,2 (121)] points to the key-code-to-ATASCII conversion table. (This address is used by the the screen handler in 400/800 models). If the code in CH1 is the same as the code in CH, the new key code will not be accepted unless the key debounce timer, KEYDEL [$02F1 (753)] is 0. When CIO is told to do an input operation from the keyboard, CH is checked to see if a key has been pressed. If CIO finds $FF (255) in CH, it waits until a key is pressed. If CH is not $FF, a key has been pressed and the ATASCII code for that key is taken from ATACHR. CH is then set to $FF. The data in CH is in the following format. Key code format: 7 6 5 4 3 2 1 0 ----------------- |C|S| key code | ----------------- C 1 = [CTRL] key is pressed S 1 = [SHIFT] key is pressed Anytime a key is pressed, CH is loaded with the key code. CH will hold the code until the computer is commanded to read the keyboard. Sometimes the computer will read a key which was pressed long ago. If you want to prevent this, load CH with $FF before reading the keyboard. (In BASIC use POKE 764,255.) This will clear out any old key pressings. Special function keys [CTRL][1] screen output start/stop [CTRL][2] BELL [CTRL][3] Generates End-Of-File status [/|\] or [/] inverse video toggle [CAPS LOWER] sets lower case [CTRL][CAPS] sets CTRL lock [SHIFT][CAPS] sets caps lock KEYBOARD REPEAT DELAY AND RATE CONTROL On the XL and XE, KRPDEL [$02D9 (729)] determines the delay before the key repeat begins. The value of this byte is the number of vertical blanks (1/60th second each) to delay. KEYREP [$02DA (730)] determines the repeat rate in vertical blanks. KEYBOARD CLICK The keyboard click of the XL/XE is heard through the TV speaker. The click may be turned off by putting $FF in NOCLIK [$02DB (731)]. NON-HANDLER, NON-CIO KEYS The [OPTION], [SELECT] and [START] keys are read from the console switch register, CONSOL [$D01F (53279)]. The console switch register 7 6 5 4 3 2 1 0 ------------------------- CONSOL |0 |0 |0 |0 |SP|OP|SE|ST| ------------------------- 8 4 2 1 ST 0 = [START] SE 0 = [SELECT] OP 0 = [OPTION] SP Console speaker. set to 1 during vertical blank. toggleing this bit operates the speaker (which is heard through the TV on XL/XE models). This bit always reads 0 The [HELP] key on XL and XE models is read from HELPFG, [$02DC (732)]. This address is latched and must be reset to zero after being read. The [HELP] key register 7 6 5 4 3 2 1 0 ----------------- HELPFG |C S 0 H 0 0 0 H| ----------------- 1 6 3 1 8 4 2 1 2 4 2 6 8 H 1 = [HELP] (bits 0 and 4) S 1 = [SHIFT] C 1 = [CONTROL] Useful database variables and OS equates KEYDEF $0079,2 (121): key code coversion table vector (XL/XE) KRPDEL $02D9 (729): delay before key repeat (XL/XE) KEYREP $02DA (730): key repeat rate (XL/XE) NOCLIK $02DB (731): $FF turns off key click (XL/XE) HELPFG $02DC (732): [HELP] key (XL/XE) ATACHR $02FB (763): ATASCII Code for last key CH $02FC (764): keycode, $FF if no key has been pressed BRKKEY $0011 (17): break key flag, 0 = break key pressed SRTIMR $022B (555): Key delay and repeat timer SHFLOK $02BE (702): SHIFT/CTRL lock flag $00 = lower case $40 (64) = upper case lock $80 (128) = CTRL lock INVFLG $02B6 (694): inverse video flag, non-zero = inverse CONSOL $D01F (53279): start, select and option keys IRQEN $D20E (53774): IRQ interrupt enable bit 7 enables [BREAK] bit 6 enables other keys shadow registers POKMSK $0010 (16): IRQEN shadow CHAPTER 6 THE PRINTER HANDLER (P:) The printer is a write only device so the printer handler has no input functions. The printer handler has no special functions other than the CIO functions common to all other devices. Although many printers have special functions, the printer handler has no control over them. See your printer manual for information on special functions. CHAPTER 7 SCREEN EDITOR (E:) The screen editor uses both the keyboard handler and the screen handler to provide interactive control of the computer. In fact, the keyboard handler, the screen handler and the screen editor are contained in a single section of code and are therefore very closely related. The editor works with one line of characters at a time. The lines it works with are called logical lines and are up to three screen lines long. The screen editor inputs data from the keyboard and then prints the data on the screen. When the [RETURN] key is pressed, the editor inputs all of the data on the present logical line for processing by CIO. If characters are typed on the screen, and then the cursor is moved off the line, then back on the line, and new characters are typed, only the characters to the right of the reentry point of the cursor are input when [RETURN] is pressed. However, if the cursor is moved off the line again, then moved back on, all characters on that logical line are input. If bit 0 of ICAX1 is 1, the editor will act as if the [RETURN] key is being held down. This bit may be changed at any time. Editor control codes The screen editor treats certain ATASCII codes as special control codes. Screen editor control codes KEY HEX DEC FUNCTION [RETURN] $9B 155 carriage return or EOL [CLEAR] $7D 125 Clear screen,put cursor in upper left [UP ARROW] $1C 28 Move cursor up one screen line [DOWN] $1D 29 down one line [LEFT] $1E 30 left one character [RIGHT] $1F 31 right one character [BACK S] $7E 126 Back-space operation [SET TAB] $9F 159 sets tab stop at cursor [CLEAR TAB] $9E 158 Clear tab stop at cursor [TAB] $7F 127 move to next tab stop [SHIFT] [INSERT] $9D 157 Make space for a new line [SHIFT] [DELETE] $9C 156 delete the logical line at the cursor [CTRL] [INSERT] $FF 255 make room for a character [CTRL] [DELETE] $FE 254 delete character at cursor [ESCAPE] $1B 27 causes next non-EOL code to be displayed as an ATASCII character, even if it is an editor control code [CTRL][1] screen print start/stop [CTRL] $FD CHAPTER 8 THE DISPLAY HANDLER (S:) The display handler manages the computer's video display. Although no data ever leaves the computer through it, the display is treated like any other CIO device. Data sent to the screen may be displayed as either characters or point by point graphics. Although it is only visible in the 40 column text mode, mode 0, there is a cursor on the screen in all of the text or graphics modes. Whenever a character or graphics point is put on the screen, the cursor moves just as in mode 0. The display is capable of both input and output. Information can be put on the screen with any of the CIO output commands. An input command will find whatever is on the screen at the position of the cursor. When text or graphics is sent to the screen it is actually stored in an area of memory called the display buffer. What you see on the screen is the computer's interpretation of the data stored there. This will be explained further as each mode is covered. DISPLAY HANDLER SPECIAL FUNCTIONS: DRAW FILL SPECIAL ERROR STATUSES: $84 (132) Invalid special command. $8D (141) Cursor out of range. $91 (145) Nonexistant screen mode. $93 (147) Insufficient ram for screen mode. TEXT MODE 0 In graphics mode 0, data passes through CIO, and is stored in the display buffer in the following format. 7 6 5 4 3 2 1 0 ----------------- |I| Data | ----------------- I 1 = displays character in inverse video. Bits 0 through 6 select one of the 128 characters in the ATASCII set. If bit seven = 1, the character is displayed in inverse video. Converting the above byte to decimal will give the BASIC ASC(x) equivalent. The characters displayed in the text modes are determined by tHE ATASCII character set. This is a bit by bit representation of how the characters appear on the screen. The character set starts $E000 (57344) in the operating system ROM. From there, for 1K of memory, each eight bytes holds a "bit map" of a particular character. Below is how the letter A is stored in the character set. Letter A as represented in the C-set 7 6 5 4 3 2 1 0 ----------------- $E208 |0 0 0 0 0 0 0 0| ----------------- |0 0 0 1 1 0 0 0| * * ----------------- |0 0 1 1 1 1 0 0| * * * * ----------------- |0 1 1 0 0 1 1 0| * * * * ----------------- |0 1 1 0 0 1 1 0| * * * * ----------------- |0 1 1 1 1 1 1 0| * * * * * * ----------------- |0 1 1 0 0 1 1 0| * * * * ----------------- $E20F |0 0 0 0 0 0 0 0| ----------------- XL and XE models have an international character set starting at $CC00 (55224). In this character set the graphics characters are replaced by international characters. Custom characters sets may be loaded at any free address which is a multiple of 1,024 ($0400, or 1K). The database variable CHBAS [$02F4 (756)] stores the most significant byte (MSB) of the address of the active C-set. Since the LSB of the C-set address is always $00, no LSB is needed to find it. The data stored in the display buffer does not use the ATASCII code. A special code needed by the ANTIC chip is used. DISPLAY CODE / ATASCII CODE CONVERSION: ATASCII display $00 - $1F ( 0 - 31) = $40 - $5F (64 - 95) $20 - $5F (32 - 95) = $00 - $3F ( 0 - 63) $60 - $7F (96 - 127) = unchanged The codes for inverse video (the above codes with bit 7 set (= 1) or the above codes + 128 in decimal) are treated likewise. When you first turn on the computer, BASIC opens channel 0 to the screen editor (E:). The screen editor uses both the keyboard handler and the screen handler, in mode 0, to display characters when they are typed in. TEXT MODES 1 AND 2 Graphics modes 1 and 2 offer a split screen configuration if desired. The split screen has four lines of mode 0 at the bottom of the screen. In mode 1 the screen holds 20 characters horizontally and 24 characters vertically. In mode 2 the characters are twice as tall so the screen holds 12 vertically. In BASIC, characters are sent to the screen with the PRINT command. Since BASIC uses channel 6 for graphics you must specify channel 6 in the command. For example: ? #6;"HELLO" If you use a comma in place of the semicolon, ten spaces will print before the "HELLO" You can also use the PLOT and DRAWTO commands. In this case the COLOR command determines the character, as well as the color to be displayed. Data passes through CIO in the following form: 7 6 5 4 3 2 1 0 ----------------- | C | D | ----------------- C determines the color. C Default Color Shadow Color Register Register 0 green COLPF1 COLOR1 1 gold COLPF0 COLOR0 2 gold COLPF0 COLOR0 3 green COLPF1 COLOR1 4 red COLPF3 COLOR3 5 blue COLPF2 COLOR2 6 blue COLPF2 COLOR2 7 red COLPF3 COLOR3 D is a 5 bit ATASCII code which selects the character to be displayed. The database variable CHBAS selects between upper case (CHBAS=$E0 (224)) and lower case (CHBAS=$E2 (226)). GRAPHICS MODES 3 THROUGH 11 Modes 3 through 8 offer a split screen mode. In modes 9 through 11 special programming is required for split screens. These modes use dot by dot (pixel by pixel) graphics instead of character sets. Before explaining how graphics are sent to the screen through CIO, I will describe how the data in the display buffer is interpreted by the ANTIC chip. Mode 8 is the simplest of the graphics modes. Each byte of the display buffer controls eight pixels horizontally. The first 40 bytes of the display buffer control the first horizontal line of graphics. This makes a total of 320 pixels horizontally. If one of the eight bits of a byte is a 1 then the pixel it controls is on. If a bit is a 0 then it's pixel is off. For example, if a particular byte is equal to $9B (binary 10011011) then its' part of the screen would look like... * ** ** (10011011) In reality the pixels are assigned to different color registers. A color register is a byte of memory which controls the color of all pixels assigned to it. In mode 8, if a bit is = 0 it's pixel is assigned to the register called COLBK. If a bit is one, it's pixel is assigned to COLPF0. See COLORS below for more information on the color registers. You may notice a close similarity between mode 0 and mode 8. The major difference between these modes is where the dot by dot information comes from. In mode 8 this information comes from the display buffer. In mode 0 the display buffer contains codes telling what characters to display. The actual dot by dot information comes for the character set at $E000. In mode 7 each pixel is controlled by two bits. Therefore each byte only controls four pixels. There are also only 1/4 as many pixels on the screen as in mode 8. See mode 3 below for an explanation of how the each byte affects the pixels. In a graphics mode, when CIO sends a byte of data to the screen handler, that byte has information for only one pixel. Do not confuse a byte which CIO sends to the screen handler with the bytes in the display buffer. CIO sends data to or retrieves data from the screen in the following forms. 7 6 5 4 3 2 1 0 ----------------- |0 0 0 0 0 0| D | Modes 3,5,7 -- D = color ----------------- ----------------- |0 0 0 0 0 0 0|D| Modes 4,6,8 -- D = Color ----------------- ----------------- |0 0 0 0| D | Modes 9,10,11 -- D = data ----------------- Mode 3 uses a screen which is 40 pixels horizontally and 24 vertically. Each pixel is a square the size of a mode 0 character. It requires 273 bytes of RAM where each byte controls 4 pixels. Each pair of bits controls which of the four color registers their pixel is assigned to. display buffer byte for mode 3 7 6 5 4 3 2 1 0 ----------------- | D | D | D | D | ----------------- P1 P2 P3 P4 Pixel/color register assignments: D = 00 COLBK (COLOR4) 01 COLPF0 (COLOR0) 10 COLPF1 (COLOR1) 11 COLPF2 (COLOR2) Mode 4 uses a screen of 80 columns by 48 rows. Each pixel is half the size of those in mode 3. Mode 4 requires 537 bytes of RAM where each byte controls 8 pixels. This mode is very similar to mode 8 except there are fewer but larger pixels. Mode 5 uses a screen of 80 columns by 48 rows. The pixels are the same size as in mode 4. Mode 5 requires 1,017 bytes of RAM where each byte controls 4 pixels in the same manner as in mode 3. Mode 6 uses a screen of 160 columns by 96 rows. It requires 2,025 bytes of RAM where each byte controls 8 pixels as in mode 4. Mode 7 uses a screen of 160 columns by 96 rows. It requires 3,945 bytes of RAM where each byte controls 4 pixels as in modes 3 and 5. Modes 8 through 11 (and 15 on XL and XE models) each require 7,900 bytes of RAM and are very similar in display set up. The main differences between these modes is the interpretation of data in the display buffer. Mode 15 (sometimes called mode 7.5) uses a screen of 160 columns by 192 rows. Each byte controls 4 pixels as in mode 7. The main difference between mode 15 and its related modes is bit 0 of each instruction byte in the display list (the program which the ANTIC chip uses). If this bit is 0 the screen is interpreted as mode 15. If the bit is 1 the screen is interpreted as modes 8 through 11. Modes 8 through 11 are set up identically in memory, including the display list. The only difference is the data in the PRIOR register of the GTIA chip. The shadow register for PRIOR is GPRIOR [$026F (623)]. Mode 8 (PRIOR = $00 - $3F (0 - 63)), uses a screen of 320 columns by 192 rows. Each byte controls 8 pixels as in modes 4 and 6. Mode 9 (PRIOR = $40 - $7F (64 - 127)) uses a screen of 80 columns by 192 rows. Each byte controls 2 pixels. The pixels are all of the same color, controlled by COLBK. Each half of a byte in the display buffer controls the luminance of the assigned pixel. The format of each byte is as follows. 7 6 5 4 3 2 1 0 ----------------- | data | data | ----------------- pixel 1|pixel 2 Mode 10 (PRIOR = $80 - $BF (128 - 191), is the same as mode 9 except 9 color luminance combinations are available. The data in each half byte chooses one of the 9 color registers for the assigned pixel. Mode 11 (PRIOR = $C0 - FF (192 - 255), is the same as mode 9 except there is one brightness but 16 colors. The pixel data chooses one of the 16 available colors. The luminance is that of the background (COLBK). USING THE SCREEN HANDLER OPENING A CHANNEL TO THE SCREEN HANDLER When a channel is opened to the screen handler the following actions take place: The area of memory to be used for the screen data is cleared. A display list (program for the ANTIC chip) is set up for the proper graphics mode. The top-of-free-memory pointer, MEMTOP [$02E5,2 (741)], is set to point to the last free byte before the display list. Before opening a channel to the screen handler, the pointer to the highest memory address needed by the program, APPMHI [$000E,2 (14)], should be properly set. This will prevent the screen handler from erasing part of the program when it sets-up the screen data region. When the channel is opened, two special options can be sent with the direction parameter (ICAX1). ICAX1 for screen open 7 6 5 4 3 2 1 0 ----------------- | C S W R | ----------------- 1 6 3 1 8 4 2 1 2 4 2 6 8 C 1 = don't clear the screen S 1 = split screen R 1 = input W 1 = output Before the open command, the graphics mode number is placed into ICAX2. ICAX2 for screen open 7 6 5 4 3 2 1 0 ----------------- | : mode | ----------------- mode = $00 through $0B (0 - 11 (0 - 15 on XL/XE)) To open a channel to the screen in BASIC use the GRAPHICS command. BASIC screen open format GRAPHICS mode For Example: GRAPHICS 8 This will set up a mode 8 graphics screen and open channel 6 to it. If the graphics mode is 1 - 8, a split screen will be set up. For example, GRAPHICS 8 will set up a mode 8 screen with a four line text window at the bottom. If 16 is added to the mode number, a full screen will be set-up. For example, GRAPHICS 8+16 or GRAPHICS 24 will set up a mode 8 screen, with no text window, a full 192 pixels high. If the number 32 is added to the mode number, the screen will not clear when the channel opens. If you want to use a channel other than #6, you will have to use the open command. It is used in the following format. screen open without GRAPHICS command OPEN #channel,direction/special,mode,S: For example: OPEN #1,8,7,S: This will open channel 1 to a mode 7 screen for output only. For use of special parameters, see ICAX1 above. USING AN OPEN CHANNEL TO THE SCREEN Once a channel is opened to the screen it is used like any other input or output device. In other words, data is placed on the screen by the PRINT and PUT commands. Data is retrieved from the screen with the INPUT and GET commands. The part of the screen which the data will be put in or taken from is determined by the X,Y coordinants in the database variables COLCRS [$0055,2 (85)] and ROWCRS [$0054 (84)]. What appears on the screen depends on what graphics mode the computer is in. Before sending data to the screen in BASIC, a color register must be assigned to the data. Once a point is plotted on the screen, it's color will be determined by the color register it was assigned to. To assign a color to a ploted point, the COLOR command us used as follows. COLOR command format COLOR register For example, COLOR 1 After using the above command, all points plotted will be controlled by color register 1. To change color registers, use the COLOR command again. In assembly language, the color is determined by the data sent to the screen. See the above section on graphics modes for color information. In BASIC the PLOT command is used to put data on the screen. The PLOT command is used as follows. The BASIC PLOT command PLOT x,y x and y are the horizontal and vertical coordinates for the plotted point. In modes 3 through 11 a single point will be plotted. In modes 1 and 2 a text character will be printed on the screen by the PLOT command. The PRINT and PUT commands can also be used in basic. What appears on the screen depends on the graphics mode. In modes 1 and 2 the ATASCII characters sent to the screen will be printed just as in mode 0. See the paragraph on modes 1 and 2 above for more information. In the other modes what appears depends on how the ANTIC chip interprets the data bytes sent to the screen. For example, in mode 8, even numbered characters will be single pixels in color 1. Odd numbered characters will be in color 0 (background). There are two special commands for the screen handler, DRAW and FILL DRAW (ICCOM = $11 (17)) The draw command works exactly like the plot command except a straight line is drawn from the previous pixel to the new one. In BASIC it is used in the following format. the BASIC DRAW command DRAWTO x,y FILL (ICCOM = $12 (18)) Fill works like draw except the area to the right of the drawn line will be filled with the color in FILDAT [$02FD (765)]. The fill command expects to find a boundary to the right. If no boundary is found, the entire horizontal screen between the ends of the line is filled. To use the fill command in BASIC the XIO command must be used in the following format. POSITION x,y XIO 18 #6,0,0,"E:" Note that the cursor is first moved by the POSITION command. Below is an example of how to prepare for and use the fill command. using the fill command 2nd DRAWTO .____. DRAWTO here | | | | | | fill to here ! ! PLOT here This will draw and fill a box on the screen. THE COLOR REGISTERS There are nine bytes of memory which control the colors on the screen. These bytes are called color registers. The color registers have the following names and relationships. Color registers and relationships Register Register modes name address 0 & 8 1 & 2 3 5 7 4 & 6 9 & 11 10 HEX decimal COLOR numbers PCOLR0 $02C0 704 0 PCOLR1 $02C1 705 1 PCOLR2 $02C2 706 2 PCOLR3 $02C3 707 3 COLOR0 $02C4 708 0 - 63 1 1 4 COLOR1 $02C5 709 1 - 255 64 -127 2 5 COLOR2 $02C6 710 0 128-191 3 6 COLOR3 $02C7 711 192-255 7 COLOR4 $02C8 712 border backgnd 0 backgnd backgnd 8 The color numbers are in decimal. These are actually shadow registers. See the O.S. equates below for relationships. In modes 0 - 3 the COLOR number actually determines the character printed The register to which a pixel/character is assigned to is determined by the data byte sent to the screen through CIO. The data in the color registers in in the following format. Color register data format 7 6 5 4 3 2 1 0 ----------------- | color |bright | ----------------- color = one of 16 possible colors bright = one of 8 possible brightnesses (even numbers, 0 - E) In basic, the COLOR command is used to assign color registers. The corresponding registers depends on the graphics mode. For example, COLOR 0 is COLOR2 in mode 8. In most other modes COLOR 0 is COLOR4. See the above chart for the register relationships. To change the contents of the color registers in BASIC, the SETCOLOR command is used. In all modes except mode 10, the SETCOLOR command refers to the registers COLOR0 to COLOR4. SETCOLOR/register relationships SETCOLOR 0 COLPF0 (COLOR0) SETCOLOR 1 COLPF1 (COLOR1) SETCOLOR 2 COLPF2 (COLOR2) SETCOLOR 3 COLPF3 (COLOR3) SETCOLOR 4 COLBK (COLOR4) The format for the SETCOLOR command is... SETCOLOR command format SETCOLOR register,hue,brightness register = 0 - 4 (0 - 8 in mode 10) hue = 0 - 15 (16 colors) brightness = 0 - 16 (even numbers only (8 brightnesses) The following chart gives the colors represented by the hue number. colors represented by hue numbers 0 grey 8 blue 1 gold 9 cyan 2 gold-orange 10 blue-green 3 red-orange 11 blue-green 4 orange 12 green 5 magenta 13 yellow-green 6 purple-blue 14 yellow 7 blue 15 yellow-red The attract mode If a key is not pressed for more than 9 minutes the computer will enter the attract mode. This mode is used to prevent burning of the TV phosphors by lowering the brightness and constantly changing the colors. The attract mode timer, ATRACT [$004D (77)], is set to 254 ($FE) when the the attract mode is entered. To force the computer out of the attract mode, poke a number less than 127 into ATRACT. Useful database variables and OS equates APPMHI $000E,2 (14): lower limit for screen region ATRACT $004D (77): attract mode timer and flag LMARGN $0052 (82): left margin RMARGN $0053 (83): right margin ROWCRS $0054 (84): horizontal cursor position COLCRS $0055,2 (85): vertical cursor position DINDEX $0057 (87): current graphics mode SAVMSC $0058,2 (88): starting address of display buffer OLDROW $005A (90): previous cursor position OLDCOL $005B,2 (91): " " " OLDCHR $005D (93): character currently at the text cursor OLDADR $005E,2 (94): memory address of cursor RAMTOP $006A (106): end-of-RAM + 1 (MSB only) SDLSTL $0230,2 (560): shadow register of display list address TXTROW $0290 (656): text window cursor position TXTCOL $0291,2 (657): " " " " TXTMSC $0294,2 (660): starting address of text window data buffer RAMSIZ $02E4 (740): permanent end-of-RAM + 1 (MSB only) CRSINH $02F0 (752): cursor inhibit, 1 = no cursor FILDAT $02FD (765): color data for fill DSPFLG $02FE (766): if >0 screen control codes are displayed as ATASCII characters (EOL is uneffected) SSFLAG $02FF (767): > 0 = stop screen print COLPM0 $D012 (53266): actual color registers COLPM1 $D013 (53267): loaded from shadow COLPM2 $D014 (53268): registers during COLPM3 $D015 (53269): vertical blank COLPF0 $D016 (53270): COLPF1 $D017 (53271): see above COLPF2 $D018 (53272): for use COLPF3 $D019 (53273): COLBK $D020 (53274): OS shadow registers PCOLR0 $02C0 (704): COLPM0 PCOLR1 $02C1 (705): COLPM1 PCOLR2 $02C2 (706): COLPM2 PCOLR3 $02C3 (707): COLPM3 COLOR0 $02C4 (708): COLPF0 COLOR1 $02C5 (709): COLPF1 COLOR2 $02C6 (710): COLPF2 COLOR3 $02C7 (711): COLPF3 COLOR4 $02C8 (712): COLBK CHAPTER 9 THE RESIDENT DISK HANDLER The resident disk handler is separate from DOS and is part of the permanent operating system ROM. The disk handler does not use CIO. The resident disk handler works with one sector at a time. It is used by setting the drive number, sector number, and operation code in the device control block. The program then jumps (JSR) to the handler entry vector, DSKINV [$E453 (58451)]. Device control block (for resident disk handler) DDEVIC [$0300 (768)] Serial bus I.D. Set by handler DUNIT [$0301 (769)] Drive number DCOMND [$0302 (770)] Command byte DSTATS [$0303 (771)] status byte DBUFLO [$0304 (772)] DBUFHI [$0305 (773)] Pointer to 128 byte memory block for data storage. DTIMLO [$0306 (774)] Timeout value (response time limit) in seconds DBYTLO [$0308 (776)] DBYTHI [$0309 (777)] number of bytes transferred, set by handler DAUX1 [$030A (778)] DAUX2 [$030B (779)] sector number DISK HANDLER COMMANDS GET SECTOR Before the JSR to DSKINV is made the following parameters are set. GET SECTOR parameters DCOMND = $52 (82) DUNIT = (1 - 4) DBUFHI and DBUFLO = address of 128 byte buffer DAUX1 and DAUX2 = Sector number (LSB,MSB) This operation will read the specified sector and put the data into the specified buffer. PUT SECTOR PUT SECTOR is used the same as GET SECTOR except for DCOMND. PUT SECTOR parameters DCOMND = $50 (80) This operation sends the data in the specified buffer to the specified disk sector. PUT SECTOR WITH VERIFY PUT SECTOR WITH VERIFY is used the same as PUT SECTOR except for DCOMND. PUT SECTOR WITH VERIFY parameters DCOMND = $57 (87) This operation sends the data in the specified buffer to the specified disk sector then checks for errors. GET STATUS Only the DUNIT and DCOMND need to be set GET STATUS parameters DCOMND = $53 (83) DUNIT = (1 - 4) The status information will be put in three bytes starting at DVSTAT [$02EA (746)]. Status format 7 6 5 4 3 2 1 0 ----------------- DVSTAT + 0 | command stat | ----------------- + 1 | hardware stat | ----------------- + 2 | timeout value | ----------------- The command status byte gives the following information. Bit 0 1 = invalid command frame received 1 1 = invalid data frame received 2 1 = unsuccessful PUT operation 3 1 = disk is write protected 4 1 = active/standby The hardware status byte contains the status register of the ISN1771-1 disk controller chip. The timeout byte contains the maximum allowable response time for the drive in seconds. FORMAT DISK The handler will format then verify the the disk. The numbers of all bad sectors (up to 63) will be put into the specified buffer followed by two bytes of $FF. The following parameters are set before the call. FORMAT parameters DCOMND = $21 (33) DUNIT = (1 - 4) DBUFLO and DBUFHI = address of bad sector list (buffer) After the operation the status byte is set. Also, DBYTLO and DBYTHI will contain the number of bytes of bad sector information (not including the two $FF bytes). Useful data base variables and OS equates DVSTAT $02EA,3 (746): device status block, 3 bytes DDEVIC $0300 (768): serial bus I.D. DUNIT $0301 (769): device number DCOMND $0302 (770): command byte DSTATS $0303 (771): status byte DBUFLO $0304 (772): data buffer DBUFHI $0305 (773): pointer DTIMLO $0306 (774): timeout value DBYTLO $0308 (776): number of bytes transfered DBYTHI $0309 (777): DAUX1 $030A (778): sector DAUX2 $030B (779): number DSKINV $E453 (58451): disk handler entry vector CHAPTER 10 SYSTEM INTERRUPTS There are four types of interrupts which can occur with the 6502 microprocessor: 6502 interrupts 1. chip reset 2. IRQ, interrupt request (maskable) 3. MNI (non-maskable interrupt) 4. software interrupt (BRK instruction) CHIP RESET On the 400/800 the chip reset occurs only upon power-up and causes the computer to do a cold start. On later models, pressing [SYSTEM RESET] will cause a chip reset but the computer then does a warm start. On the 400/800, the [SYSTEM RESET] key generates a NMI interrupt. COLD START This is a synopsis of the cold start routine. 1 The warm start flag [$0008] is set to 0 (false) 2 If a cartridge slot contains a diagnostic cartridge, control is handed to the cartridge. 3 The end of RAM is determined by trying to complement the first byte of each 4K block of memory. 4 Hardware registers at $D000 - $D4FF (except $D100 - $D1FF) are cleared. 5 RAM is cleared from $0008 to the top of ram. 6 The user program jump vector, DOSVEC [$000A] is set to point to the black board mode (Atari logo display mode in XL/XE models). 7 The screen margins are set to 2 and 39 8 Interrupt vectors are initialized. 9 Bottom of free RAM pointer, MEMLO [$02E7], is set to point to $0700. 10 Resident CIO handlers are initialized. 11 If the [START] key is pressed the cassette boot request flag, CKEY [$004A], is set. 12 The CIO device table is initialized. 13 If a cartridge is present it is initialized. 14 Channel 0 is opened to the screen editor. The top-of-free-RAM pointer, MEMTOP [$02E5], is set to point below the screen region. The computer then waits for the screen to be established before continuing. 15 If the cassette boot flag is set the cassette is booted. 16 If there is no cartridge present or a cartridge doesn't prevent it, the disk is booted. 17 The cold start flag is reset. 18 If there is a cartridge present, the computer jumps to the cartridge's run vector. 19 If there is no cartridge present the computer jumps through the vector DOSVEC [$000A (10)]. DOSVEC will point to either a booted program, the memo pad routine (400/800) or the logo display routine (XL/XE). WARM START 1 The warm start flag is set to $7F (true). 2 cold start steps 2 - 4 are executed. 3 RAM is cleared from $0010 - $007F and $0200 - $03FF. 4 Cold start steps 7 - 14 are executed. 5 If cassette booted software is present the computer JSRs through CASINI [$0002]. 6 If disk booted software is present the computer JSRs through DOSINI [$000C (12)]. The difference between cold start and warm start is the condition of the warm start flag, WARMST, [$0008]. If this flag is 0 a complete cold start is executed. If the flag is anything other than 0 then only the warm start part of the warm start/cold start code is executed. NON-MASKABLE INTERRUPTS (NMI) NMI interrupts are generated by the following conditions: 1. Display list interrupt, generated by the ANTIC chip. 2. TV vertical blank interrupt, generated by the ANTIC chip. 3. [SYSTEM RESET] key (400/800). When an NMI interrupt occurs, the hardware register NMIST [$D40F] is examined to determine what type of interrupt occurred. The computer is then directed through the proper ram vector to service the interrupt. DISPLAY LIST INTERRUPTS (DLIs) The computer makes no use of DLIs. The ram vector points to an RTI instruction. VERTICAL BLANK INTERRUPTS (VBIs) There are two stages to the VBI service routine. The second stage is only done if a critical function was not interrupted. Stage 1 (VBI) The real time clock, RTCLOK [$0012 - $0014], is incremented. The attract mode variables are processed. System timer 1 is decremented. If it goes to zero the computer JSRs through system time-out vector 1. Stage 2 (VBI) The hardware registers are loaded with the data in their shadow registers. System timer 2 is decremented. If it goes to zero the computer JSRs through the system time-out vector 2. System timers 3, 4, and 5 are decremented. If a timer goes to zero the computer sets system timer flags 3, 4, and/or 5. If auto-repeat is active, the auto-repeat process is done. The keyboard debounce timer is decremented if not 0. Information at the controller port registers is read, processed and placed in the proper shadow registers. [SYSTEM RESET] INTERRUPT If a [SYSTEM RESET] interrupt is generated on the 400/800 the computer jumps to the warm start routine. INTERRUPT REQUESTS (maskable interrupts (IRQs)) When an IRQ interrupt occurs the hardware register IRQST [$D20E], the PIA status registers, PACTL [$D302] and PBCTL [$D303] are examined to determine what caused the interrupt. For each interrupt, the 6502 accumulator is pushed to the stack. The computer is then directed to the proper ram vector to service the interrupt. SOFTWARE INTERRUPT (BRK instruction) The operating system doesn't use software interrupts. The software interrupt vector points to a PLA followed by an RTI. Interrupt vectors Label address type function VDSLST $0200 NMI DLI Points to an RTI VVBLKI $0222 NMI stage 1 VBI VVBLKD $0224 NMI return-from-interrupt routine CDTMA1 $0226 NMI time-out 1 (used by SIO) CDTMA2 $0228 NMI time-out 2 (not used by OS) VPRCED $0202 IRQ not used (points to PLA,RTI) VINTER $0204 IRQ not used (PLA,RTI) VKEYBD $0208 IRQ keyboard interrupt VSERIN $020A IRQ used by Serial I/O routine VSEROR $020C IRQ used by SIO VSEROC $020E IRQ used by SIO VTIMR1 $0210 IRQ not used by OS (PLA,RTI) VTIMR2 $0212 IRQ not used by OS (PLA,RTI) VTIMR4 $0214 IRQ ? VIMIRQ $0216 IRQ main IRQ code VBREAK $0206 BRK unused by OS (PLA,RTI) SYSTEM TIMERS The following timers are updated during vertical blank (VBI) as noted above. If a timer is decremented to 0 the computer jumps through it's associated vector or sets it's associated flag. Label address flag/vector RTCLOK $0012 3 byte clock ($0012 = MSB) CDTMV1 $0218 CDTMA1 $0226 vector (SIO time-out) CDTMV2 $021A CDTMA2 $0228 vector CDTMV3 $021C CDTMF3 $022A flag CDTMV4 $021E CDTMF4 $022C flag CDTMV5 $0220 CDTMF5 $022E flag HARDWARE INTERRUPT CONTROL There are two registers on the antic chip which control interrupts. These registers can be used to disable interrupts if necessary. There are also two associated interrupt status registers. The IRQ enable and status registers use the same address. The result is that reading the register does not reveal the enabled interrupts but the interrupts pending. IRQ interrupt enable data should usually be written to the OS shadow first. Reading the OS shadow tells which interrupts are enabled. Non maskable interrupt enable NMIEN $D40E 7 6 5 4 3 2 1 0 ----------------- | | | not used | ----------------- bit 7 1 = DLI enabled 6 1 = VBI enabled Non maskable interrupt status NMIST $D40F 7 6 5 4 3 2 1 0 ----------------- | | | | not used| ----------------- bit 7 1 = DLI pending 6 1 = VBI pending 5 1 = [SYSTEM RESET] key pending Interrupt request enable IRQEN $D20E 7 6 5 4 3 2 1 0 ----------------- | | | | | | | | | ----------------- bit 7 1 = [BREAK] key interrupt enable 6 1 = keyboard interrupt enable 5 1 = serial input interrupt enable 4 1 = serial output interrupt enable 3 1 = serial output-finished interrupt enable 2 1 = timer 4 interrupt enable 1 1 = timer 2 interrupt enable 0 1 = timer 1 interrupt enable IRQEN has a shadow register, POKMSK [$0010 (A)]. Interrupt request status IRQST $D20E 7 6 5 4 3 2 1 0 ----------------- | | | | | | | | | ----------------- bit 7 1 = [BREAK] key interrupt pending 6 1 = keyboard interrupt pending 5 1 = serial input interrupt pending 4 1 = serial output interrupt pending 3 1 = serial output-finished interrupt pending 2 1 = timer 4 interrupt pending 1 1 = timer 2 interrupt pending 0 1 = timer 1 interrupt pending WAIT FOR HORIZONTAL SYNC Writing any number to WSYNC [$D40A (54282)] will cause the computer to stop and wait for the next TV horizontal sync. It is wise to use DLIs one TV line before needed then writing to WSYNC. This will keep other interrupts from causing DLIs to be serviced late. This can cause a DLI to change something in the middle of a scan line. Useful database variables and OS equates POKMSK $0010 (16): IRQEN shadow IRQEN $D20E (53774): enables IRQs when written to IRQST $D20E (53774); gives IRQs waiting when read PACTL $D302 (54018): bit 7 (read) peripheral A interrupt status bit 0 (write) peripheral A interrupt enable PBCTL $D303 (54019): bit 7 (read) peripheral B interrupt status bit 0 (write) peripheral B interrupt enable WSYNC $D40A (54282): wait for horizontal sync NMIEN $D40E (54286): NMI enable NMIST $D40F (54287): NMI status CHAPTER 11 THE FLOATING POINT ARITHMETIC PACKAGE The routines which do floating point arithmetic are a part of the operating system ROM. The Atari computer uses the 6502's decimal math mode. This mode uses numbers represented in packed Binary Coded Decimal (BCD). This means that each byte of a floating point number holds two decimal digits. The actual method of representing a full number is complicated and probably not very important to a programmer. However, for those with the knowledge to use it, the format is given below. Floating point number representation byte 0 xx excess 64 exponent + sign xx \ xx \ xx > 10 BCD digits xx / byte 7 xx / The decimal point is shifted to left of the MSD and the exponent is adjusted accordingly. Therefore, the decimal point doesn't need to be represented. For programming purposes, floating point numbers can be in ASCII code. It takes up to 14 bytes to store a floating point number in this manner. The floating point package has a routine to convert numbers between ASCII and floating point. USE OF THE FLOATING POINT PACKAGE The floating point package has several routines to convert between ASCII and FP and to do the arithmetic functions. These are the important data base variables. Floating point data base variables FR0 $00D4,6 (212): 6 byte buffer for floating point number FR1 $00E0,6 (224): 6 byte buffer for floating point number CIX $00F2 (242): index for INBUFF address INBUFF $00F3,2 (243): 2 byte pointer to ASCII floating point number FLPTR $00FC,2 (252): 2 byte pointer to user buffer for floating point number LBUFF $0580,? (1408): result buffer for FASC routine MAKING THE CALL To do a floating point function, first set the proper pointers and JSR to the operation entry point. Below is a list of the entry points and parameters. ASCII to floating point Converts ASCII representation pointed to by INBUFF to FP in FR0. AFP = $D800 INBUFF = address of ASCII number CIX = buffer offset if any JSR AFP FLOATING POINT TO ASCII Converts floating Point number in FR0 to ASCII. The result will be in LBUFF. INBUFF will point to the ASCII number which will have the bit 7 of the last byte set to 1. FASC = $D8E6 JSR FASC INTEGER TO FLOATING POINT CONVERSION. Converts a 2 byte unsigned integer (0 to 65535) in FR0 to floating point in FR0. IFP = $D9AA JSR IFP FLOATING POINT TO INTEGER CONVERSION. Converts floating point number in FR0 to 2 byte integer in FR0. FPI = $D9D2 JSR FPI BCS overflow ADDITION Adds floating point numbers in FR0 and FR1 with result in FR0. FADD = $DA66 JSR FADD BCS out of range SUBTRACTION subtracts FR1 from FR0 with the result in FR0. FSUB = $DA60 JSR FSUB BCS out of range MULTIPLICATION Multiplies FR0 by FR1 with the result in FR0. FMUL = $DADB JSR FMUL BCS out of range DIVISION Divides FR0 by FR1 with result in FR0. FDIV = $DB28 JSR FDIV BCS out of range or divisor is 0 LOGARITHMS Puts logarithm of FR0 in FR0 LOG = $DECD LOG10 = $DED1 JSR LOG ;for natural log. or JSR LOG10 ;for base 10 log. BCS negative number or overflow EXPONENTIATION Put exponentiation of FR0 in FR0 EXP = $DDC0 EXP10 = $DDCC JSR EXP ;for e ** Z or JSR EXP10 ;for 10 ** Z POLYNOMIAL EVALUATION Puts the result of an n degree polynomial evaluation of FR0 in FR0. PLYEVL = $DD40 LDX LSB of pointer to list of floating point coefficients, ordered high to low. LDY MSB of above LDA number of coefficients in list JSR PLYEVL BCS overflow CLEAR FR0 Sets FR0 to all zeroes ZFR0 = $DA44 JSR ZFR0 CLEAR ZERO PAGE FLOATING POINT NUMBER Clears user floating point number in page zero. ZF1 = $DA46 LDX address of zero page FP buffer JSR ZF1 LOAD FR0 WITH FLOATING POINT NUMBER Loads FR0 with user FP number in buffer pointed to by 6502 X and Y registers or by FLPTR. After either operation below, FLPTR will point to the user FP buffer. FLD0R = $DD89 LDX lsb of pointer LDY msb JSR FLD0R or FLD0P = $DD8D FLPTR = address of FP number JSR FLD0P LOAD FR1 WITH FLOATING POINT NUMBER Loads FR1 with user FP number in buffer pointed to by 6502 X and Y registers or by FLPTR. After either operation below, FLPTR will point to the user FP buffer. FLD1R = $DD98 LDX lsb of pointer LDY msb JSR FLD1R or FLD1P = $DD9C FLPTR = address of FP number JSR FLD1P STORE FR0 IN USER BUFFER stores the contents of FR0 in user FP buffer pointed to by 6502 X and Y registers or by FLPTR. After either operation below, FLPTR will point to the user FP buffer. FST0R = $DDA7 LDX lsb of pointer LDY msb JSR FST0R or FST0P = $DDAB FLPTR = address of FP number JSR FST0P MOVE FR0 TO FR1 Moves the contents of FR0 to FR1 FMOVE = $DDB6 JSR FMOVE The usual use sequence of the floating point package might be to: load FR0 and FR1 with FP numbes from user specified buffers do the math then store FR0 in a user buffer. An alternative might be to: convert an ASCII representation to FP (the result is automatically in FR0). move FR0 to FR1. Convert the second ASCII number. Do the math. Convert FR0 back to ASCII. Store the number back into a user buffer. The floating point package uses the following blocks of RAM. RAM used by floating point package $00D4 - $00FF $057E - $05FF If the floating point package is not used the above ram is free. Useful data base variables and OS equates FR0 $00D4,6 (212): system FP buffer FR1 $00E0,6 (224): system FP buffer CIX $00F2 (242): INBUFF index INBUFF $00F3,2 (243): pointer to ASCII FP buffer FLPTR $00FC,2 (252): pointer to user FP buffer LBUFF $0580 (1408): result buffer for FP to ASCII AFP $D800 (55296): ASCII to FP FASC $D8E6 (55526): FP to ASCII IFP $D9AA (55722): integer to FP FPI $D9D2 (55762): FP to integer ZFR0 $DA44 (55876): clear FR0 ZF1 $DA46 (55878): clear zero page FP buffer FSUB $DA60 (55904): FR0 - FR1 FADD $DA66 (55910): FR0 + FR1 FMUL $DADB (56027): FR0 * FR1 FDIV $DB28 (56104): FR0 / FR1 FLD0R $DD89 (56713): load FR0 by X,Y pointer FLD0P $DD8D (56717): load FR0 by FLPTR pointer FLD1R $DD98 (56728): load FR1 by X,Y pointer FLD1P $DD9C (56732): load FR1 by FLPTR pointer FST0R $DDA7 (56743): store FR0 at buffer by X,Y pointer FST1P $DDAB (56747): store FR0 at buffer by FLPTR pointer FMOVE $DDB6 (56758): move FR0 to FR1 EXP $DDC0 (56768): e exponentiation EXP10 $DDCC (56780): base 10 exponentiation PLYEVL $DD40 (56640): polynomial evaluation LOG $DECD (57037): natural log of FR0 LOG10 $DED1 (57041): base 10 log of FR0 CHAPTER 12 Boot software formats There are three ways which programs may be booted (loaded automatically upon power-up): From the disk drive From the cassette recorder From a ROM cartridge DISK BOOTED SOFTWARE The disk drive is the primary source for programs (other than the BASIC interpreter in the computer ROM). A program booted from disk must be a machine language program. Secondly, the program is arranged on disk in a different manner from the DOS files. When the computer is first turned on, it will attempt to read a program starting at sector one in disk drive one. The exceptions are, if a cartridge prevents the disk boot process or the [START] key is pressed. The program is expected to use all 128 bytes of each sector. FORMAT OF A DISK BOOTED PROGRAM A disk booted program begins at sector one on the disk and continues in sequence. The first six bytes of the first sector contain program information. The rest of the bytes contain the program itself. Disk boot program header 1st byte $00 flags, stored in DFLAGS [$0240] $xx number of sectors used by program $xx address to start load $xx $xx initialization address 6th byte $xx 7th byte $xx start of program The flags byte is usually unused and should be zero. The load address is stored in BOOTAD [$0242,2 (578)]. The initialization address is stored in DOSINI [$000C,2 (12)]. After the program is completely loaded the computer will JSR to the address stored in DOSINI for initialization. It will then jump to the address stored in DOSVEC to run the program. The initialization part of the program should set the bottom-of-free-RAM pointer, MEMLO [$02E7,2 (743)], to point to the end of the program + 1. This will protect the program from the computer and other programs. The top-of-user-RAM pointer, APPMHI [$000E,2 (14)], is also usually set to point to the same address. This will protect the program from the video hardware. It must also set DOSVEC [$000A,2 (10)] to actually point to the run address of the program. The initialization should of course end with and RTS. With DOSINI and DOSVEC properly set, the program will restart up pressing the [SYSTEM RESET] key. Rmember that the load address of the program should be six bytes before where you want the program to reside in memory. The six byte header will load at the specified start address followed by the program. CASSETTE BOOTED SOFTWARE The cassette boot process is nearly identical to the disk boot process. The processes are so similar that cassette boot programs can usually be transferred directly to disk and vice-versa. The two differences are: The cassette is booted instead of the disk if the [START] key is pressed when the power is turned on. A bug in early operating systems requires the booted program to turn off the cassette motor with the following command. LDA #$3C STA PACTL [$D302] CARTRIDGE BOOTED SOFTWARE The Atari 800 has two cartridge slots. All other models have only one. The second cartridge slot, slot B on the 800, resides from $8000 to $9FFF. The first slot, slot A, resides from $A000 to BFFF. If a cartridge is inserted in a slot it will disable any RAM in the same area. Slot A, which is present in all models, can reside at the entire 16K used by both cartridges in the 800 ($8000 to $BFFF). Cartridges use the last six bytes for boot information. In cartridge A these bytes are from $BFFA to $BFFF. In cartridge B they are from $9FFA to 9FFF. last six bytes of a cartridge $9FFA or $BFFA xx start address xx 00 xx flag byte xx init address $9FFF or $BFFF xx Flag byte bit 0 1 = allow disk boot bit 2 0 = do not start cartridge after init bit 7 1 = cartridge takes control before OS is initialized The initialization process for the cartridge should be similar to that for disk and cassette. A minimum of an RTS instruction is required. The third byte of the cartridge tailer is used by the OS to check for the presence of a cartridge. This byte must be zero. A 16K cartridge will use both cartridge areas and the cartridge B tailer area can be used for program code. THE CARTRIDGE HARDWARE Most cartridges consist of two ROM chips on a single circuit board. Moreover, both chip sockets have identical pin assignments. In other words, the chips can be switched to opposite sockets and the cartridge will still work. The difference is in the chips themselves. On one chip, the A12 pin acts as an active-low chip select. On the other the A12 pin acts as an active-high chip select. Therefore the state of the A12 pin selects between the two chips. Cartridge slot pin assignments BACK 111111 543210987654321 --------------- --------------- SRPNMLKJHFEDCBA FRONT 1 1 = 16K A A13 (16K only) 2 A3 B GND 3 A2 C A4 4 A1 D A5 5 A0 E A6 6 D4 F A7 7 D5 H A8 8 D8 J A9 __ 9 D1 K A12 (CS)/(CS) 10 D0 L D3 11 D6 __ M D7 12 (CS) N A11 13 +Vcc P A10 14 +Vcc R NC 15 NC S NC The BASIC interpreter resides in the memory used by cartridge A. In 400, 800 and 1200XL models, a BASIC cartridge is required to run BASIC programs. On other XL and XE models, inserting a cartridge into the slot or pressing the [OPTION] key upon power-up will disable the internal BASIC ROM. If BASIC is disabled without inserting another cartridge, the area from $A000 to $BFFF will contain RAM. Useful data base variables and OS equates APPMHI $000E,2 (14): low limit of screen region DOSVEC $000A,2 (10): run and program reset vector DOSINI $000C,2 (12): init and reset init CARTB $8000 (32768): start of cartridge B CARTA $A000 (40960): start of cartridge A PACTL $D302 (54018): port A control register Bit 3 controls the cassette motor CHAPTER 13 THE SERIAL INPUT/OUTPUT INTERFACE (SIO) Most input and output with the Atari computer passes through the serial I/O bus. The SIO interface is rather complicated but you are unlikely to need to use it directly. CIO usually handles SIO for you. However, if you want to design your own I/O device and it's associated handler, you need to know how to use the SIO. SIO transfers data at a rate of 19,200 baud on separate input and output lines. The data is sent one byte at a time, LSB first, in an asynchronous format. There are also clock-in and clock-out lines. There is a signal on the clock-out line but it is not used by any present devices. The clock-in line is available for synchronous transfer but is not used by the OS. The signal on the clock-out line goes high at the leading edge of each bit and goes low in the middle of each bit. One byte of SIO data +-+ +-+ +-+ +-+ +-+ +-+ +-+ +-+ | | | | | | | | | | | | | | | | clock -------------+ +-+ +-+ +-+ +-+ +-+ +-+ +-+ +------ ---------+ +---+ +-------+ +-------- | 0 | 1 | 0 | 1 1 | 0 0 | 1 data +-------+ +---+ +-------+ | | start bit stop bit The SIO interface is used much like the resident disk handler. In fact, it uses the same device control block as the resident disk handler. After the control block parameters are set, a JSR is made to the SIO entry vector, SIOV, at $E459 (58457). Device control block (for SIO) DDEVIC [$0300 (768)] Serial bus I.D. Set by handler or program. DUNIT [$0301 (769)] Device number if more than one. DCOMND [$0302 (770)] Device command byte. DSTATS [$0303 (771)] Before the SIO call, this byte tells whether the operation is read, write or that there is no data transfer associated with the command. After the call this byte will hold the status (error/no error code) of the operation. DSTATS format before command 7 6 5 4 3 2 1 0 ----------------- |W|R| not used | ----------------- If both W and R are 0, there is no data transfer. DBUFLO [$0304 (772)] DBUFHI [$0305 (773)] Points to the data buffer for either input or output. DTIMLO [$0306 (774)] Timeout value (response time limit) in 64/60ths of a second to be set by handler or program. DBYTLO [$0308 (776)] DBYTHI [$0309 (777)] Number of bytes to be transferred, set by handler or program. This parameter is not required if the DSTATS specifies no data transfer. DAUX1 [$030A (778)] DAUX2 [$030B (779)] These parameters are sent to the device as part of the command frame. USING THE SIO INTERFACE All commands on the serial bus must originate from the computer. The peripherals will present data on the bus only when commanded to do so. Any operation on the serial bus begins with a five byte command frame. While the command frame is being sent, the command line of the serial connector is 0. Command frame format $xx DDEVIC $xx DCOMND $xx DAUX1 $xx DAUX2 $xx checksum The first four bytes of the command frame come from the device control block. the checksum is the sum of the other four bytes with the carry added back after each addition. If both R and W of the DSTATS are 0, no data is sent to, or expected from the peripheral, after a command frame is sent. However, the device is usually expected to send an ACK byte ($41) after the command frame is sent. If the command frame is invalid, an NAK byte ($4E) should be sent. If the operation is output (W = 1) the computer will send a data frame after it receives the ACK of the command frame. It then expects an ACK after the data frame is sent. If the operation is an input (R = 1) the computer expects a data frame from the peripheral after the ACK. With either input or output, a "complete" code ($43) should be sent to the computer when the operation is finished. The "complete" code would follow the ACK of the data frame with an output operation. If the operation is not completed for some reason, the peripheral should send an error code ($45) instead of "complete". SIO data frame byte 1 $xx\ > data bytes byte n $xx/ byte n+1 $xx checksum SIO commands READ $52 WRITE $57 STATUS $53 PUT $50 FORMAT $21 DOWNLOAD $20 READADDR $54 READ SPIN $51 MOTOR ON $55 VERIFY SECTOR $56 Present SIO device I.D.s DISK $31 - $34 (D1 - D4) PRINTER $40 RS-232-C $50 - $53 (R1 - R4) THE SERIAL CONNECTOR The serial connectors on the computer and all peripherials are identical. Nearly all peripherials have two serial connectors. Either connector may be used for any connection. The serial bus is designed so that peripherials can be daisy-chained together. The following is a diagram of the serial connector. The serial connector pin-out 1 1 2 4 6 8 0 2 ----------- /o o o o o o\ /o o o o o o o\ ----------------- 1 3 5 7 9 1 1 1 3 1 clock in (to computer) 2 clock out 3 data in 4 GND 5 data out 6 GND 7 command (active low) 8 cassette motor control 9 proceed (active low) 10 +5V/ready 11 audio in 12 +12V (400/800) 13 interrupt (active low) Proceed goes to pin 40 (CA1) of the PIA. It is not used by present peripherials. Interrupt goes to pin 18 (CB1) of the PIA. It is not used by present peripherials. Pin 10 doubles as a 50mA +5V peripharal power supply and a computer ready signal. Useful database variables and OS equates SIOV $E459 (58457): serial port handler entry DDEVIC $0300 (768): device ID DUNIT $0301 (769): device number DCOMND $0302 (770): command byte DSTATS $0303 (771): status byte DBUFLO $0304 (772): data buffer pointer DBUFHI $0305 (773): DTIMLO $0306 (774): timout value DBYTLO $0308 (776): number of bytes to transfer DBYTHI $0309 (777): DAUX1 $030A (778): sent to device DAUX2 $030B (779): sent to device CHAPTER 14 THE HARDWARE CHIPS The previous chapters described the operating system of the computer. The following chapters will examine the hardware which supports the 6502 and the hardware's associated software. THE GTIA CHIP The GTIA (George's Television Interface Adapter) is the main video circuit in the computer. It controls the following functions. GTIA functions Priority of overlapping objects Color and brightness, including information from the antic chip. Player/missile control. console switches and game control triggers. THE ANTIC CHIP The main job of the ANTIC chip is interpreting the display buffer for the GTIA chip. The ANTIC chip is somewhat of a processor in it's own right. The program which runs it is called the display list and usually resides just before the display buffer in memory. The ANTIC chip operates independent of the 6502. It operates by direct memory access (DMA). The ANTIC chip gives a HALT signal the 6502, causing the 6502 to give up control of the address bus. The ANTIC chip can then read any data it needs to from memory. ANTIC chip functions DMA (Direct Memory Access) control. NMI (Non-Maskable Interrupt) control. LIGHT PEN READING WSYNC (wait for horizontal sync) THE POKEY CHIP The most important jobs of the POKEY chip are reading the keyboard and operating the serial port. It also has the following functions. POKEY chip functions Keyboard reading. Serial port. Pot (game paddles) reading. Sound generation. System timers. IRQ (maskable interrupt) control. Random number generator. THE PIA CHIP The PIA (Parallel Interface Adapter) is a commonly used I/O chip. It consists of two 8 bit parallel ports with hand shaking lines. In the Atari, it has the following functions. Game controller port control (bi-directional). Peripheral control and interrupt lines. Registers in the hardware chips are treated as memory addresses. Many of the registers are write only. These registers cannot be read from after they are written to. Other registers control one function when written to and give the status of an entirely different function when read from. Still other registers are strobes. Any command which causes the address of one of these registers to appear on the address bus will cause their functions to be performed. The write only registers have shadow registers in RAM. Data to be put in the registers is usually put into the shadow registers. The data in the shadow registers is automatically moved to the operating registers during vertical blank. For register use and address, see the previous chaptes on the associated functions. CHAPTER 15 DISPLAY LISTS [some of this file was lost...] chip also has a memory scan counter. This register scans the display buffer for data to be interpreted and displayed. Once loaded, the memory scan counter's 4 most significant bits are fixed. The result is that the memory scan counter cannot cross a 4K memory boundary (i.e. $AFFF to $B000) without being reloaded. DISPLAY LIST INSTRUCTIONS There are three basic instructions in the display list. The type of instruction is determined by bits 0,1,2 and 3 of an instruction byte. The other four bits give auxilliary parameters for the instruction. Bit 7 always enables a display list interrupts (DLIs). Display list instruction format 7 6 5 4 3 2 1 0 ----------------- |I|n|n|n|0|0|0|0| ----------------- \ / \ / --- ------ | | | 0 = display blank lines | 0-7 = number of blank lines (1-8) 7 6 5 4 3 2 1 0 ----------------- |I|W| | |0|0|0|1| ----------------- | \ / | ------ | | | 1 = jump (3 byte instruction) | 0 = jump and display one blank line 1 = jump and wait for vertical blank 7 6 5 4 3 2 1 0 ----------------- |I|R|H|V|M|M|M|M| ----------------- | | | | \ / | | | | ------ | | | | | | | | | 2-F = display one line of graphics in | | | | ANTIC mode 2-F | | | 1 = horizontal scroll enabled | | | | | 1 = vertical scroll enabled | | | 1 = reload memory scan counter with next two bytes | 1 = display list interrupt, all instructions In the display instruction, the ANTIC mode is different from the CIO graphics mode. However, each CIO graphics mode uses a particular ANTIC mode. Below are descriptions of the ANTIC modes with their associated graphics (CIO) modes. ANTIC MODE 2 (Graphics 0) Uses 8 pixel by 8 pixel characters, 40 characters horizontal, 8 TV scan lines vertical. Only one color can be displayed at a time. ANTIC MODE 3 8 X 10 pixel, Graphics 0 type characters. This mode requires a custom character set. The advantage is that it allows true decenders. The custom C-set is still 8 X 8 pixels. Lower-case letters with decenders have the bottom row of pixels put on the top row. Lower-case "y" for ANTIC mode 3 C-set Display ---------- ---------- | XXXXX | | | | | | | | | | | | XX XX | | XX XX | | XX XX | | XX XX | | XX XX | | XX XX | | XXXXX | | XXXXX | | XX | | XX | ---------- | XXXXX | | | ---------- ANTIC MODE 4 (graphics 12 on XL and XE) This mode has characters the same size as graphics 0. However, the characters are only 4 X 8 pixels. This gives only half the horizontal resolution of graphics 0. The advantage is that up to fou