25 Operating System Routines and Addresses

25.1 Input/Output Routines

The ATOM operating system contains several routines which can be called by user programs to provide input and output facilities. The routines are defined so that they are compatible with the other Acorn operating systems; in particular, if the ATOM is expanded to include a Disk Operating System the same routines will automatically function with the disk.

OSCLI Command line interpreter

This subroutine interprets a string of characters at address #0100 and terminated by carriage return as an operating system command. Detected errors are met with a BRK. All processor registers are used, and the decimal-mode flag is set to binary on exit.

OSWRCH Write character

This subroutine sends the byte in the accumulator to the output channel. Control characters are normally recognised as detailed in Section 18.1.3. All registers are preserved.

OSCRLF Carriage return -- line feed

This subroutine generates a line feed followed by a carriage return using OSWRCH. On exit A will contain #0D, N and Z will be 0, and all other registers are preserved.

OSECHO Read character with echo

This subroutine reads a byte using OSRDCH and then writes it out using OSWRCH. The routine converts carriage returns to a line feed followed by a carriage return. On exit A will contain the byte read, N, Z, and C are undefined, and all other registers are preserved.

OSRDCH Read character

This subroutine reads a byte from the input channel and returns it in A. The state of N, Z, and C is undefined; all other reqisters are preserved.

OSLOAD Load file

This subroutine loads a complete file into a specified area of memory.
On entry X must point to the following data in zero page:

X+0 address of string of characters, terminated by #0D, which is the file name.
X+2 Address in memory of the first byte of the destination.
X+4 Flag byte: if bit 7 = 0 use the file's start address.

All processor registers are used. A break will occur if the file cannot be found. In interrupt or DMA driven systems a wait until completion should be performed if the carry flag was set on entry.

OSSAVE, Save file

This subroutine saves all of an area of memory to a specified file. On entry X must point to the following data in zero page:

X+0 Address of string of characters, terminated by #0D, which is the file name.
X+2 Address for data to be reloaded to.
X+4 Execution address if data is to be executed
X+6 Start address of data in memory
X+8 End address + 1 of data in memory

The data is copied by the operating system without being altered. All registers are used. In interrupt or DMA driven operating systems a wait until completion should be performed if the carry flag was set on entry. A break will occur if no storage space large enough can be found.

OSBPUT Put byte

This subroutine outputs the byte in the accumulator to a sequential write file. Registers X and Y are saved. In the ATOM operatinq system interrupts are disabled during OSBPUT but interrupt status is restored on exit. In the Disk Operating System the file's sequential file pointer will be incremented after the byte has been saved.

OSBGET Get byte

The subroutine returns, in A, the next byte from a sequential read file. Registers X and Y are retained. In the ATOM operating system interrupts are disabled during OSBGET but interrupt status is restored on exit. In the Disk Operating System the file's sequential file pointer will be incremented after the byte has been read.

OSFIND Find file

This subroutine returns, in A, a 'handle' for a file. The X register points to zero page locations containing the address of the first character of the file name; the file name is terminated by a #0D byte. The 'handle' is zero if the file does not exist; otherwise it is a byte uniquely specifying the file. If the file is to be used for sequential input the carry should be set, or if for sequential output the carry should be clear. In the ATOM operating system the file handle is set to 13, and the message "PLAY TAPE" or "RECORD TAPE" is produced. In the Disk Operating Systam the file's sequential pointer is set to zero.

OSSHUT Shut file

This subroutine removes a reference to a file whose handle is in the Y register. If a handle of zero is supplied, all files are shut. In the ATOM operating system the call does nothing.

The following subroutines are not used in the cassette system, and cause an error if called:

OSRDAR Read file's arguments
OSSTAR Store file's arguments

25.2 Operating System Calls

The following table gives the addresses of all the operating system calls:

      Address:  Subroutine:  Instruction:
       #FFCB      OSSHUT     JMP (SHTVEC)
       #FFCE      OSFIND     JMP (FNDVEC)
       #FFD1      OSBPUT     JMP (BPTVEC)
       #FFD4      OSBGET     JMP (BGTVEC)
       #FFD7      OSSTAR     JMP (STRVEC)
       #FFDA      OSRDAR     JMP (RDRVEC)
       #FFDD      OSSAVE     JMP (SAVVEC)
       #FFED      OSLOAD     JMP (LODVEC)
       #FFE3      OSRDCH     JMP (RDCVEC)
       #FFE6      OSECHO     JSR  OSRDCH
       #FFE9      OSASCI     CMP  @#0D
       #FFEB                 BNE  OSWRCH
       #FFED      OSCRLF     LDA  @#0A
       #FFEF                 JSR  OSWRCH
       #FFF2                 LDA  @#0D
       #FFF4      OSWRCH     JMP (WRCVEC)
       #FFF7      OSCLI      JMP (COMVEC)

The operating system calls are all indirected via addresses held in RAM, and these addresses may be changed to the addresses of user-supplied routines. The addresses are initialised on reset as follows:

      Address:  Subroutine:  Function:
       #0200      NMIVEC     NMI service routine
       #0202      BRKVEC     BRK service routine
       #0204      IRQVEC     IRQ service routine
       #0206      COMVEC     Command line interpreter
       #0208      WRCVEC     Write character
       #020A      RDCVEC     Read character
       #020C      LODVEC     Load file
       #020E      SAVVEC     Save file
       #0210      RDRVEC     Error
       #0212      STRVEC     Error
       #0214      BGTVEC     Get byte from tape
       #0216      BPTVEC     Put byte to tape
       #0218      FNDVEC     Print message
       #021A      SHTVEC     Dummy

A call to one of the routines OSRDAR or OSSTAR will cause the message:

COM?

to be output, followed by a BRK.

25.3 Interrupts

The following action is taken on interrupts:

NMI     PHA
        JMP (NMIVEC)

IRQ/BRQ STA #FF
        PLA
        PHA
        AND @#10  which interrupt was it
        BNE BRK
        LDA #FF
        PHA
        JMP (IRQVEC)

BRK     LDA #FF
        PLP
        PHP
        JMP (BRKVEC)

Note that the accumulator is pushed before the jump occurs.

25.4 Block Zero RAM Locations

Hexadecimal:  Decimal:       Function:
#0            0            Error number
#1, #2        1, 2         BASIC line number.
#8 - #C       8 - 12       Random number seed
#10, #11      16, 17       Pointer to BASIC error handler
#12           18           Text-space pointer
#00 - #6F     0 - 111      BASIC zero-page workspace
#70 - #7F     112 - 143    Floating-point workspace
#80 - #AF     144 - 175    Free
#B0 - #FF     176 - 255    Cassette system workspace
#FE           254          Character not sent to printer
#100 - #13F   256 - 319    Input line buffer
#140 - #17F   320 - 383    String processing & INPUT statement buffer
#180 - #1FF   384 - 511    Stack
#200 - #21B   512 - 539    Operating system vectors
#21C - #23F   540 - 575    Free
#240 - #3FF   576 - 1023   BASIC workspace
#3FE, #3FF    1022, 1023   Address of point-plotting routine

25.5 Input/Output Port Allocations

The 8255 Programmable Peripheral Interface Adapter contains three 8-bit ports, and all but one of these lines is used by the ATOM.

The port C output lines, bits 0 to 3, may be used for user applications when the cassette interface is not being used.

25.6 Memory Map

The following diagram shows how the ATOM's address space is allocated. Sections shown shaded are present in the minimal-system ATOM. The map includes the addresses of devices on the Acorn cards, which may be fitted inside the ATOM case.

Next chapter