Editing SmartBox OS (section)

=== OS_CALLOS ===

This OS call does various calls which are completely linked to the
OS, everything from relocating code to reading and writing the hardware
ports.

As normal, a "function" request value is placed in the A register,
any extra data is put in the X and Y registers and a call to OS_CALLOS is
made, and data is passed back in X, Y, c and z.  The A register will return
0 for all routines except for calls 0 (deemed always to exist anyway), 12 (A
is reserved for future use), 14 (returns 1 instead) and 15 (12, 14 and 15 do
not return 12, 14, 15 in A though), if the routine passes back the same
value in A (the exception being call 0) as you gave it then that OS_CALLOS
function is not supported.

==== OS_CALLOS 0: Return the OS version number ====

{|class="calltable"
|Entry||
* A = 0
* X, Y, c, z = undefined
|-
|Exit||
* A = Hardware release version
* XY = OS version number
* c, z is preserved
|-
|Note||
* Hardware version 0 is obsolete
* Hardware version 1 is SmartBox
** VIA at &8030
** UART at &8010
** ADC at &8000
** AUX_PORT (inputs) at &8020
|}

==== OS_CALLOS 1: Claim a block of JobCodes ====

{|class="calltable"
|Entry||
* A = 1
* X = number of JobCodes required
* Y, c, z = undefined
|-
|Exit||
* A = 0
* X = base JobCode, if 0, no big enough block available
* Y = Job ID number, 0 if no big enough block
* c = set if no big enough block
* z is preserved
|-
|Note||
This call claims JobCodes codes from the JobCode list.  JobCodes
are in the range 0 to 255, 0 is special and is the JobCall "Blank".  All the
OS ones are spaced out but an "application" can claim a block of JobCodes,
usually just the 1 call.  If there is not a contigous block big enough then
no JobCodes are allocated and the appropiate result is returned.  The Job ID
is from 0 to 255, 0 is unallocated, 1 is the OS calls, the rest are external
applications, each successful call increments the Job ID returned, meaning a
maximum of 255 successful calls (not important as their is not that many
free calls available !), the Job ID can be used to check whether a JobCall
request is yours.
|}

==== OS_CALLOS 2: Handle NameCode request for the application ====

{|class="calltable"
|Entry||
* A = 2
* XY = block pointing to block of JobNames
* c, z = undefined
* jobin_buf contains JobName (terminated by CR)
* zero_gp3 = JobId (as returned by CALLOS 1)
|-
|Exit||
* A = 0
* XY = undefined
* z is preserved
* if c = 1 (Name not found)
* if c = 0 (Name found)
* jobin_buf contains the JobCode
|-
|Note||
Used via the internal_vec to convert from JobName to job code, the
table format is just a list of the JobNames (each one CR terminated)
terminated by a &FF
|}

==== OS_CALLOS 3: Handle CodeName request for the application ====

{|class="calltable"
|Entry||
* A = 3
* XY = block pointing to block of JobNames
* c, z = undefined
* jobin_buf contains JobCode
* zero_gp3 = job id (as returned by CALLOS 1)
|-
|Exit||
* A = 0
* XY = undefined
* z is preserved
* if c = 1 (JobCode not found)
* if c = 0 (JobCode found)
*: jobin contains JobName (terminated by CR)
|-
|Note||
See above
|}

==== OS_CALLOS 4: Relocate code ====

{|class="calltable"
|Entry||
* A = 4
* XY = execution address (offset from start of code)
* c, z = undefined
* zero_gp1 = offset address of execution after relocation
* zero_gp2 = offset address of relocation BitMap
* zero_gp3 = length of code to relocate
|-
|Exit||
No exit, calls begining of code straight away
|-
|Note||
See later section on Relocation
|}

==== OS_CALLOS 5: Describe the enviroment ====

{|class="calltable"
|Entry||
* A = 5
* X, Y, c, z = undefined
|-
|Exit||
* A = 0
* c, z is preserved
* XY = address of table, format as such:
* 1st byte: number of bytes (ie. 14 currently)
* byte 2+:
** address of VIA
** address of ACIA
** address of ADC
** address of AUX_PORT
** address of jobs_status
** address of jobin_buf
** address of jobout_buf
|-
|Note||
It is preferred that this call is consulted first if direct use of
the hardware is going to be used to get the correct addresses, or use OS_CALLOS
0 and decide what addresses/configuration to use from the Hardware version
number.
|}

==== OS_CALLOS 6: Read a register in the VIA ====

{|class="calltable"
|Entry||
* A = 6
* X = register (0 to 15)
* Y, c, z = undefined
|-
|Exit||
* A = 0
* Y = value read
* X, c, z is preserved
|-
|Note||
The register number is not checked for range.  This call allows
access to the hardware without actually directly accessing the hardware
yourself.
|}

==== OS_CALLOS 7: Write to a register in the VIA ====

{|class="calltable"
|Entry||
* A = 7
* X = register (0 to 15)
* Y = value to write
* c, z = undefined
|-
|Exit||
* A = 0
* X, Y, c, z is preserved
|-
|Note||
See above
|}

