Allocations

From BeebWiki
Revision as of 18:40, 24 November 2020 by Jgharston (talk | contribs) (Added info about OSBYTE A3.)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Allocating new OSBYTE numbers

OSBYTE calls <&80 are short OSBYTEs that only take and return a single parameter in the X register, OSBYTE calls >&7F are long OSBYTEs that take and return two 8-bit parameters or one 16-bit parameter. Unfortunately, all the long OSBYTEs are allocated, so the only remaining ones are short OSBYTEs.

However, OSBYTE &A3 is a multi-purpose OSBYTE that takes one parameter in Y for a specific application indicated by the value in X, and can return two bytes or one 16-bit value. Only a dozen or so OSBYTE &A3 calls have been allocated, so these calls could be more appropriate to use - especially if you want to be able to return 16 bits of information. High numbered OSBYTE &A3 calls should be used for something related to the similar-numbered OSBYTE call, for example OSBYTE &A3,&FD,num causes a system reset of the type specified by OSBYTE &FD.

If implementing a operating system interface on another host, then OSBYTEs can be repurposed if they perform the same function. For instance, use OSBYTE &9C (156) to control the serial port in the same manner.

Allocating new OSWORD numbers

Make proposals here for new OSWORD calls. Give a brief outline of what you want your call to do, and an outline parameter block, and also post it to StarDot.

Calls below &80 can only have up to 16 bytes control block. If your call needs more than 16 bytes it must be numbered above &7F.

Calls calls above &7F have a defined layout that specifies the size of the control block up to a maximum of 255 bytes, and a convention has grown up that byte XY+2 and XY+3 hold command and result information.

 XY?0 inward control block size (required)
 XY?1 returned control block size (required)
 XY?2 command
 XY?3 sub-command/returned status
 XY!4 data
 XY!8 data
 etc.

Examples

       OSWORD &B0  OSWORD &BE  OSWORD &BF  OSWORD &C0  OSWORD &C8
XY?0   in          in          in          in          in
XY?1   out         out         out         out         out
XY?2   command     command     command     command     in flags
XY?3   subcommand  flags       result      result      out flags
XY!4   data        address     URI string  socket      SWI
XY!8   data        data                    data        R0
XY!12  etc         etc                     length      R1
etc                                        etc         etc