HomeBIOSBIOSThe input/output channels of the BIOS

3.1 About the BIOS

The BIOS (BasicInput/Output System) functions represent the lowest level interface between the Atari's operating system and hardware, and are called via the 680X0 Trap #13. Preferably, these functions should not be used by application programs, as substantially more powerful functions on a higher level are available to provide better alternatives. Altogether the following functions are available:

• Bconin Read a character from a device
• Bconout Send a character to a peripheral unit
• Bconstat Get input status of a peripheral unit
• Bcostat Get status of a standard output device
• Drvmap Get information about attached devices
• Getbpb Get address to the bios parameter block of a unit
• Getmpb Speicherparameterblock ermitteln.
• Kbshift Fetch/set status of the shift keys
• Mediach Ask if the media has been changed
• Rwabs Direct read/write operation on a unit
• Setexc Set an get interrupt vector
• Tickcal Get time difference between two timer calls

The BIOS is reentrant in MagiC. This means that these functions can be also called up repeatedly from interrupts (as long as the relevant supervisor stack does not overflow...).

Note:

If you hook your own routines into the BIOS, then make sure that you construct them to be fully reentrant. Make no assumptions about the contents of the !

The BIOS receives its parameters from the stack; for this the last argument from the parameter list is stored as the first on the stack. Function results are returned in the processor register d0. Only registers d3-d7 and a3-a7 are saved, all others may be altered by the call.

See also: GEMDOS   XBIOS   Reset vector   VT-52 terminal

3.1.1 bios-trap

Name: »Bios« - Execute bios-trap
Syntax: LONG bios ( VOID, ... );
Description: The routine bios executes a TRAP #13 exception. The parameters passed depend on the particular BIOS function in each case.
Return value: The function returns a value of the data type LONG.
See also: gemdos   xbios   BIOS   Dispatcher

3.1.2 Bconin

Name: Bios console input
Opcode: 2
Syntax: int32_t Bconin ( int16_t dev );
Description: The BIOS routine Bconin reads in a character from a peripheral device. The following devices can be specified for dev:

dev Meaning
0 prn: (Printer/Parallel port)
1 aux: (aux device, the RS-232 port)
2 con: (Console)
3 MIDI port
4 Keyboard port
5 Screen
6 ST compatible RS232 port (Modem 1)
7 SCC channel B (Modem 2)
8 TTMFP serial port (Modem 3)
9 SCC channel A (Modem 4)


Note that the device numbers from 6 up are only available from the TOS030 of the Atari-TT. A wrong declaration for dev can lead to a system crash.
Return value: The function returns the read-in character as an ASCII value in the bits 0..7. When reading from the console, the bits 16 to 23 contain the scan-code of the relevant key. If, in addition, the corresponding bit of the system variable conterm is set, then the bits 24 to 31 contain the current value of Kbshift.
Availability: All TOS versions.
See also: Binding   Bconout   Keytbl   Bconmap

3.1.2.1 Bindings for Bconin

C: int32_t Bconin ( int16_t dev );
Assembler:
move.w    dev,-(sp)    ; Offset 2
move.w    #2,-(sp)     ; Offset 0
trap      #13          ; Call BIOS
addq.l    #4,sp        ; Correct stack

3.1.3 Bconout

Name: Bios console output
Opcode: 3
Syntax: VOID Bconout ( int16_t dev, int16_t c );
Description: The BIOS routine Bconout writes the character c to the peripheral device dev. The following devices can be specified for dev:

dev Meaning
0 prn: (Printer/Parallel port)
1 aux: (Aux device, the RS-232 port)
2 con: (Console, VT-52 terminal)
3 MIDI port
4 Keyboard port
5 Screen
6 ST compatible RS-232 port (Modem 1)
7 SCC channel B (Modem 2)
8 TTMFP serial port (Modem 3)
9 SCC channel A (Modem 4)


Note that the device numbers from 6 up are only available from the TOS030 of the Atari-TT.