==== OS_CALLOS 8: Read a register in the ACIA ====

{|class="calltable"
|Entry||
* A = 8
* X = register (0 to 15)
* Y, c, z = undefined
|-
|Exit||
* A = 0
* Y = value read
* X, c, z is preserved
|-
|Note||
See above
|}

==== OS_CALLOS 9: Write to a register in the ACIA ====


{|class="calltable"
|Entry||
* A = 9
* X = register (0 to 15)
* Y = value to write
* c, z = undefined
|-
|Exit||
* A = 0
* X, Y, c, z is preserved
|-
|Note||
See above
|}

==== OS_CALLOS 10: Read a register in the ADC ====


{|class="calltable"
|Entry||
* A = 10
* X = register (0 to 15)
* Y, c, z = undefined
|-
|Exit||
* A = 0
* Y = value read
* X, c, z is preserved
|-
|Note||
See above
|}

==== OS_CALLOS 11: Write to a register in the ADC ====

{|class="calltable"
|Entry||
* A = 11
* X = register (0 to 15)
* Y = value to write
* c, z = undefined
|-
|Exit||
* A = 0
* X, Y, c, z is preserved
|-
|Note||
See above
|}

==== OS_CALLOS 12: Read an ADC channel ====

{|class="calltable"
|Entry||
* A = 12
* X = channel number to read (0 to 3)
* Y, c, z = undefined
|-
|Exit||
* A = reserved for future use
* if c = 0 (8 bit reading)
** Y = reading
** X = undefined
* if c = 1 (16 bit reading)
** X = reading (LSB)
** Y = reading (MSB)
* z = undefined
|-
|Note||
The A register MAY not return 0, it is guaranteed though that it will not return 12.
|}

==== OS_CALLOS 13: Read a register in the AUX_PORT ====

{|class="calltable"
|Entry||
* A = 13
* X = register (0 to 15)
* Y, c, z = undefined
|-
|Exit||
* A = 0
* Y = value read
* X, c, z is preserved
|-
|Note||
See above
|}

==== OS_CALLOS 14: Start sensor type checking (OS 2.066+) ====

{|class="calltable"
|Entry||
* A = 14
* X, Y, c, z = undefined
|-
|Exit||
* A = 1
* Y = value read
* X, c, z is preserved
|-
|Note||
A returns 1.
This flags the ADC routines to start checking the sensors.
After calling this routine, you should poll OS_CALLOS 15 to check when all the sensors have been checked.
|}

==== OS_CALLOS 15: Check the status of sensor checking (OS 2.066+) ====

{|class="calltable"
|Entry||
* A = 15
* X, Y, c, z = undefined
|-
|Exit||
* A = status
* XY = pointer to sensor types block
* c, z is preserved
|-
|Note||
A does not return 0, though it is guaranteed to not return 15.
* Status of 0 = checking finished and no futher check pending
* Status of 1 = Waiting for current ADC channel to finish converting before switching sensor checking on
* Status of >127 = Checking sensor types
The block pointed to by XY consists of 4 bytes, each byte contains the sensor type for the appropiate sensor, a type of 0 means no sensor present
|}

==== OS_CALLOS 16: Set the OS' irq mask for the VIA (OS 2.069+) ====

{|class="calltable"
|Entry||
* A = 16
* X = EOR mask
* Y = AND mask
* c, z = undefined
|-
|Exit||
* A = 0
* X = old mask value
* Y = new mask value
* c, z is preserved
|}

==== OS_CALLOS 17: Set the OS' irq mask for the ACIA (OS 2.069+) ====

{|class="calltable"
|Entry||
* A = 17
* X = EOR mask
* Y = AND mask
* c, z = undefined
|-
|Exit||
* A = 0
* X = old mask value
* Y = new mask value
* c, z is preserved
|}

==== OS_CALLOS 18: Set the OS' irq mask for the ADC (OS 2.069+) ====

{|class="calltable"
|Entry||
* A = 18
* X = EOR mask
* Y = AND mask
* c, z = undefined
|-
|Exit||
* A = 0
* X = old mask value
* Y = new mask value
* c, z is preserved
|}

==== OS_CALLOS 19: Set the ACIA's ctrl register and OS' soft copy (OS 2.069+) ====

{|class="calltable"
|Entry||
* A = 19
* X = EOR mask
* Y = AND mask
* c, z = undefined
|-
|Exit||
* A = 0
* X = old mask value
* Y = new mask value
* c, z is preserved
|}

==== OS_CALLOS 20: Set the reset vector for battery back RAM support (OS 2.069+) ====

{|class="calltable"
|Entry||
* A = 20
* XY = address to set reset vector or 0 for read only
* c, z = undefined
|-
|Exit||
* A = 0
* XY = old reset vector address
* c, z is preserved
|-
|Note||
Sets the reset vector to address supplied and sets check bytes in
workspace.
|}