Pl2 BIOS.DOC

From Atari Wiki
Revision as of 14:19, 17 December 2023 by Olivier.jan (talk | contribs)
Jump to navigation Jump to search

                          --------------------
                             CHAPTER No. 6
     
                            BIOS AND XBIOS

                           FUNCTIONS

                          -------------------- 




                      *** BIOS FUNCTIONS ***
                      -----------------------------

- All previous remarks concerning GEMDOS functions still apply for BIOS
  functions:
  
  .Essential initialization (SETBLOCK)
  .Parameter passing mode through the system stack.
  .Return of some values in certain registers.
  
  The TRAP number corresponding to the BIOS functions is: TRAP #13


- I will now enumerate and comment on the BIOS functions that are 
  useful or interesting. (as with the GEMDOS functions...)




$04 (RWABS), WORD=floppy drive unit, WORD=starting sector number, WORD=number of sectors
---     to read or write, LONG-WORD=address of a buffer, WORD=mode

RWABS allows writing or reading sectors on a floppy disk.

The parameters to pass are:

1°: The number of the floppy drive concerned:
   0=Drive A, 1=Drive B, 2=hard drive
2°: The number of the sector where RWABS should start the operation
3°: The number of sectors to read or write
4°: The address of the data buffer to read or write according to the case.
   The size of a sector is 512 bytes.
5°: The RWABS action mode:
   0=read sectors
   1=write sectors
   2=read (does not consider a disk change during the operation)
   3=write (does not consider a disk change during the operation)

RWABS returns in d0 a null value if everything is OK, or a negative error 
code whose value can be:

 -1=crash
 -2=drive not ready
 -3=unknown command
 -4=CRC error  
 -5=incorrect command 
 -6=track not found
 -7=damaged boot sector
 -8=sector not found
-10=write error
-11=read error
-13=write-protected floppy disk
-14=floppy disk changed during reading or writing
-15=unknown device
-16=verification of a poorly written sector
-17=no floppy disk
  
          MOVE      #0,-(SP)       ;DRIVE A
          MOVE      #0,-(SP)       ;start at sector 0 
          MOVE      #10,-(SP)      ;10 sectors
          PEA       buffer         ;data address
          MOVE      #1,-(SP)       ;writing
          MOVE      #4,-(SP)
          TRAP      #13
          ADDA.L    #14,SP

          DATA

buffer    DS.B      5120     ; data to write on the 10 sectors
                             ; 10 sectors=512*10 bytes 


$05 (SETEXEC), LONG-WORD=new vector value, WORD=vector number to change
---
SETEXEC allows changing the value of an exception vector.
(I will explain in detail in a chapter on EXCEPTION VECTORS)

     PEA       new        ;new address
     MOVE      #10,-(SP)      ;10=illegal instruction
     MOVE      #5,-(SP)
     TRAP      #13
     ADDA.L    #8,SP

$09 (MEDIACH), WORD=drive number
---
MEDIACH allows to know if a floppy disk has been taken out or inserted into
the floppy drive specified by number. (0=Drive A, 1=Drive B...)
This function only works if the floppy disk is NOT write-protected...

D0 returns with:

0 if the floppy disk has been kept in place. 
1 if the floppy disk might have been changed (uncertain).
2 if the floppy disk has been changed.  

MEDIACH operates a test from the start of the program's execution and at
regular intervals.
(Watch the red LED light of the floppy drive blink very faintly at regular
intervals when the drive is at rest...)

CHANGED   MACRO     $\1       ;MACRO with 1 parameter (MEDIACH)
          MOVE      \1,-(SP)  ;\1=drive number to test
          MOVE      #9,-(SP)
          TRAP      #13
          ADDQ.L    #4,SP     ;return in d0
          ENDM

     Exemple d'utilisation:

          CHANGED   #1        ;has the floppy disk in drive A been
                              ;changed?


$0A (DRVMAP), no parameters
---
This function returns in d0 the different connected floppy drives.
The bit No.X of d0 is active when the drive No.X is available.
(0=Drive A, 1=Drive B...)