Note: The function only returns when the character has actually been output by the relevant device. A wrong declaration for dev can lead to a system crash. All codes from 0x00 to 0xFF for the character c are interpreted as printable characters. Output via (5) is, incidentally, faster than via (2), as the VT-52 sequences do not have to be evaluated.
Return value: The function does not return a result.
Availability: All TOS versions.
See also: Binding   Bconin   Bconstat   Bconmap

3.1.3.1 Bindings for Bconout

C: VOID Bconout ( int16_t dev, int16_t c );
Assembler:
move.w    c,-(sp)      ; Offset 4
move.w    dev,-(sp)    ; Offset 2
move.w    #3,-(sp)     ; Offset 0
trap      #13          ; Call BIOS
addq.l    #6,sp        ; Correct stack

3.1.4 Bconstat

Name: Bios console status
Opcode: 1
Syntax: int16_t Bconstat ( int16_t dev );
Description: The BIOS routine Bconstat establishes the input status of a standard peripheral device dev. The following devices can be specified for dev:

dev Meaning
0 prn: (Printer/Parallel port)
1 aux: (Aux device, the RS-232 port)
2 con: (Console)
3 MIDI port
4 Keyboard port
5 Screen
6 ST compatible RS-232 port (Modem 1)
7 SCC channel B (Modem 2)
8 TTMFP serial port (Modem 3)
9 SCC channel A (Modem 4)


Note that the device numbers from 6 up are only available from the TOS030 of the Atari-TT. A wrong declaration for dev can lead to a system crash.
Return value: The function returns -1 when there are characters waiting in the buffer, and 0 if this is not the case.
Availability: All TOS versions.
See also: Binding   Bconin   Bconout   Bconmap

3.1.4.1 Bindings for Bconstat

C: int16_t Bconstat ( int16_t dev );
Assembler:
move.w    dev,-(sp)    ; Offset 2
move.w    #1,-(sp)     ; Offset 0
trap      #13          ; Call BIOS
addq.l    #4,sp        ; Correct stack

3.1.5 Bcostat

Name: Bios output status
Opcode: 8
Syntax: int32_t Bcostat ( int16_t dev );
Description: The BIOS routine Bcostat establishes the status of a standard output device dev. The following devices can be specified for dev on the Atari:

dev Meaning
0 prn: (Printer/Parallel port)
1 aux: (Aux device, the RS-232 port)
2 con: (Console)
3 Keyboard port
4 MIDI port
5 Screen
6 ST compatible RS-232 port (Modem 1)
7 SCC channel B (Modem 2)
8 TTMFP serial port (Modem 3)
9 SCC channel A (Modem 4)


Note that the device numbers from 6 up are only available from the TOS030 of the Atari-TT.

Note: According to Atari, the swap between the MIDI port (4) and the intelligent keyboard (3) compared to other BIOS functions has been retained from a bug in TOS 1.0 for reasons of compatibility.
Return value: The function returns the status of the output device, namely -1 if characters could be written, and 0 if the buffer is full.
Availability: All TOS versions.
See also: Binding   Bconout   Bconmap

3.1.5.1 Bindings for Bcostat

C: int32_t Bcostat ( int16_t dev );
Assembler:
move.w    dev,-(sp)    ; Offset 2
move.w    #8,-(sp)     ; Offset 0
trap      #13          ; Call BIOS
addq.l    #4,sp        ; Correct stack

3.1.6 Drvmap

Name: drive map
Opcode: 10
Syntax: int32_t Drvmap ( VOID );
Description: The BIOS routine Drvmap establishes the mounted drives. For each mounted drive one bit is set. Valid are:
Bit 0: Drive A
Bit 1: Drive B etc. (max 32 devices possible)


Note: The function returns the contents of the system variable _drvbits. To determine which drives are recognized by GEMDOS, you have to use the function Dsetdrv.
Return value: The function returns a bit-vector for the connected (mounted) drives.
Availability: All TOS versions.
See also: Binding   Dsetdrv

