CAOS Programming Reference

• Restrictions
• Invoking System Calls
• System Call Entry Points
• Special CAOS Entry Points
• System Memory Locations at B780
• System Memory Locations below 0200
• Interrupt Table
• System Calls
  • 00 CRT – print character
  • 01 MBO – tape output
  • 02 UOT1 – output user channel 1
  • 03 UOT2 – output user channel 2
  • 04 KBD – keyboard input with cursor
  • 05 MBI – tape input
  • 06 USIN1 – input user channel 1
  • 07 USIN2 – input user channel 2
  • 08 ISRO – initialize tape output
  • 09 CSRO – finalize tape output
  • 0A ISRI – initialize tape input
  • 0B CSRI – finalize tape input
  • 0C KBDS – get pressed key without ack
  • 0D BYE – warmstart
  • 0E KBDZ – get pressed key with ack
  • 0F COLOR – set color
  • 10 LOAD – load file
  • 11 VERIF – verify a file on tape
  • 12 LOOP – return control to CAOS
  • 13 NORM – reset I/O channels
  • 14 WAIT – waiting loop
  • 15 LARG – load arguments
  • 16 INTB – character from input channel
  • 17 INLIN – line input
  • 18 RHEX – parse hex number string
  • 19 ERRM – print ERROR
  • 1A HLHX – print HL
  • 1B HLDE – print HL DE
  • 1C AHEX – print A
  • 1D ZSUCH – find command
  • 1E SOUT – set output table
  • 1F SIN – set input table
  • 20 NOUT – reset output channel to screen
  • 21 NIN – reset input channel to keyboard
  • 22 GARG – parse arguments
  • 23 OSTR – output string
  • 24 OCHR – output character on output channel
  • 25 CUCP – complement cursor
  • 26 MODU – expansion module control
  • 27 JUMP – jump to alternate OS
  • 28 LDMA – LD (HL),A
  • 29 LDAM – LD A,(HL)
  • 2A BRKT – test for BRK key
  • 2B SPACE – output a space character
  • 2C CRLF – output newline
  • 2D HOME – output HOME
  • 2E MODI – call MODIFY
  • 2F PUDE – clear pixel
  • 30 PUSE – set a pixel
  • 31 SIXD – move and reset CAOS working memory
  • 32 DABR – compute character buffer address
  • 33 TCIF – test if cursor pos inside window
  • 34 PADR – compute pixel- and color-address
  • 35 TON – sound output
  • 36 SAVE – save program
  • 37 MBIN – byte-input from tape
  • 38 MBOUT – byte-output to tape
  • 39 KEY – assign function key
  • 3A KEYLI – print function key assignment
  • 3B DISP – hex/ascii dump
  • 3C WININ – initialize a window
  • 3D WINAK – select window
  • 3E LINE – draw a line
  • 3F CIRCLE – draw a circle
  • 40 SQR – square root
  • 41 MULT – multiplication
  • 42 CSTBT – toggle ASCII control code mode
  • 43 INIEA – initialize I/O channel
  • 44 INIME – initialize multiple I/O channels
  • 45 ZKOUT – output string at HL
  • 46 MENU – call MENU system command
  • 47 V24OUT – initialize printer output
  • 48 V24DUP – initialize V24 duplex

Restrictions

• do not modify the IX register, this is needed as base pointer to system memory variables by keyboard and cassette loading interrupts
• the only supported interrupt mode is IM2

Invoking System Calls

CAOS system calls are identified by a number [SYSNR] and invoked through different entry points which differ in the way how the system call identifier and arguments are provided.

System Call Entry Points

These are the entry point addresses for the jump vectors, and how they work:

F003: Entry Point 1

The SYSNR is encoded as byte in the instruction stream following the CALL instruction. Parameters are directly excpected in registers BC, DE and HL, which may be changed by the system call. The required stack depth is 2.

F006: Entry Point 2

The SYSNR must be provided in the system address ARGC (B780). Parameters are expected in BC, DE and HL. BC, DE and HL will be saved on the stack, which means the system call cannot use those registers for return values. Required stack depth is 7.

F009: Entry Point 3

Same as Entry Point 2, but the SYSNR is provided in register E.

