Introduction to Z80 assembly Part I.

Foreword

Return of the bedroom programmer was a tutorial series that I started in Micro Mart magazine in the Summer of 2010 with the aim of getting people to experiment with the sorcery which is assembly language. The target machine here is the popular Sinclair ZX Spectrum.

It was never intended for intermediate or advanced programmers, but those people who may have been utterly confused or scared off by good old 'machine code' during their youth, but always wanted to write a professional game on the Speccy anyway.

Those who followed this series found it very useful. In fact, I've never had as much positive feedback about anything I've written since I started writing back in February 2002, and this is still the case today.

So, if you've always wondered about the magic of low-level programming, but didn't like the explanations in the books and magazines of the 1980s, here is the edited and hopefully slightly improved series, split into three parts. First, we look at the basics of our target machine, so without further ado, let's get started.

Return of the bedroom programmer

Part I: Our target machine

These tutorials are inspired by Andrew Unsworth's programming series which started in Micro Mart magazine issue 1109. Andrew's excellent features looked at the popular C programming language, and I therefore decided to start a series about programming an old 8-bit computer, using Z80 assembly language (also known as machine code). It was something that I always wanted to write for Micro Mart, and finally got around to it in the Summer of 2010. I'm going to assume that you have some knowledge of programming at least in an 8-bit variant of BASIC, but this is not necessary as programming is more about problem solving than remembering exact the syntax and commands of a particular language, be that BASIC, Pascal, C or Java. Our target machine (which of course can easily and accurately emulated nowadays) is the popular Sinclair ZX Spectrum.

With a modern-days PC providing a powerful development environment, you'll need some text editing interface (Notepad will do fine) for writing the code, an assembler and an emulator. I'll be giving examples using the cross-platform Pasmo (tinyurl.com/pasmo-z80), and recommend the emulator SPIN, but use any that you are comfortable with. There is also the Windows utility WinTZX for testing on a real machine. You'll need a 2.5mm mono jack to go from your audio output on your PC to the Speccy as well, but other good solutions are available and can be found by a quick search of the Internet. Many resources are listed at https://spectrumcomputing.co.uk.

First though let's look at some basic technical information about the Speccy before we get stuck into coding. There are three main variants of the 8-bit, the initial models launched in 1982 had either 16 or 48KB of on-board RAM and a 16KB ROM, running at approximately 3.54Mhz. The sound was handled by an internal one channel 'speaker', known as the beeper, and the screen is built of 32 x 22 8-bit character cells from BASIC, on 32 x 24 with machine code trickery, giving a total of 256 by 192 pixels with eight RGB colours which have two brightness levels in each cell, except for black which is the same colour whether the 'bright' is set or not.

This means that you have a whole 15 colours in total, with two being available per eight by eight attribute cell (unless you delve into advanced graphics programming). The bits set to off colour the 'paper' (background) and the bits set to on the 'ink' (foreground) on the ZX. Unlike many other machines, everything is bit-mapped to the screen regardless of whether you are actually drawing, using 'software sprites' or the pre-defined character set. This means that the screen RAM is reserved at 6,912 bytes, or about 6.75KB. System variables take up another 738 bytes (0.73KB approximately), so just over 7KB is used by the computer, leaving around 9 or 41KB respectively free for programming either the 16K or 48K model.

The 128K machines, from 1985 onwards, had a built-in sound chip providing three channel sound plus the beeper for compatibility with earlier software. Around 104KB is available on these machines, but we won't worry about this now as the code throughout these tutorials will run on the standard 48K model.

The Speccy's Spec

It sounds really primitive by today's standards, and in truth the Speccy wasn't exactly the most sophisticated 8-bit computer on the market even when it was launched in April 1982, but that's missing the point as Sinclair Research's head honcho Clive Sinclair (later Sir Clive) envisaged a computer in every household, and at the time he made such a prediction many homes didn't even have a colour television set. The Spectrum was a major price breakthrough like it's predecessors the ZX80 and ZX81 but with more features, giving the average family the possibility of owning a colour computer with high resolution graphics and sound for under £100 [for the 16K model].

This aggressive price point put computers into the hands of hundreds of thousands and eventually millions of families. With many early magazines printing full games in BASIC and occasionally assembly along with games reviews and news, this helped the UK to become a world leader in the now lucrative video games industry, and it is largely thanks to Sir Clive's endeavours that Britain became a nation of computing enthusiasts.

Part II: First steps

