Rakewell Limited



Z88 Programmer's Section

Z88 Assembler Workbench for QDOS, SMSQ or MSDOS (Now FREE (download here) or for £10 (excluding EPROM))

History & Introduction

The Assembler Workbench enables the Z88 user to develop applications for the Cambridge Computer Z88. As the name indicates you will write your applications in assembler, or more precisely, in Z80 machine code - a widely known low level language for the Zilog Z80 processor also fitted in Britain's most sold home computer, ZX Spectrum from the mid eighties.

The package was created with the intention to enable Z88 users to develop new applications with the minimum usage of a single Z88 and no advanced add-on hardware. Everybody with a basic knowledge of programming skills should be able to produce software on his/her Z88. We have now fulfilled that intention.

Since the Z88 was presented at the PCW in '87 a small group of people have made the effort to launch software items for this compact portable. They didn't have the tools presented in this package. As far as we know, some used the old CP/M-Z80 system and in-built Assembler with special hardware to upload code to the EPROM Cards, others developed their own tools on PC's. Even the SMALL-C (developed in the late '70) system was used to develop software for the Z88 by Wordmongers.

Cambridge Computer had the intention of selling a developers system to third parties (mostly dealers). They announced it in the V2 of the "Developers' Notes", but it never came into a final product. Shortly after the release of the 'Notes in 1989, Cambridge Computer moved to Scotland and all material and people involved in the Developers' system left the company. Only the already established Z88 Software Companies were left to create new applications who already began to leave the market.

On the basis of the shortcomings from Cambridge Computer we decided to create a developer's tool for the Z88. We began late '91 as a spare time project, with months of pauses throughout the years, then completed last year -1995, still with some documents left to be written. Now, with the encouragement of Vic Gerhardi of Rakewell Limited and several Z88 users, the software package has finally been completed. In spite of the long time of development, still many active Z88 users and developers are around. Even so there is lots of potential in the Z88 after 10 years! Start developing...

The Z88 Assembler Workbench includes several software components for the Z88 computer on a 128K ROM Card and executables running on the QL and compatible computers using QDOS or SMSQ(/E) on 1.44MB or 720K formatted discs. The package is also delivered for PC's using MS-DOS, supplied on 1.44MB discs.

The 128K ROM Card contains:

• Z80asm - the Z80 Assembler on the ROM Card.
• Zprom - EPROM programming utility to Z88 produce Application Cards.
• Intuition - a code testing environment for your machine code with built-in debugger.
• EazyLink - file transfer to other computers.
• ZetriZ - a "TETRIS" look-alike graphics game that exploits the PipeDream map area.

On supplied discs you will find:

• Z80 Cross Assembler on QDOS/SMSQ operating system (or MSDOS) that is 100% compatible with "Z80asm" on the Z88. This allows you to port source and object files to/from the Z88 to work on your assembler projects on both computer platforms.
• Intuition - stand-alone executable debuggers to be included with your ROM Card application to enable you to debug the application while executing in the Z88 operating system environment.
• Complete documentation of the Z88 operating system "OZ", also known as "Z88 Developers' Notes V3". 326 pages of PipeDream files. InterLogic have improved many details in V3; more examples, error corrections, new sections and many new low level operating system calls are documented. A complete Z80 instruction reference is also included.
• Hundreds of pages of documentation of all Z88 applications (on the ROM Card), the Z80 Cross Assembler and "Link" executable for QDOS/SMSQ or MSDOS. The EazyLink file transfer protocol is also explained.
• Lots of Z80 assembler sources. You will first of all find the include files for all "OZ" manifestation mnemonic definitions, used in the "Developers' Notes V3". This avoids the need to use "magic numbers", but more correct definition names in your source files. Then, there is thousands of lines of the Z80 assembler source files; the standard library comprising many useful routines for your Z88 application projects, an extract of Z80 sources of the "Z80asm" application for evaluation, and all the Z80 sources for the "ZetriZ" application for evaluation. This enables you to exploit good application development on the Z88. We hope to inspire your programming skills on the Z88. All ASCII use tabulators where appropriate to save space.
• The "PCLINK II" application supplied as disassembled source. The "PCLINK II" ROM was part of the file transfer package supplied by Cambridge Computer.
• ANSI C sources for the QDOS/SMSQ and MSDOS supplied executables "Z80asm" and "Link". This would enable you to recompile the programs on other platforms. Please note that Z80asm is already ported to MSDOS by InterLogic. All ASCII text file use tabulators where appropriate.
• Also supplied is a utility to produce source files from Z80 binaries, named "DZasm". ANSI C source files for the utility is supplied as well. It supports all Z88 operating system manifests and the undocumented Z80 instructions that ZILOG left out of the Z80 instruction specification when the Z80 was officially released. With "DZasm" you might produce source code from the Z88 ROM and include it in your own applications.

