Editing SmartBox OS (section)

== Vectors ==

Some parts of the system are controlled by vectors, vectors also
exist to patch the normal operation of some parts of the system.  Vectors
are RAM pointers, which are called to point to the routine to use.  Being in
RAM this means that they can be altered by the user to allow the user to
modify the operation of part, or all, of a system call.  All the call
routines (eg.  OS_DECODEJOB, OS_READBYTE etc.) are called via a RAM vector. 
There are vectors which the user patches to pick up unknown jobcodes, and to
service requests like NameCode/CodeName etc.

The vectors are placed at address &200 in memory, each are 2 bytes
long.

{|class="wikitable"
| brk_vec || &200
| Called whenever there is a BRK error, which should not occur under normal use, as the controller OS does not make use of BRK errors.
|-
| nmi_vec || &202
| Called whenever there is a NMI request (not really applicable, as the NMI line is not connected to anything).
|-
| irq_vec || &204
| Called whenever there is an interupt.
|-
| irq2_vec || &206
| Called whenever an unknown interupt is encountered, ie.  didn't come from the controller's VIA, ACIA or ADC, or the interupt from the VIA was not used by the OS.
|-
| sendserial_vec || &208
| Called when OS_SENDBYTE is called.
|-
| readserial_vec || &20A
| Called when OS_READBYTE is called.
|-
| sendjob_vec || &20C
| Called when OS_SENDJOB is called.
|-
| readjob_vec || &20E
| Called when OS_READJOB is called.
|-
| decode_job_vec || &210
| Called when OS_DECODEJOB is called.  Note that OS_DECODEJOB first calls a OS routine which sets a flag to say it's been called internally, JobCode requests the OS gets from the serial port are called via this vector, with a flag saying "from the serial port".
|-
| unknownjob_vec || &212
| Called whenever an unknown JobCode is encountered.
|-
| extjob_vec || &214
| Called whenever the ExtendedJob is called, the A register holds the extension value.
|-
| centisec_vec || &216
| Called 100 times a second from the IRQ routine from interupts off timer 1 of the VIA.  The OS has its pulsing routines on the end of this.  Note that you should return with a RTS, not RTI, you may also corrupt any of the registers.
|-
| internal_vec || &218
| Called when some information is needed from various parts of the system, which includes the OS which lies on the end of this vector.  An example is NameCode, which calls this vector to ask everybody if they recognise the JobName in question.
|-
| callos_vec || &21A
| Called when OS_CALLOS is called.
|-
| printer_vec || &21C
| Called when OS_PRINTER is called.
|-
| reset_vec	|| &21E
| Called when the OS gets a reset and the internal check bytes flag the integrity of the RAM.  It is first called with C cleared for everything to setup vectors and then called with C set for a foreground "language" application to start up.  Use OS_CALLOS 20 to set this vector.
|}

All vectors should be 'daisy chained', ie.  any routine which uses
any of them should store the current value in its own workspace and alter
the vector and at the end of the routine which services the vector should
jump to the original saved value, if this isn't done the system may 'fall'
down.

unknown, extendjob and irq2 all point to (in the present OS) to a
routine which just returns.  brk in the current OS just resets the stack and
jumps back to the OS' main idle loop.

Irqs are reenabled before brk_vec is called

=== irq_vec ===

This is called when the 65c02 receives an irq from a device.  As the
65c02 signals brk and irq through the same cpu vector the OS first finds out
which one it really was and calls either brk_vec or irq_vec.  It also stores
the A reg at address &A0, as the A reg is corrupted while it finds out which
vector to really call, any irq routine which has claimed the irq should
restore the A reg from &A0 before returning via a RTI, else you should pass
on the call to the old vector owner.

irq2_vec is called by the OS irq routine if it does not find a irq
it can service (or as been masked out) in as-good-as the same conditions as
irq_vec is called.  The OS has a default irq2_vec handler of restoring A
from &A0 and doing a RTI.

=== internal_vec and unknownjob_vec ===

The main operation of extended JobCalls rely on patching some
vectors, two in fact.  These two are unknownjob_vec and internal_vec. 
unknownjob_vec is the one which the OS calls to actually tell everybody that
a JobCall has been requested which it does not know about (the JobCall MUST
have been claimed before hand with OS_CALLOS, function 1, or else it is not
passed on).  internal_vec is the one which the OS calls in request to a
NameCode or CodeName.

The vectors are defined as thus:

==== internal_vec ====

===== internal_vec 0 =====

{|class="calltable"
|Purpose||
Nothing
|-
|Entry||
* A = 0
* X, Y, c, z = undefined
|-
|Exit||
Leave everything as it is and exit straight away
|-
|Note||
Used for claimed calls
|}

===== internal_vec 1 =====

{|class="calltable"
|Purpose||
NameCode request
|-
|Entry||
* A = 1
* X, Y, c, z = undefined
* jobin_buf contains JobName (CR terminated)
|-
|Exit||
* if JobName recognised then
** A = 0
** first byte of jobin_buf contains matched JobCode
* if JobName not recognised then
** A = 1
** X, Y, c, z = undefined
|}

===== internal_vec 2 =====

{|class="calltable"
|Purpose||
CodeName request
|-
|Entry||
* A = 2
* X, Y, c, z = undefined
* jobin_buf contains JobCode
|-
|Exit||
* if JobCode recognised then
** A = 0
** jobin_buf contains matched JobName (CR terminated)
* if JobCode not recognised then
** A = 2
** X, Y, c, z = undefined
|}

All other calls (ie.  not 0, 1 or 2 should be passed on straight
away for future expansion)

==== unknownjob_vec ====

{|class="calltable"
|Purpose||
To pass on unknown JobCalls to the correct owner
|-
|Entry||
* A = environment (0 = internal call, 1 = serial call)
* Y = JobCode
* X = JOB ID of owner
* c, z = undefined
|-
|Exit||
* if jobcode yours then
** if wrong environment then
*** A = 1
*** Y = 0
*** X, c, z = undefined
** if right environment then
*** perform function
*** A = 0
*** Y = 0
*** X, c, z = undefined
* if jobcode not yours then
** pass on with registers unaltered
|}