Bradway Software
Robert Chafer
Programming: Assembler/Mcode
ZX Spectrum 48K

Simon Goodwin
Chris Bourne

Nearly all Spectrum games and utilities are written in machine code - the simple internal language recognised by the Spectrum's Z80A processor. Machine code is a very simple programming language, but it's executed most rapidly - at roughly half a million instructions a second. it's this speed that makes machine-code programming attractive to people who want to get the best possible performance out of the computer.

The snag is that each instruction is very simple in effect, and large so intricate combinations of instructions must be used if you want something relatively complicated to happen. The machine code routines built into the Spectrum ROM illustrate this.

The ROM software, used by BASIC and many games, executes about 150 instructions to print a single character on the display. When you draw a line across the screen the ROM executes about 60 instructions for every single point drawn on the line.

Machine code may execute very quickly, but writing and testing it is a slow and laborious business. Mistakes are often fatal - you don't get helpful error reports, as in ZX BASIC, unless you anticipate every possible mistake. if you use the wrong instruction in a machine-code program you may wipe out all your work in a fraction of a second. Machine code is fickle stuff, and you have to write quite a lot of it before you begin to build up a reliable framework.

Luckily, since we're using a computer, we can get the machine to help us write and test machine code. There are two approaches to this. We can use an assembler, which lets us write individual machine-code instructions in a way that makes them easy to identify, test and alter, and assembles each line into machine code. Alternatively we can use a compiler.

A compiler takes a program written in a form that's fairly concise and easy for humans to understand, and converts it into machine-code instructions automatically. if the compiler comes across anything it can't understand it tries to explain the problem so you can make things clear.

One line of compiled code may be translated into tens or hundreds of machine-code instructions, whereas one assembler line usually corresponds to a single instruction.

Compilers work well, but they restrict what you can do. No compiler knows how to write everything that a practised machine code programmer could come up with. They tend to use inefficient general-purpose routines to do something in the best possible way.

Compilers can produce fast code - if you can live without decimal numbers, compiled programs can be 100-200 times faster than BASIC - but they hardly ever produce code as fast and concise as a good machine code programmer, particularly if you're writing nitty-gritty routines, such as animating the display or packing a game map into a small amount of memory.

The speed and space penalties of compiled code mean that the most successful and impressive Spectrum programs are usually painstakingly written in machine code, using an assembler rather than a compiler. Unfortunately changes in the Spectrum market mean that most of the once-popular assembler programs are no longer available.

Back in the issue 50 Tech Tips Special I bemoaned the shortage of Spectrum assemblers. in the last few years i've reviewed good packages like Code Machine and Laser Genius, only to find that the games firms that published them were unwilling to keep them in stock for more than a few months.

For a while HiSoft's six-year-old DevPac was the only assembler advertised to Spectrum users. DevPac works fine, but it's not particularly cheap or easy to learn to use.

I'm happy to report that my plea for new assemblers has got results! I've just reviewed two programs - Z80 Toolkit, from Lerm Software, and Astrum +, from Bradway Software. I've been using them for a while, and comparing them with HiSoft's venerable DevPac.


Complete assembler-programming systems come in three main parts. The names for the parts vary, depending on the manufacturer, but in principle every system contains an editor, which lets you type in machine-code instructions in the form of simple, standard mnemonics.

The assembler itself translates the mnemonics into binary code, the debugger helps you to test assembled code and track down errors. Most packages also include a disassembler, which converts machine code in memory into mnemonics you can edit and reassemble later.

The assembler generates a symbol table, which relates names in your text, known as labels, to particular values and memory addresses. It's very helpful to be able to refer to values by name, even though most assemblers limit the maximum length of names so that the symbol table doesn't get too large.


Lerm's Z80 Toolkit is much the cheapest package, yet it's fairly comprehensive. It runs on all Spectrums, including the +3, and is compatible with almost all add-ons.

£7.99 gets you a 23-page A5 manual and a cassette containing three main files. Side 1 is the complete package assembler, editor and debugger and takes about two minutes to load.

The other side contains two copies of the debugger, called the toolkit - one loads at high memory addresses and the other loads at the bottom of memory. It's up to you to choose the version that will not get in the way of your own code. The debugger is a little over 8K long, and loads in about a minute.