3.1.6.1 Bindings for Drvmap

C: int32_t Drvmap ( VOID );
Assembler:
move.w    #$A,-(sp)     ; Offset 0
trap      #13           ; Call BIOS
addq.l    #2,sp         ; Correct stack
GFA-Basic: Fehler%=Bios(10)

3.1.7 Getbpb

Name: Get Bios parameter block
Opcode: 7
Syntax: BPB *Getbpb ( int16_t dev );
Description: The BIOS routine Getbpb establishes the BIOS parameter block of the device dev, which is coded as follows:

dev Meaning
0 Drive A
1 Drive B
2 Drive C


Any further drives follow in a similar way. By calling this function the media-change status in the BIOS is reset.
Return value: The function returns the address of the BIOS parameter block.
Availability: All TOS versions.
See also: Binding   Getmpb

3.1.7.1 Bindings for Getbpb

C: BPB *Getbpb ( int16_t dev );
Assembler:
move.w    dev,-(sp)    ; Offset 2
move.w    #7,-(sp)     ; Offset 0
trap      #13          ; Call BIOS
addq.l    #4,sp        ; Correct stack
GFA-Basic: Fehler%=Bios(7,W:dev%)

3.1.8 Getmpb

Name: Get memory parameter block
Opcode: 0
Syntax: VOID Getmpb ( MPB *ptr );
Description: The BIOS routine Getmpb serves for initialising the memory management and is called at bootup by GEMDOS to create the original TPA. After this, Getmbp may not be used any more.
Return value: This function does not return a result.
Availability: All TOS versions.
See also: Binding   Getbpb   Program launch and TPA

3.1.8.1 Bindings for Getmpb

C: VOID Getmpb ( MPB *ptr );
Assembler:
pea       ptr          ; Offset 2
move.w    #0,-(sp)     ; Offset 0
trap      #13          ; Call BIOS
addq.l    #6,sp        ; Correct stack

3.1.9 Kbshift

Name: Keyboard shift status of the 'special' keys.
Opcode: 11
Syntax: int32_t Kbshift ( int16_t mode );
Description: The BIOS routine Kbshift establishes or alters the current state of the keyboard 'special' keys. If mode is negative, then only the state is established. If mode is 0 or greater than 0, then the corresponding status will be set.
The individual bits are defined as follows:

Bit Meaning
0 Right shift key
1 Left shift key
2 Control key
3 ALT key
4 Caps-lock
5 Right mouse button
6 Left mouse button
7 Alt Gr since TOS 4.06 (Milan)


Note: The function simply inquires an internal system variable of the BIOS, whose address can be calculated via _sysbase if required.
For TOS 1.0 this system variable is at address 0xE1B.
Return value: The function returns the set keyboard status.
Availability: All TOS versions.
See also: Binding

3.1.10 Bindings for Kbshift

C: int32_t Kbshift ( int16_t mode );
Assembler:
move.w    mode,-(sp)   ; Offset 2
move.w    #$B,-(sp)    ; Offset 0
trap      #13          ; Call BIOS
addq.l    #4,sp        ; Correct stack

3.1.11 Mediach

Name: Media change
Opcode: 9
Syntax: int32_t Mediach ( int16_t dev );
Description: The BIOS routine Mediach establishes whether the data-carrier 'medium' on the device dev has been changed since the last disk operation of the particular drive. Valid are:

dev = 0 (Drive A)
  = 1 (Drive B)
  = 2 (Drive C, similarly for other drives)


Note: One should never assume that a device's medium cannot be exchanged (removable disk catridge, CD-ROM, floppy drive, floptical ...). The recognition of a floppy disk change usually only works reliably if the floppy is not write-protected. In addition one should note that during formatting a floppy different serial numbers will be asssigned.
Return value: The function returns an integer-value with the following meaning:

Value Meaning
0 Media definitely has not changed.
1 Media might have changed.
2 Media definitely has changed.
Availability: All TOS versions.
See also: Binding   Flopfmt   Protobt