F00C: Entry Point 4

Same as Entry Point 3, but the video memory bank (IRM) is switched on invocation, and switched off on return.

F015: Entry Point 5 (since CAOS 3.1)

Same as Entry Point 3, but switches on the IRM and sets the stack pointer to (SYSP) == B7AE before the syscall, and after the syscall, switches off the IRM and restores the stack pointer. The register BC will be modified.

F01E: Entry Point 6 (since CAOS 3.1)

Same as Entry Point 5, but SYSNR is provided in address (ARGC) (B780).

Special CAOS Entry Points

E000: Reset Entry

This address is called after a Reset. The system memory locations will be initialized, user memory remains unchanged.

F000: Power-On Entry

This address is called on Power-On. All RAM will be cleared, all hardware modules will be switched-off (except a 16-KByte RAM modul in the slot 08, this will automatically be mapped to address 4000 on the KC85/2 and KC85/3).

F00F: Relative Subroutine Call

This doesn’t invoke a system call, but implements a relative subroutine call, since there is no Z80 instruction for this. This is useful for position-independent-code. The relative location is expected as 16-bit word encoded in the instruction stream following the CALL:

        RCALL SUB
        CALL 0F00FH
        DEFW UP-NEXT
NEXT:   ...

The DE register cannot be used as subroutine argument, the required stack depth is 1.

F018: Switch-on IRM and set SP (since CAOS 3.1)

This call switches on the IRM and sets the stack pointer to (SYSP) (see Entry Point 5). Muste be used together with F01B.

F01B: Switch-off IRM and restore SP (since CAOS 3.1)

This is the counter-function to F018, it switches off the IRM and restores the stack pointer.

System Memory Locations at B780

System Memory Locations below 0200

The IX register is set to 01F0 at Reset/Power-On.

Interrupt Table

The I register is set to 01 at Reset/Power-On.

System Calls

00 CRT – print character

Desc:       Print a character on screen
In:         A - character code (ASCII)
Out,Change: -
Stack:      11

01 MBO – tape output

Desc:      Output a data block to cassette tape
In:        BC     - length of leading sound
           (IX+1) - block number - 1
           (IX+5) - L (buffer address)
           (IX+6) - H (buffer address)
Out:       DE     - buffer end + 1
           (IX+2) - block number
Change:    AF, BC, DE, HL
Stack:     4

02 UOT1 – output user channel 1

Desc:       call user function for output to user channel 1
In:         A   - character code 
Out:        depends on function
Change:     depends on function
Note:       the address of the user-provided function must be set
            in UOUT1 (B7BE)

03 UOT2 – output user channel 2

Desc:       see UOT1
Note:       the address of the user-provided function must be set
            in UOUT2 (B7C4)

04 KBD – keyboard input with cursor

Desc:       show cursor and wait for keyboard input or return
            code sequence from previously pressed function key
In:         -
Out:        A   - character code
Change:     AF, HL
Stack:      9

05 MBI – tape input

Desc:       read a data block from cassette tape
In:         (IX+5)  - L (buffer address)
            (IX+6)  - H (buffer address)
Out:        CY = 1  - read error
            (IX+2)  - block number
Change:     AF, BC
Stack:      4

06 USIN1 – input user channel 1

Desc:       call user function for input from user channel 1
In:         depends on function
Out:        depends on function
Change:     depends on function
Note:       the address of the user-provided function must be set
            in UIN1 (B7C1)

07 USIN2 – input user channel 2

Desc:       see USIN1
Note:       the address of the user-provided function must be set
            in UIN2 (B7C7)

08 ISRO – initialize tape output

Desc:           initialize cassette tape output, writes the 1st data block
In,Out,Change:  see 01 MBO
Stack:          4

09 CSRO – finalize tape output

Desc:           finalize cassette tape output, writes the last data block
In,Out,Change:  see 01 MBO
Stack:          10

0A ISRI – initialize tape input

Desc:           initialize cassette tape input, reads the 1st data block
In,Out,Change:  see 05 MBI
Stack:          5

0B CSRI – finalize tape input

Desc:       finalize cassette tape input.
In,Out:     -
Change:     AF,HL
Stack:      1

