Pl2 BIOS.DOC

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