3.1.11.1 Bindings for Mediach

C: int32_t Mediach ( int16_t dev );
Assembler:
move.w    dev,-(sp)    ; Offset 2
move.w    #9,-(sp)     ; Offset 0
trap      #13          ; Call BIOS
addq.l    #4,sp        ; Correct stack
GFA-Basic: Fehler%=Bios(9,W:dev%)

3.1.12 Rwabs

Name: Read/write absolute
Opcode: 4
Syntax: int32_t Rwabs ( int16_t rwflag, VOID *buff, int16_t cnt, int16_t recnr, int16_t dev, int32_t lrecno );
Description: The BIOS routine Rwabs reads or writes data directly resp. from or to the drive that was specified with dev. The parameter rwflag is a bit-vector that specifies the type of operation. Valid are:
rwflag-bit Meaning
0 0 = Read
1 = Write
1 0 = Pay regard to media change
1 = Do not read of affect media-change status
2 0 = In case of error, start a retry
1 = Do not start a retry
For this, a hard disk driver that is compatible with AHDI 3.0 is required.
3 0 = Normal mode
1 = Physical mode (1)
For this, a hard disk driver that is compatible with AHDI 3.0 is required.


cnt characters from buffer buff will be transferred In recnr the starting sector on the drive will be specified. lrecno will be used only if recnr has the value -1, and an AHDI 3.0-compatible hard disk driver is available.
Return value: The function returns 0 if the access was successful, otherwise a negative number.
Availability: All TOS versions.
See also: Binding

3.1.12.1 Bindings for Rwabs

C: int32_t Rwabs ( int16_t rwflag, VOID *buff, int16_t cnt, int16_t recnr, int16_t dev, int32_t lrecno );
Assembler:
move.l    lrecno,-(sp)  ; Offset 14
move.w    dev,-(sp)     ; Offset 12
move.w    recnr,-(sp)   ; Offset 10
move.w    cnt,-(sp)     ; Offset  8
pea       buff          ; Offset  4
move.w    rwflag,-(sp)  ; Offset  2
move.w    #4,-(sp)      ; Offset  0
trap      #13           ; Call BIOS
lea       $12(sp),sp    ; Correct stack
GFA-Basic: Fehler%=Bios(4,W:rwflag%,L:buff%,W:cnt%,W:recnr%,W:dev%,L:lrecno%)

3.1.13 Setexc

Name: Set exception vector
Opcode: 5
Syntax: int32_t Setexc ( int16_t number, VOID (*vec)() );
Description: The BIOS routine Setexc sets or reads the contents of exception vectors. Valid are:

Parameter Meaning
number Number of the vector
vec New address (or -1)


Note: Ifvec is -1L, then the vector's previous value is returned.

The number of the exception vector to be set is, by the way, identical to the address to be set divided by 4.
Return value: The function returns the previous (or current) value of the vector.
Availability: All TOS versions.
See also: Binding   System Vectors   System variables

3.1.13.1 Bindings for Setexc

C: int32_t Setexc ( int16_t number, VOID (*vec)() );
Assembler:
pea       exchdlr      ; Offset 4
move.w    number,-(sp) ; Offset 2
move.w    #5,-(sp)     ; Offset 0
trap      #13          ; Call BIOS
addq.l    #8,sp        ; Correct stack

3.1.14 Tickcal

Name: Tick calculation
Opcode: 6
Syntax: int32_t Tickcal ( void );
Description: The BIOS routine Tickcal returns the number of milliseconds that have elapsed between two calls of the system timer.

Note: For this the function accesses the _timr_ms system variable.
Return value: Number of corresonding milliseconds
Availability: All TOS versions.
See also: Binding   System variables

3.1.14.1 Bindings for Tickcal

C: LONG Tickcal ( VOID );
Assembler:
move.w    #6,-(sp)     ; Offset 0
trap      #13          ; Call BIOS
addq.l    #2,sp        ; Correct stack

HomeBIOSBIOSThe input/output channels of the BIOS