Smart Box - User contributions [en-gb]

File:DIN-5-Socket-180.svg

2025-02-21T12:35:51Z

Benryves: Benryves uploaded a new version of File:DIN-5-Socket-180.svg

5-pin DIN socket (180°)

File:DIN-5-Socket-240.svg

2025-02-21T12:35:43Z

Benryves:

Tutorial

2023-11-18T06:28:39Z

Benryves: /* Disconnecting Smart Box from the host computer */

== About Smart Move ==

Smart Move is the control program designed for use with Smart Box.
With Smart Move you can create your own programs to control models and other devices connected to Smart Box.
Smart Move includes special commands to control the motors and other outputs.
It also includes commands to detect the signals received from any sensors you have connected to Smart Box.
The sensors are the ''inputs'' to the system.
The motors, lamps or other similar devices are the ''outputs''.
The outputs can be switched on and off depending on the state of the inputs.
For example, a lamp can be switched on when a light sensor detects a fall in light level, or a buzzer can be switched on when a temperature sensor detects a predetermined temperature.

== Data capture ==

Smart Move also includes commands which allow you to save readings from the sensors to disk.
These sensor readings can then be analysed using other programs such as a spreadsheet.
The readings can also be stored when certain conditions are met.
For example the temperature during the hours of darkness could be taken by recording the values from the temperature sensor only when the light sensor reading is below a certain level.
This feature allows sophisticated data capture experiments to be designed.

== Procedures ==

Each Smart Move program you create will consist of at least one ''procedure''.
A procedure is a sequence of instructions which are grouped together and given a name.
You then simply refer to the procedure name to make your program execute the complete sequence of instructions.
A typical Smart Move program will be broken into a number of small procedures, each procedure performing a precise part of the overall program.
Breaking the program down into procedures allows each one to be tested independently.
Each procedure can be used any number of times within any other procedure.
You will usually have one main procedure which uses a number of sub procedures.

== Presumed Knowledge ==

This guide presumes no prior knowledge of Smart Box, Smart Move or control technology.
However, the guide does assume that you know how to perform certain basic tasks with your computer. You should know how to:

* Use the keyboard
* Copy disks, programs and documents
* Perform simple editing tasks, including deleting text

If you need to learn more about these basic tasks, consult the handbooks and disks that came with your computer.

== Contents ==

The following sections of this guide take you through creating your first program, and provide a number of example procedures.
The language commands are detailed in full in the [[reference]] section.

Make sure that Smart Box and your computer are correctly connected and switched on (see [[Setting up#Setting up procedure|Smart Box setting up procedure]]), then load the Smart Move software.

[[File:Tutorial-fig01.png|frame|none|fig. 1]]

Once loaded you will see the main Smart Move screen as shown in fig. 1.
The top of the screen is the monitor window.
This area of the screen displays the current state of the various inputs and outputs.
The bottom section of the screen is the text window.
You use this window to type in commands.
Any values you ask Smart Move to print will also be displayed here.

* [[Switching outputs on and off]]
* [[Procedures]]
* [[Repeating actions]]
* [[Variables]]
* [[Procedures within procedures]]
* [[Saving procedures]]
* [[Loading procedures]]
* [[Using sensors]]
* [[Making decisions]]
* [[Data capture]]
* [[Average]]
* [[Controlling a motor]]
* [[Varying power and pulsing outputs]]
* [[Printing procedures]]

== Disconnecting Smart Box from the host computer ==

If you close the Smart Move application using "Disconnect" instead of "Quit" then the procedures in the Smart Box will continue running.
The disconnect command differs according to the host computer platform:

* PC: Press Shift+F10
* Apple Macintosh: Select File→Disconnect from the Smart Move application menu.
* Acorn Archimedes: Select Disconnect from the menu displayed when the menu button is clicked over the program icon on the Icon bar.
* BBC Micro / Master: Press Shift+''f''0

Disconnecting closes the Smart Move program while allowing the procedures in the Smart Box to continue running.
The host computer can then be disconnected from the Smart Box.
When the connection is remade and the Smart Move program is run, any procedures in Smart Box will be reloaded into Smart Move.
If power is disconnected from the Smart Box, its memory is cleared, so save procedures before disconnecting.

This section has introduced the basic principles involved in creating a Smart Move program.
The [[reference]] section gives full details of each command.
Whenever you write a Smart Move program try to create a number of procedures, each doing a specific task, rather than one large program doing everything.
In this way you will be able to test the individual parts of your program and identify the errors more easily.

Tutorial

2023-11-18T06:27:30Z

Benryves: /* Disconnecting Smart Box from the host computer */ Corrected the BBC Micro keyboard shortcut

== About Smart Move ==

Smart Move is the control program designed for use with Smart Box.
With Smart Move you can create your own programs to control models and other devices connected to Smart Box.
Smart Move includes special commands to control the motors and other outputs.
It also includes commands to detect the signals received from any sensors you have connected to Smart Box.
The sensors are the ''inputs'' to the system.
The motors, lamps or other similar devices are the ''outputs''.
The outputs can be switched on and off depending on the state of the inputs.
For example, a lamp can be switched on when a light sensor detects a fall in light level, or a buzzer can be switched on when a temperature sensor detects a predetermined temperature.

== Data capture ==

Smart Move also includes commands which allow you to save readings from the sensors to disk.
These sensor readings can then be analysed using other programs such as a spreadsheet.
The readings can also be stored when certain conditions are met.
For example the temperature during the hours of darkness could be taken by recording the values from the temperature sensor only when the light sensor reading is below a certain level.
This feature allows sophisticated data capture experiments to be designed.

== Procedures ==

Each Smart Move program you create will consist of at least one ''procedure''.
A procedure is a sequence of instructions which are grouped together and given a name.
You then simply refer to the procedure name to make your program execute the complete sequence of instructions.
A typical Smart Move program will be broken into a number of small procedures, each procedure performing a precise part of the overall program.
Breaking the program down into procedures allows each one to be tested independently.
Each procedure can be used any number of times within any other procedure.
You will usually have one main procedure which uses a number of sub procedures.

== Presumed Knowledge ==

This guide presumes no prior knowledge of Smart Box, Smart Move or control technology.
However, the guide does assume that you know how to perform certain basic tasks with your computer. You should know how to:

* Use the keyboard
* Copy disks, programs and documents
* Perform simple editing tasks, including deleting text

If you need to learn more about these basic tasks, consult the handbooks and disks that came with your computer.

== Contents ==

The following sections of this guide take you through creating your first program, and provide a number of example procedures.
The language commands are detailed in full in the [[reference]] section.

Make sure that Smart Box and your computer are correctly connected and switched on (see [[Setting up#Setting up procedure|Smart Box setting up procedure]]), then load the Smart Move software.

[[File:Tutorial-fig01.png|frame|none|fig. 1]]

Once loaded you will see the main Smart Move screen as shown in fig. 1.
The top of the screen is the monitor window.
This area of the screen displays the current state of the various inputs and outputs.
The bottom section of the screen is the text window.
You use this window to type in commands.
Any values you ask Smart Move to print will also be displayed here.

* [[Switching outputs on and off]]
* [[Procedures]]
* [[Repeating actions]]
* [[Variables]]
* [[Procedures within procedures]]
* [[Saving procedures]]
* [[Loading procedures]]
* [[Using sensors]]
* [[Making decisions]]
* [[Data capture]]
* [[Average]]
* [[Controlling a motor]]
* [[Varying power and pulsing outputs]]
* [[Printing procedures]]

== Disconnecting Smart Box from the host computer ==

If you close the Smart Move application using "Disconnect" instead of "Quit" then the procedures in the Smart Box will continue running.
The disconnect command differs according to the host computer platform:

* PC: Press Shift+F10
* Apple Macintosh: Select File→Disconnect from the Smart Move application menu.
* Acorn Archimedes: Select Disconnect from the menu displayed when the menu button is clicked over the program icon on the Icon bar.
* BBC Micro / Master: Press Shift+''f''0

Pressing Shift+F10 closes the Smart Move program while allowing the procedures in the Smart Box to continue running.
The host computer can then be disconnected from the Smart Box.
When the connection is remade and the Smart Move program is run, any procedures in Smart Box will be reloaded into Smart Move.
If power is disconnected from the Smart Box, its memory is cleared, so save procedures before disconnecting.

This section has introduced the basic principles involved in creating a Smart Move program.
The [[reference]] section gives full details of each command.
Whenever you write a Smart Move program try to create a number of procedures, each doing a specific task, rather than one large program doing everything.
In this way you will be able to test the individual parts of your program and identify the errors more easily.

Internal Hardware

2023-11-13T01:19:43Z

Benryves: Added component names to list

The following documentation is from studying the inside of an SB-01 SmartBox version 2 issue 1.1. Other revisions are known to have different internal components.

{|class="wikitable"
! Component !! Part number !! Name !! Datasheet
|-
| CPU || R65C02P3 || RC65C02 Microprocessor || [[Media:Datasheet-CPU-R65C02.pdf|R65C02]]
|-
| RAM || TC55257BPI10L || 32,768 x 8 bit static RAM || [[Media:Datasheet-RAM-TC55257BPI.pdf|TC55257BPI]]
|-
| ROM || NMC27C64Q || 8,192 x 8 bit CMOS EPROM || [[Media:Datasheet-ROM-NMC27C64.pdf|NMC27C64]]
|-
| VIA || R6522AP || R6522 Versatile Interface Adapter || [[Media:Datasheet-VIA-R6522.pdf|R6522]]
|-
| ACIA || EF68B50P || Asynchronous Communications Interface Adapter || [[Media:Datasheet-ACIA-EF6850.pdf|EF6850]]
|-
| ADC || D7002C || 12-bit Binary A/D Converter || [[Media:Datasheet-ADC-D7002.pdf|µD7002]]
|}

Internal Hardware

2023-11-12T23:46:58Z

Benryves: Added list of parts and datasheets

The following documentation is from studying the inside of an SB-01 SmartBox version 2 issue 1.1. Other revisions are known to have different internal components.

{|class="wikitable"
! Component !! Part number !! Datasheet
|-
| CPU || R65C02P3 || [[Media:Datasheet-CPU-R65C02.pdf|R65C02]]
|-
| RAM || TC55257BPI10L || [[Media:Datasheet-RAM-TC55257BPI.pdf|TC55257BPI]]
|-
| ROM || NMC27C64Q || [[Media:Datasheet-ROM-NMC27C64.pdf|NMC27C64]]
|-
| VIA || R6522AP || [[Media:Datasheet-VIA-R6522.pdf|R6522]]
|-
| ACIA || EF68B50P || [[Media:Datasheet-ACIA-EF6850.pdf|EF6850]]
|-
| ADC || D7002C || [[Media:Datasheet-ADC-D7002.pdf|µD7002]]
|}

File:Datasheet-ADC-D7002.pdf

2023-11-12T23:46:17Z

Benryves: µD7002C 12-bit binary A/D converter datasheet

== Summary ==
µD7002C 12-bit binary A/D converter datasheet

File:Datasheet-ACIA-EF6850.pdf

2023-11-12T23:45:29Z

Benryves: /* Summary */

== Summary ==
EF6850 asynchronous communications interface adapter (ACIA) datasheet

File:Datasheet-ACIA-EF6850.pdf

2023-11-12T23:45:18Z

Benryves: EF6850 asynchronous communications interface adapter (ACIA)

== Summary ==
EF6850 asynchronous communications interface adapter (ACIA)

File:Datasheet-VIA-R6522.pdf

2023-11-12T23:44:31Z

Benryves: R6522 Versatile Interface Adapter (VIA) datasheet

== Summary ==
R6522 Versatile Interface Adapter (VIA) datasheet

File:Datasheet-ROM-NMC27C64.pdf

2023-11-12T23:44:08Z

Benryves: NMC27C64 65,536-Bit (8192 x 8) CMOS EPROM datasheet

== Summary ==
NMC27C64 65,536-Bit (8192 x 8) CMOS EPROM datasheet

File:Datasheet-RAM-TC55257BPI.pdf

2023-11-12T23:43:26Z

Benryves: TC55257BPI/BFI/BSPI/BFTI/BTRI-10L 32,768 word x 8 bit static RAM datasheet

== Summary ==
TC55257BPI/BFI/BSPI/BFTI/BTRI-10L 32,768 word x 8 bit static RAM datasheet

File:Datasheet-CPU-R65C02.pdf

2023-11-12T23:33:43Z

Benryves: Rockwell R65C02, R5C102 and R65C112 R65C00 Microprocessors datasheet

== Summary ==
Rockwell R65C02, R5C102 and R65C112 R65C00 Microprocessors datasheet

Main Page

2023-11-12T23:26:26Z

Benryves: /* Technical Information */

== Smart Box User Guide ==

Information has been adapted from the original ''Smart Box'' and ''Smart Move'' user manual, copyright Economatics (Education) Limited 1992.

* [[Smart Box]] - A guide to using the Smart Box, including the Smart Box ''EV''.
* [[Tutorial]] - Tutorial for the Smart Move software.
* [[Reference]] - A general reference guide to Smart Move commands.
* [[Smart Sensors and Relay]] - Information sheets on individual sensors and input/output devices.

== Technical Information ==

* [[Serial Port]] - Pinout for the Smart Box's serial port.
* [[Analogue Sensor Ports]] - Pinout for the four analogue sensors.
* [[Internal Hardware]] - The chips that make the Smart Box work.

The following pages have been adapted from information shared at https://github.com/Phipli/SmartBox/issues/

* [[SmartBox JobList]] - A list of the available jobs (routines) provided by the Smart Box OS that can be invoked from the serial link.
* [[SmartBox OS]] - Information about the organisation of the operating system and development of additional jobs.
* [[SmartBox AlbertLink]] - Details of the AlbertLink job used by the Smart Move software.

Serial Port

2023-11-12T04:22:57Z

Benryves: Added content for serial port documentation

== Pinout ==

[[File:DIN-5-Socket-240.svg|frame|right|5-pin 240° DIN socket]]

{|class="wikitable"
! Pin !! Function
|-
| 1 || CTS
|-
| 2 || GND (0V)
|-
| 3 || RTS
|-
| 4 || TXD
|-
| 5 || RXD
|}

The pin numbers and functions are given for the Smart Box as a DCE, so when connected to a computer (which is a DTE) you should the connect pins directly, i.e. TXD on the Smart Box connects to TXD on the PC, RXD on the Smart Box connects to RXD on the PC etc.

{{Clear}}

== PC ==

[[File:DE-9F.svg|frame|right|DE-9F serial connector]]

{|class="wikitable"
! Pin !! Function
|-
| 1 ||
|-
| 2 || RXD
|-
| 3 || TXD
|-
| 4 ||
|-
| 5 || GND (0V)
|-
| 6 ||
|-
| 7 || RTS
|-
| 8 || CTS
|-
| 9 ||
|}

{{Clear}}

File:DE-9F.svg

2023-11-12T04:21:25Z

Benryves: DE-9F connector

== Summary ==
DE-9F connector

Analogue Sensor Ports

2023-11-12T03:31:40Z

Benryves: Added content for analogue sensor ports documentation

== Pinout ==

[[File:DIN-5-Socket-180.svg|frame|right|5-pin 180° DIN socket]]

{|class="wikitable"
! Pin !! Function
|-
| 1 || Analogue signal input
|-
| 2 || GND (0V)
|-
| 3 || VCC (+5V)
|-
| 4 || Sense signal output
|-
| 5 || Vref (+2.55V)
|}

{{Clear}}

== Analogue input ==

The expected analogue input on pin 1 is between 0V and Vref (+2.55V) which will correspond to a reading of between 0 and 255 in the SmartMove software.

Each unit on the analogue input can therefore be said to correspond to 1/100V.

== Sense output ==

To identify the different types of Smart Sensor software on the Smart Box will drive the "Sense" pin 4 high approximately once per second. When the sense pin is driven high sensors should return a voltage corresponding to their sensor type to the Smart Box's analogue input. This can be implemented in your own sensors using an analogue multiplexer/demultiplexer (such as the 4053 IC) to switch between the sensor's output voltage when sense is low and the sensor's ID voltage when sense is high, e.g. produced by a trim pot between 0V and Vref.

=== Sensor IDs ===

There are 32 possible sensor IDs. The ADC reading mentioned in the table below is the minimum value that will cause the Smart Move software to identify a particular sensor, for example a humidity sensor can be identified with an ADC reading between 157 and 164.

Note that Smart Move 1.16 and Smart Move 1.18 have some different names for some sensors. If a space is left blank in the table then the sensor is treated as present but is labelled "SENSORA" to "SENSORD" instead of being renamed according to the sensor type.

{|class="wikitable"
!ADC!!Smart Move 1.16!!Smart Move 1.18
|-
|0||''No sensor''||''No sensor''
|-
|5||mT||
|-
|13||mm||Temp
|-
|21||No sensor||No sensor
|-
|29||No sensor||No sensor
|-
|37||Temp||Volts
|-
|45||Temp||Temp
|-
|53||mA||Volts
|-
|61||Sound||Temp
|-
|69||Sound||Sound
|-
|77||Sound||PH
|-
|85||Pulse||
|-
|93||Position||Position
|-
|101|| ||
|-
|109|| ||
|-
|117|| ||
|-
|125||Light||Light
|-
|133|| ||
|-
|141|| ||
|-
|149|| ||
|-
|157||Humidity||Humidity
|-
|165|| ||Sound
|-
|173|| ||Light
|-
|181||Pressure||Sound
|-
|189|| ||
|-
|197||PH||Atmos
|-
|205|| ||Light
|-
|213|| ||User
|-
|221||Adaptor||Adaptor
|-
|229||Lux||Temp
|-
|237||Volts||LGate
|-
|245||Wind||
|-
|253||Temp||Temp
|}

File:DIN-5-Socket-180.svg

2023-11-12T03:03:25Z

Benryves:

5-pin DIN socket (180°)

SmartBox AlbertLink

2023-11-12T00:15:54Z

Benryves: Converted plaintext documentation to markdown

AlbertLink Link Protocol (Release 11)

== Startup ==

After AL has been downloaded and called the first thing back will be a engine release number (one byte), and known setup flags (one byte) which you should check that the "new" flags you want are set. If the engine number is wrong or the setup flags you want aren't set then send a 0 and AlbertLink will quit itself, else send ANYTHING but a 0. Then send your setup flags (one byte), which will engage the various "new" options.

ie:

{|
| send jobcode for AlbertLink || → ||
|-
| || ← || engine number
|-
|-
| || ← || known setup flags
|-
| flag for continue or not || → ||
|-
| setup flags wanted || ← ||
|}

== Setup Flags ==

The 8 setup flags are setup as such:

{|class="wikitable"
! bit !! if set
|-
| 0 || use new trace system
|-
| 1 || enable procedure/label change checking
|-
| 2 || enable custom commands
|-
| 3 || enable prompt
|-
| 4 || shit computer
|-
| 5 || enable "get" line count
|}

== Idle ==

At this point the system is idling, both ends are waiting to originate a "event" or receive one.

The remote end should check the serial port as often as possible, if it detects a byte then it should read it, check it is in range, and transmit a 0 (byte) back, then it should do one of the following "event" types according to the byte it received:

=== File ===

1 +byte +string

* byte = channel reference (1 to 10)
* string = file name
* the file should then be opened and a FileBack event made or a Error event, to signal a error

=== Close ===

2 +byte

* byte = channel reference

=== Store ===

3 +byte +data (terminated by NUL)

* byte = channel reference
* data = data to put to file

=== Trace ===

==== Old ====

4 +string

* string = string to print

==== New ====

4 +string +double byte

* string = procedure name
* double byte = line number

Return: byte
* byte = flag
*: 0, no stepping
*: 1, wait for tracecont

=== Print ===

5 +[characters terminated by NUL, CR expand to CRLF]

* do not CRLF after this, keep cursor position

=== Error ===

6 +string +string2 +string3 (to change)

* string = procedure name (blank if from cmd line)
* string2 = error
* string3 = line containing error (blank if from cmd line)

=== Ask ===

7 +byte

* byte = 'S', 'N' or 'T' (input type)

Return
* use AskBack to return input string

=== Inkey ===

8

Return: byte
* 0 -> no key
* #0 -> key value

=== Cmd ===

9

* this means that command mode is ready

=== Build ===

10 +string

* string = proc to edit

=== Edit ===

11 +string

* string = proc to edit

=== Quit ===

12

* user has typed QUIT, use Quit to quit system

=== TraceFl ===

13 +byte

* byte = trace flag (0 -> off, #0 -> on)

=== Load ===

14 +string

* string = filename
* use Put
* use Error for filing errors
* string can be blank

=== Save ===

15 +string +string2

* string = filename
* string2 = procedure to save (or blank for all)
* use Error for filing errors
* use Get/List to get procedures

=== Control ===

16 +byte

* byte = control parameter, if out of range, return 0 and then use Error

Return: byte
* byte = value of control option

=== Rtc ===

17

Return: byte +byte2 +byte3 +byte4
* byte = hours
* byte2 = minutes
* byte3 = seconds
* byte4 = centiseconds

Cause Error AFTER returning 0 for all if not supported.

=== Printer ===

18

* as Print

=== Altered ===

19 +byte

* byte = flag
*: bit 0 : procedure list changed
*: bit 1 : labels changed

when you get this you should use List and/or ReadLabels to update yourself

=== Custom ===

20 +data (NUL terminated)

=== Custom2 ===

21 +data (NUL terminated)

=== Customfn ===

22 +string

Return : byte
* byte = fn value

=== Prompt ===

23 +string

* string = prompt string

NB: "string" is a group of characters terminated by CR.

Any other codes should be ignored.

== Remote "events" ==

The remote end also has "events" which it can originate, to start an event, transmit the "event" code and wait until you receive a 0 (byte), ignore all other bytes received (the remote end has priority) and then you can transmit any other bytes needed:

=== Setup ===

1 +byte

* byte = setup byte
* as startup setup flag

=== List ===

2

Return [string .....] until string is blank

* this returns a list of procedures terminated by a blank

=== NameCode ===

3 +string

* '''NB''' doesn't return normal link 0 acknowledge.
* Emulates the normal OS NameCode, quiting AlbertLink if the remote doesn't try to check for AlbertLink and going out of sleep if it does try for AlbertLink

=== Get ===

4 +byte +string

* byte = flag
*: 0 : do not use labels
*: 1 : use labels
*: 255 : use LBLS setting

==== Old ====

Return byte:
* 0 → no such procedure else procedure terminated by 0ffh

==== New ====

Return:
* byte = 0 -> no such procedure
* 1 +byte2 +byte3 +procedure → procedure found

byte2/3 is number of lines in procedure

=== Put ===

5 +string +[procedure strings terminated by 0ffh]

Return: byte
* 0 → ok
* 1 → bad name
* 2 → no room
* 3 → bad data

=== Escape ===

6

* causes escape condition

=== Quit ===

7

* causes AlbertLink to quit

=== Cmd ===

8 +string

* performs a raw command, use only after flagged cmd ready else any running procedure will be stopped

=== GetPorts ===

9

Return

* byte = run mode (1 = running procedure)
* byte = inputs
* byte = outputs
* byte = motors
* byte = adc 1
* byte = adc 2
* byte = adc 3
* byte = adc 4
* byte = clock (hours)
* byte = clock
* byte = clock
* byte = clock (cs)

=== GetPS ===

10

Return
* data as GetPorts
* byte = sensor a id
* byte = sensor b id
* byte = sensor c id
* byte = sensor d id

Perform once a second or so to re-check the sensors

=== SteadyLine ===

11 +byte +string

* byte = flag
*: 0 : do not use labels
*: 1 : use labels
*: 255 : use LBLS setting

Return string
* expanded line

use in editor to expanded abbreviated commands

=== TraceFl ===

12 +byte
* byte = new trace setting and causes Trace "events"

=== SetPort ===

13 +byte +byte2

* byte = bits to set
* byte2 = bits to mask

=== Error ===

14 +string

* string = error to cause

=== Version ===

15

Return string
* version string

=== Sleep ===

16

causes AlbertLink to sleep the remote link, waking up with a normal AlbertLink startup

=== CheckSensors ===

17

Return

* byte = sensor a id
* byte = sensor b id
* byte = sensor c id
* byte = sensor d id

=== AskBack ===

18 +string

* string = input line

=== ReadLabels ===

19

Return [+string1 (+string2) .......]
* string1 = source label
* string2 = label (not sent if string1 is blank)
* string2 terminated by 0 for hard label and 128 for soft label
* end of list terminated by string1 being blank

=== WriteLabel ===

20 +string1 +string2 +byte

* string1 = source label
* string2 = label
* byte = flag
*: 0, hard label
*: 1, soft label

Return byte

* byte = flag
*: 0, okay
*: 1, bad source label
*: 2, bad label
*: 3, label too long
*: 4, label exists as a procedure
*: 5, can't overwrite hard label with a soft label

=== FreeMem ===

21

Return byte +byte2
* byte/2 = free memory

=== TraceCont ===

22

This causes procedure execution to continue from a stopped trace

=== Clock ===

23 +byte

* byte = flag
*: 0, stop clock
*: 1, start clock
*: 2, reset clock

=== PromptBack ===

24

Send this when the user has clicked on the "prompt"

=== FileBack ===

25 +byte

* byte = flag
*: 0, cannot open file
*: 1, file opened

Used in reply to File

Print, Trace, SteadyLine, Get and Error surround any tokens with 1 to start token and 2 to finish token. Put and SteadyLine will remove them automatically before processing.

SmartBox JobList

2023-11-11T23:52:03Z

Benryves: /* OS_CALLOS */ Converted plaintext documentation to markdown

OS 4 - 14.02.00

== 0 Blank ==

Does nothing

{|class="calltable"
|Send||
* Byte 0 = 0
|-
|Returns||
Nothing
|}

== 1 Version ==

Read the operating system version number

{|class="calltable"
|Send||
* Byte 0 = 1
|-
|Returns||
* Byte 0 = version number - low byte
* Byte 1 = version number - high byte
|-
|Commments||
Divide by 1000 to get the version number, eg. version 1.023 would be returned as 1023
|}

== 2 Reset ==

Reset Smart Box

{|class="calltable"
|Send||
* Byte 0 = 2
* Byte 1 = 254 or 255
|-
|Returns||
Nothing
|-
|Commments||
Reset SmartBox from the host micro. Sending a 254 performs a soft reset (same as pressing reset), sending 255 does a reset (clears battery back RAM). Before sending codes create a small delay while SmartBox resets various parts of hardware
|}

== 3 NameCode ==

To obtain the operating system call number where the name is known

{|class="calltable"
|Send||
* Byte 0 = 3
* Byte 1 - n = ASCII characters of OS call name
* Byte n+1 = 13
|-
|Returns||
* Byte 0 = Operating system call number
|}

== 4 CodeName ==

To obtain the name associated with an operating system call

{|class="calltable"
|Send||
* Byte 0 = 4
* Byte 1 = OS call number
|-
|Returns||
* StringCR = OS call name
|}

== 5 MultipleSetup ==

To set the values that will be returned by MultipleRead

{|class="calltable"
|Send||
* Byte 0 = 5
* Byte 1 = Analogue channel 1
* Byte 2 = Analogue channel 2
* Byte 3 = Analogue channel 3
* Byte 4 = Analogue channel 4
* Byte 5 = Digitial inputs
* Byte 6 = Digital outputs
* Byte 7 = Motor outputs
|-
|Returns||
Nothing
|-
|Commments||
This sets up the readings which will be returned when the call MultipleRead is made. If a byte = 1 the corresponding port will be returned, 0 = value not returned
|}

== 6 MultipleRead ==

Returns multiple readings as defined using MultipleSetup

{|class="calltable"
|Send||
* Byte 0 = 6
|-
|Returns||
* Bytes as defined by MultipleSetup
|-
|Commments||
This call returns readings from a number of ports as
defined by MultipleSetup
|}

== 7 MultipleServer ==

Constantly returns multiple readings as defined using MultipleSetup

{|class="calltable"
|Send||
* Byte 0 = 7
|-
|Returns||
* Bytes as defined by MultipleSetup
|-
|Commments||
This call is similar to MultipleRead but continues to
return readings until SmartBox receives the byte 123
|}

== 8 IdentSystem ==
Read System Information

{|class="calltable"
|Send||
Nothing
|-
|Returns||
* Byte 0 = table length
* Word = VIA
* Word = ACIA
* Word = ADC
* Word = AUX.PORT
* Word = jobs.status
* Word = jobin.buf
* Word = jobout.buf
* Byte = Processor ident
* Word = OS version number
* Byte = Hardware version number
* String10 = Name, padded to 10 chars
* Byte = Number of inputs
* Byte = Number of outputs
* Byte = Number of motors
* Byte = Number of analogues
* Byte = BBR support
* Byte = Short support
* Byte = Printer support
* Byte = Keypad support
* Byte = LCD x dim/support
* Byte = LCD y dim
|-
|OS Release||
3,4
|}

== 9 Credits ==

Returns the copyright string

{|class="calltable"
|Send||
* Byte 0 = 9
|-
|Returns||
* StringNUL = Copyright string
|-
|Commments||
This call returns the copyright message and OS details
|}

== 10 WriteMotors ==

Writes a byte to the motor drivers

{|class="calltable"
|Send||
* Byte 0 = 10
* Byte 1 = value to write
|-
|Returns||
Nothing
|-
|Commments||
Each of the four motor outputs has two bits encoded into this value, bits 0 and 1 are for motor a, bytes 2 and 3 are for motor b, bits 4 and 5 are for motor c and bits 6 and 7 are for motor d, setting both bits to 0 will stop the motor, setting the low bit high and high bit low will make the motor go forward and setting the high bit high and the low bit low will make it go backwards. Using this call automatically stops all pulsing of motors
|}

== 11 ReadMotors ==

Read the state of the motor drivers

{|class="calltable"
|Send||
* Byte 0 = 11
|-
|Returns||
* Byte 0 = value read from the motor drivers
|-
|Commments||
The value returned is the same value as what would be sent to WriteMotors
|}

== 12 MotorForward ==

Switch a motor on

{|class="calltable"
|Send||
* Byte 0 = 12
* Byte 1 = motor number (1 to 4)
|-
|Returns||
Nothing
|-
|Commments||
This makes the appropriate motor go forward. Using this call automatically cancels the pulsing for the appropriate motor
|}

== 13 MotorReverse ==

Switch a motor on with reverse polarity

{|class="calltable"
|Send||
* Byte 0 = 13
* Byte 1 = motor number (1 to 4)
|-
|Returns||
Nothing
|-
|Commments||
This makes the appropriate motor go backward. Using this call automatically cancels the pulsing for the appropriate motor
|}

== 14 MotorHalt ==

Switch a motor off

{|class="calltable"
|Send||
* Byte 0 = 14
* Byte 1 = motor number (1 to 4)
|-
|Returns||
Nothing
|-
|Commments||
This makes the appropriate motor stop. Using this call automatically cancels the pulsing for the appropriate motor
|}

== 15 MotorPower ==

Pulse a motor outputs to vary speed

{|class="calltable"
|Send||
* Byte 0 = 15
* Byte 1 = motor number (1 to 4)
* Byte 2 = on time
* Byte 3 = off time
|-
|Returns||
Nothing
|-
|Commments||
This pulses the appropriate motor at a rate determined by the on/off time (in centiseconds) specified, alternating the motor between the state at which it was last defined (Forward or Reverse) and Halt
|}

== 16 PatchMF ==

Same as MotorForward

{|class="calltable"
|OS Release||
3,4
|}

== 17 MotorVoltage ==

Set voltage for motor outputs

{|class="calltable"
|Send||
* Byte 0 = voltage (0 to 3)
|-
|Returns||
Nothing
|-
|Notes||
Voltage values are 0 (0v), 1 (6v), 2 (9v), 3 (12v). 
''Setting a voltage of 0 will also switch '''outputs''' to 0v''
|-
|Commments||
This sets the actual voltage supplied to the motor outputs
|-
|OS Release||
4
|}

== 20 WriteOutputs ==

Write a 8 bit value to the digital output port

{|class="calltable"
|Send||
* Byte 0 = 20
* Byte 1 = byte to be written to the port
|-
|Returns||
Nothing
|-
|Commments||
Using this call automatically cancels all pulsing on the output port
|}

== 21 OutputPower ==

Vary the power by pulsing individual output lines

{|class="calltable"
|Send||
* Byte 0 = 21
* Byte 1 = bit number (0 to 7)
* Byte 2 = on time
* Byte 3 = off time
|-
|Commments||
This pulses the appropriate output line at a rate determined by the on/off time (in centiseconds) specified, alternating the output line between on and off
|}

== 22 GetSensors ==

To read the type of sensors connected to the analogue sensors

{|class="calltable"
|Send||
* Byte 0 = 22
|-
|Returns||
* Byte 1 = type of sensor connected to sensor A
* Byte 2 = type of sensor connected to sensor B
* Byte 3 = type of sensor connected to sensor C
* Byte 4 = type of sensor connected to sensor D
|-
|Commments||
This returns the sensor types connected to the analogue sensors that were returned from the last time they were checked. A sensor type of 0 means no sensor
|}

== 23 CheckSensors ==

To check the type of sensors connected to the analogue sensors

{|class="calltable"
|Send||
* Byte 0 = 23
|-
|Returns||
* Byte 1 = type of sensor connected to sensor A
* Byte 2 = type of sensor connected to sensor B
* Byte 3 = type of sensor connected to sensor C
* Byte 4 = type of sensor connected to sensor D
|-
|Commments||
This does an immediate check of the sensor types connected to the analogue sensors. A sensor type of 0 means no sensor
|}

== 24 WriteSensorTable ==

Write sensor table entry

{|class="calltable"
|Notes||
''Not Implemented''
|-
|OS Release||
3
|}

== 25 ReadSensorTable ==

Read sensor table entry

{|class="calltable"
|Send||
* Byte 0 = entry to read
|-
|Returns||
* Byte 0 = sensor number
* Byte 1 = number of decimal points to display
* Byte 2 = max adc reading
* Byte 3 = reading offset (LSB)
* Byte 4 = reading offset (MSB)
* Byte 5 = multiplication factor (LSB)
* Byte 6 = multiplication factor (MSB)
* Byte 7 = division factor (LSB)
* Byte 8 = division factor (LSB)
* String = full sensor title
* String = abbreviated sensor label
* String = sensor label
* String = sensor units
|-
|Notes||
If byte 0 is &FF then sensor is unknown
|-
|OS Release||
3,4
|}

== 28 SetBitHigh ==

Set individual output line(s) high

{|class="calltable"
|Send||
* Byte 0 = 28
* Byte 1 = byte determining which lines will be set
|-
|Returns||
Nothing
|-
|Commments||
A bit set in the byte sent will set the corresponding output line high
|}

== 29 SetBitLow ==

Set individual output line(s) low

{|class="calltable"
|Send||
* Byte 0 = 29
* Byte 1 = byte determining which lines will be unset
|-
|Returns||
Nothing
|-
|Commments||
A bit set in the byte sent will set the corresponding output line low
|}

== 30 ReadADCReg ==

To read a ADC register

{|class="calltable"
|Send||
* Byte 0 = 30
* Byte 1 = register number (0 to 15)
|-
|Returns||
* Byte 0 = value of register
|-
|OS Release||
2
|}

== 31 WriteADCReg ==

To write to a ADC register

{|class="calltable"
|Send||
* Byte 0 = 31
* Byte 1 = register number (0 to 15)
* Byte 2 = value to write
|-
|Returns||
Nothing
|-
|OS Release||
2
|}

== 32 ReadACIAReg ==

To read a ACIA register

{|class="calltable"
|Send||
* Byte 0 = 32
* Byte 1 = register number (0 to 15)
|-
|Returns||
* Byte 0 = value of register
|-
|OS Release||
2
|}

== 33 WriteACIAReg ==

To write to a ACIA register

{|class="calltable"
|Send||
* Byte 0 = 33
* Byte 1 = register number (0 to 15)
* Byte 2 = value to write
|-
|Returns||
Nothing
|-
|OS Release||
2
|}

== 34 ReadVIAReg ==

To read a VIA register

{|class="calltable"
|Send||
* Byte 0 = 34
* Byte 1 = register number (0 to 15)
|-
|Returns||
* Byte 0 = value of register
|-
|OS Release||
2
|}

== 35 WriteVIAReg ==

To write to a VIA register

{|class="calltable"
|Send||
* Byte 0 = 35
* Byte 1 = register number (0 to 15)
* Byte 2 = value to write
|-
|Returns||
Nothing
|-
|OS Release||
2
|}

== 36 SetVIAHigh ==

To set bits in a VIA register

{|class="calltable"
|Send||
* Byte 0 = 36
* Byte 1 = register number (0 to 15)
* Byte 2 = mask
|-
|Returns||
Nothing
|-
|OS Release||
2
|}

== 37 SetVIALow ==

To unset bits in a VIA register

{|class="calltable"
|Send||
* Byte 0 = 37
* Byte 1 = register number (0 to 15)
* Byte 2 = mask
|-
|Returns||
Nothing
|-
|OS Release||
2

|}

== 40 ReadADC ==

Take a reading from a specific ADC channel

{|class="calltable"
|Send||
* Byte 0 = 40
* Byte 1 = channel number (1 to 4)
|-
|Returns||
* For an 8 bit reading:
** Byte 0 = reading from ADC
* For a 16 bit reading:
** Byte 0 = low byte of reading
** Byte 1 = high byte of reading
|-
|Commments||
The value returned will be at the resolution specified by OS calls HighResADC and LowResADC
|}

== 41 ReadADCs ==

Read all the ADC channels

{|class="calltable"
|Send||
* Byte 0 = 41
|-
|Returns||
* For 8 bit readings:
** Byte 0 = reading from channel 1
** Byte 1 = reading from channel 2
** Byte 2 = reading from channel 3
** Byte 3 = reading from channel 4
* For 16 bit readings
** Byte 0 = reading from channel 1 (low byte)
** Byte 1 = reading from channel 1 (high byte)
** Byte 2 = reading from channel 2 (low byte)
** Byte 3 = reading from channel 2 (high byte)
** Byte 4 = reading from channel 3 (low byte)
** Byte 5 = reading from channel 3 (high byte)
** Byte 6 = reading from channel 4 (low byte)
** Byte 7 = reading from channel 4 (high byte)
|}

== 42 ForcedADCRead ==

Force the A to D convertor to make a conversion and return the result

{|class="calltable"
|Send||
* Byte 0 = 42
* Byte 1 = channel number (1 to 4)
|-
|Returns||
* For an 8 bit reading:
** Byte 0 = reading from ADC
* For a 16 bit reading
** Byte 0 = reading from ADC (low byte)
** Byte 1 = reading from ADC (high byte)
|}

== 44 HighResADC ==

Sets the resolution of ADC readings to 16 bit
Subsequent readings will return 2 byte values

{|class="calltable"
|Send||
* Byte 0 = 44
|-
|Returns||
Nothing
|-
|Commments||
For OS 2 readings returned will be only accurate to 10 bits. OS 3,4 provides support for 16 bit readings, but only to an accuracy of 8 bits.
|}

== 45 LowResADC ==

Sets the resolution of ADC readings to 8 bit
Subsequent readings will return single byte values

{|class="calltable"
|Send||
* Byte 0 = 45
|-
|Returns||
Nothing
|}

== 47 ReadResolution ==

Reads the current ADC resolution setting

{|class="calltable"
|Send||
* Byte 0 = 47
|-
|Returns||
* Byte 0 = resolution setting, where:
*: 0 = 8 bit
*: 1 = 16 bit
|}

== 50 DownloadData (OS 2), DownloadData740 (OS 3), DownloadData375 (OS 4) ==

Download data into the SmartBox's memory

{|class="calltable"
|Send||
* Byte 0 = 50
* Byte 1 = start address to write (low byte)
* Byte 2 = start address to write (high byte)
* Byte 3 = length of data (low byte)
* Byte 4 = length of data (high byte)
* Bytes 5 - n = data
|-
|Returns||
Nothing
|}

== 52 UploadData (OS 2), UploadData740 (OS 3), UploadData (OS 4) ==

Upload data from the SmartBox's memory

{|class="calltable"
|Send||
* Byte 0 = 52
* Byte 1 = start address to read (low byte)
* Byte 2 = start address to read (high byte)
* Byte 3 = length of data (low byte)
* Byte 4 = length of data (high byte)
|-
|Returns||
* Byte 0 - n = data
|}

== 54 ExecuteCode (OS 2), ExecuteCode740 (OS 3), ExecuteCode375 (OS 4) ==

Execute machine code held at a specified address

{|class="calltable"
|Send||
* Byte 0 = 54
* Byte 1 = execution address (low byte)
* Byte 2 = execution address (high byte)
* Byte 3 = contents of the A register on entry to the code
* Byte 4 = contents of the X register on entry to the code
* Byte 5 = contents of the Y register on entry to the code
|-
|Returns||
Nothing
|}

== 55 StoreByte (OS 2), StoreByte740 (OS 3), StoreByte375 (OS 4) ==

Store a byte in the SmartBox's RAM

{|class="calltable"
|Send||
* Byte 0 = 55
* Byte 1 = address to write (low byte)
* Byte 2 = address to write (high byte)
* Byte 3 = byte to be stored
|-
|Returns||
Nothing
|}

== 56 ReadByte (OS 2), ReadByte740 (OS 3), ReadByte (OS 4) ==

Read a byte from the SmartBox's RAM

{|class="calltable"
|Send||
* Byte 0 = 56
* Byte 1 = address to read (low byte)
* Byte 2 = address to read (high byte)
|-
|Returns||
* Byte 0 = byte read
|}

== 57 ReadRAMSize ==

Read the amount of RAM with which the SmartBox is fitted

{|class="calltable"
|Send||
* Byte 0 = 57
|-
|Returns||
* Byte 0 = RAM size (low byte)
* Byte 1 = RAM size (high byte)
|-
|OS Release||
2,3
|}

== 59 ExtendCall ==

Call the extended call vector

{|class="calltable"
|Send||
* Byte 0 = 59
|-
|Returns||
* Byte 0 = extension value
|-
|Commments||
This call provides the user with the possibility of adding extra calls to SmartBox easily
|-
|OS Release||
2,3
|}

== 60 SetClock ==

Set the internal clock in SmartBox. This clock only runs while the power in maintained

{|class="calltable"
|Send||
* Byte 0 = 60
* Byte 1 = 1/10 seconds (0 to 9)
* Byte 2 = seconds (0 to 59)
* Byte 3 = minutes (0 to 59)
* Byte 4 = hours (0 to 23)
|-
|Returns||
Nothing
|-
|Commments||
The day value is set to 0
|}

== 61 ReadClock ==

Read the internal clock. On reset the clock will be set to zero

{|class="calltable"
|Send||
* Byte 0 = 61
|-
|Returns||
* Byte 0 = 1/10 seconds
* Byte 1 = seconds
* Byte 2 = minutes
* Byte 3 = hours
* Byte 4 = days
|}

== 62 ReadTopmem ==

Read the current value of TOPMEM

{|class="calltable"
|Send||
* Byte 0 = 62
|-
|Returns||
* Byte 0 = value of TOPMEM (low byte)
* Byte 1 = value of TOPMEM (high byte)
|-
|OS Release||
2,3
|}

== 63 WriteTopmem ==

Write the value of TOPMEM

{|class="calltable"
|Send||
* Byte 0 = 63
* Byte 1 = value of TOPMEM (low byte)
* Byte 2 = value of TOPMEM (high byte)
|-
|Returns||
Nothing
|-
|OS Release||
2,3
|}

== 64 ReadLomem ==

Read the current value of LOMEM

{|class="calltable"
|Send||
* Byte 0 = 64
|-
|Returns||
* Byte 0 = value of LOMEM (low byte)
* Byte 1 = value of LOMEM (high byte)
|-
|OS Release||
2,3
|}

== 65 WriteLomem ==

Write the value of LOMEM

{|class="calltable"
|Send||
* Byte 0 = 65
* Byte 1 = value of LOMEM (low byte)
* Byte 2 = value of LOMEM (high byte)
|-
|Returns||
Nothing
|-
|OS Release||
2,3
|}

== 66 ReadHimem ==

Read the current value of HIMEM

{|class="calltable"
|Send||
* Byte 0 = 66
|-
|Returns||
* Byte 0 = value of HIMEM (low byte)
* Byte 1 = value of HIMEM (high byte)
|-
|OS Release||
2,3
|}

== 67 WriteHimem ==

Write the value of HIMEM

{|class="calltable"
|Send||
* Byte 0 = 67
* Byte 1 = value of HIMEM (low byte)
* Byte 2 = value of HIMEM (high byte)
|-
|Returns||
Nothing
|-
|OS Release||
2,3
|}

== 70 WritePrinter ==

Write printer port (no handshaking)

{|class="calltable"
|Send||
* Byte 0 = byte to write
|-
|Returns||
Nothing
|-
|OS Release||
3
|}

== 71 ReadPrinter ==

Read printer port

{|class="calltable"
|Send||
Nothing
|-
|Returns||
* Byte 0 = printer port value
|-
|OS Release||
3
|}

== 72 PrintChar ==

Send a character to printer port

{|class="calltable"
|Send||
* Byte 0 = char
|-
|Returns||
Nothing
|-
|OS Release||
3
|}

== 73 PrintStreamZ ==

Send a stream of characters to the printer port

{|class="calltable"
|Send||
* StringNUL = string to print
|-
|Returns||
Nothing
|-
|OS Release||
3
|}

== 74 PrintStream ==

Send a stream of characters to the printer port

{|class="calltable"
|Send||
* Byte 0 = number of bytes to send (LSB)
* Byte 1 = number of bytes to send (MSB)
* Bytes = stream of characters to print
|-
|Returns||
Nothing
|-
|OS Release||
3
|}

== 75 PrintServer ==

Echo all characters to printer port

{|class="calltable"
|Notes||
No exit
|-
|OS Release||
3

|}

== 80 WriteRTCReg ==

Write a RTC register

{|class="calltable"
|Send||
* Byte 0 = register
* Byte 1 = value
|-
|Returns||
Nothing
|-
|OS Release||
3
|}

== 81 ReadRTCReg ==

Read a RTC register

{|class="calltable"
|Send||
* Byte 0 = register
|-
|Returns||
* Byte 0 = value
|-
|OS Release||
3
|}

== 82 WriteRTC ==

Writes RTC as a string

{|class="calltable"
|Send||
* StringCR = RTC time
|-
|Returns||
Nothing
|-
|Notes||
''Not currently implemented'' 
Time is represented as DDD,dd mmm yyyy.hh:mm:ss
* DDD is 3 character day (Mon, Tue, Wed, Thu, Fri, Sat, Sun)
* dd is day of month
* mmm is month
* yyyy is year
* hh is hours
* mm is minutes
* ss is seconds
|-
|OS Release||
3
|}

== 83 ReadRTC ==

Reads RTC as a string

{|class="calltable"
|Send||
Nothing
|-
|Returns||
* StringCR = RTC time
|-
|Notes||
Time is represented as DDD,dd mmm yyyy.hh:mm:ss
* DDD is 3 character day (Mon, Tue, Wed, Thu, Fri, Sat, Sun)
* dd is day of month
* mmm is month
* yyyy is year
* hh is hours
* mm is minutes
* ss is seconds
|-
|OS Release||
3
|}

== 84 WriteRTCbcd ==

Writes all 7 RTC time registers

{|class="calltable"
|Send||
* Byte 0 = seconds
* Byte 1 = minutes
* Byte 2 = hours
* Byte 3 = date
* Byte 4 = month
* Byte 5 = day
* Byte 6 = year
|-
|Returns||
Nothing
|-
|Notes||
All values are represented in BCD
* Years below 80 (&80 in BCD) signify 20xx
* Day starts (0) from Monday
|-
|OS Release||
3
|}

== 85 ReadRTCbcd ==

Reads all 7 RTC time registers

{|class="calltable"
|Send||
Nothing
|-
|Returns||
* Byte 0 = seconds
* Byte 1 = minutes
* Byte 2 = hours
* Byte 3 = date
* Byte 4 = month
* Byte 5 = day
* Byte 6 = year
|-
|Notes||
All values are represented in BCD
* Years below 80 (&80 in BCD) signify 20xx
* Day starts (0) from Monday
|-
|OS Release||
3
|}

== 90 ReadInputs ==

Reads a byte from the digital inputs port

{|class="calltable"
|Send||
* Byte 0 = 90
|-
|Returns||
* Byte 0 = byte read from the digital inputs port
|}

== 91 ReadBit ==

Reads a bit from the digital inputs port

{|class="calltable"
|Send||
* Byte 0 = 91
* Byte 1 = byte to read (0 to 7)
|-
|Returns||
* Byte 0 = bit read from the digital inputs port
|-
|Commments||
Reads an individual sensor from the digital inputs port
|}

== 92 ReadOutputs ==

Reads a byte from the digital outputs port

{|class="calltable"
|Send||
* Byte 0 = 92
|-
|Returns||
* Byte 0 = byte read from the digital outputs port
|-
|Notes||
This reads the soft copy of the last written byte
|-
|OS Release||
3,4
|}

== 93 CountReset ==

Resets input port counter(s)

{|class="calltable"
|Send||
* Byte 0 = 93
* Byte 1 = bit masks for counters to reset
|-
|OS Release||
4
|}

== 94 CountRead ==

Reads input port counter(s)

{|class="calltable"
|Send||
* Byte 0 = 94
* Byte 1 = counter to read (0 to 7) or 255 for all
|-
|Returns||
* Byte 0 = value of counter (LSB)
* Byte 1 = value of counter (MSB)
* Byte n = value of counter (LSB)
* Byte n+1 = value of counter (MSB)
|-
|Notes||
Counter values return 65535 (-1) from box reset, or max count
|-
|OS Release||
4
|}

== 98 InsightDriver ==

Starts the internal Insight software

{|class="calltable"
|OS Release||
3
|}

== 99 DataApp ==

Starts the internal DataApp software

{|class="calltable"
|OS Release||
3
|}

== 100 WriteLCDReg ==

Write LCD Register

{|class="calltable"
|Send||
* Byte 0 = register number
* Byte 1 = register value
|-
|Returns||
Nothing
|-
|OS Release||
3
|}

== 101 ReadLCDReg ==

Read LCD Register

{|class="calltable"
|Send||
* Byte 0 = register number
|-
|Returns||
* Byte 0 = register value
|-
|OS Release||
3
|}

== 102 LCDChar ==

Send a character to the LCD display driver

{|class="calltable"
|Send||
* Byte 0 = char
|-
|Returns||
Nothing
|-
|OS Release||
3
|}

== 103 LCDStreamZ ==

Send a stream of characters to the LCD display driver

{|class="calltable"
|Send||
* StringNUL = string to display
|-
|Returns||
Nothing
|-
|OS Release||
3
|}

== 104 LCDStream ==

Send a stream of characters to the LCD display driver

{|class="calltable"
|Send||
* Byte 0 = number of bytes to send (LSB)
* Byte 1 = number of bytes to send (MSB)
* Bytes = stream of characters to display
|-
|Returns||
Nothing
|-
|OS Release||
3

|}

== 110 ReadKeypad ==

Reads the raw state of the keypad

{|class="calltable"
|Send||
Nothing
|-
|Returns||
* Byte 0 = current keypad reading bitstate
|-
|OS Release||
3
|}

== 111 ReadKeypadPress ==

Reads the processed state of the keypad

{|class="calltable"
|Send||
Nothing
|-
|Returns||
* Byte 0 = current keypad press bitstate
|-
|OS Release||
3
|}

SmartBox OS

2023-11-04T17:44:44Z

Benryves: /* Changelog */ Put changelog in table

== Documentation for SmartBox OS 2.066 ==

The term JobCall is the concept of the routine itself, as opposed to
JobName (which is the actual name associated with it (eg. NameCode)) and
JobCode (which is the actual number associated with it (eg. 3)).

The term controller means the SmartBox, or any other incarnation
which may appear in future time !

The term OS means the controllers' Operating System.

== Preview ==

There are a number of reasons why using Machine Code on the
controller is more desirable than using the various JobCalls via the serial
link. One reason is speed, if the task which needs to be performed, has to
be performed very quickly (more quickly than can be achieved via the serial
link at least), then some code must be written to work in the controller
itself to achieve this sort of speed. If the task required is to be a
"background" task (ie. a task which may happen while other "things" carry
on as normal, like a change of state of a particular port) then it is far
easier to let the controller do all the work, maybe under interupts, than
continuously poll the controller checking the state of various things.
Another reason may be that you would like to add another JobCall to the OS,
extending the calls available to external applications (and the user at the
same time), without the user having to write the code himself to achieve the
aim. For advanced users, there is also the ablity to alter the way the OS
does various things and to have the controller in their "power", for
dedicated tasks etc.

One advantage of writing IN the controller is that that "function"
is available to any computer using the serial link, and is thus not fixed to
one computer type or even a computer at all, where the controller is used
free running, doing a particular task which doesn't need the intervention of
the user's own computer.

== Call types ==

There are three different types of machine code routines which can
be added to the controller. Each one is suited to a more advanced level
than the other, which also relates to the amount of work needed to actually
get the routine working ! The three levels are such:

=== Simple stand alone routine ===

Here the routine is just the routine
itself with no supporting code (ie. code to integrate with the rest of the
OS). It has to be called directly, by use of the ExecuteCode JobCall, thus
it usually resides at a fixed address and obviously does not offer the user
friendly way of accessing itself like there is with normal OS calls.

=== Extended JobCall ===

There is one JobCall in the OS (ExtendJob)
which can call various routines residing in memory, each one is identified
by a 8 bit number. The disadvantages of this way is that the call hasn't
got it's own JobName/JobCode and needs the extra byte to identify itself.
This is ideal for the quick routine which the user would like to add for
himself without having to resort to the extra code needed for the full
JobCode implementation.

=== Full JobCall ===

This is where the routine can define itself one
(or a number) of JobNames/JobCodes, it can integrate itself into an
extension of the OS in a complete way. The disadvantage is that extra
coding is needed to deal with the various OS calls it has to service and
that extra work is needed to produce a suitable file to place in the
controller.

Normally with most processors, including the 65c02, the machine code
produced is produced for a fixed memory address, and it cannot be made to
run in a different place in memory unless extra work is carried out by the
user, or at least a combination of the user and the OS. For the controller
this is a very severe disadvantage as most extensions are downloaded as
"modules" and to optimise memory a system has to be devised to enable
routines to be placed anywhere in memory, thus allowing no memory to be
wasted. In the OS there is a routine to do just this, though it does need
some help. A special version of the users code has to be developed, or
rather it has to be "processed" to add extra information on the end. Extra
code is needed to set up a few pointers and call the OS routine to relocate.
See later.

== Memory ==

The first 256 bytes of memory are somewhat special, most zero page
locations are reserved for use by the OS:

{|class="wikitable"
|-
|&00-&14||General workspace, used to pass parameters to some OS routines, can also be used by other routines DURING their execution.
|-
|&15-&6F||Reserved
|-
|&70-&9F||Available to the user
|-
|&A0||Accumulator store for irqs (irq_A)
|-
|&A1-&A2||Two byte counter, decremented at 100hz, useful for temporary timing purposes (fcount)
|-
|&A3||RAM size, high byte of RAM size of machine, ie. for 32k this will be &80 (RAM_size)
|-
|&A4-&AF||Reserved
|-
|&B0-&FF||Used by the OS
|-
|}

The rest of memory space is used for the processors stack, OS'
buffers, tables, vectors and, of course, the user available memory.

A breakdown of the rest of memory:

* &100 to &1FF is the 65c02's stack.
* &200-&2FF is used by the OS for various system functions and also contains the vector table, more on that later.
* &300-&3FF is the serial input buffer.
* &400-&47F is the internal job code call output buffer. (jobout_buf)
* &480-&4FF is the internal job code call input buffer. (jobin_buf)
* &500-&5FF is the job status table.
* &600 to the end of RAM memory is for the user. The user should not assume what the top of AVAILABLE memory is and use the system variable HIMEM.

In the controller the maximum limit of RAM is &8000 (which is 32k),
from &8000-&DFFF lies the memory mapped hardware, from &E000 to &FFF9 lies
the OS and from &FFFA to &FFFF lies the 65c02 vectors.

So the user has his own limits of free memory. The lowest limit is
called LOMEM and the highest limit is called HIMEM, everything between these
boundaries is termed "available" for use by anyone, the user or the OS.

Anyone can also claim memory, thus making private to them and not allowing
anyone else to use it. You do this by altering the value of LOMEM, HIMEM
should not be moved. Of course anyone claiming memory should first check
that there is enough memory available for the amount they want to claim for.
To take a common example, a downloadable routine which installs itself as a
extension routine, The download routine will first of all read LOMEM, read
HIMEM, check there is enough memory for the routine, download it to LOMEM
and call it, the downloaded routine will then relocate itself and alter
LOMEM so it is protected.

There is one other memory limit, this is called TOPMEM, this is the
absolute top limit of RAM, HIMEM will normally equal TOPMEM, but a future OS
may alter HIMEM to below TOPMEM. TOPMEM should be ignored ideally, and
HIMEM used.

== OS Calls ==

The OS has calls (ie. a jump instruction which you call, which
then calls, via a RAM vector, a routine in the OS) setup near the top of
memory, through these calls you do everything associated with the
controller. The calls are are such:

* OS_PRINTER at address &FFB9
* OS_CALLOS at address &FFBC
* OS_SENDBYTE at address &FFBF
* OS_READBYTE at address &FFC2
* OS_SENDJOB at address &FFC5
* OS_READJOB at address &FFC8
* OS_DECODEJOB at address &FFCB

The address is the one to call for the particular routine.

* OS_PRINTER is reserved for future use.
* OS_CALLOS calls upon the OS to do various things internally.
* OS_SENDBYTE sends a byte out of the serial port.
* OS_READBYTE reads a byte from the serial port.
* OS_SENDJOB 'sends' a value to the JobCall caller.
* OS_READJOB 'reads' a value from the JobCalls caller.
* OS_DECODEJOB decodes the Job number held in A and acts on it.

Note none of these things should be used in interupt routines,
except OS_CALLOS, of any sort, except if YOU know what state the machine is
in and WHY.

=== OS_READBYTE and OS_SENDBYTE: Serial Port ===

The serial port on the controller is currently based on the 6850
UART, this need not bother you as the OS deals with the thing entirely by
itself. The chip is setup by the OS to always have a word format of 8n1 and
a baud rate of 9600, this translates to 960cps. The 6850 has two divide
rates for the baud rate, the OS only uses one, using the other one is beyond
the scope of this document and shouldn't be neccessary to use.

Only receive interupts are used, transmission of characters is done
on a polled basis.

As said, there are two calls OS_READBYTE and OS_SENDBYTE.

==== OS_READBYTE ====

OS_READBYTE tests the serial input buffer and returns the character (if any
in the A register), the c flag states whether there was a character
returned.

{|class="calltable"
|Entry||
A, X, Y, c, z = undefined
|-
|Exit||
* X, Y preserved
* z = undefined
* if c = 1 (no character received)
*: A is preserved
* if c = 0 (character received)
*: A = character received
|}

==== OS_SENDBYTE ====

OS_SENDBYTE sends the character in the A register out of the serial
port, taking into consideration flow control etc.

{|class="calltable"
|Entry||
* A = character to send
* X, Y, c, z = undefined
|-
|Exit||
* A, X, Y, c is preserved
* z = undefined
|}

=== OS_READJOB and OS_SENDJOB ===

To send/receive data from the user (either internally or via the
serial port) you call OS_SENDJOB/OS_READJOB for the next byte. If your
JobCall requires dynamic use of data, ie. interaction, then a check of the
enviroment should be done to check the call came from the serial port. One
example of this is the OS JobCall MultipleServer, which requires dynamic use
of sending a stream of data until a reaction from the user to tell it to
stop.

==== OS_READJOB: Read job value from the user ====

{|class="calltable"
|Entry||
* A, X, Y, c, z = undefined
|-
|Exit||
* A = byte read
* X, Y is preserved
* c, z = undefined
|-
|Note||
When coming from the serial port it waits for a character to be received, if you are doing a serial only call and wish to have a loop checking for a character from the user while doing "your own thing", then OS_READBYTE should be used. For internal calls this reads data out of jobin_buf.
|}

==== OS_SENDJOB: Give a job value back to the user ====

{|class="calltable"
|Entry||
* A = byte to give
* X, Y, c, z = undefined
|-
|Exit||
* A, X, Y is preserved
* c, z = undefined
|-
|Note||
This will send either out to the serial port or place a byte in jobout_buf.
For internal calls this stores the value in jobout_buf, which is allocated 128 bytes, no bound checking is done so sending more than 128 bytes to OS_SENDJOB will cause corruption of some memory.
|}

=== OS_DECODEJOB ===

JobCalls in practise are really only used by the user, JobCalls
tend not to call other calls at all, infact you shouldn't really call
another call unless you were called from the serial port. If you do need to
call another JobCall then you do it like this; with each call you have
associated with it a number, and the call might require some data or give
some data back or both. With the serial port this is simple, you just send
data down and receive data as it is produced. You can't do this with
internal calls, and some calls will not let you call them from inside the
controller, you HAVE to call them from outside. But for the ones which do
let you, you do it with two data blocks, one for input TO the call and one
for output FROM the call. These are setup in a position in memory
(jobin_buf and jobout_buf), each one has a maximum of 128 bytes and this
should not be overflowed (OS_READJOB and OS_SENDJOB do NOT do any bound
checking). So to start with you place in the input block the data you want
to give the call (if any), call it, and then act on the data in the output
block (if any). The OS call OS_DECODEJOB is the one which actually calls
the JobCall handler and eventually the actual routine, you tell the JobCall
handler which call you want by placing the JobCode in the A register.

So for OS_DECODEJOB:

{|class="calltable"
|Entry||
* A = JobCode
* X, Y, c, z = undefined
* jobin_buf should contain any input data
|-
|Exit||
* A = flag
* X = number of bytes given back by routine
* Y = undefined
* c = status, if set JobCall does not exist
* z = status, if set JobCall cannot be called internally
* jobout_buf contains any data sent from routine
|}

A typical example would be:

<nowiki> LDA #readhimem ; JobCode for ReadHimem
JSR OS_DECODEJOB ; Call the JobCall handler
LDX jobout_buf ; Read HIMEM from buffer LSB
LDY jobout_buf+1 ; Read HIMEM from buffer MSB
STX jobin_buf ; Place LSB in input buffer
STY jobin_buf+1 ; Place MSB in input buffer
LDA #writelomem ; JobCode for WriteLomem
JSR OS_DECODEJOB ; Call the JobCall handler</nowiki>

which would read HIMEM, and then write LOMEM to be the same value, leaving
no spare memory left.

The reason why you should not call an internal call from another
internal call is that the same buffers (jobin_buf and jobout_buf) would be
used for both calls, causing conflict between the two calls, or rather to
the originator of the primary call ! The only time it would be safe if is
if you have already got all the data you want from jobin_buf and haven't
placed any in the jobout_buf (it would be lost if you had done).

=== 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.
|}

=== OS_PRINTER: Place a character in the printer buffer ===

{|class="calltable"
|Entry||
* A = character to send
* X, Y, c, z = undefined
|-
|Exit||
* A, X, Y is preserved
* if c = 0 (printed)
*: The printer is on and the character was inserted
* if c = 1 (not printed)
*: The printer is off and the character was forgotten
* z = undefined
|-
|Note||
The character goes into the printer buffer and will be
actually sent to the printer when the printer asks for it. If the printer
was not awake to begin with, an attempt is made to wake it up, thus
meaning that in some circumstances when the printer wasn't ready a
character may be lost, this cannot be helped. If the printer is off (via
the BCD switch) then the character will be forgotten as the Printer Buffer
is inactive.
|}

== 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
|}

== Starting Up ==

The setup procedure for setting up extension job calls is to:

# Claim the number of JobCodes you want
#: if success:
# patch the internal_vec and unknownjob_vec vectors
# move LOMEM up to protect your program
# do anything else for initial startup you may want to do
# return back, ready and waiting

This in code looks like:

<nowiki>execute
LDX #no_of_calls ; Number of JobCodes wanted
LDA #1 ; CALLOS, function 1, Claim JobCodes
JSR OS_CALLOS ; Call CALLOS
CPX #0 ; Check we were given some codes
BEQ noinstall ; No, don't bother installing ourself
STX call ; Store base address of JobCodes allocated
STY job_id ; Store JOB ID given

LDA internal_vec ; Get old internal_vec (LSB)
STA ovec ; Store it
LDA internal_vec+1 ; Get old internal_vec (MSB)
STA ovec+1 ; Store it
LDA #>internal_handle ; Our internal handler (LSB)
STA internal_vec ; Place it in the vector (LSB)
LDA #<internal_handle ; Our internal handler (MSB)
STA internal_vec+1 ; Place it in the vector (MSB)

LDA unknownjob_vec ; Get old unknownjob_vec (LSB)
STA ovec2 ; Store it
LDA unknownjob_vec+1 ; Get old unknownjob_vec (MSB)
STA ovec2+1 ; Store it
LDA #>job_handle ; Our unknown job handler (LSB)
STA unknownjob_vec ; Place it in the vector (LSB)
LDA #<job_handle ; Our unknown job handler (MSB)
STA unknownjob_vec+1 ; Place it in the vector (MSB)

LDX #>WriteLomem ; Point to JobName
LDY #<WriteLomem
JSR findjob ; Find WriteLomem code
BEQ noinstall ; Doesn't exist !
LDX #>end_of_code ; End of code (LSB)
LDY #<end_of_code ; End of code (MSB)
STX jobin_buf ; Place it in jobin_buf (LSB)
STY jobin_buf+1 ; Place it in jobin_buf+1 (MSB)
JSR OS_DECODEJOB ; Call JobCall handler

noinstall
RTS ; End - return to OS

findjob
STX zero.gp1 ; Zero page
STY zero.gp1+
LDY #0
findthisjoblo
LDA (zero.gp1),Y
STA jobin.buf,Y ; Store name in jobin_buf
INY
CMP #13
BNE findthisjoblo
LDA #3 ; NameCode
JSR OS.DECODEJOB ; Call NameCode
LDA jobout.buf ; Get returned value
RTS

WriteLomem STR "WriteLomem"</nowiki>

This will setup the various vectors and memory pointers for the
applicaion, the actual routines (internal_handle and job_handle) are fairly
straight forward and simple:

<nowiki>internal_handle
CMP #1 : Is it function call 1 (NameCode) ?
BNE internal_handle_2 ; No, check for function 2
LDA job_id ; Get our JOB ID number
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #>job_names ; Our Job name table (LSB)
LDY #<job_names ; Our Job name table (MSB)
LDA #2 ; CALLOS function 2
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes : Found, go off and claim call
LDA #1 ; Not found, restore A
JMP (ovec) ; Call back to old vector

internal_handle_2
CMP #2 ; Is it function call 2 (CodeName) ?
BNE internal_handle_3 ; No, unknown, pass on
LDA job_id ; Get our JOB ID
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #>job_names ; Our Job name table (LSB)
LDY #<job_names ; Our Job name table (MSB)
LDA #3 ; CALLOS function 3
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes ; Found, go off and claim call
LDA #2 ; Not found, restore A
JMP (ovec) ; Call back to old vector

internal_yes
LDA #0 ; We want to claim call for some reason

internal_handle_3
JMP (ovec) ; Call back to old vector

job_handle
PHA ; Mark sure to preserve A
CPY call ; Check call wanted against base of ours
BCC job_handle_no ; Less than our base, so definately not ours
TYA
SBC #no_of_calls ; Subtract number of calls we have
CMP call ; Now compare with base
BCC job_handle2 ; Yes, one of ours

job_handle.no
PLA ; Restore A
JMP (ovec2) ; Call back to old vector

job_handle2
TYA
SEC
SBC call ; Subtract our base from call
ASL A ; Times by 2 for offset into table
TAY ; Place in Y
LDA job_run_table,Y ; Get LSB of routine
STA zero_gp1 ; Store it for indirect jump (LSB)
LDA job_run_table+1,Y ; Get MSB of routine
STA zero_gp1+1 ; Store it for indirect jump (MSB)
PLA ; Restore A
JMP (zero_gp1) ; Call our relevant routine

job_names ; List of our JobNames
STR "TestJob" ; Test job name
DFB &FF ; &FF - marks end of table

job_run_table ; List of routine addresses to match Jobs
DFW job_TestJob ; Test job routine</nowiki>

== Relocation ==

The relocation method used will not do a complete relocation, ie.
from ANY address to ANY address. The only constraint on the addresses is
that they must be the same offset in the page, which means, &2602 and &3402
is alright but &2602 and &3455 is not, ie. the difference between the two
addresses must be a multiple of 256 bytes, as only the MSB is altered, this
should not cause any real problems. What is meant by the two addresses is
the address the code was originally assembled at and the address it wants
relocating to. Because of this programs must be multiples of 256 bytes, ie.
the low byte of LOMEM must ALWAYS be 0, your program should be padded out.

The relocation mechanism works by having a table, and to each byte
of code there is one BIT, if unset it means the byte of code should not be
relocated, else it should be, thus the BitMap table is 8 times smaller than
the code. To generate the BitMap you have to assemble the code at two
different places, and compare both sets of assembled code against each
other, the differences are where the code is to be relocated. The code
which is sent up to the controller is assumed to be assembled at address
&100, so the first code should be assembled at &100, the other one should be
assembled at another address, say &600, and the first one be sent up with
the BitMap. A program is availble for the Elk/Beeb/Arc with 65Tube/Mac with
BBC BASIC to compare the two files and create the BitMap.

All the program has to do to relocate itself is execute this bit of
code first of all: (address is the base address of the program, ie. &100
for the downloaded version)

<nowiki>execcall
LDA #>(execute-address) ; Final execution address offset (LSB)
STA zero_gp1
LDA #<(execute-address) ; Final execution address offset (MSB)
STA zero_gp1+1

LDA #>(BitMap-address) ; BitMap address offset (LSB)
STA zero_gp2
LDA #<(BitMap-address) ; BitMap address offset (MSB)
STA zero_gp2+1

LDA #>(execcall-address); Length of data to relocate (LSB)
STA zero_gp3
LDA #<(execcall-address); Length of data to relocate (MSB)
STA zero_gp3+1

TXA ; Execcall REAL address
SEC
SBC #>(execcall-address); Subrtract length
TAX ; Put it back in X
TYA ; Ditto for MSB
SBC #<(execcall-address)
TAY
LDA #4 ; CALLOS function for Relocate
JMP OS_CALLOS ; Call CALLOS

BitMap ; BitMap start</nowiki>

This will relocate the code and automatically call the execution
address, which should be the initialisation code (ie. setup internal_vec
and unknownjob_vec etc.). "address" is the address the code is started to
assemble at, &100 for the version to be uploaded. The upload routine should
pass in X and Y (via ExecuteCode) the address of the start of execcall, this
means that the routine can tell where it is in memory, subtracting the
length gives the start of the code to relocate.

== Layout Summary ==

The layout of a full application should be like this by now:

<nowiki> start of code
program job codes, data etc.
internal handler
job handler
end of code
initialisation (setup internal etc.)
end of code to be relocated
execution (relocation)
relocation BitMap</nowiki>

Because of memory space the initialisation code should be placed
outside the reserved memory limit of the program, as it is only called once
and not needed again.

== Modules ==

The module is located at &8000 in memory, and should be a EPROM placed
in the second ROM socket in the controller (ie. the top RAM socket). This
module is primary designed to turn the Controller into a dedicated task,
making it perform some function from switch on. It could also be used to
add more permant JobCalls to the Controller, in the process taking up much
less RAM), but because of there being only one Module present this feature
is limited, and is much more suited to a collection of the user's own
personal routines.

For the OS to recognise a module as being in place the text "Module" is
looked for, the layout of a module should be like this (starting at
&8000):

{|class="wikitable"
!Offset!!Value!!Comment
|-
|0||"Module"||The OS checks for this string
|-
|6||0||End of check string
|-
|7||Language entry||Address of 'Language' entry
|-
|9||Service entry||Address of 'Service' entry
|-
|11||"<Module Title>"||Module title
|-
| ||0||End of Module title
|-
| ||"<Module part>"||Part Module Title
|-
| ||0||End of Part Module Title
|-
| ||"x.xx"||Part version number
|-
| ||&FF||End of parts list
|}

The language entry is a 2 byte value holding the address of the language
entry routine, this is called on reset, if the BCD is set correctly. A
value of less than &8000 means there is no valid language entry and any
language calls are ignored. If a RTS is made the OS carries on as it would
have if there wasn't a language call.

The service entry is a 2 byte value holding the address of the service
entry routine, this is called at various appropriate moments with service
numbers in A. A list of current calls is thus:

* 0 - Not used
* 1 - Unknown Job Code
* 2 - Centisecond call
* 3 - irq2 (unknown IRQ)
* 4 - internal_vec call (exit with A=0 to claim)
* 254 - RESET
* 255 - BRK

On exit all registers and flags should be preserved. For call 1 the
unknown job value is held in the Y register, the environment is held in the
X register, on exit, X should contain the flag, as A does from the exit of
unknownjob_vec. For the rest of calls, X and Y are undefined.

For both Service and Language entry points, a value of 0 means "there is
no valid routine" and the module isn't called for that type of entry.

== Example JobCall ==

Finally a full implementation of a JobCall, from start to finish.

<nowiki>DIM data% &1000
:
no_of_calls = 1
:
VIA = &E030
ACIA = &E010
ADC = &E000
AUX_PORT = &E020
brk_vec = &200
nmi_vec = &202
irq_vec = &204
irq2_vec = &206
sendserial_vec = &208
readserial_vec = &20A
sendjob_vec = &20C
readjob_vec = &20E
decodejob_vec = &210
unknownjob_vec = &212
extjob_vec = &214
centisec_vec = &216
internal_vec = &218
callos_vec = &21A
printer_vec = &21C
zero_gp1 = 0
zero_gp2 = 2
zero_gp3 = 4
zero_gp4 = 6
zero_gp5 = 8
zero_gp6 = 10
zero_gp7 = 12
zero_gp8 = 14
zero_gp9 = 16
zero_gp10 = 18
user_reserved = &70
irq_A = &A0
fcount = &A1
RAM_size = &A3
jobout_buf = &400
jobin_buf = &480
OS_PRINTER = &FFB9
OS_CALLOS = &FFBC
OS_SENDBYTE = &FFBF
OS_READBYTE = &FFC2
OS_SENDJOB = &FFC5
OS_READJOB = &FFC8
OS_DECODEJOB = &FFCB
:
FOR create=1 TO 2
:
FOR pass%=4 TO 7 STEP 3
P%=&100*create : O%=data%
[OPT pass%
:
.job_DemoJob
CMP #1
BEQ DemoJob_go
LDA #1
LDY #0
RTS
/
.DemoJob_go

:
.internal_handle
CMP #1; Is it function call 1 (NameCode) ?
BNE internal_handle_2; No, check for function 2
/
LDA job_id; Get our JOB ID number
STA zero_gp3; Place it in zero_gp3 for CALLOS
LDX #job_names MOD 256; Our Job name table (LSB)
LDY #job_names DIV 256; Our Job name table (MSB)
LDA #2; CALLOS function 2
JSR OS_CALLOS; Call CALLOS
BCC internal_yes; Found, go off and claim call
LDA #1; Not found, restore A
JMP (ovec); Call back to old vector
/
.internal_handle_2
CMP #2; Is it function call 2 (CodeName) ?
BNE internal_handle_3; No, unknown, pass on
/
LDA job_id; Get our JOB ID
STA zero_gp3; Place it in zero_gp3 for CALLOS
LDX #job_names MOD 256; Our Job name table (LSB)
LDY #job_names DIV 256; Our Job name table (MSB)
LDA #3; CALLOS function 3
JSR OS_CALLOS; Call CALLOS
BCC internal_yes; Found, go off and claim call
LDA #2; Not found, restore A
JMP (ovec); Call back to old vector
/
.internal_yes
LDA #0; We want to claim call for some reason
/
.internal_handle_3
JMP (ovec); Call back to old vector
:
.job_handle
PHA; Make sure to preserve A
CPY call; Check call wanted against base of ours
BCC job_handle_no; Less than our base, so definately not ours
TYA
SBC #no_of_calls; Subtract number of calls we have
CMP call; Now compare with base
BCC job_handle2; Yes, one of ours
/
.job_handle.no
PLA; Restore A
JMP (ovec2); Call back to old vector
/
.job_handle2
TYA
SEC
SBC call; Subtract our base from call
ASL A; Times by 2 for offset into table
TAY; Place in Y
LDA job_run_table,Y; Get LSB of routine
STA zero_gp1; Store it for indirect jump (LSB)
LDA job_run_table+1,Y; Get MSB of routine
STA zero_gp1+1; Store it for indirect jump (MSB)
PLA; Restore A
JMP (zero_gp1); Call our relevant routine
:
.job_names; List of our JobNames
EQUS "DemoJob":EQUB 13; Test job name
/
EQUB &FF; &FF - marks end of table
:
.job_run_table; List of routine addresses to match Jobs
EQUW job_DemoJob; Test job routine
:
.call : EQUB 0; Store for our JobCode base
.job_id : EQUB 0; Store for our JobId
.ovec : EQUW 0; Store for old internal_vec value
.ovec2 : EQUW 0; Store for old unknownjob_vec value
:
EQUS STRING$(&100-(P% MOD 256),CHR$0)
.end_of_code; end_of_code should be on page boundry
:
.execute
LDX #no_of_calls; Number of JobCodes wanted
LDA #1; CALLOS, function 1, Claim JobCodes
JSR OS_CALLOS; Call CALLOS
STX call; Store base address of JobCodes allocated
STY job_id; Store JOB ID given
CPX #0; Check we were given some codes
BEQ noinstall; No, don't bother installing ourself
/
LDA internal_vec; Get old internal_vec (LSB)
STA ovec; Store it
LDA internal_vec+1; Get old internal_vec (MSB)
STA ovec+1; Store it
LDA #internal_handle MOD 256; Our internal handler (LSB)
STA internal_vec; Place it in the vector (LSB)
LDA #internal_handle DIV 256; Our internal handler (MSB)
STA internal_vec+1; Place it in the vector (MSB)
/
LDA unknownjob_vec; Get old unknownjob_vec (LSB)
STA ovec2; Store it
LDA unknownjob_vec+1; Get old unknownjob_vec (MSB)
STA ovec2+1; Store it
LDA #job_handle MOD 256; Our unknown job handler (LSB)
STA unknownjob_vec; Place it in the vector (LSB)
LDA #job_handle DIV 256; Our unknown job handler (MSB)
STA unknownjob_vec+1; Place it in the vector (MSB)
/
LDX #end_of_code MOD 256; End of code (LSB)
LDY #end_of_code DIV 256; End of code (MSB)
STX jobin_buf; Place it in jobin_buf (LSB)
STY jobin_buf+1; Place it in jobin_buf+1 (MSB)
LDA #65; JobCode for WriteLomem
JSR OS_DECODEJOB; Call JobCall handler
/
.noinstall
RTS; End - return to OS
:
.execcall
LDA #>(execute-address); Final execution address offset (LSB)
STA zero_gp1
LDA #<(execute-address); Final execution address offset (MSB)
STA zero_gp1+1
/
LDA #>(BitMap-address); BitMap address offset (LSB)
STA zero_gp2
LDA #<(BitMap-address); BitMap address offset (MSB)
STA zero_gp2+1
/
LDA #>(execcall-address); Length of data to relocate (LSB)
STA zero_gp3
LDA #<(execcall-address); Length of data to relocate (MSB)
STA zero_gp3+1
/
TXA; Execcall REAL address
SEC
SBC #>(execcall-address); Subtract length
TAX; Put it back in X
TYA; Ditto for MSB
SBC #<(execcall-address)
TAY
LDA #4; CALLOS function for Relocate
JMP OS_CALLOS; Call CALLOS
/
.BitMap; BitMap start
:
]
NEXT
:
OSCLI "SAVE code"+STR$create+" "+STR$~data%+" "+STR$~O%
:
NEXT</nowiki>

== Changelog ==

{|class="wikitable"
|bob||071||Fixed MotorForward bug (%10)
|-
|bob||072||CallOS 14 now checks current adc.owner status
|-
|jim||072.d1||* Rewrite for new hardware/processor *
|-
|jim||072.d1||Moved vectors/workspace to &440
|-
|jim||072.d1||Moved rs.inp.buf to &500
|-
|jim||072.d1||Moved jobout.buf to &600
|-
|jim||072.d1||Moved jobin.buf to &680
|-
|jim||072.d1||Moved jobs.status to &700
|-
|jim||072.d1||Added irq.X (&A4)
|-
|jim||072.d1||Added irq.Y (&A5)
|-
|jim||072.d1||Removed short detection code
|-
|jim||072.d1||Voided CallOS' 6,7,8,9,10,11,13,16,17,18,19
|-
|jim||072.d1||Removed JobCalls ReadADCReg,WriteADCReg
|-
|jim||072.d1||Removed JobCalls ReadACIAReg,WriteACIAReg
|-
|jim||072.d1||Removed JobCalls ReadVIAReg,WriteVIAReg,SetVIAHigh,SetVIALow
|-
|jim||072.d1||Added CallOS 21 Write Outputs
|-
|jim||072.d1||Added CallOS 22 Read Outputs added
|-
|jim||072.d1||Added CallOS 23 Read Inputs added
|-
|jim||072.d1||Added CallOS 24 Write Motors
|-
|jim||072.d1||Added CallOS 25 Read Motors
|-
|jim||072.d1||Added CallOS 26 Read Keypad
|-
|jim||072.d1||Expanded CallOS 5 information
|-
|jim||072.d1||Added JobCall IdentSystem to return CallOS 5 info
|-
|jim||072.d1||JobCalls now use appropriate CallOS'
|-
|jim||072.d1||OS.READBYTE no longer preserves A on CS
|-
|jim||072.d1||irq.vec,irq2.vec,nmi.vec now redundant
|-
|jim||072.d1||Renamed JobCall DownloadData to DownloadData38
|-
|jim||072.d1||Renamed JobCall UploadData to UploadData38
|-
|jim||072.d1||Renamed JobCall ExecuteCode to ExecuteCode38
|-
|jim||072.d1||Renamed JobCall ReadByte to ReadByte38
|-
|jim||072.d1||Renamed JobCall StoreByte to StoreByte38
|-
|jim||072.d1||JobCall ForcedADCRead now checks adc.owner first
|-
|jim||072.d3||Added CallOS 27 Write printer
|-
|jim||072.d3||Added CallOS 28 Read printer
|-
|jim||072.d3||Added CallOS 29 Write RTC Reg
|-
|jim||072.d3||Added CallOS 30 Read RTC Reg
|-
|jim||072.d3||Added CallOS 31 Write RTC string
|-
|jim||072.d3||Added CallOS 32 Read RTC string
|-
|jim||072.d3||Added CallOS 33 Write RTC bcd
|-
|jim||072.d3||Added CallOS 34 Read RTC bcd
|-
|jim||072.d3||Added CallOS 35 Write LCD Reg
|-
|jim||072.d3||Added CallOS 36 Read LCD Reg
|-
|jim||072.d3||Added JobCall WritePrinter
|-
|jim||072.d3||Added JobCall ReadPrinter
|-
|jim||072.d3||Added JobCall PrintChar
|-
|jim||072.d3||Added JobCall PrintStreamZ
|-
|jim||072.d3||Added JobCall PrintStream
|-
|jim||072.d3||Added JobCall PrintServer
|-
|jim||072.d3||Added JobCall WriteRTCReg
|-
|jim||072.d3||Added JobCall ReadRTCReg
|-
|jim||072.d3||Added JobCall WriteRTC
|-
|jim||072.d3||Added JobCall ReadRTC
|-
|jim||072.d3||Added JobCall WriteRTCbcd
|-
|jim||072.d3||Added JobCall ReadRTCbcd
|-
|jim||072.d3||Added JobCall WriteLCDReg
|-
|jim||072.d3||Added JobCall ReadLCDReg
|-
|jim||072.d3||Added CallOS 37 Write Power ctrl
|-
|jim||072.d3||Added CallOS 38 Read Power ctrl
|-
|jim||072.d3||Implemented OS.PRINTER
|-
|jim||072.d3||Added JobCall PatchMF (MotorForward)
|-
|jim||072.d3||Changed irq.vec to int0.vec
|-
|jim||072.d3||Changed irq2.vec to int1.vec
|-
|jim||072.d3||Added int2irq.vec (wrksp+&20)
|-
|jim||072.d3||Added int3irq.vec (wrksp+&22)
|-
|jim||072.d3||Added int4irq.vec (wrksp+&24)
|-
|jim||072.d3||Added c0irq.vec (wrksp+&26)
|-
|jim||072.d3||Added c1irq.vec (wrksp+&28)
|-
|jim||072.d3||Added t1irq.vec (wrksp+&2A)
|-
|jim||072.d3||Added t2irq.vec (wrksp+&2C)
|-
|jim||072.d3||Added txirq.vec (wrksp+&2E)
|-
|jim||072.d3||Added tyirq.vec (wrksp+&30)
|-
|jim||072.d3||Added s1rirq.vec (wrksp+&32)
|-
|jim||072.d3||Added s1rirq.vec (wrksp+&34)
|-
|jim||072.d3||Added s2irq.vec (wrksp+&36)
|-
|jim||072.d3||Added adcirq.vec (wrksp+&38)
|-
|jim||072.d3||Renamed JobCall DownloadData38 to DownloadData740
|-
|jim||072.d3||Renamed JobCall UploadData38 to UploadData740
|-
|jim||072.d3||Renamed JobCall ExecuteCode38 to ExecuteCode740
|-
|jim||072.d3||Renamed JobCall ReadByte38 to ReadByte740
|-
|jim||072.d3||Renamed JobCall StoreByte38 to StoreByte740
|-
|jim||072.d4||Hardware update
|-
|jim||072.d4||Re-assigned CallOS 37 to Write Power/Charge control
|-
|jim||072.d4||Re-assigned CallOS 38 to Read Power/Charge control
|-
|jim||072.d4||Moved int2irq.vec to wrksp+&22
|-
|jim||072.d4||Moved int3irq.vec to wrksp+&24
|-
|jim||072.d4||Moved int4irq.vec to wrksp+&26
|-
|jim||072.d4||Moved c0irq.vec to wrksp+&28
|-
|jim||072.d4||Moved c1irq.vec to wrksp+&2A
|-
|jim||072.d4||Moved t1irq.vec to wrksp+&2C
|-
|jim||072.d4||Moved t2irq.vec to wrksp+&2E
|-
|jim||072.d4||Moved txirq.vec to wrksp+&30
|-
|jim||072.d4||Moved tyirq.vec to wrksp+&32
|-
|jim||072.d4||Moved s1rirq.vec to wrksp+&34
|-
|jim||072.d4||Moved s1rirq.vec to wrksp+&36
|-
|jim||072.d4||Moved s2irq.vec to wrksp+&38
|-
|jim||072.d4||Moved adcirq.vec to wrksp+&3A
|-
|jim||072.d4||Added OS.LCDVDU (&FFB7) and lcdvdu.vec (wrksp+&20)
|-
|jim||072.d5||Re-assigned CallOS 37 to Write/Read Power/Charge control
|-
|jim||072.d5||Re-assgined CallOS 38 Read Battery Voltage
|-
|jim||072.d5||OS.CALLOS now re-entrant
|-
|jim||072.d5||Fixed OS.PRINTER
|-
|jim||072.d5||Started to add internal logging software
|-
|jim||072.d5||Moved OS.LCDVDU to &FFB6
|-
|jim||072.d7||Added OS.PRINTERPOLL (&FFB3) and printerpoll.vec (wrksp+&3C)
|-
|bob||073||Matched jim & bob sensor lookup tables
|-
|bob||073||Added PatchMF
|-
|jim||072.dj||Added OS.CALLOS 51 Read keypad press
|-
|jim||072.dj||Added hard reset keypad press
|-
|jim||072.dk||Added JobCall ReadOutputs
|-
|jim||072.do||Changed soft reset of zero page locations
|-
|jim||072.do||Changed MotorForward/Backward bitmaps
|-
|jim||072.dp||Fixed OS.CALLOS WriteRTCbcd
|-
|jim||072.dq||Fixed OS.CALLOS ReadRTCstring for correct 24hr operation
|-
|jim||072.dr||Changed reset prompts
|-
|bob||074||Added support for Little Bob
|-
|jim||072.dy||Added further RTC/CMOS support
|-
|jim||072.dB||Removed double hard reset
|-
|jim||072.dE||Set _cpu.mode depending on external memory requirement
|-
|jim||072.dF||Added Insight code
|-
|jim||073||Sub-release
|-
|jim||074||Modification to LCD code - uses bsy flag all the time now
|-
|jim||074||Fixed OS.CALLOS 42 Write LCD Char Def
|-
|jim||074||Fixed OS.CALLOS 43 Read LCD Char Def
|-
|jim||075||Added simple battery charge code
|-
|jim||075||Fixed JobCall ReadSensorTable
|-
|jim||075||Fixed OS.CALLOS 42 Write LCD Char Def
|-
|jim||075||Fixed OS.CALLOS 43 Read LCD Char Def
|-
|jim||075||Added sleep code
|-
|jim||075||Added OS.CALLOS 52 Write Sleep Time
|-
|jim||075||Added OS.CALLOS 53 Read Sleep Time
|-
|jim||075||Modified battery charge code
|-
|jim||076||Modified JobCall ReadSensorTable
|-
|jim||076||Modified OS.CALLOS 26 ReadKeypad to do debounce
|-
|jim||077||Rewrote battery charging code
|-
|jim||077.2||Reduced stop charge threshold to 2
|-
|jim||077.3||Increased stop charge threshold to 3
|-
|jim||077.3||Added battery voltage averaging
|-
|bill||077||Stripped
|-
|bill||077||Moved ins to out port
|-
|bill||077||Added RTS
|-
|bill||077||Changed sensor ID system back to original, using p2.1
|-
|bill||077||Dedicated USB/RS selection line, RTS provisioned on p2.3
|-
|bill||077||Overload "bounce" timing
|-
|bill||078||CTS added
|-
|bill||079||Temperature fudge
|}

SmartBox OS

2023-11-04T17:42:37Z

Benryves: /* Modules */ Tidied up layout of modules documentation

== Documentation for SmartBox OS 2.066 ==

The term JobCall is the concept of the routine itself, as opposed to
JobName (which is the actual name associated with it (eg. NameCode)) and
JobCode (which is the actual number associated with it (eg. 3)).

The term controller means the SmartBox, or any other incarnation
which may appear in future time !

The term OS means the controllers' Operating System.

== Preview ==

There are a number of reasons why using Machine Code on the
controller is more desirable than using the various JobCalls via the serial
link. One reason is speed, if the task which needs to be performed, has to
be performed very quickly (more quickly than can be achieved via the serial
link at least), then some code must be written to work in the controller
itself to achieve this sort of speed. If the task required is to be a
"background" task (ie. a task which may happen while other "things" carry
on as normal, like a change of state of a particular port) then it is far
easier to let the controller do all the work, maybe under interupts, than
continuously poll the controller checking the state of various things.
Another reason may be that you would like to add another JobCall to the OS,
extending the calls available to external applications (and the user at the
same time), without the user having to write the code himself to achieve the
aim. For advanced users, there is also the ablity to alter the way the OS
does various things and to have the controller in their "power", for
dedicated tasks etc.

One advantage of writing IN the controller is that that "function"
is available to any computer using the serial link, and is thus not fixed to
one computer type or even a computer at all, where the controller is used
free running, doing a particular task which doesn't need the intervention of
the user's own computer.

== Call types ==

There are three different types of machine code routines which can
be added to the controller. Each one is suited to a more advanced level
than the other, which also relates to the amount of work needed to actually
get the routine working ! The three levels are such:

=== Simple stand alone routine ===

Here the routine is just the routine
itself with no supporting code (ie. code to integrate with the rest of the
OS). It has to be called directly, by use of the ExecuteCode JobCall, thus
it usually resides at a fixed address and obviously does not offer the user
friendly way of accessing itself like there is with normal OS calls.

=== Extended JobCall ===

There is one JobCall in the OS (ExtendJob)
which can call various routines residing in memory, each one is identified
by a 8 bit number. The disadvantages of this way is that the call hasn't
got it's own JobName/JobCode and needs the extra byte to identify itself.
This is ideal for the quick routine which the user would like to add for
himself without having to resort to the extra code needed for the full
JobCode implementation.

=== Full JobCall ===

This is where the routine can define itself one
(or a number) of JobNames/JobCodes, it can integrate itself into an
extension of the OS in a complete way. The disadvantage is that extra
coding is needed to deal with the various OS calls it has to service and
that extra work is needed to produce a suitable file to place in the
controller.

Normally with most processors, including the 65c02, the machine code
produced is produced for a fixed memory address, and it cannot be made to
run in a different place in memory unless extra work is carried out by the
user, or at least a combination of the user and the OS. For the controller
this is a very severe disadvantage as most extensions are downloaded as
"modules" and to optimise memory a system has to be devised to enable
routines to be placed anywhere in memory, thus allowing no memory to be
wasted. In the OS there is a routine to do just this, though it does need
some help. A special version of the users code has to be developed, or
rather it has to be "processed" to add extra information on the end. Extra
code is needed to set up a few pointers and call the OS routine to relocate.
See later.

== Memory ==

The first 256 bytes of memory are somewhat special, most zero page
locations are reserved for use by the OS:

{|class="wikitable"
|-
|&00-&14||General workspace, used to pass parameters to some OS routines, can also be used by other routines DURING their execution.
|-
|&15-&6F||Reserved
|-
|&70-&9F||Available to the user
|-
|&A0||Accumulator store for irqs (irq_A)
|-
|&A1-&A2||Two byte counter, decremented at 100hz, useful for temporary timing purposes (fcount)
|-
|&A3||RAM size, high byte of RAM size of machine, ie. for 32k this will be &80 (RAM_size)
|-
|&A4-&AF||Reserved
|-
|&B0-&FF||Used by the OS
|-
|}

The rest of memory space is used for the processors stack, OS'
buffers, tables, vectors and, of course, the user available memory.

A breakdown of the rest of memory:

* &100 to &1FF is the 65c02's stack.
* &200-&2FF is used by the OS for various system functions and also contains the vector table, more on that later.
* &300-&3FF is the serial input buffer.
* &400-&47F is the internal job code call output buffer. (jobout_buf)
* &480-&4FF is the internal job code call input buffer. (jobin_buf)
* &500-&5FF is the job status table.
* &600 to the end of RAM memory is for the user. The user should not assume what the top of AVAILABLE memory is and use the system variable HIMEM.

In the controller the maximum limit of RAM is &8000 (which is 32k),
from &8000-&DFFF lies the memory mapped hardware, from &E000 to &FFF9 lies
the OS and from &FFFA to &FFFF lies the 65c02 vectors.

So the user has his own limits of free memory. The lowest limit is
called LOMEM and the highest limit is called HIMEM, everything between these
boundaries is termed "available" for use by anyone, the user or the OS.

Anyone can also claim memory, thus making private to them and not allowing
anyone else to use it. You do this by altering the value of LOMEM, HIMEM
should not be moved. Of course anyone claiming memory should first check
that there is enough memory available for the amount they want to claim for.
To take a common example, a downloadable routine which installs itself as a
extension routine, The download routine will first of all read LOMEM, read
HIMEM, check there is enough memory for the routine, download it to LOMEM
and call it, the downloaded routine will then relocate itself and alter
LOMEM so it is protected.

There is one other memory limit, this is called TOPMEM, this is the
absolute top limit of RAM, HIMEM will normally equal TOPMEM, but a future OS
may alter HIMEM to below TOPMEM. TOPMEM should be ignored ideally, and
HIMEM used.

== OS Calls ==

The OS has calls (ie. a jump instruction which you call, which
then calls, via a RAM vector, a routine in the OS) setup near the top of
memory, through these calls you do everything associated with the
controller. The calls are are such:

* OS_PRINTER at address &FFB9
* OS_CALLOS at address &FFBC
* OS_SENDBYTE at address &FFBF
* OS_READBYTE at address &FFC2
* OS_SENDJOB at address &FFC5
* OS_READJOB at address &FFC8
* OS_DECODEJOB at address &FFCB

The address is the one to call for the particular routine.

* OS_PRINTER is reserved for future use.
* OS_CALLOS calls upon the OS to do various things internally.
* OS_SENDBYTE sends a byte out of the serial port.
* OS_READBYTE reads a byte from the serial port.
* OS_SENDJOB 'sends' a value to the JobCall caller.
* OS_READJOB 'reads' a value from the JobCalls caller.
* OS_DECODEJOB decodes the Job number held in A and acts on it.

Note none of these things should be used in interupt routines,
except OS_CALLOS, of any sort, except if YOU know what state the machine is
in and WHY.

=== OS_READBYTE and OS_SENDBYTE: Serial Port ===

The serial port on the controller is currently based on the 6850
UART, this need not bother you as the OS deals with the thing entirely by
itself. The chip is setup by the OS to always have a word format of 8n1 and
a baud rate of 9600, this translates to 960cps. The 6850 has two divide
rates for the baud rate, the OS only uses one, using the other one is beyond
the scope of this document and shouldn't be neccessary to use.

Only receive interupts are used, transmission of characters is done
on a polled basis.

As said, there are two calls OS_READBYTE and OS_SENDBYTE.

==== OS_READBYTE ====

OS_READBYTE tests the serial input buffer and returns the character (if any
in the A register), the c flag states whether there was a character
returned.

{|class="calltable"
|Entry||
A, X, Y, c, z = undefined
|-
|Exit||
* X, Y preserved
* z = undefined
* if c = 1 (no character received)
*: A is preserved
* if c = 0 (character received)
*: A = character received
|}

==== OS_SENDBYTE ====

OS_SENDBYTE sends the character in the A register out of the serial
port, taking into consideration flow control etc.

{|class="calltable"
|Entry||
* A = character to send
* X, Y, c, z = undefined
|-
|Exit||
* A, X, Y, c is preserved
* z = undefined
|}

=== OS_READJOB and OS_SENDJOB ===

To send/receive data from the user (either internally or via the
serial port) you call OS_SENDJOB/OS_READJOB for the next byte. If your
JobCall requires dynamic use of data, ie. interaction, then a check of the
enviroment should be done to check the call came from the serial port. One
example of this is the OS JobCall MultipleServer, which requires dynamic use
of sending a stream of data until a reaction from the user to tell it to
stop.

==== OS_READJOB: Read job value from the user ====

{|class="calltable"
|Entry||
* A, X, Y, c, z = undefined
|-
|Exit||
* A = byte read
* X, Y is preserved
* c, z = undefined
|-
|Note||
When coming from the serial port it waits for a character to be received, if you are doing a serial only call and wish to have a loop checking for a character from the user while doing "your own thing", then OS_READBYTE should be used. For internal calls this reads data out of jobin_buf.
|}

==== OS_SENDJOB: Give a job value back to the user ====

{|class="calltable"
|Entry||
* A = byte to give
* X, Y, c, z = undefined
|-
|Exit||
* A, X, Y is preserved
* c, z = undefined
|-
|Note||
This will send either out to the serial port or place a byte in jobout_buf.
For internal calls this stores the value in jobout_buf, which is allocated 128 bytes, no bound checking is done so sending more than 128 bytes to OS_SENDJOB will cause corruption of some memory.
|}

=== OS_DECODEJOB ===

JobCalls in practise are really only used by the user, JobCalls
tend not to call other calls at all, infact you shouldn't really call
another call unless you were called from the serial port. If you do need to
call another JobCall then you do it like this; with each call you have
associated with it a number, and the call might require some data or give
some data back or both. With the serial port this is simple, you just send
data down and receive data as it is produced. You can't do this with
internal calls, and some calls will not let you call them from inside the
controller, you HAVE to call them from outside. But for the ones which do
let you, you do it with two data blocks, one for input TO the call and one
for output FROM the call. These are setup in a position in memory
(jobin_buf and jobout_buf), each one has a maximum of 128 bytes and this
should not be overflowed (OS_READJOB and OS_SENDJOB do NOT do any bound
checking). So to start with you place in the input block the data you want
to give the call (if any), call it, and then act on the data in the output
block (if any). The OS call OS_DECODEJOB is the one which actually calls
the JobCall handler and eventually the actual routine, you tell the JobCall
handler which call you want by placing the JobCode in the A register.

So for OS_DECODEJOB:

{|class="calltable"
|Entry||
* A = JobCode
* X, Y, c, z = undefined
* jobin_buf should contain any input data
|-
|Exit||
* A = flag
* X = number of bytes given back by routine
* Y = undefined
* c = status, if set JobCall does not exist
* z = status, if set JobCall cannot be called internally
* jobout_buf contains any data sent from routine
|}

A typical example would be:

<nowiki> LDA #readhimem ; JobCode for ReadHimem
JSR OS_DECODEJOB ; Call the JobCall handler
LDX jobout_buf ; Read HIMEM from buffer LSB
LDY jobout_buf+1 ; Read HIMEM from buffer MSB
STX jobin_buf ; Place LSB in input buffer
STY jobin_buf+1 ; Place MSB in input buffer
LDA #writelomem ; JobCode for WriteLomem
JSR OS_DECODEJOB ; Call the JobCall handler</nowiki>

which would read HIMEM, and then write LOMEM to be the same value, leaving
no spare memory left.

The reason why you should not call an internal call from another
internal call is that the same buffers (jobin_buf and jobout_buf) would be
used for both calls, causing conflict between the two calls, or rather to
the originator of the primary call ! The only time it would be safe if is
if you have already got all the data you want from jobin_buf and haven't
placed any in the jobout_buf (it would be lost if you had done).

=== 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.
|}

=== OS_PRINTER: Place a character in the printer buffer ===

{|class="calltable"
|Entry||
* A = character to send
* X, Y, c, z = undefined
|-
|Exit||
* A, X, Y is preserved
* if c = 0 (printed)
*: The printer is on and the character was inserted
* if c = 1 (not printed)
*: The printer is off and the character was forgotten
* z = undefined
|-
|Note||
The character goes into the printer buffer and will be
actually sent to the printer when the printer asks for it. If the printer
was not awake to begin with, an attempt is made to wake it up, thus
meaning that in some circumstances when the printer wasn't ready a
character may be lost, this cannot be helped. If the printer is off (via
the BCD switch) then the character will be forgotten as the Printer Buffer
is inactive.
|}

== 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
|}

== Starting Up ==

The setup procedure for setting up extension job calls is to:

# Claim the number of JobCodes you want
#: if success:
# patch the internal_vec and unknownjob_vec vectors
# move LOMEM up to protect your program
# do anything else for initial startup you may want to do
# return back, ready and waiting

This in code looks like:

<nowiki>execute
LDX #no_of_calls ; Number of JobCodes wanted
LDA #1 ; CALLOS, function 1, Claim JobCodes
JSR OS_CALLOS ; Call CALLOS
CPX #0 ; Check we were given some codes
BEQ noinstall ; No, don't bother installing ourself
STX call ; Store base address of JobCodes allocated
STY job_id ; Store JOB ID given

LDA internal_vec ; Get old internal_vec (LSB)
STA ovec ; Store it
LDA internal_vec+1 ; Get old internal_vec (MSB)
STA ovec+1 ; Store it
LDA #>internal_handle ; Our internal handler (LSB)
STA internal_vec ; Place it in the vector (LSB)
LDA #<internal_handle ; Our internal handler (MSB)
STA internal_vec+1 ; Place it in the vector (MSB)

LDA unknownjob_vec ; Get old unknownjob_vec (LSB)
STA ovec2 ; Store it
LDA unknownjob_vec+1 ; Get old unknownjob_vec (MSB)
STA ovec2+1 ; Store it
LDA #>job_handle ; Our unknown job handler (LSB)
STA unknownjob_vec ; Place it in the vector (LSB)
LDA #<job_handle ; Our unknown job handler (MSB)
STA unknownjob_vec+1 ; Place it in the vector (MSB)

LDX #>WriteLomem ; Point to JobName
LDY #<WriteLomem
JSR findjob ; Find WriteLomem code
BEQ noinstall ; Doesn't exist !
LDX #>end_of_code ; End of code (LSB)
LDY #<end_of_code ; End of code (MSB)
STX jobin_buf ; Place it in jobin_buf (LSB)
STY jobin_buf+1 ; Place it in jobin_buf+1 (MSB)
JSR OS_DECODEJOB ; Call JobCall handler

noinstall
RTS ; End - return to OS

findjob
STX zero.gp1 ; Zero page
STY zero.gp1+
LDY #0
findthisjoblo
LDA (zero.gp1),Y
STA jobin.buf,Y ; Store name in jobin_buf
INY
CMP #13
BNE findthisjoblo
LDA #3 ; NameCode
JSR OS.DECODEJOB ; Call NameCode
LDA jobout.buf ; Get returned value
RTS

WriteLomem STR "WriteLomem"</nowiki>

This will setup the various vectors and memory pointers for the
applicaion, the actual routines (internal_handle and job_handle) are fairly
straight forward and simple:

<nowiki>internal_handle
CMP #1 : Is it function call 1 (NameCode) ?
BNE internal_handle_2 ; No, check for function 2
LDA job_id ; Get our JOB ID number
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #>job_names ; Our Job name table (LSB)
LDY #<job_names ; Our Job name table (MSB)
LDA #2 ; CALLOS function 2
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes : Found, go off and claim call
LDA #1 ; Not found, restore A
JMP (ovec) ; Call back to old vector

internal_handle_2
CMP #2 ; Is it function call 2 (CodeName) ?
BNE internal_handle_3 ; No, unknown, pass on
LDA job_id ; Get our JOB ID
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #>job_names ; Our Job name table (LSB)
LDY #<job_names ; Our Job name table (MSB)
LDA #3 ; CALLOS function 3
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes ; Found, go off and claim call
LDA #2 ; Not found, restore A
JMP (ovec) ; Call back to old vector

internal_yes
LDA #0 ; We want to claim call for some reason

internal_handle_3
JMP (ovec) ; Call back to old vector

job_handle
PHA ; Mark sure to preserve A
CPY call ; Check call wanted against base of ours
BCC job_handle_no ; Less than our base, so definately not ours
TYA
SBC #no_of_calls ; Subtract number of calls we have
CMP call ; Now compare with base
BCC job_handle2 ; Yes, one of ours

job_handle.no
PLA ; Restore A
JMP (ovec2) ; Call back to old vector

job_handle2
TYA
SEC
SBC call ; Subtract our base from call
ASL A ; Times by 2 for offset into table
TAY ; Place in Y
LDA job_run_table,Y ; Get LSB of routine
STA zero_gp1 ; Store it for indirect jump (LSB)
LDA job_run_table+1,Y ; Get MSB of routine
STA zero_gp1+1 ; Store it for indirect jump (MSB)
PLA ; Restore A
JMP (zero_gp1) ; Call our relevant routine

job_names ; List of our JobNames
STR "TestJob" ; Test job name
DFB &FF ; &FF - marks end of table

job_run_table ; List of routine addresses to match Jobs
DFW job_TestJob ; Test job routine</nowiki>

== Relocation ==

The relocation method used will not do a complete relocation, ie.
from ANY address to ANY address. The only constraint on the addresses is
that they must be the same offset in the page, which means, &2602 and &3402
is alright but &2602 and &3455 is not, ie. the difference between the two
addresses must be a multiple of 256 bytes, as only the MSB is altered, this
should not cause any real problems. What is meant by the two addresses is
the address the code was originally assembled at and the address it wants
relocating to. Because of this programs must be multiples of 256 bytes, ie.
the low byte of LOMEM must ALWAYS be 0, your program should be padded out.

The relocation mechanism works by having a table, and to each byte
of code there is one BIT, if unset it means the byte of code should not be
relocated, else it should be, thus the BitMap table is 8 times smaller than
the code. To generate the BitMap you have to assemble the code at two
different places, and compare both sets of assembled code against each
other, the differences are where the code is to be relocated. The code
which is sent up to the controller is assumed to be assembled at address
&100, so the first code should be assembled at &100, the other one should be
assembled at another address, say &600, and the first one be sent up with
the BitMap. A program is availble for the Elk/Beeb/Arc with 65Tube/Mac with
BBC BASIC to compare the two files and create the BitMap.

All the program has to do to relocate itself is execute this bit of
code first of all: (address is the base address of the program, ie. &100
for the downloaded version)

<nowiki>execcall
LDA #>(execute-address) ; Final execution address offset (LSB)
STA zero_gp1
LDA #<(execute-address) ; Final execution address offset (MSB)
STA zero_gp1+1

LDA #>(BitMap-address) ; BitMap address offset (LSB)
STA zero_gp2
LDA #<(BitMap-address) ; BitMap address offset (MSB)
STA zero_gp2+1

LDA #>(execcall-address); Length of data to relocate (LSB)
STA zero_gp3
LDA #<(execcall-address); Length of data to relocate (MSB)
STA zero_gp3+1

TXA ; Execcall REAL address
SEC
SBC #>(execcall-address); Subrtract length
TAX ; Put it back in X
TYA ; Ditto for MSB
SBC #<(execcall-address)
TAY
LDA #4 ; CALLOS function for Relocate
JMP OS_CALLOS ; Call CALLOS

BitMap ; BitMap start</nowiki>

This will relocate the code and automatically call the execution
address, which should be the initialisation code (ie. setup internal_vec
and unknownjob_vec etc.). "address" is the address the code is started to
assemble at, &100 for the version to be uploaded. The upload routine should
pass in X and Y (via ExecuteCode) the address of the start of execcall, this
means that the routine can tell where it is in memory, subtracting the
length gives the start of the code to relocate.

== Layout Summary ==

The layout of a full application should be like this by now:

<nowiki> start of code
program job codes, data etc.
internal handler
job handler
end of code
initialisation (setup internal etc.)
end of code to be relocated
execution (relocation)
relocation BitMap</nowiki>

Because of memory space the initialisation code should be placed
outside the reserved memory limit of the program, as it is only called once
and not needed again.

== Modules ==

The module is located at &8000 in memory, and should be a EPROM placed
in the second ROM socket in the controller (ie. the top RAM socket). This
module is primary designed to turn the Controller into a dedicated task,
making it perform some function from switch on. It could also be used to
add more permant JobCalls to the Controller, in the process taking up much
less RAM), but because of there being only one Module present this feature
is limited, and is much more suited to a collection of the user's own
personal routines.

For the OS to recognise a module as being in place the text "Module" is
looked for, the layout of a module should be like this (starting at
&8000):

{|class="wikitable"
!Offset!!Value!!Comment
|-
|0||"Module"||The OS checks for this string
|-
|6||0||End of check string
|-
|7||Language entry||Address of 'Language' entry
|-
|9||Service entry||Address of 'Service' entry
|-
|11||"<Module Title>"||Module title
|-
| ||0||End of Module title
|-
| ||"<Module part>"||Part Module Title
|-
| ||0||End of Part Module Title
|-
| ||"x.xx"||Part version number
|-
| ||&FF||End of parts list
|}

The language entry is a 2 byte value holding the address of the language
entry routine, this is called on reset, if the BCD is set correctly. A
value of less than &8000 means there is no valid language entry and any
language calls are ignored. If a RTS is made the OS carries on as it would
have if there wasn't a language call.

The service entry is a 2 byte value holding the address of the service
entry routine, this is called at various appropriate moments with service
numbers in A. A list of current calls is thus:

* 0 - Not used
* 1 - Unknown Job Code
* 2 - Centisecond call
* 3 - irq2 (unknown IRQ)
* 4 - internal_vec call (exit with A=0 to claim)
* 254 - RESET
* 255 - BRK

On exit all registers and flags should be preserved. For call 1 the
unknown job value is held in the Y register, the environment is held in the
X register, on exit, X should contain the flag, as A does from the exit of
unknownjob_vec. For the rest of calls, X and Y are undefined.

For both Service and Language entry points, a value of 0 means "there is
no valid routine" and the module isn't called for that type of entry.

== Example JobCall ==

Finally a full implementation of a JobCall, from start to finish.

<nowiki>DIM data% &1000
:
no_of_calls = 1
:
VIA = &E030
ACIA = &E010
ADC = &E000
AUX_PORT = &E020
brk_vec = &200
nmi_vec = &202
irq_vec = &204
irq2_vec = &206
sendserial_vec = &208
readserial_vec = &20A
sendjob_vec = &20C
readjob_vec = &20E
decodejob_vec = &210
unknownjob_vec = &212
extjob_vec = &214
centisec_vec = &216
internal_vec = &218
callos_vec = &21A
printer_vec = &21C
zero_gp1 = 0
zero_gp2 = 2
zero_gp3 = 4
zero_gp4 = 6
zero_gp5 = 8
zero_gp6 = 10
zero_gp7 = 12
zero_gp8 = 14
zero_gp9 = 16
zero_gp10 = 18
user_reserved = &70
irq_A = &A0
fcount = &A1
RAM_size = &A3
jobout_buf = &400
jobin_buf = &480
OS_PRINTER = &FFB9
OS_CALLOS = &FFBC
OS_SENDBYTE = &FFBF
OS_READBYTE = &FFC2
OS_SENDJOB = &FFC5
OS_READJOB = &FFC8
OS_DECODEJOB = &FFCB
:
FOR create=1 TO 2
:
FOR pass%=4 TO 7 STEP 3
P%=&100*create : O%=data%
[OPT pass%
:
.job_DemoJob
CMP #1
BEQ DemoJob_go
LDA #1
LDY #0
RTS
/
.DemoJob_go

:
.internal_handle
CMP #1; Is it function call 1 (NameCode) ?
BNE internal_handle_2; No, check for function 2
/
LDA job_id; Get our JOB ID number
STA zero_gp3; Place it in zero_gp3 for CALLOS
LDX #job_names MOD 256; Our Job name table (LSB)
LDY #job_names DIV 256; Our Job name table (MSB)
LDA #2; CALLOS function 2
JSR OS_CALLOS; Call CALLOS
BCC internal_yes; Found, go off and claim call
LDA #1; Not found, restore A
JMP (ovec); Call back to old vector
/
.internal_handle_2
CMP #2; Is it function call 2 (CodeName) ?
BNE internal_handle_3; No, unknown, pass on
/
LDA job_id; Get our JOB ID
STA zero_gp3; Place it in zero_gp3 for CALLOS
LDX #job_names MOD 256; Our Job name table (LSB)
LDY #job_names DIV 256; Our Job name table (MSB)
LDA #3; CALLOS function 3
JSR OS_CALLOS; Call CALLOS
BCC internal_yes; Found, go off and claim call
LDA #2; Not found, restore A
JMP (ovec); Call back to old vector
/
.internal_yes
LDA #0; We want to claim call for some reason
/
.internal_handle_3
JMP (ovec); Call back to old vector
:
.job_handle
PHA; Make sure to preserve A
CPY call; Check call wanted against base of ours
BCC job_handle_no; Less than our base, so definately not ours
TYA
SBC #no_of_calls; Subtract number of calls we have
CMP call; Now compare with base
BCC job_handle2; Yes, one of ours
/
.job_handle.no
PLA; Restore A
JMP (ovec2); Call back to old vector
/
.job_handle2
TYA
SEC
SBC call; Subtract our base from call
ASL A; Times by 2 for offset into table
TAY; Place in Y
LDA job_run_table,Y; Get LSB of routine
STA zero_gp1; Store it for indirect jump (LSB)
LDA job_run_table+1,Y; Get MSB of routine
STA zero_gp1+1; Store it for indirect jump (MSB)
PLA; Restore A
JMP (zero_gp1); Call our relevant routine
:
.job_names; List of our JobNames
EQUS "DemoJob":EQUB 13; Test job name
/
EQUB &FF; &FF - marks end of table
:
.job_run_table; List of routine addresses to match Jobs
EQUW job_DemoJob; Test job routine
:
.call : EQUB 0; Store for our JobCode base
.job_id : EQUB 0; Store for our JobId
.ovec : EQUW 0; Store for old internal_vec value
.ovec2 : EQUW 0; Store for old unknownjob_vec value
:
EQUS STRING$(&100-(P% MOD 256),CHR$0)
.end_of_code; end_of_code should be on page boundry
:
.execute
LDX #no_of_calls; Number of JobCodes wanted
LDA #1; CALLOS, function 1, Claim JobCodes
JSR OS_CALLOS; Call CALLOS
STX call; Store base address of JobCodes allocated
STY job_id; Store JOB ID given
CPX #0; Check we were given some codes
BEQ noinstall; No, don't bother installing ourself
/
LDA internal_vec; Get old internal_vec (LSB)
STA ovec; Store it
LDA internal_vec+1; Get old internal_vec (MSB)
STA ovec+1; Store it
LDA #internal_handle MOD 256; Our internal handler (LSB)
STA internal_vec; Place it in the vector (LSB)
LDA #internal_handle DIV 256; Our internal handler (MSB)
STA internal_vec+1; Place it in the vector (MSB)
/
LDA unknownjob_vec; Get old unknownjob_vec (LSB)
STA ovec2; Store it
LDA unknownjob_vec+1; Get old unknownjob_vec (MSB)
STA ovec2+1; Store it
LDA #job_handle MOD 256; Our unknown job handler (LSB)
STA unknownjob_vec; Place it in the vector (LSB)
LDA #job_handle DIV 256; Our unknown job handler (MSB)
STA unknownjob_vec+1; Place it in the vector (MSB)
/
LDX #end_of_code MOD 256; End of code (LSB)
LDY #end_of_code DIV 256; End of code (MSB)
STX jobin_buf; Place it in jobin_buf (LSB)
STY jobin_buf+1; Place it in jobin_buf+1 (MSB)
LDA #65; JobCode for WriteLomem
JSR OS_DECODEJOB; Call JobCall handler
/
.noinstall
RTS; End - return to OS
:
.execcall
LDA #>(execute-address); Final execution address offset (LSB)
STA zero_gp1
LDA #<(execute-address); Final execution address offset (MSB)
STA zero_gp1+1
/
LDA #>(BitMap-address); BitMap address offset (LSB)
STA zero_gp2
LDA #<(BitMap-address); BitMap address offset (MSB)
STA zero_gp2+1
/
LDA #>(execcall-address); Length of data to relocate (LSB)
STA zero_gp3
LDA #<(execcall-address); Length of data to relocate (MSB)
STA zero_gp3+1
/
TXA; Execcall REAL address
SEC
SBC #>(execcall-address); Subtract length
TAX; Put it back in X
TYA; Ditto for MSB
SBC #<(execcall-address)
TAY
LDA #4; CALLOS function for Relocate
JMP OS_CALLOS; Call CALLOS
/
.BitMap; BitMap start
:
]
NEXT
:
OSCLI "SAVE code"+STR$create+" "+STR$~data%+" "+STR$~O%
:
NEXT</nowiki>

== Changelog ==

<nowiki>bob 071 Fixed MotorForward bug (%10)
bob 072 CallOS 14 now checks current adc.owner status
jim 072.d1 * Rewrite for new hardware/processor *
jim 072.d1 Moved vectors/workspace to &440
jim 072.d1 Moved rs.inp.buf to &500
jim 072.d1 Moved jobout.buf to &600
jim 072.d1 Moved jobin.buf to &680
jim 072.d1 Moved jobs.status to &700
jim 072.d1 Added irq.X (&A4)
jim 072.d1 Added irq.Y (&A5)
jim 072.d1 Removed short detection code
jim 072.d1 Voided CallOS' 6,7,8,9,10,11,13,16,17,18,19
jim 072.d1 Removed JobCalls ReadADCReg,WriteADCReg
jim 072.d1 Removed JobCalls ReadACIAReg,WriteACIAReg
jim 072.d1 Removed JobCalls ReadVIAReg,WriteVIAReg,SetVIAHigh,SetVIALow
jim 072.d1 Added CallOS 21 Write Outputs
jim 072.d1 Added CallOS 22 Read Outputs added
jim 072.d1 Added CallOS 23 Read Inputs added
jim 072.d1 Added CallOS 24 Write Motors
jim 072.d1 Added CallOS 25 Read Motors
jim 072.d1 Added CallOS 26 Read Keypad
jim 072.d1 Expanded CallOS 5 information
jim 072.d1 Added JobCall IdentSystem to return CallOS 5 info
jim 072.d1 JobCalls now use appropriate CallOS'
jim 072.d1 OS.READBYTE no longer preserves A on CS
jim 072.d1 irq.vec,irq2.vec,nmi.vec now redundant
jim 072.d1 Renamed JobCall DownloadData to DownloadData38
jim 072.d1 Renamed JobCall UploadData to UploadData38
jim 072.d1 Renamed JobCall ExecuteCode to ExecuteCode38
jim 072.d1 Renamed JobCall ReadByte to ReadByte38
jim 072.d1 Renamed JobCall StoreByte to StoreByte38
jim 072.d1 JobCall ForcedADCRead now checks adc.owner first
jim 072.d3 Added CallOS 27 Write printer
jim 072.d3 Added CallOS 28 Read printer
jim 072.d3 Added CallOS 29 Write RTC Reg
jim 072.d3 Added CallOS 30 Read RTC Reg
jim 072.d3 Added CallOS 31 Write RTC string
jim 072.d3 Added CallOS 32 Read RTC string
jim 072.d3 Added CallOS 33 Write RTC bcd
jim 072.d3 Added CallOS 34 Read RTC bcd
jim 072.d3 Added CallOS 35 Write LCD Reg
jim 072.d3 Added CallOS 36 Read LCD Reg
jim 072.d3 Added JobCall WritePrinter
jim 072.d3 Added JobCall ReadPrinter
jim 072.d3 Added JobCall PrintChar
jim 072.d3 Added JobCall PrintStreamZ
jim 072.d3 Added JobCall PrintStream
jim 072.d3 Added JobCall PrintServer
jim 072.d3 Added JobCall WriteRTCReg
jim 072.d3 Added JobCall ReadRTCReg
jim 072.d3 Added JobCall WriteRTC
jim 072.d3 Added JobCall ReadRTC
jim 072.d3 Added JobCall WriteRTCbcd
jim 072.d3 Added JobCall ReadRTCbcd
jim 072.d3 Added JobCall WriteLCDReg
jim 072.d3 Added JobCall ReadLCDReg
jim 072.d3 Added CallOS 37 Write Power ctrl
jim 072.d3 Added CallOS 38 Read Power ctrl
jim 072.d3 Implemented OS.PRINTER
jim 072.d3 Added JobCall PatchMF (MotorForward)
jim 072.d3 Changed irq.vec to int0.vec
jim 072.d3 Changed irq2.vec to int1.vec
jim 072.d3 Added int2irq.vec (wrksp+&20)
jim 072.d3 Added int3irq.vec (wrksp+&22)
jim 072.d3 Added int4irq.vec (wrksp+&24)
jim 072.d3 Added c0irq.vec (wrksp+&26)
jim 072.d3 Added c1irq.vec (wrksp+&28)
jim 072.d3 Added t1irq.vec (wrksp+&2A)
jim 072.d3 Added t2irq.vec (wrksp+&2C)
jim 072.d3 Added txirq.vec (wrksp+&2E)
jim 072.d3 Added tyirq.vec (wrksp+&30)
jim 072.d3 Added s1rirq.vec (wrksp+&32)
jim 072.d3 Added s1rirq.vec (wrksp+&34)
jim 072.d3 Added s2irq.vec (wrksp+&36)
jim 072.d3 Added adcirq.vec (wrksp+&38)
jim 072.d3 Renamed JobCall DownloadData38 to DownloadData740
jim 072.d3 Renamed JobCall UploadData38 to UploadData740
jim 072.d3 Renamed JobCall ExecuteCode38 to ExecuteCode740
jim 072.d3 Renamed JobCall ReadByte38 to ReadByte740
jim 072.d3 Renamed JobCall StoreByte38 to StoreByte740
jim 072.d4 Hardware update
jim 072.d4 Re-assigned CallOS 37 to Write Power/Charge control
jim 072.d4 Re-assigned CallOS 38 to Read Power/Charge control
jim 072.d4 Moved int2irq.vec to wrksp+&22
jim 072.d4 Moved int3irq.vec to wrksp+&24
jim 072.d4 Moved int4irq.vec to wrksp+&26
jim 072.d4 Moved c0irq.vec to wrksp+&28
jim 072.d4 Moved c1irq.vec to wrksp+&2A
jim 072.d4 Moved t1irq.vec to wrksp+&2C
jim 072.d4 Moved t2irq.vec to wrksp+&2E
jim 072.d4 Moved txirq.vec to wrksp+&30
jim 072.d4 Moved tyirq.vec to wrksp+&32
jim 072.d4 Moved s1rirq.vec to wrksp+&34
jim 072.d4 Moved s1rirq.vec to wrksp+&36
jim 072.d4 Moved s2irq.vec to wrksp+&38
jim 072.d4 Moved adcirq.vec to wrksp+&3A
jim 072.d4 Added OS.LCDVDU (&FFB7) and lcdvdu.vec (wrksp+&20)
jim 072.d5 Re-assigned CallOS 37 to Write/Read Power/Charge control
jim 072.d5 Re-assgined CallOS 38 Read Battery Voltage
jim 072.d5 OS.CALLOS now re-entrant
jim 072.d5 Fixed OS.PRINTER
jim 072.d5 Started to add internal logging software
jim 072.d5 Moved OS.LCDVDU to &FFB6
jim 072.d7 Added OS.PRINTERPOLL (&FFB3) and printerpoll.vec (wrksp+&3C)
bob 073 Matched jim & bob sensor lookup tables
bob 073 Added PatchMF
jim 072.dj Added OS.CALLOS 51 Read keypad press
jim 072.dj Added hard reset keypad press
jim 072.dk Added JobCall ReadOutputs
jim 072.do Changed soft reset of zero page locations
jim 072.do Changed MotorForward/Backward bitmaps
jim 072.dp Fixed OS.CALLOS WriteRTCbcd
jim 072.dq Fixed OS.CALLOS ReadRTCstring for correct 24hr operation
jim 072.dr Changed reset prompts
bob 074 Added support for Little Bob
jim 072.dy Added further RTC/CMOS support
jim 072.dB Removed double hard reset
jim 072.dE Set _cpu.mode depending on external memory requirement
jim 072.dF Added Insight code
jim 073 Sub-release
jim 074 Modification to LCD code - uses bsy flag all the time now
jim 074 Fixed OS.CALLOS 42 Write LCD Char Def
jim 074 Fixed OS.CALLOS 43 Read LCD Char Def
jim 075 Added simple battery charge code
jim 075 Fixed JobCall ReadSensorTable
jim 075 Fixed OS.CALLOS 42 Write LCD Char Def
jim 075 Fixed OS.CALLOS 43 Read LCD Char Def
jim 075 Added sleep code
jim 075 Added OS.CALLOS 52 Write Sleep Time
jim 075 Added OS.CALLOS 53 Read Sleep Time
jim 075 Modified battery charge code
jim 076 Modified JobCall ReadSensorTable
jim 076 Modified OS.CALLOS 26 ReadKeypad to do debounce
jim 077 Rewrote battery charging code
jim 077.2 Reduced stop charge threshold to 2
jim 077.3 Increased stop charge threshold to 3
jim 077.3 Added battery voltage averaging
bill 077 Stripped
bill 077 Moved ins to out port
bill 077 Added RTS
bill 077 Changed sensor ID system back to original, using p2.1
bill 077 Dedicated USB/RS selection line, RTS provisioned on p2.3
bill 077 Overload "bounce" timing
bill 078 CTS added
bill 079 Temperature fudge</nowiki>

SmartBox OS

2023-11-04T17:38:21Z

Benryves: /* Example JobCall */ Tidied up formatting/indentation

== Documentation for SmartBox OS 2.066 ==

The term JobCall is the concept of the routine itself, as opposed to
JobName (which is the actual name associated with it (eg. NameCode)) and
JobCode (which is the actual number associated with it (eg. 3)).

The term controller means the SmartBox, or any other incarnation
which may appear in future time !

The term OS means the controllers' Operating System.

== Preview ==

There are a number of reasons why using Machine Code on the
controller is more desirable than using the various JobCalls via the serial
link. One reason is speed, if the task which needs to be performed, has to
be performed very quickly (more quickly than can be achieved via the serial
link at least), then some code must be written to work in the controller
itself to achieve this sort of speed. If the task required is to be a
"background" task (ie. a task which may happen while other "things" carry
on as normal, like a change of state of a particular port) then it is far
easier to let the controller do all the work, maybe under interupts, than
continuously poll the controller checking the state of various things.
Another reason may be that you would like to add another JobCall to the OS,
extending the calls available to external applications (and the user at the
same time), without the user having to write the code himself to achieve the
aim. For advanced users, there is also the ablity to alter the way the OS
does various things and to have the controller in their "power", for
dedicated tasks etc.

One advantage of writing IN the controller is that that "function"
is available to any computer using the serial link, and is thus not fixed to
one computer type or even a computer at all, where the controller is used
free running, doing a particular task which doesn't need the intervention of
the user's own computer.

== Call types ==

There are three different types of machine code routines which can
be added to the controller. Each one is suited to a more advanced level
than the other, which also relates to the amount of work needed to actually
get the routine working ! The three levels are such:

=== Simple stand alone routine ===

Here the routine is just the routine
itself with no supporting code (ie. code to integrate with the rest of the
OS). It has to be called directly, by use of the ExecuteCode JobCall, thus
it usually resides at a fixed address and obviously does not offer the user
friendly way of accessing itself like there is with normal OS calls.

=== Extended JobCall ===

There is one JobCall in the OS (ExtendJob)
which can call various routines residing in memory, each one is identified
by a 8 bit number. The disadvantages of this way is that the call hasn't
got it's own JobName/JobCode and needs the extra byte to identify itself.
This is ideal for the quick routine which the user would like to add for
himself without having to resort to the extra code needed for the full
JobCode implementation.

=== Full JobCall ===

This is where the routine can define itself one
(or a number) of JobNames/JobCodes, it can integrate itself into an
extension of the OS in a complete way. The disadvantage is that extra
coding is needed to deal with the various OS calls it has to service and
that extra work is needed to produce a suitable file to place in the
controller.

Normally with most processors, including the 65c02, the machine code
produced is produced for a fixed memory address, and it cannot be made to
run in a different place in memory unless extra work is carried out by the
user, or at least a combination of the user and the OS. For the controller
this is a very severe disadvantage as most extensions are downloaded as
"modules" and to optimise memory a system has to be devised to enable
routines to be placed anywhere in memory, thus allowing no memory to be
wasted. In the OS there is a routine to do just this, though it does need
some help. A special version of the users code has to be developed, or
rather it has to be "processed" to add extra information on the end. Extra
code is needed to set up a few pointers and call the OS routine to relocate.
See later.

== Memory ==

The first 256 bytes of memory are somewhat special, most zero page
locations are reserved for use by the OS:

{|class="wikitable"
|-
|&00-&14||General workspace, used to pass parameters to some OS routines, can also be used by other routines DURING their execution.
|-
|&15-&6F||Reserved
|-
|&70-&9F||Available to the user
|-
|&A0||Accumulator store for irqs (irq_A)
|-
|&A1-&A2||Two byte counter, decremented at 100hz, useful for temporary timing purposes (fcount)
|-
|&A3||RAM size, high byte of RAM size of machine, ie. for 32k this will be &80 (RAM_size)
|-
|&A4-&AF||Reserved
|-
|&B0-&FF||Used by the OS
|-
|}

The rest of memory space is used for the processors stack, OS'
buffers, tables, vectors and, of course, the user available memory.

A breakdown of the rest of memory:

* &100 to &1FF is the 65c02's stack.
* &200-&2FF is used by the OS for various system functions and also contains the vector table, more on that later.
* &300-&3FF is the serial input buffer.
* &400-&47F is the internal job code call output buffer. (jobout_buf)
* &480-&4FF is the internal job code call input buffer. (jobin_buf)
* &500-&5FF is the job status table.
* &600 to the end of RAM memory is for the user. The user should not assume what the top of AVAILABLE memory is and use the system variable HIMEM.

In the controller the maximum limit of RAM is &8000 (which is 32k),
from &8000-&DFFF lies the memory mapped hardware, from &E000 to &FFF9 lies
the OS and from &FFFA to &FFFF lies the 65c02 vectors.

So the user has his own limits of free memory. The lowest limit is
called LOMEM and the highest limit is called HIMEM, everything between these
boundaries is termed "available" for use by anyone, the user or the OS.

Anyone can also claim memory, thus making private to them and not allowing
anyone else to use it. You do this by altering the value of LOMEM, HIMEM
should not be moved. Of course anyone claiming memory should first check
that there is enough memory available for the amount they want to claim for.
To take a common example, a downloadable routine which installs itself as a
extension routine, The download routine will first of all read LOMEM, read
HIMEM, check there is enough memory for the routine, download it to LOMEM
and call it, the downloaded routine will then relocate itself and alter
LOMEM so it is protected.

There is one other memory limit, this is called TOPMEM, this is the
absolute top limit of RAM, HIMEM will normally equal TOPMEM, but a future OS
may alter HIMEM to below TOPMEM. TOPMEM should be ignored ideally, and
HIMEM used.

== OS Calls ==

The OS has calls (ie. a jump instruction which you call, which
then calls, via a RAM vector, a routine in the OS) setup near the top of
memory, through these calls you do everything associated with the
controller. The calls are are such:

* OS_PRINTER at address &FFB9
* OS_CALLOS at address &FFBC
* OS_SENDBYTE at address &FFBF
* OS_READBYTE at address &FFC2
* OS_SENDJOB at address &FFC5
* OS_READJOB at address &FFC8
* OS_DECODEJOB at address &FFCB

The address is the one to call for the particular routine.

* OS_PRINTER is reserved for future use.
* OS_CALLOS calls upon the OS to do various things internally.
* OS_SENDBYTE sends a byte out of the serial port.
* OS_READBYTE reads a byte from the serial port.
* OS_SENDJOB 'sends' a value to the JobCall caller.
* OS_READJOB 'reads' a value from the JobCalls caller.
* OS_DECODEJOB decodes the Job number held in A and acts on it.

Note none of these things should be used in interupt routines,
except OS_CALLOS, of any sort, except if YOU know what state the machine is
in and WHY.

=== OS_READBYTE and OS_SENDBYTE: Serial Port ===

The serial port on the controller is currently based on the 6850
UART, this need not bother you as the OS deals with the thing entirely by
itself. The chip is setup by the OS to always have a word format of 8n1 and
a baud rate of 9600, this translates to 960cps. The 6850 has two divide
rates for the baud rate, the OS only uses one, using the other one is beyond
the scope of this document and shouldn't be neccessary to use.

Only receive interupts are used, transmission of characters is done
on a polled basis.

As said, there are two calls OS_READBYTE and OS_SENDBYTE.

==== OS_READBYTE ====

OS_READBYTE tests the serial input buffer and returns the character (if any
in the A register), the c flag states whether there was a character
returned.

{|class="calltable"
|Entry||
A, X, Y, c, z = undefined
|-
|Exit||
* X, Y preserved
* z = undefined
* if c = 1 (no character received)
*: A is preserved
* if c = 0 (character received)
*: A = character received
|}

==== OS_SENDBYTE ====

OS_SENDBYTE sends the character in the A register out of the serial
port, taking into consideration flow control etc.

{|class="calltable"
|Entry||
* A = character to send
* X, Y, c, z = undefined
|-
|Exit||
* A, X, Y, c is preserved
* z = undefined
|}

=== OS_READJOB and OS_SENDJOB ===

To send/receive data from the user (either internally or via the
serial port) you call OS_SENDJOB/OS_READJOB for the next byte. If your
JobCall requires dynamic use of data, ie. interaction, then a check of the
enviroment should be done to check the call came from the serial port. One
example of this is the OS JobCall MultipleServer, which requires dynamic use
of sending a stream of data until a reaction from the user to tell it to
stop.

==== OS_READJOB: Read job value from the user ====

{|class="calltable"
|Entry||
* A, X, Y, c, z = undefined
|-
|Exit||
* A = byte read
* X, Y is preserved
* c, z = undefined
|-
|Note||
When coming from the serial port it waits for a character to be received, if you are doing a serial only call and wish to have a loop checking for a character from the user while doing "your own thing", then OS_READBYTE should be used. For internal calls this reads data out of jobin_buf.
|}

==== OS_SENDJOB: Give a job value back to the user ====

{|class="calltable"
|Entry||
* A = byte to give
* X, Y, c, z = undefined
|-
|Exit||
* A, X, Y is preserved
* c, z = undefined
|-
|Note||
This will send either out to the serial port or place a byte in jobout_buf.
For internal calls this stores the value in jobout_buf, which is allocated 128 bytes, no bound checking is done so sending more than 128 bytes to OS_SENDJOB will cause corruption of some memory.
|}

=== OS_DECODEJOB ===

JobCalls in practise are really only used by the user, JobCalls
tend not to call other calls at all, infact you shouldn't really call
another call unless you were called from the serial port. If you do need to
call another JobCall then you do it like this; with each call you have
associated with it a number, and the call might require some data or give
some data back or both. With the serial port this is simple, you just send
data down and receive data as it is produced. You can't do this with
internal calls, and some calls will not let you call them from inside the
controller, you HAVE to call them from outside. But for the ones which do
let you, you do it with two data blocks, one for input TO the call and one
for output FROM the call. These are setup in a position in memory
(jobin_buf and jobout_buf), each one has a maximum of 128 bytes and this
should not be overflowed (OS_READJOB and OS_SENDJOB do NOT do any bound
checking). So to start with you place in the input block the data you want
to give the call (if any), call it, and then act on the data in the output
block (if any). The OS call OS_DECODEJOB is the one which actually calls
the JobCall handler and eventually the actual routine, you tell the JobCall
handler which call you want by placing the JobCode in the A register.

So for OS_DECODEJOB:

{|class="calltable"
|Entry||
* A = JobCode
* X, Y, c, z = undefined
* jobin_buf should contain any input data
|-
|Exit||
* A = flag
* X = number of bytes given back by routine
* Y = undefined
* c = status, if set JobCall does not exist
* z = status, if set JobCall cannot be called internally
* jobout_buf contains any data sent from routine
|}

A typical example would be:

<nowiki> LDA #readhimem ; JobCode for ReadHimem
JSR OS_DECODEJOB ; Call the JobCall handler
LDX jobout_buf ; Read HIMEM from buffer LSB
LDY jobout_buf+1 ; Read HIMEM from buffer MSB
STX jobin_buf ; Place LSB in input buffer
STY jobin_buf+1 ; Place MSB in input buffer
LDA #writelomem ; JobCode for WriteLomem
JSR OS_DECODEJOB ; Call the JobCall handler</nowiki>

which would read HIMEM, and then write LOMEM to be the same value, leaving
no spare memory left.

The reason why you should not call an internal call from another
internal call is that the same buffers (jobin_buf and jobout_buf) would be
used for both calls, causing conflict between the two calls, or rather to
the originator of the primary call ! The only time it would be safe if is
if you have already got all the data you want from jobin_buf and haven't
placed any in the jobout_buf (it would be lost if you had done).

=== 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.
|}

=== OS_PRINTER: Place a character in the printer buffer ===

{|class="calltable"
|Entry||
* A = character to send
* X, Y, c, z = undefined
|-
|Exit||
* A, X, Y is preserved
* if c = 0 (printed)
*: The printer is on and the character was inserted
* if c = 1 (not printed)
*: The printer is off and the character was forgotten
* z = undefined
|-
|Note||
The character goes into the printer buffer and will be
actually sent to the printer when the printer asks for it. If the printer
was not awake to begin with, an attempt is made to wake it up, thus
meaning that in some circumstances when the printer wasn't ready a
character may be lost, this cannot be helped. If the printer is off (via
the BCD switch) then the character will be forgotten as the Printer Buffer
is inactive.
|}

== 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
|}

== Starting Up ==

The setup procedure for setting up extension job calls is to:

# Claim the number of JobCodes you want
#: if success:
# patch the internal_vec and unknownjob_vec vectors
# move LOMEM up to protect your program
# do anything else for initial startup you may want to do
# return back, ready and waiting

This in code looks like:

<nowiki>execute
LDX #no_of_calls ; Number of JobCodes wanted
LDA #1 ; CALLOS, function 1, Claim JobCodes
JSR OS_CALLOS ; Call CALLOS
CPX #0 ; Check we were given some codes
BEQ noinstall ; No, don't bother installing ourself
STX call ; Store base address of JobCodes allocated
STY job_id ; Store JOB ID given

LDA internal_vec ; Get old internal_vec (LSB)
STA ovec ; Store it
LDA internal_vec+1 ; Get old internal_vec (MSB)
STA ovec+1 ; Store it
LDA #>internal_handle ; Our internal handler (LSB)
STA internal_vec ; Place it in the vector (LSB)
LDA #<internal_handle ; Our internal handler (MSB)
STA internal_vec+1 ; Place it in the vector (MSB)

LDA unknownjob_vec ; Get old unknownjob_vec (LSB)
STA ovec2 ; Store it
LDA unknownjob_vec+1 ; Get old unknownjob_vec (MSB)
STA ovec2+1 ; Store it
LDA #>job_handle ; Our unknown job handler (LSB)
STA unknownjob_vec ; Place it in the vector (LSB)
LDA #<job_handle ; Our unknown job handler (MSB)
STA unknownjob_vec+1 ; Place it in the vector (MSB)

LDX #>WriteLomem ; Point to JobName
LDY #<WriteLomem
JSR findjob ; Find WriteLomem code
BEQ noinstall ; Doesn't exist !
LDX #>end_of_code ; End of code (LSB)
LDY #<end_of_code ; End of code (MSB)
STX jobin_buf ; Place it in jobin_buf (LSB)
STY jobin_buf+1 ; Place it in jobin_buf+1 (MSB)
JSR OS_DECODEJOB ; Call JobCall handler

noinstall
RTS ; End - return to OS

findjob
STX zero.gp1 ; Zero page
STY zero.gp1+
LDY #0
findthisjoblo
LDA (zero.gp1),Y
STA jobin.buf,Y ; Store name in jobin_buf
INY
CMP #13
BNE findthisjoblo
LDA #3 ; NameCode
JSR OS.DECODEJOB ; Call NameCode
LDA jobout.buf ; Get returned value
RTS

WriteLomem STR "WriteLomem"</nowiki>

This will setup the various vectors and memory pointers for the
applicaion, the actual routines (internal_handle and job_handle) are fairly
straight forward and simple:

<nowiki>internal_handle
CMP #1 : Is it function call 1 (NameCode) ?
BNE internal_handle_2 ; No, check for function 2
LDA job_id ; Get our JOB ID number
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #>job_names ; Our Job name table (LSB)
LDY #<job_names ; Our Job name table (MSB)
LDA #2 ; CALLOS function 2
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes : Found, go off and claim call
LDA #1 ; Not found, restore A
JMP (ovec) ; Call back to old vector

internal_handle_2
CMP #2 ; Is it function call 2 (CodeName) ?
BNE internal_handle_3 ; No, unknown, pass on
LDA job_id ; Get our JOB ID
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #>job_names ; Our Job name table (LSB)
LDY #<job_names ; Our Job name table (MSB)
LDA #3 ; CALLOS function 3
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes ; Found, go off and claim call
LDA #2 ; Not found, restore A
JMP (ovec) ; Call back to old vector

internal_yes
LDA #0 ; We want to claim call for some reason

internal_handle_3
JMP (ovec) ; Call back to old vector

job_handle
PHA ; Mark sure to preserve A
CPY call ; Check call wanted against base of ours
BCC job_handle_no ; Less than our base, so definately not ours
TYA
SBC #no_of_calls ; Subtract number of calls we have
CMP call ; Now compare with base
BCC job_handle2 ; Yes, one of ours

job_handle.no
PLA ; Restore A
JMP (ovec2) ; Call back to old vector

job_handle2
TYA
SEC
SBC call ; Subtract our base from call
ASL A ; Times by 2 for offset into table
TAY ; Place in Y
LDA job_run_table,Y ; Get LSB of routine
STA zero_gp1 ; Store it for indirect jump (LSB)
LDA job_run_table+1,Y ; Get MSB of routine
STA zero_gp1+1 ; Store it for indirect jump (MSB)
PLA ; Restore A
JMP (zero_gp1) ; Call our relevant routine

job_names ; List of our JobNames
STR "TestJob" ; Test job name
DFB &FF ; &FF - marks end of table

job_run_table ; List of routine addresses to match Jobs
DFW job_TestJob ; Test job routine</nowiki>

== Relocation ==

The relocation method used will not do a complete relocation, ie.
from ANY address to ANY address. The only constraint on the addresses is
that they must be the same offset in the page, which means, &2602 and &3402
is alright but &2602 and &3455 is not, ie. the difference between the two
addresses must be a multiple of 256 bytes, as only the MSB is altered, this
should not cause any real problems. What is meant by the two addresses is
the address the code was originally assembled at and the address it wants
relocating to. Because of this programs must be multiples of 256 bytes, ie.
the low byte of LOMEM must ALWAYS be 0, your program should be padded out.

The relocation mechanism works by having a table, and to each byte
of code there is one BIT, if unset it means the byte of code should not be
relocated, else it should be, thus the BitMap table is 8 times smaller than
the code. To generate the BitMap you have to assemble the code at two
different places, and compare both sets of assembled code against each
other, the differences are where the code is to be relocated. The code
which is sent up to the controller is assumed to be assembled at address
&100, so the first code should be assembled at &100, the other one should be
assembled at another address, say &600, and the first one be sent up with
the BitMap. A program is availble for the Elk/Beeb/Arc with 65Tube/Mac with
BBC BASIC to compare the two files and create the BitMap.

All the program has to do to relocate itself is execute this bit of
code first of all: (address is the base address of the program, ie. &100
for the downloaded version)

<nowiki>execcall
LDA #>(execute-address) ; Final execution address offset (LSB)
STA zero_gp1
LDA #<(execute-address) ; Final execution address offset (MSB)
STA zero_gp1+1

LDA #>(BitMap-address) ; BitMap address offset (LSB)
STA zero_gp2
LDA #<(BitMap-address) ; BitMap address offset (MSB)
STA zero_gp2+1

LDA #>(execcall-address); Length of data to relocate (LSB)
STA zero_gp3
LDA #<(execcall-address); Length of data to relocate (MSB)
STA zero_gp3+1

TXA ; Execcall REAL address
SEC
SBC #>(execcall-address); Subrtract length
TAX ; Put it back in X
TYA ; Ditto for MSB
SBC #<(execcall-address)
TAY
LDA #4 ; CALLOS function for Relocate
JMP OS_CALLOS ; Call CALLOS

BitMap ; BitMap start</nowiki>

This will relocate the code and automatically call the execution
address, which should be the initialisation code (ie. setup internal_vec
and unknownjob_vec etc.). "address" is the address the code is started to
assemble at, &100 for the version to be uploaded. The upload routine should
pass in X and Y (via ExecuteCode) the address of the start of execcall, this
means that the routine can tell where it is in memory, subtracting the
length gives the start of the code to relocate.

== Layout Summary ==

The layout of a full application should be like this by now:

<nowiki> start of code
program job codes, data etc.
internal handler
job handler
end of code
initialisation (setup internal etc.)
end of code to be relocated
execution (relocation)
relocation BitMap</nowiki>

Because of memory space the initialisation code should be placed
outside the reserved memory limit of the program, as it is only called once
and not needed again.

== Modules ==

The module is located at &8000 in memory, and should be a EPROM placed
in the second ROM socket in the controller (ie. the top RAM socket). This
module is primary designed to turn the Controller into a dedicated task,
making it perform some function from switch on. It could also be used to
add more permant JobCalls to the Controller, in the process taking up much
less RAM), but because of there being only one Module present this feature
is limited, and is much more suited to a collection of the user's own
personal routines.

For the OS to recognise a module as being in place the text "Module" is
looked for, the layout of a module should be like this (starting at
&8000):

<nowiki>Offset value comment
0 "Module" The OS checks for this string
6 0 End of check string
7 Language entry Address of 'Language' entry
9 Service entry Address of 'Service' entry
11 "<Module Title>" Module title
0 End of Module title

"<Module part>" Part Module Title
0 End of Part Module Title
"x.xx" Part version number

&FF End of parts list</nowiki>

The language entry is a 2 byte value holding the address of the language
entry routine, this is called on reset, if the BCD is set correctly. A
value of less than &8000 means there is no valid language entry and any
language calls are ignored. If a RTS is made the OS carries on as it would
have if there wasn't a language call.

The service entry is a 2 byte value holding the address of the service
entry routine, this is called at various appropiate moments with service
numbers in A. A list of current calls is thus:

<nowiki> 0 - Not used
1 - Unknown Job Code
2 - Centisecond call
3 - Irq2 (unknown IRQ)
4 - internal_vec call (exit with A=0 to claim)
254 - RESET
255 - BRK</nowiki>

On exit all registers and flags should be preserved. For call 1 the
unknown job value is held in the Y register, the enviroment is held in the
X register, on exit, X should contain the flag, as A does from the exit of
unknownjob_vec. For the rest of calls, X and Y are undefined.

For both Service and Language entry points, a value of 0 means "there is
no valid routine" and the module isn't called for that type of entry.

== Example JobCall ==

Finally a full implementation of a JobCall, from start to finish.

<nowiki>DIM data% &1000
:
no_of_calls = 1
:
VIA = &E030
ACIA = &E010
ADC = &E000
AUX_PORT = &E020
brk_vec = &200
nmi_vec = &202
irq_vec = &204
irq2_vec = &206
sendserial_vec = &208
readserial_vec = &20A
sendjob_vec = &20C
readjob_vec = &20E
decodejob_vec = &210
unknownjob_vec = &212
extjob_vec = &214
centisec_vec = &216
internal_vec = &218
callos_vec = &21A
printer_vec = &21C
zero_gp1 = 0
zero_gp2 = 2
zero_gp3 = 4
zero_gp4 = 6
zero_gp5 = 8
zero_gp6 = 10
zero_gp7 = 12
zero_gp8 = 14
zero_gp9 = 16
zero_gp10 = 18
user_reserved = &70
irq_A = &A0
fcount = &A1
RAM_size = &A3
jobout_buf = &400
jobin_buf = &480
OS_PRINTER = &FFB9
OS_CALLOS = &FFBC
OS_SENDBYTE = &FFBF
OS_READBYTE = &FFC2
OS_SENDJOB = &FFC5
OS_READJOB = &FFC8
OS_DECODEJOB = &FFCB
:
FOR create=1 TO 2
:
FOR pass%=4 TO 7 STEP 3
P%=&100*create : O%=data%
[OPT pass%
:
.job_DemoJob
CMP #1
BEQ DemoJob_go
LDA #1
LDY #0
RTS
/
.DemoJob_go

:
.internal_handle
CMP #1; Is it function call 1 (NameCode) ?
BNE internal_handle_2; No, check for function 2
/
LDA job_id; Get our JOB ID number
STA zero_gp3; Place it in zero_gp3 for CALLOS
LDX #job_names MOD 256; Our Job name table (LSB)
LDY #job_names DIV 256; Our Job name table (MSB)
LDA #2; CALLOS function 2
JSR OS_CALLOS; Call CALLOS
BCC internal_yes; Found, go off and claim call
LDA #1; Not found, restore A
JMP (ovec); Call back to old vector
/
.internal_handle_2
CMP #2; Is it function call 2 (CodeName) ?
BNE internal_handle_3; No, unknown, pass on
/
LDA job_id; Get our JOB ID
STA zero_gp3; Place it in zero_gp3 for CALLOS
LDX #job_names MOD 256; Our Job name table (LSB)
LDY #job_names DIV 256; Our Job name table (MSB)
LDA #3; CALLOS function 3
JSR OS_CALLOS; Call CALLOS
BCC internal_yes; Found, go off and claim call
LDA #2; Not found, restore A
JMP (ovec); Call back to old vector
/
.internal_yes
LDA #0; We want to claim call for some reason
/
.internal_handle_3
JMP (ovec); Call back to old vector
:
.job_handle
PHA; Make sure to preserve A
CPY call; Check call wanted against base of ours
BCC job_handle_no; Less than our base, so definately not ours
TYA
SBC #no_of_calls; Subtract number of calls we have
CMP call; Now compare with base
BCC job_handle2; Yes, one of ours
/
.job_handle.no
PLA; Restore A
JMP (ovec2); Call back to old vector
/
.job_handle2
TYA
SEC
SBC call; Subtract our base from call
ASL A; Times by 2 for offset into table
TAY; Place in Y
LDA job_run_table,Y; Get LSB of routine
STA zero_gp1; Store it for indirect jump (LSB)
LDA job_run_table+1,Y; Get MSB of routine
STA zero_gp1+1; Store it for indirect jump (MSB)
PLA; Restore A
JMP (zero_gp1); Call our relevant routine
:
.job_names; List of our JobNames
EQUS "DemoJob":EQUB 13; Test job name
/
EQUB &FF; &FF - marks end of table
:
.job_run_table; List of routine addresses to match Jobs
EQUW job_DemoJob; Test job routine
:
.call : EQUB 0; Store for our JobCode base
.job_id : EQUB 0; Store for our JobId
.ovec : EQUW 0; Store for old internal_vec value
.ovec2 : EQUW 0; Store for old unknownjob_vec value
:
EQUS STRING$(&100-(P% MOD 256),CHR$0)
.end_of_code; end_of_code should be on page boundry
:
.execute
LDX #no_of_calls; Number of JobCodes wanted
LDA #1; CALLOS, function 1, Claim JobCodes
JSR OS_CALLOS; Call CALLOS
STX call; Store base address of JobCodes allocated
STY job_id; Store JOB ID given
CPX #0; Check we were given some codes
BEQ noinstall; No, don't bother installing ourself
/
LDA internal_vec; Get old internal_vec (LSB)
STA ovec; Store it
LDA internal_vec+1; Get old internal_vec (MSB)
STA ovec+1; Store it
LDA #internal_handle MOD 256; Our internal handler (LSB)
STA internal_vec; Place it in the vector (LSB)
LDA #internal_handle DIV 256; Our internal handler (MSB)
STA internal_vec+1; Place it in the vector (MSB)
/
LDA unknownjob_vec; Get old unknownjob_vec (LSB)
STA ovec2; Store it
LDA unknownjob_vec+1; Get old unknownjob_vec (MSB)
STA ovec2+1; Store it
LDA #job_handle MOD 256; Our unknown job handler (LSB)
STA unknownjob_vec; Place it in the vector (LSB)
LDA #job_handle DIV 256; Our unknown job handler (MSB)
STA unknownjob_vec+1; Place it in the vector (MSB)
/
LDX #end_of_code MOD 256; End of code (LSB)
LDY #end_of_code DIV 256; End of code (MSB)
STX jobin_buf; Place it in jobin_buf (LSB)
STY jobin_buf+1; Place it in jobin_buf+1 (MSB)
LDA #65; JobCode for WriteLomem
JSR OS_DECODEJOB; Call JobCall handler
/
.noinstall
RTS; End - return to OS
:
.execcall
LDA #>(execute-address); Final execution address offset (LSB)
STA zero_gp1
LDA #<(execute-address); Final execution address offset (MSB)
STA zero_gp1+1
/
LDA #>(BitMap-address); BitMap address offset (LSB)
STA zero_gp2
LDA #<(BitMap-address); BitMap address offset (MSB)
STA zero_gp2+1
/
LDA #>(execcall-address); Length of data to relocate (LSB)
STA zero_gp3
LDA #<(execcall-address); Length of data to relocate (MSB)
STA zero_gp3+1
/
TXA; Execcall REAL address
SEC
SBC #>(execcall-address); Subtract length
TAX; Put it back in X
TYA; Ditto for MSB
SBC #<(execcall-address)
TAY
LDA #4; CALLOS function for Relocate
JMP OS_CALLOS; Call CALLOS
/
.BitMap; BitMap start
:
]
NEXT
:
OSCLI "SAVE code"+STR$create+" "+STR$~data%+" "+STR$~O%
:
NEXT</nowiki>

== Changelog ==

<nowiki>bob 071 Fixed MotorForward bug (%10)
bob 072 CallOS 14 now checks current adc.owner status
jim 072.d1 * Rewrite for new hardware/processor *
jim 072.d1 Moved vectors/workspace to &440
jim 072.d1 Moved rs.inp.buf to &500
jim 072.d1 Moved jobout.buf to &600
jim 072.d1 Moved jobin.buf to &680
jim 072.d1 Moved jobs.status to &700
jim 072.d1 Added irq.X (&A4)
jim 072.d1 Added irq.Y (&A5)
jim 072.d1 Removed short detection code
jim 072.d1 Voided CallOS' 6,7,8,9,10,11,13,16,17,18,19
jim 072.d1 Removed JobCalls ReadADCReg,WriteADCReg
jim 072.d1 Removed JobCalls ReadACIAReg,WriteACIAReg
jim 072.d1 Removed JobCalls ReadVIAReg,WriteVIAReg,SetVIAHigh,SetVIALow
jim 072.d1 Added CallOS 21 Write Outputs
jim 072.d1 Added CallOS 22 Read Outputs added
jim 072.d1 Added CallOS 23 Read Inputs added
jim 072.d1 Added CallOS 24 Write Motors
jim 072.d1 Added CallOS 25 Read Motors
jim 072.d1 Added CallOS 26 Read Keypad
jim 072.d1 Expanded CallOS 5 information
jim 072.d1 Added JobCall IdentSystem to return CallOS 5 info
jim 072.d1 JobCalls now use appropriate CallOS'
jim 072.d1 OS.READBYTE no longer preserves A on CS
jim 072.d1 irq.vec,irq2.vec,nmi.vec now redundant
jim 072.d1 Renamed JobCall DownloadData to DownloadData38
jim 072.d1 Renamed JobCall UploadData to UploadData38
jim 072.d1 Renamed JobCall ExecuteCode to ExecuteCode38
jim 072.d1 Renamed JobCall ReadByte to ReadByte38
jim 072.d1 Renamed JobCall StoreByte to StoreByte38
jim 072.d1 JobCall ForcedADCRead now checks adc.owner first
jim 072.d3 Added CallOS 27 Write printer
jim 072.d3 Added CallOS 28 Read printer
jim 072.d3 Added CallOS 29 Write RTC Reg
jim 072.d3 Added CallOS 30 Read RTC Reg
jim 072.d3 Added CallOS 31 Write RTC string
jim 072.d3 Added CallOS 32 Read RTC string
jim 072.d3 Added CallOS 33 Write RTC bcd
jim 072.d3 Added CallOS 34 Read RTC bcd
jim 072.d3 Added CallOS 35 Write LCD Reg
jim 072.d3 Added CallOS 36 Read LCD Reg
jim 072.d3 Added JobCall WritePrinter
jim 072.d3 Added JobCall ReadPrinter
jim 072.d3 Added JobCall PrintChar
jim 072.d3 Added JobCall PrintStreamZ
jim 072.d3 Added JobCall PrintStream
jim 072.d3 Added JobCall PrintServer
jim 072.d3 Added JobCall WriteRTCReg
jim 072.d3 Added JobCall ReadRTCReg
jim 072.d3 Added JobCall WriteRTC
jim 072.d3 Added JobCall ReadRTC
jim 072.d3 Added JobCall WriteRTCbcd
jim 072.d3 Added JobCall ReadRTCbcd
jim 072.d3 Added JobCall WriteLCDReg
jim 072.d3 Added JobCall ReadLCDReg
jim 072.d3 Added CallOS 37 Write Power ctrl
jim 072.d3 Added CallOS 38 Read Power ctrl
jim 072.d3 Implemented OS.PRINTER
jim 072.d3 Added JobCall PatchMF (MotorForward)
jim 072.d3 Changed irq.vec to int0.vec
jim 072.d3 Changed irq2.vec to int1.vec
jim 072.d3 Added int2irq.vec (wrksp+&20)
jim 072.d3 Added int3irq.vec (wrksp+&22)
jim 072.d3 Added int4irq.vec (wrksp+&24)
jim 072.d3 Added c0irq.vec (wrksp+&26)
jim 072.d3 Added c1irq.vec (wrksp+&28)
jim 072.d3 Added t1irq.vec (wrksp+&2A)
jim 072.d3 Added t2irq.vec (wrksp+&2C)
jim 072.d3 Added txirq.vec (wrksp+&2E)
jim 072.d3 Added tyirq.vec (wrksp+&30)
jim 072.d3 Added s1rirq.vec (wrksp+&32)
jim 072.d3 Added s1rirq.vec (wrksp+&34)
jim 072.d3 Added s2irq.vec (wrksp+&36)
jim 072.d3 Added adcirq.vec (wrksp+&38)
jim 072.d3 Renamed JobCall DownloadData38 to DownloadData740
jim 072.d3 Renamed JobCall UploadData38 to UploadData740
jim 072.d3 Renamed JobCall ExecuteCode38 to ExecuteCode740
jim 072.d3 Renamed JobCall ReadByte38 to ReadByte740
jim 072.d3 Renamed JobCall StoreByte38 to StoreByte740
jim 072.d4 Hardware update
jim 072.d4 Re-assigned CallOS 37 to Write Power/Charge control
jim 072.d4 Re-assigned CallOS 38 to Read Power/Charge control
jim 072.d4 Moved int2irq.vec to wrksp+&22
jim 072.d4 Moved int3irq.vec to wrksp+&24
jim 072.d4 Moved int4irq.vec to wrksp+&26
jim 072.d4 Moved c0irq.vec to wrksp+&28
jim 072.d4 Moved c1irq.vec to wrksp+&2A
jim 072.d4 Moved t1irq.vec to wrksp+&2C
jim 072.d4 Moved t2irq.vec to wrksp+&2E
jim 072.d4 Moved txirq.vec to wrksp+&30
jim 072.d4 Moved tyirq.vec to wrksp+&32
jim 072.d4 Moved s1rirq.vec to wrksp+&34
jim 072.d4 Moved s1rirq.vec to wrksp+&36
jim 072.d4 Moved s2irq.vec to wrksp+&38
jim 072.d4 Moved adcirq.vec to wrksp+&3A
jim 072.d4 Added OS.LCDVDU (&FFB7) and lcdvdu.vec (wrksp+&20)
jim 072.d5 Re-assigned CallOS 37 to Write/Read Power/Charge control
jim 072.d5 Re-assgined CallOS 38 Read Battery Voltage
jim 072.d5 OS.CALLOS now re-entrant
jim 072.d5 Fixed OS.PRINTER
jim 072.d5 Started to add internal logging software
jim 072.d5 Moved OS.LCDVDU to &FFB6
jim 072.d7 Added OS.PRINTERPOLL (&FFB3) and printerpoll.vec (wrksp+&3C)
bob 073 Matched jim & bob sensor lookup tables
bob 073 Added PatchMF
jim 072.dj Added OS.CALLOS 51 Read keypad press
jim 072.dj Added hard reset keypad press
jim 072.dk Added JobCall ReadOutputs
jim 072.do Changed soft reset of zero page locations
jim 072.do Changed MotorForward/Backward bitmaps
jim 072.dp Fixed OS.CALLOS WriteRTCbcd
jim 072.dq Fixed OS.CALLOS ReadRTCstring for correct 24hr operation
jim 072.dr Changed reset prompts
bob 074 Added support for Little Bob
jim 072.dy Added further RTC/CMOS support
jim 072.dB Removed double hard reset
jim 072.dE Set _cpu.mode depending on external memory requirement
jim 072.dF Added Insight code
jim 073 Sub-release
jim 074 Modification to LCD code - uses bsy flag all the time now
jim 074 Fixed OS.CALLOS 42 Write LCD Char Def
jim 074 Fixed OS.CALLOS 43 Read LCD Char Def
jim 075 Added simple battery charge code
jim 075 Fixed JobCall ReadSensorTable
jim 075 Fixed OS.CALLOS 42 Write LCD Char Def
jim 075 Fixed OS.CALLOS 43 Read LCD Char Def
jim 075 Added sleep code
jim 075 Added OS.CALLOS 52 Write Sleep Time
jim 075 Added OS.CALLOS 53 Read Sleep Time
jim 075 Modified battery charge code
jim 076 Modified JobCall ReadSensorTable
jim 076 Modified OS.CALLOS 26 ReadKeypad to do debounce
jim 077 Rewrote battery charging code
jim 077.2 Reduced stop charge threshold to 2
jim 077.3 Increased stop charge threshold to 3
jim 077.3 Added battery voltage averaging
bill 077 Stripped
bill 077 Moved ins to out port
bill 077 Added RTS
bill 077 Changed sensor ID system back to original, using p2.1
bill 077 Dedicated USB/RS selection line, RTS provisioned on p2.3
bill 077 Overload "bounce" timing
bill 078 CTS added
bill 079 Temperature fudge</nowiki>

SmartBox OS

2023-11-04T17:33:13Z

Benryves: Moved OS_PRINTER into OS Calls section and added header to Modules description

== Documentation for SmartBox OS 2.066 ==

The term JobCall is the concept of the routine itself, as opposed to
JobName (which is the actual name associated with it (eg. NameCode)) and
JobCode (which is the actual number associated with it (eg. 3)).

The term controller means the SmartBox, or any other incarnation
which may appear in future time !

The term OS means the controllers' Operating System.

== Preview ==

There are a number of reasons why using Machine Code on the
controller is more desirable than using the various JobCalls via the serial
link. One reason is speed, if the task which needs to be performed, has to
be performed very quickly (more quickly than can be achieved via the serial
link at least), then some code must be written to work in the controller
itself to achieve this sort of speed. If the task required is to be a
"background" task (ie. a task which may happen while other "things" carry
on as normal, like a change of state of a particular port) then it is far
easier to let the controller do all the work, maybe under interupts, than
continuously poll the controller checking the state of various things.
Another reason may be that you would like to add another JobCall to the OS,
extending the calls available to external applications (and the user at the
same time), without the user having to write the code himself to achieve the
aim. For advanced users, there is also the ablity to alter the way the OS
does various things and to have the controller in their "power", for
dedicated tasks etc.

One advantage of writing IN the controller is that that "function"
is available to any computer using the serial link, and is thus not fixed to
one computer type or even a computer at all, where the controller is used
free running, doing a particular task which doesn't need the intervention of
the user's own computer.

== Call types ==

There are three different types of machine code routines which can
be added to the controller. Each one is suited to a more advanced level
than the other, which also relates to the amount of work needed to actually
get the routine working ! The three levels are such:

=== Simple stand alone routine ===

Here the routine is just the routine
itself with no supporting code (ie. code to integrate with the rest of the
OS). It has to be called directly, by use of the ExecuteCode JobCall, thus
it usually resides at a fixed address and obviously does not offer the user
friendly way of accessing itself like there is with normal OS calls.

=== Extended JobCall ===

There is one JobCall in the OS (ExtendJob)
which can call various routines residing in memory, each one is identified
by a 8 bit number. The disadvantages of this way is that the call hasn't
got it's own JobName/JobCode and needs the extra byte to identify itself.
This is ideal for the quick routine which the user would like to add for
himself without having to resort to the extra code needed for the full
JobCode implementation.

=== Full JobCall ===

This is where the routine can define itself one
(or a number) of JobNames/JobCodes, it can integrate itself into an
extension of the OS in a complete way. The disadvantage is that extra
coding is needed to deal with the various OS calls it has to service and
that extra work is needed to produce a suitable file to place in the
controller.

Normally with most processors, including the 65c02, the machine code
produced is produced for a fixed memory address, and it cannot be made to
run in a different place in memory unless extra work is carried out by the
user, or at least a combination of the user and the OS. For the controller
this is a very severe disadvantage as most extensions are downloaded as
"modules" and to optimise memory a system has to be devised to enable
routines to be placed anywhere in memory, thus allowing no memory to be
wasted. In the OS there is a routine to do just this, though it does need
some help. A special version of the users code has to be developed, or
rather it has to be "processed" to add extra information on the end. Extra
code is needed to set up a few pointers and call the OS routine to relocate.
See later.

== Memory ==

The first 256 bytes of memory are somewhat special, most zero page
locations are reserved for use by the OS:

{|class="wikitable"
|-
|&00-&14||General workspace, used to pass parameters to some OS routines, can also be used by other routines DURING their execution.
|-
|&15-&6F||Reserved
|-
|&70-&9F||Available to the user
|-
|&A0||Accumulator store for irqs (irq_A)
|-
|&A1-&A2||Two byte counter, decremented at 100hz, useful for temporary timing purposes (fcount)
|-
|&A3||RAM size, high byte of RAM size of machine, ie. for 32k this will be &80 (RAM_size)
|-
|&A4-&AF||Reserved
|-
|&B0-&FF||Used by the OS
|-
|}

The rest of memory space is used for the processors stack, OS'
buffers, tables, vectors and, of course, the user available memory.

A breakdown of the rest of memory:

* &100 to &1FF is the 65c02's stack.
* &200-&2FF is used by the OS for various system functions and also contains the vector table, more on that later.
* &300-&3FF is the serial input buffer.
* &400-&47F is the internal job code call output buffer. (jobout_buf)
* &480-&4FF is the internal job code call input buffer. (jobin_buf)
* &500-&5FF is the job status table.
* &600 to the end of RAM memory is for the user. The user should not assume what the top of AVAILABLE memory is and use the system variable HIMEM.

In the controller the maximum limit of RAM is &8000 (which is 32k),
from &8000-&DFFF lies the memory mapped hardware, from &E000 to &FFF9 lies
the OS and from &FFFA to &FFFF lies the 65c02 vectors.

So the user has his own limits of free memory. The lowest limit is
called LOMEM and the highest limit is called HIMEM, everything between these
boundaries is termed "available" for use by anyone, the user or the OS.

Anyone can also claim memory, thus making private to them and not allowing
anyone else to use it. You do this by altering the value of LOMEM, HIMEM
should not be moved. Of course anyone claiming memory should first check
that there is enough memory available for the amount they want to claim for.
To take a common example, a downloadable routine which installs itself as a
extension routine, The download routine will first of all read LOMEM, read
HIMEM, check there is enough memory for the routine, download it to LOMEM
and call it, the downloaded routine will then relocate itself and alter
LOMEM so it is protected.

There is one other memory limit, this is called TOPMEM, this is the
absolute top limit of RAM, HIMEM will normally equal TOPMEM, but a future OS
may alter HIMEM to below TOPMEM. TOPMEM should be ignored ideally, and
HIMEM used.

== OS Calls ==

The OS has calls (ie. a jump instruction which you call, which
then calls, via a RAM vector, a routine in the OS) setup near the top of
memory, through these calls you do everything associated with the
controller. The calls are are such:

* OS_PRINTER at address &FFB9
* OS_CALLOS at address &FFBC
* OS_SENDBYTE at address &FFBF
* OS_READBYTE at address &FFC2
* OS_SENDJOB at address &FFC5
* OS_READJOB at address &FFC8
* OS_DECODEJOB at address &FFCB

The address is the one to call for the particular routine.

* OS_PRINTER is reserved for future use.
* OS_CALLOS calls upon the OS to do various things internally.
* OS_SENDBYTE sends a byte out of the serial port.
* OS_READBYTE reads a byte from the serial port.
* OS_SENDJOB 'sends' a value to the JobCall caller.
* OS_READJOB 'reads' a value from the JobCalls caller.
* OS_DECODEJOB decodes the Job number held in A and acts on it.

Note none of these things should be used in interupt routines,
except OS_CALLOS, of any sort, except if YOU know what state the machine is
in and WHY.

=== OS_READBYTE and OS_SENDBYTE: Serial Port ===

The serial port on the controller is currently based on the 6850
UART, this need not bother you as the OS deals with the thing entirely by
itself. The chip is setup by the OS to always have a word format of 8n1 and
a baud rate of 9600, this translates to 960cps. The 6850 has two divide
rates for the baud rate, the OS only uses one, using the other one is beyond
the scope of this document and shouldn't be neccessary to use.

Only receive interupts are used, transmission of characters is done
on a polled basis.

As said, there are two calls OS_READBYTE and OS_SENDBYTE.

==== OS_READBYTE ====

OS_READBYTE tests the serial input buffer and returns the character (if any
in the A register), the c flag states whether there was a character
returned.

{|class="calltable"
|Entry||
A, X, Y, c, z = undefined
|-
|Exit||
* X, Y preserved
* z = undefined
* if c = 1 (no character received)
*: A is preserved
* if c = 0 (character received)
*: A = character received
|}

==== OS_SENDBYTE ====

OS_SENDBYTE sends the character in the A register out of the serial
port, taking into consideration flow control etc.

{|class="calltable"
|Entry||
* A = character to send
* X, Y, c, z = undefined
|-
|Exit||
* A, X, Y, c is preserved
* z = undefined
|}

=== OS_READJOB and OS_SENDJOB ===

To send/receive data from the user (either internally or via the
serial port) you call OS_SENDJOB/OS_READJOB for the next byte. If your
JobCall requires dynamic use of data, ie. interaction, then a check of the
enviroment should be done to check the call came from the serial port. One
example of this is the OS JobCall MultipleServer, which requires dynamic use
of sending a stream of data until a reaction from the user to tell it to
stop.

==== OS_READJOB: Read job value from the user ====

{|class="calltable"
|Entry||
* A, X, Y, c, z = undefined
|-
|Exit||
* A = byte read
* X, Y is preserved
* c, z = undefined
|-
|Note||
When coming from the serial port it waits for a character to be received, if you are doing a serial only call and wish to have a loop checking for a character from the user while doing "your own thing", then OS_READBYTE should be used. For internal calls this reads data out of jobin_buf.
|}

==== OS_SENDJOB: Give a job value back to the user ====

{|class="calltable"
|Entry||
* A = byte to give
* X, Y, c, z = undefined
|-
|Exit||
* A, X, Y is preserved
* c, z = undefined
|-
|Note||
This will send either out to the serial port or place a byte in jobout_buf.
For internal calls this stores the value in jobout_buf, which is allocated 128 bytes, no bound checking is done so sending more than 128 bytes to OS_SENDJOB will cause corruption of some memory.
|}

=== OS_DECODEJOB ===

JobCalls in practise are really only used by the user, JobCalls
tend not to call other calls at all, infact you shouldn't really call
another call unless you were called from the serial port. If you do need to
call another JobCall then you do it like this; with each call you have
associated with it a number, and the call might require some data or give
some data back or both. With the serial port this is simple, you just send
data down and receive data as it is produced. You can't do this with
internal calls, and some calls will not let you call them from inside the
controller, you HAVE to call them from outside. But for the ones which do
let you, you do it with two data blocks, one for input TO the call and one
for output FROM the call. These are setup in a position in memory
(jobin_buf and jobout_buf), each one has a maximum of 128 bytes and this
should not be overflowed (OS_READJOB and OS_SENDJOB do NOT do any bound
checking). So to start with you place in the input block the data you want
to give the call (if any), call it, and then act on the data in the output
block (if any). The OS call OS_DECODEJOB is the one which actually calls
the JobCall handler and eventually the actual routine, you tell the JobCall
handler which call you want by placing the JobCode in the A register.

So for OS_DECODEJOB:

{|class="calltable"
|Entry||
* A = JobCode
* X, Y, c, z = undefined
* jobin_buf should contain any input data
|-
|Exit||
* A = flag
* X = number of bytes given back by routine
* Y = undefined
* c = status, if set JobCall does not exist
* z = status, if set JobCall cannot be called internally
* jobout_buf contains any data sent from routine
|}

A typical example would be:

<nowiki> LDA #readhimem ; JobCode for ReadHimem
JSR OS_DECODEJOB ; Call the JobCall handler
LDX jobout_buf ; Read HIMEM from buffer LSB
LDY jobout_buf+1 ; Read HIMEM from buffer MSB
STX jobin_buf ; Place LSB in input buffer
STY jobin_buf+1 ; Place MSB in input buffer
LDA #writelomem ; JobCode for WriteLomem
JSR OS_DECODEJOB ; Call the JobCall handler</nowiki>

which would read HIMEM, and then write LOMEM to be the same value, leaving
no spare memory left.

The reason why you should not call an internal call from another
internal call is that the same buffers (jobin_buf and jobout_buf) would be
used for both calls, causing conflict between the two calls, or rather to
the originator of the primary call ! The only time it would be safe if is
if you have already got all the data you want from jobin_buf and haven't
placed any in the jobout_buf (it would be lost if you had done).

=== 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.
|}

=== OS_PRINTER: Place a character in the printer buffer ===

{|class="calltable"
|Entry||
* A = character to send
* X, Y, c, z = undefined
|-
|Exit||
* A, X, Y is preserved
* if c = 0 (printed)
*: The printer is on and the character was inserted
* if c = 1 (not printed)
*: The printer is off and the character was forgotten
* z = undefined
|-
|Note||
The character goes into the printer buffer and will be
actually sent to the printer when the printer asks for it. If the printer
was not awake to begin with, an attempt is made to wake it up, thus
meaning that in some circumstances when the printer wasn't ready a
character may be lost, this cannot be helped. If the printer is off (via
the BCD switch) then the character will be forgotten as the Printer Buffer
is inactive.
|}

== 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
|}

== Starting Up ==

The setup procedure for setting up extension job calls is to:

# Claim the number of JobCodes you want
#: if success:
# patch the internal_vec and unknownjob_vec vectors
# move LOMEM up to protect your program
# do anything else for initial startup you may want to do
# return back, ready and waiting

This in code looks like:

<nowiki>execute
LDX #no_of_calls ; Number of JobCodes wanted
LDA #1 ; CALLOS, function 1, Claim JobCodes
JSR OS_CALLOS ; Call CALLOS
CPX #0 ; Check we were given some codes
BEQ noinstall ; No, don't bother installing ourself
STX call ; Store base address of JobCodes allocated
STY job_id ; Store JOB ID given

LDA internal_vec ; Get old internal_vec (LSB)
STA ovec ; Store it
LDA internal_vec+1 ; Get old internal_vec (MSB)
STA ovec+1 ; Store it
LDA #>internal_handle ; Our internal handler (LSB)
STA internal_vec ; Place it in the vector (LSB)
LDA #<internal_handle ; Our internal handler (MSB)
STA internal_vec+1 ; Place it in the vector (MSB)

LDA unknownjob_vec ; Get old unknownjob_vec (LSB)
STA ovec2 ; Store it
LDA unknownjob_vec+1 ; Get old unknownjob_vec (MSB)
STA ovec2+1 ; Store it
LDA #>job_handle ; Our unknown job handler (LSB)
STA unknownjob_vec ; Place it in the vector (LSB)
LDA #<job_handle ; Our unknown job handler (MSB)
STA unknownjob_vec+1 ; Place it in the vector (MSB)

LDX #>WriteLomem ; Point to JobName
LDY #<WriteLomem
JSR findjob ; Find WriteLomem code
BEQ noinstall ; Doesn't exist !
LDX #>end_of_code ; End of code (LSB)
LDY #<end_of_code ; End of code (MSB)
STX jobin_buf ; Place it in jobin_buf (LSB)
STY jobin_buf+1 ; Place it in jobin_buf+1 (MSB)
JSR OS_DECODEJOB ; Call JobCall handler

noinstall
RTS ; End - return to OS

findjob
STX zero.gp1 ; Zero page
STY zero.gp1+
LDY #0
findthisjoblo
LDA (zero.gp1),Y
STA jobin.buf,Y ; Store name in jobin_buf
INY
CMP #13
BNE findthisjoblo
LDA #3 ; NameCode
JSR OS.DECODEJOB ; Call NameCode
LDA jobout.buf ; Get returned value
RTS

WriteLomem STR "WriteLomem"</nowiki>

This will setup the various vectors and memory pointers for the
applicaion, the actual routines (internal_handle and job_handle) are fairly
straight forward and simple:

<nowiki>internal_handle
CMP #1 : Is it function call 1 (NameCode) ?
BNE internal_handle_2 ; No, check for function 2
LDA job_id ; Get our JOB ID number
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #>job_names ; Our Job name table (LSB)
LDY #<job_names ; Our Job name table (MSB)
LDA #2 ; CALLOS function 2
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes : Found, go off and claim call
LDA #1 ; Not found, restore A
JMP (ovec) ; Call back to old vector

internal_handle_2
CMP #2 ; Is it function call 2 (CodeName) ?
BNE internal_handle_3 ; No, unknown, pass on
LDA job_id ; Get our JOB ID
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #>job_names ; Our Job name table (LSB)
LDY #<job_names ; Our Job name table (MSB)
LDA #3 ; CALLOS function 3
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes ; Found, go off and claim call
LDA #2 ; Not found, restore A
JMP (ovec) ; Call back to old vector

internal_yes
LDA #0 ; We want to claim call for some reason

internal_handle_3
JMP (ovec) ; Call back to old vector

job_handle
PHA ; Mark sure to preserve A
CPY call ; Check call wanted against base of ours
BCC job_handle_no ; Less than our base, so definately not ours
TYA
SBC #no_of_calls ; Subtract number of calls we have
CMP call ; Now compare with base
BCC job_handle2 ; Yes, one of ours

job_handle.no
PLA ; Restore A
JMP (ovec2) ; Call back to old vector

job_handle2
TYA
SEC
SBC call ; Subtract our base from call
ASL A ; Times by 2 for offset into table
TAY ; Place in Y
LDA job_run_table,Y ; Get LSB of routine
STA zero_gp1 ; Store it for indirect jump (LSB)
LDA job_run_table+1,Y ; Get MSB of routine
STA zero_gp1+1 ; Store it for indirect jump (MSB)
PLA ; Restore A
JMP (zero_gp1) ; Call our relevant routine

job_names ; List of our JobNames
STR "TestJob" ; Test job name
DFB &FF ; &FF - marks end of table

job_run_table ; List of routine addresses to match Jobs
DFW job_TestJob ; Test job routine</nowiki>

== Relocation ==

The relocation method used will not do a complete relocation, ie.
from ANY address to ANY address. The only constraint on the addresses is
that they must be the same offset in the page, which means, &2602 and &3402
is alright but &2602 and &3455 is not, ie. the difference between the two
addresses must be a multiple of 256 bytes, as only the MSB is altered, this
should not cause any real problems. What is meant by the two addresses is
the address the code was originally assembled at and the address it wants
relocating to. Because of this programs must be multiples of 256 bytes, ie.
the low byte of LOMEM must ALWAYS be 0, your program should be padded out.

The relocation mechanism works by having a table, and to each byte
of code there is one BIT, if unset it means the byte of code should not be
relocated, else it should be, thus the BitMap table is 8 times smaller than
the code. To generate the BitMap you have to assemble the code at two
different places, and compare both sets of assembled code against each
other, the differences are where the code is to be relocated. The code
which is sent up to the controller is assumed to be assembled at address
&100, so the first code should be assembled at &100, the other one should be
assembled at another address, say &600, and the first one be sent up with
the BitMap. A program is availble for the Elk/Beeb/Arc with 65Tube/Mac with
BBC BASIC to compare the two files and create the BitMap.

All the program has to do to relocate itself is execute this bit of
code first of all: (address is the base address of the program, ie. &100
for the downloaded version)

<nowiki>execcall
LDA #>(execute-address) ; Final execution address offset (LSB)
STA zero_gp1
LDA #<(execute-address) ; Final execution address offset (MSB)
STA zero_gp1+1

LDA #>(BitMap-address) ; BitMap address offset (LSB)
STA zero_gp2
LDA #<(BitMap-address) ; BitMap address offset (MSB)
STA zero_gp2+1

LDA #>(execcall-address); Length of data to relocate (LSB)
STA zero_gp3
LDA #<(execcall-address); Length of data to relocate (MSB)
STA zero_gp3+1

TXA ; Execcall REAL address
SEC
SBC #>(execcall-address); Subrtract length
TAX ; Put it back in X
TYA ; Ditto for MSB
SBC #<(execcall-address)
TAY
LDA #4 ; CALLOS function for Relocate
JMP OS_CALLOS ; Call CALLOS

BitMap ; BitMap start</nowiki>

This will relocate the code and automatically call the execution
address, which should be the initialisation code (ie. setup internal_vec
and unknownjob_vec etc.). "address" is the address the code is started to
assemble at, &100 for the version to be uploaded. The upload routine should
pass in X and Y (via ExecuteCode) the address of the start of execcall, this
means that the routine can tell where it is in memory, subtracting the
length gives the start of the code to relocate.

== Layout Summary ==

The layout of a full application should be like this by now:

<nowiki> start of code
program job codes, data etc.
internal handler
job handler
end of code
initialisation (setup internal etc.)
end of code to be relocated
execution (relocation)
relocation BitMap</nowiki>

Because of memory space the initialisation code should be placed
outside the reserved memory limit of the program, as it is only called once
and not needed again.

== Modules ==

The module is located at &8000 in memory, and should be a EPROM placed
in the second ROM socket in the controller (ie. the top RAM socket). This
module is primary designed to turn the Controller into a dedicated task,
making it perform some function from switch on. It could also be used to
add more permant JobCalls to the Controller, in the process taking up much
less RAM), but because of there being only one Module present this feature
is limited, and is much more suited to a collection of the user's own
personal routines.

For the OS to recognise a module as being in place the text "Module" is
looked for, the layout of a module should be like this (starting at
&8000):

<nowiki>Offset value comment
0 "Module" The OS checks for this string
6 0 End of check string
7 Language entry Address of 'Language' entry
9 Service entry Address of 'Service' entry
11 "<Module Title>" Module title
0 End of Module title

"<Module part>" Part Module Title
0 End of Part Module Title
"x.xx" Part version number

&FF End of parts list</nowiki>

The language entry is a 2 byte value holding the address of the language
entry routine, this is called on reset, if the BCD is set correctly. A
value of less than &8000 means there is no valid language entry and any
language calls are ignored. If a RTS is made the OS carries on as it would
have if there wasn't a language call.

The service entry is a 2 byte value holding the address of the service
entry routine, this is called at various appropiate moments with service
numbers in A. A list of current calls is thus:

<nowiki> 0 - Not used
1 - Unknown Job Code
2 - Centisecond call
3 - Irq2 (unknown IRQ)
4 - internal_vec call (exit with A=0 to claim)
254 - RESET
255 - BRK</nowiki>

On exit all registers and flags should be preserved. For call 1 the
unknown job value is held in the Y register, the enviroment is held in the
X register, on exit, X should contain the flag, as A does from the exit of
unknownjob_vec. For the rest of calls, X and Y are undefined.

For both Service and Language entry points, a value of 0 means "there is
no valid routine" and the module isn't called for that type of entry.

== Example JobCall ==

Finally a full implementation of a JobCall, from start to finish.

<nowiki> DIM data% &1000
:
no_of_calls = 1
:
VIA = &E030
ACIA = &E010
ADC = &E000
AUX_PORT = &E020
brk_vec = &200
nmi_vec = &202
irq_vec = &204
irq2_vec = &206
sendserial_vec = &208
readserial_vec = &20A
sendjob_vec = &20C
readjob_vec = &20E
decodejob_vec = &210
unknownjob_vec = &212
extjob_vec = &214
centisec_vec = &216
internal_vec = &218
callos_vec = &21A
printer_vec = &21C
zero_gp1 = 0
zero_gp2 = 2
zero_gp3 = 4
zero_gp4 = 6
zero_gp5 = 8
zero_gp6 = 10
zero_gp7 = 12
zero_gp8 = 14
zero_gp9 = 16
zero_gp10 = 18
user_reserved = &70
irq_A = &A0
fcount = &A1
RAM_size = &A3
jobout_buf = &400
jobin_buf = &480
OS_PRINTER = &FFB9
OS_CALLOS = &FFBC
OS_SENDBYTE = &FFBF
OS_READBYTE = &FFC2
OS_SENDJOB = &FFC5
OS_READJOB = &FFC8
OS_DECODEJOB = &FFCB
:
FOR create=1 TO 2
:
FOR pass%=4 TO 7 STEP 3
P%=&100*create : O%=data%
[OPT pass%
:
.job_DemoJob
CMP #1
BEQ DemoJob_go
LDA #1
LDY #0
RTS
/
.DemoJob_go

:
.internal_handle
CMP #1 ; Is it function call 1 (NameCode) ?
BNE internal_handle_2 ; No, check for function 2
/
LDA job_id ; Get our JOB ID number
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #job_names MOD 256 ; Our Job name table (LSB)
LDY #job_names DIV 256 ; Our Job name table (MSB)
LDA #2 ; CALLOS function 2
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes ; Found, go off and claim call
LDA #1 ; Not found, restore A
JMP (ovec) ; Call back to old vector
/
.internal_handle_2
CMP #2 ; Is it function call 2 (CodeName) ?
BNE internal_handle_3 ; No, unknown, pass on
/
LDA job_id ; Get our JOB ID
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #job_names MOD 256 ; Our Job name table (LSB)
LDY #job_names DIV 256 ; Our Job name table (MSB)
LDA #3 ; CALLOS function 3
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes ; Found, go off and claim call
LDA #2 ; Not found, restore A
JMP (ovec) ; Call back to old vector
/
.internal_yes
LDA #0 ; We want to claim call for some reason
/
.internal_handle_3
JMP (ovec) ; Call back to old vector
:
.job_handle
PHA ; Make sure to preserve A
CPY call ; Check call wanted against base of ours
BCC job_handle_no ; Less than our base, so definately not ours
TYA
SBC #no_of_calls ; Subtract number of calls we have
CMP call ; Now compare with base
BCC job_handle2 ; Yes, one of ours
/
.job_handle.no
PLA ; Restore A
JMP (ovec2) ; Call back to old vector
/
.job_handle2
TYA
SEC
SBC call ; Subtract our base from call
ASL A ; Times by 2 for offset into table
TAY ; Place in Y
LDA job_run_table,Y ; Get LSB of routine
STA zero_gp1 ; Store it for indirect jump (LSB)
LDA job_run_table+1,Y ; Get MSB of routine
STA zero_gp1+1 ; Store it for indirect jump (MSB)
PLA ; Restore A
JMP (zero_gp1) ; Call our relevant routine
:
.job_names ; List of our JobNames
EQUS "DemoJob":EQUB 13 ; Test job name
/
EQUB &FF ; &FF - marks end of table
:
.job_run_table ; List of routine addresses to match Jobs
EQUW job_DemoJob ; Test job routine
:
.call : EQUB 0 ; Store for our JobCode base
.job_id : EQUB 0 ; Store for our JobId
.ovec : EQUW 0 ; Store for old internal_vec value
.ovec2 : EQUW 0 ; Store for old unknownjob_vec value
:
EQUS STRING$(&100-(P% MOD 256),CHR$0)
.end_of_code ; end_of_code should be on page boundry
:
.execute
LDX #no_of_calls ; Number of JobCodes wanted
LDA #1 ; CALLOS, function 1, Claim JobCodes
JSR OS_CALLOS ; Call CALLOS
STX call ; Store base address of JobCodes allocated
STY job_id ; Store JOB ID given
CPX #0 ; Check we were given some codes
BEQ noinstall ; No, don't bother installing ourself
/
LDA internal_vec ; Get old internal_vec (LSB)
STA ovec ; Store it
LDA internal_vec+1 ; Get old internal_vec (MSB)
STA ovec+1 ; Store it
LDA #internal_handle MOD 256 ; Our internal handler (LSB)
STA internal_vec ; Place it in the vector (LSB)
LDA #internal_handle DIV 256 ; Our internal handler (MSB)
STA internal_vec+1 ; Place it in the vector (MSB)
/
LDA unknownjob_vec ; Get old unknownjob_vec (LSB)
STA ovec2 ; Store it
LDA unknownjob_vec+1 ; Get old unknownjob_vec (MSB)
STA ovec2+1 ; Store it
LDA #job_handle MOD 256 ; Our unknown job handler (LSB)
STA unknownjob_vec ; Place it in the vector (LSB)
LDA #job_handle DIV 256 ; Our unknown job handler (MSB)
STA unknownjob_vec+1 ; Place it in the vector (MSB)
/
LDX #end_of_code MOD 256 ; End of code (LSB)
LDY #end_of_code DIV 256 ; End of code (MSB)
STX jobin_buf ; Place it in jobin_buf (LSB)
STY jobin_buf+1 ; Place it in jobin_buf+1 (MSB)
LDA #65 ; JobCode for WriteLomem
JSR OS_DECODEJOB ; Call JobCall handler
/
.noinstall
RTS ; End - return to OS
:
.execcall
LDA #>(execute-address) ; Final execution address offset (LSB)
STA zero_gp1
LDA #<(execute-address) ; Final execution address offset (MSB)
STA zero_gp1+1
/
LDA #>(BitMap-address) ; BitMap address offset (LSB)
STA zero_gp2
LDA #<(BitMap-address) ; BitMap address offset (MSB)
STA zero_gp2+1
/
LDA #>(execcall-address) ; Length of data to relocate (LSB)
STA zero_gp3
LDA #<(execcall-address) ; Length of data to relocate (MSB)
STA zero_gp3+1
/
TXA ; Execcall REAL address
SEC
SBC #>(execcall-address) ; Subrtract length
TAX ; Put it back in X
TYA ; Ditto for MSB
SBC #<(execcall-address)
TAY
LDA #4 ; CALLOS function for Relocate
JMP OS_CALLOS ; Call CALLOS
/
.BitMap ; BitMap start
:
]
NEXT
:
OSCLI "SAVE code"+STR$create+" "+STR$~data%+" "+STR$~O%
:
NEXT</nowiki>

== Changelog ==

<nowiki>bob 071 Fixed MotorForward bug (%10)
bob 072 CallOS 14 now checks current adc.owner status
jim 072.d1 * Rewrite for new hardware/processor *
jim 072.d1 Moved vectors/workspace to &440
jim 072.d1 Moved rs.inp.buf to &500
jim 072.d1 Moved jobout.buf to &600
jim 072.d1 Moved jobin.buf to &680
jim 072.d1 Moved jobs.status to &700
jim 072.d1 Added irq.X (&A4)
jim 072.d1 Added irq.Y (&A5)
jim 072.d1 Removed short detection code
jim 072.d1 Voided CallOS' 6,7,8,9,10,11,13,16,17,18,19
jim 072.d1 Removed JobCalls ReadADCReg,WriteADCReg
jim 072.d1 Removed JobCalls ReadACIAReg,WriteACIAReg
jim 072.d1 Removed JobCalls ReadVIAReg,WriteVIAReg,SetVIAHigh,SetVIALow
jim 072.d1 Added CallOS 21 Write Outputs
jim 072.d1 Added CallOS 22 Read Outputs added
jim 072.d1 Added CallOS 23 Read Inputs added
jim 072.d1 Added CallOS 24 Write Motors
jim 072.d1 Added CallOS 25 Read Motors
jim 072.d1 Added CallOS 26 Read Keypad
jim 072.d1 Expanded CallOS 5 information
jim 072.d1 Added JobCall IdentSystem to return CallOS 5 info
jim 072.d1 JobCalls now use appropriate CallOS'
jim 072.d1 OS.READBYTE no longer preserves A on CS
jim 072.d1 irq.vec,irq2.vec,nmi.vec now redundant
jim 072.d1 Renamed JobCall DownloadData to DownloadData38
jim 072.d1 Renamed JobCall UploadData to UploadData38
jim 072.d1 Renamed JobCall ExecuteCode to ExecuteCode38
jim 072.d1 Renamed JobCall ReadByte to ReadByte38
jim 072.d1 Renamed JobCall StoreByte to StoreByte38
jim 072.d1 JobCall ForcedADCRead now checks adc.owner first
jim 072.d3 Added CallOS 27 Write printer
jim 072.d3 Added CallOS 28 Read printer
jim 072.d3 Added CallOS 29 Write RTC Reg
jim 072.d3 Added CallOS 30 Read RTC Reg
jim 072.d3 Added CallOS 31 Write RTC string
jim 072.d3 Added CallOS 32 Read RTC string
jim 072.d3 Added CallOS 33 Write RTC bcd
jim 072.d3 Added CallOS 34 Read RTC bcd
jim 072.d3 Added CallOS 35 Write LCD Reg
jim 072.d3 Added CallOS 36 Read LCD Reg
jim 072.d3 Added JobCall WritePrinter
jim 072.d3 Added JobCall ReadPrinter
jim 072.d3 Added JobCall PrintChar
jim 072.d3 Added JobCall PrintStreamZ
jim 072.d3 Added JobCall PrintStream
jim 072.d3 Added JobCall PrintServer
jim 072.d3 Added JobCall WriteRTCReg
jim 072.d3 Added JobCall ReadRTCReg
jim 072.d3 Added JobCall WriteRTC
jim 072.d3 Added JobCall ReadRTC
jim 072.d3 Added JobCall WriteRTCbcd
jim 072.d3 Added JobCall ReadRTCbcd
jim 072.d3 Added JobCall WriteLCDReg
jim 072.d3 Added JobCall ReadLCDReg
jim 072.d3 Added CallOS 37 Write Power ctrl
jim 072.d3 Added CallOS 38 Read Power ctrl
jim 072.d3 Implemented OS.PRINTER
jim 072.d3 Added JobCall PatchMF (MotorForward)
jim 072.d3 Changed irq.vec to int0.vec
jim 072.d3 Changed irq2.vec to int1.vec
jim 072.d3 Added int2irq.vec (wrksp+&20)
jim 072.d3 Added int3irq.vec (wrksp+&22)
jim 072.d3 Added int4irq.vec (wrksp+&24)
jim 072.d3 Added c0irq.vec (wrksp+&26)
jim 072.d3 Added c1irq.vec (wrksp+&28)
jim 072.d3 Added t1irq.vec (wrksp+&2A)
jim 072.d3 Added t2irq.vec (wrksp+&2C)
jim 072.d3 Added txirq.vec (wrksp+&2E)
jim 072.d3 Added tyirq.vec (wrksp+&30)
jim 072.d3 Added s1rirq.vec (wrksp+&32)
jim 072.d3 Added s1rirq.vec (wrksp+&34)
jim 072.d3 Added s2irq.vec (wrksp+&36)
jim 072.d3 Added adcirq.vec (wrksp+&38)
jim 072.d3 Renamed JobCall DownloadData38 to DownloadData740
jim 072.d3 Renamed JobCall UploadData38 to UploadData740
jim 072.d3 Renamed JobCall ExecuteCode38 to ExecuteCode740
jim 072.d3 Renamed JobCall ReadByte38 to ReadByte740
jim 072.d3 Renamed JobCall StoreByte38 to StoreByte740
jim 072.d4 Hardware update
jim 072.d4 Re-assigned CallOS 37 to Write Power/Charge control
jim 072.d4 Re-assigned CallOS 38 to Read Power/Charge control
jim 072.d4 Moved int2irq.vec to wrksp+&22
jim 072.d4 Moved int3irq.vec to wrksp+&24
jim 072.d4 Moved int4irq.vec to wrksp+&26
jim 072.d4 Moved c0irq.vec to wrksp+&28
jim 072.d4 Moved c1irq.vec to wrksp+&2A
jim 072.d4 Moved t1irq.vec to wrksp+&2C
jim 072.d4 Moved t2irq.vec to wrksp+&2E
jim 072.d4 Moved txirq.vec to wrksp+&30
jim 072.d4 Moved tyirq.vec to wrksp+&32
jim 072.d4 Moved s1rirq.vec to wrksp+&34
jim 072.d4 Moved s1rirq.vec to wrksp+&36
jim 072.d4 Moved s2irq.vec to wrksp+&38
jim 072.d4 Moved adcirq.vec to wrksp+&3A
jim 072.d4 Added OS.LCDVDU (&FFB7) and lcdvdu.vec (wrksp+&20)
jim 072.d5 Re-assigned CallOS 37 to Write/Read Power/Charge control
jim 072.d5 Re-assgined CallOS 38 Read Battery Voltage
jim 072.d5 OS.CALLOS now re-entrant
jim 072.d5 Fixed OS.PRINTER
jim 072.d5 Started to add internal logging software
jim 072.d5 Moved OS.LCDVDU to &FFB6
jim 072.d7 Added OS.PRINTERPOLL (&FFB3) and printerpoll.vec (wrksp+&3C)
bob 073 Matched jim & bob sensor lookup tables
bob 073 Added PatchMF
jim 072.dj Added OS.CALLOS 51 Read keypad press
jim 072.dj Added hard reset keypad press
jim 072.dk Added JobCall ReadOutputs
jim 072.do Changed soft reset of zero page locations
jim 072.do Changed MotorForward/Backward bitmaps
jim 072.dp Fixed OS.CALLOS WriteRTCbcd
jim 072.dq Fixed OS.CALLOS ReadRTCstring for correct 24hr operation
jim 072.dr Changed reset prompts
bob 074 Added support for Little Bob
jim 072.dy Added further RTC/CMOS support
jim 072.dB Removed double hard reset
jim 072.dE Set _cpu.mode depending on external memory requirement
jim 072.dF Added Insight code
jim 073 Sub-release
jim 074 Modification to LCD code - uses bsy flag all the time now
jim 074 Fixed OS.CALLOS 42 Write LCD Char Def
jim 074 Fixed OS.CALLOS 43 Read LCD Char Def
jim 075 Added simple battery charge code
jim 075 Fixed JobCall ReadSensorTable
jim 075 Fixed OS.CALLOS 42 Write LCD Char Def
jim 075 Fixed OS.CALLOS 43 Read LCD Char Def
jim 075 Added sleep code
jim 075 Added OS.CALLOS 52 Write Sleep Time
jim 075 Added OS.CALLOS 53 Read Sleep Time
jim 075 Modified battery charge code
jim 076 Modified JobCall ReadSensorTable
jim 076 Modified OS.CALLOS 26 ReadKeypad to do debounce
jim 077 Rewrote battery charging code
jim 077.2 Reduced stop charge threshold to 2
jim 077.3 Increased stop charge threshold to 3
jim 077.3 Added battery voltage averaging
bill 077 Stripped
bill 077 Moved ins to out port
bill 077 Added RTS
bill 077 Changed sensor ID system back to original, using p2.1
bill 077 Dedicated USB/RS selection line, RTS provisioned on p2.3
bill 077 Overload "bounce" timing
bill 078 CTS added
bill 079 Temperature fudge</nowiki>

SmartBox OS

2023-11-04T17:27:52Z

Benryves: /* OS_DECODEJOB */

== Documentation for SmartBox OS 2.066 ==

The term JobCall is the concept of the routine itself, as opposed to
JobName (which is the actual name associated with it (eg. NameCode)) and
JobCode (which is the actual number associated with it (eg. 3)).

The term controller means the SmartBox, or any other incarnation
which may appear in future time !

The term OS means the controllers' Operating System.

== Preview ==

There are a number of reasons why using Machine Code on the
controller is more desirable than using the various JobCalls via the serial
link. One reason is speed, if the task which needs to be performed, has to
be performed very quickly (more quickly than can be achieved via the serial
link at least), then some code must be written to work in the controller
itself to achieve this sort of speed. If the task required is to be a
"background" task (ie. a task which may happen while other "things" carry
on as normal, like a change of state of a particular port) then it is far
easier to let the controller do all the work, maybe under interupts, than
continuously poll the controller checking the state of various things.
Another reason may be that you would like to add another JobCall to the OS,
extending the calls available to external applications (and the user at the
same time), without the user having to write the code himself to achieve the
aim. For advanced users, there is also the ablity to alter the way the OS
does various things and to have the controller in their "power", for
dedicated tasks etc.

One advantage of writing IN the controller is that that "function"
is available to any computer using the serial link, and is thus not fixed to
one computer type or even a computer at all, where the controller is used
free running, doing a particular task which doesn't need the intervention of
the user's own computer.

== Call types ==

There are three different types of machine code routines which can
be added to the controller. Each one is suited to a more advanced level
than the other, which also relates to the amount of work needed to actually
get the routine working ! The three levels are such:

=== Simple stand alone routine ===

Here the routine is just the routine
itself with no supporting code (ie. code to integrate with the rest of the
OS). It has to be called directly, by use of the ExecuteCode JobCall, thus
it usually resides at a fixed address and obviously does not offer the user
friendly way of accessing itself like there is with normal OS calls.

=== Extended JobCall ===

There is one JobCall in the OS (ExtendJob)
which can call various routines residing in memory, each one is identified
by a 8 bit number. The disadvantages of this way is that the call hasn't
got it's own JobName/JobCode and needs the extra byte to identify itself.
This is ideal for the quick routine which the user would like to add for
himself without having to resort to the extra code needed for the full
JobCode implementation.

=== Full JobCall ===

This is where the routine can define itself one
(or a number) of JobNames/JobCodes, it can integrate itself into an
extension of the OS in a complete way. The disadvantage is that extra
coding is needed to deal with the various OS calls it has to service and
that extra work is needed to produce a suitable file to place in the
controller.

Normally with most processors, including the 65c02, the machine code
produced is produced for a fixed memory address, and it cannot be made to
run in a different place in memory unless extra work is carried out by the
user, or at least a combination of the user and the OS. For the controller
this is a very severe disadvantage as most extensions are downloaded as
"modules" and to optimise memory a system has to be devised to enable
routines to be placed anywhere in memory, thus allowing no memory to be
wasted. In the OS there is a routine to do just this, though it does need
some help. A special version of the users code has to be developed, or
rather it has to be "processed" to add extra information on the end. Extra
code is needed to set up a few pointers and call the OS routine to relocate.
See later.

== Memory ==

The first 256 bytes of memory are somewhat special, most zero page
locations are reserved for use by the OS:

{|class="wikitable"
|-
|&00-&14||General workspace, used to pass parameters to some OS routines, can also be used by other routines DURING their execution.
|-
|&15-&6F||Reserved
|-
|&70-&9F||Available to the user
|-
|&A0||Accumulator store for irqs (irq_A)
|-
|&A1-&A2||Two byte counter, decremented at 100hz, useful for temporary timing purposes (fcount)
|-
|&A3||RAM size, high byte of RAM size of machine, ie. for 32k this will be &80 (RAM_size)
|-
|&A4-&AF||Reserved
|-
|&B0-&FF||Used by the OS
|-
|}

The rest of memory space is used for the processors stack, OS'
buffers, tables, vectors and, of course, the user available memory.

A breakdown of the rest of memory:

* &100 to &1FF is the 65c02's stack.
* &200-&2FF is used by the OS for various system functions and also contains the vector table, more on that later.
* &300-&3FF is the serial input buffer.
* &400-&47F is the internal job code call output buffer. (jobout_buf)
* &480-&4FF is the internal job code call input buffer. (jobin_buf)
* &500-&5FF is the job status table.
* &600 to the end of RAM memory is for the user. The user should not assume what the top of AVAILABLE memory is and use the system variable HIMEM.

In the controller the maximum limit of RAM is &8000 (which is 32k),
from &8000-&DFFF lies the memory mapped hardware, from &E000 to &FFF9 lies
the OS and from &FFFA to &FFFF lies the 65c02 vectors.

So the user has his own limits of free memory. The lowest limit is
called LOMEM and the highest limit is called HIMEM, everything between these
boundaries is termed "available" for use by anyone, the user or the OS.

Anyone can also claim memory, thus making private to them and not allowing
anyone else to use it. You do this by altering the value of LOMEM, HIMEM
should not be moved. Of course anyone claiming memory should first check
that there is enough memory available for the amount they want to claim for.
To take a common example, a downloadable routine which installs itself as a
extension routine, The download routine will first of all read LOMEM, read
HIMEM, check there is enough memory for the routine, download it to LOMEM
and call it, the downloaded routine will then relocate itself and alter
LOMEM so it is protected.

There is one other memory limit, this is called TOPMEM, this is the
absolute top limit of RAM, HIMEM will normally equal TOPMEM, but a future OS
may alter HIMEM to below TOPMEM. TOPMEM should be ignored ideally, and
HIMEM used.

== OS Calls ==

The OS has calls (ie. a jump instruction which you call, which
then calls, via a RAM vector, a routine in the OS) setup near the top of
memory, through these calls you do everything associated with the
controller. The calls are are such:

* OS_PRINTER at address &FFB9
* OS_CALLOS at address &FFBC
* OS_SENDBYTE at address &FFBF
* OS_READBYTE at address &FFC2
* OS_SENDJOB at address &FFC5
* OS_READJOB at address &FFC8
* OS_DECODEJOB at address &FFCB

The address is the one to call for the particular routine.

* OS_PRINTER is reserved for future use.
* OS_CALLOS calls upon the OS to do various things internally.
* OS_SENDBYTE sends a byte out of the serial port.
* OS_READBYTE reads a byte from the serial port.
* OS_SENDJOB 'sends' a value to the JobCall caller.
* OS_READJOB 'reads' a value from the JobCalls caller.
* OS_DECODEJOB decodes the Job number held in A and acts on it.

Note none of these things should be used in interupt routines,
except OS_CALLOS, of any sort, except if YOU know what state the machine is
in and WHY.

=== OS_READBYTE and OS_SENDBYTE: Serial Port ===

The serial port on the controller is currently based on the 6850
UART, this need not bother you as the OS deals with the thing entirely by
itself. The chip is setup by the OS to always have a word format of 8n1 and
a baud rate of 9600, this translates to 960cps. The 6850 has two divide
rates for the baud rate, the OS only uses one, using the other one is beyond
the scope of this document and shouldn't be neccessary to use.

Only receive interupts are used, transmission of characters is done
on a polled basis.

As said, there are two calls OS_READBYTE and OS_SENDBYTE.

==== OS_READBYTE ====

OS_READBYTE tests the serial input buffer and returns the character (if any
in the A register), the c flag states whether there was a character
returned.

{|class="calltable"
|Entry||
A, X, Y, c, z = undefined
|-
|Exit||
* X, Y preserved
* z = undefined
* if c = 1 (no character received)
*: A is preserved
* if c = 0 (character received)
*: A = character received
|}

==== OS_SENDBYTE ====

OS_SENDBYTE sends the character in the A register out of the serial
port, taking into consideration flow control etc.

{|class="calltable"
|Entry||
* A = character to send
* X, Y, c, z = undefined
|-
|Exit||
* A, X, Y, c is preserved
* z = undefined
|}

=== OS_READJOB and OS_SENDJOB ===

To send/receive data from the user (either internally or via the
serial port) you call OS_SENDJOB/OS_READJOB for the next byte. If your
JobCall requires dynamic use of data, ie. interaction, then a check of the
enviroment should be done to check the call came from the serial port. One
example of this is the OS JobCall MultipleServer, which requires dynamic use
of sending a stream of data until a reaction from the user to tell it to
stop.

==== OS_READJOB: Read job value from the user ====

{|class="calltable"
|Entry||
* A, X, Y, c, z = undefined
|-
|Exit||
* A = byte read
* X, Y is preserved
* c, z = undefined
|-
|Note||
When coming from the serial port it waits for a character to be received, if you are doing a serial only call and wish to have a loop checking for a character from the user while doing "your own thing", then OS_READBYTE should be used. For internal calls this reads data out of jobin_buf.
|}

==== OS_SENDJOB: Give a job value back to the user ====

{|class="calltable"
|Entry||
* A = byte to give
* X, Y, c, z = undefined
|-
|Exit||
* A, X, Y is preserved
* c, z = undefined
|-
|Note||
This will send either out to the serial port or place a byte in jobout_buf.
For internal calls this stores the value in jobout_buf, which is allocated 128 bytes, no bound checking is done so sending more than 128 bytes to OS_SENDJOB will cause corruption of some memory.
|}

=== OS_DECODEJOB ===

JobCalls in practise are really only used by the user, JobCalls
tend not to call other calls at all, infact you shouldn't really call
another call unless you were called from the serial port. If you do need to
call another JobCall then you do it like this; with each call you have
associated with it a number, and the call might require some data or give
some data back or both. With the serial port this is simple, you just send
data down and receive data as it is produced. You can't do this with
internal calls, and some calls will not let you call them from inside the
controller, you HAVE to call them from outside. But for the ones which do
let you, you do it with two data blocks, one for input TO the call and one
for output FROM the call. These are setup in a position in memory
(jobin_buf and jobout_buf), each one has a maximum of 128 bytes and this
should not be overflowed (OS_READJOB and OS_SENDJOB do NOT do any bound
checking). So to start with you place in the input block the data you want
to give the call (if any), call it, and then act on the data in the output
block (if any). The OS call OS_DECODEJOB is the one which actually calls
the JobCall handler and eventually the actual routine, you tell the JobCall
handler which call you want by placing the JobCode in the A register.

So for OS_DECODEJOB:

{|class="calltable"
|Entry||
* A = JobCode
* X, Y, c, z = undefined
* jobin_buf should contain any input data
|-
|Exit||
* A = flag
* X = number of bytes given back by routine
* Y = undefined
* c = status, if set JobCall does not exist
* z = status, if set JobCall cannot be called internally
* jobout_buf contains any data sent from routine
|}

A typical example would be:

<nowiki> LDA #readhimem ; JobCode for ReadHimem
JSR OS_DECODEJOB ; Call the JobCall handler
LDX jobout_buf ; Read HIMEM from buffer LSB
LDY jobout_buf+1 ; Read HIMEM from buffer MSB
STX jobin_buf ; Place LSB in input buffer
STY jobin_buf+1 ; Place MSB in input buffer
LDA #writelomem ; JobCode for WriteLomem
JSR OS_DECODEJOB ; Call the JobCall handler</nowiki>

which would read HIMEM, and then write LOMEM to be the same value, leaving
no spare memory left.

The reason why you should not call an internal call from another
internal call is that the same buffers (jobin_buf and jobout_buf) would be
used for both calls, causing conflict between the two calls, or rather to
the originator of the primary call ! The only time it would be safe if is
if you have already got all the data you want from jobin_buf and haven't
placed any in the jobout_buf (it would be lost if you had done).

=== 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.
|}

== 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
|}

== Starting Up ==

The setup procedure for setting up extension job calls is to:

# Claim the number of JobCodes you want
#: if success:
# patch the internal_vec and unknownjob_vec vectors
# move LOMEM up to protect your program
# do anything else for initial startup you may want to do
# return back, ready and waiting

This in code looks like:

<nowiki>execute
LDX #no_of_calls ; Number of JobCodes wanted
LDA #1 ; CALLOS, function 1, Claim JobCodes
JSR OS_CALLOS ; Call CALLOS
CPX #0 ; Check we were given some codes
BEQ noinstall ; No, don't bother installing ourself
STX call ; Store base address of JobCodes allocated
STY job_id ; Store JOB ID given

LDA internal_vec ; Get old internal_vec (LSB)
STA ovec ; Store it
LDA internal_vec+1 ; Get old internal_vec (MSB)
STA ovec+1 ; Store it
LDA #>internal_handle ; Our internal handler (LSB)
STA internal_vec ; Place it in the vector (LSB)
LDA #<internal_handle ; Our internal handler (MSB)
STA internal_vec+1 ; Place it in the vector (MSB)

LDA unknownjob_vec ; Get old unknownjob_vec (LSB)
STA ovec2 ; Store it
LDA unknownjob_vec+1 ; Get old unknownjob_vec (MSB)
STA ovec2+1 ; Store it
LDA #>job_handle ; Our unknown job handler (LSB)
STA unknownjob_vec ; Place it in the vector (LSB)
LDA #<job_handle ; Our unknown job handler (MSB)
STA unknownjob_vec+1 ; Place it in the vector (MSB)

LDX #>WriteLomem ; Point to JobName
LDY #<WriteLomem
JSR findjob ; Find WriteLomem code
BEQ noinstall ; Doesn't exist !
LDX #>end_of_code ; End of code (LSB)
LDY #<end_of_code ; End of code (MSB)
STX jobin_buf ; Place it in jobin_buf (LSB)
STY jobin_buf+1 ; Place it in jobin_buf+1 (MSB)
JSR OS_DECODEJOB ; Call JobCall handler

noinstall
RTS ; End - return to OS

findjob
STX zero.gp1 ; Zero page
STY zero.gp1+
LDY #0
findthisjoblo
LDA (zero.gp1),Y
STA jobin.buf,Y ; Store name in jobin_buf
INY
CMP #13
BNE findthisjoblo
LDA #3 ; NameCode
JSR OS.DECODEJOB ; Call NameCode
LDA jobout.buf ; Get returned value
RTS

WriteLomem STR "WriteLomem"</nowiki>

This will setup the various vectors and memory pointers for the
applicaion, the actual routines (internal_handle and job_handle) are fairly
straight forward and simple:

<nowiki>internal_handle
CMP #1 : Is it function call 1 (NameCode) ?
BNE internal_handle_2 ; No, check for function 2
LDA job_id ; Get our JOB ID number
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #>job_names ; Our Job name table (LSB)
LDY #<job_names ; Our Job name table (MSB)
LDA #2 ; CALLOS function 2
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes : Found, go off and claim call
LDA #1 ; Not found, restore A
JMP (ovec) ; Call back to old vector

internal_handle_2
CMP #2 ; Is it function call 2 (CodeName) ?
BNE internal_handle_3 ; No, unknown, pass on
LDA job_id ; Get our JOB ID
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #>job_names ; Our Job name table (LSB)
LDY #<job_names ; Our Job name table (MSB)
LDA #3 ; CALLOS function 3
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes ; Found, go off and claim call
LDA #2 ; Not found, restore A
JMP (ovec) ; Call back to old vector

internal_yes
LDA #0 ; We want to claim call for some reason

internal_handle_3
JMP (ovec) ; Call back to old vector

job_handle
PHA ; Mark sure to preserve A
CPY call ; Check call wanted against base of ours
BCC job_handle_no ; Less than our base, so definately not ours
TYA
SBC #no_of_calls ; Subtract number of calls we have
CMP call ; Now compare with base
BCC job_handle2 ; Yes, one of ours

job_handle.no
PLA ; Restore A
JMP (ovec2) ; Call back to old vector

job_handle2
TYA
SEC
SBC call ; Subtract our base from call
ASL A ; Times by 2 for offset into table
TAY ; Place in Y
LDA job_run_table,Y ; Get LSB of routine
STA zero_gp1 ; Store it for indirect jump (LSB)
LDA job_run_table+1,Y ; Get MSB of routine
STA zero_gp1+1 ; Store it for indirect jump (MSB)
PLA ; Restore A
JMP (zero_gp1) ; Call our relevant routine

job_names ; List of our JobNames
STR "TestJob" ; Test job name
DFB &FF ; &FF - marks end of table

job_run_table ; List of routine addresses to match Jobs
DFW job_TestJob ; Test job routine</nowiki>

== Relocation ==

The relocation method used will not do a complete relocation, ie.
from ANY address to ANY address. The only constraint on the addresses is
that they must be the same offset in the page, which means, &2602 and &3402
is alright but &2602 and &3455 is not, ie. the difference between the two
addresses must be a multiple of 256 bytes, as only the MSB is altered, this
should not cause any real problems. What is meant by the two addresses is
the address the code was originally assembled at and the address it wants
relocating to. Because of this programs must be multiples of 256 bytes, ie.
the low byte of LOMEM must ALWAYS be 0, your program should be padded out.

The relocation mechanism works by having a table, and to each byte
of code there is one BIT, if unset it means the byte of code should not be
relocated, else it should be, thus the BitMap table is 8 times smaller than
the code. To generate the BitMap you have to assemble the code at two
different places, and compare both sets of assembled code against each
other, the differences are where the code is to be relocated. The code
which is sent up to the controller is assumed to be assembled at address
&100, so the first code should be assembled at &100, the other one should be
assembled at another address, say &600, and the first one be sent up with
the BitMap. A program is availble for the Elk/Beeb/Arc with 65Tube/Mac with
BBC BASIC to compare the two files and create the BitMap.

All the program has to do to relocate itself is execute this bit of
code first of all: (address is the base address of the program, ie. &100
for the downloaded version)

<nowiki>execcall
LDA #>(execute-address) ; Final execution address offset (LSB)
STA zero_gp1
LDA #<(execute-address) ; Final execution address offset (MSB)
STA zero_gp1+1

LDA #>(BitMap-address) ; BitMap address offset (LSB)
STA zero_gp2
LDA #<(BitMap-address) ; BitMap address offset (MSB)
STA zero_gp2+1

LDA #>(execcall-address); Length of data to relocate (LSB)
STA zero_gp3
LDA #<(execcall-address); Length of data to relocate (MSB)
STA zero_gp3+1

TXA ; Execcall REAL address
SEC
SBC #>(execcall-address); Subrtract length
TAX ; Put it back in X
TYA ; Ditto for MSB
SBC #<(execcall-address)
TAY
LDA #4 ; CALLOS function for Relocate
JMP OS_CALLOS ; Call CALLOS

BitMap ; BitMap start</nowiki>

This will relocate the code and automatically call the execution
address, which should be the initialisation code (ie. setup internal_vec
and unknownjob_vec etc.). "address" is the address the code is started to
assemble at, &100 for the version to be uploaded. The upload routine should
pass in X and Y (via ExecuteCode) the address of the start of execcall, this
means that the routine can tell where it is in memory, subtracting the
length gives the start of the code to relocate.

== Layout Summary ==

The layout of a full application should be like this by now:

<nowiki> start of code
program job codes, data etc.
internal handler
job handler
end of code
initialisation (setup internal etc.)
end of code to be relocated
execution (relocation)
relocation BitMap</nowiki>

Because of memory space the initialisation code should be placed
outside the reserved memory limit of the program, as it is only called once
and not needed again.

== Other miscellaneous calls ==

<nowiki>Call : OS_PRINTER
Purpose : To place a character in the printer buffer
Entry : A = character to send
X, Y, c, z = undefined
Exit : A, X, Y is preserved
if c = 0 (printed)
The printer is on and the character was inserted
if c = 1 (not printed)
The printer is off and the character was forgotten
z = undefined
Note : The character goes into the printer buffer and will be
actually sent to the printer when the printer asks for it. If the printer
was not awake to begin with, an attempt is made to wake it up, thus
meaning that in some circumstances when the printer wasn't ready a
character may be lost, this cannot be helped. If the printer is off (via
the BCD switch) then the character will be forgotten as the Printer Buffer
is inactive.</nowiki>

The module is located at &8000 in memory, and should be a EPROM placed
in the second ROM socket in the controller (ie. the top RAM socket). This
module is primary designed to turn the Controller into a dedicated task,
making it perform some function from switch on. It could also be used to
add more permant JobCalls to the Controller, in the process taking up much
less RAM), but because of there being only one Module present this feature
is limited, and is much more suited to a collection of the user's own
personal routines.

For the OS to recognise a module as being in place the text "Module" is
looked for, the layout of a module should be like this (starting at
&8000):

<nowiki>Offset value comment
0 "Module" The OS checks for this string
6 0 End of check string
7 Language entry Address of 'Language' entry
9 Service entry Address of 'Service' entry
11 "<Module Title>" Module title
0 End of Module title

"<Module part>" Part Module Title
0 End of Part Module Title
"x.xx" Part version number

&FF End of parts list</nowiki>

The language entry is a 2 byte value holding the address of the language
entry routine, this is called on reset, if the BCD is set correctly. A
value of less than &8000 means there is no valid language entry and any
language calls are ignored. If a RTS is made the OS carries on as it would
have if there wasn't a language call.

The service entry is a 2 byte value holding the address of the service
entry routine, this is called at various appropiate moments with service
numbers in A. A list of current calls is thus:

<nowiki> 0 - Not used
1 - Unknown Job Code
2 - Centisecond call
3 - Irq2 (unknown IRQ)
4 - internal_vec call (exit with A=0 to claim)
254 - RESET
255 - BRK</nowiki>

On exit all registers and flags should be preserved. For call 1 the
unknown job value is held in the Y register, the enviroment is held in the
X register, on exit, X should contain the flag, as A does from the exit of
unknownjob_vec. For the rest of calls, X and Y are undefined.

For both Service and Language entry points, a value of 0 means "there is
no valid routine" and the module isn't called for that type of entry.

Finally a full implementation of a JobCall, from start to finish.

<nowiki> DIM data% &1000
:
no_of_calls = 1
:
VIA = &E030
ACIA = &E010
ADC = &E000
AUX_PORT = &E020
brk_vec = &200
nmi_vec = &202
irq_vec = &204
irq2_vec = &206
sendserial_vec = &208
readserial_vec = &20A
sendjob_vec = &20C
readjob_vec = &20E
decodejob_vec = &210
unknownjob_vec = &212
extjob_vec = &214
centisec_vec = &216
internal_vec = &218
callos_vec = &21A
printer_vec = &21C
zero_gp1 = 0
zero_gp2 = 2
zero_gp3 = 4
zero_gp4 = 6
zero_gp5 = 8
zero_gp6 = 10
zero_gp7 = 12
zero_gp8 = 14
zero_gp9 = 16
zero_gp10 = 18
user_reserved = &70
irq_A = &A0
fcount = &A1
RAM_size = &A3
jobout_buf = &400
jobin_buf = &480
OS_PRINTER = &FFB9
OS_CALLOS = &FFBC
OS_SENDBYTE = &FFBF
OS_READBYTE = &FFC2
OS_SENDJOB = &FFC5
OS_READJOB = &FFC8
OS_DECODEJOB = &FFCB
:
FOR create=1 TO 2
:
FOR pass%=4 TO 7 STEP 3
P%=&100*create : O%=data%
[OPT pass%
:
.job_DemoJob
CMP #1
BEQ DemoJob_go
LDA #1
LDY #0
RTS
/
.DemoJob_go

:
.internal_handle
CMP #1 ; Is it function call 1 (NameCode) ?
BNE internal_handle_2 ; No, check for function 2
/
LDA job_id ; Get our JOB ID number
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #job_names MOD 256 ; Our Job name table (LSB)
LDY #job_names DIV 256 ; Our Job name table (MSB)
LDA #2 ; CALLOS function 2
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes ; Found, go off and claim call
LDA #1 ; Not found, restore A
JMP (ovec) ; Call back to old vector
/
.internal_handle_2
CMP #2 ; Is it function call 2 (CodeName) ?
BNE internal_handle_3 ; No, unknown, pass on
/
LDA job_id ; Get our JOB ID
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #job_names MOD 256 ; Our Job name table (LSB)
LDY #job_names DIV 256 ; Our Job name table (MSB)
LDA #3 ; CALLOS function 3
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes ; Found, go off and claim call
LDA #2 ; Not found, restore A
JMP (ovec) ; Call back to old vector
/
.internal_yes
LDA #0 ; We want to claim call for some reason
/
.internal_handle_3
JMP (ovec) ; Call back to old vector
:
.job_handle
PHA ; Make sure to preserve A
CPY call ; Check call wanted against base of ours
BCC job_handle_no ; Less than our base, so definately not ours
TYA
SBC #no_of_calls ; Subtract number of calls we have
CMP call ; Now compare with base
BCC job_handle2 ; Yes, one of ours
/
.job_handle.no
PLA ; Restore A
JMP (ovec2) ; Call back to old vector
/
.job_handle2
TYA
SEC
SBC call ; Subtract our base from call
ASL A ; Times by 2 for offset into table
TAY ; Place in Y
LDA job_run_table,Y ; Get LSB of routine
STA zero_gp1 ; Store it for indirect jump (LSB)
LDA job_run_table+1,Y ; Get MSB of routine
STA zero_gp1+1 ; Store it for indirect jump (MSB)
PLA ; Restore A
JMP (zero_gp1) ; Call our relevant routine
:
.job_names ; List of our JobNames
EQUS "DemoJob":EQUB 13 ; Test job name
/
EQUB &FF ; &FF - marks end of table
:
.job_run_table ; List of routine addresses to match Jobs
EQUW job_DemoJob ; Test job routine
:
.call : EQUB 0 ; Store for our JobCode base
.job_id : EQUB 0 ; Store for our JobId
.ovec : EQUW 0 ; Store for old internal_vec value
.ovec2 : EQUW 0 ; Store for old unknownjob_vec value
:
EQUS STRING$(&100-(P% MOD 256),CHR$0)
.end_of_code ; end_of_code should be on page boundry
:
.execute
LDX #no_of_calls ; Number of JobCodes wanted
LDA #1 ; CALLOS, function 1, Claim JobCodes
JSR OS_CALLOS ; Call CALLOS
STX call ; Store base address of JobCodes allocated
STY job_id ; Store JOB ID given
CPX #0 ; Check we were given some codes
BEQ noinstall ; No, don't bother installing ourself
/
LDA internal_vec ; Get old internal_vec (LSB)
STA ovec ; Store it
LDA internal_vec+1 ; Get old internal_vec (MSB)
STA ovec+1 ; Store it
LDA #internal_handle MOD 256 ; Our internal handler (LSB)
STA internal_vec ; Place it in the vector (LSB)
LDA #internal_handle DIV 256 ; Our internal handler (MSB)
STA internal_vec+1 ; Place it in the vector (MSB)
/
LDA unknownjob_vec ; Get old unknownjob_vec (LSB)
STA ovec2 ; Store it
LDA unknownjob_vec+1 ; Get old unknownjob_vec (MSB)
STA ovec2+1 ; Store it
LDA #job_handle MOD 256 ; Our unknown job handler (LSB)
STA unknownjob_vec ; Place it in the vector (LSB)
LDA #job_handle DIV 256 ; Our unknown job handler (MSB)
STA unknownjob_vec+1 ; Place it in the vector (MSB)
/
LDX #end_of_code MOD 256 ; End of code (LSB)
LDY #end_of_code DIV 256 ; End of code (MSB)
STX jobin_buf ; Place it in jobin_buf (LSB)
STY jobin_buf+1 ; Place it in jobin_buf+1 (MSB)
LDA #65 ; JobCode for WriteLomem
JSR OS_DECODEJOB ; Call JobCall handler
/
.noinstall
RTS ; End - return to OS
:
.execcall
LDA #>(execute-address) ; Final execution address offset (LSB)
STA zero_gp1
LDA #<(execute-address) ; Final execution address offset (MSB)
STA zero_gp1+1
/
LDA #>(BitMap-address) ; BitMap address offset (LSB)
STA zero_gp2
LDA #<(BitMap-address) ; BitMap address offset (MSB)
STA zero_gp2+1
/
LDA #>(execcall-address) ; Length of data to relocate (LSB)
STA zero_gp3
LDA #<(execcall-address) ; Length of data to relocate (MSB)
STA zero_gp3+1
/
TXA ; Execcall REAL address
SEC
SBC #>(execcall-address) ; Subrtract length
TAX ; Put it back in X
TYA ; Ditto for MSB
SBC #<(execcall-address)
TAY
LDA #4 ; CALLOS function for Relocate
JMP OS_CALLOS ; Call CALLOS
/
.BitMap ; BitMap start
:
]
NEXT
:
OSCLI "SAVE code"+STR$create+" "+STR$~data%+" "+STR$~O%
:
NEXT</nowiki>

== Changelog ==

<nowiki>bob 071 Fixed MotorForward bug (%10)
bob 072 CallOS 14 now checks current adc.owner status
jim 072.d1 * Rewrite for new hardware/processor *
jim 072.d1 Moved vectors/workspace to &440
jim 072.d1 Moved rs.inp.buf to &500
jim 072.d1 Moved jobout.buf to &600
jim 072.d1 Moved jobin.buf to &680
jim 072.d1 Moved jobs.status to &700
jim 072.d1 Added irq.X (&A4)
jim 072.d1 Added irq.Y (&A5)
jim 072.d1 Removed short detection code
jim 072.d1 Voided CallOS' 6,7,8,9,10,11,13,16,17,18,19
jim 072.d1 Removed JobCalls ReadADCReg,WriteADCReg
jim 072.d1 Removed JobCalls ReadACIAReg,WriteACIAReg
jim 072.d1 Removed JobCalls ReadVIAReg,WriteVIAReg,SetVIAHigh,SetVIALow
jim 072.d1 Added CallOS 21 Write Outputs
jim 072.d1 Added CallOS 22 Read Outputs added
jim 072.d1 Added CallOS 23 Read Inputs added
jim 072.d1 Added CallOS 24 Write Motors
jim 072.d1 Added CallOS 25 Read Motors
jim 072.d1 Added CallOS 26 Read Keypad
jim 072.d1 Expanded CallOS 5 information
jim 072.d1 Added JobCall IdentSystem to return CallOS 5 info
jim 072.d1 JobCalls now use appropriate CallOS'
jim 072.d1 OS.READBYTE no longer preserves A on CS
jim 072.d1 irq.vec,irq2.vec,nmi.vec now redundant
jim 072.d1 Renamed JobCall DownloadData to DownloadData38
jim 072.d1 Renamed JobCall UploadData to UploadData38
jim 072.d1 Renamed JobCall ExecuteCode to ExecuteCode38
jim 072.d1 Renamed JobCall ReadByte to ReadByte38
jim 072.d1 Renamed JobCall StoreByte to StoreByte38
jim 072.d1 JobCall ForcedADCRead now checks adc.owner first
jim 072.d3 Added CallOS 27 Write printer
jim 072.d3 Added CallOS 28 Read printer
jim 072.d3 Added CallOS 29 Write RTC Reg
jim 072.d3 Added CallOS 30 Read RTC Reg
jim 072.d3 Added CallOS 31 Write RTC string
jim 072.d3 Added CallOS 32 Read RTC string
jim 072.d3 Added CallOS 33 Write RTC bcd
jim 072.d3 Added CallOS 34 Read RTC bcd
jim 072.d3 Added CallOS 35 Write LCD Reg
jim 072.d3 Added CallOS 36 Read LCD Reg
jim 072.d3 Added JobCall WritePrinter
jim 072.d3 Added JobCall ReadPrinter
jim 072.d3 Added JobCall PrintChar
jim 072.d3 Added JobCall PrintStreamZ
jim 072.d3 Added JobCall PrintStream
jim 072.d3 Added JobCall PrintServer
jim 072.d3 Added JobCall WriteRTCReg
jim 072.d3 Added JobCall ReadRTCReg
jim 072.d3 Added JobCall WriteRTC
jim 072.d3 Added JobCall ReadRTC
jim 072.d3 Added JobCall WriteRTCbcd
jim 072.d3 Added JobCall ReadRTCbcd
jim 072.d3 Added JobCall WriteLCDReg
jim 072.d3 Added JobCall ReadLCDReg
jim 072.d3 Added CallOS 37 Write Power ctrl
jim 072.d3 Added CallOS 38 Read Power ctrl
jim 072.d3 Implemented OS.PRINTER
jim 072.d3 Added JobCall PatchMF (MotorForward)
jim 072.d3 Changed irq.vec to int0.vec
jim 072.d3 Changed irq2.vec to int1.vec
jim 072.d3 Added int2irq.vec (wrksp+&20)
jim 072.d3 Added int3irq.vec (wrksp+&22)
jim 072.d3 Added int4irq.vec (wrksp+&24)
jim 072.d3 Added c0irq.vec (wrksp+&26)
jim 072.d3 Added c1irq.vec (wrksp+&28)
jim 072.d3 Added t1irq.vec (wrksp+&2A)
jim 072.d3 Added t2irq.vec (wrksp+&2C)
jim 072.d3 Added txirq.vec (wrksp+&2E)
jim 072.d3 Added tyirq.vec (wrksp+&30)
jim 072.d3 Added s1rirq.vec (wrksp+&32)
jim 072.d3 Added s1rirq.vec (wrksp+&34)
jim 072.d3 Added s2irq.vec (wrksp+&36)
jim 072.d3 Added adcirq.vec (wrksp+&38)
jim 072.d3 Renamed JobCall DownloadData38 to DownloadData740
jim 072.d3 Renamed JobCall UploadData38 to UploadData740
jim 072.d3 Renamed JobCall ExecuteCode38 to ExecuteCode740
jim 072.d3 Renamed JobCall ReadByte38 to ReadByte740
jim 072.d3 Renamed JobCall StoreByte38 to StoreByte740
jim 072.d4 Hardware update
jim 072.d4 Re-assigned CallOS 37 to Write Power/Charge control
jim 072.d4 Re-assigned CallOS 38 to Read Power/Charge control
jim 072.d4 Moved int2irq.vec to wrksp+&22
jim 072.d4 Moved int3irq.vec to wrksp+&24
jim 072.d4 Moved int4irq.vec to wrksp+&26
jim 072.d4 Moved c0irq.vec to wrksp+&28
jim 072.d4 Moved c1irq.vec to wrksp+&2A
jim 072.d4 Moved t1irq.vec to wrksp+&2C
jim 072.d4 Moved t2irq.vec to wrksp+&2E
jim 072.d4 Moved txirq.vec to wrksp+&30
jim 072.d4 Moved tyirq.vec to wrksp+&32
jim 072.d4 Moved s1rirq.vec to wrksp+&34
jim 072.d4 Moved s1rirq.vec to wrksp+&36
jim 072.d4 Moved s2irq.vec to wrksp+&38
jim 072.d4 Moved adcirq.vec to wrksp+&3A
jim 072.d4 Added OS.LCDVDU (&FFB7) and lcdvdu.vec (wrksp+&20)
jim 072.d5 Re-assigned CallOS 37 to Write/Read Power/Charge control
jim 072.d5 Re-assgined CallOS 38 Read Battery Voltage
jim 072.d5 OS.CALLOS now re-entrant
jim 072.d5 Fixed OS.PRINTER
jim 072.d5 Started to add internal logging software
jim 072.d5 Moved OS.LCDVDU to &FFB6
jim 072.d7 Added OS.PRINTERPOLL (&FFB3) and printerpoll.vec (wrksp+&3C)
bob 073 Matched jim & bob sensor lookup tables
bob 073 Added PatchMF
jim 072.dj Added OS.CALLOS 51 Read keypad press
jim 072.dj Added hard reset keypad press
jim 072.dk Added JobCall ReadOutputs
jim 072.do Changed soft reset of zero page locations
jim 072.do Changed MotorForward/Backward bitmaps
jim 072.dp Fixed OS.CALLOS WriteRTCbcd
jim 072.dq Fixed OS.CALLOS ReadRTCstring for correct 24hr operation
jim 072.dr Changed reset prompts
bob 074 Added support for Little Bob
jim 072.dy Added further RTC/CMOS support
jim 072.dB Removed double hard reset
jim 072.dE Set _cpu.mode depending on external memory requirement
jim 072.dF Added Insight code
jim 073 Sub-release
jim 074 Modification to LCD code - uses bsy flag all the time now
jim 074 Fixed OS.CALLOS 42 Write LCD Char Def
jim 074 Fixed OS.CALLOS 43 Read LCD Char Def
jim 075 Added simple battery charge code
jim 075 Fixed JobCall ReadSensorTable
jim 075 Fixed OS.CALLOS 42 Write LCD Char Def
jim 075 Fixed OS.CALLOS 43 Read LCD Char Def
jim 075 Added sleep code
jim 075 Added OS.CALLOS 52 Write Sleep Time
jim 075 Added OS.CALLOS 53 Read Sleep Time
jim 075 Modified battery charge code
jim 076 Modified JobCall ReadSensorTable
jim 076 Modified OS.CALLOS 26 ReadKeypad to do debounce
jim 077 Rewrote battery charging code
jim 077.2 Reduced stop charge threshold to 2
jim 077.3 Increased stop charge threshold to 3
jim 077.3 Added battery voltage averaging
bill 077 Stripped
bill 077 Moved ins to out port
bill 077 Added RTS
bill 077 Changed sensor ID system back to original, using p2.1
bill 077 Dedicated USB/RS selection line, RTS provisioned on p2.3
bill 077 Overload "bounce" timing
bill 078 CTS added
bill 079 Temperature fudge</nowiki>

SmartBox OS

2023-11-04T17:26:17Z

Benryves: /* OS_READJOB and OS_SENDJOB */

== Documentation for SmartBox OS 2.066 ==

The term JobCall is the concept of the routine itself, as opposed to
JobName (which is the actual name associated with it (eg. NameCode)) and
JobCode (which is the actual number associated with it (eg. 3)).

The term controller means the SmartBox, or any other incarnation
which may appear in future time !

The term OS means the controllers' Operating System.

== Preview ==

There are a number of reasons why using Machine Code on the
controller is more desirable than using the various JobCalls via the serial
link. One reason is speed, if the task which needs to be performed, has to
be performed very quickly (more quickly than can be achieved via the serial
link at least), then some code must be written to work in the controller
itself to achieve this sort of speed. If the task required is to be a
"background" task (ie. a task which may happen while other "things" carry
on as normal, like a change of state of a particular port) then it is far
easier to let the controller do all the work, maybe under interupts, than
continuously poll the controller checking the state of various things.
Another reason may be that you would like to add another JobCall to the OS,
extending the calls available to external applications (and the user at the
same time), without the user having to write the code himself to achieve the
aim. For advanced users, there is also the ablity to alter the way the OS
does various things and to have the controller in their "power", for
dedicated tasks etc.

One advantage of writing IN the controller is that that "function"
is available to any computer using the serial link, and is thus not fixed to
one computer type or even a computer at all, where the controller is used
free running, doing a particular task which doesn't need the intervention of
the user's own computer.

== Call types ==

There are three different types of machine code routines which can
be added to the controller. Each one is suited to a more advanced level
than the other, which also relates to the amount of work needed to actually
get the routine working ! The three levels are such:

=== Simple stand alone routine ===

Here the routine is just the routine
itself with no supporting code (ie. code to integrate with the rest of the
OS). It has to be called directly, by use of the ExecuteCode JobCall, thus
it usually resides at a fixed address and obviously does not offer the user
friendly way of accessing itself like there is with normal OS calls.

=== Extended JobCall ===

There is one JobCall in the OS (ExtendJob)
which can call various routines residing in memory, each one is identified
by a 8 bit number. The disadvantages of this way is that the call hasn't
got it's own JobName/JobCode and needs the extra byte to identify itself.
This is ideal for the quick routine which the user would like to add for
himself without having to resort to the extra code needed for the full
JobCode implementation.

=== Full JobCall ===

This is where the routine can define itself one
(or a number) of JobNames/JobCodes, it can integrate itself into an
extension of the OS in a complete way. The disadvantage is that extra
coding is needed to deal with the various OS calls it has to service and
that extra work is needed to produce a suitable file to place in the
controller.

Normally with most processors, including the 65c02, the machine code
produced is produced for a fixed memory address, and it cannot be made to
run in a different place in memory unless extra work is carried out by the
user, or at least a combination of the user and the OS. For the controller
this is a very severe disadvantage as most extensions are downloaded as
"modules" and to optimise memory a system has to be devised to enable
routines to be placed anywhere in memory, thus allowing no memory to be
wasted. In the OS there is a routine to do just this, though it does need
some help. A special version of the users code has to be developed, or
rather it has to be "processed" to add extra information on the end. Extra
code is needed to set up a few pointers and call the OS routine to relocate.
See later.

== Memory ==

The first 256 bytes of memory are somewhat special, most zero page
locations are reserved for use by the OS:

{|class="wikitable"
|-
|&00-&14||General workspace, used to pass parameters to some OS routines, can also be used by other routines DURING their execution.
|-
|&15-&6F||Reserved
|-
|&70-&9F||Available to the user
|-
|&A0||Accumulator store for irqs (irq_A)
|-
|&A1-&A2||Two byte counter, decremented at 100hz, useful for temporary timing purposes (fcount)
|-
|&A3||RAM size, high byte of RAM size of machine, ie. for 32k this will be &80 (RAM_size)
|-
|&A4-&AF||Reserved
|-
|&B0-&FF||Used by the OS
|-
|}

The rest of memory space is used for the processors stack, OS'
buffers, tables, vectors and, of course, the user available memory.

A breakdown of the rest of memory:

* &100 to &1FF is the 65c02's stack.
* &200-&2FF is used by the OS for various system functions and also contains the vector table, more on that later.
* &300-&3FF is the serial input buffer.
* &400-&47F is the internal job code call output buffer. (jobout_buf)
* &480-&4FF is the internal job code call input buffer. (jobin_buf)
* &500-&5FF is the job status table.
* &600 to the end of RAM memory is for the user. The user should not assume what the top of AVAILABLE memory is and use the system variable HIMEM.

In the controller the maximum limit of RAM is &8000 (which is 32k),
from &8000-&DFFF lies the memory mapped hardware, from &E000 to &FFF9 lies
the OS and from &FFFA to &FFFF lies the 65c02 vectors.

So the user has his own limits of free memory. The lowest limit is
called LOMEM and the highest limit is called HIMEM, everything between these
boundaries is termed "available" for use by anyone, the user or the OS.

Anyone can also claim memory, thus making private to them and not allowing
anyone else to use it. You do this by altering the value of LOMEM, HIMEM
should not be moved. Of course anyone claiming memory should first check
that there is enough memory available for the amount they want to claim for.
To take a common example, a downloadable routine which installs itself as a
extension routine, The download routine will first of all read LOMEM, read
HIMEM, check there is enough memory for the routine, download it to LOMEM
and call it, the downloaded routine will then relocate itself and alter
LOMEM so it is protected.

There is one other memory limit, this is called TOPMEM, this is the
absolute top limit of RAM, HIMEM will normally equal TOPMEM, but a future OS
may alter HIMEM to below TOPMEM. TOPMEM should be ignored ideally, and
HIMEM used.

== OS Calls ==

The OS has calls (ie. a jump instruction which you call, which
then calls, via a RAM vector, a routine in the OS) setup near the top of
memory, through these calls you do everything associated with the
controller. The calls are are such:

* OS_PRINTER at address &FFB9
* OS_CALLOS at address &FFBC
* OS_SENDBYTE at address &FFBF
* OS_READBYTE at address &FFC2
* OS_SENDJOB at address &FFC5
* OS_READJOB at address &FFC8
* OS_DECODEJOB at address &FFCB

The address is the one to call for the particular routine.

* OS_PRINTER is reserved for future use.
* OS_CALLOS calls upon the OS to do various things internally.
* OS_SENDBYTE sends a byte out of the serial port.
* OS_READBYTE reads a byte from the serial port.
* OS_SENDJOB 'sends' a value to the JobCall caller.
* OS_READJOB 'reads' a value from the JobCalls caller.
* OS_DECODEJOB decodes the Job number held in A and acts on it.

Note none of these things should be used in interupt routines,
except OS_CALLOS, of any sort, except if YOU know what state the machine is
in and WHY.

=== OS_READBYTE and OS_SENDBYTE: Serial Port ===

The serial port on the controller is currently based on the 6850
UART, this need not bother you as the OS deals with the thing entirely by
itself. The chip is setup by the OS to always have a word format of 8n1 and
a baud rate of 9600, this translates to 960cps. The 6850 has two divide
rates for the baud rate, the OS only uses one, using the other one is beyond
the scope of this document and shouldn't be neccessary to use.

Only receive interupts are used, transmission of characters is done
on a polled basis.

As said, there are two calls OS_READBYTE and OS_SENDBYTE.

==== OS_READBYTE ====

OS_READBYTE tests the serial input buffer and returns the character (if any
in the A register), the c flag states whether there was a character
returned.

{|class="calltable"
|Entry||
A, X, Y, c, z = undefined
|-
|Exit||
* X, Y preserved
* z = undefined
* if c = 1 (no character received)
*: A is preserved
* if c = 0 (character received)
*: A = character received
|}

==== OS_SENDBYTE ====

OS_SENDBYTE sends the character in the A register out of the serial
port, taking into consideration flow control etc.

{|class="calltable"
|Entry||
* A = character to send
* X, Y, c, z = undefined
|-
|Exit||
* A, X, Y, c is preserved
* z = undefined
|}

=== OS_READJOB and OS_SENDJOB ===

To send/receive data from the user (either internally or via the
serial port) you call OS_SENDJOB/OS_READJOB for the next byte. If your
JobCall requires dynamic use of data, ie. interaction, then a check of the
enviroment should be done to check the call came from the serial port. One
example of this is the OS JobCall MultipleServer, which requires dynamic use
of sending a stream of data until a reaction from the user to tell it to
stop.

==== OS_READJOB: Read job value from the user ====

{|class="calltable"
|Entry||
* A, X, Y, c, z = undefined
|-
|Exit||
* A = byte read
* X, Y is preserved
* c, z = undefined
|-
|Note||
When coming from the serial port it waits for a character to be received, if you are doing a serial only call and wish to have a loop checking for a character from the user while doing "your own thing", then OS_READBYTE should be used. For internal calls this reads data out of jobin_buf.
|}

==== OS_SENDJOB: Give a job value back to the user ====

{|class="calltable"
|Entry||
* A = byte to give
* X, Y, c, z = undefined
|-
|Exit||
* A, X, Y is preserved
* c, z = undefined
|-
|Note||
This will send either out to the serial port or place a byte in jobout_buf.
For internal calls this stores the value in jobout_buf, which is allocated 128 bytes, no bound checking is done so sending more than 128 bytes to OS_SENDJOB will cause corruption of some memory.
|}

=== OS_DECODEJOB ===

JobCalls in practise are really only used by the user, JobCalls
tend not to call other calls at all, infact you shouldn't really call
another call unless you were called from the serial port. If you do need to
call another JobCall then you do it like this; with each call you have
associated with it a number, and the call might require some data or give
some data back or both. With the serial port this is simple, you just send
data down and receive data as it is produced. You can't do this with
internal calls, and some calls will not let you call them from inside the
controller, you HAVE to call them from outside. But for the ones which do
let you, you do it with two data blocks, one for input TO the call and one
for output FROM the call. These are setup in a position in memory
(jobin_buf and jobout_buf), each one has a maximum of 128 bytes and this
should not be overflowed (OS_READJOB and OS_SENDJOB do NOT do any bound
checking). So to start with you place in the input block the data you want
to give the call (if any), call it, and then act on the data in the output
block (if any). The OS call OS_DECODEJOB is the one which actually calls
the JobCall handler and eventually the actual routine, you tell the JobCall
handler which call you want by placing the JobCode in the A register.

So for OS_DECODEJOB:

<nowiki> Call : OS_DECODEJOB
Entry : A = JobCode
X, Y, c, z = undefined
jobin_buf should contain any input data
Exit : A = flag
X = number of bytes given back by routine
Y = undefined
c = status, if set JobCall does not exist
z = status, if set JobCall cannot be called internally
jobout_buf contains any data sent from routine</nowiki>

A typical example would be:

<nowiki> LDA #readhimem ; JobCode for ReadHimem
JSR OS_DECODEJOB ; Call the JobCall handler
LDX jobout_buf ; Read HIMEM from buffer LSB
LDY jobout_buf+1 ; Read HIMEM from buffer MSB
STX jobin_buf ; Place LSB in input buffer
STY jobin_buf+1 ; Place MSB in input buffer
LDA #writelomem ; JobCode for WriteLomem
JSR OS_DECODEJOB ; Call the JobCall handler</nowiki>

which would read HIMEM, and then write LOMEM to be the same value, leaving
no spare memory left.

The reason why you should not call an internal call from another
internal call is that the same buffers (jobin_buf and jobout_buf) would be
used for both calls, causing conflict between the two calls, or rather to
the originator of the primary call ! The only time it would be safe if is
if you have already got all the data you want from jobin_buf and haven't
placed any in the jobout_buf (it would be lost if you had done).

=== 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.
|}

== 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
|}

== Starting Up ==

The setup procedure for setting up extension job calls is to:

# Claim the number of JobCodes you want
#: if success:
# patch the internal_vec and unknownjob_vec vectors
# move LOMEM up to protect your program
# do anything else for initial startup you may want to do
# return back, ready and waiting

This in code looks like:

<nowiki>execute
LDX #no_of_calls ; Number of JobCodes wanted
LDA #1 ; CALLOS, function 1, Claim JobCodes
JSR OS_CALLOS ; Call CALLOS
CPX #0 ; Check we were given some codes
BEQ noinstall ; No, don't bother installing ourself
STX call ; Store base address of JobCodes allocated
STY job_id ; Store JOB ID given

LDA internal_vec ; Get old internal_vec (LSB)
STA ovec ; Store it
LDA internal_vec+1 ; Get old internal_vec (MSB)
STA ovec+1 ; Store it
LDA #>internal_handle ; Our internal handler (LSB)
STA internal_vec ; Place it in the vector (LSB)
LDA #<internal_handle ; Our internal handler (MSB)
STA internal_vec+1 ; Place it in the vector (MSB)

LDA unknownjob_vec ; Get old unknownjob_vec (LSB)
STA ovec2 ; Store it
LDA unknownjob_vec+1 ; Get old unknownjob_vec (MSB)
STA ovec2+1 ; Store it
LDA #>job_handle ; Our unknown job handler (LSB)
STA unknownjob_vec ; Place it in the vector (LSB)
LDA #<job_handle ; Our unknown job handler (MSB)
STA unknownjob_vec+1 ; Place it in the vector (MSB)

LDX #>WriteLomem ; Point to JobName
LDY #<WriteLomem
JSR findjob ; Find WriteLomem code
BEQ noinstall ; Doesn't exist !
LDX #>end_of_code ; End of code (LSB)
LDY #<end_of_code ; End of code (MSB)
STX jobin_buf ; Place it in jobin_buf (LSB)
STY jobin_buf+1 ; Place it in jobin_buf+1 (MSB)
JSR OS_DECODEJOB ; Call JobCall handler

noinstall
RTS ; End - return to OS

findjob
STX zero.gp1 ; Zero page
STY zero.gp1+
LDY #0
findthisjoblo
LDA (zero.gp1),Y
STA jobin.buf,Y ; Store name in jobin_buf
INY
CMP #13
BNE findthisjoblo
LDA #3 ; NameCode
JSR OS.DECODEJOB ; Call NameCode
LDA jobout.buf ; Get returned value
RTS

WriteLomem STR "WriteLomem"</nowiki>

This will setup the various vectors and memory pointers for the
applicaion, the actual routines (internal_handle and job_handle) are fairly
straight forward and simple:

<nowiki>internal_handle
CMP #1 : Is it function call 1 (NameCode) ?
BNE internal_handle_2 ; No, check for function 2
LDA job_id ; Get our JOB ID number
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #>job_names ; Our Job name table (LSB)
LDY #<job_names ; Our Job name table (MSB)
LDA #2 ; CALLOS function 2
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes : Found, go off and claim call
LDA #1 ; Not found, restore A
JMP (ovec) ; Call back to old vector

internal_handle_2
CMP #2 ; Is it function call 2 (CodeName) ?
BNE internal_handle_3 ; No, unknown, pass on
LDA job_id ; Get our JOB ID
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #>job_names ; Our Job name table (LSB)
LDY #<job_names ; Our Job name table (MSB)
LDA #3 ; CALLOS function 3
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes ; Found, go off and claim call
LDA #2 ; Not found, restore A
JMP (ovec) ; Call back to old vector

internal_yes
LDA #0 ; We want to claim call for some reason

internal_handle_3
JMP (ovec) ; Call back to old vector

job_handle
PHA ; Mark sure to preserve A
CPY call ; Check call wanted against base of ours
BCC job_handle_no ; Less than our base, so definately not ours
TYA
SBC #no_of_calls ; Subtract number of calls we have
CMP call ; Now compare with base
BCC job_handle2 ; Yes, one of ours

job_handle.no
PLA ; Restore A
JMP (ovec2) ; Call back to old vector

job_handle2
TYA
SEC
SBC call ; Subtract our base from call
ASL A ; Times by 2 for offset into table
TAY ; Place in Y
LDA job_run_table,Y ; Get LSB of routine
STA zero_gp1 ; Store it for indirect jump (LSB)
LDA job_run_table+1,Y ; Get MSB of routine
STA zero_gp1+1 ; Store it for indirect jump (MSB)
PLA ; Restore A
JMP (zero_gp1) ; Call our relevant routine

job_names ; List of our JobNames
STR "TestJob" ; Test job name
DFB &FF ; &FF - marks end of table

job_run_table ; List of routine addresses to match Jobs
DFW job_TestJob ; Test job routine</nowiki>

== Relocation ==

The relocation method used will not do a complete relocation, ie.
from ANY address to ANY address. The only constraint on the addresses is
that they must be the same offset in the page, which means, &2602 and &3402
is alright but &2602 and &3455 is not, ie. the difference between the two
addresses must be a multiple of 256 bytes, as only the MSB is altered, this
should not cause any real problems. What is meant by the two addresses is
the address the code was originally assembled at and the address it wants
relocating to. Because of this programs must be multiples of 256 bytes, ie.
the low byte of LOMEM must ALWAYS be 0, your program should be padded out.

The relocation mechanism works by having a table, and to each byte
of code there is one BIT, if unset it means the byte of code should not be
relocated, else it should be, thus the BitMap table is 8 times smaller than
the code. To generate the BitMap you have to assemble the code at two
different places, and compare both sets of assembled code against each
other, the differences are where the code is to be relocated. The code
which is sent up to the controller is assumed to be assembled at address
&100, so the first code should be assembled at &100, the other one should be
assembled at another address, say &600, and the first one be sent up with
the BitMap. A program is availble for the Elk/Beeb/Arc with 65Tube/Mac with
BBC BASIC to compare the two files and create the BitMap.

All the program has to do to relocate itself is execute this bit of
code first of all: (address is the base address of the program, ie. &100
for the downloaded version)

<nowiki>execcall
LDA #>(execute-address) ; Final execution address offset (LSB)
STA zero_gp1
LDA #<(execute-address) ; Final execution address offset (MSB)
STA zero_gp1+1

LDA #>(BitMap-address) ; BitMap address offset (LSB)
STA zero_gp2
LDA #<(BitMap-address) ; BitMap address offset (MSB)
STA zero_gp2+1

LDA #>(execcall-address); Length of data to relocate (LSB)
STA zero_gp3
LDA #<(execcall-address); Length of data to relocate (MSB)
STA zero_gp3+1

TXA ; Execcall REAL address
SEC
SBC #>(execcall-address); Subrtract length
TAX ; Put it back in X
TYA ; Ditto for MSB
SBC #<(execcall-address)
TAY
LDA #4 ; CALLOS function for Relocate
JMP OS_CALLOS ; Call CALLOS

BitMap ; BitMap start</nowiki>

This will relocate the code and automatically call the execution
address, which should be the initialisation code (ie. setup internal_vec
and unknownjob_vec etc.). "address" is the address the code is started to
assemble at, &100 for the version to be uploaded. The upload routine should
pass in X and Y (via ExecuteCode) the address of the start of execcall, this
means that the routine can tell where it is in memory, subtracting the
length gives the start of the code to relocate.

== Layout Summary ==

The layout of a full application should be like this by now:

<nowiki> start of code
program job codes, data etc.
internal handler
job handler
end of code
initialisation (setup internal etc.)
end of code to be relocated
execution (relocation)
relocation BitMap</nowiki>

Because of memory space the initialisation code should be placed
outside the reserved memory limit of the program, as it is only called once
and not needed again.

== Other miscellaneous calls ==

<nowiki>Call : OS_PRINTER
Purpose : To place a character in the printer buffer
Entry : A = character to send
X, Y, c, z = undefined
Exit : A, X, Y is preserved
if c = 0 (printed)
The printer is on and the character was inserted
if c = 1 (not printed)
The printer is off and the character was forgotten
z = undefined
Note : The character goes into the printer buffer and will be
actually sent to the printer when the printer asks for it. If the printer
was not awake to begin with, an attempt is made to wake it up, thus
meaning that in some circumstances when the printer wasn't ready a
character may be lost, this cannot be helped. If the printer is off (via
the BCD switch) then the character will be forgotten as the Printer Buffer
is inactive.</nowiki>

The module is located at &8000 in memory, and should be a EPROM placed
in the second ROM socket in the controller (ie. the top RAM socket). This
module is primary designed to turn the Controller into a dedicated task,
making it perform some function from switch on. It could also be used to
add more permant JobCalls to the Controller, in the process taking up much
less RAM), but because of there being only one Module present this feature
is limited, and is much more suited to a collection of the user's own
personal routines.

For the OS to recognise a module as being in place the text "Module" is
looked for, the layout of a module should be like this (starting at
&8000):

<nowiki>Offset value comment
0 "Module" The OS checks for this string
6 0 End of check string
7 Language entry Address of 'Language' entry
9 Service entry Address of 'Service' entry
11 "<Module Title>" Module title
0 End of Module title

"<Module part>" Part Module Title
0 End of Part Module Title
"x.xx" Part version number

&FF End of parts list</nowiki>

The language entry is a 2 byte value holding the address of the language
entry routine, this is called on reset, if the BCD is set correctly. A
value of less than &8000 means there is no valid language entry and any
language calls are ignored. If a RTS is made the OS carries on as it would
have if there wasn't a language call.

The service entry is a 2 byte value holding the address of the service
entry routine, this is called at various appropiate moments with service
numbers in A. A list of current calls is thus:

<nowiki> 0 - Not used
1 - Unknown Job Code
2 - Centisecond call
3 - Irq2 (unknown IRQ)
4 - internal_vec call (exit with A=0 to claim)
254 - RESET
255 - BRK</nowiki>

On exit all registers and flags should be preserved. For call 1 the
unknown job value is held in the Y register, the enviroment is held in the
X register, on exit, X should contain the flag, as A does from the exit of
unknownjob_vec. For the rest of calls, X and Y are undefined.

For both Service and Language entry points, a value of 0 means "there is
no valid routine" and the module isn't called for that type of entry.

Finally a full implementation of a JobCall, from start to finish.

<nowiki> DIM data% &1000
:
no_of_calls = 1
:
VIA = &E030
ACIA = &E010
ADC = &E000
AUX_PORT = &E020
brk_vec = &200
nmi_vec = &202
irq_vec = &204
irq2_vec = &206
sendserial_vec = &208
readserial_vec = &20A
sendjob_vec = &20C
readjob_vec = &20E
decodejob_vec = &210
unknownjob_vec = &212
extjob_vec = &214
centisec_vec = &216
internal_vec = &218
callos_vec = &21A
printer_vec = &21C
zero_gp1 = 0
zero_gp2 = 2
zero_gp3 = 4
zero_gp4 = 6
zero_gp5 = 8
zero_gp6 = 10
zero_gp7 = 12
zero_gp8 = 14
zero_gp9 = 16
zero_gp10 = 18
user_reserved = &70
irq_A = &A0
fcount = &A1
RAM_size = &A3
jobout_buf = &400
jobin_buf = &480
OS_PRINTER = &FFB9
OS_CALLOS = &FFBC
OS_SENDBYTE = &FFBF
OS_READBYTE = &FFC2
OS_SENDJOB = &FFC5
OS_READJOB = &FFC8
OS_DECODEJOB = &FFCB
:
FOR create=1 TO 2
:
FOR pass%=4 TO 7 STEP 3
P%=&100*create : O%=data%
[OPT pass%
:
.job_DemoJob
CMP #1
BEQ DemoJob_go
LDA #1
LDY #0
RTS
/
.DemoJob_go

:
.internal_handle
CMP #1 ; Is it function call 1 (NameCode) ?
BNE internal_handle_2 ; No, check for function 2
/
LDA job_id ; Get our JOB ID number
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #job_names MOD 256 ; Our Job name table (LSB)
LDY #job_names DIV 256 ; Our Job name table (MSB)
LDA #2 ; CALLOS function 2
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes ; Found, go off and claim call
LDA #1 ; Not found, restore A
JMP (ovec) ; Call back to old vector
/
.internal_handle_2
CMP #2 ; Is it function call 2 (CodeName) ?
BNE internal_handle_3 ; No, unknown, pass on
/
LDA job_id ; Get our JOB ID
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #job_names MOD 256 ; Our Job name table (LSB)
LDY #job_names DIV 256 ; Our Job name table (MSB)
LDA #3 ; CALLOS function 3
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes ; Found, go off and claim call
LDA #2 ; Not found, restore A
JMP (ovec) ; Call back to old vector
/
.internal_yes
LDA #0 ; We want to claim call for some reason
/
.internal_handle_3
JMP (ovec) ; Call back to old vector
:
.job_handle
PHA ; Make sure to preserve A
CPY call ; Check call wanted against base of ours
BCC job_handle_no ; Less than our base, so definately not ours
TYA
SBC #no_of_calls ; Subtract number of calls we have
CMP call ; Now compare with base
BCC job_handle2 ; Yes, one of ours
/
.job_handle.no
PLA ; Restore A
JMP (ovec2) ; Call back to old vector
/
.job_handle2
TYA
SEC
SBC call ; Subtract our base from call
ASL A ; Times by 2 for offset into table
TAY ; Place in Y
LDA job_run_table,Y ; Get LSB of routine
STA zero_gp1 ; Store it for indirect jump (LSB)
LDA job_run_table+1,Y ; Get MSB of routine
STA zero_gp1+1 ; Store it for indirect jump (MSB)
PLA ; Restore A
JMP (zero_gp1) ; Call our relevant routine
:
.job_names ; List of our JobNames
EQUS "DemoJob":EQUB 13 ; Test job name
/
EQUB &FF ; &FF - marks end of table
:
.job_run_table ; List of routine addresses to match Jobs
EQUW job_DemoJob ; Test job routine
:
.call : EQUB 0 ; Store for our JobCode base
.job_id : EQUB 0 ; Store for our JobId
.ovec : EQUW 0 ; Store for old internal_vec value
.ovec2 : EQUW 0 ; Store for old unknownjob_vec value
:
EQUS STRING$(&100-(P% MOD 256),CHR$0)
.end_of_code ; end_of_code should be on page boundry
:
.execute
LDX #no_of_calls ; Number of JobCodes wanted
LDA #1 ; CALLOS, function 1, Claim JobCodes
JSR OS_CALLOS ; Call CALLOS
STX call ; Store base address of JobCodes allocated
STY job_id ; Store JOB ID given
CPX #0 ; Check we were given some codes
BEQ noinstall ; No, don't bother installing ourself
/
LDA internal_vec ; Get old internal_vec (LSB)
STA ovec ; Store it
LDA internal_vec+1 ; Get old internal_vec (MSB)
STA ovec+1 ; Store it
LDA #internal_handle MOD 256 ; Our internal handler (LSB)
STA internal_vec ; Place it in the vector (LSB)
LDA #internal_handle DIV 256 ; Our internal handler (MSB)
STA internal_vec+1 ; Place it in the vector (MSB)
/
LDA unknownjob_vec ; Get old unknownjob_vec (LSB)
STA ovec2 ; Store it
LDA unknownjob_vec+1 ; Get old unknownjob_vec (MSB)
STA ovec2+1 ; Store it
LDA #job_handle MOD 256 ; Our unknown job handler (LSB)
STA unknownjob_vec ; Place it in the vector (LSB)
LDA #job_handle DIV 256 ; Our unknown job handler (MSB)
STA unknownjob_vec+1 ; Place it in the vector (MSB)
/
LDX #end_of_code MOD 256 ; End of code (LSB)
LDY #end_of_code DIV 256 ; End of code (MSB)
STX jobin_buf ; Place it in jobin_buf (LSB)
STY jobin_buf+1 ; Place it in jobin_buf+1 (MSB)
LDA #65 ; JobCode for WriteLomem
JSR OS_DECODEJOB ; Call JobCall handler
/
.noinstall
RTS ; End - return to OS
:
.execcall
LDA #>(execute-address) ; Final execution address offset (LSB)
STA zero_gp1
LDA #<(execute-address) ; Final execution address offset (MSB)
STA zero_gp1+1
/
LDA #>(BitMap-address) ; BitMap address offset (LSB)
STA zero_gp2
LDA #<(BitMap-address) ; BitMap address offset (MSB)
STA zero_gp2+1
/
LDA #>(execcall-address) ; Length of data to relocate (LSB)
STA zero_gp3
LDA #<(execcall-address) ; Length of data to relocate (MSB)
STA zero_gp3+1
/
TXA ; Execcall REAL address
SEC
SBC #>(execcall-address) ; Subrtract length
TAX ; Put it back in X
TYA ; Ditto for MSB
SBC #<(execcall-address)
TAY
LDA #4 ; CALLOS function for Relocate
JMP OS_CALLOS ; Call CALLOS
/
.BitMap ; BitMap start
:
]
NEXT
:
OSCLI "SAVE code"+STR$create+" "+STR$~data%+" "+STR$~O%
:
NEXT</nowiki>

== Changelog ==

<nowiki>bob 071 Fixed MotorForward bug (%10)
bob 072 CallOS 14 now checks current adc.owner status
jim 072.d1 * Rewrite for new hardware/processor *
jim 072.d1 Moved vectors/workspace to &440
jim 072.d1 Moved rs.inp.buf to &500
jim 072.d1 Moved jobout.buf to &600
jim 072.d1 Moved jobin.buf to &680
jim 072.d1 Moved jobs.status to &700
jim 072.d1 Added irq.X (&A4)
jim 072.d1 Added irq.Y (&A5)
jim 072.d1 Removed short detection code
jim 072.d1 Voided CallOS' 6,7,8,9,10,11,13,16,17,18,19
jim 072.d1 Removed JobCalls ReadADCReg,WriteADCReg
jim 072.d1 Removed JobCalls ReadACIAReg,WriteACIAReg
jim 072.d1 Removed JobCalls ReadVIAReg,WriteVIAReg,SetVIAHigh,SetVIALow
jim 072.d1 Added CallOS 21 Write Outputs
jim 072.d1 Added CallOS 22 Read Outputs added
jim 072.d1 Added CallOS 23 Read Inputs added
jim 072.d1 Added CallOS 24 Write Motors
jim 072.d1 Added CallOS 25 Read Motors
jim 072.d1 Added CallOS 26 Read Keypad
jim 072.d1 Expanded CallOS 5 information
jim 072.d1 Added JobCall IdentSystem to return CallOS 5 info
jim 072.d1 JobCalls now use appropriate CallOS'
jim 072.d1 OS.READBYTE no longer preserves A on CS
jim 072.d1 irq.vec,irq2.vec,nmi.vec now redundant
jim 072.d1 Renamed JobCall DownloadData to DownloadData38
jim 072.d1 Renamed JobCall UploadData to UploadData38
jim 072.d1 Renamed JobCall ExecuteCode to ExecuteCode38
jim 072.d1 Renamed JobCall ReadByte to ReadByte38
jim 072.d1 Renamed JobCall StoreByte to StoreByte38
jim 072.d1 JobCall ForcedADCRead now checks adc.owner first
jim 072.d3 Added CallOS 27 Write printer
jim 072.d3 Added CallOS 28 Read printer
jim 072.d3 Added CallOS 29 Write RTC Reg
jim 072.d3 Added CallOS 30 Read RTC Reg
jim 072.d3 Added CallOS 31 Write RTC string
jim 072.d3 Added CallOS 32 Read RTC string
jim 072.d3 Added CallOS 33 Write RTC bcd
jim 072.d3 Added CallOS 34 Read RTC bcd
jim 072.d3 Added CallOS 35 Write LCD Reg
jim 072.d3 Added CallOS 36 Read LCD Reg
jim 072.d3 Added JobCall WritePrinter
jim 072.d3 Added JobCall ReadPrinter
jim 072.d3 Added JobCall PrintChar
jim 072.d3 Added JobCall PrintStreamZ
jim 072.d3 Added JobCall PrintStream
jim 072.d3 Added JobCall PrintServer
jim 072.d3 Added JobCall WriteRTCReg
jim 072.d3 Added JobCall ReadRTCReg
jim 072.d3 Added JobCall WriteRTC
jim 072.d3 Added JobCall ReadRTC
jim 072.d3 Added JobCall WriteRTCbcd
jim 072.d3 Added JobCall ReadRTCbcd
jim 072.d3 Added JobCall WriteLCDReg
jim 072.d3 Added JobCall ReadLCDReg
jim 072.d3 Added CallOS 37 Write Power ctrl
jim 072.d3 Added CallOS 38 Read Power ctrl
jim 072.d3 Implemented OS.PRINTER
jim 072.d3 Added JobCall PatchMF (MotorForward)
jim 072.d3 Changed irq.vec to int0.vec
jim 072.d3 Changed irq2.vec to int1.vec
jim 072.d3 Added int2irq.vec (wrksp+&20)
jim 072.d3 Added int3irq.vec (wrksp+&22)
jim 072.d3 Added int4irq.vec (wrksp+&24)
jim 072.d3 Added c0irq.vec (wrksp+&26)
jim 072.d3 Added c1irq.vec (wrksp+&28)
jim 072.d3 Added t1irq.vec (wrksp+&2A)
jim 072.d3 Added t2irq.vec (wrksp+&2C)
jim 072.d3 Added txirq.vec (wrksp+&2E)
jim 072.d3 Added tyirq.vec (wrksp+&30)
jim 072.d3 Added s1rirq.vec (wrksp+&32)
jim 072.d3 Added s1rirq.vec (wrksp+&34)
jim 072.d3 Added s2irq.vec (wrksp+&36)
jim 072.d3 Added adcirq.vec (wrksp+&38)
jim 072.d3 Renamed JobCall DownloadData38 to DownloadData740
jim 072.d3 Renamed JobCall UploadData38 to UploadData740
jim 072.d3 Renamed JobCall ExecuteCode38 to ExecuteCode740
jim 072.d3 Renamed JobCall ReadByte38 to ReadByte740
jim 072.d3 Renamed JobCall StoreByte38 to StoreByte740
jim 072.d4 Hardware update
jim 072.d4 Re-assigned CallOS 37 to Write Power/Charge control
jim 072.d4 Re-assigned CallOS 38 to Read Power/Charge control
jim 072.d4 Moved int2irq.vec to wrksp+&22
jim 072.d4 Moved int3irq.vec to wrksp+&24
jim 072.d4 Moved int4irq.vec to wrksp+&26
jim 072.d4 Moved c0irq.vec to wrksp+&28
jim 072.d4 Moved c1irq.vec to wrksp+&2A
jim 072.d4 Moved t1irq.vec to wrksp+&2C
jim 072.d4 Moved t2irq.vec to wrksp+&2E
jim 072.d4 Moved txirq.vec to wrksp+&30
jim 072.d4 Moved tyirq.vec to wrksp+&32
jim 072.d4 Moved s1rirq.vec to wrksp+&34
jim 072.d4 Moved s1rirq.vec to wrksp+&36
jim 072.d4 Moved s2irq.vec to wrksp+&38
jim 072.d4 Moved adcirq.vec to wrksp+&3A
jim 072.d4 Added OS.LCDVDU (&FFB7) and lcdvdu.vec (wrksp+&20)
jim 072.d5 Re-assigned CallOS 37 to Write/Read Power/Charge control
jim 072.d5 Re-assgined CallOS 38 Read Battery Voltage
jim 072.d5 OS.CALLOS now re-entrant
jim 072.d5 Fixed OS.PRINTER
jim 072.d5 Started to add internal logging software
jim 072.d5 Moved OS.LCDVDU to &FFB6
jim 072.d7 Added OS.PRINTERPOLL (&FFB3) and printerpoll.vec (wrksp+&3C)
bob 073 Matched jim & bob sensor lookup tables
bob 073 Added PatchMF
jim 072.dj Added OS.CALLOS 51 Read keypad press
jim 072.dj Added hard reset keypad press
jim 072.dk Added JobCall ReadOutputs
jim 072.do Changed soft reset of zero page locations
jim 072.do Changed MotorForward/Backward bitmaps
jim 072.dp Fixed OS.CALLOS WriteRTCbcd
jim 072.dq Fixed OS.CALLOS ReadRTCstring for correct 24hr operation
jim 072.dr Changed reset prompts
bob 074 Added support for Little Bob
jim 072.dy Added further RTC/CMOS support
jim 072.dB Removed double hard reset
jim 072.dE Set _cpu.mode depending on external memory requirement
jim 072.dF Added Insight code
jim 073 Sub-release
jim 074 Modification to LCD code - uses bsy flag all the time now
jim 074 Fixed OS.CALLOS 42 Write LCD Char Def
jim 074 Fixed OS.CALLOS 43 Read LCD Char Def
jim 075 Added simple battery charge code
jim 075 Fixed JobCall ReadSensorTable
jim 075 Fixed OS.CALLOS 42 Write LCD Char Def
jim 075 Fixed OS.CALLOS 43 Read LCD Char Def
jim 075 Added sleep code
jim 075 Added OS.CALLOS 52 Write Sleep Time
jim 075 Added OS.CALLOS 53 Read Sleep Time
jim 075 Modified battery charge code
jim 076 Modified JobCall ReadSensorTable
jim 076 Modified OS.CALLOS 26 ReadKeypad to do debounce
jim 077 Rewrote battery charging code
jim 077.2 Reduced stop charge threshold to 2
jim 077.3 Increased stop charge threshold to 3
jim 077.3 Added battery voltage averaging
bill 077 Stripped
bill 077 Moved ins to out port
bill 077 Added RTS
bill 077 Changed sensor ID system back to original, using p2.1
bill 077 Dedicated USB/RS selection line, RTS provisioned on p2.3
bill 077 Overload "bounce" timing
bill 078 CTS added
bill 079 Temperature fudge</nowiki>

SmartBox OS

2023-11-04T17:23:01Z

Benryves: /* Serial Port */

== Documentation for SmartBox OS 2.066 ==

The term JobCall is the concept of the routine itself, as opposed to
JobName (which is the actual name associated with it (eg. NameCode)) and
JobCode (which is the actual number associated with it (eg. 3)).

The term controller means the SmartBox, or any other incarnation
which may appear in future time !

The term OS means the controllers' Operating System.

== Preview ==

There are a number of reasons why using Machine Code on the
controller is more desirable than using the various JobCalls via the serial
link. One reason is speed, if the task which needs to be performed, has to
be performed very quickly (more quickly than can be achieved via the serial
link at least), then some code must be written to work in the controller
itself to achieve this sort of speed. If the task required is to be a
"background" task (ie. a task which may happen while other "things" carry
on as normal, like a change of state of a particular port) then it is far
easier to let the controller do all the work, maybe under interupts, than
continuously poll the controller checking the state of various things.
Another reason may be that you would like to add another JobCall to the OS,
extending the calls available to external applications (and the user at the
same time), without the user having to write the code himself to achieve the
aim. For advanced users, there is also the ablity to alter the way the OS
does various things and to have the controller in their "power", for
dedicated tasks etc.

One advantage of writing IN the controller is that that "function"
is available to any computer using the serial link, and is thus not fixed to
one computer type or even a computer at all, where the controller is used
free running, doing a particular task which doesn't need the intervention of
the user's own computer.

== Call types ==

There are three different types of machine code routines which can
be added to the controller. Each one is suited to a more advanced level
than the other, which also relates to the amount of work needed to actually
get the routine working ! The three levels are such:

=== Simple stand alone routine ===

Here the routine is just the routine
itself with no supporting code (ie. code to integrate with the rest of the
OS). It has to be called directly, by use of the ExecuteCode JobCall, thus
it usually resides at a fixed address and obviously does not offer the user
friendly way of accessing itself like there is with normal OS calls.

=== Extended JobCall ===

There is one JobCall in the OS (ExtendJob)
which can call various routines residing in memory, each one is identified
by a 8 bit number. The disadvantages of this way is that the call hasn't
got it's own JobName/JobCode and needs the extra byte to identify itself.
This is ideal for the quick routine which the user would like to add for
himself without having to resort to the extra code needed for the full
JobCode implementation.

=== Full JobCall ===

This is where the routine can define itself one
(or a number) of JobNames/JobCodes, it can integrate itself into an
extension of the OS in a complete way. The disadvantage is that extra
coding is needed to deal with the various OS calls it has to service and
that extra work is needed to produce a suitable file to place in the
controller.

Normally with most processors, including the 65c02, the machine code
produced is produced for a fixed memory address, and it cannot be made to
run in a different place in memory unless extra work is carried out by the
user, or at least a combination of the user and the OS. For the controller
this is a very severe disadvantage as most extensions are downloaded as
"modules" and to optimise memory a system has to be devised to enable
routines to be placed anywhere in memory, thus allowing no memory to be
wasted. In the OS there is a routine to do just this, though it does need
some help. A special version of the users code has to be developed, or
rather it has to be "processed" to add extra information on the end. Extra
code is needed to set up a few pointers and call the OS routine to relocate.
See later.

== Memory ==

The first 256 bytes of memory are somewhat special, most zero page
locations are reserved for use by the OS:

{|class="wikitable"
|-
|&00-&14||General workspace, used to pass parameters to some OS routines, can also be used by other routines DURING their execution.
|-
|&15-&6F||Reserved
|-
|&70-&9F||Available to the user
|-
|&A0||Accumulator store for irqs (irq_A)
|-
|&A1-&A2||Two byte counter, decremented at 100hz, useful for temporary timing purposes (fcount)
|-
|&A3||RAM size, high byte of RAM size of machine, ie. for 32k this will be &80 (RAM_size)
|-
|&A4-&AF||Reserved
|-
|&B0-&FF||Used by the OS
|-
|}

The rest of memory space is used for the processors stack, OS'
buffers, tables, vectors and, of course, the user available memory.

A breakdown of the rest of memory:

* &100 to &1FF is the 65c02's stack.
* &200-&2FF is used by the OS for various system functions and also contains the vector table, more on that later.
* &300-&3FF is the serial input buffer.
* &400-&47F is the internal job code call output buffer. (jobout_buf)
* &480-&4FF is the internal job code call input buffer. (jobin_buf)
* &500-&5FF is the job status table.
* &600 to the end of RAM memory is for the user. The user should not assume what the top of AVAILABLE memory is and use the system variable HIMEM.

In the controller the maximum limit of RAM is &8000 (which is 32k),
from &8000-&DFFF lies the memory mapped hardware, from &E000 to &FFF9 lies
the OS and from &FFFA to &FFFF lies the 65c02 vectors.

So the user has his own limits of free memory. The lowest limit is
called LOMEM and the highest limit is called HIMEM, everything between these
boundaries is termed "available" for use by anyone, the user or the OS.

Anyone can also claim memory, thus making private to them and not allowing
anyone else to use it. You do this by altering the value of LOMEM, HIMEM
should not be moved. Of course anyone claiming memory should first check
that there is enough memory available for the amount they want to claim for.
To take a common example, a downloadable routine which installs itself as a
extension routine, The download routine will first of all read LOMEM, read
HIMEM, check there is enough memory for the routine, download it to LOMEM
and call it, the downloaded routine will then relocate itself and alter
LOMEM so it is protected.

There is one other memory limit, this is called TOPMEM, this is the
absolute top limit of RAM, HIMEM will normally equal TOPMEM, but a future OS
may alter HIMEM to below TOPMEM. TOPMEM should be ignored ideally, and
HIMEM used.

== OS Calls ==

The OS has calls (ie. a jump instruction which you call, which
then calls, via a RAM vector, a routine in the OS) setup near the top of
memory, through these calls you do everything associated with the
controller. The calls are are such:

* OS_PRINTER at address &FFB9
* OS_CALLOS at address &FFBC
* OS_SENDBYTE at address &FFBF
* OS_READBYTE at address &FFC2
* OS_SENDJOB at address &FFC5
* OS_READJOB at address &FFC8
* OS_DECODEJOB at address &FFCB

The address is the one to call for the particular routine.

* OS_PRINTER is reserved for future use.
* OS_CALLOS calls upon the OS to do various things internally.
* OS_SENDBYTE sends a byte out of the serial port.
* OS_READBYTE reads a byte from the serial port.
* OS_SENDJOB 'sends' a value to the JobCall caller.
* OS_READJOB 'reads' a value from the JobCalls caller.
* OS_DECODEJOB decodes the Job number held in A and acts on it.

Note none of these things should be used in interupt routines,
except OS_CALLOS, of any sort, except if YOU know what state the machine is
in and WHY.

=== OS_READBYTE and OS_SENDBYTE: Serial Port ===

The serial port on the controller is currently based on the 6850
UART, this need not bother you as the OS deals with the thing entirely by
itself. The chip is setup by the OS to always have a word format of 8n1 and
a baud rate of 9600, this translates to 960cps. The 6850 has two divide
rates for the baud rate, the OS only uses one, using the other one is beyond
the scope of this document and shouldn't be neccessary to use.

Only receive interupts are used, transmission of characters is done
on a polled basis.

As said, there are two calls OS_READBYTE and OS_SENDBYTE.

==== OS_READBYTE ====

OS_READBYTE tests the serial input buffer and returns the character (if any
in the A register), the c flag states whether there was a character
returned.

{|class="calltable"
|Entry||
A, X, Y, c, z = undefined
|-
|Exit||
* X, Y preserved
* z = undefined
* if c = 1 (no character received)
*: A is preserved
* if c = 0 (character received)
*: A = character received
|}

==== OS_SENDBYTE ====

OS_SENDBYTE sends the character in the A register out of the serial
port, taking into consideration flow control etc.

{|class="calltable"
|Entry||
* A = character to send
* X, Y, c, z = undefined
|-
|Exit||
* A, X, Y, c is preserved
* z = undefined
|}

=== OS_READJOB and OS_SENDJOB ===

To send/receive data from the user (either internally or via the
serial port) you call OS_SENDJOB/OS_READJOB for the next byte. If your
JobCall requires dynamic use of data, ie. interaction, then a check of the
enviroment should be done to check the call came from the serial port. One
example of this is the OS JobCall MultipleServer, which requires dynamic use
of sending a stream of data until a reaction from the user to tell it to
stop.

<nowiki> Call : OS_READJOB
Purpose: To read job value from the user
Entry : A, X, Y, c, z = undefined
Exit : A = byte read
X, Y is preserved
c, z = undefined
Note : When coming from the serial port it waits for a character to be
received, if you are doing a serial only call and wish to have a loop
checking for a character from the user while doing "your own thing", then
OS_READBYTE should be used. For internal calls this reads data out of
jobin_buf.</nowiki>

<nowiki> Call : OS_SENDJOB
Purpose: To give a job value back to the user
Entry : A = byte to give
X, Y, c, z = undefined
Exit : A, X, Y is preserved
c, z = undefined
Note : This will send either out to the serial port or place a byte in
jobout_buf. For internal calls this stores the value in jobout_buf, which
is allocated 128 bytes, no bound checking is done so sending more than 128
bytes to OS_SENDJOB will cause corruption of some memory.</nowiki>

=== OS_DECODEJOB ===

JobCalls in practise are really only used by the user, JobCalls
tend not to call other calls at all, infact you shouldn't really call
another call unless you were called from the serial port. If you do need to
call another JobCall then you do it like this; with each call you have
associated with it a number, and the call might require some data or give
some data back or both. With the serial port this is simple, you just send
data down and receive data as it is produced. You can't do this with
internal calls, and some calls will not let you call them from inside the
controller, you HAVE to call them from outside. But for the ones which do
let you, you do it with two data blocks, one for input TO the call and one
for output FROM the call. These are setup in a position in memory
(jobin_buf and jobout_buf), each one has a maximum of 128 bytes and this
should not be overflowed (OS_READJOB and OS_SENDJOB do NOT do any bound
checking). So to start with you place in the input block the data you want
to give the call (if any), call it, and then act on the data in the output
block (if any). The OS call OS_DECODEJOB is the one which actually calls
the JobCall handler and eventually the actual routine, you tell the JobCall
handler which call you want by placing the JobCode in the A register.

So for OS_DECODEJOB:

<nowiki> Call : OS_DECODEJOB
Entry : A = JobCode
X, Y, c, z = undefined
jobin_buf should contain any input data
Exit : A = flag
X = number of bytes given back by routine
Y = undefined
c = status, if set JobCall does not exist
z = status, if set JobCall cannot be called internally
jobout_buf contains any data sent from routine</nowiki>

A typical example would be:

<nowiki> LDA #readhimem ; JobCode for ReadHimem
JSR OS_DECODEJOB ; Call the JobCall handler
LDX jobout_buf ; Read HIMEM from buffer LSB
LDY jobout_buf+1 ; Read HIMEM from buffer MSB
STX jobin_buf ; Place LSB in input buffer
STY jobin_buf+1 ; Place MSB in input buffer
LDA #writelomem ; JobCode for WriteLomem
JSR OS_DECODEJOB ; Call the JobCall handler</nowiki>

which would read HIMEM, and then write LOMEM to be the same value, leaving
no spare memory left.

The reason why you should not call an internal call from another
internal call is that the same buffers (jobin_buf and jobout_buf) would be
used for both calls, causing conflict between the two calls, or rather to
the originator of the primary call ! The only time it would be safe if is
if you have already got all the data you want from jobin_buf and haven't
placed any in the jobout_buf (it would be lost if you had done).

=== 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.
|}

== 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
|}

== Starting Up ==

The setup procedure for setting up extension job calls is to:

# Claim the number of JobCodes you want
#: if success:
# patch the internal_vec and unknownjob_vec vectors
# move LOMEM up to protect your program
# do anything else for initial startup you may want to do
# return back, ready and waiting

This in code looks like:

<nowiki>execute
LDX #no_of_calls ; Number of JobCodes wanted
LDA #1 ; CALLOS, function 1, Claim JobCodes
JSR OS_CALLOS ; Call CALLOS
CPX #0 ; Check we were given some codes
BEQ noinstall ; No, don't bother installing ourself
STX call ; Store base address of JobCodes allocated
STY job_id ; Store JOB ID given

LDA internal_vec ; Get old internal_vec (LSB)
STA ovec ; Store it
LDA internal_vec+1 ; Get old internal_vec (MSB)
STA ovec+1 ; Store it
LDA #>internal_handle ; Our internal handler (LSB)
STA internal_vec ; Place it in the vector (LSB)
LDA #<internal_handle ; Our internal handler (MSB)
STA internal_vec+1 ; Place it in the vector (MSB)

LDA unknownjob_vec ; Get old unknownjob_vec (LSB)
STA ovec2 ; Store it
LDA unknownjob_vec+1 ; Get old unknownjob_vec (MSB)
STA ovec2+1 ; Store it
LDA #>job_handle ; Our unknown job handler (LSB)
STA unknownjob_vec ; Place it in the vector (LSB)
LDA #<job_handle ; Our unknown job handler (MSB)
STA unknownjob_vec+1 ; Place it in the vector (MSB)

LDX #>WriteLomem ; Point to JobName
LDY #<WriteLomem
JSR findjob ; Find WriteLomem code
BEQ noinstall ; Doesn't exist !
LDX #>end_of_code ; End of code (LSB)
LDY #<end_of_code ; End of code (MSB)
STX jobin_buf ; Place it in jobin_buf (LSB)
STY jobin_buf+1 ; Place it in jobin_buf+1 (MSB)
JSR OS_DECODEJOB ; Call JobCall handler

noinstall
RTS ; End - return to OS

findjob
STX zero.gp1 ; Zero page
STY zero.gp1+
LDY #0
findthisjoblo
LDA (zero.gp1),Y
STA jobin.buf,Y ; Store name in jobin_buf
INY
CMP #13
BNE findthisjoblo
LDA #3 ; NameCode
JSR OS.DECODEJOB ; Call NameCode
LDA jobout.buf ; Get returned value
RTS

WriteLomem STR "WriteLomem"</nowiki>

This will setup the various vectors and memory pointers for the
applicaion, the actual routines (internal_handle and job_handle) are fairly
straight forward and simple:

<nowiki>internal_handle
CMP #1 : Is it function call 1 (NameCode) ?
BNE internal_handle_2 ; No, check for function 2
LDA job_id ; Get our JOB ID number
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #>job_names ; Our Job name table (LSB)
LDY #<job_names ; Our Job name table (MSB)
LDA #2 ; CALLOS function 2
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes : Found, go off and claim call
LDA #1 ; Not found, restore A
JMP (ovec) ; Call back to old vector

internal_handle_2
CMP #2 ; Is it function call 2 (CodeName) ?
BNE internal_handle_3 ; No, unknown, pass on
LDA job_id ; Get our JOB ID
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #>job_names ; Our Job name table (LSB)
LDY #<job_names ; Our Job name table (MSB)
LDA #3 ; CALLOS function 3
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes ; Found, go off and claim call
LDA #2 ; Not found, restore A
JMP (ovec) ; Call back to old vector

internal_yes
LDA #0 ; We want to claim call for some reason

internal_handle_3
JMP (ovec) ; Call back to old vector

job_handle
PHA ; Mark sure to preserve A
CPY call ; Check call wanted against base of ours
BCC job_handle_no ; Less than our base, so definately not ours
TYA
SBC #no_of_calls ; Subtract number of calls we have
CMP call ; Now compare with base
BCC job_handle2 ; Yes, one of ours

job_handle.no
PLA ; Restore A
JMP (ovec2) ; Call back to old vector

job_handle2
TYA
SEC
SBC call ; Subtract our base from call
ASL A ; Times by 2 for offset into table
TAY ; Place in Y
LDA job_run_table,Y ; Get LSB of routine
STA zero_gp1 ; Store it for indirect jump (LSB)
LDA job_run_table+1,Y ; Get MSB of routine
STA zero_gp1+1 ; Store it for indirect jump (MSB)
PLA ; Restore A
JMP (zero_gp1) ; Call our relevant routine

job_names ; List of our JobNames
STR "TestJob" ; Test job name
DFB &FF ; &FF - marks end of table

job_run_table ; List of routine addresses to match Jobs
DFW job_TestJob ; Test job routine</nowiki>

== Relocation ==

The relocation method used will not do a complete relocation, ie.
from ANY address to ANY address. The only constraint on the addresses is
that they must be the same offset in the page, which means, &2602 and &3402
is alright but &2602 and &3455 is not, ie. the difference between the two
addresses must be a multiple of 256 bytes, as only the MSB is altered, this
should not cause any real problems. What is meant by the two addresses is
the address the code was originally assembled at and the address it wants
relocating to. Because of this programs must be multiples of 256 bytes, ie.
the low byte of LOMEM must ALWAYS be 0, your program should be padded out.

The relocation mechanism works by having a table, and to each byte
of code there is one BIT, if unset it means the byte of code should not be
relocated, else it should be, thus the BitMap table is 8 times smaller than
the code. To generate the BitMap you have to assemble the code at two
different places, and compare both sets of assembled code against each
other, the differences are where the code is to be relocated. The code
which is sent up to the controller is assumed to be assembled at address
&100, so the first code should be assembled at &100, the other one should be
assembled at another address, say &600, and the first one be sent up with
the BitMap. A program is availble for the Elk/Beeb/Arc with 65Tube/Mac with
BBC BASIC to compare the two files and create the BitMap.

All the program has to do to relocate itself is execute this bit of
code first of all: (address is the base address of the program, ie. &100
for the downloaded version)

<nowiki>execcall
LDA #>(execute-address) ; Final execution address offset (LSB)
STA zero_gp1
LDA #<(execute-address) ; Final execution address offset (MSB)
STA zero_gp1+1

LDA #>(BitMap-address) ; BitMap address offset (LSB)
STA zero_gp2
LDA #<(BitMap-address) ; BitMap address offset (MSB)
STA zero_gp2+1

LDA #>(execcall-address); Length of data to relocate (LSB)
STA zero_gp3
LDA #<(execcall-address); Length of data to relocate (MSB)
STA zero_gp3+1

TXA ; Execcall REAL address
SEC
SBC #>(execcall-address); Subrtract length
TAX ; Put it back in X
TYA ; Ditto for MSB
SBC #<(execcall-address)
TAY
LDA #4 ; CALLOS function for Relocate
JMP OS_CALLOS ; Call CALLOS

BitMap ; BitMap start</nowiki>

This will relocate the code and automatically call the execution
address, which should be the initialisation code (ie. setup internal_vec
and unknownjob_vec etc.). "address" is the address the code is started to
assemble at, &100 for the version to be uploaded. The upload routine should
pass in X and Y (via ExecuteCode) the address of the start of execcall, this
means that the routine can tell where it is in memory, subtracting the
length gives the start of the code to relocate.

== Layout Summary ==

The layout of a full application should be like this by now:

<nowiki> start of code
program job codes, data etc.
internal handler
job handler
end of code
initialisation (setup internal etc.)
end of code to be relocated
execution (relocation)
relocation BitMap</nowiki>

Because of memory space the initialisation code should be placed
outside the reserved memory limit of the program, as it is only called once
and not needed again.

== Other miscellaneous calls ==

<nowiki>Call : OS_PRINTER
Purpose : To place a character in the printer buffer
Entry : A = character to send
X, Y, c, z = undefined
Exit : A, X, Y is preserved
if c = 0 (printed)
The printer is on and the character was inserted
if c = 1 (not printed)
The printer is off and the character was forgotten
z = undefined
Note : The character goes into the printer buffer and will be
actually sent to the printer when the printer asks for it. If the printer
was not awake to begin with, an attempt is made to wake it up, thus
meaning that in some circumstances when the printer wasn't ready a
character may be lost, this cannot be helped. If the printer is off (via
the BCD switch) then the character will be forgotten as the Printer Buffer
is inactive.</nowiki>

The module is located at &8000 in memory, and should be a EPROM placed
in the second ROM socket in the controller (ie. the top RAM socket). This
module is primary designed to turn the Controller into a dedicated task,
making it perform some function from switch on. It could also be used to
add more permant JobCalls to the Controller, in the process taking up much
less RAM), but because of there being only one Module present this feature
is limited, and is much more suited to a collection of the user's own
personal routines.

For the OS to recognise a module as being in place the text "Module" is
looked for, the layout of a module should be like this (starting at
&8000):

<nowiki>Offset value comment
0 "Module" The OS checks for this string
6 0 End of check string
7 Language entry Address of 'Language' entry
9 Service entry Address of 'Service' entry
11 "<Module Title>" Module title
0 End of Module title

"<Module part>" Part Module Title
0 End of Part Module Title
"x.xx" Part version number

&FF End of parts list</nowiki>

The language entry is a 2 byte value holding the address of the language
entry routine, this is called on reset, if the BCD is set correctly. A
value of less than &8000 means there is no valid language entry and any
language calls are ignored. If a RTS is made the OS carries on as it would
have if there wasn't a language call.

The service entry is a 2 byte value holding the address of the service
entry routine, this is called at various appropiate moments with service
numbers in A. A list of current calls is thus:

<nowiki> 0 - Not used
1 - Unknown Job Code
2 - Centisecond call
3 - Irq2 (unknown IRQ)
4 - internal_vec call (exit with A=0 to claim)
254 - RESET
255 - BRK</nowiki>

On exit all registers and flags should be preserved. For call 1 the
unknown job value is held in the Y register, the enviroment is held in the
X register, on exit, X should contain the flag, as A does from the exit of
unknownjob_vec. For the rest of calls, X and Y are undefined.

For both Service and Language entry points, a value of 0 means "there is
no valid routine" and the module isn't called for that type of entry.

Finally a full implementation of a JobCall, from start to finish.

<nowiki> DIM data% &1000
:
no_of_calls = 1
:
VIA = &E030
ACIA = &E010
ADC = &E000
AUX_PORT = &E020
brk_vec = &200
nmi_vec = &202
irq_vec = &204
irq2_vec = &206
sendserial_vec = &208
readserial_vec = &20A
sendjob_vec = &20C
readjob_vec = &20E
decodejob_vec = &210
unknownjob_vec = &212
extjob_vec = &214
centisec_vec = &216
internal_vec = &218
callos_vec = &21A
printer_vec = &21C
zero_gp1 = 0
zero_gp2 = 2
zero_gp3 = 4
zero_gp4 = 6
zero_gp5 = 8
zero_gp6 = 10
zero_gp7 = 12
zero_gp8 = 14
zero_gp9 = 16
zero_gp10 = 18
user_reserved = &70
irq_A = &A0
fcount = &A1
RAM_size = &A3
jobout_buf = &400
jobin_buf = &480
OS_PRINTER = &FFB9
OS_CALLOS = &FFBC
OS_SENDBYTE = &FFBF
OS_READBYTE = &FFC2
OS_SENDJOB = &FFC5
OS_READJOB = &FFC8
OS_DECODEJOB = &FFCB
:
FOR create=1 TO 2
:
FOR pass%=4 TO 7 STEP 3
P%=&100*create : O%=data%
[OPT pass%
:
.job_DemoJob
CMP #1
BEQ DemoJob_go
LDA #1
LDY #0
RTS
/
.DemoJob_go

:
.internal_handle
CMP #1 ; Is it function call 1 (NameCode) ?
BNE internal_handle_2 ; No, check for function 2
/
LDA job_id ; Get our JOB ID number
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #job_names MOD 256 ; Our Job name table (LSB)
LDY #job_names DIV 256 ; Our Job name table (MSB)
LDA #2 ; CALLOS function 2
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes ; Found, go off and claim call
LDA #1 ; Not found, restore A
JMP (ovec) ; Call back to old vector
/
.internal_handle_2
CMP #2 ; Is it function call 2 (CodeName) ?
BNE internal_handle_3 ; No, unknown, pass on
/
LDA job_id ; Get our JOB ID
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #job_names MOD 256 ; Our Job name table (LSB)
LDY #job_names DIV 256 ; Our Job name table (MSB)
LDA #3 ; CALLOS function 3
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes ; Found, go off and claim call
LDA #2 ; Not found, restore A
JMP (ovec) ; Call back to old vector
/
.internal_yes
LDA #0 ; We want to claim call for some reason
/
.internal_handle_3
JMP (ovec) ; Call back to old vector
:
.job_handle
PHA ; Make sure to preserve A
CPY call ; Check call wanted against base of ours
BCC job_handle_no ; Less than our base, so definately not ours
TYA
SBC #no_of_calls ; Subtract number of calls we have
CMP call ; Now compare with base
BCC job_handle2 ; Yes, one of ours
/
.job_handle.no
PLA ; Restore A
JMP (ovec2) ; Call back to old vector
/
.job_handle2
TYA
SEC
SBC call ; Subtract our base from call
ASL A ; Times by 2 for offset into table
TAY ; Place in Y
LDA job_run_table,Y ; Get LSB of routine
STA zero_gp1 ; Store it for indirect jump (LSB)
LDA job_run_table+1,Y ; Get MSB of routine
STA zero_gp1+1 ; Store it for indirect jump (MSB)
PLA ; Restore A
JMP (zero_gp1) ; Call our relevant routine
:
.job_names ; List of our JobNames
EQUS "DemoJob":EQUB 13 ; Test job name
/
EQUB &FF ; &FF - marks end of table
:
.job_run_table ; List of routine addresses to match Jobs
EQUW job_DemoJob ; Test job routine
:
.call : EQUB 0 ; Store for our JobCode base
.job_id : EQUB 0 ; Store for our JobId
.ovec : EQUW 0 ; Store for old internal_vec value
.ovec2 : EQUW 0 ; Store for old unknownjob_vec value
:
EQUS STRING$(&100-(P% MOD 256),CHR$0)
.end_of_code ; end_of_code should be on page boundry
:
.execute
LDX #no_of_calls ; Number of JobCodes wanted
LDA #1 ; CALLOS, function 1, Claim JobCodes
JSR OS_CALLOS ; Call CALLOS
STX call ; Store base address of JobCodes allocated
STY job_id ; Store JOB ID given
CPX #0 ; Check we were given some codes
BEQ noinstall ; No, don't bother installing ourself
/
LDA internal_vec ; Get old internal_vec (LSB)
STA ovec ; Store it
LDA internal_vec+1 ; Get old internal_vec (MSB)
STA ovec+1 ; Store it
LDA #internal_handle MOD 256 ; Our internal handler (LSB)
STA internal_vec ; Place it in the vector (LSB)
LDA #internal_handle DIV 256 ; Our internal handler (MSB)
STA internal_vec+1 ; Place it in the vector (MSB)
/
LDA unknownjob_vec ; Get old unknownjob_vec (LSB)
STA ovec2 ; Store it
LDA unknownjob_vec+1 ; Get old unknownjob_vec (MSB)
STA ovec2+1 ; Store it
LDA #job_handle MOD 256 ; Our unknown job handler (LSB)
STA unknownjob_vec ; Place it in the vector (LSB)
LDA #job_handle DIV 256 ; Our unknown job handler (MSB)
STA unknownjob_vec+1 ; Place it in the vector (MSB)
/
LDX #end_of_code MOD 256 ; End of code (LSB)
LDY #end_of_code DIV 256 ; End of code (MSB)
STX jobin_buf ; Place it in jobin_buf (LSB)
STY jobin_buf+1 ; Place it in jobin_buf+1 (MSB)
LDA #65 ; JobCode for WriteLomem
JSR OS_DECODEJOB ; Call JobCall handler
/
.noinstall
RTS ; End - return to OS
:
.execcall
LDA #>(execute-address) ; Final execution address offset (LSB)
STA zero_gp1
LDA #<(execute-address) ; Final execution address offset (MSB)
STA zero_gp1+1
/
LDA #>(BitMap-address) ; BitMap address offset (LSB)
STA zero_gp2
LDA #<(BitMap-address) ; BitMap address offset (MSB)
STA zero_gp2+1
/
LDA #>(execcall-address) ; Length of data to relocate (LSB)
STA zero_gp3
LDA #<(execcall-address) ; Length of data to relocate (MSB)
STA zero_gp3+1
/
TXA ; Execcall REAL address
SEC
SBC #>(execcall-address) ; Subrtract length
TAX ; Put it back in X
TYA ; Ditto for MSB
SBC #<(execcall-address)
TAY
LDA #4 ; CALLOS function for Relocate
JMP OS_CALLOS ; Call CALLOS
/
.BitMap ; BitMap start
:
]
NEXT
:
OSCLI "SAVE code"+STR$create+" "+STR$~data%+" "+STR$~O%
:
NEXT</nowiki>

== Changelog ==

<nowiki>bob 071 Fixed MotorForward bug (%10)
bob 072 CallOS 14 now checks current adc.owner status
jim 072.d1 * Rewrite for new hardware/processor *
jim 072.d1 Moved vectors/workspace to &440
jim 072.d1 Moved rs.inp.buf to &500
jim 072.d1 Moved jobout.buf to &600
jim 072.d1 Moved jobin.buf to &680
jim 072.d1 Moved jobs.status to &700
jim 072.d1 Added irq.X (&A4)
jim 072.d1 Added irq.Y (&A5)
jim 072.d1 Removed short detection code
jim 072.d1 Voided CallOS' 6,7,8,9,10,11,13,16,17,18,19
jim 072.d1 Removed JobCalls ReadADCReg,WriteADCReg
jim 072.d1 Removed JobCalls ReadACIAReg,WriteACIAReg
jim 072.d1 Removed JobCalls ReadVIAReg,WriteVIAReg,SetVIAHigh,SetVIALow
jim 072.d1 Added CallOS 21 Write Outputs
jim 072.d1 Added CallOS 22 Read Outputs added
jim 072.d1 Added CallOS 23 Read Inputs added
jim 072.d1 Added CallOS 24 Write Motors
jim 072.d1 Added CallOS 25 Read Motors
jim 072.d1 Added CallOS 26 Read Keypad
jim 072.d1 Expanded CallOS 5 information
jim 072.d1 Added JobCall IdentSystem to return CallOS 5 info
jim 072.d1 JobCalls now use appropriate CallOS'
jim 072.d1 OS.READBYTE no longer preserves A on CS
jim 072.d1 irq.vec,irq2.vec,nmi.vec now redundant
jim 072.d1 Renamed JobCall DownloadData to DownloadData38
jim 072.d1 Renamed JobCall UploadData to UploadData38
jim 072.d1 Renamed JobCall ExecuteCode to ExecuteCode38
jim 072.d1 Renamed JobCall ReadByte to ReadByte38
jim 072.d1 Renamed JobCall StoreByte to StoreByte38
jim 072.d1 JobCall ForcedADCRead now checks adc.owner first
jim 072.d3 Added CallOS 27 Write printer
jim 072.d3 Added CallOS 28 Read printer
jim 072.d3 Added CallOS 29 Write RTC Reg
jim 072.d3 Added CallOS 30 Read RTC Reg
jim 072.d3 Added CallOS 31 Write RTC string
jim 072.d3 Added CallOS 32 Read RTC string
jim 072.d3 Added CallOS 33 Write RTC bcd
jim 072.d3 Added CallOS 34 Read RTC bcd
jim 072.d3 Added CallOS 35 Write LCD Reg
jim 072.d3 Added CallOS 36 Read LCD Reg
jim 072.d3 Added JobCall WritePrinter
jim 072.d3 Added JobCall ReadPrinter
jim 072.d3 Added JobCall PrintChar
jim 072.d3 Added JobCall PrintStreamZ
jim 072.d3 Added JobCall PrintStream
jim 072.d3 Added JobCall PrintServer
jim 072.d3 Added JobCall WriteRTCReg
jim 072.d3 Added JobCall ReadRTCReg
jim 072.d3 Added JobCall WriteRTC
jim 072.d3 Added JobCall ReadRTC
jim 072.d3 Added JobCall WriteRTCbcd
jim 072.d3 Added JobCall ReadRTCbcd
jim 072.d3 Added JobCall WriteLCDReg
jim 072.d3 Added JobCall ReadLCDReg
jim 072.d3 Added CallOS 37 Write Power ctrl
jim 072.d3 Added CallOS 38 Read Power ctrl
jim 072.d3 Implemented OS.PRINTER
jim 072.d3 Added JobCall PatchMF (MotorForward)
jim 072.d3 Changed irq.vec to int0.vec
jim 072.d3 Changed irq2.vec to int1.vec
jim 072.d3 Added int2irq.vec (wrksp+&20)
jim 072.d3 Added int3irq.vec (wrksp+&22)
jim 072.d3 Added int4irq.vec (wrksp+&24)
jim 072.d3 Added c0irq.vec (wrksp+&26)
jim 072.d3 Added c1irq.vec (wrksp+&28)
jim 072.d3 Added t1irq.vec (wrksp+&2A)
jim 072.d3 Added t2irq.vec (wrksp+&2C)
jim 072.d3 Added txirq.vec (wrksp+&2E)
jim 072.d3 Added tyirq.vec (wrksp+&30)
jim 072.d3 Added s1rirq.vec (wrksp+&32)
jim 072.d3 Added s1rirq.vec (wrksp+&34)
jim 072.d3 Added s2irq.vec (wrksp+&36)
jim 072.d3 Added adcirq.vec (wrksp+&38)
jim 072.d3 Renamed JobCall DownloadData38 to DownloadData740
jim 072.d3 Renamed JobCall UploadData38 to UploadData740
jim 072.d3 Renamed JobCall ExecuteCode38 to ExecuteCode740
jim 072.d3 Renamed JobCall ReadByte38 to ReadByte740
jim 072.d3 Renamed JobCall StoreByte38 to StoreByte740
jim 072.d4 Hardware update
jim 072.d4 Re-assigned CallOS 37 to Write Power/Charge control
jim 072.d4 Re-assigned CallOS 38 to Read Power/Charge control
jim 072.d4 Moved int2irq.vec to wrksp+&22
jim 072.d4 Moved int3irq.vec to wrksp+&24
jim 072.d4 Moved int4irq.vec to wrksp+&26
jim 072.d4 Moved c0irq.vec to wrksp+&28
jim 072.d4 Moved c1irq.vec to wrksp+&2A
jim 072.d4 Moved t1irq.vec to wrksp+&2C
jim 072.d4 Moved t2irq.vec to wrksp+&2E
jim 072.d4 Moved txirq.vec to wrksp+&30
jim 072.d4 Moved tyirq.vec to wrksp+&32
jim 072.d4 Moved s1rirq.vec to wrksp+&34
jim 072.d4 Moved s1rirq.vec to wrksp+&36
jim 072.d4 Moved s2irq.vec to wrksp+&38
jim 072.d4 Moved adcirq.vec to wrksp+&3A
jim 072.d4 Added OS.LCDVDU (&FFB7) and lcdvdu.vec (wrksp+&20)
jim 072.d5 Re-assigned CallOS 37 to Write/Read Power/Charge control
jim 072.d5 Re-assgined CallOS 38 Read Battery Voltage
jim 072.d5 OS.CALLOS now re-entrant
jim 072.d5 Fixed OS.PRINTER
jim 072.d5 Started to add internal logging software
jim 072.d5 Moved OS.LCDVDU to &FFB6
jim 072.d7 Added OS.PRINTERPOLL (&FFB3) and printerpoll.vec (wrksp+&3C)
bob 073 Matched jim & bob sensor lookup tables
bob 073 Added PatchMF
jim 072.dj Added OS.CALLOS 51 Read keypad press
jim 072.dj Added hard reset keypad press
jim 072.dk Added JobCall ReadOutputs
jim 072.do Changed soft reset of zero page locations
jim 072.do Changed MotorForward/Backward bitmaps
jim 072.dp Fixed OS.CALLOS WriteRTCbcd
jim 072.dq Fixed OS.CALLOS ReadRTCstring for correct 24hr operation
jim 072.dr Changed reset prompts
bob 074 Added support for Little Bob
jim 072.dy Added further RTC/CMOS support
jim 072.dB Removed double hard reset
jim 072.dE Set _cpu.mode depending on external memory requirement
jim 072.dF Added Insight code
jim 073 Sub-release
jim 074 Modification to LCD code - uses bsy flag all the time now
jim 074 Fixed OS.CALLOS 42 Write LCD Char Def
jim 074 Fixed OS.CALLOS 43 Read LCD Char Def
jim 075 Added simple battery charge code
jim 075 Fixed JobCall ReadSensorTable
jim 075 Fixed OS.CALLOS 42 Write LCD Char Def
jim 075 Fixed OS.CALLOS 43 Read LCD Char Def
jim 075 Added sleep code
jim 075 Added OS.CALLOS 52 Write Sleep Time
jim 075 Added OS.CALLOS 53 Read Sleep Time
jim 075 Modified battery charge code
jim 076 Modified JobCall ReadSensorTable
jim 076 Modified OS.CALLOS 26 ReadKeypad to do debounce
jim 077 Rewrote battery charging code
jim 077.2 Reduced stop charge threshold to 2
jim 077.3 Increased stop charge threshold to 3
jim 077.3 Added battery voltage averaging
bill 077 Stripped
bill 077 Moved ins to out port
bill 077 Added RTS
bill 077 Changed sensor ID system back to original, using p2.1
bill 077 Dedicated USB/RS selection line, RTS provisioned on p2.3
bill 077 Overload "bounce" timing
bill 078 CTS added
bill 079 Temperature fudge</nowiki>

MediaWiki:Common.css

2023-11-04T17:17:56Z

Benryves:

hr {
overflow: hidden;
}

table.calltable tr td {
vertical-align: top;
}
table.calltable tr td > * {
margin-top: 0;
}
table.calltable tr td:first-child {
font-style: italic;
}
table.calltable tr td:first-child::after {
content: ':';
}

SmartBox OS

2023-11-04T09:41:35Z

Benryves: /* Vectors */ Converted plaintext documentation to call tables

== Documentation for SmartBox OS 2.066 ==

The term JobCall is the concept of the routine itself, as opposed to
JobName (which is the actual name associated with it (eg. NameCode)) and
JobCode (which is the actual number associated with it (eg. 3)).

The term controller means the SmartBox, or any other incarnation
which may appear in future time !

The term OS means the controllers' Operating System.

== Preview ==

There are a number of reasons why using Machine Code on the
controller is more desirable than using the various JobCalls via the serial
link. One reason is speed, if the task which needs to be performed, has to
be performed very quickly (more quickly than can be achieved via the serial
link at least), then some code must be written to work in the controller
itself to achieve this sort of speed. If the task required is to be a
"background" task (ie. a task which may happen while other "things" carry
on as normal, like a change of state of a particular port) then it is far
easier to let the controller do all the work, maybe under interupts, than
continuously poll the controller checking the state of various things.
Another reason may be that you would like to add another JobCall to the OS,
extending the calls available to external applications (and the user at the
same time), without the user having to write the code himself to achieve the
aim. For advanced users, there is also the ablity to alter the way the OS
does various things and to have the controller in their "power", for
dedicated tasks etc.

One advantage of writing IN the controller is that that "function"
is available to any computer using the serial link, and is thus not fixed to
one computer type or even a computer at all, where the controller is used
free running, doing a particular task which doesn't need the intervention of
the user's own computer.

== Call types ==

There are three different types of machine code routines which can
be added to the controller. Each one is suited to a more advanced level
than the other, which also relates to the amount of work needed to actually
get the routine working ! The three levels are such:

=== Simple stand alone routine ===

Here the routine is just the routine
itself with no supporting code (ie. code to integrate with the rest of the
OS). It has to be called directly, by use of the ExecuteCode JobCall, thus
it usually resides at a fixed address and obviously does not offer the user
friendly way of accessing itself like there is with normal OS calls.

=== Extended JobCall ===

There is one JobCall in the OS (ExtendJob)
which can call various routines residing in memory, each one is identified
by a 8 bit number. The disadvantages of this way is that the call hasn't
got it's own JobName/JobCode and needs the extra byte to identify itself.
This is ideal for the quick routine which the user would like to add for
himself without having to resort to the extra code needed for the full
JobCode implementation.

=== Full JobCall ===

This is where the routine can define itself one
(or a number) of JobNames/JobCodes, it can integrate itself into an
extension of the OS in a complete way. The disadvantage is that extra
coding is needed to deal with the various OS calls it has to service and
that extra work is needed to produce a suitable file to place in the
controller.

Normally with most processors, including the 65c02, the machine code
produced is produced for a fixed memory address, and it cannot be made to
run in a different place in memory unless extra work is carried out by the
user, or at least a combination of the user and the OS. For the controller
this is a very severe disadvantage as most extensions are downloaded as
"modules" and to optimise memory a system has to be devised to enable
routines to be placed anywhere in memory, thus allowing no memory to be
wasted. In the OS there is a routine to do just this, though it does need
some help. A special version of the users code has to be developed, or
rather it has to be "processed" to add extra information on the end. Extra
code is needed to set up a few pointers and call the OS routine to relocate.
See later.

== Memory ==

The first 256 bytes of memory are somewhat special, most zero page
locations are reserved for use by the OS:

{|class="wikitable"
|-
|&00-&14||General workspace, used to pass parameters to some OS routines, can also be used by other routines DURING their execution.
|-
|&15-&6F||Reserved
|-
|&70-&9F||Available to the user
|-
|&A0||Accumulator store for irqs (irq_A)
|-
|&A1-&A2||Two byte counter, decremented at 100hz, useful for temporary timing purposes (fcount)
|-
|&A3||RAM size, high byte of RAM size of machine, ie. for 32k this will be &80 (RAM_size)
|-
|&A4-&AF||Reserved
|-
|&B0-&FF||Used by the OS
|-
|}

The rest of memory space is used for the processors stack, OS'
buffers, tables, vectors and, of course, the user available memory.

A breakdown of the rest of memory:

* &100 to &1FF is the 65c02's stack.
* &200-&2FF is used by the OS for various system functions and also contains the vector table, more on that later.
* &300-&3FF is the serial input buffer.
* &400-&47F is the internal job code call output buffer. (jobout_buf)
* &480-&4FF is the internal job code call input buffer. (jobin_buf)
* &500-&5FF is the job status table.
* &600 to the end of RAM memory is for the user. The user should not assume what the top of AVAILABLE memory is and use the system variable HIMEM.

In the controller the maximum limit of RAM is &8000 (which is 32k),
from &8000-&DFFF lies the memory mapped hardware, from &E000 to &FFF9 lies
the OS and from &FFFA to &FFFF lies the 65c02 vectors.

So the user has his own limits of free memory. The lowest limit is
called LOMEM and the highest limit is called HIMEM, everything between these
boundaries is termed "available" for use by anyone, the user or the OS.

Anyone can also claim memory, thus making private to them and not allowing
anyone else to use it. You do this by altering the value of LOMEM, HIMEM
should not be moved. Of course anyone claiming memory should first check
that there is enough memory available for the amount they want to claim for.
To take a common example, a downloadable routine which installs itself as a
extension routine, The download routine will first of all read LOMEM, read
HIMEM, check there is enough memory for the routine, download it to LOMEM
and call it, the downloaded routine will then relocate itself and alter
LOMEM so it is protected.

There is one other memory limit, this is called TOPMEM, this is the
absolute top limit of RAM, HIMEM will normally equal TOPMEM, but a future OS
may alter HIMEM to below TOPMEM. TOPMEM should be ignored ideally, and
HIMEM used.

== OS Calls ==

The OS has calls (ie. a jump instruction which you call, which
then calls, via a RAM vector, a routine in the OS) setup near the top of
memory, through these calls you do everything associated with the
controller. The calls are are such:

* OS_PRINTER at address &FFB9
* OS_CALLOS at address &FFBC
* OS_SENDBYTE at address &FFBF
* OS_READBYTE at address &FFC2
* OS_SENDJOB at address &FFC5
* OS_READJOB at address &FFC8
* OS_DECODEJOB at address &FFCB

The address is the one to call for the particular routine.

* OS_PRINTER is reserved for future use.
* OS_CALLOS calls upon the OS to do various things internally.
* OS_SENDBYTE sends a byte out of the serial port.
* OS_READBYTE reads a byte from the serial port.
* OS_SENDJOB 'sends' a value to the JobCall caller.
* OS_READJOB 'reads' a value from the JobCalls caller.
* OS_DECODEJOB decodes the Job number held in A and acts on it.

Note none of these things should be used in interupt routines,
except OS_CALLOS, of any sort, except if YOU know what state the machine is
in and WHY.

=== Serial Port ===

The serial port on the controller is currently based on the 6850
UART, this need not bother you as the OS deals with the thing entirely by
itself. The chip is setup by the OS to always have a word format of 8n1 and
a baud rate of 9600, this translates to 960cps. The 6850 has two divide
rates for the baud rate, the OS only uses one, using the other one is beyond
the scope of this document and shouldn't be neccessary to use.

Only receive interupts are used, transmission of characters is done
on a polled basis.

As said, there are two calls OS_READBYTE and OS_SENDBYTE.
OS_READBYTE tests the serial input buffer and returns the character (if any
in the A register), the c flag states whether there was a character
returned.

<nowiki> Call : OS_READBYTE
Entry : A, X, Y, c, z = undefined
Exit : X, Y preserved
z = undefined
if c = 1 (no character received)
A is preserved
if c = 0 (character received)
A = character received</nowiki>

OS_SENDBYTE sends the character in the A register out of the serial
port, taking into consideration flow control etc.

<nowiki> Call : OS_SENDBYTE
Entry : A = character to send
X, Y, c, z = undefined
Exit : A, X, Y, c is preserved
z = undefined</nowiki>

=== OS_READJOB and OS_SENDJOB ===

To send/receive data from the user (either internally or via the
serial port) you call OS_SENDJOB/OS_READJOB for the next byte. If your
JobCall requires dynamic use of data, ie. interaction, then a check of the
enviroment should be done to check the call came from the serial port. One
example of this is the OS JobCall MultipleServer, which requires dynamic use
of sending a stream of data until a reaction from the user to tell it to
stop.

<nowiki> Call : OS_READJOB
Purpose: To read job value from the user
Entry : A, X, Y, c, z = undefined
Exit : A = byte read
X, Y is preserved
c, z = undefined
Note : When coming from the serial port it waits for a character to be
received, if you are doing a serial only call and wish to have a loop
checking for a character from the user while doing "your own thing", then
OS_READBYTE should be used. For internal calls this reads data out of
jobin_buf.</nowiki>

<nowiki> Call : OS_SENDJOB
Purpose: To give a job value back to the user
Entry : A = byte to give
X, Y, c, z = undefined
Exit : A, X, Y is preserved
c, z = undefined
Note : This will send either out to the serial port or place a byte in
jobout_buf. For internal calls this stores the value in jobout_buf, which
is allocated 128 bytes, no bound checking is done so sending more than 128
bytes to OS_SENDJOB will cause corruption of some memory.</nowiki>

=== OS_DECODEJOB ===

JobCalls in practise are really only used by the user, JobCalls
tend not to call other calls at all, infact you shouldn't really call
another call unless you were called from the serial port. If you do need to
call another JobCall then you do it like this; with each call you have
associated with it a number, and the call might require some data or give
some data back or both. With the serial port this is simple, you just send
data down and receive data as it is produced. You can't do this with
internal calls, and some calls will not let you call them from inside the
controller, you HAVE to call them from outside. But for the ones which do
let you, you do it with two data blocks, one for input TO the call and one
for output FROM the call. These are setup in a position in memory
(jobin_buf and jobout_buf), each one has a maximum of 128 bytes and this
should not be overflowed (OS_READJOB and OS_SENDJOB do NOT do any bound
checking). So to start with you place in the input block the data you want
to give the call (if any), call it, and then act on the data in the output
block (if any). The OS call OS_DECODEJOB is the one which actually calls
the JobCall handler and eventually the actual routine, you tell the JobCall
handler which call you want by placing the JobCode in the A register.

So for OS_DECODEJOB:

<nowiki> Call : OS_DECODEJOB
Entry : A = JobCode
X, Y, c, z = undefined
jobin_buf should contain any input data
Exit : A = flag
X = number of bytes given back by routine
Y = undefined
c = status, if set JobCall does not exist
z = status, if set JobCall cannot be called internally
jobout_buf contains any data sent from routine</nowiki>

A typical example would be:

<nowiki> LDA #readhimem ; JobCode for ReadHimem
JSR OS_DECODEJOB ; Call the JobCall handler
LDX jobout_buf ; Read HIMEM from buffer LSB
LDY jobout_buf+1 ; Read HIMEM from buffer MSB
STX jobin_buf ; Place LSB in input buffer
STY jobin_buf+1 ; Place MSB in input buffer
LDA #writelomem ; JobCode for WriteLomem
JSR OS_DECODEJOB ; Call the JobCall handler</nowiki>

which would read HIMEM, and then write LOMEM to be the same value, leaving
no spare memory left.

The reason why you should not call an internal call from another
internal call is that the same buffers (jobin_buf and jobout_buf) would be
used for both calls, causing conflict between the two calls, or rather to
the originator of the primary call ! The only time it would be safe if is
if you have already got all the data you want from jobin_buf and haven't
placed any in the jobout_buf (it would be lost if you had done).

=== 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.
|}

== 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
|}

== Starting Up ==

The setup procedure for setting up extension job calls is to:

# Claim the number of JobCodes you want
#: if success:
# patch the internal_vec and unknownjob_vec vectors
# move LOMEM up to protect your program
# do anything else for initial startup you may want to do
# return back, ready and waiting

This in code looks like:

<nowiki>execute
LDX #no_of_calls ; Number of JobCodes wanted
LDA #1 ; CALLOS, function 1, Claim JobCodes
JSR OS_CALLOS ; Call CALLOS
CPX #0 ; Check we were given some codes
BEQ noinstall ; No, don't bother installing ourself
STX call ; Store base address of JobCodes allocated
STY job_id ; Store JOB ID given

LDA internal_vec ; Get old internal_vec (LSB)
STA ovec ; Store it
LDA internal_vec+1 ; Get old internal_vec (MSB)
STA ovec+1 ; Store it
LDA #>internal_handle ; Our internal handler (LSB)
STA internal_vec ; Place it in the vector (LSB)
LDA #<internal_handle ; Our internal handler (MSB)
STA internal_vec+1 ; Place it in the vector (MSB)

LDA unknownjob_vec ; Get old unknownjob_vec (LSB)
STA ovec2 ; Store it
LDA unknownjob_vec+1 ; Get old unknownjob_vec (MSB)
STA ovec2+1 ; Store it
LDA #>job_handle ; Our unknown job handler (LSB)
STA unknownjob_vec ; Place it in the vector (LSB)
LDA #<job_handle ; Our unknown job handler (MSB)
STA unknownjob_vec+1 ; Place it in the vector (MSB)

LDX #>WriteLomem ; Point to JobName
LDY #<WriteLomem
JSR findjob ; Find WriteLomem code
BEQ noinstall ; Doesn't exist !
LDX #>end_of_code ; End of code (LSB)
LDY #<end_of_code ; End of code (MSB)
STX jobin_buf ; Place it in jobin_buf (LSB)
STY jobin_buf+1 ; Place it in jobin_buf+1 (MSB)
JSR OS_DECODEJOB ; Call JobCall handler

noinstall
RTS ; End - return to OS

findjob
STX zero.gp1 ; Zero page
STY zero.gp1+
LDY #0
findthisjoblo
LDA (zero.gp1),Y
STA jobin.buf,Y ; Store name in jobin_buf
INY
CMP #13
BNE findthisjoblo
LDA #3 ; NameCode
JSR OS.DECODEJOB ; Call NameCode
LDA jobout.buf ; Get returned value
RTS

WriteLomem STR "WriteLomem"</nowiki>

This will setup the various vectors and memory pointers for the
applicaion, the actual routines (internal_handle and job_handle) are fairly
straight forward and simple:

<nowiki>internal_handle
CMP #1 : Is it function call 1 (NameCode) ?
BNE internal_handle_2 ; No, check for function 2
LDA job_id ; Get our JOB ID number
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #>job_names ; Our Job name table (LSB)
LDY #<job_names ; Our Job name table (MSB)
LDA #2 ; CALLOS function 2
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes : Found, go off and claim call
LDA #1 ; Not found, restore A
JMP (ovec) ; Call back to old vector

internal_handle_2
CMP #2 ; Is it function call 2 (CodeName) ?
BNE internal_handle_3 ; No, unknown, pass on
LDA job_id ; Get our JOB ID
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #>job_names ; Our Job name table (LSB)
LDY #<job_names ; Our Job name table (MSB)
LDA #3 ; CALLOS function 3
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes ; Found, go off and claim call
LDA #2 ; Not found, restore A
JMP (ovec) ; Call back to old vector

internal_yes
LDA #0 ; We want to claim call for some reason

internal_handle_3
JMP (ovec) ; Call back to old vector

job_handle
PHA ; Mark sure to preserve A
CPY call ; Check call wanted against base of ours
BCC job_handle_no ; Less than our base, so definately not ours
TYA
SBC #no_of_calls ; Subtract number of calls we have
CMP call ; Now compare with base
BCC job_handle2 ; Yes, one of ours

job_handle.no
PLA ; Restore A
JMP (ovec2) ; Call back to old vector

job_handle2
TYA
SEC
SBC call ; Subtract our base from call
ASL A ; Times by 2 for offset into table
TAY ; Place in Y
LDA job_run_table,Y ; Get LSB of routine
STA zero_gp1 ; Store it for indirect jump (LSB)
LDA job_run_table+1,Y ; Get MSB of routine
STA zero_gp1+1 ; Store it for indirect jump (MSB)
PLA ; Restore A
JMP (zero_gp1) ; Call our relevant routine

job_names ; List of our JobNames
STR "TestJob" ; Test job name
DFB &FF ; &FF - marks end of table

job_run_table ; List of routine addresses to match Jobs
DFW job_TestJob ; Test job routine</nowiki>

== Relocation ==

The relocation method used will not do a complete relocation, ie.
from ANY address to ANY address. The only constraint on the addresses is
that they must be the same offset in the page, which means, &2602 and &3402
is alright but &2602 and &3455 is not, ie. the difference between the two
addresses must be a multiple of 256 bytes, as only the MSB is altered, this
should not cause any real problems. What is meant by the two addresses is
the address the code was originally assembled at and the address it wants
relocating to. Because of this programs must be multiples of 256 bytes, ie.
the low byte of LOMEM must ALWAYS be 0, your program should be padded out.

The relocation mechanism works by having a table, and to each byte
of code there is one BIT, if unset it means the byte of code should not be
relocated, else it should be, thus the BitMap table is 8 times smaller than
the code. To generate the BitMap you have to assemble the code at two
different places, and compare both sets of assembled code against each
other, the differences are where the code is to be relocated. The code
which is sent up to the controller is assumed to be assembled at address
&100, so the first code should be assembled at &100, the other one should be
assembled at another address, say &600, and the first one be sent up with
the BitMap. A program is availble for the Elk/Beeb/Arc with 65Tube/Mac with
BBC BASIC to compare the two files and create the BitMap.

All the program has to do to relocate itself is execute this bit of
code first of all: (address is the base address of the program, ie. &100
for the downloaded version)

<nowiki>execcall
LDA #>(execute-address) ; Final execution address offset (LSB)
STA zero_gp1
LDA #<(execute-address) ; Final execution address offset (MSB)
STA zero_gp1+1

LDA #>(BitMap-address) ; BitMap address offset (LSB)
STA zero_gp2
LDA #<(BitMap-address) ; BitMap address offset (MSB)
STA zero_gp2+1

LDA #>(execcall-address); Length of data to relocate (LSB)
STA zero_gp3
LDA #<(execcall-address); Length of data to relocate (MSB)
STA zero_gp3+1

TXA ; Execcall REAL address
SEC
SBC #>(execcall-address); Subrtract length
TAX ; Put it back in X
TYA ; Ditto for MSB
SBC #<(execcall-address)
TAY
LDA #4 ; CALLOS function for Relocate
JMP OS_CALLOS ; Call CALLOS

BitMap ; BitMap start</nowiki>

This will relocate the code and automatically call the execution
address, which should be the initialisation code (ie. setup internal_vec
and unknownjob_vec etc.). "address" is the address the code is started to
assemble at, &100 for the version to be uploaded. The upload routine should
pass in X and Y (via ExecuteCode) the address of the start of execcall, this
means that the routine can tell where it is in memory, subtracting the
length gives the start of the code to relocate.

== Layout Summary ==

The layout of a full application should be like this by now:

<nowiki> start of code
program job codes, data etc.
internal handler
job handler
end of code
initialisation (setup internal etc.)
end of code to be relocated
execution (relocation)
relocation BitMap</nowiki>

Because of memory space the initialisation code should be placed
outside the reserved memory limit of the program, as it is only called once
and not needed again.

== Other miscellaneous calls ==

<nowiki>Call : OS_PRINTER
Purpose : To place a character in the printer buffer
Entry : A = character to send
X, Y, c, z = undefined
Exit : A, X, Y is preserved
if c = 0 (printed)
The printer is on and the character was inserted
if c = 1 (not printed)
The printer is off and the character was forgotten
z = undefined
Note : The character goes into the printer buffer and will be
actually sent to the printer when the printer asks for it. If the printer
was not awake to begin with, an attempt is made to wake it up, thus
meaning that in some circumstances when the printer wasn't ready a
character may be lost, this cannot be helped. If the printer is off (via
the BCD switch) then the character will be forgotten as the Printer Buffer
is inactive.</nowiki>

The module is located at &8000 in memory, and should be a EPROM placed
in the second ROM socket in the controller (ie. the top RAM socket). This
module is primary designed to turn the Controller into a dedicated task,
making it perform some function from switch on. It could also be used to
add more permant JobCalls to the Controller, in the process taking up much
less RAM), but because of there being only one Module present this feature
is limited, and is much more suited to a collection of the user's own
personal routines.

For the OS to recognise a module as being in place the text "Module" is
looked for, the layout of a module should be like this (starting at
&8000):

<nowiki>Offset value comment
0 "Module" The OS checks for this string
6 0 End of check string
7 Language entry Address of 'Language' entry
9 Service entry Address of 'Service' entry
11 "<Module Title>" Module title
0 End of Module title

"<Module part>" Part Module Title
0 End of Part Module Title
"x.xx" Part version number

&FF End of parts list</nowiki>

The language entry is a 2 byte value holding the address of the language
entry routine, this is called on reset, if the BCD is set correctly. A
value of less than &8000 means there is no valid language entry and any
language calls are ignored. If a RTS is made the OS carries on as it would
have if there wasn't a language call.

The service entry is a 2 byte value holding the address of the service
entry routine, this is called at various appropiate moments with service
numbers in A. A list of current calls is thus:

<nowiki> 0 - Not used
1 - Unknown Job Code
2 - Centisecond call
3 - Irq2 (unknown IRQ)
4 - internal_vec call (exit with A=0 to claim)
254 - RESET
255 - BRK</nowiki>

On exit all registers and flags should be preserved. For call 1 the
unknown job value is held in the Y register, the enviroment is held in the
X register, on exit, X should contain the flag, as A does from the exit of
unknownjob_vec. For the rest of calls, X and Y are undefined.

For both Service and Language entry points, a value of 0 means "there is
no valid routine" and the module isn't called for that type of entry.

Finally a full implementation of a JobCall, from start to finish.

<nowiki> DIM data% &1000
:
no_of_calls = 1
:
VIA = &E030
ACIA = &E010
ADC = &E000
AUX_PORT = &E020
brk_vec = &200
nmi_vec = &202
irq_vec = &204
irq2_vec = &206
sendserial_vec = &208
readserial_vec = &20A
sendjob_vec = &20C
readjob_vec = &20E
decodejob_vec = &210
unknownjob_vec = &212
extjob_vec = &214
centisec_vec = &216
internal_vec = &218
callos_vec = &21A
printer_vec = &21C
zero_gp1 = 0
zero_gp2 = 2
zero_gp3 = 4
zero_gp4 = 6
zero_gp5 = 8
zero_gp6 = 10
zero_gp7 = 12
zero_gp8 = 14
zero_gp9 = 16
zero_gp10 = 18
user_reserved = &70
irq_A = &A0
fcount = &A1
RAM_size = &A3
jobout_buf = &400
jobin_buf = &480
OS_PRINTER = &FFB9
OS_CALLOS = &FFBC
OS_SENDBYTE = &FFBF
OS_READBYTE = &FFC2
OS_SENDJOB = &FFC5
OS_READJOB = &FFC8
OS_DECODEJOB = &FFCB
:
FOR create=1 TO 2
:
FOR pass%=4 TO 7 STEP 3
P%=&100*create : O%=data%
[OPT pass%
:
.job_DemoJob
CMP #1
BEQ DemoJob_go
LDA #1
LDY #0
RTS
/
.DemoJob_go

:
.internal_handle
CMP #1 ; Is it function call 1 (NameCode) ?
BNE internal_handle_2 ; No, check for function 2
/
LDA job_id ; Get our JOB ID number
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #job_names MOD 256 ; Our Job name table (LSB)
LDY #job_names DIV 256 ; Our Job name table (MSB)
LDA #2 ; CALLOS function 2
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes ; Found, go off and claim call
LDA #1 ; Not found, restore A
JMP (ovec) ; Call back to old vector
/
.internal_handle_2
CMP #2 ; Is it function call 2 (CodeName) ?
BNE internal_handle_3 ; No, unknown, pass on
/
LDA job_id ; Get our JOB ID
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #job_names MOD 256 ; Our Job name table (LSB)
LDY #job_names DIV 256 ; Our Job name table (MSB)
LDA #3 ; CALLOS function 3
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes ; Found, go off and claim call
LDA #2 ; Not found, restore A
JMP (ovec) ; Call back to old vector
/
.internal_yes
LDA #0 ; We want to claim call for some reason
/
.internal_handle_3
JMP (ovec) ; Call back to old vector
:
.job_handle
PHA ; Make sure to preserve A
CPY call ; Check call wanted against base of ours
BCC job_handle_no ; Less than our base, so definately not ours
TYA
SBC #no_of_calls ; Subtract number of calls we have
CMP call ; Now compare with base
BCC job_handle2 ; Yes, one of ours
/
.job_handle.no
PLA ; Restore A
JMP (ovec2) ; Call back to old vector
/
.job_handle2
TYA
SEC
SBC call ; Subtract our base from call
ASL A ; Times by 2 for offset into table
TAY ; Place in Y
LDA job_run_table,Y ; Get LSB of routine
STA zero_gp1 ; Store it for indirect jump (LSB)
LDA job_run_table+1,Y ; Get MSB of routine
STA zero_gp1+1 ; Store it for indirect jump (MSB)
PLA ; Restore A
JMP (zero_gp1) ; Call our relevant routine
:
.job_names ; List of our JobNames
EQUS "DemoJob":EQUB 13 ; Test job name
/
EQUB &FF ; &FF - marks end of table
:
.job_run_table ; List of routine addresses to match Jobs
EQUW job_DemoJob ; Test job routine
:
.call : EQUB 0 ; Store for our JobCode base
.job_id : EQUB 0 ; Store for our JobId
.ovec : EQUW 0 ; Store for old internal_vec value
.ovec2 : EQUW 0 ; Store for old unknownjob_vec value
:
EQUS STRING$(&100-(P% MOD 256),CHR$0)
.end_of_code ; end_of_code should be on page boundry
:
.execute
LDX #no_of_calls ; Number of JobCodes wanted
LDA #1 ; CALLOS, function 1, Claim JobCodes
JSR OS_CALLOS ; Call CALLOS
STX call ; Store base address of JobCodes allocated
STY job_id ; Store JOB ID given
CPX #0 ; Check we were given some codes
BEQ noinstall ; No, don't bother installing ourself
/
LDA internal_vec ; Get old internal_vec (LSB)
STA ovec ; Store it
LDA internal_vec+1 ; Get old internal_vec (MSB)
STA ovec+1 ; Store it
LDA #internal_handle MOD 256 ; Our internal handler (LSB)
STA internal_vec ; Place it in the vector (LSB)
LDA #internal_handle DIV 256 ; Our internal handler (MSB)
STA internal_vec+1 ; Place it in the vector (MSB)
/
LDA unknownjob_vec ; Get old unknownjob_vec (LSB)
STA ovec2 ; Store it
LDA unknownjob_vec+1 ; Get old unknownjob_vec (MSB)
STA ovec2+1 ; Store it
LDA #job_handle MOD 256 ; Our unknown job handler (LSB)
STA unknownjob_vec ; Place it in the vector (LSB)
LDA #job_handle DIV 256 ; Our unknown job handler (MSB)
STA unknownjob_vec+1 ; Place it in the vector (MSB)
/
LDX #end_of_code MOD 256 ; End of code (LSB)
LDY #end_of_code DIV 256 ; End of code (MSB)
STX jobin_buf ; Place it in jobin_buf (LSB)
STY jobin_buf+1 ; Place it in jobin_buf+1 (MSB)
LDA #65 ; JobCode for WriteLomem
JSR OS_DECODEJOB ; Call JobCall handler
/
.noinstall
RTS ; End - return to OS
:
.execcall
LDA #>(execute-address) ; Final execution address offset (LSB)
STA zero_gp1
LDA #<(execute-address) ; Final execution address offset (MSB)
STA zero_gp1+1
/
LDA #>(BitMap-address) ; BitMap address offset (LSB)
STA zero_gp2
LDA #<(BitMap-address) ; BitMap address offset (MSB)
STA zero_gp2+1
/
LDA #>(execcall-address) ; Length of data to relocate (LSB)
STA zero_gp3
LDA #<(execcall-address) ; Length of data to relocate (MSB)
STA zero_gp3+1
/
TXA ; Execcall REAL address
SEC
SBC #>(execcall-address) ; Subrtract length
TAX ; Put it back in X
TYA ; Ditto for MSB
SBC #<(execcall-address)
TAY
LDA #4 ; CALLOS function for Relocate
JMP OS_CALLOS ; Call CALLOS
/
.BitMap ; BitMap start
:
]
NEXT
:
OSCLI "SAVE code"+STR$create+" "+STR$~data%+" "+STR$~O%
:
NEXT</nowiki>

== Changelog ==

<nowiki>bob 071 Fixed MotorForward bug (%10)
bob 072 CallOS 14 now checks current adc.owner status
jim 072.d1 * Rewrite for new hardware/processor *
jim 072.d1 Moved vectors/workspace to &440
jim 072.d1 Moved rs.inp.buf to &500
jim 072.d1 Moved jobout.buf to &600
jim 072.d1 Moved jobin.buf to &680
jim 072.d1 Moved jobs.status to &700
jim 072.d1 Added irq.X (&A4)
jim 072.d1 Added irq.Y (&A5)
jim 072.d1 Removed short detection code
jim 072.d1 Voided CallOS' 6,7,8,9,10,11,13,16,17,18,19
jim 072.d1 Removed JobCalls ReadADCReg,WriteADCReg
jim 072.d1 Removed JobCalls ReadACIAReg,WriteACIAReg
jim 072.d1 Removed JobCalls ReadVIAReg,WriteVIAReg,SetVIAHigh,SetVIALow
jim 072.d1 Added CallOS 21 Write Outputs
jim 072.d1 Added CallOS 22 Read Outputs added
jim 072.d1 Added CallOS 23 Read Inputs added
jim 072.d1 Added CallOS 24 Write Motors
jim 072.d1 Added CallOS 25 Read Motors
jim 072.d1 Added CallOS 26 Read Keypad
jim 072.d1 Expanded CallOS 5 information
jim 072.d1 Added JobCall IdentSystem to return CallOS 5 info
jim 072.d1 JobCalls now use appropriate CallOS'
jim 072.d1 OS.READBYTE no longer preserves A on CS
jim 072.d1 irq.vec,irq2.vec,nmi.vec now redundant
jim 072.d1 Renamed JobCall DownloadData to DownloadData38
jim 072.d1 Renamed JobCall UploadData to UploadData38
jim 072.d1 Renamed JobCall ExecuteCode to ExecuteCode38
jim 072.d1 Renamed JobCall ReadByte to ReadByte38
jim 072.d1 Renamed JobCall StoreByte to StoreByte38
jim 072.d1 JobCall ForcedADCRead now checks adc.owner first
jim 072.d3 Added CallOS 27 Write printer
jim 072.d3 Added CallOS 28 Read printer
jim 072.d3 Added CallOS 29 Write RTC Reg
jim 072.d3 Added CallOS 30 Read RTC Reg
jim 072.d3 Added CallOS 31 Write RTC string
jim 072.d3 Added CallOS 32 Read RTC string
jim 072.d3 Added CallOS 33 Write RTC bcd
jim 072.d3 Added CallOS 34 Read RTC bcd
jim 072.d3 Added CallOS 35 Write LCD Reg
jim 072.d3 Added CallOS 36 Read LCD Reg
jim 072.d3 Added JobCall WritePrinter
jim 072.d3 Added JobCall ReadPrinter
jim 072.d3 Added JobCall PrintChar
jim 072.d3 Added JobCall PrintStreamZ
jim 072.d3 Added JobCall PrintStream
jim 072.d3 Added JobCall PrintServer
jim 072.d3 Added JobCall WriteRTCReg
jim 072.d3 Added JobCall ReadRTCReg
jim 072.d3 Added JobCall WriteRTC
jim 072.d3 Added JobCall ReadRTC
jim 072.d3 Added JobCall WriteRTCbcd
jim 072.d3 Added JobCall ReadRTCbcd
jim 072.d3 Added JobCall WriteLCDReg
jim 072.d3 Added JobCall ReadLCDReg
jim 072.d3 Added CallOS 37 Write Power ctrl
jim 072.d3 Added CallOS 38 Read Power ctrl
jim 072.d3 Implemented OS.PRINTER
jim 072.d3 Added JobCall PatchMF (MotorForward)
jim 072.d3 Changed irq.vec to int0.vec
jim 072.d3 Changed irq2.vec to int1.vec
jim 072.d3 Added int2irq.vec (wrksp+&20)
jim 072.d3 Added int3irq.vec (wrksp+&22)
jim 072.d3 Added int4irq.vec (wrksp+&24)
jim 072.d3 Added c0irq.vec (wrksp+&26)
jim 072.d3 Added c1irq.vec (wrksp+&28)
jim 072.d3 Added t1irq.vec (wrksp+&2A)
jim 072.d3 Added t2irq.vec (wrksp+&2C)
jim 072.d3 Added txirq.vec (wrksp+&2E)
jim 072.d3 Added tyirq.vec (wrksp+&30)
jim 072.d3 Added s1rirq.vec (wrksp+&32)
jim 072.d3 Added s1rirq.vec (wrksp+&34)
jim 072.d3 Added s2irq.vec (wrksp+&36)
jim 072.d3 Added adcirq.vec (wrksp+&38)
jim 072.d3 Renamed JobCall DownloadData38 to DownloadData740
jim 072.d3 Renamed JobCall UploadData38 to UploadData740
jim 072.d3 Renamed JobCall ExecuteCode38 to ExecuteCode740
jim 072.d3 Renamed JobCall ReadByte38 to ReadByte740
jim 072.d3 Renamed JobCall StoreByte38 to StoreByte740
jim 072.d4 Hardware update
jim 072.d4 Re-assigned CallOS 37 to Write Power/Charge control
jim 072.d4 Re-assigned CallOS 38 to Read Power/Charge control
jim 072.d4 Moved int2irq.vec to wrksp+&22
jim 072.d4 Moved int3irq.vec to wrksp+&24
jim 072.d4 Moved int4irq.vec to wrksp+&26
jim 072.d4 Moved c0irq.vec to wrksp+&28
jim 072.d4 Moved c1irq.vec to wrksp+&2A
jim 072.d4 Moved t1irq.vec to wrksp+&2C
jim 072.d4 Moved t2irq.vec to wrksp+&2E
jim 072.d4 Moved txirq.vec to wrksp+&30
jim 072.d4 Moved tyirq.vec to wrksp+&32
jim 072.d4 Moved s1rirq.vec to wrksp+&34
jim 072.d4 Moved s1rirq.vec to wrksp+&36
jim 072.d4 Moved s2irq.vec to wrksp+&38
jim 072.d4 Moved adcirq.vec to wrksp+&3A
jim 072.d4 Added OS.LCDVDU (&FFB7) and lcdvdu.vec (wrksp+&20)
jim 072.d5 Re-assigned CallOS 37 to Write/Read Power/Charge control
jim 072.d5 Re-assgined CallOS 38 Read Battery Voltage
jim 072.d5 OS.CALLOS now re-entrant
jim 072.d5 Fixed OS.PRINTER
jim 072.d5 Started to add internal logging software
jim 072.d5 Moved OS.LCDVDU to &FFB6
jim 072.d7 Added OS.PRINTERPOLL (&FFB3) and printerpoll.vec (wrksp+&3C)
bob 073 Matched jim & bob sensor lookup tables
bob 073 Added PatchMF
jim 072.dj Added OS.CALLOS 51 Read keypad press
jim 072.dj Added hard reset keypad press
jim 072.dk Added JobCall ReadOutputs
jim 072.do Changed soft reset of zero page locations
jim 072.do Changed MotorForward/Backward bitmaps
jim 072.dp Fixed OS.CALLOS WriteRTCbcd
jim 072.dq Fixed OS.CALLOS ReadRTCstring for correct 24hr operation
jim 072.dr Changed reset prompts
bob 074 Added support for Little Bob
jim 072.dy Added further RTC/CMOS support
jim 072.dB Removed double hard reset
jim 072.dE Set _cpu.mode depending on external memory requirement
jim 072.dF Added Insight code
jim 073 Sub-release
jim 074 Modification to LCD code - uses bsy flag all the time now
jim 074 Fixed OS.CALLOS 42 Write LCD Char Def
jim 074 Fixed OS.CALLOS 43 Read LCD Char Def
jim 075 Added simple battery charge code
jim 075 Fixed JobCall ReadSensorTable
jim 075 Fixed OS.CALLOS 42 Write LCD Char Def
jim 075 Fixed OS.CALLOS 43 Read LCD Char Def
jim 075 Added sleep code
jim 075 Added OS.CALLOS 52 Write Sleep Time
jim 075 Added OS.CALLOS 53 Read Sleep Time
jim 075 Modified battery charge code
jim 076 Modified JobCall ReadSensorTable
jim 076 Modified OS.CALLOS 26 ReadKeypad to do debounce
jim 077 Rewrote battery charging code
jim 077.2 Reduced stop charge threshold to 2
jim 077.3 Increased stop charge threshold to 3
jim 077.3 Added battery voltage averaging
bill 077 Stripped
bill 077 Moved ins to out port
bill 077 Added RTS
bill 077 Changed sensor ID system back to original, using p2.1
bill 077 Dedicated USB/RS selection line, RTS provisioned on p2.3
bill 077 Overload "bounce" timing
bill 078 CTS added
bill 079 Temperature fudge</nowiki>

SmartBox OS

2023-11-04T09:22:29Z

Benryves: /* OS_CALLOS */ Converted plaintext documentation to call tables

== Documentation for SmartBox OS 2.066 ==

The term JobCall is the concept of the routine itself, as opposed to
JobName (which is the actual name associated with it (eg. NameCode)) and
JobCode (which is the actual number associated with it (eg. 3)).

The term controller means the SmartBox, or any other incarnation
which may appear in future time !

The term OS means the controllers' Operating System.

== Preview ==

There are a number of reasons why using Machine Code on the
controller is more desirable than using the various JobCalls via the serial
link. One reason is speed, if the task which needs to be performed, has to
be performed very quickly (more quickly than can be achieved via the serial
link at least), then some code must be written to work in the controller
itself to achieve this sort of speed. If the task required is to be a
"background" task (ie. a task which may happen while other "things" carry
on as normal, like a change of state of a particular port) then it is far
easier to let the controller do all the work, maybe under interupts, than
continuously poll the controller checking the state of various things.
Another reason may be that you would like to add another JobCall to the OS,
extending the calls available to external applications (and the user at the
same time), without the user having to write the code himself to achieve the
aim. For advanced users, there is also the ablity to alter the way the OS
does various things and to have the controller in their "power", for
dedicated tasks etc.

One advantage of writing IN the controller is that that "function"
is available to any computer using the serial link, and is thus not fixed to
one computer type or even a computer at all, where the controller is used
free running, doing a particular task which doesn't need the intervention of
the user's own computer.

== Call types ==

There are three different types of machine code routines which can
be added to the controller. Each one is suited to a more advanced level
than the other, which also relates to the amount of work needed to actually
get the routine working ! The three levels are such:

=== Simple stand alone routine ===

Here the routine is just the routine
itself with no supporting code (ie. code to integrate with the rest of the
OS). It has to be called directly, by use of the ExecuteCode JobCall, thus
it usually resides at a fixed address and obviously does not offer the user
friendly way of accessing itself like there is with normal OS calls.

=== Extended JobCall ===

There is one JobCall in the OS (ExtendJob)
which can call various routines residing in memory, each one is identified
by a 8 bit number. The disadvantages of this way is that the call hasn't
got it's own JobName/JobCode and needs the extra byte to identify itself.
This is ideal for the quick routine which the user would like to add for
himself without having to resort to the extra code needed for the full
JobCode implementation.

=== Full JobCall ===

This is where the routine can define itself one
(or a number) of JobNames/JobCodes, it can integrate itself into an
extension of the OS in a complete way. The disadvantage is that extra
coding is needed to deal with the various OS calls it has to service and
that extra work is needed to produce a suitable file to place in the
controller.

Normally with most processors, including the 65c02, the machine code
produced is produced for a fixed memory address, and it cannot be made to
run in a different place in memory unless extra work is carried out by the
user, or at least a combination of the user and the OS. For the controller
this is a very severe disadvantage as most extensions are downloaded as
"modules" and to optimise memory a system has to be devised to enable
routines to be placed anywhere in memory, thus allowing no memory to be
wasted. In the OS there is a routine to do just this, though it does need
some help. A special version of the users code has to be developed, or
rather it has to be "processed" to add extra information on the end. Extra
code is needed to set up a few pointers and call the OS routine to relocate.
See later.

== Memory ==

The first 256 bytes of memory are somewhat special, most zero page
locations are reserved for use by the OS:

{|class="wikitable"
|-
|&00-&14||General workspace, used to pass parameters to some OS routines, can also be used by other routines DURING their execution.
|-
|&15-&6F||Reserved
|-
|&70-&9F||Available to the user
|-
|&A0||Accumulator store for irqs (irq_A)
|-
|&A1-&A2||Two byte counter, decremented at 100hz, useful for temporary timing purposes (fcount)
|-
|&A3||RAM size, high byte of RAM size of machine, ie. for 32k this will be &80 (RAM_size)
|-
|&A4-&AF||Reserved
|-
|&B0-&FF||Used by the OS
|-
|}

The rest of memory space is used for the processors stack, OS'
buffers, tables, vectors and, of course, the user available memory.

A breakdown of the rest of memory:

* &100 to &1FF is the 65c02's stack.
* &200-&2FF is used by the OS for various system functions and also contains the vector table, more on that later.
* &300-&3FF is the serial input buffer.
* &400-&47F is the internal job code call output buffer. (jobout_buf)
* &480-&4FF is the internal job code call input buffer. (jobin_buf)
* &500-&5FF is the job status table.
* &600 to the end of RAM memory is for the user. The user should not assume what the top of AVAILABLE memory is and use the system variable HIMEM.

In the controller the maximum limit of RAM is &8000 (which is 32k),
from &8000-&DFFF lies the memory mapped hardware, from &E000 to &FFF9 lies
the OS and from &FFFA to &FFFF lies the 65c02 vectors.

So the user has his own limits of free memory. The lowest limit is
called LOMEM and the highest limit is called HIMEM, everything between these
boundaries is termed "available" for use by anyone, the user or the OS.

Anyone can also claim memory, thus making private to them and not allowing
anyone else to use it. You do this by altering the value of LOMEM, HIMEM
should not be moved. Of course anyone claiming memory should first check
that there is enough memory available for the amount they want to claim for.
To take a common example, a downloadable routine which installs itself as a
extension routine, The download routine will first of all read LOMEM, read
HIMEM, check there is enough memory for the routine, download it to LOMEM
and call it, the downloaded routine will then relocate itself and alter
LOMEM so it is protected.

There is one other memory limit, this is called TOPMEM, this is the
absolute top limit of RAM, HIMEM will normally equal TOPMEM, but a future OS
may alter HIMEM to below TOPMEM. TOPMEM should be ignored ideally, and
HIMEM used.

== OS Calls ==

The OS has calls (ie. a jump instruction which you call, which
then calls, via a RAM vector, a routine in the OS) setup near the top of
memory, through these calls you do everything associated with the
controller. The calls are are such:

* OS_PRINTER at address &FFB9
* OS_CALLOS at address &FFBC
* OS_SENDBYTE at address &FFBF
* OS_READBYTE at address &FFC2
* OS_SENDJOB at address &FFC5
* OS_READJOB at address &FFC8
* OS_DECODEJOB at address &FFCB

The address is the one to call for the particular routine.

* OS_PRINTER is reserved for future use.
* OS_CALLOS calls upon the OS to do various things internally.
* OS_SENDBYTE sends a byte out of the serial port.
* OS_READBYTE reads a byte from the serial port.
* OS_SENDJOB 'sends' a value to the JobCall caller.
* OS_READJOB 'reads' a value from the JobCalls caller.
* OS_DECODEJOB decodes the Job number held in A and acts on it.

Note none of these things should be used in interupt routines,
except OS_CALLOS, of any sort, except if YOU know what state the machine is
in and WHY.

=== Serial Port ===

The serial port on the controller is currently based on the 6850
UART, this need not bother you as the OS deals with the thing entirely by
itself. The chip is setup by the OS to always have a word format of 8n1 and
a baud rate of 9600, this translates to 960cps. The 6850 has two divide
rates for the baud rate, the OS only uses one, using the other one is beyond
the scope of this document and shouldn't be neccessary to use.

Only receive interupts are used, transmission of characters is done
on a polled basis.

As said, there are two calls OS_READBYTE and OS_SENDBYTE.
OS_READBYTE tests the serial input buffer and returns the character (if any
in the A register), the c flag states whether there was a character
returned.

<nowiki> Call : OS_READBYTE
Entry : A, X, Y, c, z = undefined
Exit : X, Y preserved
z = undefined
if c = 1 (no character received)
A is preserved
if c = 0 (character received)
A = character received</nowiki>

OS_SENDBYTE sends the character in the A register out of the serial
port, taking into consideration flow control etc.

<nowiki> Call : OS_SENDBYTE
Entry : A = character to send
X, Y, c, z = undefined
Exit : A, X, Y, c is preserved
z = undefined</nowiki>

=== OS_READJOB and OS_SENDJOB ===

To send/receive data from the user (either internally or via the
serial port) you call OS_SENDJOB/OS_READJOB for the next byte. If your
JobCall requires dynamic use of data, ie. interaction, then a check of the
enviroment should be done to check the call came from the serial port. One
example of this is the OS JobCall MultipleServer, which requires dynamic use
of sending a stream of data until a reaction from the user to tell it to
stop.

<nowiki> Call : OS_READJOB
Purpose: To read job value from the user
Entry : A, X, Y, c, z = undefined
Exit : A = byte read
X, Y is preserved
c, z = undefined
Note : When coming from the serial port it waits for a character to be
received, if you are doing a serial only call and wish to have a loop
checking for a character from the user while doing "your own thing", then
OS_READBYTE should be used. For internal calls this reads data out of
jobin_buf.</nowiki>

<nowiki> Call : OS_SENDJOB
Purpose: To give a job value back to the user
Entry : A = byte to give
X, Y, c, z = undefined
Exit : A, X, Y is preserved
c, z = undefined
Note : This will send either out to the serial port or place a byte in
jobout_buf. For internal calls this stores the value in jobout_buf, which
is allocated 128 bytes, no bound checking is done so sending more than 128
bytes to OS_SENDJOB will cause corruption of some memory.</nowiki>

=== OS_DECODEJOB ===

JobCalls in practise are really only used by the user, JobCalls
tend not to call other calls at all, infact you shouldn't really call
another call unless you were called from the serial port. If you do need to
call another JobCall then you do it like this; with each call you have
associated with it a number, and the call might require some data or give
some data back or both. With the serial port this is simple, you just send
data down and receive data as it is produced. You can't do this with
internal calls, and some calls will not let you call them from inside the
controller, you HAVE to call them from outside. But for the ones which do
let you, you do it with two data blocks, one for input TO the call and one
for output FROM the call. These are setup in a position in memory
(jobin_buf and jobout_buf), each one has a maximum of 128 bytes and this
should not be overflowed (OS_READJOB and OS_SENDJOB do NOT do any bound
checking). So to start with you place in the input block the data you want
to give the call (if any), call it, and then act on the data in the output
block (if any). The OS call OS_DECODEJOB is the one which actually calls
the JobCall handler and eventually the actual routine, you tell the JobCall
handler which call you want by placing the JobCode in the A register.

So for OS_DECODEJOB:

<nowiki> Call : OS_DECODEJOB
Entry : A = JobCode
X, Y, c, z = undefined
jobin_buf should contain any input data
Exit : A = flag
X = number of bytes given back by routine
Y = undefined
c = status, if set JobCall does not exist
z = status, if set JobCall cannot be called internally
jobout_buf contains any data sent from routine</nowiki>

A typical example would be:

<nowiki> LDA #readhimem ; JobCode for ReadHimem
JSR OS_DECODEJOB ; Call the JobCall handler
LDX jobout_buf ; Read HIMEM from buffer LSB
LDY jobout_buf+1 ; Read HIMEM from buffer MSB
STX jobin_buf ; Place LSB in input buffer
STY jobin_buf+1 ; Place MSB in input buffer
LDA #writelomem ; JobCode for WriteLomem
JSR OS_DECODEJOB ; Call the JobCall handler</nowiki>

which would read HIMEM, and then write LOMEM to be the same value, leaving
no spare memory left.

The reason why you should not call an internal call from another
internal call is that the same buffers (jobin_buf and jobout_buf) would be
used for both calls, causing conflict between the two calls, or rather to
the originator of the primary call ! The only time it would be safe if is
if you have already got all the data you want from jobin_buf and haven't
placed any in the jobout_buf (it would be lost if you had done).

=== 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.
|}

== 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 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 isnXt 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 infact. 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 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 ====

===== Function: 0 =====
Purpose: Nothing
<nowiki> Entry : A = 0
X, Y, c, z = undefined
Exit : Leave everything as it is and exit straight away
Note : Used for claimed calls</nowiki>

===== Function: 1 =====
Purpose: NameCode request
<nowiki> 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
Note :</nowiki>

===== Function: 2 =====
Purpose: CodeName request
<nowiki> 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 Code not recognised then
A = 2
X, Y, c, z = undefined
Note :</nowiki>

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

==== unknownjob_vec ====
Purpose: To pass on unknown JobCalls to the correct owner
<nowiki> Entry : A = enviroment (0 = internal call, 1 = serial call)
Y = JobCode
X = JOB ID of owner
c, z = undefined
Exit : if jobcode yours then
if wrong enviroment then
A = 1
Y = 0
X, c, z = undefined
if right enviroment then
perform function
A = 0
Y = 0
X, c, z = undefined
if jobcode not yours then
pass on with registers unaltered
Note :</nowiki>

== Starting Up ==

The setup procedure for setting up extension job calls is to:

# Claim the number of JobCodes you want
#: if success:
# patch the internal_vec and unknownjob_vec vectors
# move LOMEM up to protect your program
# do anything else for initial startup you may want to do
# return back, ready and waiting

This in code looks like:

<nowiki>execute
LDX #no_of_calls ; Number of JobCodes wanted
LDA #1 ; CALLOS, function 1, Claim JobCodes
JSR OS_CALLOS ; Call CALLOS
CPX #0 ; Check we were given some codes
BEQ noinstall ; No, don't bother installing ourself
STX call ; Store base address of JobCodes allocated
STY job_id ; Store JOB ID given

LDA internal_vec ; Get old internal_vec (LSB)
STA ovec ; Store it
LDA internal_vec+1 ; Get old internal_vec (MSB)
STA ovec+1 ; Store it
LDA #>internal_handle ; Our internal handler (LSB)
STA internal_vec ; Place it in the vector (LSB)
LDA #<internal_handle ; Our internal handler (MSB)
STA internal_vec+1 ; Place it in the vector (MSB)

LDA unknownjob_vec ; Get old unknownjob_vec (LSB)
STA ovec2 ; Store it
LDA unknownjob_vec+1 ; Get old unknownjob_vec (MSB)
STA ovec2+1 ; Store it
LDA #>job_handle ; Our unknown job handler (LSB)
STA unknownjob_vec ; Place it in the vector (LSB)
LDA #<job_handle ; Our unknown job handler (MSB)
STA unknownjob_vec+1 ; Place it in the vector (MSB)

LDX #>WriteLomem ; Point to JobName
LDY #<WriteLomem
JSR findjob ; Find WriteLomem code
BEQ noinstall ; Doesn't exist !
LDX #>end_of_code ; End of code (LSB)
LDY #<end_of_code ; End of code (MSB)
STX jobin_buf ; Place it in jobin_buf (LSB)
STY jobin_buf+1 ; Place it in jobin_buf+1 (MSB)
JSR OS_DECODEJOB ; Call JobCall handler

noinstall
RTS ; End - return to OS

findjob
STX zero.gp1 ; Zero page
STY zero.gp1+
LDY #0
findthisjoblo
LDA (zero.gp1),Y
STA jobin.buf,Y ; Store name in jobin_buf
INY
CMP #13
BNE findthisjoblo
LDA #3 ; NameCode
JSR OS.DECODEJOB ; Call NameCode
LDA jobout.buf ; Get returned value
RTS

WriteLomem STR "WriteLomem"</nowiki>

This will setup the various vectors and memory pointers for the
applicaion, the actual routines (internal_handle and job_handle) are fairly
straight forward and simple:

<nowiki>internal_handle
CMP #1 : Is it function call 1 (NameCode) ?
BNE internal_handle_2 ; No, check for function 2
LDA job_id ; Get our JOB ID number
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #>job_names ; Our Job name table (LSB)
LDY #<job_names ; Our Job name table (MSB)
LDA #2 ; CALLOS function 2
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes : Found, go off and claim call
LDA #1 ; Not found, restore A
JMP (ovec) ; Call back to old vector

internal_handle_2
CMP #2 ; Is it function call 2 (CodeName) ?
BNE internal_handle_3 ; No, unknown, pass on
LDA job_id ; Get our JOB ID
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #>job_names ; Our Job name table (LSB)
LDY #<job_names ; Our Job name table (MSB)
LDA #3 ; CALLOS function 3
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes ; Found, go off and claim call
LDA #2 ; Not found, restore A
JMP (ovec) ; Call back to old vector

internal_yes
LDA #0 ; We want to claim call for some reason

internal_handle_3
JMP (ovec) ; Call back to old vector

job_handle
PHA ; Mark sure to preserve A
CPY call ; Check call wanted against base of ours
BCC job_handle_no ; Less than our base, so definately not ours
TYA
SBC #no_of_calls ; Subtract number of calls we have
CMP call ; Now compare with base
BCC job_handle2 ; Yes, one of ours

job_handle.no
PLA ; Restore A
JMP (ovec2) ; Call back to old vector

job_handle2
TYA
SEC
SBC call ; Subtract our base from call
ASL A ; Times by 2 for offset into table
TAY ; Place in Y
LDA job_run_table,Y ; Get LSB of routine
STA zero_gp1 ; Store it for indirect jump (LSB)
LDA job_run_table+1,Y ; Get MSB of routine
STA zero_gp1+1 ; Store it for indirect jump (MSB)
PLA ; Restore A
JMP (zero_gp1) ; Call our relevant routine

job_names ; List of our JobNames
STR "TestJob" ; Test job name
DFB &FF ; &FF - marks end of table

job_run_table ; List of routine addresses to match Jobs
DFW job_TestJob ; Test job routine</nowiki>

== Relocation ==

The relocation method used will not do a complete relocation, ie.
from ANY address to ANY address. The only constraint on the addresses is
that they must be the same offset in the page, which means, &2602 and &3402
is alright but &2602 and &3455 is not, ie. the difference between the two
addresses must be a multiple of 256 bytes, as only the MSB is altered, this
should not cause any real problems. What is meant by the two addresses is
the address the code was originally assembled at and the address it wants
relocating to. Because of this programs must be multiples of 256 bytes, ie.
the low byte of LOMEM must ALWAYS be 0, your program should be padded out.

The relocation mechanism works by having a table, and to each byte
of code there is one BIT, if unset it means the byte of code should not be
relocated, else it should be, thus the BitMap table is 8 times smaller than
the code. To generate the BitMap you have to assemble the code at two
different places, and compare both sets of assembled code against each
other, the differences are where the code is to be relocated. The code
which is sent up to the controller is assumed to be assembled at address
&100, so the first code should be assembled at &100, the other one should be
assembled at another address, say &600, and the first one be sent up with
the BitMap. A program is availble for the Elk/Beeb/Arc with 65Tube/Mac with
BBC BASIC to compare the two files and create the BitMap.

All the program has to do to relocate itself is execute this bit of
code first of all: (address is the base address of the program, ie. &100
for the downloaded version)

<nowiki>execcall
LDA #>(execute-address) ; Final execution address offset (LSB)
STA zero_gp1
LDA #<(execute-address) ; Final execution address offset (MSB)
STA zero_gp1+1

LDA #>(BitMap-address) ; BitMap address offset (LSB)
STA zero_gp2
LDA #<(BitMap-address) ; BitMap address offset (MSB)
STA zero_gp2+1

LDA #>(execcall-address); Length of data to relocate (LSB)
STA zero_gp3
LDA #<(execcall-address); Length of data to relocate (MSB)
STA zero_gp3+1

TXA ; Execcall REAL address
SEC
SBC #>(execcall-address); Subrtract length
TAX ; Put it back in X
TYA ; Ditto for MSB
SBC #<(execcall-address)
TAY
LDA #4 ; CALLOS function for Relocate
JMP OS_CALLOS ; Call CALLOS

BitMap ; BitMap start</nowiki>

This will relocate the code and automatically call the execution
address, which should be the initialisation code (ie. setup internal_vec
and unknownjob_vec etc.). "address" is the address the code is started to
assemble at, &100 for the version to be uploaded. The upload routine should
pass in X and Y (via ExecuteCode) the address of the start of execcall, this
means that the routine can tell where it is in memory, subtracting the
length gives the start of the code to relocate.

== Layout Summary ==

The layout of a full application should be like this by now:

<nowiki> start of code
program job codes, data etc.
internal handler
job handler
end of code
initialisation (setup internal etc.)
end of code to be relocated
execution (relocation)
relocation BitMap</nowiki>

Because of memory space the initialisation code should be placed
outside the reserved memory limit of the program, as it is only called once
and not needed again.

== Other miscellaneous calls ==

<nowiki>Call : OS_PRINTER
Purpose : To place a character in the printer buffer
Entry : A = character to send
X, Y, c, z = undefined
Exit : A, X, Y is preserved
if c = 0 (printed)
The printer is on and the character was inserted
if c = 1 (not printed)
The printer is off and the character was forgotten
z = undefined
Note : The character goes into the printer buffer and will be
actually sent to the printer when the printer asks for it. If the printer
was not awake to begin with, an attempt is made to wake it up, thus
meaning that in some circumstances when the printer wasn't ready a
character may be lost, this cannot be helped. If the printer is off (via
the BCD switch) then the character will be forgotten as the Printer Buffer
is inactive.</nowiki>

The module is located at &8000 in memory, and should be a EPROM placed
in the second ROM socket in the controller (ie. the top RAM socket). This
module is primary designed to turn the Controller into a dedicated task,
making it perform some function from switch on. It could also be used to
add more permant JobCalls to the Controller, in the process taking up much
less RAM), but because of there being only one Module present this feature
is limited, and is much more suited to a collection of the user's own
personal routines.

For the OS to recognise a module as being in place the text "Module" is
looked for, the layout of a module should be like this (starting at
&8000):

<nowiki>Offset value comment
0 "Module" The OS checks for this string
6 0 End of check string
7 Language entry Address of 'Language' entry
9 Service entry Address of 'Service' entry
11 "<Module Title>" Module title
0 End of Module title

"<Module part>" Part Module Title
0 End of Part Module Title
"x.xx" Part version number

&FF End of parts list</nowiki>

The language entry is a 2 byte value holding the address of the language
entry routine, this is called on reset, if the BCD is set correctly. A
value of less than &8000 means there is no valid language entry and any
language calls are ignored. If a RTS is made the OS carries on as it would
have if there wasn't a language call.

The service entry is a 2 byte value holding the address of the service
entry routine, this is called at various appropiate moments with service
numbers in A. A list of current calls is thus:

<nowiki> 0 - Not used
1 - Unknown Job Code
2 - Centisecond call
3 - Irq2 (unknown IRQ)
4 - internal_vec call (exit with A=0 to claim)
254 - RESET
255 - BRK</nowiki>

On exit all registers and flags should be preserved. For call 1 the
unknown job value is held in the Y register, the enviroment is held in the
X register, on exit, X should contain the flag, as A does from the exit of
unknownjob_vec. For the rest of calls, X and Y are undefined.

For both Service and Language entry points, a value of 0 means "there is
no valid routine" and the module isn't called for that type of entry.

Finally a full implementation of a JobCall, from start to finish.

<nowiki> DIM data% &1000
:
no_of_calls = 1
:
VIA = &E030
ACIA = &E010
ADC = &E000
AUX_PORT = &E020
brk_vec = &200
nmi_vec = &202
irq_vec = &204
irq2_vec = &206
sendserial_vec = &208
readserial_vec = &20A
sendjob_vec = &20C
readjob_vec = &20E
decodejob_vec = &210
unknownjob_vec = &212
extjob_vec = &214
centisec_vec = &216
internal_vec = &218
callos_vec = &21A
printer_vec = &21C
zero_gp1 = 0
zero_gp2 = 2
zero_gp3 = 4
zero_gp4 = 6
zero_gp5 = 8
zero_gp6 = 10
zero_gp7 = 12
zero_gp8 = 14
zero_gp9 = 16
zero_gp10 = 18
user_reserved = &70
irq_A = &A0
fcount = &A1
RAM_size = &A3
jobout_buf = &400
jobin_buf = &480
OS_PRINTER = &FFB9
OS_CALLOS = &FFBC
OS_SENDBYTE = &FFBF
OS_READBYTE = &FFC2
OS_SENDJOB = &FFC5
OS_READJOB = &FFC8
OS_DECODEJOB = &FFCB
:
FOR create=1 TO 2
:
FOR pass%=4 TO 7 STEP 3
P%=&100*create : O%=data%
[OPT pass%
:
.job_DemoJob
CMP #1
BEQ DemoJob_go
LDA #1
LDY #0
RTS
/
.DemoJob_go

:
.internal_handle
CMP #1 ; Is it function call 1 (NameCode) ?
BNE internal_handle_2 ; No, check for function 2
/
LDA job_id ; Get our JOB ID number
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #job_names MOD 256 ; Our Job name table (LSB)
LDY #job_names DIV 256 ; Our Job name table (MSB)
LDA #2 ; CALLOS function 2
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes ; Found, go off and claim call
LDA #1 ; Not found, restore A
JMP (ovec) ; Call back to old vector
/
.internal_handle_2
CMP #2 ; Is it function call 2 (CodeName) ?
BNE internal_handle_3 ; No, unknown, pass on
/
LDA job_id ; Get our JOB ID
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #job_names MOD 256 ; Our Job name table (LSB)
LDY #job_names DIV 256 ; Our Job name table (MSB)
LDA #3 ; CALLOS function 3
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes ; Found, go off and claim call
LDA #2 ; Not found, restore A
JMP (ovec) ; Call back to old vector
/
.internal_yes
LDA #0 ; We want to claim call for some reason
/
.internal_handle_3
JMP (ovec) ; Call back to old vector
:
.job_handle
PHA ; Make sure to preserve A
CPY call ; Check call wanted against base of ours
BCC job_handle_no ; Less than our base, so definately not ours
TYA
SBC #no_of_calls ; Subtract number of calls we have
CMP call ; Now compare with base
BCC job_handle2 ; Yes, one of ours
/
.job_handle.no
PLA ; Restore A
JMP (ovec2) ; Call back to old vector
/
.job_handle2
TYA
SEC
SBC call ; Subtract our base from call
ASL A ; Times by 2 for offset into table
TAY ; Place in Y
LDA job_run_table,Y ; Get LSB of routine
STA zero_gp1 ; Store it for indirect jump (LSB)
LDA job_run_table+1,Y ; Get MSB of routine
STA zero_gp1+1 ; Store it for indirect jump (MSB)
PLA ; Restore A
JMP (zero_gp1) ; Call our relevant routine
:
.job_names ; List of our JobNames
EQUS "DemoJob":EQUB 13 ; Test job name
/
EQUB &FF ; &FF - marks end of table
:
.job_run_table ; List of routine addresses to match Jobs
EQUW job_DemoJob ; Test job routine
:
.call : EQUB 0 ; Store for our JobCode base
.job_id : EQUB 0 ; Store for our JobId
.ovec : EQUW 0 ; Store for old internal_vec value
.ovec2 : EQUW 0 ; Store for old unknownjob_vec value
:
EQUS STRING$(&100-(P% MOD 256),CHR$0)
.end_of_code ; end_of_code should be on page boundry
:
.execute
LDX #no_of_calls ; Number of JobCodes wanted
LDA #1 ; CALLOS, function 1, Claim JobCodes
JSR OS_CALLOS ; Call CALLOS
STX call ; Store base address of JobCodes allocated
STY job_id ; Store JOB ID given
CPX #0 ; Check we were given some codes
BEQ noinstall ; No, don't bother installing ourself
/
LDA internal_vec ; Get old internal_vec (LSB)
STA ovec ; Store it
LDA internal_vec+1 ; Get old internal_vec (MSB)
STA ovec+1 ; Store it
LDA #internal_handle MOD 256 ; Our internal handler (LSB)
STA internal_vec ; Place it in the vector (LSB)
LDA #internal_handle DIV 256 ; Our internal handler (MSB)
STA internal_vec+1 ; Place it in the vector (MSB)
/
LDA unknownjob_vec ; Get old unknownjob_vec (LSB)
STA ovec2 ; Store it
LDA unknownjob_vec+1 ; Get old unknownjob_vec (MSB)
STA ovec2+1 ; Store it
LDA #job_handle MOD 256 ; Our unknown job handler (LSB)
STA unknownjob_vec ; Place it in the vector (LSB)
LDA #job_handle DIV 256 ; Our unknown job handler (MSB)
STA unknownjob_vec+1 ; Place it in the vector (MSB)
/
LDX #end_of_code MOD 256 ; End of code (LSB)
LDY #end_of_code DIV 256 ; End of code (MSB)
STX jobin_buf ; Place it in jobin_buf (LSB)
STY jobin_buf+1 ; Place it in jobin_buf+1 (MSB)
LDA #65 ; JobCode for WriteLomem
JSR OS_DECODEJOB ; Call JobCall handler
/
.noinstall
RTS ; End - return to OS
:
.execcall
LDA #>(execute-address) ; Final execution address offset (LSB)
STA zero_gp1
LDA #<(execute-address) ; Final execution address offset (MSB)
STA zero_gp1+1
/
LDA #>(BitMap-address) ; BitMap address offset (LSB)
STA zero_gp2
LDA #<(BitMap-address) ; BitMap address offset (MSB)
STA zero_gp2+1
/
LDA #>(execcall-address) ; Length of data to relocate (LSB)
STA zero_gp3
LDA #<(execcall-address) ; Length of data to relocate (MSB)
STA zero_gp3+1
/
TXA ; Execcall REAL address
SEC
SBC #>(execcall-address) ; Subrtract length
TAX ; Put it back in X
TYA ; Ditto for MSB
SBC #<(execcall-address)
TAY
LDA #4 ; CALLOS function for Relocate
JMP OS_CALLOS ; Call CALLOS
/
.BitMap ; BitMap start
:
]
NEXT
:
OSCLI "SAVE code"+STR$create+" "+STR$~data%+" "+STR$~O%
:
NEXT</nowiki>

== Changelog ==

<nowiki>bob 071 Fixed MotorForward bug (%10)
bob 072 CallOS 14 now checks current adc.owner status
jim 072.d1 * Rewrite for new hardware/processor *
jim 072.d1 Moved vectors/workspace to &440
jim 072.d1 Moved rs.inp.buf to &500
jim 072.d1 Moved jobout.buf to &600
jim 072.d1 Moved jobin.buf to &680
jim 072.d1 Moved jobs.status to &700
jim 072.d1 Added irq.X (&A4)
jim 072.d1 Added irq.Y (&A5)
jim 072.d1 Removed short detection code
jim 072.d1 Voided CallOS' 6,7,8,9,10,11,13,16,17,18,19
jim 072.d1 Removed JobCalls ReadADCReg,WriteADCReg
jim 072.d1 Removed JobCalls ReadACIAReg,WriteACIAReg
jim 072.d1 Removed JobCalls ReadVIAReg,WriteVIAReg,SetVIAHigh,SetVIALow
jim 072.d1 Added CallOS 21 Write Outputs
jim 072.d1 Added CallOS 22 Read Outputs added
jim 072.d1 Added CallOS 23 Read Inputs added
jim 072.d1 Added CallOS 24 Write Motors
jim 072.d1 Added CallOS 25 Read Motors
jim 072.d1 Added CallOS 26 Read Keypad
jim 072.d1 Expanded CallOS 5 information
jim 072.d1 Added JobCall IdentSystem to return CallOS 5 info
jim 072.d1 JobCalls now use appropriate CallOS'
jim 072.d1 OS.READBYTE no longer preserves A on CS
jim 072.d1 irq.vec,irq2.vec,nmi.vec now redundant
jim 072.d1 Renamed JobCall DownloadData to DownloadData38
jim 072.d1 Renamed JobCall UploadData to UploadData38
jim 072.d1 Renamed JobCall ExecuteCode to ExecuteCode38
jim 072.d1 Renamed JobCall ReadByte to ReadByte38
jim 072.d1 Renamed JobCall StoreByte to StoreByte38
jim 072.d1 JobCall ForcedADCRead now checks adc.owner first
jim 072.d3 Added CallOS 27 Write printer
jim 072.d3 Added CallOS 28 Read printer
jim 072.d3 Added CallOS 29 Write RTC Reg
jim 072.d3 Added CallOS 30 Read RTC Reg
jim 072.d3 Added CallOS 31 Write RTC string
jim 072.d3 Added CallOS 32 Read RTC string
jim 072.d3 Added CallOS 33 Write RTC bcd
jim 072.d3 Added CallOS 34 Read RTC bcd
jim 072.d3 Added CallOS 35 Write LCD Reg
jim 072.d3 Added CallOS 36 Read LCD Reg
jim 072.d3 Added JobCall WritePrinter
jim 072.d3 Added JobCall ReadPrinter
jim 072.d3 Added JobCall PrintChar
jim 072.d3 Added JobCall PrintStreamZ
jim 072.d3 Added JobCall PrintStream
jim 072.d3 Added JobCall PrintServer
jim 072.d3 Added JobCall WriteRTCReg
jim 072.d3 Added JobCall ReadRTCReg
jim 072.d3 Added JobCall WriteRTC
jim 072.d3 Added JobCall ReadRTC
jim 072.d3 Added JobCall WriteRTCbcd
jim 072.d3 Added JobCall ReadRTCbcd
jim 072.d3 Added JobCall WriteLCDReg
jim 072.d3 Added JobCall ReadLCDReg
jim 072.d3 Added CallOS 37 Write Power ctrl
jim 072.d3 Added CallOS 38 Read Power ctrl
jim 072.d3 Implemented OS.PRINTER
jim 072.d3 Added JobCall PatchMF (MotorForward)
jim 072.d3 Changed irq.vec to int0.vec
jim 072.d3 Changed irq2.vec to int1.vec
jim 072.d3 Added int2irq.vec (wrksp+&20)
jim 072.d3 Added int3irq.vec (wrksp+&22)
jim 072.d3 Added int4irq.vec (wrksp+&24)
jim 072.d3 Added c0irq.vec (wrksp+&26)
jim 072.d3 Added c1irq.vec (wrksp+&28)
jim 072.d3 Added t1irq.vec (wrksp+&2A)
jim 072.d3 Added t2irq.vec (wrksp+&2C)
jim 072.d3 Added txirq.vec (wrksp+&2E)
jim 072.d3 Added tyirq.vec (wrksp+&30)
jim 072.d3 Added s1rirq.vec (wrksp+&32)
jim 072.d3 Added s1rirq.vec (wrksp+&34)
jim 072.d3 Added s2irq.vec (wrksp+&36)
jim 072.d3 Added adcirq.vec (wrksp+&38)
jim 072.d3 Renamed JobCall DownloadData38 to DownloadData740
jim 072.d3 Renamed JobCall UploadData38 to UploadData740
jim 072.d3 Renamed JobCall ExecuteCode38 to ExecuteCode740
jim 072.d3 Renamed JobCall ReadByte38 to ReadByte740
jim 072.d3 Renamed JobCall StoreByte38 to StoreByte740
jim 072.d4 Hardware update
jim 072.d4 Re-assigned CallOS 37 to Write Power/Charge control
jim 072.d4 Re-assigned CallOS 38 to Read Power/Charge control
jim 072.d4 Moved int2irq.vec to wrksp+&22
jim 072.d4 Moved int3irq.vec to wrksp+&24
jim 072.d4 Moved int4irq.vec to wrksp+&26
jim 072.d4 Moved c0irq.vec to wrksp+&28
jim 072.d4 Moved c1irq.vec to wrksp+&2A
jim 072.d4 Moved t1irq.vec to wrksp+&2C
jim 072.d4 Moved t2irq.vec to wrksp+&2E
jim 072.d4 Moved txirq.vec to wrksp+&30
jim 072.d4 Moved tyirq.vec to wrksp+&32
jim 072.d4 Moved s1rirq.vec to wrksp+&34
jim 072.d4 Moved s1rirq.vec to wrksp+&36
jim 072.d4 Moved s2irq.vec to wrksp+&38
jim 072.d4 Moved adcirq.vec to wrksp+&3A
jim 072.d4 Added OS.LCDVDU (&FFB7) and lcdvdu.vec (wrksp+&20)
jim 072.d5 Re-assigned CallOS 37 to Write/Read Power/Charge control
jim 072.d5 Re-assgined CallOS 38 Read Battery Voltage
jim 072.d5 OS.CALLOS now re-entrant
jim 072.d5 Fixed OS.PRINTER
jim 072.d5 Started to add internal logging software
jim 072.d5 Moved OS.LCDVDU to &FFB6
jim 072.d7 Added OS.PRINTERPOLL (&FFB3) and printerpoll.vec (wrksp+&3C)
bob 073 Matched jim & bob sensor lookup tables
bob 073 Added PatchMF
jim 072.dj Added OS.CALLOS 51 Read keypad press
jim 072.dj Added hard reset keypad press
jim 072.dk Added JobCall ReadOutputs
jim 072.do Changed soft reset of zero page locations
jim 072.do Changed MotorForward/Backward bitmaps
jim 072.dp Fixed OS.CALLOS WriteRTCbcd
jim 072.dq Fixed OS.CALLOS ReadRTCstring for correct 24hr operation
jim 072.dr Changed reset prompts
bob 074 Added support for Little Bob
jim 072.dy Added further RTC/CMOS support
jim 072.dB Removed double hard reset
jim 072.dE Set _cpu.mode depending on external memory requirement
jim 072.dF Added Insight code
jim 073 Sub-release
jim 074 Modification to LCD code - uses bsy flag all the time now
jim 074 Fixed OS.CALLOS 42 Write LCD Char Def
jim 074 Fixed OS.CALLOS 43 Read LCD Char Def
jim 075 Added simple battery charge code
jim 075 Fixed JobCall ReadSensorTable
jim 075 Fixed OS.CALLOS 42 Write LCD Char Def
jim 075 Fixed OS.CALLOS 43 Read LCD Char Def
jim 075 Added sleep code
jim 075 Added OS.CALLOS 52 Write Sleep Time
jim 075 Added OS.CALLOS 53 Read Sleep Time
jim 075 Modified battery charge code
jim 076 Modified JobCall ReadSensorTable
jim 076 Modified OS.CALLOS 26 ReadKeypad to do debounce
jim 077 Rewrote battery charging code
jim 077.2 Reduced stop charge threshold to 2
jim 077.3 Increased stop charge threshold to 3
jim 077.3 Added battery voltage averaging
bill 077 Stripped
bill 077 Moved ins to out port
bill 077 Added RTS
bill 077 Changed sensor ID system back to original, using p2.1
bill 077 Dedicated USB/RS selection line, RTS provisioned on p2.3
bill 077 Overload "bounce" timing
bill 078 CTS added
bill 079 Temperature fudge</nowiki>

MediaWiki:Common.css

2023-11-04T09:05:04Z

Benryves:

hr {
overflow: hidden;
}

table.calltable tr td {
vertical-align: top;
}
table.calltable tr td > * {
margin-top: 0;
}
table.calltable tr td:first-child {
font-weight: bold;
}

MediaWiki:Common.css

2023-11-04T09:03:13Z

Benryves: Added calltable styles

hr {
overflow: hidden;
}

table.calltable tr td {
vertical-align: top;
}

table.calltable tr td:first-child {
font-weight: bold;
}

SmartBox OS

2023-11-04T08:54:51Z

Benryves: /* CallOS */ Restructured OS_CALLOS headers for more consistent names and to include routine description

== Documentation for SmartBox OS 2.066 ==

The term JobCall is the concept of the routine itself, as opposed to
JobName (which is the actual name associated with it (eg. NameCode)) and
JobCode (which is the actual number associated with it (eg. 3)).

The term controller means the SmartBox, or any other incarnation
which may appear in future time !

The term OS means the controllers' Operating System.

== Preview ==

There are a number of reasons why using Machine Code on the
controller is more desirable than using the various JobCalls via the serial
link. One reason is speed, if the task which needs to be performed, has to
be performed very quickly (more quickly than can be achieved via the serial
link at least), then some code must be written to work in the controller
itself to achieve this sort of speed. If the task required is to be a
"background" task (ie. a task which may happen while other "things" carry
on as normal, like a change of state of a particular port) then it is far
easier to let the controller do all the work, maybe under interupts, than
continuously poll the controller checking the state of various things.
Another reason may be that you would like to add another JobCall to the OS,
extending the calls available to external applications (and the user at the
same time), without the user having to write the code himself to achieve the
aim. For advanced users, there is also the ablity to alter the way the OS
does various things and to have the controller in their "power", for
dedicated tasks etc.

One advantage of writing IN the controller is that that "function"
is available to any computer using the serial link, and is thus not fixed to
one computer type or even a computer at all, where the controller is used
free running, doing a particular task which doesn't need the intervention of
the user's own computer.

== Call types ==

There are three different types of machine code routines which can
be added to the controller. Each one is suited to a more advanced level
than the other, which also relates to the amount of work needed to actually
get the routine working ! The three levels are such:

=== Simple stand alone routine ===

Here the routine is just the routine
itself with no supporting code (ie. code to integrate with the rest of the
OS). It has to be called directly, by use of the ExecuteCode JobCall, thus
it usually resides at a fixed address and obviously does not offer the user
friendly way of accessing itself like there is with normal OS calls.

=== Extended JobCall ===

There is one JobCall in the OS (ExtendJob)
which can call various routines residing in memory, each one is identified
by a 8 bit number. The disadvantages of this way is that the call hasn't
got it's own JobName/JobCode and needs the extra byte to identify itself.
This is ideal for the quick routine which the user would like to add for
himself without having to resort to the extra code needed for the full
JobCode implementation.

=== Full JobCall ===

This is where the routine can define itself one
(or a number) of JobNames/JobCodes, it can integrate itself into an
extension of the OS in a complete way. The disadvantage is that extra
coding is needed to deal with the various OS calls it has to service and
that extra work is needed to produce a suitable file to place in the
controller.

Normally with most processors, including the 65c02, the machine code
produced is produced for a fixed memory address, and it cannot be made to
run in a different place in memory unless extra work is carried out by the
user, or at least a combination of the user and the OS. For the controller
this is a very severe disadvantage as most extensions are downloaded as
"modules" and to optimise memory a system has to be devised to enable
routines to be placed anywhere in memory, thus allowing no memory to be
wasted. In the OS there is a routine to do just this, though it does need
some help. A special version of the users code has to be developed, or
rather it has to be "processed" to add extra information on the end. Extra
code is needed to set up a few pointers and call the OS routine to relocate.
See later.

== Memory ==

The first 256 bytes of memory are somewhat special, most zero page
locations are reserved for use by the OS:

{|class="wikitable"
|-
|&00-&14||General workspace, used to pass parameters to some OS routines, can also be used by other routines DURING their execution.
|-
|&15-&6F||Reserved
|-
|&70-&9F||Available to the user
|-
|&A0||Accumulator store for irqs (irq_A)
|-
|&A1-&A2||Two byte counter, decremented at 100hz, useful for temporary timing purposes (fcount)
|-
|&A3||RAM size, high byte of RAM size of machine, ie. for 32k this will be &80 (RAM_size)
|-
|&A4-&AF||Reserved
|-
|&B0-&FF||Used by the OS
|-
|}

The rest of memory space is used for the processors stack, OS'
buffers, tables, vectors and, of course, the user available memory.

A breakdown of the rest of memory:

* &100 to &1FF is the 65c02's stack.
* &200-&2FF is used by the OS for various system functions and also contains the vector table, more on that later.
* &300-&3FF is the serial input buffer.
* &400-&47F is the internal job code call output buffer. (jobout_buf)
* &480-&4FF is the internal job code call input buffer. (jobin_buf)
* &500-&5FF is the job status table.
* &600 to the end of RAM memory is for the user. The user should not assume what the top of AVAILABLE memory is and use the system variable HIMEM.

In the controller the maximum limit of RAM is &8000 (which is 32k),
from &8000-&DFFF lies the memory mapped hardware, from &E000 to &FFF9 lies
the OS and from &FFFA to &FFFF lies the 65c02 vectors.

So the user has his own limits of free memory. The lowest limit is
called LOMEM and the highest limit is called HIMEM, everything between these
boundaries is termed "available" for use by anyone, the user or the OS.

Anyone can also claim memory, thus making private to them and not allowing
anyone else to use it. You do this by altering the value of LOMEM, HIMEM
should not be moved. Of course anyone claiming memory should first check
that there is enough memory available for the amount they want to claim for.
To take a common example, a downloadable routine which installs itself as a
extension routine, The download routine will first of all read LOMEM, read
HIMEM, check there is enough memory for the routine, download it to LOMEM
and call it, the downloaded routine will then relocate itself and alter
LOMEM so it is protected.

There is one other memory limit, this is called TOPMEM, this is the
absolute top limit of RAM, HIMEM will normally equal TOPMEM, but a future OS
may alter HIMEM to below TOPMEM. TOPMEM should be ignored ideally, and
HIMEM used.

== OS Calls ==

The OS has calls (ie. a jump instruction which you call, which
then calls, via a RAM vector, a routine in the OS) setup near the top of
memory, through these calls you do everything associated with the
controller. The calls are are such:

* OS_PRINTER at address &FFB9
* OS_CALLOS at address &FFBC
* OS_SENDBYTE at address &FFBF
* OS_READBYTE at address &FFC2
* OS_SENDJOB at address &FFC5
* OS_READJOB at address &FFC8
* OS_DECODEJOB at address &FFCB

The address is the one to call for the particular routine.

* OS_PRINTER is reserved for future use.
* OS_CALLOS calls upon the OS to do various things internally.
* OS_SENDBYTE sends a byte out of the serial port.
* OS_READBYTE reads a byte from the serial port.
* OS_SENDJOB 'sends' a value to the JobCall caller.
* OS_READJOB 'reads' a value from the JobCalls caller.
* OS_DECODEJOB decodes the Job number held in A and acts on it.

Note none of these things should be used in interupt routines,
except OS_CALLOS, of any sort, except if YOU know what state the machine is
in and WHY.

=== Serial Port ===

The serial port on the controller is currently based on the 6850
UART, this need not bother you as the OS deals with the thing entirely by
itself. The chip is setup by the OS to always have a word format of 8n1 and
a baud rate of 9600, this translates to 960cps. The 6850 has two divide
rates for the baud rate, the OS only uses one, using the other one is beyond
the scope of this document and shouldn't be neccessary to use.

Only receive interupts are used, transmission of characters is done
on a polled basis.

As said, there are two calls OS_READBYTE and OS_SENDBYTE.
OS_READBYTE tests the serial input buffer and returns the character (if any
in the A register), the c flag states whether there was a character
returned.

<nowiki> Call : OS_READBYTE
Entry : A, X, Y, c, z = undefined
Exit : X, Y preserved
z = undefined
if c = 1 (no character received)
A is preserved
if c = 0 (character received)
A = character received</nowiki>

OS_SENDBYTE sends the character in the A register out of the serial
port, taking into consideration flow control etc.

<nowiki> Call : OS_SENDBYTE
Entry : A = character to send
X, Y, c, z = undefined
Exit : A, X, Y, c is preserved
z = undefined</nowiki>

=== OS_READJOB and OS_SENDJOB ===

To send/receive data from the user (either internally or via the
serial port) you call OS_SENDJOB/OS_READJOB for the next byte. If your
JobCall requires dynamic use of data, ie. interaction, then a check of the
enviroment should be done to check the call came from the serial port. One
example of this is the OS JobCall MultipleServer, which requires dynamic use
of sending a stream of data until a reaction from the user to tell it to
stop.

<nowiki> Call : OS_READJOB
Purpose: To read job value from the user
Entry : A, X, Y, c, z = undefined
Exit : A = byte read
X, Y is preserved
c, z = undefined
Note : When coming from the serial port it waits for a character to be
received, if you are doing a serial only call and wish to have a loop
checking for a character from the user while doing "your own thing", then
OS_READBYTE should be used. For internal calls this reads data out of
jobin_buf.</nowiki>

<nowiki> Call : OS_SENDJOB
Purpose: To give a job value back to the user
Entry : A = byte to give
X, Y, c, z = undefined
Exit : A, X, Y is preserved
c, z = undefined
Note : This will send either out to the serial port or place a byte in
jobout_buf. For internal calls this stores the value in jobout_buf, which
is allocated 128 bytes, no bound checking is done so sending more than 128
bytes to OS_SENDJOB will cause corruption of some memory.</nowiki>

=== OS_DECODEJOB ===

JobCalls in practise are really only used by the user, JobCalls
tend not to call other calls at all, infact you shouldn't really call
another call unless you were called from the serial port. If you do need to
call another JobCall then you do it like this; with each call you have
associated with it a number, and the call might require some data or give
some data back or both. With the serial port this is simple, you just send
data down and receive data as it is produced. You can't do this with
internal calls, and some calls will not let you call them from inside the
controller, you HAVE to call them from outside. But for the ones which do
let you, you do it with two data blocks, one for input TO the call and one
for output FROM the call. These are setup in a position in memory
(jobin_buf and jobout_buf), each one has a maximum of 128 bytes and this
should not be overflowed (OS_READJOB and OS_SENDJOB do NOT do any bound
checking). So to start with you place in the input block the data you want
to give the call (if any), call it, and then act on the data in the output
block (if any). The OS call OS_DECODEJOB is the one which actually calls
the JobCall handler and eventually the actual routine, you tell the JobCall
handler which call you want by placing the JobCode in the A register.

So for OS_DECODEJOB:

<nowiki> Call : OS_DECODEJOB
Entry : A = JobCode
X, Y, c, z = undefined
jobin_buf should contain any input data
Exit : A = flag
X = number of bytes given back by routine
Y = undefined
c = status, if set JobCall does not exist
z = status, if set JobCall cannot be called internally
jobout_buf contains any data sent from routine</nowiki>

A typical example would be:

<nowiki> LDA #readhimem ; JobCode for ReadHimem
JSR OS_DECODEJOB ; Call the JobCall handler
LDX jobout_buf ; Read HIMEM from buffer LSB
LDY jobout_buf+1 ; Read HIMEM from buffer MSB
STX jobin_buf ; Place LSB in input buffer
STY jobin_buf+1 ; Place MSB in input buffer
LDA #writelomem ; JobCode for WriteLomem
JSR OS_DECODEJOB ; Call the JobCall handler</nowiki>

which would read HIMEM, and then write LOMEM to be the same value, leaving
no spare memory left.

The reason why you should not call an internal call from another
internal call is that the same buffers (jobin_buf and jobout_buf) would be
used for both calls, causing conflict between the two calls, or rather to
the originator of the primary call ! The only time it would be safe if is
if you have already got all the data you want from jobin_buf and haven't
placed any in the jobout_buf (it would be lost if you had done).

=== 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 ====

<nowiki> 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 </nowiki>

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

<nowiki> 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.</nowiki>

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

<nowiki> 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</nowiki>

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

<nowiki> 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</nowiki>

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

<nowiki> 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</nowiki>

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

<nowiki> 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 CALLOS
0 and decide what addresses/configuration to use from the Hardware version
number.</nowiki>

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

<nowiki> 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.</nowiki>

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

<nowiki> 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</nowiki>

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

<nowiki> 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</nowiki>

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

<nowiki> 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</nowiki>

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

<nowiki> 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</nowiki>

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

<nowiki> 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</nowiki>

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

<nowiki> 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.</nowiki>

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

<nowiki> 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</nowiki>

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

<nowiki> 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 CALLOS 15 to check
when all the sensors have been checked.</nowiki>

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

<nowiki> 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</nowiki>

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

<nowiki> 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
Note :</nowiki>

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

<nowiki> 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
Note :</nowiki>

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

<nowiki> 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
Note :</nowiki>

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

<nowiki> 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
Note :</nowiki>

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

<nowiki> 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.</nowiki>

== 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 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 isnXt 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 infact. 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 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 ====

===== Function: 0 =====
Purpose: Nothing
<nowiki> Entry : A = 0
X, Y, c, z = undefined
Exit : Leave everything as it is and exit straight away
Note : Used for claimed calls</nowiki>

===== Function: 1 =====
Purpose: NameCode request
<nowiki> 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
Note :</nowiki>

===== Function: 2 =====
Purpose: CodeName request
<nowiki> 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 Code not recognised then
A = 2
X, Y, c, z = undefined
Note :</nowiki>

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

==== unknownjob_vec ====
Purpose: To pass on unknown JobCalls to the correct owner
<nowiki> Entry : A = enviroment (0 = internal call, 1 = serial call)
Y = JobCode
X = JOB ID of owner
c, z = undefined
Exit : if jobcode yours then
if wrong enviroment then
A = 1
Y = 0
X, c, z = undefined
if right enviroment then
perform function
A = 0
Y = 0
X, c, z = undefined
if jobcode not yours then
pass on with registers unaltered
Note :</nowiki>

== Starting Up ==

The setup procedure for setting up extension job calls is to:

# Claim the number of JobCodes you want
#: if success:
# patch the internal_vec and unknownjob_vec vectors
# move LOMEM up to protect your program
# do anything else for initial startup you may want to do
# return back, ready and waiting

This in code looks like:

<nowiki>execute
LDX #no_of_calls ; Number of JobCodes wanted
LDA #1 ; CALLOS, function 1, Claim JobCodes
JSR OS_CALLOS ; Call CALLOS
CPX #0 ; Check we were given some codes
BEQ noinstall ; No, don't bother installing ourself
STX call ; Store base address of JobCodes allocated
STY job_id ; Store JOB ID given

LDA internal_vec ; Get old internal_vec (LSB)
STA ovec ; Store it
LDA internal_vec+1 ; Get old internal_vec (MSB)
STA ovec+1 ; Store it
LDA #>internal_handle ; Our internal handler (LSB)
STA internal_vec ; Place it in the vector (LSB)
LDA #<internal_handle ; Our internal handler (MSB)
STA internal_vec+1 ; Place it in the vector (MSB)

LDA unknownjob_vec ; Get old unknownjob_vec (LSB)
STA ovec2 ; Store it
LDA unknownjob_vec+1 ; Get old unknownjob_vec (MSB)
STA ovec2+1 ; Store it
LDA #>job_handle ; Our unknown job handler (LSB)
STA unknownjob_vec ; Place it in the vector (LSB)
LDA #<job_handle ; Our unknown job handler (MSB)
STA unknownjob_vec+1 ; Place it in the vector (MSB)

LDX #>WriteLomem ; Point to JobName
LDY #<WriteLomem
JSR findjob ; Find WriteLomem code
BEQ noinstall ; Doesn't exist !
LDX #>end_of_code ; End of code (LSB)
LDY #<end_of_code ; End of code (MSB)
STX jobin_buf ; Place it in jobin_buf (LSB)
STY jobin_buf+1 ; Place it in jobin_buf+1 (MSB)
JSR OS_DECODEJOB ; Call JobCall handler

noinstall
RTS ; End - return to OS

findjob
STX zero.gp1 ; Zero page
STY zero.gp1+
LDY #0
findthisjoblo
LDA (zero.gp1),Y
STA jobin.buf,Y ; Store name in jobin_buf
INY
CMP #13
BNE findthisjoblo
LDA #3 ; NameCode
JSR OS.DECODEJOB ; Call NameCode
LDA jobout.buf ; Get returned value
RTS

WriteLomem STR "WriteLomem"</nowiki>

This will setup the various vectors and memory pointers for the
applicaion, the actual routines (internal_handle and job_handle) are fairly
straight forward and simple:

<nowiki>internal_handle
CMP #1 : Is it function call 1 (NameCode) ?
BNE internal_handle_2 ; No, check for function 2
LDA job_id ; Get our JOB ID number
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #>job_names ; Our Job name table (LSB)
LDY #<job_names ; Our Job name table (MSB)
LDA #2 ; CALLOS function 2
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes : Found, go off and claim call
LDA #1 ; Not found, restore A
JMP (ovec) ; Call back to old vector

internal_handle_2
CMP #2 ; Is it function call 2 (CodeName) ?
BNE internal_handle_3 ; No, unknown, pass on
LDA job_id ; Get our JOB ID
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #>job_names ; Our Job name table (LSB)
LDY #<job_names ; Our Job name table (MSB)
LDA #3 ; CALLOS function 3
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes ; Found, go off and claim call
LDA #2 ; Not found, restore A
JMP (ovec) ; Call back to old vector

internal_yes
LDA #0 ; We want to claim call for some reason

internal_handle_3
JMP (ovec) ; Call back to old vector

job_handle
PHA ; Mark sure to preserve A
CPY call ; Check call wanted against base of ours
BCC job_handle_no ; Less than our base, so definately not ours
TYA
SBC #no_of_calls ; Subtract number of calls we have
CMP call ; Now compare with base
BCC job_handle2 ; Yes, one of ours

job_handle.no
PLA ; Restore A
JMP (ovec2) ; Call back to old vector

job_handle2
TYA
SEC
SBC call ; Subtract our base from call
ASL A ; Times by 2 for offset into table
TAY ; Place in Y
LDA job_run_table,Y ; Get LSB of routine
STA zero_gp1 ; Store it for indirect jump (LSB)
LDA job_run_table+1,Y ; Get MSB of routine
STA zero_gp1+1 ; Store it for indirect jump (MSB)
PLA ; Restore A
JMP (zero_gp1) ; Call our relevant routine

job_names ; List of our JobNames
STR "TestJob" ; Test job name
DFB &FF ; &FF - marks end of table

job_run_table ; List of routine addresses to match Jobs
DFW job_TestJob ; Test job routine</nowiki>

== Relocation ==

The relocation method used will not do a complete relocation, ie.
from ANY address to ANY address. The only constraint on the addresses is
that they must be the same offset in the page, which means, &2602 and &3402
is alright but &2602 and &3455 is not, ie. the difference between the two
addresses must be a multiple of 256 bytes, as only the MSB is altered, this
should not cause any real problems. What is meant by the two addresses is
the address the code was originally assembled at and the address it wants
relocating to. Because of this programs must be multiples of 256 bytes, ie.
the low byte of LOMEM must ALWAYS be 0, your program should be padded out.

The relocation mechanism works by having a table, and to each byte
of code there is one BIT, if unset it means the byte of code should not be
relocated, else it should be, thus the BitMap table is 8 times smaller than
the code. To generate the BitMap you have to assemble the code at two
different places, and compare both sets of assembled code against each
other, the differences are where the code is to be relocated. The code
which is sent up to the controller is assumed to be assembled at address
&100, so the first code should be assembled at &100, the other one should be
assembled at another address, say &600, and the first one be sent up with
the BitMap. A program is availble for the Elk/Beeb/Arc with 65Tube/Mac with
BBC BASIC to compare the two files and create the BitMap.

All the program has to do to relocate itself is execute this bit of
code first of all: (address is the base address of the program, ie. &100
for the downloaded version)

<nowiki>execcall
LDA #>(execute-address) ; Final execution address offset (LSB)
STA zero_gp1
LDA #<(execute-address) ; Final execution address offset (MSB)
STA zero_gp1+1

LDA #>(BitMap-address) ; BitMap address offset (LSB)
STA zero_gp2
LDA #<(BitMap-address) ; BitMap address offset (MSB)
STA zero_gp2+1

LDA #>(execcall-address); Length of data to relocate (LSB)
STA zero_gp3
LDA #<(execcall-address); Length of data to relocate (MSB)
STA zero_gp3+1

TXA ; Execcall REAL address
SEC
SBC #>(execcall-address); Subrtract length
TAX ; Put it back in X
TYA ; Ditto for MSB
SBC #<(execcall-address)
TAY
LDA #4 ; CALLOS function for Relocate
JMP OS_CALLOS ; Call CALLOS

BitMap ; BitMap start</nowiki>

This will relocate the code and automatically call the execution
address, which should be the initialisation code (ie. setup internal_vec
and unknownjob_vec etc.). "address" is the address the code is started to
assemble at, &100 for the version to be uploaded. The upload routine should
pass in X and Y (via ExecuteCode) the address of the start of execcall, this
means that the routine can tell where it is in memory, subtracting the
length gives the start of the code to relocate.

== Layout Summary ==

The layout of a full application should be like this by now:

<nowiki> start of code
program job codes, data etc.
internal handler
job handler
end of code
initialisation (setup internal etc.)
end of code to be relocated
execution (relocation)
relocation BitMap</nowiki>

Because of memory space the initialisation code should be placed
outside the reserved memory limit of the program, as it is only called once
and not needed again.

== Other miscellaneous calls ==

<nowiki>Call : OS_PRINTER
Purpose : To place a character in the printer buffer
Entry : A = character to send
X, Y, c, z = undefined
Exit : A, X, Y is preserved
if c = 0 (printed)
The printer is on and the character was inserted
if c = 1 (not printed)
The printer is off and the character was forgotten
z = undefined
Note : The character goes into the printer buffer and will be
actually sent to the printer when the printer asks for it. If the printer
was not awake to begin with, an attempt is made to wake it up, thus
meaning that in some circumstances when the printer wasn't ready a
character may be lost, this cannot be helped. If the printer is off (via
the BCD switch) then the character will be forgotten as the Printer Buffer
is inactive.</nowiki>

The module is located at &8000 in memory, and should be a EPROM placed
in the second ROM socket in the controller (ie. the top RAM socket). This
module is primary designed to turn the Controller into a dedicated task,
making it perform some function from switch on. It could also be used to
add more permant JobCalls to the Controller, in the process taking up much
less RAM), but because of there being only one Module present this feature
is limited, and is much more suited to a collection of the user's own
personal routines.

For the OS to recognise a module as being in place the text "Module" is
looked for, the layout of a module should be like this (starting at
&8000):

<nowiki>Offset value comment
0 "Module" The OS checks for this string
6 0 End of check string
7 Language entry Address of 'Language' entry
9 Service entry Address of 'Service' entry
11 "<Module Title>" Module title
0 End of Module title

"<Module part>" Part Module Title
0 End of Part Module Title
"x.xx" Part version number

&FF End of parts list</nowiki>

The language entry is a 2 byte value holding the address of the language
entry routine, this is called on reset, if the BCD is set correctly. A
value of less than &8000 means there is no valid language entry and any
language calls are ignored. If a RTS is made the OS carries on as it would
have if there wasn't a language call.

The service entry is a 2 byte value holding the address of the service
entry routine, this is called at various appropiate moments with service
numbers in A. A list of current calls is thus:

<nowiki> 0 - Not used
1 - Unknown Job Code
2 - Centisecond call
3 - Irq2 (unknown IRQ)
4 - internal_vec call (exit with A=0 to claim)
254 - RESET
255 - BRK</nowiki>

On exit all registers and flags should be preserved. For call 1 the
unknown job value is held in the Y register, the enviroment is held in the
X register, on exit, X should contain the flag, as A does from the exit of
unknownjob_vec. For the rest of calls, X and Y are undefined.

For both Service and Language entry points, a value of 0 means "there is
no valid routine" and the module isn't called for that type of entry.

Finally a full implementation of a JobCall, from start to finish.

<nowiki> DIM data% &1000
:
no_of_calls = 1
:
VIA = &E030
ACIA = &E010
ADC = &E000
AUX_PORT = &E020
brk_vec = &200
nmi_vec = &202
irq_vec = &204
irq2_vec = &206
sendserial_vec = &208
readserial_vec = &20A
sendjob_vec = &20C
readjob_vec = &20E
decodejob_vec = &210
unknownjob_vec = &212
extjob_vec = &214
centisec_vec = &216
internal_vec = &218
callos_vec = &21A
printer_vec = &21C
zero_gp1 = 0
zero_gp2 = 2
zero_gp3 = 4
zero_gp4 = 6
zero_gp5 = 8
zero_gp6 = 10
zero_gp7 = 12
zero_gp8 = 14
zero_gp9 = 16
zero_gp10 = 18
user_reserved = &70
irq_A = &A0
fcount = &A1
RAM_size = &A3
jobout_buf = &400
jobin_buf = &480
OS_PRINTER = &FFB9
OS_CALLOS = &FFBC
OS_SENDBYTE = &FFBF
OS_READBYTE = &FFC2
OS_SENDJOB = &FFC5
OS_READJOB = &FFC8
OS_DECODEJOB = &FFCB
:
FOR create=1 TO 2
:
FOR pass%=4 TO 7 STEP 3
P%=&100*create : O%=data%
[OPT pass%
:
.job_DemoJob
CMP #1
BEQ DemoJob_go
LDA #1
LDY #0
RTS
/
.DemoJob_go

:
.internal_handle
CMP #1 ; Is it function call 1 (NameCode) ?
BNE internal_handle_2 ; No, check for function 2
/
LDA job_id ; Get our JOB ID number
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #job_names MOD 256 ; Our Job name table (LSB)
LDY #job_names DIV 256 ; Our Job name table (MSB)
LDA #2 ; CALLOS function 2
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes ; Found, go off and claim call
LDA #1 ; Not found, restore A
JMP (ovec) ; Call back to old vector
/
.internal_handle_2
CMP #2 ; Is it function call 2 (CodeName) ?
BNE internal_handle_3 ; No, unknown, pass on
/
LDA job_id ; Get our JOB ID
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #job_names MOD 256 ; Our Job name table (LSB)
LDY #job_names DIV 256 ; Our Job name table (MSB)
LDA #3 ; CALLOS function 3
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes ; Found, go off and claim call
LDA #2 ; Not found, restore A
JMP (ovec) ; Call back to old vector
/
.internal_yes
LDA #0 ; We want to claim call for some reason
/
.internal_handle_3
JMP (ovec) ; Call back to old vector
:
.job_handle
PHA ; Make sure to preserve A
CPY call ; Check call wanted against base of ours
BCC job_handle_no ; Less than our base, so definately not ours
TYA
SBC #no_of_calls ; Subtract number of calls we have
CMP call ; Now compare with base
BCC job_handle2 ; Yes, one of ours
/
.job_handle.no
PLA ; Restore A
JMP (ovec2) ; Call back to old vector
/
.job_handle2
TYA
SEC
SBC call ; Subtract our base from call
ASL A ; Times by 2 for offset into table
TAY ; Place in Y
LDA job_run_table,Y ; Get LSB of routine
STA zero_gp1 ; Store it for indirect jump (LSB)
LDA job_run_table+1,Y ; Get MSB of routine
STA zero_gp1+1 ; Store it for indirect jump (MSB)
PLA ; Restore A
JMP (zero_gp1) ; Call our relevant routine
:
.job_names ; List of our JobNames
EQUS "DemoJob":EQUB 13 ; Test job name
/
EQUB &FF ; &FF - marks end of table
:
.job_run_table ; List of routine addresses to match Jobs
EQUW job_DemoJob ; Test job routine
:
.call : EQUB 0 ; Store for our JobCode base
.job_id : EQUB 0 ; Store for our JobId
.ovec : EQUW 0 ; Store for old internal_vec value
.ovec2 : EQUW 0 ; Store for old unknownjob_vec value
:
EQUS STRING$(&100-(P% MOD 256),CHR$0)
.end_of_code ; end_of_code should be on page boundry
:
.execute
LDX #no_of_calls ; Number of JobCodes wanted
LDA #1 ; CALLOS, function 1, Claim JobCodes
JSR OS_CALLOS ; Call CALLOS
STX call ; Store base address of JobCodes allocated
STY job_id ; Store JOB ID given
CPX #0 ; Check we were given some codes
BEQ noinstall ; No, don't bother installing ourself
/
LDA internal_vec ; Get old internal_vec (LSB)
STA ovec ; Store it
LDA internal_vec+1 ; Get old internal_vec (MSB)
STA ovec+1 ; Store it
LDA #internal_handle MOD 256 ; Our internal handler (LSB)
STA internal_vec ; Place it in the vector (LSB)
LDA #internal_handle DIV 256 ; Our internal handler (MSB)
STA internal_vec+1 ; Place it in the vector (MSB)
/
LDA unknownjob_vec ; Get old unknownjob_vec (LSB)
STA ovec2 ; Store it
LDA unknownjob_vec+1 ; Get old unknownjob_vec (MSB)
STA ovec2+1 ; Store it
LDA #job_handle MOD 256 ; Our unknown job handler (LSB)
STA unknownjob_vec ; Place it in the vector (LSB)
LDA #job_handle DIV 256 ; Our unknown job handler (MSB)
STA unknownjob_vec+1 ; Place it in the vector (MSB)
/
LDX #end_of_code MOD 256 ; End of code (LSB)
LDY #end_of_code DIV 256 ; End of code (MSB)
STX jobin_buf ; Place it in jobin_buf (LSB)
STY jobin_buf+1 ; Place it in jobin_buf+1 (MSB)
LDA #65 ; JobCode for WriteLomem
JSR OS_DECODEJOB ; Call JobCall handler
/
.noinstall
RTS ; End - return to OS
:
.execcall
LDA #>(execute-address) ; Final execution address offset (LSB)
STA zero_gp1
LDA #<(execute-address) ; Final execution address offset (MSB)
STA zero_gp1+1
/
LDA #>(BitMap-address) ; BitMap address offset (LSB)
STA zero_gp2
LDA #<(BitMap-address) ; BitMap address offset (MSB)
STA zero_gp2+1
/
LDA #>(execcall-address) ; Length of data to relocate (LSB)
STA zero_gp3
LDA #<(execcall-address) ; Length of data to relocate (MSB)
STA zero_gp3+1
/
TXA ; Execcall REAL address
SEC
SBC #>(execcall-address) ; Subrtract length
TAX ; Put it back in X
TYA ; Ditto for MSB
SBC #<(execcall-address)
TAY
LDA #4 ; CALLOS function for Relocate
JMP OS_CALLOS ; Call CALLOS
/
.BitMap ; BitMap start
:
]
NEXT
:
OSCLI "SAVE code"+STR$create+" "+STR$~data%+" "+STR$~O%
:
NEXT</nowiki>

== Changelog ==

<nowiki>bob 071 Fixed MotorForward bug (%10)
bob 072 CallOS 14 now checks current adc.owner status
jim 072.d1 * Rewrite for new hardware/processor *
jim 072.d1 Moved vectors/workspace to &440
jim 072.d1 Moved rs.inp.buf to &500
jim 072.d1 Moved jobout.buf to &600
jim 072.d1 Moved jobin.buf to &680
jim 072.d1 Moved jobs.status to &700
jim 072.d1 Added irq.X (&A4)
jim 072.d1 Added irq.Y (&A5)
jim 072.d1 Removed short detection code
jim 072.d1 Voided CallOS' 6,7,8,9,10,11,13,16,17,18,19
jim 072.d1 Removed JobCalls ReadADCReg,WriteADCReg
jim 072.d1 Removed JobCalls ReadACIAReg,WriteACIAReg
jim 072.d1 Removed JobCalls ReadVIAReg,WriteVIAReg,SetVIAHigh,SetVIALow
jim 072.d1 Added CallOS 21 Write Outputs
jim 072.d1 Added CallOS 22 Read Outputs added
jim 072.d1 Added CallOS 23 Read Inputs added
jim 072.d1 Added CallOS 24 Write Motors
jim 072.d1 Added CallOS 25 Read Motors
jim 072.d1 Added CallOS 26 Read Keypad
jim 072.d1 Expanded CallOS 5 information
jim 072.d1 Added JobCall IdentSystem to return CallOS 5 info
jim 072.d1 JobCalls now use appropriate CallOS'
jim 072.d1 OS.READBYTE no longer preserves A on CS
jim 072.d1 irq.vec,irq2.vec,nmi.vec now redundant
jim 072.d1 Renamed JobCall DownloadData to DownloadData38
jim 072.d1 Renamed JobCall UploadData to UploadData38
jim 072.d1 Renamed JobCall ExecuteCode to ExecuteCode38
jim 072.d1 Renamed JobCall ReadByte to ReadByte38
jim 072.d1 Renamed JobCall StoreByte to StoreByte38
jim 072.d1 JobCall ForcedADCRead now checks adc.owner first
jim 072.d3 Added CallOS 27 Write printer
jim 072.d3 Added CallOS 28 Read printer
jim 072.d3 Added CallOS 29 Write RTC Reg
jim 072.d3 Added CallOS 30 Read RTC Reg
jim 072.d3 Added CallOS 31 Write RTC string
jim 072.d3 Added CallOS 32 Read RTC string
jim 072.d3 Added CallOS 33 Write RTC bcd
jim 072.d3 Added CallOS 34 Read RTC bcd
jim 072.d3 Added CallOS 35 Write LCD Reg
jim 072.d3 Added CallOS 36 Read LCD Reg
jim 072.d3 Added JobCall WritePrinter
jim 072.d3 Added JobCall ReadPrinter
jim 072.d3 Added JobCall PrintChar
jim 072.d3 Added JobCall PrintStreamZ
jim 072.d3 Added JobCall PrintStream
jim 072.d3 Added JobCall PrintServer
jim 072.d3 Added JobCall WriteRTCReg
jim 072.d3 Added JobCall ReadRTCReg
jim 072.d3 Added JobCall WriteRTC
jim 072.d3 Added JobCall ReadRTC
jim 072.d3 Added JobCall WriteRTCbcd
jim 072.d3 Added JobCall ReadRTCbcd
jim 072.d3 Added JobCall WriteLCDReg
jim 072.d3 Added JobCall ReadLCDReg
jim 072.d3 Added CallOS 37 Write Power ctrl
jim 072.d3 Added CallOS 38 Read Power ctrl
jim 072.d3 Implemented OS.PRINTER
jim 072.d3 Added JobCall PatchMF (MotorForward)
jim 072.d3 Changed irq.vec to int0.vec
jim 072.d3 Changed irq2.vec to int1.vec
jim 072.d3 Added int2irq.vec (wrksp+&20)
jim 072.d3 Added int3irq.vec (wrksp+&22)
jim 072.d3 Added int4irq.vec (wrksp+&24)
jim 072.d3 Added c0irq.vec (wrksp+&26)
jim 072.d3 Added c1irq.vec (wrksp+&28)
jim 072.d3 Added t1irq.vec (wrksp+&2A)
jim 072.d3 Added t2irq.vec (wrksp+&2C)
jim 072.d3 Added txirq.vec (wrksp+&2E)
jim 072.d3 Added tyirq.vec (wrksp+&30)
jim 072.d3 Added s1rirq.vec (wrksp+&32)
jim 072.d3 Added s1rirq.vec (wrksp+&34)
jim 072.d3 Added s2irq.vec (wrksp+&36)
jim 072.d3 Added adcirq.vec (wrksp+&38)
jim 072.d3 Renamed JobCall DownloadData38 to DownloadData740
jim 072.d3 Renamed JobCall UploadData38 to UploadData740
jim 072.d3 Renamed JobCall ExecuteCode38 to ExecuteCode740
jim 072.d3 Renamed JobCall ReadByte38 to ReadByte740
jim 072.d3 Renamed JobCall StoreByte38 to StoreByte740
jim 072.d4 Hardware update
jim 072.d4 Re-assigned CallOS 37 to Write Power/Charge control
jim 072.d4 Re-assigned CallOS 38 to Read Power/Charge control
jim 072.d4 Moved int2irq.vec to wrksp+&22
jim 072.d4 Moved int3irq.vec to wrksp+&24
jim 072.d4 Moved int4irq.vec to wrksp+&26
jim 072.d4 Moved c0irq.vec to wrksp+&28
jim 072.d4 Moved c1irq.vec to wrksp+&2A
jim 072.d4 Moved t1irq.vec to wrksp+&2C
jim 072.d4 Moved t2irq.vec to wrksp+&2E
jim 072.d4 Moved txirq.vec to wrksp+&30
jim 072.d4 Moved tyirq.vec to wrksp+&32
jim 072.d4 Moved s1rirq.vec to wrksp+&34
jim 072.d4 Moved s1rirq.vec to wrksp+&36
jim 072.d4 Moved s2irq.vec to wrksp+&38
jim 072.d4 Moved adcirq.vec to wrksp+&3A
jim 072.d4 Added OS.LCDVDU (&FFB7) and lcdvdu.vec (wrksp+&20)
jim 072.d5 Re-assigned CallOS 37 to Write/Read Power/Charge control
jim 072.d5 Re-assgined CallOS 38 Read Battery Voltage
jim 072.d5 OS.CALLOS now re-entrant
jim 072.d5 Fixed OS.PRINTER
jim 072.d5 Started to add internal logging software
jim 072.d5 Moved OS.LCDVDU to &FFB6
jim 072.d7 Added OS.PRINTERPOLL (&FFB3) and printerpoll.vec (wrksp+&3C)
bob 073 Matched jim & bob sensor lookup tables
bob 073 Added PatchMF
jim 072.dj Added OS.CALLOS 51 Read keypad press
jim 072.dj Added hard reset keypad press
jim 072.dk Added JobCall ReadOutputs
jim 072.do Changed soft reset of zero page locations
jim 072.do Changed MotorForward/Backward bitmaps
jim 072.dp Fixed OS.CALLOS WriteRTCbcd
jim 072.dq Fixed OS.CALLOS ReadRTCstring for correct 24hr operation
jim 072.dr Changed reset prompts
bob 074 Added support for Little Bob
jim 072.dy Added further RTC/CMOS support
jim 072.dB Removed double hard reset
jim 072.dE Set _cpu.mode depending on external memory requirement
jim 072.dF Added Insight code
jim 073 Sub-release
jim 074 Modification to LCD code - uses bsy flag all the time now
jim 074 Fixed OS.CALLOS 42 Write LCD Char Def
jim 074 Fixed OS.CALLOS 43 Read LCD Char Def
jim 075 Added simple battery charge code
jim 075 Fixed JobCall ReadSensorTable
jim 075 Fixed OS.CALLOS 42 Write LCD Char Def
jim 075 Fixed OS.CALLOS 43 Read LCD Char Def
jim 075 Added sleep code
jim 075 Added OS.CALLOS 52 Write Sleep Time
jim 075 Added OS.CALLOS 53 Read Sleep Time
jim 075 Modified battery charge code
jim 076 Modified JobCall ReadSensorTable
jim 076 Modified OS.CALLOS 26 ReadKeypad to do debounce
jim 077 Rewrote battery charging code
jim 077.2 Reduced stop charge threshold to 2
jim 077.3 Increased stop charge threshold to 3
jim 077.3 Added battery voltage averaging
bill 077 Stripped
bill 077 Moved ins to out port
bill 077 Added RTS
bill 077 Changed sensor ID system back to original, using p2.1
bill 077 Dedicated USB/RS selection line, RTS provisioned on p2.3
bill 077 Overload "bounce" timing
bill 078 CTS added
bill 079 Temperature fudge</nowiki>

SmartBox OS

2023-11-04T08:46:19Z

Benryves: /* Vectors */ Put vector list into a table

== Documentation for SmartBox OS 2.066 ==

The term JobCall is the concept of the routine itself, as opposed to
JobName (which is the actual name associated with it (eg. NameCode)) and
JobCode (which is the actual number associated with it (eg. 3)).

The term controller means the SmartBox, or any other incarnation
which may appear in future time !

The term OS means the controllers' Operating System.

== Preview ==

There are a number of reasons why using Machine Code on the
controller is more desirable than using the various JobCalls via the serial
link. One reason is speed, if the task which needs to be performed, has to
be performed very quickly (more quickly than can be achieved via the serial
link at least), then some code must be written to work in the controller
itself to achieve this sort of speed. If the task required is to be a
"background" task (ie. a task which may happen while other "things" carry
on as normal, like a change of state of a particular port) then it is far
easier to let the controller do all the work, maybe under interupts, than
continuously poll the controller checking the state of various things.
Another reason may be that you would like to add another JobCall to the OS,
extending the calls available to external applications (and the user at the
same time), without the user having to write the code himself to achieve the
aim. For advanced users, there is also the ablity to alter the way the OS
does various things and to have the controller in their "power", for
dedicated tasks etc.

One advantage of writing IN the controller is that that "function"
is available to any computer using the serial link, and is thus not fixed to
one computer type or even a computer at all, where the controller is used
free running, doing a particular task which doesn't need the intervention of
the user's own computer.

== Call types ==

There are three different types of machine code routines which can
be added to the controller. Each one is suited to a more advanced level
than the other, which also relates to the amount of work needed to actually
get the routine working ! The three levels are such:

=== Simple stand alone routine ===

Here the routine is just the routine
itself with no supporting code (ie. code to integrate with the rest of the
OS). It has to be called directly, by use of the ExecuteCode JobCall, thus
it usually resides at a fixed address and obviously does not offer the user
friendly way of accessing itself like there is with normal OS calls.

=== Extended JobCall ===

There is one JobCall in the OS (ExtendJob)
which can call various routines residing in memory, each one is identified
by a 8 bit number. The disadvantages of this way is that the call hasn't
got it's own JobName/JobCode and needs the extra byte to identify itself.
This is ideal for the quick routine which the user would like to add for
himself without having to resort to the extra code needed for the full
JobCode implementation.

=== Full JobCall ===

This is where the routine can define itself one
(or a number) of JobNames/JobCodes, it can integrate itself into an
extension of the OS in a complete way. The disadvantage is that extra
coding is needed to deal with the various OS calls it has to service and
that extra work is needed to produce a suitable file to place in the
controller.

Normally with most processors, including the 65c02, the machine code
produced is produced for a fixed memory address, and it cannot be made to
run in a different place in memory unless extra work is carried out by the
user, or at least a combination of the user and the OS. For the controller
this is a very severe disadvantage as most extensions are downloaded as
"modules" and to optimise memory a system has to be devised to enable
routines to be placed anywhere in memory, thus allowing no memory to be
wasted. In the OS there is a routine to do just this, though it does need
some help. A special version of the users code has to be developed, or
rather it has to be "processed" to add extra information on the end. Extra
code is needed to set up a few pointers and call the OS routine to relocate.
See later.

== Memory ==

The first 256 bytes of memory are somewhat special, most zero page
locations are reserved for use by the OS:

{|class="wikitable"
|-
|&00-&14||General workspace, used to pass parameters to some OS routines, can also be used by other routines DURING their execution.
|-
|&15-&6F||Reserved
|-
|&70-&9F||Available to the user
|-
|&A0||Accumulator store for irqs (irq_A)
|-
|&A1-&A2||Two byte counter, decremented at 100hz, useful for temporary timing purposes (fcount)
|-
|&A3||RAM size, high byte of RAM size of machine, ie. for 32k this will be &80 (RAM_size)
|-
|&A4-&AF||Reserved
|-
|&B0-&FF||Used by the OS
|-
|}

The rest of memory space is used for the processors stack, OS'
buffers, tables, vectors and, of course, the user available memory.

A breakdown of the rest of memory:

* &100 to &1FF is the 65c02's stack.
* &200-&2FF is used by the OS for various system functions and also contains the vector table, more on that later.
* &300-&3FF is the serial input buffer.
* &400-&47F is the internal job code call output buffer. (jobout_buf)
* &480-&4FF is the internal job code call input buffer. (jobin_buf)
* &500-&5FF is the job status table.
* &600 to the end of RAM memory is for the user. The user should not assume what the top of AVAILABLE memory is and use the system variable HIMEM.

In the controller the maximum limit of RAM is &8000 (which is 32k),
from &8000-&DFFF lies the memory mapped hardware, from &E000 to &FFF9 lies
the OS and from &FFFA to &FFFF lies the 65c02 vectors.

So the user has his own limits of free memory. The lowest limit is
called LOMEM and the highest limit is called HIMEM, everything between these
boundaries is termed "available" for use by anyone, the user or the OS.

Anyone can also claim memory, thus making private to them and not allowing
anyone else to use it. You do this by altering the value of LOMEM, HIMEM
should not be moved. Of course anyone claiming memory should first check
that there is enough memory available for the amount they want to claim for.
To take a common example, a downloadable routine which installs itself as a
extension routine, The download routine will first of all read LOMEM, read
HIMEM, check there is enough memory for the routine, download it to LOMEM
and call it, the downloaded routine will then relocate itself and alter
LOMEM so it is protected.

There is one other memory limit, this is called TOPMEM, this is the
absolute top limit of RAM, HIMEM will normally equal TOPMEM, but a future OS
may alter HIMEM to below TOPMEM. TOPMEM should be ignored ideally, and
HIMEM used.

== OS Calls ==

The OS has calls (ie. a jump instruction which you call, which
then calls, via a RAM vector, a routine in the OS) setup near the top of
memory, through these calls you do everything associated with the
controller. The calls are are such:

* OS_PRINTER at address &FFB9
* OS_CALLOS at address &FFBC
* OS_SENDBYTE at address &FFBF
* OS_READBYTE at address &FFC2
* OS_SENDJOB at address &FFC5
* OS_READJOB at address &FFC8
* OS_DECODEJOB at address &FFCB

The address is the one to call for the particular routine.

* OS_PRINTER is reserved for future use.
* OS_CALLOS calls upon the OS to do various things internally.
* OS_SENDBYTE sends a byte out of the serial port.
* OS_READBYTE reads a byte from the serial port.
* OS_SENDJOB 'sends' a value to the JobCall caller.
* OS_READJOB 'reads' a value from the JobCalls caller.
* OS_DECODEJOB decodes the Job number held in A and acts on it.

Note none of these things should be used in interupt routines,
except OS_CALLOS, of any sort, except if YOU know what state the machine is
in and WHY.

=== Serial Port ===

The serial port on the controller is currently based on the 6850
UART, this need not bother you as the OS deals with the thing entirely by
itself. The chip is setup by the OS to always have a word format of 8n1 and
a baud rate of 9600, this translates to 960cps. The 6850 has two divide
rates for the baud rate, the OS only uses one, using the other one is beyond
the scope of this document and shouldn't be neccessary to use.

Only receive interupts are used, transmission of characters is done
on a polled basis.

As said, there are two calls OS_READBYTE and OS_SENDBYTE.
OS_READBYTE tests the serial input buffer and returns the character (if any
in the A register), the c flag states whether there was a character
returned.

<nowiki> Call : OS_READBYTE
Entry : A, X, Y, c, z = undefined
Exit : X, Y preserved
z = undefined
if c = 1 (no character received)
A is preserved
if c = 0 (character received)
A = character received</nowiki>

OS_SENDBYTE sends the character in the A register out of the serial
port, taking into consideration flow control etc.

<nowiki> Call : OS_SENDBYTE
Entry : A = character to send
X, Y, c, z = undefined
Exit : A, X, Y, c is preserved
z = undefined</nowiki>

=== OS_READJOB and OS_SENDJOB ===

To send/receive data from the user (either internally or via the
serial port) you call OS_SENDJOB/OS_READJOB for the next byte. If your
JobCall requires dynamic use of data, ie. interaction, then a check of the
enviroment should be done to check the call came from the serial port. One
example of this is the OS JobCall MultipleServer, which requires dynamic use
of sending a stream of data until a reaction from the user to tell it to
stop.

<nowiki> Call : OS_READJOB
Purpose: To read job value from the user
Entry : A, X, Y, c, z = undefined
Exit : A = byte read
X, Y is preserved
c, z = undefined
Note : When coming from the serial port it waits for a character to be
received, if you are doing a serial only call and wish to have a loop
checking for a character from the user while doing "your own thing", then
OS_READBYTE should be used. For internal calls this reads data out of
jobin_buf.</nowiki>

<nowiki> Call : OS_SENDJOB
Purpose: To give a job value back to the user
Entry : A = byte to give
X, Y, c, z = undefined
Exit : A, X, Y is preserved
c, z = undefined
Note : This will send either out to the serial port or place a byte in
jobout_buf. For internal calls this stores the value in jobout_buf, which
is allocated 128 bytes, no bound checking is done so sending more than 128
bytes to OS_SENDJOB will cause corruption of some memory.</nowiki>

=== OS_DECODEJOB ===

JobCalls in practise are really only used by the user, JobCalls
tend not to call other calls at all, infact you shouldn't really call
another call unless you were called from the serial port. If you do need to
call another JobCall then you do it like this; with each call you have
associated with it a number, and the call might require some data or give
some data back or both. With the serial port this is simple, you just send
data down and receive data as it is produced. You can't do this with
internal calls, and some calls will not let you call them from inside the
controller, you HAVE to call them from outside. But for the ones which do
let you, you do it with two data blocks, one for input TO the call and one
for output FROM the call. These are setup in a position in memory
(jobin_buf and jobout_buf), each one has a maximum of 128 bytes and this
should not be overflowed (OS_READJOB and OS_SENDJOB do NOT do any bound
checking). So to start with you place in the input block the data you want
to give the call (if any), call it, and then act on the data in the output
block (if any). The OS call OS_DECODEJOB is the one which actually calls
the JobCall handler and eventually the actual routine, you tell the JobCall
handler which call you want by placing the JobCode in the A register.

So for OS_DECODEJOB:

<nowiki> Call : OS_DECODEJOB
Entry : A = JobCode
X, Y, c, z = undefined
jobin_buf should contain any input data
Exit : A = flag
X = number of bytes given back by routine
Y = undefined
c = status, if set JobCall does not exist
z = status, if set JobCall cannot be called internally
jobout_buf contains any data sent from routine</nowiki>

A typical example would be:

<nowiki> LDA #readhimem ; JobCode for ReadHimem
JSR OS_DECODEJOB ; Call the JobCall handler
LDX jobout_buf ; Read HIMEM from buffer LSB
LDY jobout_buf+1 ; Read HIMEM from buffer MSB
STX jobin_buf ; Place LSB in input buffer
STY jobin_buf+1 ; Place MSB in input buffer
LDA #writelomem ; JobCode for WriteLomem
JSR OS_DECODEJOB ; Call the JobCall handler</nowiki>

which would read HIMEM, and then write LOMEM to be the same value, leaving
no spare memory left.

The reason why you should not call an internal call from another
internal call is that the same buffers (jobin_buf and jobout_buf) would be
used for both calls, causing conflict between the two calls, or rather to
the originator of the primary call ! The only time it would be safe if is
if you have already got all the data you want from jobin_buf and haven't
placed any in the jobout_buf (it would be lost if you had done).

=== 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.

==== CALLOS : 0 ====
Purpose: Returns the OS version number
<nowiki> 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 </nowiki>

==== CALLOS : 1 ====
Purpose: To claim a block of JobCodes
<nowiki> 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.</nowiki>

==== CALLOS : 2 ====
Purpose: To handle NameCode request for the application.
<nowiki> 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</nowiki>

==== CALLOS : 3 ====
Purpose: To handle CodeName request for the application.
<nowiki> 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</nowiki>

==== CALLOS : 4 ====
Purpose: To relocate code
<nowiki> 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</nowiki>

==== CALLOS : 5 ====
Purpose: To "describe" the enviroment
<nowiki> 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 CALLOS
0 and decide what addresses/configuration to use from the Hardware version
number.</nowiki>

==== CALLOS : 6 ====
Purpose: To read a register in the VIA
<nowiki> 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.</nowiki>

==== CALLOS : 7 ====
Purpose: To write to a register in the VIA
<nowiki> 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</nowiki>

==== CALLOS : 8 ====
Purpose: To read a register in the ACIA
<nowiki> 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</nowiki>

==== CALLOS : 9 ====
Purpose: To write to a register in the ACIA
<nowiki> 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</nowiki>

==== CALLOS : 10 ====
Purpose: To read a register in the ADC
<nowiki> 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</nowiki>

==== CALLOS : 11 ====
Purpose: To write to a register in the ADC
<nowiki> 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</nowiki>

==== CALLOS : 12 ====
Purpose: To read a ADC channel
<nowiki> 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.</nowiki>

==== CALLOS : 13 ====
Purpose: To read a register in the AUX_PORT
<nowiki> 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</nowiki>

==== CALLOS : 14 (OS 2.066+) ====
Purpose: To start sensor type checking
<nowiki> 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 CALLOS 15 to check
when all the sensors have been checked.</nowiki>

==== CALLOS : 15 (OS 2.066+) ====
Purpose: To check the status of sensor checking
<nowiki> 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</nowiki>

==== CALLOS : 16 (OS 2.069+) ====
Purpose: To set the OS' irq mask for the VIA
<nowiki> 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
Note :</nowiki>

==== CALLOS : 17 (OS 2.069+) ====
Purpose: To set the OS' irq mask for the ACIA
<nowiki> 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
Note :</nowiki>

==== CALLOS : 18 (OS 2.069+) ====
Purpose: To set the OS' irq mask for the ADC
<nowiki> 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
Note :</nowiki>

==== CALLOS : 19 (OS 2.069+) ====
Purpose: To set the ACIA's ctrl register and OS' soft copy
<nowiki> 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
Note :</nowiki>

==== CALLOS : 20 (OS 2.069+) ====
Purpose: To set the reset vector for battery back RAM support
<nowiki> 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.</nowiki>

== 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 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 isnXt 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 infact. 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 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 ====

===== Function: 0 =====
Purpose: Nothing
<nowiki> Entry : A = 0
X, Y, c, z = undefined
Exit : Leave everything as it is and exit straight away
Note : Used for claimed calls</nowiki>

===== Function: 1 =====
Purpose: NameCode request
<nowiki> 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
Note :</nowiki>

===== Function: 2 =====
Purpose: CodeName request
<nowiki> 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 Code not recognised then
A = 2
X, Y, c, z = undefined
Note :</nowiki>

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

==== unknownjob_vec ====
Purpose: To pass on unknown JobCalls to the correct owner
<nowiki> Entry : A = enviroment (0 = internal call, 1 = serial call)
Y = JobCode
X = JOB ID of owner
c, z = undefined
Exit : if jobcode yours then
if wrong enviroment then
A = 1
Y = 0
X, c, z = undefined
if right enviroment then
perform function
A = 0
Y = 0
X, c, z = undefined
if jobcode not yours then
pass on with registers unaltered
Note :</nowiki>

== Starting Up ==

The setup procedure for setting up extension job calls is to:

# Claim the number of JobCodes you want
#: if success:
# patch the internal_vec and unknownjob_vec vectors
# move LOMEM up to protect your program
# do anything else for initial startup you may want to do
# return back, ready and waiting

This in code looks like:

<nowiki>execute
LDX #no_of_calls ; Number of JobCodes wanted
LDA #1 ; CALLOS, function 1, Claim JobCodes
JSR OS_CALLOS ; Call CALLOS
CPX #0 ; Check we were given some codes
BEQ noinstall ; No, don't bother installing ourself
STX call ; Store base address of JobCodes allocated
STY job_id ; Store JOB ID given

LDA internal_vec ; Get old internal_vec (LSB)
STA ovec ; Store it
LDA internal_vec+1 ; Get old internal_vec (MSB)
STA ovec+1 ; Store it
LDA #>internal_handle ; Our internal handler (LSB)
STA internal_vec ; Place it in the vector (LSB)
LDA #<internal_handle ; Our internal handler (MSB)
STA internal_vec+1 ; Place it in the vector (MSB)

LDA unknownjob_vec ; Get old unknownjob_vec (LSB)
STA ovec2 ; Store it
LDA unknownjob_vec+1 ; Get old unknownjob_vec (MSB)
STA ovec2+1 ; Store it
LDA #>job_handle ; Our unknown job handler (LSB)
STA unknownjob_vec ; Place it in the vector (LSB)
LDA #<job_handle ; Our unknown job handler (MSB)
STA unknownjob_vec+1 ; Place it in the vector (MSB)

LDX #>WriteLomem ; Point to JobName
LDY #<WriteLomem
JSR findjob ; Find WriteLomem code
BEQ noinstall ; Doesn't exist !
LDX #>end_of_code ; End of code (LSB)
LDY #<end_of_code ; End of code (MSB)
STX jobin_buf ; Place it in jobin_buf (LSB)
STY jobin_buf+1 ; Place it in jobin_buf+1 (MSB)
JSR OS_DECODEJOB ; Call JobCall handler

noinstall
RTS ; End - return to OS

findjob
STX zero.gp1 ; Zero page
STY zero.gp1+
LDY #0
findthisjoblo
LDA (zero.gp1),Y
STA jobin.buf,Y ; Store name in jobin_buf
INY
CMP #13
BNE findthisjoblo
LDA #3 ; NameCode
JSR OS.DECODEJOB ; Call NameCode
LDA jobout.buf ; Get returned value
RTS

WriteLomem STR "WriteLomem"</nowiki>

This will setup the various vectors and memory pointers for the
applicaion, the actual routines (internal_handle and job_handle) are fairly
straight forward and simple:

<nowiki>internal_handle
CMP #1 : Is it function call 1 (NameCode) ?
BNE internal_handle_2 ; No, check for function 2
LDA job_id ; Get our JOB ID number
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #>job_names ; Our Job name table (LSB)
LDY #<job_names ; Our Job name table (MSB)
LDA #2 ; CALLOS function 2
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes : Found, go off and claim call
LDA #1 ; Not found, restore A
JMP (ovec) ; Call back to old vector

internal_handle_2
CMP #2 ; Is it function call 2 (CodeName) ?
BNE internal_handle_3 ; No, unknown, pass on
LDA job_id ; Get our JOB ID
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #>job_names ; Our Job name table (LSB)
LDY #<job_names ; Our Job name table (MSB)
LDA #3 ; CALLOS function 3
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes ; Found, go off and claim call
LDA #2 ; Not found, restore A
JMP (ovec) ; Call back to old vector

internal_yes
LDA #0 ; We want to claim call for some reason

internal_handle_3
JMP (ovec) ; Call back to old vector

job_handle
PHA ; Mark sure to preserve A
CPY call ; Check call wanted against base of ours
BCC job_handle_no ; Less than our base, so definately not ours
TYA
SBC #no_of_calls ; Subtract number of calls we have
CMP call ; Now compare with base
BCC job_handle2 ; Yes, one of ours

job_handle.no
PLA ; Restore A
JMP (ovec2) ; Call back to old vector

job_handle2
TYA
SEC
SBC call ; Subtract our base from call
ASL A ; Times by 2 for offset into table
TAY ; Place in Y
LDA job_run_table,Y ; Get LSB of routine
STA zero_gp1 ; Store it for indirect jump (LSB)
LDA job_run_table+1,Y ; Get MSB of routine
STA zero_gp1+1 ; Store it for indirect jump (MSB)
PLA ; Restore A
JMP (zero_gp1) ; Call our relevant routine

job_names ; List of our JobNames
STR "TestJob" ; Test job name
DFB &FF ; &FF - marks end of table

job_run_table ; List of routine addresses to match Jobs
DFW job_TestJob ; Test job routine</nowiki>

== Relocation ==

The relocation method used will not do a complete relocation, ie.
from ANY address to ANY address. The only constraint on the addresses is
that they must be the same offset in the page, which means, &2602 and &3402
is alright but &2602 and &3455 is not, ie. the difference between the two
addresses must be a multiple of 256 bytes, as only the MSB is altered, this
should not cause any real problems. What is meant by the two addresses is
the address the code was originally assembled at and the address it wants
relocating to. Because of this programs must be multiples of 256 bytes, ie.
the low byte of LOMEM must ALWAYS be 0, your program should be padded out.

The relocation mechanism works by having a table, and to each byte
of code there is one BIT, if unset it means the byte of code should not be
relocated, else it should be, thus the BitMap table is 8 times smaller than
the code. To generate the BitMap you have to assemble the code at two
different places, and compare both sets of assembled code against each
other, the differences are where the code is to be relocated. The code
which is sent up to the controller is assumed to be assembled at address
&100, so the first code should be assembled at &100, the other one should be
assembled at another address, say &600, and the first one be sent up with
the BitMap. A program is availble for the Elk/Beeb/Arc with 65Tube/Mac with
BBC BASIC to compare the two files and create the BitMap.

All the program has to do to relocate itself is execute this bit of
code first of all: (address is the base address of the program, ie. &100
for the downloaded version)

<nowiki>execcall
LDA #>(execute-address) ; Final execution address offset (LSB)
STA zero_gp1
LDA #<(execute-address) ; Final execution address offset (MSB)
STA zero_gp1+1

LDA #>(BitMap-address) ; BitMap address offset (LSB)
STA zero_gp2
LDA #<(BitMap-address) ; BitMap address offset (MSB)
STA zero_gp2+1

LDA #>(execcall-address); Length of data to relocate (LSB)
STA zero_gp3
LDA #<(execcall-address); Length of data to relocate (MSB)
STA zero_gp3+1

TXA ; Execcall REAL address
SEC
SBC #>(execcall-address); Subrtract length
TAX ; Put it back in X
TYA ; Ditto for MSB
SBC #<(execcall-address)
TAY
LDA #4 ; CALLOS function for Relocate
JMP OS_CALLOS ; Call CALLOS

BitMap ; BitMap start</nowiki>

This will relocate the code and automatically call the execution
address, which should be the initialisation code (ie. setup internal_vec
and unknownjob_vec etc.). "address" is the address the code is started to
assemble at, &100 for the version to be uploaded. The upload routine should
pass in X and Y (via ExecuteCode) the address of the start of execcall, this
means that the routine can tell where it is in memory, subtracting the
length gives the start of the code to relocate.

== Layout Summary ==

The layout of a full application should be like this by now:

<nowiki> start of code
program job codes, data etc.
internal handler
job handler
end of code
initialisation (setup internal etc.)
end of code to be relocated
execution (relocation)
relocation BitMap</nowiki>

Because of memory space the initialisation code should be placed
outside the reserved memory limit of the program, as it is only called once
and not needed again.

== Other miscellaneous calls ==

<nowiki>Call : OS_PRINTER
Purpose : To place a character in the printer buffer
Entry : A = character to send
X, Y, c, z = undefined
Exit : A, X, Y is preserved
if c = 0 (printed)
The printer is on and the character was inserted
if c = 1 (not printed)
The printer is off and the character was forgotten
z = undefined
Note : The character goes into the printer buffer and will be
actually sent to the printer when the printer asks for it. If the printer
was not awake to begin with, an attempt is made to wake it up, thus
meaning that in some circumstances when the printer wasn't ready a
character may be lost, this cannot be helped. If the printer is off (via
the BCD switch) then the character will be forgotten as the Printer Buffer
is inactive.</nowiki>

The module is located at &8000 in memory, and should be a EPROM placed
in the second ROM socket in the controller (ie. the top RAM socket). This
module is primary designed to turn the Controller into a dedicated task,
making it perform some function from switch on. It could also be used to
add more permant JobCalls to the Controller, in the process taking up much
less RAM), but because of there being only one Module present this feature
is limited, and is much more suited to a collection of the user's own
personal routines.

For the OS to recognise a module as being in place the text "Module" is
looked for, the layout of a module should be like this (starting at
&8000):

<nowiki>Offset value comment
0 "Module" The OS checks for this string
6 0 End of check string
7 Language entry Address of 'Language' entry
9 Service entry Address of 'Service' entry
11 "<Module Title>" Module title
0 End of Module title

"<Module part>" Part Module Title
0 End of Part Module Title
"x.xx" Part version number

&FF End of parts list</nowiki>

The language entry is a 2 byte value holding the address of the language
entry routine, this is called on reset, if the BCD is set correctly. A
value of less than &8000 means there is no valid language entry and any
language calls are ignored. If a RTS is made the OS carries on as it would
have if there wasn't a language call.

The service entry is a 2 byte value holding the address of the service
entry routine, this is called at various appropiate moments with service
numbers in A. A list of current calls is thus:

<nowiki> 0 - Not used
1 - Unknown Job Code
2 - Centisecond call
3 - Irq2 (unknown IRQ)
4 - internal_vec call (exit with A=0 to claim)
254 - RESET
255 - BRK</nowiki>

On exit all registers and flags should be preserved. For call 1 the
unknown job value is held in the Y register, the enviroment is held in the
X register, on exit, X should contain the flag, as A does from the exit of
unknownjob_vec. For the rest of calls, X and Y are undefined.

For both Service and Language entry points, a value of 0 means "there is
no valid routine" and the module isn't called for that type of entry.

Finally a full implementation of a JobCall, from start to finish.

<nowiki> DIM data% &1000
:
no_of_calls = 1
:
VIA = &E030
ACIA = &E010
ADC = &E000
AUX_PORT = &E020
brk_vec = &200
nmi_vec = &202
irq_vec = &204
irq2_vec = &206
sendserial_vec = &208
readserial_vec = &20A
sendjob_vec = &20C
readjob_vec = &20E
decodejob_vec = &210
unknownjob_vec = &212
extjob_vec = &214
centisec_vec = &216
internal_vec = &218
callos_vec = &21A
printer_vec = &21C
zero_gp1 = 0
zero_gp2 = 2
zero_gp3 = 4
zero_gp4 = 6
zero_gp5 = 8
zero_gp6 = 10
zero_gp7 = 12
zero_gp8 = 14
zero_gp9 = 16
zero_gp10 = 18
user_reserved = &70
irq_A = &A0
fcount = &A1
RAM_size = &A3
jobout_buf = &400
jobin_buf = &480
OS_PRINTER = &FFB9
OS_CALLOS = &FFBC
OS_SENDBYTE = &FFBF
OS_READBYTE = &FFC2
OS_SENDJOB = &FFC5
OS_READJOB = &FFC8
OS_DECODEJOB = &FFCB
:
FOR create=1 TO 2
:
FOR pass%=4 TO 7 STEP 3
P%=&100*create : O%=data%
[OPT pass%
:
.job_DemoJob
CMP #1
BEQ DemoJob_go
LDA #1
LDY #0
RTS
/
.DemoJob_go

:
.internal_handle
CMP #1 ; Is it function call 1 (NameCode) ?
BNE internal_handle_2 ; No, check for function 2
/
LDA job_id ; Get our JOB ID number
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #job_names MOD 256 ; Our Job name table (LSB)
LDY #job_names DIV 256 ; Our Job name table (MSB)
LDA #2 ; CALLOS function 2
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes ; Found, go off and claim call
LDA #1 ; Not found, restore A
JMP (ovec) ; Call back to old vector
/
.internal_handle_2
CMP #2 ; Is it function call 2 (CodeName) ?
BNE internal_handle_3 ; No, unknown, pass on
/
LDA job_id ; Get our JOB ID
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #job_names MOD 256 ; Our Job name table (LSB)
LDY #job_names DIV 256 ; Our Job name table (MSB)
LDA #3 ; CALLOS function 3
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes ; Found, go off and claim call
LDA #2 ; Not found, restore A
JMP (ovec) ; Call back to old vector
/
.internal_yes
LDA #0 ; We want to claim call for some reason
/
.internal_handle_3
JMP (ovec) ; Call back to old vector
:
.job_handle
PHA ; Make sure to preserve A
CPY call ; Check call wanted against base of ours
BCC job_handle_no ; Less than our base, so definately not ours
TYA
SBC #no_of_calls ; Subtract number of calls we have
CMP call ; Now compare with base
BCC job_handle2 ; Yes, one of ours
/
.job_handle.no
PLA ; Restore A
JMP (ovec2) ; Call back to old vector
/
.job_handle2
TYA
SEC
SBC call ; Subtract our base from call
ASL A ; Times by 2 for offset into table
TAY ; Place in Y
LDA job_run_table,Y ; Get LSB of routine
STA zero_gp1 ; Store it for indirect jump (LSB)
LDA job_run_table+1,Y ; Get MSB of routine
STA zero_gp1+1 ; Store it for indirect jump (MSB)
PLA ; Restore A
JMP (zero_gp1) ; Call our relevant routine
:
.job_names ; List of our JobNames
EQUS "DemoJob":EQUB 13 ; Test job name
/
EQUB &FF ; &FF - marks end of table
:
.job_run_table ; List of routine addresses to match Jobs
EQUW job_DemoJob ; Test job routine
:
.call : EQUB 0 ; Store for our JobCode base
.job_id : EQUB 0 ; Store for our JobId
.ovec : EQUW 0 ; Store for old internal_vec value
.ovec2 : EQUW 0 ; Store for old unknownjob_vec value
:
EQUS STRING$(&100-(P% MOD 256),CHR$0)
.end_of_code ; end_of_code should be on page boundry
:
.execute
LDX #no_of_calls ; Number of JobCodes wanted
LDA #1 ; CALLOS, function 1, Claim JobCodes
JSR OS_CALLOS ; Call CALLOS
STX call ; Store base address of JobCodes allocated
STY job_id ; Store JOB ID given
CPX #0 ; Check we were given some codes
BEQ noinstall ; No, don't bother installing ourself
/
LDA internal_vec ; Get old internal_vec (LSB)
STA ovec ; Store it
LDA internal_vec+1 ; Get old internal_vec (MSB)
STA ovec+1 ; Store it
LDA #internal_handle MOD 256 ; Our internal handler (LSB)
STA internal_vec ; Place it in the vector (LSB)
LDA #internal_handle DIV 256 ; Our internal handler (MSB)
STA internal_vec+1 ; Place it in the vector (MSB)
/
LDA unknownjob_vec ; Get old unknownjob_vec (LSB)
STA ovec2 ; Store it
LDA unknownjob_vec+1 ; Get old unknownjob_vec (MSB)
STA ovec2+1 ; Store it
LDA #job_handle MOD 256 ; Our unknown job handler (LSB)
STA unknownjob_vec ; Place it in the vector (LSB)
LDA #job_handle DIV 256 ; Our unknown job handler (MSB)
STA unknownjob_vec+1 ; Place it in the vector (MSB)
/
LDX #end_of_code MOD 256 ; End of code (LSB)
LDY #end_of_code DIV 256 ; End of code (MSB)
STX jobin_buf ; Place it in jobin_buf (LSB)
STY jobin_buf+1 ; Place it in jobin_buf+1 (MSB)
LDA #65 ; JobCode for WriteLomem
JSR OS_DECODEJOB ; Call JobCall handler
/
.noinstall
RTS ; End - return to OS
:
.execcall
LDA #>(execute-address) ; Final execution address offset (LSB)
STA zero_gp1
LDA #<(execute-address) ; Final execution address offset (MSB)
STA zero_gp1+1
/
LDA #>(BitMap-address) ; BitMap address offset (LSB)
STA zero_gp2
LDA #<(BitMap-address) ; BitMap address offset (MSB)
STA zero_gp2+1
/
LDA #>(execcall-address) ; Length of data to relocate (LSB)
STA zero_gp3
LDA #<(execcall-address) ; Length of data to relocate (MSB)
STA zero_gp3+1
/
TXA ; Execcall REAL address
SEC
SBC #>(execcall-address) ; Subrtract length
TAX ; Put it back in X
TYA ; Ditto for MSB
SBC #<(execcall-address)
TAY
LDA #4 ; CALLOS function for Relocate
JMP OS_CALLOS ; Call CALLOS
/
.BitMap ; BitMap start
:
]
NEXT
:
OSCLI "SAVE code"+STR$create+" "+STR$~data%+" "+STR$~O%
:
NEXT</nowiki>

== Changelog ==

<nowiki>bob 071 Fixed MotorForward bug (%10)
bob 072 CallOS 14 now checks current adc.owner status
jim 072.d1 * Rewrite for new hardware/processor *
jim 072.d1 Moved vectors/workspace to &440
jim 072.d1 Moved rs.inp.buf to &500
jim 072.d1 Moved jobout.buf to &600
jim 072.d1 Moved jobin.buf to &680
jim 072.d1 Moved jobs.status to &700
jim 072.d1 Added irq.X (&A4)
jim 072.d1 Added irq.Y (&A5)
jim 072.d1 Removed short detection code
jim 072.d1 Voided CallOS' 6,7,8,9,10,11,13,16,17,18,19
jim 072.d1 Removed JobCalls ReadADCReg,WriteADCReg
jim 072.d1 Removed JobCalls ReadACIAReg,WriteACIAReg
jim 072.d1 Removed JobCalls ReadVIAReg,WriteVIAReg,SetVIAHigh,SetVIALow
jim 072.d1 Added CallOS 21 Write Outputs
jim 072.d1 Added CallOS 22 Read Outputs added
jim 072.d1 Added CallOS 23 Read Inputs added
jim 072.d1 Added CallOS 24 Write Motors
jim 072.d1 Added CallOS 25 Read Motors
jim 072.d1 Added CallOS 26 Read Keypad
jim 072.d1 Expanded CallOS 5 information
jim 072.d1 Added JobCall IdentSystem to return CallOS 5 info
jim 072.d1 JobCalls now use appropriate CallOS'
jim 072.d1 OS.READBYTE no longer preserves A on CS
jim 072.d1 irq.vec,irq2.vec,nmi.vec now redundant
jim 072.d1 Renamed JobCall DownloadData to DownloadData38
jim 072.d1 Renamed JobCall UploadData to UploadData38
jim 072.d1 Renamed JobCall ExecuteCode to ExecuteCode38
jim 072.d1 Renamed JobCall ReadByte to ReadByte38
jim 072.d1 Renamed JobCall StoreByte to StoreByte38
jim 072.d1 JobCall ForcedADCRead now checks adc.owner first
jim 072.d3 Added CallOS 27 Write printer
jim 072.d3 Added CallOS 28 Read printer
jim 072.d3 Added CallOS 29 Write RTC Reg
jim 072.d3 Added CallOS 30 Read RTC Reg
jim 072.d3 Added CallOS 31 Write RTC string
jim 072.d3 Added CallOS 32 Read RTC string
jim 072.d3 Added CallOS 33 Write RTC bcd
jim 072.d3 Added CallOS 34 Read RTC bcd
jim 072.d3 Added CallOS 35 Write LCD Reg
jim 072.d3 Added CallOS 36 Read LCD Reg
jim 072.d3 Added JobCall WritePrinter
jim 072.d3 Added JobCall ReadPrinter
jim 072.d3 Added JobCall PrintChar
jim 072.d3 Added JobCall PrintStreamZ
jim 072.d3 Added JobCall PrintStream
jim 072.d3 Added JobCall PrintServer
jim 072.d3 Added JobCall WriteRTCReg
jim 072.d3 Added JobCall ReadRTCReg
jim 072.d3 Added JobCall WriteRTC
jim 072.d3 Added JobCall ReadRTC
jim 072.d3 Added JobCall WriteRTCbcd
jim 072.d3 Added JobCall ReadRTCbcd
jim 072.d3 Added JobCall WriteLCDReg
jim 072.d3 Added JobCall ReadLCDReg
jim 072.d3 Added CallOS 37 Write Power ctrl
jim 072.d3 Added CallOS 38 Read Power ctrl
jim 072.d3 Implemented OS.PRINTER
jim 072.d3 Added JobCall PatchMF (MotorForward)
jim 072.d3 Changed irq.vec to int0.vec
jim 072.d3 Changed irq2.vec to int1.vec
jim 072.d3 Added int2irq.vec (wrksp+&20)
jim 072.d3 Added int3irq.vec (wrksp+&22)
jim 072.d3 Added int4irq.vec (wrksp+&24)
jim 072.d3 Added c0irq.vec (wrksp+&26)
jim 072.d3 Added c1irq.vec (wrksp+&28)
jim 072.d3 Added t1irq.vec (wrksp+&2A)
jim 072.d3 Added t2irq.vec (wrksp+&2C)
jim 072.d3 Added txirq.vec (wrksp+&2E)
jim 072.d3 Added tyirq.vec (wrksp+&30)
jim 072.d3 Added s1rirq.vec (wrksp+&32)
jim 072.d3 Added s1rirq.vec (wrksp+&34)
jim 072.d3 Added s2irq.vec (wrksp+&36)
jim 072.d3 Added adcirq.vec (wrksp+&38)
jim 072.d3 Renamed JobCall DownloadData38 to DownloadData740
jim 072.d3 Renamed JobCall UploadData38 to UploadData740
jim 072.d3 Renamed JobCall ExecuteCode38 to ExecuteCode740
jim 072.d3 Renamed JobCall ReadByte38 to ReadByte740
jim 072.d3 Renamed JobCall StoreByte38 to StoreByte740
jim 072.d4 Hardware update
jim 072.d4 Re-assigned CallOS 37 to Write Power/Charge control
jim 072.d4 Re-assigned CallOS 38 to Read Power/Charge control
jim 072.d4 Moved int2irq.vec to wrksp+&22
jim 072.d4 Moved int3irq.vec to wrksp+&24
jim 072.d4 Moved int4irq.vec to wrksp+&26
jim 072.d4 Moved c0irq.vec to wrksp+&28
jim 072.d4 Moved c1irq.vec to wrksp+&2A
jim 072.d4 Moved t1irq.vec to wrksp+&2C
jim 072.d4 Moved t2irq.vec to wrksp+&2E
jim 072.d4 Moved txirq.vec to wrksp+&30
jim 072.d4 Moved tyirq.vec to wrksp+&32
jim 072.d4 Moved s1rirq.vec to wrksp+&34
jim 072.d4 Moved s1rirq.vec to wrksp+&36
jim 072.d4 Moved s2irq.vec to wrksp+&38
jim 072.d4 Moved adcirq.vec to wrksp+&3A
jim 072.d4 Added OS.LCDVDU (&FFB7) and lcdvdu.vec (wrksp+&20)
jim 072.d5 Re-assigned CallOS 37 to Write/Read Power/Charge control
jim 072.d5 Re-assgined CallOS 38 Read Battery Voltage
jim 072.d5 OS.CALLOS now re-entrant
jim 072.d5 Fixed OS.PRINTER
jim 072.d5 Started to add internal logging software
jim 072.d5 Moved OS.LCDVDU to &FFB6
jim 072.d7 Added OS.PRINTERPOLL (&FFB3) and printerpoll.vec (wrksp+&3C)
bob 073 Matched jim & bob sensor lookup tables
bob 073 Added PatchMF
jim 072.dj Added OS.CALLOS 51 Read keypad press
jim 072.dj Added hard reset keypad press
jim 072.dk Added JobCall ReadOutputs
jim 072.do Changed soft reset of zero page locations
jim 072.do Changed MotorForward/Backward bitmaps
jim 072.dp Fixed OS.CALLOS WriteRTCbcd
jim 072.dq Fixed OS.CALLOS ReadRTCstring for correct 24hr operation
jim 072.dr Changed reset prompts
bob 074 Added support for Little Bob
jim 072.dy Added further RTC/CMOS support
jim 072.dB Removed double hard reset
jim 072.dE Set _cpu.mode depending on external memory requirement
jim 072.dF Added Insight code
jim 073 Sub-release
jim 074 Modification to LCD code - uses bsy flag all the time now
jim 074 Fixed OS.CALLOS 42 Write LCD Char Def
jim 074 Fixed OS.CALLOS 43 Read LCD Char Def
jim 075 Added simple battery charge code
jim 075 Fixed JobCall ReadSensorTable
jim 075 Fixed OS.CALLOS 42 Write LCD Char Def
jim 075 Fixed OS.CALLOS 43 Read LCD Char Def
jim 075 Added sleep code
jim 075 Added OS.CALLOS 52 Write Sleep Time
jim 075 Added OS.CALLOS 53 Read Sleep Time
jim 075 Modified battery charge code
jim 076 Modified JobCall ReadSensorTable
jim 076 Modified OS.CALLOS 26 ReadKeypad to do debounce
jim 077 Rewrote battery charging code
jim 077.2 Reduced stop charge threshold to 2
jim 077.3 Increased stop charge threshold to 3
jim 077.3 Added battery voltage averaging
bill 077 Stripped
bill 077 Moved ins to out port
bill 077 Added RTS
bill 077 Changed sensor ID system back to original, using p2.1
bill 077 Dedicated USB/RS selection line, RTS provisioned on p2.3
bill 077 Overload "bounce" timing
bill 078 CTS added
bill 079 Temperature fudge</nowiki>

SmartBox OS

2023-11-04T08:34:02Z

Benryves: /* Memory */ Put zero page data in a table

== Documentation for SmartBox OS 2.066 ==

The term JobCall is the concept of the routine itself, as opposed to
JobName (which is the actual name associated with it (eg. NameCode)) and
JobCode (which is the actual number associated with it (eg. 3)).

The term controller means the SmartBox, or any other incarnation
which may appear in future time !

The term OS means the controllers' Operating System.

== Preview ==

There are a number of reasons why using Machine Code on the
controller is more desirable than using the various JobCalls via the serial
link. One reason is speed, if the task which needs to be performed, has to
be performed very quickly (more quickly than can be achieved via the serial
link at least), then some code must be written to work in the controller
itself to achieve this sort of speed. If the task required is to be a
"background" task (ie. a task which may happen while other "things" carry
on as normal, like a change of state of a particular port) then it is far
easier to let the controller do all the work, maybe under interupts, than
continuously poll the controller checking the state of various things.
Another reason may be that you would like to add another JobCall to the OS,
extending the calls available to external applications (and the user at the
same time), without the user having to write the code himself to achieve the
aim. For advanced users, there is also the ablity to alter the way the OS
does various things and to have the controller in their "power", for
dedicated tasks etc.

One advantage of writing IN the controller is that that "function"
is available to any computer using the serial link, and is thus not fixed to
one computer type or even a computer at all, where the controller is used
free running, doing a particular task which doesn't need the intervention of
the user's own computer.

== Call types ==

There are three different types of machine code routines which can
be added to the controller. Each one is suited to a more advanced level
than the other, which also relates to the amount of work needed to actually
get the routine working ! The three levels are such:

=== Simple stand alone routine ===

Here the routine is just the routine
itself with no supporting code (ie. code to integrate with the rest of the
OS). It has to be called directly, by use of the ExecuteCode JobCall, thus
it usually resides at a fixed address and obviously does not offer the user
friendly way of accessing itself like there is with normal OS calls.

=== Extended JobCall ===

There is one JobCall in the OS (ExtendJob)
which can call various routines residing in memory, each one is identified
by a 8 bit number. The disadvantages of this way is that the call hasn't
got it's own JobName/JobCode and needs the extra byte to identify itself.
This is ideal for the quick routine which the user would like to add for
himself without having to resort to the extra code needed for the full
JobCode implementation.

=== Full JobCall ===

This is where the routine can define itself one
(or a number) of JobNames/JobCodes, it can integrate itself into an
extension of the OS in a complete way. The disadvantage is that extra
coding is needed to deal with the various OS calls it has to service and
that extra work is needed to produce a suitable file to place in the
controller.

Normally with most processors, including the 65c02, the machine code
produced is produced for a fixed memory address, and it cannot be made to
run in a different place in memory unless extra work is carried out by the
user, or at least a combination of the user and the OS. For the controller
this is a very severe disadvantage as most extensions are downloaded as
"modules" and to optimise memory a system has to be devised to enable
routines to be placed anywhere in memory, thus allowing no memory to be
wasted. In the OS there is a routine to do just this, though it does need
some help. A special version of the users code has to be developed, or
rather it has to be "processed" to add extra information on the end. Extra
code is needed to set up a few pointers and call the OS routine to relocate.
See later.

== Memory ==

The first 256 bytes of memory are somewhat special, most zero page
locations are reserved for use by the OS:

{|class="wikitable"
|-
|&00-&14||General workspace, used to pass parameters to some OS routines, can also be used by other routines DURING their execution.
|-
|&15-&6F||Reserved
|-
|&70-&9F||Available to the user
|-
|&A0||Accumulator store for irqs (irq_A)
|-
|&A1-&A2||Two byte counter, decremented at 100hz, useful for temporary timing purposes (fcount)
|-
|&A3||RAM size, high byte of RAM size of machine, ie. for 32k this will be &80 (RAM_size)
|-
|&A4-&AF||Reserved
|-
|&B0-&FF||Used by the OS
|-
|}

The rest of memory space is used for the processors stack, OS'
buffers, tables, vectors and, of course, the user available memory.

A breakdown of the rest of memory:

* &100 to &1FF is the 65c02's stack.
* &200-&2FF is used by the OS for various system functions and also contains the vector table, more on that later.
* &300-&3FF is the serial input buffer.
* &400-&47F is the internal job code call output buffer. (jobout_buf)
* &480-&4FF is the internal job code call input buffer. (jobin_buf)
* &500-&5FF is the job status table.
* &600 to the end of RAM memory is for the user. The user should not assume what the top of AVAILABLE memory is and use the system variable HIMEM.

In the controller the maximum limit of RAM is &8000 (which is 32k),
from &8000-&DFFF lies the memory mapped hardware, from &E000 to &FFF9 lies
the OS and from &FFFA to &FFFF lies the 65c02 vectors.

So the user has his own limits of free memory. The lowest limit is
called LOMEM and the highest limit is called HIMEM, everything between these
boundaries is termed "available" for use by anyone, the user or the OS.

Anyone can also claim memory, thus making private to them and not allowing
anyone else to use it. You do this by altering the value of LOMEM, HIMEM
should not be moved. Of course anyone claiming memory should first check
that there is enough memory available for the amount they want to claim for.
To take a common example, a downloadable routine which installs itself as a
extension routine, The download routine will first of all read LOMEM, read
HIMEM, check there is enough memory for the routine, download it to LOMEM
and call it, the downloaded routine will then relocate itself and alter
LOMEM so it is protected.

There is one other memory limit, this is called TOPMEM, this is the
absolute top limit of RAM, HIMEM will normally equal TOPMEM, but a future OS
may alter HIMEM to below TOPMEM. TOPMEM should be ignored ideally, and
HIMEM used.

== OS Calls ==

The OS has calls (ie. a jump instruction which you call, which
then calls, via a RAM vector, a routine in the OS) setup near the top of
memory, through these calls you do everything associated with the
controller. The calls are are such:

* OS_PRINTER at address &FFB9
* OS_CALLOS at address &FFBC
* OS_SENDBYTE at address &FFBF
* OS_READBYTE at address &FFC2
* OS_SENDJOB at address &FFC5
* OS_READJOB at address &FFC8
* OS_DECODEJOB at address &FFCB

The address is the one to call for the particular routine.

* OS_PRINTER is reserved for future use.
* OS_CALLOS calls upon the OS to do various things internally.
* OS_SENDBYTE sends a byte out of the serial port.
* OS_READBYTE reads a byte from the serial port.
* OS_SENDJOB 'sends' a value to the JobCall caller.
* OS_READJOB 'reads' a value from the JobCalls caller.
* OS_DECODEJOB decodes the Job number held in A and acts on it.

Note none of these things should be used in interupt routines,
except OS_CALLOS, of any sort, except if YOU know what state the machine is
in and WHY.

=== Serial Port ===

The serial port on the controller is currently based on the 6850
UART, this need not bother you as the OS deals with the thing entirely by
itself. The chip is setup by the OS to always have a word format of 8n1 and
a baud rate of 9600, this translates to 960cps. The 6850 has two divide
rates for the baud rate, the OS only uses one, using the other one is beyond
the scope of this document and shouldn't be neccessary to use.

Only receive interupts are used, transmission of characters is done
on a polled basis.

As said, there are two calls OS_READBYTE and OS_SENDBYTE.
OS_READBYTE tests the serial input buffer and returns the character (if any
in the A register), the c flag states whether there was a character
returned.

<nowiki> Call : OS_READBYTE
Entry : A, X, Y, c, z = undefined
Exit : X, Y preserved
z = undefined
if c = 1 (no character received)
A is preserved
if c = 0 (character received)
A = character received</nowiki>

OS_SENDBYTE sends the character in the A register out of the serial
port, taking into consideration flow control etc.

<nowiki> Call : OS_SENDBYTE
Entry : A = character to send
X, Y, c, z = undefined
Exit : A, X, Y, c is preserved
z = undefined</nowiki>

=== OS_READJOB and OS_SENDJOB ===

To send/receive data from the user (either internally or via the
serial port) you call OS_SENDJOB/OS_READJOB for the next byte. If your
JobCall requires dynamic use of data, ie. interaction, then a check of the
enviroment should be done to check the call came from the serial port. One
example of this is the OS JobCall MultipleServer, which requires dynamic use
of sending a stream of data until a reaction from the user to tell it to
stop.

<nowiki> Call : OS_READJOB
Purpose: To read job value from the user
Entry : A, X, Y, c, z = undefined
Exit : A = byte read
X, Y is preserved
c, z = undefined
Note : When coming from the serial port it waits for a character to be
received, if you are doing a serial only call and wish to have a loop
checking for a character from the user while doing "your own thing", then
OS_READBYTE should be used. For internal calls this reads data out of
jobin_buf.</nowiki>

<nowiki> Call : OS_SENDJOB
Purpose: To give a job value back to the user
Entry : A = byte to give
X, Y, c, z = undefined
Exit : A, X, Y is preserved
c, z = undefined
Note : This will send either out to the serial port or place a byte in
jobout_buf. For internal calls this stores the value in jobout_buf, which
is allocated 128 bytes, no bound checking is done so sending more than 128
bytes to OS_SENDJOB will cause corruption of some memory.</nowiki>

=== OS_DECODEJOB ===

JobCalls in practise are really only used by the user, JobCalls
tend not to call other calls at all, infact you shouldn't really call
another call unless you were called from the serial port. If you do need to
call another JobCall then you do it like this; with each call you have
associated with it a number, and the call might require some data or give
some data back or both. With the serial port this is simple, you just send
data down and receive data as it is produced. You can't do this with
internal calls, and some calls will not let you call them from inside the
controller, you HAVE to call them from outside. But for the ones which do
let you, you do it with two data blocks, one for input TO the call and one
for output FROM the call. These are setup in a position in memory
(jobin_buf and jobout_buf), each one has a maximum of 128 bytes and this
should not be overflowed (OS_READJOB and OS_SENDJOB do NOT do any bound
checking). So to start with you place in the input block the data you want
to give the call (if any), call it, and then act on the data in the output
block (if any). The OS call OS_DECODEJOB is the one which actually calls
the JobCall handler and eventually the actual routine, you tell the JobCall
handler which call you want by placing the JobCode in the A register.

So for OS_DECODEJOB:

<nowiki> Call : OS_DECODEJOB
Entry : A = JobCode
X, Y, c, z = undefined
jobin_buf should contain any input data
Exit : A = flag
X = number of bytes given back by routine
Y = undefined
c = status, if set JobCall does not exist
z = status, if set JobCall cannot be called internally
jobout_buf contains any data sent from routine</nowiki>

A typical example would be:

<nowiki> LDA #readhimem ; JobCode for ReadHimem
JSR OS_DECODEJOB ; Call the JobCall handler
LDX jobout_buf ; Read HIMEM from buffer LSB
LDY jobout_buf+1 ; Read HIMEM from buffer MSB
STX jobin_buf ; Place LSB in input buffer
STY jobin_buf+1 ; Place MSB in input buffer
LDA #writelomem ; JobCode for WriteLomem
JSR OS_DECODEJOB ; Call the JobCall handler</nowiki>

which would read HIMEM, and then write LOMEM to be the same value, leaving
no spare memory left.

The reason why you should not call an internal call from another
internal call is that the same buffers (jobin_buf and jobout_buf) would be
used for both calls, causing conflict between the two calls, or rather to
the originator of the primary call ! The only time it would be safe if is
if you have already got all the data you want from jobin_buf and haven't
placed any in the jobout_buf (it would be lost if you had done).

=== 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.

==== CALLOS : 0 ====
Purpose: Returns the OS version number
<nowiki> 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 </nowiki>

==== CALLOS : 1 ====
Purpose: To claim a block of JobCodes
<nowiki> 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.</nowiki>

==== CALLOS : 2 ====
Purpose: To handle NameCode request for the application.
<nowiki> 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</nowiki>

==== CALLOS : 3 ====
Purpose: To handle CodeName request for the application.
<nowiki> 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</nowiki>

==== CALLOS : 4 ====
Purpose: To relocate code
<nowiki> 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</nowiki>

==== CALLOS : 5 ====
Purpose: To "describe" the enviroment
<nowiki> 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 CALLOS
0 and decide what addresses/configuration to use from the Hardware version
number.</nowiki>

==== CALLOS : 6 ====
Purpose: To read a register in the VIA
<nowiki> 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.</nowiki>

==== CALLOS : 7 ====
Purpose: To write to a register in the VIA
<nowiki> 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</nowiki>

==== CALLOS : 8 ====
Purpose: To read a register in the ACIA
<nowiki> 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</nowiki>

==== CALLOS : 9 ====
Purpose: To write to a register in the ACIA
<nowiki> 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</nowiki>

==== CALLOS : 10 ====
Purpose: To read a register in the ADC
<nowiki> 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</nowiki>

==== CALLOS : 11 ====
Purpose: To write to a register in the ADC
<nowiki> 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</nowiki>

==== CALLOS : 12 ====
Purpose: To read a ADC channel
<nowiki> 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.</nowiki>

==== CALLOS : 13 ====
Purpose: To read a register in the AUX_PORT
<nowiki> 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</nowiki>

==== CALLOS : 14 (OS 2.066+) ====
Purpose: To start sensor type checking
<nowiki> 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 CALLOS 15 to check
when all the sensors have been checked.</nowiki>

==== CALLOS : 15 (OS 2.066+) ====
Purpose: To check the status of sensor checking
<nowiki> 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</nowiki>

==== CALLOS : 16 (OS 2.069+) ====
Purpose: To set the OS' irq mask for the VIA
<nowiki> 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
Note :</nowiki>

==== CALLOS : 17 (OS 2.069+) ====
Purpose: To set the OS' irq mask for the ACIA
<nowiki> 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
Note :</nowiki>

==== CALLOS : 18 (OS 2.069+) ====
Purpose: To set the OS' irq mask for the ADC
<nowiki> 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
Note :</nowiki>

==== CALLOS : 19 (OS 2.069+) ====
Purpose: To set the ACIA's ctrl register and OS' soft copy
<nowiki> 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
Note :</nowiki>

==== CALLOS : 20 (OS 2.069+) ====
Purpose: To set the reset vector for battery back RAM support
<nowiki> 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.</nowiki>

== 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.

* brk_vec at address &200
* nmi_vec at address &202
* irq_vec at address &204
* irq2_vec at address &206
* sendserial_vec at address &208
* readserial_vec at address &20A
* sendjob_vec at address &20C
* readjob_vec at address &20E
* decode_job_vec at address &210
* unknownjob_vec at address &212
* extjob_vec at address &214
* centisec_vec at address &216
* internal_vec at address &218
* callos_vec at address &21A
* printer_vec at address &21C
* reset_vec at address &21E

The brk_vec is 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.

The nmi_vec is called whenever there is a NMI request (not really
applicable, as the NMI line is not connected to anything).

The irq_vec is called whenever there is an interupt.

The irq2_vec is called whenever an unknown interupt is encountered,
ie. didn't come from the controllerXs VIA, ACIA or ADC, or the interupt
from the VIA was not used by the OS.

The sendserial_vec is called when OS_SENDBYTE is called.

The readserial_vec is called when OS_READBYTE is called.

The sendjob_vec is called when OS_SENDJOB is called.

The readjob_vec is called when OS_READJOB is called.

The decodejob_vec is 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".

The unknownjob_vec is called whenever an unknown JobCode is
encountered.

The extendedjob_vec is called whenever the ExtendedJob is called,
the A register holds the extension value.

The centisecond_vec is 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.

The internal_vec is called when some information is needed from
various parts of the system, which includes the OS whch 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.

The callos_vec is called when OS_CALLOS is called.

The printer_vec is called when OS_PRINTER is called.

The reset_vec is 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 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 isnXt 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 infact. 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 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 ====

===== Function: 0 =====
Purpose: Nothing
<nowiki> Entry : A = 0
X, Y, c, z = undefined
Exit : Leave everything as it is and exit straight away
Note : Used for claimed calls</nowiki>

===== Function: 1 =====
Purpose: NameCode request
<nowiki> 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
Note :</nowiki>

===== Function: 2 =====
Purpose: CodeName request
<nowiki> 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 Code not recognised then
A = 2
X, Y, c, z = undefined
Note :</nowiki>

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

==== unknownjob_vec ====
Purpose: To pass on unknown JobCalls to the correct owner
<nowiki> Entry : A = enviroment (0 = internal call, 1 = serial call)
Y = JobCode
X = JOB ID of owner
c, z = undefined
Exit : if jobcode yours then
if wrong enviroment then
A = 1
Y = 0
X, c, z = undefined
if right enviroment then
perform function
A = 0
Y = 0
X, c, z = undefined
if jobcode not yours then
pass on with registers unaltered
Note :</nowiki>

== Starting Up ==

The setup procedure for setting up extension job calls is to:

# Claim the number of JobCodes you want
#: if success:
# patch the internal_vec and unknownjob_vec vectors
# move LOMEM up to protect your program
# do anything else for initial startup you may want to do
# return back, ready and waiting

This in code looks like:

<nowiki>execute
LDX #no_of_calls ; Number of JobCodes wanted
LDA #1 ; CALLOS, function 1, Claim JobCodes
JSR OS_CALLOS ; Call CALLOS
CPX #0 ; Check we were given some codes
BEQ noinstall ; No, don't bother installing ourself
STX call ; Store base address of JobCodes allocated
STY job_id ; Store JOB ID given

LDA internal_vec ; Get old internal_vec (LSB)
STA ovec ; Store it
LDA internal_vec+1 ; Get old internal_vec (MSB)
STA ovec+1 ; Store it
LDA #>internal_handle ; Our internal handler (LSB)
STA internal_vec ; Place it in the vector (LSB)
LDA #<internal_handle ; Our internal handler (MSB)
STA internal_vec+1 ; Place it in the vector (MSB)

LDA unknownjob_vec ; Get old unknownjob_vec (LSB)
STA ovec2 ; Store it
LDA unknownjob_vec+1 ; Get old unknownjob_vec (MSB)
STA ovec2+1 ; Store it
LDA #>job_handle ; Our unknown job handler (LSB)
STA unknownjob_vec ; Place it in the vector (LSB)
LDA #<job_handle ; Our unknown job handler (MSB)
STA unknownjob_vec+1 ; Place it in the vector (MSB)

LDX #>WriteLomem ; Point to JobName
LDY #<WriteLomem
JSR findjob ; Find WriteLomem code
BEQ noinstall ; Doesn't exist !
LDX #>end_of_code ; End of code (LSB)
LDY #<end_of_code ; End of code (MSB)
STX jobin_buf ; Place it in jobin_buf (LSB)
STY jobin_buf+1 ; Place it in jobin_buf+1 (MSB)
JSR OS_DECODEJOB ; Call JobCall handler

noinstall
RTS ; End - return to OS

findjob
STX zero.gp1 ; Zero page
STY zero.gp1+
LDY #0
findthisjoblo
LDA (zero.gp1),Y
STA jobin.buf,Y ; Store name in jobin_buf
INY
CMP #13
BNE findthisjoblo
LDA #3 ; NameCode
JSR OS.DECODEJOB ; Call NameCode
LDA jobout.buf ; Get returned value
RTS

WriteLomem STR "WriteLomem"</nowiki>

This will setup the various vectors and memory pointers for the
applicaion, the actual routines (internal_handle and job_handle) are fairly
straight forward and simple:

<nowiki>internal_handle
CMP #1 : Is it function call 1 (NameCode) ?
BNE internal_handle_2 ; No, check for function 2
LDA job_id ; Get our JOB ID number
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #>job_names ; Our Job name table (LSB)
LDY #<job_names ; Our Job name table (MSB)
LDA #2 ; CALLOS function 2
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes : Found, go off and claim call
LDA #1 ; Not found, restore A
JMP (ovec) ; Call back to old vector

internal_handle_2
CMP #2 ; Is it function call 2 (CodeName) ?
BNE internal_handle_3 ; No, unknown, pass on
LDA job_id ; Get our JOB ID
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #>job_names ; Our Job name table (LSB)
LDY #<job_names ; Our Job name table (MSB)
LDA #3 ; CALLOS function 3
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes ; Found, go off and claim call
LDA #2 ; Not found, restore A
JMP (ovec) ; Call back to old vector

internal_yes
LDA #0 ; We want to claim call for some reason

internal_handle_3
JMP (ovec) ; Call back to old vector

job_handle
PHA ; Mark sure to preserve A
CPY call ; Check call wanted against base of ours
BCC job_handle_no ; Less than our base, so definately not ours
TYA
SBC #no_of_calls ; Subtract number of calls we have
CMP call ; Now compare with base
BCC job_handle2 ; Yes, one of ours

job_handle.no
PLA ; Restore A
JMP (ovec2) ; Call back to old vector

job_handle2
TYA
SEC
SBC call ; Subtract our base from call
ASL A ; Times by 2 for offset into table
TAY ; Place in Y
LDA job_run_table,Y ; Get LSB of routine
STA zero_gp1 ; Store it for indirect jump (LSB)
LDA job_run_table+1,Y ; Get MSB of routine
STA zero_gp1+1 ; Store it for indirect jump (MSB)
PLA ; Restore A
JMP (zero_gp1) ; Call our relevant routine

job_names ; List of our JobNames
STR "TestJob" ; Test job name
DFB &FF ; &FF - marks end of table

job_run_table ; List of routine addresses to match Jobs
DFW job_TestJob ; Test job routine</nowiki>

== Relocation ==

The relocation method used will not do a complete relocation, ie.
from ANY address to ANY address. The only constraint on the addresses is
that they must be the same offset in the page, which means, &2602 and &3402
is alright but &2602 and &3455 is not, ie. the difference between the two
addresses must be a multiple of 256 bytes, as only the MSB is altered, this
should not cause any real problems. What is meant by the two addresses is
the address the code was originally assembled at and the address it wants
relocating to. Because of this programs must be multiples of 256 bytes, ie.
the low byte of LOMEM must ALWAYS be 0, your program should be padded out.

The relocation mechanism works by having a table, and to each byte
of code there is one BIT, if unset it means the byte of code should not be
relocated, else it should be, thus the BitMap table is 8 times smaller than
the code. To generate the BitMap you have to assemble the code at two
different places, and compare both sets of assembled code against each
other, the differences are where the code is to be relocated. The code
which is sent up to the controller is assumed to be assembled at address
&100, so the first code should be assembled at &100, the other one should be
assembled at another address, say &600, and the first one be sent up with
the BitMap. A program is availble for the Elk/Beeb/Arc with 65Tube/Mac with
BBC BASIC to compare the two files and create the BitMap.

All the program has to do to relocate itself is execute this bit of
code first of all: (address is the base address of the program, ie. &100
for the downloaded version)

<nowiki>execcall
LDA #>(execute-address) ; Final execution address offset (LSB)
STA zero_gp1
LDA #<(execute-address) ; Final execution address offset (MSB)
STA zero_gp1+1

LDA #>(BitMap-address) ; BitMap address offset (LSB)
STA zero_gp2
LDA #<(BitMap-address) ; BitMap address offset (MSB)
STA zero_gp2+1

LDA #>(execcall-address); Length of data to relocate (LSB)
STA zero_gp3
LDA #<(execcall-address); Length of data to relocate (MSB)
STA zero_gp3+1

TXA ; Execcall REAL address
SEC
SBC #>(execcall-address); Subrtract length
TAX ; Put it back in X
TYA ; Ditto for MSB
SBC #<(execcall-address)
TAY
LDA #4 ; CALLOS function for Relocate
JMP OS_CALLOS ; Call CALLOS

BitMap ; BitMap start</nowiki>

This will relocate the code and automatically call the execution
address, which should be the initialisation code (ie. setup internal_vec
and unknownjob_vec etc.). "address" is the address the code is started to
assemble at, &100 for the version to be uploaded. The upload routine should
pass in X and Y (via ExecuteCode) the address of the start of execcall, this
means that the routine can tell where it is in memory, subtracting the
length gives the start of the code to relocate.

== Layout Summary ==

The layout of a full application should be like this by now:

<nowiki> start of code
program job codes, data etc.
internal handler
job handler
end of code
initialisation (setup internal etc.)
end of code to be relocated
execution (relocation)
relocation BitMap</nowiki>

Because of memory space the initialisation code should be placed
outside the reserved memory limit of the program, as it is only called once
and not needed again.

== Other miscellaneous calls ==

<nowiki>Call : OS_PRINTER
Purpose : To place a character in the printer buffer
Entry : A = character to send
X, Y, c, z = undefined
Exit : A, X, Y is preserved
if c = 0 (printed)
The printer is on and the character was inserted
if c = 1 (not printed)
The printer is off and the character was forgotten
z = undefined
Note : The character goes into the printer buffer and will be
actually sent to the printer when the printer asks for it. If the printer
was not awake to begin with, an attempt is made to wake it up, thus
meaning that in some circumstances when the printer wasn't ready a
character may be lost, this cannot be helped. If the printer is off (via
the BCD switch) then the character will be forgotten as the Printer Buffer
is inactive.</nowiki>

The module is located at &8000 in memory, and should be a EPROM placed
in the second ROM socket in the controller (ie. the top RAM socket). This
module is primary designed to turn the Controller into a dedicated task,
making it perform some function from switch on. It could also be used to
add more permant JobCalls to the Controller, in the process taking up much
less RAM), but because of there being only one Module present this feature
is limited, and is much more suited to a collection of the user's own
personal routines.

For the OS to recognise a module as being in place the text "Module" is
looked for, the layout of a module should be like this (starting at
&8000):

<nowiki>Offset value comment
0 "Module" The OS checks for this string
6 0 End of check string
7 Language entry Address of 'Language' entry
9 Service entry Address of 'Service' entry
11 "<Module Title>" Module title
0 End of Module title

"<Module part>" Part Module Title
0 End of Part Module Title
"x.xx" Part version number

&FF End of parts list</nowiki>

The language entry is a 2 byte value holding the address of the language
entry routine, this is called on reset, if the BCD is set correctly. A
value of less than &8000 means there is no valid language entry and any
language calls are ignored. If a RTS is made the OS carries on as it would
have if there wasn't a language call.

The service entry is a 2 byte value holding the address of the service
entry routine, this is called at various appropiate moments with service
numbers in A. A list of current calls is thus:

<nowiki> 0 - Not used
1 - Unknown Job Code
2 - Centisecond call
3 - Irq2 (unknown IRQ)
4 - internal_vec call (exit with A=0 to claim)
254 - RESET
255 - BRK</nowiki>

On exit all registers and flags should be preserved. For call 1 the
unknown job value is held in the Y register, the enviroment is held in the
X register, on exit, X should contain the flag, as A does from the exit of
unknownjob_vec. For the rest of calls, X and Y are undefined.

For both Service and Language entry points, a value of 0 means "there is
no valid routine" and the module isn't called for that type of entry.

Finally a full implementation of a JobCall, from start to finish.

<nowiki> DIM data% &1000
:
no_of_calls = 1
:
VIA = &E030
ACIA = &E010
ADC = &E000
AUX_PORT = &E020
brk_vec = &200
nmi_vec = &202
irq_vec = &204
irq2_vec = &206
sendserial_vec = &208
readserial_vec = &20A
sendjob_vec = &20C
readjob_vec = &20E
decodejob_vec = &210
unknownjob_vec = &212
extjob_vec = &214
centisec_vec = &216
internal_vec = &218
callos_vec = &21A
printer_vec = &21C
zero_gp1 = 0
zero_gp2 = 2
zero_gp3 = 4
zero_gp4 = 6
zero_gp5 = 8
zero_gp6 = 10
zero_gp7 = 12
zero_gp8 = 14
zero_gp9 = 16
zero_gp10 = 18
user_reserved = &70
irq_A = &A0
fcount = &A1
RAM_size = &A3
jobout_buf = &400
jobin_buf = &480
OS_PRINTER = &FFB9
OS_CALLOS = &FFBC
OS_SENDBYTE = &FFBF
OS_READBYTE = &FFC2
OS_SENDJOB = &FFC5
OS_READJOB = &FFC8
OS_DECODEJOB = &FFCB
:
FOR create=1 TO 2
:
FOR pass%=4 TO 7 STEP 3
P%=&100*create : O%=data%
[OPT pass%
:
.job_DemoJob
CMP #1
BEQ DemoJob_go
LDA #1
LDY #0
RTS
/
.DemoJob_go

:
.internal_handle
CMP #1 ; Is it function call 1 (NameCode) ?
BNE internal_handle_2 ; No, check for function 2
/
LDA job_id ; Get our JOB ID number
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #job_names MOD 256 ; Our Job name table (LSB)
LDY #job_names DIV 256 ; Our Job name table (MSB)
LDA #2 ; CALLOS function 2
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes ; Found, go off and claim call
LDA #1 ; Not found, restore A
JMP (ovec) ; Call back to old vector
/
.internal_handle_2
CMP #2 ; Is it function call 2 (CodeName) ?
BNE internal_handle_3 ; No, unknown, pass on
/
LDA job_id ; Get our JOB ID
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #job_names MOD 256 ; Our Job name table (LSB)
LDY #job_names DIV 256 ; Our Job name table (MSB)
LDA #3 ; CALLOS function 3
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes ; Found, go off and claim call
LDA #2 ; Not found, restore A
JMP (ovec) ; Call back to old vector
/
.internal_yes
LDA #0 ; We want to claim call for some reason
/
.internal_handle_3
JMP (ovec) ; Call back to old vector
:
.job_handle
PHA ; Make sure to preserve A
CPY call ; Check call wanted against base of ours
BCC job_handle_no ; Less than our base, so definately not ours
TYA
SBC #no_of_calls ; Subtract number of calls we have
CMP call ; Now compare with base
BCC job_handle2 ; Yes, one of ours
/
.job_handle.no
PLA ; Restore A
JMP (ovec2) ; Call back to old vector
/
.job_handle2
TYA
SEC
SBC call ; Subtract our base from call
ASL A ; Times by 2 for offset into table
TAY ; Place in Y
LDA job_run_table,Y ; Get LSB of routine
STA zero_gp1 ; Store it for indirect jump (LSB)
LDA job_run_table+1,Y ; Get MSB of routine
STA zero_gp1+1 ; Store it for indirect jump (MSB)
PLA ; Restore A
JMP (zero_gp1) ; Call our relevant routine
:
.job_names ; List of our JobNames
EQUS "DemoJob":EQUB 13 ; Test job name
/
EQUB &FF ; &FF - marks end of table
:
.job_run_table ; List of routine addresses to match Jobs
EQUW job_DemoJob ; Test job routine
:
.call : EQUB 0 ; Store for our JobCode base
.job_id : EQUB 0 ; Store for our JobId
.ovec : EQUW 0 ; Store for old internal_vec value
.ovec2 : EQUW 0 ; Store for old unknownjob_vec value
:
EQUS STRING$(&100-(P% MOD 256),CHR$0)
.end_of_code ; end_of_code should be on page boundry
:
.execute
LDX #no_of_calls ; Number of JobCodes wanted
LDA #1 ; CALLOS, function 1, Claim JobCodes
JSR OS_CALLOS ; Call CALLOS
STX call ; Store base address of JobCodes allocated
STY job_id ; Store JOB ID given
CPX #0 ; Check we were given some codes
BEQ noinstall ; No, don't bother installing ourself
/
LDA internal_vec ; Get old internal_vec (LSB)
STA ovec ; Store it
LDA internal_vec+1 ; Get old internal_vec (MSB)
STA ovec+1 ; Store it
LDA #internal_handle MOD 256 ; Our internal handler (LSB)
STA internal_vec ; Place it in the vector (LSB)
LDA #internal_handle DIV 256 ; Our internal handler (MSB)
STA internal_vec+1 ; Place it in the vector (MSB)
/
LDA unknownjob_vec ; Get old unknownjob_vec (LSB)
STA ovec2 ; Store it
LDA unknownjob_vec+1 ; Get old unknownjob_vec (MSB)
STA ovec2+1 ; Store it
LDA #job_handle MOD 256 ; Our unknown job handler (LSB)
STA unknownjob_vec ; Place it in the vector (LSB)
LDA #job_handle DIV 256 ; Our unknown job handler (MSB)
STA unknownjob_vec+1 ; Place it in the vector (MSB)
/
LDX #end_of_code MOD 256 ; End of code (LSB)
LDY #end_of_code DIV 256 ; End of code (MSB)
STX jobin_buf ; Place it in jobin_buf (LSB)
STY jobin_buf+1 ; Place it in jobin_buf+1 (MSB)
LDA #65 ; JobCode for WriteLomem
JSR OS_DECODEJOB ; Call JobCall handler
/
.noinstall
RTS ; End - return to OS
:
.execcall
LDA #>(execute-address) ; Final execution address offset (LSB)
STA zero_gp1
LDA #<(execute-address) ; Final execution address offset (MSB)
STA zero_gp1+1
/
LDA #>(BitMap-address) ; BitMap address offset (LSB)
STA zero_gp2
LDA #<(BitMap-address) ; BitMap address offset (MSB)
STA zero_gp2+1
/
LDA #>(execcall-address) ; Length of data to relocate (LSB)
STA zero_gp3
LDA #<(execcall-address) ; Length of data to relocate (MSB)
STA zero_gp3+1
/
TXA ; Execcall REAL address
SEC
SBC #>(execcall-address) ; Subrtract length
TAX ; Put it back in X
TYA ; Ditto for MSB
SBC #<(execcall-address)
TAY
LDA #4 ; CALLOS function for Relocate
JMP OS_CALLOS ; Call CALLOS
/
.BitMap ; BitMap start
:
]
NEXT
:
OSCLI "SAVE code"+STR$create+" "+STR$~data%+" "+STR$~O%
:
NEXT</nowiki>

== Changelog ==

<nowiki>bob 071 Fixed MotorForward bug (%10)
bob 072 CallOS 14 now checks current adc.owner status
jim 072.d1 * Rewrite for new hardware/processor *
jim 072.d1 Moved vectors/workspace to &440
jim 072.d1 Moved rs.inp.buf to &500
jim 072.d1 Moved jobout.buf to &600
jim 072.d1 Moved jobin.buf to &680
jim 072.d1 Moved jobs.status to &700
jim 072.d1 Added irq.X (&A4)
jim 072.d1 Added irq.Y (&A5)
jim 072.d1 Removed short detection code
jim 072.d1 Voided CallOS' 6,7,8,9,10,11,13,16,17,18,19
jim 072.d1 Removed JobCalls ReadADCReg,WriteADCReg
jim 072.d1 Removed JobCalls ReadACIAReg,WriteACIAReg
jim 072.d1 Removed JobCalls ReadVIAReg,WriteVIAReg,SetVIAHigh,SetVIALow
jim 072.d1 Added CallOS 21 Write Outputs
jim 072.d1 Added CallOS 22 Read Outputs added
jim 072.d1 Added CallOS 23 Read Inputs added
jim 072.d1 Added CallOS 24 Write Motors
jim 072.d1 Added CallOS 25 Read Motors
jim 072.d1 Added CallOS 26 Read Keypad
jim 072.d1 Expanded CallOS 5 information
jim 072.d1 Added JobCall IdentSystem to return CallOS 5 info
jim 072.d1 JobCalls now use appropriate CallOS'
jim 072.d1 OS.READBYTE no longer preserves A on CS
jim 072.d1 irq.vec,irq2.vec,nmi.vec now redundant
jim 072.d1 Renamed JobCall DownloadData to DownloadData38
jim 072.d1 Renamed JobCall UploadData to UploadData38
jim 072.d1 Renamed JobCall ExecuteCode to ExecuteCode38
jim 072.d1 Renamed JobCall ReadByte to ReadByte38
jim 072.d1 Renamed JobCall StoreByte to StoreByte38
jim 072.d1 JobCall ForcedADCRead now checks adc.owner first
jim 072.d3 Added CallOS 27 Write printer
jim 072.d3 Added CallOS 28 Read printer
jim 072.d3 Added CallOS 29 Write RTC Reg
jim 072.d3 Added CallOS 30 Read RTC Reg
jim 072.d3 Added CallOS 31 Write RTC string
jim 072.d3 Added CallOS 32 Read RTC string
jim 072.d3 Added CallOS 33 Write RTC bcd
jim 072.d3 Added CallOS 34 Read RTC bcd
jim 072.d3 Added CallOS 35 Write LCD Reg
jim 072.d3 Added CallOS 36 Read LCD Reg
jim 072.d3 Added JobCall WritePrinter
jim 072.d3 Added JobCall ReadPrinter
jim 072.d3 Added JobCall PrintChar
jim 072.d3 Added JobCall PrintStreamZ
jim 072.d3 Added JobCall PrintStream
jim 072.d3 Added JobCall PrintServer
jim 072.d3 Added JobCall WriteRTCReg
jim 072.d3 Added JobCall ReadRTCReg
jim 072.d3 Added JobCall WriteRTC
jim 072.d3 Added JobCall ReadRTC
jim 072.d3 Added JobCall WriteRTCbcd
jim 072.d3 Added JobCall ReadRTCbcd
jim 072.d3 Added JobCall WriteLCDReg
jim 072.d3 Added JobCall ReadLCDReg
jim 072.d3 Added CallOS 37 Write Power ctrl
jim 072.d3 Added CallOS 38 Read Power ctrl
jim 072.d3 Implemented OS.PRINTER
jim 072.d3 Added JobCall PatchMF (MotorForward)
jim 072.d3 Changed irq.vec to int0.vec
jim 072.d3 Changed irq2.vec to int1.vec
jim 072.d3 Added int2irq.vec (wrksp+&20)
jim 072.d3 Added int3irq.vec (wrksp+&22)
jim 072.d3 Added int4irq.vec (wrksp+&24)
jim 072.d3 Added c0irq.vec (wrksp+&26)
jim 072.d3 Added c1irq.vec (wrksp+&28)
jim 072.d3 Added t1irq.vec (wrksp+&2A)
jim 072.d3 Added t2irq.vec (wrksp+&2C)
jim 072.d3 Added txirq.vec (wrksp+&2E)
jim 072.d3 Added tyirq.vec (wrksp+&30)
jim 072.d3 Added s1rirq.vec (wrksp+&32)
jim 072.d3 Added s1rirq.vec (wrksp+&34)
jim 072.d3 Added s2irq.vec (wrksp+&36)
jim 072.d3 Added adcirq.vec (wrksp+&38)
jim 072.d3 Renamed JobCall DownloadData38 to DownloadData740
jim 072.d3 Renamed JobCall UploadData38 to UploadData740
jim 072.d3 Renamed JobCall ExecuteCode38 to ExecuteCode740
jim 072.d3 Renamed JobCall ReadByte38 to ReadByte740
jim 072.d3 Renamed JobCall StoreByte38 to StoreByte740
jim 072.d4 Hardware update
jim 072.d4 Re-assigned CallOS 37 to Write Power/Charge control
jim 072.d4 Re-assigned CallOS 38 to Read Power/Charge control
jim 072.d4 Moved int2irq.vec to wrksp+&22
jim 072.d4 Moved int3irq.vec to wrksp+&24
jim 072.d4 Moved int4irq.vec to wrksp+&26
jim 072.d4 Moved c0irq.vec to wrksp+&28
jim 072.d4 Moved c1irq.vec to wrksp+&2A
jim 072.d4 Moved t1irq.vec to wrksp+&2C
jim 072.d4 Moved t2irq.vec to wrksp+&2E
jim 072.d4 Moved txirq.vec to wrksp+&30
jim 072.d4 Moved tyirq.vec to wrksp+&32
jim 072.d4 Moved s1rirq.vec to wrksp+&34
jim 072.d4 Moved s1rirq.vec to wrksp+&36
jim 072.d4 Moved s2irq.vec to wrksp+&38
jim 072.d4 Moved adcirq.vec to wrksp+&3A
jim 072.d4 Added OS.LCDVDU (&FFB7) and lcdvdu.vec (wrksp+&20)
jim 072.d5 Re-assigned CallOS 37 to Write/Read Power/Charge control
jim 072.d5 Re-assgined CallOS 38 Read Battery Voltage
jim 072.d5 OS.CALLOS now re-entrant
jim 072.d5 Fixed OS.PRINTER
jim 072.d5 Started to add internal logging software
jim 072.d5 Moved OS.LCDVDU to &FFB6
jim 072.d7 Added OS.PRINTERPOLL (&FFB3) and printerpoll.vec (wrksp+&3C)
bob 073 Matched jim & bob sensor lookup tables
bob 073 Added PatchMF
jim 072.dj Added OS.CALLOS 51 Read keypad press
jim 072.dj Added hard reset keypad press
jim 072.dk Added JobCall ReadOutputs
jim 072.do Changed soft reset of zero page locations
jim 072.do Changed MotorForward/Backward bitmaps
jim 072.dp Fixed OS.CALLOS WriteRTCbcd
jim 072.dq Fixed OS.CALLOS ReadRTCstring for correct 24hr operation
jim 072.dr Changed reset prompts
bob 074 Added support for Little Bob
jim 072.dy Added further RTC/CMOS support
jim 072.dB Removed double hard reset
jim 072.dE Set _cpu.mode depending on external memory requirement
jim 072.dF Added Insight code
jim 073 Sub-release
jim 074 Modification to LCD code - uses bsy flag all the time now
jim 074 Fixed OS.CALLOS 42 Write LCD Char Def
jim 074 Fixed OS.CALLOS 43 Read LCD Char Def
jim 075 Added simple battery charge code
jim 075 Fixed JobCall ReadSensorTable
jim 075 Fixed OS.CALLOS 42 Write LCD Char Def
jim 075 Fixed OS.CALLOS 43 Read LCD Char Def
jim 075 Added sleep code
jim 075 Added OS.CALLOS 52 Write Sleep Time
jim 075 Added OS.CALLOS 53 Read Sleep Time
jim 075 Modified battery charge code
jim 076 Modified JobCall ReadSensorTable
jim 076 Modified OS.CALLOS 26 ReadKeypad to do debounce
jim 077 Rewrote battery charging code
jim 077.2 Reduced stop charge threshold to 2
jim 077.3 Increased stop charge threshold to 3
jim 077.3 Added battery voltage averaging
bill 077 Stripped
bill 077 Moved ins to out port
bill 077 Added RTS
bill 077 Changed sensor ID system back to original, using p2.1
bill 077 Dedicated USB/RS selection line, RTS provisioned on p2.3
bill 077 Overload "bounce" timing
bill 078 CTS added
bill 079 Temperature fudge</nowiki>

SmartBox OS

2023-11-03T22:51:45Z

Benryves: Did rough conversion of plain text to MediaWiki markup

== Documentation for SmartBox OS 2.066 ==

The term JobCall is the concept of the routine itself, as opposed to
JobName (which is the actual name associated with it (eg. NameCode)) and
JobCode (which is the actual number associated with it (eg. 3)).

The term controller means the SmartBox, or any other incarnation
which may appear in future time !

The term OS means the controllers' Operating System.

== Preview ==

There are a number of reasons why using Machine Code on the
controller is more desirable than using the various JobCalls via the serial
link. One reason is speed, if the task which needs to be performed, has to
be performed very quickly (more quickly than can be achieved via the serial
link at least), then some code must be written to work in the controller
itself to achieve this sort of speed. If the task required is to be a
"background" task (ie. a task which may happen while other "things" carry
on as normal, like a change of state of a particular port) then it is far
easier to let the controller do all the work, maybe under interupts, than
continuously poll the controller checking the state of various things.
Another reason may be that you would like to add another JobCall to the OS,
extending the calls available to external applications (and the user at the
same time), without the user having to write the code himself to achieve the
aim. For advanced users, there is also the ablity to alter the way the OS
does various things and to have the controller in their "power", for
dedicated tasks etc.

One advantage of writing IN the controller is that that "function"
is available to any computer using the serial link, and is thus not fixed to
one computer type or even a computer at all, where the controller is used
free running, doing a particular task which doesn't need the intervention of
the user's own computer.

== Call types ==

There are three different types of machine code routines which can
be added to the controller. Each one is suited to a more advanced level
than the other, which also relates to the amount of work needed to actually
get the routine working ! The three levels are such:

=== Simple stand alone routine ===

Here the routine is just the routine
itself with no supporting code (ie. code to integrate with the rest of the
OS). It has to be called directly, by use of the ExecuteCode JobCall, thus
it usually resides at a fixed address and obviously does not offer the user
friendly way of accessing itself like there is with normal OS calls.

=== Extended JobCall ===

There is one JobCall in the OS (ExtendJob)
which can call various routines residing in memory, each one is identified
by a 8 bit number. The disadvantages of this way is that the call hasn't
got it's own JobName/JobCode and needs the extra byte to identify itself.
This is ideal for the quick routine which the user would like to add for
himself without having to resort to the extra code needed for the full
JobCode implementation.

=== Full JobCall ===

This is where the routine can define itself one
(or a number) of JobNames/JobCodes, it can integrate itself into an
extension of the OS in a complete way. The disadvantage is that extra
coding is needed to deal with the various OS calls it has to service and
that extra work is needed to produce a suitable file to place in the
controller.

Normally with most processors, including the 65c02, the machine code
produced is produced for a fixed memory address, and it cannot be made to
run in a different place in memory unless extra work is carried out by the
user, or at least a combination of the user and the OS. For the controller
this is a very severe disadvantage as most extensions are downloaded as
"modules" and to optimise memory a system has to be devised to enable
routines to be placed anywhere in memory, thus allowing no memory to be
wasted. In the OS there is a routine to do just this, though it does need
some help. A special version of the users code has to be developed, or
rather it has to be "processed" to add extra information on the end. Extra
code is needed to set up a few pointers and call the OS routine to relocate.
See later.

== Memory ==

The first 256 bytes of memory are somewhat special, most zero page
locations are reserved for use by the OS:

<nowiki> 0 General workspace, used to pass parameters to some OS
routines, can also be used by other routines DURING
14 their execution.
15 Reserved
6f
70 Available to the user
9f
a0 Accumulator store for irqs (irq_A)
a1 Two byte counter, decremented at 100hz, useful for temporary
a2 timing purposes (fcount)
a3 RAM size, high byte of RAM size of machine, ie. for 32k
this will be &80 (RAM_size)
a4 Reserved
af
b0 Used by the OS
ff</nowiki>

The rest of memory space is used for the processors stack, OS'
buffers, tables, vectors and, of course, the user available memory.

A breakdown of the rest of memory:

* &100 to &1FF is the 65c02's stack.
* &200-&2FF is used by the OS for various system functions and also contains the vector table, more on that later.
* &300-&3FF is the serial input buffer.
* &400-&47F is the internal job code call output buffer. (jobout_buf)
* &480-&4FF is the internal job code call input buffer. (jobin_buf)
* &500-&5FF is the job status table.
* &600 to the end of RAM memory is for the user. The user should not assume what the top of AVAILABLE memory is and use the system variable HIMEM.

In the controller the maximum limit of RAM is &8000 (which is 32k),
from &8000-&DFFF lies the memory mapped hardware, from &E000 to &FFF9 lies
the OS and from &FFFA to &FFFF lies the 65c02 vectors.

So the user has his own limits of free memory. The lowest limit is
called LOMEM and the highest limit is called HIMEM, everything between these
boundaries is termed "available" for use by anyone, the user or the OS.
Anyone can also claim memory, thus making private to them and not allowing
anyone else to use it. You do this by altering the value of LOMEM, HIMEM
should not be moved. Of course anyone claiming memory should first check
that there is enough memory available for the amount they want to claim for.
To take a common example, a downloadable routine which installs itself as a
extension routine, The download routine will first of all read LOMEM, read
HIMEM, check there is enough memory for the routine, download it to LOMEM
and call it, the downloaded routine will then relocate itself and alter
LOMEM so it is protected.

There is one other memory limit, this is called TOPMEM, this is the
absolute top limit of RAM, HIMEM will normally equal TOPMEM, but a future OS
may alter HIMEM to below TOPMEM. TOPMEM should be ignored ideally, and
HIMEM used.

== OS Calls ==

The OS has calls (ie. a jump instruction which you call, which
then calls, via a RAM vector, a routine in the OS) setup near the top of
memory, through these calls you do everything associated with the
controller. The calls are are such:

* OS_PRINTER at address &FFB9
* OS_CALLOS at address &FFBC
* OS_SENDBYTE at address &FFBF
* OS_READBYTE at address &FFC2
* OS_SENDJOB at address &FFC5
* OS_READJOB at address &FFC8
* OS_DECODEJOB at address &FFCB

The address is the one to call for the particular routine.

* OS_PRINTER is reserved for future use.
* OS_CALLOS calls upon the OS to do various things internally.
* OS_SENDBYTE sends a byte out of the serial port.
* OS_READBYTE reads a byte from the serial port.
* OS_SENDJOB 'sends' a value to the JobCall caller.
* OS_READJOB 'reads' a value from the JobCalls caller.
* OS_DECODEJOB decodes the Job number held in A and acts on it.

Note none of these things should be used in interupt routines,
except OS_CALLOS, of any sort, except if YOU know what state the machine is
in and WHY.

=== Serial Port ===

The serial port on the controller is currently based on the 6850
UART, this need not bother you as the OS deals with the thing entirely by
itself. The chip is setup by the OS to always have a word format of 8n1 and
a baud rate of 9600, this translates to 960cps. The 6850 has two divide
rates for the baud rate, the OS only uses one, using the other one is beyond
the scope of this document and shouldn't be neccessary to use.

Only receive interupts are used, transmission of characters is done
on a polled basis.

As said, there are two calls OS_READBYTE and OS_SENDBYTE.
OS_READBYTE tests the serial input buffer and returns the character (if any
in the A register), the c flag states whether there was a character
returned.

<nowiki> Call : OS_READBYTE
Entry : A, X, Y, c, z = undefined
Exit : X, Y preserved
z = undefined
if c = 1 (no character received)
A is preserved
if c = 0 (character received)
A = character received</nowiki>

OS_SENDBYTE sends the character in the A register out of the serial
port, taking into consideration flow control etc.

<nowiki> Call : OS_SENDBYTE
Entry : A = character to send
X, Y, c, z = undefined
Exit : A, X, Y, c is preserved
z = undefined</nowiki>

=== OS_READJOB and OS_SENDJOB ===

To send/receive data from the user (either internally or via the
serial port) you call OS_SENDJOB/OS_READJOB for the next byte. If your
JobCall requires dynamic use of data, ie. interaction, then a check of the
enviroment should be done to check the call came from the serial port. One
example of this is the OS JobCall MultipleServer, which requires dynamic use
of sending a stream of data until a reaction from the user to tell it to
stop.

<nowiki> Call : OS_READJOB
Purpose: To read job value from the user
Entry : A, X, Y, c, z = undefined
Exit : A = byte read
X, Y is preserved
c, z = undefined
Note : When coming from the serial port it waits for a character to be
received, if you are doing a serial only call and wish to have a loop
checking for a character from the user while doing "your own thing", then
OS_READBYTE should be used. For internal calls this reads data out of
jobin_buf.</nowiki>

<nowiki> Call : OS_SENDJOB
Purpose: To give a job value back to the user
Entry : A = byte to give
X, Y, c, z = undefined
Exit : A, X, Y is preserved
c, z = undefined
Note : This will send either out to the serial port or place a byte in
jobout_buf. For internal calls this stores the value in jobout_buf, which
is allocated 128 bytes, no bound checking is done so sending more than 128
bytes to OS_SENDJOB will cause corruption of some memory.</nowiki>

=== OS_DECODEJOB ===

JobCalls in practise are really only used by the user, JobCalls
tend not to call other calls at all, infact you shouldn't really call
another call unless you were called from the serial port. If you do need to
call another JobCall then you do it like this; with each call you have
associated with it a number, and the call might require some data or give
some data back or both. With the serial port this is simple, you just send
data down and receive data as it is produced. You can't do this with
internal calls, and some calls will not let you call them from inside the
controller, you HAVE to call them from outside. But for the ones which do
let you, you do it with two data blocks, one for input TO the call and one
for output FROM the call. These are setup in a position in memory
(jobin_buf and jobout_buf), each one has a maximum of 128 bytes and this
should not be overflowed (OS_READJOB and OS_SENDJOB do NOT do any bound
checking). So to start with you place in the input block the data you want
to give the call (if any), call it, and then act on the data in the output
block (if any). The OS call OS_DECODEJOB is the one which actually calls
the JobCall handler and eventually the actual routine, you tell the JobCall
handler which call you want by placing the JobCode in the A register.

So for OS_DECODEJOB:

<nowiki> Call : OS_DECODEJOB
Entry : A = JobCode
X, Y, c, z = undefined
jobin_buf should contain any input data
Exit : A = flag
X = number of bytes given back by routine
Y = undefined
c = status, if set JobCall does not exist
z = status, if set JobCall cannot be called internally
jobout_buf contains any data sent from routine</nowiki>

A typical example would be:

<nowiki> LDA #readhimem ; JobCode for ReadHimem
JSR OS_DECODEJOB ; Call the JobCall handler
LDX jobout_buf ; Read HIMEM from buffer LSB
LDY jobout_buf+1 ; Read HIMEM from buffer MSB
STX jobin_buf ; Place LSB in input buffer
STY jobin_buf+1 ; Place MSB in input buffer
LDA #writelomem ; JobCode for WriteLomem
JSR OS_DECODEJOB ; Call the JobCall handler</nowiki>

which would read HIMEM, and then write LOMEM to be the same value, leaving
no spare memory left.

The reason why you should not call an internal call from another
internal call is that the same buffers (jobin_buf and jobout_buf) would be
used for both calls, causing conflict between the two calls, or rather to
the originator of the primary call ! The only time it would be safe if is
if you have already got all the data you want from jobin_buf and haven't
placed any in the jobout_buf (it would be lost if you had done).

=== 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.

==== CALLOS : 0 ====
Purpose: Returns the OS version number
<nowiki> 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 </nowiki>

==== CALLOS : 1 ====
Purpose: To claim a block of JobCodes
<nowiki> 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.</nowiki>

==== CALLOS : 2 ====
Purpose: To handle NameCode request for the application.
<nowiki> 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</nowiki>

==== CALLOS : 3 ====
Purpose: To handle CodeName request for the application.
<nowiki> 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</nowiki>

==== CALLOS : 4 ====
Purpose: To relocate code
<nowiki> 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</nowiki>

==== CALLOS : 5 ====
Purpose: To "describe" the enviroment
<nowiki> 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 CALLOS
0 and decide what addresses/configuration to use from the Hardware version
number.</nowiki>

==== CALLOS : 6 ====
Purpose: To read a register in the VIA
<nowiki> 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.</nowiki>

==== CALLOS : 7 ====
Purpose: To write to a register in the VIA
<nowiki> 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</nowiki>

==== CALLOS : 8 ====
Purpose: To read a register in the ACIA
<nowiki> 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</nowiki>

==== CALLOS : 9 ====
Purpose: To write to a register in the ACIA
<nowiki> 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</nowiki>

==== CALLOS : 10 ====
Purpose: To read a register in the ADC
<nowiki> 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</nowiki>

==== CALLOS : 11 ====
Purpose: To write to a register in the ADC
<nowiki> 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</nowiki>

==== CALLOS : 12 ====
Purpose: To read a ADC channel
<nowiki> 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.</nowiki>

==== CALLOS : 13 ====
Purpose: To read a register in the AUX_PORT
<nowiki> 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</nowiki>

==== CALLOS : 14 (OS 2.066+) ====
Purpose: To start sensor type checking
<nowiki> 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 CALLOS 15 to check
when all the sensors have been checked.</nowiki>

==== CALLOS : 15 (OS 2.066+) ====
Purpose: To check the status of sensor checking
<nowiki> 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</nowiki>

==== CALLOS : 16 (OS 2.069+) ====
Purpose: To set the OS' irq mask for the VIA
<nowiki> 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
Note :</nowiki>

==== CALLOS : 17 (OS 2.069+) ====
Purpose: To set the OS' irq mask for the ACIA
<nowiki> 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
Note :</nowiki>

==== CALLOS : 18 (OS 2.069+) ====
Purpose: To set the OS' irq mask for the ADC
<nowiki> 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
Note :</nowiki>

==== CALLOS : 19 (OS 2.069+) ====
Purpose: To set the ACIA's ctrl register and OS' soft copy
<nowiki> 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
Note :</nowiki>

==== CALLOS : 20 (OS 2.069+) ====
Purpose: To set the reset vector for battery back RAM support
<nowiki> 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.</nowiki>

== 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.

* brk_vec at address &200
* nmi_vec at address &202
* irq_vec at address &204
* irq2_vec at address &206
* sendserial_vec at address &208
* readserial_vec at address &20A
* sendjob_vec at address &20C
* readjob_vec at address &20E
* decode_job_vec at address &210
* unknownjob_vec at address &212
* extjob_vec at address &214
* centisec_vec at address &216
* internal_vec at address &218
* callos_vec at address &21A
* printer_vec at address &21C
* reset_vec at address &21E

The brk_vec is 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.

The nmi_vec is called whenever there is a NMI request (not really
applicable, as the NMI line is not connected to anything).

The irq_vec is called whenever there is an interupt.

The irq2_vec is called whenever an unknown interupt is encountered,
ie. didn't come from the controllerXs VIA, ACIA or ADC, or the interupt
from the VIA was not used by the OS.

The sendserial_vec is called when OS_SENDBYTE is called.

The readserial_vec is called when OS_READBYTE is called.

The sendjob_vec is called when OS_SENDJOB is called.

The readjob_vec is called when OS_READJOB is called.

The decodejob_vec is 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".

The unknownjob_vec is called whenever an unknown JobCode is
encountered.

The extendedjob_vec is called whenever the ExtendedJob is called,
the A register holds the extension value.

The centisecond_vec is 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.

The internal_vec is called when some information is needed from
various parts of the system, which includes the OS whch 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.

The callos_vec is called when OS_CALLOS is called.

The printer_vec is called when OS_PRINTER is called.

The reset_vec is 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 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 isnXt 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 infact. 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 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 ====

===== Function: 0 =====
Purpose: Nothing
<nowiki> Entry : A = 0
X, Y, c, z = undefined
Exit : Leave everything as it is and exit straight away
Note : Used for claimed calls</nowiki>

===== Function: 1 =====
Purpose: NameCode request
<nowiki> 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
Note :</nowiki>

===== Function: 2 =====
Purpose: CodeName request
<nowiki> 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 Code not recognised then
A = 2
X, Y, c, z = undefined
Note :</nowiki>

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

==== unknownjob_vec ====
Purpose: To pass on unknown JobCalls to the correct owner
<nowiki> Entry : A = enviroment (0 = internal call, 1 = serial call)
Y = JobCode
X = JOB ID of owner
c, z = undefined
Exit : if jobcode yours then
if wrong enviroment then
A = 1
Y = 0
X, c, z = undefined
if right enviroment then
perform function
A = 0
Y = 0
X, c, z = undefined
if jobcode not yours then
pass on with registers unaltered
Note :</nowiki>

== Starting Up ==

The setup procedure for setting up extension job calls is to:

# Claim the number of JobCodes you want
#: if success:
# patch the internal_vec and unknownjob_vec vectors
# move LOMEM up to protect your program
# do anything else for initial startup you may want to do
# return back, ready and waiting

This in code looks like:

<nowiki>execute
LDX #no_of_calls ; Number of JobCodes wanted
LDA #1 ; CALLOS, function 1, Claim JobCodes
JSR OS_CALLOS ; Call CALLOS
CPX #0 ; Check we were given some codes
BEQ noinstall ; No, don't bother installing ourself
STX call ; Store base address of JobCodes allocated
STY job_id ; Store JOB ID given

LDA internal_vec ; Get old internal_vec (LSB)
STA ovec ; Store it
LDA internal_vec+1 ; Get old internal_vec (MSB)
STA ovec+1 ; Store it
LDA #>internal_handle ; Our internal handler (LSB)
STA internal_vec ; Place it in the vector (LSB)
LDA #<internal_handle ; Our internal handler (MSB)
STA internal_vec+1 ; Place it in the vector (MSB)

LDA unknownjob_vec ; Get old unknownjob_vec (LSB)
STA ovec2 ; Store it
LDA unknownjob_vec+1 ; Get old unknownjob_vec (MSB)
STA ovec2+1 ; Store it
LDA #>job_handle ; Our unknown job handler (LSB)
STA unknownjob_vec ; Place it in the vector (LSB)
LDA #<job_handle ; Our unknown job handler (MSB)
STA unknownjob_vec+1 ; Place it in the vector (MSB)

LDX #>WriteLomem ; Point to JobName
LDY #<WriteLomem
JSR findjob ; Find WriteLomem code
BEQ noinstall ; Doesn't exist !
LDX #>end_of_code ; End of code (LSB)
LDY #<end_of_code ; End of code (MSB)
STX jobin_buf ; Place it in jobin_buf (LSB)
STY jobin_buf+1 ; Place it in jobin_buf+1 (MSB)
JSR OS_DECODEJOB ; Call JobCall handler

noinstall
RTS ; End - return to OS

findjob
STX zero.gp1 ; Zero page
STY zero.gp1+
LDY #0
findthisjoblo
LDA (zero.gp1),Y
STA jobin.buf,Y ; Store name in jobin_buf
INY
CMP #13
BNE findthisjoblo
LDA #3 ; NameCode
JSR OS.DECODEJOB ; Call NameCode
LDA jobout.buf ; Get returned value
RTS

WriteLomem STR "WriteLomem"</nowiki>

This will setup the various vectors and memory pointers for the
applicaion, the actual routines (internal_handle and job_handle) are fairly
straight forward and simple:

<nowiki>internal_handle
CMP #1 : Is it function call 1 (NameCode) ?
BNE internal_handle_2 ; No, check for function 2
LDA job_id ; Get our JOB ID number
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #>job_names ; Our Job name table (LSB)
LDY #<job_names ; Our Job name table (MSB)
LDA #2 ; CALLOS function 2
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes : Found, go off and claim call
LDA #1 ; Not found, restore A
JMP (ovec) ; Call back to old vector

internal_handle_2
CMP #2 ; Is it function call 2 (CodeName) ?
BNE internal_handle_3 ; No, unknown, pass on
LDA job_id ; Get our JOB ID
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #>job_names ; Our Job name table (LSB)
LDY #<job_names ; Our Job name table (MSB)
LDA #3 ; CALLOS function 3
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes ; Found, go off and claim call
LDA #2 ; Not found, restore A
JMP (ovec) ; Call back to old vector

internal_yes
LDA #0 ; We want to claim call for some reason

internal_handle_3
JMP (ovec) ; Call back to old vector

job_handle
PHA ; Mark sure to preserve A
CPY call ; Check call wanted against base of ours
BCC job_handle_no ; Less than our base, so definately not ours
TYA
SBC #no_of_calls ; Subtract number of calls we have
CMP call ; Now compare with base
BCC job_handle2 ; Yes, one of ours

job_handle.no
PLA ; Restore A
JMP (ovec2) ; Call back to old vector

job_handle2
TYA
SEC
SBC call ; Subtract our base from call
ASL A ; Times by 2 for offset into table
TAY ; Place in Y
LDA job_run_table,Y ; Get LSB of routine
STA zero_gp1 ; Store it for indirect jump (LSB)
LDA job_run_table+1,Y ; Get MSB of routine
STA zero_gp1+1 ; Store it for indirect jump (MSB)
PLA ; Restore A
JMP (zero_gp1) ; Call our relevant routine

job_names ; List of our JobNames
STR "TestJob" ; Test job name
DFB &FF ; &FF - marks end of table

job_run_table ; List of routine addresses to match Jobs
DFW job_TestJob ; Test job routine</nowiki>

== Relocation ==

The relocation method used will not do a complete relocation, ie.
from ANY address to ANY address. The only constraint on the addresses is
that they must be the same offset in the page, which means, &2602 and &3402
is alright but &2602 and &3455 is not, ie. the difference between the two
addresses must be a multiple of 256 bytes, as only the MSB is altered, this
should not cause any real problems. What is meant by the two addresses is
the address the code was originally assembled at and the address it wants
relocating to. Because of this programs must be multiples of 256 bytes, ie.
the low byte of LOMEM must ALWAYS be 0, your program should be padded out.

The relocation mechanism works by having a table, and to each byte
of code there is one BIT, if unset it means the byte of code should not be
relocated, else it should be, thus the BitMap table is 8 times smaller than
the code. To generate the BitMap you have to assemble the code at two
different places, and compare both sets of assembled code against each
other, the differences are where the code is to be relocated. The code
which is sent up to the controller is assumed to be assembled at address
&100, so the first code should be assembled at &100, the other one should be
assembled at another address, say &600, and the first one be sent up with
the BitMap. A program is availble for the Elk/Beeb/Arc with 65Tube/Mac with
BBC BASIC to compare the two files and create the BitMap.

All the program has to do to relocate itself is execute this bit of
code first of all: (address is the base address of the program, ie. &100
for the downloaded version)

<nowiki>execcall
LDA #>(execute-address) ; Final execution address offset (LSB)
STA zero_gp1
LDA #<(execute-address) ; Final execution address offset (MSB)
STA zero_gp1+1

LDA #>(BitMap-address) ; BitMap address offset (LSB)
STA zero_gp2
LDA #<(BitMap-address) ; BitMap address offset (MSB)
STA zero_gp2+1

LDA #>(execcall-address); Length of data to relocate (LSB)
STA zero_gp3
LDA #<(execcall-address); Length of data to relocate (MSB)
STA zero_gp3+1

TXA ; Execcall REAL address
SEC
SBC #>(execcall-address); Subrtract length
TAX ; Put it back in X
TYA ; Ditto for MSB
SBC #<(execcall-address)
TAY
LDA #4 ; CALLOS function for Relocate
JMP OS_CALLOS ; Call CALLOS

BitMap ; BitMap start</nowiki>

This will relocate the code and automatically call the execution
address, which should be the initialisation code (ie. setup internal_vec
and unknownjob_vec etc.). "address" is the address the code is started to
assemble at, &100 for the version to be uploaded. The upload routine should
pass in X and Y (via ExecuteCode) the address of the start of execcall, this
means that the routine can tell where it is in memory, subtracting the
length gives the start of the code to relocate.

== Layout Summary ==

The layout of a full application should be like this by now:

<nowiki> start of code
program job codes, data etc.
internal handler
job handler
end of code
initialisation (setup internal etc.)
end of code to be relocated
execution (relocation)
relocation BitMap</nowiki>

Because of memory space the initialisation code should be placed
outside the reserved memory limit of the program, as it is only called once
and not needed again.

== Other miscellaneous calls ==

<nowiki>Call : OS_PRINTER
Purpose : To place a character in the printer buffer
Entry : A = character to send
X, Y, c, z = undefined
Exit : A, X, Y is preserved
if c = 0 (printed)
The printer is on and the character was inserted
if c = 1 (not printed)
The printer is off and the character was forgotten
z = undefined
Note : The character goes into the printer buffer and will be
actually sent to the printer when the printer asks for it. If the printer
was not awake to begin with, an attempt is made to wake it up, thus
meaning that in some circumstances when the printer wasn't ready a
character may be lost, this cannot be helped. If the printer is off (via
the BCD switch) then the character will be forgotten as the Printer Buffer
is inactive.</nowiki>

The module is located at &8000 in memory, and should be a EPROM placed
in the second ROM socket in the controller (ie. the top RAM socket). This
module is primary designed to turn the Controller into a dedicated task,
making it perform some function from switch on. It could also be used to
add more permant JobCalls to the Controller, in the process taking up much
less RAM), but because of there being only one Module present this feature
is limited, and is much more suited to a collection of the user's own
personal routines.

For the OS to recognise a module as being in place the text "Module" is
looked for, the layout of a module should be like this (starting at
&8000):

<nowiki>Offset value comment
0 "Module" The OS checks for this string
6 0 End of check string
7 Language entry Address of 'Language' entry
9 Service entry Address of 'Service' entry
11 "<Module Title>" Module title
0 End of Module title

"<Module part>" Part Module Title
0 End of Part Module Title
"x.xx" Part version number

&FF End of parts list</nowiki>

The language entry is a 2 byte value holding the address of the language
entry routine, this is called on reset, if the BCD is set correctly. A
value of less than &8000 means there is no valid language entry and any
language calls are ignored. If a RTS is made the OS carries on as it would
have if there wasn't a language call.

The service entry is a 2 byte value holding the address of the service
entry routine, this is called at various appropiate moments with service
numbers in A. A list of current calls is thus:

<nowiki> 0 - Not used
1 - Unknown Job Code
2 - Centisecond call
3 - Irq2 (unknown IRQ)
4 - internal_vec call (exit with A=0 to claim)
254 - RESET
255 - BRK</nowiki>

On exit all registers and flags should be preserved. For call 1 the
unknown job value is held in the Y register, the enviroment is held in the
X register, on exit, X should contain the flag, as A does from the exit of
unknownjob_vec. For the rest of calls, X and Y are undefined.

For both Service and Language entry points, a value of 0 means "there is
no valid routine" and the module isn't called for that type of entry.

Finally a full implementation of a JobCall, from start to finish.

<nowiki> DIM data% &1000
:
no_of_calls = 1
:
VIA = &E030
ACIA = &E010
ADC = &E000
AUX_PORT = &E020
brk_vec = &200
nmi_vec = &202
irq_vec = &204
irq2_vec = &206
sendserial_vec = &208
readserial_vec = &20A
sendjob_vec = &20C
readjob_vec = &20E
decodejob_vec = &210
unknownjob_vec = &212
extjob_vec = &214
centisec_vec = &216
internal_vec = &218
callos_vec = &21A
printer_vec = &21C
zero_gp1 = 0
zero_gp2 = 2
zero_gp3 = 4
zero_gp4 = 6
zero_gp5 = 8
zero_gp6 = 10
zero_gp7 = 12
zero_gp8 = 14
zero_gp9 = 16
zero_gp10 = 18
user_reserved = &70
irq_A = &A0
fcount = &A1
RAM_size = &A3
jobout_buf = &400
jobin_buf = &480
OS_PRINTER = &FFB9
OS_CALLOS = &FFBC
OS_SENDBYTE = &FFBF
OS_READBYTE = &FFC2
OS_SENDJOB = &FFC5
OS_READJOB = &FFC8
OS_DECODEJOB = &FFCB
:
FOR create=1 TO 2
:
FOR pass%=4 TO 7 STEP 3
P%=&100*create : O%=data%
[OPT pass%
:
.job_DemoJob
CMP #1
BEQ DemoJob_go
LDA #1
LDY #0
RTS
/
.DemoJob_go

:
.internal_handle
CMP #1 ; Is it function call 1 (NameCode) ?
BNE internal_handle_2 ; No, check for function 2
/
LDA job_id ; Get our JOB ID number
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #job_names MOD 256 ; Our Job name table (LSB)
LDY #job_names DIV 256 ; Our Job name table (MSB)
LDA #2 ; CALLOS function 2
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes ; Found, go off and claim call
LDA #1 ; Not found, restore A
JMP (ovec) ; Call back to old vector
/
.internal_handle_2
CMP #2 ; Is it function call 2 (CodeName) ?
BNE internal_handle_3 ; No, unknown, pass on
/
LDA job_id ; Get our JOB ID
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #job_names MOD 256 ; Our Job name table (LSB)
LDY #job_names DIV 256 ; Our Job name table (MSB)
LDA #3 ; CALLOS function 3
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes ; Found, go off and claim call
LDA #2 ; Not found, restore A
JMP (ovec) ; Call back to old vector
/
.internal_yes
LDA #0 ; We want to claim call for some reason
/
.internal_handle_3
JMP (ovec) ; Call back to old vector
:
.job_handle
PHA ; Make sure to preserve A
CPY call ; Check call wanted against base of ours
BCC job_handle_no ; Less than our base, so definately not ours
TYA
SBC #no_of_calls ; Subtract number of calls we have
CMP call ; Now compare with base
BCC job_handle2 ; Yes, one of ours
/
.job_handle.no
PLA ; Restore A
JMP (ovec2) ; Call back to old vector
/
.job_handle2
TYA
SEC
SBC call ; Subtract our base from call
ASL A ; Times by 2 for offset into table
TAY ; Place in Y
LDA job_run_table,Y ; Get LSB of routine
STA zero_gp1 ; Store it for indirect jump (LSB)
LDA job_run_table+1,Y ; Get MSB of routine
STA zero_gp1+1 ; Store it for indirect jump (MSB)
PLA ; Restore A
JMP (zero_gp1) ; Call our relevant routine
:
.job_names ; List of our JobNames
EQUS "DemoJob":EQUB 13 ; Test job name
/
EQUB &FF ; &FF - marks end of table
:
.job_run_table ; List of routine addresses to match Jobs
EQUW job_DemoJob ; Test job routine
:
.call : EQUB 0 ; Store for our JobCode base
.job_id : EQUB 0 ; Store for our JobId
.ovec : EQUW 0 ; Store for old internal_vec value
.ovec2 : EQUW 0 ; Store for old unknownjob_vec value
:
EQUS STRING$(&100-(P% MOD 256),CHR$0)
.end_of_code ; end_of_code should be on page boundry
:
.execute
LDX #no_of_calls ; Number of JobCodes wanted
LDA #1 ; CALLOS, function 1, Claim JobCodes
JSR OS_CALLOS ; Call CALLOS
STX call ; Store base address of JobCodes allocated
STY job_id ; Store JOB ID given
CPX #0 ; Check we were given some codes
BEQ noinstall ; No, don't bother installing ourself
/
LDA internal_vec ; Get old internal_vec (LSB)
STA ovec ; Store it
LDA internal_vec+1 ; Get old internal_vec (MSB)
STA ovec+1 ; Store it
LDA #internal_handle MOD 256 ; Our internal handler (LSB)
STA internal_vec ; Place it in the vector (LSB)
LDA #internal_handle DIV 256 ; Our internal handler (MSB)
STA internal_vec+1 ; Place it in the vector (MSB)
/
LDA unknownjob_vec ; Get old unknownjob_vec (LSB)
STA ovec2 ; Store it
LDA unknownjob_vec+1 ; Get old unknownjob_vec (MSB)
STA ovec2+1 ; Store it
LDA #job_handle MOD 256 ; Our unknown job handler (LSB)
STA unknownjob_vec ; Place it in the vector (LSB)
LDA #job_handle DIV 256 ; Our unknown job handler (MSB)
STA unknownjob_vec+1 ; Place it in the vector (MSB)
/
LDX #end_of_code MOD 256 ; End of code (LSB)
LDY #end_of_code DIV 256 ; End of code (MSB)
STX jobin_buf ; Place it in jobin_buf (LSB)
STY jobin_buf+1 ; Place it in jobin_buf+1 (MSB)
LDA #65 ; JobCode for WriteLomem
JSR OS_DECODEJOB ; Call JobCall handler
/
.noinstall
RTS ; End - return to OS
:
.execcall
LDA #>(execute-address) ; Final execution address offset (LSB)
STA zero_gp1
LDA #<(execute-address) ; Final execution address offset (MSB)
STA zero_gp1+1
/
LDA #>(BitMap-address) ; BitMap address offset (LSB)
STA zero_gp2
LDA #<(BitMap-address) ; BitMap address offset (MSB)
STA zero_gp2+1
/
LDA #>(execcall-address) ; Length of data to relocate (LSB)
STA zero_gp3
LDA #<(execcall-address) ; Length of data to relocate (MSB)
STA zero_gp3+1
/
TXA ; Execcall REAL address
SEC
SBC #>(execcall-address) ; Subrtract length
TAX ; Put it back in X
TYA ; Ditto for MSB
SBC #<(execcall-address)
TAY
LDA #4 ; CALLOS function for Relocate
JMP OS_CALLOS ; Call CALLOS
/
.BitMap ; BitMap start
:
]
NEXT
:
OSCLI "SAVE code"+STR$create+" "+STR$~data%+" "+STR$~O%
:
NEXT</nowiki>

== Changelog ==

<nowiki>bob 071 Fixed MotorForward bug (%10)
bob 072 CallOS 14 now checks current adc.owner status
jim 072.d1 * Rewrite for new hardware/processor *
jim 072.d1 Moved vectors/workspace to &440
jim 072.d1 Moved rs.inp.buf to &500
jim 072.d1 Moved jobout.buf to &600
jim 072.d1 Moved jobin.buf to &680
jim 072.d1 Moved jobs.status to &700
jim 072.d1 Added irq.X (&A4)
jim 072.d1 Added irq.Y (&A5)
jim 072.d1 Removed short detection code
jim 072.d1 Voided CallOS' 6,7,8,9,10,11,13,16,17,18,19
jim 072.d1 Removed JobCalls ReadADCReg,WriteADCReg
jim 072.d1 Removed JobCalls ReadACIAReg,WriteACIAReg
jim 072.d1 Removed JobCalls ReadVIAReg,WriteVIAReg,SetVIAHigh,SetVIALow
jim 072.d1 Added CallOS 21 Write Outputs
jim 072.d1 Added CallOS 22 Read Outputs added
jim 072.d1 Added CallOS 23 Read Inputs added
jim 072.d1 Added CallOS 24 Write Motors
jim 072.d1 Added CallOS 25 Read Motors
jim 072.d1 Added CallOS 26 Read Keypad
jim 072.d1 Expanded CallOS 5 information
jim 072.d1 Added JobCall IdentSystem to return CallOS 5 info
jim 072.d1 JobCalls now use appropriate CallOS'
jim 072.d1 OS.READBYTE no longer preserves A on CS
jim 072.d1 irq.vec,irq2.vec,nmi.vec now redundant
jim 072.d1 Renamed JobCall DownloadData to DownloadData38
jim 072.d1 Renamed JobCall UploadData to UploadData38
jim 072.d1 Renamed JobCall ExecuteCode to ExecuteCode38
jim 072.d1 Renamed JobCall ReadByte to ReadByte38
jim 072.d1 Renamed JobCall StoreByte to StoreByte38
jim 072.d1 JobCall ForcedADCRead now checks adc.owner first
jim 072.d3 Added CallOS 27 Write printer
jim 072.d3 Added CallOS 28 Read printer
jim 072.d3 Added CallOS 29 Write RTC Reg
jim 072.d3 Added CallOS 30 Read RTC Reg
jim 072.d3 Added CallOS 31 Write RTC string
jim 072.d3 Added CallOS 32 Read RTC string
jim 072.d3 Added CallOS 33 Write RTC bcd
jim 072.d3 Added CallOS 34 Read RTC bcd
jim 072.d3 Added CallOS 35 Write LCD Reg
jim 072.d3 Added CallOS 36 Read LCD Reg
jim 072.d3 Added JobCall WritePrinter
jim 072.d3 Added JobCall ReadPrinter
jim 072.d3 Added JobCall PrintChar
jim 072.d3 Added JobCall PrintStreamZ
jim 072.d3 Added JobCall PrintStream
jim 072.d3 Added JobCall PrintServer
jim 072.d3 Added JobCall WriteRTCReg
jim 072.d3 Added JobCall ReadRTCReg
jim 072.d3 Added JobCall WriteRTC
jim 072.d3 Added JobCall ReadRTC
jim 072.d3 Added JobCall WriteRTCbcd
jim 072.d3 Added JobCall ReadRTCbcd
jim 072.d3 Added JobCall WriteLCDReg
jim 072.d3 Added JobCall ReadLCDReg
jim 072.d3 Added CallOS 37 Write Power ctrl
jim 072.d3 Added CallOS 38 Read Power ctrl
jim 072.d3 Implemented OS.PRINTER
jim 072.d3 Added JobCall PatchMF (MotorForward)
jim 072.d3 Changed irq.vec to int0.vec
jim 072.d3 Changed irq2.vec to int1.vec
jim 072.d3 Added int2irq.vec (wrksp+&20)
jim 072.d3 Added int3irq.vec (wrksp+&22)
jim 072.d3 Added int4irq.vec (wrksp+&24)
jim 072.d3 Added c0irq.vec (wrksp+&26)
jim 072.d3 Added c1irq.vec (wrksp+&28)
jim 072.d3 Added t1irq.vec (wrksp+&2A)
jim 072.d3 Added t2irq.vec (wrksp+&2C)
jim 072.d3 Added txirq.vec (wrksp+&2E)
jim 072.d3 Added tyirq.vec (wrksp+&30)
jim 072.d3 Added s1rirq.vec (wrksp+&32)
jim 072.d3 Added s1rirq.vec (wrksp+&34)
jim 072.d3 Added s2irq.vec (wrksp+&36)
jim 072.d3 Added adcirq.vec (wrksp+&38)
jim 072.d3 Renamed JobCall DownloadData38 to DownloadData740
jim 072.d3 Renamed JobCall UploadData38 to UploadData740
jim 072.d3 Renamed JobCall ExecuteCode38 to ExecuteCode740
jim 072.d3 Renamed JobCall ReadByte38 to ReadByte740
jim 072.d3 Renamed JobCall StoreByte38 to StoreByte740
jim 072.d4 Hardware update
jim 072.d4 Re-assigned CallOS 37 to Write Power/Charge control
jim 072.d4 Re-assigned CallOS 38 to Read Power/Charge control
jim 072.d4 Moved int2irq.vec to wrksp+&22
jim 072.d4 Moved int3irq.vec to wrksp+&24
jim 072.d4 Moved int4irq.vec to wrksp+&26
jim 072.d4 Moved c0irq.vec to wrksp+&28
jim 072.d4 Moved c1irq.vec to wrksp+&2A
jim 072.d4 Moved t1irq.vec to wrksp+&2C
jim 072.d4 Moved t2irq.vec to wrksp+&2E
jim 072.d4 Moved txirq.vec to wrksp+&30
jim 072.d4 Moved tyirq.vec to wrksp+&32
jim 072.d4 Moved s1rirq.vec to wrksp+&34
jim 072.d4 Moved s1rirq.vec to wrksp+&36
jim 072.d4 Moved s2irq.vec to wrksp+&38
jim 072.d4 Moved adcirq.vec to wrksp+&3A
jim 072.d4 Added OS.LCDVDU (&FFB7) and lcdvdu.vec (wrksp+&20)
jim 072.d5 Re-assigned CallOS 37 to Write/Read Power/Charge control
jim 072.d5 Re-assgined CallOS 38 Read Battery Voltage
jim 072.d5 OS.CALLOS now re-entrant
jim 072.d5 Fixed OS.PRINTER
jim 072.d5 Started to add internal logging software
jim 072.d5 Moved OS.LCDVDU to &FFB6
jim 072.d7 Added OS.PRINTERPOLL (&FFB3) and printerpoll.vec (wrksp+&3C)
bob 073 Matched jim & bob sensor lookup tables
bob 073 Added PatchMF
jim 072.dj Added OS.CALLOS 51 Read keypad press
jim 072.dj Added hard reset keypad press
jim 072.dk Added JobCall ReadOutputs
jim 072.do Changed soft reset of zero page locations
jim 072.do Changed MotorForward/Backward bitmaps
jim 072.dp Fixed OS.CALLOS WriteRTCbcd
jim 072.dq Fixed OS.CALLOS ReadRTCstring for correct 24hr operation
jim 072.dr Changed reset prompts
bob 074 Added support for Little Bob
jim 072.dy Added further RTC/CMOS support
jim 072.dB Removed double hard reset
jim 072.dE Set _cpu.mode depending on external memory requirement
jim 072.dF Added Insight code
jim 073 Sub-release
jim 074 Modification to LCD code - uses bsy flag all the time now
jim 074 Fixed OS.CALLOS 42 Write LCD Char Def
jim 074 Fixed OS.CALLOS 43 Read LCD Char Def
jim 075 Added simple battery charge code
jim 075 Fixed JobCall ReadSensorTable
jim 075 Fixed OS.CALLOS 42 Write LCD Char Def
jim 075 Fixed OS.CALLOS 43 Read LCD Char Def
jim 075 Added sleep code
jim 075 Added OS.CALLOS 52 Write Sleep Time
jim 075 Added OS.CALLOS 53 Read Sleep Time
jim 075 Modified battery charge code
jim 076 Modified JobCall ReadSensorTable
jim 076 Modified OS.CALLOS 26 ReadKeypad to do debounce
jim 077 Rewrote battery charging code
jim 077.2 Reduced stop charge threshold to 2
jim 077.3 Increased stop charge threshold to 3
jim 077.3 Added battery voltage averaging
bill 077 Stripped
bill 077 Moved ins to out port
bill 077 Added RTS
bill 077 Changed sensor ID system back to original, using p2.1
bill 077 Dedicated USB/RS selection line, RTS provisioned on p2.3
bill 077 Overload "bounce" timing
bill 078 CTS added
bill 079 Temperature fudge</nowiki>

SmartBox OS

2023-11-03T22:10:51Z

Benryves: Moved changelog below the documentation

<nowiki> Documentation for SmartBox OS 2.066

The term JobCall is the concept of the routine itself, as opposed to
JobName (which is the actual name associated with it (eg. NameCode)) and
JobCode (which is the actual number associated with it (eg. 3)).

The term controller means the SmartBox, or any other incarnation
which may appear in future time !

The term OS means the controllers' Operating System.

Preview

There are a number of reasons why using Machine Code on the
controller is more desirable than using the various JobCalls via the serial
link. One reason is speed, if the task which needs to be performed, has to
be performed very quickly (more quickly than can be achieved via the serial
link at least), then some code must be written to work in the controller
itself to achieve this sort of speed. If the task required is to be a
"background" task (ie. a task which may happen while other "things" carry
on as normal, like a change of state of a particular port) then it is far
easier to let the controller do all the work, maybe under interupts, than
continuously poll the controller checking the state of various things.
Another reason may be that you would like to add another JobCall to the OS,
extending the calls available to external applications (and the user at the
same time), without the user having to write the code himself to achieve the
aim. For advanced users, there is also the ablity to alter the way the OS
does various things and to have the controller in their "power", for
dedicated tasks etc.

One advantage of writing IN the controller is that that "function"
is available to any computer using the serial link, and is thus not fixed to
one computer type or even a computer at all, where the controller is used
free running, doing a particular task which doesn't need the intervention of
the user's own computer.

Call types

There are three different types of machine code routines which can
be added to the controller. Each one is suited to a more advanced level
than the other, which also relates to the amount of work needed to actually
get the routine working ! The three levels are such:

a) Simple stand alone routine. Here the routine is just the routine
itself with no supporting code (ie. code to integrate with the rest of the
OS). It has to be called directly, by use of the ExecuteCode JobCall, thus
it usually resides at a fixed address and obviously does not offer the user
friendly way of accessing itself like there is with normal OS calls.

b) Extended JobCall. There is one JobCall in the OS (ExtendJob)
which can call various routines residing in memory, each one is identified
by a 8 bit number. The disadvantages of this way is that the call hasn't
got it's own JobName/JobCode and needs the extra byte to identify itself.
This is ideal for the quick routine which the user would like to add for
himself without having to resort to the extra code needed for the full
JobCode implementation.

c) Full JobCall. This is where the routine can define itself one
(or a number) of JobNames/JobCodes, it can integrate itself into an
extension of the OS in a complete way. The disadvantage is that extra
coding is needed to deal with the various OS calls it has to service and
that extra work is needed to produce a suitable file to place in the
controller.

Normally with most processors, including the 65c02, the machine code
produced is produced for a fixed memory address, and it cannot be made to
run in a different place in memory unless extra work is carried out by the
user, or at least a combination of the user and the OS. For the controller
this is a very severe disadvantage as most extensions are downloaded as
"modules" and to optimise memory a system has to be devised to enable
routines to be placed anywhere in memory, thus allowing no memory to be
wasted. In the OS there is a routine to do just this, though it does need
some help. A special version of the users code has to be developed, or
rather it has to be "processed" to add extra information on the end. Extra
code is needed to set up a few pointers and call the OS routine to relocate.
See later.

Memory

The first 256 bytes of memory are somewhat special, most zero page
locations are reserved for use by the OS:

0 General workspace, used to pass parameters to some OS
routines, can also be used by other routines DURING
14 their execution.
15 Reserved
6f
70 Available to the user
9f
a0 Accumulator store for irqs (irq_A)
a1 Two byte counter, decremented at 100hz, useful for temporary
a2 timing purposes (fcount)
a3 RAM size, high byte of RAM size of machine, ie. for 32k
this will be &80 (RAM_size)
a4 Reserved
af
b0 Used by the OS
ff

The rest of memory space is used for the processors stack, OS'
buffers, tables, vectors and, of course, the user available memory.

A breakdown of the rest of memory:

&100 to &1FF is the 65c02's stack.

&200-&2FF is used by the OS for various system functions and also
contains the vector table, more on that later.

&300-&3FF is the serial input buffer.

&400-&47F is the internal job code call output buffer. (jobout_buf)

&480-&4FF is the internal job code call input buffer. (jobin_buf)

&500-&5FF is the job status table.

&600 to the end of RAM memory is for the user. The user should not
assume what the top of AVAILABLE memory is and use the
system variable HIMEM.

In the controller the maximum limit of RAM is &8000 (which is 32k),
from &8000-&DFFF lies the memory mapped hardware, from &E000 to &FFF9 lies
the OS and from &FFFA to &FFFF lies the 65c02 vectors.

So the user has his own limits of free memory. The lowest limit is
called LOMEM and the highest limit is called HIMEM, everything between these
boundaries is termed "available" for use by anyone, the user or the OS.
Anyone can also claim memory, thus making private to them and not allowing
anyone else to use it. You do this by altering the value of LOMEM, HIMEM
should not be moved. Of course anyone claiming memory should first check
that there is enough memory available for the amount they want to claim for.
To take a common example, a downloadable routine which installs itself as a
extension routine, The download routine will first of all read LOMEM, read
HIMEM, check there is enough memory for the routine, download it to LOMEM
and call it, the downloaded routine will then relocate itself and alter
LOMEM so it is protected.

There is one other memory limit, this is called TOPMEM, this is the
absolute top limit of RAM, HIMEM will normally equal TOPMEM, but a future OS
may alter HIMEM to below TOPMEM. TOPMEM should be ignored ideally, and
HIMEM used.

OS Calls

The OS has calls (ie. a jump instruction which you call, which
then calls, via a RAM vector, a routine in the OS) setup near the top of
memory, through these calls you do everything associated with the
controller. The calls are are such:

OS_PRINTER at address &FFB9
OS_CALLOS at address &FFBC
OS_SENDBYTE at address &FFBF
OS_READBYTE at address &FFC2
OS_SENDJOB at address &FFC5
OS_READJOB at address &FFC8
OS_DECODEJOB at address &FFCB

The address is the one to call for the particular routine.

OS_PRINTER is reserved for future use.
OS_CALLOS calls upon the OS to do various things internally.
OS_SENDBYTE sends a byte out of the serial port.
OS_READBYTE reads a byte from the serial port.
OS_SENDJOB 'sends' a value to the JobCall caller.
OS_READJOB 'reads' a value from the JobCalls caller.
OS_DECODEJOB decodes the Job number held in A and acts on it.

Note none of these things should be used in interupt routines,
except OS_CALLOS, of any sort, except if YOU know what state the machine is
in and WHY.

Serial Port

The serial port on the controller is currently based on the 6850
UART, this need not bother you as the OS deals with the thing entirely by
itself. The chip is setup by the OS to always have a word format of 8n1 and
a baud rate of 9600, this translates to 960cps. The 6850 has two divide
rates for the baud rate, the OS only uses one, using the other one is beyond
the scope of this document and shouldn't be neccessary to use.

Only receive interupts are used, transmission of characters is done
on a polled basis.

As said, there are two calls OS_READBYTE and OS_SENDBYTE.
OS_READBYTE tests the serial input buffer and returns the character (if any
in the A register), the c flag states whether there was a character
returned.

Call : OS_READBYTE
Entry : A, X, Y, c, z = undefined
Exit : X, Y preserved
z = undefined
if c = 1 (no character received)
A is preserved
if c = 0 (character received)
A = character received

OS_SENDBYTE sends the character in the A register out of the serial
port, taking into consideration flow control etc.

Call : OS_SENDBYTE
Entry : A = character to send
X, Y, c, z = undefined
Exit : A, X, Y, c is preserved
z = undefined

OS_READJOB and OS_SENDJOB

To send/receive data from the user (either internally or via the
serial port) you call OS_SENDJOB/OS_READJOB for the next byte. If your
JobCall requires dynamic use of data, ie. interaction, then a check of the
enviroment should be done to check the call came from the serial port. One
example of this is the OS JobCall MultipleServer, which requires dynamic use
of sending a stream of data until a reaction from the user to tell it to
stop.

Call : OS_READJOB
Purpose: To read job value from the user
Entry : A, X, Y, c, z = undefined
Exit : A = byte read
X, Y is preserved
c, z = undefined
Note : When coming from the serial port it waits for a character to be
received, if you are doing a serial only call and wish to have a loop
checking for a character from the user while doing "your own thing", then
OS_READBYTE should be used. For internal calls this reads data out of
jobin_buf.

Call : OS_SENDJOB
Purpose: To give a job value back to the user
Entry : A = byte to give
X, Y, c, z = undefined
Exit : A, X, Y is preserved
c, z = undefined
Note : This will send either out to the serial port or place a byte in
jobout_buf. For internal calls this stores the value in jobout_buf, which
is allocated 128 bytes, no bound checking is done so sending more than 128
bytes to OS_SENDJOB will cause corruption of some memory.

OS_DECODEJOB

JobCalls in practise are really only used by the user, JobCalls
tend not to call other calls at all, infact you shouldn't really call
another call unless you were called from the serial port. If you do need to
call another JobCall then you do it like this; with each call you have
associated with it a number, and the call might require some data or give
some data back or both. With the serial port this is simple, you just send
data down and receive data as it is produced. You can't do this with
internal calls, and some calls will not let you call them from inside the
controller, you HAVE to call them from outside. But for the ones which do
let you, you do it with two data blocks, one for input TO the call and one
for output FROM the call. These are setup in a position in memory
(jobin_buf and jobout_buf), each one has a maximum of 128 bytes and this
should not be overflowed (OS_READJOB and OS_SENDJOB do NOT do any bound
checking). So to start with you place in the input block the data you want
to give the call (if any), call it, and then act on the data in the output
block (if any). The OS call OS_DECODEJOB is the one which actually calls
the JobCall handler and eventually the actual routine, you tell the JobCall
handler which call you want by placing the JobCode in the A register.

So for OS_DECODEJOB:

Call : OS_DECODEJOB
Entry : A = JobCode
X, Y, c, z = undefined
jobin_buf should contain any input data
Exit : A = flag
X = number of bytes given back by routine
Y = undefined
c = status, if set JobCall does not exist
z = status, if set JobCall cannot be called internally
jobout_buf contains any data sent from routine

A typical example would be:

LDA #readhimem ; JobCode for ReadHimem
JSR OS_DECODEJOB ; Call the JobCall handler
LDX jobout_buf ; Read HIMEM from buffer LSB
LDY jobout_buf+1 ; Read HIMEM from buffer MSB
STX jobin_buf ; Place LSB in input buffer
STY jobin_buf+1 ; Place MSB in input buffer
LDA #writelomem ; JobCode for WriteLomem
JSR OS_DECODEJOB ; Call the JobCall handler

which would read HIMEM, and then write LOMEM to be the same value, leaving
no spare memory left.

The reason why you should not call an internal call from another
internal call is that the same buffers (jobin_buf and jobout_buf) would be
used for both calls, causing conflict between the two calls, or rather to
the originator of the primary call ! The only time it would be safe if is
if you have already got all the data you want from jobin_buf and haven't
placed any in the jobout_buf (it would be lost if you had done).

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.

CALLOS : 0
Purpose: Returns the OS version number
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

CALLOS : 1
Purpose: To claim a block of JobCodes
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.

CALLOS : 2
Purpose: To handle NameCode request for the application.
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

CALLOS : 3
Purpose: To handle CodeName request for the application.
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

CALLOS : 4
Purpose: To relocate code
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

CALLOS : 5
Purpose: To "describe" the enviroment
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 CALLOS
0 and decide what addresses/configuration to use from the Hardware version
number.

CALLOS : 6
Purpose: To read a register in the VIA
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.

CALLOS : 7
Purpose: To write to a register in the VIA
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

CALLOS : 8
Purpose: To read a register in the ACIA
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

CALLOS : 9
Purpose: To write to a register in the ACIA
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

CALLOS : 10
Purpose: To read a register in the ADC
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

CALLOS : 11
Purpose: To write to a register in the ADC
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

CALLOS : 12
Purpose: To read a ADC channel
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.

CALLOS : 13
Purpose: To read a register in the AUX_PORT
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

CALLOS : 14 (OS 2.066+)
Purpose: To start sensor type checking
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 CALLOS 15 to check
when all the sensors have been checked.

CALLOS : 15 (OS 2.066+)
Purpose: To check the status of sensor checking
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

CALLOS : 16 (OS 2.069+)
Purpose: To set the OS' irq mask for the VIA
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
Note :

CALLOS : 17 (OS 2.069+)
Purpose: To set the OS' irq mask for the ACIA
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
Note :

CALLOS : 18 (OS 2.069+)
Purpose: To set the OS' irq mask for the ADC
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
Note :

CALLOS : 19 (OS 2.069+)
Purpose: To set the ACIA's ctrl register and OS' soft copy
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
Note :

CALLOS : 20 (OS 2.069+)
Purpose: To set the reset vector for battery back RAM support
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.

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.

brk_vec at address &200
nmi_vec at address &202
irq_vec at address &204
irq2_vec at address &206
sendserial_vec at address &208
readserial_vec at address &20A
sendjob_vec at address &20C
readjob_vec at address &20E
decode_job_vec at address &210
unknownjob_vec at address &212
extjob_vec at address &214
centisec_vec at address &216
internal_vec at address &218
callos_vec at address &21A
printer_vec at address &21C
reset_vec at address &21E

The brk_vec is 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.
The nmi_vec is called whenever there is a NMI request (not really
applicable, as the NMI line is not connected to anything).
The irq_vec is called whenever there is an interupt.
The irq2_vec is called whenever an unknown interupt is encountered,
ie. didnXt come from the controllerXs VIA, ACIA or ADC, or the interupt
from the VIA was not used by the OS.
The sendserial_vec is called when OS_SENDBYTE is called.
The readserial_vec is called when OS_READBYTE is called.
The sendjob_vec is called when OS_SENDJOB is called.
The readjob_vec is called when OS_READJOB is called.
The decodejob_vec is 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".
The unknownjob_vec is called whenever an unknown JobCode is
encountered.
The extendedjob_vec is called whenever the ExtendedJob is called,
the A register holds the extension value.
The centisecond_vec is 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.
The internal_vec is called when some information is needed from
various parts of the system, which includes the OS whch 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.
The callos_vec is called when OS_CALLOS is called.
The printer_vec is called when OS_PRINTER is called.
The reset_vec is 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 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 isnXt 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 infact. 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 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

Function: 0
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

Function: 1
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
Note :

Function: 2
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 Code not recognised then
A = 2
X, Y, c, z = undefined
Note :

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

unknownjob_vec

Purpose: To pass on unknown JobCalls to the correct owner
Entry : A = enviroment (0 = internal call, 1 = serial call)
Y = JobCode
X = JOB ID of owner
c, z = undefined
Exit : if jobcode yours then
if wrong enviroment then
A = 1
Y = 0
X, c, z = undefined
if right enviroment then
perform function
A = 0
Y = 0
X, c, z = undefined
if jobcode not yours then
pass on with registers unaltered
Note :

Starting Up

The setup procedure for setting up extension job calls is to:

a) Claim the number of JobCodes you want
if success:
b) patch the internal_vec and unknownjob_vec vectors
c) move LOMEM up to protect your program
d) do anything else for initial startup you may want to do
e) return back, ready and waiting

This in code looks like:

execute
LDX #no_of_calls ; Number of JobCodes wanted
LDA #1 ; CALLOS, function 1, Claim JobCodes
JSR OS_CALLOS ; Call CALLOS
CPX #0 ; Check we were given some codes
BEQ noinstall ; No, don�t bother installing ourself
STX call ; Store base address of JobCodes allocated
STY job_id ; Store JOB ID given

LDA internal_vec ; Get old internal_vec (LSB)
STA ovec ; Store it
LDA internal_vec+1 ; Get old internal_vec (MSB)
STA ovec+1 ; Store it
LDA #>internal_handle ; Our internal handler (LSB)
STA internal_vec ; Place it in the vector (LSB)
LDA #<internal_handle ; Our internal handler (MSB)
STA internal_vec+1 ; Place it in the vector (MSB)

LDA unknownjob_vec ; Get old unknownjob_vec (LSB)
STA ovec2 ; Store it
LDA unknownjob_vec+1 ; Get old unknownjob_vec (MSB)
STA ovec2+1 ; Store it
LDA #>job_handle ; Our unknown job handler (LSB)
STA unknownjob_vec ; Place it in the vector (LSB)
LDA #<job_handle ; Our unknown job handler (MSB)
STA unknownjob_vec+1 ; Place it in the vector (MSB)

LDX #>WriteLomem ; Point to JobName
LDY #<WriteLomem
JSR findjob ; Find WriteLomem code
BEQ noinstall ; Doesn't exist !
LDX #>end_of_code ; End of code (LSB)
LDY #<end_of_code ; End of code (MSB)
STX jobin_buf ; Place it in jobin_buf (LSB)
STY jobin_buf+1 ; Place it in jobin_buf+1 (MSB)
JSR OS_DECODEJOB ; Call JobCall handler

noinstall
RTS ; End - return to OS

findjob
STX zero.gp1 ; Zero page
STY zero.gp1+
LDY #0
findthisjoblo
LDA (zero.gp1),Y
STA jobin.buf,Y ; Store name in jobin_buf
INY
CMP #13
BNE findthisjoblo
LDA #3 ; NameCode
JSR OS.DECODEJOB ; Call NameCode
LDA jobout.buf ; Get returned value
RTS

WriteLomem STR "WriteLomem"

This will setup the various vectors and memory pointers for the
applicaion, the actual routines (internal_handle and job_handle) are fairly
straight forward and simple:

internal_handle
CMP #1 : Is it function call 1 (NameCode) ?
BNE internal_handle_2 ; No, check for function 2
LDA job_id ; Get our JOB ID number
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #>job_names ; Our Job name table (LSB)
LDY #<job_names ; Our Job name table (MSB)
LDA #2 ; CALLOS function 2
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes : Found, go off and claim call
LDA #1 ; Not found, restore A
JMP (ovec) ; Call back to old vector

internal_handle_2
CMP #2 ; Is it function call 2 (CodeName) ?
BNE internal_handle_3 ; No, unknown, pass on
LDA job_id ; Get our JOB ID
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #>job_names ; Our Job name table (LSB)
LDY #<job_names ; Our Job name table (MSB)
LDA #3 ; CALLOS function 3
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes ; Found, go off and claim call
LDA #2 ; Not found, restore A
JMP (ovec) ; Call back to old vector

internal_yes
LDA #0 ; We want to claim call for some reason

internal_handle_3
JMP (ovec) ; Call back to old vector

job_handle
PHA ; Mark sure to preserve A
CPY call ; Check call wanted against base of ours
BCC job_handle_no ; Less than our base, so definately not ours
TYA
SBC #no_of_calls ; Subtract number of calls we have
CMP call ; Now compare with base
BCC job_handle2 ; Yes, one of ours

job_handle.no
PLA ; Restore A
JMP (ovec2) ; Call back to old vector

job_handle2
TYA
SEC
SBC call ; Subtract our base from call
ASL A ; Times by 2 for offset into table
TAY ; Place in Y
LDA job_run_table,Y ; Get LSB of routine
STA zero_gp1 ; Store it for indirect jump (LSB)
LDA job_run_table+1,Y ; Get MSB of routine
STA zero_gp1+1 ; Store it for indirect jump (MSB)
PLA ; Restore A
JMP (zero_gp1) ; Call our relevant routine

job_names ; List of our JobNames
STR "TestJob" ; Test job name
DFB &FF ; &FF - marks end of table

job_run_table ; List of routine addresses to match Jobs
DFW job_TestJob ; Test job routine

Relocation

The relocation method used will not do a complete relocation, ie.
from ANY address to ANY address. The only constraint on the addresses is
that they must be the same offset in the page, which means, &2602 and &3402
is alright but &2602 and &3455 is not, ie. the difference between the two
addresses must be a multiple of 256 bytes, as only the MSB is altered, this
should not cause any real problems. What is meant by the two addresses is
the address the code was originally assembled at and the address it wants
relocating to. Because of this programs must be multiples of 256 bytes, ie.
the low byte of LOMEM must ALWAYS be 0, your program should be padded out.

The relocation mechanism works by having a table, and to each byte
of code there is one BIT, if unset it means the byte of code should not be
relocated, else it should be, thus the BitMap table is 8 times smaller than
the code. To generate the BitMap you have to assemble the code at two
different places, and compare both sets of assembled code against each
other, the differences are where the code is to be relocated. The code
which is sent up to the controller is assumed to be assembled at address
&100, so the first code should be assembled at &100, the other one should be
assembled at another address, say &600, and the first one be sent up with
the BitMap. A program is availble for the Elk/Beeb/Arc with 65Tube/Mac with
BBC BASIC to compare the two files and create the BitMap.

All the program has to do to relocate itself is execute this bit of
code first of all: (address is the base address of the program, ie. &100
for the downloaded version)

execcall
LDA #>(execute-address) ; Final execution address offset (LSB)
STA zero_gp1
LDA #<(execute-address) ; Final execution address offset (MSB)
STA zero_gp1+1

LDA #>(BitMap-address) ; BitMap address offset (LSB)
STA zero_gp2
LDA #<(BitMap-address) ; BitMap address offset (MSB)
STA zero_gp2+1

LDA #>(execcall-address); Length of data to relocate (LSB)
STA zero_gp3
LDA #<(execcall-address); Length of data to relocate (MSB)
STA zero_gp3+1

TXA ; Execcall REAL address
SEC
SBC #>(execcall-address); Subrtract length
TAX ; Put it back in X
TYA ; Ditto for MSB
SBC #<(execcall-address)
TAY
LDA #4 ; CALLOS function for Relocate
JMP OS_CALLOS ; Call CALLOS

BitMap ; BitMap start

This will relocate the code and automatically call the execution
address, which should be the initialisation code (ie. setup internal_vec
and unknownjob_vec etc.). "address" is the address the code is started to
assemble at, &100 for the version to be uploaded. The upload routine should
pass in X and Y (via ExecuteCode) the address of the start of execcall, this
means that the routine can tell where it is in memory, subtracting the
length gives the start of the code to relocate.

Layout Summary

The layout of a full application should be like this by now:

start of code
program job codes, data etc.
internal handler
job handler
end of code
initialisation (setup internal etc.)
end of code to be relocated
execution (relocation)
relocation BitMap

Because of memory space the initialisation code should be placed
outside the reserved memory limit of the program, as it is only called once
and not needed again.

Other miscellaneous calls:

Call : OS_PRINTER
Purpose : To place a character in the printer buffer
Entry : A = character to send
X, Y, c, z = undefined
Exit : A, X, Y is preserved
if c = 0 (printed)
The printer is on and the character was inserted
if c = 1 (not printed)
The printer is off and the character was forgotten
z = undefined
Note : The character goes into the printer buffer and will be
actually sent to the printer when the printer asks for it. If the printer
was not awake to begin with, an attempt is made to wake it up, thus
meaning that in some circumstances when the printer wasn't ready a
character may be lost, this cannot be helped. If the printer is off (via
the BCD switch) then the character will be forgotten as the Printer Buffer
is inactive.

The module is located at &8000 in memory, and should be a EPROM placed
in the second ROM socket in the controller (ie. the top RAM socket). This
module is primary designed to turn the Controller into a dedicated task,
making it perform some function from switch on. It could also be used to
add more permant JobCalls to the Controller, in the process taking up much
less RAM), but because of there being only one Module present this feature
is limited, and is much more suited to a collection of the user's own
personal routines.
For the OS to recognise a module as being in place the text "Module" is
looked for, the layout of a module should be like this (starting at
&8000):

Offset value comment
0 "Module" The OS checks for this string
6 0 End of check string
7 Language entry Address of 'Language' entry
9 Service entry Address of 'Service' entry
11 "<Module Title>" Module title
0 End of Module title

"<Module part>" Part Module Title
0 End of Part Module Title
"x.xx" Part version number

&FF End of parts list

The language entry is a 2 byte value holding the address of the language
entry routine, this is called on reset, if the BCD is set correctly. A
value of less than &8000 means there is no valid language entry and any
language calls are ignored. If a RTS is made the OS carries on as it would
have if there wasn't a language call.

The service entry is a 2 byte value holding the address of the service
entry routine, this is called at various appropiate moments with service
numbers in A. A list of current calls is thus:

0 - Not used
1 - Unknown Job Code
2 - Centisecond call
3 - Irq2 (unknown IRQ)
4 - internal_vec call (exit with A=0 to claim)
254 - RESET
255 - BRK

On exit all registers and flags should be preserved. For call 1 the
unknown job value is held in the Y register, the enviroment is held in the
X register, on exit, X should contain the flag, as A does from the exit of
unknownjob_vec. For the rest of calls, X and Y are undefined.

For both Service and Language entry points, a value of 0 means "there is
no valid routine" and the module isn't called for that type of entry.

Finally a full implementation of a JobCall, from start to finish.

DIM data% &1000
:
no_of_calls = 1
:
VIA = &E030
ACIA = &E010
ADC = &E000
AUX_PORT = &E020
brk_vec = &200
nmi_vec = &202
irq_vec = &204
irq2_vec = &206
sendserial_vec = &208
readserial_vec = &20A
sendjob_vec = &20C
readjob_vec = &20E
decodejob_vec = &210
unknownjob_vec = &212
extjob_vec = &214
centisec_vec = &216
internal_vec = &218
callos_vec = &21A
printer_vec = &21C
zero_gp1 = 0
zero_gp2 = 2
zero_gp3 = 4
zero_gp4 = 6
zero_gp5 = 8
zero_gp6 = 10
zero_gp7 = 12
zero_gp8 = 14
zero_gp9 = 16
zero_gp10 = 18
user_reserved = &70
irq_A = &A0
fcount = &A1
RAM_size = &A3
jobout_buf = &400
jobin_buf = &480
OS_PRINTER = &FFB9
OS_CALLOS = &FFBC
OS_SENDBYTE = &FFBF
OS_READBYTE = &FFC2
OS_SENDJOB = &FFC5
OS_READJOB = &FFC8
OS_DECODEJOB = &FFCB
:
FOR create=1 TO 2
:
FOR pass%=4 TO 7 STEP 3
P%=&100*create : O%=data%
[OPT pass%
:
.job_DemoJob
CMP #1
BEQ DemoJob_go
LDA #1
LDY #0
RTS
/
.DemoJob_go

:
.internal_handle
CMP #1 ; Is it function call 1 (NameCode) ?
BNE internal_handle_2 ; No, check for function 2
/
LDA job_id ; Get our JOB ID number
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #job_names MOD 256 ; Our Job name table (LSB)
LDY #job_names DIV 256 ; Our Job name table (MSB)
LDA #2 ; CALLOS function 2
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes ; Found, go off and claim call
LDA #1 ; Not found, restore A
JMP (ovec) ; Call back to old vector
/
.internal_handle_2
CMP #2 ; Is it function call 2 (CodeName) ?
BNE internal_handle_3 ; No, unknown, pass on
/
LDA job_id ; Get our JOB ID
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #job_names MOD 256 ; Our Job name table (LSB)
LDY #job_names DIV 256 ; Our Job name table (MSB)
LDA #3 ; CALLOS function 3
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes ; Found, go off and claim call
LDA #2 ; Not found, restore A
JMP (ovec) ; Call back to old vector
/
.internal_yes
LDA #0 ; We want to claim call for some reason
/
.internal_handle_3
JMP (ovec) ; Call back to old vector
:
.job_handle
PHA ; Make sure to preserve A
CPY call ; Check call wanted against base of ours
BCC job_handle_no ; Less than our base, so definately not ours
TYA
SBC #no_of_calls ; Subtract number of calls we have
CMP call ; Now compare with base
BCC job_handle2 ; Yes, one of ours
/
.job_handle.no
PLA ; Restore A
JMP (ovec2) ; Call back to old vector
/
.job_handle2
TYA
SEC
SBC call ; Subtract our base from call
ASL A ; Times by 2 for offset into table
TAY ; Place in Y
LDA job_run_table,Y ; Get LSB of routine
STA zero_gp1 ; Store it for indirect jump (LSB)
LDA job_run_table+1,Y ; Get MSB of routine
STA zero_gp1+1 ; Store it for indirect jump (MSB)
PLA ; Restore A
JMP (zero_gp1) ; Call our relevant routine
:
.job_names ; List of our JobNames
EQUS "DemoJob":EQUB 13 ; Test job name
/
EQUB &FF ; &FF - marks end of table
:
.job_run_table ; List of routine addresses to match Jobs
EQUW job_DemoJob ; Test job routine
:
.call : EQUB 0 ; Store for our JobCode base
.job_id : EQUB 0 ; Store for our JobId
.ovec : EQUW 0 ; Store for old internal_vec value
.ovec2 : EQUW 0 ; Store for old unknownjob_vec value
:
EQUS STRING$(&100-(P% MOD 256),CHR$0)
.end_of_code ; end_of_code should be on page boundry
:
.execute
LDX #no_of_calls ; Number of JobCodes wanted
LDA #1 ; CALLOS, function 1, Claim JobCodes
JSR OS_CALLOS ; Call CALLOS
STX call ; Store base address of JobCodes allocated
STY job_id ; Store JOB ID given
CPX #0 ; Check we were given some codes
BEQ noinstall ; No, don't bother installing ourself
/
LDA internal_vec ; Get old internal_vec (LSB)
STA ovec ; Store it
LDA internal_vec+1 ; Get old internal_vec (MSB)
STA ovec+1 ; Store it
LDA #internal_handle MOD 256 ; Our internal handler (LSB)
STA internal_vec ; Place it in the vector (LSB)
LDA #internal_handle DIV 256 ; Our internal handler (MSB)
STA internal_vec+1 ; Place it in the vector (MSB)
/
LDA unknownjob_vec ; Get old unknownjob_vec (LSB)
STA ovec2 ; Store it
LDA unknownjob_vec+1 ; Get old unknownjob_vec (MSB)
STA ovec2+1 ; Store it
LDA #job_handle MOD 256 ; Our unknown job handler (LSB)
STA unknownjob_vec ; Place it in the vector (LSB)
LDA #job_handle DIV 256 ; Our unknown job handler (MSB)
STA unknownjob_vec+1 ; Place it in the vector (MSB)
/
LDX #end_of_code MOD 256 ; End of code (LSB)
LDY #end_of_code DIV 256 ; End of code (MSB)
STX jobin_buf ; Place it in jobin_buf (LSB)
STY jobin_buf+1 ; Place it in jobin_buf+1 (MSB)
LDA #65 ; JobCode for WriteLomem
JSR OS_DECODEJOB ; Call JobCall handler
/
.noinstall
RTS ; End - return to OS
:
.execcall
LDA #>(execute-address) ; Final execution address offset (LSB)
STA zero_gp1
LDA #<(execute-address) ; Final execution address offset (MSB)
STA zero_gp1+1
/
LDA #>(BitMap-address) ; BitMap address offset (LSB)
STA zero_gp2
LDA #<(BitMap-address) ; BitMap address offset (MSB)
STA zero_gp2+1
/
LDA #>(execcall-address) ; Length of data to relocate (LSB)
STA zero_gp3
LDA #<(execcall-address) ; Length of data to relocate (MSB)
STA zero_gp3+1
/
TXA ; Execcall REAL address
SEC
SBC #>(execcall-address) ; Subrtract length
TAX ; Put it back in X
TYA ; Ditto for MSB
SBC #<(execcall-address)
TAY
LDA #4 ; CALLOS function for Relocate
JMP OS_CALLOS ; Call CALLOS
/
.BitMap ; BitMap start
:
]
NEXT
:
OSCLI "SAVE code"+STR$create+" "+STR$~data%+" "+STR$~O%
:
NEXT</nowiki>

== Changelog ==

<nowiki>bob 071 Fixed MotorForward bug (%10)
bob 072 CallOS 14 now checks current adc.owner status
jim 072.d1 * Rewrite for new hardware/processor *
jim 072.d1 Moved vectors/workspace to &440
jim 072.d1 Moved rs.inp.buf to &500
jim 072.d1 Moved jobout.buf to &600
jim 072.d1 Moved jobin.buf to &680
jim 072.d1 Moved jobs.status to &700
jim 072.d1 Added irq.X (&A4)
jim 072.d1 Added irq.Y (&A5)
jim 072.d1 Removed short detection code
jim 072.d1 Voided CallOS' 6,7,8,9,10,11,13,16,17,18,19
jim 072.d1 Removed JobCalls ReadADCReg,WriteADCReg
jim 072.d1 Removed JobCalls ReadACIAReg,WriteACIAReg
jim 072.d1 Removed JobCalls ReadVIAReg,WriteVIAReg,SetVIAHigh,SetVIALow
jim 072.d1 Added CallOS 21 Write Outputs
jim 072.d1 Added CallOS 22 Read Outputs added
jim 072.d1 Added CallOS 23 Read Inputs added
jim 072.d1 Added CallOS 24 Write Motors
jim 072.d1 Added CallOS 25 Read Motors
jim 072.d1 Added CallOS 26 Read Keypad
jim 072.d1 Expanded CallOS 5 information
jim 072.d1 Added JobCall IdentSystem to return CallOS 5 info
jim 072.d1 JobCalls now use appropriate CallOS'
jim 072.d1 OS.READBYTE no longer preserves A on CS
jim 072.d1 irq.vec,irq2.vec,nmi.vec now redundant
jim 072.d1 Renamed JobCall DownloadData to DownloadData38
jim 072.d1 Renamed JobCall UploadData to UploadData38
jim 072.d1 Renamed JobCall ExecuteCode to ExecuteCode38
jim 072.d1 Renamed JobCall ReadByte to ReadByte38
jim 072.d1 Renamed JobCall StoreByte to StoreByte38
jim 072.d1 JobCall ForcedADCRead now checks adc.owner first
jim 072.d3 Added CallOS 27 Write printer
jim 072.d3 Added CallOS 28 Read printer
jim 072.d3 Added CallOS 29 Write RTC Reg
jim 072.d3 Added CallOS 30 Read RTC Reg
jim 072.d3 Added CallOS 31 Write RTC string
jim 072.d3 Added CallOS 32 Read RTC string
jim 072.d3 Added CallOS 33 Write RTC bcd
jim 072.d3 Added CallOS 34 Read RTC bcd
jim 072.d3 Added CallOS 35 Write LCD Reg
jim 072.d3 Added CallOS 36 Read LCD Reg
jim 072.d3 Added JobCall WritePrinter
jim 072.d3 Added JobCall ReadPrinter
jim 072.d3 Added JobCall PrintChar
jim 072.d3 Added JobCall PrintStreamZ
jim 072.d3 Added JobCall PrintStream
jim 072.d3 Added JobCall PrintServer
jim 072.d3 Added JobCall WriteRTCReg
jim 072.d3 Added JobCall ReadRTCReg
jim 072.d3 Added JobCall WriteRTC
jim 072.d3 Added JobCall ReadRTC
jim 072.d3 Added JobCall WriteRTCbcd
jim 072.d3 Added JobCall ReadRTCbcd
jim 072.d3 Added JobCall WriteLCDReg
jim 072.d3 Added JobCall ReadLCDReg
jim 072.d3 Added CallOS 37 Write Power ctrl
jim 072.d3 Added CallOS 38 Read Power ctrl
jim 072.d3 Implemented OS.PRINTER
jim 072.d3 Added JobCall PatchMF (MotorForward)
jim 072.d3 Changed irq.vec to int0.vec
jim 072.d3 Changed irq2.vec to int1.vec
jim 072.d3 Added int2irq.vec (wrksp+&20)
jim 072.d3 Added int3irq.vec (wrksp+&22)
jim 072.d3 Added int4irq.vec (wrksp+&24)
jim 072.d3 Added c0irq.vec (wrksp+&26)
jim 072.d3 Added c1irq.vec (wrksp+&28)
jim 072.d3 Added t1irq.vec (wrksp+&2A)
jim 072.d3 Added t2irq.vec (wrksp+&2C)
jim 072.d3 Added txirq.vec (wrksp+&2E)
jim 072.d3 Added tyirq.vec (wrksp+&30)
jim 072.d3 Added s1rirq.vec (wrksp+&32)
jim 072.d3 Added s1rirq.vec (wrksp+&34)
jim 072.d3 Added s2irq.vec (wrksp+&36)
jim 072.d3 Added adcirq.vec (wrksp+&38)
jim 072.d3 Renamed JobCall DownloadData38 to DownloadData740
jim 072.d3 Renamed JobCall UploadData38 to UploadData740
jim 072.d3 Renamed JobCall ExecuteCode38 to ExecuteCode740
jim 072.d3 Renamed JobCall ReadByte38 to ReadByte740
jim 072.d3 Renamed JobCall StoreByte38 to StoreByte740
jim 072.d4 Hardware update
jim 072.d4 Re-assigned CallOS 37 to Write Power/Charge control
jim 072.d4 Re-assigned CallOS 38 to Read Power/Charge control
jim 072.d4 Moved int2irq.vec to wrksp+&22
jim 072.d4 Moved int3irq.vec to wrksp+&24
jim 072.d4 Moved int4irq.vec to wrksp+&26
jim 072.d4 Moved c0irq.vec to wrksp+&28
jim 072.d4 Moved c1irq.vec to wrksp+&2A
jim 072.d4 Moved t1irq.vec to wrksp+&2C
jim 072.d4 Moved t2irq.vec to wrksp+&2E
jim 072.d4 Moved txirq.vec to wrksp+&30
jim 072.d4 Moved tyirq.vec to wrksp+&32
jim 072.d4 Moved s1rirq.vec to wrksp+&34
jim 072.d4 Moved s1rirq.vec to wrksp+&36
jim 072.d4 Moved s2irq.vec to wrksp+&38
jim 072.d4 Moved adcirq.vec to wrksp+&3A
jim 072.d4 Added OS.LCDVDU (&FFB7) and lcdvdu.vec (wrksp+&20)
jim 072.d5 Re-assigned CallOS 37 to Write/Read Power/Charge control
jim 072.d5 Re-assgined CallOS 38 Read Battery Voltage
jim 072.d5 OS.CALLOS now re-entrant
jim 072.d5 Fixed OS.PRINTER
jim 072.d5 Started to add internal logging software
jim 072.d5 Moved OS.LCDVDU to &FFB6
jim 072.d7 Added OS.PRINTERPOLL (&FFB3) and printerpoll.vec (wrksp+&3C)
bob 073 Matched jim & bob sensor lookup tables
bob 073 Added PatchMF
jim 072.dj Added OS.CALLOS 51 Read keypad press
jim 072.dj Added hard reset keypad press
jim 072.dk Added JobCall ReadOutputs
jim 072.do Changed soft reset of zero page locations
jim 072.do Changed MotorForward/Backward bitmaps
jim 072.dp Fixed OS.CALLOS WriteRTCbcd
jim 072.dq Fixed OS.CALLOS ReadRTCstring for correct 24hr operation
jim 072.dr Changed reset prompts
bob 074 Added support for Little Bob
jim 072.dy Added further RTC/CMOS support
jim 072.dB Removed double hard reset
jim 072.dE Set _cpu.mode depending on external memory requirement
jim 072.dF Added Insight code
jim 073 Sub-release
jim 074 Modification to LCD code - uses bsy flag all the time now
jim 074 Fixed OS.CALLOS 42 Write LCD Char Def
jim 074 Fixed OS.CALLOS 43 Read LCD Char Def
jim 075 Added simple battery charge code
jim 075 Fixed JobCall ReadSensorTable
jim 075 Fixed OS.CALLOS 42 Write LCD Char Def
jim 075 Fixed OS.CALLOS 43 Read LCD Char Def
jim 075 Added sleep code
jim 075 Added OS.CALLOS 52 Write Sleep Time
jim 075 Added OS.CALLOS 53 Read Sleep Time
jim 075 Modified battery charge code
jim 076 Modified JobCall ReadSensorTable
jim 076 Modified OS.CALLOS 26 ReadKeypad to do debounce
jim 077 Rewrote battery charging code
jim 077.2 Reduced stop charge threshold to 2
jim 077.3 Increased stop charge threshold to 3
jim 077.3 Added battery voltage averaging
bill 077 Stripped
bill 077 Moved ins to out port
bill 077 Added RTS
bill 077 Changed sensor ID system back to original, using p2.1
bill 077 Dedicated USB/RS selection line, RTS provisioned on p2.3
bill 077 Overload "bounce" timing
bill 078 CTS added
bill 079 Temperature fudge</nowiki>

SmartBox AlbertLink

2023-11-01T04:39:58Z

Benryves: Created page with " <nowiki>AlbertLink Link Protocol (Release 11) Startup After AL has been downloaded and called the first thing back will be a engine release number (one byte), and known setup flags (one byte) which you should check that the "new" flags you want are set. If the engine number is wrong or the setup flags you want aren't set then send a 0 and AlbertLink will quit itself, else send ANYTHING but a 0. Then send your setup flags (one byte), which will engage the various "ne..."

<nowiki>AlbertLink Link Protocol (Release 11)

Startup

After AL has been downloaded and called the first thing back will be a engine release number (one byte), and known setup flags (one byte) which you should check that the "new" flags you want are set. If the engine number is wrong or the setup flags you want aren't set then send a 0 and AlbertLink will quit itself, else send ANYTHING but a 0. Then send your setup flags (one byte), which will engage the various "new" options.

ie:
send jobcode for AlbertLink >
< engine number
< known setup flags
flag for continue or not >
setup flags wanted >

Setup Flags

The 8 setup flags are setup as such:
bit if set
0 use new trace system
1 enable procedure/label change checking
2 enable custom commands
3 enable prompt
4 shit computer
5 enable "get" line count

Idle

At this point the system is idling, both ends are waiting to originate a "event" or receive one.

The remote end should check the serial port as often as possible, if it detects a byte then it should read it, check it is in range, and transmit a 0 (byte) back, then it should do one of the following "event" types according to the byte it received:

File 1 +byte +string
note byte = channel reference (1 to 10)
note string = file name
note the file should then be opened and a FileBack event made or a
Error event, to signal a error

Close 2 +byte
note byte = channel reference

Store 3 +byte +data (terminated by NUL)
note byte = channel reference
note data = data to put to file

Trace old:
4 +string
note string = string to print
new:
4 +string +double byte
note string = procedure name
note double byte = line number
return byte
note byte = flag
: 0, no stepping
: 1, wait for tracecont

Print 5 +[characters terminated by NUL, CR expand to CRLF]
note do not CRLF after this, keep cursor position

Error 6 +string +string2 +string3 (to change)
note string = procedure name (blank if from cmd line)
note string2 = error
note string3 = line containing error (blank if from cmd line)

Ask 7 +byte
note byte = 'S', 'N' or 'T' (input type)
return use AskBack to return input string

Inkey 8
return byte = 0 -> no key, #0 -> key value

Cmd 9
note this means that command mode is ready

Build 10 +string
note string = proc to edit

Edit 11 +string
note string = proc to edit

Quit 12
note user has typed QUIT, use Quit to quit system

TraceFl 13 +byte
note byte = trace flag (0 -> off, #0 -> on)

Load 14 +string
note string = filename
note use Put
note use Error for filing errors
note string can be blank

Save 15 +string +string2
note string = filename
note string2 = procedure to save (or blank for all)
note use Error for filing errors
note use Get/List to get procedures

Control 16 +byte
note byte = control parameter, if out of range, return 0 and then
use Error
return byte
note byte = value of control option

Rtc 17
return byte +byte2 +byte3 +byte4
note byte = hours
note byte2 = minutes
note byte3 = seconds
note byte4 = centiseconds
note cause Error AFTER returning 0 for all if not supported.

Printer 18
note as Print

Altered 19 +byte
note byte = flag
bit 0 : procedure list changed
bit 1 : labels changed
note when you get this you should use List and/or ReadLabels to
update yourself

Custom 20 +data (NUL terminated)

Custom2 21 +data (NUL terminated)

Customfn 22 +string
return byte
note byte = fn value

Prompt 23 +string
note string = prompt string

NB: "string" is a group of characters terminated by CR.

Any other codes should be ignored.

Remote "events"

The remote end also has "events" which it can originate, to start an event, transmit the "event" code and wait until you receive a 0 (byte), ignore all other bytes received (the remote end has priority) and then you can transmit any other bytes needed:

Setup 1 +byte
note byte = setup byte
note as startup setup flag

List 2
return [string .....] until string is blank
note this returns a list of procedures terminated by a blank

NameCode 3 +string
note *NB* doesn't return normal link 0 acknowledge.
note Emulates the normal OS NameCode, quiting AlbertLink if the
remote doesn't try to check for AlbertLink and going out
of sleep if it does try for AlbertLink

Get 4 +byte +string
note byte = flag
0 : do not use labels
1 : use labels
255 : use LBLS setting
old:
return byte = 0 -> no such procedure else procedure terminated by 0ffh
new:
return byte = 0 -> no such procedure
1 +byte2 +byte3 +procedure -> procedure found
note byte2/3 is number of lines in procedure

Put 5 +string +[procedure strings terminated by 0ffh]
return byte = 0 -> ok, 1 -> bad name, 2 -) no room 3 -> bad data

Escape 6
note causes escape condition

Quit 7
note causes AlbertLink to quit

Cmd 8 +string
note performs a raw command, use only after flagged cmd ready else
any running procedure will be stopped

GetPorts 9
return byte = run mode (1 = running procedure)
byte = inputs
byte = outputs
byte = motors
byte = adc 1
byte = adc 2
byte = adc 3
byte = adc 4
byte = clock (hours)
byte = clock
byte = clock
byte = clock (cs)

GetPS 10
return data as GetPorts
return byte = sensor a id
byte = sensor b id
byte = sensor c id
byte = sensor d id
note perform once a second or so to re-check the sensors

SteadyLine 11 +byte +string
note byte = flag
0 : do not use labels
1 : use labels
255 : use LBLS setting
return string = expanded line
note use in editor to expanded abbreviated commands

TraceFl 12 +byte
note byte = new trace setting and causes Trace "events"

SetPort 13 +byte +byte2
note byte = bits to set
note byte2 = bits to mask

Error 14 +string
note string = error to cause

Version 15
return string = version string

Sleep 16
note causes AlbertLink to sleep the remote link, waking up with a
normal AlbertLink startup

CheckSensors 17
return byte = sensor a id
byte = sensor b id
byte = sensor c id
byte = sensor d id

AskBack 18 +string
note string = input line

ReadLabels 19
return [+string1 (+string2) .......]
note string1 = source label
note string2 = label (not sent if string1 is blank)
note string2 terminated by 0 for hard label and 128 for soft label
note end of list terminated by string1 being blank

WriteLabel 20 +string1 +string2 +byte
note string1 = source label
note string2 = label
note byte = flag
: 0, hard label
: 1, soft label
return byte
note byte = flag
: 0, okay
: 1, bad source label
: 2, bad label
: 3, label too long
: 4, label exists as a procedure
: 5, can't overwrite hard label with a soft label

FreeMem 21
return byte +byte2
note byte/2 = free memory

TraceCont 22
note this causes procedure execution to continue from a stopped trace

Clock 23 +byte
note byte = flag
: 0, stop clock
: 1, start clock
: 2, reset clock

PromptBack 24
note send this when the user has clicked on the "prompt"

FileBack 25 +byte
note byte = flag
: 0, cannot open file
: 1, file opened
note used in reply to File

Print, Trace, SteadyLine, Get and Error surround any tokens with 1 to start token and 2 to finish token. Put and SteadyLine will remove them automatically before processing.</nowiki>

SmartBox OS

2023-11-01T04:39:15Z

Benryves: Created page with "== Changelog == <nowiki>bob 071 Fixed MotorForward bug (%10) bob 072 CallOS 14 now checks current adc.owner status jim 072.d1 * Rewrite for new hardware/processor * jim 072.d1 Moved vectors/workspace to &440 jim 072.d1 Moved rs.inp.buf to &500 jim 072.d1 Moved jobout.buf to &600 jim 072.d1 Moved jobin.buf to &680 jim 072.d1 Moved jobs.status to &700 jim 072.d1 Added irq.X (&A4) jim 072.d1 Added irq.Y (&A5) jim 072.d1 Removed short detection code jim 072.d1 Voided CallO..."

== Changelog ==

<nowiki>bob 071 Fixed MotorForward bug (%10)
bob 072 CallOS 14 now checks current adc.owner status
jim 072.d1 * Rewrite for new hardware/processor *
jim 072.d1 Moved vectors/workspace to &440
jim 072.d1 Moved rs.inp.buf to &500
jim 072.d1 Moved jobout.buf to &600
jim 072.d1 Moved jobin.buf to &680
jim 072.d1 Moved jobs.status to &700
jim 072.d1 Added irq.X (&A4)
jim 072.d1 Added irq.Y (&A5)
jim 072.d1 Removed short detection code
jim 072.d1 Voided CallOS' 6,7,8,9,10,11,13,16,17,18,19
jim 072.d1 Removed JobCalls ReadADCReg,WriteADCReg
jim 072.d1 Removed JobCalls ReadACIAReg,WriteACIAReg
jim 072.d1 Removed JobCalls ReadVIAReg,WriteVIAReg,SetVIAHigh,SetVIALow
jim 072.d1 Added CallOS 21 Write Outputs
jim 072.d1 Added CallOS 22 Read Outputs added
jim 072.d1 Added CallOS 23 Read Inputs added
jim 072.d1 Added CallOS 24 Write Motors
jim 072.d1 Added CallOS 25 Read Motors
jim 072.d1 Added CallOS 26 Read Keypad
jim 072.d1 Expanded CallOS 5 information
jim 072.d1 Added JobCall IdentSystem to return CallOS 5 info
jim 072.d1 JobCalls now use appropriate CallOS'
jim 072.d1 OS.READBYTE no longer preserves A on CS
jim 072.d1 irq.vec,irq2.vec,nmi.vec now redundant
jim 072.d1 Renamed JobCall DownloadData to DownloadData38
jim 072.d1 Renamed JobCall UploadData to UploadData38
jim 072.d1 Renamed JobCall ExecuteCode to ExecuteCode38
jim 072.d1 Renamed JobCall ReadByte to ReadByte38
jim 072.d1 Renamed JobCall StoreByte to StoreByte38
jim 072.d1 JobCall ForcedADCRead now checks adc.owner first
jim 072.d3 Added CallOS 27 Write printer
jim 072.d3 Added CallOS 28 Read printer
jim 072.d3 Added CallOS 29 Write RTC Reg
jim 072.d3 Added CallOS 30 Read RTC Reg
jim 072.d3 Added CallOS 31 Write RTC string
jim 072.d3 Added CallOS 32 Read RTC string
jim 072.d3 Added CallOS 33 Write RTC bcd
jim 072.d3 Added CallOS 34 Read RTC bcd
jim 072.d3 Added CallOS 35 Write LCD Reg
jim 072.d3 Added CallOS 36 Read LCD Reg
jim 072.d3 Added JobCall WritePrinter
jim 072.d3 Added JobCall ReadPrinter
jim 072.d3 Added JobCall PrintChar
jim 072.d3 Added JobCall PrintStreamZ
jim 072.d3 Added JobCall PrintStream
jim 072.d3 Added JobCall PrintServer
jim 072.d3 Added JobCall WriteRTCReg
jim 072.d3 Added JobCall ReadRTCReg
jim 072.d3 Added JobCall WriteRTC
jim 072.d3 Added JobCall ReadRTC
jim 072.d3 Added JobCall WriteRTCbcd
jim 072.d3 Added JobCall ReadRTCbcd
jim 072.d3 Added JobCall WriteLCDReg
jim 072.d3 Added JobCall ReadLCDReg
jim 072.d3 Added CallOS 37 Write Power ctrl
jim 072.d3 Added CallOS 38 Read Power ctrl
jim 072.d3 Implemented OS.PRINTER
jim 072.d3 Added JobCall PatchMF (MotorForward)
jim 072.d3 Changed irq.vec to int0.vec
jim 072.d3 Changed irq2.vec to int1.vec
jim 072.d3 Added int2irq.vec (wrksp+&20)
jim 072.d3 Added int3irq.vec (wrksp+&22)
jim 072.d3 Added int4irq.vec (wrksp+&24)
jim 072.d3 Added c0irq.vec (wrksp+&26)
jim 072.d3 Added c1irq.vec (wrksp+&28)
jim 072.d3 Added t1irq.vec (wrksp+&2A)
jim 072.d3 Added t2irq.vec (wrksp+&2C)
jim 072.d3 Added txirq.vec (wrksp+&2E)
jim 072.d3 Added tyirq.vec (wrksp+&30)
jim 072.d3 Added s1rirq.vec (wrksp+&32)
jim 072.d3 Added s1rirq.vec (wrksp+&34)
jim 072.d3 Added s2irq.vec (wrksp+&36)
jim 072.d3 Added adcirq.vec (wrksp+&38)
jim 072.d3 Renamed JobCall DownloadData38 to DownloadData740
jim 072.d3 Renamed JobCall UploadData38 to UploadData740
jim 072.d3 Renamed JobCall ExecuteCode38 to ExecuteCode740
jim 072.d3 Renamed JobCall ReadByte38 to ReadByte740
jim 072.d3 Renamed JobCall StoreByte38 to StoreByte740
jim 072.d4 Hardware update
jim 072.d4 Re-assigned CallOS 37 to Write Power/Charge control
jim 072.d4 Re-assigned CallOS 38 to Read Power/Charge control
jim 072.d4 Moved int2irq.vec to wrksp+&22
jim 072.d4 Moved int3irq.vec to wrksp+&24
jim 072.d4 Moved int4irq.vec to wrksp+&26
jim 072.d4 Moved c0irq.vec to wrksp+&28
jim 072.d4 Moved c1irq.vec to wrksp+&2A
jim 072.d4 Moved t1irq.vec to wrksp+&2C
jim 072.d4 Moved t2irq.vec to wrksp+&2E
jim 072.d4 Moved txirq.vec to wrksp+&30
jim 072.d4 Moved tyirq.vec to wrksp+&32
jim 072.d4 Moved s1rirq.vec to wrksp+&34
jim 072.d4 Moved s1rirq.vec to wrksp+&36
jim 072.d4 Moved s2irq.vec to wrksp+&38
jim 072.d4 Moved adcirq.vec to wrksp+&3A
jim 072.d4 Added OS.LCDVDU (&FFB7) and lcdvdu.vec (wrksp+&20)
jim 072.d5 Re-assigned CallOS 37 to Write/Read Power/Charge control
jim 072.d5 Re-assgined CallOS 38 Read Battery Voltage
jim 072.d5 OS.CALLOS now re-entrant
jim 072.d5 Fixed OS.PRINTER
jim 072.d5 Started to add internal logging software
jim 072.d5 Moved OS.LCDVDU to &FFB6
jim 072.d7 Added OS.PRINTERPOLL (&FFB3) and printerpoll.vec (wrksp+&3C)
bob 073 Matched jim & bob sensor lookup tables
bob 073 Added PatchMF
jim 072.dj Added OS.CALLOS 51 Read keypad press
jim 072.dj Added hard reset keypad press
jim 072.dk Added JobCall ReadOutputs
jim 072.do Changed soft reset of zero page locations
jim 072.do Changed MotorForward/Backward bitmaps
jim 072.dp Fixed OS.CALLOS WriteRTCbcd
jim 072.dq Fixed OS.CALLOS ReadRTCstring for correct 24hr operation
jim 072.dr Changed reset prompts
bob 074 Added support for Little Bob
jim 072.dy Added further RTC/CMOS support
jim 072.dB Removed double hard reset
jim 072.dE Set _cpu.mode depending on external memory requirement
jim 072.dF Added Insight code
jim 073 Sub-release
jim 074 Modification to LCD code - uses bsy flag all the time now
jim 074 Fixed OS.CALLOS 42 Write LCD Char Def
jim 074 Fixed OS.CALLOS 43 Read LCD Char Def
jim 075 Added simple battery charge code
jim 075 Fixed JobCall ReadSensorTable
jim 075 Fixed OS.CALLOS 42 Write LCD Char Def
jim 075 Fixed OS.CALLOS 43 Read LCD Char Def
jim 075 Added sleep code
jim 075 Added OS.CALLOS 52 Write Sleep Time
jim 075 Added OS.CALLOS 53 Read Sleep Time
jim 075 Modified battery charge code
jim 076 Modified JobCall ReadSensorTable
jim 076 Modified OS.CALLOS 26 ReadKeypad to do debounce
jim 077 Rewrote battery charging code
jim 077.2 Reduced stop charge threshold to 2
jim 077.3 Increased stop charge threshold to 3
jim 077.3 Added battery voltage averaging
bill 077 Stripped
bill 077 Moved ins to out port
bill 077 Added RTS
bill 077 Changed sensor ID system back to original, using p2.1
bill 077 Dedicated USB/RS selection line, RTS provisioned on p2.3
bill 077 Overload "bounce" timing
bill 078 CTS added
bill 079 Temperature fudge</nowiki>

== Documentation ==

<nowiki> Documentation for SmartBox OS 2.066

The term JobCall is the concept of the routine itself, as opposed to
JobName (which is the actual name associated with it (eg. NameCode)) and
JobCode (which is the actual number associated with it (eg. 3)).

The term controller means the SmartBox, or any other incarnation
which may appear in future time !

The term OS means the controllers' Operating System.

Preview

There are a number of reasons why using Machine Code on the
controller is more desirable than using the various JobCalls via the serial
link. One reason is speed, if the task which needs to be performed, has to
be performed very quickly (more quickly than can be achieved via the serial
link at least), then some code must be written to work in the controller
itself to achieve this sort of speed. If the task required is to be a
"background" task (ie. a task which may happen while other "things" carry
on as normal, like a change of state of a particular port) then it is far
easier to let the controller do all the work, maybe under interupts, than
continuously poll the controller checking the state of various things.
Another reason may be that you would like to add another JobCall to the OS,
extending the calls available to external applications (and the user at the
same time), without the user having to write the code himself to achieve the
aim. For advanced users, there is also the ablity to alter the way the OS
does various things and to have the controller in their "power", for
dedicated tasks etc.

One advantage of writing IN the controller is that that "function"
is available to any computer using the serial link, and is thus not fixed to
one computer type or even a computer at all, where the controller is used
free running, doing a particular task which doesn't need the intervention of
the user's own computer.

Call types

There are three different types of machine code routines which can
be added to the controller. Each one is suited to a more advanced level
than the other, which also relates to the amount of work needed to actually
get the routine working ! The three levels are such:

a) Simple stand alone routine. Here the routine is just the routine
itself with no supporting code (ie. code to integrate with the rest of the
OS). It has to be called directly, by use of the ExecuteCode JobCall, thus
it usually resides at a fixed address and obviously does not offer the user
friendly way of accessing itself like there is with normal OS calls.

b) Extended JobCall. There is one JobCall in the OS (ExtendJob)
which can call various routines residing in memory, each one is identified
by a 8 bit number. The disadvantages of this way is that the call hasn't
got it's own JobName/JobCode and needs the extra byte to identify itself.
This is ideal for the quick routine which the user would like to add for
himself without having to resort to the extra code needed for the full
JobCode implementation.

c) Full JobCall. This is where the routine can define itself one
(or a number) of JobNames/JobCodes, it can integrate itself into an
extension of the OS in a complete way. The disadvantage is that extra
coding is needed to deal with the various OS calls it has to service and
that extra work is needed to produce a suitable file to place in the
controller.

Normally with most processors, including the 65c02, the machine code
produced is produced for a fixed memory address, and it cannot be made to
run in a different place in memory unless extra work is carried out by the
user, or at least a combination of the user and the OS. For the controller
this is a very severe disadvantage as most extensions are downloaded as
"modules" and to optimise memory a system has to be devised to enable
routines to be placed anywhere in memory, thus allowing no memory to be
wasted. In the OS there is a routine to do just this, though it does need
some help. A special version of the users code has to be developed, or
rather it has to be "processed" to add extra information on the end. Extra
code is needed to set up a few pointers and call the OS routine to relocate.
See later.

Memory

The first 256 bytes of memory are somewhat special, most zero page
locations are reserved for use by the OS:

0 General workspace, used to pass parameters to some OS
routines, can also be used by other routines DURING
14 their execution.
15 Reserved
6f
70 Available to the user
9f
a0 Accumulator store for irqs (irq_A)
a1 Two byte counter, decremented at 100hz, useful for temporary
a2 timing purposes (fcount)
a3 RAM size, high byte of RAM size of machine, ie. for 32k
this will be &80 (RAM_size)
a4 Reserved
af
b0 Used by the OS
ff

The rest of memory space is used for the processors stack, OS'
buffers, tables, vectors and, of course, the user available memory.

A breakdown of the rest of memory:

&100 to &1FF is the 65c02's stack.

&200-&2FF is used by the OS for various system functions and also
contains the vector table, more on that later.

&300-&3FF is the serial input buffer.

&400-&47F is the internal job code call output buffer. (jobout_buf)

&480-&4FF is the internal job code call input buffer. (jobin_buf)

&500-&5FF is the job status table.

&600 to the end of RAM memory is for the user. The user should not
assume what the top of AVAILABLE memory is and use the
system variable HIMEM.

In the controller the maximum limit of RAM is &8000 (which is 32k),
from &8000-&DFFF lies the memory mapped hardware, from &E000 to &FFF9 lies
the OS and from &FFFA to &FFFF lies the 65c02 vectors.

So the user has his own limits of free memory. The lowest limit is
called LOMEM and the highest limit is called HIMEM, everything between these
boundaries is termed "available" for use by anyone, the user or the OS.
Anyone can also claim memory, thus making private to them and not allowing
anyone else to use it. You do this by altering the value of LOMEM, HIMEM
should not be moved. Of course anyone claiming memory should first check
that there is enough memory available for the amount they want to claim for.
To take a common example, a downloadable routine which installs itself as a
extension routine, The download routine will first of all read LOMEM, read
HIMEM, check there is enough memory for the routine, download it to LOMEM
and call it, the downloaded routine will then relocate itself and alter
LOMEM so it is protected.

There is one other memory limit, this is called TOPMEM, this is the
absolute top limit of RAM, HIMEM will normally equal TOPMEM, but a future OS
may alter HIMEM to below TOPMEM. TOPMEM should be ignored ideally, and
HIMEM used.

OS Calls

The OS has calls (ie. a jump instruction which you call, which
then calls, via a RAM vector, a routine in the OS) setup near the top of
memory, through these calls you do everything associated with the
controller. The calls are are such:

OS_PRINTER at address &FFB9
OS_CALLOS at address &FFBC
OS_SENDBYTE at address &FFBF
OS_READBYTE at address &FFC2
OS_SENDJOB at address &FFC5
OS_READJOB at address &FFC8
OS_DECODEJOB at address &FFCB

The address is the one to call for the particular routine.

OS_PRINTER is reserved for future use.
OS_CALLOS calls upon the OS to do various things internally.
OS_SENDBYTE sends a byte out of the serial port.
OS_READBYTE reads a byte from the serial port.
OS_SENDJOB 'sends' a value to the JobCall caller.
OS_READJOB 'reads' a value from the JobCalls caller.
OS_DECODEJOB decodes the Job number held in A and acts on it.

Note none of these things should be used in interupt routines,
except OS_CALLOS, of any sort, except if YOU know what state the machine is
in and WHY.

Serial Port

The serial port on the controller is currently based on the 6850
UART, this need not bother you as the OS deals with the thing entirely by
itself. The chip is setup by the OS to always have a word format of 8n1 and
a baud rate of 9600, this translates to 960cps. The 6850 has two divide
rates for the baud rate, the OS only uses one, using the other one is beyond
the scope of this document and shouldn't be neccessary to use.

Only receive interupts are used, transmission of characters is done
on a polled basis.

As said, there are two calls OS_READBYTE and OS_SENDBYTE.
OS_READBYTE tests the serial input buffer and returns the character (if any
in the A register), the c flag states whether there was a character
returned.

Call : OS_READBYTE
Entry : A, X, Y, c, z = undefined
Exit : X, Y preserved
z = undefined
if c = 1 (no character received)
A is preserved
if c = 0 (character received)
A = character received

OS_SENDBYTE sends the character in the A register out of the serial
port, taking into consideration flow control etc.

Call : OS_SENDBYTE
Entry : A = character to send
X, Y, c, z = undefined
Exit : A, X, Y, c is preserved
z = undefined

OS_READJOB and OS_SENDJOB

To send/receive data from the user (either internally or via the
serial port) you call OS_SENDJOB/OS_READJOB for the next byte. If your
JobCall requires dynamic use of data, ie. interaction, then a check of the
enviroment should be done to check the call came from the serial port. One
example of this is the OS JobCall MultipleServer, which requires dynamic use
of sending a stream of data until a reaction from the user to tell it to
stop.

Call : OS_READJOB
Purpose: To read job value from the user
Entry : A, X, Y, c, z = undefined
Exit : A = byte read
X, Y is preserved
c, z = undefined
Note : When coming from the serial port it waits for a character to be
received, if you are doing a serial only call and wish to have a loop
checking for a character from the user while doing "your own thing", then
OS_READBYTE should be used. For internal calls this reads data out of
jobin_buf.

Call : OS_SENDJOB
Purpose: To give a job value back to the user
Entry : A = byte to give
X, Y, c, z = undefined
Exit : A, X, Y is preserved
c, z = undefined
Note : This will send either out to the serial port or place a byte in
jobout_buf. For internal calls this stores the value in jobout_buf, which
is allocated 128 bytes, no bound checking is done so sending more than 128
bytes to OS_SENDJOB will cause corruption of some memory.

OS_DECODEJOB

JobCalls in practise are really only used by the user, JobCalls
tend not to call other calls at all, infact you shouldn't really call
another call unless you were called from the serial port. If you do need to
call another JobCall then you do it like this; with each call you have
associated with it a number, and the call might require some data or give
some data back or both. With the serial port this is simple, you just send
data down and receive data as it is produced. You can't do this with
internal calls, and some calls will not let you call them from inside the
controller, you HAVE to call them from outside. But for the ones which do
let you, you do it with two data blocks, one for input TO the call and one
for output FROM the call. These are setup in a position in memory
(jobin_buf and jobout_buf), each one has a maximum of 128 bytes and this
should not be overflowed (OS_READJOB and OS_SENDJOB do NOT do any bound
checking). So to start with you place in the input block the data you want
to give the call (if any), call it, and then act on the data in the output
block (if any). The OS call OS_DECODEJOB is the one which actually calls
the JobCall handler and eventually the actual routine, you tell the JobCall
handler which call you want by placing the JobCode in the A register.

So for OS_DECODEJOB:

Call : OS_DECODEJOB
Entry : A = JobCode
X, Y, c, z = undefined
jobin_buf should contain any input data
Exit : A = flag
X = number of bytes given back by routine
Y = undefined
c = status, if set JobCall does not exist
z = status, if set JobCall cannot be called internally
jobout_buf contains any data sent from routine

A typical example would be:

LDA #readhimem ; JobCode for ReadHimem
JSR OS_DECODEJOB ; Call the JobCall handler
LDX jobout_buf ; Read HIMEM from buffer LSB
LDY jobout_buf+1 ; Read HIMEM from buffer MSB
STX jobin_buf ; Place LSB in input buffer
STY jobin_buf+1 ; Place MSB in input buffer
LDA #writelomem ; JobCode for WriteLomem
JSR OS_DECODEJOB ; Call the JobCall handler

which would read HIMEM, and then write LOMEM to be the same value, leaving
no spare memory left.

The reason why you should not call an internal call from another
internal call is that the same buffers (jobin_buf and jobout_buf) would be
used for both calls, causing conflict between the two calls, or rather to
the originator of the primary call ! The only time it would be safe if is
if you have already got all the data you want from jobin_buf and haven't
placed any in the jobout_buf (it would be lost if you had done).

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.

CALLOS : 0
Purpose: Returns the OS version number
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

CALLOS : 1
Purpose: To claim a block of JobCodes
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.

CALLOS : 2
Purpose: To handle NameCode request for the application.
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

CALLOS : 3
Purpose: To handle CodeName request for the application.
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

CALLOS : 4
Purpose: To relocate code
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

CALLOS : 5
Purpose: To "describe" the enviroment
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 CALLOS
0 and decide what addresses/configuration to use from the Hardware version
number.

CALLOS : 6
Purpose: To read a register in the VIA
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.

CALLOS : 7
Purpose: To write to a register in the VIA
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

CALLOS : 8
Purpose: To read a register in the ACIA
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

CALLOS : 9
Purpose: To write to a register in the ACIA
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

CALLOS : 10
Purpose: To read a register in the ADC
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

CALLOS : 11
Purpose: To write to a register in the ADC
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

CALLOS : 12
Purpose: To read a ADC channel
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.

CALLOS : 13
Purpose: To read a register in the AUX_PORT
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

CALLOS : 14 (OS 2.066+)
Purpose: To start sensor type checking
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 CALLOS 15 to check
when all the sensors have been checked.

CALLOS : 15 (OS 2.066+)
Purpose: To check the status of sensor checking
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

CALLOS : 16 (OS 2.069+)
Purpose: To set the OS' irq mask for the VIA
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
Note :

CALLOS : 17 (OS 2.069+)
Purpose: To set the OS' irq mask for the ACIA
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
Note :

CALLOS : 18 (OS 2.069+)
Purpose: To set the OS' irq mask for the ADC
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
Note :

CALLOS : 19 (OS 2.069+)
Purpose: To set the ACIA's ctrl register and OS' soft copy
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
Note :

CALLOS : 20 (OS 2.069+)
Purpose: To set the reset vector for battery back RAM support
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.

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.

brk_vec at address &200
nmi_vec at address &202
irq_vec at address &204
irq2_vec at address &206
sendserial_vec at address &208
readserial_vec at address &20A
sendjob_vec at address &20C
readjob_vec at address &20E
decode_job_vec at address &210
unknownjob_vec at address &212
extjob_vec at address &214
centisec_vec at address &216
internal_vec at address &218
callos_vec at address &21A
printer_vec at address &21C
reset_vec at address &21E

The brk_vec is 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.
The nmi_vec is called whenever there is a NMI request (not really
applicable, as the NMI line is not connected to anything).
The irq_vec is called whenever there is an interupt.
The irq2_vec is called whenever an unknown interupt is encountered,
ie. didnXt come from the controllerXs VIA, ACIA or ADC, or the interupt
from the VIA was not used by the OS.
The sendserial_vec is called when OS_SENDBYTE is called.
The readserial_vec is called when OS_READBYTE is called.
The sendjob_vec is called when OS_SENDJOB is called.
The readjob_vec is called when OS_READJOB is called.
The decodejob_vec is 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".
The unknownjob_vec is called whenever an unknown JobCode is
encountered.
The extendedjob_vec is called whenever the ExtendedJob is called,
the A register holds the extension value.
The centisecond_vec is 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.
The internal_vec is called when some information is needed from
various parts of the system, which includes the OS whch 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.
The callos_vec is called when OS_CALLOS is called.
The printer_vec is called when OS_PRINTER is called.
The reset_vec is 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 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 isnXt 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 infact. 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 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

Function: 0
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

Function: 1
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
Note :

Function: 2
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 Code not recognised then
A = 2
X, Y, c, z = undefined
Note :

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

unknownjob_vec

Purpose: To pass on unknown JobCalls to the correct owner
Entry : A = enviroment (0 = internal call, 1 = serial call)
Y = JobCode
X = JOB ID of owner
c, z = undefined
Exit : if jobcode yours then
if wrong enviroment then
A = 1
Y = 0
X, c, z = undefined
if right enviroment then
perform function
A = 0
Y = 0
X, c, z = undefined
if jobcode not yours then
pass on with registers unaltered
Note :

Starting Up

The setup procedure for setting up extension job calls is to:

a) Claim the number of JobCodes you want
if success:
b) patch the internal_vec and unknownjob_vec vectors
c) move LOMEM up to protect your program
d) do anything else for initial startup you may want to do
e) return back, ready and waiting

This in code looks like:

execute
LDX #no_of_calls ; Number of JobCodes wanted
LDA #1 ; CALLOS, function 1, Claim JobCodes
JSR OS_CALLOS ; Call CALLOS
CPX #0 ; Check we were given some codes
BEQ noinstall ; No, don�t bother installing ourself
STX call ; Store base address of JobCodes allocated
STY job_id ; Store JOB ID given

LDA internal_vec ; Get old internal_vec (LSB)
STA ovec ; Store it
LDA internal_vec+1 ; Get old internal_vec (MSB)
STA ovec+1 ; Store it
LDA #>internal_handle ; Our internal handler (LSB)
STA internal_vec ; Place it in the vector (LSB)
LDA #<internal_handle ; Our internal handler (MSB)
STA internal_vec+1 ; Place it in the vector (MSB)

LDA unknownjob_vec ; Get old unknownjob_vec (LSB)
STA ovec2 ; Store it
LDA unknownjob_vec+1 ; Get old unknownjob_vec (MSB)
STA ovec2+1 ; Store it
LDA #>job_handle ; Our unknown job handler (LSB)
STA unknownjob_vec ; Place it in the vector (LSB)
LDA #<job_handle ; Our unknown job handler (MSB)
STA unknownjob_vec+1 ; Place it in the vector (MSB)

LDX #>WriteLomem ; Point to JobName
LDY #<WriteLomem
JSR findjob ; Find WriteLomem code
BEQ noinstall ; Doesn't exist !
LDX #>end_of_code ; End of code (LSB)
LDY #<end_of_code ; End of code (MSB)
STX jobin_buf ; Place it in jobin_buf (LSB)
STY jobin_buf+1 ; Place it in jobin_buf+1 (MSB)
JSR OS_DECODEJOB ; Call JobCall handler

noinstall
RTS ; End - return to OS

findjob
STX zero.gp1 ; Zero page
STY zero.gp1+
LDY #0
findthisjoblo
LDA (zero.gp1),Y
STA jobin.buf,Y ; Store name in jobin_buf
INY
CMP #13
BNE findthisjoblo
LDA #3 ; NameCode
JSR OS.DECODEJOB ; Call NameCode
LDA jobout.buf ; Get returned value
RTS

WriteLomem STR "WriteLomem"

This will setup the various vectors and memory pointers for the
applicaion, the actual routines (internal_handle and job_handle) are fairly
straight forward and simple:

internal_handle
CMP #1 : Is it function call 1 (NameCode) ?
BNE internal_handle_2 ; No, check for function 2
LDA job_id ; Get our JOB ID number
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #>job_names ; Our Job name table (LSB)
LDY #<job_names ; Our Job name table (MSB)
LDA #2 ; CALLOS function 2
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes : Found, go off and claim call
LDA #1 ; Not found, restore A
JMP (ovec) ; Call back to old vector

internal_handle_2
CMP #2 ; Is it function call 2 (CodeName) ?
BNE internal_handle_3 ; No, unknown, pass on
LDA job_id ; Get our JOB ID
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #>job_names ; Our Job name table (LSB)
LDY #<job_names ; Our Job name table (MSB)
LDA #3 ; CALLOS function 3
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes ; Found, go off and claim call
LDA #2 ; Not found, restore A
JMP (ovec) ; Call back to old vector

internal_yes
LDA #0 ; We want to claim call for some reason

internal_handle_3
JMP (ovec) ; Call back to old vector

job_handle
PHA ; Mark sure to preserve A
CPY call ; Check call wanted against base of ours
BCC job_handle_no ; Less than our base, so definately not ours
TYA
SBC #no_of_calls ; Subtract number of calls we have
CMP call ; Now compare with base
BCC job_handle2 ; Yes, one of ours

job_handle.no
PLA ; Restore A
JMP (ovec2) ; Call back to old vector

job_handle2
TYA
SEC
SBC call ; Subtract our base from call
ASL A ; Times by 2 for offset into table
TAY ; Place in Y
LDA job_run_table,Y ; Get LSB of routine
STA zero_gp1 ; Store it for indirect jump (LSB)
LDA job_run_table+1,Y ; Get MSB of routine
STA zero_gp1+1 ; Store it for indirect jump (MSB)
PLA ; Restore A
JMP (zero_gp1) ; Call our relevant routine

job_names ; List of our JobNames
STR "TestJob" ; Test job name
DFB &FF ; &FF - marks end of table

job_run_table ; List of routine addresses to match Jobs
DFW job_TestJob ; Test job routine

Relocation

The relocation method used will not do a complete relocation, ie.
from ANY address to ANY address. The only constraint on the addresses is
that they must be the same offset in the page, which means, &2602 and &3402
is alright but &2602 and &3455 is not, ie. the difference between the two
addresses must be a multiple of 256 bytes, as only the MSB is altered, this
should not cause any real problems. What is meant by the two addresses is
the address the code was originally assembled at and the address it wants
relocating to. Because of this programs must be multiples of 256 bytes, ie.
the low byte of LOMEM must ALWAYS be 0, your program should be padded out.

The relocation mechanism works by having a table, and to each byte
of code there is one BIT, if unset it means the byte of code should not be
relocated, else it should be, thus the BitMap table is 8 times smaller than
the code. To generate the BitMap you have to assemble the code at two
different places, and compare both sets of assembled code against each
other, the differences are where the code is to be relocated. The code
which is sent up to the controller is assumed to be assembled at address
&100, so the first code should be assembled at &100, the other one should be
assembled at another address, say &600, and the first one be sent up with
the BitMap. A program is availble for the Elk/Beeb/Arc with 65Tube/Mac with
BBC BASIC to compare the two files and create the BitMap.

All the program has to do to relocate itself is execute this bit of
code first of all: (address is the base address of the program, ie. &100
for the downloaded version)

execcall
LDA #>(execute-address) ; Final execution address offset (LSB)
STA zero_gp1
LDA #<(execute-address) ; Final execution address offset (MSB)
STA zero_gp1+1

LDA #>(BitMap-address) ; BitMap address offset (LSB)
STA zero_gp2
LDA #<(BitMap-address) ; BitMap address offset (MSB)
STA zero_gp2+1

LDA #>(execcall-address); Length of data to relocate (LSB)
STA zero_gp3
LDA #<(execcall-address); Length of data to relocate (MSB)
STA zero_gp3+1

TXA ; Execcall REAL address
SEC
SBC #>(execcall-address); Subrtract length
TAX ; Put it back in X
TYA ; Ditto for MSB
SBC #<(execcall-address)
TAY
LDA #4 ; CALLOS function for Relocate
JMP OS_CALLOS ; Call CALLOS

BitMap ; BitMap start

This will relocate the code and automatically call the execution
address, which should be the initialisation code (ie. setup internal_vec
and unknownjob_vec etc.). "address" is the address the code is started to
assemble at, &100 for the version to be uploaded. The upload routine should
pass in X and Y (via ExecuteCode) the address of the start of execcall, this
means that the routine can tell where it is in memory, subtracting the
length gives the start of the code to relocate.

Layout Summary

The layout of a full application should be like this by now:

start of code
program job codes, data etc.
internal handler
job handler
end of code
initialisation (setup internal etc.)
end of code to be relocated
execution (relocation)
relocation BitMap

Because of memory space the initialisation code should be placed
outside the reserved memory limit of the program, as it is only called once
and not needed again.

Other miscellaneous calls:

Call : OS_PRINTER
Purpose : To place a character in the printer buffer
Entry : A = character to send
X, Y, c, z = undefined
Exit : A, X, Y is preserved
if c = 0 (printed)
The printer is on and the character was inserted
if c = 1 (not printed)
The printer is off and the character was forgotten
z = undefined
Note : The character goes into the printer buffer and will be
actually sent to the printer when the printer asks for it. If the printer
was not awake to begin with, an attempt is made to wake it up, thus
meaning that in some circumstances when the printer wasn't ready a
character may be lost, this cannot be helped. If the printer is off (via
the BCD switch) then the character will be forgotten as the Printer Buffer
is inactive.

The module is located at &8000 in memory, and should be a EPROM placed
in the second ROM socket in the controller (ie. the top RAM socket). This
module is primary designed to turn the Controller into a dedicated task,
making it perform some function from switch on. It could also be used to
add more permant JobCalls to the Controller, in the process taking up much
less RAM), but because of there being only one Module present this feature
is limited, and is much more suited to a collection of the user's own
personal routines.
For the OS to recognise a module as being in place the text "Module" is
looked for, the layout of a module should be like this (starting at
&8000):

Offset value comment
0 "Module" The OS checks for this string
6 0 End of check string
7 Language entry Address of 'Language' entry
9 Service entry Address of 'Service' entry
11 "<Module Title>" Module title
0 End of Module title

"<Module part>" Part Module Title
0 End of Part Module Title
"x.xx" Part version number

&FF End of parts list

The language entry is a 2 byte value holding the address of the language
entry routine, this is called on reset, if the BCD is set correctly. A
value of less than &8000 means there is no valid language entry and any
language calls are ignored. If a RTS is made the OS carries on as it would
have if there wasn't a language call.

The service entry is a 2 byte value holding the address of the service
entry routine, this is called at various appropiate moments with service
numbers in A. A list of current calls is thus:

0 - Not used
1 - Unknown Job Code
2 - Centisecond call
3 - Irq2 (unknown IRQ)
4 - internal_vec call (exit with A=0 to claim)
254 - RESET
255 - BRK

On exit all registers and flags should be preserved. For call 1 the
unknown job value is held in the Y register, the enviroment is held in the
X register, on exit, X should contain the flag, as A does from the exit of
unknownjob_vec. For the rest of calls, X and Y are undefined.

For both Service and Language entry points, a value of 0 means "there is
no valid routine" and the module isn't called for that type of entry.

Finally a full implementation of a JobCall, from start to finish.

DIM data% &1000
:
no_of_calls = 1
:
VIA = &E030
ACIA = &E010
ADC = &E000
AUX_PORT = &E020
brk_vec = &200
nmi_vec = &202
irq_vec = &204
irq2_vec = &206
sendserial_vec = &208
readserial_vec = &20A
sendjob_vec = &20C
readjob_vec = &20E
decodejob_vec = &210
unknownjob_vec = &212
extjob_vec = &214
centisec_vec = &216
internal_vec = &218
callos_vec = &21A
printer_vec = &21C
zero_gp1 = 0
zero_gp2 = 2
zero_gp3 = 4
zero_gp4 = 6
zero_gp5 = 8
zero_gp6 = 10
zero_gp7 = 12
zero_gp8 = 14
zero_gp9 = 16
zero_gp10 = 18
user_reserved = &70
irq_A = &A0
fcount = &A1
RAM_size = &A3
jobout_buf = &400
jobin_buf = &480
OS_PRINTER = &FFB9
OS_CALLOS = &FFBC
OS_SENDBYTE = &FFBF
OS_READBYTE = &FFC2
OS_SENDJOB = &FFC5
OS_READJOB = &FFC8
OS_DECODEJOB = &FFCB
:
FOR create=1 TO 2
:
FOR pass%=4 TO 7 STEP 3
P%=&100*create : O%=data%
[OPT pass%
:
.job_DemoJob
CMP #1
BEQ DemoJob_go
LDA #1
LDY #0
RTS
/
.DemoJob_go

:
.internal_handle
CMP #1 ; Is it function call 1 (NameCode) ?
BNE internal_handle_2 ; No, check for function 2
/
LDA job_id ; Get our JOB ID number
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #job_names MOD 256 ; Our Job name table (LSB)
LDY #job_names DIV 256 ; Our Job name table (MSB)
LDA #2 ; CALLOS function 2
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes ; Found, go off and claim call
LDA #1 ; Not found, restore A
JMP (ovec) ; Call back to old vector
/
.internal_handle_2
CMP #2 ; Is it function call 2 (CodeName) ?
BNE internal_handle_3 ; No, unknown, pass on
/
LDA job_id ; Get our JOB ID
STA zero_gp3 ; Place it in zero_gp3 for CALLOS
LDX #job_names MOD 256 ; Our Job name table (LSB)
LDY #job_names DIV 256 ; Our Job name table (MSB)
LDA #3 ; CALLOS function 3
JSR OS_CALLOS ; Call CALLOS
BCC internal_yes ; Found, go off and claim call
LDA #2 ; Not found, restore A
JMP (ovec) ; Call back to old vector
/
.internal_yes
LDA #0 ; We want to claim call for some reason
/
.internal_handle_3
JMP (ovec) ; Call back to old vector
:
.job_handle
PHA ; Make sure to preserve A
CPY call ; Check call wanted against base of ours
BCC job_handle_no ; Less than our base, so definately not ours
TYA
SBC #no_of_calls ; Subtract number of calls we have
CMP call ; Now compare with base
BCC job_handle2 ; Yes, one of ours
/
.job_handle.no
PLA ; Restore A
JMP (ovec2) ; Call back to old vector
/
.job_handle2
TYA
SEC
SBC call ; Subtract our base from call
ASL A ; Times by 2 for offset into table
TAY ; Place in Y
LDA job_run_table,Y ; Get LSB of routine
STA zero_gp1 ; Store it for indirect jump (LSB)
LDA job_run_table+1,Y ; Get MSB of routine
STA zero_gp1+1 ; Store it for indirect jump (MSB)
PLA ; Restore A
JMP (zero_gp1) ; Call our relevant routine
:
.job_names ; List of our JobNames
EQUS "DemoJob":EQUB 13 ; Test job name
/
EQUB &FF ; &FF - marks end of table
:
.job_run_table ; List of routine addresses to match Jobs
EQUW job_DemoJob ; Test job routine
:
.call : EQUB 0 ; Store for our JobCode base
.job_id : EQUB 0 ; Store for our JobId
.ovec : EQUW 0 ; Store for old internal_vec value
.ovec2 : EQUW 0 ; Store for old unknownjob_vec value
:
EQUS STRING$(&100-(P% MOD 256),CHR$0)
.end_of_code ; end_of_code should be on page boundry
:
.execute
LDX #no_of_calls ; Number of JobCodes wanted
LDA #1 ; CALLOS, function 1, Claim JobCodes
JSR OS_CALLOS ; Call CALLOS
STX call ; Store base address of JobCodes allocated
STY job_id ; Store JOB ID given
CPX #0 ; Check we were given some codes
BEQ noinstall ; No, don't bother installing ourself
/
LDA internal_vec ; Get old internal_vec (LSB)
STA ovec ; Store it
LDA internal_vec+1 ; Get old internal_vec (MSB)
STA ovec+1 ; Store it
LDA #internal_handle MOD 256 ; Our internal handler (LSB)
STA internal_vec ; Place it in the vector (LSB)
LDA #internal_handle DIV 256 ; Our internal handler (MSB)
STA internal_vec+1 ; Place it in the vector (MSB)
/
LDA unknownjob_vec ; Get old unknownjob_vec (LSB)
STA ovec2 ; Store it
LDA unknownjob_vec+1 ; Get old unknownjob_vec (MSB)
STA ovec2+1 ; Store it
LDA #job_handle MOD 256 ; Our unknown job handler (LSB)
STA unknownjob_vec ; Place it in the vector (LSB)
LDA #job_handle DIV 256 ; Our unknown job handler (MSB)
STA unknownjob_vec+1 ; Place it in the vector (MSB)
/
LDX #end_of_code MOD 256 ; End of code (LSB)
LDY #end_of_code DIV 256 ; End of code (MSB)
STX jobin_buf ; Place it in jobin_buf (LSB)
STY jobin_buf+1 ; Place it in jobin_buf+1 (MSB)
LDA #65 ; JobCode for WriteLomem
JSR OS_DECODEJOB ; Call JobCall handler
/
.noinstall
RTS ; End - return to OS
:
.execcall
LDA #>(execute-address) ; Final execution address offset (LSB)
STA zero_gp1
LDA #<(execute-address) ; Final execution address offset (MSB)
STA zero_gp1+1
/
LDA #>(BitMap-address) ; BitMap address offset (LSB)
STA zero_gp2
LDA #<(BitMap-address) ; BitMap address offset (MSB)
STA zero_gp2+1
/
LDA #>(execcall-address) ; Length of data to relocate (LSB)
STA zero_gp3
LDA #<(execcall-address) ; Length of data to relocate (MSB)
STA zero_gp3+1
/
TXA ; Execcall REAL address
SEC
SBC #>(execcall-address) ; Subrtract length
TAX ; Put it back in X
TYA ; Ditto for MSB
SBC #<(execcall-address)
TAY
LDA #4 ; CALLOS function for Relocate
JMP OS_CALLOS ; Call CALLOS
/
.BitMap ; BitMap start
:
]
NEXT
:
OSCLI "SAVE code"+STR$create+" "+STR$~data%+" "+STR$~O%
:
NEXT</nowiki>

SmartBox JobList

2023-11-01T04:37:53Z

Benryves: Created page with " <nowiki>OS 4 - 14.02.00 0 Blank Does nothing Send Byte 0 = 0 Returns Nothing 1 Version Read the operating system version number Send Byte 0 = 1 Returns Byte 0 = version number - low byte Byte 1 = version number - high byte Comments Divide by 1000 to get the version number, eg. version 1.023 would be returned as 1023 2 Reset Reset Smart Box Send Byte 0 = 2 Byte 1 = 254 or 255 Returns Nothing Comments Reset SmartBox from the host micro. Sending a..."

<nowiki>OS 4 - 14.02.00

0 Blank
Does nothing
Send Byte 0 = 0
Returns Nothing

1 Version
Read the operating system version number
Send Byte 0 = 1
Returns Byte 0 = version number - low byte
Byte 1 = version number - high byte
Comments Divide by 1000 to get the version number, eg. version 1.023
would be returned as 1023

2 Reset
Reset Smart Box
Send Byte 0 = 2
Byte 1 = 254 or 255
Returns Nothing
Comments Reset SmartBox from the host micro. Sending a 254 performs
a soft reset (same as pressing reset), sending 255 does a
hard reset (clears battery back RAM). Before sending
anymore codes create a small delay while SmartBox resets
various parts of hardware

3 NameCode
To obtain the operating system call number where the name
is known
Send Byte 0 = 3
Byte 1 - n = ASCII characters of OS call name
Byte n+1 = 13
Returns Byte 0 = Operating system call number

4 CodeName
To obtain the name associated with an operating system
call
Send Byte 0 = 4
Byte 1 = OS call number
Returns StringCR = OS call name

5 MultipleSetup
To set the values that will be returned by MultipleRead
Send Byte 0 = 5
Byte 1 = Analogue channel 1
Byte 2 = Analogue channel 2
Byte 3 = Analogue channel 3
Byte 4 = Analogue channel 4
Byte 5 = Digitial inputs
Byte 6 = Digital outputs
Byte 7 = Motor outputs
Returns Nothing
Comments This sets up the readings which will be returned when the
call MultipleRead is made. If a byte = 1 the corresponding
port will be returned, 0 = value not returned

6 MultipleRead
Returns multiple readings as defined using MultipleSetup
Send Byte 0 = 6
Returns Bytes as defined by MultipleSetup
Comments This call returns readings from a number of ports as
defined by MultipleSetup

7 MultipleServer
Constantly returns multiple readings as defined using
MultipleSetup
Send Byte 0 = 7
Returns Bytes as defined by MultipleSetup
Comments This call is similar to MultipleRead but continues to
return readings until SmartBox receives the byte 123

8 IdentSystem
Read System Information
Send Nothing
Returns Byte 0 = table length
Word = VIA
Word = ACIA
Word = ADC
Word = AUX.PORT
Word = jobs.status
Word = jobin.buf
Word = jobout.buf
Byte = Processor ident
Word = OS version number
Byte = Hardware version number
String10 = Name, padded to 10 chars
Byte = Number of inputs
Byte = Number of outputs
Byte = Number of motors
Byte = Number of analogues
Byte = BBR support
Byte = Short support
Byte = Printer support
Byte = Keypad support
Byte = LCD x dim/support
Byte = LCD y dim
OS Release 3,4

9 Credits
Returns the copyright string
Send Byte 0 = 9
Returns StringNUL = Copyright string
Comments This call returns the copyright message and OS details

10 WriteMotors
Writes a byte to the motor drivers
Send Byte 0 = 10
Byte 1 = value to write
Returns Nothing
Comments Each of the four motor outputs has two bits encoded into
this value, bits 0 and 1 are for motor a, bytes 2 and 3 are
for motor b, bits 4 and 5 are for motor c and bits 6 and 7
are for motor d, setting both bits to 0 will stop the
motor, setting the low bit high and high bit low will make
the motor go forward and setting the high bit high and the
low bit low will make it go backwards. Using this call
automatically stops all pulsing of motors

11 ReadMotors
Read the state of the motor drivers
Send Byte 0 = 11
Returns Byte 0 = value read from the motor drivers
Comments The value returned is the same value as what would be sent
to WriteMotors

12 MotorForward
Switch a motor on
Send Byte 0 = 12
Byte 1 = motor number (1 to 4)
Returns Nothing
Comments This makes the appropiate motor go forward. Using this call
automatically cancels the pulsing for the appropiate motor

13 MotorReverse
Switch a motor on with reverse polarity
Send Byte 0 = 13
Byte 1 = motor number (1 to 4)
Returns Nothing
Comments This makes the appropiate motor go backward. Using this
call automatically cancels the pulsing for the appropiate
motor

14 MotorHalt
Switch a motor off
Send Byte 0 = 14
Byte 1 = motor number (1 to 4)
Returns Nothing
Comments This makes the appropiate motor stop. Using this call
automatically cancels the pulsing for the appropiate motor

15 MotorPower
Pulse a motor outputs to vary speed
Send Byte 0 = 15
Byte 1 = motor number (1 to 4)
Byte 2 = on time
Byte 3 = off time
Returns Nothing
Comments This pulses the appropiate motor at a rate determined by
the on/off time (in centiseconds) specified, alternating
the motor between the state at which it was last defined
(Forward or Reverse) and Halt

16 PatchMF
Same as MotorForward
OS Release 3,4

17 MotorVoltage
Set voltage for motor outputs
Send Byte 0 = voltage (0 to 3)
Returns Nothing
Notes Voltage values are 0 (0v), 1 (6v), 2 (9v), 3 (12v).
*Setting a voltage of 0 will also switch *outputs* to 0v*
Comments This sets the actual voltage supplied to the motor outputs
OS Release 4

20 WriteOutputs
Write a 8 bit value to the digital output port
Send Byte 0 = 20
Byte 1 = byte to be written to the port
Returns Nothing
Comments Using this call automatically cancels all pulsing on the
output port

21 OutputPower
Vary the power by pulsing individual output lines
Send Byte 0 = 21
Byte 1 = bit number (0 to 7)
Byte 2 = on time
Byte 3 = off time
Comments This pulses the appropiate output line at a rate determined
by the on/off time (in centiseconds) specified, alternating
the output line between on and off

22 GetSensors
To read the type of sensors connected to the analogue
sensors
Send Byte 0 = 22
Returns Byte 1 = type of sensor connected to sensor A
Byte 2 = type of sensor connected to sensor B
Byte 3 = type of sensor connected to sensor C
Byte 4 = type of sensor connected to sensor D
Comments This returns the sensor types connected to the analogue
sensors that were returned from the last time they were
checked. A sensor type of 0 means no sensor

23 CheckSensors
To check the type of sensors connected to the analogue
sensors
Send Byte 0 = 23
Returns Byte 1 = type of sensor connected to sensor A
Byte 2 = type of sensor connected to sensor B
Byte 3 = type of sensor connected to sensor C
Byte 4 = type of sensor connected to sensor D
Comments This does an immediate check of the sensor types connected
to the analogue sensors. A sensor type of 0 means no
sensor

24 WriteSensorTable
Write sensor table entry
Notes * Not Implemented *
OS Release 3

25 ReadSensorTable
Read sensor table entry
Send Byte 0 = entry to read
Returns Byte 0 = sensor number
Byte 1 = number of decimal points to display
Byte 2 = max adc reading
Byte 3 = reading offset (LSB)
Byte 4 = reading offset (MSB)
Byte 5 = multiplication factor (LSB)
Byte 6 = multiplication factor (MSB)
Byte 7 = division factor (LSB)
Byte 8 = division factor (LSB)
String = full sensor title
String = abbreviated sensor label
String = sensor label
String = sensor units
Notes If byte 0 is &FF then sensor is unknown
OS Release 3,4

28 SetBitHigh
Set individual output line(s) high
Send Byte 0 = 28
Byte 1 = byte determining which lines will be set
Returns Nothing
Comments A bit set in the byte sent will set the corresponding
output line high

29 SetBitLow
Set individual output line(s) low
Send Byte 0 = 29
Byte 1 = byte determining which lines will be unset
Returns Nothing
Comments A bit set in the byte sent will set the corresponding
output line low

30 ReadADCReg
To read a ADC register
Send Byte 0 = 30
Byte 1 = register number (0 to 15)
Returns Byte 0 = value of register
OS Release 2

31 WriteADCReg
To write to a ADC register
Send Byte 0 = 31
Byte 1 = register number (0 to 15)
Byte 2 = value to write
Returns Nothing
OS Release 2

32 ReadACIAReg
To read a ACIA register
Send Byte 0 = 32
Byte 1 = register number (0 to 15)
Returns Byte 0 = value of register
OS Release 2

33 WriteACIAReg
To write to a ACIA register
Send Byte 0 = 33
Byte 1 = register number (0 to 15)
Byte 2 = value to write
Returns Nothing
OS Release 2

34 ReadVIAReg
To read a VIA register
Send Byte 0 = 34
Byte 1 = register number (0 to 15)
Returns Byte 0 = value of register
OS Release 2

35 WriteVIAReg
To write to a VIA register
Send Byte 0 = 35
Byte 1 = register number (0 to 15)
Byte 2 = value to write
Returns Nothing
OS Release 2

36 SetVIAHigh
To set bits in a VIA register
Send Byte 0 = 36
Byte 1 = register number (0 to 15)
Byte 2 = mask
Returns Nothing
OS Release 2

37 SetVIALow
To unset bits in a VIA register
Send Byte 0 = 37
Byte 1 = register number (0 to 15)
Byte 2 = mask
Returns Nothing
OS Release 2

40 ReadADC
Take a reading from a specific ADC channel
Send Byte 0 = 40
Byte 1 = channel number (1 to 4)
Returns For an 8 bit reading:
Byte 0 = reading from ADC
For a 16 bit reading:
Byte 0 = low byte of reading
Byte 1 = high byte of reading
Comments The value returned will be at the resolution specified by
OS calls HighResADC and LowResADC

41 ReadADCs
Read all the ADC channels
Send Byte 0 = 41
Returns For 8 bit readings:
Byte 0 = reading from channel 1
Byte 1 = reading from channel 2
Byte 2 = reading from channel 3
Byte 3 = reading from channel 4
For 16 bit readings
Byte 0 = reading from channel 1 (low byte)
Byte 1 = reading from channel 1 (high byte)
Byte 2 = reading from channel 2 (low byte)
Byte 3 = reading from channel 2 (high byte)
Byte 4 = reading from channel 3 (low byte)
Byte 5 = reading from channel 3 (high byte)
Byte 6 = reading from channel 4 (low byte)
Byte 7 = reading from channel 4 (high byte)

42 ForcedADCRead
Force the A to D convertor to make a conversion and return
the result
Send Byte 0 = 42
Byte 1 = channel number (1 to 4)
Returns For an 8 bit reading:
Byte 0 = reading from ADC
For a 16 bit reading
Byte 0 = reading from ADC (low byte)
Byte 1 = reading from ADC (high byte)

44 HighResADC
Sets the resolution of ADC readings to 16 bit
Subsequent readings will return 2 byte values
Send Byte 0 = 44
Returns Nothing
Comments For OS 2 readings returned will be only accurate to
10 bits. OS 3,4 provides support for 16 bit readings,
but only to an accuracy of 8 bits.

45 LowResADC
Sets the resolution of ADC readings to 8 bit
Subsequent readings will return single byte values
Send Byte 0 = 45
Returns Nothing

47 ReadResolution
Reads the current ADC resolution setting
Send Byte 0 = 47
Returns Byte 0 = resolution setting, where:
0 = 8 bit
1 = 16 bit

50 DownloadData (OS 2), DownloadData740 (OS 3),
DownloadData375 (OS 4)
Download data into the SmartBox's memory
Send Byte 0 = 50
Byte 1 = start address to write (low byte)
Byte 2 = start address to write (high byte)
Byte 3 = length of data (low byte)
Byte 4 = length of data (high byte)
Bytes 5 - n = data
Returns Nothing

52 UploadData (OS 2), UploadData740 (OS 3),
UploadData (OS 4)
Upload data from the SmartBox's memory
Send Byte 0 = 52
Byte 1 = start address to read (low byte)
Byte 2 = start address to read (high byte)
Byte 3 = length of data (low byte)
Byte 4 = length of data (high byte)
Returns Byte 0 - n = data

54 ExecuteCode (OS 2), ExecuteCode740 (OS 3),
ExecuteCode375 (OS 4)
Execute machine code held at a specified address
Send Byte 0 = 54
Byte 1 = execution address (low byte)
Byte 2 = execution address (high byte)
Byte 3 = contents of the A register on entry to the code
Byte 4 = contents of the X register on entry to the code
Byte 5 = contents of the Y register on entry to the code
Returns Nothing

55 StoreByte (OS 2), StoreByte740 (OS 3),
StoreByte375 (OS 4)
Store a byte in the SmartBox's RAM
Send Byte 0 = 55
Byte 1 = address to write (low byte)
Byte 2 = address to write (high byte)
Byte 3 = byte to be stored
Returns Nothing

56 ReadByte (OS 2), ReadByte740 (OS 3),
ReadByte (OS 4)
Read a byte from the SmartBox's RAM
Send Byte 0 = 56
Byte 1 = address to read (low byte)
Byte 2 = address to read (high byte)
Returns Byte 0 = byte read

57 ReadRAMSize
Read the amount of RAM with which the SmartBox is fitted
Send Byte 0 = 57
Returns Byte 0 = RAM size (low byte)
Byte 1 = RAM size (high byte)
OS Release 2,3

59 ExtendCall
Call the extended call vector
Send Byte 0 = 59
Returns Byte 0 = extension value
Comments This call provides the user with the possibility of adding
extra calls to SmartBox easily
OS Release 2,3

60 SetClock
Set the internal clock in SmartBox. This clock only runs
while the power in maintained
Send Byte 0 = 60
Byte 1 = 1/10 seconds (0 to 9)
Byte 2 = seconds (0 to 59)
Byte 3 = minutes (0 to 59)
Byte 4 = hours (0 to 23)
Returns Nothing
Comments The day value is set to 0

61 ReadClock
Read the internal clock. On reset the clock will be set to
zero
Send Byte 0 = 61
Returns Byte 0 = 1/10 seconds
Byte 1 = seconds
Byte 2 = minutes
Byte 3 = hours
Byte 4 = days

62 ReadTopmem
Read the current value of TOPMEM
Send Byte 0 = 62
Returns Byte 0 = value of TOPMEM (low byte)
Byte 1 = value of TOPMEM (high byte)
OS Release 2,3

63 WriteTopmem
Write the value of TOPMEM
Send Byte 0 = 63
Byte 1 = value of TOPMEM (low byte)
Byte 2 = value of TOPMEM (high byte)
Returns Nothing
OS Release 2,3

64 ReadLomem
Read the current value of LOMEM
Send Byte 0 = 64
Returns Byte 0 = value of LOMEM (low byte)
Byte 1 = value of LOMEM (high byte)
OS Release 2,3

65 WriteLomem
Write the value of LOMEM
Send Byte 0 = 65
Byte 1 = value of LOMEM (low byte)
Byte 2 = value of LOMEM (high byte)
Returns Nothing
OS Release 2,3

66 ReadHimem
Read the current value of HIMEM
Send Byte 0 = 66
Returns Byte 0 = value of HIMEM (low byte)
Byte 1 = value of HIMEM (high byte)
OS Release 2,3

67 WriteHimem
Write the value of HIMEM
Send Byte 0 = 67
Byte 1 = value of HIMEM (low byte)
Byte 2 = value of HIMEM (high byte)
Returns Nothing
OS Release 2,3

70 WritePrinter
Write printer port (no handshaking)
Send Byte 0 = byte to write
Returns Nothing
OS Release 3

71 ReadPrinter
Read printer port
Send Nothing
Returns Byte 0 = printer port value
OS Release 3

72 PrintChar
Send a character to printer port
Send Byte 0 = char
Returns Nothing
OS Release 3

73 PrintStreamZ
Send a stream of characters to the printer port
Send StringNUL = string to print
Returns Nothing
OS Release 3

74 PrintStream
Send a stream of characters to the printer port
Send Byte 0 = number of bytes to send (LSB)
Byte 1 = number of bytes to send (MSB)
Bytes = stream of characters to print
Returns Nothing
OS Release 3

75 PrintServer
Echo all characters to printer port
Notes No exit
OS Release 3

80 WriteRTCReg
Write a RTC register
Send Byte 0 = register
Byte 1 = value
Returns Nothing
OS Release 3

81 ReadRTCReg
Read a RTC register
Send Byte 0 = register
Returns Byte 0 = value
OS Release 3

82 WriteRTC
Writes RTC as a string
Send StringCR = RTC time
Returns Nothing
Notes * Not currently implemented *
Time is represented as DDD,dd mmm yyyy.hh:mm:ss
DDD is 3 character day (Mon, Tue, Wed, Thu, Fri, Sat, Sun)
dd is day of month
mmm is month
yyyy is year
hh is hours
mm is minutes
ss is seconds
OS Release 3

83 ReadRTC
Reads RTC as a string
Send Nothing
Returns StringCR = RTC time
Notes Time is represented as DDD,dd mmm yyyy.hh:mm:ss
DDD is 3 character day (Mon, Tue, Wed, Thu, Fri, Sat, Sun)
dd is day of month
mmm is month
yyyy is year
hh is hours
mm is minutes
ss is seconds
OS Release 3

84 WriteRTCbcd
Writes all 7 RTC time registers
Send Byte 0 = seconds
Byte 1 = minutes
Byte 2 = hours
Byte 3 = date
Byte 4 = month
Byte 5 = day
Byte 6 = year
Returns Nothing
Notes All values are represented in BCD
Years below 80 (&80 in BCD) signify 20xx
Day starts (0) from Monday
OS Release 3

85 ReadRTCbcd
Reads all 7 RTC time registers
Send Nothing
Returns Byte 0 = seconds
Byte 1 = minutes
Byte 2 = hours
Byte 3 = date
Byte 4 = month
Byte 5 = day
Byte 6 = year
Notes All values are represented in BCD
Years below 80 (&80 in BCD) signify 20xx
Day starts (0) from Monday
OS Release 3

90 ReadInputs
Reads a byte from the digital inputs port
Send Byte 0 = 90
Returns Byte 0 = byte read from the digital inputs port

91 ReadBit
Reads a bit from the digital inputs port
Send Byte 0 = 91
Byte 1 = byte to read (0 to 7)
Returns Byte 0 = bit read from the digital inputs port
Comments Reads an individual sensor from the digital inputs port

92 ReadOutputs
Reads a byte from the digital outputs port
Send Byte 0 = 92
Returns Byte 0 = byte read from the digital outputs port
Notes This reads the soft copy of the last written byte
OS Release 3,4

93 CountReset
Resets input port counter(s)
Send Byte 0 = 93
Byte 1 = bit masks for counters to reset
OS Release 4

94 CountRead
Reads input port counter(s)
Send Byte 0 = 94
Byte 1 = counter to read (0 to 7) or 255 for all
Returns Byte 0 = value of counter (LSB)
Byte 1 = value of counter (MSB)
Byte n = value of counter (LSB)
Byte n+1 = value of counter (MSB)
Notes Counter values return 65535 (-1) from box reset, or max count
OS Release 4

98 InsightDriver
Starts the internal Insight software
OS Release 3

99 DataApp
Starts the internal DataApp software
OS Release 3

100 WriteLCDReg
Write LCD Register
Send Byte 0 = register number
Byte 1 = register value
Returns Nothing
OS Release 3

101 ReadLCDReg
Read LCD Register
Send Byte 0 = register number
Returns Byte 0 = register value
OS Release 3

102 LCDChar
Send a character to the LCD display driver
Send Byte 0 = char
Returns Nothing
OS Release 3

103 LCDStreamZ
Send a stream of characters to the LCD display driver
Send StringNUL = string to display
Returns Nothing
OS Release 3

104 LCDStream
Send a stream of characters to the LCD display driver
Send Byte 0 = number of bytes to send (LSB)
Byte 1 = number of bytes to send (MSB)
Bytes = stream of characters to display
Returns Nothing
OS Release 3

110 ReadKeypad
Reads the raw state of the keypad
Send Nothing
Returns Byte 0 = current keypad reading bitstate
OS Release 3

111 ReadKeypadPress
Reads the processed state of the keypad
Send Nothing
Returns Byte 0 = current keypad press bitstate
OS Release 3</nowiki>

Main Page

2023-11-01T04:32:51Z

Benryves:

== Smart Box User Guide ==

Information has been adapted from the original ''Smart Box'' and ''Smart Move'' user manual, copyright Economatics (Education) Limited 1992.

* [[Smart Box]] - A guide to using the Smart Box, including the Smart Box ''EV''.
* [[Tutorial]] - Tutorial for the Smart Move software.
* [[Reference]] - A general reference guide to Smart Move commands.
* [[Smart Sensors and Relay]] - Information sheets on individual sensors and input/output devices.

== Technical Information ==

* [[Serial Port]] - Pinout for the Smart Box's serial port.
* [[Analogue Sensor Ports]] - Pinout for the four analogue sensors.

The following pages have been adapted from information shared at https://github.com/Phipli/SmartBox/issues/

* [[SmartBox JobList]] - A list of the available jobs (routines) provided by the Smart Box OS that can be invoked from the serial link.
* [[SmartBox OS]] - Information about the organisation of the operating system and development of additional jobs.
* [[SmartBox AlbertLink]] - Details of the AlbertLink job used by the Smart Move software.

Digital Sensors

2023-10-25T20:45:28Z

Benryves: /* An example project */ Added Macintosh monitor window graphic

The range of digital sensors allow simple on / off conditions to be detected.
The sensors are connected between the pairs of red and yellow digital sensor sockets on the top of the box.
When the sensor is in its ‘On’ condition the indicator on the box will light.
The Smart Move software can detect the condition of the switch as ‘On’ or ‘Off’ or alternatively ‘1’ or ‘0’.
Both these Smart Move program lines are valid:

IF SENSOR 1 IS ON THEN FORWARD A
IF SENSOR 1 = 1 THEN FORWARD A

<gallery>
File:Sensor-Push-Switch.svg|A '''Push Switch''' can be used as a manual input device. The switch is normally ‘Off’ and will be detected as ‘On’ when pressed.
File:Sensor-Tilt-Switch.svg|A '''Tilt switch''' can be used to detect when an object has moved beyond a particular angle.
File:Sensor-Magnetic-Switch.svg|A '''Magnetic Switch''' will be ‘On’ when a magnet is close to the end.
</gallery>

== Making your own sensors ==

Any device which completes a circuit between a red and yellow socket on Smart Box can be used as a digital sensor.
This can be as simple as two contacts closing together.
Switches can be manufactured using card and tin foil, pegs and drawing pins etc.

== An example project ==

The following example uses three digital sensors and a buzzer to create a simple security system.

Sensors 0 and 1 are magnetic contact switches which will open as a door or window is opened.
A push switch is connected to sensor 2 which is used to switch off the system.
The Digital sensors can be ‘Labelled’ or given an alternative name using the LABEL command in Smart Move.
This makes the sensors easier to identify.
In the same way some of the Smart Move keywords can be changed.
In this example the keyword OFF is changed to OPEN.
The [[LABEL|reference section]] gives more details.

[[File:Monitor-Alarm-Sensor-Labels.png|frame|right|Macintosh monitor window showing labels]]

Type in the following as direct commands

LABEL OFF open
LABEL SENSOR0 door
LABEL SENSOR1 window
LABEL SENSOR2 turnoff
LABEL OUTPUT0 buzzer

Type in all the procedures as shown then run the ''Alarm'' procedure.

=== Procedure: Alarm ===

REPEAT
IF DOOR IS OPEN THEN Soundalarm
IF WINDOW IS OPEN THEN Soundalarm
UNTIL TURNOFF IS ON
Stopalarm

=== Procedure: Soundalarm ===

SWITCH ON buzzer PULSE 50,50

=== Procedure: Stopalarm ===

SWITCH OFF buzzer

[[Category:Sensors]]

File:Monitor-Alarm-Sensor-Labels.png

2023-10-25T20:43:12Z

Benryves:

Macintosh monitor window showing labels

File:Output-7-Segment-Display.svg

2023-10-24T00:22:03Z

Benryves: Benryves uploaded a new version of File:Output-7-Segment-Display.svg

== Summary ==
7-Segment display board

File:Output-7-Segment-Display-Connection.svg

2023-10-24T00:21:27Z

Benryves: Benryves uploaded a new version of File:Output-7-Segment-Display-Connection.svg

Connections between a 7-segment display board and the Smart Box

File:Tutorial-Printing-Procedures.svg

2023-10-24T00:09:19Z

Benryves: Benryves uploaded a new version of File:Tutorial-Printing-Procedures.svg

Printer printing a single procedure

Printing procedures

2023-10-24T00:08:48Z

Benryves: Added the missing printer image

To print your procedures first check that your printer is on line and ready.
Type LIST followed by the procedure name.
The procedure will be printed to your printer.

[[File:Tutorial-Printing-Procedures.svg|frameless]]

[[Category:Tutorial]]

File:Tutorial-Printing-Procedures.svg

2023-10-24T00:07:28Z

Benryves:

Printer printing a single procedure

Template:Output gallery

2023-10-23T23:42:28Z

Benryves: Added double-pole relay

File:Output-Relay-Double-Pole.svg

2023-10-23T23:41:36Z

Benryves: Added a picture of a double-pole relay

== Summary ==
Added a picture of a double-pole relay