NBD  MACRO
     MOVE      #$A,-(SP)
     TRAP      #13
     ADDQ.L    #2,SP
     ENDM

     Example of use:

     NDB

if d0.B returns %00001001, drives A and D are available.
(You can test the bits of d0 with BTST #X for example to know if a
drive X is available...).


$0B (GETSHIFT), WORD=-1
---
GETSHIFT allows obtaining the state of certain keys that cannot be
detected by other key waiting functions.

You must pass to GETSHIFT a word=-1 via the system stack to obtain in d0.B
a byte whose bits have the following meaning:

bit number: Meaning 

0         :Right Shift
1         :Left Shift
2         :Control
3         :Alternate
4         :Caps Lock
5         :Clr/Home (or right mouse button)
6         :Insert (or left mouse button)

If the bit is active, the corresponding key is pressed.

GETSHIFT  MACRO     $\1       ;MACRO with 1 parameter
          MOVE      \1,-(SP)  ;\1=-1 for key state
          MOVE      #$B,-(SP)
          TRAP      #13
          ADDQ.L    #4,SP
          ENDM

     Example of use:

test      GETSHIFT
          BTST      #2,D0     ;is the Control key pressed?
          BEQ       test      ;if Bit=0:Z=1=no=retest



                    *** XBIOS FUNCTIONS ***
                    ------------------------------     

- All previous remarks concerning BIOS functions still apply for XBIOS
  functions:
  
  .Essential initialization (SETBLOCK)
  .Parameter passing mode through the system stack.
  .Return of some values in certain registers.
  
  The TRAP number corresponding to BIOS functions is: TRAP #14


- I will now enumerate and comment on the XBIOS functions that are
  useful or interesting. (as with BIOS functions...)


$02 (PHYSBASE), no parameters
---
PHYSBASE gives in a0 the start of the physical RAM screen memory.

PHYSBASE  MACRO
          MOVE      #2,-(SP)
          TRAP      #14
          ADDQ.L    #2,SP
          ENDM

$03 (LOGBASE), no parameters
---
LOGBASE gives in a0 the start of the logical RAM screen memory.

LOGBASE   MACRO
          MOVE      #3,-(SP)
          TRAP      #14
          ADDQ.L    #2,SP
          ENDM

For the PHYSBASE and LOGBASE functions, I will give you all the details
of use and operation in an example program that uses these 2 functions.


$04 (GETREZ), no parameters
---
GETREZ allows obtaining the current screen resolution in d0.

0=Low resolution (320*200 pixels in 16 colors)
1=Medium resolution (640*200 pixels in 4 colors)
2=High resolution (640*400 pixels in monochrome)

GETREZ    MACRO
          MOVE      #4,-(SP)
          TRAP      #14
          ADDQ.L    #2,SP
          ENDM

  
$05 (SETSCREEN), WORD=resolution, LONG-WORD=physbase, LONG-WORD=logbase
---
SETSCREEN allows changing the screen resolution, the address of the 
physbase, and the address of the logbase.
If one of these parameters should not be changed, you must pass the 
parameter -1 to the function.

SETSCREEN      MACRO     $\1,$\2,$\3    ;MACRO with 3 parameters
               MOVE      \1,-(SP)       ;\1=REZ
               MOVE      \2,-(SP)       ;\2=PHYSBASE
               MOVE      \3,-(SP)       ;\3=LOGBASE
               MOVE      #5,-(SP)
               TRAP      #14
               ADDA.L    #12,SP
               ENDM

     Example of use:

     SETSCREEN  #1,#-1,#-1

     Switch to medium resolution.

WARNING: moving to a lower resolution (e.g., from Medium to Low resolution)
only allows you to have the maximum number of colors from the calling mode.
(in our example, 4 colors in Low resolution...)
  

