BIOS

Overview

The Basic Input/Output System (BIOS) is responsible for the lowest level of communications between the operating system and hardware devices. This chapter will document the operating system functions of the BIOS and other system level operations.

System Startup

OS Header

OS Configuration Bits

The pointer at offset $14 in the OS header points to the GEM Memory Usage Parameter Block which is defined as follows:

typedef struct
{
	/* $87654321 if GEM present */
	LONG gem_magic;

	/* End address of OS RAM usage */
	LONG gem_end;

	/* Execution address of GEM */
	LONG gem_entry;
} MUPB;	

Currently Running Process

The OS header entry _p_run is used to locate the of the basepage of the currently running process. This entry has only existed as of TOS 1.02 and should never be modified. The following routine returns the address of the basepage of the currently running process in all versions of TOS:

#define SPAIN		4
typedef long PID

PID *
get_run()
{
	OSHEADER *os = GetROMSysbase();

	if(os->os_version < 0x0102)
	{
		if(( os->os_conf >> 1 ) == SPAIN)
			return (PID *)0x873C;
		else
			return (PID *)0x602C;
	}
	else
		return (PID *)(os->p_run);
}

The Cookie Jar

Overview

The 'Cookie Jar' is a structure in memory containing entries called 'cookies' which are placed in the 'jar' by the operating system or Terminate and Stay Resident (TSR) applications. Applications can test for the presence of a cookie to determine the presence of a hardware device or system feature.

The variable _p_cookies points to multiple COOKIE structures as defined below:

	typedef struct
	{
		LONG cookie;
		LONG value;
	} COOKIE;

The structure member cookie contains a value that hopefully uniquely identifies the cookie. cookie values are 4-byte packed longword identifiers (often a 4 letter ASCII code word). Entries with the high byte equal to $5F, the underscore character, are reserved for use by Atari.

The structure member value may contain any value meaningful to an application or no value at all. In some cases a cookie won't have a meaningful value and its presence simply signals the existence of another process or system feature. TSR's often use value to store a pointer to an internal structure. The operating system uses cookies to signal the availability of hardware devices or system features.

The following code may be used to find a cookie in the cookie jar. It returns 0 if an error occurred or 1 if successful. If p_value is non-NULL on entry, the address it points to will be filled in with the value of the cookie.

	WORD
	getcookie( target, p_value )
	LONG target;
	LONG *p_value;
	{
			char *oldssp;
			COOKIE *cookie_ptr;
	
			oldssp = (Super(SUP_INQUIRE) ? NULL : Super(1L));

			cookie_ptr = *(COOKIE **)0x5A0;

			if(oldssp)
				Super( oldssp );

			if(cookie_ptr != NULL)
			{
				do
				{
					if(cookie_ptr->cookie == target)
					{
						if(p_value != NULL)
							*p_value = cookie_ptr->value;

						return 1;
					}
				} while((cookie_ptr++)->cookie != 0L);
			}

			return 0;
	}

Placing a Cookie

Only TSR programs should place cookies in the cookie jar. The cookie these programs place should either signal a function provided by the TSR or the presence of an expansion device. A CPX, desk accessory, or standard application should not place cookies in the jar.

To place a cookie, the TSR must first locate the current location of the cookie jar. It is possible that a cookie jar does not exist ( _p_cookies == 0 ). In that case, a new jar should be allocated.

In most instances, the cookie jar should be allocated in increments of 8 slots (though it is not a requirement). In addition, if the process installs a new cookie jar in a TOS version lower than 1.06 it is also the processes responsibility to remove it upon a warm reset. Calling the following code after installing the cookie jar for the first time will ensure that the cookie jar pointer is properly reset on a warm boot.

	RESMAGIC		equ		$31415926
	_resvalid		equ		$426
	_resvector		equ		$42A
	_p_cookies		equ		$5A0

						.globl	_unjar

	_unjar:			move.l	_resvalid,valsave
						move.l	_resvector,vecsave
						move.l	#reshand,_resvector
						move.l	#RESMAGIC,_resvalid
						rts

	reshand:			clr.l	_p_cookies
						move.l	vecsave,_resvector
						move.l	valsave,_resvalid
						jmp		(a6)

						.bss

	vecsave:			.ds.l		1
	valsave			.ds.l		1

After determining the location of the cookie jar, the application should search for the first empty slot in the jar by looking for a NULL in the cookie field of a slot. Next, the application must determine if this is the last slot in the jar by comparing the entry in the value field of the current cookie to the number of the actual slot you are comparing. For instance, if you have found NULL as the value for cookie in slot 16 and value is equal to 16, the jar is full and must be reallocated.

If the slot found is not the last one, the application can simply copy the current slot to the next slot and insert its own cookie.

If the jar must be reallocated, you should allocate enough memory to increase the size of the cookie jar, copy the old entries to the new jar, insert your entry as the last cookie in the jar, and finally terminate the jar with a cookie containing a NULL and the new number of slots you have allocated.

