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:

The <saveptr_area> of the BIOS is still present (for reasons of compatibility), but it is not used by the system.
The stack checks of Turbo C/Pure-C will fail for routines that are executed in supervisor-mode (under TOS this could happen until now only for USERDEF routines in the AES, that are also executed in supervisor-mode).

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 <saveptr_area>!

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.

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:

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:

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:

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:

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:

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:

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:

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:

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:

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 sectors 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

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:

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

BIOS

The input/output channels of the BIOS