0C KBDS – get pressed key without ack

Desc:       gets pressed key without acknowledge
In:         -
Out:        CY = 1  - key pressed
            A       - key code (ASCII, function keys are F1..FC
Change:     AF
Stack:      0

0D BYE – warmstart

Desc:           jumps to RESET address E000
In,Out,Change:  -

0E KBDZ – get pressed key with ack

Desc:       get pressed key with acknowledge and autorepeat
In:         -
Out:        CY = 1  - key pressed
            A       - key code (ASCII, function keys are F1..FC)
Change:     AF
Stack:      1

0F COLOR – set color

Desc:       sets the current color
In:         E - background color (0..7)
            L - foreground color (0..1FH)
            (ARGN) = 1  - only change foreground color
                   = 2  - change fore- and background color
Out:        -
Change:     AF,L
Stack:      1

10 LOAD – load file

Desc:       loads a file from cassette tape
In:         (ARGN)  = 0 - load without offset
                    = 1 - load with offset
            (ARG1)  = loading offset
Out:        -
Change:     AF,BC,DE,HL
Stack:      14

11 VERIF – verify a file on tape

Desc:       verifies a file on cassette tape by checking
            the data block checksums
In,Out:     -
Change:     AF,BC,DE,HL
Stack:      14

12 LOOP – return control to CAOS

Desc:           returns control to CAOS without memory initialization,
                can be used by menu programs if a RET instruction is
                not possible
In,Out,Change:  -

13 NORM – reset I/O channels

Desc:       sets the input and output channel handler functions to 
            CRT and KBD
In:         -
Out:        HL - old output pointer
Change:     HL
Stack:      2

14 WAIT – waiting loop

Desc:       implements a simple waiting loop without interrupts
In:         A - t=(A) * 6ms
Out:        -
Change:     AF,B
Stack:      2

15 LARG – load arguments

Desc:       load arguments into registers
In:         -
Out:        HL - (ARG1)
            DE - (ARG2)
            BC - (ARG3)
            A  - (ARGN)
Change:     A,BC,DE,HL
Stack:      0

16 INTB – character from input channel

Desc:       returns character from current input channel
            (defined by INTAB)
In:         -
Out:        A - character (ASCII)
Change:     -
Stack:      12 (if input channel is set to keyboard)

17 INLIN – line input

Desc:       input a complete line until [ENTER]
In:         -
Out:        DE - address to start of line in video ram ascii buffer
Change:     AF,DE
Stack:      12

18 RHEX – parse hex number string

Desc:       converts a hex number string into a number
In:         DE - points to number string
Out:        DE - points to end of number string
            (NUMNX) - length of string
            (NUMVX) - converted number
            CY = 1  - error, invalid characters or number string too long
Change:     AF,DE,HL
Stack:      0

19 ERRM – print ERROR

Desc:           outputs the text "ERROR"
In,Out,Change:  -
Stack:          13

1A HLHX – print HL

Desc:       outputs the register HL as hex number
In:         HL
Out:        -
Change:     AF
Stack:      17

1B HLDE – print HL DE

Desc:       outputs the registers HL and DE as hex numbers
In:         HL,DE
Out:        -
Change:     AF
Stack:      19

1C AHEX – print A

Desc:       outputs the register A as hex number
In:         A
Out:        -
Change:     AF
Stack:      16

1D ZSUCH – find command

Desc:       find a menu command by name
In:         A   - prolog byte (e.g. for CAOS menu: 7F)
            BC  - length of search area
            DE  - start of search string
            HL  - start of search area
Out:        DE      - end+1 of search string
            HL      - end+1 of found string
            CY=1    - if search successful
Change:     AF,BC,DE,HL
Stack:      2

1E SOUT – set output table

Desc:       updates the OUTAB pointer to HL
In:         HL - new OUTAB pointer
Out:        HL - old OUTAB pointer
Change:     HL
Stack:      1

1F SIN – set input table

Desc:       updates the INTAB pointer to HL
In:         HL - new INTAB pointer
Out:        HL - old INTAB pointer
Change:     HL
Stack:      1

20 NOUT – reset output channel to screen

Desc:       resets the character output handler to screen (00 CRT)
In:         -
Out:        HL - pointer to old handler
Change:     HL
Stack:      1

21 NIN – reset input channel to keyboard

Desc:       resets the character input handler to keyboard (04 KBD)
In:         -
Out:        HL - pointer to old handler
Change:     HL
Stack:      1

22 GARG – parse arguments

Desc:       parse up to 10 hex numbers string
In:         DE - address of first character
Out:        DE - address of last character + 1
            (ARGN)          - number of parsed numbers
            (ARG1)..(ARG10) - parsed number values
            CY = 1          - parsing error occured
Change:     AF,BC,DE,HL
Stack:      1
Note:       valid characters are 0..9, A..F, space, end: 0

23 OSTR – output string

Desc:       print embedded string following the subroutine call
In/Out:     -
Change:     AF
Stack:      16

24 OCHR – output character on output channel

Desc:       write a character to device defined by OUTAB
In:         A - character code (ASCII)
Out:        -
Change:     AF
Stack:      15

25 CUCP – complement cursor

Desc:       sets the cursor image to shift-lock mode(???)
In:         (CURSO) - cursor position
Out,Change  -
Stack:      8

26 MODU – expansion module control

Desc:       read module type or send modul control byte
In:         A = 1   - read module type
              = 2   - write control byte
            L       - module slot
            D       - control byte
Out:        H       - module type
            D       - current module control byte
Change:     AF,H,C,B
Stack:      0

27 JUMP – jump to alternate OS

Desc:       jump into a new operating system, switch off built-in ROM banks
In:         A - module slot
Out,Change: -
Note:       the start address of the new operating system must be F012,
            FF will be written as module control byte

28 LDMA – LD (HL),A

Desc:       LD (HL),A
In:         A - value
            HL - address
Out,Change: -
Note:       only useful with entry points 4 to 6

29 LDAM – LD A,(HL)

Desc:       LD A,(HL)
In:         HL - address
Out:        A - value
Change:     -
Stack:      0
Note:       Only useful with entry points 4 to 6

2A BRKT – test for BRK key

Desc:       test whether the BRK key was pressed
In:         -
Out:        CY = 1 - key BRK was pressed
            A - key code
Change:     -
Stack:      1

2B SPACE – output a space character

Desc:       outputs a space character via 24 OCHR
In,Out:     -
Change:     AF
Stack:      15

2C CRLF – output newline

Desc:       outputs a newline (0A + 0D)
In,Out:     -
Change:     AF
Stack:      17

2D HOME – output HOME

Desc:       outputs the HOME character control code
In,Out:     -
Change:     AF
Stack:      15

2E MODI – call MODIFY

Desc:       this calls the MODIFY system command
In:         HL - start address
Out:        -
Change:     AF,BC,DE,HL
Stack:      18

2F PUDE – clear pixel

Desc:       clear pixel at position (HOR),(VERT)
In:         (HOR)   - horizontal position (0..13FH)
            (VERT)  - vertical position (0..FFH)
Out:        A       - color byte
            CY = 1  - error: invalid position
            Z  = 1  - pixel was not set
Note:       position (0,0) is lower-left corner

30 PUSE – set a pixel

Desc:       set pixel at position (HOR),(VERT)
In:         (HOR)   - horizontal position (0..13FH)
            (VERT)  - vertical position (0..FFH)
            (FARB)  - pixel color
                      bit 0 set: XOR
                      bit 1 set: clear point
                      bits 3..7: pixel color
Out:        CY = 1  - error: invalid position
Change:     AF
Stack:      4

31 SIXD – move and reset CAOS working memory

Desc:       moves the CAOS working memory area (default location: 01F0):
            - initialize the interrupt table
            - initialize the IX register
            - set interrupt mode IM2
            - initialize the PIO and CTC
            - initialize the cassette tape buffer
            - initialize the menu prolog byte
In:         A - high-byte of new memory location
Out:        (MIXIT) - high-byte of new memory location
Change:     AF,BC,DE,HL,IX
Stack       6

32 DABR – compute character buffer address

Desc:       computes the character buffer address relativ to the
            currently set window
In:         D   - line in current window
            E   - column in current window
Out:        CY = 1  - error: position outside window
            HL      - character buffer address
Change:     AF,BC,HL
Stack:      2
Note:       can be used to read-back ASCII codes from the character buffer

33 TCIF – test if cursor pos inside window

Desc:       tests if cursor position is inside current window
In:         D   - line in current window
            E   - column in current window
Out:        CY = 1  - position outside window
Change:     AF
Stack:      0

34 PADR – compute pixel- and color-address

Desc:       computes the pixel- and color-buffer address from a charcter position
In:         H   - vertical position (0..FFH ??)
            L   - horizontal position (0..27H)
Out:        DE  - color buffer address (only KC85/2 and KC85/3)
            HL  - pixel buffer address
Note:       can only be called through entry point 1 (F003)
            HL = 00 is top-left corner
            on KC85/4, pixel and color buffer address is identical!

35 TON – sound output

Desc:       emits a sound
In:         (ARG1+0)    - sound pitch 1 (timer constant for CTC0)
            (ARG1+1)    - CTC0 prescaler (0: prescaler=16, 1: prescaler=256)
            (ARG2+0)    - sound pitch 2 (timer constant for CTC1)
            (ARG2+1)    - CTC1 prescaler
            (ARG3+0)    - volume (0..1FH), must be even on KC85/4 (?)
            (ARG3+1)    - duration in N*20ms, or 0 to loop infinitely
Out:        AF,BC,DE,HL
Stack:      1
Note:       the sound duration is controlled via CTC interrupr

36 SAVE – save program

Desc:       save a machine-code program to cassette tape
In:         HL      - start address of filename (as 8.3 name.type)
            (ARGN)  - number of arguments (2 or 3)
            (ARG1)  - start address of program
            (ARG2)  - end address of program
            (ARG3)  - entry point address of program
Out:        -
Change:     AF,BC,DE,HL
Stack:      16
Note:       auto-start programs use (ARGN)=3

37 MBIN – byte-input from tape

Desc:       read bytes from cassette tape with name check in first block
In:         A   - data (?)
                  bit 3 set: INIT
            D   - control byte
                  bit 6 set: CLOSE
            HL  - points to name (11 bytes), only for INIT
Out:        -
Change:     AF,DE,HL
Stack:      16
Note:       the documentation doesn't make a lot of sense for this function :/
            only CAOS 3.1 and up

38 MBOUT – byte-output to tape

Desc:       write bytes to cassette tape
In:         A   - data (?)
            D   - control byte
                  bit 3 set: INIT
                  bit 6 set: CLOSE
            HL  - points to name (11 bytes), only for INIT
Out:        -
Change:     AF,DE,HL
Stack:      16
Note:       the documentation doesn't make a lot of sense for this function :/
            only CAOS 3.1 and up

39 KEY – assign function key

Desc:       calls the KEY system command to interactively assign a function key
In:         A   - function key number (1..0CH)
Out:        -
Change:     AF,BC,DE,HL
Stack:      18
Note:       only CAOS 3.1 and up

3A KEYLI – print function key assignment

Desc:       calls the KEYLIST system command to output the current 
            function key assignment
In,Out:     -
Change:     AF,BC,HL
Stack:      18
Note:       only CAOS 3.1 and up

3B DISP – hex/ascii dump

Desc:       calls the DISPLAY system command
In KC85/3:  (ARGN)  - number of arguments
            HL      - start address
            DE      - end address
            C       - number of lines (if ARGN > 2)
In KC85/4:  A       - number of arguments
            HL      - start address
            E       - number of lines (if A > 1)
            C       - number of columns (if A > 2)
Out:        -
Change:     AF,BC,DE,HL
Stack:      19
Note:       key BRK: cancel
            key STOP: change into MODIFY mode
            only CAOS 3.1 and up

3C WININ – initialize a window

Desc:       initialize or a new window 
In:         A   - window number (0..9)
            HL  - top left corner
            DE  - window size
Out:        CY = 1: error
Change:     AF,BC,DE,HL
Stack:      5
Note:       only CAOS 3.1 and up

3D WINAK – select window

Desc:       sets the current window 
In:         A   - window number (0..9)
Out:        CY = 1: error
Change:     AF,BC,DE,HL
Stack:      2
Note:       only CAOS 3.1 and up

3E LINE – draw a line

Desc:       draws a pixel line from X0/Y0 to X1/Y1
In:         (ARG1)  - X0
            (ARG2)  - Y0
            (ARG3)  - X1
            (ARG4)  - Y1
            (FARB)  - color byte:
                      bit 0 set: XOR
                      bit 1 set: clear pixels
                      bits 3..7: color
Out:        -
Change:     AF,BC,DE,HL,AF',BC',DE',HL'
Stack:      8
Note:       only CAOS 3.1 and up

3F CIRCLE – draw a circle

Desc:       draw a circle at XM/YM and radius R
In:         (ARG1) - XM
            (ARG2) - YM
            (ARG3) - R
            (FARB) - see 3E LINE
Out:        -
Change:     AF,BC,DE,HL,AF',BC',DE',HL'
Stack:      8
Note:       only CAOS 3.1 and up

40 SQR – square root

Desc:       compute 8-bit square root from 16-bit value
In:         HL  - 16-bit value
Out:        A   - 8-bit result
Change:     AF,HL,DE
Stack:      1
Note:       only CAOS 3.1 and up

41 MULT – multiplication

Desc:       multiply 2 8-bit numbers into a 16-bit result
In:         D, C    - 8-bit factors
Out:        BA      - 16-bit result
Change:     AF,HL,DE,B
Stack:      1
Note:       only CAOS 3.1 and up

42 CSTBT – toggle ASCII control code mode

Desc:       toggles between rendering or executing an ASCII control code
            by inverting bit 4 of (STBT)
In:         -
Out:        -
Change:     -
Stack:      1
Note:       only CAOS 3.1 and up

43 INIEA – initialize I/O channel

Desc:       initialize an I/O channel via table
In:         HL  - start address of init table
Out:        HL  - end of init table + 1
Change:     HL
Stack:      1
Note:       only CAOS 3.1 and up
            table structure:
            1st byte    - I/O address
            2nd byte    - number of init bytes
            3rd byte    - init bytes
            .
            .
            .
            Nth byte

44 INIME – initialize multiple I/O channels

Desc:       initialize multiple I/O channels via table
In:         HL  - start address of init table
            D   - number of I/O channels
Out:        HL  - end of init tables + 1
Change:     D,HL,F
Stack:      1
Note:       only CAOS 3.1 and up
            the I/O init table is made of multiple tables
            as described in 43 INIEA

45 ZKOUT – output string at HL

Desc:       output a null-terminated string at HL
In:         HL  - points to null-terminated string
Out:        HL  - points to end of string (?)
Change:     HL,AF
Stack:      22
Note:       only CAOS 3.1 and up

46 MENU – call MENU system command

Desc:       outputs the current menu and enters interactive command mode
In:         (IX+9)  - prolog byte
Out,Change: -
Note:       only CAOS 3.1 and up

47 V24OUT – initialize printer output

Desc:       initializes printer output
In:         (ARG1)  - module slot with M003 module
            (ARG2)  - channel of M003 module 
            (ARG3)  - user output channel
            (ARG4)  - = 1: protocol on/off at SHIFT CLEAR
                      = 2: at SHIFT CLEAR HARDCOPY/SCREENCOPY
            (ARG5)  - printer type
            (ARGN)  - number of arguments
            (INTV1)     - start addr of init table (SIO, CTC)
            (INTV1L)    - length of init table
Out:        -
Change:     AF,BC,DE,HL
Stack:      2
Note:       CAOS 4.1 and up
            documentation is unclear

48 V24DUP – initialize V24 duplex

Desc:       initializes V24 duplex routine
In:         (ARG1)  - module slot with M003 module
            (ARG2)  - channel of M003 module
            (ARG3)  - user in/out channel
            (ARGN)  - number of arguments
            (INTV2)     - start addr of init table
            (INTV2L)    - length of init table
Out:        -
Change:     AF,BC,DE,HL
Stack:      1
Note:       CAOS 4.1 and up
            documentation is unclear