Some of the components of the Z88 Assembler Workbench are Free ware. You are allowed to distribute the following components to other users:

• Executable and ANSI C source files of "Z80asm", the Z80 Cross Assembler, with documentation.
• Executable and ANSI C source files of "Link", the "EazyLink" Client transfer utility, with documentation.
• Executable and ANSI C source files of "DZasm", the Z80 source file generator.
• The standard library for the Z88 Assembler Workbench with Z80 sources files.
• "Developers' Notes V3".

Z80asm - Z80 Module Assembler (running as native Z88 application or cross assembler)

The Z88 already contains a small in-line assembler built into the BBC BASIC application. However, it is a limited developers environment since all the source has to be part of the BBC BASIC program. On an expanded Z88 this allows you to sizes of max. 40K BASIC programs (of source text) that needs to be loaded into the BBC BASIC application, then compiled into machine code inside the same memory space of the BBC BASIC application. The end result is not much. BBC BASIC gives an opportunity to develop small machine code utilities to complement the BBC BASIC interpreter.

The Z80 Assembler application on the Z88 (and cross assembler versions on other platforms) enables you to compile ASCII text source files into machine code. Z80asm is an integrated Z80 parser, linker and library manager. The following features is available:

• project setup for modular file compilation and linking
• facilities controlled using UNIX-alike command line interface
• date stamp controlled assembly
• on-line help for all directives and other facilities in the Z88 "Z80asm" application
• 2 Pass text file parsing
• error files
• 2 pass linking
• 16K boundary splitting of compiled code (only needed for EPROM applications)
• all compiling stages uses dynamic memory principles for unlimited compilation
• multiple line feed support (CR, LF and CRLF) on Z88 version of assembler
• free format of source files
• compact object file format for intermediate code used by in-built linker
• conditional assembly using multilevel IF, ELSE, ENDIF directives
• list file output (including page info headers, line numbers and hex code dump)
• symbol table output for each compiled module
• Multiple level INCLUDE file support (for header files or other source files)
• loading of external BINARY files into code (specified as directive in source)
• data directives, data structures templates, enumeration
• free-form expressions allowed for all instruction constants (addresses, operands), arithmetic operators
• relational operators
• object file generation (ready for linking)
• Z80 relocatable code generation
• creation of library files (searchable object files)
• address map files (of compiled, executable code) for debugging purposes
• create global address definition file
• code generation of ZILOG's undocumented Z80 instructions
• compatibility across platforms

Project setup for modular file compilation and linking

Application projects can be split into modular format and combined during linking into a single Z80 native executable. Each source file module has its own name and scope of local identifiers. Each module can reference to external identifiers that in turn has been defined as a global identifier in a particular source file module. Scope of identifiers are managed using the XDEF (define global identifier) and XREF (reference external identifier) directives.

Each module can be specified on the command line or in a project file containing all (file)names of the project. The organisation of the files in a project also determine the location in the compiled code.

Facilities controlled using UNIX-alike command line interface

The syntax of the assembler parameters is a straightforward design. Filenames or a project file are always specified. The options may be left out:

z80asm [options] <filename {filename}> | <#modulesfile>

As seen above <options> 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 #<modulesfile> containing all file names. File name are specified without the 'asm extension. This is added 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 pre-set 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 (help page is displayed when no arguments are specified at the command line.

