Topic       : The ATARI Compendium
Author      : Scott Sanders / JAY Software
Version     : 1.25 (20/6/2003)
Subject     : Documentation
Nodes       : 1117
Index Size  : 32614
HCP-Version : 6
Compiled on : Atari
@charset    : UTF-8
@lang       : en
@default    : 
@help       : %About
@options    : +g -i -t4 +y +z
@width      : 100
View Ref-File
                     XBIOS  Function Calling Procedure


XBIOS system functions are called via the TRAP #14 exception. Function
arguments are pushed onto the current stack (user or supervisor) in reverse
order followed by the function opcode. The calling application is responsible
for correctly resetting the stack pointer after the call.

The XBIOS, like the BIOS may utilize registers D0-D2 and A0-A2 as scratch
registers and their contents should not be depended upon at the completion
of a call. In addition, the function opcode placed on the stack will be
modified. The XBIOS places its return code value in d0.

The following example for Getrez() illustrates calling the XBIOS from
assembly language:

                   move.w    #$04,-(sp)
                   trap      #14
                   addq.l    #6,sp

A 'C' binding for a generic XBIOS handler would be as follows:

    _xbios:
                    ; Save the return code from the stack
                    move.l   (sp)+,trp14ret
                    trap     #14
                    move.l   trp14ret,-(sp)
                    rts

                    .bss
    trp14ret:
                    ds.l     1

The XBIOS is re-entrant to three levels, however there is no depth checking
performed so interrupt handlers should avoid intense XBIOS usage. In
addition, no disk or printer usage should be attempted from the system timer
interrupt, critical error, or process-terminate handlers. Calling the XBIOS
from an Interrupt

The BIOS and XBIOS are the only two OS sub-systems which may be called
from an interrupt handler. Precisely one interrupt handler at a time may
use the XBIOS as shown in the following code segment:

    savptr          equ     $4A2
    savamt          equ     $23*2

    myhandler:
                    sub.l   #savamt,savptr

                    ; BIOS calls may be performed here

                    add.l   #savamt,savptr

                    rte     ; (or rts?)

Certain XBIOS calls are not re-entrant because they call GEMDOS routines.
The Setscreen() function, and any DSP function which loads data from disk
should not be attempted during an interrupt.

It is not possible to use this method to call XBIOS functions during an
interrupt when running under MultiTOS.

The XBIOS places this value in D0.