The manual is a good tutorial in the use of the entire package, though it's short of some reference material - for instance, there's no explanation of how you add documentary comments to a program. In fact, comments are entered in the standard way - just start your line with a semicolon and the assembler will ignore the rest, assuming it's for human eyes only.

The Z80 Toolkit editor uses the normal Spectrum 32-character line display, which means comments really have to be on lines of their own. The editor lets you edit and re-enter lines on the screen, using the cursor keys to move around. Special keypresses let you insert spaces into a line, delete characters and jump between columns to keep your listing tidy.

You can enter lines more than 32 characters long, but the insert-character key doesn't let you extend a line down the screen, so it's best to keep lines short and put up with rather narrow printouts.

As in BASIC, lines are kept in order, so you must start them with a line number between 1 and 65,500. You can get the system to generate numbers automatically, or renumber whole files to give even steps between line numbers.

The undocumented limit of 65,500 is generous, as the maximum size of your program text is limited to about 20K, which usually corresponds to 2K or 3K of machine code.

If you want to write bigger programs you must write them in sections and copy addresses from one program to another so that each part can find the others. This is a fiddle, but lots of successful programmers work that way.

You can move lines around the file with Z80 Toolkit, but you have to move them one by one by editing their numbers - a rather tedious process.

Z80 Toolkit will load files created with the Zeus assembler distributed by Sinclair a few years ago, though you may need to make a few minor changes before the file will assemble.

Z80 Toolkit is compatible with just about every filing device - cassettes, Opus, +D, +3, Swift Disc, Disciple, Microdrive and everything else that leaves most of the memory free and lets you save code from BASIC.

This compatibility has its cost: there are no commands to save and load built into Z80 Toolkit, but you can find out the address and length of any file, before or after it is assembled.

Z80 Toolkit makes saving and loading long-winded but easy, if you make a note of the relevant numbers. You are expected to hop back to BASIC and use the normal programming commands for your system to save and load code. You must make a note, because the screen is cleared as you return to BASIC.

To re-enter the toolkit you just type RUN or a USR call. When you restart the program text appears to have vanished! But it reappears when you use the O command.

As long as you can fit everything, including the symbol table, into 23k you can have several files in memory at once, and swap between them at will by specifying a new start address for text.

Z80 Toolkit uses single-letter commands, but it's not particularly consistent. The assembler lets you edit text and translate it into machine code. A special Command gets you to a set of add-on utilities, confusingly called the monitor, which let you change the screen colour, search for labels in the symbol table, or move the symbol table into screen memory to leave the maximum possible space for your program text. Another command gets you into the toolkit, which others would call the monitor or debugger. Yet another command then calls up the disassembler. This gets a bit confusing, as command letters have different purposes in each of these four modes, and it's not always clear which mode you're in.


Astrum+ has many more features than Z80 Toolkit, but it's almost twice the price - £14. The manual is 36 A5 pages long, and has no examples, though it's a good reference guide.

The cassette contains around 20 files, spread over both sides, totalling 80K of code. The tape files transfer automatically to microdrive or disk, as long as you press the PAUSE button while files are saved. I found this rather tricky because I started on Side 1 of the tape, and missed the instructions - for some reason Bradway Software assume people will load Side 2 first!

Besides the editor and assembler, Bradway supply utility programs to read other assembler text tapes, copy files from one drive to another, print file details, and configure the system for particular drives and printers.

The debugger and disassembler come in three versions, to load at address 36000, 46000 and 56000. The manual refers to a file of Spectrum system labels, covering the ROM and system variables but I couldn't find it.

Astrum+ may appeal as an upgrade for many programmers, as it comes with a utility to convert files from HiSoft, Oasis, OCP and Picturesque format to suit itself.

Astrum+ works on all Spectrum versions except the +3. It will assemble from disk to disk (or microdrive), so you can write very large programs, but first you must divide your text into 10K sections, called pages. Single pages can be assembled from memory to memory, but there's only about 2K spare for your code, at address 56000.

The Astrum + editor is happy with lines up to 256 characters long, panning the screen sideways to show lines of more than 32 characters. Lines are automatically formatted into neat columns as you enter them.

Astrum+ has a true screen editor, without line numbers, so you can't intersperse system commands as you enter lines. You must use a set of trendy pull-down menus to control Astrum+'s most powerful features. I found these menus rather clumsy to use, and would prefer an old-fashioned command line.

