Difference between revisions of "Service calls"

From BeebWiki
Jump to: navigation, search
m (Jgharston moved page Paged ROM service calls to Service calls: .)
(quote comment from source code)
 
(18 intermediate revisions by 2 users not shown)
Line 12: Line 12:
  
 
The MOS expects every paged ROM to provide a service entry point, except for
 
The MOS expects every paged ROM to provide a service entry point, except for
BASIC which has none. Individual paged ROMs will implement a subset of
+
BASIC which has none. The call must always return. Individual paged ROMs will
functions depending on their purpose and complexity.
+
implement a subset of functions depending on their purpose and complexity.
  
 
'''Interface'''
 
'''Interface'''
Line 51: Line 51:
 
| 0 || No operation.  Paged ROMs are to ignore this call as it has already been serviced by a higher ROM. A must be preserved.
 
| 0 || No operation.  Paged ROMs are to ignore this call as it has already been serviced by a higher ROM. A must be preserved.
 
|- style="vertical-align:top"
 
|- style="vertical-align:top"
| 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.
+
| 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 issued on Soft Break.
 
|- style="vertical-align:top"
 
|- style="vertical-align:top"
| 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 <code>TYA:STA &0DF0,X</code>), 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.
+
| 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 <code>TYA:STA &0DF0,X</code>), 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.
 
|- style="vertical-align:top"
 
|- style="vertical-align:top"
 
| 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.
 
| 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.
Line 59: Line 59:
 
| 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.
 
| 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.
 
|- style="vertical-align:top"
 
|- style="vertical-align:top"
| 5 || Unrecognised interupt.
+
| 5 || Unrecognised interrupt.
 
|- style="vertical-align:top"
 
|- style="vertical-align:top"
 
| 6 || Error occured. The error block is pointed to by &FD/E.
 
| 6 || Error occured. The error block is pointed to by &FD/E.
Line 71: Line 71:
 
| &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.
 
| &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.
 
|- style="vertical-align:top"
 
|- style="vertical-align:top"
| &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<ref>Acorn Application Note 031</ref> of the previous owner (which the releaser got from OSBYTE after issuing call &C.) A should be preserved.
+
| &0B || NMI code area is being released. The current owner of the NMI area is returning it to the previous owner<ref name="dnfs300-src-nfs01">Comment in source code, Acorn Computers, source code to DNFS 3.00, file <tt>[https://github.com/stardot/AcornDNFSv300/blob/master/src/NFS01#L130 NFS01]</tt>, l.130: <tt>Relinquish NMI, restore old user</tt></ref> or to the MOS by default. On entry Y contains the filing system ID<ref name="appnote031-037">Acorn Computers, Application Note 031 or 037, "Functional Differences Between Master 128 and BBC Models B and B+"</ref> 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.<ref name="appnote031-037" />
 
|- style="vertical-align:top"
 
|- style="vertical-align:top"
| &0C || NMI code area is being claimed. On receiving this call the current owner should relinquish the area and return A=0 and its FS ID number in Y. The issuer of the call should save the return value and pass it when issuing call &B.
+
| &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.<ref name="footnote-ddos">DDOS 3.46 does not issue call &0B if call &0C returned Y=&FF; this is arguably improper.</ref> It should then immediately place its code at &0D00, or 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<ref name="appnote031-037" /> – 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.<ref name="footnote-gazump">Its claim could only be usurped if an interrupting IRQ service routine claimed and took over the NMI resource, which is deprecated.</ref>  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.
 
|- style="vertical-align:top"
 
|- style="vertical-align:top"
| &0D || RFS initialisation. An RFS ROM should take the low 4 bits of location &F5 (also provided in Y on entry) 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.
+
| &0D || RFS initialisation. An RFS ROM should take the low 4 bits of Y<ref name="footnote-0d">A.Dickens, M.Holmes (1987), ''The new advanced user guide for the BBC microcomputer''. Cambridge: Adder Publishing Limited, p.315. Also AUG p.324.<br>However the example RFS ROM code in the NAUG (pp.318&ndash;321), and ROMs derived from it, take the current RFS ROM number from location &F5 set by RFS, ignoring the Y parameter passed through OSBYTE &8F.</ref> 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.
 
|- style="vertical-align:top"
 
|- style="vertical-align:top"
 
| &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.
 
| &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.
 
|- style="vertical-align:top"
 
|- style="vertical-align:top"
| &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 should not use this call to relinquish the shared workspace at &E00, 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.
+
| &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.<ref name="footnote-0f">Call &0F is the only warning to ROMs that the CFS is being selected.  Some ROMs vacate the shared workspace as a precaution, as applications commonly assume the shared workspace is free when <code>*TAPE</code> is in effect.</ref>  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.
 
|- style="vertical-align:top"
 
|- style="vertical-align:top"
 
| &10 || <code>*SPOOL</code>/<code>*EXEC</code> file closure warning. Intended for those using the aforementioned files.
 
| &10 || <code>*SPOOL</code>/<code>*EXEC</code> file closure warning. Intended for those using the aforementioned files.
Line 95: Line 95:
 
| &16 || BEL request. If the external sound flag has been set on the Electron, this call will be made when VDU 7 is issued.
 
| &16 || BEL request. If the external sound flag has been set on the Electron, this call will be made when VDU 7 is issued.
 
|- style="vertical-align:top"
 
|- style="vertical-align:top"
| &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.
+
| &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.
 
|- style="vertical-align:top"
 
|- style="vertical-align:top"
 
| &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.
 
| &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.
Line 123: Line 123:
 
| &2C || Master Compact joystick call.
 
| &2C || Master Compact joystick call.
 
|- style="vertical-align:top"
 
|- style="vertical-align:top"
| &30 || The Internationalisation ROM uses this call.
+
| &30 || Translate Internationalised keyboard keypress.<br>On entry, Y=hardware keycode number &80-&FF.<br>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.
 +
|- style="vertical-align:top"
 +
| &31 || Keyboard driver call.
 
|- style="vertical-align:top"
 
|- style="vertical-align:top"
 
| &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.
 
| &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.

Latest revision as of 16:41, 23 December 2020

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 issued 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 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 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 interrupt.
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[1] 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. The current owner of the NMI area is returning it to the previous owner[2] or to the MOS by default. On entry Y contains the filing system ID[3] 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.[3]
&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.[4] It should then immediately place its code at &0D00, or 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[3] – 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.[5] 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[6] 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.[7] 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 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.

References

  1. X is immediately clobbered on return (OS 1.20: &F17E = TAX); after this call X is recovered from &F0 (&E7D1).
  2. Comment in source code, Acorn Computers, source code to DNFS 3.00, file NFS01, l.130: Relinquish NMI, restore old user
  3. 3.0 3.1 3.2 Acorn Computers, Application Note 031 or 037, "Functional Differences Between Master 128 and BBC Models B and B+"
  4. DDOS 3.46 does not issue call &0B if call &0C returned Y=&FF; this is arguably improper.
  5. Its claim could only be usurped if an interrupting IRQ service routine claimed and took over the NMI resource, which is deprecated.
  6. A.Dickens, M.Holmes (1987), The new advanced user guide for the BBC microcomputer. Cambridge: Adder Publishing Limited, p.315. Also AUG p.324.
    However the example RFS ROM code in the NAUG (pp.318–321), and ROMs derived from it, take the current RFS ROM number from location &F5 set by RFS, ignoring the Y parameter passed through OSBYTE &8F.
  7. Call &0F is the only warning to ROMs that the CFS is being selected. Some ROMs vacate the shared workspace as a precaution, as applications commonly assume the shared workspace is free when *TAPE is in effect.