XBIOS Functions II

 ALL ABOUT XBIOS FUNCTIONS by Richard Karsmakers

Originally  published  in ST NEWS Volume 1 Issue  5,  launched  on 
October 5th 1986.

16 keytbl

Example: move.l capslock,-(sp)
         move.l shift,-(sp)
         move.l normal,-(sp)
         move.w #16,-(sp)
         trap #14
         addq.l #14,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 
key.

17 random

Example: move.w #17,-(sp)
         trap #14
         addq.l #2,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.

18 protobt

Example: move.w execflag,-(sp)
         move.w disktype,-(sp)
         move.l serialnr,-(sp)
         move.l buffer,-(sp)
         move.w #18,-(sp)
         trap #14
         add.l #14,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 
not:
         0        Not executable
         1        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 
directory.
'buffer' is the pointer to a 512-byte buffer, located somewhere in 
memory,  that  contains  the  contents of the boot  sector  to  be 
written.

A bootsector is normally built up like this:

Address:        80 Track SS:      80 Track DS:

 0-1             Branch-instruction on boot-code if executable
 2-7             'Loader'
 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

30-31    EXECFLG
32-33    LDMODE
34-35    SSECT
36-37    SECTCNT
38-41    LDADDR
42-45    FATBUF
46-56    FNAME
57       (Reserved)
58-509   BOOTIT Code
510-511  CHECKSUM

'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-
byte file!).
'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 
extension.
'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.

19 flopver

Example: move.w count,-(sp)
         move.w side,-(sp)
         move.w track,-(sp)
         move.w sector,-(sp)
         move.w device,-(sp)
         clr.l -(sp)
         move.l buffer,-(sp)
         move.w #19,-(sp)
         trap #14
         add.l #20,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.

20 scrdmp

Example: move.w #20,-(sp)
         trap #14
         addq.l #2,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").

21 cursconf

Example: move.w rate,-(sp)
         move.w function,-(sp)
         move.w #21,-(sp)
         trap #14
         addq.l #6,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.

22 settime

Example: move.l time,-(sp)
         move.w #22,-(sp)
         trap #14
         addq.l #6,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)

23 gettime

Example: move.w #23,-(sp)
         trap #14
         addq.l #2,sp

This  function returns the current date and time of the system  in 
D0.

24 bioskeys

Example: move.w #24,-(sp)
         trap #14
         addq.l #2,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.

25 ikbdws

Example: move.l pointer,-(sp)
         move.w quantity,-(sp)
         move.w #25,-(sp)
         trap #14
         addq.l #8,sp

This  function  allows  you  to  send  commands  to  the  keyboard 
processor.

'pointer' is the address of a string  that contains the commands.
'quantity' is the number of bytes in the string,  of which 1  must 
be substracted.

26 jdisint

Example: move.w number,-(sp)
         move.w #26,-(sp)
         trap #14
         addq.l #4,sp

This  function  allows the user to halt an interrupt  of  the  MFP 
68901 processor.
'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
         3        Unused
         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.

27 jenabint

Example: move.w number,-(sp)
         move.w #27,-(sp)
         trap #14
         addq.l #4,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.

28 giaccess

Example: move.w #register,-(sp)
         move.w #data,-(sp)
         move,w #28,-(sp)
         trap #14
         addq.l #6,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:
         0        Read
         1        Write
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.

29 offgibit

Example: move.w #bitnumber,-(sp)
         move.w #29,-(sp)
         trap #14
         addq.l #4,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
         7        Unused

30 ongibit

Example: move.w #bitnumber,-(sp)
         move.w #30,-(sp)
         trap #14
         addq.l #4,sp

This  function clears s selected bit in Port A of  the  Soundchip. 
The bitnumbers have the same meaning as described above.

31 xbtimer

Example: move.l vector,-(sp)
         move.w fata,-(sp)
         move.w control,-(sp)
         move.w timer,-(sp)
         move.w #31,-(sp)
         trap #14
         add.l #12,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)

32 dosound

Example: move.l pointer,-(sp)
         move.w #32,-(sp)
         trap #14
         addq.l #6,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.

Commands $00-$0F
These commands are interpreted as register numbers,  always to  be 
followed  by  a  byte that will be  loaded  in  the  corresponding 
register.
Command $80
This  command is followed by an argument that will be loaded in  a 
temporary register.

Command $81
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 
register.

Commands $82-$FF
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.

33 setprt

Example: move.w config,-(sp)
         move.w #33,-(sp)
         trap #14
         addq.l #4,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)
         6-14     Reserved
        15        Always 0

34 kbdvbase

Example: move.w #34,-(sp)
         trap #14
         addq.l #2,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 perform.
The  vectortable is located at $A0E and has the following  vectors 
in it:
         midivec  $79C6
         vkbderr  $759C
         vmiderr  $759C
         statvec  $7034
         mousevec $15296
         clockvec $6A46
         joyvec   $7034

35 kbrate

Example: move.w repeat,-(sp)
         move.w wait,-(sp)
         move.w #35,-(sp)
         trap #14
         addq.l #6,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 
tact.
'repeat' specifies the time that passes for each repeat.
These  two  values  can be changed from  the  Control  Panel  desk 
accesory.
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.

36 prtblk

Example: move.l parameter,-(sp)
         move.w #36,-(sp)
         trap #14
         addq.l #6,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      offset
         int      width     Screen width
         int      height    Screen height
         int      left
         int      right
         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
37 wvbl

Example: move.w #36,-(sp)
         trap #14
         addq.l #2,sp

This function can be used to synchronize graphics with wvbl   of 
the screen. It just waits until wvbl has occured.

38 supexec

Example: move.l address,-(sp)
         move.w #38,-(sp)
         trap #14
         addq.l #6,sp

This  function may be used to execute the routine at 'address'  in 
Supervisor Mode of the 68000.

39 puntaes

Example: move.w #39,-(sp)
         trap #14
         addq.l #2,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 Netherlands.