There are too many menus, and each one is too small. You have to press SYMBOL SHIFT and Q, to select the required bank of menus, then SYMBOL SHIFT and E to select one from each bank of three. SYMBOL SHIFT W pulls down the chosen menu, then you press any key to cycle through the options, pressing ENTER to select one in particular.

You can create, save, load and merge files, display a list of filenames (without any other details) on a chosen drive - but the drive-changing and merging options are not on the main files menu. You can print, move, copy or delete marked blocks of lines, find or replace any characters, swap between file pages or assemble the program.

Astrum+ asks you to check that you've loaded the correct disk or cartridge, and then press a key, before it uses the drives. You can turn this function off when assembling from a single drive.

The software supports up to eight microdrives, but all the pages of a particular program must be on one drive, so you may have to swap tapes manually even it you've got enough drives to plug all the cartridges in at once.

Users of the Opus Discovery version should be able to avoid this, even if their files total more than 180K of code, as Bradway sell an add-on 720K second drive for that interface. A complete kit, consisting of the drive, cable, RAM expansion, software and manual, costs just £85, making this upgrade attractive to all Discovery users, whether or not they're interested in Astrum+.

I tested the microdrive version of Astrum+, using Version 1.2 of Sixword's Swift Disk microdrive emulator. This worked well but I found that I had to return to BASIC to erase files before I could replace them with others that had the same name. Apart from that minor quirk, the emulation was perfect, and a fair bit faster than my ZX Microdrive ever went! Microdrive files are automatically verified after saving - a sensible precaution.

Astrum+ will save and load cassette files, but it's really intended for Opus disk or microdrive users - the tape options are just to allow you to take cheap backup copies of your work.

Astrum+ issues clear error messages in plain English, and shows unused labels in a special colour in the symbol table a nice touch that should help you detect errors and keep your text tidy.

The Astrum+ debugger is controlled with four or five letter commands, rather than single keys. This makes it easy to remember the commands, but slows you down. It will work in decimal or hexadecimal, whichever you choose.

The front-panel display packs all the register values into eight lines and wont show the value of each half of the 16-bit register-pairs. This doesn't matter if you're using the hex display, but it makes the decimaJ display rather useless if you're using 8-bit values.

You can change register values more easily than you can display them, but you still have to move a pointer to indicate the registers you want to change, then type a command to set the new value - you can't just type the name and the new value, as you can with Z80 Toolkit.

By contrast, Z80 Toolkit shows 16-bit and 8-bit register values separately, plus individual register contents in binary. It still steps at about the same speed - a maximum of roughly five instructions a second, updating the whole screen at each step.


Both these packages have advantages and disadvantages compared with HiSoft's old stalwart, DevPac. Whereas DevPac insists on capital letters, the others let you mix upper-case and lower-case in your programs. Astrum+ has better error reports than the others - it uses text, rather than numbers, to tell you what's gone wrong. The snag is that things like this limit the amount of text you can edit at any one time. The program editors vary a lot - HiSoft's is capable but very old-fashioned, a line editor rather than a screen editor. Astrum+ has the most modern user interface, with its pull-down menus, but I found them tiresome to use. The Z80 Toolkit editor is simple and straightforward, but rather limited if you want to make large-scale changes.

Astrum+ allows labels to be up to eight characters long, while the others limit you to six characters. I think both limits are rather restrictive, though I welcome the extra couple of characters Astrum+ can handle.

Astrum+ is relatively slow, because it is written as a large collection of separate programs. For instance, you have to reload the debugger every time you use the assembler, because the label information overwrites the memory locations used by the debugger. This is not too painful if you've got a 128K Spectrum, as you can keep the debugger on RAM disk.

DevPac has some unique advantages, but they are rather poorly implemented unless you splash out £50 for the CP/M version which HiSoft use to write their own software. DevPac lets you define macros like shorthand instructions, one macro name can stand for a whole block of code defined elsewhere in the text. Z80 Toolkit has none, and Astrum+ only has a few predefined ones to call ROM routines.

DevPac also allows conditional code - sections that are assembled only if certain conditions are satisfied. The snag is that on standard Spectrum versions of DevPac these structures cannot be nested. You need the £50 CP/M version before you can do really useful things like put conditions inside conditions or use macros in other macro definitions. The CP/M version also comes with ED80 - a proper screen editor capable of editing files over 50K long.