The assembler options are used to control the assembly process and output. They are recognised 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 pre-set 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. The following list displays the all available options:

• Create listing file output, -l
• Information during assembly, -v
• Create symbol table, -s
• Assemble only updated files, -d
• Link/relocate object files, -b
• Splitting completed machine code into 16K segments, -c
• Create address map information file, -m
• Redefine the ORG relocation address, -r
• Generate address independent code, -R
• Create global address definition file, -g
• Define a static symbol (logically true), -D
• Include library modules during linking/relocation, -i
• Create a library, -x
• Define tabulator distance (for text output files), -t

Date stamp controlled assembly

To facilitate large projects, date stamp controlled assembly is unavoidable. The Z80asm application itself if a large project of nearly 1MB in size. Without the ability to compile only the last modified source, it would have been a pain to develop it. With no updated source files compared to the corresponding object files, the assembler automatically begins the linking process (if linking has been enabled).

On-line help for all directives and other facilities in the Z88 "Z80asm" application

The Z80asm application on the Z88 has been provided with 24 help topics containing compact descriptions of all available assembler command line options, directives in source files, assembler principles and much more. With the on-line help you can easily acquire the simply interface of an otherwise complex application. Pressing the <HELP> key display all 24 items to be selected by <ENTER>. However, everything is not explainable in 24 simple topics. You will find a 100K comprehensive documentation of Z80asm on the supplied discs.

2 Pass Text file parsing

The Assembler is based around the principle of a two pass assembly of the source files. The first stage performs all syntax parsing, source file manipulation (Include files, conditional assembly) and code generation. Pass 2 evaluates all forward referenced names and expressions. During pass 1 and 2 the object file is generated. The object file is the basis of the linking process to generate the executable code. The object file contains unresolved expressions to references of external identifiers referenced in other source modules, local and globally defined identifiers and the raw code generation of the source module without address referencing. All parsing is performed using dynamic data structures for symbol tables and other control structures. The outcome of this is unlimited compilation - the only barrier is your computer's memory and disc storage capacity (this applies both for the Z88 and Cross assembler version).

The complete source including OZ definition files and other header files was actually compiled on the Z88 using 1MB RAM for testing purposes. At maximum, the assembler had allocated 350K during the linking process for all internal data structures of the complete project. Every bit of the RAM card was exploited to perform the complete process of producing the executable application code of the Z88 version of Z80asm.

The 2 pass file parsing allows you to create symbol table output files (address relative) and listing files (containing line numbers and intermediate hex dump of generated Z80 code in front of each line).

Create listing file output

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:

<source file line number><assembler address><machine code hex dump><source line>

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).

Create symbol table output

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.

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 during parsing of the current source file module, the error file is automatically closed and deleted.

Multiple line feed support (CR, LF and CRLF) on Z88 version of assembler

The Z80asm application supports three line feed standards - probably the only known at all. The reason for this is the pure simplicity of transferring your source files from one system to the Z88 with modification. Without automatic line feed support you would need to convert source files to the local Z88 standard before compiling. The Z80asm on Z88 support LF (QDOS and UNIX standard) and CR (Z88 standard) as single line feed characters, and CRLF as extended line feed (the MS-DOS/Windows standard).

Line feed conversion would in fact not be difficult anyway, because you can easily specify these in EazyLink during transfer. The only problem is to remember to actually perform it and not get different line feed standard mixed in your source files.

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.

Conditional assembly using multilevel IF, ELSE, ENDIF directives

One of the advantages of conditional assembly is to produce different versions of your application using simple identifier mnemonics and logical markings in the source. The Z80asm has been implemented with this feature using a straightforward model of the IF - ELSE - ENDIF clause.

Each IF may be expressed with a constant or a true non-forward referenced expression. Inside each sub-block you may place your source. Only the source inside the IF-ELSE-ENDIF block that evaluates to the true-false nature of the IF expression is parsed. You may perform as many nesting of conditional assembly as needed. There is no limit to the amount of nesting levels. Conditional assembly is perfect for INCLUDE files; e.g.. the same constant definitions but placed differently on the various platforms of your project (Z88, QL, PC ...).

