Home XBIOSXBIOS Sound routinesSound routines Keyboard functionsKeyboard functions

4.20 Special commands

• Blitmode Gets or changes blitter configuration.
• CacheCtrl CPU cache management.
• CJar Creates, interrogates and removes cookies.
• Dbmsg Outputs debug message.
• Janus Makes the "Janus" emulator available.
• Puntaes Switches off AES in ROM.
• Random Generates a random number.
• Ssbrk Reserves memory (only used internally).
• Supexec Starts routine in supervisor-mode.
• Trapper Hooks into system functions.
• WdgCtrl Sets the hardware watchdog.

See Also: Interface programming

4.20.1 Blitmode

Name: »blitter mode« - Blitter-chip configuration
 
Opcode: 64
 
Syntax: int16_t Blitmode( int16_t mode );
 
Description: Blitmode is an XBIOS routine to switch on the blitter or to verify its existence. If the parameter mode has the value -1 then one obtains the state of the blitter chip. All other values configure the blitter:
 

Bit Description
0 0 = Blitter off
  1 = Blitter on
1-14 Reserved
15 Must always be 0

Note: According to Atari the function may be used without checking the TOS version (although it is not present in TOS 1.0, for instance). This is possible due to a side-effect in the dispatcher of the XBIOS. However, it is better not to rely on this, as the corresponding trap may be diverted by other programs, so that the correct value may not be returned.
 
Return value: The function returns the properties of the blitter chip by the set bits:
 

Bit Meaning
0 0: Blitter off
  1: Blitter on
   
1 0: Blitter not present
  1: Blitter present
   
15 Always 0

All further bits are reserved.
 
Availability: Officially this function is present only as of TOS Version 1.02.
 
Group: Special commands
 
See Also: Binding
 

4.20.1.1 Bindings for Blitmode

C: #include <tos.h>
 
int16_t Blitmode( int16_t mode );
 
Assembler:
  
move.w    mode,-(sp)   ; Offset 2
move.w    #64,-(sp)    ; Offset 0
trap      #14          ; Call XBIOS
addq.l    #4,sp        ; Correct stack

4.20.2 CacheCtrl

Name: »CacheCtrl« - CPU cache management
 
Opcode: 160
 
Syntax: int32_t CacheCtrl( int16_t OpCode, int16_t Param );
 
Description: The XBIOS routine CacheCtrl serves for the management of the CPU cache.
 

OpCode Description
0 Return 0 to check that function is implemented
1 Flush data cache
2 Flush instruction cache
3 Flush data and instruction cache
4 Inquire data cache mode
5 Activation/deactivation of the data cache
   Param= 0, switch off
   Param= 1, switch on
   Write-back of the caches if necessary
6 Inquire instruction cache mode
7 Activation/deactivation of the command cache
   Param= 0, switch off
   Param= 1, switch on
   Write-back of the caches if necessary

Note:
Under the CT60 XBIOS, OpCode 5/7 has the same effect :
Param: 0 = disable all caches.
       1 = enable all caches.
All caches are: Data cache, store buffer, branch cache, instruction cache.
 
Return value: If successful the function returns the value 0, or EBADRQ when a value larger than seven is passed for OpCode.
 
As an alternative the driver "CPU Cache Control Driver v1.10" by Robert Federle and Thomas Tempelmann is available for other computers.
 
Availability: The function ist available on the Milan from TOS 4.06, in CT60 XBIOS as of Version v0.98a.
 
Group: Special commands
 
See Also: Binding
 

4.20.2.1 Bindings for CacheCtrl

C: int32_t CacheCtrl( int16_t OpCode, int16_t Param );
 
Assembler:
  
move.w    Param,-(sp)  ; Offset 4
move.w    OpCode,-(sp) ; Offset 2
move.w    #160,-(sp)   ; Offset 0
trap      #14          ; Call XBIOS
addq.l    #6,sp        ; Correct stack

4.20.3 CJar

Name: »CJar« - Creation, interrogation and removal of cookies
 
Opcode: 17226 (0x434A)
 
Syntax: int32_t CJar( int16_t mode, int32_t cookie, int32_t *value );
 
Description: The XBIOS routine CJar offers a simple way of creating, interrogating and removing cookies.
 
Parameter Meaning
   
