ZX Spectrum Assembly, Space Battle – 0x0F ZEsarUX

1 de octubre de 2023 Juan Antonio Rubio García

In this chapter of ZX Spectrum Assembly, we will go deeper into the use of ZEsarUX.

Translation by Felipe Monge Corbalán

ZEsarUX
Personalisation
Debugging
ZX Spectrum Assembly, Space Battle
Useful links

ZEsarUX

Throughout this tutorial I have used ZEsarUX, an emulator developed by César Hernández Bañó, which you can get for free at https://github.com/chernandezba/zesarux. César is constantly adding new features and making improvements.

We have used ZEsarUX as a ZX Spectrum emulator, but it is capable of emulating many machines and doing many other things.

In this chapter we will not be creating folders, copying files or generating code.

Personalisation

The first step is to set up ZEsarUX to suit your needs. ZEsarUX has many options that can be configured, but we are going to focus on the ones that I think are most interesting for the use we are going to make of it in this book. I encourage you to do your own research.

To customise ZEsarUX, press F5 to access the menu and then click on Preferences.

The first thing we need to do is configure a function key to restart the machine and another to enter debugging. Go to Settings and select the Function Keys option.

Once in the Function Keys, select the F11 key by either clicking or pressing Enter.

Once the key has been selected, we are shown the options available to us; we choose DebugCPU. We repeat the operation for the F12 key, but in this case we select Reset.

We need to test the buttons. Leave the menu by pressing Esc until it closes completely, or press F5 to go to the main menu and then Esc.

Once the menu is closed, check that pressing F11 opens the debug window and that pressing F12 restarts the machine.

There are many functions that can be associated with a function key, in fact I have defined several keys.

I do not define F5 or F9 as one opens the menu and the other gives direct access to file upload.

When debugging, I keep the debug window and the memory window visible, so it can be inferred that I am running out of space.

Next we go to Settings, select ZX Desktop and then the first option, Enabled. When you select it, more options are displayed, the first of which we are interested in, width. Click on it until the value is 512 (or another value that suits you). We can also set the value directly if we select custom Width.

To open the menu on the desktop, select the Open Menu on ZX Desktop option. On the other hand, if you don’t want the menu to open when you click on it, I find it more convenient to go to Preferences/General and uncheck the Clicking mouse open menu option.

Now we have space to open other windows so that they don’t share space with the screen of our beloved ZX Spectrum.

As I mentioned before, I like to have both the debug and memory windows visible while debugging. We need to change some options to be able to see how the memory is being updated while the program is running, and to be able to stop execution when the menu is open.

Go to Settings/ZX Vision and almost at the end, select the options Stop emulation on menu and Background Windows. Once the second option is activated, you will see another option to activate Even when menu closed.

We have already set up the environment. All we need to do is open the debug windows and the hexadecimal editor from the Debug menu and place them where we want them; press F11 to open the debug window.

Under Settings/General we can change the language, although at the time of writing not all terms have been translated.

If at any time the windows do not respond, press F5.

Debugging

Let’s say we have a program and we load it at address $8000; make sure you don’t have the 16K machine selected or it won’t work.

ASM

org  $8000

Start:
ld   hl, $4000
ld   de, $8100
ld   a, $ff

Loop:
ld   (hl), a
ld   (de), a
dec  a
jr   nz, Loop

Exit:
jr   Start

end  $8000

In this programme we point HL to the start of the VideoRAM, DE to position $8100 and load 255 ($FF) into A. Then we go through a loop in which we load the value of A into the positions pointed to by HL and DE and decrement A. At the end of the loop we go back to the start and continue in an infinite loop.

The programme is very simple, but it is enough to show what I want to show you.

The first thing we do is go into Debug and set a breakpoint at memory address $8000 so that execution stops at the start of the programme.

The different options are accessed by pressing the key corresponding to the highlighted letter.

In the central part of the screen, on the left, we see the disassembled code and the address where each instruction is assembled. On the right, we see mainly the value of the different registers and the state of the flags. Just below this we see the values of the stack.

At the top and bottom we see the different options; we will only see the ones we need to start debugging our programs.

On the top right we see 1-7: View. Clicking from one to seven will show different views of this window; by default view one is shown.

At the top left we see mptr. Pressing the M key opens a window where we can enter the address we want to go to. If we are entering hexadecimal values, the suffix H must be used.

Once we have entered the address, we press Enter and the disassembly from that address is displayed.

As we haven’t loaded any programs yet, the only disassembly we see is NOP ($00).

We set a breakpoint at address $8000. If we look at the fourth option in the second line of options, at the bottom of the window, we see Togl; by pressing the L key we set or remove a breakpoint on the selected line.

We already have a breakpoint set at address $8000. When the program is loaded it will stop at this address and we will enter debugging mode. Press the N (Run) key to continue and return to Basic.

ZEsarUX displays a window warning us that there is a breakpoint, we have to press a key to enter the Debug window. We can prevent this window from appearing in the debug properties.

We load the program and debug it.

To follow the programme, we can run it intwo ways: en: Stp and Stovr. In other environments, these are known as Step-by-instruction and Step-by-procedure.

Step by step by instructions (Enter) executes the instructions one by one, and when we are faced with a CALL to a routine, either ours or from the ROM, we enter it, with the possibility of executing it step by step and seeing its code.

In step by step procedures (O key), the execution is done instruction by instruction, but when we are faced with a CALL to a routine, either ours or from the ROM, it is executed and the PC (program counter) is passed to the instruction following the CALL; this must be taken into account in the loops.

In our programme, when PC is at instruction JR NZ, 8008, if we press Enter and A is not zero, it will jump to address $8008. Conversely, pressing O will execute the whole loop (all iterations) and point PC to the next instruction, JR 8000. Try it and see how it works.

At each iteration of the loop, it loads the value of A into the addresses pointed to by HL and DE. We can only see the different values loaded at the address pointed to by HL because it points to VideoRAM.

To see how the value of address $8100 changes, press F5, select the Hexadecimal Editor window, press M (memptr), type in address 8100H and press Enter.

If we remove the breakpoint and press N (Run) we will see that the position $8100 is updated.

With this you should be able to debug programs, although ZEsarUX offers much more power, but it’s up to you to discover it, but let’s talk about one last thing: adding or modifying code directly in the debugger.

In the first line of options at the bottom, pressing the S (stM) key will display other options. Pressing the A (assemble) key allows us to modify the instruction at the selected address. To leave the Assemble window, press the Esc key.

In our case, we will change the VideoRAM address where we load the value of A to column ten.

As you can see in the picture, the value of A is painted in column ten.