Multiple level INCLUDE file support (for header files or other source files)

An important facility in a source file developing system is to extract definitions in external "header" files. This saves spaces and makes it easier to adjust constant values that affect the whole project. The Z80 Assembler has implemented the INCLUDE directive which allows you to merge external source files at the current position within the current source file being parsed. You may also specify other INCLUDE directives inside your included files. The only limit necessary is to avoid including files that also includes the current file - which would create an endless loop and an application crash.

Loading of external BINARY files into code (specified as directive in source)

Most of the time all developments of your project is source code containing assembler mnemonic and data structure definitions using a mixture of data directives like DEFB, DEFW and DEFS. However, sometimes it may be necessary to specify an external source of data that is not immediately available as source text. Using the BINARY directive you may merge external binary data from a file into the current position of the code (defined by the current relative position of the code generation of pass 1).

Data directives, data structures templates and enumerations

The second most important feature in an assembler (apart from symbolic assembler instructions and address labels) is the ability to define data or data structures. Z80asm implements all the necessary data directives:

DEFB <8bit expr> {,<8bit expr>} (-128; 255)
DEFW <16bit expr> {,<16bit expr>} (-32768; 65535)
DEFL <32bit expr> {,<32bit expr>} (-2147483647; 4294967295)
DEFM <string expression>

Directives for defining constants:

DEFGROUP '{' name {',' name ['=' <8bit expression>]} '}'

Defines a group of identifier symbols with implicit values. This is similar 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.

DEFC name=<32bit expression>{, name=<32bit expression>}

Define a symbol constant. The allowed range is a signed 32 bit integer value. The expression must be evaluable, i.e. no forward referencing identifiers. All standard Z88 operating system header files use DEFC.

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.

DEFVARS <16bit expression>
'{'
[<name>] [<storage_size>
<size_multiplier>]
{ [<name>] [<storage_size>
<size_multiplier>] }
'}'
<name> ::= 'a' .. 'z'
<storage_size> ::= 'ds.b' | 'ds.w' |
'ds.p' | 'ds.l'

Defines variable address area or offsets that first defines the origin of a variable area. This may be defined using an evaluable 16 bit 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 structures 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
}

Compact object file format for intermediate code used by inbuilt linker

Object files are very compact compared to the original source file. The main purpose of object files is to avoid continuous recompilation of source files even if they haven't been altered (the idea behind date stamp control). The next important factor is size. On the Z88 a developer needs every byte possible. Using a compact format it may be possible to compile relative large application projects on the Z88. You could for example compile all your source files into object code, then remove the source files from memory to obtain sufficient space to link all modules into executable code.

The next obvious reason for object files is the need to keep information about the assembled module for the linking stage (local, global identifiers, expressions and unresolved addresses). Some assembler actually perform everything at once but on the price of huge processing time and space. The object file format is documented. Developers are welcome to add new features to the object file format.

Code generation of ZILOG's undocumented Z80 instructions

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 undocumented instructions for fast access to register variables. They are as follows:

LD r,IXL r = A,B,C,D,E,IXL,IXH
LD r,IXH
LD IXL,n n = 8 bit 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.

Freeform expressions allowed for all instruction constants (addresses, operands), arithmetic operators

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 wherever 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 internally 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, <n> . 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 32 bit integers). This standard is also known as little endian notation (also used by INTEL processors).

All basic arithmetic operators are supported: addition, subtraction, multiplication, division and modulus. In addition binary logical operators are implemented: binary AND, OR and XOR. The following is the complete list :

+ 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)

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

2 pass linking

The first linking stage of the assembler scans all available object files in the project for identifiers (both local and global), creating symbol tables and loading of the raw Z80 code. The machine code is gradually added together to form the complete executable code. Pass 2 evaluates all expressions from all modules and performs the address patching of the complete executable code. When both passes are complete, the completed code is saved to a file and an address map file is generated (if selected) that contains all label references defined with the actual address in memory when the Z80 code is executed.

Create global address definition file

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).

