SNasm

 Code Assemble !

Assembling your first application isn't quite as simple as it is on the C64 with Kick.

There are a couple of important assembler directives that must be used or what you assemble won't work at all.

The first is:

OPT ZXNEXT

This option will enable the extended Spectrum Next functions such as the NEXTREG command which is used to talk to the hardware registers of the machine.

ORG $C000

This option tells the assembler where to start the code addressing from, the address $C000 is a common place to start applications, especially for new devs who don't yet know the hardware. The 1st 16k is ROM, this can be paged out but not until the program has loaded and is running, the second 16k is, by default, used for the screen and user defined tiles, this depends upon the screen mode and can be moved. 

The top 32k is all yours!

Finally:

savenex "../bin/main.nex",StartAddress,StackStart

is required, this tells SNasm how to write out the file so that it can be executed on the next.

The filename is simply the path and name of the file to produce, to keep things tidy I like to drop this into a bin (or binary) directory which can then be passed to the emulator.

The StartAddress is the address of the first line of the program that will be run, usually this is the same as the ORG value set above but you can specify any memory address to start the code. One very important thing to note is that if you wish to start your code in a particular memory block make sure that the label is AFTER the ORG command not before it.

ie

    ORG $C000

StartAddress:

    ...

NOT

StartAddress:

    ORG $C000

   ...

doing the the latter will set the start code to end of the previous code block (or zero if its at the top of the code). Guess how I found that out.

Finally the Next needs to know where its stack is, unlike the 6502 the stack is not in a fixed memory page.

Firstly you need to allocate a block of memory for the stack, the size of the stack really depends on how and what the program does. If the program has a lot of recursion,  for example, more stack space is required. Usually I would suggest 256 byte as a reasonable value.

A simple and predictable way to define this is:

ds 255

StackStart:

db 0

Remember the stack grows backwards in memory so we define the label after the reserved space and the first element on the stack is zeroed.

Obviously you could just set a variable to an area of memory you expect to be free but I prefer to define it, it save tears later. 

It doesn't really matter where the stack is place although my preference is to put it at the end of any blocks of data rather than at the end of a block of code. This way if the stack grows beyond the reserved space it corrupts data rather than code, which is easier to trouble shoot, especially if it graphics data as it will be obvious something is overwriting. Corrupt code just does weird stuff that is not always obvious to diagnose. 

The Spectrum Next!

Spectrum Next 

Like many, many people I have backed the Kick Stater for the Spectrum Next and I'm planning on once again half finishing a bunch of projects that will never see light of day. That said it keeps me out of trouble so I thought I'd document a few of my adventures.

For my first steps I need to set up a development environment and as usual this will be on my Mac, though much of this will apply to Windows users too. In fact most of the tools I'm using here are .NET tools running under mono. Mono a Mac project that simply allow .NET application to run on a Mac. 

If you are using a Mac you will need to download  and install Mono Framework before starting. This is available free from https://www.mono-project.com/docs/getting-started/install/mac/

I've chosen to go with CSpect as my emulator, from what I've read in the forums and generally in the community this is a well regarded product and so far it's worked very well for me. It can be downloaded from https://mdf200.itch.io/cspect for free but personally I always give a few quid to the devs, these things don't write with themselves.

CSpect also includes a copy of SNasm which is my assembler of choice for this project. Both products have been developed by Mike Dailly who is not only a great dev but seem like a totally awesome guy too so thanks for your work Mike. It seems only fair to give Mike's web site a plug too so here it is https://lemmings.info

Ok now for the editor, Sublime text is my go to code editor, has been for years. But this is probably personal choice and if you want to use notepad++ or even worse VSCode it makes no difference.

Once you have downloaded all the components its time to install them, if you're using a Mac run the mono installer package and just take the defaults.

To simplify all the relative paths for building, covered later, I made a very simple file structure. Again this will make sense later.

spectrum

-CSpect

-gameName

  -bin

  -src

  -assets

These are all relative but their placement is important later on.

First job is to copy CSpect directory from download to the spectrum folder. There will be a version tagged onto the filename, remove the version number and just call the folder CSpect. This make the path names in build script much easer to troubleshoot later on.

The SNasm assembler is already in this folder.

Also under the spectrum folder create a sub directory for each new project.

The structure of folders in the project folders just help to keep files organised and isn't essential, I just get a bit anal about code being in the "right" place.

In the project folder create a text file named build.sh and give it execute permissions, for windows this would be build.bat and you won't need to set execute permission.

Use chmod +x build.sh to make the file executable.

Edit the build.sh file and paste the following:

#!/bin/bash

  echo
  echo "   Doing some assembling   "
  mono ../../CSpect/SNasm.exe -map ./main.s ../bin/main.dat
  echo "        Assemble done   "
  mono ../../CSPect/CSpect.exe -map=../projectName/bin/main.dat.map -zxnext -w5 -mmc=.i/ ../bin/main.nex

The echo statements are optional but it lets you see how things are progressing. This file can be copied to any project just edit the projectName in the last line.

I always use the main.s file as my core code file for all projects, just habit. if you start file is called something different just edit the file. Remember too that on the Mac case is important so just check that first if there are any issues.

For windows users remove the mono command at the start of the lines.

Unfortunately the mono command does not pass through any return codes from the applications so if the assemble fails there is no way to detect it and stop the script, the emulator just fires up and runs the last version of  program that did assemble.

There are also a number of additional parameters you can pass to emulator, there are detailed in the readme file in the CSpect directory. This basic command line seems to do the job for me.

Now all that's left to do is setup a hot key in the editor to assemble and run. Again this is editor dependant but for Sublime I created a new build system and named it SpectrumNext using the following settings.

{
"shell_cmd": "build.sh"
}

Now when you open the base directory of the project and him apple-b the program assembles and fires up the emulator.