CHAPTER 5 - LINKER
Jump to navigation
Jump to search
Well, this file concludes the majority of the tutorial on Devpac
version 2. for more information, see the accompanying quick
reference files also on this Sewer Doc Disk Number 8, the Devpac
Disk. As usual, this file was typed by the Animal House and
edited by Sewer Rat
CHAPTER 5
LINKER
Introduction
A linker's job is to accept one or more input files generated
with GenST or a high-level language compiler and create a single
executable file from it. One of the most powerful features is
library searching, which means that the linker will only use the
parts of a library of modules that are required by other sections
of the program, resulting in much smaller output files.
There are unfortunately tow different linker file formats on the
Atari ST, known as DRI- and GST-formats. While GenST can
generate both formats, only the GST-format is supported in the
LinkST linker. To link DRI code you need either the Atari ALN
program or the Digital Research LINK68 and RELMOD programs.
Note: LinkST will only link GST format files.
Invoking the Linker
The simplest way to run the linker from the Desktop is to
double-click on the LINKST.TTP icon, and enter a suitable command
line. There is another way to invoke the linker, using a control
file which contains the required options.
The command line contains the necessary information for the
linker to read all the relevant files, and generate an output
file.
Command Line
The command line should be of the form:
<filename> <-options> [filename] [options]
Options are denoted by a - sign then an alphabetic character,
allowed options being:
B generate a true BSS section for any such named sections
D debug - include all symbols in the binary file using DR
standard 8 character format (for MonST or other debuggers)
F force pass 2 of the linker, useful if you want to see all
errors (as any pass 1 errors will by default stop the link
before the second pass)
L specify that all following filenames are library filenames
M dump a map file showing the order of the sections and labels,
will be the main filename with an extension of .MAP
O specify object code filename, may be followed by white space
before filename
Q 'quiet' mode, which disables the pause after the link
S dump a symbol table listing, will be the main filename with an
extension of .SYM
X extended debug, using the HiSoft Extended Debug format
W specify control file filename, defaults to .LINK extension
Normally any filenames given are taken to be input files,
defaulting to the extension of .BIN, though if a .LNK extension
is specified it will be taken to be a control file, or after a -L
option filenames are all assumed to be libraries.
The output filename can be specified with the -o option on the
command line, or using the OUTPUT directive in the control file.
If there is more than one of these, the last one is used. If
there is none, then the first input filename specified in the
command line or control file is used with an extension of .PRG.
Example Command Lines
PART1 PART2 -d
Reads PART1.BIN and PART2.BIN as input files, and generates
PART1.PRG as an output file complete with debugging information.
PART1 PART2 -o TEST.PRG
Reads PART1.BIN and PART2.BIN as input files, and generates
TEST.PRG as an output file.
-o TEST.TOS START -1 MYLIB -s
Reads START.BIN as an input file, selectively reads MYLIB.BIN as
a library, and generates the output file TEST.TOS and the symbol
listing file TEST.SYM.
LiokST Running
LinkST has tow passes - during pass 1 it builds up a symbol table
of all sections and modules, and during pass 2 it actually
creates the output file. When it starts a logon message, then
reports on which files it is reading or scanning during both
passes. This gives you some idea of what takes time to do, as
well as exactly where errors have occurred.
If there is enough free memory at the end of pass 1 LinkST will
use a cache to store the output file, which greatly speeds up the
process. If it uses the cache it will write to the disk at the
end of pass 2, and report the number of errors.
When the link finishes you will be prompted to press a key before
quitting. This is to give you an opportunity to read any warning
or error messages before returning to the Desktop. You can
disable this pause by using the -q option, useful if you are
using a CLI or batch file program.
LinkST was especially optimised for speed, though the speed of
the ST floppies is still a restricting factor. If you can't
afford a hard disk we recommend the use of a RAM disk which can
make great improvements, but leave enough memory free for the
linker to cache your output file. If you are limited in what you
can fit on your RAM disk we recommend you put many small library
or input files on there.
Error and warning messages are directed to the screen - if you
want to pause output you can press Ctrl-S, and Ctrl-Q will resume
it. Pressing Ctrl-C will abort the linker immediately. You can
re-direct screen output to a disk file by starting the command
line with
>FILENMAE.TXT
or you can re-direct it to a printer by starting the command line
with
>PRN: (parallel port) or >AUX: (serial port)
Control Files
The alternate way to run the linker is to have a control file for
the programs which you are linking together.
If you require a lot of options which won't fit on the command
line or you get bored of typing them you can use a control file,
which is a text file containing commands and filenames for the
linker. The default extension is .LNK, and the text file can be
generated with GenST (though don't try and assemble it!). The
control filename is specified on the command line with the -w
(for With) option, and each line can be one of the following:
INPUT <filename>
This specifies a filename to be read as an input file. The
default extension is .BIN if none is given.
OUTPUT <filename>
This specifies the filename to be used for the output file. There
is no default extension - you should specify it explicitly.
LIBRARY <filename>
This specifies a filename to be scanned as a library. The default
extension is .BIN if none is given.
SECTION <sectionname>
This allows specific section ordering to be forced.
DEBUG
All symbol names included in the link are put in the output file
so that debugging programs such as MonST can use them when the
program is running.
XDEBUG
Similar to debug option us uses HiSoft Extended Debug format for
up to 22 character significance.
DATA size(K)
The BSS segment size is set accordingly. The size can be given
either as a number of bytes of as a number of K-bytes (units of
1024). This option is particularly useful for compilers like
Prospero Pascal which store their variables in the BSS segment.
Blank lines in the control file are ignored, and comments can be
included by making the first character in the line a (small zero
in superscript), a semicolon or an exclamation mark.
BSS <sectionname>
Specifies that the named sections should lie in the GEMDOS BSS
section area. This can save valuable disk space, but will
generate errors if the section contains any non-zero data. This
should not be used at the same time as the DATA statement.
With the INPUT or OUTPUT directive if the filename is specified
as (small zero in superscript) it is substituted for the first
filename on the command line. This can be useful for having
a generic control file for linking C programs, for example.
An example control file is:
(small zer in superscript) control file for linking C program
INPUT STARTUP
INPUT (small zero in superscript)
XDEBUG
LIBRARY BLIB
Assuming this control file is called CPROG.LNK, the LinkST
command line
TEST -w CPROG
will read as input files STARTUP.BIN and TEST.BIN, and scan the
library CLIB.BIN. The object code, including extended debug
information, will be written to TEST.PRG, as none was explicitly
specified.
If you do not specify a drive name in the control file or on the
command line, the default drive will be assumed. If you run
LinkST from the Desktop, the default drive will always be the
same as the file on which you double-clicked; though if you run
it from a CLI or from the GenST editor this will not necessarily
be so.
Automatic Double-Clicking
It is possible to install LinkST so that you can double-click on
a .LNK file from the Desktop to invoke the linker, by using the
Install Application option from the Desktop. This is a similar
process to that described for GenST, except the type should be
left as TOS Take Parameters and the extension should be .LNK.
LinkST Warnings
Warnings are messages indicating that something might be wrong,
but it's nothing too serious.
duplicate definition of value for symbol "x"
The symbol was defined twice. This can happen if you replace a
subroutine in a module with one of your own, for example. The
linker will use the first definition it comes across, and give
this warning on the second.
module name is too long
Module names can only be 80 characters long.
comment is too long
Comment directives are only allowed to 80 characters long (don't
ask us why, we don't know!)
absolute sections overlap
Two absolute sections clash with each other.
SECTION "x" is neither COMMON nor SECTION
A section name was specified without defining its type.
LinkST Errors
LinkST errors divide into four areas; general errors, I/O errors,
binary file errors, and linker bugs. In some error messages a
string is included, denoted by "x" below. In others a number may
be output, denoted by 99 below.
General Errors
unresolved symbol "x" in file "x"
The symbol was referred to but not defined in the file. There may
also be other files which refer to the symbol, but this gives you
a start in your search!
XREF value truncated
A value was too large to fit into the space allocated for it, for
example a BSR to an external may be out of range.
bad control line "x"
An illegal line was found in a control file.
non-zero data in BSS section
A section wanted as a true BSS section contained non-zero data.
file "x" not found
Can't open output file "x"
Can't open map file "x"
Can't open symbol file "x"
Can't open input file "x"
i/o error on input file
disk write failed
filename "x" was too long
Binary File Errors
These are errors in the internal syntax of the input file, and
should not occur. If they do it probably means the compiler or
assembler produced incorrect code.
missing SOURCE directive
Can occur if a file is not in GST format, for example a DRI file.
runtime relocation is only available for LONGs
attempt to redefine id of symbol "x"
attempt to DEFINE "x" with <id> of zero
bad operator code 0x99 in XREF directive
bad truncation rule in XREF
wrongly placed SOURCE directive
bad directive 99
<id> 99 not DEFINEd as a SECTION but used as one
attempted re-use of <id> 99 as SECTION id
attempted re-use of "x" as SECTION name
Section is COMMON but being used as though it's not
SECTION is being misused as COMMON
unexpected end of input file
'Linker Bug' Messages
These can be produced as a result of internal checks by the
linker. If you get one please send us copies of the files you are
trying to link!
APPENDIX A
GEMDOS error codes
This appendix details the numeric GEMDOS errors and their
meanings. The error numbers shown are those displayed by MonST
and GenST; when calling GEMDOS from your own programs these
values will be negative.
0 OK (no error) 32 Invalid function number
1 Fundamental error 33 File not found
2 Drive not ready 34 Path not found
3 Unknown command 35 Too many files open
4 CRC error 36 Access denied
5 Bad request 37 Invalid Handle
6 Seek error 39 Insufficient memory
7 Unknown medium 40 Invalid memory block address
8 sector not found 46 Invalid drive
9 No paper 49 No more files
10 Write fault 50 Disk full (not a GEMDOS error;
11 Read fault produced by GenST)
12 General error 64 Range error
13 Write protect 65 Internal error
14 Medium change 66 Invalid program load format
15 Unknown device 67 Setblock failure due to growth
16 Bad sectors on format restrictions
17 Insert other disk
APPENDIX B
GenST error messages
GenST can produce a large number of error messages, most of which
are pretty self explanatory. This appendix lists them all in
alphabetic order, with clarifications for those which require
them.
Please note that GenST is continually being improved and list may
not agree exactly with the version you have, there may be
additional messages not documented here.
Errors
If you get a message beginning with INTERNAL please tell us - you
should never see these.
.W or .L expected as index size
absolute expression MUST evaluate
absolute not allowed
additional symbol on pass 2
somehow a symbol has appeared during pass 2 that did
not appear during pass 1
address register expected
addressing mode not allowed
addressing mode not recognised
BSS or OFFSET cannot contain data
OFFSET sections and non-GST BSS sections can only
contain DS directives
cannot create a binary file
could be a bad filename, or a write-protected disk,
etc.
cannot export symbol
cannot import symbol
cannot reset MACRO definitions or define in REPTs
macro definitions may not be nested or defined within
repeat loops
cannot nest repeat loops
comma expected
data register expected
data too large
division by zero
duplicate MODULE name
module names must be unique
error during listing output
listing will be stopped at this point
error during writing binary file
normally disk full
executable code only
only executable code may be assembled to memory
expression mismatch
normally a syntax error within an expression
fatally bad conditional
there were more ENDCs in a macro than IFs
file not found
forward reference
garbage following instruction
illegal BSR.S
a BSR.S to the following instruction is not allowed -
change it to BSR
illegal type combination
immediate data expected
imported label not allowed
include file read error
instruction not recognised
invalid FORMAT parameter
invalid IF expression, ignored
invalid MOVEF addressing mode
invalid number
invalid numeric expression
the symbol is not defined or relative or a syntax
error
invalid option
invalid printer parameter
invalid register list
invalid section name, TEXT assumed
invalid size
line malformed
linked format restriction
the DRI format is destructive about where it allows
imports
local not allowed
missing close bracket
missing ENDC
there were more IFs than ENDCs
missing quote
misuse of label
not yet implemented
number too large
odd address
option must be at start
ORG not allowed
out of memory
phasing error
should never happen, look investigate immediately
before first such error
program buffer full
change the program buffer size when assembling to
memory
register expected
relative not allowed
relocation not allowed
repeated include file
each include file may only be included once on each pass
source expired prematurely
with an IF, MACRO or REPT and the source ran out
spurious ENDC
spurious ENDM or MEXIT
spurious ENDR
symbol defined twice
symbol expected
undefined symbol
user error
caused by FAIL directive
wrong processor
XREFs not allowed within brackets
Warnings
68010 instruction, converted to MOVE SR
MOVE CCR, is not a 68000 instruction
branch made short
by optimising
directive ignored
invalid LINK displacement
if negative or odd
offset removed
xx(An) form reduce to (An) by optimising
relative cannot be relocated
short branch converted to NOP
sign extended operand
data in MOVEQ needed sign extension to fit
size should be .W
APPENDIX C
ST Memory Map
This Appendix details certain information about the ST memory
map:
1. Processor Dump area
2. Base Page layout
3. Hardware memory map
Processor Dump Area
When the ST crashes with an exception (i.e. mushrooms or bombs)
it stores a copy of the processor's state in an area of memory
which is not destroyed by a RESET. Thus after such a crash you
can load MonST and investigate the relevant area of memory to try
to ascertain what exactly went wrong. If this happens a lot you
should use the auto-resident version of MonST so you will have a
much better idea of the cause of the problem.
$380 long contains $12345678 if valid
$384 8 longs saved values of D0-D7
$3A4 8 longs saved values of A0-A7
$3C4 byte exception number
$3C8 long saved USP
$3CC 16 words copied from the SSP
Base Page Layout
Every program that runs under GEMDOS has a base page area which
contains certain information. It is $100 bytes long.
Offset Name Contents
$00 p_lowtpa base address of the TPA (i.e. here)
$04 p_hitpa pointer to end of TPA+1
$08 p_tbase pointer to start of TEXT area
$0C p_tien length of TEXT area
$10 p_dbase pointer to start of DATA area
$14 p_dlen length of DATA area
$18 p_bbase pointer to start of BSS area
$1C p_blen length of BSS area
$20 p_data pointer to DTA address
$24 p_parent pointer to parents's base page (0 if
desk acc.)
$28 (reserved)
$2C p_env pointer to environment string
$80 p_cmdlin command line: length byte then string,
which is not guaranteed to be null-
terminated
$100 your program starts here
Hardware Memory Map
Address Usage MonST Access
Read Write
FFFFFF ÿ ÿ
Hardware Registers
FF8000
FFEFFF ÿ
System ROM |
FC0000 |
Expansion ROM |
FA0000 -
1040ST 100000 _ _
520ST 080000 | |
RAM | |
020000 | |
Protected RAM | |
000000 | ÿ
ÿ ÿ
Not to scale
APPENDIX D
Calling the Operating System
The operating system of the ST is large and complex and consists
of various levels. To help in your own program development, this
appendix describes the calling mechanisms and routines available,
but it is not intended to be definitive. It also details the
various example programs and include files supplied with
DevpacST. The various levels of the operating system are:
GEM AES window and event manager
GEM VDI device-independent graphics routine
GEMDOS disk and screen I/O, similar to MS-DOS
BIOS low level I/O
XBIOS extended low level I/O
Each of these will now be described in varying degrees of detail.
GEMDOS - Disk and Screen I/O
GEMDOS was converted from CP/M 68k and is similar in many ways to
generic CP/M but with extra facilities (e.g. sub-directories)
taken from MS-DOS. It is responsible for disk I/O and character
I/O via the screen, keyboard, serial and parallel ports. It is
also responsible for memory management.
GEMDOS was designed to be called directly from C, so all
parameters are put onto the stack and have to be removed
afterwards. The calling sequence from assembler is of this
general form:
move ??,-(a7) put parameters on stack
move.w #??,-(a7) the function number
trap #1 call GEMDOS\
add.l #??,a7 restore the stack
After the call the stack has to be corrected; while an ADD.L can
be used as above, it is slow and takes six bytes. If the stack
needs correction by 8 bytes or less, the best way is to use
add.l #??,a7
which takes two bytes. If it has to be corrected by more than 8
bytes, the best way is
lea ??(a7),a7
which takes four bytes. Both methods are smaller and faster than
the first method. Incidentally, a major source of bugs when
starting programming with GEMDOS is forgetting to correct the
stack, or correcting it by the wrong value.
Program Startup and Termination
When a GEMDOS program starts up it owns all free memory - that is
the memory from the end of the program through to the end of
usable RAM (normally just before the screen) is owned by the
program, which is just as well as the stack is at the very end of
the area.
If any memory management calls (such as m_alloc) are required,
you wish to execute other programs within yours, or if you are
writing a GEM program, it is important to give back some of this
memory. If you don't there will be no free memory for these uses.
this is normally done during at the beginning of programs using
the m_shrink call, utilising the fact that a pointer to the
programs basepage is 4 bytes down on the stack, like this:
move.l 4(a7),a3 basepage
move.l $C(a3),d0 text length
add.l $14(a3),d0 data length
add.l $1C(a3),d0 BSS length
add.l #extra,d0 any additional memory
add.l #$100,d0 basepage length
move.l #mystack,a7 before shrinking
move.l d0,-(a7)
move.l a3,-(a7)
clr.w -(a7)
move.w _(a7)
trap #1 do the shrink
lea 12(sp),sp
The extra bytes may be required for your programs storage. Note
that you should move the stack to a safe before the shrink,
otherwise the stack will be in memory that is not owned by your
program and liable to corruption.
A GEMDOS program can terminate in one of three ways: p_term0,
which is not recommended, p_term, the normal way to finish a
program, and p_termres, for system patches and the like. For
normal termination use this code:
clr.w -(a7) no return code
move.w #S4c,-(a7) p_term
trap #1
When a program terminates all memory it owns is freed and any
open files are closed.
GEMDOS Summary
The calls will now be described in numeric order by giving the
size of the parameters, in the order they should be placed on the
stack, and the stack correction number. For example, using
function call 2, c_conout, to print the character x, the code
would be
move.w #'X',-(a7) the character
move.w #2,-(a7) the function number
trap #1 call it
addq.l #4,sp then correct
At present GEMDOS calls corrupt registers d0 and a0 only, but
this is not documented. We therefore recommended programmers to
assume that registers d0-d2/a0-a2 are corrupted, in a similar way
to the other operating system calls.
0 - Terminate Process (old form), p_term0
Parameters: None
Result: None
Stack: 2
This terminates the current program, with a return code of 0. It
is recommended that p_term (function $4c) should be used in
preference to this call. As control never returns after the call,
no stack correction is actually required.
1 - Read character from keyboard, c_conin
Parameters: None
Result: D0.L=key code
Stack: 2
This waits for a key to be struck, echoes it to the screen, and
returns its value. The long result has the ASCII value in the
lowest 8 bits, and a physical key number is returned in bits 16-
23. All other bits are set to 0.
2 - Write character to screen, c_conout
Parameters: word: character
Result: None
Stack: 4
This writes the given character to the screen. A 16-bit parameter
is supported for future expansion, so bytes should always be
ANDed with $FF before the call, though currently the upper 8 bits
are ignored.
3 - Read Character from serial port, c_auxin
Parameters: None
Result: D0.B=character read
Stack: 2
This waits for a byte to be received from the auxiliary device,
which is the serial port.
4 - Write characters to serial port, c_auxout
Parameters: word: character
Result: None
Stack: 4
This sends the character out via the serial port. As with
function 2, the upper 8 bits of the word should be 0 for upward
compatibility.
5 - Write character to printer, c_prnout
Parameters: word: character
Result: D0.W=0 if failed, -1 if OK
Stack: 4
This sends the character out via the parallel printer port. As
with functions 2 and 4 above, bits 8-15 of the word should be 0.
6 - Raw I/O to standard I/O, c_rawio
Parameters: word: character for output, or $00FF to read
Result: D0.W if $00FF passed
Stack: 4
If the character is passed as $00FF then the keyboard is scanned
and a result returned in D0.W (or 0 if no key available). If the
character is not $00FF, then it is printed on the screen.
7 - Raw input from keyboard, c_rawcin
Parameters: None
Result: D0.L=character read
Stack: 2
This waits for a key to be pressed and returns its value. It does
not echo it to the screen.
8 - Read character from keyboard, no echo, c_necin
Parameters: None
Result: D0.L=character read
Stack: 2
This waits for a key to be pressed and returns its value. It does
not echo, but the control keys Ctrl-C, Ctrl-S and Ctrl-Q are
interpreted in their usual way - Ctrl-C will abort the program.
Ctrl-S will pause output and Ctrl-Q will resume it.
9 - Write string to screen, c_conws
Parameters: long: address of string
Result: Non
Stack: 6
This writes the given null-terminated string to the screen.
$A - Read edited string from keyboard, c_conrs
Parameters: long: address of input buffer
Result: None
Stack: 6
Before calling this, the first byte of the buffer should be set
to the size of the data portion of the buffer. On return, the
second byte in the buffer will be set to the length of the
string, and the string itself starts at the third byte. No CR or
null is stored in the returned string and pressing Ctrl-C will
terminate the entire program.
$B - Check status of keyboard, c_conis
Parameters: None
Result: D0.L=-1 if character available, 0 if none
Stack: 2
This returns the status of the keyboard. The key itself should be
read with another call.
$E - Set default drive, d_setdrv
Parameters: word: drive number
Result: D0.L=bit map of drives in the system
Stack: 4
This sets the default drive; a word of 0 denotes A:, 1 denotes
B;, etc. The returned value has a bit set for each installed
drive, bit 0=A:, bit 1=B:, etc.
$10 _ Check status of standard output, c_conos
Parameters: None
Result: D0.L=-1 if ready, 0 if not
Stack: 2
This tests to see if the console device is ready for output.
$11 - Check status of printer, c_prnos
Parameters: None
Result: D0.L=-1 if ready, 0 if not
Stack: 2
This tests the status of the printer port. If the printer is
ready to receive a character it returns -1, else it returns 0.
$12 - Check status of serial port input, c_auxis
Parameters: None
Result: D0.L=-1 if character waiting. 0 if not
Stack: 2
This tests the serial port and returns -1 if there is a character
waiting to be read.
$13 - Check status of serial port output, c_auxos
Parameters: None
Result: D0.L=-1 if ready, 0 if not
Stack: 2
This tests the serial port and returns -1 if it is ready to
receive a character.
$19 - Get default drive, d_getdrv
Parameters: None
Result: D0.W=drive number
Stack: 2
This returns the number of the current drive, with A:=0, B:=1,
etc.
$1A - Set disk transfer address, f_setdta
Parameters: long: pointer to disk transfer address
Result: None
Stack: 6
This sets the address of a 44-byte buffer used for searching for
filenames. It must be word-aligned.
$20 - Get into Supervisor/User Mode, s_super
Parameters: long: value for stack, or 0 or 1
Result: D0.L=(depends on parameter)
Stack: 6
This has two functions - it can tell you if the program is in
User or Supervisor mode and it can switch from one mode to
another. To find which mode the processor is in, call this
routine with a parameter of 1. The return value will be 0 for
user mode, and -1 for supervisor. To switch modes you have to
supply a new stack pointer, or pass 0 if you want the stack to
remain unchanged. For example, if you are in user mode and want
to switch to supervisor mode using a SPP at address myssp, the
code would be:
move.l #myssp,-(a7)
move.w #$20,-(a7)
trap #1
addq.l #6,a7
When switching to supervisor mode the old value of the SSP is
returned in d0.l. If you only want to go temporarily into
Supervisor mode to hack protected memory, for example, XBIOS call
supexec is a lot easier.
$2A - Get date, t_getdate
Parameters: None
Result: D0.W
Stack: 2
This reads the date, with the result in this format:
Day: bits 0-4
Month: bits 5-8
Year: bits 9-15 (since 1980).
$2B - Set date, t_setdate
Parameters: word: date
Result: None
Stack: 4
This sets the date, using the same word format as the previous
function.
$2C - Get time, t_gettime
Parameters: None
Result: D0.W
Stack: 2
This returns the time of day, with the result in this format:
Seconds/2: bits 0-4
Minutes: bits 5-10
Hours: bits 11-15
$2D - Set time, t_settime
Parameters: word: time
Result: None
Stack: 4
This sets the current time of day, in the same word format as the
previous function.
$2F - Get disk transfer address, f_getdta
Parameters: None
Result: D0.L=pointer to disk transfer address
Stack: 2
This returns the current disk transfer address, and should always
be even.
$30 - Get version number, s_version
Parameters: None
Result: D0.W=version number
Stack: 2
This returns the GEMDOS version number, with the major number in
the low byte, and the minor number in the high byte. Known
releases at this time are:
$0D00 version 0.13 (obsolete disk-based)
$1300 version 0.19 (ROM-based)
$31 - Terminate and stay resident, p_termres
Parameters: word: exit code, long: bytes to keep
Result: None
Stack: 8
This allows a program to terminate while keeping part or all of
it in memory. It is useful for programs which extend the system,
such as RAM disk drivers; if they terminated normally the memory
the lie in would get destroyed when the next program loaded. The
memory that can be retained is that starting at the base page,
and the length parameter should include the $100 of the base
page, the required program length, data and stack space if
relevant.
$36 - Get drive free space, d_free
Parameters: word: drive code, long: pointer to buffer
Result: None
Stack: 8
This returns various bits of information about a particular disk
drive. The drive code should be 0 for the default drive, 1 for
A:, 2 for B:, etc. The buffer should be 16 bytes long, and word
aligned. On return, it will contain 4 longs of information; free
space, number of available clusters, sector size (in bytes), and
cluster size (in sectors).
$39 - Create a sub-directory, d_create
Parameters: long: address of pathname
Result: D0.W=0 if OK, else error code
Stack: 6
This creates a new directory, according to the null-terminated
string.
$3A - Delete a sub-directory, d_delete
Parameters: long: address of pathname
Result: D0.W=0 if OK, else error code
Stack: 6
This deletes a directory, so long as it has no files or other
directories in it.
$3B - Set current directory, d_setpath
Parameters: long: address of pathname
Result: D0.W=0 if OK, else error code
Stack: 6
This sets the current directory, according to the null-terminated
string. Note that drive specifiers are not allowed - you should
set the current drive then its directory.
$3C - Create a file, f_create
Parameters: word: attributes, long: pointer to string
Result: D0.W=file handle if successful, else error (and
longword negative)
Stack: 8
This will attempt to create the given file and if successful will
return a file handle that can be used in other file GEMDOS calls.
The attribute word can be these values:
01 read only
02 hidden file
04 hidden system file
08 filename contains volume name in first 11 bytes
File handle numbers returned by this call and the following one
start are words normally starting at 6 and go upwards. Handles 0
to 5 are standard handles which are already open when a program
starts. They correspond to the following devices:
0 - console input
1 - console output
2 - serial port
3 - parallel port
There are three system device names, called CON:, AUX: and PRN:
which can be used with this and the following call. They return
negative works, so to distinguish these from error returns always
TST.L/BMI for the error case.
$3D - Open a file, f_open
Parameters: word: mode, long: pointer to filename
Result: D0,W=file handle if successful, else error (and
longword negative)
Stack: 8
This will open an existing file for reading, writing, or both.
The mode word must be one of the following:
0 open to read
1 open to write
2 open for both reading and writing
If successful this will return a handle which can be used
subsequently, else an error number.
$3E - Close file, f_close
Parameters: word: handle
Result: D0.W=0 if OK, else an error number
Stack: 4
Given a file handle this will close the file. Do not close a
standard handle.
Note: This call, along with all the others that require handles,
do not do very extensive checks on the validity of the handle. If
you pass an invalid one you may get an error return, or the
machine may crash!
$3F - Read file, f_read
Parameters: long: load address, long: number of bytes to
read, word: handle
Result: D0.L=number of bytes read, or an error code
Stack: 12
This will attempt to read bytes from the given file. If an error
occurs D0.L will be negative. If the end of file is reached
during the read operation an error code is not returned - if you
wish to check for this you have to compare the number of bytes
you asked for with the result - if they are different then you
tried to read past the end of file.
$40 - Write file, f_write
Parameters: long: start address, long: number of bytes to
write, word: handle
Result: D0.L=number of bytes written, or an error code
Stack: 12
This will attempt to write bytes to the given file. If an error
occurs D0.L will be negative. If the disk becomes full an error
code will not be issued, but the value returned will not be the
same as the value passed to it as the number of bytes to write.
Note: If you pass a negative length parameter GEMDOS will crash
very badly.
$41 - Delete File, f_delete
Parameters: long: pointer to filename
Result: D0.W=0 if successful, else error code
Stack: 6
This will attempt to delete the given file.
$42 - Seek file pointer, f_seek
Parameters: word: mode, word: file handling, long position
Result: D0.L=absolute position in file after seek
Stack: 10
This will move the file pointer to a given position in the file.
The mode word should be one of the following.
0 move to N bytes from the start of the file
1 move to N bytes from the current location
2 move to N bytes from the end of the file
If you try and move past either end of the file you will get a
result of 0 (for the start) or the actual length of the file.
$43 - Get/Set file attributes, f_attrib
Parameters: word: attributes, word: get/set, long: pointer to
filename
Result: D0.W=new attributes, or an error code
Stack: 10
This can be used to get or set the attributes for a given file.
The attribute's word can be:
01 read only
02 hidden file
04 hidden system file
08 filename is actually the volume label in first 11
bytes
$10 sub-directory
$20 file is written and closed
The other word should be 0 to Get the attribute, or 1 to Set it.
$45 - Duplicate File Handle, f_dup
Parameters: word: standard handle
Result: D0.W=new handle, or error code
Stack: 4
Given a handle to a standard device (0-5), this function returns
another handle that can be used to address the same device. It
can also be closed without affecting the standard device handle.
$46 - Force file handle, f_force
Parameters: word: non-standard handle, word: standard handle
Result: D0.W=0 if OK, else error code
Stack: 6
This forces the standard handle to point to the same device or
file as the non-standard one, and can be used, for example, to
re-direct screen output to a disk file.
$47 - Get Current Directory, d_getpath
Parameters: word: drive number, long: pointer to buffer
Result: D0.W=0 if OK, else error code
Stack: 8
Given a drive number (default drive=0, A:=1, B:=2 etc.) this will
return the current directory in the given buffer, in null-
terminated form. The buffer should be 64 bytes long.
$48 - Allocate Memory, m_alloc
Parameters: long: number of bytes required
Result: D0.L=address of memory allocated, or 0 if failed
Stack: 6
This allocates the given amount of memory from the system pool,
if available. When a program terminates all its memory
allocations are cleaned up. This call can also be used to find
the amount of free memory, if -1 is passed.
Note: When GEMDOS itself uses this call it always ensures the
number of bytes required is even, so we recommend this out of
paranoia. This call can occasionally return an odd value for the
start of the allocated memory under TOS 13.
$49 - Free Allocated Memory, m_free
Parameters: long: address of area to free
Result: D0.W=0 if OK, else an error code
Stack: 6
This frees a block of memory allocated with m_alloc above.
$4A - Shrink Allocated Memory, m_shrink
Parameters: long: length to keep, long: start address to
keep, word: 0
Result: D0.W=0 if OK, else an error code
Stack: 12
This is normally used when a program starts up and releases part
of the allocated memory back to GEMDOS.
$4B - Load or Execute a Program, p_exec
Parameters: long: pointer to environment string, long:
pointer to command line, long: pointer to
filename, word: mode
Result: D0.L=(depends on mode)
Stack: 16
This call can be used for loading and chaining programs. The mode
word can be one of:
0 load and execute
3 load but do not execute
4 execute base page
5 create base page
For load and execute, the return value is either an error code,
or the value returned when the child program exited.
For load but don't execute the return value is either an error
code, or a pointer to the base page of the loaded program.
A discussion of using modes 4 and 5 is beyond the scope of this
document.
The command line should be of the form of a length byte followed
by the line itself.
The environment string may be passed as 0 to inherit the programs
parents basepage, or as a pointer to a list of null-terminated
environment strings, ending in a double-null. The normal
environment looks like this:
dc.b 'PATH=',0,'A:\',0,0
$4C - Terminate Program, p_term
Parameters: word: return value
Result: N/A as doesn't return
Stack: N/A
$4E - Search for First, f_sfirst
Parameters: word: attributes, long: pointer to filespec
Result: D0.W=0 if found, else -33 not found
Stack: 8
This trap can be used to scan a directory using wild-cards to
find all the files. This should be called to find the first one,
then f_snext should be called for the rest. When a file is found
the parameters of the file are returned in the DTA buffer area.
The attribute word determines which file types are to be included
in the search, and may be one of:
00 normal files
01 read only files
02 hidden files
04 system files
08 return volume name only
$10 sub-directories
$20 files that have been written to and closed
The returned values in the DTA buffer are:
0-20 reserved for internal use
21 file attributes
22-23 file time stamp
24-25 file date stamp
26-29 file size (long)
30-43 name and extension of file, null terminated
The address of the DTA buffer can be set with function $1A, and
read with function $2F.
$4F - Search for Next Occurrence, f_snext
Parameters: None
Result: D0.W=0 if found, else -33 not found
Stack: 2
After calling f_first to find the first occurrence of a filespec,
this call is used to find subsequent files. When a file is found
the DTA buffer is filled as described previously. For it to work
the first 20 bytes of the DTA must remain untouched between
calls.
$57 - Rename a file, f_rename
Parameters: long: pointer to new name, long: pointer to old
name, word: 0
Result: D0.W=0 if OK, else error code
Stack: 12
This will attempt to rename the file to the new name. A file with
the new name must not already exist.
$57 - Get/Set File Date & Time Stamp
Parameters: word: 0 for Get/1 for Set, word: file handle,
long: pointer to buffer
Result: None
Stack: 10
This can be used to get or set the time and date stamp on an open
file. The buffer should contain two words, the first being the
time, and the second the date, in the format already described.
BIOS - Basic I/O System
The ST BIOS is intended for low-level access to the screen,
keyboard and disk drives. It is accessed using the stack for
parameters as described previously, but using TRAP #13 to invoke
it. Programmers who require access to the BIOS are likely to need
much more details then we could provide, so only one BIOS call is
described here. For greater BIOS detail see the books in the
bibliography. The BIOS handler preserves registers D3-D7/A3-A7 -
all others may be corrupted by a call.
BIOS 5 - Set Exception Vector, setexc
This is a very useful trap and sets certain system vectors to
point to your own routines. It can set both exception vectors and
system vectors. The calling sequence is:
move.l #myroutine,-(a7) address of new handler
move.w #vectornum,-(a7) vector number
move.w #5,-(a7) BIOS function number
trap #8,a7 restore stack
move.l d0,oldroutine store old one
The vector number should be the exception number (2 for bus
error, 3 for address error etc.) or one of the following system
vectors:
$45 200Hz list
$100 system timer interrupt
$101 critical error handler
$102 process terminate hook
On return from the trap D0.L contains the previous value. If a
program modifies any vectors it should always restore them to
their original values before terminating.
If you pass an address of -1 it will not be changed, but the
current value will be returned in D0.L.
XBIOS - Extended BIOS
The XBIOS consists of 40 functions for a wide variety of
functions including hardware access, screen control, and
keyboard mapping. Again we leave most of the description to the
books in the bibliography, with the exception of five XBIOS
calls. The XBIOS handler preserves registers D3-D7/A3-A7 - all
others can be corrupted by a call. The calling sequence is the
usual one: put parameters on the stack, put a function word on
the stack, do a TRAP #14, then restore the stack. The XBIOS
functions are:
XBIOS 2 - Get Physical Screen Address, _physbase
Parameters: None
Result: D0.L=start of screen
Stack: 2
This will return the physical address of the screen, which always
occupies 32000 bytes and is aligned on a 256-byte boundary.
XBIOS 3 - Get Logical Screen Address, _logbase
Parameters: None
Result: D0.L=start of screen
Stack: 2
This will return the logical address of the screen.
XBIOS 4 - Get Screen Resolution, _getRez
Parameters: None
Result: D0.W=0 low, 1 medium, 2 high
Stack: 2
This will return the current screen resolution.
XBIOS 5 - Set Screen Address & Mode, _setScreen
Parameters: word: mode, long: physical address, long: logical
address
Result: None
Stack: 12
This lets you change the screen resolution and addresses. If any
parameter is specified as -1 then it is left alone. Changing the
screen mode will clear the screen.
XBIOS $26 - Call Supervisor Routine, supexec
Parameters: long: address of routine
Result: None
Stack: 6
This will call the given routine in supervisor mode. The routine
should not make any BIOS, XBIOS or GEMDOS calls.
GEM Libraries
GEM itself consists of two components; the VDI and the AES.
The GEM VDI (for virtual Device Interface) is the main part of
the operating system that draws graphics and text on the screen.
The GEM AES (for Application Environment Services) is the part of
the operating system that provides the user-interface facilities
of GEM such as windows, menus and dialogue boxes.
This section is intended to give details of the supplied library
files and calling conventions used. It does not attempt to
describe either the VDI or the AES in great detail - the books in
the Bibliography should be referred to for this. However, details
are given of information that we feel is badly documented or not
documented at all.
GEM AES Library
The calling sequence to the AES is based on various arrays of
words and longwords. These arrays are defined using DS directives
and are:
control words
int_in words
addr_in longwords
int_out words
addr_out words
aes_params longwords
global words
For example the C program segement
val=int_out (2)+int_out (3)
could be converted into this assembly language:
move.w int_out+4,d0
add.w int_out+6,d0
Note the way that the array index is doubled before adding to the
start of the array, as it is an array of words. For an array of
longs the index should be quadrupled.
A macro file, called GEMMACRO.S should be used which defines
various macros and, if generating executable code, the file
AESLIB.S should be included at the end of assembly.
The macros take a varying number of parameters and place them in
the required places in the AES arrays, before making a call to
the general AES routine. If passing a constant to a macro be sure
to precede it with a # sign, for example passing the parameters
3,myptr to a macro could generate the code
move.w 3,int_in
move.1 myptr,addr_in
The first line will cause a run-time error, the parameter should
have been #3. There are a few AES macros which do not take all
the required parameters - additional information may have to be
placed in other arrays. On return from and AES macro D0.W (and
the flags) reflect the contents of the array int_out(0), normally
useful. Various return values can often be found in the int_out
array.
The following descriptions assume all parameters to be word
sized, unless shown with a .L suffix, denoting a longword
parameter.
Application Library
appl_init
Should be called at the start of any AES program.
appl_read id,length,buffer.L
apppl_write id,length,buffer.L
appl_find name.L
Find a named program, normally a desk accessory
appl_tplay memory.L,number scale
appl_trecord memory.L,count
appl_exit
Should be just before an AES program terminates. It sends
AC_CLOSE type messages to all desk accessories.
Event Library
evnt_keybd
evnt_button clicks,mask,state
The return value is the number of times the button entered the
desired state. Array elements 1-4 of int_out contain the X co-
ordinate, the Y co-ordinate, the button state and the keyboard
state at the time of the event in that order.
evnt_mouse flags,x,y,w,h
The return values are as described for the previous call.
evnt_mesag buffer.L
evnt_timer count.L
evnt_multi flags,clicks,mask,m1flags,m1x,m1y,m1w,m1h,
& m2flags,m2x,m2y,m2w,m2h,count.L
All parameters except the first are optional, specifying a null
parameter means nothing is placed in the relevant element of
int_in. It shown above with the syntax of a multi-line macro
call but this is not obligatory. The int_out array contains
which event, mouse X, mouse Y, button, keyboard state, keyboard
code and button value, respectively.
evnt_dclick new,getset
Menu Library
menu_bar free.L,show
menu_icheck tree.L,item,check
menu_ienable tree.L,item,enable
menu_tnormal tree.L,title,normal
menu_text tree.L,item,text.L
menu_register id,string
Note: Normally a menu tree is generated by a resource editor
though they can be constructed, with a great deal of care, by
hand. Another alternative is to use the MENU2ASM
compiler,detailed later in this section.
Object Library
Object trees are normally constructed with a resouce editor,
though they can be constructed by hand if required. Dialog boxes
are the easiest type of object tree to construct by hand and
menus the most difficult.
objc_add tree.L,parent,child
objc_delete tree.L,object
objc_draw tree.L,startob,depth,x,y,w,h
objc_find tree.L,startob,depth,x,y
objc_offset tree.L,object
Elements 1 and 2 of int_out contain the returned X and Y co-
ordinates.
objc_order tree.L,object,newpos
objc_edit tree.L, object,char,idx,kind
int_out(1) contains the new idx
objc_change tree.L,object,x,y,w,h,new,redraw
Form Library
form_do tree.L,startob
Never pass startob as -1 as often documented, use 0 instead
form_dial flag,x1,y1,w1,h1,x2,y2,w2,h2
form_alert button,string.L
form_error errnum
Error numbers should be positive and less than 64
form_center tree.L
Graphics Library
graf_rubberbox x,y,w,h
int_out(1) contains the finish width, int_out(2) the height
graf_dragbox w,h,x,y,bx,by,bw,bh
int_out(1) contains the finish X co-ordinate, int_out(2) the Y
graf_movebox w,h,x,y,dx,dy
graf_growbox w,y,w,h,fx,fy,fw,fh
graf_shrinkbox x,y,w,h,sx,sy,sw,sh
graf_watchbox tree.L,object,instate,outstate
graf_slidebox tree.L,parent,obj,vh
graf_handle
The int_out array will contain the VDI handle, character cell
width, then height, system font width, then height
graf_mouse number,address.L
The address parameter is optional, only required if defining
your own shape
graf_mkstate
The int_out array will contain a reserved value, mouse X and Y
position, mouse button state and keyboard state.
Scrap Library
scrp_read buffer.L
scrp_write buffer.L
File Selector Library
fsel_input path.L,filename.L
The path parameter should point to a buffer containing the
null-terminated path, such as A:\ø.S, and the new path will be
returned in it, so be sure it is large enough. The filename
buffer should be 13 bytes, with a maximum of 12 used for
filename, for example TEST.S. If D0.W is non-zero on return
then it means there was not enough free memory to invoke the
selector, else int_out(1) will contain 0 if Cancelled.
Window Library
wind_create kind,x,y,w,h
wind_open handle,x,y,w,h
wind_close handle
wind_delete handle
wind_get handle,field
wind_set handle,field
wind_find x,y
wind_update begend
wind_calc type,kind,inx,iny,inw,inh
Resource Library
rsrc_load filename.L
rsrc_free
rsrc_gaddr type,index
The result address may be found in addr_out
rsrc_saddr type,index,saddr.L
rsrc_obfex tree.L,object
Shell Library
shel_read command.L,shell.L
shel_write doex,sgr,scr,cmd.L,shell.L
We have never managed to get this call to work reliably
shel_find buffer.L
The buffer should be a minimum of 80 bytes
shel_envrn value.L,string.L
Debugging AES Calls
Unlike the calls to the VDI, calls to the AES are not immediately
obvious when viewed from MonSt as they are of the form:
moveq #??,d0 AES function number
bsr CALL_AES
As an aid to decoding these, here is a table listing all the AES
calls and their hex function numbers:
A appl_init B appl_read C appl_write
D appl_find E appl_tplay F appl_trecord
13 appl_exit 14 evnt_keybd 15 evnt_button
16 evnt_mouse 17 evnt_mesag 18 evnt_timer
19 evnt_multi 1A evnt_dclick 1E menu_bar
1F menu_icheck 20 menu_ienable 21 menu_tnormal
22 menu_text 23 menu_register 28 objc_add
29 objc_delete 2A objc_draw 2B objc_find
2C objc_offset 2D objc_order 2E objc_edit
2F objc_change 32 form_do 33 form_dial
34 form_alert 35 form_error 36 form_center
46 graf_rubberbox 47 graf_dragbox 48 graf_movebox
49 graf_growbox 4A graf_shrinkbox 4B graf_watchbox
4C graf_slidebox 4D graf_handle 4E graf_mouse
4F graf_mkstate 50 scrp_read 51 scrp_write
5A fsel_input 64 wind_create 65 wind_open
66 wind_close 67 wind_delete 68 wind_get
69 wind_set 6A wind_find 6B wind_update
6C wind_calc 6E rsrc_load 6F rsrc_free
70 rsrc_gaddr 71 rsrc_saddr 72 rsrc_obfix
78 shel_read 79 shel_write 7A shel_find
7B shel_envrn
GEM VDI Library
The calling sequence itself to the VDI is, like the AES, based on
various arrays of words and longwords. These arrays are defined
using DS directives and are:
contrl words
intin words
ptsin words
intout words
ptsout words
vdi_params longwords
All (but one) VDI calls require a VDI handle, which by tradition
is a parameter to every call. However, the majority of programs
only use one handle, to a virtual workstation (the screen), so
the supplied VDI libraries use a word called current_handle as
the handle to pass on to the VDI itself. This saves an
appreciable amount of code and is the same way the HiSoft BASIC
libraries work. As the source to the library is supplied you
could change this, if required.
The macro file GEMMACRO.S should be used which defines various
macros and, if generating executable code, the file VDILIB.S
should be included at the end of assembly.
The macros take a varying number of parameters and place them in
the required places in the VDI arrays, before making a call to a
VDI library routine. The warning about # signs in parameters
described previously applies to the VDI too. There are a number
of VDI macros which do not take all the required parameters -
additional information may have to be placed in other macros. On
return, various return values can often be found in the intout
ptsout arrays.
The following descriptions assume all parameters to be word
sized, unless shown with a .L suffix, denoting a longword
parameter.
Control Functions
v_opnwk Open Workstation
This should not be used unless GDOS is installed. The intin array
should be suitably initialised, current_handle will be set to the
result of this call.
v_clswk Close Workstation
v_opnvwk Open Virtual workstation
This uses current_handle to open another workstation and sets
current_handle to the result. intin is normally filled with 10
words of 1 and one word of 2 (denoting RC co-ordinates).
v_clsvwk Close Virtual Workstation
V_clrwrk Clear Workstation
v_updwk Update Workstation
vst_load_fonts Load Fonts
Do not attempt this unless GDOS is loaded.
vst_unload_fonts Unload Fonts
Fonts must be unloaded before a workstation is closed.
vs_clip flag,x1,y1,x2,y2 Set Clipping Rectangle
Output Functions
v_pline count Polyline
The input co-ordinates should be copied to intin before the call.
v_pmarket count Polymarker
The input co-ordinates should be copied to intin before the call.
v_gtext x,y,string.L Text
The string should be in the form of null-terminated bytes.
v_fillarea Filled Area
The input co-ordinates should be copies to itin before the call.
v_contourfill x,y,index Contour Fill
vr_recfl x1,y1,x2,y2 Bar
v_arc x,y,radius,start,end Arc
v_pieslice x,y,radius,start,end Pie
v_circle x,y,radius Circle
v_ellarc x,y,xradius,yradius,start,end Elliptical Arc
v_ellpie x,y,xradius,yradius,start,end Elliptical Pie
v_ellipse x,y,xradius,yradius Ellipse
v_rbox x1,y1,x2,y2 Rounded Rectangle
v_rfbox x1,y1,x2,y2 Filled Rounded Rectangle
v_justified x,y,string.L,length,ws,cs Justified Graphics Text
The string should be null-terminated
Attribute Functions
vswr_mode mode Set Writing Mode
vs_colour index,red,green,blue Set Colour Representation
vsl_type style Set Polyline Line Type
vsl_udsty pattern Set User Defined Line Style Pattern
vsl_width width Set Polyline Line Width
vsl_color index Set Polyline Colour Index
vsl_ends begin,end Set Polyline End Styles
vsm_type symbol Set Polymarker Type
vsm_height height Set Polymarker Height
vsm_color index Set Polymarker Colour Index
vst_height height Set Character Height, Absolute Mode
The ptsout array will contain the selected size
vst_point point Set Character Height, Points Mode
The ptsout array will contain the selected size.
vst_rotation angle Set Character Baseline Vector
vst_font font Set Text Face
vst_colour index Set Graphic Text Colour Index
vst_effects effect Set Graphic Text Special Effects
vst_alignment horizontal,vertical Set Graphic Text Alignment
vst_interior style Set Fill Interior Style
vst_style index Set Fill Style Index
vsf_color index Set Fill Colour Index
vsf_perimeter vis Set Fill Perimeter Visibility
vsf_updat Set User Defined Fill Pattern
The intin array should be filled with the pattern and contrl(3)
set suitably.
Raster Operations
vro_cpyfm mode,source.L,dest.L Copy Raster, Opaque
This is the general blit call, most often used for scrolling the
screen. The source and destination parameters should point to a
memory form definition block (MFDB) which describes the format of
the memory to blit. An MFDB consists of ten words:
0 high word of address
2 low word of address
4 width in pixels
6 height in pixels
8 width in words
10 form flag, normally 1
12 number of planes
14-18 reserved, set to 0
The address in the first two words is normally either the screen
address of the address of a buffer being used for the blit. The
width and height fields should be those suitable for the screen
size and the number of planes can be found from a vq_extend 1
call in intout(4). When scrolling the screen the source and
destination parameters may point to the same MFDB.
The source and destination rectangles should be placed in the
ptsin array, each in the form x1,y1,x2,y2. A mode of 3 means
replace.
vrt_cpyfm mode,source.L,dest.L,i1,i2 Copy Raster, Transparent
vr_trnfm source.L,destination.L Transform Form
vr_get_pixel x,y Get Pixel
Input Functions
vex_timv newtimer Exchange Timer Interrupt Vector
v_show_c reset Show Cursor
v_hide_c Hide Cursor
vq_mouse Sample Mouse Button State
vex_butv newxbut Exchange Button Change Vector
vex_motv newmotv Exchange Mouse Movement Vector
vex_curv newcursor Exchange Cursor Change Vector
vq_key_s Sample Keyboard State Information
Inquire Functions
vq_extnd flag Extended Inquire
vq_color index,flag Inquire Colour Representation
vql_attributes Inquire Polyline Attributes
vqm_attributes Inquire Polymarker Attributes
vqf_attributes Inquire Fill Area Attributes
vqf_attributes Inquire Graphic Text Attributes
vqt_extent string.L Inquire Text Extent
The string should be null-terminated, the results will be found
in ptsout.
vqt_width char Inquire Character Cell Width
vqt_name number Inquire Face Name & Index
vqt_fontinfo Inquire Current Face Information
AES & VDI Program Skeleton
The general structure of a GEM-type program is as follows:
shrink memory call
call appl_init
set current_handle to the result from graf_handle
open a virtual workstation using this handle
open a window, perhaps
main wait for events & act on them as required
quit close any window
call appl_exit
finally p_term
Desk Accessories
A desk accessory is an executable file with the extension .ACC
loaded during AES initialisation. We have never seen any official
documentation on desk accessories, and the following information
has been learnt the hard way, mainly when writing our Saved!
program.
The first thing to be wary of is that it is not a normal GEMDOS
program. When it starts up all registers including A7 are 0, with
the exception of A0 which points to the basepage. An accessory
must include all the memory it requires within itself, the BSS
segment being a good place. An accessory must not do a GEMDOS
shrink call or attempt to terminate.
The main loop of an accessory is like any other AES program,
consisting of an event loop, but note that most documentation
details incorrect message numbers - AC_OPEN is really 40 and
AC_CLOSE is 41.
Other programmers have reported problems using the VDI from
within an accessory. The recommended method is to open a virtual
workstation only when you have to (i.e. before creating a window)
and always close it (when you close your window or, failing that,
when receiving an AC_CLOSE message. The example accessory
supplied, like our Saved! program, does not use the VDI at all -
paranoia rules!
If your accessory responds to timer events ensure that no GEMDOS
calls (Trap #1s) are made unless your window is the front one,
otherwise time bombs will be set and a crash is highly likely.
The file DESKACC.S contains the source to an example accessory,
which simply displays the system free memory in an alert box. It
has a label called RUNNER which can be set to 1 to produce a
stand-alone application instead of an accessory. This can be
invaluable during program development as you can symbolically
debug a stand-alone program, while an accessory has to be
debugged using AMONST without the benefit of symbols.
Linking with AES & VDI Libraries
The supplied macro file GEMMACRO.S is designed to be used in
executable or linkable programs. The files AESLIB.S and VDILIB.S
contain the actual code and should be included at the end of
programs when generating executable code, but if generating
linkable code they should not. If you look at GEMTEST.S you can
see how a conditional is used to make this automatic.
When developing a program using these libraries we recommend
executable code as it greatly reduces development time. However
the file size can be reduced by using the selective library
feature of the linker and using the GEMLIB.BIN file. For example,
if GEMTEST is linked to GST-linkable code, producing
GEMTEST.BIN, it can be linked with this library by passing LinkST
the command line
gemtest -wgemlib
The GEMLIB.LNK control file will do the rest. If you want to
reduce your program to the absolute minimum then you can change
the libraries as you require, which is why we supply the source
code.
Menu Compiler
For those who wish to use menus without using a resource editor
we supply the program MENU2ASM.TTP which converts a menu
definition file into assembly language source statement for
inclusion in your program. We use this method ourselves in the
GenST editor.
The menu specification should be created in a text file with the
extension .MDF and an example follows:
[ Desk | About Program ]
[ File | New \ Load \ (-------\ Quit ]
[ Search | Find ]
and so on. Line breaks are ignored. Each menu title and its items
are enclosed in square brackets [ and ]. There is a vertical bar
(|) after each title and the individual items separated by back-
slashes (\). For grey items precede the text with an open
parentheses (. The first menu is always the desk title (normally
Desk); the currently loaded desk accessories will be added by the
AES. (It is no coincidence that this is the same syntax as that
accepted by our BASIC compilers).
We recommend that you precede each menu item with two spaces and
have at least one space after the item. Menu titles should have
one space before and after them.
To compile a file double-click on MENU2ASM.TTP and enter the
filename, without an extension. It will produce a file with an
extension of .MNU which may be included in your program.
The file MENUTEST.MDF contains an example definition of a menu
and MENUTEST.S the source code to a program illustrating its use,
as well as showing other AES features.
Old GenST AES & VDI Libraries
The folder OLDGEM contains updated versions of the source files
supplied with version 1 of DevpacST. These use different calling
conventions and are supplied for users who have upgraded.
VT52 Screen Codes
When writing to the screen via the BDOS or BIOS calls, the screen
driver emulates VT52 protocols. The control codes are sent via
escape sequences, which means an escape character is sent (27
decimal, or $1B) followed by one or more other characters.
ESC A cursor up; no effect if at the top line
ESC B cursor down; no effect if at the bottom line
ESC C cursor right; no effect if on the right hand side
ESC D cursor left; no effect if on left hand side
ESC E clear screen and home cursor
ESC H home cursor
ESC I move cursor up one line; if at top scrolls the screen
down a line
ESC J erase to end of screen, from the cursor position onwards
ESC K clear to end of line
ESC L insert a line by moving all following lines down. Cursor
is positioned at start of the new line
ESC M delete a line by moving all following lines up
ESC Y position cursor; should be followed by two characters the
first being the Y position, the second the X. Row and
column numbering starts at (32,32) which is the top left
ESC b foreground colour; should be followed by a character to
determine the colour, of which the four lowest bits are
used
ESC c background colour; similar to above
ESC d erase from beginning of display to the current position
ESC e enable cursor
ESC f disable cursor
ESC j save the current cursor position
ESC k restore a current position saved using ESC j
ESC l erase a line and put cursor at start of line
ESC o erase from start of line to cursor position
ESC p inverse video on
ESC q inverse video off
ESC v wrap around at end of line on
ESC w wrap around at end of line off
APPENDIX E
Converting from other Assemblers
Most 68000 assemblers for the ST follow, to one degree or another
the Motorola standard. While the instructions themselves are
thankfully standard, the syntax rules for labels, comments and
directives can, and do, vary. This Appendix covers the changes
most likely to be made when converting programs from another
assembler, whether they are your old source files or a program
listed in a magazine. It does not attempt to detail the
differences in user interfaces or options between the different
assemblers.
Atari MADMAC
GenST does not require colons after labels or comments to be
delimited with semi-colons, but it does not allow instructions or
directives to start in the label field.
The syntax and rules for local labels are the same, though $ and
? are not valid in GenST symbols. The use of \ in quoted strings
may have to be changed, and some arithmetic operators and
priorities are different.
MADMAC allows directives to start with dot, if these are removed
most directives are the same as GenST. Those that differ, and
their GenST equivalents are:
BSS=SECTION BSS, DATA=SECTION DATA, TEXT=SECTION TEXT,
ABS=OFFSET, ELSE=ELSEIF, ENDIF=ENDC, EXITM=MEXIT, GLOBL and
EXTERN=XREF or XDEF, EJECT=PAGE, TITLE=TTL, NLIST=NOLIST.
INIT can be converted to DC or DCB statements and CARGS can be
replaced with suitable RS directives.
MADMACs macro syntax is unique and its named parameters will need
conversion, equivalents for its parameters are \~=\@ and
\#=NARG.\? can be emulated using IFC or IFNC. The 6502 options of
MADMAC are not supported.
GST-ASM
GST labels are significant only to the first 8 characters and are
case insensitive so OPT C8- may be required. Its rules for
expression evaluation are very similar though $ is not allowed
within a GenST symbol.
Most directives are the same, those requiring name changes are
PAGEWID=LEN and PAGELEN=PLEN. Macro definitions will require
conversion as will GSTs unique form of local symbols.
Built-in functions and structure statements are not supported.
MCC Assembler
Very few changes are required, only the syntax for local labels
and add.L to XREF directives of absolutes.
K-SEKA
Colons are not required after labels in GenST though instructions
or directives that start in the label field will need a tab added
before them. Several Seka directives default to Byte instead of
Word sizes for some reason. Equivalent directives names are:
D=DC, BLK=DS, CODE=SECTION CODE, DATA=SECTION DATA, IF=IFNE,
ELSE=ELSEIF, ENDIF=ENDC.
Macro syntax requires ?s to be changed to \s, except ?0 which
should be replaced with \@.
Fast ASM
The syntax of Fast ASM was designed around GenST 1.2 so few
changes are required. Tokenised source files will need conversion
to ASCII (using the Clipboard) before attempting to load them
into the GenST editor. The main change involves comment
delimiters - Fast ASM lines starting with \ should be changed to
start with ø or ;-\s used after instructions will not require any
changes.
The floating point facilities in Fast ASM, left over from its
BASIC interpreter origins, are not supported in GenST.
APPENDIX F
BIBLIOGRAPHY
This bibliography contains our suggestions for further reading on
the subject of the 68000, the ST, and GEM. The views expressed
are our own and as with all reference books there is no
substitute for looking at the books in a good bookshop before
making a decision.
68000 Programming
M68000 Programmer's Reference Manual
Published by Prentice-Hall
The definitive guide to the instruction set produced by Motorola.
the supplied Pocket Guide is a subset of this book. Be sure to
get the latest version - at the time of writing the Fifth Edition
is the latest.
68000 Assembly Language Programming by Kane, Hawkins & Leventhal
Published by Osborne/McGraw-Hill
This is large (and expensive) but good, containing lots of
examples. Be sure to get the second edition. Not for complete
beginners to microprocessors.
68000 Tricks and Traps by Mike Morton
BYTE magazine, September 1986 issue
By far the best article on 68000 programming we have ever seen.
We wish there was a book like this.
ST Technical Manuals
GEM Programmer's Guide Volumes 1 & 2 - VDI and AES
By Digital Research
The definitive guide to the VDI and the AES, but marred by
mistakes and lack of 68000 details. Only available to registered
developers.
GEMDOS Specification by Digital Research
The definition of the GEMDOS calls. Only available to registered
developers.
A Hitchhikers Guide to the BIOS by Atari Corp
The definition of the BIOS and XBIOS calls, and corrections to
the GEMDOS manual. This is accurate, a good read and updated
regularly. Normally only available to developers.
The Anatomy of the Atari ST by Data Becker/Abacus
This book is the best documentation available for the user who is
not a registered developer. It describes the hardware and non-GEM
aspects of the operating system, including an (out-of-date) BIOS
listing. Thoroughly recommended, despite its inaccuracies.
GEM on the Atari ST by Data Becker/Abacus
This describes programming under GEM, though is not as complete
as the DR manual, but has similar errors. It describes calls
mainly from C, although there is more reference to the 68000 than
in the DR manual. Better than no book at all on GEM.
Concise Atari 68000 Programmer's Reference by Katherine Peel
Published by Glentop
An alternative to Atari ST internals. It contains information on
the ST's hardware, the operating system and GEM. Its coverage of
the various levels of the machine is comprehensive, though a
couple of sections are very inaccurate and some features are
described that simply don't exist. It is rather difficult to find
one's way around as the layout is based on large numbers of
tables and it lacks an index.
Tricks and Tips on the Atari St by Data Becker/Abacus
This contains a wide variety of material, including an accurate
description of the more esoteric ST BASIC commands, and good
sample listings including a RAM-disk driver and desk accessory.
M68000 Cross Macro Assembler Reference Manual
Published by Motorola (M68KXASM)
The official definition of 68000 assembly-language syntax on
which GenST is based.
M68000 Resident Structured Assembler Reference Manual
Published by Motorola (M68KMASM)
This details the more advanced aspects of the Motorola standard
including extended macros and 68010/20/881 processors.
APPENDIX G
TECHNICAL SUPPORT & UPGRADES
So that we can maintain the quality of our technical support
service we are detailing how to take best advantage of it. These
guidelines will make it easier for us to help you, fix bugs as
they get reported and save other users from having the same
problem. Technical support is available in three ways.
Phone our technical support hour is normally between 3 p.m. and
4 p.m. though non-European customers' calls will be
accepted at other times.
Post if sending a disk, please put your name & address on it.
BIXTM our username is (not surprisingly) hisoft. Would UK
customers please use more old fashioned methods; it's
cheaper for everyone.
Whichever method you use please always quote your serial number
(from your master disk) and the version number of the program. We
reserve the right to refuse technical support if you do not
supply this information.
For bug reports, please run the CHECKST.PRG program supplied and
quote the information given by it, as well as details of any desk
accessories and auto-folder programs in use. If you think you
have found a bug, try and create a small program that reproduces
the problem. It is always easier for us to answer your questions
if you send us a letter and, if the problem is with a particular
source file, enclose a copy on disk (which we will return).
Upgrades
As with all our products, DevpacST is undergoing continual
development and, periodically, new versions become available. We
make a small charge for upgrades, though if extensive additional
documentation is supplied the charge may be higher. All users who
return their registration cards will be notified of major
upgrades.
Suggestions
We welcome any comments or suggestions about out programs and, to
ensure we remember them, they should be made in writing.
DevpacST Developer Version
For those that require maximum power from their 68000 assembler
we have available the Developer version of Devpac ST. Features
over and above this version include:
GDOS is supplied together with documentation, sample program and
calling sequences; Motorola S record hex output and multiple-ORG
statements for users cross-developing; Amiga executable &
linkable file formats; 68010/20/30/881/882 instructions; Dual
machine debugging; Detailed notes on GST & DRI file formats
including special dump programs for both formats, source (in
HiSoft BASIC) included; Free upgrades for a year, despatched
automatically).
DevpacST Developer is available as an upgrade.
APPENDIX H
REVISION HISTORY
Product History
DevpacST 0.50 was first released in late 1985, but with various
restrictions to do with the editor and lack of linkable code. The
next major version was 0.91 which was much improved in many
respects, followed by 0.99f, the last version which didn't
produce linkable code. Version 1.0 was released in April 1986,
and underwent a few minor changes before the release of version
1.22 in June 1986, the first version supplied in a ring-bound
manual. After various small revisions the greatly improved
version 2.0 was released in April 1988.
Development Technique
DevpacST was originally based on DevpacQL, our Assembler
Development suite for the Sinclair QL. Both GenST and MonST were
written in assembler on the QL then uploaded via the serial port
into the ST, and LinkST was written using Lattice C on the ST.
Development moved across to the ST around version 1.24 which had
minor changes made, reaching version 1.26. Special internal
versions were written to experiment with things like linkable
code and extended debug and reached version 1.57 before both
GenST and MonST were completely re-written for version 2. The
editor was extensively altered, originally for HiSoft BASIC, then
Power BASIC, then GenST. The editor is written entirely in
assembly language.
Summary of Version 2 Improvements
This section is intended as a quick guide to the main additional
features for users who have upgraded from version 1.2 or
DevpacST. It gives an overview of the new features, for further
details you should consult the relevant sections of the new
manual.
The Editor
This has been greatly enhanced, with an overall improvement in
display speed being the most obvious. The editor supports lines
up to 240 characters in length, sideways scrolling as required.
It also works in low-resolution. There is now a horizontal scroll
bar and the workings of the vertical scroll bar is now more
"standard". By default the numeric pad is configured as an IBM-
style cursor cluster and the text editor. This, combined with the
saving of preferences, means the installation program in version
1 is redundant. Other programs can be run from within the editor
using the Run Other facility.
Block Deleter has changed to Shift-F5 from Shift-F3 (as fast
left-handed typists can generate the Shift-F3 scan-code in
ordinary typing) and now remembers the block, if possible,
allowing it to be pasted. A deleted line may be recalled as many
times as required. A block may be copied to the block buffer, and
marked blocks are now shown on screen. Our Saved! desk accessory
may be invoked at the press of a key, there is a keyboard
shortcut for Save, and the editor will now run in low-resolution.
The Assembler
Symbols are now significant to the first 127 characters and local
labels are supported. The INCBIN directive takes a straight
binary file and copies it into the output file, particularly
useful for screen data. Speed - include files are read only once,
memory permitting, and the binary file is buffered for as long as
possible. The absolute maximum speed has over doubled to 75,000
lines per minute though for real programs 35,000 lines is the
norm. The output file is also extensively buffered if possible
producing spectacular improvements during floppy-to-floppy
assemblies in particular.
General improvements in symbol table searching and hashing have
also increased overall speed. Extended Debug - a HiSoft extended
version of the DR symbol table, allowing debugging with up to 22
character significance. Macro calls and Includes may be nested as
deeply as memory allows. IFs can be 64K levels deep. TEXT, DATA &
BSS segments are properly supported when generating executable
code.
There is much greater control over output filenames. Multiple
Modules & Sections - the GST linker format is more fully
supported allowing multiple modules and multiple sections.
Externals may be used in expressions, with each other if
required. DRI linkable code can now be generated.
Optimising can now be performed by the assembler on things such
as short branches. Macros now support up to 36 parameters multi-
line calls and numeric substitution. The macro buffer is now
dynamic, the free space in the editor workspace is no longer used
for this. REPEAT loops are now allowed and the exprerssion
evaluator now includes comparisons. The REG directive allows
symbolic register lists. There are a considerable number of
extensions to the OPT directive. Octal numbers are supported.
Registers may also be called R0 through R15. A stand-alone
assembler is supplied for those who use alternate editors, CLIs
or batch files.
Compatibility Issues
Most source files should assemble with little or no changes. The
differences to be careful of are: BSS sections - neither RSBSS or
DSBSS are supported, the code should be converted to switch to
SECTION BSS then use DS statements. Symbols now default to case-
dependent and are significant to the first 127 characters. OPT N
for narrow listings has been superseded with the FORMAT directive
allowing much greater flexibility and general listing control has
been improved. The ORG statement has changed which will effect
any programs that use it.
HiSoft BASIC users - if creating libraries please note that GenST
2 output is not accepted by BUILDLIBs prior to version 1.4.
BRA.W wasn't accepted by version 1, forcing the use of BRA.L -
this is, strictly speaking, a 68020 instruction so now generates
a warning, BRA.W (and BRA.B) are now accepted. Various minor
changes have been made to the parsing of instructions allowing a
greater degree of flexibility. If you used (expressions)\W
(denoting short-word addressing) within a macro this will be
ignored as \W and \L refer to macro parameters and will probably
be replaced with nulls. Use instead (expression).W. which is the
Motorola standard.
The use of \W or \L after register equates used as index
registers is no longer required, for example if buf is a register
equate then move,b d0,0(a6,buf.l) is now allowed. Register
equates are now allowed in MOVEMs. The priority of the equality
operator (=) has been changed.
The GEM example program has been changed to use a true BSS
section and to fix a bug preventing correct operation under GDOS
- this and its include file can be found in the OLDGEM folder.
Many new example files are supplied including a desk accessory
and completely new AES and VDI libraries.
The assembler now reports syntactic errors on pass 1 and will not
start pass 2 if errors have been found. It now uses GEMDOS
character output routines so can be paused with Ctrl-S, resumed
with Ctrl-Q and aborted with Ctrl-C.
There are several new directives which could potentially clash
with macro names in GenST 1 source files. These are: COMMENT,
DCB, ELSEIF, ENDR, FORMAT, IIF, INCBIN, OFFSET, OUTPUT, REG,
REPT, RSSET, SUBTTL.
There are three reserved symbols which could theoretically clash
with your own, all starting with two underlines: __LK, __RS and
__G2.
Debugger
MonST supports a great number of new features including multiple
windows and, as a result, has a changed user interface. It is
strongly recommended that you read the Reference section of the
Chapter 4 before trying any serious work with the new version.
The main new features are: Multi-window display; Timed screen
switching removing flicker; Full expression evaluator including
indirection; Supports up to 22 significant characters in symbols;
Multi-resolution allows you to debug a low-res program in medium
res (or vice versa); Allows the viewing of source files within
the debugger; Disassemble to printer with automatic label
generation or to a disk file in GenST format; Conditional
breakpoints; History Buffer; Interrupt running programs.
Both GEM and TOS versions of the debugger are now the same except
for the file extension and one one auto-resident version needs to
be supplied.
Integration
Probably the greatest improvement to the package as a whole is
the integration between its various parts. The assembler is
available at the press of a key from the editor, as it was, but
so is the debugger. The assembler can assemble directly into
memory, then the code can be run from the editor without any disk
accesses. If required debugging information can also be included
in assembled-to-memory programs so they can be debugged at the
press of a key, directly from the editor. A program assembled to
memory is a true GEMDOS task so no code changes are required.
Assembly warnings and errors are remembered by the editor and can
be stepped through by pressing Alt-J. Errors are no longer lost
when the number of lines is changed, though they are not re-
calculated. After an assembly which had an error the editor will
automatically place the cursor on the line of the first error.
Linker
This now supports the HiSoft Extended Debug format and is faster
than its predecessors. It also allows explicit section ordering
and true BSS sections. Note that LinkST only supports the GST
format - if you wish to link DRI format code you need to use the
Atari ALN or the Digital Research LINK68 linkers.