Z80 relocatable code generation

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 automatic address-relocation is performed to the current position in memory. This is done only once. A small routine must be included with the program to read the relocation information and patch it into the specified locations of the program. You can generate address independent code using the -R option on the command line. 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.

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 superseded - this is not necessary in a relocatable program!

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).

Creation of library files (searchable object files)

The Z80 Assembler also enables you to develop libraries that you can include into your application projects during linking. Libraries are an organisation of object files. Each object has a name definition that is used to find the module during linking if another module references it. Libraries are usually organised in a project file containing all filenames of the modules. Modules benefit from being organised in topological order for optimal lookup.

Compatibility across platforms

Source files are usually no problem between platforms. However, Z80asm on the Z88 supports 3 different new line formats - <CR>, <LF> and <CRLF>. This enables you to easily port your sources from your main computer and continue compilation without changing the line feed format of your sources.

The compiled object files can be ported to the platform of the Z80 cross assembler and linked to produce the native code. The object file format is also documented to enable for further development or external utilities that may manipulate the object files. Object files are small and thus easy to transfer between platforms.

Zprom - EPROM Programming Utility for Z88 Application Cards

This application takes compiled Z80 code and blows it into a conventional UV light EPROM Card or by using additional commands to handle erasing and programming, the new 1M Flash EPROM.

Since the Z88 already has the hardware, it was only a simple step to exploit this facility into producing a utility to enable the developer to create his own EPROM Application Cards. Other solutions would have been to use EPROM add-on hardware on a stationary computer with a special adapter (using a Z88 slot edge-connector that converts to a standard chip pin out) to allow an EPROM card to be blown. Too expensive and with a problem to fetch a Z88 edge connector - only possible if you destroy a Z88!

You may also use Zprom to perform copies of existing Application Cards if you want to use the EPROM card for file storage in stead, or even want to transfer applications from 32K Cards to 128K or larger Cards (enabling more applications to fit in one single Card). Zprom also facilitates commands to view, edit or copy every part of the Z88 memory to a file (through a work buffer). Binary search facilities in all available memory are also possible.

Special commands are available to load memory blocks directly into a RAM Card. This requires a special modified RAM Card that the Z88 operating system regards as an EPROM Card. The modified RAM Card is very useful in software development since you avoid the tedious task of using EPROM Cards as the developing media (remember that you have to erase them again!).

All Zprom commands have in-built on-line help for easy learning of the EPROM management principles. Pressing the <HELP> key in conjunction with a <MENU> key automatically displays on-line help for that command. 24 stand-alone topics have been provided as well for an easy understanding of Zprom principles and the underlying Z88 hardware architecture. However, all necessary information cannot be explained in detail through the on-line help. You should then go for the Zprom documentation (PipeDream format) or read the Developers' Notes V3 (also in PipeDream format) for all necessary knowledge about the hardware organisation of the Z88.

Intuition - a code testing environment with built-in debugger

Forming an idea of a program, developing it through the symbolic code of assembler is about two processes. The challenge at hand is to make it run reliably and efficient. This is almost an impossible task with a low level language as assembler - especially the Z80 with it's limited registers and operands. Still, it has become a popular programming issue for thousands of users on the ZX Spectrum. Remember some of the Ultimate Games?

The Z88 is born with a sophisticated operating system. With all it's system traps to manipulate it's device-, memory- and file resources it's a vital component of the development stage that you have a debugger at hand that can execute your code and allow you to investigate the execution step by step. monitor correct set-up of your system calls and watch how the application is executed side by side with a window that displays the Z80 instruction while they are executed. Intuition is just that. Intuition has all the necessary features for the novice and professional developer:

