Creating a Z80 assembly development environment on Windows

There are many ways to set up your environment depending on which text editor you use, which assembler, which emulator etc. In this tutorial, I will describe the set up that I use personally for writing machine-code only projects in a Windows environment.

This will not be a tutorial on how to write Z80 machine code for the Next.

The Components

In this tutorial, we will need to set up the following components of the development environment:

  • The folder structure.
  • The file system.
  • The emulator.
  • The audio system (if you want sound coming from your emulator).
  • The assembler.
  • The SD card image tool.
  • Some initial source code to generate what you need.
  • Some batch files to bring it all together.

I will go through them all in turn and at the end you will have a development environment you can use for your own projects.

The Folder Structure

Find or create a folder where you want to put all your Next development code. Each project you start should have their own folder, but all them share another single folder that will contain the SD card image your emulator will use as its file system.

I personally use subst or the tool vsubst.exe at https://www.ntwind.com/software/visual-subst.html to create a drive letter that points to the folder you’ve found or created. For example: I may create a folder called “C:\Next” that I wish to contain all my Next-related code. I then use the above tools to create the drive letter N: to point to that folder so that my development environment now lives in “N:\”.

Within this folder, you will create two sub-folders, one called “sdcard” and the other named after your project (for the purposes of this tutorial, we will call it “project”). The “sdcard” folder will eventually contain a required image of the file system your emulator requires. The reason it’s in its own folder is because it will be shared by all your projects. And the reason for this is because the image file is very large, as in gigabytes large.

So hit Win+R to bring up the “run dialog” and type “cmd” and hit ENTER or click on OK:

Now type these commands (for the purposes of this tutorial, I will assume the base folder is “N:\”, but you can substitute this for any other drive and folder name).

Creating the first folders.

Now we will enter the “project” folder and create some more folders:

  • a bin folder to contain our tools.
  • a src folder to contain our Z80 source code.
  • a data folder to contain any data our code needs (this is optional).
  • a etc folder to contain any notes, information or any non-source related files that we just want to store somewhere.

So, continuing on:

More folders!

The File System

Now, the next job is to grab a copy of the ZX Spectrum Next’s file system, which contains all the ROMs, tools etc that you would have on the real Next. This is required by the emulator so it can function like a proper Next.

So bring up a web browser window and go over to:

http://zxspectrumnext.online/cspect/

Scroll down and you will see a bunch of links referring to various SD card image files containing the OS of different sizes:

Choose the size you wish. I choose the 2GB version, which is more than I will even need (2GB is HUGE!) and takes up less space of my hard disk. Make sure you download the zip file that you will download when you click on those links to the “N:\sdcard” folder.

Now use explorer and navigate to the “N:\sdcard” folder. You should see a .zip folder. Double-click this and you will see three files (assuming you chose the 2GB version, which I will assume for the rest of this tutorial):

  • cspect-next-2gb.img – the SD card image
  • enNextZX.rom – the ZX Spectrum Next ROM holding NextBASIC and NextZXOS.
  • enNxtmmc.rom – the DivMMC ROM.

Those two extra “.rom” files are required by the emulator to start up. The first thing you need to do is copy “cpsect-next-2gb.img” to the “N:\sdcard” folder, which is the one you put the zip file in. You may need to open another explorer window to do the copy.

Secondly, you need to copy the two “.rom” files to the “bin” folder in your project directory. The bin folder will house the emulator eventually and it will find those files there.

The Emulator

OK, my emulator of choice is Cspect by Mike Dailly. There are only two emulators out there at time of writing this (the other being ZesarUX) that emulator the ZX Spectrum Next. I prefer Cspect because of two important reasons: 1) it’s the most accurate; and 2) it super fast to start up, which is vital when you’re writing code.

With your web-browser go to:

http://cspect.org

And download the latest Cspect emulator version. You will be downloading a zip file and you must put its contents into the “bin” folder in your project. Navigate to your “bin” folder and make sure “cspect.exe” is there.

Well that was easy!

The Audio System

Cspect requires OpenAL to produce sound. OpenAL is a standard audio library that many programs use to create sound. In your web browser go over to this address:

https://www.openal.org/downloads/

In that page you will see a link to download:

Click on this to download another .zip file, which you will open to find a “oalinst.exe” file. You can run this and OpenAL will be installed to your PC.

The Assembler

Cspect comes with an assembler called snasm, which you will find already sitting in your bin directory. But we won’t be using this assembler because at time of writing it currently has an issue. It does not output the latest version of the “.nex” file format, which is the file format used for executables on the Next. It is a fine assembler and will create “.sna” files, but because of our requirement of using “.nex” files, we cannot use this.

So, my assembler of choice is sjasmplus, which is a very powerful assembler that is well documented. You can find the documentation over at:

https://z00m128.github.io/sjasmplus/documentation.html

You can find the latest release at:

https://github.com/z00m128/sjasmplus/releases

The assembler was originally written by Sjoerd Mastijn, but has been contributed to by others including Peter Ped Helcmanovsky.