mode Mode 0:
Obtains the value of a cookie and stores it at the specified address. If one passed a NULL-pointer for value, then only the existence of the cookie will be checked. If presence of the cookie is established, the call returns 0x6172 (="CJar_OK"), or a different value otherwise.
Mode 1:
Creates a new cookie. In this case, value points to a longword whose contents are copied into the cookie jar. If value is NULL (zero), then a value of zero is entered into the cookie jar. If the cookie already exists, the old value is overwritten.
This mode returns $6172 (="CJar_OK") if the addition was successful or -1 if the addition failed due to lack of room in the cookie jar.
Mode 2:
Removes the cookie cookie from the jar. The value of value is immaterial. If the removal was successful the return will be "CJar_OK", or another value otherwise.
Is only available if the system extension Liberty (cookie 'Lity') is installed.
cookie Cookie identifier
value Address of the buffer in which the data is to be stored.
Return value: If successful the function returns the value CJar_OK (0x6172).
 
Availability: The function is available when the cookie 'CJar' ($434A6172) is present. This is created by JARxxx (Cookie Jar Manager) or by Liberty.
 
Group: Special commands
 
See Also: Binding   Cookie function
 

4.20.3.1 Bindings for CJar

C: int32_t CJar( int16_t mode, int32_t cookie, int32_t *value );
 
Assembler:
  
pea       value          ; Offset 8
move.l    cookie,-(sp)   ; Offset 4
move.w    mode,-(sp)     ; Offset 2
move.w    #17226,-(sp)   ; Offset 0
trap      #14            ; Call XBIOS
lea       12(sp),sp      ; Correct stack

4.20.4 Dbmsg

Name: »Dbmsg« - Output debug message
 
Opcode: 11
 
Syntax: void Dbmsg( int16_t rsrvd, int16_t msg_num, int32_t msg_arg )
 
Description: Dbmsg allows special debugging messages to be sent to a resident debugger application.
 
srsrvd is currently reserved and should always be 5.
 
msg_num is the message number which you want to send to the debugging host. Values of 0x0000 to 0xEFFF are reserved for applications to define. Values of 0xF000 to 0xFFFF are reserved for special debugging messages. If msg_num is in the application defined range, it and the int32_t contained in msg_arg will be displayed by the debugger and the application will be halted. If msg_num is between 0xF001 and 0xF0FF inclusive then msg_arg is interpreted as a character pointer pointing to a string to be output by the debugger and debugging to halt. The string length is determined by the low byte of msg_num.
 
If msg_num is DB_NULLSTRING (0xF000), the string will be output until a NULL is reached.
 
If msg_num is DB_COMMAND (0xF100), msg_arg is interpreted as a character pointer to a string containing a debugger command. The command format is specific to the debugger which you are running. A useful example of this format when running under the Atari debugger allows a string to be output to the debugger without terminating debugging as shown in the following example:
 
Dbmsg( 5, DB_COMMAND, "echo 'Debugging Message';g" );
 
The Atari Debugger only understands the value DB_COMMAND (0xF100) for msg_num as of version 3. Though it is normally harmless to run an application with embedded debugging messages when no debugger is present in the system, distribution versions of applications should have these instructions removed.
 
Return value:
 
Availability: Only if a resident debugger was loaded, which supports this call. The only debugger that currently supports this call is the Atari debugger.
 
Group: Special commands
 
See Also: Binding
 

4.20.4.1 Bindings for Dbmsg

C: #include <tos.h>
 
void Dbmsg( int16_t rsrvd, int16_t msg_num, int32_t msg_arg )
 
Assembler:
  
move.l    msg_arg,-(sp)  ; Offset 6
move.w    msg_num,-(sp)  ; Offset 4
move.w    srsrvd,-(sp)   ; Offset 2
move.w    #11,-(sp)      ; Offset 0
trap      #14            ; Call XBIOS
lea       10(sp),sp      ; Correct stack

4.20.5 Janus

Name: »Janus« - Make the "Janus" emulator available.
 
Opcode: 43
 
Syntax: void Janus( int16_t mode )
 
Description: This function makes the hardware emulator "Janus" available. According to an article in ST-Computer 1996-04 p. 44, the following may be achieved with this:
 

mode Description
-1 Obtain the active parallel port
1 Switch to first parallel port
2 Switch to second parallel port
256 Quit Janus