Z80 Toolkit is the fastest assembler if you're processing short files, but it gets very fiddly assembling programs of more than about 20K text, as it's up to you to join up the sections.

Z80 Toolkit allows numbers to be entered or displayed in hexadecimal - base 16 - or normal decimal; DevPac and Astrum+ recognise octal - base 8 and binary as well.

Unlike the others, Z80 Toolkit doesn't allow complex calculations in your text. Astrum+ and DevPac let you write calculations involving labels and 16-bit numbers, whereas it seems Z80 Toolkit will only let you add or subtract a single number from a label.

The Z80 Toolkit manual is vague on this, as on other things it's a good tutorial, but less of a reference manual than the documentation for the other assemblers. Be warned: none of these packages will teach you Z80 programming. You'll need a separate book if you're new to machine code.

All the debugging programs let you examine registers and step through code, instruction by instruction, tracing register values and following the program flow. Z80 Toolkit has much the clearest and most helpful display, and is relatively easy to use. In particular it shows the values of the stack very clearly, with a ten-line column dynamically showing values as they are pushed onto the stack and popped off it.

The main flaw is that Z80 Toolkit won't let you enter breakpoints - instructions which interrupt code at a specified point, returning you to the monitor. The software requires you to step right through each subroutine as you test it; you can't make it zoom through to a certain point, and step slowly thereafter.

Z80 Tooikit has one unique and friendly feature. It can trap all instructions that modify memory contents, stepping quickly through the rest of the code but waiting for a key press - Y or N - to tell it whether or not to operate each store instruction.

The Astrum+ debugging program does everything you'd expect, but it uses a cramped display and commands have to be typed in full.

DevPac and Astrum+ can disassemble code in memory back into mnemonics and labels, so you can edit and reassemble other people's code. This is tricky with Z80 Toolkit, because it only disassembles mnemonics - it doesn't work out the labels for you.

Astrum+ can skip data areas automatically. Just tell it where you've put text or tables of values, and it will avoid trying to turn the contents of that part of memory into nonsensical assembly code. The other disassemblers just pretend the values are code.

Z80 Toolkit disassembles the secret Z80 instructions I mentioned in issue 52 but, like the others, it doesn't let you type these instructions into your assembler program. You must enter them as numeric values.

DevPac is the only assembler that takes advantage of the extra RAM on a Spectrum 128 - almost all the debugging code is stored in the RAM disk, so users of the 128 machines can test up to 8K more code at a time if they use DevPac, rather than one of the other debuggers.


If you've always wanted to try writing some machine code, but never got around to i, Lerm's Z80 Toolkit is a good buy. It's cheap, easy to use, and it works, though it's not ideal if you want to write programs thousands of lines long (and remember, it takes quite a few lines of assembler to do anything at all!)

Astrum+ has advantages and disadvantages compared with DevPac. It has a better editor and comes with lots of useful utility programs. Astrum+ also reports errors in English, so you don't have to memorize the meanings of a set of error codes.

DevPac takes up less RAM and drive space, and is more flexible about assembling to and from a drive. It lets you define your own macros and switch lumps of code in and out conditionally. DevPac works with a 51-column screen display, and the debugger fits inside the Spectrum 128's RAM disk.

Personally, I found Z80 Toolkit the easiest program to use, perhaps because it's designed for smaller projects. Lerm's debugger has its limitations, but boasts the best front-panel display. If you're working on a blockbuster program either Astrum+ or DevPac should suit you, though in both cases it may take you a while to find your way around the system.


Z80 Toolkit £7.99 from LERM, 11 Beaconsfield Close, Whitley Bay, Tyne & Wear NE25 9UW (091) 253 3615

Astrum+ £14 (Opus Microdrive) from Bradway Software, Hillsett, Upper Padley, Grindleford, Derbyshire S30 1JA

DevPac £15.95 (tape), £19.95 (Opus Disciple, +3) £49.95 (+3 CP/M - enhanced) from HiSoft, The Old School, Greenfield, Bedford MK45 5DE (0525) 718181

Screenshot Text

Machine code is executed at 500,000 instructions a second

We can get the computer to help us write code