$06 (SETPALETTE), LONG-WORD=address of the new palette
---
SETPALETTE allows changing the colors of the current palette with the
colors located at the address pointed by the parameter address.
The values defining the different colors must be WORDS and there must be 16 of them.
The 1st word defines color 0, the 2nd word color 1, etc..

PALETTE   MACRO     $\1       ;MACRO with 1 parameter
          PEA       \1        ;\1=address of the new palette.
          MOVE      #$6,-(SP)
          TRAP      #14
          ADDQ.L    #6,SP
          ENDM

     Example of use:

          PALETTE   colors

          DATA

colors  DC.W      $000,$077,$070,$700,$234,$123,$700,$444
          DC.W      $444,$000,$777,$700,$070,$007,$050,$777

NB:To easily define a color, we use the hexadecimal mode:
-- The hundreds digit represents the amount of Red (from 0 to 7)
   The tens digit represents the amount of Green (from 0 to 7)
   The units digit represents the amount of Blue (from 0 to 7)

Thus: $000=black color
       $777=white color
       $700=bright Red color 
       $070=light Green color ...



$07 (SETCOLOR), WORD=new color, WORD=color number (0 to 15) to
---            change.

SETCOLOR allows changing only one color by providing its number (from 0
to 15).
You must first provide SETCOLOR with the value to be taken by the color
to be changed.

COLOR     MACRO     $\1,$\2   ;MACRO with 2 parameters.
          MOVE      \1,-(SP)  ;\1=value to take
          MOVE      \2,-(SP)  ;\2=color number to change
          MOVE      #7,-(SP)
          TRAP      #14
          ADDQ.L    #6,SP
          ENDM

     Example of use:

     COLOR     #$777,#1

Color No.1 will be white ($777)

$08 (FLOPRD), WORD=number of sectors (1 to 9), WORD=face, WORD=track number (0-79 
---          or 0-40), WORD=1st sector number to read (1-9), WORD=Drive, WORD=0,
             LONG-WORD=buffer address to place the data.

FLOPRD allows reading sectors on a floppy disk and deposits the data 
read into a buffer.

The parameters to pass are:

1°: The number of sectors to read in a row on a track (from 1 to 9)
2°: The face of the disk concerned (0=face A, 1=face B for double-sided)
3°: The number of the track to read (0 to 79 or 0 to 40 depending on formatting)
4°: The number of the 1st sector to read (from 1 to 9)
5°: The number of the Drive concerned (1=A, 2=B...)
6°: A word=0
7°: The address of a buffer where the data will be deposited, with a size of
   (512 bytes )*( the number of sectors read )
   The buffer must be located at an EVEN address.

D0 returns with a null value if everything is OK or with the same negative 
error codes as RWABS.

To get something valuable you will of course also need to put
this function in a loop and vary the parameters that need
to be changed (sector number...)
          


$0A (FLOPFMT), WORD=VIRGIN, LONG-WORD=$87654321, WORD=INTERLEAVE, WORD=face, WORD=track
---           number, WORD=number of sectors per track, WORD=Drive number, WORD=
              0, LONG-WORD=address of a buffer of at least 8 KB

FLOPFMT allows formatting a floppy disk, just pass the following parameters
to the function:

