Pl2 BIOS.DOC
{{Languages|Pl 2 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