As of TOS 1.06, the operating system will place several cookies in the cookie jar to inform applications of certain operating system and hardware capabilities as follows:

cookie	value
_CPU	The low WORD of the CPU cookie contains a number representing the processor installed in the system as follows: Value Processor 0 68000 10 68010 20 68020 30 68030
_VDO	This cookie represents the revision of the video shifter present. The low WORD represents the minor revision number and the high WORD represents the major revision number. Currently valid values are: Major Minor Shifter 0 0 ST 1 0 STe 2 0 TT030 3 0 Falcon030
_FPU	This cookie identifies the presence of floating-point math capabilities in the system. A non-zero low WORD indicates the presence of software floating point support (no specific values have yet been assigned). The high WORD indicates the type of coprocessor currently connected to the system as follows: Value Meaning 0 No FPU is installed. 1 SFP004 2 68881 or 68882 3 68881 or 68882 and SFP004 4 68881 5 68881 and SFP004 6 68882 7 68882 and SFP004 8 68040 Internal 9 68040 Internal and SFP004
_FDC	This cookie indicates the capability of the currently connected floppy drive. The lowest three bytes is a code indicating the origin of the unit ('ATC' is an Atari unit). The upper byte is a value indicating the highest density floppy present as follows: Value Density 0 360 Kb/ 720 Kb 1 1.44 Mb 2 2.88 Mb
_SND	This cookie contains a bitmap of sound features available to the system as follows: Bit Feature 0 GI Sound Chip (PSG) 1 Stereo 8-bit Playback 2 DMA Record (w/XBIOS) 3 16-bit CODEC 4 DSP
_MCH	This cookie indicates the machine type with the major revision number in the high WORD and the minor revision number in the low WORD as follows: Major Minor Shifter 0 0 ST 1 0 STe 1 8 ST Book 1 16 Mega STe 2 0 TT030 3 0 Falcon030
_SWI	On machines that contain internal configuration dip switches, this value specifies their positions as a bitmap. Dip switches are generally used to indicate the presence of additional hardware which will be represented by other cookies.
_FRB	This cookie is present when alternative RAM is present. It points to a 64k buffer that may be used by DMA device drivers to transfer memory between alternative RAM and ST RAM for DMA operations.
_FLK	The presence of this cookie indicates that file and record locking extensions to GEMDOS exist. The value field is a version number currently undefined.
_NET	This cookie indicates the presence of networking software. The cookie value points to a structure which gives manufacturer and version information as follows: struct netinfo { LONG publisher; LONG version; };
_IDT	This cookie defines the currently configured date and time format, Bits #0-7 contain the ASCII code of the date separator. Bits #8-11 contain a value indicating the date display format as follows: Value Meaning 0 MM-DD-YY 1 DD-MM-YY 2 YY-MM-DD 3 YY-DD-MMBits #12-15 contain a value indicating the time format as follows: Value Meaning 0 12 hour 1 24 hourNote: The value of this cookie does not affect any of the internal time functions. It is intended for informational use by applications only.
_AKP	This cookie indicates the presence of an Advanced Keyboard Processor. The high word of this cookie is currently reserved. The low word indicates the language currently used by TOS for keyboard interpretation and alerts. See the explanation for the country code in the OS header earlier in this chapter for valid values.If this cookie is present on TOS 5.0 and higher then the system supports soft-loaded keyboard tables.
FSMC	This cookie indicates the presence of FSM or SpeedoGDOS. Its value field is a pointer to a structure as follows:typedef struct { LONG gdos_type; UWORD version; WORD quality; } GDOS_INFO;The gdos_type field determines the variety of GDOS. '_FSM' represents Imagen font-based FSM whereas '_SPD' represents Bitstream font-based FSM. version specifies the current GDOS version.quality determines the output quality of v_updwk(). The default setting is QUAL_DEFAULT (0xFFFF) which causes the driver to use the setting last set in the driver configuration accessory or CPX. This default setting may be overridden by placing a value of QUAL_DRAFT (0x0000) or QUAL_FINAL (0x0001) at this location. The quality setting should be restored to QUAL_DEFAULT at the end of each print job.
SAM\0	This cookie indicates the presence of System Audio Manager and the XBIOS extensions it provides. The value field is currently reserved for internal use.
MiNT	This cookie indicates the presence of MiNT (MultiTOS) and its value field is the current version number (ex: MiNT 1.02 has a value field of 0x00000102).

BIOS Devices

Two methods are provided for outputting characters to the screen. Output via BIOS device #2 subjects character codes to interpretation. Codes such as a carriage return (ASCII 13), line feed (ASCII 10), TAB (ASCII 9), CTRL-G (ASCII 7), and ESCAPE (ASCII 27) are interpreted as special cases and handled specially.

Output via BIOS device #5 causes all characters to be output literally to the screen without interpretation.

The Atari console device contains emulation code compatible with the VT52 standard. Special escapes may be used to manipulate the cursor and create text effects.