Click on the zip file link to download that. Inside that zip file you will find a folder, and inside that you will find the “sjasmplus.exe” file. Copy that over to your “bin” folder in your project folder. This must sit next to the Cspect emulator.

The SD Card Image Tool

So, the assembler will create a “.nex” file for you, which you can run from the usual NextZXOS browser after running the emulator. However, we need to get the “.nex” file on to the SD card image sitting in your “N:\sdcard” folder. Without this step, the emulator will not see your new creation.

To fix this, we use a simple tool called hdfmonkey, written by Matt Westcott. However, he wrote it for Linux but some kind soul converted it to Windows and you can download it using this link:

http://uto.speccy.org/downloads/hdfmonkey_windows.zip

Inside, this zip file you will find a single file called “hdfmonkey.exe”, and you guessed it, need to copy it into the “bin” folder in your project.

The Source Code

For the purposes of this tutorial, I will show you how to write a program that sets the border green, then hangs forever (i.e. enters an infinite loop). A very simple program that will demonstrate what sjasmplus directives you will use in the code.

Create a file “project.asm” using your favourite editor (I use Sublime Text 3, which has a plug-in for Z80 assembly coding) in the “src” folder. Enter this code (either by typing or cut & pasting):

;;
;; Sample code
;;

        ; Allow the Next paging and instructions
        DEVICE ZXSPECTRUMNEXT

        ; Generate a map file for use with Cspect
        CSPECTMAP "project.map"

        org  $8000

Start:
        ld   a,4        ; Set A to green
        out  ($fe),a    ; Change the border
        jr   $          ; Loop forever!

;;
;; Set up the Nex output
;;

        ; This sets the name of the project, the start address, 
        ; and the initial stack pointer.
        SAVENEX OPEN "project.nex", Start, $ff40

        ; This asserts the minimum core version.  Set it to the core version 
        ; you are developing on.
        SAVENEX CORE 2,0,0

        ; This sets the border colour while loading (in this case white),
        ; what to do with the file handle of the nex file when starting (0 = 
        ; close file handle as we're not going to access the project.nex 
        ; file after starting.  See sjasmplus documentation), whether
        ; we preserve the next registers (0 = no, we set to default), and 
        ; whether we require the full 2MB expansion (0 = no we don't).
        SAVENEX CFG 7,0,0,0

        ; Generate the Nex file automatically based on which pages you use.
        SAVENEX AUTO

The SAVENEX directives at the end basically give information on how to build the final “.nex” file. For more documentation, please read:

https://z00m128.github.io/sjasmplus/documentation.html#c_savenex

All your other source code files should be inserted into this top-level file (“project.asm”) using the INCLUDE directive so you only refer to a single file when running your assembler.

The Batch Files

Finally, we write some batch files to put all of these components together. Firstly we will create a “m.bat” file to build the code and generate the “project.nex” file our source will create. You will be able run “m.bat” from the command line whenever you want to create the “.nex” file. With your text editor create the file “N:\project\m.bat”:

@echo off
bin\sjasmplus src/project.asm --zxnext=cspect --msg=war

The “–zxnext=cspect” will allow you to add the “break” and “exit” instructions in your code to trigger the debugger in Cspect. The “exit” instruction will just quit Cspect.

The “–msg=war” will tell sjasmplus to only output warnings and errors and not spam you with tons of information about other things. This is optional, of course, but I prefer it.

When you run this batch file, you will see two new files appear in your “N:\project” folder: “project.nex” and “project.map”. The first is your final executable, which will be launched by NextZXOS. The second houses information that the Cspect debugger can use (such as the labels you’ve used).

Now we create a second batch file “r.bat”, that will allow “m.bat” to build your code, insert the “project.nex” file into your SD card image and launch Cspect so you can use the Next’s browser to launch your “project.nex” file. Notice, Cspect will not run your code automatically.

@echo off
call m.bat
if not errorlevel 1 (
    bin\hdfmonkey put n:\sdcard\cspect-next-2gb.img project.nex
    bin\CSpect.exe -r -brk -w3 -zxnext -nextrom -map=project.map -mmc=n:\sdcard\cspect-next-2gb.img
)

If “m.bat” fails (i.e. your build fails because of errors), the batch file stops there. Assuming everything builds, hdfmonkey will insert your file into the SD card image and launches Cspect. Cspect has a myriad of options and I will go through them one at a time.

  • -r tells Cspect to remember its position for next time you run it. This is optional.
  • -brk allows Cspect to react to the “break” instruction. If you don’t have this option, “break” instructions act like “nop” instructions and so are harmless.
  • -w3 sets the size of the window so that one Spectrum pixel equals 3 PC pixels.
  • -zxnext turns on the Next emulation. Without Cspect runs like an original 48K Spectrum.
  • -nextrom tells Cspect to load the two “.rom” files into memory so it launches like a proper ZX Spectrum Next.
  • -map tells Cspect which map file to use to help its debugger show labels.
  • -mmc tells Cspect where to find the SD card image. Change the path here to your actual path.

Run “r.bat” and you should see Cspect launch after sjasmplus builds your code. Use the browser to launch “project.nex” and you should see a green border.

Use this as a template for writing your own code and good luck.