z88dk-1.8.ds1/ 0000755 0001750 0001750 00000000000 10765235724 012517 5 ustar tygrys tygrys z88dk-1.8.ds1/amigabuild.sh 0000755 0001750 0001750 00000002240 07575171127 015153 0 ustar tygrys tygrys #!/bin/sh
#
#
# Bootstrap an amiga build from scratch, first build the unix system in
# situ
#
# Start from scratch
make clean
Z80_OZFILES=`pwd`/lib/
ZCCCFG=`pwd`/lib/config/
export Z80_OZFILES
export ZCCCFG
CC=gcc
CFLAGS="-g -O2"
CCOPT=-DUNIX
export CC
export CFLAGS
export CCOPT
PATH=`pwd`/bin:$PATH
export PATH
make -e
make -C `pwd`/libsrc
make -C `pwd`/libsrc install
# That's the unix part bootstrapped, now onto the Amiga
#CC="dcc -unixrc"
CC="m68k-amigaos-gcc -noixemul"
CFLAGS="-g -O2"
CCOPT=-DAMIGA
DESTDIR=`pwd`/amiga/bin
export CC
export CFLAGS
export CCOPT
make -C `pwd` -e amiga
cat > z88dk/bin/startzcc << EOD
; Set up of Z88DK for the Amiga
; 28/2/99 djm
; 26/4/99 djm Made Hopefully independent of where the thing is
; 8/12/02 djm Remove the annoying zlib: assign
;Root directory for everything - remember to change this if you move it!
assign zcc: /
;Path to executables!
path zcc:bin add
;Set some variables for z80asm (so it can find various files)
setenv Z80_OZFILES zcc:lib/
; Set the variable so ZCC knows where to find its config file
setenv ZCCCFG zcc:lib/config/
EOD
rm -fr `find z88dk -type d -name 'CVS'`
lha a z88dk-amiga-1.5.lha z88dk/
z88dk-1.8.ds1/build.sh 0000755 0001750 0001750 00000000524 10762270713 014150 0 ustar tygrys tygrys #!/bin/sh
#
#
# Build z88dk on unix systems
#
# Start from scratch
#make clean
mkdir bin
PATH=`pwd`/bin:$PATH
export PATH
Z80_OZFILES=`pwd`/lib/
ZCCCFG=`pwd`/lib/config/
export Z80_OZFILES
export ZCCCFG
CC=gcc
CFLAGS="-g -O2"
CCOPT=-DUNIX
export CC
export CFLAGS
export CCOPT
make -e
make -C `pwd`/libsrc
make -C `pwd`/libsrc install
z88dk-1.8.ds1/config.sh 0000755 0001750 0001750 00000000506 10637517564 014327 0 ustar tygrys tygrys #!/bin/sh
# Some script hackery to allow global installs
destdir=$1
default=$2
rm -f lib/config/*.cfg
for file in `ls lib/config/*.lnx`; do
dest=`echo $file | sed 's/\.lnx/\.cfg/g'`
sed "s?DESTDIR\/?$destdir?g" < $file > $dest
done
if [ x$default != x ]; then
cp lib/config/${default}.cfg lib/config/zcc.cfg
fi
z88dk-1.8.ds1/doc/ 0000755 0001750 0001750 00000000000 10765202715 013256 5 ustar tygrys tygrys z88dk-1.8.ds1/doc/apps.html 0000644 0001750 0001750 00000031020 07130401727 015077 0 ustar tygrys tygrys
Writing Z88 Applications
Writing Z88 Applications
Introduction
This document is under construction and hence might not make any
sense - if you want to create a Z88 application it's probably a good idea
to look in the examples/app/ directory to see how to do it
Lets be frank, unless you're Gunther (or some other deity) <grin>
writing DORs is not fun, in fact almost impossible first time, then once
you find a setup that works you constantly recycle the DOR for each
application. I've been there, done that, given up, asked for help, got it
and then recycled it, and here it is again in the kit!
One of the original aims of the Z88dk was to be able to create
applications simply and easily without having to go into the messy bits
of how to construct the DOR - simply give it your parameters and away
it goes and creates it without you having to know whats going on.
Well, I've finally implemented it, hopefully in a non messy way within
the limits the system, so read on, and find out how easy it is to create
applications with the z88dk.
How to do it
For the creation of applications two header files are important: dor.h and application.h - both of these need to be included in order to
construct the application DOR.
dor.h contains some constants for the application type and application.h
uses these constants to construct the DOR, hence they should be included
in this order. However! It's not as simple as that - application.h
needs some information from you such as application name etc - there
are defaults, but I don't think you'd want to use those!
The information is given courtesy of #define in between the including
of dor.h and application.h, you should define the following:
The information for the application help page, if HELP1 is not defined
then the standard HELP page is used <grin>, if any of the others (HELP2 to HELP6) is not defined then "" is substituted
#define APP_NAME "..."
The name of the application (as appears in the Index)
#define APP_KEY '[KEY]'
The hotkey for the application
#define APP_INFO "..."
The equivalent of *name from BASIC
#define APP_TYPE [constants or'd together as from dor.def]
The application type, if you don't define this then the default type
is bad with OZ preserving the screen (i.e. very, very bad!)
#define APP_TYPE2 [constants]
The application type byte 2 - specifies whether caps lock should be on
or not.
All of the constants above are in z80asm format - not C style, so insert
Z88 control sequences in the form ".." &blah &".." and not \[blah] or you
might get a bit of suprise!
Extra Features
As I said above, the default application type is bad and to let OZ
redraw the screen, this isn't particularly friendly as you can imagine so
you can turn off the redraw screen flag by #define APP_TYPE yourself,
this does however leave you with a bit of a problem - you won't
be able to redraw your screen, so, to this end, I've provided an facility for you to be able to do it - simply have a function called redrawscreen which is defined thus:
void __APPFUNC__ redrawscreen()
{
/* Put some code here */
}
The __APPFUNC__ flag causes the flag DEFINED_[function] to be written to
the zcc_opt.def file. This is then
picked up by the startup code and appropriate code is generated to call
this function - NB it won't automatically turn off OZ preservation of the
screen. This __APPFUNC__ call could be applied to other functions to
enable your code to take over error handling for example, however that
isn't supported at the moment.
For an example of this see the examples/app/dstar.c demo.
Menus and Topics
[Or whatever the name is!] In a fit of conscience and against my
better principles(!) I've implemented topics. They're fully implemented
except for help pages (maybe coming soon!). This is where things get
a little complicated, so listen up!
You are allowed up to 7 topics per application and 24 items within
each topic (if you ever fit this many into an app please let me know!)
you define a topic with #define TOPIC[num] "[name]". Each item under
a topic is named via #define TOPIC[num]_[item], it's hotkey by
#define TOP[num]_[item]KEY, code by #define TOPIC(...)CODE and its
attribute (see dev notes and dor,h) by #define TOPIC(...)ATTR. But thats
getting confusing, so have a look at the dstar.c example in examples/app
to see what I mean.
Each topic and each command on a topic may have a help page attached
to it, have a look at useless.c to see how it's done - remember don't
specify so much help that it goes over the 8k limit or all hell will
break loose (I'm sure you can live with that limitation!)
As an aside, topics also have an attribute byte, which can be defined
by #define TOPIC[num]ATTR. All attributes can be left out in which case
they default to 0.
In order to handle menu selections you should define a function
thus:
void __APPFUNC__ handlecmds(int code)
Where code is the command code that has been selected. If you don't
do this then you can't react to your menus!.
Bad, but not so bad Applications
If the amount of static variables used by your application is less
than 8k (the minimum amount of bad memory that can be allocated) then
give the flag -reqpag=num to the frontend where num is the number of
256 byte pages of bad memory required - the unused memory up to the 8k
limit is given back to OZ on pre-emption. To find out what num is for
your application look at the .opt/.asm file and search for DEFVARS and
count the number of bytes there. Sorry, there is no foolproof way to
do this automatically. For example the dstar.c program needs -reqpag=5
and rpn.c needs -reqpag=1. Remember that the startup code (maybe unnecessarily) reserves a byte at $2000 so add 1 to your variable count
before dividing by 256!
Good Applications
It should in theory be possible to write good applicatons with the
kit - simply don't use any static variables, supply the flag -reqpag=0
to the frontend and of course set the the appropriate APP_TYPE
I have placed all variables used by the startup code into safe workspace
area to allow this facility - I reserve 50 bytes which is more than
sufficient for our needs (we need 47 ATM) to allow for future
expansion.
[Untested feature!!] If you're feeling particularly cocky, you can
write good apps that have static variables...as long as you don't have
too many of them that is. You can specify the flag -safedata=[n bytes]
where n is the amount of static data that you want, this space is
taken from the safe workspace, which remember is also shared by the
stack, mail and other such things. A suppose a safe limit would be in
the region of 500 bytes or so, but experiment, if you don't have
arrays of local variables and no recursion you might be able to get away
with more, as the saying goes, your mileage may vary!!
Changing the origin of the application
The default origin for an application is 49152 - this should give you
plenty of space to do whatever you like, however, perhaps you want to
slot it in elsewhere in an eprom - in this case use the -zorg= flag.
NB. The application DOR created assumes that it is located in top top
bank (63) of an EPROM cartridge, so unless you have a large application
don't relocate it to < 49152 [This is to ensure that the application
entry point is in segment 3 - the DOR contains a dummy startup which
then jumps to the real start address.]
Using a Near Heap
Until the far routines and code are working properly it is possible
to write applications which use the same malloc functions as for BASIC,
however please define your heapsize thus (or strange things will happen!):
#include <malloc.h>
#define HPSIZE [size]
HEAPSIZE(HPSIZE)
#pragma set HEAPSIZE HPSIZE
#pragma set is a synonym for #define that gets passed through to the
compiler (as opposed to being expanded out by the preprocessoe). When the
time comes to write the zcc_opt.def file the compiler looks for the
#define HEAPSIZE divides by 256 (for the number of pages) adds it to 32
(mininum size of bad memory) and writes this value to the zcc_opt.def file,
this allows the DOR to be created requesting the correct amount of bad
memory.
However, this can be a bit wasteful to say the least, say you only
had 50 bytes of static variables and an 8k heap, the application would
request 16k of bad memory when in fact it only needs 8448 bytes (to the
nearest 256 byte page), so in this case supply the parameter -reqpag=33
and only 8448 bytes will be requested - smart eh?
Eventually the -reqpag= will enable unused memory in the 8k default
bad memory to be returned to the system upon suspension, however in order
to this elegantly and without too much unwieldy code this requires a
couple of modifications to z80asm so that IF statements can evaluate
expressions, since this mod hasn't be made yet, this feature isn't
enabled - the compiler will reject any parameter which is less than 32 (and isn't 0
Sending/receiving mail
I've now implemented functions to allow passing and sending of mail
between functions, the two functions are called: readmail and sendmail and
both have the prototype (char *type, far char *info, int length). Don't
worry about the far char * type - a near pointer (eg for local variables)
is automatically extended to far when needed. For an example of the usage
of readmail look at examples/app/viewer.c which is a simple text viewer
which accepts the NAME type so to use it, select a file from the filer
and switch to to the Textview popdown.
NB. To save heartache from typos (I'm a fine one to talk!) in the z88.h
header file I've defined the two OZ supported mail types, these are
FILEMAIL and DATEMAIL, use these instead of typing the character string
yourself!
The program appmake
This is a quick knock up of a program which will generate bank images
from an application binary - it creates the ROM header and the front DOR
as appropriate, call it from the frontend using the -create-app flag at
the same time as compile time. Internally it callocs 64k and then loads
the appropriate addresses with the necessary information. It obtains
information about the application from the z88_crt0.map and z88_crt0.sym
files and as such should not be run alone.
The algorithm used to generate a Card ID is based on the time()
function, I don't know whether this will be sufficient to guarantee
exclusive-ness, but hopefully it will be sufficient - does anyone have
a better algorithm for thus - rand() is useless since it isn't random -
i.e. given the same seed it will of course generate the same random
number - (It seem that picking up ROM values via the r register on the
Z80 is more random!)
A few precautionary notes
Due to a small feechure in z80asm which causes DEFVARS -1 to be
incorrectly resolved when linking object files, all assembling takes
place at one time, this means that the -a flag is ineffective, and is
equivalent to -c when the -create-app flag is supplied. So, as a result
don't compile to object files then link - you'll trash the lower memory
of the Z88! [Been there, done that!]
In summary
To create an application supply the following command line to zcc:
After of course including dor.h and application.h in your application.
The two flags -create-app and -make-app are needed so that the compiler
doesn't become to specifically Z88 orientated - other Z80 machines might
require different flags to the compiler in order to create a different
type of executable, this way thinks are quite transparent and the zcc.cfg
file doesn't become even more overloaded!!
If you wish to use graphic functions then you have to supply the
application graphics library which is -lgfxapp - this pages the graphics
page into the 16384 segment instead of the 49152 segment - I've taken
the needed routines from standard.lib and placed them in gfx[app].lib due
to a label clash with some of the standard.lib routines.
Enjoy making applications with Z88dk.
dom 10.4.99
z88dk-1.8.ds1/doc/compile.txt 0000644 0001750 0001750 00000013301 07346211434 015444 0 ustar tygrys tygrys $Id: compile.txt,v 1.2 2001/09/07 18:34:04 dom Exp $
-------------------------------------------------------------------------------
Compiling with the z88dk ; By Henk Poley ; 05-jun-2001
-------------------------------------------------------------------------------
general compilation command:
zcc [flags] file(s)
[+..]
- Config file to load (must be the first argument)
zcc.cfg is used by default. See below for the arguments.
[-startup=..]
- Startup header to use (see other docs for more information)
[-l..]
- Link this library (see below and in zcc.html)
[-o..]
- Binary output file (standard a.bin)
file(s)
- File(s) to compile
Controlling steps of the compilation process:
[-E]
- Preprocess files only, leave output in .i file
[-a]
- Produce .asm (or .opt) file only (aka don't assemble)
[-c]
- Do not link object files
[-make-lib]
- Shortcut to generate .o files from library .c files
[-m]
- Generate .map files when assembling/linking
(When compiling libs)
Options to control the type code produced:
[-O[0,1,2,3]]
- Optimize compiler output (to .opt file)
Can be either 0 (none) 1,2,3, level 2 is recommended. Level 3 is
suitable for large programs (includes certain lib functions to
reduce size of code(!))
[-cc]
- Intersperse C code as comments in the assembler output,
WARNING: this *will* clobber some optimizations.
Options to control compiler functions:
[-unsigned]
- Implicitly define everything as unsigned unless explicitly told otherwise.
(will optimize much better)
[-smartpf]
- Intelligent printf routine handling (see zcc.html for more info)
[-no-smartpf]
- Turn off the intelligent printf handling
Z88 specific:
[-create-app]
- Create an application image (i.e. bank 63,62 etc)
[-make-app]
- (App) Notify the compiler that you're trying to make an application
[-reqpag=..]
- (App) Number of 256 byte pages required for bad application
[-zorg=..]
- (App) Origin for a Z88 application
[-safedata=..]
- (App) Amount of safedata required by your code
[-defvars=..]
- (App) Where static variables should be dropped (only valid for single
file compilations, but see later)
[-expandz88]
- (App) Expanded z88 required
[-no-expandz88]
- (App) Expanded z88 not required (these two flags toggle some startup
code to check for an expanded machine)
[-startup=3]
- Produce standalone code that can be run from a set address from BASIC.
Use -zorg= to change the address
[-R]
- (Use with above) produces relocatable code that can be loaded into
a DIM'd BASIC array.
[-stackoffset]
- Sets the stack offset for shared libs (see package.txt for details)
Miscellaneous options:
[-v]
- Verbose - echo commands as they are executed
[-vn]
- Don't be verbose
[-Wall]
- Turn on all the compiler warnings
[-Wnone]
- Turn off all compiler warnings
[-Wn[num]]
- Turn off the compiler warning [num]
[-W[num]]
- Turn on the compiler warning [num]
[-z80-verb]
- Allow z80asm to be verbose, this tends to generate a lot of output to
the screen so may not be desired.
[-asxx]
- Cause the compiler to emit asxx compatible code
[-Cp..]
- Pass an option through to the pre-processor
[-Ca..]
- Pass an option through to the assembler
[-D, -I, -U]
- are passed through to the preprocessor.
Any unrecognised options are passed through to the compiler (to allow
for improvements in the future.)
-------------------------------------------------------------------------------
[+..]
abc80 (ABC80)
aceansi (Jupiter ACE, using VT-ANSI engine)
cpm (CP/M)
msx (MSX 1)
mz (Sharp MZ)
mzansi (Sharp MZ, using VT-ANSI)
nc (Amstrad NC100)
rex (REX 6000)
sam (Sam Coupe)
svi (Spectravideo SVI)
m5 (SORD M5)
ti82 (Ti82, using ROM text routines)
ti82ansi (Ti82, using VT-ANSI)
ti83 (Ti83 ...)
ti83ansi (Ti83 ...)
ti85 (Ti85 ...)
ti85ansi (Ti85 ...)
ti86 (Ti86 ...)
ti86ansi (Ti86 ...)
ti8x (Ti83+ ...)
[ti8xansi] (Ti83+ ...)
vz (VZ / Laser 200)
vzansi (VZ / Laser 200, using VT-ANSI)
z88 (Cambridge Z88)
z88ansi (Cambridge Z88, using VT-ANSI)
z88net (Cambridge Z88 with TCP/IP)
zx (ZX Spectrum)
zx81 (ZX 81)
zx81ansi (ZX 81, using VT-ANSI)
zxansi (ZX Spectrum, using VT-ANSI)
-------------------------------------------------------------------------------
[-startup=..]
See other documentation to learn what -startup is used for.
Like:
Ti.txt Compiling for the Ti82, Ti83(+), Ti85 and Ti86
-------------------------------------------------------------------------------
[-l..]
farz88 (Z88 far support)
gfx (Z88 BASIC graphics lib)
gfxapp (Z88 application graphics lib)
m (Generic math routines)
malloc (Generic near malloc routine)
mz (OZ's math routines)
ndos (Fake file-routines, return errors only)
net (Z88 socket routines for ZSock)
netdev (Z88 socket routines for devices)
p3 (+3 file support library)
tigray82 (Ti82 graylib routines)
tigray83 (Ti83 ...)
tigray83p (Ti83+ ...)
tigray85 (Ti85 ...)
tigray86 (Ti86 ...)
z88 (Some Z88 application routines, like mailboxing)
z88dk-1.8.ds1/doc/copt.man 0000644 0001750 0001750 00000004467 07130401727 014727 0 ustar tygrys tygrys
copt(1) copt(1)
NNAAMMEE
copt - peephole optimizer
SSYYNNOOPPSSIISS
ccoopptt _f_i_l_e ...
DDEESSCCRRIIPPTTIIOONN
_c_o_p_t is a general-purpose peephole optimizer. It reads
code from its standard input and writes an improved ver-
sion to its standard output. _c_o_p_t reads the named files
for its optimizations, which are encoded as follows:
...
=
...
Pattern matching uses literal string comparison, with one
exception: ``%%'' matches the ``%'' character, and ``%''
followed by a digit matches everything up to the next
occurrence of the next pattern character, though all
occurrences of %_n must denote the same string. For exam-
ple, the pattern ``%1=%1.'' matches exactly those strings
that begin with a string X, followed by a ``='' (the
first), followed by a second occurrence of X, followed by
a period. In this way, the input/output pattern
mov $%1,r%2
mov *r%2,r%2
=
mov %1,r%2
commands _c_o_p_t to replace runs like
mov $_a,r3
mov *r3,r3
with
mov _a,r3
Note that a tab or newline can terminate a %_n variable.
_c_o_p_t compares each run of input patterns with the current
input instruction and its predecessors. If no match is
found, it advances to the next input instruction and tries
again. Otherwise, it replaces the input instructions with
the corresponding output patterns, pattern variables
instantiated, and resumes its search with the _f_i_r_s_t
instruction of the replacement. _c_o_p_t matches input pat-
terns in reverse order to cascade optimizations without
backing up.
BBUUGGSS
Errors in optimization files are always possible.
1
z88dk-1.8.ds1/doc/cpc.txt 0000644 0001750 0001750 00000004065 07731051412 014564 0 ustar tygrys tygrys Notes on the CPC target
=======================
Loading Addresses
-----------------
The code is compiled to address $6000 (24576), to run the code on a CPC you
should do the following:
MEMORY &5fff
load "[filename]",&6000
call &6000
Floating Point Support
----------------------
The CPC target supports a native maths library, this is selected using the
-lmz switch when compiling.
The library that is linked in by default supports 3 models of CPC - CPC464,
CPC664 and CPC6128. Should memory be in short supply and you wish to compile
for a specific CPC then you can do the following:
zcc +cpc [...] -lmz -l6128_math
or -l664_math or -l664_math which will save about 600 bytes of memory.
The native CPC library supports some additional functions, these are:
void deg();
Switch the FP engine into degrees mode
void rad();
Switch the FP engine into radians mode
double pi();
Return the value of pi.
double pow10(int x);
Returns 10^x
File IO Library
---------------
Support for file IO on the CPC has been added. This uses the CAS_ interface
and as such as the limitation that only 2 files may be open at a time -
one for reading and one for writing. In addition due to the firmware
implementation of these routines, a 2k buffer is required for both input
and output. This buffer is statically built into the program.
The following routines are not supported by the CPC fcntl library:
ftell()
fgetpos()
fsetpos()
rewind()
fseek()
creat()
lseek()
mkdir()
getcwd()
rmdir()
getwd()
Additionally, open() only supports the O_RDONLY and O_WRONLY flags.
To link in the library supply the -lcpcfs flag to the compiler. If you do
not require file IO in your program then supply the -lndos flag which
links in a dummy stub library that simply returns errors.
Application Creation
--------------------
The appmake has been updated to support the CPC as a target. When compiling
if you supply the -create-app flag then a file with the suffix .cpc is
generated. This file contains a CPC disc file header which can then be
easily transferred onto a CPC disc using cpcfs or a similar tool.
z88dk-1.8.ds1/doc/dstar.gif 0000644 0001750 0001750 00000003317 07130401726 015061 0 ustar tygrys tygrys GIF87a , I8ͻ`(di%"R/:·,`0Fl18tɤңp%EdR͘j7ݸ3n=[f]7/ibwnlswXop}=S'{MnsXZU8Vb4`)Sg[FK#(ǀ̵}~ҡiQ5eTޒfЗͲ?u걜jkf`== %
dlv_@UB\wxhW8>_2:%5 ͚/s2T!@ *h*\%W!Kx4#rdV_`Ê K2! f)PRF,fDJl^j(H^# <;7 } nx%֘sM&~[l XX(ڄ0lQhEűV5j ? Ea
rwveWaTwP8!@`q`G>]| VR:$DXȣtGwؗydihlp)tix|矀*蠄j衈&袌6裐F*餔Vj饘f馜v駠*ꨤjꩨꪬ䠟3}jg뮺*+%xV"ǞXl=+7N쐚&˶Uv/~+neeq9ˮFWk/KNR l0 p y[1 o1 j2mk,,. ̠kÞg4 o6VR?gYq.z)/ˣȩQͯ5GY -r#2f H[$%7FuG|w'\rprY-ObtϑZwyN6]W*固gÍx-sͤbzCnyuMsg{x
/O4O;!N1_:+.z졓7ʳ\==6HnG۞Ktsox?֒rg; ؼU.kFYASw "J{ p[4ԅAp}r\ǿ_ [aH
Ã4`8(u. 9 @ zA4
N%3aC]SPXG@fFpj|@Cq+:Q{ '|! %-un d/ +I"$Y1Ʀ-# C0y䤉I)- 7"oC$)q^ϗuxb:pD191fkl վL)&Mi[I9}ӓD
Nqs# 0y'6g}2X@'VfaB P:pER F z
HGJҒ(MJWҖ0LgJӚ8ͩNwӞ@
PJԢHMRԦ:PTJժZXͪVծz`
XJֲhMZֶp\皖RD ; z88dk-1.8.ds1/doc/embedded.txt 0000644 0001750 0001750 00000001055 07553527756 015571 0 ustar tygrys tygrys The embedded target (+embedded) has been supplied by Daniel Wallner and targets
his Z80 core http://www.opencores.org/projects/t80/.
"Console" Input and output is provided by a 16450 UART.
It is important to initialise the UART at the start of your program, eg:
#include
#include "ns16450.h"
int main()
{
init_uart(0,1);
printf("Hello world!");
}
Floating point is supported by this port, and some example are given in
examples/embedded (NB. Many of these examples could be made to work
on other z88dk targets with the minimum of hassle)
z88dk-1.8.ds1/doc/enigma.gif 0000644 0001750 0001750 00000001361 07130401726 015201 0 ustar tygrys tygrys GIF87a , I8ͻ`(diRHrȉ&# _6Jy5
?8юA&-'eU[#p:\^c;7O)᳥F{}e0klK^uUɊmaм݆.7ޱQխXr\
5_Z8Crf B3㻈0JTⵌqh7= Sj!c8tɳϟ@
J' ?OSJWѫhjxfJIkQ`|i'4sԬ]Gp6}*aߓݽvd Y*lE;]ќ9q\_C MӨS^ͺװc˞M۸sͻ Nȓ+_μУKNسkνË Oӫ_Ͼ˟OϿ (h& 6F(Vhf v ($h(,0(4h8<@)DiH&L6PF)TViXf\v`)dihlp)tix|矀*蠄f ; z88dk-1.8.ds1/doc/error.txt 0000644 0001750 0001750 00000015437 07130401726 015155 0 ustar tygrys tygrys
Errors and Warnings Produced by the Small C+ Compiler
-----------------------------------------------------
[Document under construction]
The compiler has two ways of letting you know if something is either
potentially, or is actually wrong with your code.
To let you know of potential problems, or problems that it can usually
overcome the compiler will emit a warning, if the problem is more serious
and the compiler cannot overcome it an error will be emitted. The line
between these two is fairly fuzzy, but given time (and this document!) I
hope you'll discover what is important and what isn't.
WARNINGS
--------
#1 Too few arguments in function
#2 Too many arguments in function call
#3 Too many arguments in declaration
Potentially a very big problem - have you remembered to prototype
correctly?
#4 Function returns different type to prototype
#5 Prototype is %s
#6 Function is %s
These three warnings come together, another prototyping problem perhaps? Or
have you called a function which doesn't return an int before declaring
it?
#7 Return type defaults to int
This annoying can be very warning, to get round it explicitly say what
your return type is during function declaration - old Small C programs
will kick up loads of these.
#8 Converting integer to pointer without cast
#9 Converting pointer to integer without cast
"Does exactly what is says on the can"
#10 Equating of different signedness
#11 Operation on different signedness!
Both of these are a sign that there may be trouble ahead - be careful
with your signedness!
#12 Converting far ptr to near ptr
Uh-oh, you *really* don't want to do this, information is lost and the
pointer could end up being wild, you can get rid of it using a cast
but are you really sure you want to do that?
#13 Pointer/pointer type mismatch
This occurs during functions calls if your pointer types aren't matched
up - eg your function needs a pointer to int and you're supplying pointer
to char - do take care!
#14 Expected ','
#15 Expected '"'
#16 Expected ''' (single ')
#17 Expected ';'
The last one isn't fatal, but the others possible are.
#18 Unterminated assembler code
Bung a #endasm in where it should've been in the first place!
#19 Unknown #pragma directive
You've either made a typo, or just ported some code across.
#20 Far only applicable to pointers
There's no such thing as a far [blah] it doesn't make sense, you have
to point to any far data.
#21 Initialisation too long, truncating!
This is caused by supplying a string which is too long during definition
of a character array with a finite size.
#22 Bad variable declaration (void)
Duh.
#23 Static incompatible with register/auto
What exactly did you mean here?
#24 Cannot assign value to pointer
This arrives during global initialisation - 0 is the only value to
which you can assign a pointer to [During code anything goes, so maybe
you want to try it then]
#25 Illegal size of operation (on function)
#26 Expected argument
#27 Int constant in double expression
#28 Getting value from void function
I like explanatory error messages!
#29 Compiler bug - code may not work properly
#30 Fix soon hopefully! Next warning may be dubious!
These should probably be disabled now - the code generated is perfectly
fine - this is caused prompted by the address operator on an array in
a struct accessed via a pointer (well, that's the only instance that
I've found of it..)
#31 Bitfields not supported by compiler
Nice try They're parsed correctly but just default to ints instead
of bits within an int - it's not worth implementing them IMHO - the
space saved in storage is more than cancelled out than the code that
would be required to handle them.
#32 Division by zero, result set to be zero
The code produced here isn't optimal, but the optimizer does its best to
remove any wastage - check your code!
#33 Call to function without prototype
Do yerself a favour and prototype!
#34 Func expects: %s"
#35 Func gets: %s"
#36 In function: %s() line %d"
#37 Typedef doesn't support pointer types (sorry!)
I am a lazy programmer! In theory typedef could support pointer types
with no additional strain, however it's easier just to barf the warning
at this point. Code is correctly parsed, but any use of the typedef
results in use of the fundamental only.
Various messages which provide further information..
ERRORS
------
#1 Unexpected end of file FATAL
#2 Can't open zcc_opt.def file FATAL
zcc_opt.def is a key file to the entire system - it's written to by
the compiler to give instructions for assemble and linktime.
#3 Can't nest include files FATAL
#4 Can't open include file FATAL
The built in pre-processor is in a word crap, you should never see
these messages if you use the frontend
#4 Input line too long
Wow, that is an impressive macro - the line buffer is 1k!
#5 Output file error FATAL
Is your disc write protected?
#6 Double literal space exhausted FATAL
#7 Literal Queue Overflow FATAL
#8 Staging buffer overflow FATAL
#9 Macro table full FATAL
#10 Global symbol table overflow FATAL
#11 Local symbol table overflow FATAL
#12 Structure member table overflow FATAL
#13 Structure symbol table overflow FATAL
You trying to compile emacs or sommat? Your program is too big - split
it up into little chunks!
#14 Indirection too deep FATAL
Pointers to pointers to arrays are not permitted!
#15 Negative Size Illegal
An array definition with a negative index?
#16 Not in switch
#17 Too many cases
#18 Multiple defaults
#19 Too many active whiles FATAL
#20 Out of context
#21 Must assign to char pointer or array
#22 Dodgy declaration (not pointer)
Initialising a global pointer to function with a non pointer
#23 Can't declare within switch FATAL
#24 Must declare at start of block FATAL
#25 Illegal Function or Declaration
#26 Missing Open Parenthesis
#27 Illegal Argument Name: %s
#28 Incorrect number of arguments
#29 Expected arguments
#30 Out of data for struct initial.. FATAL
#31 Already defined
#32 Must be lvalue FATAL
#33 Illegal address,
#34 Can't subscript
#35 Can't take member FATAL
#36 Unknown member FATAL
#37 Unknown struct FATAL
#38 Illegal symbol name
#39 Missing closing bracket
#40 Missing token: %s
#41 Unknown symbol: %s
#42 Argument mismatch %s() Arg #%d: %s
#43 Doesn't match original decl type: %s
#44 Missing token, expecting %c got %c
#45 Invalid Exponent
#46 Floating Overflow
#47 Invalid expression
#48 Can't dereference
#49 Operands must be int
#50 Expecting constant expression
#51 Enum name already used by another symbol
#52 No matching #if
z88dk-1.8.ds1/doc/faq.html 0000644 0001750 0001750 00000007271 07130401726 014715 0 ustar tygrys tygrys
Answers to some (not so) Frequently Asked Questions
z88dk is a complete programming package originally designed to produce
programs for the Cambridge Computers Ltd z88 computer. The z88 is a z80a
based machine and was Sir Clive Sinclairs first (and last..) computer
after selling Sinclair Research to Amstrad, for more details on the z88 see
Z88
Forever
The package consists of a Small C+ compiler (much extended), a peephole
optimizer an integrated assembler/linker and a front end to drive it all.
There's also an additional support program to facilitate the easy building
of z88 applications
The kit an be easily retargetted for other z80 based machines - in
5 minutes I had created some simple code to allow Spectrum programs
to be produced.
Why bother with C
Well, for almost as long as I can remember people on c.s.s. have been
going on about a C compiler, but no one has ever done anything about it
(with the exception of John Elliot who created a wrapper for Hitech C),
but that's not what this section is about....why bother with C..well:
Complex expressions can be easily and quickly written
Code can be easily ported from other machines
Your code is now portable across platforms
It's just quicker to write than the equivalent assembler
And lots of other reasons, I'm not going to lie, the code will be larger
than hand coded assembler, but it will be so much easier to maintain, and
will take far less time to write that it is worth it! [Not that I'm
biased!]
I've discovered this bug...
Good! There's bound to be some, but are you sure it's not in your
code? If not then test without optimization (use -O0) and it's still
there try to isolate where it goes wrong - is it in the generated code, or
is it in a library function? Let me know by sending me the C source, the
assembler output and the optimizer output, and point out where it's
going wrong as well. If it's in a library routine, can you come up with
a fix for it?
Basically, if you've found a bug make sure you can reproduce it - how
does it occur - does it pop up in any other place? Send me examples of it
and it at all possible send me a fix! Basically send me as much information
as you can.
On the other hand, if it's a bug in the assembler then read the z80asm.txt file in the doc directory for more details as to what to do with it!
I can't compile the examples
Only one thing to say here - are you supply the correct libraries?
Anything that uses floating point needs to be linked with -lm (generic) for maths support. For the z88, anything that uses graphics
needs to be linked with -lgfx. The README in each examples program tells
you how to compile them.
How do I access memory directly
The compiler, sccz80, offers you several ways of accessing memory
directly - you can cast a constant to a pointer to type and then dereference it (eg *(char *) 40000) or you can use the "external pointer" data type which is detailed in the main doc file.
z88dk-1.8.ds1/doc/far.html 0000644 0001750 0001750 00000011414 07130401726 014710 0 ustar tygrys tygrys
Extended Memory Access for the Small C+ Compiler
More than 64k?
The Z80 processor is an old processor, and it's based on an even older
one - the Intel 8080. These two processors are 8 bit accumulator based and
can access an address space of 65536 bytes (or 64k).
Quite early on it was realised that this simply isn't enough address
space to implement a comprehensive operating system and leave sufficient user RAM for their own programs.
The solution to this is quite straightforward, have more ROM/RAM in the
system and page it in when required. This trick isn't just used on the Z80
but also for the 6500 series of processors from Motorola.
However, this isn't going to be a lecture on memory models and computer
architecture (I'd end up in hot water for what I'd say, and probably will
even for that small bit just there!) - it's a description of how the Small
C+ compiler can access more than 64k and whats still left to do!
The far pointers used by Small C+ are 24 bits long i.e. 3 bytes, this
enables the theoretical access of 16Mb of memory (if your program
requires more than this then please tell me what you're trying to do on
a Z80!). The far pointer allows for a flat memory model - i.e. they
are treated as "normal" 24 bit number by the compiler.
Before I begin I should like to point out the for Small C+ far pointers
are stored in the registers ehl where e contains bits 16-23 and hl bits
0-15 of the pointer. If e holds 0 then hl is taken to be an absolute
address in the current memory configuration.
For this concept to work, it will be necessary to create an extremely
well designed memory allocation system which will have to present in all
programs that use far pointers.
Thus initially we need a malloc routine would far the prototype:
far *malloc(long)
Which would take a four byte integer, reserve this much space in the
system, and return a pointer which would consist effectively of a memory
pool number in e and 0 in hl. If enough space couldn't be reserved it
should return with ehl=0.
Internally however it would have to create a memory pool within the Z88
and extend this until the size is that wished by the user. In returning a
pointer in ehl it should internally bind whatever e is to the system memory
pool (this maybe via a look up table or some other method) so that whenever
access to the pool e is requested it can be calculated where exactly offset
hl actually is.
I should obviously mention free which will free the memory pool e and
deallocate all memory reserved by malloc. In addition to this there should
be a cleanup function which will deallocate all the memory in all the
memory pools. (This is an internal function and will be used by the
startup code to clean up on exit of the program - and hence avoid leakage).
All access to the memory pools at C-level will be via a set of functions to read and write various types, which will now be described with entry
parameters and projected exit conditions:
Reading routines, all these have entry ehl = memory pool address
lp_gchar - read char
Exit: a=l = byte at that location
h=0
This routine should not bother with signedness - the compiler will sort
this out
lp_gint - read 2 byte integer
Exit: hl = word at that location (stored little endian)
lp_gptr
Exit: ehl = far pointer at that location
lp_glong - read 4 byte integer
Exit: dehl = long at that location (l=LSB)
lp_gdoub - read 6 byte double
Exit: Load FA -> FA+5 with the double stored at that location
FA -> FA+5 are 6 bytes presently located in the startup code, but will
be relocated to the bad memory for applications. This routine may require
some thought - there is a routine in the float package to place bcixde into
the FA area.
Writing routines, all these have entry e'h'l' = memory pool address and the following additional entry parameters:
lp_pchar - write char
Entry: l = byte to write
lp_pint - write 2 byte integer
Entry: hl = word to write
lp_pptr - write far pointer
Entry: ehl = far pointer to write
lp_plong - write 4 byte integer
Entry: dehl = long to write
lp_pdoub - write double
Entry: none
This routine will write the bytes stored in FA -> FA+5 to the memory
pool address, once again this may require some thought.
These routines have now been written by Garry Lancaster for the z88
and so this document is just hanging around should someone feel like
writing routines for other machines.
Dom 16/4/2000
z88dk-1.8.ds1/doc/farmods.txt 0000644 0001750 0001750 00000002150 07130401727 015444 0 ustar tygrys tygrys The addition of working far pointers has neccessitated a few changes in
the z88 library - a few routines have lost their far ability (though
since they weren't used with this in the first place this is no loss), these
routines are:
readmail
sendmail
remove
In contrast, fopen/open/wcopen now fully understand far pointers for a filename
specification and will not blink if you supply one. This is achieved by copying
the string down into near memory and rewriting the address supplied to the
gn_opf routine so that it points to this near copy. This approach is taken (as
opposed to rewriting a C far ptr to and OZ far ptr due to the fact that a string
may in actual fact be spread across any number of pages or banks. This happens
tranparently and you have no need to worry about it.
Should you wish to write library routines which utilise far pointers take
a look at open_z88 in fcntl/z88 which is a commented implementation.
It should be noted that since far data cannot be used with BASIC programs
for a basic program fopen etc do not comprehend far pointers and the chances
are that the opening the file would fail.
z88dk-1.8.ds1/doc/farz88.html 0000644 0001750 0001750 00000022223 07130401727 015263 0 ustar tygrys tygrys
Z88 Far Memory access with z88dk
Z88 Far Memory
Far memory routines have now been implemented in z88dk
for the Z88. This document describes how you can write C programs using
these routines, and also gives details of how the scheme is implemented
for anyone interested.
The document is divided into the following sections:
The Z88 far memory model used by the Z88 Development Kit uses
a 3-byte far pointer size. Near pointers can easily be cast as far pointers,
so it is easy to write programs using a mixture of near and far memory. It
is obviously not possible to cast far pointers as near
pointers, however.
There is no limit to the size of the far memory heap (other than the 4Mb
limit imposed by the Z88 architecture!), and allocations of any size can be
made, provided your heap is large enough and the host Z88 has sufficient RAM
available. Very large heaps will require more of your bad application
RAM to be reserved for memory management, however, and full details of
this are given in the next section.
The far memory model is only supported by the application
target type in Small C; so it is not possible to write programs running
under BASIC using far data. Due to the memory overheads required by the
allocation routines (see implementation details if
you're interested), any application which uses this model will be
bad.
Packages may use far pointers as parameters passed to them by applications,
but since each application has its own far heap managed through its static
workspace, the following limitations apply:
the far pointer may only be used while the process to which it belongs is
active
far pointers may not be passed from one process to another
Using the far memory allocation words in your Z88 applications is quite
straightforward. Firstly, you must signal that you will be using the far
memory functions with the following line:
#define FARDATA 1
This line should be before any includes, as the standard library
header files use it to determine whether to make far memory versions of
the library functions available.
Secondly, specify the size of the far heap your application requires
with a line as follows:
#pragma -farheap=65536
The above line gives a heapsize of 64K. You can specify any size up to
a maximum of 4194304 (4Mb). Bear in mind the following points:
memory is not actually reserved in the Z88 until it is allocated with
the malloc function, so you can specify a large heapsize without
worrying that your application is "wasting" large amounts of the Z88s
memory
the amount of bad application memory (or static workspace) required
by the allocation system is equal to (HEAPSIZE/128)+487 bytes,
where HEAPSIZE is the maximum heap size in bytes
For example, if you have a maximum heapsize of 65536 bytes, the amount of
static workspace used will be 999 bytes. A 4Mb heap would require about 32.5K
of static workspace!
Allocating and using far memory
Within your C application, you can now use the following functions:
far *malloc(long size)
Returns a far pointer to a region of memory "size" bytes in size
void free(far *ptr)
Free the previously allocated region of memory at "ptr"
void freeall(void)
Frees all allocated memory (this is done automatically when applications
are terminated)
You can use various string functions on far memory pointers; where functions
take two parameters, you can also provide near pointers as parameters (remembering
to cast them as far!) The following functions are currently available for
far pointers: strchr, strrchr, strcpy, strncpy, strcat, strncat,
strlen, strlwr, strupr.
For more information, take a look at the example in examples/app/farmall/.
Knowledge of the way far memory is implemented on the Z88 may be helpful to
anyone wishing to write a similar library for another machine, or for those
hoping to port the method to their own (non-C) environment.
Also, if you are planning to rewrite the Z88 operating system (!) or replace
any of the memory-allocation calls using the pkg_ozcr call, you should take
careful note of the assumptions I have made here, and try not to break them ;-)
Note that all the assumptions made below are true for all versions of OZ up to
and including v4.0
Memory overheads
Whenever far memory support is required in an application, a certain amount of
bad application workspace is automatically reserved. This consists of:
pool_table (224 bytes)
Used to hold memory pool handles allocated by OZ
copybuff (258 bytes)
Used by some library routines as a temporary buffer for OZ calls that use
strings (this is not used internally by memory allocation routines, and will not
be considered further)
malloc_table (2 bytes for every 256 bytes required in the far heap)
The most important structure, holding details of the bank and address of
each 256-byte allocation in the heap
The pool table
This structure, as noted above, is used to hold the pool handles that have
been opened by the application. Initially, it is filled with nulls, indicating
that no pools are open.
This is a table of 1-byte entries, each corresponding to a bank in the Z88's
memory map. As banks 0-31 are always ROM (internal), the first entry corresponds
to bank 32, with the final entry corresponding to bank 255. Each entry holds
either 0 (indicating no pool open for that bank), or a value which relates
directly to the pool handle returned by OZ for that bank.
Three important assumptions are made when constructing and using this table:
each OZ pool handle always gives allocations from the same bank; when the bank is
exhausted, no further allocations are possible with the handle
as a consequence, for each process, only one pool handle is ever associated with
a particular bank
the values of OZ pool handles are always of the form $0XY0, where $XY!=$00
The first two assumptions mean that we only need 224 table entries (one for each
bank) no matter how much memory we allocate. The last assumption means that each
entry only needs to be one byte in size (we shift the handle value 4 bits to the right),
and a zero value can indicate no pool.
The malloc table
Each entry in the malloc table consists of two bytes, and corresponds to an allocation
of 256 bytes of far memory.
The first byte contains the bank number containing the allocation (0 indicates no
allocation has been made for this entry), and the second byte contains the high byte
of the address of the memory allocation (always in segment 1).
The low byte of the address is not required, since for allocations of 256 bytes, OZ
always returns an address with a low byte of zero; thus this is always assumed.
Allocation method
The first stage in memory allocation is to locate a section of the malloc table
which has not yet been allocated (ie contains nulls) and which is large enough for the
required allocation. An extra 2 bytes are always added to the amount of memory required,
to hold the number of pages (256-byte allocations) in the allocated block.
When a suitable region has been located (malloc always uses the smallest suitable
region), we start making allocations and filling the malloc table. This is done as
follows:
first, existing pools in the pool table are checked, and allocations made from these
if all existing pools are exhausted, new pools are opened and allocations made from these
If all pools are exhausted and no further ones can be opened before all memory is allocated,
the memory allocated so far is freed, and malloc returns an error.
Once the allocations are completed, the number of 256-byte pages used is stored in the first
two bytes, and a far pointer following this value is returned.
Deallocation method
Deallocating is much more straightforward. The pointer is decremented twice, and the value
fetched is thus the number of 256-byte pages that were allocated.
A loop is entered which frees each 256-byte allocation, and zeros the corresponding entry
in the malloc table.
Note that no pool handles are freed during this process, but they become usable again when
further mallocs are performed. All handles in the pool table are freed by the freeall
function, which is automatically called on exit from the application.
Garry Lancaster, 18/4/00
z88dk-1.8.ds1/doc/fileio.txt 0000644 0001750 0001750 00000002417 07273751461 015301 0 ustar tygrys tygrys File I/O and z88dk
------------------
Many machines supported by z88dk support multiple types of disc system,
for this reason it is desirable to make it as easy as possible to switch
between them. To this end, the file libraries for certain targets have now
been separated out from the main machine library and located in separate
libraries. The routines which gave been isolated are:
close
creat
fdgetpos
ftell
lseek
open
open_z88
read
readbyte
remove
rename
write
writebyte
Which are all the routines required to enable file i/o. A dummy library
called ndos.lib has been created which contains minimal stubs for these
routines which simply return an error value.
Unfortunately, this means that if you don't require file i/o you have to
supply an extra parameter for the compile, but I believe the flexibility
of being able to switch between different DOS systems is worthwhile.
So far, a file library has only been prepared for one system besides the
z88 (whose file i/o routines remain integrated) and that is for the
Spectrum.
Spectrum:
A file i/o library has been prepared for the +3, this hasn't been tested
but it should just work! To use it compile thusly:
zcc +zx -DPLUS3 [files] -lp3
To compile with no/dummy file io routines use:
zcc +zx [files] -lndos
In future
z88dk-1.8.ds1/doc/history.html 0000644 0001750 0001750 00000050310 07130401726 015637 0 ustar tygrys tygrys
Z88 Development Kit History File
Z88 Development Kit
There seems to be little point carrying on with this file since the
history is really contained in the "Whats New?" section, this file
will continue to grow when I move old "What's New?" over to here.
Some past history
This is getting quite long, hence the re-location into a separate
file where I can rabbit on about the changes I made to my hearts
content!
As a recap on the versions between v0.66 of the compiler and
whatever the last release beneath was (v0.55?) here are the important
new features:
Initialising xx *[]= { ,,, } types now works properly
Auto variables can be initialised
sizeof() now works on structure members
Casts now slightly more cast like
goto now works a lot better than before
Octal constants are now understood
Bug fixes (lots!)
Optimisatioin rules (lots!)
More lib functions
New for v1.2 on v1.1 are the following features:
Menus and topics (v1.1p2)
Help for menus and topics (v1.1p3)
Reduction of startup codesize for good apps (v1.1p4)
Application Mailboxing (v1.1p4)
Exit function rewritten to return exit code (eg for displaying
of error box for z88 apps)
Corrected bug in prototyping which could produce spurious errors (v1.1p4)
More example apps (v1.1p3,v1.1p4)
Even more optimization rules <grin>
Support for new z80asm v1.0.10 features (this version is the minimum supported!)
New mini(f)printf functions which are automagically utilised (you can of course use them explicitly!)
fcntl.h library routines
static [type] outside of function or in function definition
correctly limits the scope
...details on the changes for a particular patch can always
be found in the readme.1st file in the root directory
New for v1.1 of Z88dk (sccz80 v0.55) are the following features:
More optimization rules (including a speed(!) one!)
Rejigged front end allowing easy retargetting of the compiler
for other Z80 machines
Hopefully memory leak free WinSucks version
Z80asm v1.0.5
Release v0.52 22/3/99
Does anyone actually read this file? Anyway, I've had enough of this
compiler for the moment so this is the first Aminet version (no doubt to
be followed by another later this week!) Lots of fixes in this release
and a couple of extensions as well, but if you've read the docs you'll
know that of course!
Pre-release v0.51 18/3/99
This is just getting silly! Everytime I say I want to release it I
go through a spurt of adding new features, new this time are:
Correct initialisation of local statics (oops, forgot to
give the size to the initials function!)
Ability to set pointers to functions equal to a function name in static declarations
Sizeof now works on all variables (except for those passed to a function and obviously kicks up a fuss about functions!)
What, you want more, do you really want my blood?
Okay then...fixed the string.h file - missing comma!
Just for you...another optimization rule
Pre-release v0.50 17/3/99
Corrected a few silly problems with function return values
(prototyping), killed a silly error, added the -Wnone flag.
Pre-release v0.49 16/3/99
Hopefully the same as v0.48d?
Pre-release v0.48[a-e] 5-14/3/99
Internal release. This version saw a substantial rejigging of the
compiler code to allow almost error free compilation - gcc -Wall is
now without errors (I'm not going to bother with -pedantic!) Several
annoying bugs which only showed up on Linux were fixed. Memory leaks
on Winblows were sorted out (sassen frassen). Full prototypes make their
appearance for the first time in Small C (is it right to call it Small
C anymore?)
Pre-release v0.47 3/3/99
Internal bug fix release only
Pre-release v0.46 2/3/99
zcc Added provison for a second layer of optimization and a few
other tweaks. Sorted out a few problems which would have arisen in multi-module programs which used floating point operations. Also allowed
the order of input files to be irrelevant (previously the file with main() had to be the first in the list.
copt Second rule file for optimization of logical operations
on unsigned chars as well as a few other simple optimizations.
sccz80 Fixed lots of bugs in cc6.c regarding calling of long functions (mainly missed out else statements!), squashed bugs in +/- calling for long functions (stack was not being equalised correctly),
sorted out the widenlong() function in cc5.c so that chars/ints are
correctly extended to longs (regardless of sign). Sorted out representation
of negative long constants, countless other bug fixes to long routines.
Improved the handling of -no-header (this is used to compile library
sources which are in C) so now it does something useful. It's also now
possible to overwrite library functions for a particular program (in
principle at least) - though are you sure you want to do this?
library Almost completely rewritten the library routines for long
- there were so many silly mistakes here it amazes me that no one
actually
spotted them, I've extensively tested them, and am fairly confident that
they all work now. Some sample problems that I came across l_long_sub calculated b-a instead of a-b l_long_inc/dec were completely fubarred.
Comparison routines were complete nonsense (some more so than others) -
mostly due to the l_long_sub bug/feature <grin>. In summary it
transpires that what with bugs in the compiler and in the libraries that
any code utilising longs would never have worked.
There's also lots of new string functions as well as some new ctype
functions. Also all new is a malloc() system.
Pre-release v0.45 ??/2/99
This release only got as far as Dennis, it's the release that first
saw the introduction of the config file for zcc.
Pre-release v0.44 19/1/99
I hope you all had a good holiday season and are ready to start
attempting to trip the compiler up once more!
A new frontend with this edition, and at last meaningful flags for
the compiler. Also new is support for Z88 maths routines - there is
something fishy somewhere in the code though - the cube.c example
refuses to work correctly and I'm baffled!
Fixed a problem with #pragma asm/endasm statements - they weren't being
parsed correctly.
Pre-release v0.43 2/12/98
A bit of a little bug fix release really, I noticed a few problems
with the generated code and though I'd better fix them sharpish (The
classic one is of course getting the size of integer incorrect!). There's
also a new demo program - Dstarz88
Pre-release v0.42 29/11/98
Far pointers have been implemented, hopefully correctly, declare as
you would a normal pointer but prefix by "far". No support routines have
been written for them, so nothing will compile if you use them ,
but have a look at the assembler file and see whether it is as you would
expect it to be. [See far.html for descriptions
of the proposed routines!]
I've also done a bit of fixing up of longs, so now you can set them
equal to a constant correctly! And finally, yes I know I've been saying
it for the past x releases, but longs should work properly know - I've
fixed up long comparisions in if statements, and it's also possible to
switch via a long (untested!). Also added is a lot of
type-checking so
that you get warnings if you try to equate/do arithmetic on different
signed values (obviously not applicable for +/-).
This behaviour isn't ANSI atm, in the future I'll fix it so promotion
to unsigned takes place.
Also, warnings pop up
if you do int<->ptr conversions - it's not really a good idea to do these
sort of things if you want your code to be portable! [Code will still
be generated, but side effects might occur!]
Fixed the "bug" in the 16 bit divide routines - I got the input
parameters the wrong way round, an ex de,hl solves all! Did a small mod
in crt0/l_mult to change rl a to rla (DLE).
Pre-release v0.41 17/11/98
This and v0.40 were released concurrently, this version adds literal
queue compression to save memory in the resulting executable - it works
remarkable well and saves almost 180 bytes in the cube demo, in programs
with lots of text even more should be saved.
Pre-release v0.40 16/11/98
Another long pause However, to make it worth your while I've
come back with a cracker - hopefully longs will now be functioning
correctly. I've changed the manner in which they were stored when calling
library functions - now like doubles they are stored on the stack instead
of in the alternate registers, this makes for much nicer code that will
work as opposed to code that might work! To celebrate this I've written
32 bit multiplication and division routines!
Also rewritten are the 16 bit multiply and divide routines (they're
now a little small and hopefully faster), and I've finally got the (l)abs
routines right..or at least I hope so!
Labels in the compiler are now prefixed by a smc_ to avoid potential
label clashes with routines in the library. A little bit more work has
be done on long pointers though they still won't work! [I'm gonna hate
sorting that out!]
Barring any major hiccups I think the compiler is almost ready for its
first public release, any comments?
Pre-release v0.39 20/10/98
Apologies for the long delay in releasing this - I've been kinda tied
up with other things of late! Anyway, it's now here and the compiler now
fixes a few things like signed chars (dumb mistake by me) and the
initialisation of aggregates.
In the library functions it's been big change time - the graphic
functions have been rewritten so that they page in the map bank each
time (previously it was (rather sloppily!)) just left paged in permanently.
As predicted this caused a "few" problems! There's an integer printf
function - use only if absolutely necessary - even after serious
hand optimization (It took a whole evening!!) it still weighs in at around
2k. The exit() function has been rewritten to cope with the atexit()
function which someone might possibly care to use.
More serious problems are avoided by insertion of the correct case/switch
function! Ooops, that one was hanging around waiting to clobber people!
Pre-release v0.38 8/10/98
Implemented the local static variable storage class and fixed a few
minor problems in sccz80 with filenames, removed some obsolete code,
removed the prototypes for malloc and exit from ccfunc.h and included
stdlib.h where appropriate.
Corrected the strings.h include file and altered the strncmp() library
function to be more efficient and smaller (DLE), found the minusfa fp
routine and put it in mathsupp/ along with odd. Altered the double <=
function so it has the label dleq so to avoid clash with a defc in
cntlchar.def - hopefully fp programs will now compile?
Pre-release v0.37 6/10/98
The last two releases never got very far due to problems with
prototyping. This new release fixes those, and adds another batch of
library functions - investigate the headers for more details!
This release is only supplied as a complete archive because I've
completely reorganised the libsrc/ directory and added several new files -
it's much easier to start again that to create a set of patch
distributions!
Hopefully I've finally(!) fully implemented unsigned datatypes - they
are now scanned for in function definitions, also a bare unsigned results
in an unsigned int being produced. Removed the int and word datatypes -
silly! In the source code spent a lot of time prototyping certain functions
to knock some warnings off a -Wall compilation.
Allowed for longer include filenames than 16! This also prevents
possible segmentation faults - which solves the Amiga "gcc" problem and quite a few others I imagine as well!
The keywords register and auto are parsed for in statement() though
they are silently ignored.
There's a very big bugfix for this release, dereferencing of pointers
are now resolved correctly and generate good code - this was broken since
v0.33 and was due to the incorrect assignment of one variable in the
primary() function. This took me about 4 hours to track down and correct!
Many thanks to David Earlam for putting me onto the trail for this one.
There's also another optimization rule which optimizes some more of
the structure referencing code.
Pre-release v0.36 29/9/98
sccz80 Pesky prototypes again, now they're done with #pragma proto and #pragma unproto, these will now work with the Borland pp.
Hopefully sorted out the gcc crash problem, this was due to not checking
whether a pointer to struct was set or not, if unset the compiler tried to
reference an address in low memory and this seems to have upset the memory
protection agent, though why it should also do this on the Amiga which has
no memory protection is a tad strange.
Implemented Dennis' startup code so a BASIC program is generated which
contains the compiled code as well making life that little bit easier!
Added a couple more optimizing rules.
Pre-release v0.35 28/9/98
sccz80 (Almost) ANSI function definitions have been implemented.
Fixed the distinguishing of prototypes by implementing #proto/#unproto. The
previous fix used #defines which were swallowed by the preprocessor.
Fixed a problem that arose after v0.32 due to over-zealous use of the
delete line key!
Pre-release v0.34 22/9/98
sccz80 Made the error messages much more legible (i.e. ala Dice),
corrected a nasty hang which could result if a symbol wasn't found by end
of file, made the differentiation between library functions and external
functions in other modules.
Includes Implemented the slightly kludgey (but it works!) way of
ensuring that prototypes here do reference the library functions.
Pre-release v0.33 14/9/98
sccz80 Implemented the long data type and the associated libraries.
Pre-release v0.32 12-13/9/98
sccz80 Changed the maximum line length to 192 (so as to get
enigma_sc to compile!), and altered the assembler label length from 8 to 32.
The big modification is the use of the signed and unsigned keywords - this
actually affects the code being produced and hence should work! A small
warning (which I shouldn't really need to state :) is that don't try doing
functions on combinations of the two, really weird things will result
otherwise!
Libraries Corrected a few label problems in the l_mul and l_lt
library functions.
Optimizer Put some of the rules in the correct order so that they
don't prevent other optimizations being made.
zcc New pass through to the compiler for -e (stop on errors) and -f
(implicitly define all ints and chars as unsigned.)
Startup code Installs a simple error handler which will trap
escapes to stop those annoying hangs. Pressing escape will abort the program (much like Ctrl+C does on other computers).
Pre-release v0.31 8/9/98
sccz80 Corrected a few problems in the definition of extern and
static variables (assembler output) - programs should now compile and
execute correctly!
Restored the data type of external pointer (lost in the conversion over to
Small C+). Allowed the explicit use of static for global variables. Created a
fake data size of void (which is effectively int) for functions, thus allowing
more code to compile with fewer changes.
The most important change is that to the Small-C+ compiler which has more features than the original Small-C and will allow the compilation of
many more programs.
Have moved all of the runtime functions previously held in z88_crt0.asm
into library functions so will only be linked in if needed, this has a
dramatic effect at reducing the size of the produced binaries. Hopefully
all the cross references have been resolved correctly.
Pre-release v0.2 August 1998
Added a lot of untested library functions, and a driver.
Pre-release v0.1 August 1998
First release of the Z80 compatible Small-C compiler based on the zcc
v0.96 sources by Ken Yap. Very minimal, just enough to compile Hello
World.
Back to main doc file
z88dk-1.8.ds1/doc/interrupts.txt 0000644 0001750 0001750 00000012030 10416272011 016217 0 ustar tygrys tygrys
INTERRUPTS IN Z88DK
The z80 supports three interrupt modes: IM0, IM1 and IM2.
1. IM 0 - The Forgotten Mode
IM0 is the least used mode and is mainly there for 8080
compatibility. In this mode an interrupting peripheral
supplies an instruction to execute when the interrupt
is acknowledged. That instruction is typically a
single-byte "RST n" which effectively causes a subroutine
call to one of eight fixed entry points in the first
256 bytes of memory. A pro for this mode of operation
is the quick interrupt response since the interrupt
service routine for up to eight different peripherals
is directly jumped to right away. There is no direct
support for this mode under z88dk but it is a simple
matter to assemble a 3-byte JP instruction at these
entry points to cause a jump to an ISR of your creation.
One or more copies of the generic ISR described below can
be used to handle the interrupts.
2. IM 1 - Keep It Simple
IM1 is more commonly used. In this mode, an interrupt
causes a jump to address 0x38. Typically the interrupt
service routine there might poll attached peripherals
to determine which need servicing. If only a single
device or two can cause interrupts this might be
acceptable. Again, There is no direct support for this
mode under z88dk but it is a simple matter to assemble
a 3-byte JP instruction at 0x38 to cause a jump to an ISR
of your creation. The generic ISR described below can be
used to handle the interrupt.
3. IM 2 - The Sexy Mode
IM2 is the most powerful interrupt mode. In this mode
an interrupting peripheral supplies a single-byte vector
when the interrupt is acknowledged. The contents of the
I register is concatenated with this vector byte (with
I most significant) forming a 16-bit address where the
address of the interrupt service routine to jump to
is stored. Effectively register I*256 points at a
256 byte table of interrupt service routine addresses.
By convention (and convention only since this seems to
be frequently violated) vectors supplied by interrupting
peripherals are even. This ensures that interrupt
service routine addresses do not overlap in the table
pointed at by register I. In particular, it is worthwhile
noting that Zilog's peripheral chips can only store
even vectors and therefore reset bit 0 of vectors written
to them automatically.
This means that normally only even vectors 0-254 can
be generated by peripherals making the table pointed
to by register I exactly 256 bytes long and fitting
nicely into a single 256-byte page. However in the
real world, some peripherals can generate odd vectors,
including 255 meaning the vector table could be 257
bytes long and may (without care) have overlapping
entries due to the mix of odd and even vectors
generated by attached peripherals.
z88dk supplies an im2 library; consult the header
file im2.h for function prototypes in the library.
To use the library you must first declare the location
of the 256(257) byte interrupt vector table as described
in the header file.
im2_Init() is called to initialize im2 mode. This call
will create the im2 vector table, set im2 mode, and allow
you to choose between a conventional 256 byte table or
the less conventional 257 byte variant. Each vector entry
will point at a default interrupt service routine that you
pass in as parameter; this can be a C function or an
absolute memory address.
Typical interrupt service routines can be installed
on any vector with im2_InstallISR(). This can be
the address of a C function, assembly function or
absolute memory address. Any such interrupt routine
must save and restore registers as well as reenable
interrupts prior to a "reti" to return from interrupt.
If the function registered is a C function this must
be done with embedded assembler.
The library also supplies a Generic Interrupt Service
Routine. This is an ISR that can be installed on any
vector with im2_InstallISR() as any typical ISR is.
The difference is that this ISR can have any number of
hooks registered with it. Each hook will be executed
one after the other on interrupt. Should any hook return
with the carry flag set, succeeding hooks will not be
run. The ISR itself will take care of saving and
restoring registers as well as reenabling interrupts
so any hooks registered with it do not need to worry
about those details. This model is the usual model
used when several peripherals could supply the same
vector, but can also be used to register plain C
ISRs without their having to worry about the low-level
housekeeping associated with ISRs.
To create a generic ISR, it must be copied into RAM.
This is done with im2_CreateGenericISR(). Any number
of independent generic ISRs can be created in this
manner and can be registered on one or more interrupt
vectors with im2_InstallISR().
When making changes to the z80's interrupt state
whether using im2.lib or not, make sure to have
interrupts disabled using some inline assembler.
Im2.lib will not enable or reenable maskable interrupts
so as not to interfere with the program.
Further questions can be answered on the z88dk users
mailing list.
- aralbrec 04.2006
z88dk-1.8.ds1/doc/lib3d.txt 0000755 0001750 0001750 00000005657 10021135454 015022 0 ustar tygrys tygrys -------------------------
3D Libraries (2/15/2002)
Doc taken from the OZ Developement kit.
See section III for Credits on this file and on the whole library
$Id: lib3d.txt,v 1.3 2004/03/02 16:49:48 stefano Exp $
-------------------------
TOC
I. Introduction
II. Reference
III. Credits/Acknowledgements
IV. Links
I. Introduction
----------------
The 3D Libraries include a standard set of functions for making your own 3D functions. This document is a reference for these functions.
II. Reference
--------------
The following is a reference for the available functions in lib3d.lib. Please note that you will have to include "lib3d.h" in order to use these functions in your code.
void ozrotatepointx(Vector_t *v, int rot)
void ozrotatepointy(Vector_t *v, int rot)
void ozrotatepointz(Vector_t *v, int rot)
Use these functions to rotate a vector around the origin. The variable 'rot' is the rotation factor in degrees (?), not radians (? p 180). Note: Do not rotate the original coordinates! This will distort an object after a few times of use. Use ozcopyvector() to first copy the coordinates into a temporary variable and rotate them there.
Example:
...
Vector_t v;
...
v.x = 10;
v.y = 10;
v.z = 10;
ozrotatepointx(&v, 90);
ozrotatepointy(&v, 90);
ozrotatepointz(&v, 90);
...
void ozcopyvector(Vector_t *dest, Vector_t *src)
This function copies a vector's X, Y, and Z coordinates from *src to *dest.
Example:
...
Vector_t v1;
Vector_t v2;
...
ozcopyvector(&v2, &v1);
...
void oztranslatevector(Vector_t *v, Vector_t *offset)
Offset a vector by using this function. It will add the X, Y and Z coordinates from *offset to *v.
Example:
...
Vector_t v1;
Vector_t v2;
...
oztranslatevector(&v2, &v1);
...
void ozplotpointcam(Vector_t *v, Cam_t *c, Point_t *p)
This function will convert 3D vectors (X, Y, Z) into 2D Points (X, Y). This will even compensate for camera's position and angle. If you do not wish to use a camera in your program, use ozplotpoint() instead (see next function.)
Example:
...
Vector_t v;
Point_t p;
Cam_t mycam;
...
ozplotpointcam(&v, &mycam, &p);
...
void ozplotpoint(Vector_t *v, Point_t *p)
This function converts 3D vectors to 2D points without compensating for camera's position, thus it is much faster.
Example:
...
Vector_t v;
Point_t p;
...
ozplotpointcam(&v, &p);
...
III. Credits/Acknowledgements
3D Libraries Copyright 2002, Mark Hamilton Jr. Vector rotation optimizations performed by Lawrence Chitty. Wonderful Sine and Cosine enhancements done by Alexander Pruss.
Many thanks to on-line tutorials, Alexander Pruss and Benjamin Green for helping me with 3D concepts. I certainly learned a lot from this experience.
IV. Links
http://evesw.techmods.com - My development site.
http://www.ozdev.com - You should know this place--it's where you got the Hi-Tech C compiler from!
z88dk-1.8.ds1/doc/memoryallocation.txt 0000644 0001750 0001750 00000034241 10416272011 017366 0 ustar tygrys tygrys
MEMORY ALLOCATION UNDER Z88DK
This file describes several dynamic and static memory allocation schemes that
work well under z88dk. All assume a 64K memory space model, but a thing or
two will be said about >64K model memory allocation.
Besides what is described here, z88dk does have a far memory model concept
which uses 24-bit memory pointers to access up to 16MB of memory. This has
been implemented for the z88 target and you should consult other documentation
in this directory to learn more about it.
Before getting into it, let's briefly investigate how C's variables are
treated by the compiler.
1. AUTOMATIC VARIABLES
Local variables declared in a C program are allocated on the stack as
a function is entered and are popped off the stack as functions are
exited. They are dynamic (in that memory is allocated and deallocated
from the stack as required) and transient (in that referring to their
addresses has no meaning after the function terminates).
Example: accessing local variables from assembler embedded in a
C function.
int myfunc(char b, unsigned char *p)
{
#asm
ld hl,2
add hl,sp ; skip over return address on stack
ld e,(hl)
inc hl
ld d,(hl) ; de = p
inc hl
ld a,(hl) ; a = b, "char b" occupies 16 bits on stack
; but only the LSB is relevant
...
ld hl,1 ; hl is the return parameter
#endasm
}
Example: z88dk's special __FASTCALL__ qualifier can be used if
the C function has just one parameter. In that case, the parameter
is passed in the HL register pair instead of being allocated on
the stack.
int __FASTCALL__ myfunc(unsigned char *p)
{
#asm
; hl = p
...
; return value in hl
#endasm
}
2. STATIC VARIABLES
In C, static variables are those variables declared outside the
scope of any function. They are global by default (as in they can
be referred to from anywhere) and can be made lexically local to
a particular C file by using the "static" modifier in their declaration.
Because they are declared outside the scope of any function, they
exist for the duration of the entire program. For this reason they
cannot be allocated on the stack but instead are assigned their own
absolute locations in memory. The assembler used by z88dk does not,
at this time, have any concept of separate code or data segments.
Therefore the compiler simply generates a single monolithic binary
that contains compiled code and space for statically declared variables.
This can be a problem if ROMable code must be generated because these
globally defined static variables will be mixed in with code in the
final binary, and will become constants when they are burned into
a ROM.
An example of a static variable being accessed from assembler:
int a;
...
#asm
ld hl,(_a)
#endasm
The C variable has sufficient space reserved by the compiler and
is given an assembler label which is constructed by prefixing
the C name with a "_".
There are several workarounds for accommodating ROMable code. One
is to declare variables as pointers to fixed memory locations in RAM.
If your program statically declares an int, make it statically
declare a pointer to int instead with the pointer initialized to a
constant memory address in RAM. This constant value is safely ROMable.
There are two ways to place a pointer at an arbitrary memory address.
The first method uses a bit of embedded assembler for assistance:
extern int *p;
#asm
._p defw 60000
#endasm
The extern qualifier tells the compiler that the variable is
declared someplace else so that no memory is reserved for it
when the declaration is met. Recall that the C compiler will
cause references to this variable to be made from assembler using
the C name with a prefixed "_". We arrange in the embedded
assembler to supply that name and space with a constant memory
address safely in RAM. The two bytes referred to by assembler
label "_p" with value 60000 will be compiled as part of the final
binary and will be burned into ROM. References to "p" from the
C program will access the word 60000 and dereferencing the "p"
ptr will cause an int to be written or read from address 60000.
The second method accomplishes the same thing but perhaps uses
a cleaner declaration style:
extern int *p @ 60000; // FIXME
Another frequently used method in some of z88dk's libraries is
to have the user declare locations in memory of various necessary
data structures. Eg, the im2 library requires a single label
to be defined in the program that holds the location of the interrupt
vector table. Consult the im2.h header file for further information.
3. STATIC MEMORY ALLOCATION
There are two reasons why you may want to remove static variables
from the final binary. One is that you want to make the final
binary smaller for loading into the final target by pruning out
RAM variables. Another is that the binary must be ROMable
so that static variables must be removed and placed in RAM locations.
The methods mentioned in the last section may not be entirely
satisfactory if you have a lot of static variables to worry
about. Each time your program changes the static variables
it uses, you will have to modify by hand the locations of each
pointer variable.
Another alternative is to write a static memory allocator:
unsigned int static_free = 50000;
void *static_alloc(unsigned int size)
{
unsigned int temp;
temp = static_free;
static_free += size;
return temp;
}
The variable "static_free" holds the address of freely available
memory in RAM, and is adjusted upward as static memory is allocated
during the initialization of the program.
All static variables are made into pointers and are allocated
memory for their data from the static allocator.
Example:
int a;
char *table[100];
Is turned into this:
int *a;
char **table;
main()
{
a = static_alloc(sizeof(int));
table = static_alloc(100*sizeof(char *));
}
This will reduce the size of the final binary that needs to be
loaded into the target (the original static table array reserved
200 bytes in the final binary but after the change only 2 bytes
in the final binary would be reserved for the pointer) but it is
*still* not ROMable code. Space for each pointer variable
(2 bytes) will be allocated within the output binary destined for
the ROM. One must place the location of each pointer variable at
a specific memory address in RAM using the special pointer
declaration syntax mentioned in the last section so that they can
be assigned to from a call to static_alloc.
4. DYNAMIC MEMORY ALLOCATION
There are currently two dynamic memory allocators in z88dk that
are independent from each other and can be used together if desired.
A. Standard C Malloc and Free
The standard C malloc functions manage a single monolithic
chunk of memory (called the "heap") accessed by malloc() for
allocation and free() for returning memory chunks for reuse. Any
size memory chunks can be requested and a block of sufficient
size will be returned if sufficient memory space in the heap is
present.
In your program you must include the header malloc.h and link
to the malloc library in your compile command with "-lmalloc".
In main() you must initialize the heap with a call to heapinit().
In the tiny memory space of the z80, where this free memory
chunk for the malloc functions is located is a problem. z88dk's
malloc implementation requires the user program to declare the
location of the heap in one of two ways.
The first way is to declare the macro supplied in the header file
globally with the rest of the static variable declarations in your
main.c file:
HEAPSIZE(bytes)
where "bytes" is the size of the heap in bytes.
This macro actually declares a static array of the given size,
which is something that will be compiled as part of the final
binary. This is not good if your binary will need to be ROMable
or if you want to shrink the size of the final binary.
Instead you can declare the location of the heap using some
embedded assembler:
#asm
XDEF _heap
DEFC _heap = 50000
#endasm
This will place the heap at address 50000. The initialization
call to heapinit() takes as parameter the size of the heap and
this will format a block of memory at that address to use that
size only.
B. The Dynamic Block Allocator
The standard malloc() and free() implementation is very flexible in
that it allows memory blocks of any size to be allocated and returned
to the heap. It also has some drawbacks, namely it suffers from
speed issues (relatively speaking) and external fragmentation.
Because any size memory blocks can be requested from the heap, a
substantial amount of overhead is incurred keeping track of which
pieces of the heap are still available. This makes it comparatively
slow.
Again because any size memory blocks can be allocated, the heap
can suffer from a condition known as external fragmentation. Over
the course of running a program, many blocks of variable sizes can
be allocated and freed. This can lead to a situation where there are
a lot of scattered smallish segments available in the heap for
allocation. Memory requests may no longer be satisfiable since any
single free segment is too small, even though the total amount of
space in the heap (found by adding up all the little segments) would
be sufficient. This situation is known as external fragmentation.
If the heap is too small (quite likely given the small 64k space
available) programs that make use of the heap may grind to a halt
after running long periods because memory requests are no longer
satisfiable due to the scattered condition of the heap.
A solution to both these problems is the dynamic block memory
allocator.
A block memory allocator maintains several memory queues, each of
which maintains a list of free blocks of fixed size. Queue #0 might
contain 6-byte blocks, queue #1 14-byte blocks, etc. Memory requests
are made from a specific queue, retrieving a memory block of known size.
Because the free memory blocks are maintained in a list, allocation and
freeing is very fast. Another important advantage this allocator has to
the heap oriented one is that scattered free memory from all over the memory
map can be made available through the block allocator.
To use the block memory allocator, you must include the header balloc.h
and link to the balloc library with "-lballoc" in your compile command.
In your C program you must declare the location of the queue table
which is 2*numQ bytes in size where numQ is the number of memory queues
you want. You can do this in one of two ways.
One way is to declare the macro from the header file with the rest of
your static variables in the main.c file:
BAQTBL(numQ)
where numQ is the number of memory queues desired. Again, this will
declare a static array that will be compiled as part of your final
binary, something not suitable for ROMable code.
The other method is to declare the location of the queue table using
some embedded assembler:
#asm
XDEF _ba_qtbl
DEFC _ba_qtbl = 50000
#endasm
which will place the queue table at address 50000.
You must initialize the queues to empty prior to use with a call
to ba_Init(). The queues will be empty and you must add memory
to the queues with calls to ba_AddMem().
The header files are a source of further documentation on both dynamic
memory allocators.
5. IMPLICIT DYNAMIC MEMORY ALLOCATION BY SOME Z88DK LIBRARIES
Several of z88dk's libraries need to allocate dynamic memory for their
own purposes. The abstract data types library (see adt.h), for example,
has a linked list data type that needs to allocate containers for each
node in a linked list. These libraries do not make assumptions about
how your program does memory allocation (ie whether it uses the standard
heap or the block allocator or another scheme of your own creation).
Instead they call two functions that you must provide in your C program
to perform the memory allocation on their behalf.
These two functions are declared thus:
( u_malloc must return carry flag set if allocation successful )
void __FASTCALL__ *u_malloc(uint size) {
return(malloc(size)); // lib function malloc sets carry
}
( u_free must ignore addr == 0 )
void __FASTCALL__ u_free(void *addr) {
free(addr); // lib function free ignores 0
}
In this example, the standard malloc() and free() are used to
satisfy all requests, but the block memory allocator is probably
the best choice for the library functions since they frequently
allocate and free small fixed size blocks.
Here are the same two functions written in assembler:
XDEF _u_malloc
._u_malloc ; HL = size in bytes
LIB malloc
jp malloc ; return in HL address of memory block
XDEF _u_free
._u_free ; HL = address of memory block
LIB free
jp free
Whether or not a library makes use of implicit memory allocation
will be mentioned in its header file and the sizes of those
requests should be clear from the data structures declared there.
If you have a certain amount of programming experience, it shouldn't
be a mystery as to which libraries might need to dynamically allocate
memory.
6. WHAT IF YOU HAVE MORE THAN 64K?
Aside from the far pointers mentioned at the beginning of this article,
there are two things that can be done to take advantage of this extra
memory space.
By far the easiest thing you can do is access the extra memory through
a RAMdisk model, ie copy data to and from the extra banks to the main
64K bank where your program is designed to run, as needed.
Another is to make use of the block memory allocator. Separate queues
can be maintained for available memory in different memory banks.
Subroutines within your program can be confined to certain banks so that
whenever they run they only access data in those banks and have those
banks paged in when they run. Those subroutines can use the block allocator
for their memory allocation needs, making sure they allocate from the
appropriate queues.
That's the end of the overview... Any specific questions can be addressed
to the z88dk users mailing list.
- aralbrec 04.2006
z88dk-1.8.ds1/doc/netman/ 0000755 0001750 0001750 00000000000 10765202715 014540 5 ustar tygrys tygrys z88dk-1.8.ds1/doc/netman/.sock_open.man.swp 0000644 0001750 0001750 00000030000 07130401727 020070 0 ustar tygrys tygrys b0VIM 5.3 >8 R; dom dylan.cheshire.hunt ~dom/z88dk/doc/netman/sock_open.man 3210#"! U tp ad s r < February 13, 2000 djm RETURN VALUE DESCRIPTION void (*datahandler)(), char protocol); SOCKET *sock_open(ipaddr_t ipaddr, tcpport_t dport, #include SYNOPSIS sock_open - Open an active connection NAME sock_open(3Z) z88dk Programmers Manual sock_open(3Z) z88dk-1.8.ds1/doc/netman/cat3z/ 0000755 0001750 0001750 00000000000 10765202715 015564 5 ustar tygrys tygrys z88dk-1.8.ds1/doc/netman/cat3z/byteorder.3 0000644 0001750 0001750 00000004404 07130401727 017645 0 ustar tygrys tygrys
byteorder(3) z88dk Programmer's Manual byteorder(3)
NNAAMMEE
htonl, htons, ntohl, ntohs - convert values between host
and network byte order
SSYYNNOOPPSSIISS
##iinncclluuddee <>
uunnssiiggnneedd lloonngg iinntt hhttoonnll((uunnssiiggnneedd lloonngg iinntt _h_o_s_t_l_o_n_g));;
uunnssiiggnneedd sshhoorrtt iinntt hhttoonnss((uunnssiiggnneedd sshhoorrtt iinntt _h_o_s_t_s_h_o_r_t));;
uunnssiiggnneedd lloonngg iinntt nnttoohhll((uunnssiiggnneedd lloonngg iinntt _n_e_t_l_o_n_g));;
uunnssiiggnneedd sshhoorrtt iinntt nnttoohhss((uunnssiiggnneedd sshhoorrtt iinntt _n_e_t_s_h_o_r_t));;
DDEESSCCRRIIPPTTIIOONN
The hhttoonnll(()) function converts the long integer _h_o_s_t_l_o_n_g
from host byte order to network byte order.
The hhttoonnss(()) function converts the short integer _h_o_s_t_s_h_o_r_t
from host byte order to network byte order.
The nnttoohhll(()) function converts the long integer _n_e_t_l_o_n_g
from network byte order to host byte order.
The nnttoohhss(()) function converts the short integer _n_e_t_s_h_o_r_t
from network byte order to host byte order.
On the z80 the host byte order is Least Significant Byte
first, whereas the network byte order, as used on the
Internet, is Most Significant Byte first.
CCOONNFFOORRMMIINNGG TTOO
BSD 4.3
NNOOTTEESS
Unlike on other machines these functions are not provided
through macros - they are instead functions kept in
z80_crt0.lib. The optimization rules supplied with z88dk
are aware of these routines and when appropriate optimize
the function call away.
AAUUTTHHOORR
Dominic Morris
Original manual page by David Metcalfe
BSD February 18 2000 1
z88dk-1.8.ds1/doc/netman/cat3z/DeviceOffline.3 0000644 0001750 0001750 00000002732 07130401730 020344 0 ustar tygrys tygrys
DeviceOffline(3z) z88dk Programmer's Manual DeviceOffline(3z)
NNAAMMEE
DeviceOffline - turn the network device online
SSYYNNOOPPSSIISS
##iinncclluuddee <>
vvooiidd DDeevviicceeOOfffflliinnee((iinntt _f_l_a_g));;
DDEESSCCRRIIPPTTIIOONN
The DDeevviicceeOOfffflliinnee(()) function turns the packet driver
offline so that other application may utilise the
resources that it is using.
For example for the built in SLIP driver, turning the
device online prevents polling of the serial port for
incoming bytes and the sending of queued packets, thus
allowing another program (e.g. Terminal) to use the serial
port.
The parameter _f_l_a_g specifies how the device is to be
turned offline, with current device drivers this has no
significence. However it is envisaged that the value
NOHANGUP the device will simply suspend sending and
receiving packets. Whilst with HANGUP the device will
hangup the line and terminate the telephone connection.
RREETTUURRNN VVAALLUUEE
None.
SSEEEE AALLSSOO
DDeevviicceeOOnnlliinnee(3z)
AAUUTTHHOORR
Dominic Morris
18 February 2000 1
z88dk-1.8.ds1/doc/netman/cat3z/DeviceOnline.3 0000644 0001750 0001750 00000001603 07130401727 020210 0 ustar tygrys tygrys
DeviceOnline(3z) z88dk Programmer's Manual DeviceOnline(3z)
NNAAMMEE
DeviceOnline - turn the network device online
SSYYNNOOPPSSIISS
##iinncclluuddee <>
vvooiidd DDeevviicceeOOnnlliinnee((vvooiidd));;
DDEESSCCRRIIPPTTIIOONN
The DDeevviicceeOOnnlliinnee(()) function turns the packet driver back
on again after it has been previously turned offline by
DDeevviicceeOOfffflliinnee((33zz)). How this is achieved depends on the
device driver in use.
RREETTUURRNN VVAALLUUEE
None.
SSEEEE AALLSSOO
DDeevviicceeOOfffflliinnee(3z)
AAUUTTHHOORR
Dominic Morris
18 February 2000 1
z88dk-1.8.ds1/doc/netman/cat3z/getnetbyname.3 0000644 0001750 0001750 00000002457 07130401727 020336 0 ustar tygrys tygrys
getnetbyname(3z) z88dk Programmer's Manual getnetbyname(3z)
NNAAMMEE
getnetbyname, getnetbynumber - get network entry
SSYYNNOOPPSSIISS
##iinncclluuddee <>
iinntt ggeettnneettbbyynnaammee((cchhaarr **_n_a_m_e));;
cchhaarr **ggeettnneettbbyynnuummbbeerr((iinntt _n_e_t_w_o_r_k,, cchhaarr ** _b_u_f));;
DDEESSCCRRIIPPTTIIOONN
The ggeettnneettbbyynnaammee(()) function returns the standard number
for the network with the name _n_a_m_e. If no network is known
then NULL is returned.
The ggeettnneettbbyynnuummbbeerr(()) function copies into _b_u_f (and returns
_b_u_f) the network matching the _n_e_t_w_o_r_k. If no network is
known then _n_e_t_w_o_r_k is returned in ASCII form.
RREETTUURRNN VVAALLUUEE
Detailed above.
NNOOTTEESS
These functions use a lookup table compiled into the ZSock
kernel, it is not likely that method will change in the
near future.
AAUUTTHHOORR
Dominic Morris
18 February 2000 1
z88dk-1.8.ds1/doc/netman/cat3z/getnetbynumber.3 0000644 0001750 0001750 00000002457 07130401727 020706 0 ustar tygrys tygrys
getnetbyname(3z) z88dk Programmer's Manual getnetbyname(3z)
NNAAMMEE
getnetbyname, getnetbynumber - get network entry
SSYYNNOOPPSSIISS
##iinncclluuddee <>
iinntt ggeettnneettbbyynnaammee((cchhaarr **_n_a_m_e));;
cchhaarr **ggeettnneettbbyynnuummbbeerr((iinntt _n_e_t_w_o_r_k,, cchhaarr ** _b_u_f));;
DDEESSCCRRIIPPTTIIOONN
The ggeettnneettbbyynnaammee(()) function returns the standard number
for the network with the name _n_a_m_e. If no network is known
then NULL is returned.
The ggeettnneettbbyynnuummbbeerr(()) function copies into _b_u_f (and returns
_b_u_f) the network matching the _n_e_t_w_o_r_k. If no network is
known then _n_e_t_w_o_r_k is returned in ASCII form.
RREETTUURRNN VVAALLUUEE
Detailed above.
NNOOTTEESS
These functions use a lookup table compiled into the ZSock
kernel, it is not likely that method will change in the
near future.
AAUUTTHHOORR
Dominic Morris
18 February 2000 1
z88dk-1.8.ds1/doc/netman/cat3z/getprotobyname.3 0000644 0001750 0001750 00000002542 07130401727 020706 0 ustar tygrys tygrys
getprotobyname(3z) z88dk Programmer's Manual getprotobyname(3z)
NNAAMMEE
getprotobyname, getprotobynumber - get protocol entry
SSYYNNOOPPSSIISS
##iinncclluuddee <>
iinntt ggeettpprroottoobbyynnaammee((cchhaarr **_n_a_m_e));;
cchhaarr **ggeettpprroottoobbyynnuummbbeerr((iinntt _p_r_o_t_o_c_o_l,, cchhaarr ** _b_u_f));;
DDEESSCCRRIIPPTTIIOONN
The ggeettpprroottoobbyynnaammee(()) function returns the standard number
for the protocol with the name _n_a_m_e. If no protocol is
known then NULL is returned.
The ggeettpprroottoobbyynnuummbbeerr(()) function copies into _b_u_f (and
returns _b_u_f) the protocol matching the _p_r_o_t_o_c_o_l. If no
protocol is known then _p_r_o_t_o_c_o_l is returned in ASCII form.
RREETTUURRNN VVAALLUUEE
Detailed above.
NNOOTTEESS
These functions use a lookup table compiled into the ZSock
kernel, it is not likely that method will change in the
near future.
AAUUTTHHOORR
Dominic Morris
18 February 2000 1
z88dk-1.8.ds1/doc/netman/cat3z/getprotobynumber.3 0000644 0001750 0001750 00000002542 07130401727 021256 0 ustar tygrys tygrys
getprotobyname(3z) z88dk Programmer's Manual getprotobyname(3z)
NNAAMMEE
getprotobyname, getprotobynumber - get protocol entry
SSYYNNOOPPSSIISS
##iinncclluuddee <>
iinntt ggeettpprroottoobbyynnaammee((cchhaarr **_n_a_m_e));;
cchhaarr **ggeettpprroottoobbyynnuummbbeerr((iinntt _p_r_o_t_o_c_o_l,, cchhaarr ** _b_u_f));;
DDEESSCCRRIIPPTTIIOONN
The ggeettpprroottoobbyynnaammee(()) function returns the standard number
for the protocol with the name _n_a_m_e. If no protocol is
known then NULL is returned.
The ggeettpprroottoobbyynnuummbbeerr(()) function copies into _b_u_f (and
returns _b_u_f) the protocol matching the _p_r_o_t_o_c_o_l. If no
protocol is known then _p_r_o_t_o_c_o_l is returned in ASCII form.
RREETTUURRNN VVAALLUUEE
Detailed above.
NNOOTTEESS
These functions use a lookup table compiled into the ZSock
kernel, it is not likely that method will change in the
near future.
AAUUTTHHOORR
Dominic Morris
18 February 2000 1
z88dk-1.8.ds1/doc/netman/cat3z/getservbyname.3 0000644 0001750 0001750 00000002506 07130401727 020522 0 ustar tygrys tygrys
getservbyname(3z) z88dk Programmer's Manual getservbyname(3z)
NNAAMMEE
getservbyname, getservbyport - get service entry
SSYYNNOOPPSSIISS
##iinncclluuddee <>
ttccppppoorrtt__tt ggeettsseerrvvbbyynnaammee((cchhaarr **_n_a_m_e));;
cchhaarr **ggeettsseerrvvbbyyppoorrtt((ttccppppoorrtt__tt _p_o_r_t,, cchhaarr ** _b_u_f));;
DDEESSCCRRIIPPTTIIOONN
The ggeettsseerrvvbbyynnaammee(()) function returns the standard port for
the service with the name _n_a_m_e. If no service is known
then NULL is returned.
The ggeettsseerrvvbbyyppoorrtt(()) function copies into _b_u_f (and returns
_b_u_f) the service matching the standard port _p_o_r_t. If no
service is known then _p_o_r_t is returned in ASCII form.
RREETTUURRNN VVAALLUUEE
Detailed above.
NNOOTTEESS
These functions use a lookup table compiled into the ZSock
kernel, it is not likely that method will change in the
near future.
AAUUTTHHOORR
Dominic Morris
18 February 2000 1
z88dk-1.8.ds1/doc/netman/cat3z/getservbyport.3 0000644 0001750 0001750 00000002506 07130401727 020566 0 ustar tygrys tygrys
getservbyname(3z) z88dk Programmer's Manual getservbyname(3z)
NNAAMMEE
getservbyname, getservbyport - get service entry
SSYYNNOOPPSSIISS
##iinncclluuddee <>
ttccppppoorrtt__tt ggeettsseerrvvbbyynnaammee((cchhaarr **_n_a_m_e));;
cchhaarr **ggeettsseerrvvbbyyppoorrtt((ttccppppoorrtt__tt _p_o_r_t,, cchhaarr ** _b_u_f));;
DDEESSCCRRIIPPTTIIOONN
The ggeettsseerrvvbbyynnaammee(()) function returns the standard port for
the service with the name _n_a_m_e. If no service is known
then NULL is returned.
The ggeettsseerrvvbbyyppoorrtt(()) function copies into _b_u_f (and returns
_b_u_f) the service matching the standard port _p_o_r_t. If no
service is known then _p_o_r_t is returned in ASCII form.
RREETTUURRNN VVAALLUUEE
Detailed above.
NNOOTTEESS
These functions use a lookup table compiled into the ZSock
kernel, it is not likely that method will change in the
near future.
AAUUTTHHOORR
Dominic Morris
18 February 2000 1
z88dk-1.8.ds1/doc/netman/cat3z/getservprotobyname.3 0000644 0001750 0001750 00000002670 07130401727 021610 0 ustar tygrys tygrys
getservprotobyname(3zz)88dk Programmer's Manuagletservprotobyname(3z)
NNAAMMEE
getservprotobyname, getservprotobyport - get servprotoice
entry
SSYYNNOOPPSSIISS
##iinncclluuddee <>
uu88__tt ggeettsseerrvvpprroottoobbyynnaammee((cchhaarr **_n_a_m_e));;
uu88__tt ggeettsseerrvvpprroottoobbyyppoorrtt((ttccppppoorrtt__tt _p_o_r_t));;
DDEESSCCRRIIPPTTIIOONN
The ggeettsseerrvvpprroottoobbyynnaammee(()) function returns the appropriate
protocol for the service with the name _n_a_m_e. If the ser-
vice isn't known then NULL is returned.
The ggeettsseerrvvpprroottoobbyyppoorrtt(()) function returns the appropriate
protocol for the service with the standard port number
_p_o_r_t. If the service is unknown then NULL is returned.
RREETTUURRNN VVAALLUUEE
If a service is known to more than one protocol then the
most frequently used is returned.
NNOOTTEESS
These functions use a lookup table compiled into the ZSock
kernel, it is not likely that method will change in the
near future.
AAUUTTHHOORR
Dominic Morris
18 February 2000 1
z88dk-1.8.ds1/doc/netman/cat3z/getservprotobynumber.3 0000644 0001750 0001750 00000002670 07130401727 022160 0 ustar tygrys tygrys
getservprotobyname(3zz)88dk Programmer's Manuagletservprotobyname(3z)
NNAAMMEE
getservprotobyname, getservprotobyport - get servprotoice
entry
SSYYNNOOPPSSIISS
##iinncclluuddee <>
uu88__tt ggeettsseerrvvpprroottoobbyynnaammee((cchhaarr **_n_a_m_e));;
uu88__tt ggeettsseerrvvpprroottoobbyyppoorrtt((ttccppppoorrtt__tt _p_o_r_t));;
DDEESSCCRRIIPPTTIIOONN
The ggeettsseerrvvpprroottoobbyynnaammee(()) function returns the appropriate
protocol for the service with the name _n_a_m_e. If the ser-
vice isn't known then NULL is returned.
The ggeettsseerrvvpprroottoobbyyppoorrtt(()) function returns the appropriate
protocol for the service with the standard port number
_p_o_r_t. If the service is unknown then NULL is returned.
RREETTUURRNN VVAALLUUEE
If a service is known to more than one protocol then the
most frequently used is returned.
NNOOTTEESS
These functions use a lookup table compiled into the ZSock
kernel, it is not likely that method will change in the
near future.
AAUUTTHHOORR
Dominic Morris
18 February 2000 1
z88dk-1.8.ds1/doc/netman/cat3z/pktdrive.3 0000644 0001750 0001750 00000010501 07130401730 017463 0 ustar tygrys tygrys
pktdrive(3z) z88dk Programmer's Manual pktdrive(3z)
NNAAMMEE
pktdrive - packet driver descriptor structure
SSYYNNOOPPSSIISS
##iinncclluuddee <>
DDEESSCCRRIIPPTTIIOONN
The _p_k_t_d_r_i_v_e structure defines access to a device, it is
only used by the ZSock kernel. Should you wish to write a
packet driver then this structure should be filled with
the relevent routines.
All external packet drivers run at address 8192 ($2000)
and it as this address that the structure should be
placed. Had z88dk the capability _p_k_t_d_r_i_v_e would be defined
as follows:
struct pktdrive {
char magic[10];
char *type;
char *copymsg;
void (*initfunc)(void);
void (*queuefn)(void *pkt, size_t len);
void *(*packetfn)(void);
void *(*sendfn)(void);
int (*readfn)(void);
void (*onlinefn)();
void (*offlinefn)(int);
int (*statusfn)(void);
};
The members of the _p_k_t_d_r_i_v_e structure are:
_m_a_g_i_c Magic to identifier the file as a packet driver,
this is defined as ZS0PKTDRV
_t_y_p_e A pointer to the type of the device
_c_o_p_y_m_s_g
A pointer to the copyright message
_i_n_i_t_f_u_n_c
A function that initialises the device during the
initial configurationin this function.
_q_u_e_u_e_f_n
A function that stores outgoing backets in a queue
pending sending. Depending on the speed of the
device it may also inject packets into the inter-
face.
_p_a_c_k_e_t_f_n
A function that returns the address of the incoming
packet. This function is called immediately after
initialisation and after the _r_e_a_d_f_n function
(below) has returned a packet.
_s_e_n_d_f_n A function that is called on the interrupt to
inject bytes out of the interface. If this function
returns non-zero then packet at the address
returned is freed.
_r_e_a_d_f_n A function that is called on the interrupt to read
incoming bytes. If the function returns non-zero
then a packet is assumed to have been read, with
length as returned by readfn and lying at the
address specified by packetfn.
_o_n_l_i_n_e_f_n
A function that is called when the device is to be
turned online
_o_f_f_l_i_n_e_f_n
A function that is called when the device is to be
turned offline, if the parameter is non-zero then
the function should hang up line (if appropriate)
otherwise it should just suspend sending and
receiving packets.
_s_t_a_t_u_s_f_n
A function that returns the status of the device.
It is envisaged that it will return 0 for offline
and 1 for online though it may return other values.
The value returned is left for the user to under-
stand.
NNOOTTEESS
When the packet is passed to the driver for output a 4
bytes of header space is available at dp-4. The SLIP
driver by Dominic Morris utilises these bytes to implement
a linked list and to hold the length of the outgoing
packet.
Other packet drivers might wish to copy the packet to
their own address space for converting into other forms -
eg CSLIP form. Alternatively they might simply create a
link from their own space to the packet in the queue so to
reduce time wasted copying bytes.
AAUUTTHHOORR
Dominic Morris
18 February 2000 1
z88dk-1.8.ds1/doc/netman/cat3z/QueryPackage.3 0000644 0001750 0001750 00000002357 07130401727 020234 0 ustar tygrys tygrys
QueryPackage(3z) z88dk Programmer's Manual QueryPackage(3z)
NNAAMMEE
QueryPackage - open a shared library/package
SSYYNNOOPPSSIISS
##iinncclluuddee <>
bbooooll__tt QQuueerryyPPaacckkaaggee((cchhaarr _p_a_c_k_a_g_e,, cchhaarr _m_a_j_o_r ,, cchhaarr _m_i_n_o_r));;
DDEESSCCRRIIPPTTIIOONN
The QQuueerryyPPaacckkaaggee(()) function checks and makes available for
use the shared package _p_a_c_k_a_g_e with a version of at least
_m_i_n_o_r._m_i_n_o_r
The function initially checks for the presence of the
package subsystem and then proceeds to check for the spec-
ified package.
Version checking can be disabled by specifying _m_i_n_o_r and
_m_a_j_o_r to be 0.
RREETTUURRNN VVAALLUUEE
The QQuueerryyPPaacckkaaggee(()) function returns 0 on failure or 1 on
success. The carry flag is set accordingly and thus the
non-standard iferror { ... } construct can be used to
check for success.
18 February 2000 1
z88dk-1.8.ds1/doc/netman/cat3z/resolve.3 0000644 0001750 0001750 00000002311 07130401727 017320 0 ustar tygrys tygrys
resolve(3z) z88dk Programmer's Manual resolve(3z)
NNAAMMEE
resolve - convert hostname to IP address
SSYYNNOOPPSSIISS
##iinncclluuddee <>
iippaaddddrr__tt rreessoollvvee((cchhaarr **_n_a_m_e));;
DDEESSCCRRIIPPTTIIOONN
The rreessoollvvee(()) function queries any configured nameservers
for the IP address of the host with the name _n_a_m_e.
If _n_a_m_e is in the form a.b.c.d then this is converted to
an IP address and returned.
RREETTUURRNN VVAALLUUEE
rreessoollvv(()) returns the network order IP address of the
requested host. If the name cannot be resolved then NULL
is returned.
rreessoollvv(()) may also be called by the macro ggeetthhoossttbbyynnaammee
BBUUGGSS
If you use the macro ggeetthhoossttbbyynnaammee then beware that the
ZSock implementation is not at all standard.
AAUUTTHHOORR
Dominic Morris
18 February 2000 1
z88dk-1.8.ds1/doc/netman/cat3z/reverse_addr_lookup.3 0000644 0001750 0001750 00000003157 07130401727 021710 0 ustar tygrys tygrys
reverse_addr(3z) z88dk Programmer's Manual reverse_addr(3z)
NNAAMMEE
reverse_addr_lookup - convert IP address to hstname
SSYYNNOOPPSSIISS
##iinncclluuddee <>
bbooooll__tt rreevveerrssee__aaddddrr__llooookkuupp((iippaaddddrr__tt _i_p_a_d_d_r,, cchhaarr **_n_a_m_e));;
DDEESSCCRRIIPPTTIIOONN
The rreevveerrssee__aaddddrr__llooookkuupp(()) function queries any configured
nameservers for the name of the host with IP address
_i_p_a_d_d_r.
If _i_p_a_d_d_r is not known to the queried nameservers then the
_i_p_a_d_d_r is converted to the form a.b.c.d and returned.
RREETTUURRNN VVAALLUUEE
rreevveerrssee__aaddddrr__llooookkuupp(()) places the hostname in the buffer
specified by _n_a_m_e, no checks are made that this buffer is
large enough to hold the full hostname. The function
returns TRUE or FALSE depending on whether the queried
nameservers knew _i_p_a_d_d_r.
rreevveerrssee__aaddddrr__llooookkuupp(()) may also be called by the macro
ggeetthhoossttbbyyaaddddrr
BBUUGGSS
If you use the macro ggeetthhoossttbbyyaaddddrr then beware that the
ZSock implementation is not at all standard.
AAUUTTHHOORR
Dominic Morris
18 February 2000 1
z88dk-1.8.ds1/doc/netman/cat3z/sock_abort.3 0000644 0001750 0001750 00000001744 07130401727 020000 0 ustar tygrys tygrys
sock_abort(3z) z88dk Programmer's Manual sock_abort(3z)
NNAAMMEE
sock_abort - abort a network connection
SSYYNNOOPPSSIISS
##iinncclluuddee <>
vvooiidd ssoocckk__aabboorrtt((SSOOCCKKEETT **_s_)_;
DDEESSCCRRIIPPTTIIOONN
The parameter _s is a descriptor to an open socket created
using ssoocckk__ooppeenn((33zz)) or ssoocckk__lliisstteenn((33zz)).
The ssoocckk__aabboorrtt(()) function will immediately move a socket
into a closed state disallowing any further reads or
writes.
RREETTUURRNN VVAALLUUEE
None
SSEEEE AALLSSOO
ssoocckk__cclloossee(3z), ssoocckk__sshhuuttddoowwnn(3z)
AAUUTTHHOORR
Dominic Morris
18 February 2000 1
z88dk-1.8.ds1/doc/netman/cat3z/sock_close.3 0000644 0001750 0001750 00000002127 07130401730 017764 0 ustar tygrys tygrys
sock_close(3z) z88dk Programmer's Manual sock_close(3z)
NNAAMMEE
sock_close - close a network connection
SSYYNNOOPPSSIISS
##iinncclluuddee <>
vvooiidd ssoocckk__cclloossee((SSOOCCKKEETT **_s_)_;
DDEESSCCRRIIPPTTIIOONN
The parameter _s is a descriptor to an open socket created
using ssoocckk__ooppeenn((33zz)) or ssoocckk__lliisstteenn((33zz)).
The ssoocckk__cclloossee(()) function will initiate a close on the
socket specified by _s. Once this function has been called
no more data can be written to the socket. If the socket
is of type prot_TCP then data can continue to be read.
RREETTUURRNN VVAALLUUEE
None
SSEEEE AALLSSOO
ssoocckk__aabboorrtt(3z), ssoocckk__sshhuuttddoowwnn(3z)
AAUUTTHHOORR
Dominic Morris
18 February 2000 1
z88dk-1.8.ds1/doc/netman/cat3z/sock_closed.3 0000644 0001750 0001750 00000002147 07130401730 020132 0 ustar tygrys tygrys
sock_closed(3z) z88dk Programmer's Manual sock_closed(3z)
NNAAMMEE
sock_closed - test whether a network connection is closed
SSYYNNOOPPSSIISS
##iinncclluuddee <>
bbooooll__tt ssoocckk__cclloosseedd((SSOOCCKKEETT **_s_)_;
DDEESSCCRRIIPPTTIIOONN
The parameter _s is a descriptor to a socket created using
ssoocckk__ooppeenn((33zz)) or ssoocckk__lliisstteenn((33zz)).
The ssoocckk__cclloosseedd(()) function tests whether a socket is
closed i.e. connection to a remote host has not been
established or has already been closed by the kernel.
A socket of prot_UDP is never closed.
RREETTUURRNN VVAALLUUEE
ssoocckk__cclloosseedd(()) returns TRUE or FALSE
SSEEEE AALLSSOO
ssoocckk__ooppeenneedd(3z)
AAUUTTHHOORR
Dominic Morris
18 February 2000 1
z88dk-1.8.ds1/doc/netman/cat3z/sock_dataready.3 0000644 0001750 0001750 00000002104 07130401730 020610 0 ustar tygrys tygrys
sock_dataready(3z) z88dk Programmer's Manual sock_dataready(3z)
NNAAMMEE
sock_dataready - test whether a network connection has
incoming data
SSYYNNOOPPSSIISS
##iinncclluuddee <>
ssiizzee__tt ssoocckk__ddaattaarreeaaddyy((SSOOCCKKEETT **_s_)_;
DDEESSCCRRIIPPTTIIOONN
The parameter _s is a descriptor to an open socket created
using ssoocckk__ooppeenn((33zz)) or ssoocckk__lliisstteenn((33zz)).
The ssoocckk__ddaattaarreeaaddyy(()) function tests whether a socket has
data waiting to be read by the user program.
RREETTUURRNN VVAALLUUEE
ssoocckk__ddaattaarreeaaddyy(()) returns the amount of data waiting in the
input queue.
SSEEEE AALLSSOO
ssoocckk__rreeaadd(3z)
AAUUTTHHOORR
Dominic Morris
18 February 2000 1
z88dk-1.8.ds1/doc/netman/cat3z/sock_flush.3 0000644 0001750 0001750 00000001746 07130401730 020006 0 ustar tygrys tygrys
sock_flush(3z) z88dk Programmer's Manual sock_flush(3z)
NNAAMMEE
sock_flush - flush a network connection
SSYYNNOOPPSSIISS
##iinncclluuddee <>
vvooiidd ssoocckk__fflluusshh((SSOOCCKKEETT **_s_)_;
DDEESSCCRRIIPPTTIIOONN
The parameter _s is a descriptor to an open socket created
using ssoocckk__ooppeenn((33zz)) or ssoocckk__lliisstteenn((33zz)). The socket should
be of type prot_TCP.
The ssoocckk__fflluusshh(()) function will depending on the state of
the connection either immediately send any pending data in
the socket buffer or flag the data for sending in the next
timer call.
RREETTUURRNN VVAALLUUEE
None
AAUUTTHHOORR
Dominic Morris
18 February 2000 1
z88dk-1.8.ds1/doc/netman/cat3z/sock_listen.3 0000644 0001750 0001750 00000003326 07130401730 020157 0 ustar tygrys tygrys
sock_listen(3z) z88dk Programmer's Manual sock_listen(3z)
NNAAMMEE
sock_listen - open a passive network connection
SSYYNNOOPPSSIISS
##iinncclluuddee <>
SSOOCCKKEETT **ssoocckk__lliisstteenn((iippaaddddrr__tt _i_p_d_e_s_t,, ttccppppoorrtt__tt _l_p_o_r_t,,
vvooiidd _(_*_h_a_n_d_l_e_r_)_(_),, cchhaarr _p_r_o_t_o_)_;
DDEESSCCRRIIPPTTIIOONN
The ssoocckk__lliisstteenn(()) function creates a socket descriptor for
a passive (i.e. listening) connection on local port _l_p_o_r_t
awaiting a connection from host _i_p_d_e_s_t. At the moment only
protocols prot_UDP and prot_TCP are supported.
To accept connections from any host specify the parameter
_i_p_d_e_s_t to be 0L.
The parameter _h_a_n_d_l_e_r specifies a handler to be called
whenever the connection changes state or new data arrives.
It should be the code for a package routine.
The input parameters of the function _h_a_n_d_l_e_r vary depend-
ing on whether the socket is of type prot_UDP or prot_TCP.
RREETTUURRNN VVAALLUUEE
ssoocckk__lliisstteenn(()) returns a socket descriptor. Specifying a
non support protocol will result in the carry flag being
set and the return value being EPROTONOSUPPORT.
SSEEEE AALLSSOO
ssoocckk__ooppeenn(3z)
AAUUTTHHOORR
Dominic Morris
18 February 2000 1
z88dk-1.8.ds1/doc/netman/cat3z/sock_open.3 0000644 0001750 0001750 00000002720 07130401730 017617 0 ustar tygrys tygrys
sock_open(3z) z88dk Programmer's Manual sock_open(3z)
NNAAMMEE
sock_open - open an active network connection
SSYYNNOOPPSSIISS
##iinncclluuddee <>
SSOOCCKKEETT **ssoocckk__ooppeenn((iippaaddddrr__tt _i_p_d_e_s_t,, ttccppppoorrtt__tt _d_p_o_r_t,,
vvooiidd _(_*_h_a_n_d_l_e_r_)_(_),, cchhaarr _p_r_o_t_o_)_;
DDEESSCCRRIIPPTTIIOONN
The ssoocckk__ooppeenn(()) function creates a socket descriptor and
attempts to establish a connection to the port _d_p_o_r_t on
the host _i_p_d_e_s_t using the protocol _p_r_o_t_o. At the moment
only protocols prot_UDP and prot_TCP are supported.
The parameter _h_a_n_d_l_e_r specifies a handler to be called
whenever the connection changes state or new data arrives.
It is of archaic interest only.
RREETTUURRNN VVAALLUUEE
ssoocckk__ooppeenn(()) returns a socket descriptor. Specifying a non-
supported protocol will result in the carry flag being set
and the return value being EPROTONOSUPPORT.
SSEEEE AALLSSOO
ssoocckk__lliisstteenn(3z)
AAUUTTHHOORR
Dominic Morris
18 February 2000 1
z88dk-1.8.ds1/doc/netman/cat3z/sock_opened.3 0000644 0001750 0001750 00000002073 07130401730 020131 0 ustar tygrys tygrys
sock_opened(3z) z88dk Programmer's Manual sock_opened(3z)
NNAAMMEE
sock_opened - test whether a network connection is estab-
lished
SSYYNNOOPPSSIISS
##iinncclluuddee <>
bbooooll__tt ssoocckk__ooppeenneedd((SSOOCCKKEETT **_s_)_;
DDEESSCCRRIIPPTTIIOONN
The parameter _s is a descriptor to a socket created using
ssoocckk__ooppeenn((33zz)) or ssoocckk__lliisstteenn((33zz)).
The ssoocckk__ooppeenneedd(()) function tests whether a socket is open
i.e. connection to a remote host has been established.
A socket of prot_UDP is always established.
RREETTUURRNN VVAALLUUEE
ssoocckk__ooppeenneedd(()) returns TRUE or FALSE
SSEEEE AALLSSOO
ssoocckk__cclloosseedd(3z)
AAUUTTHHOORR
Dominic Morris
18 February 2000 1
z88dk-1.8.ds1/doc/netman/cat3z/sock_putc.3 0000644 0001750 0001750 00000002266 07130401730 017636 0 ustar tygrys tygrys
sock_putc(3z) z88dk Programmer's Manual sock_putc(3z)
NNAAMMEE
sock_putc - write byte to a network socket
SSYYNNOOPPSSIISS
##iinncclluuddee <>
ssiizzee__tt ssoocckk__ppuuttcc((cchhaarr _c,, SSOOCCKKEETT **_s));;
DDEESSCCRRIIPPTTIIOONN
The parameter _s is a descriptor to an open socket created
using ssoocckk__ooppeenn((33zz)) or ssoocckk__lliisstteenn((33zz))
The ssoocckk__ppuuttcc(()) function writes a single byte _c to the
socket specified by _s.
RREETTUURRNN VVAALLUUEE
The ssoocckk__wwrriittee(()) function returns the number of bytes
written to the socket (i.e. 0 or 1). If an illegal socket
is supplied the carry flag will be set and the return
value will be EPROTONOSUPPORT.
SSEEEE AALLSSOO
ssoocckk__wwrriittee(3z), ssoocckk__ppuuttss(3z)
AAUUTTHHOORR
Dominic Morris
18 February 2000 1
z88dk-1.8.ds1/doc/netman/cat3z/sock_puts.3 0000644 0001750 0001750 00000002276 07130401730 017657 0 ustar tygrys tygrys
sock_puts(3z) z88dk Programmer's Manual sock_puts(3z)
NNAAMMEE
sock_write - write string to a network socket
SSYYNNOOPPSSIISS
##iinncclluuddee <>
ssiizzee__tt ssoocckk__ppuuttss((SSOOCCKKEETT **_s,, cchhaarr **_d_p));;
DDEESSCCRRIIPPTTIIOONN
The parameter _s is a descriptor to an open socket created
using ssoocckk__ooppeenn((33zz)) or ssoocckk__lliisstteenn((33zz))
The ssoocckk__ppuuttss(()) function writes the NULL terminated string
_d_p to the socket specified by _s.
RREETTUURRNN VVAALLUUEE
The ssoocckk__wwrriittee(()) function returns the number of bytes
written to the socket. If an illegal socket is supplied
the carry flag will be set and the return value will be
EPROTONOSUPPORT.
SSEEEE AALLSSOO
ssoocckk__wwrriittee(3z), ssoocckk__ppuuttcc(3z)
AAUUTTHHOORR
Dominic Morris
18 February 2000 1
z88dk-1.8.ds1/doc/netman/cat3z/sock_read.3 0000644 0001750 0001750 00000002300 07130401730 017563 0 ustar tygrys tygrys
sock_read(3z) z88dk Programmer's Manual sock_read(3z)
NNAAMMEE
sock_read - read bytes from a network socket
SSYYNNOOPPSSIISS
##iinncclluuddee <>
ssiizzee__tt ssoocckk__rreeaadd((SSOOCCKKEETT ** _s,, vvooiidd ** _d_p ,, ssiizzee__tt _l_e_n));;
DDEESSCCRRIIPPTTIIOONN
The parameter _s is a descriptor to an open socket created
using ssoocckk__ooppeenn((33zz)) or ssoocckk__lliisstteenn((33zz))
The ssoocckk__rreeaadd(()) function reads at most _l_e_n bytes from the
socket _s and places them at _d_p. _d_p which should be in the
lower 16k of the memory map.
RREETTUURRNN VVAALLUUEE
The ssoocckk__rreeaadd(()) function returns the number of bytes read
from the socket. If an illegal socket is supplied the
carry flag will be set and the return value will be
EPROTONOSUPPORT.
AAUUTTHHOORR
Dominic Morris
18 February 2000 1
z88dk-1.8.ds1/doc/netman/cat3z/sock_shutdown.3 0000644 0001750 0001750 00000002140 07130401730 020525 0 ustar tygrys tygrys
sock_shutdown(3z) z88dk Programmer's Manual sock_shutdown(3z)
NNAAMMEE
sock_shutdown - abort a network connection
SSYYNNOOPPSSIISS
##iinncclluuddee <>
vvooiidd ssoocckk__cclloossee((SSOOCCKKEETT **_s_)_;
DDEESSCCRRIIPPTTIIOONN
The parameter _s is a descriptor to an open socket created
using ssoocckk__ooppeenn((33zz)) or ssoocckk__lliisstteenn((33zz)).
The ssoocckk__sshhuuttddoowwnn(()) function wipes all trace of the socket
_s from the system. It should be preceded by either a
ssoocckk__cclloossee((33zz)) or ssoocckk__aabboorrtt((33zz)) depending on the circum-
stances.
RREETTUURRNN VVAALLUUEE
None
SSEEEE AALLSSOO
ssoocckk__cclloossee(3z), ssoocckk__aabboorrtt(3z)
AAUUTTHHOORR
Dominic Morris
18 February 2000 1
z88dk-1.8.ds1/doc/netman/cat3z/sock_write.3 0000644 0001750 0001750 00000002530 07130401730 020007 0 ustar tygrys tygrys
sock_write(3z) z88dk Programmer's Manual sock_write(3z)
NNAAMMEE
sock_write - write bytes to a network socket
SSYYNNOOPPSSIISS
##iinncclluuddee <>
ssiizzee__tt ssoocckk__wwrriittee((SSOOCCKKEETT **_s,, vvooiidd **_d_p ,, ssiizzee__tt _l_e_n));;
DDEESSCCRRIIPPTTIIOONN
The parameter _s is a descriptor to an open socket created
using ssoocckk__ooppeenn((33zz)) or ssoocckk__lliisstteenn((33zz))
The ssoocckk__wwrriittee(()) function writes a stream of bytes to the
open socket specified by _s. The data of length _l_e_n is
taken from address _d_p which should be in the lower 16k of
the memory map.
RREETTUURRNN VVAALLUUEE
The ssoocckk__wwrriittee(()) function returns the number of bytes
written to the socket. If an illegal socket is supplied
the carry flag will be set and the return value will be
EPROTONOSUPPORT.
SSEEEE AALLSSOO
ssoocckk__ppuuttcc(3z), ssoocckk__ppuuttss(3z)
AAUUTTHHOORR
Dominic Morris
18 February 2000 1
z88dk-1.8.ds1/doc/netman/cat3z/tcp_calloc.3 0000644 0001750 0001750 00000004773 07130401730 017754 0 ustar tygrys tygrys
tcp_malloc(3) z88dk Programmer's Manual tcp_malloc(3)
NNAAMMEE
tcp_calloc, tcp_malloc, tcp_free - Allocate and free mem-
ory
SSYYNNOOPPSSIISS
##iinncclluuddee <>
vvooiidd **ttccpp__ccaalllloocc((ssiizzee__tt _n_m_e_m_b,, ssiizzee__tt _s_i_z_e));;
vvooiidd **ttccpp__mmaalllloocc((ssiizzee__tt _s_i_z_e));;
vvooiidd ttccpp__ffrreeee((vvooiidd _*_p_t_r));;
DDEESSCCRRIIPPTTIIOONN
ccaalllloocc(()) allocates memory for an array of _n_m_e_m_b elements
of _s_i_z_e bytes each and returns a pointer to the allocated
memory. The memory is set to zero.
mmaalllloocc(()) allocates _s_i_z_e bytes and returns a pointer to the
allocated memory. The memory is not cleared.
ffrreeee(()) frees the memory space pointed to by _p_t_r, which
must have been returned by a previous call to mmaalllloocc(()) or
ccaalllloocc(()) Otherwise, or if ffrreeee((_p_t_r)) has already been
called before, undefined behaviour occurs. If _p_t_r is
NNUULLLL, no operation is performed.
RREETTUURRNN VVAALLUUEESS
For ccaalllloocc(()) and mmaalllloocc(()), the value returned is a pointer
to the allocated memory, which is suitably aligned for any
kind of variable, or NNUULLLL if the request fails.
ffrreeee(()) returns no value.
SSEEEE AALLSSOO
ttccpp__ppaaggeeiinn(3z) ,ttccpp__ppaaggeeoouutt(3z)
NNOOTTEESS
These functions manipulate memory in a private memory page
belonging to ZSock. This 16k page holds all the buffers
that ZSock uses and hence requests for large amounts of
memory are likely to fail (and in any case are not recom-
mended).
This facility has been offered to allow daemons to be
written simply (they have no address space of their own).
User applications should not use these facilities. If a
large (>256 bytes) amount of memory is required for a user
application then the application should either be of the
BAD type or be redesigned.
AAUUTTHHOORR
Dominic Morris
February 18 2000 1
z88dk-1.8.ds1/doc/netman/cat3z/tcp_free.3 0000644 0001750 0001750 00000004773 07130401730 017440 0 ustar tygrys tygrys
tcp_malloc(3) z88dk Programmer's Manual tcp_malloc(3)
NNAAMMEE
tcp_calloc, tcp_malloc, tcp_free - Allocate and free mem-
ory
SSYYNNOOPPSSIISS
##iinncclluuddee <>
vvooiidd **ttccpp__ccaalllloocc((ssiizzee__tt _n_m_e_m_b,, ssiizzee__tt _s_i_z_e));;
vvooiidd **ttccpp__mmaalllloocc((ssiizzee__tt _s_i_z_e));;
vvooiidd ttccpp__ffrreeee((vvooiidd _*_p_t_r));;
DDEESSCCRRIIPPTTIIOONN
ccaalllloocc(()) allocates memory for an array of _n_m_e_m_b elements
of _s_i_z_e bytes each and returns a pointer to the allocated
memory. The memory is set to zero.
mmaalllloocc(()) allocates _s_i_z_e bytes and returns a pointer to the
allocated memory. The memory is not cleared.
ffrreeee(()) frees the memory space pointed to by _p_t_r, which
must have been returned by a previous call to mmaalllloocc(()) or
ccaalllloocc(()) Otherwise, or if ffrreeee((_p_t_r)) has already been
called before, undefined behaviour occurs. If _p_t_r is
NNUULLLL, no operation is performed.
RREETTUURRNN VVAALLUUEESS
For ccaalllloocc(()) and mmaalllloocc(()), the value returned is a pointer
to the allocated memory, which is suitably aligned for any
kind of variable, or NNUULLLL if the request fails.
ffrreeee(()) returns no value.
SSEEEE AALLSSOO
ttccpp__ppaaggeeiinn(3z) ,ttccpp__ppaaggeeoouutt(3z)
NNOOTTEESS
These functions manipulate memory in a private memory page
belonging to ZSock. This 16k page holds all the buffers
that ZSock uses and hence requests for large amounts of
memory are likely to fail (and in any case are not recom-
mended).
This facility has been offered to allow daemons to be
written simply (they have no address space of their own).
User applications should not use these facilities. If a
large (>256 bytes) amount of memory is required for a user
application then the application should either be of the
BAD type or be redesigned.
AAUUTTHHOORR
Dominic Morris
February 18 2000 1
z88dk-1.8.ds1/doc/netman/cat3z/tcp_malloc.3 0000644 0001750 0001750 00000004773 07130401730 017766 0 ustar tygrys tygrys
tcp_malloc(3) z88dk Programmer's Manual tcp_malloc(3)
NNAAMMEE
tcp_calloc, tcp_malloc, tcp_free - Allocate and free mem-
ory
SSYYNNOOPPSSIISS
##iinncclluuddee <>
vvooiidd **ttccpp__ccaalllloocc((ssiizzee__tt _n_m_e_m_b,, ssiizzee__tt _s_i_z_e));;
vvooiidd **ttccpp__mmaalllloocc((ssiizzee__tt _s_i_z_e));;
vvooiidd ttccpp__ffrreeee((vvooiidd _*_p_t_r));;
DDEESSCCRRIIPPTTIIOONN
ccaalllloocc(()) allocates memory for an array of _n_m_e_m_b elements
of _s_i_z_e bytes each and returns a pointer to the allocated
memory. The memory is set to zero.
mmaalllloocc(()) allocates _s_i_z_e bytes and returns a pointer to the
allocated memory. The memory is not cleared.
ffrreeee(()) frees the memory space pointed to by _p_t_r, which
must have been returned by a previous call to mmaalllloocc(()) or
ccaalllloocc(()) Otherwise, or if ffrreeee((_p_t_r)) has already been
called before, undefined behaviour occurs. If _p_t_r is
NNUULLLL, no operation is performed.
RREETTUURRNN VVAALLUUEESS
For ccaalllloocc(()) and mmaalllloocc(()), the value returned is a pointer
to the allocated memory, which is suitably aligned for any
kind of variable, or NNUULLLL if the request fails.
ffrreeee(()) returns no value.
SSEEEE AALLSSOO
ttccpp__ppaaggeeiinn(3z) ,ttccpp__ppaaggeeoouutt(3z)
NNOOTTEESS
These functions manipulate memory in a private memory page
belonging to ZSock. This 16k page holds all the buffers
that ZSock uses and hence requests for large amounts of
memory are likely to fail (and in any case are not recom-
mended).
This facility has been offered to allow daemons to be
written easily (they have no address space of their own).
User applications should not use these facilities. If a
large (>256 bytes) amount of memory is required for a user
application then the application should either be of the
BAD type or be redesigned.
AAUUTTHHOORR
Dominic Morris
February 18 2000 1
z88dk-1.8.ds1/doc/netman/cat3z/tcp_pagein.3 0000644 0001750 0001750 00000002231 07130401730 017745 0 ustar tygrys tygrys
tcp_pagein(3z) z88dk Programmer's Manual tcp_pagein(3z)
NNAAMMEE
tcp_pagein - page the ZSock data area into the memory map
SSYYNNOOPPSSIISS
##iinncclluuddee <>
uu88__tt ttccpp__ppaaggeeiinn((vvooiidd));;
DDEESSCCRRIIPPTTIIOONN
The ttccpp__ppaaggeeiinn(()) function pages in the ZSock data area
into segment 1 (addresses 16384-32767) of the z88s memory
map.
This function is primarily of use to daemons which use the
ZSock dataarea for small amounts of storage.
RREETTUURRNN VVAALLUUEE
ttccpp__ppaaggeeiinn(()) returns the previous binding of segment 1
which should be used as a parameter to ttccpp__ppaaggeeoouutt(3z)
SSEEEE AALLSSOO
ttccpp__ppaaggeeoouutt(3z), ttccpp__mmaalllloocc(3z), ttccpp__ccaalllloocc(3z)
ttccpp__ffrreeee(3z)
AAUUTTHHOORR
Dominic Morris
18 February 2000 1
z88dk-1.8.ds1/doc/netman/cat3z/tcp_pageout.3 0000644 0001750 0001750 00000002717 07130401730 020157 0 ustar tygrys tygrys
tcp_pageout(3z) z88dk Programmer's Manual tcp_pageout(3z)
NNAAMMEE
tcp_pageout - page the ZSock data area out of the memory
map
SSYYNNOOPPSSIISS
##iinncclluuddee <>
vvooiidd ttccpp__ppaaggeeoouutt((uu88__tt _o_l_d_b_i_n_d_i_n_g_)_;
DDEESSCCRRIIPPTTIIOONN
The ttccpp__ppaaggeeoouutt(()) function pages out the ZSock data area
into segment 1 (addresses 16384-32767) of the z88s memory
map.
The parameter _o_l_d_b_i_n_d_i_n_g is the return value from a prior
ttccpp__ppaaggeeiinn((33zz)) function.
This function is primarily of use to daemons which use the
ZSock dataarea for small amounts of storage.
RREETTUURRNN VVAALLUUEE
ttccpp__ppaaggeeiinn(()) returns the previous binding of segment 1
which should be used as a parameter to ttccpp__ppaaggeeoouutt(3z)
SSEEEE AALLSSOO
ttccpp__ppaaggeeiinn(3z), ttccpp__mmaalllloocc(3z), ttccpp__ccaalllloocc(3z)
ttccpp__ffrreeee(3z)
BBUUGGSS
Supplying an incorrect _o_l_d_b_i_n_d_i_n_g will most likely crash
the z88.
AAUUTTHHOORR
Dominic Morris
18 February 2000 1
z88dk-1.8.ds1/doc/netman/cat3z/tcp_RegCatchall.3 0000644 0001750 0001750 00000004223 07130401730 020656 0 ustar tygrys tygrys
tcp_RegCatchall(3z) z88dk Programmer's Manual tcp_RegCatchall(3z)
NNAAMMEE
tcp_RegCatchall - (De)register packet catcher
SSYYNNOOPPSSIISS
##iinncclluuddee <>
iinntt ttccpp__RReeggCCaattcchhaallll((iinntt _l_i_b_c_a_l_l));;
DDEESSCCRRIIPPTTIIOONN
The ttccpp__RReeggCCaattcchhaallll(()) function registers or deregisters a
function that is used to catch all incoming packets after
it has passed the basic tests of checksumming, length and
ttl-checking. l-checking.
The parameter lliibbccaallll is the ID for a shared
library/packet call which has the prototype thus:
bbooooll__tt FFuunnccttiioonn((vvooiidd **_d_p,, ssiizzee__tt _l_e_n));;
Where _d_p is the address of the packet and _l_e_n is the
length of the packet. This function should return
TRUE/FALSE to indicate to the ZSock kernel whether the
function has dealt with the packet and ZSock should not
process it.
RREETTUURRNN VVAALLUUEE
ttccpp__RReeggCCaattcchhaallll(()) returns the previous ID of the catchall
function.
NNOOTTEESS
Should you wish to stop calling your catchall function
simply call the function with an argument of NULL.
This function is of use should somebody write a driver for
an as yet unsupported protocol.
The package call should page in the ZSock data area using
the function ttccpp__ppaaggeeiinn((33zz)).
This call could for example be used to implement a tracer-
oute style routine to catch ICMP replies. Returning TRUE
when it has received an ICMP reply packet of the correct
tyoe, and FALSE otherwise.
SSEEEE AALLSSOO
ttccpp__ppaaggeeiinn(3z), ttccpp__ppaaggeeoouutt(3z)
AAUUTTHHOORR
Dominic Morris
18 February 2000 1
z88dk-1.8.ds1/doc/netman/man3z/ 0000755 0001750 0001750 00000000000 10765202715 015570 5 ustar tygrys tygrys z88dk-1.8.ds1/doc/netman/man3z/byteorder.3 0000644 0001750 0001750 00000005470 07130401730 017647 0 ustar tygrys tygrys .\" Copyright 1993 David Metcalfe (david@prism.demon.co.uk)
.\"
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one
.\"
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date. The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein. The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\"
.\" References consulted:
.\" Linux libc source code
.\" Lewine's _POSIX Programmer's Guide_ (O'Reilly & Associates, 1991)
.\" 386BSD man pages
.\" Modified Sat Jul 24 21:29:05 1993 by Rik Faith (faith@cs.unc.edu)
.\" z88dk version 18/2/2000
.TH byteorder 3 "February 18 2000" "BSD" "z88dk Programmer's Manual"
.SH NAME
htonl, htons, ntohl, ntohs \- convert values between host and network
byte order
.SH SYNOPSIS
.nf
.B #include
.sp
.BI "unsigned long int htonl(unsigned long int " hostlong );
.sp
.BI "unsigned short int htons(unsigned short int " hostshort );
.sp
.BI "unsigned long int ntohl(unsigned long int " netlong );
.sp
.BI "unsigned short int ntohs(unsigned short int " netshort );
.fi
.SH DESCRIPTION
The \fBhtonl()\fP function converts the long integer \fIhostlong\fP
from host byte order to network byte order.
.PP
The \fBhtons()\fP function converts the short integer \fIhostshort\fP
from host byte order to network byte order.
.PP
The \fBntohl()\fP function converts the long integer \fInetlong\fP
from network byte order to host byte order.
.PP
The \fBntohs()\fP function converts the short integer \fInetshort\fP
from network byte order to host byte order.
.PP
On the z80 the host byte order is Least Significant Byte first,
whereas the network byte order, as used on the Internet, is Most
Significant Byte first.
.SH "CONFORMING TO"
BSD 4.3
.SH NOTES
Unlike on other machines these functions are not provided through
macros - they are instead functions kept in z80_crt0.lib. The
optimization rules supplied with z88dk are aware of these routines
and when appropriate optimize the function call away.
.SH AUTHOR
Dominic Morris
.PP
Original manual page by David Metcalfe
z88dk-1.8.ds1/doc/netman/man3z/DeviceOffline.3 0000755 0001750 0001750 00000002030 07130401730 020342 0 ustar tygrys tygrys .TH DeviceOffline 3z "18 February 2000" "" "z88dk Programmer's Manual"
.SH NAME
DeviceOffline \- turn the network device online
.SH SYNOPSIS
.nf
.B #include
.sp
.BI "void DeviceOffline(int "flag );
.fi
.SH DESCRIPTION
The \fBDeviceOffline()\fP function turns the packet driver offline
so that other application may utilise the resources that it is using.
.PP
For example for the built in SLIP driver, turning the device online
prevents polling of the serial port for incoming bytes and the sending
of queued packets, thus allowing another program (e.g. Terminal) to
use the serial port.
.PP
The parameter \fIflag\fP specifies how the device is to be turned
offline, with current device drivers this has no significence. However
it is envisaged that the value NOHANGUP the device will simply
suspend sending and receiving packets. Whilst with HANGUP the
device will hangup the line and terminate the telephone connection.
.SH "RETURN VALUE"
None.
.SH "SEE ALSO"
.BR DeviceOnline "(3z)"
.SH AUTHOR
Dominic Morris
z88dk-1.8.ds1/doc/netman/man3z/DeviceOnline.3 0000755 0001750 0001750 00000001033 07130401730 020206 0 ustar tygrys tygrys .TH DeviceOnline 3z "18 February 2000" "" "z88dk Programmer's Manual"
.SH NAME
DeviceOnline \- turn the network device online
.SH SYNOPSIS
.nf
.B #include
.sp
.BI "void DeviceOnline(void);
.fi
.SH DESCRIPTION
The \fBDeviceOnline()\fP function turns the packet driver back on
again after it has been previously turned offline by \fBDeviceOffline(3z)\fP.
How this is achieved depends on the device driver in use.
.SH "RETURN VALUE"
None.
.SH "SEE ALSO"
.BR DeviceOffline "(3z)"
.SH AUTHOR
Dominic Morris
z88dk-1.8.ds1/doc/netman/man3z/getnetbyname.3 0000755 0001750 0001750 00000001534 07130401730 020332 0 ustar tygrys tygrys .TH getnetbyname 3z "18 February 2000" "" "z88dk Programmer's Manual"
.SH NAME
getnetbyname, getnetbynumber \- get network entry
.SH SYNOPSIS
.nf
.B #include
.sp
.BI "int getnetbyname(char *"name );
.BI "char *getnetbynumber(int "network ", char * "buf );
.fi
.SH DESCRIPTION
The \fBgetnetbyname()\fP function returns the standard number for
the network with the name \fIname\fP. If no network is known then
NULL is returned.
.PP
The \fBgetnetbynumber()\fP function copies into \fIbuf\fP (and returns
\fIbuf\fP) the network matching the \fInetwork\fP. If no
network is known then \fInetwork\fP is returned in ASCII form.
.SH "RETURN VALUE"
Detailed above.
.SH NOTES
These functions use a lookup table compiled into the ZSock kernel,
it is not likely that method will change in the near future.
.SH AUTHOR
Dominic Morris
z88dk-1.8.ds1/doc/netman/man3z/getnetbynumber.3 0000755 0001750 0001750 00000001534 07130401730 020702 0 ustar tygrys tygrys .TH getnetbyname 3z "18 February 2000" "" "z88dk Programmer's Manual"
.SH NAME
getnetbyname, getnetbynumber \- get network entry
.SH SYNOPSIS
.nf
.B #include
.sp
.BI "int getnetbyname(char *"name );
.BI "char *getnetbynumber(int "network ", char * "buf );
.fi
.SH DESCRIPTION
The \fBgetnetbyname()\fP function returns the standard number for
the network with the name \fIname\fP. If no network is known then
NULL is returned.
.PP
The \fBgetnetbynumber()\fP function copies into \fIbuf\fP (and returns
\fIbuf\fP) the network matching the \fInetwork\fP. If no
network is known then \fInetwork\fP is returned in ASCII form.
.SH "RETURN VALUE"
Detailed above.
.SH NOTES
These functions use a lookup table compiled into the ZSock kernel,
it is not likely that method will change in the near future.
.SH AUTHOR
Dominic Morris
z88dk-1.8.ds1/doc/netman/man3z/getprotobyname.3 0000755 0001750 0001750 00000001562 07130401730 020710 0 ustar tygrys tygrys .TH getprotobyname 3z "18 February 2000" "" "z88dk Programmer's Manual"
.SH NAME
getprotobyname, getprotobynumber \- get protocol entry
.SH SYNOPSIS
.nf
.B #include
.sp
.BI "int getprotobyname(char *"name );
.BI "char *getprotobynumber(int "protocol ", char * "buf );
.fi
.SH DESCRIPTION
The \fBgetprotobyname()\fP function returns the standard number for
the protocol with the name \fIname\fP. If no protocol is known then
NULL is returned.
.PP
The \fBgetprotobynumber()\fP function copies into \fIbuf\fP (and returns
\fIbuf\fP) the protocol matching the \fIprotocol\fP. If no
protocol is known then \fIprotocol\fP is returned in ASCII form.
.SH "RETURN VALUE"
Detailed above.
.SH NOTES
These functions use a lookup table compiled into the ZSock kernel,
it is not likely that method will change in the near future.
.SH AUTHOR
Dominic Morris
z88dk-1.8.ds1/doc/netman/man3z/getprotobynumber.3 0000755 0001750 0001750 00000001562 07130401730 021260 0 ustar tygrys tygrys .TH getprotobyname 3z "18 February 2000" "" "z88dk Programmer's Manual"
.SH NAME
getprotobyname, getprotobynumber \- get protocol entry
.SH SYNOPSIS
.nf
.B #include
.sp
.BI "int getprotobyname(char *"name );
.BI "char *getprotobynumber(int "protocol ", char * "buf );
.fi
.SH DESCRIPTION
The \fBgetprotobyname()\fP function returns the standard number for
the protocol with the name \fIname\fP. If no protocol is known then
NULL is returned.
.PP
The \fBgetprotobynumber()\fP function copies into \fIbuf\fP (and returns
\fIbuf\fP) the protocol matching the \fIprotocol\fP. If no
protocol is known then \fIprotocol\fP is returned in ASCII form.
.SH "RETURN VALUE"
Detailed above.
.SH NOTES
These functions use a lookup table compiled into the ZSock kernel,
it is not likely that method will change in the near future.
.SH AUTHOR
Dominic Morris
z88dk-1.8.ds1/doc/netman/man3z/getservbyname.3 0000755 0001750 0001750 00000001554 07130401730 020525 0 ustar tygrys tygrys .TH getservbyname 3z "18 February 2000" "" "z88dk Programmer's Manual"
.SH NAME
getservbyname, getservbyport \- get service entry
.SH SYNOPSIS
.nf
.B #include
.sp
.BI "tcpport_t getservbyname(char *"name );
.BI "char *getservbyport(tcpport_t "port ", char * "buf );
.fi
.SH DESCRIPTION
The \fBgetservbyname()\fP function returns the standard port for
the service with the name \fIname\fP. If no service is known then
NULL is returned.
.PP
The \fBgetservbyport()\fP function copies into \fIbuf\fP (and returns
\fIbuf\fP) the service matching the standard port \fIport\fP. If no
service is known then \fIport\fP is returned in ASCII form.
.SH "RETURN VALUE"
Detailed above.
.SH NOTES
These functions use a lookup table compiled into the ZSock kernel,
it is not likely that method will change in the near future.
.SH AUTHOR
Dominic Morris
z88dk-1.8.ds1/doc/netman/man3z/getservbyport.3 0000755 0001750 0001750 00000001554 07130401730 020571 0 ustar tygrys tygrys .TH getservbyname 3z "18 February 2000" "" "z88dk Programmer's Manual"
.SH NAME
getservbyname, getservbyport \- get service entry
.SH SYNOPSIS
.nf
.B #include
.sp
.BI "tcpport_t getservbyname(char *"name );
.BI "char *getservbyport(tcpport_t "port ", char * "buf );
.fi
.SH DESCRIPTION
The \fBgetservbyname()\fP function returns the standard port for
the service with the name \fIname\fP. If no service is known then
NULL is returned.
.PP
The \fBgetservbyport()\fP function copies into \fIbuf\fP (and returns
\fIbuf\fP) the service matching the standard port \fIport\fP. If no
service is known then \fIport\fP is returned in ASCII form.
.SH "RETURN VALUE"
Detailed above.
.SH NOTES
These functions use a lookup table compiled into the ZSock kernel,
it is not likely that method will change in the near future.
.SH AUTHOR
Dominic Morris
z88dk-1.8.ds1/doc/netman/man3z/getservprotobyname.3 0000755 0001750 0001750 00000001675 07130401730 021615 0 ustar tygrys tygrys .TH getservprotobyname 3z "18 February 2000" "" "z88dk Programmer's Manual"
.SH NAME
getservprotobyname, getservprotobyport \- get servprotoice entry
.SH SYNOPSIS
.nf
.B #include
.sp
.BI "u8_t getservprotobyname(char *"name );
.BI "u8_t getservprotobyport(tcpport_t "port );
.fi
.SH DESCRIPTION
The \fBgetservprotobyname()\fP function returns the appropriate protocol
for the service with the name \fIname\fP. If the service isn't known then
NULL is returned.
.PP
The \fBgetservprotobyport()\fP function returns the appropriate protocol
for the service with the standard port number \fIport\fP. If the
service is unknown then NULL is returned.
.SH "RETURN VALUE"
If a service is known to more than one protocol then the most
frequently used is returned.
.SH NOTES
These functions use a lookup table compiled into the ZSock kernel,
it is not likely that method will change in the near future.
.SH AUTHOR
Dominic Morris
z88dk-1.8.ds1/doc/netman/man3z/getservprotobynumber.3 0000755 0001750 0001750 00000001675 07130401730 022165 0 ustar tygrys tygrys .TH getservprotobyname 3z "18 February 2000" "" "z88dk Programmer's Manual"
.SH NAME
getservprotobyname, getservprotobyport \- get servprotoice entry
.SH SYNOPSIS
.nf
.B #include
.sp
.BI "u8_t getservprotobyname(char *"name );
.BI "u8_t getservprotobyport(tcpport_t "port );
.fi
.SH DESCRIPTION
The \fBgetservprotobyname()\fP function returns the appropriate protocol
for the service with the name \fIname\fP. If the service isn't known then
NULL is returned.
.PP
The \fBgetservprotobyport()\fP function returns the appropriate protocol
for the service with the standard port number \fIport\fP. If the
service is unknown then NULL is returned.
.SH "RETURN VALUE"
If a service is known to more than one protocol then the most
frequently used is returned.
.SH NOTES
These functions use a lookup table compiled into the ZSock kernel,
it is not likely that method will change in the near future.
.SH AUTHOR
Dominic Morris
z88dk-1.8.ds1/doc/netman/man3z/htonl.3 0000644 0001750 0001750 00000000026 07130401730 016764 0 ustar tygrys tygrys .so man3z/byteorder.3
z88dk-1.8.ds1/doc/netman/man3z/htons.3 0000644 0001750 0001750 00000000026 07130401730 016773 0 ustar tygrys tygrys .so man3z/byteorder.3
z88dk-1.8.ds1/doc/netman/man3z/ntohl.3 0000644 0001750 0001750 00000000026 07130401730 016764 0 ustar tygrys tygrys .so man3z/byteorder.3
z88dk-1.8.ds1/doc/netman/man3z/ntohs.3 0000644 0001750 0001750 00000000026 07130401730 016773 0 ustar tygrys tygrys .so man3z/byteorder.3
z88dk-1.8.ds1/doc/netman/man3z/pktdrive.3 0000755 0001750 0001750 00000006147 07130401730 017505 0 ustar tygrys tygrys .TH pktdrive 3z "18 February 2000" "" "z88dk Programmer's Manual"
.SH NAME
pktdrive \- packet driver descriptor structure
.SH SYNOPSIS
.nf
.B #include
.fi
.SH DESCRIPTION
The \fIpktdrive\fP structure defines access to a device, it is
only used by the ZSock kernel. Should you wish to write a packet
driver then this structure should be filled with the relevent
routines.
.PP
All external packet drivers run at address 8192 ($2000) and it as
this address that the structure should be placed. Had z88dk the
capability \fIpktdrive\fP would be defined as follows:
.sp
.RS
.nf
.ne 7
.ta 8n 16n
struct pktdrive {
char magic[10];
char *type;
char *copymsg;
void (*initfunc)(void);
void (*queuefn)(void *pkt, size_t len);
void *(*packetfn)(void);
void *(*sendfn)(void);
int (*readfn)(void);
void (*onlinefn)();
void (*offlinefn)(int);
int (*statusfn)(void);
};
.ta
.fi
.RE
.PP
The members of the \fIpktdrive\fP structure are:
.TP
.I magic
Magic to identifier the file as a packet driver, this is defined
as ZS0PKTDRV\0
.TP
.I type
A pointer to the type of the device
.TP
.I copymsg
A pointer to the copyright message
.TP
.I initfunc
A function that initialises the device during the initial configurationin
this function.
.TP
.I queuefn
A function that stores outgoing backets in a queue pending sending.
Depending on the speed of the device it may also inject packets into
the interface.
.TP
.I packetfn
A function that returns the address of the incoming packet. This
function is called immediately after initialisation and after
the \fIreadfn\fP function (below) has returned a packet.
.TP
.I sendfn
A function that is called on the interrupt to inject bytes out of
the interface. If this function returns non-zero then packet at
the address returned is freed.
.TP
.I readfn
A function that is called on the interrupt to read incoming bytes.
If the function returns non-zero then a packet is assumed to have
been read, with length as returned by readfn and lying at the address
specified by packetfn.
.TP
.I onlinefn
A function that is called when the device is to be turned online
.TP
.I offlinefn
A function that is called when the device is to be turned offline,
if the parameter is non-zero then the function should hang up line
(if appropriate) otherwise it should just suspend sending and
receiving packets.
.TP
.I statusfn
A function that returns the status of the device. It is envisaged
that it will return 0 for offline and 1 for online though it may
return other values. The value returned is left for the user to
understand.
.SH NOTES
When the packet is passed to the driver for output a 4 bytes of header
space is available at dp-4. The SLIP driver by Dominic Morris utilises
these bytes to implement a linked list and to hold the length of
the outgoing packet.
.PP
Other packet drivers might wish to copy the packet to their own
address space for converting into other forms - eg CSLIP form. Alternatively
they might simply create a link from their own space to the packet in
the queue so to reduce time wasted copying bytes.
.SH AUTHOR
Dominic Morris
z88dk-1.8.ds1/doc/netman/man3z/QueryPackage.3 0000755 0001750 0001750 00000001517 07130401730 020232 0 ustar tygrys tygrys .TH QueryPackage 3z "18 February 2000" "" "z88dk Programmer's Manual"
.SH NAME
QueryPackage \- open a shared library/package
.SH SYNOPSIS
.nf
.B #include
.sp
.BI "bool_t QueryPackage(char " package ", char " major " , char " minor );
.fi
.SH DESCRIPTION
The \fBQueryPackage()\fP function checks and makes available for use
the shared package \fIpackage\fP with a version of at least
\fIminor\fP.\fIminor\fP
.PP
The function initially checks for the presence of the package subsystem
and then proceeds to check for the specified package.
.PP
Version checking can be disabled by specifying \fIminor\fP and \fImajor\fP
to be 0.
.SH "RETURN VALUE"
The \fBQueryPackage()\fP function returns 0 on failure or 1 on success.
The carry flag is set accordingly and thus the non-standard iferror { ... }
construct can be used to check for success.
z88dk-1.8.ds1/doc/netman/man3z/resolve.3 0000755 0001750 0001750 00000001467 07130401730 017334 0 ustar tygrys tygrys .TH resolve 3z "18 February 2000" "" "z88dk Programmer's Manual"
.SH NAME
resolve \- convert hostname to IP address
.SH SYNOPSIS
.nf
.B #include
.sp
.BI "ipaddr_t resolve(char *"name );
.fi
.SH DESCRIPTION
The \fBresolve()\fP function queries any configured nameservers for the
IP address of the host with the name \fIname\fP.
.PP
If \fIname\fP is in the form a.b.c.d then this is converted to an
IP address and returned.
.SH "RETURN VALUE"
\fBresolv()\fP returns the network order IP address of the requested
host. If the name cannot be resolved then NULL is returned.
.PP
\fBresolv()\fP may also be called by the macro \fBgethostbyname\fP
.SH BUGS
If you use the macro \fBgethostbyname\fP then beware that the ZSock
implementation is not at all standard.
.SH AUTHOR
Dominic Morris
z88dk-1.8.ds1/doc/netman/man3z/reverse_addr_lookup.3 0000755 0001750 0001750 00000002045 07130401730 021704 0 ustar tygrys tygrys .TH reverse_addr 3z "18 February 2000" "" "z88dk Programmer's Manual"
.SH NAME
reverse_addr_lookup \- convert IP address to hstname
.SH SYNOPSIS
.nf
.B #include
.sp
.BI "bool_t reverse_addr_lookup(ipaddr_t "ipaddr ", char *"name );
.fi
.SH DESCRIPTION
The \fBreverse_addr_lookup()\fP function queries any configured nameservers for the
name of the host with IP address \fIipaddr\fP.
.PP
If \fIipaddr\fP is not known to the queried nameservers then the
\fIipaddr\fP is converted to the form a.b.c.d and returned.
.SH "RETURN VALUE"
\fBreverse_addr_lookup()\fP places the hostname in the buffer specified
by \fIname\fP, no checks are made that this buffer is large enough to
hold the full hostname. The function returns TRUE or FALSE depending
on whether the queried nameservers knew \fIipaddr\fP.
.PP
\fBreverse_addr_lookup()\fP may also be called by the macro \fBgethostbyaddr\fP
.SH BUGS
If you use the macro \fBgethostbyaddr\fP then beware that the ZSock
implementation is not at all standard.
.SH AUTHOR
Dominic Morris
z88dk-1.8.ds1/doc/netman/man3z/sock_abort.3 0000755 0001750 0001750 00000001130 07130401730 017766 0 ustar tygrys tygrys .TH sock_abort 3z "18 February 2000" "" "z88dk Programmer's Manual"
.SH NAME
sock_abort \- abort a network connection
.SH SYNOPSIS
.nf
.B #include
.sp
.BI "void sock_abort(SOCKET *"s);
.fi
.SH DESCRIPTION
The parameter \fIs\fP is a descriptor to an open socket created using
\fBsock_open(3z)\fP or \fBsock_listen(3z)\fP.
.PP
The \fBsock_abort()\fP function will immediately move a socket into a closed state disallowing any further reads or writes.
.SH "RETURN VALUE"
None
.SH "SEE ALSO"
.BR sock_close "(3z), " sock_shutdown "(3z)"
.SH AUTHOR
Dominic Morris
z88dk-1.8.ds1/doc/netman/man3z/sock_close.3 0000755 0001750 0001750 00000001311 07130401730 017765 0 ustar tygrys tygrys .TH sock_close 3z "18 February 2000" "" "z88dk Programmer's Manual"
.SH NAME
sock_close \- close a network connection
.SH SYNOPSIS
.nf
.B #include
.sp
.BI "void sock_close(SOCKET *"s);
.fi
.SH DESCRIPTION
The parameter \fIs\fP is a descriptor to an open socket created using
\fBsock_open(3z)\fP or \fBsock_listen(3z)\fP.
.PP
The \fBsock_close()\fP function will initiate a close on the socket
specified by \fIs\fP. Once this function has been called no more data
can be written to the socket. If the socket is of type prot_TCP then
data can continue to be read.
.SH "RETURN VALUE"
None
.SH "SEE ALSO"
.BR sock_abort "(3z), " sock_shutdown "(3z)"
.SH AUTHOR
Dominic Morris
z88dk-1.8.ds1/doc/netman/man3z/sock_closed.3 0000755 0001750 0001750 00000001313 07130401730 020133 0 ustar tygrys tygrys .TH sock_closed 3z "18 February 2000" "" "z88dk Programmer's Manual"
.SH NAME
sock_closed \- test whether a network connection is closed
.SH SYNOPSIS
.nf
.B #include
.sp
.BI "bool_t sock_closed(SOCKET *"s);
.fi
.SH DESCRIPTION
The parameter \fIs\fP is a descriptor to a socket created using
\fBsock_open(3z)\fP or \fBsock_listen(3z)\fP.
.PP
The \fBsock_closed()\fP function tests whether a socket is closed i.e.
connection to a remote host has not been established or has already been
closed by the kernel.
.PP
A socket of prot_UDP is never closed.
.SH "RETURN VALUE"
\fBsock_closed()\fP returns TRUE or FALSE
.SH "SEE ALSO"
.BR sock_opened "(3z)"
.SH AUTHOR
Dominic Morris
z88dk-1.8.ds1/doc/netman/man3z/sock_dataready.3 0000755 0001750 0001750 00000001241 07130401730 020620 0 ustar tygrys tygrys .TH sock_dataready 3z "18 February 2000" "" "z88dk Programmer's Manual"
.SH NAME
sock_dataready \- test whether a network connection has incoming data
.SH SYNOPSIS
.nf
.B #include
.sp
.BI "size_t sock_dataready(SOCKET *"s);
.fi
.SH DESCRIPTION
The parameter \fIs\fP is a descriptor to an open socket created using
\fBsock_open(3z)\fP or \fBsock_listen(3z)\fP.
.PP
The \fBsock_dataready()\fP function tests whether a socket has data
waiting to be read by the user program.
.SH "RETURN VALUE"
\fBsock_dataready()\fP returns the amount of data waiting in the input
queue.
.SH "SEE ALSO"
.BR sock_read "(3z)"
.SH AUTHOR
Dominic Morris
z88dk-1.8.ds1/doc/netman/man3z/sock_flush.3 0000755 0001750 0001750 00000001204 07130401730 020002 0 ustar tygrys tygrys .TH sock_flush 3z "18 February 2000" "" "z88dk Programmer's Manual"
.SH NAME
sock_flush \- flush a network connection
.SH SYNOPSIS
.nf
.B #include
.sp
.BI "void sock_flush(SOCKET *"s);
.fi
.SH DESCRIPTION
The parameter \fIs\fP is a descriptor to an open socket created using
\fBsock_open(3z)\fP or \fBsock_listen(3z)\fP. The socket should be
of type prot_TCP.
.PP
The \fBsock_flush()\fP function will depending on the state of the
connection either immediately send any pending data in the socket buffer
or flag the data for sending in the next timer call.
.SH "RETURN VALUE"
None
.SH AUTHOR
Dominic Morris
z88dk-1.8.ds1/doc/netman/man3z/sock_listen.3 0000755 0001750 0001750 00000002275 07130401730 020170 0 ustar tygrys tygrys .TH sock_listen 3z "18 February 2000" "" "z88dk Programmer's Manual"
.SH NAME
sock_listen \- open a passive network connection
.SH SYNOPSIS
.nf
.B #include
.sp
.BI "SOCKET *sock_listen(ipaddr_t "ipdest ", tcpport_t "lport ",
.BI " void "(*handler)() ", char "proto);
.fi
.SH DESCRIPTION
The \fBsock_listen()\fP function creates a socket descriptor for a
passive (i.e. listening) connection on local port \fIlport\fP awaiting
a connection from host \fIipdest\fP. At the moment only protocols prot_UDP
and prot_TCP are supported.
.PP
To accept connections from any host specify the parameter \fIipdest\fP to
be 0L.
.PP
The parameter \fIhandler\fP specifies a handler to be called whenever
the connection changes state or new data arrives. It should be the
code for a package routine.
.PP
The input parameters of the function \fIhandler\fP vary depending on
whether the socket is of type prot_UDP or prot_TCP.
.SH "RETURN VALUE"
\fBsock_listen()\fP returns a socket descriptor. Specifying a non support
protocol will result in the carry flag being set and the return value being
EPROTONOSUPPORT.
.SH "SEE ALSO"
.BR sock_open "(3z)"
.SH AUTHOR
Dominic Morris
z88dk-1.8.ds1/doc/netman/man3z/sock_open.3 0000755 0001750 0001750 00000001735 07130401730 017633 0 ustar tygrys tygrys .TH sock_open 3z "18 February 2000" "" "z88dk Programmer's Manual"
.SH NAME
sock_open \- open an active network connection
.SH SYNOPSIS
.nf
.B #include
.sp
.BI "SOCKET *sock_open(ipaddr_t "ipdest ", tcpport_t "dport ",
.BI " void "(*handler)() ", char "proto);
.fi
.SH DESCRIPTION
The \fBsock_open()\fP function creates a socket descriptor and attempts
to establish a connection to the port \fIdport\fP on the host \fIipdest\fP
using the protocol \fIproto\fP. At the moment only protocols prot_UDP and
prot_TCP are supported.
.PP
The parameter \fIhandler\fP specifies a handler to be called whenever
the connection changes state or new data arrives. It is of archaic
interest only.
.SH "RETURN VALUE"
\fBsock_open()\fP returns a socket descriptor. Specifying a non-supported
protocol will result in the carry flag being set and the return value
being EPROTONOSUPPORT.
.SH "SEE ALSO"
.BR sock_listen "(3z)"
.SH AUTHOR
Dominic Morris
z88dk-1.8.ds1/doc/netman/man3z/sock_opened.3 0000755 0001750 0001750 00000001246 07130401730 020141 0 ustar tygrys tygrys .TH sock_opened 3z "18 February 2000" "" "z88dk Programmer's Manual"
.SH NAME
sock_opened \- test whether a network connection is established
.SH SYNOPSIS
.nf
.B #include
.sp
.BI "bool_t sock_opened(SOCKET *"s);
.fi
.SH DESCRIPTION
The parameter \fIs\fP is a descriptor to a socket created using
\fBsock_open(3z)\fP or \fBsock_listen(3z)\fP.
.PP
The \fBsock_opened()\fP function tests whether a socket is open i.e.
connection to a remote host has been established.
.PP
A socket of prot_UDP is always established.
.SH "RETURN VALUE"
\fBsock_opened()\fP returns TRUE or FALSE
.SH "SEE ALSO"
.BR sock_closed "(3z)"
.SH AUTHOR
Dominic Morris
z88dk-1.8.ds1/doc/netman/man3z/sock_putc.3 0000755 0001750 0001750 00000001410 07130401730 017633 0 ustar tygrys tygrys .TH sock_putc 3z "18 February 2000" "" "z88dk Programmer's Manual"
.SH NAME
sock_putc \- write byte to a network socket
.SH SYNOPSIS
.nf
.B #include
.sp
.BI "size_t sock_putc(char "c ", SOCKET *"s );
.fi
.SH DESCRIPTION
The parameter \fIs\fP is a descriptor to an open socket created using
\fBsock_open(3z)\fP or \fBsock_listen(3z)\fP
.PP
The \fBsock_putc()\fP function writes a single byte \fIc\fP to the socket specified by \fIs\fP.
.SH "RETURN VALUE"
The \fBsock_write()\fP function returns the number of bytes written
to the socket (i.e. 0 or 1). If an illegal socket is supplied the carry
flag will be set and the return value will be EPROTONOSUPPORT.
.SH "SEE ALSO"
.BR sock_write "(3z), " sock_puts (3z)
.SH AUTHOR
Dominic Morris
z88dk-1.8.ds1/doc/netman/man3z/sock_puts.3 0000755 0001750 0001750 00000001416 07130401730 017661 0 ustar tygrys tygrys .TH sock_puts 3z "18 February 2000" "" "z88dk Programmer's Manual"
.SH NAME
sock_write \- write string to a network socket
.SH SYNOPSIS
.nf
.B #include
.sp
.BI "size_t sock_puts(SOCKET *"s ", char *"dp );
.fi
.SH DESCRIPTION
The parameter \fIs\fP is a descriptor to an open socket created using
\fBsock_open(3z)\fP or \fBsock_listen(3z)\fP
.PP
The \fBsock_puts()\fP function writes the NULL terminated string \fIdp\fP
to the socket specified by \fIs\fP.
.SH "RETURN VALUE"
The \fBsock_write()\fP function returns the number of bytes written
to the socket. If an illegal socket is supplied the carry
flag will be set and the return value will be EPROTONOSUPPORT.
.SH "SEE ALSO"
.BR sock_write "(3z), " sock_putc (3z)
.SH AUTHOR
Dominic Morris
z88dk-1.8.ds1/doc/netman/man3z/sock_read.3 0000755 0001750 0001750 00000001446 07130401730 017604 0 ustar tygrys tygrys .TH sock_read 3z "18 February 2000" "" "z88dk Programmer's Manual"
.SH NAME
sock_read \- read bytes from a network socket
.SH SYNOPSIS
.nf
.B #include
.sp
.BI "size_t sock_read(SOCKET * "s ", void * "dp " , size_t " len );
.fi
.SH DESCRIPTION
The parameter \fIs\fP is a descriptor to an open socket created using
\fBsock_open(3z)\fP or \fBsock_listen(3z)\fP
.PP
The \fBsock_read()\fP function reads at most \fIlen\fP bytes from the
socket \fIs\fP and places them at \fIdp\fP.
\fIdp\fP which should be in the lower 16k of the memory map.
.SH "RETURN VALUE"
The \fBsock_read()\fP function returns the number of bytes read
from the socket. If an illegal socket is supplied the carry flag will be
set and the return value will be EPROTONOSUPPORT.
.SH AUTHOR
Dominic Morris
z88dk-1.8.ds1/doc/netman/man3z/sock_shutdown.3 0000755 0001750 0001750 00000001247 07130401730 020543 0 ustar tygrys tygrys .TH sock_shutdown 3z "18 February 2000" "" "z88dk Programmer's Manual"
.SH NAME
sock_shutdown \- abort a network connection
.SH SYNOPSIS
.nf
.B #include
.sp
.BI "void sock_close(SOCKET *"s);
.fi
.SH DESCRIPTION
The parameter \fIs\fP is a descriptor to an open socket created using
\fBsock_open(3z)\fP or \fBsock_listen(3z)\fP.
.PP
The \fBsock_shutdown()\fP function wipes all trace of the socket \fIs\fP from the system. It should be preceded by either a \fBsock_close(3z)\fP or
\fBsock_abort(3z)\fP depending on the circumstances.
.SH "RETURN VALUE"
None
.SH "SEE ALSO"
.BR sock_close "(3z), " sock_abort "(3z)"
.SH AUTHOR
Dominic Morris
z88dk-1.8.ds1/doc/netman/man3z/sock_write.3 0000755 0001750 0001750 00000001602 07130401730 020015 0 ustar tygrys tygrys .TH sock_write 3z "18 February 2000" "" "z88dk Programmer's Manual"
.SH NAME
sock_write \- write bytes to a network socket
.SH SYNOPSIS
.nf
.B #include
.sp
.BI "size_t sock_write(SOCKET *"s ", void *"dp " , size_t "len );
.fi
.SH DESCRIPTION
The parameter \fIs\fP is a descriptor to an open socket created using
\fBsock_open(3z)\fP or \fBsock_listen(3z)\fP
.PP
The \fBsock_write()\fP function writes a stream of bytes to the open socket
specified by \fIs\fP. The data of length \fIlen\fP is taken from address
\fIdp\fP which should be in the lower 16k of the memory map.
.SH "RETURN VALUE"
The \fBsock_write()\fP function returns the number of bytes written
to the socket. If an illegal socket is supplied the carry flag will be
set and the return value will be EPROTONOSUPPORT.
.SH "SEE ALSO"
.BR sock_putc "(3z), " sock_puts "(3z)
.SH AUTHOR
Dominic Morris
z88dk-1.8.ds1/doc/netman/man3z/tcp_calloc.3 0000644 0001750 0001750 00000003446 07130401730 017754 0 ustar tygrys tygrys .TH tcp_malloc 3 "February 18 2000" "" "z88dk Programmer's Manual"
.SH NAME
tcp_calloc, tcp_malloc, tcp_free \- Allocate and free memory
.SH SYNOPSIS
.nf
.B #include
.sp
.BI "void *tcp_calloc(size_t " "nmemb" ", size_t " "size" ");"
.nl
.BI "void *tcp_malloc(size_t " "size" ");"
.nl
.BI "void tcp_free(void " "*ptr" ");"
.nl
.fi
.SH DESCRIPTION
.B calloc()
allocates memory for an array of
.I nmemb
elements of
.I size
bytes each and returns a pointer to the allocated memory.
The memory is set to zero.
.PP
.B malloc()
allocates
.I size
bytes and returns a pointer to the allocated memory.
The memory is not cleared.
.PP
.B free()
frees the memory space pointed to by
.IR ptr ,
which must have been returned by a previous call to
.BR malloc()
or
.B calloc()
Otherwise, or if
.BI "free(" "ptr" )
has already been called before, undefined behaviour occurs.
If
.I ptr
is
.BR NULL ,
no operation is performed.
.PP
.SH "RETURN VALUES"
For
.BR calloc() " and " malloc() ,
the value returned is a pointer to the allocated memory, which is suitably
aligned for any kind of variable, or
.B NULL
if the request fails.
.PP
.B free()
returns no value.
.PP
.SH "SEE ALSO"
.BR tcp_pagein "(3z) ," tcp_pageout (3z)
.SH NOTES
These functions manipulate memory in a private memory page belonging
to ZSock. This 16k page holds all the buffers that ZSock uses
and hence requests for large amounts of memory are likely to fail (and
in any case are not recommended).
.PP
This facility has been offered to allow daemons to be written simply
(they have no address space of their own). User applications should
not use these facilities. If a large (>256 bytes) amount of memory
is required for a user application then the application should
either be of the BAD type or be redesigned.
.SH AUTHOR
Dominic Morris
z88dk-1.8.ds1/doc/netman/man3z/tcp_free.3 0000644 0001750 0001750 00000003446 07130401730 017440 0 ustar tygrys tygrys .TH tcp_malloc 3 "February 18 2000" "" "z88dk Programmer's Manual"
.SH NAME
tcp_calloc, tcp_malloc, tcp_free \- Allocate and free memory
.SH SYNOPSIS
.nf
.B #include
.sp
.BI "void *tcp_calloc(size_t " "nmemb" ", size_t " "size" ");"
.nl
.BI "void *tcp_malloc(size_t " "size" ");"
.nl
.BI "void tcp_free(void " "*ptr" ");"
.nl
.fi
.SH DESCRIPTION
.B calloc()
allocates memory for an array of
.I nmemb
elements of
.I size
bytes each and returns a pointer to the allocated memory.
The memory is set to zero.
.PP
.B malloc()
allocates
.I size
bytes and returns a pointer to the allocated memory.
The memory is not cleared.
.PP
.B free()
frees the memory space pointed to by
.IR ptr ,
which must have been returned by a previous call to
.BR malloc()
or
.B calloc()
Otherwise, or if
.BI "free(" "ptr" )
has already been called before, undefined behaviour occurs.
If
.I ptr
is
.BR NULL ,
no operation is performed.
.PP
.SH "RETURN VALUES"
For
.BR calloc() " and " malloc() ,
the value returned is a pointer to the allocated memory, which is suitably
aligned for any kind of variable, or
.B NULL
if the request fails.
.PP
.B free()
returns no value.
.PP
.SH "SEE ALSO"
.BR tcp_pagein "(3z) ," tcp_pageout (3z)
.SH NOTES
These functions manipulate memory in a private memory page belonging
to ZSock. This 16k page holds all the buffers that ZSock uses
and hence requests for large amounts of memory are likely to fail (and
in any case are not recommended).
.PP
This facility has been offered to allow daemons to be written simply
(they have no address space of their own). User applications should
not use these facilities. If a large (>256 bytes) amount of memory
is required for a user application then the application should
either be of the BAD type or be redesigned.
.SH AUTHOR
Dominic Morris
z88dk-1.8.ds1/doc/netman/man3z/tcp_malloc.3 0000644 0001750 0001750 00000003447 07130401730 017767 0 ustar tygrys tygrys .TH tcp_malloc 3 "February 18 2000" "" "z88dk Programmer's Manual"
.SH NAME
tcp_calloc, tcp_malloc, tcp_free \- Allocate and free memory
.SH SYNOPSIS
.nf
.B #include
.sp
.BI "void *tcp_calloc(size_t " "nmemb" ", size_t " "size" ");"
.nl
.BI "void *tcp_malloc(size_t " "size" ");"
.nl
.BI "void tcp_free(void " "*ptr" ");"
.nl
.fi
.SH DESCRIPTION
.B calloc()
allocates memory for an array of
.I nmemb
elements of
.I size
bytes each and returns a pointer to the allocated memory.
The memory is set to zero.
.PP
.B malloc()
allocates
.I size
bytes and returns a pointer to the allocated memory.
The memory is not cleared.
.PP
.B free()
frees the memory space pointed to by
.IR ptr ,
which must have been returned by a previous call to
.BR malloc()
or
.B calloc()
Otherwise, or if
.BI "free(" "ptr" )
has already been called before, undefined behaviour occurs.
If
.I ptr
is
.BR NULL ,
no operation is performed.
.PP
.SH "RETURN VALUES"
For
.BR calloc() " and " malloc() ,
the value returned is a pointer to the allocated memory, which is suitably
aligned for any kind of variable, or
.B NULL
if the request fails.
.PP
.B free()
returns no value.
.PP
.SH "SEE ALSO"
.BR tcp_pagein "(3z) ," tcp_pageout (3z)
.SH NOTES
These functions manipulate memory in a private memory page belonging
to ZSock. This 16k page holds all the buffers that ZSock uses
and hence requests for large amounts of memory are likely to fail (and
in any case are not recommended).
.PP
This facility has been offered to allow daemons to be written easily
(they have no address space of their own). User applications should
not use these facilities. If a large (>256 bytes) amount of memory
is required for a user application then the application should
either be of the BAD type or be redesigned.
.SH AUTHOR
Dominic Morris
z88dk-1.8.ds1/doc/netman/man3z/tcp_pagein.3 0000755 0001750 0001750 00000001354 07130401730 017761 0 ustar tygrys tygrys .TH tcp_pagein 3z "18 February 2000" "" "z88dk Programmer's Manual"
.SH NAME
tcp_pagein \- page the ZSock data area into the memory map
.SH SYNOPSIS
.nf
.B #include
.sp
.BI "u8_t tcp_pagein(void);
.fi
.SH DESCRIPTION
The \fBtcp_pagein()\fP function pages in the ZSock data area into segment
1 (addresses 16384-32767) of the z88s memory map.
.PP
This function is primarily of use to daemons which use the ZSock dataarea
for small amounts of storage.
.SH "RETURN VALUE"
\fBtcp_pagein()\fP returns the previous binding of segment 1 which should
be used as a parameter to \fBtcp_pageout\fP(3z)
.SH "SEE ALSO"
.BR tcp_pageout "(3z), " tcp_malloc (3z), " tcp_calloc"(3z)
.BR tcp_free "(3z)"
.SH AUTHOR
Dominic Morris
z88dk-1.8.ds1/doc/netman/man3z/tcp_pageout.3 0000755 0001750 0001750 00000001663 07130401730 020165 0 ustar tygrys tygrys .TH tcp_pageout 3z "18 February 2000" "" "z88dk Programmer's Manual"
.SH NAME
tcp_pageout \- page the ZSock data area out of the memory map
.SH SYNOPSIS
.nf
.B #include
.sp
.BI "void tcp_pageout(u8_t "oldbinding);
.fi
.SH DESCRIPTION
The \fBtcp_pageout()\fP function pages out the ZSock data area into segment
1 (addresses 16384-32767) of the z88s memory map.
.PP
The parameter \fIoldbinding\fP is the return value from a prior
\fBtcp_pagein(3z)\fP function.
.PP
This function is primarily of use to daemons which use the ZSock dataarea
for small amounts of storage.
.SH "RETURN VALUE"
\fBtcp_pagein()\fP returns the previous binding of segment 1 which should
be used as a parameter to \fBtcp_pageout\fP(3z)
.SH "SEE ALSO"
.BR tcp_pagein "(3z), " tcp_malloc (3z), " tcp_calloc"(3z)
.BR tcp_free "(3z)"
.SH BUGS
Supplying an incorrect \fIoldbinding\fP will most likely crash the z88.
.SH AUTHOR
Dominic Morris
z88dk-1.8.ds1/doc/netman/man3z/tcp_RegCatchall.3 0000755 0001750 0001750 00000003022 07130401730 020661 0 ustar tygrys tygrys .TH tcp_RegCatchall 3z "18 February 2000" "" "z88dk Programmer's Manual"
.SH NAME
tcp_RegCatchall \- (De)register packet catcher
.SH SYNOPSIS
.nf
.B #include
.sp
.BI "int tcp_RegCatchall(int "libcall );
.fi
.SH DESCRIPTION
The \fBtcp_RegCatchall()\fP function registers or deregisters a
function that is used to catch all incoming packets after it has
passed the basic tests of checksumming, length and ttl-checking.
l-checking.
.PP
The parameter \fBlibcall\fP is the ID for a shared library/packet
call which has the prototype thus:
.sp
.BI "bool_t Function(void *" dp ", size_t "len );
.PP
Where \fIdp\fP is the address of the packet and \fIlen\fP is the
length of the packet. This function should return TRUE/FALSE to
indicate to the ZSock kernel whether the function has dealt with the
packet and ZSock should not process it.
.SH "RETURN VALUE"
\fBtcp_RegCatchall()\fP returns the previous ID of the catchall
function.
.SH NOTES
Should you wish to stop calling your catchall function simply call
the function with an argument of NULL.
.PP
This function is of use should somebody write a driver for an
as yet unsupported protocol.
.PP
The package call should page in the ZSock data area using the function
\fBtcp_pagein(3z)\fP.
.PP
This call could for example be used to implement a traceroute style
routine to catch ICMP replies. Returning TRUE when it has received
an ICMP reply packet of the correct tyoe, and FALSE otherwise.
.SH "SEE ALSO"
.BR tcp_pagein "(3z), " tcp_pageout (3z)
.SH AUTHOR
Dominic Morris
z88dk-1.8.ds1/doc/options.txt 0000644 0001750 0001750 00000012224 07130401726 015506 0 ustar tygrys tygrys This is intended to be a quick reference to the types of code that
z88dk can produce - there is now a plethora of flags controlling
almost every aspect of it, and needless to say it has got quite
confusing (even for me!) so now follows a quick reminder of what
can be achieved!
BASIC Programs
--------------
The default type of output code produced by z88dk, it requires no
flags other than those for any libraries that you wish to link in,
eg: % zcc -lm -lgfx cube.c
Will compile file cube.c into a BASIC program whilst pulling in
routines from the generic maths library and the graphics library.
Applications
------------
This is where the fun begins, to create an application in the .63
form we need two flags, one to trigger the compiler into
producing appropriate code (essentially using DEFVARS instead
of defs to create storage), and another to call the "appmaker" program.
eg: % zcc -create-app -make-app -lgfxapp dstar.c
Will compile the dstar.c file into an application whilst pulling in
routines from the application graphics library (We need different
libraries for applications and BASIC programs due to paging
requirements - essential so we don't page the executing code out!)
We can further tweak the compilation; suppose you want to combine
several apps onto one card (using some other program to achieve this),
the default address that the application is compiled to is 49152, if
you wish to compile to a different address use the following command
line:
% zcc -zorg=[address in decimal] -create-app -make-app -lgfxapp dstar.c
Which if the address is > 49152 will create a truncated .63 image
from the address supplied. The application is of course org'd to
this address.
To change the amount of bad memory given to a bad application (or ugly
popdown) we use the flag -reqpag= where reqpag is the number of 256
byte pages that we require. This flag is also very useful for giving
back memory to the system on preemption - have a look at the dstar.c
and rpn.c examples for examples of the usage of reqpag.
Using the defaults for application creation it isn't possible to create
a good application which uses static variables (by default these are
placed in "bad memory") however, should you wish to do this then a
couple of flags can come to your rescue!
As you know each application is allowed certain amounts of "safe
memory" to store some static variables (usually used to hold
the "far pointer" to some allocated memory), the startup code
for applications uses some of this space to hold some extremely
useful information (have a look at the app_crt0.asm file in the lib
directory for the gory details).
The flags of concern are -safedata=[number] and -defvars=[address].
-safedata tells the compiler how much safe memory *your* code requires
and -defvars is used to place static variables at this address.
These options should really only be used by those who should know
better (I myself have not even used them!) but some brief information:
- Your safedata area starts at $1FFD-[num of bytes reqd], so if you
need $10 bytes then your defvars flag should be -defvars=$1FED
It is probably a good idea not to specify -defvars on the command line
- but to place it in the C file using the #pragma directive - this
allows multifile projects to be compiled without variable space
clash.
Intuition Debugging Of Application
----------------------------------
By supplying the flag -intuition to the compiler the necessary call
is inserted in the startup code to enable the program to be debugged
via Intuition (the Z88 debugger from Interlogic). You will need to
blow the application to an EPROM with Intuition and adjust the
application DOR appropriately. For more details read the very fine
documentation that came with your copy of Assembler Workbench.
[I'm getting a strange sense of deja-vu regarding the names of
these programs ]
Absolute Address Code
---------------------
The compiler can also produce code that can run from an absolute
address, this is perhaps most suitable for use from within a BASIC
program with a well known memory map.
To invoke it use:
% zcc -startup=3 -ofile.bin [files]
And file.bin will be a self contained C program or module, which can be
utilised via the BASIC command CALL 16384. To compile it to a different
address use the -zorg= flag.
Relocatable Code
----------------
Thanks to the relocation feature of z80asm it is possible to produce
code which can be run from any address in RAM. To switch into this mode
supply the -R flag to the frontend.
At present it is not possible to pass parameters from BASIC to the
compiled C program - a way of translating BBC BASICs parameter passing
method into the argc/argv method used by C is something of headache the
moment.
Spectrum Startup Code
---------------------
To compile code for the ZX Spectrum use the flag +zx Support is steadily
improving and can only get better. Likewise for other machines:
+zxansi - Use ZX VT100 terminal
+vz - Create a file for a VZ200/300
+nc - Create an application image for the Amstrad nc100
----
I hope that I've covered most of the important flags of the compiler
which affect the type of code that is produced. If you have any questions
just ask me!
djm 18/4/2000
z88dk-1.8.ds1/doc/packages.txt 0000644 0001750 0001750 00000004756 07130401727 015605 0 ustar tygrys tygrys Writing Packages With z88dk
At the time of writing, the package subsystem by Garry Lancaster has not
fully been finalised so where differences exist between this document
and the documentation supplied by Garry, his should take precedence.
A package is always attached to a application eg. The Packege Package is
attached to Installer and the TCP Package is attached to the application
ZSock, thus building a package with z88dk is tied to building an
application. As result this documentation is written with the assumption
that you know how to write and build applications with z88dk.
Constructing the Package DOR
----------------------------
The package DOR is the structure which informs the Package system about
your package. Creating the DOR with z88dk is incredibly simple. Normally
to create an application DOR you would do the following:
#include
/* Define application paramaters */
#include
In a similar vein, to build the package DOR you do the following:
#include
/* Define package parameters */
#include
/* Define table of pointers to functions (jump table)*/
/* Define application parameters */
#include
The package parameters are as follows:
#define MAKE_PACKAGE 1
Say that you do want to create a package(!
#define PACK_VERSION $MMmm
The version of the package you are creating - MM=major, mm=minor
#define PACK_NAME "[name]"
The name of the package (without the [] of course!)
#define PACK_BOOT
This should be set to either 0 or 1 depending on whether the package
should autoboot or not (This is of course bypassed by holding down 'P'
on reset)
#define PACKAGE_ID $xx
The package number as allocated by Garry Lancaster
#define MAX_CALL_NUM $nn
The maximum LSB of a call to your package.
Setting Up The Jump Table
-------------------------
The jump table can be easily defined using the following construct:
package_str blahfishcakeblah[] = {
{Func1},
{Func2},
....
{FuncN}
};
Remember to prototype as external to the file Func1....FuncN
Finally
-------
You have to supply 3 functions yourself to fully define the package, these
are the pack_ayt, pack_bye and pack_dat functions. Due to the complex
entry and exit parameters of these functions they are best written in
assembler. For more details about these calls please see Garry's
documentation. These functions must either be prototyped (to allow correct
linking)
At a later date these 3 functions may be writable in C if there's enough
demand for the ability.
dom
3/3/2000
z88dk-1.8.ds1/doc/platforms.txt 0000644 0001750 0001750 00000011477 10631472636 016043 0 ustar tygrys tygrys Z88DK Port Status
$Id: platforms.txt,v 1.15 2007/06/06 08:51:42 stefano Exp $
PLATFORM | Native I/O | ANSI VT I/O | GRAPH LIB | GRAY LIB | FILELIB | ZSOCK | SOUND | Others |
-------------------------------------------------------------------------------------------------------------------------------
| | | | | | | | |
ABC80 | No | 40x24-buggy | No | No | No | No | --- | --- |
Amstrad NC100 | Yes | No | No | No | No | No | --- | Untested |
Amstrad CPC | Yes | 20-80x25 COL| 256x192 | No | No | No | --- | Alt. FP lib |
Aquarius | 38x25 | 40x24 COL| No | No | No | No | 1 bit | --- |
Cambridge Z88 | Yes | Yes | 256x64 | No | Yes | Yes | 1 bit | Paging+many |
Commodore 128 | No | 40x25 COL| No | No | No | No | --- | --- |
CP/M | Yes | If Hardware | No | No | Yes | No | --- | --- |
Jupiter ACE | No | 32x24 B/W| 96x64 emul. | No | No | No | 1 bit | --- |
MSX 1 | 40x24 | No | No | No | No | No | --- | --- |
NASCOM 1/2 | 48x15 | 48x16 B/W| Unfinished | No | No | No | --- | --- |
REX 6000 | No | No | No | No | No | No | --- | (1) |
NewBrain | Yes | No | No | No | Yes | No | --- | --- |
Rabbit C.M. | | No | No | No | No | No | --- | --- |
Sam Coupe | 32x24-buggy | No | No | No | No | No | --- | --- |
Sega Master S | | | | No | | No | | --- |
Sharp MZ | 40x25 | 40x25 COL| 80x50 | No | No | No | --- | (2) |
Sharp OZ | Yes | 59x10 B/W| 239x80 | No | No | No | --- | (3) |
SORD M5 | 32x24 | No | No | No | No | No | --- | --- |
Spectravideo | 40x24 | No | No | No | No | No | --- | --- |
Sprinter | 80x35 | 80x35 COL| No | No | Yes | No | --- | (4) |
TI82 | 16x8 | 32x4 B/W| 96x64 | Yes | No | No | 1 bit | --- |
TI83 | 16x8 | 32x4 B/W| 96x64 | Yes | In Progress | No | 1 bit | --- |
TI83 Plus | 16x8 | 32x4 B/W| 96x64 | Yes | No | No | 1 bit | --- |
TI85 | 21x8 | 32x4 B/W| 128x64 | Yes | No | No | 1 bit | --- |
TI86 | 21x8 | 32x4 B/W| 128x64 | Yes | No | No | 1 bit | --- |
VZ/Laser 200 | 32x16 | 32x12 B/W| 128x64 | No | No | No | --- | --- |
ZX 81 | 32x21-buggy | 32x21 B/W| 96x64 emul. | No | No | No | --- | FP Unstable |
ZX Spectrum | 32x24+64x24 |24..85x24 COL| 256x192 | No | +3 | No | 1 bit | (5) |
ZXVGS | | | | | Yes | | | |
| | | | | | | | |
(1) The Xircom REX 6000 port provides hooks into the native OS. No z88dk i/o functions are supported
(2) Flagged for a lot of time as "instable" because of an emulator instability !!
(3) Much of the "OZDK" functions are ported; at the moment doesn't work if code size > 8Kbytes.
(4) Sprinter has many "standard" functions implemented
(5) Work on a +3 (and others) file library is in progress
FP Unstable = On these platforms there are problems using some of the "special" registers, making some functions crash.
The float variables, for example, can't be used (for now).
z88dk-1.8.ds1/doc/retarget.txt 0000644 0001750 0001750 00000013375 07454524662 015656 0 ustar tygrys tygrys Retargetting the Compiler For Other Z80 Based Machines
------------------------------------------------------
[Document under construction]
The compiler part of the Z88DK produces perfectly standard Z80 assembler,
to this end it could easily be retargetted to other Z80 based machines with
the minimum of effort.
In order to port for other Z80 machines a new startup file has to be
supplied along with slightly rewritten library functions.
The startup file for the Z88 is located in the {zcc}/lib directory and
is called z88_crt0.asm, it just provides a simple way to interface
machine code programs to BASIC - in it is contained a short BASIC program
which calls the startup code.
In the case of the Z88 the startup code allocates memory for the atexit()
stack and installs a simple error handler which exits to BASIC when escape
is pressed.
The file also includes the floating point routines if required by any
module in a project. Also defined in this file are LIBrary references
to the various runtime routines used by generated code - such as routines
to divide and multiply etc.
Unlike the earlier versions of Small C runtime routines are only linked in
if they are used, for example if your programs doesn't do any
multiplication or division then these routines will not be included in
the generated executable, hence resulting in much smaller executables.
This is a very fine idea, however potential problems may arise if you
have retargetted the compiler to another Z80 system eg the ZX Spectrum and
wish to generate executables which access far code.
The Z88 has a very flexible method of memory paging - (virtually) any
bank can be placed in any 16k segment of the Z80 physical address space,
and hence it is irrelevant where the code to access far data is located.
However in the case of the Spectrum 128 memory can only be paged in the
top 16k of address space and, well, I think you see the problem - the code
to access far data is in danger of being paged out.
To circumvent this, place the routines which access far data (the lp_*
routines in the libsrc/crt0 directory) in with the startup code - this
will slightly increase the executable size but will almost guarantee no
embarrassing paging out mistakes (assuming of course that your startup
code is located in low memory).
A short startup for the ZX Spectrum is now in lib/spec_crt0.asm file,
a few Spectrum specific functions have been written so that many of the
examples for the z88 now compile and work on the Spectrum as well.
Floating Point Routines
-----------------------
A set of floating point routines is supplied which will work on any Z80
(it does use undocumented opcodes, but...), however should you wish to
write your own to utilise the fp calculator in your machines ROM, take
a look at the mathz88.asm file in the lib directory for a template, the
chances are you'll need to change the constant for 0.1 in the const.c file,
but let me know and I'll add another flag to the compiler!
Stdio Library Routines
----------------------
The "new" stdio library is now almost completely machine independent however
obviously some low level routines are needed in order for the generic routines
to work, here I shall list the required routines:
int fgetc_cons(void)
Should read a key from the keyboard returning the ASCII
key value in hl. This routine should return 0 if no key
is pressed, however unless an error occurs it should wait
for a keypress.
void fputc_cons(char code)
Should print code to the screen
int fgets_cons(char *buf, int maxlen)
Should read a string from the keyboard. Done this way because
some computers (i.e. z88) have an OS call to do this which
offers editing facilities
void puts_cons(char *str) [optional]
Writes a NULL terminated string to the console, this call
is provided to conserve memory usage should no other stdio
routines be required
int getk(void) [optional]
Should read the current state of the keyboard, returning
NULL if no key is pressed
Should you require file handling you will need the following standard routines
from fcntl.h (or unistd.h as it is sometimes known), should you not want
file-handling for your machine then these functions should be NULL functions
(chances are they won't be called!):
int open(far char *name, int flags, mode_t mode);
int creat(far char *name, mode_t mode);
int close(int fd);
size_t read(int fd, void *ptr, size_t len);
size_t write(int fd, void *ptr, size_t len);
long lseek(int fd,long posn, int whence);
int open_z88(far char *name, int flags, mode_t mode, char *explicit, size_t len)
This is a non-standard routine and on most machines will
probably just call open() however this provides the facility
to return the explicit file name (which is placed in explicit,
up to a maximum length len)
extern int __FASTCALL__ readbyte(int fd);
This function reads a byte from filehandle fd (which is
supplied in the register pair hl), if an error occurred it
should return EOF (-1) and return with carry set. Otherwise
it should return with carry reset and hl holding the byte
just read
extern int writebyte(int fd, int c);
This function writes byte c to filehandle fd, once more if
an error occurs it should return EOF and carry set, otherwise
hl holds the byte just written and carry is reset
void fabandon(FILE *fp)
Abandon file with the handle fd - this is called by the system
on program exit should it not be able to close a file. This
function is a dummy function on the z88 but for example on the
Spectrum +3 this function would be of use.
Once you have supplied the above functions the entire z88dk stdio library
is available to you (including printf etc) in addition to all the ctype,
string, assert, setjmp, near malloc, some stdlib and the generic math
routines - just a little work yields over 100 usable functions!
dom, 9/4/2000
z88dk-1.8.ds1/doc/stdio.txt 0000644 0001750 0001750 00000003517 07130401727 015143 0 ustar tygrys tygrys z88dk New Stdio Library - 4/4/2000 djm
Yup, after ages of promising I've finally gotten around to updating the
crusty stdio of z88dk. This new library finally dumps the equivalence of
file handles and streams and hence brings the model more into line with
libraries for "big C"
The library is now highly portable across machines - to gain basic
functionality on another machine just 3 functions have to be written -
write character to console, read character from console and read string
from console.
At the moment for simplicities sake, file streams are not buffered, though
adding buffering should be fairly trivial - if there is enough
demand/clamouring then I can add it.
It is highly recommended that your programs use the new library (it is the
default and simply recompiling will enable support) even though it is
slightly larger it offers many advantages:
- Standard ANSI return values (I hope)
- Standard ANSI functions (gets() is now defined correctly, and other
functions behave in a standard manner (eg putchar() will now output to
whatever stdout is instead of always to the console)
- An ungetc() function - hurrah!
- All streams are closed on program exit
- minisprintf now uses the minivfprintf core routine and thus now supports
long datatypes
- freopen(_z88) is now available
There are some as yet unresolved disadvantages:
- Your program becomes slightly larger
- A maximum of 7 open streams (10 in total including std*)
This last point is not a particular disadvantage - you can of course open
files using open() and creat() however files opened this way are /not/
automatically closed on program exit.
Should you wish to use the old stdio routines then do a #define FDSTDIO 1
before including and link with -lz88 and you can use them,
however you should note that the printf() family of functions is not
available.
djm
4/4/2000
z88dk-1.8.ds1/doc/ti.txt 0000644 0001750 0001750 00000011666 07307445237 014453 0 ustar tygrys tygrys -------------------------------------------------------------------------------
Compiling for the Ti82, Ti83(+), Ti85 and Ti86 ; By Henk Poley ; 05-jun-2001
-------------------------------------------------------------------------------
general compilation command:
zcc [+..] [-startup=..] [-o..] [-l..] [flags] file(s)
[+..]
- Config file to load:
Ti82
Ti82ansi
Ti83
Ti83ansi
Ti8x
Ti8xansi
Ti85
Ti85ansi
Ti86
Ti86ansi
[-startup=..]
- Startup header to use (see below for values)
[-o..]
- Binary output file (standard a.bin)
[-l..]
- Link this library (see zcc.html for others):
tigray82
tigray83
tigray83p
tigray85
tigray86
[flags]
- For other flags see compile.txt
file(s)
- File(s) to compile
-------------------------------------------------------------------------------
Ti82:
compiles for CrASH (always)
#pragma string name xxx
- program description, max 22 characters (approx)
#pragma output nostreams
- If you just don't use the streams at all (no text and file-stuff)
#pragma output atexit
- If you use the atexit() command (uses 64 bytes extra stack).
-------------------------------------------------------------------------------
Ti83:
zcc [+..] [-startup=..] [-o..] [-l..] file(s)
-startup =
n - Primary shell(s); compatible shell(s)
(Primary shell merely means it's the smallest implementation
for that shell, that uses full capabilities of the shell)
1 - Ion; Ti-Explorer (default)
2 - Venus;
3 - ZES;
4 - Anova; SOS
5 - Ti-Explorer, AShell; SOS, Anova (same as 6)
6 - AShell, Ti-Explorer; SOS, Anova (same as 5)
7 - SOS; Anova
8 - Venus Explorer (VE); Venus
9 - Ion, Ti-Explorer; ZASMLOAD, plain TIOS
10 - Plain TIOS, ZASMLOAD
#pragma string name xxx
- program description, max 22 characters (approx)
#pragma data icon xx,xx,xx;
- shell icon 5 (Anova), 7 (VE), or 8 (rest) bytes long.
Bigger icons won't brake anything, they are just displayed truncated
(with most of the shells). Standard icon is "C+".
#pragma output nostreams
- If you just don't use the streams at all (no text and file-stuff)
#pragma output atexit
- If you use the atexit() command (uses 64 bytes extra stack).
-------------------------------------------------------------------------------
Ti83+ (Second Edition):
zcc -startup =
n - Primary shell, compatible shells
(Primary shell merely means it's the smallest implementation
for that shell, that uses full capabilities of the shell)
1 - Ion (default)
2 - MirageOS without quit key
3 - MirageOS with quit key - *dangerous* (possibly)
4 - TSE Kernel
#pragma string name xxx
- program description, max 22 characters (approx)
#pragma data icon xx,xx,xx;
- shell icon 8 bytes long. Standard icon is "C+".
#pragma data mirage_icon xx,xx,xx;
- Icon for MirageOS, 16 bytes long. Standard icon is a 'map' with
"C+" written on it.
#pragma output GimmeSpeed
- Will switch the Ti83+ Second Edition to 15MHz during runtime.
Setting this when compiling for the normal Ti83+ won't brake
anything. It will return to the shell at the normal 6MHz.
This won't work when using grayscale, until there is made a
"high speed" IM2 grayscale interrupt...
NOTE: Only works with ROM v1.13 and higher.
#pragma output StackNeeded = nnn;
- External Data Required for virtual stack.
TSE uses this value, it is standard set to 400 bytes, which equals
to the normal stackspace of the Ti83+. When you think your program
uses more or less than that, try a bit to find the best value.
#pragma output nostreams
- If you just don't use the streams at all (no text and file-stuff)
#pragma output atexit
- If you use the atexit() command (uses 64 bytes extra stack).
-------------------------------------------------------------------------------
Ti85:
compiles for Rigel (always)
#pragma string name xxx
- program description
#pragma output nostreams
- If you just don't use the streams at all (no text and file-stuff)
#pragma output atexit
- If you use the atexit() command (uses 64 bytes extra stack).
-------------------------------------------------------------------------------
Ti86:
zcc -startup =
n - Primary shell(s); compatible shell(s)
(Primary shell merely means it's the smallest implementation
for that shell, that uses full capabilities of the shell)
1 - LASM (default)
2 - ASE, Rascal, emanon, etc.
3 - zap2000
4 - emanon
5 - Embedded LargeLd - !!!EXPERIMENTAL!!!
10 - asm() executable
#pragma string name xxx
- program description
#pragma data icon xx,xx,xx;
- shell icon 8 bytes long. Standard icon is "C+".
#pragma output nostreams
- If you just don't use the streams at all (no text and file-stuff)
#pragma output atexit
- If you use the atexit() command (uses 64 bytes extra stack).
z88dk-1.8.ds1/doc/windows.txt 0000644 0001750 0001750 00000006156 07307445237 015527 0 ustar tygrys tygrys -------------------------------------------------------------------------------
Setting up the z88dk for Windows9x ; By Henk Poley ; 05-jun-2001
-------------------------------------------------------------------------------
To begin with, these steps have only been tested on Windows95 & 98 (Lite), but they should work on other (Windows) platforms as long as they have 32bit DOS capabilities and long filenames. Maybe you will need to add entries to the PATH and environment variables in a different way than described here, because AUTOEXEC.BAT is no longer in use (Windows ME/NT/2000/XP), please revert to the manuals if it doesn't seem to work this way. You could also ask us, the makers of the z88dk, off coarse...
This is going to be a step-by-step guide, please don't feel embarrassed.
First unzip all files in the archive to a directory. We will call this directory from now on {z88dk}. Now you will need the Windows executables from which a link can found on the z88dk's website (http://z88dk.sourceforge.net/).
Unzip the files into {z88dk}\bin.
Now for the following steps open your AUTOEXEC.BAT file, you will find it in your C:\ directory. If it isn't there, create it.
Then search for the line beginning with "PATH" or "SET PATH=". Add {z88dk}\bin\ to it, you will get a line like the following. Note that you need to separate different entries with a colon ';' (in this case {z88dk} is "c:\dos\z88dk").
PATH c:\dos\tools\;c:\dos\z88dk\bin\
Now we have to setup where the z88dk needs to look for it's data files (libraries, assembly and config files needed during compile time). Add the following lines to your AUTOEXEC.BAT (remark that all "DOS" backslashes need to be turned into "unix" slashes):
SET Z80_OZFILES = {z88dk}/LIB/
SET ZCCCFG = {z88dk}/LIB/CONFIG/
You will get for example:
SET Z80_OZFILES = C:/DOS/Z88DK/LIB/
SET ZCCCFG = C:/DOS/Z88DK/LIB/CONFIG/
Save your new AUTOEXEC.BAT in the root (C:\).
Now you need a text-editor that can search-and-replace in more documents at one time (like TextPad or UltraEdit, search for them at http://www.downloads.com/). We need this when editing the config files. You could also only change the config (*.cfg) files of the platforms you will work with, you will then only need Notepad or similar programs. Open a DOS-window and type:
cd {z88dk}
cd lib
cd config
copy *.lnx *.cfg
Now go to {z88dk}\lib\config within Windows. Select all .cfg files and open them with the text-editor. If it doesn't open them in the right program, hold shift down and right click on the files. Chose "open with...", then deselect the "use always" selection, and select your program, then press "OK".
Now find the search-and-replace utility in your text-editor. Replace the following (can also be done manualy on one file):
cp -> copy
DESTDIR -> {z88dk} (remove the "DOS" backslash at the end!)
/ -> \ ("unix" slashes into "DOS" backslashes)
Restart your PC and there you go. For info about using the z88dk please revert to other documentation found in the {z88dk}\doc\ directory, like compile.txt and zcc.html.
Have a nice day,
Henk Poley
z88dk-1.8.ds1/doc/z80asm.txt 0000644 0001750 0001750 00000271420 07130401727 015143 0 ustar tygrys tygrys THE Z80 CROSS ASSEMBLER, V1.0.16 (30th January 2000)
Thank you for purchasing a copy of this cross assembler. We have made an effort
to program an easy user interface and efficient assembler source file compiling.
The object file and library format is an invention of our own and has also been
included in this documentation. We hope that you will enjoy your Z80 machine
code programming with our assembler.
We have made an effort to produce a fairly easy-to-understand documentation. If
you have any comments or corrections, please don't hesitate to contact us:
Gunther Strube
Gl. Kongevej 37, 4.tv.
DK-1610 Kobenhavn V
Denmark
e-mail gbs@image.dk
1.0 Running the asssembler
Since assemblers are developed for programmers the user interface have been
implemented according to the standard command line environment (CLI) used in
most operating systems; however, if only a GUI interface is available (as in
MacOS) then a command shell must be executed to allow standard command line
input. The Z80 Module Asssembler command line interface may change if other
programmers wish to implement a different interface to the assembler. You have
the opportunity!
o The help page
When executing the assembler from the command line without parameters, i.e.
pressing after the assembler program name, a help page is automatically
displayed whereafter control is returned to the operating system command line.
The page shortly explains the syntax of parameter specification and which
parameters are available.
o The command line
The syntax of the assembler parameters is a streightforward design. Filenames or
a project file are always specified. The options may be left out:
z80asm [options] | <@modulesfile>
As seen above must be specified first. Then you enter the names of all
files to be assembled. You either choose to specify all file names or a
@ containing all file names. File name may be specified with or
without the 'asm extension. The correct filename parsing is handled
automatically by the assembler. As seen on the syntax at least on source file
must be specified and may be repeated with several file names. Only one project
file may be specified if no source file names are given.
Many of the parameters are preset with default values which gives an easy user
interface when specifying the assembly parameters. Only advanced parameters need
to be specified explicitly. The help page displays the default parameter values
at the bottom of the page.
o The assembler options
Options are used to control the assembly process and output. They are recognized
by the assembler when you specify a leading minus before the option identifier
('-'). Options are always specified before file names or project files.
When the assembler is executed options are all preset with default values and
are either switched ON or OFF (active or not). All options have a single letter
identification. Upper and lower case letters are distinguished, which means that
'a' might be different command than 'A'. If an option is to be turned off, you
simply specify a 'n' before the identification, e.g. -nl which selects listing
files not to be created by the assembler.
- Information during assembly, -v
The assembler writes a certain amount of information to its program window (or
on the command line screen) to let the user know what is happening. For each
source file both the current assembler pass and include file names are
displayed. During linking all object file names and specified names of library
modules are displayed. When all files have been processed and the necessary
output generated, a status message is displayed which informs you of how many
errors occurred (or none). You will also be reported with a message of how many
source lines that have been parsed during a compilation. This information can be
very convenient during a large compilation project, especially on relatively
smaller computers (with less powerful processors) and no harddisk. If you own a
powerful 32bit computer equipped with a fast harddisk, assembly information is
displayed at high speed (and almost impossible to read); it may then be useful
to turn this information off specifying a -nv option at the command line.
- Use alternative source file extension, -e
The default assembler source file extension is ".asm". Using this option, you
force the assembler to use another default extension, like ".opt" or "as the
source file.
The extension is specified without the ".". Only three letters are accepted
- the rest is discarded.
- Use alternative object file extension, -M
The default assembler object file extension is ".obj". Using this option, you
force the assembler to use another default extension, like ".o" as the object
file name extension.
The extension is specified without the ".". Only three letters are accepted
- the rest is discarded.
- Create listing file output, -l
The information in listing files is a combination of the original source file
and additional information of the generated machine code. Further, the listing
file is page formatted with a header specifying the date and time of the
compilation, the file name of the listing and a page number.
For each line of the source file the following information is written:
The machine code and assembler address output are written in hexadecimal
notation. If the machine code uses more the 4 bytes, the source file line is
written on the following line. This usually happens when you have defined a
string constant or a relatively large amount of constant definitions.
The assembler address is always beginning at zero, i.e. the beginning of the
current modules' machine code. In a relocated context of the machine code, where
all code is positioned at fixed addresses, you will have the opportunity to view
the addresses of your code relative to the start of individual modules using the
assembler output addresses. Further, the last assembler address can be
interpreted as the size of the modules' generated machine code.
Listing files also serves the purpose of a hard copy on paper of your programs,
and are useful in a debugging phase (identifying opcodes versus the mnemonic
representation of instructions).
The creation of listing files imposes much more processing work of the
assembler. If you want to compile your code as quickly as possible then don't
create listing files. Listing files obtain their file name from the base of the
source file name, and is added with the 'lst' extension.
- Create symbol table, -s
Symbol tables contains the integer form of symbolical names and constants that
has been parsed and generated during a compilation of a source file. The
structure of the symbol table is divided into two columns. The first contains
the parsed symbol names, converted to upper case. The second column contains the
generated value of the symbol name.
All symbol values are displayed in signed 32 bit hexadecimal notation.
The two columns are separated by tabulators which represents a default value of
8 spaces per tabulator. The width of the symbol name column is defined as the
tabulator distance multiplied by 4. The default with of the name column is 4 * 8
= 32 spaces.
The symbol table will be written to the end of the appropriate listing file, if
listing file and symbol table output is enabled. If no listing file output is
enabled, the symbol table will be written to a separate file, identified with
the base name of the source file module and given the 'sym' extension.
- Assemble only updated files, -d
Assemblers usually force compiles all specified files. This is also possible (as
default) for the Z80 Module Assembler. In large application project with 15
modules or more it can be quite frustrating to compile all every time. The
solution is to only assemble updated files and leave the rest (since they have
been compiled to the programmers knowledge).
But in a long term view it is better to just compile a project without thinking
of which files need to be compiled or not. That can be done with the Z80 Module
Assembler. By simply specifying the -d parameter at the command line, only
updated source files are assembled into object files - the rest are ignored.
Using the -d option in combination with a project file gives the best project
setup for a large compilation; compile your projects without worrying about
which module is updated or not.
- Link/relocate object files, -b
The -b option must be used if you want to create an executable Z80 machine code
output file of your previosly created object files. You may also use the -a
option which is identical in functionality but also includes the -d option. In
other words assemble only updated source modules and perform linking/relocation
of the code afterwards.
Pass 1: When the linking process begins with the first object module, it is
examined for an ORG address to perform the absolute address relocation of all
the object module machine code. The ORG (loading address for memory) will have
to be defined in the first source file module. If not, the assembler will prompt
you for it on the command line. The ORG address must be typed in hexadecimal
notation. If you never use the ORG directive in your source files, you can
always explicitly define one at the command line with the -r option. The next
step in the linking process is loading of the machine code from each object
module, in the order of the specified modules. Pass 1 is completed with loading
all local and global symbol definitions of the object modules. All relocatable
address symbols are assigned the correct absolute memory location (based on
ORG).
Pass 2: The address patching process. All expressions are now read and
evaluated, then patched into the appropriate positions of the linked machine
code.
When all expressions have been evaluated the machine code is completed and saved
to a file named as the first source file module, and assigned the 'bin'
extension.
-o
Define another filename for the compiled binary output than the default
source filename of the project, appended with the .bin extension.
- Splitting completed machine code into 16K segments, -c
This feature has only meaning to the Z88. Since the Z88 memory organisation is
based on 16K memory banks to be paged into the 4 segments of the Z80 address
space, it may be necessary to split your code into 16K blocks if it exceeds 16K
in size. Due to the size of the Z88 Assembler application, it is necessary to
position it as to separate blocks on the EPROM; in segment 2 and 3.
- Create address map information file, -m
When the linking process has been completed and the machine code saved to a
file, the address map file is produced. This file contains the information of
all relocated address symbols with their assigned absolute addresses. Further,
an id is written that displays the scope of the symbols; local ('L') or global
('G'). The last item of each address map line, identified after the colon, is
the name of the module which the symbol name belongs to.
The address map file is divided into two sections; the first produces the symbol
list in alphabetical order (fast lookup of symbol names), the second in order of
their address counterparts. The section is more used during a debugging session
when an address in a dissassembly needs to be identified with a name. The second
list also gives a chronological view (composition) of the linked modules. The
following is an example of an address map file:
- Re-define the ORG relocation address, -r
During the linking phase of the assembler the ORG address that defines the
position in memory where the code is to be loaded and executed, is fetched from
the first object module file. You can override this by specifying an explicit
address origin by entering the -r option followed by an address in hexadecimal
notation at the command line, e.g.:
-r4000
which specifies that your code is to be relocated for address 4000h (16384d)
onwards.
Using the -r option superseeds a defined ORG in an object file. You could for
example have defined the ORG to 8000h (32768d) in your first source file, then
compiled the project. This would have generated machine code for memory location
8000h (segment 2 in the Cambridge Z88). Since the object files are generated it
is easy to link them again with another ORG address by just using the -r option.
The linking process does not alter the information in object files - they are
only read. The same project could then easily be re-linked to another address,
e.g. -r2000.
- Generate address independent code, -R
The Z80 processor instruction set allows only relative jumps in maximum +/- 128
bytes using the JR and DJNZ instructions. Further, there is no program counter
relative call-to-subroutine or jump-to-subroutine instruction. If you want a
program to be address-independent no absolute address references may be used in
jump or call instructions. If you want to program Z80 address independent code
you can only write small routines using the JR and DJNZ instructions. With a
restricted interval of 128 bytes you can imagine the size of those routines!
Programming of large applications using address independency is simply
impossible on the Z80 processor with the basic instruction set available. You
can only define a fixed address origin (ORG) for your machine code to be loaded
and executed from. However, there is one solution: before the code is executed
an automatical address-relocation is performed to the current position in
memory. This is done only once. The penalty is that the program fills more space
in memory. This is unavoidable since information must be available to define
where the address relocation has to be performed in the program. Further, a
small routine must be included with the program to read the relocation
information and patch it into the specified locations of the program. It is
impossible to determine the extra size generated with a relocation table. We
assume an extra size of 3 - 3.5K for a typical 16K application program.
You can generate address independent code using the -R option accompanied with
the -a or -b option. There is no other requirements. The relocatable code may be
useful for programmers using the Cambridge Z88 who want to use machine code in
the BBC BASIC application environment. This can easily be interfaced with the
DIM statement to allocate memory for the machine code program, and issue a CALL
or USR() to execute the machine code.
Please note that the linking process with the -R option addresses your code from
0 onwards. This is necessary when the runtime relocation is performed by the
relocater (just before your program is executed). This can be examined by
loading the address map file into a text editor.
The principle of relocation is in fact a self-modifying program. You cannot
relocate a program that has been blown into an EPROM (cannot be modified). You
may only execute relocatable programs in dynamic memory (RAM).
The relocater is built into the Z80 Module Assembler. The relocation table is
created during the linking phase. When all object modules have been linked and
the appropriate machine code generated, the process is ended with first copying
the relocater routine into the executable file, then a relocation table and
finally the compiled machine code program. Any defined ORG in your code is
superseeded - this is not necessary in a relocatable program!
Two rules must be obeyed when using relocatable programs:
1. The IY register must have been set up to point at the address where your
program resides. The first code is in fact the relocater which manipulates your
code on the basis of the IY register. IF IY is not setup properly your machine
code program will be relocated for an address it is not resided at. On execution
your might then call a random address (on the basis of the random IY register).
2. Don't use the alternate register set for parameter passing between the caller
(of your code) in the main code and the relocated program. The following
registers are affected by the initial relocation process:
AFBCDEHL/IXIY/........ same
......../..../afbcdehl different
You still have all the main registers for parameter passing which is more than
sufficient for average programming.
When your address-independent code is stored to the file, a message is displayed
which informs the user of how many bytes the relocation header consists of. This
constant is useful since it informs you of the distance between the relocation
header and the start of your code. The map file automatically reflects the
relocation header. All addresses of your code has been modified to include the
relocation header. Please note that all addresses in the map file are defined
from address 0. When your code is placed in an absolute memory address, and you
need to perform a debugging session, you can find your specific label address by
adding the constant from the map file to the memory origin of your code. The
inbuilt relocator routine may be examined by extracting the "relocate.asm" file
from the "Z80src.zip" comressed file resource.
- Create global address definition file, -g
With this option it is possible to generate a DEFC directive definition file of
all globally declared identifiers in a file project (declared with the XDEF
directive). These global definitions are calculated from the specified ORG
address (from first module or the -r option). This feature is very useful, if
you want to get access to routines from a separate compilation. If the two code
compilation were placed in different banks of the Z88, it would be possible to
know the correct address of a routine just by using the DEFC address definition
previously compiled. We used this facility to access routines in the two 8K
halves of the segment 0 debugge version. This debugger actually swaps one of the
two 8K blocks in and out of segment 0 when needed to call an 'external' routine.
Applications on the Z88 may only acces the upper 8K of segment 0. A 16K
application therefore needs to be split in 8K halves and paged in when needed to
be run in this area. Tuff!
- Define a static symbol (logically true), -D
This option is useful if you want to produce conditional compilations. The
symbol defined here will be active throughout the compilation. We used this
feature to compile machine code on different computer platforms (QL, IBM, LINUX
or Z88). Specify the symbol immediatly after the option identifier, i.e.
-Dsymbol .
- Using a project file, @
Project files defines all file names of a project. The file name standard stored
in a project file obeyes the operating system notation.
In stead of specifying every module file name at the command line, a simple
reference of a project file can be made in stead. According to the rules of the
specification of parameters you specify either your source file modules or use a
project file. The project file specification is of cource much faster. An
example:
z80asm -a main pass1 pass2 link asmdrctv z80instr
This command line will compile all specified module file names into a single
executable file called 'main.bin'. However if a project file 'assembler' were
created already containing the same file names, the command line would have
been:
z80asm -a @assembler
- much easier!
A project file only contains file names. Each file name is separated by a new
line character \n. The new line character may be different on various computer
platforms - but the assembler interprets it correctly. The contents of a project
file may look like this:
z80asm\n
z80pass1\nz80pass1\n
modlink\n
The \n identifies a new line in the file ( in MSDOS or in LINUX).
Project files are easily created using a simple text editor. Always define
project files on the platform you are going to use for the assembly process -
this assures that you use the correct new line character; e.g. MSDOS uses
for new line, and QDOS uses only for new line.
- Include library modules during linking/relocation, -i
This option allowes compilation time linking of external machine code, better
known as library routines. Much, much programming time can be saved by producing
a set of standard routines compiled into library files. These may then be
included later in application project compilations. The command line option
allowes specification of several library files. For each library reference in an
application module, all library files will be scanned for that particular
module. The filename (inclusive directory path) of the library may be specified
explicitly on the command line immedialty after the -i identifier. If you ommit
the filename, a default library filename will be used by the assembler. This
default filename is defined by creating the environment variable
"Z80_STDLIB=..." ("..." refers to your filename). Please refer to your operating
system documentation on how to create environment variables. Library files are
recognised by the ".LIB" extension.
- Create a library, -x
A library file is composed of object files surrounded by a few file structures.
The library file format (and object file format) may be found at the end of this
documentation. A library is simply a set of independent routines (that may refer
to each other) put together in a sequential form. You may only specify a single
-x option on the command line. A filename may be explicitly defined (including
device and path information) to determine the storage location of the library.
As in -i you may ommit the filename to use the default filename identified by
the "Z80_STDLIB" environment variable. A library routine must be defined using a
simple XLIB directive with an identical address name label definition. Please
refer to further information later in this documentation. The "Z80lib.zip"
contains the standard library with all corrseponding source files. Have a look
at them - they clearly displays how to compose a library routine.
One very important aspect of libraries is the time that the assembler spends
searching through them. To optimize the search you should place your routines in
a "topological" order, i.e. routines that acces other library routines should be
placed first. In most situations you avoid redundant sequential searching
through the library.
- Define tabulator distance (for text output files), -t
To save storage space the Z80 cross assembler output files (listing, map, symbol
and XDEF definition files) uses a tabulator control character in stead of
spaces. The benefit is about 30% compressed files.
The tabulator distance defines the distance of space between each tabulator it
represents. The default value is 8 spaces per tabulator.
The tabulators are used to separate two columns of information. The first column
contains a name of some sort. Since names have variable length, a size of the
column is defined. The Assembler defines the size of the column by multiplying
the current tabulator distance with 4, i.e. giving a default size of 4*8 = 32
'spaces'. This is usually more than enough for most name definitions parsed from
source files.
You may redefine the tabulator distance by usign the -t option immediatly
followed by a decimal number, e.g. -t4 for defining a tabulator distance of 4.
The with of the first column will then be 4*4 = 16 'spaces'.
2.0 An overview of assembler features and related files
o The Z88 operating system definition files
You will find header files containing all operating system definitions as
defined in the Z88 Developers' Notes V3 in the "OZdefc.zip" file. This makes the
operating system interface programming a lot easier.
o The supplied standard library Z80 source files
We have supplied a standard library with useful routines for both beginners and
professional machine code programmers. All source files are supplied for having
the opportunity to study and improve the routines. However some routines are
programmed especially for the Z88 operating system and may not be of use for
other Z80 based computers unless thorougly rewritten. The standard library
source files may be found in the "Z80lib.zip" file.
o Z88 module assembler application source
We have supplied the complete source of the Z88 module assembler application.
This allowes you to evaluate many aspects of programming applications on the
Z88. Further, most features of the assembler are mirrored in these source files;
using directives, the free format of Z80 mnemonics, library routine access,
modular file design, labels, using expressions, comments, data structure
manipulation and good programming design.
o File based compilation
This assembler is completely file based, i.e. all parsing and code generation is
manipulated via files on storage medias such as harddisks or floppy discs (or
file based RAM-discs).
o Modular source file design
A compilation may be split into individual source files that either can be
linked together during assembly as a single module or assembled as separate
source file modules. Separate source file modules saves compilation time and
memory. Further, this design is much more straightforward and much more
logically clear in a design phase of a large compilation project than one huge
kludge of a source file.
o Scope of symbols in source modules
All source modules may refer to each others symbols by using XREF directives.
This means that you refer to external information outside the current source
module. The opposite of an external module reference is to declare symbols
globally available using a XDEF directive, i.e. making symbols available to
other source modules. Finally it is possible to have local symbols that is not
known to other source modules than the current. A label or constant that has not
been declared with XREF, XDEF or XLIB is local to the module.
o Using arithmetic and relational expressions
All directives that require a numerical parameter or Z80 mnemonics that use an
integer argument may use expressions. Expressions may be formed by all standard
arithmetic operators and relational operators. Even binary operators are
implemented. All expressions may contain external identifiers and is
automatically resolved during the linking phase. Only certain directives require
compilation time evaluable expressions.
o Source file manipulation
To allow the Assembler to execute in multitasking environments such as LINUX and
QDOS, all source input files are opened as shared I/O. This allows other
programs to access the source files while the assembler is working. All output
files (both text and binary files) are opened/created for exclusive use; other
programs will have no access to those files until they have been closed.
o Free format of assembler source files
The source files may be written in a free format. No fixed position columns as
needed as in the COBOL programming language. All text may be typed in mixed case
(the assembler converts all text input to upper case). Tabulators may be used
freely (in stead of spaces which also saves source file space) to suit the
programmers own habits of structured text layouts. However, one rule must be
obeyed: syntax of Z80 assembler mnemonics and most directives must be completed
on individual lines. Text files using different OS dependant line feed
standard are parsed properly; line feed types CR, LF or CRLF are automatically
recognized. So you can easily compile your sources from Linux/UNIX on an
MSDOS platform.
o Specification of filenames
Specification of filenames in source files are always enclosed in double quotes.
The assembler just collects the filename string and uses this to open a file.
This way all filename standards may be used as defined on different operating
system platforms.
o Including other source files into the current source file
The need for header file information such as operating system constants or data
structures is often indispensable for source file modules. In stead of copying
the contents of those files into each module, it is possible to include them at
run time (during parsing). Infinite include file levels are permitted, i.e.
included files calling other files.
o Conditional assembly in source file modules
Large compilation projects often need to compile the application in several
variations. This can be achieved with enclosing parts of the source with
conditional directives for the different variations of the application. This may
also be useful if the assembler source is ported to several platforms, where
inclusion of other source files (such as header files) are using different
filename standards. The conditional directives IF, ELSE, and ENDIF may be nested
into infinite levels.
o Undocumented Z80 instruction code generation
We have included the syntax parsing and code generation of the undocumented Z80
instructions for the sake of completeness. However, IM 2 interrupts must be
disabled before they are executed (an interrupt may otherwise occur in the
middle of the instruction execution).
Many games on the ZX Spectrum have used them to protect the code from prying
eyes. The Z88 native debugger code uses some of the un-documented instructions
for fast access to register variables.
o Object file generation
The Z80 Module Assembler generates object files that contains the compressed
version of an assembled source module. The information herein contains declared
symbols (local, global and external), expressions, address origin, module name
and machine code. The object file modules are much smaller than their source
file counterparts (often smaller than 2K).
o Transfer of object files across platforms
The Z80 Module Assembler is already implemented on several different computer
platforms. You may freely transfer the object files and use them as a part of
another cross-compilation. There is no system-dependent information in the
object files.
o Date stamp controlled assembly
To avoid unnecessary compilation of source file modules, it is possible to let
the assembler compile only recently updated source file modules by comparing the
date stamp of the source and the object file modules. Source file modules that
are older than object file modules are ignored. This facility is indispensable
in large compilation projects.
o Listing files
The assembler may generate listing files that contain a copy of the source file
with additional code generation information of Z80 mnemonics dumped in
hexadecimal format. The listing files are formatted with page headers containg
time of assembly and the filename. Line numbers are included which corresponds
to the source file lines.
o Symbol information
All symbol generated values used in source modules may be dumped to the end of
the listing file or as a separate symbol file. If the symbol table is dumped
into the listing file, each symbol will be written with page references of all
occurences in the listing file. Address symbols (labels) are addressed relative
to the start of the module. Symbol constants are written as defined in the
source. The symbol table are written in alphabetical order with corresponding
values in hexadecimal format.
o Linking & relocation of object modules into executable Z80 machine code
To obtain an executable Z80 machine code file it is necessary to link all
assembled object modules and relocate them at a defined address, where the code
is to be executed at in the computers' memory. The linking & relocation is
performed automatically after completed assembly of all specified source file
modules. The ORG relocation address is specified in the first object module.
o Address map files
The address map is an invaluable information during a debugging session of your
compiled program. This file contains all symbolical address labels with their
generated address constants after a completed linking/relocation of all modules
into executable machine code. The map file is ordered in two groups; the first
list contains all symbol names ordered alphabetically with corresponding address
constants, the second list contains all symbols ordered by their address value
(in chronological order).
o Symbol address definition files
As with address map files this contains information of globally declared
symbolical address labels, relocated to their absolute position as for the
compiled machine code file. However, the format is completely different; all
symbols are created as constant definitions to be included as a header file into
another source file and assembled. This is useful if you want to call
subroutines compiled separately in another project (originated in a different
memory setup).
o Error files
Error files are created by the assembler during processing. If any errors should
occur, they will be written to this file containing information of where the
error occurred in the source module. If no errors were found, the error file is
automatically closed and deleted.
o Creating and using object file libraries for standard routines
Machine programmers often re-use their standard routines. We have implemented a
file format for generating libraries using the existing object file modules.
Using a simple set of rules makes it very easy to create your own libraries from
your source file modules. Documentation of the library file format is included
in this documentation. At command line infinite number of libraries may be
specified. All will be searched during linking of your object modules for
referenced library routines.
3.0 Executing the cross assembler and environment variables
The following text describes how to execute the assembler and defining the
environment variables used by the assembler.
o The environment variables
The assembler uses two environment variables:
"Z80_STDLIB" define the default filename of the standard library filename.
"Z80_OZFILES" define the default path of the standard Z88 OZ system headers.
o Running in the QDOS/SMSQ operating system environment
z80asm may be compiled using the C68 compiler developed by the Walker brothers.
You also need the 'env_bin' file. This is necessary to install into the operating
system before using the assembler. It contains the environment variable facility
integrated on UNIX, MS-DOS and many other operating systems. Include the
following line into your BOOT upstart program:
LRESPR win1_ext_env_bin
The device and path 'win1_ext_' is just an example of where to store your system
extension file. You may have it on your BOOT disk as well. If you don't have
ToolKit 2 on your system use the following line in your BOOT program:
envext = RESPR(1024): LBYTES win1_ext_env_bin, envext: CALL envext
Use the following in your BOOT file to set the environment variables:
SETENV "Z80_OZFILES=win1_z80_src_oz_" SETENV "Z80_STDLIB=win1_z80_standard_lib"
The example filenames are only a demonstration. Change them as necessary.
o Running in the LINUX/UNIX operating system environment
This program can be executed on the LINUX operating system and any other
UNIX. The sources are strictly ANSI C and uses only library calls that are
described in Brian W. Kernigham and Dennis M. Ritchie's C books.
The important thing to remember before compiling it under UNIX, is in which
direction the integers are stored by the processor architecture; the
famous Big Endian and Little endian concept. The config.h file uses a
"ENDIAN" definition when z80asm must interpretate integers in big endian order.
Please set this definition according to your system's processor architecture.
Most people uses the Intel processor when running Linux - this is a little
endian architecture (so you don't need the ENDIAN define...).
You can compile z80asm using GNU C compiler simply by entering the following
on your command line:
gcc -o z80asm -O2 *.c
The environment variables needed by z80asm are easily added in your accounts
login script, ".profile" or ".bash_profile" in your home directory.
o Running in the MS-DOS operating system environment
This program can be executed on all MSDOS operating systems using the INTEL 8086
processor up to high speed 80386/80486/Pentium processors on IBM & compatible
computers. Add the source files to your favorite C compiler system in MSDOS
or Windows (here you need to specify compilation options o a console appliction).
The environment variables are easily put into your AUTOEXEC.BAT file. Simply
specify:
SET Z80_OZFILES=C:\Z80\OZ\ SET Z80_STDLIB=C:\Z80\STANDARD.LIB
Choose your own settings if you like.
If you want the assembler to be accessible in any path, add the path location of
the assembler in the PATH search line: ;C:\Z80
4.0 Z80 module assembler file types
o The assembler file types and their extension names
The Z80 Module Assembler uses several different file name extensions to
distinguish the type of files processed. The base name of the source file is
used to create the various assembler output file types. The following list
explaines the available files:
o The file name extension identifier
The file name extension identifier may be different from platform to platform.
UNIX has no defined standard. MSDOS and TOS uses '.'. QDOS uses the '_'
identifier. SMSQ also allowes the '.' extension identifer.
The Assembler implemented on the supplied platforms are defined with the correct
extension identifier. You can see this on the Assembler help page (executing the
program with no parameters).
- The source file extension
The extension for assembler mnemonic source files are 'asm'. Source files are
specified by the user with or without the extension - whatever chosen, the
assembler will investigate automatically what is needed to read the source
files.
- The object file extension
The extension for object files are 'obj'. The base file name is taken from the
corresponding source file name. This file is generated by the assembler from
parsing the source file and contains intermediate generated machine code, an
address origin of the machine code, symbol information and expressions.
- The error file extension
The extension for error files are 'err'. Before beginning processing the source
files, an error file is created. If any errors should occur, they will be
written to this file containing information of where the error occurred. If no
error were found, the error file is automatically closed and deleted. Error
files are simple text files that can be loaded by any text editor for
evaluation.
- The listing file extension
The extension for listing files are 'lst'. The base file name is taken from the
corresponding source file name. This file is generated by the assembler and
contains a hexadecimal output of the generated machine code that corresponds to
the Z80 mnemonic instruction or directive, followed by a copy of the original
source line. If selected, the symbol table is dumped at the end of the listing
file.
- The symbol file extension
The extension for symbol table files are 'sym'. The base file name is taken from
the corresponding source file name. The symbol table file contains information
about the defined and used symbols of the source file and their generated values
(labels and constants). The symbol file is only created if listing file output
is disabled.
- The executable file extension
The extension for executable Z80 machine code files are 'bin'. The base file
name is taken from the first specified source file name at the command line (or
project file). This is the linked and relocated output of object files and may
be executed by the Z80 processor. You may override this default behaviour
by using the -o option and specify your own output filename (and extension).
- The address map file extension
The extension for address map files are 'map'. The basefile name is taken from
the first specified source file name at the command line (or project file). This
file is generated by the assembler and contains a list of all defined address
labels from all linked/relocated modules with their calculated (absolute)
address in memory. Used for debugging reference.
- The definition file extension
The extension for global address label definition files are 'def'. The base file
name is taken from the first specified source file name at the command line (or
project file). This file is generated by the assembler and contains a list of
all globally declared address labels with their calculated (absolute) origin
address, fetched only during assembly of source file modules. The format of the
list contains constant definitions (addresses) and may be parsed e.g. as include
files for other projects.
- The library file extension
Library files are identified with the 'lib' extension. Library files may be
created using the -x option. Library may be included into application code
during linking of object modules.
5.0 Compiling files
o The assembler compiling process
The Z80 Module Assembler uses a two stage compilation process; stage 1 parses
source files and generates object files. Stage 2 reads the object files and
links the object file code, completes with address patching and finishes with
storing the executable code.
Stage 1, parsing & code generation of all source files, object file generation:
A source file is being parsed for Z80 mnemonics and directives. An object file
is created to hold information of module name, local, global and external symbol
identifiers, expressions and the intermediate code generation (but address and
other constant information). During pass 1 all Z80 mnemonics are parsed and
code is generated appropriately. All expression are evaluated; expressions that
contain relocatable address symbols or external symbol are automatically stored
into the object file. Expressions that didn't evaluate are preserved for pass 2.
When a source file has been read successfully to the end, pass 2 is started.
During pass 2 all non-evaluated expressions from pass 1 are re-evaluated and
stored to the object file if necessary. Errors are reported if symbols are stil
missing in expressions. When all expressions are evaluated and no errors
occurred, all "touched" symbols (used in expressions) are stored into the object
file, with scope, type and value. Then, the module name and generated code is
stored to the object file. Various file pointers to sub-sections of the object
file is resolved. The completion of stage 1 is to produce the symbol table
output (either appended to listing file if selected or as a separate file).
This process is performed for all specified source modules in a project.
Stage 2, linking object files and library modules, producing executable code:
Pass 1 of the linking loads information from each object file in the project;
the ORG address is fetched, identifiers (resolving scope, and absolute values)
loaded, and machine code linked. During this pass all external library modules
are fetched and linked with the object modules (if a library is specified from
the command line). When all modules have been loaded, pass 2 begins. Pass 2 then
reads each expression section from all object modules (including library
modules), evaluates them and patches the value into the appropriate position of
the linked machine code. When all expressions have been evaluated successfully
the executable code is stored. If selected, the address map file is produces
from the current symbol table resided in the data structures of the assembler's
memory is stored to a text file.
o File names
Specification of file names follow the convention used on the various platforms
that the assembler is ported to. Please read your operating systems manual for
more information.
o Portability of assembler file names
If you are going to port your Z80 Module Assembler files across several
platforms a few hints may be worth considering:
Avoid special symbols in file names like '_', '#' and '.' . They may have
special meaning on some operating system platforms. Use only 7 bit standard
ASCII letters in file names ('A' to 'z'). Non english language letters are not
always allowed, and further they may not be interpreted correctly when ported to
another platform. Avoid too long file names. Some operating systems have
boundaries for length of file names in a directory path. For example MS-DOS only
allows 8 characters in a file name (followed by an extension). Others may have
no boundaries.
o The standard platform identifier
When the Z80 Module Assembler is running a standard platform identifier is made
available. The identifier reflects the name of the platform:
"Z88" - the assembler is running on the Z88 portable computer.
"QDOS" - the assembler is running on the QDOS/SMSQ platform (QL & compatibles)
"MSDOS" - the assembler is running on the IBM MS-DOS platform of computers
"UNIX" - the assembler is running on the LINUX/UNIX platform.
The identifier might be very handy when you need to port your source files to
different computer platforms. We use them in for loading header files. Have a
look on the INCLUDE directive example in the Directive Reference section.
o Source file structure
The composition of a source file module is completely free to the programmer.
How he chooses to place the source code on a text line has no effect of the
parsing process of the assembler. The linefeed interpretation is also handled
by z80asm - it understands the following formats:
(used by QDOS/SMSQ/UNIX/AMIGA), (used by MSDOS),
(used by Z88/MacIntosh).
o Using local, global and external symbols
In larger application projects it is unavoidable to use a modular programming
design, i.e. splitting the source into several individual files. This approaches
the popular top - down design where you can isolate the problem solving into
single modules. The outside world just needs to know where the routine is to be
called by linking the modules with a few directives.
In the Z80 Module Assembler you only need two directives to accomplish just
that: the XREF and XDEF directives.
XREF declares a symbol to be external to the current source file module. This
tells the assembler that all expressions using that symbol is not to be
evaluated until the compiled object modules are to linked and relocated
together. Expressions that contains this symbol is simply stored into the object
file.
XDEF declares a symbol to be created in this module and made globally available
to other modules during the linking/relocation phase. All expressions that
contain a globally declared symbol is automatically stored into the object file.
When a symbol is created and is neither declared external or global, it is
implicitly defined as local to the current source module. The symbol is then
only available to the current module during linking/relocation.
If you want to access (external) library modules from a library, use the LIB
directive followed by the name of the routine. Several routine names may be
specified separated by a comma.
During the linking process all external and corresponding global symbols are
resolved. If two identical global identifier are loaded by the linking process,
the most recently loaded identifier is used by the linker.
o Defining symbol names
Good programming involves a structured approach to mnemonic identification of
names in subroutines, variables, data structures and other constants. The Z80
Module Assembler gives you several possibilities. The easiest and frequently
used one is DEFC (Define Constant). We have supplied a complete set of header
files (the "OZdefc.zip" file) containing the Z88 operating system manifests as
defined in the Developers' Notes V3 (the "devnotes.zip" file) which just
contains DEFC directives.
Each DEFC directive is followed by a an identifier name, followed by a = symbol
and then an evaluable constant expression (usually just a constant). Constant
definitions are usually operating system manifest or other frequently used
items. They are put into separate source files and later inserted into main
source files using the INCLUDE directive.
Though DEFC resolves most needs, it may be necessary to define variable areas or
templates containing names with an appropriate size tag (byte, word or long
word). This is possible using the DEFVARS directive. Here you may specify as
many names as needed in the group. Then, it is easy to add, re-arrange or delete
any of the variable names - only a few modifications and then just re-compiling
the necessary source files that use the templates. This would be a nightmare
with DEFC, since you have to keep track of the previous and next name in the
group in addition to count the size of all names. All this is managed by DEFVARS
automatically. Have a look at the syntax in the Directive Reference section.
With advanced Z80 programming you cannot avoid dynamic data structures like
linked lists or binary trees. The fundamentals for this are known as records in
PASCAL or strucures in C. DEFVARS is well suited for this purpose. Defining each
DEFVARS group with 0 automatically generates offset variables. The last name
then automatically defines the size of the data structure. Again, refer to the
directive reference for a good example.
A third possibility for an easy definition of symbols is to use the DEFGROUP
directive. Here you're able to define a set of symbols equal to an enumeration.
It follows the same principles as for C's ENUM facility. The default starts at 0
and increases by 1. If you choose, a specific identifier may be set to a value,
which then can set the next enumeration sequense. Again, this directive have
been made to implement an easy way of defining symbols and providing a simple
method to alter the identifier group. Please refer to the directive reference
for an example.
o Comments in source files
As always, good programming requires good documentation. Without comments your
programs loose overview and logic. Machine code is especially hard to follow -
have you trid to look at a piece of code 2 years after implementation AND
without any comments? HORRIBLE! There is never too many comments in machine code
- we especially like to use high level language as comments - it avoids
un-necessary text and logic is much more clear.
Comments in Z80 source files are possible using a semicolon. When the assembler
meets a semicolon the rest of the current source line is ignored until the
linefeed. Parsing will then commence from the beginning of the line. The
semicolon may be placed anywhere in a source line. As stated you cannot place
mnemonics after the semicolon - they will be ignored. The Z80 parser will in
many places accept comments without a semicolon has been set - but don't rely on
it. Better use a semicolon. The context is much more clear. The following is an
example on how to use comments in Z80 source files:
; **********************
; main menu
;
.mainmenu call window ; display menu
call getkey ; readkeyboard
ret ; action in register A
o Defining symbolic address labels
The main reason for using an assembler is to be able to determine symbolical
addresses and use them as reference in the code. These are defined by a name
preceeded with a full stop. It is allowed to place a mnemonic or directive after
an address label. An address label may be left as a single statement on a line -
you may of course use comment after the label. The following is a label
definition:
; *****************
; routine definition
.mainmenu call xxx ; mainmenu is the label preceeded with '.'
It is not allowed to position two labels on the same line. However, you may
place as many label after each other - even though no code is between them. They
just receive the same assembler address. It is not allowed to specify two
identical address labels in the same source file.
If you want to declare an address globally accessible to other modules, then use
XDEF for the address label definition, otherwise the label definition will be
interpreted as a local address label.
XDEF mainmenu
...
.mainmenu ; this label is accessible from other modules with XREF
You may use before or after the label - z80asm automatically handles the scope
resolution as long as you use XDEF to define it as globally accessible.
o Writing Z80 mnemonic instructions
All Z80 instructions may be written in mixed case, lower or upper case - you
decide! How you separate opcode words, register names and operands is your
choice. Only a few rules must be obeyed:
1) each instruction mnemonic must be completed on a single line. 2) the
instruction identifier must be a word, i.e. don't use space between CALL 3)
register identifiers must be a word, ie. HL not H L
A few examples which all are legal syntax:
Ld HL , 0
ld hl, $fFFF
caLL ttttt
o Optional Z80 mnemonic instruction syntax
We have added some syntactical option on a few Z80 mnemonics. They are:
DJNZ label (the comma is not needed)
IN F,(C) (special case instruction which only affects the flags)
The instructions below allow additional specification of the accumulator register.
Zilog standard convention is to only specify the source operand. Sometimes
it is better to specify the accumulator to make the instruction look more clear,
and to avoid confusion. After all, they specified it for "add", "adc" and "sbc".
sub a,r
sub a,n
sub a,(hl)
sub a,(ix+0)
sub a,(iy+0)
this syntax applies also to
"and", "or", "xor" & "cp"
o The undocumented Z80 instructions
We have included the parsing and code generation of the undocumented Z80
instructions. They are as follows:
LD r,IXL r = A,B,C,D,E,IXL,IXH
LD r,IXH
LD IXL,n n = 8bit operand
LD IXH,n
ADC A,IXL
ADC A,IXH
ADD, AND, CP, DEC, INC, OR, SBC, SUB, XOR ...
SLL A, B, C, D, E, H, L
SLL (HL), (IX+d), (IY+d)
(SLL = [S]hift [L]ogical [L]eft).
SLL does shift leftwards but insert a '1' in bit 0 instead of a '0'. Except for
the SLL instruction all have bugs related to an interrupt being able to occur
while the instructions are decoded by the processor. They are implemented on the
chip, but are reported to be unreliable. We have used some of them in our
debugger software for the Z88. Until now the code has been running successfully
on all our Z88 computers.
o Referencing library routines
When you need to use a library routine in your application code, you need to do
two things; include a library file at the assembler command line with the -i
option and refer to the library routine in your source file using the LIB
directive followed by the name of the library routine, e.g.
LIB malloc, mfree
which will declare the two names "malloc" and "mfree" as external identifiers to
the current source file module. Please note that you can declare the names
before or after they actually are referred in your program source,. Failing to
use the LIB directive will interprete labels as local symbols to that source
file module. When the parser meets the instruction that uses one of the above
names in a parameter, the parameter "expression" is automatically saved to the
object file for later processing.
During the linking phase of all the object files the specified library file is
automatically scanned for "malloc" and "free" and included into the application
code when found.
Much application programming can be saved in "re-inventing the wheel" if you
store frequently used standard routines in libraries. We have supplied a
comprehensive set of library routines that were created along the development of
the Assembler Workbench application EPROM. Use them as appropriate and add new
ones. We are interested in your work - if you feel that you have made some good
routines that others may benefit from, e-mail them to us and we will include
them into the standard library.
o Creating/updating libraries
Creating libraries is an inbuilt feature of the assembler. The following steps
are necessary to create a library:
1) define a project file containing all filenames (without extensions) in your
directory that contains all library routines (the easiest method since you later
can move all files to another directory). Remember to arrange the filename in a
topological order, i.e. library routines that access other routines must pe
placed first. This optimizes the searching through a library during the linking
process.
2) Each library source module uses the XLIB directive to define the name of the
routine. The same name must be used for the address label definition. If your
library uses other library routines then declare them with the LIB directive.
Please note that a library routine creates the module name itself (performed by
XLIB automatically). The module name is used to search for routines in a
library.
3) The command line contains the -x option immediately followed by your
filename. If you don't specify a filename, the default standard filename is used
(defined by the Z80_STDLIB environment variable). Then you need to specify your
project filename preceeded by @, for example:
Z80asm -xiofunctions @iofunctions
will create a library "iofunctions.lib" in the current directory (also
containing all library source files). The project file is "iofunctions" also in
the current directory.
Please note that no binary file is created (a library is NOT an executable
file), but a collection of object files sequentially organized in a file.
o Referencing routines in other compiled projects
It may be necessary in some situations to get access to routines previously
compiled in another project. This implies however a knowledge of their absolute
addresses during linking. This information is stored in the map file, but not
accessible in a form suitable to be parsed by the assembler. However, this is
possible in using the -g option at the assembler command line. The action
performed creates a DEFC list file of address labels that have been declared as
globally available (using the XDEF directive). Only compiled source files are
included in the list. If you were using the -a option (compile only updated
source files) and no files were updated then the -g file would be empty. If you
would like a complete list of all global routines then it is needed to compile
the whole project (using the -b command line option).
When the file is generated, it can easily be INCLUDE'd in another project where
your routines may access the external routines. You might do this in two ways:
1) including the file in every source module that needs to access external
routines. This may be the easiest solutuion if you're only going to need
external acces in one or two source modules. With many external calls in
different module of the current project it requires much altering of files.
2) creating a new source file that is part of your project. This file could
easily be the first file in your project but could just as well be placed
anywhere in your project. Declare each external name that is needed somewhere in
your project as XDEF, meaning that all names to be included are globally
accessible from this module. Then specify the INCLUDE of the DEFC list of the
other project file. As the names get loaded, they become global defintions. All
other definitions will be ignored and not stored to the object file (they are
not referref in the source module). All your other modules just needs to specify
the external names as XREF. During linking they all get resolved and your code
has access to external routines from a previosly compiled project.
Whenever the previous project has been re-compiled (and issued with -g option)
there is a possibility that routine addresses has changed. You therefore need to
recompile the extra source module in your project to get the new identifier
values - the rest of your compilation is unaffected (due to the XREF
directives). Only the linking process gets the new proper addresses. In example
1) you had to recompile all source files that would have used an INCLUDE of the
DEFC list file. In example 2) only one file had to be recompiled.
The principle of external addresses was used to compile the debugger version to
be resided in segment 0 (into the upper 8K). The actual size of the debugger
code uses 16K, but was split into two separate halfes to fit into the upper 8K
of segment 0. Each of the 8K code-segments had to get access to the other 8K
block. The solution was the -g option and cross referencing using XREF and an
additional source module (containing the XDEF declarations) that included the -g
list file of the other project compilation.
6.0 Using expressions
Expressions is almost unavoidable in source files. They define and explain
things much clearer than just using a constant. The Z80 Module Assembler allows
expressions whereever a parameter is needed. This applies to Z80 mnemonic
instructions, directives and even in character strings. The resulting value from
an evaluated expression is always an integer. All expressions are calculated
internall as 32 bit signed integers. However, the parameter type defines the
true range of the expression. E.g. you cannot store a 32 bit signed integer at
an 8 bit LD instruction like LD A, . If a parameter is outside an allowed
integer range an assemble error is reported. Finally, no floating point
operations are needed by the assembler. There is no real standard on Z80 based
computers.
Whenever an integer is stored in a Z80 file, the standard Zilog notation is
used, i.e. storing the integer in low byte, high byte order (this also applies
to 32bit integers). This standard is also known as little endian notation (also
used by INTEL processors).
Expressions may be formed as arithmetic and relational expressions. Several
components are supported: symbol names (identifiers), constants, ASCII
characters and various arithmetic operators.
o Constant identifiers
Apart from specifying decimal integer numbers, you are allowed to use
hexadecimal constants, binary constants and ASCII characters. The following
symbols are put in front of the constant to identify the type:
$ hexadecimal constant, e.g. $4000 (16384).
@ binary constant, e.g. @11000000 (192).
' ' ASCII character, e.g. 'a'.
o Arithmetic operators
All basic arithmetic operators are supported: addition, subtraction,
multiplication, division and modulus. In addition binary logical operators are
implemented: binary AND, OR and XOR.
+ addition, e.g. 12+13
- unary minus, subtraction. E.g. -10, 12-45.
* multiplication, e.g. 45*2 (90).
/ division, e.g. 256/8 (32).
% modulus, e.g. 256%8 (0).
^ power, e.g. 2^7 (128).
~ Binary AND, e.g. 255 ~ 7 (7).
| Binary OR, e.g. 128 | 64 (192).
: Binary XOR, e.g. 128 ~ 128 (0).
# Truncate expression as constant (remove relocatable address flag)
Arithmetic operators use the standard operator precedence, shown from highest to
lowest:
$@' (constant identifiers)
() ^ */% +-~|:
If you want to overide the default operator precedence rules, use brackets ().
o The # operator
This is not a real operator, though. It is only used as the first symbol in an
expression to identify that this expression evaluates to a constant, i.e.
containing no relocatable information. This feature may be necessary when you
have to calculate a distance between two address labels without letting the
assembler think it is a relocatable address. The assembler thinks that
expressions containing address labels are relocatable items. In 99% of any
expression used this is perfectly adequate.
During the linking phase such an expression may have undiserable side effect
when you want to produce relocatable machine code using the -R option. The
relocator identifies the expression as an relocatable item and will add a
constant to the evaluated value of the expression. This is a perfectly correct
handling in normal address references for relocatable code. However, since the
assembler cannot see this as a constant expression, you have to force it as one.
LD BC, end_relocator-relocator ; the relocator will add an ORG constant
LD BC, #end_relocator-relocator ; the relocator sees a constant expression
Normal executable code, compiled for a an absolute address, won't conflict with
the above problem, since no constants are added to expressions. All address
information is calculated during loading of the address labels in pass 1 of the
linking process. Pass 2 of the linking process just evaluates expressions
(thereby using the proper values of labels and other constants) and patches them
into the corresponding locations of the code.
o Relational operators
With relational operators you may form logical expressions resulting in true or
false conditions. The resulting value of a true expression is 1. The resulting
value of a false expression is 0. These operators are quite handy when you need
to perform complex logic for conditional assembly in IF-ELSE-ENDIF statements.
The following relational operators are available:
= equal to
<> not equal to
< less than
> larger than
<= less than or equal to
>= larger than or equal to
! not
You may link several relational expressions with the binary operators AND, OR
and XOR. You have all the possibilities available!
It is perfectly legal to use relational expressions in parameters requiring an
arithmetic value. For example:
LD A, (USING_IBM = 1) | RTMFLAGS
o The ASMPC standard function
In occasional circumstances it may be necessary to use the current location of
the assembler program counter in an expression e.g. calculating a relative
distance. This may be done with the help of the ASMPC identifier. An example:
.errmsg0 DEFM errmsg1 - ASMPC - 1 & "File open error"
.errmsg1 DEFM errmsg2 - ASMPC - 1 & "Syntax error"
.errmsg2
Here, a length byte of the following string (excluding the length byte) is
calculated by using the current ASMPC address value.
o The & operator
You may use expressions in string definitions when using the DEFM directive.
String constants are enclosed in double quotes, e.g. "abcdefgh". Several strings
and byte expressions may be concatanated using the & operator. The resulting
type of an expression in strings are an unsigned byte of the range of 0 to 255,
e.g.: "string_a" & "string_b" & 'X' & CR & LF & 0
o Symbol identifiers in expressions
Apart from using integer constants in your expressions, names are allowed as
well. This is frequently used for symbolical address label references (both
external and local).
Forward referencing of symbols is not really something that is important in
evaluating expressions. The logic is built into the assembler parser. If an
expression cannot be resolved in pass 1 of source file parsing, it will try to
re-evaluate the failed expression in pass 2 of the parsing. If it still fails a
symbol has not been found (XREF and LIB external symbols are handled during the
linking phase).
7.0 Directive reference
The Z80 Module Assembler directives are used to manipulate the Z80 assembler
mnemonics and to generate data structures, variables and constants. You are even
permitted to include binary files while code generation is performed.
As the name imply they direct the assembler to perform other tasks than just
parsing and compiling Z80 instruction mnemonics. All directives are treated as
mnemonics by the assembler, i.e. it is necessary that they appear as the first
command identifier on the source line (NOT necessarily the first character).
Only one directive is allowed at a single source line. Even though they are
written as CAPITALS in this documentation they may be written in mixed case
letters in your source files.
Since the directives cover very different topics of assembler processing, each
directive will be explained in detail, identified with a header description for
each text section. The following syntax is used:
<> defines an entity, i.e. a number, character or string.
{} defines a an optional repetition of an entity.
[] defines an option that may be left out.
BINARY "filename"
Loads a binary file at the assembler PC. This could for example be a static data
structure or an executable machine code routine. The loaded binary file
information is included into the object file code section. The assembler PC is
updated to the end of the loaded binary code.
CALL_OZ['('] [')']
The may be a 16bit expression and must evaluate to a constant. This
is an easy interface call to the Z88 operating system. This is an advanced RST
20H instruction which automatically allocates space for the size of the
specified parameter (either 8 bit or 16 bit). Code is internally generated as
follows:
RST $20
DEFB x ; 8bit parameter
or
RST $20
DEFW x ; 16bit parameter
DEFB <8bit expr>,{<8bit expr>} (-128; 255)
DEFW <16bit expr>,{<16bit expr>} (-32768; 65535)
DEFL <32bit expr>,{<32bit expr>} (-2147483647; 4294967295)
Stores a yte (8 bit), ord (16 bit) or a ong word (32 bit) at the
current assembler PC. Expressions may be used to calculate the constant. All
constant are stored in low byte - high byte order (little endian).
DEFC name=<32bit expression>{, name=<32bit expression>}
Define a symbol constant. The allowed range is a signed 32bit integer value. The
expression must be evaluable, i.e. no forward referencing identifiers. All
standard Z88 operating system header files use DEFC
DEFM
Stores a string constant at the current assembler PC. Strings are enclosed in
double quotes. Strings may be concatanated with byte constants using the &
operator. This is useful if control characters need to be a part of the string
and cannot be typed from the keyboard.
DEFGROUP
'{'
name {',' name ['=' <8bit expression>]}
'}'
Defines a group of identifier symbols with implicit values. This is similiar to
the enumeration principles used in C and PASCAL. The initial symbol value is 0,
increased by 1 for each new symbol in the list. You may include a which breaks the linear enumeration from that constant. The DEFGROUP
directive may be spanned across several lines and MUST be enclosed with { and }.
DEFGROUP is just a more easy way than: DEFC name0 = 0, name1 = name0, ...
The following example illustrates a useful example of defining symbol values:
DEFGROUP
{
sym_null, sym_dquote, sym_squote, sym_semicolon, sym_comma, sym_fullstop,
sym_lparen, sym_lcurly, sym_rcurly, sym_rparen, sym_plus, sym_minus,
sym_multiply, sym_divi, sym_mod, sym_power, sym_assign, sym_strconq, sym_and,
sym_or, sym_xor, sym_not sym_less, sym_greater, sym_constexpr, sym_newline,
sym_lf,
sym_name, sym_number, sym_decmconst, sym_hexconst, sym_binconst, sym_charconst,
sym_lessequal, sym_greatequal, sym_notequal sym_negated, sym_nil, sym_ifstatm,
sym_elsestatm, sym_endifstatm
}
DEFINE name,{name}
Defines a symbol identifier as logically true (integer <> 0). The symbol will be
created as a local variable and disappears when assembly is finished on the
current source file module. Nice feature for conditional assembly.
DEFS <16bit expression>
Allocates storage. The size of the area will be filled with zero bytes. The
expression must be [1; 65535].
DEFVARS <16bit expression>
'{'
[] []
{ [] [] }
'}'
::= 'a' .. 'z'
::= 'ds.b' | 'ds.w' | 'ds.p' | 'ds.l'
Defines variable address area or offsets. First you define the origin of a
variabe area. This may be defined using an evaluable 16bit expression
(positive). Each variable name is followed by a size specifier which can be a
byte, word, pointer (3 bytes) or long word size. This is particularly useful for
defining dynamic data strucures in linked lists and binary search trees.
Defining variable areas are only template definitions not allocations. An
example:
DEFVARS Z80asm_vars
{
RuntimeFlags1 ds.b 1 ; space for next variable is 1 byte
RuntimeFlags2 ds.b 1
RuntimeFlags3 ds.b 1
ds.w 1 ; space not defined
explicitORIG ds.w 1 ; 2 bytes space
asmtime ds.b 3 ; 3 bytes space
datestamp_src ds.b 6 ; 6 bytes space
datestamp_obj ds.b 6
TOTALERRORS ds.l 1 ; 4 bytes space
}
the following is useful for defining dynamic data structures:
DEFVARS 0
; 'PfixStack' structure (used for postfix expressions):
{
pfixstack_const ds.l 1 ; The stack item value
pfixstack_previtem ds.p 1 ; Pointer to previous element on stack
SIZEOF_pfixstack ; total size of data structure
}
This type of variable declaration makes it very easy for modifications, e.g.
deleting or inserting variable definitions.
A special logic is available too which can be used throughout individual source
files during compilation. If you specify -1 as the starting address, the last
offset from the previous DEFVARS which was not specified as 0 will be used.
This enables you to gradually build up a list of identifier name offsets across
DEFVARS areas in different source files. The following example explains everything:
defvars $4000
{
aaa ds.b 1
bbb ds.b 100
}
defvars -1
{
ccc ds.b 100
ddd ds.b 1
eee ds.b 10
}
defvars 0
{
fff ds.p 1
ggg ds.b 1
hhh ds.w 1
iii ds.p 1
}
defvars -1
{
jjj ds.b 100
}
Some of the symbols will look like this:
BBB = 00004001
CCC = 00004065
GGG = 00000003
JJJ = 000040D4
FPP['('] <8bit expression> [')']
Interface call to the Z88 operating systems' floating point library. This is
easier than writing: RST $18 DEFB mnemonic
This is an advanced RST 18H instruction which automatically allocates space for
the specified parameter. All Z88 floating point call mnemonics are defined in
the "fpp.def" file.
IF
[ELSE]
ENDIF
Multi-line-directive. This allows to assemble particular source lines between
the IF, ELSE and ENDIF directives. The logical truth of the IF condition depends
on which source lines will be assembled inside the directive construction. ELSE
is optional. Infinite nesting of IF directives are allowed. Each directive must
be specified on separate lines. An example:
if QDOS
INCLUDE "defs_h"
INCLUDE "symbol_def"
INCLUDE "#stdio_def"
INCLUDE "#fileio_def"
INCLUDE "#memory_def"
else
INCLUDE "defs.h"
INCLUDE "symbol.def"
if MSDOS | UNIX
INCLUDE "#stdio.def"
INCLUDE "#fileio.def"
INCLUDE "#memory.def"
endif
if Z88
INCLUDE ":*//stdio.def"
INCLUDE ":*//fileio.def"
INCLUDE ":*//memory.def"
endif
endif
INCLUDE "filename"
Another component that is frequently used is to 'link' an additional source file
together with the current source file. Usually this contains variable
definitions that is commonly used by several modules in a project. This makes
sense since there is no idea in copying the same information into several files
- it simply uses redundant space of your storage media. This is certainly
important on the Z88 which not always has huge amounts of installed user/system
RAM (usually 128K). The external source file will be included at the position of
the INCLUDE directive. You specify an include file as with the following
example:
INCLUDE "#stdio.def"
The format of the filename depends on the operating system platform. As with the
current source file, you may also insert files in include files. There is no
limit of how many levels (of files) you specify of include files.
Recursive or mutual recursive INCLUDE files (an INCLUDE file calling it self)
is not possible - the assembler program will immediately return an error
message back to you!
Include files are usually put at the start of the source file module but may be
placed anywhere in the source text. The current source file will be continued
after the INCLUDE directive when the included file has been parsed to the end of
file.
If you specifiy a leading '#' in the filename (as shown above) the assembler
automatically preceeds a default directory path, defined from the Z80_OZFILES
environment variable. Most of the time INCLUDE is used for including Z88
operating system manifests - which enables you to place them in a particular
place on your system. Using the '#' also enables you to have these OZ header
files placed anywhere on any computer platform. The '#' resolves this for you.
LIB name {,name}
Declares symbol as external to the current module. The symbol name will be
defined as the name of a library routine which will be automatically linked into
the application code from a library during the linking/relocation phase of the
compilation process (if a library has been specified at the command line with
the -i option).
LSTOFF
Switches listing output to file off temporarily. The listing file is not closed.
LSTON
Enables listing output (usually from a previous LSTOFF). Both directives may be
useful when information from INCLUDE files is redundant in the listing file,
e.g. operating system definitions.
MODULE name
Defines the name of the current module. This may be defined only once for a
module. All source file modules contain a module name. This name is used by the
assembler when creating address map files and for searching routines in
libraries. Further, it allowes the programmer to choose a well defined name for
the source file module. The position of the module name is of no importance; it
may be placed at the end or the start of the source file. However, it has more
sense to put it at the top. The syntax is simple - specify a legal identifier
name after the MODULE directive, e.g. MODULE main_module
ORG <16bit expression>
Define address origin of compiled machine code - the position in memory where
the machine is to be loaded and executed. The expression must be evaluable
(containing no forward or external references). All address references will be
calculated from the defined ORG value. The ORG address will be placed in the
current module that is being compiled. However, during linking only the first
object module is being read for an ORG address. The ORG is ignored during
linking if you have specified an -r option on the command line.
XDEF name {, name}
Declares symbol globally available to other specified source file modules during
the linking phase of the compilation process.
XLIB name
When you need to create a library routine, it is necessary to declare the
routine with XLIB. In fuctionality it declares the name globally available to
all other modules in project, but also serves as a searchable item in libraries.
A library routine does not contain a MODULE directive, since the XLIB name is
also identified as the module name (you only specify one library routine per
module).
XREF name {, name}
Declares symbol as external to the current module. The name must have been
defined as XDEF in another module to let this module reach the value of the
symbol during the linking phase.
8.0 Run time error messages
The following error messages will be written in corresponding error files
(related to a source file). Each error message will contain the name of the
source file and a line number where the error occurred in the file.
0, "File open/read error"
You have tried to access a file that either was not found, already opened by
other resources, or the assembler wasn't able to create output files (object
file, listing-, symbol-, map- or executable binary file).
1, "Syntax error"
This is a message used by many routines - hence the general but descriptive
message. You have tried to use illegal registers in Z80 mnemonic instructions,
specified an illegal parameter type (string instead of integer), omitted a
parameter (DEFB without constant).
2, "Symbol not defined"
This error is given if you are referring to an identifier (usually in an address
reference) that was not declared. Either a label definition is missing in the
current module or you have forgotten to declare an identifier as external using
the XREF directive.
3, "Not enough memory" / "No room in Z88"
Well, well. It seems that there wasn't enough room to hold the internal data
structures during parsing or linking your code. Delete any unnecessary running
applications/jobs then try again. If you got the message on the Z88, try also to
delete un-necessary files from the filing system of your current RAM card.
4, "Integer out of range"
You have an expression which evaluates into a constant that are beyond the legal
integer range (e.g. trying to store a 16bit value into an 8bit parameter).
5, "Syntax error in expression"
Quite clearly you ahve made an illegal expression, e.g. specifying two following
operands without an operator to separate them, used an illegal constant
specifier or using illegal characters that aren't a legal identifier.
6, "Right bracket missing"
Your expression is usgin brackets and is not properly balanced, i.e. too many
beginning brackets or to few ending brackets...
7, "Out of range"
Same as 4.
8, "Source filename missing"
There has not been specified any source file modules or project file to start a
compilation.
9, "Illegal option"
The command line parser couldn't recognise the -option. Remember to specify your
option in EXACT case size. You have probably used a space between an option and
a filename parameter.
10, "Unknown identifier"
The parser expected a legal identifier, i.e. a directiver or Z80 mnemonic. You
have probably omitted the '.' in front of a label definition, misspelled a name
or used a comment without a leading ';'.
11, "Illegal identifier"
You have been trying to use a name that is either not known to the parser or an
illegal identifier. This might happen if you try to use a register that is not
allowed in a LD instruction, e.g. LD A,F .
12, "Max. code size reached"
Is that really possible? Very interesting code of yours! Z80 machine code
program tend to be in the 32K range (at least on the Z88)... Well, the Z80
processor cannot address more than 64K. Start changing your code to a smaller
size!
13, "errors occurred during assembly"
Status error message displayed on the screen when the assembler has completed
its parsing on all modules. You have one or more errors to correct in your
source files before the assembler continues with linking the next time.
14, "Symbol already defined"
In the current source file, you have tried to create two identical address label
definitions, or other name identifier creators (using DEFC, DEFVARS, DEFGROUP).
15, "Module name already defined"
You have used the MODULE directive more than once in your source file, or used
both a MODULE and XLIB directive (library modules only need an XLIB).
16, "Module name not defined"
A MODULE directive is missing in your source file (or XLIB directive in a
library source file routine).
17, "Symbol already declared local"
You have tried to declare a symbol as XREF, but it was already defined
local, eg. using a ".lbaddr" in your source.
18, "Symbol already declared global"
You have two identical XDEF symbol declarations in your source file module.
19, "Symbol already declared external"
You have two identical XREF symbol declarations in your source file module.
20, "No command line arguments"
Ups - display Z80 Module Assembler help text.
21, "Illegal source filename"
You have tried to specify an option after having begun to specify filenames.
Options must always be specified before filenames or project files.
22, "Symbol declared global in another module"
You have two identical XDEF definitions in separate modules. One of them should
probably be an XREF instead.
23, "Re-declaration not allowed"
You are trying to specify an XDEF for a name that has already been XREF'ed in
the same module (or the other way around).
24, "ORG already defined"
Not used.
25, "Relative jump address must be local"
You have tried to JR to a label address that is declared as external (with XREF
or LIB). JR must be performed in the current source file module.
26, "Not a relocatable file" / "Not an object file"
The assembler opened a supposed object file (with the proper ".obj" extension)
but realised it wasn't conforming to the Z80 assembler standard object file
format.
27, "Reserved name"
You have tried to create a label or other name as "ASMPC".
28, "Couldn't open library file"
The library file was found but couldn't be opened (probably already opened by
another application resource)
29, "Not a library file"
Your library file is not a library file (at least is not of the correct file
format used by this assembler). Have you maybe used another "library" file? The
Z80 library file could also be corrupted (at least in the header)...
30, "Environment variable not defined"
The assembler reports that either the "Z80_OZFILES" or "Z80_STDLIB" environment
variables wasn't found in the operating system.
31, "Cannot include file recurseively"
An file was tried to be included which was already included at a previous
include level. INCLUDE "a.h" cannot contain an INCLUDE "a.h"...
9.0 Compiling the Z80 Module Assembler ANSI C source files
If it is needed to re-compile the assembler for the current platform or
compiling it for a new platform, two files must be stored together with the
source files present in the same source directory:
1) The 'config.h' file
This file contains three components:
a) A constant string (name) to identfiy the name of the platform the assembler
is running in. The name may be used in assembly source texts as an identifier
e.g. for conditional assembly of your compilation project.
b) A C compiler identifier to control #ifdef conditional compilation of the
assembler source files. If new platforms are added to the source files the
compiler identifier is added to the 'config.h' file. Please choose a well
defined name of the operating system.
c) If your processor architecture uses Big Endian integer storage (high
byte - low byte order), then it is necessary to use the "ENDIAN" directive
(e.g. for MC68000).
The 'config.h' file must be in the same directory as the C source files.
2) The 'symbol.h' file
This file contains all data structures (linked lists for
expressions, AVL binary trees for symbol tables, source module specifications,
etc.) used by the assembler C source files. Almost all C source files include
this file. The 'symbol.h' file must be in the same directory as the C source
files.
o The assember program supplied as ANSI C source files
The Z80 Module Assembler is already established on several computer platforms.
However, other programmers wishing to use the assembler on a another platform
must port the source files and compile them on a local ANSI C compiler. We chose
the ANSI C language because it is a widely known language, standardized and well
suited for text processing and compiler oriented applications. Further, a ANSI C
compiler is almost always available on various computer platforms.
o The format of the source files
The source files contain no binary information, such as internal data structures
for specific wordprocessors or editors. All source files are stored as 7 bit
ASCII characters using only new line (\n) and tabulators (\t) as control
characters. The syntax layout of the sources use the GNU programming style.
o Defining the current platform
As seen on the supplied 'config.h' file only one platform identification can be
active at one time. All other platform identifications are commented out (not
active). Setting more than one platform active may result in the C compiler
failing with unknown identifier errors or generating fatal code.
o The C source files
The Z80 Module Assembler is composed of the following ANSI C source files:
z80asm.c
This file contains the main entry of the assembler. Command line parsing,
assembler file control, calling of pass1, pass2, linking, relocating, code
generation. Various assembler output files are created from this source module.
z80pass.c
Control of pass1: source file parsing, inclusion of files, conditional assembly
and code generation to object files. Listing file generation. Control of pass2:
expression evaluation, patching and completion of object files. Patching in
listing files and symbol table generation (to separate file or at end of listing
file).
modlink.c
Control of linking and relocating of object module machine code. Also automatic
library inclusion and relocating of code modules. Creation of object module
libraries and executable Z80 machine code files. Creation of mapfiles (sorting
of symbols and writing to file).
symbols.c
Symbol table management og local, global and external assembler source module
symbols.
exprprsr.c
Expression parsing and evaluation. Storing of expressions in infix notation to
object files.
prsline.c
Source line parsing functions. These recognize identifiers, constants and Z80
standard mnemonics.
prsident.c
Here, all standard mnemonics and directives are found and executed to begin
parsing, generate machine code and store information into the object file.
asmdrctv.c
All function logic routines (DEFB, INCLUDE, ORG, DEFVARS, etc.) that parse and
code generate Z80 assembler directives.
ldinstr.c
All functions that parse and code generate the Z80 LD instruction group to the
object file.
z80instr.c
All functions that parse and code generate the rest of the Z80 instructions to
the object file.
hist.c
This contains the development history of z80asm, right from the start, with
more or less interesting details. if you make any changes, please specify them
here, supplied with your name (and maybe an email address).
This file uses c format multi-line comments. It is not needed to include this
file in the compilation project.
o Using a Make utility or a compiler front end
Most C compilers accept the following command line:
cc -oz80asm *.c
which will identify the execute filename as "z80asm". All c files will auto-
matically be compiled, and the main() function is automatically resolved in
the appropriate "main" source during compilation. You may however be forced
to use a make utility.
o Future platform implementations
If you have ported this assembler to a new platform, please send us a disc with
the appropriate files. PLEASE SPECIFY WHERE YOU HAVE MADE THE CHANGES.
We prefer MSDOS discs (since almost everybody can read/write them). If otherwise,
please specify the format. Send the discs to:
Gunther Strube
Gl. Kongevej 37, 4.tv.
DK-1610 Kobenhavn V
Denmark
I can also be reached by email: gbs@image.dk
The Z80 Module Assembler may have been further developed in parallel with your
port. It is of extreme importance that we know of all your changes to be able to
put them into a new release. Write a file with your programming changes, the
executable program, and which platform the assembler is running on. Make sure
that the compiled program may be distributed freely - some companies expect
royalties for selling/ distributing software that was compiled with their C
compilers. We take NO responsibility for illegally distributed programs! The Z80
Module Assembler is a GPL'ed program and should be kept that way to the
benefit of all developers...
10.0 File formats
o Object file format documentation
The structure of the object file format is designed exclusively for the Z80
Module Assembler. However, it may be useful for other programmers if they wish
to use the file format for other purposes. We have included the documentation of
the object file structure in this document. Improvement suggestions are welcome.
We hope to have designed a simple and straightforward file format. The
documentation may be necessary if you want to use the object file format in
other systems.
I have created the design structure of the object file format to be suitable
for future expansion. The primary aim of the design has been to maintain
structure simplicity and load efficiency during link processing.
The format of the object file is as follows:
0 [ 'Z80RMF01' ]
[ ]
[ ]
[ ]
[ ]
[ ]
[ ]
[ ... ]
[ ]
[ ... ]
[ ]
[ ... ]
[ ]
[ ]
n
The 0 (null) - defines start to total of bytes file length. The above
figure has deliberately been split into sections to clarify the file structure,
allthough there is no actual physical separation between the sections in the
file; each section is immediatly followed by the next.
The file pointers are 32bit integers stored in low byte - high byte order
(Little endian format - Z80/Intel notation).
Contains the ORG address for the linked machine code or FFFFh for no ORG address
defined.
Contains the following:
defines the resulting evaluation type range:
'U': 8bit integer (0 to 255)
'S': 8bit signed integer (-128 to 127)
'C': 16bit integer (-32768 to 65535)
'L': 32bit signed integer
defines the 16bit relative module code patch pointer to store result.
defines byte length of expression string.
contains the infix expression parsed from the source file.
Contains the following:
defines the scope of the name:
'L' is local,
'G' is global,
'X' global library
defines whether it is a:
'A' relocatable address,
'C' a constant'
defines length byte of the following string.
Contains the following which defines library reference names:
defines length byte of the following string.
Contains a preceeding byte identifying the length of the following string
Contains a preceeding 16bit integer identifying the total length of the
following machine code block.
o Library file format documentation
The library file format is a sequense of object files with additional
structures.
0 [ 'Z80LMF01' ]
[