To send an escape sequence, one of the following codes (and possibly additional characters) must be sent following the ESCAPE character (ASCII 27):

Escape	Code	Effect
A	65	Move the cursor up one line. If the cursor is on the top line this does nothing.
B	66	Move the cursor down one line. If the cursor is on the bottom line this does nothing.
C	67	Move the cursor right one line. If the cursor is on the far right of the screen this does nothing.
D	68	Move the cursor left one line. If the cursor is on the far left of the screen this does nothing.
E	69	Clear the screen and place the cursor at the upper-left corner.
H	72	Move the cursor to the upper-left corner of the screen.
I	73	Move the cursor up one line. If the cursor is on the top line, the screen scrolls down one line.
J	74	Erase the screen downwards from the current position of the cursor.
K	75	Clear the current line to the right from the cursor position.
L	76	Insert a line by scrolling all lines at the cursor position down one line.
M	77	Delete the current line and scroll lines below the cursor position up one line.
Y	89	Position the cursor at the coordinates given by the following two codes. The screen starts with coordinates ( 32, 32 ) at the upper-left of the screen. Coordinates should be presented in reverse order, Y and then X.
b	98	This code is followed by a character from which the lowest four bits determine a new text foreground color.
c	99	This code is followed by a character from which the lowest four bits determine a new text background color.
d	100	Erase the screen from the upper-left to the current cursor position.
e	101	Enable the cursor.
f	102	Disable the cursor.
j	106	Save the current cursor position. (Only implemented as of TOS 1.02)
k	107	Restore the current cursor position. (Only implemented as of TOS 1.02)
l	108	Erase the current line and place the cursor at the far left.
o	111	Erase the current line from the far left to the current cursor position.
p	112	Enable inverse video.
q	113	Disable inverse video.
v	118	Enable line wrap.
w	119	Disable line wrap.

Media Change

BIOS Vectors

Reset Vector

Shortly after a warm boot the OS will jump to the address contained in the system variable resvector ($42A) if the value in the system variable resvalid ($426) contains the magic number $31415926. The OS will supply a return address to this code segment in register A6 but the subroutine must not utilize the stack as neither stack pointer will be valid.

If your process needs to do cleanup in the event of a warm reset (see "Placing a Cookie" earlier in this chapter) the following code installs a user routine to accomplish this.

	_resvalid		equ		$426
	_resvector		equ		$42A
	RESMAGIC		equ		$31415926

					.text

	installres:
					move.l	_resvalid,oldvalid
					move.l	_resvector,oldvector
					move.l	#myresvec,_resvector
					move.l	#RESMAGIC,_resvalid
					rts
	myresvec:
					*
					* Insert user code here
					*
					move.l	oldvector,_resvector
					move.l	oldvalid,_resvalid
					jmp		(a6)

					.bss

	oldvector:		ds.l		1
	oldvalid:		ds.l		1

					.end

System Bell Vector

As of TOS 1.06, the OS jumps through the address contained in the system variable bell_hook ($5AC) to ring the system bell. It is possible for a custom routine to hook into this vector to alter the bell sound. The user routine may modify registers D0-D2/A0-A2 and may chain to the old bell handler if desired. It is also safe to make BIOS and XBIOS calls following the procedure for calling from an interrupt (when not running under MultiTOS). The routine should either jump to the old handler or execute an RTS statement.

System Keyclick Vector

Applications may install custom routines which are called during every vertical blank (approx. 50-72 times per second). The OS performs several operations during the vertical blank as follows:

The system variable _frclock is incremented.

The system variable vblsem is tested. If 0, the vertical blank handler exits immediately.

All registers are saved.

The system variable _vbclock is incremented.

If the system is currently in a high resolution video mode and a low-resolution monitor is detected, the video resolution is adjusted and the vector found at system variable swv_vec is called.

The text cursor blink routine is called.

If a new palette has been selected since the last vertical blank, it is loaded.

If a new screen base address has been selected since the last vertical blank, it is selected.

Each of the "deferred" vertical blank routine handlers is called.

If the system variable prt_cnt is greater than -1, the vector at system variable scr_dump is called.

Saved registers are restored and processing continues.

The XBRA Protocol

The following code example shows how to correctly use the XBRA protocol in a routine designed to supplement the 680x0 TRAP #1 vector (GEMDOS):

instl_trap1:
			move.l		#my_trap1,-(sp)
			move.w		#VEC_GEMDOS,-(sp)
			move.w		#Setexc,-(sp)
			trap			#13
			addq.l		#8,sp
			move.l		d0,old_handler
			rts

			DC.L			'XBRA'
			DC.L			'SDS1'	; Put your cookie here
old_handler	DC.L			0

my_trap1:
			movem.l		d2-d7/a2-a6,-(sp)

			;
			; Your TRAP #1 handler goes here.
			;

			movem.l		(sp)+,d2-d7/a2-a6
			move.l		old_handler,-(sp)		; Fake a return
			rts								; to old code.

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.

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