• Single stepping, or tracing code with definition of up to 8 address breakpoints
• Instruction opcode breakpoints (stop at instruction, e.g. just before a specific operating system call)
• Recursive subroutine tracing (e.g. trace CALL instruction and sub CALL's)
• Break instruction execution at any time from keyboard using <SHIFT><DIAMOND>
• Break at OZ call error (All OZ calls return the Carry Flag = 1 if an error occurred)
• Register dumps and command line register manipulation
• Number Conversion Utilities (e.g.. Hex to binary and decimal)
• Disassembly with optional opcodes. All OZ mnemonic calls represented. Disassemble code in Z80 address space or extended addresses (all available Z88 memory).
• Memory editing, viewing and searching in address space or available banks
• View application windows (always preserved by Intuition)
• Extended CLI screen logging with up to 256 different files in current RAM device
• Display disassembly with optional register dump while executing application
• Seamlessly integrated with the operating system (switch freely out of the debugger in command mode to activate other applications)
• 24 topics of On-line help containing descriptions of all available Intuition commands and facilities. If you're in doubt of how to access a feature in Intuition, press <HELP> and a menu displays all available items.

You may use the Intuition application (#ZI) as a test ground which provides 40K of contiguous memory - the same principle behind the BBC BASIC application. This is of course pure luxury. Real Z88 application are memory efficient programs that exploit the fragmented memory scheme as in PipeDream or Diary. We made this debugger version only to supply the programmer with a quick feature to test modular routines. However, you could use the Intuition application as an environment for machine code utility programs, e.g. loading different small programs at various memory areas and providing a menu which could activate each routine. This would be a way to avoid the Application Card production and insertion of the card to be able to run the code.

The real power of Intuition is to be able to monitor the external applications on EPROM Cards and seamlessly interface with the Z88 operating system. Traditional debuggers require RAM to monitor programs, but we implemented a virtual Z80 processor that is the core of the debugger - this avoids the traditional memory address patching technique for redirecting the flow of instructions back to the debugger (e.g. on a breakpoint). Patching is impossible on EPROM, as you may well know.

When Intuition has encountered a breakpoint during execution of the monitored application, it enters command mode and uses the GN_SIP operating system call (standard line input). Intuition only monitors applications, not the operating system. This is necessary due to the interrupt system and for security reasons - imagine killing a monitored application while the operating system is being traced!

The virtual Z80 processor just executes opcodes (bytes) directly from memory whether it is RAM or EPROM. The average speed loss in execution of your monitored application is about 11 times slower than the original processor. The core of the debugger, the Z80 instruction parser, is packed in 8K. All remaining features are resided in the next 8K - a comprehensive debugger only in 16K of memory.

Intuition - stand-alone executable debuggers for inclusion in external EPROM Cards

As mentioned before, The Intuition Application is merely for testing purposes of routines with the need for EPROM blowing. The real core of Intuition is to include it with an external Application on EPROM. On insertion of the Card into the Z88 and activation of the application (pressing it's hot key) you just call the debugger once from your external application and Intuition takes over. From then on you may monitor your application and still be able to switch out to other applications when Intuition enters it's command mode. Intuition may then be preempted (activating other applications) but the Z88 only sees the external application present on the Card.

The Z88 memory organisation inhibits the segmentation principles found on Intel 80x86 processors. The Z88 can address 4MB of memory which is divided into 16K banks that can be made to point into the Z80 address space. The Z80 address is 64K which are divided into 4 logical segments. Each segment may hold one of the 256 possible memory banks in the Z88. The application programmer has control of which banks that are bound into the Z80 address space during run time of the application.

We have made Intuition to fit into a 16K bank to allow the developer to choose which segment he wants to insert Intution. Three different versions are available, which are resided as binary files on the supplied 3.5" discs:

• Intuition addressed and configured for segment 0 (8K boundary). Intuition actually divides itself into two 8K halves and swap's each half into the 8K half of segment 0.
• Intuition versions addressed for segment 1 and 2 (16K boundaries).

EazyLink - file transfer to other computers

EazyLink provides a simply interface to transfer files back and forth between the Z88 and another computer connected to the serial port. The difference between conventional file transfer and EazyLink is that the user controls all from one computer - the machine talking with the Z88. The Z88 EazyLink pop down acts as a file server, awaiting commands from the Client to be processed, followed by a response e.g. returning a file). The Client program is executed on your host computer where all information is displayed inside the Z88, and where commands are activated. The "Link" Client (separate product - not part of Assembler Workbench) executable is supplied  as a complete GUI application currently for Windows 3.x or Windows 95/NT. QDOS/SMSQ GUI versions are under development. A simple command line oriented version is bundled with the Assembler Workbench that handles all request for file protocol level 04 of the EazyLink Communication Protocol.
EazyLink Server enables you to perform the following:

• Request for all Z88 RAM devices
• Request for directories at a defined path. Wild cards may define all directories in all devices.
• Request for files in a defined path. Using wild cards you may receive all available file names in the Z88.
• Request for receiving a file or several files. Wild cards allows for parsing through directories in all devices.
• Request for backup of only updated files (Create & Update stamp logic).
• Transmitting of a file or files to the Z88. Path (directory) definitions in filenames are automatically created in the Z88 filing system when files are received by EazyLink.
• Request for file existence.
• Request for file size
• Delete Z88 file
• Rename Z88 file
• Create Z88 RAM Directory
• Delete Z88 RAM Directory
• Request for Z88 file date stamp.
• Set date stamp of Z88 file.
• Set Z88 System Clock.
• Get Z88 System Clock.
• Request for estimated free Z88 memory (all RAM in the computer).
• Perform automatic translation of files during transfer (receiving/transmitting). Very important for non-English Z88 users.
• User defined translation tables may be loaded. An IBM Code page 865 (Nordic) - ISO LATIN 1 translation table is default
• Automatic CR <-> CRLF conversion during transfer (more useful for the MS-DOS system).
• Request for Server Version and file protocol level.
• PC-LINK II compatible. All original PC-LINK II commands are implemented which means that you easily could connect to a PC and execute the original PC LINK II software in MS-DOS and perform your necessary transfer. PC-LINK II is emulated, is much faster than the original and also allows for automatic translation and line feed conversion during transfer - without the original PC LINK II Client knowing about it!

A GUI Client for QDOS/SMSQ is being developed at the moment that will enable easier file transfer processing and backup. Due to the nature of the Z88 filling system and possible conflicts of the QDOS/SMSQ filing system (the famous 40 character limit for complete path and filename), all files may be transferred to a Virtual Backup Device which can be regarded as a mirror of the Z88 filing system. This system allows transfer of files to your host computer without worrying about the compatibility of your host computers' filing system. All transmitted files are kept in a the shell of the Virtual Backup Device. Viewing this feature from the outside, it is a simple data base of interrelated hierarchical organised records. The Virtual Backup Device is implemented using the DATADesign system and Pointer Environment User Interface. Q-Branch will announce the availability of "EazyLink for Qdos" when completed. "EazyLink for Windows 3.x" have already been completed, using the same principles as described above. EazyLink for Windows is implemented using Visual Basic, the Access database engine and various third party tools to display the information.

Please contact Rakewell for more information.

ZetriZ - a "TETRIS" look-alike graphics game that exploits the PipeDream map area

InterLogic have provided a complete set of graphics routines bundled with the Z88 Assembler Workbench, which is a part of the standard library. All source files are supplied. We made ZetriZ to display the potential of graphics in the map area - also known as the PipeDream Map Area. ZetriZ - apart from the graphics are using many of the standard library routines. As an extra bonus, we have supplied the complete source for the ZetriZ game as well - for your sole pleasure of investigating the inner workings of the algorithm behind the block game and how the graphics are displayed. We hope to encourage new developers to develop exciting new applications that can exploit the graphics capabilities of the Z88.

ZetriZ allows you to play in three modes; using standard Tetris Blocks, extended blocks only or both modes mixed. You may adjust the playing area, and starting speed. The high score table is automatically loaded and saved when the ZetriZ application is activated or KILL'ed. You may create several ZetriZ applications that can be simultaneously suspended/reactivated. High scores of the different games are merged with each other; this allows always for the best score to be kept (until it is beaten!).

The graphics routines support plotting, line drawing (inclusive squares), sprite movement and graphics area pixel scrolling.
 





| | | | | For Software Questions - Ask Gunther

© Rakewell Limited 1998 InterLogic 1999