Like almost everything in programming, there is more than one way to do things, and using assembly isn't the only way to make the Sinclair ZX Spectrum do exciting (or sometimes not so exciting) stuff. You could enter the op-codes directly into memory with Sinclair BASIC, using a FOR/NEXT loop reading a typically long list of DATA statements into an variable of integer type and then POKEing each into RAM. This is handy for small routines, but anything more substantial will be no good for your sanity. If you were going to go down this route, then you may consider writing your whole program in BASIC and use a compiler to speed things up. Some professionally produced games were compiled BASIC, but these did not generally require the speed of a typical arcade game.

Another way of programming would be to use a machine code monitor. A monitor can disassemble all of the computer's memory into either the code and mnemonics and/or ASCII (well, the Sinclair equivalent). This is good for debugging your program, and it's possible to write low-level code with a monitor. Again, if you value your sanity, stay away from monitors but for debugging.

If you haven't already done so, download Pasmo assembler (tinyurl.com/pasmo-z80) and assuming you've got a Speccy emulator, we're ready to go.

To write your code, you can use Notepad or any text editor (Notepad++ might be worth a look if you use other languages), although from the Windows command prompt I've found 'edit' just as good as anything else. You should save your code with '.asm' file extension at the end of the file name. Open your text editor and first enter:

org $6000

The dollar sign tells the assembler that we're dealing in hexadecimal (referred to as hex, see below) and the 'org' command tells the assembler where to place the code, so we're starting our short program at memory location $6000. There's three more lines we want, as follows:

    ld bc,DATA
    ld a,(bc)
    ret
  

Note the spaces after the 'ld' command. The command ld tells the processor to load a register or accumulator ('bc' and 'a' in this case) with a number or memory location. So, here we're using the register pair BC to point at the area of memory we're calling DATA, and then loading the first byte in DATA into the accumulator (A). Note that the label doesn't take up any of the Spectrum's memory, it's simply used by the assembler when it compiles our code so it knows where everything is. This also makes programming a little easier than it would be, as otherwise you would have to hard-code the DATA pointer yourself, which would mean manually working out where in memory it resides. So, if you add code which moves the DATA area to another address, you'll need to work this out again.

The above routine is the equivalent to LET bc=(start of DATA) and then LET a=PEEK (bc) in BASIC, whilst the command 'ret' will return to BASIC this time around.

Now we want to define our data block, so enter the following lines and then save your file, and call it First.asm or whatever you like. The data block is simply as follows:

DATA
    defb 0    ; Zero not 'o'
  

As I've already said, we have defined an area in RAM called 'DATA' and the 'defb' command has a byte there – so our first (and only) data item is a zero. There's also a comment after the semi-colon to clarify that we need a number. We'll talk more about labels and comments later.

Providing you're in the same directory as the Pasmo program (it's a good idea to have your code and Pasmo in the same place), from the command prompt, enter:

pasmo First.asm First.bin

This creates the binary file. Now enter:

pasmo --tapbas First.asm First.tap

and this will create a tape image for your emulator. Set your Speccy to the 48K model and load your newly created tap file (a tape image). Once loaded, you should see three lines of BASIC, which is automatically generated by PASMO. Now type:

PRINT USR 24576

