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
X	= preserved
Y	= return value

Later ROMs follow Master Series documentation and preserve the X register, by restoring the slot number to it, before returning. Some earlier titles return with X undefined. Preserving X becomes significant when chaining firmware modules together to share a paged ROM slot.

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. 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 and Y 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 lowest free page number of absolute workspace (1 page = 256 bytes). If and only if the current ROM needs more workspace, it should increase Y to 1 plus 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 issued on Soft Break.
2	Request private workspace. On entry Y contains the number of the lowest free page. Hazel-aware ROMs should first test their private page allocation (at &0DF0 + X) and return if their private workspace is already fully accommodated below page &DC. The ROM should store Y 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 issued 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 recognise the first word of the *command passed to it. (*commands that do not start with a word are sent straight to the FS via FSCV call 3.) 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 interrupt. A device driver ROM should poll its device. If and only if its device is responsible for the interrupt it should service it and claim the call. It should pass or service the call as quickly as possible. If the call is unclaimed then the interrupt is passed to IRQ2V.
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. FSCV call 6, a change of filing system vectors, and then service call &0F, should always precede or follow this call. A filing system must not call its public entry points to clean up, as an incoming FS may already have changed the vectors; it must call its internal routines instead.
&0B	NMI code area is being released. The current owner of the NMI area is returning it to the previous owner or to the MOS by default. On entry Y contains the filing system ID of the previous owner (which the releaser got from OSBYTE after issuing call &0C), or Y=&FF if the MOS was the previous owner. The filing system identified in Y, if not shutting down, has an opportunity to reinstall its background NMI service routine and return A=0, otherwise A should be preserved and the NMI area left alone. Non-ROM users of the NMI area may intercept OSBYTE &8F to listen for this call.
&0C	NMI code area is being claimed. The issuer of this call sets Y=&FF. It should save the value returned in Y and pass it when issuing call &0B. Y=&FF on return indicates the MOS was the previous owner. It should then immediately place its code at &0D00, or else an RTI instruction to ignore spurious interrupts. An owner using the NMI area in the background must listen for service call &0C – by intercepting OSBYTE &8F if it is not a ROM – and vacate the NMI area when claimed. A foreground routine that has control until it releases the area need not listen for calls &0B or &0C. Mass storage drivers such as Acorn DFS are of the foreground type. On receiving this call, 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, 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. Acorn source code comments imply that this call refers exclusively to the filing system vectors, FILEV to FSCV. 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 Electron, 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 absolute workspace in Hazel. On entry and exit Y contains the lowest free page number of absolute workspace (1 page = 256 bytes). If and only if the current ROM needs more workspace, it should increase Y to 1 plus the highest page number it uses. Y must not exceed &DC. A must be preserved. Absolute workspace is for filing system ROMs only. See Using high workspace.
&22	Claim private workspace in Hazel. On entry Y contains the number of the lowest free page; it should be treated as &C0 if less. The ROM should store this number in the space provided (with TYA:STA &0DF0,X), and increase Y by the number of pages it needs - except that Y must not exceed &DC on exit. In that case it must decrease Y to return part or all of its claim, and attempt to claim main memory during call &02 instead. A must be preserved. Filing system ROMs only. See Using high workspace.
&23	Reports top of absolute workspace. This call informs filing system ROMs how much absolute workspace has been allocated - the end page number (that is, the lowest page number of private workspace) is in Y. Advanced ROMs may then make use of the extra pages beyond their requested allocation. A and Y must be preserved. Filing system ROMs only.
&24	Private workspace in Hazel count. The current ROM decreases Y by the number of pages of private workspace required. A must be preserved. Filing system ROMs only.
&25	Return filing system information. On entry and exit (?&F2),Y points to the end of the filing system information table. A filing system ROM may append a number of 11-byte entries consisting of: 8 bytes filing system name (space-padded), 1 byte lowest valid file handle, 1 byte highest valid file handle, 1 byte filing system ID. The ROM must preserve A, ?&F2 and ?&F3 and return the offset of the new end of the table in Y. Filing systems named in the table may be used as temporary filing systems and must support service call &12.
&26	*SHUT command issued.
&27	Reset call. Acorn DFS 2.29 uses this call to discard the cached catalogue after pressing Break.
&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.

See also

• Using high workspace