1°: The VIRGIN (it's the value that will be written during formatting)
   normally, this WORD=$E5E5
2°: A LONG-WORD=$87654321 
3°: The INTERLEAVE that determines the order in which sectors are written
   Normally this WORD=1
4°: The face of the floppy disk to be formatted (0 or optionally 1 for D.F)
5°: The track number of the disk to be formatted (0 to 79)
6°: The number of sectors per track (normally 9)
7°: The Drive number concerned (0=A, 1=B...)
8°: A WORD=0
9°: The address of a buffer of at least 8 KB for formatting with 9 sectors
   per track...
   The buffer must be located at an EVEN address.

D0 returns with the value 0 if everything is OK or with a negative error
code.


$11 (RANDOM), no parameters
---
RANDOM gives a random number in d0.L.
Bits 24 to 31 will always be null in d0.

RANDOM    MACRO
          MOVE      #$11,-(SP)
          TRAP      #14
          ADDQ.L    #2,SP
          ENDM

NB:To obtain a random number between two values, you can, for example,
-- call RANDOM and do an 'AND.L  #max,d0' followed by 'ADD.L 
   #min,d0' if (max+min) is the maximum value and min is the minimum
   desired value.
   The number thus obtained will be <=(max+min) and will be >=min.

   It is much faster than performing several tests, multiple calls to
   RANDOM function, and conditional branchings...


$14 (SCRDMP), no parameters
---
SCRDMP allows making a HARDCOPY of the current screen on a printer.

NB:This can also be achieved by pressing [Alternate]+[Help] ...
--

HARDCOPY  MACRO
          MOVE      #$14,-(SP)
          TRAP      #14
          ADDQ.L    #2,SP
          ENDM


$16 (SETTIME), LONG-WORD=time and date 
---
SETTIME allows changing the time AND date of the GEM desktop clock.

The LONG-WORD parameter has the following configuration:

bits  0- 4:seconds/2
bits  5-10:minutes
bits 11-15:hours
bits 16-20:day
bits 21-24:month
bits 25-31:(year-1980)

SETTIME   MACRO     $\1       ;MACRO with 1 parameter
          MOVE.L    \1,-(SP)  ;\1=time+date
          MOVE      #$16,-(SP)
          TRAP      #14
          ADDQ.L    #6,SP
          ENDM

     Example of use:

          SETTIME   #%00010000001000010001000000100001

bits  0- 4:%00001*2=2 seconds
bits  5-10:%000001=1 minute  
bits 11-15:%00010=2 hours
bits 16-20:%00001=1 day
bits 21-24:%0001=January
bits 25-31:%0001000=8+1980=1988


$17 (GETTIME), no parameters
---
GETTIME returns the time and date in d0.L according to the previous format.

GETTIME   MACRO
          MOVE      #$17,-(SP)
          TRAP      #14
          ADDQ.L    #2,SP
          ENDM


$1A (JDSINT), WORD=interrupt number
---
JDSINT allows blocking the interruption of the MFP 68901 of which
the number is indicated.

We will use this function in the chapter concerning 
interruptions.


$1F (XBTIMER), LONG-WORD=address of the routine, WORD=DATA register, WORD=CONTROL
---           register, WORD=timer (A=0,B=1,C=2,D=3)

XBTIMER allows installing a program under interruption in the TIMER 
specified by number.
You just need to pass the values of the DATA and CONTROL registers as well as
the address of the program to the function.

We will use XBTIMER when we talk about programs under interruption, patience...


$20 (DOSOUND), LONG-WORD=address of the data
---
DOSOUND allows playing a sound whose defining data is
pointed by the address passed as a parameter in the system stack.

The best way to use DOSOUND is to create sounds with PRO
SOUND DESIGNER (Edited by TRIANGLE SOFTWARE):
It has an editor that saves the created sounds in a file that can be 
used in assembler (DC.B data).
To illustrate the capabilities of DOSOUND, you will find a program
named SON.PRG (listing=SON.L) on the disk.


$23 (KEY RATE), WORD=repetition, WORD=delay
---
KEY RATE allows controlling the repetition of keyboard keys, the
'repetition' parameter indicates the time that elapses between 2 repetitions
of the key, the 'delay' parameter indicates the time that elapses before
the repetition starts.
The 'repetition' and 'delay' parameters are expressed as multiples of 20 ms.

If one of the 2 parameters is -1, it is not changed and d0 returns the
current values of delay and repetition like this:

Least significant byte of d0.W=repetition
Most significant byte of d0.W=delay

KEYRATE   MACRO     $\1,$\2   ;MACRO with 2 parameters
          MOVE      \1,-(SP)  ;\1=repetition
          MOVE      \2,-(SP)  ;\2=delay
          MOVE      #$23,-(SP)
          TRAP      #14
          ADDQ.L    #6,SP