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


GEMDOS system functions are called via the TRAP #1 exception. Function
arguments are pushed onto the current stack in reverse order followed by
the function opcode. The calling application is responsible for correctly
resetting the stack pointer after the call.

GEMDOS 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 following example for Super() illustrates calling GEMDOS from assembly
language:

clr.l       -(sp)
move.w      #$20,-(sp)
trap        #1
addq.l      #4,sp

'C' compilers often provide a reusable interface to GEMDOS that allows new
GEMDOS calls to be added with a macro as in the following example:

#define Super( a )  gemdos( 0x20, a )

The gemdos() function used in the above macro can be written in assembly
language as follows:

            .globl      _gemdos

            .text
_gemdos:
            move.l      (sp)+, t1sav    ; Save return address
            trap        #1              ; Call GEMDOS
            move.l      t1sav,-(sp)     ; Restore return address
            rts

            .bss

t1sav:      ds.l            1           ; Return address storage

            .end

GEMDOS is not guaranteed to be re-entrant and therefore should not be
called from an interrupt handler.

GEMDOS return values are stored in D0 on function exit.