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
                      BIOS  Function Calling Procedure


BIOS system functions are called via the TRAP #13 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 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
BIOS places return codes in D0.

The following example for Bconout() illustrates calling the BIOS from
assembly language:

move.w      #char,-(sp)
move.w      #dev,-(sp)
move.w      #$03,-(sp)
trap        #13
addq.l      #6,sp

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

_bios:
    ; Save the return code from the stack
    move.l  (sp)+,trp13ret
    trap    #13
    move.l  trp13ret,-(sp)
    rts

    .bss
trp13ret:
    .ds.l       1

With the above code, you could easily design a 'C' macro to add BIOS
calls to your compiler as in the following example for Bconout():

#define Bconout( a )    bios( 0x02, a )

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

Calling the BIOS from an Interrupt

The BIOS and XBIOS are the only two OS sub-systems which can be called
from an interrupt handler. Precisely one interrupt handler at a time may
use the BIOS 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?)

This method is not valid under MultiTOS.

The BIOS places return codes in D0.