---------------------
CHAPTER 5:
*** THE GEMDOS ***
---------------------
*** GEMDOS FUNCTIONS ***
-------------------------------
- The GEMDOS functions can be directly called in assembly.
Just:
.Pass the parameters needed by the function in the system stack
(WORDS or L-W).
.Pass the function code in the system stack. (WORD)
.Call the GEMDOS with a TRAP #1
- The same is true for BIOS and XBIOS functions.
(Only the TRAP number changes: TRAP #13 for BIOS and TRAP #14 for
XBIOS)
- ATTENTION! The GEMDOS, BIOS and XBIOS functions often return
information: in certain data registers and some
address registers.
Care must be taken to preserve the concerned registers before
calling one of these functions so as not to lose their content.
(e.g. using MOVEM)
- Before using the GEMDOS, BIOS and XBIOS functions, it is necessary
to reserve a certain amount of memory because when the operating
system launches your program, we must allocate the quantity of memory
that the program really needs.
(To avoid overlapping of data in memory)
The operating system (the GEM Desktop) will read the BASE PAGE which
is at the start of your .PRG program (see the INTRODUCTION chapter)
before executing it.
This BASE PAGE is of size $100 (256) bytes and contains all
the information needed by the operating system for the loading
of the PRG, but it is up to us to indicate the size of memory
that will need to be reserved.
After loading the program, SP points to the BASE PAGE, so
the various data contained in the
BASE PAGE can easily be read by incrementing SP for example.
Organization of the BASE PAGE:
------------
Byte:$00=Start of the Base Page
----- $04=Pointer to the end of free memory
$08=Pointer to the start of the prg
$0C=Size of the TEXT area
$10=Pointer to the DATA area
$14=Size of the DATA area
$18=Pointer to the BSS area
$1C=Size of the BSS area
$20=Pointer to the DTA buffer
$24=Pointer to the base page of the calling PRG (parent)
$80=The command line
To indicate the size of memory to reserve, there is a GEMDOS function, the parameters to pass are:
.the number of BYTES to reserve (L-W)
.A L-W which is the pointer to the end of free memory
.a WORD equal to 0
The function code is $4A (function 'SETBLOCK')
To find the number of bytes to reserve (the total size of the PRG)
thanks to the Base Page, we add:
.The size of the Base Page ($100 bytes)
.The space occupied by the instructions (L-W at $C(SP) because SP points to
the start of the base page)
.The size of the DATA area (L-W at $14(SP) )
.The size of the BSS area (L-W at $1C(SP) )
We put the result in a dn register and place it as a parameter
(L-W) in the system stack (MOVE.L dn,-(SP) ) followed by a L-W which is
the pointer to the end of free memory and a WORD equal to 0:
(MOVE #0,-(SP) )
Then we stack the code of the function SETBLOCK: MOVE #$4A,-(SP)
and call the GEMDOS with TRAP #1.
This initialization must be done at the beginning of any program.
----------------------------------------------------------------
To avoid retyping everything each time, we will create a
MACRO INSTRUCTION that will do it for us.
A MACRO is delimited by the directives:
MACRO (After the name of the Macro to mark the beginning of the MACRO)
-----
ENDM (At the end of the MACRO to mark the end of it)
----
Example: A MACRO called ADD which adds the low word
---- of registers d0 and d1 will be written:
TEXT
add MACRO ;beginning of the macro
ADD.W d0,d1 ;the Macro itself
ENDM ;End of the Macro
; This MACRO can then be used:
MOVE #3,d0
MOVE #5,d1
add ;call of the MACRO 'add'
MOVE d1,res
BSS
res DS.W 1 ;We will find the word 5+3=8 in 'res'
END
The MACRO can be used as many times as you want, but
care must be taken not to put Labels in your MACRO because they
would be rewritten multiple times and this would cause errors...
The MACRO can then be saved in a file.
To indicate to the LINKER that you are going to use a MACRO that is in
an external file, you will have to use the DIRECTIVE:
INCLUDE "file.xxx"
-------
It must be used before the first MACRO from 'file.xxx' is
used.
The entire file will be ASSEMBLED separately, but only the used MACROs
will be included.
But let's go back to our GEMDOS 'setblock' function:
The Listing of the SETBLOCK Macro will be:
TEXT
SETBLOCK MACRO ;beginning macro
move.l a7,a5 ;USP in a5
lea stack,a7 ;'stack' is the address pointing to an area
;of memory reserved for certain
;functions.
;(the name of the label is arbitrary...)
;(Of course, you must reserve this area with
;DS.x space: 200 bytes are generally enough)
move.l 4(a5),a5 ;free memory ending address in a5
move.l $c(a5),d0 ;TEXT area length in d0
add.l $14(a5),d0 ;adds the size of the DATA zone
add.l $1C(a5),d0 ;adds the size of the BSS zone
add.l #$100,d0 ;adds size of Base P. to d0
move.l d0,-(sp) ;STACKS the space to reserve (1st parameter)
move.l a5,-(sp) ;STACKS a5 (2nd parameter)
move #0,-(sp) ;STACKS word=0 (3rd parameter)
move #$4a,-(sp) ;STACKS the CODE of SETBLOCK
trap #1 ;GEMDOS call ->execution of the function.
add.l #12,sp ;When returning, SP is incremented to
;regain its initial value.
ENDM ;end of the MACRO
END ;end of assembly
We will save this macro in the file 'INIT_TOS.L'.
All the programs we write will therefore have to look like this:
---------------------------------------------------------------------
TEXT
INCLUDE "INIT_TOS.L" ;Linkage of the file
SETBLOCK ;call of the MACRO SETBLOCK
. ;the instructions
. ;that form the prg
.
DATA ;the data zone
. ;with the initialized data
.
.
BSS ;the bss zone
. ;with the reservations
.
.
DS.B 200 ;and space reserved for the needs
stack DS.B 1 ;of the GEMDOS, BIOS, XBIOS functions we
;will use. (Upstream of the
;'stack' label). USP points on 'stack' and
;will be decremented when passing the
;parameters to the functions
;(MOVE.x source, -(SP) )
;:Let's not forget that only the memory that
;the program really needs is
;reserved after SETBLOCK.
END
The listing of the SETBLOCK macro instruction is found in the file
INIT_TOS.L on this disk and is fully available to you.
NB:You will therefore always have to make sure to reserve memory in the
-- BSS zone upstream from the address pointed to by the label we
named 'STACK'.
There is no need to economize on space by reserving little memory,
the size of the BSS segment does not affect the
size of the PRG...
- I will now enumerate the various functions of the GEMDOS.
Only the commonly used functions will be studied, for the
others, you will have to refer to THE ST BIBLE, but I doubt you
will need to use them in the near future...
For each function, I will give you:
.The CODE and the NAME of the function
---- ---
.The PARAMETERS to pass
----------
.The PURPOSE of the function
---
.A MACRO INSTRUCTION that uses the studied function if it
can be frequently useful to us...
All these macro instructions that we will create from the
GEMDOS, BIOS and XBIOS functions will be collected in the file
MACROS.L and of course, you can use them whenever
you desire.
*** THE GEMDOS FUNCTIONS ***
-------------------------------
$00 (TERM), no parameter
---
TERM allows to end the program and return to the calling program
(or parent program).
That is to say that if we use the TERM function of gemdos, the prg stops and
returns to the GEM DESKTOP (if the program has only been loaded from
the DESKTOP) or to the instruction following the calling instruction, of
the FATHER program. In this latter case, the PRG using the term function is
named SON program and has been loaded by the so called 'FATHER' program.
TERM MACRO ;TERM macro named 'TERM'
CLR.W -(SP) ;TERM code
TRAP #1 ;GEMDOS call
ENDM ;MACRO end
$01 (CCONIN), no parameter
---
CCONIN waits for a character on the keyboard and displays it at the current
cursor position.
The function returns, the ASCII code of the pressed key in the low
byte of the low word of d0 and the SCANCODE of the
key in the low byte of the high word of d0.
The SCANCODE allows to identify keys that do not have an ASCII code
(such as function keys) and it also allows to distinguish between
keys that have the same ASCII code (such as numbers on the numeric
keypad and those on the main block)
The ASCII code and SCANCODE can be reached in this way for
example:
MOVE #$01,-(SP) ;CCONIN CODE
TRAP #1 ;-->gemdos
ADDQ.L #2,SP ;we reinitialize SP
CMPI.B #'A',d0 ;compare the low byte of the low word of
;d0 with the ASCII code of
;'A' that is $41
BEQ yes
SWAP.W d0 ;SWAP the 2 words of d0
CMPI.B #0,d0 ;is the SCANCODE nill ???
BNE no
etc...
NB:You have noticed that I wrote:CMPI #'A',d0.
-- Writing 'A' or the ASCII code of A that is $41 is identical.
You can therefore for example replace MOVE #$42,d0 with MOVE #'B',d0
,this makes the listing more readable if you use instructions
that must move data representing ASCII codes...
The assembler will make the correction. (just as MOVE source,an is
accepted and replaced by MOVEA source,an)
CCONIN MACRO ;The equivalent macro
MOVE #$1,-(SP)
TRAP #1
ADDQ.L #2,SP
ENDM
$02 (CCONOUT), WORD=ascii code
---
CCONOUT displays the character represented by the ASCII code that is passed
as a parameter on the stack at the current cursor position.
CCONOUT MACRO $\1 ;here, $\1 tells the assembler that we
;will pass a parameter to the macro.
move \1,-(SP) ;we stack the parameter \1
move #2,-(SP) ;then the code of CCONOUT
trap #1 ;gemdos
addq.l #4,SP ;correction of the stack
ENDM ;end of the MACRO
As you can see, we have just created a MACRO instruction
that accepts a PARAMETER.
It is indicated to the assembler by the directive: MACRO $\1
The parameter can be for example:#'A' or d0 or #$48 etc...
Examples of using the macro CCONOUT (with a parameter):
CCONOUT #'a'
will display an 'a' on the screen
MOVE #'a',d0
CCONOUT d0
idem
CCONOUT #53
will display the character with ASCII code 53.
$03 (CAUXIN), no parameter
---
CAUXIN allows the reception of a character via the RS232 interface.
If there has been no error, the ASCII code of the character returns in
the low byte of d0.
MOVE #$3,-(SP)
TRAP #1
ADDQ.L #2,SP
$04 (CAUXOUT), WORD=ascii code
---
CAUXOUT causes the emission of the character whose ASCII code has been passed
as a parameter in the stack to the RS232 interface.
MOVE #'A',-(SP) ;sends an 'A'
MOVE #$4,-(SP)
TRAP #1
ADDQ.L #4,SP
$05 (CPRNOUT),WORD=ascii code
---
CPRNOUT emits the character whose ASCII code has been stacked to
the printer.
If the character was well sent, we obtain the word -1 in d0.
If the printer is unable to receive the character, we obtain a
word equal to 0 in d0.
MOVE #'A',-(SP) ;we print an 'A'
MOVE #$5,-(SP) ;CPRNOUT code
TRAP #1
ADDQ.L #4,SP
$06 (CRAWIO),WORD=$FF or ascii code
---
CRAWIO admits two types of parameters.
If the parameter is a WORD equal to $FF, CRAWIO tests if a key of
the keyboard IS pressed.(like INKEY in BASIC)
If a key was pressed, its ASCII code and its scan code enter
in d0, otherwise d0 remains unchanged.
If the parameter is different from $FF, this value is interpreted as
the ASCII code of a character to send to the screen.
INKEY MACRO ;CRAWIO with $FF as parameter
MOVE #$FF,-(SP)
MOVE #$6,-(SP)
TRAP #1
ENDM
Example of using the INKEY macro:
-------
test INKEY ;macro call INKEY
CMPI.B #'A',d0 ;compare the ASCII code of d0 with 'A'
BEQ yes ;key 'A' pressed? If yes, goes to 'yes'
JMP test ;otherwise return to 'test'
yes NOP
As long as the 'A' key is not pressed, we jump to 'test'.
$07 (CRAWCIN), no parameter
---
CRAWCIN waits for a key to be pressed.
The recognized character is not displayed, but the ASCII code and scan code
of the pressed key is transmitted to d0 in return.
WAIT MACRO ;waiting macro for a key
MOVE #$7,-(SP) ;CRAWCIN code
TRAP #1
ADDQ.L #2,SP ;keys codes in d0.
ENDM
$08 (CNECIN), no parameter
---
Identical function to CRAWCIN, except that here, pressing CONTROL-C ends the
PRG (like with PTERM), CONTROL-S stops the display, CONTROL-Q resumes
the display interrupted by control-s.
$09 (PRINT LINE), L-W= address of a string of characters terminated by a
--- zero byte.
This function allows to display a string of characters on the screen.
The string of characters to be displayed must be located in the DATA area
and must be terminated by a NULL byte.
PRINTLINE MACRO $\1 ;MACRO with \1 parameter: The address of
;the string of characters to be displayed.
PEA \1 ;STACK the address \1.
MOVE #$9,-(SP) ;PRINTLINE code
TRAP #1
ADDQ.L #6,SP
ENDM
Example of using the macro PRINTLINE:
PRINTLINE laurent
PRINTLINE exp2
PRINTLINE exp3
DATA
laurent DC.B 'laurent PIECHOCKI 8,impasse Bellevue 57980',0
exp2 DC.B 53,54,56,80,45,25,0
exp3 DC.B 27,'E',7,'LAURENT',25,0
NB: To obtain effects such as screen erasing, line jumps... there are special codes that must be transmitted to
--- functions such as PRINTLINE,CCONOUT...
The codes preceded by the ASCII value 27 (ESC).
-----------------------------------------------
27,'E' :erase the screen
27,'B' :positions the cursor one line lower
27,'A' :positions the cursor one line higher
27,'C' :positions the cursor one line further to the right
27,'D' :positions the cursor one line further to the left
27,'J' : clear the screen from the current cursor position
27,'L' : insert a line
27,'M' : delete the line where the cursor is
27,'I' : scroll the cursor and text upwards
27,'H' : position the cursor at line 1, column 1
27,'K' : delete a line from the cursor to the end of the line
27,'Y',x,y : position the cursor at line x-32 and at column
y-32
----
----
27,'b',x : Change the text color to color number x
27,'c',x : Change the background color to color number x
27,'f' : Makes the cursor disappear
27,'e' : Makes the cursor reappear
27,'j' : Memorize the cursor position
27,'k' : Position the cursor at the memorized position
27,'p' : VIDEO-INVERSE mode of writing
27,'q' : Return to normal VIDEO
Thus, if I write:
------------------
PRINTLINE clear
DATA
clear DC.B 27,'E','laurent',0
or
--
CCONOUT #27
CCONOUT #'E'
PRINTLINE laurent
DATA
laurent DC.B 'laurent',0
Clear the screen (ESC,'E') and display the string:'laurent'
$0A (READLINE), L-M pointing to a buffer
---
READLINE allows the entry of a certain quantity of characters on the screen.
(similar to INPUT in BASIC).
The string can be modified during editing with
[Backspace] and [Delete] and will be validated by [Return] or [Enter].
(CONTROL-C ends the program)
You must provide the address of a buffer organized as follows:
In BSS area: DS.B maximum number of characters to enter+2
You must have placed at the beginning of this buffer a BYTE representing the maximum
number of characters to enter (MOVE.B x,buffer) before using the
READLINE function.
After returning from the function:
In 'buffer'+1 is the number of entered characters
In 'buffer'+2 is the start of the entered character string.
READLINE MACRO $\1 ;parameter=buffer address
PEA \1
MOVE #$0A,-(SP)
TRAP #1
ADDQ.L #6,SP
ENDM
Example of using the READLINE macro:
---------------------
MOVE.B #5,resu ;5 characters to enter
LEA resu,a5 ;address of 'resu' in a5
READLINE resu ;readline
addq.l #2,a5 ;a5 points to the entered character string
MOVE.B #0,zero ;places a NULL BYTE at the end of the string for
PRINTLINE a5 ;display the string with PRINTLINE
TOUCH ;waiting for a key press
DESKTOP ;then exit the program
BSS
resu DS.B 7 ;reservation for READLINE
zero DS.B 1 ;reservation for the NULL byte that will end the
;string for PRINTLINE
$0B (CONIN STAT),no parameter
---
Calling this function returns a WORD in d0 equal to -1 if the keystroke buffer contains characters.
d0=0 if there are no characters available in this buffer.
MOVE #$B,-(SP)
TRAP #1
ADDQ.L #2,SP
TST.W D0
BNE nothing
$0E (SETDRIVE),WORD=drive number to activate.
---
SETDRIVE activates the drive whose number is passed as a parameter in
the system stack.
0=Drive A
1=Drive B etc...
In return, the function gives d0 which is organized in such a way that the
only active bit of d0 represents the last activated drive.
(active bit number=drive number)
DRIVE MACRO $\1 ;param. \1=drive number
MOVE \1,-(SP)
MOVE #$E,-(SP)
TRAP #1
ADDQ.L #4,SP
ENDM
Example of use:
------------------
DRIVE #2
Drive C is activated.
If the last active Drive was drive B, we would have:
d0=%0000000000000010
|
\|/
bit number1=drive B
$19 (CURRENT DISK),no parameter
---
This function allows you to know which DRIVE is ACTIVE.
The number of the active drive is returned in d0 in the previous format.
WATHDRIVE MACRO ;Which is the active drive?
MOVE #$19,-(SP)
TRAP #1
ADDQ.L #2,SP
ENDM
$1A (SETDTA), L-M=address of the DTA buffer
---
SETDTA installs the DTA buffer used by some GEMDOS functions that operate on files.
This buffer must be 44 bytes in size, its address must be
stacked in the system stack and must be EVEN.
To obtain an even address, you can reset the PC with the
BSS directive or use appropriate directives (but specific to
the assembler used): ALIGN.W for PROFIMAT
:CNOP 0,2 for METACOMCO
You can also simply make a correction by adding 1 BYTE
to a lower address (DS.B 1), this has the effect of increasing the value
of the DTA address: odd address+1=even address.
PEA buffer
MOVE #$1A,-(SP)
TRAP #1
ADDQ.L #6,SP
BSS
buffer DS.B 44
$20 (SUPER),L-M=0 or L-M=new SP value
---
Here is the function that allows you to switch to SUPERVISOR MODE.
If the parameter you provide is a L-M=0, SUPER will activate SUPERVISOR MODE and return the SP value in d0.
You must save this address because it will be essential to
return to USER MODE (To exit the program for example)
If you stack another L-M than 0, it will be interpreted as the new
SP value and d0 will contain the old SP value.
SUPER MACRO ;switching to SUPERVISOR MODE
CLR.L -(SP)
MOVE.W #$20,-(SP)
TRAP #1
ADDQ.L #6,SP
MOVE.L d0,sauv_sp ;save SP in 'sauv_sp'
ENDM
Of course, a L-M must be reserved in 'sauv_sp'!
To return to USER MODE (essential to exit the program
for example...):
Use the same function, but pass it the old
SP value that was saved in sauv_sp.
USER MACRO ;returning to USER MODE
MOVE.L sauv_sp,-(SP) ;restore SP
MOVE.W #$20,-(SP)
TRAP #1
ADDQ.L #6,SP
ENDM
$2A (GET DATE),no parameter
---
Allows you to obtain the DATE of the GEM desktop clock in d0 as follows:
Bits 0 to 4=day
Bits 5 to 8=month
Bits 9 to 15=(year-1980)
MOVE #$2A,-(SP)
TRAP #1
ADDQ.L #2,SP
Example: if d0=%0001000000100001
The date is:
DAY:bits 0 to 4 :%00001=the 1st
MONTH:bits 5 to 8 :%00001=January
YEAR :bits 9 to 15:%0001000=8+1980=1988
$2B (SET DATE),WORD=date
---
SET DATE allows setting the GEM clock to the date you provide as a parameter.
The date (WORD) is in the format previously described.
bits 0 to 4: day
bits 5 to 8: month
bits 9 to 15: (year-1980)
If the date is incorrect (45/20/1745...), d0 returns with the value -1,
otherwise, it returns with the value 0.
MOVE #%00010000000100001,-(SP) ;January 1st, 1988
MOVE #$2A,-(SP)
TRAP #1
ADDQ.L #4,SP
$2C (GET TIME),no parameter
---
GET TIME returns the time from the GEM clock in d0 in the form:
bits 0 to 4 :(seconds/2)
bits 5 to 10 :minutes
bits 11 to 15:hour
Example:
test MOVE #$2C,-(SP) ;GET TIME
TRAP #1
ADDQ.L #2,SP
;d0 contains the time
AND.W #%11111,d0 ;we MASK bits 0 to 4 of d0:
;bits 5 to 15 of d0 are therefore cleared.
;it leaves the seconds.
MULS #2,d0 ;x2 because seconds=(seconds/2) in d0
CMPI #30,d0 ;do we have seconds=30?
BEQ yes ;if yes: go to 'yes'
JMP test ;otherwise, return and request the time again.
$2D (SET TIME),WORD=time
---
SET TIME sets the time of the GEM clock with the parameter provided.
The time must be coded in the form:
bits 0 to 4 :(seconds/2)
bits 5 to 10 :minutes
bits 11 to 15:hours
Example:
MOVE #%0001000000100001,-(SP)
MOVE #$2D,-(SP)
TRAP #1
ADDQ.L #4,SP
We set the clock to 2h, 1 min, 2 sec
$31 (KEEP PROCESS),WORD=0,L-M=number of bytes to protect.
---
KEEP PROCESS, like PTERM, ends the program and returns to the 'parent' program.
With PTERM, the exited program is permanently erased from memory,
while with KEEP PROCESS, a certain amount of BYTES in memory (parameter 2) is reserved and the program to exit is placed there.
This is important for interrupt-driven programs, for example,
we will talk about this again...
KEEP MACRO $\1 ;parameter=number of bytes to reserve
CLR.W -(SP)
MOVE.L #\1,-(SP)
MOVE #$31,-(SP)
TRAP #1
ADDQ.L #8,SP
ENDM
Example of use:
KEEP 1024
We place the PRG in the reserved KO and exit...
NB: Be careful that you reserve enough memory...
--
$3C (CREATE),WORD=file attribute,L-M=address of the file name
---
CREATE allows creating a file in which you can place data.
The first parameter is the file attribute:
0=file accessible in Read and Write
1=file accessible in Read only
2=invisible file
4=system file (invisible to desktop)
8=volume label file (invisible to desktop)
The second parameter is the address pointing to the file name:
Organized like this: 'A:\file\name.ext',0
If the name of the program to create is 'name.ext' and if it is in the
'file' (unnecessary if it is not in a file...).
'A:' indicates that it is on the floppy disk unit A.
The character string must end with a NULL byte.
In return, CREATE returns in d0 the FILE HANDLE number of the file.
This number is used to distinguish the different external programs loaded.
CREATE MACRO $\1,$\2,$\3 ;CREATE with 3 parameters
MOVE #\1,-(SP) ;\1=file attribute
PEA \2 ;\2=address of the name
MOVE #$3C,-(SP)
TRAP #1
ADDA.L #8,SP
MOVE d0,\3 ;\3=address to save d0.
ENDM
Example of use:
CREATE 0,prg,handle ;file in Read/Write mode
DATA
prg DC.B 'A:\laurent.gag',0 ;name of the file to create
BSS
handle DS.W 1 ;1 Word for the handle
