z88dk - The z88 Development Kit - Retargetting


Home
News
Downloads
Documentation
Contact
Links
Introduction

As can be seen from the number of platforms that z88dk can generate code for, retargetting the kit for a new platform can be a trivial process.

This document is split into several sections, each of which adds an added degree of functionality to the new target, if you wish to retarget to a new machine then it is recommended that you follow the directory structure mentioned in this document - this permits easier integration and prevents the source tree from getting overly messy, with over 1500 files and over 7MB of code this is a very important thing to do!
Basic retargetting

Initial Steps

The first thing to do is to create a crt0 file in the z88dk/lib directory, this file is used for startup and should initialise the stack, set the origin of the program, parse any command line arguments (if supported), call the main function and then release resources on program completion.

There are a number of recommended starting places for these files, dependent on whether the application is ROM based or RAM based. If,

The system is ROM based, base your startup file on lib/rex_crt0.asm
The system is RAM based, base your startup file on lib/cpc_crt0.asm
The name of the file should be something along the lines of [3/4 letter id]_crt0.asm. This 3/4 letter id should be the unique indentifier that will be used throughout the source tree (Yes, the Spectrum is different, but this was a mistake a long time ago!).

In addition to the .asm file, you will also need to create a file with the suffix .opt, this should include the .asm, each for the z88, this file contains:
        INCLUDE         "#z88_crt0.asm"
Whilst we're in the lib/ directory you should go to the lib/config directory and create a .cfg file for your target. If you take a look at the config file for the system you based your startup on it then you should be able to work out what should go in it!

Library Routines

Create a directory z88dk/libsrc/stdio/[machine id]. This is the directory that will contain the basic routines that are needed for supporting a machine. Below is a list of functions that you should implement:

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. There is a generic fgets_cons() in z88dk/libsrc/stdio which might prove a useful skeleton for your implementation.

void puts_cons(char *str)       [optional]
Writes a NUL terminated string to the console, this call is provided so that the application writer can call this directly should they not wish to use any other stdio routines.

int getk(void)                  [optional]
Should read the current state of the keyboard, returning NUL if no key is pressed

Once you've written these files you should adjust/create Makefiles to generate your machines library.
Implementing file I/O

Initial Steps

Create a directory libsrc/fcntl/machine_id

Required Functions

The following functions are required to be implemented for full file I/O support.

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);
The purpose of these functions should be obvious, if your target doesn't support far pointers then they can be cast to near pointers inside the open/creat functions.

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 many platforms but for example on the Spectrum +3 this function would be of use. NB. A dummy function is located in z88dk/libsrc/stdio, but if it is implemented on your machine then it should be placed in fcntl.

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!

Graphics Support
Details to be written - contact Stefano for more details

Last Modified by Dom on 11.10.2003