Note: All statements without any guarantees, as the article is not very detailed.
 
Return value: Unknown, or see above.
 
Availability: Only with hardware emulator Janus.
 
Group: Special commands
 
See Also: Binding
 

4.20.5.1 Bindings for Janus

C: #include <tos.h>
 
void Janus( int16_t mode )
 
Assembler:
  
move.w    mode,-(sp)    ; Offset 2
move.w    #43,-(sp)     ; Offset 0
trap      #14           ; Call XBIOS
addq.l    #4,sp         ; Correct stack

4.20.6 Puntaes

Name: »punt AES« - Switch off AES in ROM
 
Opcode: 39
 
Syntax: void Puntaes( void );
 
Description: The XBIOS function Puntaes switches off the AES part of the operating system. The AES will start only if the "os_magic" in OSHEADER has the magic number 0x87654321. Puntaes sets the flag back (if possible) and reboots the system. Note that the call is only valid with disk-loaded AES's.
 
Hint: Ab MagiC 4.00 wurde diese Funktion verändert und besitzt verschiedene Unterfunktionen. Zum Aufruf muss zusätzlich der Wert 'AnKr' übergeben werden. Bei einer falschen Funktionsnummer wird EINVFN zurückgeliefert.
 
int32_t Puntaes ( 'AnKr', subfn, ... )

 

  • int32_t Puntaes ( 'AnKr', 0 )
    System beenden und zurück zum MacOS bzw. Windows
     

  • int32_t Puntaes ( 'AnKr', 1, int16_t keycode )
    Wandle folgenden Alt-Tastencode in ASCII u.
     

  • int32_t Puntaes ( 'AnKr', 2 )
    Neustart (warm_boot, nur für Atari)
     

  • int32_t Puntaes ( 'AnKr', 3 )
    Kaltstart (cold_boot, nur für Atari)
     

  • int32_t Puntaes ( 'AnKr', 4, int32_t key ) seit 12.04.1998
    Ermittle Cookie
    Liefert den Zeiger des Cookies key oder 0L wenn er nicht vorhanden ist.
     

  • int32_t Puntaes ( 'AnKr', 5 )
    Date2str: initialisiert die interne Variable datemode von MagiC und liefert einen Zeiger auf die interne Funktion date2str.
     
    void date2str ( int8_t *s, int16_t date );
    DOS-Datum in eine Zeichenkette umwandeln.
     

  • int32_t Puntaes ( 'AnKr', 6, vtsys *pointer )
    VT52 anmelden, alten Vektor zurückgeben. Ist pointer -1 dann wird nur der alte Vektor zurückgeliefert, bei 0 wird er gelöscht.
     

Return value: Die Funktion liefert kein Ergebnis.
 
Availability: All TOS versions.
 
Group: Special commands
 
See Also: Binding   Cookie function
 

4.20.6.1 Bindings for Puntaes

C: #include <tos.h>
 
void Puntaes( void );
 
Assembler:
  
move.w    #39,-(sp)    ; Offset 0
trap      #14          ; Call XBIOS
addq.l    #2,sp        ; Correct stack

4.20.7 Random

Name: »random generator« - Random number generator
 
Opcode: 17
 
Syntax: int32_t Random( void );
 
Description: The XBIOS routine Random returns a 24-bit random number (based on a clock in the computer).
 
Note: With this function we are not dealing with a hardware random number generator, but with a software version, which uses the following algorithm:
  
X = (X * 3.1415926...) + 1

The return value is X shifted by 8 bits to the right, i.e. using the lower three bytes of the returned int32_t. Incidentally, the behaviour for the complete number is pretty good, the inquiry of individual bits in the sense of reduced randomness is however not advisable.
 
Return value: The function returns a 24-bit random number.
 
Availability: All TOS versions.
 
Group: Special commands
 
See Also: Binding
 

4.20.7.1 Bindings for Random

C: #include <tos.h>
 
int32_t Random( void );
 
Assembler:
  
move.w    #17,-(sp)    ; Offset 0
trap      #14          ; Call XBIOS
addq.l    #2,sp        ; Correct stack

4.20.8 Ssbrk

Name: »set memory break point« - Reserve memory
 
Opcode: 1
 
