ALL ABOUT XBIOS FUNCTIONS by Richard Karsmakers
Originally published in ST NEWS Volume 1 Issue 5, launched on
October 5th 1986.
Example: move.l capslock,-(sp)
This function enables you to redefine the keyboard tables (3 in
all). Therefore, you'll have to specify the addresses on which the
tables are located for normal keys ('normal'), keys with Shift
('shift') and keys with Caps Lock ('capslock'). Each table must be
128 bytes in length. The function returns the pointer to a table
in which all three vectors are written. If one of the keyboard
tables should not be changed, you should specify -1 instead of the
memory address. The tables are scanned through the key-scancode
and they will result in giving the ASCII-code belonging to that
Example: move.w #17,-(sp)
This function returns a 24-bit random number. Bits 24-31 will be 0
(cleared). At each call of this function, one will get a different
random number. At each system power-up, another starting-value
will be generated.
Example: move.w execflag,-(sp)
This function enables you to create a boot sector. The boot sector
is located on track 1, sector 0 and tells to TOS all kinds of
things about the disk format, e.g. disk type. If this boot sector
is set to be executable, the Operating System can be loaded. With
this function you can change or create a boot sector.
'execflag' is used to specify if the boot sector is executable or
0 Not executable
-1 The boot sector stays like it was
'disktype' can have one of the following values:
0 40 tracks, single sided (180K)
1 40 tracks, double sided (360K)
2 80 tracks, single sided (360K)
3 80 tracks, double sided (720K)
'serialnr' is a 24-bit serial number, that will be written into
the bootsector. This serial number is supposed to be never the
same on any disk, and TOS therefore uses it to check if a disk is
changed. If you specify a value larger than 24 bits (e.g.
$01000000), a random serial number will be created with function
number 18 (see previous page). If it's -1, the serial number will
not be changed. In this part of the disk, a serious error can be
found. For example, when one formats a disk with the program "ST
Happy + Maxiformatter" it will always have the same serial number.
If you have for instance opened a folder, and if you change a disk
and then hit the ESC key, you will get a garbled directory (which
can cause a system crash sometimes). Normally, you'd get an empty
'buffer' is the pointer to a 512-byte buffer, located somewhere in
memory, that contains the contents of the boot sector to be
A bootsector is normally built up like this:
Address: 80 Track SS: 80 Track DS:
0-1 Branch-instruction on boot-code if executable
8-10 24-bit serial number
11-12 BPS 512 512
13 SPC 2 2
14-15 RES 1 1
16 FAT 2 2
17-18 DIR 112 112
19-20 SEC 720 1440
21 MEDIA 248 249
22-23 SPF 5 5
24-25 SPT 9 9
26-27 NSIDE 1 2
28-29 NHID 0 0
58-509 BOOTIT Code
'Loader' is for use with several programming tools, to enable them
to recognize a Loader boot sector.
'BPS' is the number of bytes per sector. Normally, this is 512
bytes but it can also be 1024 bytes or another value.
'SPC' is the number of sectors per cluster. Normally, this is 2,
but it is possible to format a disk so that it is 1 or maybe 3 or
more. The smaller the number, the more economical is disk usage
(with a value of 2, 2*512=1024 bytes are allocated even for a 1-
'RES' is the number of reserved sectors at the beginning of the
disk, including the boot sector.
'FAT' is the number of FATs (File Allocation Tables; one can
compare it with the Block Availability Map or BAM on the Commodore
1541 disk drives) on a disk. The more FATs, the safer is your data
on the disk. But it takes quite a lot of space as well.
'DIR' is the maximal number of directory entries on a disk. A
directory entry is any entry on the disk's root directory (so all
the names that appear on a disk drive window once you've opened
it, including the folders).
'SEC' is the total number of sectors on your disk.
'MEDIA' is the Media Descriptor Byte. ST BIOS doesn't use this
byte, but other file systems might!
'SPF' is the number of sectors that are included in each FATY
entry (read more about the FAT in previous issues of ST NEWS - the
articles about disk manipulation in issues 2 and 3).
'SPT' is the number of sectors per track. This value is normally
9, but can range from 0 to 11 theoretically (1 to 10 practically).
'NSIDE' is the number of sides on the disk. Logically, this will
be 1 on any single-sided disk, and 2 on any double sided disk.
'NHID' is the number of "Hidden" sectors on the disk. ST BIOS
ignores this value for floppies.
'EXECFLG' is a word that is copied to the system variable
_cmdload. As you could have read in ST NEWS Volume 1 Issue 2, when
this system variable is set to 0, the desktop will appear after
booting. If set to nonzero, TOS will try to load an application
(DOS shell, etc.) first. An example of an application is the
Command Shell of Atari. The file must be called COMMAND.PRG.
'LDMODE' specifies the load mode. If it is zero, the file with the
name 'FNAME' will be loaded and executed. If 'LDMODE' is nonzero,
however, 'SECTCNT' sectors (starting at logical sector number
'SSECT') will be loaded and executed.
'SSECT' is the logical sector number to start loading from. This
value is only useful when 'LDMODE' is nonzero.
'SECTCNT' is the number of sectors to load. Like 'SSECT', this
value is only useful when 'LDMODE' is nonzero.
'LDADDR' is the memory-address on which a file (or sectors) will
be loaded. In case of TOS on disk, this will be $40000.
'FATBUF' points to a memory location where the FAT-and directory
sectors can be put.
'FNAME' is the filename of the file that will be loaded when
'LDMODE' equals zero. It consists of the normal eight characters
of the name, together with three characters for the file
'BOOTIT' is bootcode.
Because the bootsector is MS-DOS 2.x compatible, all 16-bit words
are written in 8086-format: Low-byte first, High-byte second.
Example: move.w count,-(sp)
This function enables you to verify one or several sectors of a
disk. The sectors will be read from disk and compared with the
contents of a buffer. The parameters have the same meaning as
those explained by the commands to read or write sectors. When the
contents of the buffer are the same as the contents of the
sectors, the function returns the value 0. When an error occurs,
you will find that (as a negative value) in D0. The error codes
are explained by the function 'floprd'.
When it turns out that one or more sectors do not match with the
buffer contents, you will be able to find a list of bad sectors in
the buffer you specified, each as a longword. The last sector
number will be marked by a zero after it.
When you use the BIOS function 5 (rwabs), and when the system
variable _fverify is set (that is the variable at location $444),
sectors are automatically verified.
Example: move.w #20,-(sp)
This function makes it possible to make a screen hardcopy on a
printer that is hooked up to your ST. Thereby, XBIOS uses the pre-
set printer parameters. This function can be called at any time by
simultaneously pressing ALTERNATE and HELP or choosing "Print
Screen" from the Desktop ("Options").
Example: move.w rate,-(sp)
This function can specify the function of the cursor (in case you
didn't know: that's the small black rectangle somewhere on the
screen of you're working with First Word (Plus)).
'function' can have one of the following values:
0 Turn cursor off
1 Turn cursor on
2 Flashing cursor
3 Non-flashing cursor
4 Set cursor flash-rate
5 Get cursor flash-rate
The value of 'rate' depends on if you're using a monochrome-or a
color video display. With a monochrome monitor this is 70 Hz,
whereas this value if 50 Hz for color monitors. When you want to
change the flash-rate, only then you'll have to use the 'rate'
parameter. Example: you can specify 30 if you want the cursor to
invert after every 30/70th second on a monochrome monitor or every
30/50th second on a color display.
Example: move.l time,-(sp)
This function enables you to set the date and time of the system.
Therefore you must set up the longword like this:
Bit 0- 4 Seconds/2
Bit 5-10 Minutes
Bit 11-15 Hours
Bit 16-20 Day 1-31
Bit 21-24 Month 1-12
Bit 25-31 Year 0-119 (minus Offset 1980)
Example: move.w #23,-(sp)
This function returns the current date and time of the system in
Example: move.w #24,-(sp)
If you have changed the keyboard table(s) with XBIOS 16 (keytbl),
this function enables you to get back to the standard key tables.
It is handy if you call this routine after ending your own program
that uses another keyboard table.
Example: move.l pointer,-(sp)
This function allows you to send commands to the keyboard
'pointer' is the address of a string that contains the commands.
'quantity' is the number of bytes in the string, of which 1 must
Example: move.w number,-(sp)
This function allows the user to halt an interrupt of the MFP
'number' is the number of the interrupt, from 0 to 15.
These are the Interrupts of the MFP 68901 processor:
0 Centronics Busy
1 RS232 DCD
2 RS232 CTS
4 RS232 Baudrate generator, Timer D
5 Timer C
6 Keyboard and MIDI ACIAs
7 Floppy Controller and DMA
8 Linefeed counter, Timer B
9 RS232 Sending error
10 RS232 Sending buffer empty
11 RS232 Receivance error
12 RS232 Receivance buffer filled
13 System Clock Timer A
14 RS232 Ring Indicator
15 Monochrome Monitor Detect
For more information about interrupt levels, etc., please refer to
pages 268-274 in "ST Intern", chapter 3.5.1.
Example: move.w number,-(sp)
This function is the opponent to the 'jdisint' function described
above. It is used to enable a MFP Interrupt again.
'number' is the number of the interrupt level to reactivate. See
above for a list of MFP Interrupt levels.
Example: move.w #register,-(sp)
This functions lets you access the GI-soundchip.
'register' must be the soundchip's register number, ranging from 0
to15. Bit 7 of the register number specifies if the register
should be read from or written to:
If you want to write to a register, 'data' will have to contain
the 8-bit value of the code to write. When this function is used
to read the register with the specified number, you get the value
of that register.
Example: move.w #bitnumber,-(sp)
This function sets a selected bit in port A of the Soundchip. The
individual bits have the following meaning:
0 Floppy Select side 0/side 1
1 Floppy Select drive A
2 Floppy Select drive B
3 RS232 RTS (Request to Send)
4 RS232 DTR (Data Terminal Ready)
5 Centronics Stobe
6 General Purpose Output
Example: move.w #bitnumber,-(sp)
This function clears s selected bit in Port A of the Soundchip.
The bitnumbers have the same meaning as described above.
Example: move.l vector,-(sp)
With this function one can start an MFP Timer, and specify an
Interrupt routine for it.
'timer' is the number of the timer in the MFP:
0 Timer A
1 Timer B
2 Timer C
3 Timer D
'data' and 'control' are the values that will be given to the
specified timer's data-and control-registers. Have a look at any
MFP 68901 hardware description concerning that.
'vector' is the address of the interrupt routine that belongs to
the specified timer.
The four timers of the MFP are partly used by the system already:
A Reserved for the user
B Horizontal Blank Counter
C 200 Hz system Timer
D RS232 Baudrate-generator
(the vector belonging hereto is free)
Example: move.l pointer,-(sp)
This function enables the user to comfortable use sounds.
'pointer' has to point to a string of sound-commands. These
commands may be used.
These commands are interpreted as register numbers, always to be
followed by a byte that will be loaded in the corresponding
This command is followed by an argument that will be loaded in a
This command must be followed by three arguments. The first one
must be the soundchip register number in which the contents of the
temporary will be copied. The second argument is a values that
complements that value. The command reaches its end when the third
byte (the end criterium) is equal to the contents of the temporary
These commands are always to be followed by one more argument.
When that argument equals zero, sound processing will be cut off.
When it isn't it specifies the number of timerticks (20ms, 50Hz)
that pass until the next sound processing occurs.
Example: move.w config,-(sp)
This function makes it possible to change or read the printer
configuration. When 'config' is -1, the configuration is read,
otherwise 'config' is installed as printer configuration.
The individual bits in 'config' have the following meaning:
0 Matrixprinter (0) or Daisywheel printer (1)
1 Color Printer (0) or Monochrome printer (1)
2 ATARI printer (0) or Epson printer (1)
3 Test mode (0) or Quality mode (1)
4 Centronics port (0) or RS232 port (1)
5 Tractorfeed (0) or Single sheet (1)
15 Always 0
Example: move.w #34,-(sp)
This function returns the pointer to a table of vectors that
contains the addresses to certain routines that handle the
keyboard processor. It is built up like this:
long midivec MIDI input
long vkbderr Keyboard error
long vmiderr MIDI error
long statvec IKBD status
long mousevec Mouse-routines
long clockvec Time routines
long joyvec Joystick routines (have a look at
this issue's "Question & Answers
for more information about this)
'midivec' points to a routine that writes MIDI data from the MIDI-
IN (from D0) to the MIDI buffer.
'vkbderr' and 'vmiderr' are called whenever an overflow is
detected from Keyboard-or MIDI-ACIAs.
The other vectors handle packets that come from mouse, joystick,
etc. If you write routines for this, you must watch out that they
end with an RTS and that they don't take more than 1 millisecond
The vectortable is located at $A0E and has the following vectors
Example: move.w repeat,-(sp)
This function enables manipulation of the keyboard-repeat.
'wait' specifies the time that passes before the key is
automatically repeated. The time is based upon the 50 Hz system
'repeat' specifies the time that passes for each repeat.
These two values can be changed from the Control Panel desk
When one of the parameters is set to -1, the corresponding value
is not changed. That way, this function will give the value at the
current moment in one word: bit 0-7 contain the 'repeat' value,
whereas bits 8-15 contain the 'wait' value.
Example: move.l parameter,-(sp)
This function looks very much liek XBIOS function 20 (scrdmp), but
this one expects a parameterlist. 'parameter' is the address of
that parameterlist, that is built up like this:
long blkprt Address of screen-RAM
int width Screen width
int height Screen height
int scrres Screen resolution (1,2 or 3)
int dstres Printer resolution (1 or 2)
long colpal Address of the color palette
int type Printer type (0-3)
int port Printer Port (0=Centronics,1=RS232)
long masks Pointer to half-tone mask
Example: move.w #36,-(sp)
This function can be used to synchronize graphics with wvbl of
the screen. It just waits until wvbl has occured.
Example: move.l address,-(sp)
This function may be used to execute the routine at 'address' in
Supervisor Mode of the 68000.
Example: move.w #39,-(sp)
This function turns of AES, as long as it's not in ROM.
That was it for today, folks. I've told you all I know about XBIOS
functions. I hope you will write to us if you have experienced
specific things with XBIOS functions, or if you have succesfully
used some rare XBIOS functions in GfA Basic using the XBIOS
command. Our address: ST NEWS, Kievitstraat 50, 5702 LE, Helmond,
The text of the articles is identical to the originals like they appeared in old ST NEWS issues. Please take into consideration that the author(s) was (were) a lot younger and less responsible back then. So bad jokes, bad English, youthful arrogance, insults, bravura, over-crediting and tastelessness should be taken with at least a grain of salt. Any contact and/or payment information, as well as deadlines/release dates of any kind should be regarded as outdated. Due to the fact that these pages are not actually contained in an Atari executable here, references to scroll texts, featured demo screens and hidden articles may also be irrelevant.