Service calls

The service entry is an entry point in a paged ROM that is called by the MOS, allowing the ROM to initialise, to claim and release resources, provide its own API and give help to the user.

Users, and paged ROMs themselves, can issue service calls by calling OSBYTE &8F.

Entry address: &8003, not vectored.

Availability

The MOS expects every paged ROM to provide a service entry point, except for BASIC which has none. The call must always return. Individual paged ROMs will implement a subset of functions depending on their purpose and complexity.

Interface

On entry:
A	= Service call number, reason code
X	= Paged ROM slot number (also in memory at address &F4)
Y	= Parameter to the service call

On exit:
A	= 0 if call has been dealt with, otherwise preserved
Y	= return value

Function

Starting at slot 15 and going down to 0, the MOS pages in every valid ROM and calls its entry point at &8003. On entry A contains the call number and Y contains a parameter for the call, where relevant. The values of A and Y returned by each ROM are passed directly to the next ROM's service routine in a daisy chain. Sometimes ROMs can pass information to each other in this way, but otherwise they should be careful to preserve registers unless they are responding to that call. ROMs should interpret the value of A on entry according to the following table:

A=	Meaning
0	No operation. Paged ROMs are to ignore this call as it has already been serviced by a higher ROM. A must be preserved.
1	Request absolute workspace. This workspace is in main memory, and shared between paged ROMs. On entry and exit Y contains the highest page number assigned to absolute workspace (1 page = 256 bytes). If and only if the current ROM needs more workspace, it should increase Y to the highest page number it uses. A must be preserved. Most ROMs also use this service call to initialise themselves on Break. On the Master series this call is not issue on Soft Break.
2	Request private workspace. On entry Y contains the number of the lowest free page. The ROM should store this number in the space provided (with TYA:STA &0DF0,X), increase Y by the number of pages it needs and return. A must be preserved. On the Master series this call is not issue on Soft Break.
3	Boot filing system. A filing system ROM should test the keyboard. If its assigned key, or no key is pressed, it should select itself as the current filing system. If Y is &00 it should boot the default media (for instance by testing the boot flags on it and issuing the relevant *command). If the filing system selected itself it should return with A=0.
4	Unrecognised OSCLI. The MOS does not understand the *command passed to it. On entry (&F2),Y points to the start of the string. Utility ROMs should scan the start of the string for commands they accept and if one is found, should process the command and return with A=0.
5	Unrecognised interupt.
6	Error occured. The error block is pointed to by &FD/E.
7	Unrecognised OSBYTE. On entry, the OSBYTE A, X and Y values are in memory locatons &EF, &F0 and &F1. If the call is claimed, it should return the X value in &F0 and the Y value in &F1.
8	Unrecognised OSWORD. The MOS does not understand the OSWORD call submitted to it. On entry the OSWORD reason code (A) can be found at &EF and the parameter block is pointed to by &F0 and &F1. This call will also be issued for unrecognised SOUND channels. If the ROM recognises the reason code it should process the OSWORD call and return with A=0.
9	*HELP. Similar to service call 4. On entry (&F2),Y points to the keyword after *HELP, or a carriage return. If there is no keyword the ROM should print its title and a list of accepted keywords. If an unrecognised keyword is present it should just return with A unchanged. Otherwise it should print its title and information about the keyword. The keyword may end with . (a dot) in which case it is an abbreviation and the ROM should give help about all matching keywords. The call should always return with A preserved so that other ROMs can match the keyword. The *HELP title should be printed with a leading NEWLINE so that there is a blank line before the text and no blank line after the text.
&0A	Absolute workspace is being claimed. The current user should save important data to its private page and vacate the workspace, setting a flag in its private page indicating that it no longer owns the workspace. A should be preserved.
&0B	NMI code area is being released. This notifies paged ROMs that the current owner of the NMI code area is releasing it. On entry Y contains the filing system ID of the previous owner (which the releaser got from OSBYTE after issuing call &C.) A should be preserved.
&0C	NMI code area is being claimed. The issuer of this call sets Y to its filing system ID if claiming the area to service NMIs in the background, Y = &FF if in the foreground (no listener recognises &FF as its own ID.) It should save the value returned in Y and pass it when issuing call &B. If it is installing a background NMI service routine it must listen for service call &0C – either via the Paged ROM service entry point or by intercepting OSBYTE &8F – and relinquish the NMI area on receipt. A foreground NMI handler, that is, one that possesses the main thread as long as NMIs are expected, will not have its NMI resource usurped and need not listen for call &0C. Mass storage drivers such as Acorn DFS are of the foreground type. On receiving this call, a listener should ignore it if the FS ID in Y is its own (on the assumption that it sent the call), otherwise the current owner must relinquish the area and return A=0 and its FS ID number in Y – not its ROM number as alleged in the AUG.
&0D	RFS initialisation. An RFS ROM should take the low 4 bits of Y and XOR them with &F. If the result equals or exceeds its slot number, it should should set &F6 and &F7 to the start address of its data, then store its slot number, similarly inverted, back in &F5 and return with A=0.
&0E	RFS data poll. On entry &F5 contains the current RFS ROM's slot number (inverted), &F6 and &F7 a pointer to the data in that ROM, and Y=255 iff the MOS implements OSRDRM, otherwise Y=0. The current RFS ROM should fetch the byte at the data pointer, increment the pointer and return A=0 and the byte in Y. Any higher ROM that supports OSRDRM may serve the call on its behalf, peeking in its data area, to save time. Compressed ROMs therefore need to be the highest priority RFS ROMs.
&0F	Vectors have changed. This notifies paged ROMs that something has changed the MOS call vectors from &200 onward. The service call may itself be issued by a paged ROM. The owner of the absolute workspace at &E00 retains it, and is not obliged to relinquish; it should only do that with service call &0A. However, on the Master series, when this call is received the ROM should relinquish the shared filing system workspace at &C000. A must be preserved.
&10	*SPOOL/*EXEC file closure warning. Intended for those using the aforementioned files.
&11	Bottom of user memory changing. This call informs languages that the operating system high water mark (the value PAGE is initialised to) is about to change. It is issued when the font is imploded or exploded. On entry Y contains the new memory limit. Note that as BASIC does not have a service entry, it ignores this warning.
&12	Select filing system. On entry, Y is the filing system number to be selected.
&13	Character placed in serial buffer. This call is made on systems without serial hardware when a character has been placed in the serial output buffer. If not claimed, the operating system purges the buffer.
&14	Character placed in printer buffer. This call is made on systems without printer hardware when a character has been placed in the printer output buffer. If not claimed, the operating system purges the buffer.
&15	100Hz poll. On Electron and Master series computers this call is made if the ROM polling semaphore is non-zero. On entry, Y contains the semaphore value.
&16	BEL request. If the external sound flag has been set on the Electron, this call will be made when VDU 7 is issued.
&17	SOUND buffer purged. If the external sound flag has been set on the Elctron, this call will be made if an attempt to purge any of the SOUND buffers is made.
&18	Interactive *HELP. This call is implemented on Master series computers and is issued after the *HELP service call (&09). ANFS responds by looking for and displaying a suitable file.
&21	Claim private workspace in Hazel.
&22	Claim absolute workspace in Hazel.
&23	Reports top of private workspace.
&24	Absolute workspace in Hazel count.
&25	Return filing system information.
&26	*SHUT command issued.
&27	Reset call.
&28	Unknown *CONFIGURE command.
&29	Unknown *STATUS command.
&2A	Language about to be entered.
&2B	Check for sideways RAM presence.
&2C	Master Compact joystick call.
&30	Translate Internationalised keyboard keypress. On entry, Y=hardware keycode number &80-&FF. On exit, &023C=translated keypress, &023D=flags, Y.b0=modifier key, no keypress to enter keyboard buffer, Y.b1=keyboard repeat needs to be cleared.
&31	Keyboard driver call.
&FE	Tube system post initialisation. This call is issued after OSHWM as been set up, and allows Tube software to explode the character set and set up anything else in memory. On entry Y contains the Tube presence flag, &FF if Tube present, &00 is absent. If the call is claimed then no startup message will be displayed.
&FF	Tube system main initialisation. This call is made after service call &FE if Tube hardware is present.