Syntax: void *Ssbrk( int16_t count );
 
Description: The XBIOS routine Ssbrk reserves memory at the top of RAM. The number of bytes must be passed in count. This function must be called prior to the initialization of GEMDOS, and should therefore not be used by application programs. In all the Atari ROM versions this function is implemented only as a dummy routine.
 
Return value: The function returns the start address of the allocated memory segment.
 
Availability: All TOS versions.
 
Group: Special commands
 
See Also: Binding
 

4.20.8.1 Bindings for Ssbrk

C: #include <tos.h>
 
void *Ssbrk( int16_t count );
 
Assembler:
  
move.w    count,-(sp)  ; Offset 2
move.w    #1,-(sp)     ; Offset 0
trap      #14          ; Call XBIOS
addq.l    #4,sp        ; Correct stack

4.20.9 Supexec

Name: »supervisor execute« - Start routine in supervisor-mode.
 
Opcode: 38
 
Syntax: int32_t Supexec( int32_t (*func)( ) );
 
Description: The XBIOS routine Supexec executes a user-defined routine in supervisor-mode. func is the address of the function to be called in supervisor-mode.
 
Return value: The function returns the int32_t value returned by the user function.
 
Availability: All TOS versions.
 
Group: Special commands
 
See Also: Binding   Super
 

4.20.9.1 Bindings for Supexec

C: #include <tos.h>
 
int32_t Supexec( int32_t (*func)( ) );
 
Assembler:
  
pea       func         ; Offset 2
move.w    #38,-(sp)    ; Offset 0
trap      #14          ; Call XBIOS
addq.l    #6,sp        ; Correct stack

4.20.10 Trapper

Name: »Trapper« - Hook into system functions.
 
Opcode: 555
 
Syntax: int32_t xbios( 555, int16_t layer, int16_t install, int16_t opcode, void *function );
 
Description: With the aid of Trapper, other programs can hook themselves simply and effectively before and after system calls - even completely replace them - or add new system calls to the system.
 
With Trapper we are dealing with an external program!
 
More information in the instructions to be found there.
 
Return value:
 
Availability: The function is only present on computers on which the program Trapper has been installed.
 
Group: Special commands
 
See Also: Binding
 

4.20.10.1 Bindings for Trapper

C: #include <tos.h>
 
int32_t xbios( 555, int16_t layer, int16_t install, int16_t opcode, void *function );
 
Assembler:
  
pea (a2)                  ; TOS does not save A2 in traps
move.l    function,-(sp)  ; Offset 8
move.w    opcode,-(sp)    ; Offset 6
move.w    install,-(sp)   ; Offset 4
move.w    layer,-(sp)     ; Offset 2
move.w    #555,-(sp)      ; Offset 0
trap      #14             ; Call XBIOS
lea       12(sp),sp       ; Correct stack
move.l    (sp)+,a2        ; restore A2

4.20.11 WdgCtrl

Name: »WdgCtrl« - Set the hardware watchdog.
 
Opcode: 161
 
Syntax: int32_t WdgCtrl ( int16_t OpCode );
 
Description: This function disables or activates the hardware watchdog.
 

Parameter Value
OpCode 0x0000 - Return 0 to check that WdgCtrl is
           present
  0x1234 - Enable watchdog
  0xdead - Disable watchdog
  0x4242 - Re-trigger watchdog

Note: The function is only meant for the hardware of the Milan 2.1. The version however exists only as a special version and is not freely available.
 
Return value:
 
E_OK (0) - OK
EUNDEV (-15) - No watchdog present
EBADRQ (-5) - Unimplemented OpCode
Availability: The function is present from MilanTOS with the date 2002-06-09 onwards.
 
Group: Special commands
 
See Also: Binding
 

4.20.11.1 Bindings for WdgCtrl

C:
 
int32_t WdgCtrl ( int16_t OpCode );
 
Assembler:
  
pea (a2)                  ; TOS does not save A2 in traps
move.w    OpCode,-(sp)    ; Offset 2
move.w    #161,-(sp)      ; Offset 0
trap      #14             ; Call XBIOS
lea       4(sp),sp        ; Correct stack
move.l    (sp)+,a2        ; restore A2
Home XBIOSXBIOS Sound routinesSound routines Keyboard functionsKeyboard functions