directly (as you'll be using the one-touch entry system, refer to the help file on your emulator, or the original BASIC programming manual that came with the machine) and press ENTER. A number will appear on the screen. This is the value in the register bc, which is the start of your DATA memory block in your code. This is because we've asked the computer to 'PRINT' our routine, so the Sinclair ROM knows it needs to output something to the screen area on returning to BASIC.

Go back into your code to edit it, add the following lines before the 'ret' instruction:

    nop
    nop
  

This means 'no operation', so the CPU basically does nothing when for those lines. Not that you will notice as each will take just a fraction of a second. This is a useful instruction if you ever need exact timing in your code.

Re-assemble and load it back into the emulator, and call the routine as above. You'll notice that the number printed has increased. The assembler has automatically relocated the block of memory we've called DATA for you. Good, eh? But not very exciting either. But hey, you've written your first piece of machine code!

Hex to decimal

Computers do everything in binary, a number system to the the power of base two. This can be difficult to read for our human brains used to dealing in 10s. For instance, our program is located at $6000 in hex or 24576 in decimal. In binary, this would be 110000000000000. Imagine if we had to call the program with binary and missed a zero out? It could crash the ZX Spectrum or cause all kinds of unexpected results.

Hexadecimal works to the power of base 16, and fits binary really well. As we don't have a single numeric digit to represent 10 through to 15, we substitute these for the first five letters of the alphabet, therefore A in hex is 10 and F is 15, and hex 10 is 16. To convert any 16-bit hex number, use the following formula: (X3x4096)+(X2x256)+(X1x16)+X, so $FEDC is (15x4096)+(14x256)+(13x16)+12, or 65244.

It's even easier to convert any binary number into hex. Split each octet (8-bit number) into 4-bit 'nybbles' (note the spelling), let's say 01101101, for instance. So, we split like this:

0110 – 1101

We can now convert this directly into hex, so:

0110 = $6

and

1101 = $D

Therefore, our binary number represented in hex is $6D. This works for any length binary number providing that you break it down each octet correctly. If we look at a 16-bit binary number, like:

1110101110011011

break it down into 4-bit nybbles, we get:

1110 – 1011 – 1001 - 1010

and this into hex is:

1110 = $E
1011 = $B
1001 = $9 and finally
1010 = $A

So our number is $EB9A. We can then use the above method to convert this hexadecimal into decimal using the above formula. But if maths isn't your strong suit, cheat and use an online converter.

Part III: Introducing the screen

The Sinclair ZX Spectrum's screen is built up of two main areas; the border, which, unless you're loading from tape, is usually one solid colour from the eight available, and the 'paper' in Sinclair terminology is where we draw and write to.

The paper area consists of 256 by 192 pixels, residing in RAM at location 16384 ($4000 in hex) onwards. Each eight pixels are represented by one byte, and the screen memory excluding colour ends at 22527, and from 22528 to 23296 we have the colour attribute data for each 8x8 character cell. More about this in the next instalment.

Open your preferred text editor and let's get cracking with the code. Our first lines are:

SCR equ 16384    ; Sets a constant
org $6000        ; Where our program
                 ; will being in the
                 ; computer's memory
    ld bc,STRING
    ld de,SCR
  

The first line sets up a constant reference equal to [memory location] 16384, the start of the screen RAM. As you might recall, org is where our program starts in RAM, and ld bc is our point of reference for a block of data we're going to call STRING later in the code. The register pair de is set to the value in SCR, or 16384, like saying LET de=SCR in BASIC. Now here's the main bit code, which will be a loop:

LOOP             ; Loop marker
    ld a,(bc)
    cp 0         ; zero not 'o'
    jr z,EXIT    ; Goto EXIT if zero
    rst $10
    inc bc
    inc de
    jr LOOP      ; Goto LOOP
  

What it's does is reads the current location held in bc and puts it into the accumulator, like saying LET a=PEEK (bc). This is then compared to the value zero, and if equal, it jumps to the code held in the area of memory called EXIT. Next, rst $10, calls the part of the Sinclair ROM to print out the contents of 'a' (the accumulator - similar to PRINT CHR$ a), then bc is increased by one to read the next memory location, and we increase de to keep track on where we are up to on the screen. Here's the rest of the code:

EXIT
    ret
STRING
    defb "Your Name rulez!"
    defb 13,0 ; zero not 'o'
  

The code in the bit of memory we've called EXIT will simply return to BASIC. In STRING we have all of our data. We can define blocks of memory as bytes, bits or character strings. For the latter, we need to use quotes around the text, like in BASIC (DATA "Dave Jones rulez!" or LET a$="Dave Jones rulez!" for instance). In our program, we are passing one byte at a time into the accumulator (as 'a' can only hold one byte at a time), which is why we need a loop until we hit zero, whereas we could use a single line of code in BASIC like PRINT a$ or PRINT "Hello Mum!". Before the zero, the value 13 is equivalent of a carriage return. There's also a couple of comments for some clarity after the semi-colon, but these are ignored by the assembler. A comment is equivalent to the REM statement for remarks in BASIC.

Comments are very useful for explaining your code and/or for placing markers, handy if you have a large project on the go, or you are working with other programmers on one project.

For readability, I tend to put labels in capitals, tabulate the code and use lower-case letters for the commands and tabulate again for comments. Of course, you do what you think will make your programs more readable, as you are the one who is writing and maintaining them.

Assemble your code with Pasmo (see the previous instalment if you've forgot), load and execute it with PRINT USR 24576. You should see Your Name rulez! at the top of the screen and on the next line, the value of bc will also appear. We'll find a way of getting rid of the bc memory pointer being outputted in the next instalment, and look changing the text colour too. For now, experiment with the code to see if you can get an extra space in between each character, or move the text onto another line.

Bits and bobs

There are eight binary bits to the byte, and each memory location holds one byte. As I pointed out in the last instalment, binary works to the power of base two; every time we move left one place, the number is doubled from the place to the right. To convert an 8-bit binary number to decimal, you can first convert each 4-bit nybble to hex and then convert that to decimal, as stated last time, or you could use the following formula: (X7x128)+(X6x64)+(X5x32)+(X4x16)+(X3x8)+(X2x4)+(X1x2)+X0. That's a bit long winded, so as each place represents one or zero, we add the relevant number were we see a 'one' and ignore any place where there is a zero, for instance:

10110010

will be

128+32+16+2

Obviously, if bit zero, the least significant bit, is set (or one) – this is the bit furthest to the right as we look at our binary octet - then the number is odd and if it's unset (zero) the number is even [as long as the byte represents a positive integer number between zero and 255 inclusive]. There is a way to represent negative numbers in binary too, which we'll come onto in due course.

You can use an [online] converter if you're really stuck though, or the standard calculator on Windows in 'Programmer' mode, or whatever is installed on your operating system.

Part IV: Colour

Look back and you'll notice from the last instalment, I set a little challenge for you to see if you could get the code to add extra spaces between each character as it was displayed, and whether you could get the text to appear on a new line. There are many ways of doing this. You could have just added character spaces in the text in the data block, as follows:

STRING
    defb " Y o u r   N a m e   r u l e z !"
  

Knowing that the screen has 32 columns (or 32 characters) per line, you could also have added this number (or multiples thereof) of spaces before the text to get it written on a new line. This adds one byte per character space to the size of your overall code, and as you don't have limitless resources on a Spectrum, a more efficient way should be considered. We know the value 13 is the Sinclair equivalent of a carriage return. We could add this to the beginning of the data, as follows:

    defb 13,"Your Name rules!"
  

As for adding spaces between the characters, unless you manually did this as above, you might have tried to add inc de before the line jr LOOP, increasing the screen pointer twice. This wouldn't have had the desired effect though as we were using the register pair DE simply to keep track to which character we're writing to. More will be explained about the screen in later instalments.

What we need to find out is the code for a single space, like 13 is a carriage return. Here's how it's done. Before the line jr LOOP (and after the rst $10 line), enter the following:

    ld a,32        ; 32 is a character space
    rst $10        ; print the contents of 'a'
  

That said, there isn't really a correct answer in either case, but it's how I would have done it. Now we can output text to the screen, let's have a look at adding colour. I've included comments on each line for further clarity, but if you are unsure about anything, pop over to tinyurl.com/Speccy-Coding and feel free to ask any questions. Here's the example:

org $6000        ; Start of code
                 ; (6x4096 in decimal)
    ld a,7       ; Colour seven is white
                 ; ink and black paper
    ld (23693),a ; This sets the screen
                 ; colour as defined by
                 ; the accumulator (a)
    call 3503    ; Calls a routine to
                 ; clear the screen
    ld a,1       ; One is blue
    call 8859    ; We'll set the border
                 ; colour to blue
    ld bc,STRING ; bc points to the
                 ; string data in memory
LOOP             ; Here's our main loop
    ld a,(bc)    ; Load a with the byte
                 ; in location bc
    cp 0         ; Compare a to zero
                 ; (end of STRING data)
    jr z,EXIT    ; If equal to zero then
                 ; jump to EXIT
    rst $10      ; Output a to screen
    inc bc       ; Increase bc by one
                 ; to get next byte
    jr LOOP      ; Jump back to loop
                 ; label to do it all
                 ; again
EXIT                    
    ret          ; This will return us
                 ; to BASIC
STRING           ; This is our main
                 ; data block:
    defb "Your Name rules!"
    defb 13,0    ; 13 is a new line and
                 ; 0 is the end of data
  

Assemble and load this program into the emulator. To execute this code, we can now use:

RANDOMIZE USR 24576

And as you will see, the value of bc isn't printed when you return to BASIC. For our next challenge, see if you can change the colours of the text and border. For a handy reference, look in the old ZX Spectrum BASIC programming manual, but there are plenty of online resources which are a simple search away.

Colour handling

The Spectrum's colour handling for the screen is worked out with the following formula: (128xFLASH)+(64xBRIGHT)+(8xPAPER)+INK. The border can only be one of eight colours, as follows, 0=black.1=blue, 2=red, 3=magenta, 4=green, 5=cyan, 6=yellow, 7=white. If you want any INK (or foreground) colour on a black background, it's simply the colours as above, because zero is black and 0x8 will always be naught. If you want yellow text on a blue background, it'll be (1x8)+6, or 14. The attributes FLASH and BRIGHT can only be one or zero. To set them, just add 128 and/or 64 as needed. This concludes are first instalment, more will follow soon so keep an eye on this blog.