SpecNext Wiki - User contributions [en-gb]

Development Tools:Linux setup

2026-04-29T18:19:21Z

Ped7g: adding more info about possible MAME config

== General ==

This page collects summaries of installation process of various tools related to ZX Spectrum Next software development for linux OS users.

As usual with linux, most of the suggestions are in the form of command line command to be used from terminal.

== sjasmplus assembler ==

You can also check the [https://www.youtube.com/watch?v=c6I4kdErEwE video] of installing sjasmplus on freshly reinstalled KDE neon 5.20 linux, where is also extended info how to run the automated tests of sjasmplus, and opening it in KDevelop IDE to eventually write your own modifications.

=== Prerequisites ===

On Debian based systems make sure you have these packages installed (git-cola and cmake are optional, but often handy):
<nowiki>sudo apt-get install git build-essential g++ git-cola cmake</nowiki>

=== Retrieving the sjasmplus source ===

Use git to clone the [https://github.com/z00m128/sjasmplus z00m's sjasmplus repository]:
<nowiki>git clone --recursive -j8 https://github.com/z00m128/sjasmplus.git</nowiki>

To update already cloned repository, do inside the sjasmplus folder:
<nowiki>git pull</nowiki>
- or use your favourite GIT client app to update the cloned repository.

=== Building the executable binary ===

The GNU make and common C++ compiler (gcc or clang) should be enough to build the binary:
<nowiki>make clean && make</nowiki>

To verify the binary was built ("dot slash" prefix to force running of binary in current folder, not system one):
<nowiki>./sjasmplus --version</nowiki>

=== Installing the executable ===

If you already have sjasmplus installed, use <code>which sjasmplus</code> to see where the installed executable is (and which installed executable has precedence), you can use this command also after installing the new executable to verify it is being picked up by the system.

Installing the binary in system-wide fashion:
<nowiki>sudo make install</nowiki>

Or you can install the binary only locally for your user (without root/sudo permissions):
<nowiki>mkdir -p ~/.local/bin
make PREFIX=~/.local install</nowiki>
- then make sure you have <code>~/.local/bin</code> in your user <code>PATH</code> environment variable (on some distros there is already script in .profile to add this to PATH if the dir does exist, so you may need to only logout/restart after creating it to get it active).

=== Checking if it all works ===

Open your terminal and type (in any directory):
<nowiki>sjasmplus --version</nowiki>

You should see version of the freshly built sjasmplus executable like this:
<nowiki>SjASMPlus Z80 Cross-Assembler v1.17.0 (https://github.com/z00m128/sjasmplus)</nowiki>

== hdfmonkey tool ==

The hdfmonkey tool can manipulate card-images, helping to write new builds of your project into NextZXOS card-image, to boot the emulators with full file system. (it's also possible to mount the images directly into linux by other means, to operate on them with regular file manager/etc, but hdfmonkey suits better use-case when the build script does update the image)

=== Prerequisites ===

On Debian based systems make sure you have these packages installed:
<nowiki>sudo apt-get install git build-essential g++ autoconf</nowiki>

=== Retrieving the hdfmonkey source ===

Use git to clone the [https://github.com/ped7g/hdfmonkey hdfmonkey repository with patched 0.5.7 <code>jjjs version</code> sources]:
<nowiki>git clone https://github.com/ped7g/hdfmonkey.git</nowiki>
(make sure you are on the default branch <code>"jjjs-variant"</code> to build the improved version, it should be checked out by default after clone)

* to update already cloned repository, do inside the hdfmonkey folder:
<nowiki>git pull</nowiki>
* or use your favourite GIT client app to update the cloned repository.
* if you cloned original gasman's repository before, you may want to clone and rebuild here mentioned <code>jjjs version</code> to get multiple fixes and convenience features.

=== Building the executable binary ===

The hdfmonkey is using autoconf/autotools to build final Makefile, check the hdfmonkey README for "from git" installation notes, at the moment of writing this page, the steps were:
<nowiki>cd hdfmonkey
autoheader
aclocal
autoconf
automake -a
./configure
make</nowiki>

To verify the binary was built:
<nowiki>src/hdfmonkey help</nowiki>

=== Installing the executable ===

If you already have hdfmonkey installed, use <code>which hdfmonkey</code> to see where the installed executable is (and which installed executable has precedence), you can use this command also after installing the new executable to verify it is being picked up by the system.

Installing the binary in system-wide fashion:
<nowiki>sudo make install</nowiki>

Or you can install the binary only locally for your user (without root/sudo permissions):
<nowiki>make prefix=~/.local install</nowiki>
- then make sure you have <code>~/.local/bin</code> in your user <code>PATH</code> environment variable.

=== Checking if it all works ===

Open your terminal and type (in any directory):
<nowiki>hdfmonkey help</nowiki>

You should see help of the freshly built hdfmonkey `jjjs version` executable like this:
<nowiki>hdfmonkey: utility for manipulating HDF disk images v0.5.7 jjjs

usage: hdfmonkey <command> [args]
...</nowiki>

== Extracting all files from the sd-card image ==

7-zip is the most convenient tool to extract the the files from the existing image.

To install 7-zip on a Debian system use <code>sudo apt install 7zip</code>.

To extract all the files from an existing image <code>tbblue.img</code> to a new subdirectory <code>myfiles</code>:

<nowiki>7z x tbblue.img -omyfiles</nowiki>

== Creating new sd-card image with hdfmonkey ==

This example:

* downloads the archive from the specnext.com
* unpacks it to the subdirectory <code>tmptb</code>
* creates a new SD image (with the space for 2GB files) from all the files
* deletes the subdirectory <code>tmptb</code>
* shows that the new image uses much less than 2GB
* starts listing the content of the newly created image

<nowiki>
wget https://www.specnext.com/distro/24.11/sn-complete-24.11.zip
7z x sn-complete-24.11.zip -otmptb
hdfmonkey create tbblue.img 2GB
hdfmonkey putdir tbblue.img tmptb /
rm -rf tmptb
du -h tbblue.img
7z l tbblue.img | more</nowiki>

=== Creating new sd-card image without hdfmonkey ===

It's possible to use gnu coreutils and dosfstools to create card image without hdfmonkey, but depending on exact size of image these may be less compatible with various emulator, following example for 1GB card image works in MAME but fails in CSpect (while images created by hdfmonkey tool should work for both emulator, so using '''hdfmonkey is recommended''')

<nowiki>
truncate -s 1G NextZXOS.img
parted NextZXOS.img mklabel msdos
parted NextZXOS.img mkpart primary fat32 2048s 100%
mkfs.fat -F 32 --offset=2048 NextZXOS.img
# and now to copy files to image you have to either mount it or use hdfmonkey:
# hdfmonkey putdir NextZXOS.img tmptb /</nowiki>

== Mounting sd-card image directly ==

Sometimes it may be useful to mount the card image directly, to be able to browse it and manipulate with common tools. But make sure you are not using mounted card image also in emulator at the same time, to prevent any data damage by parallel access.

=== Prerequisites ===

On Debian based systems make sure you have these packages installed:
<nowiki>sudo apt-get install fdisk mount</nowiki>

Prepare empty directory to mount the card image into (let's call it "next-card") and have the image file around ("tbblue.mmc" in following examples)
<nowiki>mkdir -p next-card</nowiki>

=== Mounting the card image ===

To mount the card image you need to know the exact byte-offset where the FAT partition starts, it's possible to read it from "fdisk" or "parted" tools outputs:
<nowiki>fdisk -l -o Start tbblue.mmc
# prints value in sector units, like:
# Start
# 63
# This has to be multiplied by 512 to get byte offset: 63*512 = 32256

# or

parted tbblue.mmc unit B print
# prints values in bytes with "B" suffix in "Start" column</nowiki>

But the fdisk output can be incorporated directly into mount command, which needs root permissions, example with sudo:
<nowiki>sudo mount tbblue.mmc next-card/ -o loop,offset=$((`fdisk -l -o Start tbblue.mmc | tail -1` * 512)),user,uid=`id -u`,gid=`id -g`

# or you can enter the offset yourself

sudo mount tbblue.mmc next-card/ -o loop,offset=32256,user,uid=`id -u`,gid=`id -g`</nowiki>

The uid and gid options will mount the filesystem under your regular user, so you can now browse it with file manager, text editors, etc.

Do not run the emulator yet, before unmounting the image (after you are done manipulating the files)!

=== Unmount the image before using it in emulator ===

<nowiki>sudo umount next-card/</nowiki>

Check the result. If the unmounting fails (probably with "target is busy"), find which process is still accessing/viewing the files in the next-card directory, and try to unmount it again.

== Mounting sd-card image with losetup ==

Alternative using losetup to use local "loop" device for mounting the image. This method can automatically detect partitions inside the image and exposes them as loop devices.

Prepare mounting dir and make sure you have <code>mount</code> and <code>losetup</code> available, Ubuntu based systems packages:
<nowiki>sudo apt-get install util-linux mount</nowiki>

=== Use losetup to attach image and scan its partitions ===

<nowiki>sudo losetup --partscan --show --find NextZXOS.img
# this will print new loop device and automatically create partition devices like /dev/loop0p1
# now mount the desired FAT32 partition:
sudo mount /dev/loop0p1 next-card/</nowiki>

=== Unmounting and cleanup of loop device ===

When finished:
<nowiki>sudo umount next-card/
sudo losetup -d /dev/loop0
# or `sudo losetup -D` to detach *ALL* loop devices</nowiki>

This detaches the loop device and frees all associated /dev/loop* entries.

Notes and gotchas:
* Do not use the image in an emulator while it is mounted.
* If the image has no partition table, --partscan will not create /dev/loop0p1.
* If multiple loop devices are active, check <code>losetup -a</code> to confirm which one is yours.

== Mounting sd‑card image with udisksctl ==

The <code>udisksctl</code> tool provides a desktop‑friendly way to attach loop devices and mount filesystems without manually calculating offsets or using <code>losetup</code>. It integrates with system services such as UDisks2, and on many desktop Linux systems it allows non‑root users (who are in the correct group) to mount images safely.

=== Prerequisites ===

On Debian‑based systems install the UDisks2 tools:

<nowiki>sudo apt-get install udisks2</nowiki>

To run <code>udisksctl</code> without <code>sudo</code>, your user must belong to the '''disk''', '''storage''', or '''udisks''' policy group (varies by distribution). If unsure, simply use <code>sudo</code> in the examples below.

=== Attaching the image as a loop device ===

Use <code>udisksctl loop-setup</code> to create a loop device for the image:

<nowiki>udisksctl loop-setup --file NextZXOS.img
# prints something like:
# Mapped file NextZXOS.img as /dev/loop2.
# UDisks automatically scans the partition table and exposes partitions as:
# /dev/loop2p1
# /dev/loop2p2
# ...</nowiki>

=== Mounting the FAT32 partition ===

Mount the desired partition:

<nowiki>udisksctl mount --block-device /dev/loop2p1
# This prints the mount point, for example:
# Mounted /dev/loop2p1 at /media/youruser/NextZXOS.</nowiki>

You can now browse and edit the filesystem normally using your file manager or command‑line tools.

=== Unmounting and cleanup ===

<nowiki>udisksctl unmount --block-device /dev/loop2p1
udisksctl loop-delete --block-device /dev/loop2</nowiki>

This cleanly detaches the loop device and removes all <code>/dev/loop*</code> entries created for the image.

=== Notes and gotchas ===

* Do not use the image in an emulator while it is mounted, parallel access may corrupt data.
* If the image has no partition table, UDisks will not create '''/dev/loopXp1''' and you must mount manually using an offset.
* Mount points are created under <code>/media/$USER/</code> unless overridden by system policy.
* UDisks may auto‑mount partitions immediately after '''loop‑setup''' depending on desktop environment settings.

== MAME emulator ==

MAME got Next emulation and it got improved a lot around end of 2025, turning it into probably most accurate and performant Next emulator currently available. But as that shift is quite recent, the developers community haven’t transitioned to it yet in large numbers and the tutorials and examples are non-existent. This section provides a basic Linux setup guide.

This chapter focuses only on installing MAME from source code git repository, so you can update to latest work in progress or even contribute to the development yourself. The stable binary releases already contain decent Next emulation, but bug fixes and improvements are still coming often and stable releases trail a few weeks behind.

At the moment, the primary developer working on Next emulation in MAME is Andrei Holub, so his fork repo will be used as default source.

=== Prerequisites ===

You need C++17 compiler (GCC 10.3+ or clang 11+), GNU make and few more development tools and common libraries, for specific list for your distro and up to date information check [https://docs.mamedev.org/initialsetup/compilingmame.html Compiling MAME] web page from official docs.

Keep this page around as the example here is quick hint and not meant as replacement for full documentation.

=== Retrieving the MAME source ===

Use git to clone the [https://github.com/holub/mame holub's MAME repository] and add the [https://github.com/mamedev/mame official MAME repository] as an additional remote:
<nowiki>git clone --origin holubdev https://github.com/holub/mame.git
cd mame
git remote add -f --tags mamedev https://github.com/mamedev/mame.git</nowiki>

To update already cloned repository checked out at master branch, do inside the mame folder (WARNING: this will drop any local changes in the repository, as MAME devs often rewrite already published commits and you need to reset your local clone to latest state - if you are developer working on MAME sources, you should know yourself how to work with git to preserve your changes and rebase/merge):
<nowiki>git fetch --all --force
git reset --hard master</nowiki>
Or use your favourite GIT client app to update the cloned repository.

=== Building the executable binary ===

To '''rebuild''' '''only''' Next emulation (''"tbblue"'' machine) and get executable named <code>tbblue</code>, run <code>make</code> like this:
<nowiki># make sure there are no remnants from previous builds
make clean
# If you want to, you can change to TOOLS=1 to build also "various additional tools, such as chdman"
# The name of resulting binary is affected by SUBTARGET=tbblue, leave it out if you want "mame"
make REGENIE=1 EMULATOR=1 TOOLS=0 SOURCES=sinclair/next/specnext.cpp SUBTARGET=tbblue -j $(nproc)
# check the build output to confirm that compilation succeeded. To list binary:
ls -lh tbblue</nowiki>

This may take a considerable amount of time depending on how powerful your PC is.

If you are developing MAME yourself, you can do incremental build (after REGENIE=1 was used to "generate project files" in previous build and your source code changes don't require full rebuild) - this will be lot faster of course as usual:
<nowiki>make SUBTARGET=tbblue -j $(nproc)</nowiki>

To rebuild full MAME including all other emulation targets (computers and arcade machines) - which will take even much longer - use:
<nowiki>make clean && make REGENIE=1 EMULATOR=1 TOOLS=0 -j $(nproc)
# check existence of new binary (the line above will produce default name "mame")
ls -lh mame</nowiki>

=== Installing the executable and configuration ===

Linux MAME by default [https://docs.mamedev.org/commandline/commandline-all.html#mame-commandline-pathoptions looks for configuration file] in directories: <code>$HOME/.mame;.;ini</code> (that is search the .mame directory in the current user's home directory, followed by the current working directory, and finally the directory ini in the current working directory)

For most of the other paths like <code>roms, samples, artwork, ...</code> it looks by default in current directory <code>.</code>, but you can provide custom paths in the <code>mame.ini</code> file.

My (Ped7g) personal preference is to have all these helper directories in $HOME/.mame along the global mame.ini file, so I can launch the same configuration of MAME from any directory on the system and to keep the configuration and helper file outside of the git repository folder where I build the binary. To seed the ini file first time after building from source, you can use <code>mame -createconfig</code> to get template of .ini file in desired directory (like $HOME/.mame). Then edit the fresh ini file to your liking, for example I modified these lines (diff view):
<pre>
$ diff mame.ini ~/.mame/mame.ini
10,22c10,22
< homepath .
< rompath roms
< hashpath hash
< samplepath samples
< artpath artwork
< ctrlrpath ctrlr
< inipath $HOME/.mame;.;ini
< fontpath .
< cheatpath cheat
< crosshairpath crosshair
< pluginspath plugins
< languagepath language
< swpath software
---
> inipath $HOME/.mame
> homepath $HOME/.mame/lua
> rompath $HOME/.mame/roms
> hashpath $HOME/.mame/hash
> samplepath $HOME/.mame/samples
> artpath $HOME/.mame/artwork
> ctrlrpath $HOME/.mame/ctrlr
> fontpath $HOME/.mame
> cheatpath $HOME/.mame/cheat
> crosshairpath $HOME/.mame/crosshair
> pluginspath $HOME/.mame/plugins
> languagepath $HOME/.mame/language
> swpath $HOME/.mame/software
27,34c27,34
< cfg_directory cfg
< nvram_directory nvram
< input_directory inp
< state_directory sta
< snapshot_directory snap
< diff_directory diff
< comment_directory comments
< share_directory share
---
> cfg_directory $HOME/.mame/cfg
> nvram_directory $HOME/.mame/nvram
> input_directory $HOME/.mame/inp
> state_directory $HOME/.mame/sta
> snapshot_directory $HOME/.mame/snap
> diff_directory $HOME/.mame/diff
> comment_directory $HOME/.mame/comments
> share_directory $HOME/.mame/share
349c348
< bgfx_path bgfx
---
> bgfx_path $HOME/.mame/bgfx
</pre>

And I set up the helper subfolders like this (some are real directories copied from git repo or created empty - where I expect the content to be modified by me, others are symlinks to cloned git repository where I expect content to be read-only):
<pre>
~/.mame$ ls -Aogh
total 32K
lrwxrwxrwx 1 41 Nov 17 13:43 artwork -> /git_repos/mame/artwork
lrwxrwxrwx 1 38 Nov 17 13:40 bgfx -> /git_repos/mame/bgfx
drwxrwxr-x 2 4.0K Nov 17 02:36 cfg
lrwxrwxrwx 1 39 Nov 17 13:44 ctrlr -> /git_repos/mame/ctrlr
lrwxrwxrwx 1 38 Nov 17 13:43 hash -> /git_repos/mame/hash
lrwxrwxrwx 1 42 Nov 17 13:44 language -> /git_repos/mame/language
-rw-rw-r-- 1 8.7K Nov 17 13:45 mame.ini
drwxrwxr-x 3 4.0K Nov 17 02:36 nvram
lrwxrwxrwx 1 41 Nov 17 13:40 plugins
drwxrwxr-x 2 4.0K Apr 22 23:47 roms
lrwxrwxrwx 1 41 Nov 17 13:43 samples -> /git_repos/mame/samples
drwxrwxr-x 3 4.0K Jan 16 13:30 snap
-rw-rw-r-- 1 2.0K Jan 17 22:50 ui.ini
</pre>

And my helper launch script is public in git repo [https://github.com/MrKWatkins/ZXSpectrumNextTests/blob/develop/Tools/mmcMame ZXSpectrumNextTests/Tools/mmcMame], the current content (to launch mame with particular mmc image file and further options):
<pre>
#!/bin/bash
# personal script of Ped to launch MAME emulator with the "tbblue.mmc" (or first argument is image filename)
if [[ -s "$1" ]]; then
MMCFILE="$1"
shift
else
MMCFILE=tbblue.mmc
fi
mame tbblue -ui_active -nounevenstretch -aspect 2:1 -video bgfx -bgfx_screen_chains unfiltered -window -skip_gameinfo -mouse_device none -hard1 "$MMCFILE" "$@"
</pre>

=== Checking if it all works ===

TODO

TODO: add chapter(s) about plugins, config of them, dezog, example of launch, ... once you actually make it work yourself :D

== #CSpect emulator ==

The #CSpect is Mike Dailly's ZX Spectrum Next emulator, written in C# making it cross-platform (sort of, where the mono framework is available). It is non-free (closed-source, custom license) project, but available for usage without any payment (it's possible to use it internally to develop also commercial titles, but you can not distribute/sell the emulator itself, not even packaged with your game - for such agreement contact the author first and get his permission).

Currently it is most performant and user friendly emulator of ZX Spectrum Next, with good emulation accuracy (see [https://wiki.specnext.dev/CSpect:known_bugs CSpect:known_bugs] page for more detailed report).

=== Prerequisites ===

On Debian based systems make sure you have these packages installed:
<nowiki>sudo apt-get install mono-complete libopenal1 libsdl2-dev</nowiki>

=== Retrieving the #CSpect package ===

Use web browser to visit itch.io dedicated to CSpect project [https://mdf200.itch.io/cspect mdf200.itch.io/cspect] and download latest release.

You may get warnings from your browser or antivirus about the page itself and about the zip/binary files. The #CSpect has long record of triggering false positives of AV engines due to the executable being not digitally signed and because of the code using features of OS which are normal for emulator, but may look wonky for AV heuristic. Whether you trust the executable is virus free is up to you, in the end.

=== Installing the executable ===

Unzip the retrieved zip file (I personally use KDE Dolphin file manager, the file context menu ''"Extract -> Extract archive here, autodetect subfolder"''), and place the unzipped directory to target destination (<code>~/zx/emulators/CSpect/CSpect2_13_0</code> in my case). I prefer to keep every version in its own directory, and have general symbolic link pointing to the one I want use by default:
<nowiki>cd ~/zx/emulators/CSpect
ln -s CSpect2_13_0 CSpect_current</nowiki>

Then I create launcher bash-scripts in my <code>~/.local/bin</code> like this (name of script <code>runCSpect</code>):
<nowiki>#!/bin/bash
# personal script of Ped to launch "#CSpect" emulator in "current directory" (with arguments like: "runCSpect file.nex")
MONO_IOMAP=all mono ~/zx/emulators/CSpect/CSpect_current/CSpect.exe -tv -zxnext -s28 -w4 -mmc=./ "$@"</nowiki>

Notes: I don't know any more what <code>MONO_IOMAP=all</code> helps with, I believe it was suggested to help with any filesystem windows-like paths containing backslashes, you can try to do your own research. The <code>-tv</code> switch will switch off "scanlines" shader effect and generally switch off any GPU shaders, which makes CSpect more compatible with graphics drivers (try it, if you get only black screen or instant crash during init). The <code>-w4</code> will make the window quite large - 4x scale, the <code>-zxnext -s28</code> switch #CSpect into ZX Next emulation mode and set 28Mhz speed of OS as default. And finally the <code>-mmc=./ "$@"</code> will set ''current directory'' for esxdos emulation to the directory where you use the script to launch the emulator, and pass any remaining command line options entered by user, like the name of the SNA/NEX file. Other noteworthy options are <code>-debug -brk -map=file.map</code>, the -debug entering the debugger just ahead of the first instruction, -brk enables CSpect specific two-byte tag 0xDD 0x01 to work as breakpoint and the -map option allows you to load into debugger the symbol table from your assembler (directive CSPECTMAP in sjasmplus), making labels visible in disassembly.

=== Checking if it all works ===

Go to some directory with SNA/SNX/NEX file (there are also some demo files right in the CSpect directory) and use the launcher script, like:
<nowiki>runCSpect beast.nex</nowiki>

You should see #CSpect emulator window running the beast.nex demo (or whatever else you did want to launch and entered as argument).

[[File:Cspect_test_run.png|frameless|Running CSpect from directory with test snapshots]]

Development Tools:Linux setup

2026-04-25T18:52:10Z

Ped7g: /* Installing the executable and configuration */

== General ==

This page collects summaries of installation process of various tools related to ZX Spectrum Next software development for linux OS users.

As usual with linux, most of the suggestions are in the form of command line command to be used from terminal.

== sjasmplus assembler ==

You can also check the [https://www.youtube.com/watch?v=c6I4kdErEwE video] of installing sjasmplus on freshly reinstalled KDE neon 5.20 linux, where is also extended info how to run the automated tests of sjasmplus, and opening it in KDevelop IDE to eventually write your own modifications.

=== Prerequisites ===

On Debian based systems make sure you have these packages installed (git-cola and cmake are optional, but often handy):
<nowiki>sudo apt-get install git build-essential g++ git-cola cmake</nowiki>

=== Retrieving the sjasmplus source ===

Use git to clone the [https://github.com/z00m128/sjasmplus z00m's sjasmplus repository]:
<nowiki>git clone --recursive -j8 https://github.com/z00m128/sjasmplus.git</nowiki>

To update already cloned repository, do inside the sjasmplus folder:
<nowiki>git pull</nowiki>
- or use your favourite GIT client app to update the cloned repository.

=== Building the executable binary ===

The GNU make and common C++ compiler (gcc or clang) should be enough to build the binary:
<nowiki>make clean && make</nowiki>

To verify the binary was built ("dot slash" prefix to force running of binary in current folder, not system one):
<nowiki>./sjasmplus --version</nowiki>

=== Installing the executable ===

If you already have sjasmplus installed, use <code>which sjasmplus</code> to see where the installed executable is (and which installed executable has precedence), you can use this command also after installing the new executable to verify it is being picked up by the system.

Installing the binary in system-wide fashion:
<nowiki>sudo make install</nowiki>

Or you can install the binary only locally for your user (without root/sudo permissions):
<nowiki>mkdir -p ~/.local/bin
make PREFIX=~/.local install</nowiki>
- then make sure you have <code>~/.local/bin</code> in your user <code>PATH</code> environment variable (on some distros there is already script in .profile to add this to PATH if the dir does exist, so you may need to only logout/restart after creating it to get it active).

=== Checking if it all works ===

Open your terminal and type (in any directory):
<nowiki>sjasmplus --version</nowiki>

You should see version of the freshly built sjasmplus executable like this:
<nowiki>SjASMPlus Z80 Cross-Assembler v1.17.0 (https://github.com/z00m128/sjasmplus)</nowiki>

== hdfmonkey tool ==

The hdfmonkey tool can manipulate card-images, helping to write new builds of your project into NextZXOS card-image, to boot the emulators with full file system. (it's also possible to mount the images directly into linux by other means, to operate on them with regular file manager/etc, but hdfmonkey suits better use-case when the build script does update the image)

=== Prerequisites ===

On Debian based systems make sure you have these packages installed:
<nowiki>sudo apt-get install git build-essential g++ autoconf</nowiki>

=== Retrieving the hdfmonkey source ===

Use git to clone the [https://github.com/ped7g/hdfmonkey hdfmonkey repository with patched 0.5.7 <code>jjjs version</code> sources]:
<nowiki>git clone https://github.com/ped7g/hdfmonkey.git</nowiki>
(make sure you are on the default branch <code>"jjjs-variant"</code> to build the improved version, it should be checked out by default after clone)

* to update already cloned repository, do inside the hdfmonkey folder:
<nowiki>git pull</nowiki>
* or use your favourite GIT client app to update the cloned repository.
* if you cloned original gasman's repository before, you may want to clone and rebuild here mentioned <code>jjjs version</code> to get multiple fixes and convenience features.

=== Building the executable binary ===

The hdfmonkey is using autoconf/autotools to build final Makefile, check the hdfmonkey README for "from git" installation notes, at the moment of writing this page, the steps were:
<nowiki>cd hdfmonkey
autoheader
aclocal
autoconf
automake -a
./configure
make</nowiki>

To verify the binary was built:
<nowiki>src/hdfmonkey help</nowiki>

=== Installing the executable ===

If you already have hdfmonkey installed, use <code>which hdfmonkey</code> to see where the installed executable is (and which installed executable has precedence), you can use this command also after installing the new executable to verify it is being picked up by the system.

Installing the binary in system-wide fashion:
<nowiki>sudo make install</nowiki>

Or you can install the binary only locally for your user (without root/sudo permissions):
<nowiki>make prefix=~/.local install</nowiki>
- then make sure you have <code>~/.local/bin</code> in your user <code>PATH</code> environment variable.

=== Checking if it all works ===

Open your terminal and type (in any directory):
<nowiki>hdfmonkey help</nowiki>

You should see help of the freshly built hdfmonkey `jjjs version` executable like this:
<nowiki>hdfmonkey: utility for manipulating HDF disk images v0.5.7 jjjs

usage: hdfmonkey <command> [args]
...</nowiki>

== Extracting all files from the sd-card image ==

7-zip is the most convenient tool to extract the the files from the existing image.

To install 7-zip on a Debian system use <code>sudo apt install 7zip</code>.

To extract all the files from an existing image <code>tbblue.img</code> to a new subdirectory <code>myfiles</code>:

<nowiki>7z x tbblue.img -omyfiles</nowiki>

== Creating new sd-card image with hdfmonkey ==

This example:

* downloads the archive from the specnext.com
* unpacks it to the subdirectory <code>tmptb</code>
* creates a new SD image (with the space for 2GB files) from all the files
* deletes the subdirectory <code>tmptb</code>
* shows that the new image uses much less than 2GB
* starts listing the content of the newly created image

<nowiki>
wget https://www.specnext.com/distro/24.11/sn-complete-24.11.zip
7z x sn-complete-24.11.zip -otmptb
hdfmonkey create tbblue.img 2GB
hdfmonkey putdir tbblue.img tmptb /
rm -rf tmptb
du -h tbblue.img
7z l tbblue.img | more</nowiki>

=== Creating new sd-card image without hdfmonkey ===

It's possible to use gnu coreutils and dosfstools to create card image without hdfmonkey, but depending on exact size of image these may be less compatible with various emulator, following example for 1GB card image works in MAME but fails in CSpect (while images created by hdfmonkey tool should work for both emulator, so using '''hdfmonkey is recommended''')

<nowiki>
truncate -s 1G NextZXOS.img
parted NextZXOS.img mklabel msdos
parted NextZXOS.img mkpart primary fat32 2048s 100%
mkfs.fat -F 32 --offset=2048 NextZXOS.img
# and now to copy files to image you have to either mount it or use hdfmonkey:
# hdfmonkey putdir NextZXOS.img tmptb /</nowiki>

== Mounting sd-card image directly ==

Sometimes it may be useful to mount the card image directly, to be able to browse it and manipulate with common tools. But make sure you are not using mounted card image also in emulator at the same time, to prevent any data damage by parallel access.

=== Prerequisites ===

On Debian based systems make sure you have these packages installed:
<nowiki>sudo apt-get install fdisk mount</nowiki>

Prepare empty directory to mount the card image into (let's call it "next-card") and have the image file around ("tbblue.mmc" in following examples)
<nowiki>mkdir -p next-card</nowiki>

=== Mounting the card image ===

To mount the card image you need to know the exact byte-offset where the FAT partition starts, it's possible to read it from "fdisk" or "parted" tools outputs:
<nowiki>fdisk -l -o Start tbblue.mmc
# prints value in sector units, like:
# Start
# 63
# This has to be multiplied by 512 to get byte offset: 63*512 = 32256

# or

parted tbblue.mmc unit B print
# prints values in bytes with "B" suffix in "Start" column</nowiki>

But the fdisk output can be incorporated directly into mount command, which needs root permissions, example with sudo:
<nowiki>sudo mount tbblue.mmc next-card/ -o loop,offset=$((`fdisk -l -o Start tbblue.mmc | tail -1` * 512)),user,uid=`id -u`,gid=`id -g`

# or you can enter the offset yourself

sudo mount tbblue.mmc next-card/ -o loop,offset=32256,user,uid=`id -u`,gid=`id -g`</nowiki>

The uid and gid options will mount the filesystem under your regular user, so you can now browse it with file manager, text editors, etc.

Do not run the emulator yet, before unmounting the image (after you are done manipulating the files)!

=== Unmount the image before using it in emulator ===

<nowiki>sudo umount next-card/</nowiki>

Check the result. If the unmounting fails (probably with "target is busy"), find which process is still accessing/viewing the files in the next-card directory, and try to unmount it again.

== Mounting sd-card image with losetup ==

Alternative using losetup to use local "loop" device for mounting the image. This method can automatically detect partitions inside the image and exposes them as loop devices.

Prepare mounting dir and make sure you have <code>mount</code> and <code>losetup</code> available, Ubuntu based systems packages:
<nowiki>sudo apt-get install util-linux mount</nowiki>

=== Use losetup to attach image and scan its partitions ===

<nowiki>sudo losetup --partscan --show --find NextZXOS.img
# this will print new loop device and automatically create partition devices like /dev/loop0p1
# now mount the desired FAT32 partition:
sudo mount /dev/loop0p1 next-card/</nowiki>

=== Unmounting and cleanup of loop device ===

When finished:
<nowiki>sudo umount next-card/
sudo losetup -d /dev/loop0
# or `sudo losetup -D` to detach *ALL* loop devices</nowiki>

This detaches the loop device and frees all associated /dev/loop* entries.

Notes and gotchas:
* Do not use the image in an emulator while it is mounted.
* If the image has no partition table, --partscan will not create /dev/loop0p1.
* If multiple loop devices are active, check <code>losetup -a</code> to confirm which one is yours.

== Mounting sd‑card image with udisksctl ==

The <code>udisksctl</code> tool provides a desktop‑friendly way to attach loop devices and mount filesystems without manually calculating offsets or using <code>losetup</code>. It integrates with system services such as UDisks2, and on many desktop Linux systems it allows non‑root users (who are in the correct group) to mount images safely.

=== Prerequisites ===

On Debian‑based systems install the UDisks2 tools:

<nowiki>sudo apt-get install udisks2</nowiki>

To run <code>udisksctl</code> without <code>sudo</code>, your user must belong to the '''disk''', '''storage''', or '''udisks''' policy group (varies by distribution). If unsure, simply use <code>sudo</code> in the examples below.

=== Attaching the image as a loop device ===

Use <code>udisksctl loop-setup</code> to create a loop device for the image:

<nowiki>udisksctl loop-setup --file NextZXOS.img
# prints something like:
# Mapped file NextZXOS.img as /dev/loop2.
# UDisks automatically scans the partition table and exposes partitions as:
# /dev/loop2p1
# /dev/loop2p2
# ...</nowiki>

=== Mounting the FAT32 partition ===

Mount the desired partition:

<nowiki>udisksctl mount --block-device /dev/loop2p1
# This prints the mount point, for example:
# Mounted /dev/loop2p1 at /media/youruser/NextZXOS.</nowiki>

You can now browse and edit the filesystem normally using your file manager or command‑line tools.

=== Unmounting and cleanup ===

<nowiki>udisksctl unmount --block-device /dev/loop2p1
udisksctl loop-delete --block-device /dev/loop2</nowiki>

This cleanly detaches the loop device and removes all <code>/dev/loop*</code> entries created for the image.

=== Notes and gotchas ===

* Do not use the image in an emulator while it is mounted, parallel access may corrupt data.
* If the image has no partition table, UDisks will not create '''/dev/loopXp1''' and you must mount manually using an offset.
* Mount points are created under <code>/media/$USER/</code> unless overridden by system policy.
* UDisks may auto‑mount partitions immediately after '''loop‑setup''' depending on desktop environment settings.

== MAME emulator ==

MAME got Next emulation and it got improved a lot around end of 2025, turning it into probably most accurate and performant Next emulator currently available. But as that shift is quite recent, the developers community haven’t transitioned to it yet in large numbers and the tutorials and examples are non-existent. This section provides a basic Linux setup guide.

This chapter focuses only on installing MAME from source code git repository, so you can update to latest work in progress or even contribute to the development yourself. The stable binary releases already contain decent Next emulation, but bug fixes and improvements are still coming often and stable releases trail a few weeks behind.

At the moment, the primary developer working on Next emulation in MAME is Andrei Holub, so his fork repo will be used as default source.

=== Prerequisites ===

You need C++17 compiler (GCC 10.3+ or clang 11+), GNU make and few more development tools and common libraries, for specific list for your distro and up to date information check [https://docs.mamedev.org/initialsetup/compilingmame.html Compiling MAME] web page from official docs.

Keep this page around as the example here is quick hint and not meant as replacement for full documentation.

=== Retrieving the MAME source ===

Use git to clone the [https://github.com/holub/mame holub's MAME repository] and add the [https://github.com/mamedev/mame official MAME repository] as an additional remote:
<nowiki>git clone --origin holubdev https://github.com/holub/mame.git
cd mame
git remote add -f --tags mamedev https://github.com/mamedev/mame.git</nowiki>

To update already cloned repository checked out at master branch, do inside the mame folder (WARNING: this will drop any local changes in the repository, as MAME devs often rewrite already published commits and you need to reset your local clone to latest state - if you are developer working on MAME sources, you should know yourself how to work with git to preserve your changes and rebase/merge):
<nowiki>git fetch --all --force
git reset --hard master</nowiki>
Or use your favourite GIT client app to update the cloned repository.

=== Building the executable binary ===

To '''rebuild''' '''only''' Next emulation (''"tbblue"'' machine) and get executable named <code>tbblue</code>, run <code>make</code> like this:
<nowiki># make sure there are no remnants from previous builds
make clean
# If you want to, you can change to TOOLS=1 to build also "various additional tools, such as chdman"
# The name of resulting binary is affected by SUBTARGET=tbblue, leave it out if you want "mame"
make REGENIE=1 EMULATOR=1 TOOLS=0 SOURCES=sinclair/next/specnext.cpp SUBTARGET=tbblue -j $(nproc)
# check the build output to confirm that compilation succeeded. To list binary:
ls -lh tbblue</nowiki>

This may take a considerable amount of time depending on how powerful your PC is.

If you are developing MAME yourself, you can do incremental build (after REGENIE=1 was used to "generate project files" in previous build and your source code changes don't require full rebuild) - this will be lot faster of course as usual:
<nowiki>make SUBTARGET=tbblue -j $(nproc)</nowiki>

To rebuild full MAME including all other emulation targets (computers and arcade machines) - which will take even much longer - use:
<nowiki>make clean && make REGENIE=1 EMULATOR=1 TOOLS=0 -j $(nproc)
# check existence of new binary (the line above will produce default name "mame")
ls -lh mame</nowiki>

=== Installing the executable and configuration ===

Linux MAME by default [https://docs.mamedev.org/commandline/commandline-all.html#mame-commandline-pathoptions looks for configuration file] in directories: <code>$HOME/.mame;.;ini</code> (that is search the .mame directory in the current user's home directory, followed by the current working directory, and finally the directory ini in the current working directory)

For most of the other paths like <code>roms, samples, artwork, ...</code> it looks by default in current directory <code>.</code>, but you can provide custom paths in the <code>mame.ini</code> file.

My (Ped7g) personal preference is to have all these helper directories in $HOME/.mame along the global mame.ini file, so I can launch the same configuration of MAME from any directory on the system and to keep the configuration and helper file outside of the git repository folder where I build the binary. To seed the ini file first time after building from source, you can use <code>mame -createconfig</code> to get template of .ini file in desired directory (like $HOME/.mame). Then edit the fresh ini file to your liking, for example I added these lines:
<pre>
#
# CORE CONFIGURATION OPTIONS
#
readconfig 1
writeconfig 0

#
# CORE SEARCH PATH OPTIONS
#
inipath $HOME/.mame
homepath $HOME/.mame/lua
rompath $HOME/.mame/roms
hashpath $HOME/.mame/hash
samplepath $HOME/.mame/samples
artpath $HOME/.mame/artwork
ctrlrpath $HOME/.mame/ctrlr
fontpath $HOME/.mame
cheatpath $HOME/.mame/cheat
crosshairpath $HOME/.mame/crosshair
pluginspath $HOME/.mame/plugins
languagepath $HOME/.mame/language
swpath $HOME/.mame/software

#
# CORE OUTPUT DIRECTORY OPTIONS
#
cfg_directory $HOME/.mame/cfg
nvram_directory $HOME/.mame/nvram
input_directory $HOME/.mame/inp
state_directory $HOME/.mame/sta
snapshot_directory $HOME/.mame/snap
diff_directory $HOME/.mame/diff
comment_directory $HOME/.mame/comments
share_directory $HOME/.mame/share
</pre>

TODO
- explain how the helper subfolders are set (create vs symlinks)
- helper launcher

=== Checking if it all works ===

TODO

== #CSpect emulator ==

The #CSpect is Mike Dailly's ZX Spectrum Next emulator, written in C# making it cross-platform (sort of, where the mono framework is available). It is non-free (closed-source, custom license) project, but available for usage without any payment (it's possible to use it internally to develop also commercial titles, but you can not distribute/sell the emulator itself, not even packaged with your game - for such agreement contact the author first and get his permission).

Currently it is most performant and user friendly emulator of ZX Spectrum Next, with good emulation accuracy (see [https://wiki.specnext.dev/CSpect:known_bugs CSpect:known_bugs] page for more detailed report).

=== Prerequisites ===

On Debian based systems make sure you have these packages installed:
<nowiki>sudo apt-get install mono-complete libopenal1 libsdl2-dev</nowiki>

=== Retrieving the #CSpect package ===

Use web browser to visit itch.io dedicated to CSpect project [https://mdf200.itch.io/cspect mdf200.itch.io/cspect] and download latest release.

You may get warnings from your browser or antivirus about the page itself and about the zip/binary files. The #CSpect has long record of triggering false positives of AV engines due to the executable being not digitally signed and because of the code using features of OS which are normal for emulator, but may look wonky for AV heuristic. Whether you trust the executable is virus free is up to you, in the end.

=== Installing the executable ===

Unzip the retrieved zip file (I personally use KDE Dolphin file manager, the file context menu ''"Extract -> Extract archive here, autodetect subfolder"''), and place the unzipped directory to target destination (<code>~/zx/emulators/CSpect/CSpect2_13_0</code> in my case). I prefer to keep every version in its own directory, and have general symbolic link pointing to the one I want use by default:
<nowiki>cd ~/zx/emulators/CSpect
ln -s CSpect2_13_0 CSpect_current</nowiki>

Then I create launcher bash-scripts in my <code>~/.local/bin</code> like this (name of script <code>runCSpect</code>):
<nowiki>#!/bin/bash
# personal script of Ped to launch "#CSpect" emulator in "current directory" (with arguments like: "runCSpect file.nex")
MONO_IOMAP=all mono ~/zx/emulators/CSpect/CSpect_current/CSpect.exe -tv -zxnext -s28 -w4 -mmc=./ "$@"</nowiki>

Notes: I don't know any more what <code>MONO_IOMAP=all</code> helps with, I believe it was suggested to help with any filesystem windows-like paths containing backslashes, you can try to do your own research. The <code>-tv</code> switch will switch off "scanlines" shader effect and generally switch off any GPU shaders, which makes CSpect more compatible with graphics drivers (try it, if you get only black screen or instant crash during init). The <code>-w4</code> will make the window quite large - 4x scale, the <code>-zxnext -s28</code> switch #CSpect into ZX Next emulation mode and set 28Mhz speed of OS as default. And finally the <code>-mmc=./ "$@"</code> will set ''current directory'' for esxdos emulation to the directory where you use the script to launch the emulator, and pass any remaining command line options entered by user, like the name of the SNA/NEX file. Other noteworthy options are <code>-debug -brk -map=file.map</code>, the -debug entering the debugger just ahead of the first instruction, -brk enables CSpect specific two-byte tag 0xDD 0x01 to work as breakpoint and the -map option allows you to load into debugger the symbol table from your assembler (directive CSPECTMAP in sjasmplus), making labels visible in disassembly.

=== Checking if it all works ===

Go to some directory with SNA/SNX/NEX file (there are also some demo files right in the CSpect directory) and use the launcher script, like:
<nowiki>runCSpect beast.nex</nowiki>

You should see #CSpect emulator window running the beast.nex demo (or whatever else you did want to launch and entered as argument).

[[File:Cspect_test_run.png|frameless|Running CSpect from directory with test snapshots]]

Assemblers

2026-04-23T12:55:37Z

Ped7g: sjasmplus version bump

Any Z80 assembler can produce code suitable for the Next. However the raw blocks of Z80 code may be not as convenient to use with Next or emulators, so a Next specific tools may be useful for creating one of the supported [[File Formats]].

== Cross-platform tools (running on PC) ==

=== ''[http://www.desdes.com/products/oldfiles/zeus.htm Zeus-ish]'' ===
: Provides a complete Z80 IDE and Macro assembler, scripted disassember plus an integrated Z80 emulator for a range of machines including partial Next support
: Supports the Next opcodes directly
: Supports remote debugging on the Next using ParaSys across a serial link
: Supports MMU paging in the integrated emulator
: Supports sprites (core versions prior to 2.00.26) in the integrated emulator

=== ''[http://pasmo.speccy.org/ Pasmo]'' ===
: A long established Z80 assembler, but has been mostly out of development for a long time (0.5.4-beta2 released in 2008, 0.5.5 in 2022)
: Supports all currently known Next extension opcodes in the 0.5.4-beta2-based 2018 version of [https://github.com/spec-chum/pasmo Pasmo modified by Russ McNulty and Tony Thompson] (also producing .sna files which were at that time used by CSpect).

=== ''SNasm'' ===
: Included with the [https://mdf200.itch.io/cspect #CSpect] emulator
: Full macro assembler
: Full bank control via Segment management
: Supports the Next extension opcodes directly
: Generates full 24bit map files for use in CSpect

=== ''z80asm'' ===
: Part of [https://github.com/z88dk/z88dk Z88dk]''
: Supports the Next extension opcodes directly, linking assembler with large z80 library, targets any memory configuration

=== ''[https://github.com/z00m128/sjasmplus z00m's fork of sjasmplus]'' ===
: Supports all (core2.00.28) Next extension opcodes, ZXN memory model (8 memory slots with 8ki pages and 1.75MiB virtual device memory), SAVENEX to build NEX files directly from ASM source (NEX version V1.2 (and experimental extension "V1.3")), MAP files for [https://mdf200.itch.io/cspect #CSpect] emulator, SLD tracing files for [https://github.com/maziac/DeZog DeZog] and [https://github.com/Ckirby101/NDS-NextDevSystem NDS-NextDevSystem] and it is under active development (feedback is welcome).
: Open source project ("BSD-3-Clause" license), '''windows executables available at [https://github.com/z00m128/sjasmplus/releases/latest releases]''', mac and linux users are expected to simply build from source (both make and CMake are supported).
: [http://z00m128.github.io/sjasmplus/documentation.html Documentation], latest stable release v1.23.0 2026-04-23

=== ''zmac'' ===

: [http://48k.ca/zmac.html zmac - Z-80 Macro Cross Assembler]

=== ''[https://github.com/CatpainBlack/FantASM FantASM]'' ===
: FantASM is a two pass non optimising assembler for the Z80 processor by [https://github.com/CatpainBlack Guy 'CatpainBlack' Black].

:It supports all undocumented op-codes and the extended instruction set of the ZX Next and additional pseudo opcodes used by the CSpect emulator to control debugging.

== Native tools (running on Next) ==

=== ''[https://gitlab.com/next-tools/odin Odin]'' ===

Work-in-progress Next-specific assembler written by Matt Davies, used also in video tutorials presented by Jim Bagley, the best way to acquire the binary is to join the official ZX Next discord server and check channel <code>#odin</code> - pinned messages, where you can also discuss any issues and get how-to hints.

: supports most of the undocumented opcodes, all official Z80 and Next-extended instructions
: supports nested includes and binary includes
: source is stored in tokenised form (smaller file), up to 48kiB of source in single file
: assembling can produce 32kiB of machine code (enough to produce simpler dot command)
: includes also editor and console modules (debugger is planned)

=== ''[https://www.solarisite.com/spectrumnext.html Sol]'' ===

Sol is an assembler and editor written by Solaris, that runs natively on the Next. Manual, assembler binary and assembler source can be downloaded [https://www.solarisite.com/spectrumnext.html here].

=== ''[https://gitlab.com/thesmog358/tbblue/-/tree/master/tools/dev/Zeus ZEUS]'' ===

Classic ZEUS native assembler by Simon Brattel, extended and included directly in the ZX Next distro.

=== ''[https://gitlab.com/thesmog358/tbblue/-/tree/master/tools/dev/SPED SPED]'' ===

Classic SPED assembler by César Hernández Bañó, included directly in the ZX Next distro, see [https://gitlab.com/thesmog358/tbblue/-/raw/master/docs/apps/dev/SPED53readme.txt README].

=== ''[https://taylorza.itch.io/nextbasic-inline-assembler NextBASIC Inline Assembler]''===
Enables you to write inline assembly code in your NextBASIC application. The assembler can be downloaded from [https://taylorza.itch.io/nextbasic-inline-assembler HERE] with documentation available [https://github.com/taylorza/zxn-inlineasm-doc/blob/main/README.md HERE]

MAME:Installing

2026-04-22T22:12:51Z

Ped7g: fix urls to specnext.cpp

[https://www.mamedev.org/ MAME] (formerly an acronym of Multiple Arcade Machine Emulator) is a free and open-source emulator designed to emulate the hardware of arcade games, later expanded to include video game consoles, old computers and other systems in software on modern personal computers and other platforms.

MAME has supported the ZX Spectrum Next since version 0.267. The existing implementation is based on the v3.02.01 core and implements most of the features.

= Installation =

You will need to install MAME, provide it with the Next firmware ('ROM'), and get the NextZXOS image:

=== 1. Get MAME ===
Start with these official MAME releases. If you encounter crashes or other bugs, try replacing the MAME executable with holub's latest Continuous Integration (CI) builds as described at the end of this article.

* '''Windows:''' Download [https://www.mamedev.org/release.html MAME for Windows].
* '''macOS:''' Download [https://sdlmame.lngn.net/ MAME for macOS].
* '''Linux:''' Install MAME from the flatpak repositories by running:
<pre>sudo flatpak install org.mamedev.MAME</pre>

Note that Windows and macOS will likely prevent you from launching MAME directly for security reasons. See below on how to solve this.

Alternatively, for the MAME platform as a whole, you can also check your package manager, or [https://docs.mamedev.org/initialsetup/compilingmame.html build from sources].

Git of official MAME: [https://github.com/mamedev/mame/ https://github.com/mamedev/mame/] [https://github.com/mamedev/mame/blob/master/src/mame/sinclair/next/specnext.cpp specnext.cpp]

Git of holub's fork: [https://github.com/holub/mame https://github.com/holub/mame] [https://github.com/holub/mame/blob/master/src/mame/sinclair/next/specnext.cpp specnext.cpp] (may contain extra fixes and features before they are merged to official repository)

=== 2. Get TBBLUE (the Next 'boot ROM') ===
Put the file [https://github.com/Threetwosevensixseven/NexCreator/raw/master/bootroms/tbblue.zip tbblue.zip] into MAME's <code>roms</code> folder. Don't extract it; MAME will look for the zip file when the "tbblue" machine is selected.

Note: The ROMs in this zip are what is embedded inside the FPGA core on real Next hardware. They're different from any ZX Spectrum machine ROMs you may be used to using, that are on the distro, SD card or SD image file.

=== 3. Get the NextZXOS Image ===
Get an SD card image file of [https://www.specnext.com/latestdistro/ NextZXOS]. Note that '''some disk images published on the official SpecNext.com site do not work with some emulators currently''' (the <code>latestdistro</code> link points to the official location where the latest distribution can be found), but '''all images from <code>https://zxnext.uk/hosted/</code> work with both MAME and CSpect''', like [https://zxnext.uk/hosted/index_files/hdfimages/cspect-next-2gb.zip this SD card image in the zip archive]. Extract the image <code>cspect-next-2gb.img</code> from the archive to use it, then point MAME to this SD card image with the <code>-hard1</code> option (or select that file from the menu inside MAME).

= Usage =
MAME looks for its configuration and helper files in specific (configurable) folders. By default, these are relative to the current working directory (cwd), i.e., from where you launched the executable. The <code>mame.ini</code> file and folders like <code>roms, bgfx, plugins, language, ...</code> are expected there, unless the <code>mame.ini</code> file specifies other paths. When launching through a desktop icon or menu, depending on the OS, the working directory is often defined by the properties of that launch shortcut. When launching MAME from the command line, the current directory is "cwd" (doh). On Linux, MAME will look for <code>mame.ini</code> first in the <code>~/.mame</code> folder. You can use the option <code>-inipath</code> to point MAME to a different path for the <code>mame.ini</code> file.

However, the fastest way to run a machine with a desired configuration is from the command prompt, without requiring a <code>mame.ini</code> file. Most of the features are also available through MAME's UI, although that takes more time to configure.

As an example, this invocation enables the UI, uses "crisp pixels", starts in a window, doesn't display the starting gameinfo window (it can still be displayed interactively from the UI), disables the mouse, confirms before exiting MAME, and specifies the disk image (remember to adjust the path to it):

<pre>mame -ui_active -nounevenstretch -aspect 2:1 -video bgfx -bgfx_screen_chains unfiltered -window -skip_gameinfo -mouse_device none -confirm_quit tbblue -hard1 /path/to/cspect-next-2gb.img</pre>

Let's cover some useful options:

<ol start="1">

<li>
Run inside a window and with no mouse support, until you get familiar with the UI keys:
<pre>> mame tbblue -window -mouse_device none -hard1 /path/to/next-distribution.img</pre>
To launch the Linux flatpak version using the same options:
<pre>> flatpak run org.mamedev.MAME tbblue -window -mouse_device none -hard1 /path/to/next-distribution.img</pre>
</li>

<li>
Activate UI keys on startup:
<pre>> ... -ui_active</pre>
</li>

<li>
Don't show the info popup on startup:
<pre>> ... -skip_gameinfo</pre>
</li>

<li>Run with debugger. If you don't request this on startup, you won't have access to it:
<pre>> ... -debug</pre>
</li>

<li>Use "crisp" pixels:
<pre>> ... -nounevenstretch -aspect 2:1 -video bgfx -bgfx_screen_chains unfiltered</pre>
</li>

<li>No joystick connected to PC (having this may slightly speed up MAME's startup, but ''remember to remove this part from the command line and the corresponding setting in the ini file if you do want to use a joystick''):
<pre>> ... -joystickprovider none</pre>
</li>

<li>Ask for confirmation when exiting MAME (otherwise it's easy to exit MAME accidentally by hitting ESC, especially when playing games or navigating menus):
<pre>> ... -confirm_quit</pre>
</ol>

Check the [https://docs.mamedev.org/commandline/commandline-all.html#mame-commandline-universal official MAME documentation] for more advanced usage.

= Security: Allowing MAME to Run on Windows and macOS =

'''On Windows,''' you will need to confirm that you want to launch MAME by clicking "Run Anyway" on first launch. ''(More details needed here.)''

'''On macOS,''' MAME will not open at first. Instead, a dialog will appear saying:

''“mame” Not Opened. Apple could not verify “mame” is free of malware that may harm your Mac or compromise your privacy.''

Click “Done”. Then open '''System Settings -> Privacy & Security''', and scroll down to the message ''mame was blocked to protect your Mac.'' Click “Allow Anyway”.

Now launch MAME again. A dialog will ask once more if you want to open “mame”. Click “Open Anyway”, and enter your password or use Touch ID when prompted by macOS.

From now on, you can launch this version of MAME without warnings. However, you '''will''' need to repeat this each time you update MAME.

= Keys =

Keys are emulated in two modes: either to control the MAME emulator or completely dedicated to the emulated system (the Next). You can toggle between these two keyboard modes with ScrLk (on Win and Linux) or fn+delete (on Mac).

Some UI keys:
* F3 - soft reset
* Shift+F3 - hard reset
* F4 - sprites/tiles/font viewer (Enter, ], [)
* F5 - pause emulation
* F6 - save state
* F7 - load state
* Tab - emulator settings
* ~ - menu
* ` (backtick) - debugger (when enabled by starting MAME with <code>-debug</code> or <code>-d</code> on the command line)
* PgDwn (Linux/Mac), fn-Downarrow (MacBooks) or Insert (Win) - hold down to fast-forward emulation at maximum speed, e.g., to speed up booting the Next
* Esc - exit (exits menus but also the entire emulator - see <code>-confirm_quit</code> option above)
* F11 - DivMMC NMI
* F12 - Multiface NMI

Check [https://docs.mamedev.org/usingmame/defaultkeys.html default keys documentation] for more.

= Changing the UI toggle key =

Some laptops don't have a Scroll Lock key, so you may not be able to exit MAME if you run it in full-screen mode. In these cases, you can change the UI toggle key as follows:

* Run MAME without any command line arguments (except maybe -window) to open its GUI.
* Push TAB and enter the General Settings menu.
* Go to Input Assignments -> User Interface -> Toggle UI controls and select a new key. I use Right Alt / Alt GR.
* Return to the previous menu twice, then choose Save Settings

= Creating and manipulating NextZXOS SD card image =

Most users wanting to emulate the Next using MAME will be fine using a pre-built SD card image downloaded from the site hosting best pre-made images (currently, [https://zxnext.uk/hosted zxnext.uk/hosted] ) website. The following guide is provided for anyone wanting to create a NextZXOS SD card image from scratch.

Download the [https://www.specnext.com/latestdistro/ latest NextZXOS distribution zip file] (named something like sn-complete-WX.YZ.zip) and extract it into a new, empty directory.

== Creating and populating a SD card image using hdfmonkey jjjs build ==

The [https://www.specnext.com/forum/viewtopic.php?t=2604 hdfmonkey "jjjs build"] is a variant of hdfmonkey tool which includes some unique features and its main archive (at the previously given link) also contains pre-built binaries for Windows x64, MacOS x64, MacOS Apple Silicon and Linux x64. (Alternatively, the process to build a local Linux version of the executable is described [[Development_Tools:Linux_setup#hdfmonkey_tool | here]] )

If you extracted sn-complete-WX.YZ.zip into a subdirectory named <code>snWXYZ</code>, and you want to create a 1GB image called <code>NextZXOS.img</code> and you have a jjjs build" of hdfmonkey, then it's enough to do:

<pre>
hdfmonkey create NextZXOS.img 1G
hdfmonkey putdir NextZXOS.img snWXYZ /
</pre>

The first line creates an empty 1GB image and formats it with the best FAT parameters suited to the size of the image.

The second line recursively copies all the content of the directory <code>snWXYZ</code> to the image, preserving the directory structure inside, starting from the <code>/</code> in the image.

One of the advantages of this method is that even if the image has a capacity of 1GB, it will use much less space on your hard drive until you fill up the image. On Linux or MacOS, a command <code>du -h NextZXOS.img</code> shows the actual amount of disk space used by the image. On Windows the same information can be seen in the File Properties dialog.

The fastest way to transfer a file or a directory (including its content, recursively) into an image is by using a single <code>put</code> (or <code>putdir</code>, if it's to transfer the directory file content to an existing directory) command of hdfmonkey.

The most convenient tool to copy of all the content from the image to a folder outside of the image is 7-zip. On Windows, just use the 7-zip GUI. On MacOS and Linux, see: [[Development_Tools:Linux_setup#Extracting_all_files_from_the_sd-card_image]].

=MAME Plugins and Scripts=

Some MAME plugins and scripts that may be useful for Next developers and end users are listed [[MAME:Plugins_and_Scripts|here]]. They let you speed up the Next boot time, profile your NextBASIC or assembler code, and more.

=Continuous Integration MAME Builds=

MAME is updated on a release schedule, but due to the ongoing nature of development, including for the MAME Next machine, it can sometimes be useful to install a more recent build if it contains a new feature or bugfix you are interested in. Sometimes, this ongoing work is discussed on social media, such as the [https://discordapp.com/channels/556228195767156758/752197165891321886 Next Developer Discord].

Continuous Integration (CI) builds are available from both the [https://github.com/mamedev/mame/actions primary MAME repo] and [https://github.com/holub/mame/actions holub's GitHub repo]. Both are considered bleeding-edge, with the primary MAME repo slightly less so. MAME CI builds are available for Windows, Linux, and macOS and are updated automatically whenever code is committed by a maintainer or pushed to the primary repo.

To try out a CI build (more precisely, the resulting binary executable, which is a produced "artifact" of the build process) , first do a full MAME install from the [https://www.mamedev.org/release.html latest release] if you have not already done so. Then back up your main binary from its installation location - these are called something like <code>mame.exe</code> or <code>mame</code>. You can always restore these if the CI build doesn't work, or if you don't like how it behaves.

'''You need to be logged in to github''' to download CI artifacts, so [https://github.com/login sign in] or [https://github.com/signup sign up].

Then visit one of the links above and find a workflow run item for your platform. Workflow items are the things in the list. The tags are flagged as <code>CI (Windows)</code>, <code>CI (Linux)</code>, or <code>CI (macOS)</code> in the second row of each workflow item in the list (not the filter in the left hand nav menu). Click on a completed workfow item (only items with green checkmarks will have created downloadable binaries yet), find the Artifacts section at the bottom, then click the Download button. Unzip the downloaded file and find the main binary (with the same name as above). Copy the main binary to the install location, overwriting the original one, and run MAME the same way you were running it before. On Windows and macOS, you need to repeat the security steps above to trust the new MAME executable.

= More MAME related links =

MAME [https://docs.mamedev.org/ documentation].

Report any issues with MAME on the [https://mametesters.org/ bugtracker].

For '''Linux''' users there are more tips (how to compile MAME from source, how to configure it to not use CWD as starting path for resource directories, how to mount or create image file) at [[Development_Tools:Linux_setup]] page.

[https://docs.mamedev.org/advanced/devicemap.html MAMEDEV.ORG MAME Stable Controller IDs].
By default, MAME does not assign stable numbers to input devices. For instance, a game pad controller may be assigned to “Joy 1” initially, but after restarting, the same game pad may be reassigned to “Joy 3”.
Here a some hints how to fixate MAME´s Joystick-Detection to specific Controllers: [https://www.youtube.com/watch?v=YmjfwLuZ_X0 Youtube - Mapping your controllers for stable IDs]
and: [https://forums.launchbox-app.com/topic/89296-stable-controller-ids-for-mame/ Stable Controller IDs for MAME]

Development Tools:Linux setup

2026-04-22T22:11:53Z

Ped7g:

== General ==

This page collects summaries of installation process of various tools related to ZX Spectrum Next software development for linux OS users.

As usual with linux, most of the suggestions are in the form of command line command to be used from terminal.

== sjasmplus assembler ==

You can also check the [https://www.youtube.com/watch?v=c6I4kdErEwE video] of installing sjasmplus on freshly reinstalled KDE neon 5.20 linux, where is also extended info how to run the automated tests of sjasmplus, and opening it in KDevelop IDE to eventually write your own modifications.

=== Prerequisites ===

On Debian based systems make sure you have these packages installed (git-cola and cmake are optional, but often handy):
<nowiki>sudo apt-get install git build-essential g++ git-cola cmake</nowiki>

=== Retrieving the sjasmplus source ===

Use git to clone the [https://github.com/z00m128/sjasmplus z00m's sjasmplus repository]:
<nowiki>git clone --recursive -j8 https://github.com/z00m128/sjasmplus.git</nowiki>

To update already cloned repository, do inside the sjasmplus folder:
<nowiki>git pull</nowiki>
- or use your favourite GIT client app to update the cloned repository.

=== Building the executable binary ===

The GNU make and common C++ compiler (gcc or clang) should be enough to build the binary:
<nowiki>make clean && make</nowiki>

To verify the binary was built ("dot slash" prefix to force running of binary in current folder, not system one):
<nowiki>./sjasmplus --version</nowiki>

=== Installing the executable ===

If you already have sjasmplus installed, use <code>which sjasmplus</code> to see where the installed executable is (and which installed executable has precedence), you can use this command also after installing the new executable to verify it is being picked up by the system.

Installing the binary in system-wide fashion:
<nowiki>sudo make install</nowiki>

Or you can install the binary only locally for your user (without root/sudo permissions):
<nowiki>mkdir -p ~/.local/bin
make PREFIX=~/.local install</nowiki>
- then make sure you have <code>~/.local/bin</code> in your user <code>PATH</code> environment variable (on some distros there is already script in .profile to add this to PATH if the dir does exist, so you may need to only logout/restart after creating it to get it active).

=== Checking if it all works ===

Open your terminal and type (in any directory):
<nowiki>sjasmplus --version</nowiki>

You should see version of the freshly built sjasmplus executable like this:
<nowiki>SjASMPlus Z80 Cross-Assembler v1.17.0 (https://github.com/z00m128/sjasmplus)</nowiki>

== hdfmonkey tool ==

The hdfmonkey tool can manipulate card-images, helping to write new builds of your project into NextZXOS card-image, to boot the emulators with full file system. (it's also possible to mount the images directly into linux by other means, to operate on them with regular file manager/etc, but hdfmonkey suits better use-case when the build script does update the image)

=== Prerequisites ===

On Debian based systems make sure you have these packages installed:
<nowiki>sudo apt-get install git build-essential g++ autoconf</nowiki>

=== Retrieving the hdfmonkey source ===

Use git to clone the [https://github.com/ped7g/hdfmonkey hdfmonkey repository with patched 0.5.7 <code>jjjs version</code> sources]:
<nowiki>git clone https://github.com/ped7g/hdfmonkey.git</nowiki>
(make sure you are on the default branch <code>"jjjs-variant"</code> to build the improved version, it should be checked out by default after clone)

* to update already cloned repository, do inside the hdfmonkey folder:
<nowiki>git pull</nowiki>
* or use your favourite GIT client app to update the cloned repository.
* if you cloned original gasman's repository before, you may want to clone and rebuild here mentioned <code>jjjs version</code> to get multiple fixes and convenience features.

=== Building the executable binary ===

The hdfmonkey is using autoconf/autotools to build final Makefile, check the hdfmonkey README for "from git" installation notes, at the moment of writing this page, the steps were:
<nowiki>cd hdfmonkey
autoheader
aclocal
autoconf
automake -a
./configure
make</nowiki>

To verify the binary was built:
<nowiki>src/hdfmonkey help</nowiki>

=== Installing the executable ===

If you already have hdfmonkey installed, use <code>which hdfmonkey</code> to see where the installed executable is (and which installed executable has precedence), you can use this command also after installing the new executable to verify it is being picked up by the system.

Installing the binary in system-wide fashion:
<nowiki>sudo make install</nowiki>

Or you can install the binary only locally for your user (without root/sudo permissions):
<nowiki>make prefix=~/.local install</nowiki>
- then make sure you have <code>~/.local/bin</code> in your user <code>PATH</code> environment variable.

=== Checking if it all works ===

Open your terminal and type (in any directory):
<nowiki>hdfmonkey help</nowiki>

You should see help of the freshly built hdfmonkey `jjjs version` executable like this:
<nowiki>hdfmonkey: utility for manipulating HDF disk images v0.5.7 jjjs

usage: hdfmonkey <command> [args]
...</nowiki>

== Extracting all files from the sd-card image ==

7-zip is the most convenient tool to extract the the files from the existing image.

To install 7-zip on a Debian system use <code>sudo apt install 7zip</code>.

To extract all the files from an existing image <code>tbblue.img</code> to a new subdirectory <code>myfiles</code>:

<nowiki>7z x tbblue.img -omyfiles</nowiki>

== Creating new sd-card image with hdfmonkey ==

This example:

* downloads the archive from the specnext.com
* unpacks it to the subdirectory <code>tmptb</code>
* creates a new SD image (with the space for 2GB files) from all the files
* deletes the subdirectory <code>tmptb</code>
* shows that the new image uses much less than 2GB
* starts listing the content of the newly created image

<nowiki>
wget https://www.specnext.com/distro/24.11/sn-complete-24.11.zip
7z x sn-complete-24.11.zip -otmptb
hdfmonkey create tbblue.img 2GB
hdfmonkey putdir tbblue.img tmptb /
rm -rf tmptb
du -h tbblue.img
7z l tbblue.img | more</nowiki>

=== Creating new sd-card image without hdfmonkey ===

It's possible to use gnu coreutils and dosfstools to create card image without hdfmonkey, but depending on exact size of image these may be less compatible with various emulator, following example for 1GB card image works in MAME but fails in CSpect (while images created by hdfmonkey tool should work for both emulator, so using '''hdfmonkey is recommended''')

<nowiki>
truncate -s 1G NextZXOS.img
parted NextZXOS.img mklabel msdos
parted NextZXOS.img mkpart primary fat32 2048s 100%
mkfs.fat -F 32 --offset=2048 NextZXOS.img
# and now to copy files to image you have to either mount it or use hdfmonkey:
# hdfmonkey putdir NextZXOS.img tmptb /</nowiki>

== Mounting sd-card image directly ==

Sometimes it may be useful to mount the card image directly, to be able to browse it and manipulate with common tools. But make sure you are not using mounted card image also in emulator at the same time, to prevent any data damage by parallel access.

=== Prerequisites ===

On Debian based systems make sure you have these packages installed:
<nowiki>sudo apt-get install fdisk mount</nowiki>

Prepare empty directory to mount the card image into (let's call it "next-card") and have the image file around ("tbblue.mmc" in following examples)
<nowiki>mkdir -p next-card</nowiki>

=== Mounting the card image ===

To mount the card image you need to know the exact byte-offset where the FAT partition starts, it's possible to read it from "fdisk" or "parted" tools outputs:
<nowiki>fdisk -l -o Start tbblue.mmc
# prints value in sector units, like:
# Start
# 63
# This has to be multiplied by 512 to get byte offset: 63*512 = 32256

# or

parted tbblue.mmc unit B print
# prints values in bytes with "B" suffix in "Start" column</nowiki>

But the fdisk output can be incorporated directly into mount command, which needs root permissions, example with sudo:
<nowiki>sudo mount tbblue.mmc next-card/ -o loop,offset=$((`fdisk -l -o Start tbblue.mmc | tail -1` * 512)),user,uid=`id -u`,gid=`id -g`

# or you can enter the offset yourself

sudo mount tbblue.mmc next-card/ -o loop,offset=32256,user,uid=`id -u`,gid=`id -g`</nowiki>

The uid and gid options will mount the filesystem under your regular user, so you can now browse it with file manager, text editors, etc.

Do not run the emulator yet, before unmounting the image (after you are done manipulating the files)!

=== Unmount the image before using it in emulator ===

<nowiki>sudo umount next-card/</nowiki>

Check the result. If the unmounting fails (probably with "target is busy"), find which process is still accessing/viewing the files in the next-card directory, and try to unmount it again.

== Mounting sd-card image with losetup ==

Alternative using losetup to use local "loop" device for mounting the image. This method can automatically detect partitions inside the image and exposes them as loop devices.

Prepare mounting dir and make sure you have <code>mount</code> and <code>losetup</code> available, Ubuntu based systems packages:
<nowiki>sudo apt-get install util-linux mount</nowiki>

=== Use losetup to attach image and scan its partitions ===

<nowiki>sudo losetup --partscan --show --find NextZXOS.img
# this will print new loop device and automatically create partition devices like /dev/loop0p1
# now mount the desired FAT32 partition:
sudo mount /dev/loop0p1 next-card/</nowiki>

=== Unmounting and cleanup of loop device ===

When finished:
<nowiki>sudo umount next-card/
sudo losetup -d /dev/loop0
# or `sudo losetup -D` to detach *ALL* loop devices</nowiki>

This detaches the loop device and frees all associated /dev/loop* entries.

Notes and gotchas:
* Do not use the image in an emulator while it is mounted.
* If the image has no partition table, --partscan will not create /dev/loop0p1.
* If multiple loop devices are active, check <code>losetup -a</code> to confirm which one is yours.

== Mounting sd‑card image with udisksctl ==

The <code>udisksctl</code> tool provides a desktop‑friendly way to attach loop devices and mount filesystems without manually calculating offsets or using <code>losetup</code>. It integrates with system services such as UDisks2, and on many desktop Linux systems it allows non‑root users (who are in the correct group) to mount images safely.

=== Prerequisites ===

On Debian‑based systems install the UDisks2 tools:

<nowiki>sudo apt-get install udisks2</nowiki>

To run <code>udisksctl</code> without <code>sudo</code>, your user must belong to the '''disk''', '''storage''', or '''udisks''' policy group (varies by distribution). If unsure, simply use <code>sudo</code> in the examples below.

=== Attaching the image as a loop device ===

Use <code>udisksctl loop-setup</code> to create a loop device for the image:

<nowiki>udisksctl loop-setup --file NextZXOS.img
# prints something like:
# Mapped file NextZXOS.img as /dev/loop2.
# UDisks automatically scans the partition table and exposes partitions as:
# /dev/loop2p1
# /dev/loop2p2
# ...</nowiki>

=== Mounting the FAT32 partition ===

Mount the desired partition:

<nowiki>udisksctl mount --block-device /dev/loop2p1
# This prints the mount point, for example:
# Mounted /dev/loop2p1 at /media/youruser/NextZXOS.</nowiki>

You can now browse and edit the filesystem normally using your file manager or command‑line tools.

=== Unmounting and cleanup ===

<nowiki>udisksctl unmount --block-device /dev/loop2p1
udisksctl loop-delete --block-device /dev/loop2</nowiki>

This cleanly detaches the loop device and removes all <code>/dev/loop*</code> entries created for the image.

=== Notes and gotchas ===

* Do not use the image in an emulator while it is mounted, parallel access may corrupt data.
* If the image has no partition table, UDisks will not create '''/dev/loopXp1''' and you must mount manually using an offset.
* Mount points are created under <code>/media/$USER/</code> unless overridden by system policy.
* UDisks may auto‑mount partitions immediately after '''loop‑setup''' depending on desktop environment settings.

== MAME emulator ==

MAME got Next emulation and it got improved a lot around end of 2025, turning it into probably most accurate and performant Next emulator currently available. But as that shift is quite recent, the developers community haven’t transitioned to it yet in large numbers and the tutorials and examples are non-existent. This section provides a basic Linux setup guide.

This chapter focuses only on installing MAME from source code git repository, so you can update to latest work in progress or even contribute to the development yourself. The stable binary releases already contain decent Next emulation, but bug fixes and improvements are still coming often and stable releases trail a few weeks behind.

At the moment, the primary developer working on Next emulation in MAME is Andrei Holub, so his fork repo will be used as default source.

=== Prerequisites ===

You need C++17 compiler (GCC 10.3+ or clang 11+), GNU make and few more development tools and common libraries, for specific list for your distro and up to date information check [https://docs.mamedev.org/initialsetup/compilingmame.html Compiling MAME] web page from official docs.

Keep this page around as the example here is quick hint and not meant as replacement for full documentation.

=== Retrieving the MAME source ===

Use git to clone the [https://github.com/holub/mame holub's MAME repository] and add the [https://github.com/mamedev/mame official MAME repository] as an additional remote:
<nowiki>git clone --origin holubdev https://github.com/holub/mame.git
cd mame
git remote add -f --tags mamedev https://github.com/mamedev/mame.git</nowiki>

To update already cloned repository checked out at master branch, do inside the mame folder (WARNING: this will drop any local changes in the repository, as MAME devs often rewrite already published commits and you need to reset your local clone to latest state - if you are developer working on MAME sources, you should know yourself how to work with git to preserve your changes and rebase/merge):
<nowiki>git fetch --all --force
git reset --hard master</nowiki>
Or use your favourite GIT client app to update the cloned repository.

=== Building the executable binary ===

To '''rebuild''' '''only''' Next emulation (''"tbblue"'' machine) and get executable named <code>tbblue</code>, run <code>make</code> like this:
<nowiki># make sure there are no remnants from previous builds
make clean
# If you want to, you can change to TOOLS=1 to build also "various additional tools, such as chdman"
# The name of resulting binary is affected by SUBTARGET=tbblue, leave it out if you want "mame"
make REGENIE=1 EMULATOR=1 TOOLS=0 SOURCES=sinclair/next/specnext.cpp SUBTARGET=tbblue -j $(nproc)
# check the build output to confirm that compilation succeeded. To list binary:
ls -lh tbblue</nowiki>

This may take a considerable amount of time depending on how powerful your PC is.

If you are developing MAME yourself, you can do incremental build (after REGENIE=1 was used to "generate project files" in previous build and your source code changes don't require full rebuild) - this will be lot faster of course as usual:
<nowiki>make SUBTARGET=tbblue -j $(nproc)</nowiki>

To rebuild full MAME including all other emulation targets (computers and arcade machines) - which will take even much longer - use:
<nowiki>make clean && make REGENIE=1 EMULATOR=1 TOOLS=0 -j $(nproc)
# check existence of new binary (the line above will produce default name "mame")
ls -lh mame</nowiki>

=== Installing the executable and configuration ===

TODO

=== Checking if it all works ===

TODO

== #CSpect emulator ==

The #CSpect is Mike Dailly's ZX Spectrum Next emulator, written in C# making it cross-platform (sort of, where the mono framework is available). It is non-free (closed-source, custom license) project, but available for usage without any payment (it's possible to use it internally to develop also commercial titles, but you can not distribute/sell the emulator itself, not even packaged with your game - for such agreement contact the author first and get his permission).

Currently it is most performant and user friendly emulator of ZX Spectrum Next, with good emulation accuracy (see [https://wiki.specnext.dev/CSpect:known_bugs CSpect:known_bugs] page for more detailed report).

=== Prerequisites ===

On Debian based systems make sure you have these packages installed:
<nowiki>sudo apt-get install mono-complete libopenal1 libsdl2-dev</nowiki>

=== Retrieving the #CSpect package ===

Use web browser to visit itch.io dedicated to CSpect project [https://mdf200.itch.io/cspect mdf200.itch.io/cspect] and download latest release.

You may get warnings from your browser or antivirus about the page itself and about the zip/binary files. The #CSpect has long record of triggering false positives of AV engines due to the executable being not digitally signed and because of the code using features of OS which are normal for emulator, but may look wonky for AV heuristic. Whether you trust the executable is virus free is up to you, in the end.

=== Installing the executable ===

Unzip the retrieved zip file (I personally use KDE Dolphin file manager, the file context menu ''"Extract -> Extract archive here, autodetect subfolder"''), and place the unzipped directory to target destination (<code>~/zx/emulators/CSpect/CSpect2_13_0</code> in my case). I prefer to keep every version in its own directory, and have general symbolic link pointing to the one I want use by default:
<nowiki>cd ~/zx/emulators/CSpect
ln -s CSpect2_13_0 CSpect_current</nowiki>

Then I create launcher bash-scripts in my <code>~/.local/bin</code> like this (name of script <code>runCSpect</code>):
<nowiki>#!/bin/bash
# personal script of Ped to launch "#CSpect" emulator in "current directory" (with arguments like: "runCSpect file.nex")
MONO_IOMAP=all mono ~/zx/emulators/CSpect/CSpect_current/CSpect.exe -tv -zxnext -s28 -w4 -mmc=./ "$@"</nowiki>

Notes: I don't know any more what <code>MONO_IOMAP=all</code> helps with, I believe it was suggested to help with any filesystem windows-like paths containing backslashes, you can try to do your own research. The <code>-tv</code> switch will switch off "scanlines" shader effect and generally switch off any GPU shaders, which makes CSpect more compatible with graphics drivers (try it, if you get only black screen or instant crash during init). The <code>-w4</code> will make the window quite large - 4x scale, the <code>-zxnext -s28</code> switch #CSpect into ZX Next emulation mode and set 28Mhz speed of OS as default. And finally the <code>-mmc=./ "$@"</code> will set ''current directory'' for esxdos emulation to the directory where you use the script to launch the emulator, and pass any remaining command line options entered by user, like the name of the SNA/NEX file. Other noteworthy options are <code>-debug -brk -map=file.map</code>, the -debug entering the debugger just ahead of the first instruction, -brk enables CSpect specific two-byte tag 0xDD 0x01 to work as breakpoint and the -map option allows you to load into debugger the symbol table from your assembler (directive CSPECTMAP in sjasmplus), making labels visible in disassembly.

=== Checking if it all works ===

Go to some directory with SNA/SNX/NEX file (there are also some demo files right in the CSpect directory) and use the launcher script, like:
<nowiki>runCSpect beast.nex</nowiki>

You should see #CSpect emulator window running the beast.nex demo (or whatever else you did want to launch and entered as argument).

[[File:Cspect_test_run.png|frameless|Running CSpect from directory with test snapshots]]

Fallback Colour Register

2026-04-05T18:58:08Z

Ped7g: fix default value description

{{NextRegister
|Number=$4A
|Readable=Yes
|Writable=Yes
|ShortDesc=8-bit colour to be used when all layers contain transparent pixel.
}}
Colour format is RRRGGGBB, like {{NextRegNo|$41}} uses.

Value is set to 0xE3 by core upon soft reset, but I (Ped7g) think the NextZXOS sets it to 0 (black colour) upon finishing boot.

This colour is also used for PAPER and BORDER when ULANext mode is enabled, and "full ink" (ink mask = 255) mode is selected.

DMA

2026-03-30T14:13:17Z

Ped7g: Note about command A7 and Zilog docs vs Next FPGA implementation

== Overview ==
The ZX Spectrum Next DMA (zxnDMA) is a single channel DMA device that implements a subset of the Z80 DMA functionality. The subset is large enough to be compatible with common uses of the similar Datagear interface available for standard ZX Spectrum computers and compatibles. It also adds a burst mode capability that can deliver audio at programmable sample rates to the DAC device.

== Accessing the zxnDMA ==
<del>The zxnDMA is mapped to a single Read/Write IO Port 0x6B which is the same one used by the Datagear but unlike the Datagear it doesn't also map itself to a second port 0x0B similar to the MB-02 interface.</del>

Since core 3.1.2 the zxnDMA is mapped to {{PortNo|$xx6B}}, and Zilog-DMA mode is mapped to {{PortNo|$xx0B}}.

== Description ==
The normal Z80 DMA (Z8410) chip is a pipelined device and because of that it has numerous off-by-one idiosyncrasies and requirements on the order that certain commands should be carried out. These issues are not duplicated in the zxnDMA. You can continue to program the zxnDMA as if it is were a Z8410 DMA device but it can also be programmed in a simpler manner.

The single channel of the zxnDMA chip consists of two ports named A and B. Transfers can occur in either direction between ports A and B, each port can describe a target in memory or IO, and each can be configured to autoincrement, autodecrement or stay fixed after a byte is transferred.

A special feature of the zxnDMA can force each byte transfer to take a fixed amount of time so that the zxnDMA can be used to deliver sampled audio.

== Modes of Operation ==
The zxnDMA can operate in a z80-DMA compatibility mode.

'''REMOVED in core 3.1.2:''' <del>The z80-DMA compatibility mode is selected by setting bit 6 of nextreg 0x06. In this mode, all transfers involve length+1 bytes which is the same behaviour as the z80-DMA chip. In zxn-DMA mode, the transfer length is exactly the number of bytes programmed. This mode is mainly present to accommodate existing spectrum software that uses the z80-DMA and for cp/m programs that may have a z80-DMA option.</del>

'''Since core 3.1.2:''' the DMA mode is selected by port number, the {{PortNo|$xx6B}} works in zxnDMA mode, {{PortNo|$xx0B}} works in Zilog mode. The bit 6 in {{NextRegNo|$06}} is not DMA related any more and will be reused for something different.

The zxnDMA can also operate in either burst or continuous modes.

Continuous mode means the DMA chip runs to completion without allowing the CPU to run. When the CPU starts the DMA, the DMA operation will complete before the CPU executes its next instruction.

Burst mode nominally means the DMA lets the CPU run if either port is not ready. This condition can't happen in the zxnDMA chip except when operated in the special fixed time transfer mode. In this mode, the zxnDMA will let the CPU run while it waits for the fixed time to expire between bytes transferred.

Note that there is no byte transfer mode as in the Z80 DMA.

== Programming the zxnDMA ==
Like the Z80 DMA chip, the zxnDMA has seven write registers named WR0-WR6 that control the device. Each register WR0-WR6 can have zero or more parameters associated with it.

In a first write to the zxnDMA port, the write value is compared against a bitmask to determine which of the WR0-WR6 is the target. Remaining bits in the written value can contain data as well as a list of associated parameter bits. The parameter bits determine if further writes are expected to deliver parameter values. If there are multiple parameter bits set, the expected order of parameter values written is determined by parameter bit position from right to left (bit 0 through bit 7). Once all parameters are written, the zxnDMA again expects a regular register write selecting WR0-WR6.

The table below describes the registers and the bitmask required to select them on the zxnDMA.

{|
! Register Group
! Register Function Description
! Bitmask
! Notes
|-
| WR0
| Direction, Operation and Port A configuration
| <pre>0XXXXXAA</pre>
| AA must NOT be 00
|-
| WR1
| Port A configuration
| <pre>0XXXX100</pre>
|
|-
| WR2
| Port B configuration
| <pre>0XXXX000</pre>
|
|-
| WR3
| Activation
| <pre>1XXXXX00</pre>
| It’s best to use WR6
|-
| WR4
| Port B, Timing and Interrupt configuration
| <pre>1XXXXX01</pre>
|
|-
| WR5
| Ready and Stop configuration
| <pre>10XXX010</pre>
|
|-
| WR6
| Command Register
| <pre>1XXXXX11</pre>
|
|}

== zxnDMA Registers ==
These are described below following the same convention used by Zilog for its DMA chip:

=== WR0 – Write Register Group 0 ===

<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
0 | | | | | | |
| | | | | 0 0 Do not use
| | | | | 0 1 Transfer (Prefer this for Z80 DMA compatibility)
| | | | | 1 0 Do not use (Behaves like Transfer, Search on Z80 DMA)
| | | | |
| | | | | 1 1 Do not use (Behaves like Transfer, Search/Transfer on Z80 DMA)
| | | | |
| | | | 0 = Port B -> Port A (Byte transfer direction)
| | | | 1 = Port A -> Port B
| | | V
D7 D6 D5 D4 D3 D2 D1 D0 PORT A STARTING ADDRESS (LOW BYTE)
| | V
D7 D6 D5 D4 D3 D2 D1 D0 PORT A STARTING ADDRESS (HIGH BYTE)
| V
D7 D6 D5 D4 D3 D2 D1 D0 BLOCK LENGTH (LOW BYTE)
V
D7 D6 D5 D4 D3 D2 D1 D0 BLOCK LENGTH (HIGH BYTE)</pre>

Several registers are accessible from WR0. The first write to WR0 is to the base register byte. Bits D6:D3 are optionally set to indicate that associated registers in this group will be written next. The order the writes come in are from D3 to D6 (right to left). For example, if bits D6 and D3 are set, the next two writes will be directed to PORT A STARTING ADDRESS LOW followed by BLOCK LENGTH HIGH.

=== WR1 – Write Register Group 1 ===

<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
0 | | | | 1 0 0
| | | |
| | | 0 = Port A is memory
| | | 1 = Port A is IO
| | |
| 0 0 = Port A address decrements
| 0 1 = Port A address increments
| 1 0 = Port A address is fixed
| 1 1 = Port A address is fixed
|
V
D7 D6 D5 D4 D3 D2 D1 D0 PORT A VARIABLE TIMING BYTE
0 0 0 0 0 0 | |
0 0 = Cycle Length = 4
0 1 = Cycle Length = 3
1 0 = Cycle Length = 2
1 1 = Do not use
</pre>

The cycle length is the number of cycles used in a read or write operation. The first cycle asserts signals and the last cycle releases them. There is no half cycle timing for the control signals.

=== WR2 – Write Register Group 2 ===

<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
0 | | | | 0 0 0
| | | |
| | | 0 = Port B is memory
| | | 1 = Port B is IO
| | |
| 0 0 = Port B address decrements
| 0 1 = Port B address increments
| 1 0 = Port B address is fixed
| 1 1 = Port B address is fixed
|
V
D7 D6 D5 D4 D3 D2 D1 D0 PORT B VARIABLE TIMING BYTE
0 0 | 0 0 0 | |
| 0 0 = Cycle Length = 4
| 0 1 = Cycle Length = 3
| 1 0 = Cycle Length = 2
| 1 1 = Do not use
|
V
D7 D6 D5 D4 D3 D2 D1 D0 ZXN PRESCALAR (FIXED TIME TRANSFER)
</pre>
The ZXN PRESCALAR is a feature of the zxnDMA implementation. If non-zero, a delay will be inserted after each byte is transferred such that the total time needed for each transfer is determined by the prescalar. This works in both the continuous mode and the burst mode. If the DMA is operated in burst mode, the DMA will give up any waiting time to the CPU so that the CPU can run while the DMA is idle.

The rate of transfer is given by the formula “Frate = 875kHz / prescalar” or, rearranged, “prescalar = 875kHz / Frate”. The formula is framed in terms of a sample rate (Frate) but Frate can be inverted to set a transfer time for each byte instead. The 875kHz constant is a nominal value assuming a 28MHz system clock; the system clock actually varies from this depending on the video timing selected by the user (HDMI, VGA0-6) so for complete accuracy the constant should be prorated according to documentation for nextreg 0x11.

In a DMA audio setting, selecting a sample rate of 16kHz would mean setting the prescalar value to 55. This sample period is constant across changes in CPU speed.

=== WR3 – Write Register Group 3 ===

<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
1 | 0 0 0 0 0 0
|
1 = DMA Enable
</pre>
The Z80 DMA defines more fields but they are ignored by the zxnDMA. The two other registers defined by the Z80 DMA in this group on D4 and D3 are implemented by the zxnDMA but they do nothing.

It is preferred to start the DMA by writing an 'Enable DMA' command to WR6.

=== WR4 – Write Register Group 4 ===

<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
1 | | 0 | | 0 1
| | | |
0 0 = Do not use (Behaves like Continuous mode, Byte mode on Z80 DMA)
0 1 = Continuous mode
1 0 = Burst mode
1 1 = Do not use
| |
| V
D7 D6 D5 D4 D3 D2 D1 D0 PORT B STARTING ADDRESS (LOW BYTE)
|
V
D7 D6 D5 D4 D3 D2 D1 D0 PORT B STARTING ADDRESS (HIGH BYTE)
</pre>
The Z80 DMA defines three more registers in this group through D4 that define interrupt behaviour. Interrups and pulse generation are not implemented in the zxnDMA nor are these registers available for writing.

=== WR5 – Write Register Group 5 ===
<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
1 0 | | 0 0 1 0
| |
| 0 = /ce only
| 1 = /ce & /wait multiplexed
|
0 = Stop on end of block
1 = Auto restart on end of block
</pre>
The /ce & /wait mode is implemented in the zxnDMA but is not currently used. This mode has an external device using the DMA's /ce pin to insert wait states during the DMA's transfer.

The auto restart feature causes the DMA to automatically reload its source and destination addresses and reset its byte counter to zero to repeat the last transfer when a previous one is finished.

=== WR6 – Command Register ===
<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
1 ? ? ? ? ? 1 1
| | | | |
1 0 0 0 0 = 0xC3 = Reset
1 0 0 0 1 = 0xC7 = Reset Port A Timing
1 0 0 1 0 = 0xCB = Reset Port B Timing
0 1 1 0 0 = 0xB3 = Force Ready (irrelevant for zxnDMA)
0 1 1 1 1 = 0xBF = Read Status Byte
0 0 0 1 0 = 0x8B = Reinitialize Status Byte
0 1 0 0 1 = 0xA7 = Initialize Read Sequence
1 0 0 1 1 = 0xCF = Load
1 0 1 0 0 = 0xD3 = Continue
0 0 0 0 1 = 0x87 = Enable DMA
0 0 0 0 0 = 0x83 = Disable DMA
+-- 0 1 1 1 0 = 0xBB = Read Mask Follows
|
D7 D6 D5 D4 D3 D2 D1 D0 READ MASK
0 | | | | | | |
| | | | | | V
D7 D6 D5 D4 D3 D2 D1 D0 Status Byte
| | | | | |
| | | | | V
D7 D6 D5 D4 D3 D2 D1 D0 Byte Counter Low ("High" with core 3.0.5 = bug in core)
| | | | |
| | | | V
D7 D6 D5 D4 D3 D2 D1 D0 Byte Counter High ("Low" with core 3.0.5 = bug in core)
| | | |
| | | V
D7 D6 D5 D4 D3 D2 D1 D0 Port A Address Low
| | |
| | V
D7 D6 D5 D4 D3 D2 D1 D0 Port A Address High
| |
| V
D7 D6 D5 D4 D3 D2 D1 D0 Port B Address Low
|
V
D7 D6 D5 D4 D3 D2 D1 D0 Port B Address High
</pre>
Unimplemented Z80 DMA commands are ignored.

Prior to starting the DMA transfer, a LOAD command must be issued to copy the Port A and Port B addresses into the DMA's internal pointers. Then an 'Enable DMA' command is issued to start the DMA. The last LOAD command before ENABLE must be done with correct transfer direction set.

The 'Continue' command resets the DMA's byte counter so that a following 'Enable DMA' allows the DMA to repeat the last transfer but using the current internal address pointers. I.e. it continues from where the last copy operation left off.

Reset and Reset Port A/B Timing commands on zxnDMA do reset also prescalar value.

Registers can be read via an IO read from the DMA port after setting the read mask. (At power up the read mask is set to 0x7f). Register values are the current internal DMA counter values. So 'Port Address A Low' is the lower 8-bits of Port A’s next transfer address. Once the end of the read mask is reached, further reads loop around to the first one.

The format of the DMA status byte is as follows:

<pre>00E1101T</pre>

E is set to 0 if the total block length has been transferred at least once.

T is set to 1 if at least one byte has been transferred.

== Operating speed ==
The zxnDMA operates at the same speed as the CPU, that is 3.5MHz, 7MHz, 14MHz or 28Mhz. This is a contended clock that is modified by the ULA and the auto-slowdown by [[Layer 2|Layer2]] (which only occurred in Next core's 1 and 2, the limitation was lifted in core 3.0).

The (pre-core 3.0) auto-slowdown occurs without user intervention if speed exceeds 7Mhz and the active Layer2 display is being generated (higher speed operation resumes when the active Layer2 display is not generated). Programmers do NOT need to account for speed differences regarding DMA transfers as this happens automatically.

Because of this, the cycle lengths for Ports A and B can be set to their minimum values without ill effects. The cycle lengths specified for Ports A and B are intended to selectively slow down read or write cycles for hardware that cannot operate at the DMA's full speed.

== The DMA and Interrupts ==
The zxnDMA cannot currently generate [[Interrupts|interrupts]].

The other side of this is that while the DMA controls the bus, the Z80 cannot respond to interrupts. On the Z80, the NMI interrupt is edge triggered so if an NMI occurs the fact that it occurred is stored internally in the Z80 so that it will respond when it is woken up. On the other hand, maskable interrupts are level triggered. That is, the Z80 must be active to regularly sample the /INT line to determine if a maskable interrupt is occurring. On the Spectrum and the ZX Next, the ULA (and line interrupt) are only asserted for a fixed amount of time ~30 cycles at 3.5MHz. If the DMA is executing a transfer while the interrupt is asserted, the CPU will not be able to see this and it will most likely miss the interrupt. In burst mode, with large-enough prescalar value, the CPU will never miss these interrupts, although this may change if multiple channels are implemented.

'''Since core 3.1.8:''' the ability to interrupt DMA transfers was added, this is opt-in mechanism and must be configured through {{NextRegNo|$CC}}, {{NextRegNo|$CD}} and {{NextRegNo|$CE}} and requires "hw im2 mode" interrupts being set. Because interrupts are only sampled at the end of an instruction by the Z80, each time the dma is interrupted one instruction of progress is made in the main program (before the interrupt handler code is entered).

This means after starting the DMA transfer with last `out` instruction you must follow it by N instructions which don't affect the transfer (don't remap source data memory, select different sprite/copper/... index if that's target of transfer, don't write anything to zxnDMA port), either doing different kind of work with CPU or adding block of `nop` instructions, to have non-interfering block of code available to fire N interrupts during transfer. Chose N to accommodate for worst case scenario of how many times you will interrupt the running DMA transfer. Or you can read state of zxnDMA to see if transfer did finish, but (IMHO by ped7g) in most cases it will be performance-cheaper to just add block of nop instructions or do other work on CPU not interfering with transfer.

== Programming examples ==
A simple way to program the DMA is to walk down the list of registers WR0-WR5, sending desired settings to each. Then start the DMA by sending a LOAD command followed by an ENABLE_DMA command to WR6. Once more familiar with the DMA, you will discover that the amount of information sent can be reduced to what changes between transfers.

=== Assembly ===
Short example program to DMA memory to the screen, then DMA a sprite image from memory to sprite RAM, and then showing said sprite scrolling across the screen.

<pre>;------------------------------------------------------------------------------
; sjasmplus extra options to enable Z80N, stricter syntax and Next device
opt --zxnext --syntax=abf : device zxspectrumnext
;------------------------------------------------------------------------------
; DEFINE testing ; uncomment to produce NEX file (instead of DOT)
;------------------------------------------------------------------------------
; DMA (Register 6)
;
;------------------------------------------------------------------------------
;zxnDMA programming example
;------------------------------------------------------------------------------
;(c) Jim Bagley
;------------------------------------------------------------------------------
DMA_RESET equ $c3
DMA_RESET_PORT_A_TIMING equ $c7
DMA_RESET_PORT_B_TIMING equ $cb
DMA_LOAD equ $cf ; %11001111
DMA_CONTINUE equ $d3
DMA_DISABLE_INTERUPTS equ $af
DMA_ENABLE_INTERUPTS equ $ab
DMA_RESET_DISABLE_INTERUPTS equ $a3
DMA_ENABLE_AFTER_RETI equ $b7
DMA_READ_STATUS_BYTE equ $bf
DMA_REINIT_STATUS_BYTE equ $8b
DMA_START_READ_SEQUENCE equ $a7
DMA_FORCE_READY equ $b3
DMA_DISABLE equ $83
DMA_ENABLE equ $87
DMA_WRITE_REGISTER_COMMAND equ $bb
DMA_BURST equ %11001101
DMA_CONTINUOUS equ %10101101
ZXN_DMA_PORT equ $6b
SPRITE_STATUS_SLOT_SELECT equ $303B
SPRITE_IMAGE_PORT equ $5b
SPRITE_INFO_PORT equ $57
;------------------------------------------------------------------------------

IFDEF testing
org $5800
block 32*24, $38 ; default ULA attributes
org $6000
ELSE
org $2000
ENDIF

start
ld hl,$0000
ld de,$4000
ld bc,$800
call TransferDMA ; copy some random data to the screen pointing
; to ROM for now, for the purpose of showing
; how to do a DMA copy.
ld a,0 ; sprite image number we want to update
ld bc,SPRITE_STATUS_SLOT_SELECT
out (c),a ; set the sprite image number
ld bc,1*256 ; number to transfer (1)
ld hl,testsprite ; from
call TransferDMASprite ; transfer to sprite ram

nextreg 21,1 ; turn sprite on. for more info on this check
; out https://www.specnext.com/tbblue-io-port-system/
ld de,0
ld (xpos),de ; set initial X position ( doesn't need it for
; this demo, but if you run the .loop again it
; will continue from where it was
ld a,$20
ld (ypos),a ; set initial Y position

.loop
ld a,0 ; sprite number we want to position
ld bc,SPRITE_STATUS_SLOT_SELECT
out (c),a
ld de,(xpos)
ld hl,(ypos) ; ignores H so doing this rather than
; ld a,(ypos):ld l,a
ld bc,(image) ; not flipped or palette shifted
call SetSprite

halt

ld de,(xpos)
inc de
ld (xpos),de
ld a,d
cp $01
jr nz,.loop ; if high byte of xpos is not 1 (right of
; screen )
ld a,e
cp $20+1
jr nz,.loop ; if low byte is not $21 just off the right of
; the screen, $20 is off screen but as the
; INC DE is just above and not updated sprite
; after it, it needs to be $21
xor a
ret ; return back to basic with OK

xpos dw 0 ; x position
ypos db 0 ; y position
; these next two BITS and IMAGE are swapped
; as bits needs to go into B register
image db 0+$80 ; use image 0 (for the image we transfered)
; +$80 to set the sprite to active
bits db 0 ; not flipped or palette shifted

c1 = %11100000
c2 = %11000000
c3 = %10100000
c4 = %10000000
c5 = %01100000
c6 = %01000000
c7 = %00100000
c8 = %00000000

testsprite
db c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1
db c1,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c1
db c1,c2,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c2,c1
db c1,c2,c3,c4,c4,c4,c4,c4,c4,c4,c4,c4,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c5,c5,c5,c5,c5,c5,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c6,c6,c6,c6,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c7,c7,c7,c7,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c7,c8,c8,c7,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c7,c8,c8,c7,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c7,c7,c7,c7,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c6,c6,c6,c6,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c5,c5,c5,c5,c5,c5,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c4,c4,c4,c4,c4,c4,c4,c4,c4,c3,c2,c1
db c1,c2,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c2,c1
db c1,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c1
db c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1

;-------------------------------------------------
; de = X
; l = Y
; b = bits
; c = sprite image
SetSprite
push bc
ld bc,SPRITE_INFO_PORT
out (c),e ; Xpos
out (c),l ; Ypos
pop hl
ld a,d
and 1
or h
out (c),a
ld a,l:or $80
out (c),a ; image
ret

;--------------------------------
; hl = source
; de = destination
; bc = length
;--------------------------------
TransferDMA
di
ld (DMASource),hl
ld (DMADest),de
ld (DMALength),bc
ld hl,DMACode
ld b,DMACode_Len
ld c,ZXN_DMA_PORT
otir
ei
ret

DMACode db DMA_DISABLE
db %01111101 ; R0-Transfer mode, A -> B, write adress
; + block length
DMASource dw 0 ; R0-Port A, Start address
; (source address)
DMALength dw 0 ; R0-Block length (length in bytes)
db %01010100 ; R1-write A time byte, increment, to
; memory, bitmask
db %00000010 ; 2t
db %01010000 ; R2-write B time byte, increment, to
; memory, bitmask
db %00000010 ; R2-Cycle length port B
db DMA_CONTINUOUS ; R4-Continuous mode (use this for block
; transfer), write dest adress
DMADest dw 0 ; R4-Dest address (destination address)
db %10000010 ; R5-Restart on end of block, RDY active
; LOW
db DMA_LOAD ; R6-Load
db DMA_ENABLE ; R6-Enable DMA

DMACode_Len equ $-DMACode

;------------------------------------------------------------------------------
; hl = source
; bc = length
; set port to write to with TBBLUE_REGISTER_SELECT
; prior to call
;------------------------------------------------------------------------------
TransferDMAPort
di
ld (DMASourceP),hl
ld (DMALengthP),bc
ld hl,DMACodeP
ld b,DMACode_LenP
ld c,ZXN_DMA_PORT
otir
ei
ret

DMACodeP db DMA_DISABLE
db %01111101 ; R0-Transfer mode, A -> B, write adress
; + block length
DMASourceP dw 0 ; R0-Port A, Start address (source address)
DMALengthP dw 0 ; R0-Block length (length in bytes)
db %01010100 ; R1-read A time byte, increment, to
; memory, bitmask
db %00000010 ; R1-Cycle length port A
db %01101000 ; R2-write B time byte, increment, to
; memory, bitmask
db %00000010 ; R2-Cycle length port B
db %10101101 ; R4-Continuous mode (use this for block
; transfer), write dest adress
dw $253b ; R4-Dest address (destination address)
db %10000010 ; R5-Restart on end of block, RDY active
; LOW
db DMA_LOAD ; R6-Load
db DMA_ENABLE ; R6-Enable DMA

DMACode_LenP equ $-DMACodeP
;------------------------------------------------------------------------------
; hl = source
; bc = length
;------------------------------------------------------------------------------
TransferDMASprite
di
ld (DMASourceS),hl
ld (DMALengthS),bc
ld hl,DMACodeS
ld b,DMACode_LenS
ld c,ZXN_DMA_PORT
otir
ei
ret

DMACodeS db DMA_DISABLE
db %01111101 ; R0-Transfer mode, A -> B, write adress
; + block length
DMASourceS dw 0 ; R0-Port A, Start address (source address)
DMALengthS dw 0 ; R0-Block length (length in bytes)
db %01010100 ; R1-read A time byte, increment, to
; memory, bitmask
db %00000010 ; R1-Cycle length port A
db %01101000 ; R2-write B time byte, increment, to
; memory, bitmask
db %00000010 ; R2-Cycle length port B
db %10101101 ; R4-Continuous mode (use this for block
; transfer), write dest adress
dw SPRITE_IMAGE_PORT ; R4-Dest address (destination address)
db %10000010 ; R5-Restart on end of block, RDY active
; LOW
db DMA_LOAD ; R6-Load
db DMA_ENABLE ; R6-Enable DMA
DMACode_LenS equ $-DMACodeS
;------------------------------------------------------------------------------
; de = dest, a = fill value, bc = lenth
;------------------------------------------------------------------------------
DMAFill
di
ld (FillValue),a
ld (DMACDest),de
ld (DMACLength),bc
ld hl,DMACCode
ld b,DMACCode_Len
ld c,ZXN_DMA_PORT
otir
ei
ret

FillValue db 22
DMACCode db DMA_DISABLE
db %01111101
DMACSource dw FillValue
DMACLength dw 0
db %00100100,%00010000,%10101101
DMACDest dw 0
db DMA_LOAD,DMA_ENABLE
DMACCode_Len equ $-DMACCode

;------------------------------------------------------------------------------
; End of file
;------------------------------------------------------------------------------

IFDEF testing
savenex open "DMAtest.nex", start, $FF00
savenex bank 5
ELSE
fin
savebin "DMATEST",start,fin-start
ENDIF
</pre>

Based on original text by: Allen Albright & Mike Dailly with input by Jim Bagley, Lyndon J Sharp and Phoebus R. Dokos

== Technical details (core 3.1.3+) ==

The Zilog/zxnDMA mode is now selected by using the particular I/O port number ({{PortNo|$xx6B}} for zxnDMA mode, {{PortNo|$xx0B}} for Zilog mode). The bit 6 in {{NextRegNo|$06}} is not DMA related any more and will be reused for something different.

The "counter" RR1-RR2 read back after transfer has correct byte order since core 3.1.4.

Other differences described below in "3.0.5" remains (but from practical point of view the Zilog DMA emulation in 3.1.4 is near-perfect, all the remaining differences are very minor).

== Technical details (core 3.0.5) ==

=== Zilog DMA compatibility mode ===
In Zilog DMA compatibility mode (bit 6 of {{NextRegNo|$06}}) the zxnDMA will mostly work as expected, but there are few differences in behaviour which may eventually throw off some rare SW, here is the list of the known differences (most of them describe also how the zxnDMA mode works):

The LOAD command must be issued with correct transfer direction, loading addresses in opposite direction and flipping direction afterward will mismatch the source/destination address data (Zilog/UA858D DMA chips are also sensitive to direction flip after LOAD, but the resulting transfer quirks in different way, reading source data byte after write, offsetting whole transfer by one and damaging start/end of sequence).
(does apply also to zxnDMA mode)

The LOAD command will NOT destroy the already issued "Initialize Read Sequence" - this is how even the original Zilog documentation describes the DMA chip operation, but the real Zilog DMA and UA858D (clone chip) both destroy read sequence upon LOAD command (zxnDMA is better).
(does apply also to zxnDMA mode)

The content of registers read back after finished transfer differs: the counter has swapped LSB with MSB byte, and both addresses will be adjusted length+1 times (Zilog/UA858D will return destination address adjusted only length-many times).
(does apply also to zxnDMA mode, except addresses are adjusted only "length" times of course, counter has still swapped bytes)

<del>Any read of zxnDMA port without pending read request (commands "Read Status Byte" or "Initialize Read Sequence") will return status byte (Zilog will return random value vaguely similar to status byte, but incorrect, UA858D will return zero).
(does apply also to zxnDMA mode)</del> 
2026-03-30: any read of zxnDMA port without pending read request will return next byte in read sequence, the default read mask is 0x7F after power on (based on reading the VHDL, needs to verify with HW).

<del>Status byte doesn't have bit 0 set (the "T" bit in description above).
(does apply also to zxnDMA mode)</del> 
2026-03-30: going by [https://gitlab.com/SpectrumNext/ZX%20Spectrum%20Next%20FPGA/-/blob/master/cores/zxnext/src/device/dma.vhd?ref%20type=heads VHDL source] this seems to be now fixed, needs to verify with HW and guess in which version of core this was fixed

The command 0xBB setting read mask will cause implicit 0xA7 Initialize Read Sequence.
(does apply also to zxnDMA mode)

The command 0xA7 does initialize read sequence even when the previous sequence was only partially read (ZX Next FPGA implementation for both zxnDMA and Zilog-DMA) and there were more bytes pending. According to Zilog documentation the original Zilog DMA is claimed to ignore 0xA7 command in such case. Needs verification on HW to be fully confirmed, especially the original Zilog chip, this looks a bit unlikely, it would make lot more sense to abort current sequence and reset it.

Be aware that both custom timing cycles count, and prescalar values are preserved in zxnDMA even when future write to WR1/WR2 does skip these particular bytes. To reset prescalar or cycles timing, write explicitly zero into prescalar register or use commands reset/reset-port-timing.
(does apply also to zxnDMA mode, the prescalar works only in zxnDMA mode)

The destination port address is LOAD-ed even when it is "fixed" type (Contrary to Zilog DMA, which requires you to load such port as "source", flip the direction after and re-LOAD again with correct direction. UA858D chip does also load destination port address in any case, just like zxnDMA).
(does apply also to zxnDMA mode)

=== zxnDMA mode vs Zilog mode ===

In zxnDMA mode length of transfer is equal to the length written to WR0 register, port addresses are adjusted also only length-times.

Prescalar value will affect speed of transfer (use zero to switch prescalar off) (in burst mode during the extra idle time the CPU receives control back and can execute further instructions, in continuous mode the transfer will keep blocking CPU even when "slow" transfer is being done).

DMA

2026-03-30T12:16:56Z

Ped7g: formatting + note

== Overview ==
The ZX Spectrum Next DMA (zxnDMA) is a single channel DMA device that implements a subset of the Z80 DMA functionality. The subset is large enough to be compatible with common uses of the similar Datagear interface available for standard ZX Spectrum computers and compatibles. It also adds a burst mode capability that can deliver audio at programmable sample rates to the DAC device.

== Accessing the zxnDMA ==
<del>The zxnDMA is mapped to a single Read/Write IO Port 0x6B which is the same one used by the Datagear but unlike the Datagear it doesn't also map itself to a second port 0x0B similar to the MB-02 interface.</del>

Since core 3.1.2 the zxnDMA is mapped to {{PortNo|$xx6B}}, and Zilog-DMA mode is mapped to {{PortNo|$xx0B}}.

== Description ==
The normal Z80 DMA (Z8410) chip is a pipelined device and because of that it has numerous off-by-one idiosyncrasies and requirements on the order that certain commands should be carried out. These issues are not duplicated in the zxnDMA. You can continue to program the zxnDMA as if it is were a Z8410 DMA device but it can also be programmed in a simpler manner.

The single channel of the zxnDMA chip consists of two ports named A and B. Transfers can occur in either direction between ports A and B, each port can describe a target in memory or IO, and each can be configured to autoincrement, autodecrement or stay fixed after a byte is transferred.

A special feature of the zxnDMA can force each byte transfer to take a fixed amount of time so that the zxnDMA can be used to deliver sampled audio.

== Modes of Operation ==
The zxnDMA can operate in a z80-DMA compatibility mode.

'''REMOVED in core 3.1.2:''' <del>The z80-DMA compatibility mode is selected by setting bit 6 of nextreg 0x06. In this mode, all transfers involve length+1 bytes which is the same behaviour as the z80-DMA chip. In zxn-DMA mode, the transfer length is exactly the number of bytes programmed. This mode is mainly present to accommodate existing spectrum software that uses the z80-DMA and for cp/m programs that may have a z80-DMA option.</del>

'''Since core 3.1.2:''' the DMA mode is selected by port number, the {{PortNo|$xx6B}} works in zxnDMA mode, {{PortNo|$xx0B}} works in Zilog mode. The bit 6 in {{NextRegNo|$06}} is not DMA related any more and will be reused for something different.

The zxnDMA can also operate in either burst or continuous modes.

Continuous mode means the DMA chip runs to completion without allowing the CPU to run. When the CPU starts the DMA, the DMA operation will complete before the CPU executes its next instruction.

Burst mode nominally means the DMA lets the CPU run if either port is not ready. This condition can't happen in the zxnDMA chip except when operated in the special fixed time transfer mode. In this mode, the zxnDMA will let the CPU run while it waits for the fixed time to expire between bytes transferred.

Note that there is no byte transfer mode as in the Z80 DMA.

== Programming the zxnDMA ==
Like the Z80 DMA chip, the zxnDMA has seven write registers named WR0-WR6 that control the device. Each register WR0-WR6 can have zero or more parameters associated with it.

In a first write to the zxnDMA port, the write value is compared against a bitmask to determine which of the WR0-WR6 is the target. Remaining bits in the written value can contain data as well as a list of associated parameter bits. The parameter bits determine if further writes are expected to deliver parameter values. If there are multiple parameter bits set, the expected order of parameter values written is determined by parameter bit position from right to left (bit 0 through bit 7). Once all parameters are written, the zxnDMA again expects a regular register write selecting WR0-WR6.

The table below describes the registers and the bitmask required to select them on the zxnDMA.

{|
! Register Group
! Register Function Description
! Bitmask
! Notes
|-
| WR0
| Direction, Operation and Port A configuration
| <pre>0XXXXXAA</pre>
| AA must NOT be 00
|-
| WR1
| Port A configuration
| <pre>0XXXX100</pre>
|
|-
| WR2
| Port B configuration
| <pre>0XXXX000</pre>
|
|-
| WR3
| Activation
| <pre>1XXXXX00</pre>
| It’s best to use WR6
|-
| WR4
| Port B, Timing and Interrupt configuration
| <pre>1XXXXX01</pre>
|
|-
| WR5
| Ready and Stop configuration
| <pre>10XXX010</pre>
|
|-
| WR6
| Command Register
| <pre>1XXXXX11</pre>
|
|}

== zxnDMA Registers ==
These are described below following the same convention used by Zilog for its DMA chip:

=== WR0 – Write Register Group 0 ===

<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
0 | | | | | | |
| | | | | 0 0 Do not use
| | | | | 0 1 Transfer (Prefer this for Z80 DMA compatibility)
| | | | | 1 0 Do not use (Behaves like Transfer, Search on Z80 DMA)
| | | | |
| | | | | 1 1 Do not use (Behaves like Transfer, Search/Transfer on Z80 DMA)
| | | | |
| | | | 0 = Port B -> Port A (Byte transfer direction)
| | | | 1 = Port A -> Port B
| | | V
D7 D6 D5 D4 D3 D2 D1 D0 PORT A STARTING ADDRESS (LOW BYTE)
| | V
D7 D6 D5 D4 D3 D2 D1 D0 PORT A STARTING ADDRESS (HIGH BYTE)
| V
D7 D6 D5 D4 D3 D2 D1 D0 BLOCK LENGTH (LOW BYTE)
V
D7 D6 D5 D4 D3 D2 D1 D0 BLOCK LENGTH (HIGH BYTE)</pre>

Several registers are accessible from WR0. The first write to WR0 is to the base register byte. Bits D6:D3 are optionally set to indicate that associated registers in this group will be written next. The order the writes come in are from D3 to D6 (right to left). For example, if bits D6 and D3 are set, the next two writes will be directed to PORT A STARTING ADDRESS LOW followed by BLOCK LENGTH HIGH.

=== WR1 – Write Register Group 1 ===

<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
0 | | | | 1 0 0
| | | |
| | | 0 = Port A is memory
| | | 1 = Port A is IO
| | |
| 0 0 = Port A address decrements
| 0 1 = Port A address increments
| 1 0 = Port A address is fixed
| 1 1 = Port A address is fixed
|
V
D7 D6 D5 D4 D3 D2 D1 D0 PORT A VARIABLE TIMING BYTE
0 0 0 0 0 0 | |
0 0 = Cycle Length = 4
0 1 = Cycle Length = 3
1 0 = Cycle Length = 2
1 1 = Do not use
</pre>

The cycle length is the number of cycles used in a read or write operation. The first cycle asserts signals and the last cycle releases them. There is no half cycle timing for the control signals.

=== WR2 – Write Register Group 2 ===

<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
0 | | | | 0 0 0
| | | |
| | | 0 = Port B is memory
| | | 1 = Port B is IO
| | |
| 0 0 = Port B address decrements
| 0 1 = Port B address increments
| 1 0 = Port B address is fixed
| 1 1 = Port B address is fixed
|
V
D7 D6 D5 D4 D3 D2 D1 D0 PORT B VARIABLE TIMING BYTE
0 0 | 0 0 0 | |
| 0 0 = Cycle Length = 4
| 0 1 = Cycle Length = 3
| 1 0 = Cycle Length = 2
| 1 1 = Do not use
|
V
D7 D6 D5 D4 D3 D2 D1 D0 ZXN PRESCALAR (FIXED TIME TRANSFER)
</pre>
The ZXN PRESCALAR is a feature of the zxnDMA implementation. If non-zero, a delay will be inserted after each byte is transferred such that the total time needed for each transfer is determined by the prescalar. This works in both the continuous mode and the burst mode. If the DMA is operated in burst mode, the DMA will give up any waiting time to the CPU so that the CPU can run while the DMA is idle.

The rate of transfer is given by the formula “Frate = 875kHz / prescalar” or, rearranged, “prescalar = 875kHz / Frate”. The formula is framed in terms of a sample rate (Frate) but Frate can be inverted to set a transfer time for each byte instead. The 875kHz constant is a nominal value assuming a 28MHz system clock; the system clock actually varies from this depending on the video timing selected by the user (HDMI, VGA0-6) so for complete accuracy the constant should be prorated according to documentation for nextreg 0x11.

In a DMA audio setting, selecting a sample rate of 16kHz would mean setting the prescalar value to 55. This sample period is constant across changes in CPU speed.

=== WR3 – Write Register Group 3 ===

<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
1 | 0 0 0 0 0 0
|
1 = DMA Enable
</pre>
The Z80 DMA defines more fields but they are ignored by the zxnDMA. The two other registers defined by the Z80 DMA in this group on D4 and D3 are implemented by the zxnDMA but they do nothing.

It is preferred to start the DMA by writing an 'Enable DMA' command to WR6.

=== WR4 – Write Register Group 4 ===

<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
1 | | 0 | | 0 1
| | | |
0 0 = Do not use (Behaves like Continuous mode, Byte mode on Z80 DMA)
0 1 = Continuous mode
1 0 = Burst mode
1 1 = Do not use
| |
| V
D7 D6 D5 D4 D3 D2 D1 D0 PORT B STARTING ADDRESS (LOW BYTE)
|
V
D7 D6 D5 D4 D3 D2 D1 D0 PORT B STARTING ADDRESS (HIGH BYTE)
</pre>
The Z80 DMA defines three more registers in this group through D4 that define interrupt behaviour. Interrups and pulse generation are not implemented in the zxnDMA nor are these registers available for writing.

=== WR5 – Write Register Group 5 ===
<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
1 0 | | 0 0 1 0
| |
| 0 = /ce only
| 1 = /ce & /wait multiplexed
|
0 = Stop on end of block
1 = Auto restart on end of block
</pre>
The /ce & /wait mode is implemented in the zxnDMA but is not currently used. This mode has an external device using the DMA's /ce pin to insert wait states during the DMA's transfer.

The auto restart feature causes the DMA to automatically reload its source and destination addresses and reset its byte counter to zero to repeat the last transfer when a previous one is finished.

=== WR6 – Command Register ===
<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
1 ? ? ? ? ? 1 1
| | | | |
1 0 0 0 0 = 0xC3 = Reset
1 0 0 0 1 = 0xC7 = Reset Port A Timing
1 0 0 1 0 = 0xCB = Reset Port B Timing
0 1 1 0 0 = 0xB3 = Force Ready (irrelevant for zxnDMA)
0 1 1 1 1 = 0xBF = Read Status Byte
0 0 0 1 0 = 0x8B = Reinitialize Status Byte
0 1 0 0 1 = 0xA7 = Initialize Read Sequence
1 0 0 1 1 = 0xCF = Load
1 0 1 0 0 = 0xD3 = Continue
0 0 0 0 1 = 0x87 = Enable DMA
0 0 0 0 0 = 0x83 = Disable DMA
+-- 0 1 1 1 0 = 0xBB = Read Mask Follows
|
D7 D6 D5 D4 D3 D2 D1 D0 READ MASK
0 | | | | | | |
| | | | | | V
D7 D6 D5 D4 D3 D2 D1 D0 Status Byte
| | | | | |
| | | | | V
D7 D6 D5 D4 D3 D2 D1 D0 Byte Counter Low ("High" with core 3.0.5 = bug in core)
| | | | |
| | | | V
D7 D6 D5 D4 D3 D2 D1 D0 Byte Counter High ("Low" with core 3.0.5 = bug in core)
| | | |
| | | V
D7 D6 D5 D4 D3 D2 D1 D0 Port A Address Low
| | |
| | V
D7 D6 D5 D4 D3 D2 D1 D0 Port A Address High
| |
| V
D7 D6 D5 D4 D3 D2 D1 D0 Port B Address Low
|
V
D7 D6 D5 D4 D3 D2 D1 D0 Port B Address High
</pre>
Unimplemented Z80 DMA commands are ignored.

Prior to starting the DMA transfer, a LOAD command must be issued to copy the Port A and Port B addresses into the DMA's internal pointers. Then an 'Enable DMA' command is issued to start the DMA. The last LOAD command before ENABLE must be done with correct transfer direction set.

The 'Continue' command resets the DMA's byte counter so that a following 'Enable DMA' allows the DMA to repeat the last transfer but using the current internal address pointers. I.e. it continues from where the last copy operation left off.

Reset and Reset Port A/B Timing commands on zxnDMA do reset also prescalar value.

Registers can be read via an IO read from the DMA port after setting the read mask. (At power up the read mask is set to 0x7f). Register values are the current internal DMA counter values. So 'Port Address A Low' is the lower 8-bits of Port A’s next transfer address. Once the end of the read mask is reached, further reads loop around to the first one.

The format of the DMA status byte is as follows:

<pre>00E1101T</pre>

E is set to 0 if the total block length has been transferred at least once.

T is set to 1 if at least one byte has been transferred.

== Operating speed ==
The zxnDMA operates at the same speed as the CPU, that is 3.5MHz, 7MHz, 14MHz or 28Mhz. This is a contended clock that is modified by the ULA and the auto-slowdown by [[Layer 2|Layer2]] (which only occurred in Next core's 1 and 2, the limitation was lifted in core 3.0).

The (pre-core 3.0) auto-slowdown occurs without user intervention if speed exceeds 7Mhz and the active Layer2 display is being generated (higher speed operation resumes when the active Layer2 display is not generated). Programmers do NOT need to account for speed differences regarding DMA transfers as this happens automatically.

Because of this, the cycle lengths for Ports A and B can be set to their minimum values without ill effects. The cycle lengths specified for Ports A and B are intended to selectively slow down read or write cycles for hardware that cannot operate at the DMA's full speed.

== The DMA and Interrupts ==
The zxnDMA cannot currently generate [[Interrupts|interrupts]].

The other side of this is that while the DMA controls the bus, the Z80 cannot respond to interrupts. On the Z80, the NMI interrupt is edge triggered so if an NMI occurs the fact that it occurred is stored internally in the Z80 so that it will respond when it is woken up. On the other hand, maskable interrupts are level triggered. That is, the Z80 must be active to regularly sample the /INT line to determine if a maskable interrupt is occurring. On the Spectrum and the ZX Next, the ULA (and line interrupt) are only asserted for a fixed amount of time ~30 cycles at 3.5MHz. If the DMA is executing a transfer while the interrupt is asserted, the CPU will not be able to see this and it will most likely miss the interrupt. In burst mode, with large-enough prescalar value, the CPU will never miss these interrupts, although this may change if multiple channels are implemented.

'''Since core 3.1.8:''' the ability to interrupt DMA transfers was added, this is opt-in mechanism and must be configured through {{NextRegNo|$CC}}, {{NextRegNo|$CD}} and {{NextRegNo|$CE}} and requires "hw im2 mode" interrupts being set. Because interrupts are only sampled at the end of an instruction by the Z80, each time the dma is interrupted one instruction of progress is made in the main program (before the interrupt handler code is entered).

This means after starting the DMA transfer with last `out` instruction you must follow it by N instructions which don't affect the transfer (don't remap source data memory, select different sprite/copper/... index if that's target of transfer, don't write anything to zxnDMA port), either doing different kind of work with CPU or adding block of `nop` instructions, to have non-interfering block of code available to fire N interrupts during transfer. Chose N to accommodate for worst case scenario of how many times you will interrupt the running DMA transfer. Or you can read state of zxnDMA to see if transfer did finish, but (IMHO by ped7g) in most cases it will be performance-cheaper to just add block of nop instructions or do other work on CPU not interfering with transfer.

== Programming examples ==
A simple way to program the DMA is to walk down the list of registers WR0-WR5, sending desired settings to each. Then start the DMA by sending a LOAD command followed by an ENABLE_DMA command to WR6. Once more familiar with the DMA, you will discover that the amount of information sent can be reduced to what changes between transfers.

=== Assembly ===
Short example program to DMA memory to the screen, then DMA a sprite image from memory to sprite RAM, and then showing said sprite scrolling across the screen.

<pre>;------------------------------------------------------------------------------
; sjasmplus extra options to enable Z80N, stricter syntax and Next device
opt --zxnext --syntax=abf : device zxspectrumnext
;------------------------------------------------------------------------------
; DEFINE testing ; uncomment to produce NEX file (instead of DOT)
;------------------------------------------------------------------------------
; DMA (Register 6)
;
;------------------------------------------------------------------------------
;zxnDMA programming example
;------------------------------------------------------------------------------
;(c) Jim Bagley
;------------------------------------------------------------------------------
DMA_RESET equ $c3
DMA_RESET_PORT_A_TIMING equ $c7
DMA_RESET_PORT_B_TIMING equ $cb
DMA_LOAD equ $cf ; %11001111
DMA_CONTINUE equ $d3
DMA_DISABLE_INTERUPTS equ $af
DMA_ENABLE_INTERUPTS equ $ab
DMA_RESET_DISABLE_INTERUPTS equ $a3
DMA_ENABLE_AFTER_RETI equ $b7
DMA_READ_STATUS_BYTE equ $bf
DMA_REINIT_STATUS_BYTE equ $8b
DMA_START_READ_SEQUENCE equ $a7
DMA_FORCE_READY equ $b3
DMA_DISABLE equ $83
DMA_ENABLE equ $87
DMA_WRITE_REGISTER_COMMAND equ $bb
DMA_BURST equ %11001101
DMA_CONTINUOUS equ %10101101
ZXN_DMA_PORT equ $6b
SPRITE_STATUS_SLOT_SELECT equ $303B
SPRITE_IMAGE_PORT equ $5b
SPRITE_INFO_PORT equ $57
;------------------------------------------------------------------------------

IFDEF testing
org $5800
block 32*24, $38 ; default ULA attributes
org $6000
ELSE
org $2000
ENDIF

start
ld hl,$0000
ld de,$4000
ld bc,$800
call TransferDMA ; copy some random data to the screen pointing
; to ROM for now, for the purpose of showing
; how to do a DMA copy.
ld a,0 ; sprite image number we want to update
ld bc,SPRITE_STATUS_SLOT_SELECT
out (c),a ; set the sprite image number
ld bc,1*256 ; number to transfer (1)
ld hl,testsprite ; from
call TransferDMASprite ; transfer to sprite ram

nextreg 21,1 ; turn sprite on. for more info on this check
; out https://www.specnext.com/tbblue-io-port-system/
ld de,0
ld (xpos),de ; set initial X position ( doesn't need it for
; this demo, but if you run the .loop again it
; will continue from where it was
ld a,$20
ld (ypos),a ; set initial Y position

.loop
ld a,0 ; sprite number we want to position
ld bc,SPRITE_STATUS_SLOT_SELECT
out (c),a
ld de,(xpos)
ld hl,(ypos) ; ignores H so doing this rather than
; ld a,(ypos):ld l,a
ld bc,(image) ; not flipped or palette shifted
call SetSprite

halt

ld de,(xpos)
inc de
ld (xpos),de
ld a,d
cp $01
jr nz,.loop ; if high byte of xpos is not 1 (right of
; screen )
ld a,e
cp $20+1
jr nz,.loop ; if low byte is not $21 just off the right of
; the screen, $20 is off screen but as the
; INC DE is just above and not updated sprite
; after it, it needs to be $21
xor a
ret ; return back to basic with OK

xpos dw 0 ; x position
ypos db 0 ; y position
; these next two BITS and IMAGE are swapped
; as bits needs to go into B register
image db 0+$80 ; use image 0 (for the image we transfered)
; +$80 to set the sprite to active
bits db 0 ; not flipped or palette shifted

c1 = %11100000
c2 = %11000000
c3 = %10100000
c4 = %10000000
c5 = %01100000
c6 = %01000000
c7 = %00100000
c8 = %00000000

testsprite
db c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1
db c1,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c1
db c1,c2,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c2,c1
db c1,c2,c3,c4,c4,c4,c4,c4,c4,c4,c4,c4,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c5,c5,c5,c5,c5,c5,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c6,c6,c6,c6,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c7,c7,c7,c7,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c7,c8,c8,c7,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c7,c8,c8,c7,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c7,c7,c7,c7,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c6,c6,c6,c6,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c5,c5,c5,c5,c5,c5,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c4,c4,c4,c4,c4,c4,c4,c4,c4,c3,c2,c1
db c1,c2,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c2,c1
db c1,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c1
db c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1

;-------------------------------------------------
; de = X
; l = Y
; b = bits
; c = sprite image
SetSprite
push bc
ld bc,SPRITE_INFO_PORT
out (c),e ; Xpos
out (c),l ; Ypos
pop hl
ld a,d
and 1
or h
out (c),a
ld a,l:or $80
out (c),a ; image
ret

;--------------------------------
; hl = source
; de = destination
; bc = length
;--------------------------------
TransferDMA
di
ld (DMASource),hl
ld (DMADest),de
ld (DMALength),bc
ld hl,DMACode
ld b,DMACode_Len
ld c,ZXN_DMA_PORT
otir
ei
ret

DMACode db DMA_DISABLE
db %01111101 ; R0-Transfer mode, A -> B, write adress
; + block length
DMASource dw 0 ; R0-Port A, Start address
; (source address)
DMALength dw 0 ; R0-Block length (length in bytes)
db %01010100 ; R1-write A time byte, increment, to
; memory, bitmask
db %00000010 ; 2t
db %01010000 ; R2-write B time byte, increment, to
; memory, bitmask
db %00000010 ; R2-Cycle length port B
db DMA_CONTINUOUS ; R4-Continuous mode (use this for block
; transfer), write dest adress
DMADest dw 0 ; R4-Dest address (destination address)
db %10000010 ; R5-Restart on end of block, RDY active
; LOW
db DMA_LOAD ; R6-Load
db DMA_ENABLE ; R6-Enable DMA

DMACode_Len equ $-DMACode

;------------------------------------------------------------------------------
; hl = source
; bc = length
; set port to write to with TBBLUE_REGISTER_SELECT
; prior to call
;------------------------------------------------------------------------------
TransferDMAPort
di
ld (DMASourceP),hl
ld (DMALengthP),bc
ld hl,DMACodeP
ld b,DMACode_LenP
ld c,ZXN_DMA_PORT
otir
ei
ret

DMACodeP db DMA_DISABLE
db %01111101 ; R0-Transfer mode, A -> B, write adress
; + block length
DMASourceP dw 0 ; R0-Port A, Start address (source address)
DMALengthP dw 0 ; R0-Block length (length in bytes)
db %01010100 ; R1-read A time byte, increment, to
; memory, bitmask
db %00000010 ; R1-Cycle length port A
db %01101000 ; R2-write B time byte, increment, to
; memory, bitmask
db %00000010 ; R2-Cycle length port B
db %10101101 ; R4-Continuous mode (use this for block
; transfer), write dest adress
dw $253b ; R4-Dest address (destination address)
db %10000010 ; R5-Restart on end of block, RDY active
; LOW
db DMA_LOAD ; R6-Load
db DMA_ENABLE ; R6-Enable DMA

DMACode_LenP equ $-DMACodeP
;------------------------------------------------------------------------------
; hl = source
; bc = length
;------------------------------------------------------------------------------
TransferDMASprite
di
ld (DMASourceS),hl
ld (DMALengthS),bc
ld hl,DMACodeS
ld b,DMACode_LenS
ld c,ZXN_DMA_PORT
otir
ei
ret

DMACodeS db DMA_DISABLE
db %01111101 ; R0-Transfer mode, A -> B, write adress
; + block length
DMASourceS dw 0 ; R0-Port A, Start address (source address)
DMALengthS dw 0 ; R0-Block length (length in bytes)
db %01010100 ; R1-read A time byte, increment, to
; memory, bitmask
db %00000010 ; R1-Cycle length port A
db %01101000 ; R2-write B time byte, increment, to
; memory, bitmask
db %00000010 ; R2-Cycle length port B
db %10101101 ; R4-Continuous mode (use this for block
; transfer), write dest adress
dw SPRITE_IMAGE_PORT ; R4-Dest address (destination address)
db %10000010 ; R5-Restart on end of block, RDY active
; LOW
db DMA_LOAD ; R6-Load
db DMA_ENABLE ; R6-Enable DMA
DMACode_LenS equ $-DMACodeS
;------------------------------------------------------------------------------
; de = dest, a = fill value, bc = lenth
;------------------------------------------------------------------------------
DMAFill
di
ld (FillValue),a
ld (DMACDest),de
ld (DMACLength),bc
ld hl,DMACCode
ld b,DMACCode_Len
ld c,ZXN_DMA_PORT
otir
ei
ret

FillValue db 22
DMACCode db DMA_DISABLE
db %01111101
DMACSource dw FillValue
DMACLength dw 0
db %00100100,%00010000,%10101101
DMACDest dw 0
db DMA_LOAD,DMA_ENABLE
DMACCode_Len equ $-DMACCode

;------------------------------------------------------------------------------
; End of file
;------------------------------------------------------------------------------

IFDEF testing
savenex open "DMAtest.nex", start, $FF00
savenex bank 5
ELSE
fin
savebin "DMATEST",start,fin-start
ENDIF
</pre>

Based on original text by: Allen Albright & Mike Dailly with input by Jim Bagley, Lyndon J Sharp and Phoebus R. Dokos

== Technical details (core 3.1.3+) ==

The Zilog/zxnDMA mode is now selected by using the particular I/O port number ({{PortNo|$xx6B}} for zxnDMA mode, {{PortNo|$xx0B}} for Zilog mode). The bit 6 in {{NextRegNo|$06}} is not DMA related any more and will be reused for something different.

The "counter" RR1-RR2 read back after transfer has correct byte order since core 3.1.4.

Other differences described below in "3.0.5" remains (but from practical point of view the Zilog DMA emulation in 3.1.4 is near-perfect, all the remaining differences are very minor).

== Technical details (core 3.0.5) ==

=== Zilog DMA compatibility mode ===
In Zilog DMA compatibility mode (bit 6 of {{NextRegNo|$06}}) the zxnDMA will mostly work as expected, but there are few differences in behaviour which may eventually throw off some rare SW, here is the list of the known differences (most of them describe also how the zxnDMA mode works):

The LOAD command must be issued with correct transfer direction, loading addresses in opposite direction and flipping direction afterward will mismatch the source/destination address data (Zilog/UA858D DMA chips are also sensitive to direction flip after LOAD, but the resulting transfer quirks in different way, reading source data byte after write, offsetting whole transfer by one and damaging start/end of sequence).
(does apply also to zxnDMA mode)

The LOAD command will NOT destroy the already issued "Initialize Read Sequence" - this is how even the original Zilog documentation describes the DMA chip operation, but the real Zilog DMA and UA858D (clone chip) both destroy read sequence upon LOAD command (zxnDMA is better).
(does apply also to zxnDMA mode)

The content of registers read back after finished transfer differs: the counter has swapped LSB with MSB byte, and both addresses will be adjusted length+1 times (Zilog/UA858D will return destination address adjusted only length-many times).
(does apply also to zxnDMA mode, except addresses are adjusted only "length" times of course, counter has still swapped bytes)

<del>Any read of zxnDMA port without pending read request (commands "Read Status Byte" or "Initialize Read Sequence") will return status byte (Zilog will return random value vaguely similar to status byte, but incorrect, UA858D will return zero).
(does apply also to zxnDMA mode)</del> 
2026-03-30: any read of zxnDMA port without pending read request will return next byte in read sequence, the default read mask is 0x7F after power on (based on reading the VHDL, needs to verify with HW).

<del>Status byte doesn't have bit 0 set (the "T" bit in description above).
(does apply also to zxnDMA mode)</del> 
2026-03-30: going by [https://gitlab.com/SpectrumNext/ZX%20Spectrum%20Next%20FPGA/-/blob/master/cores/zxnext/src/device/dma.vhd?ref%20type=heads VHDL source] this seems to be now fixed, needs to verify with HW and guess in which version of core this was fixed

The command 0xBB setting read mask will cause implicit 0xA7 Initialize Read Sequence.
(does apply also to zxnDMA mode)

Be aware that both custom timing cycles count, and prescalar values are preserved in zxnDMA even when future write to WR1/WR2 does skip these particular bytes. To reset prescalar or cycles timing, write explicitly zero into prescalar register or use commands reset/reset-port-timing.
(does apply also to zxnDMA mode, the prescalar works only in zxnDMA mode)

The destination port address is LOAD-ed even when it is "fixed" type (Contrary to Zilog DMA, which requires you to load such port as "source", flip the direction after and re-LOAD again with correct direction. UA858D chip does also load destination port address in any case, just like zxnDMA).
(does apply also to zxnDMA mode)

=== zxnDMA mode vs Zilog mode ===

In zxnDMA mode length of transfer is equal to the length written to WR0 register, port addresses are adjusted also only length-times.

Prescalar value will affect speed of transfer (use zero to switch prescalar off) (in burst mode during the extra idle time the CPU receives control back and can execute further instructions, in continuous mode the transfer will keep blocking CPU even when "slow" transfer is being done).

DMA

2026-03-30T12:14:20Z

Ped7g: adding more notes about reading-status of zxnDMA, figured out while reading VHDL and debugging Mike's mod player init.

== Overview ==
The ZX Spectrum Next DMA (zxnDMA) is a single channel DMA device that implements a subset of the Z80 DMA functionality. The subset is large enough to be compatible with common uses of the similar Datagear interface available for standard ZX Spectrum computers and compatibles. It also adds a burst mode capability that can deliver audio at programmable sample rates to the DAC device.

== Accessing the zxnDMA ==
<del>The zxnDMA is mapped to a single Read/Write IO Port 0x6B which is the same one used by the Datagear but unlike the Datagear it doesn't also map itself to a second port 0x0B similar to the MB-02 interface.</del>

Since core 3.1.2 the zxnDMA is mapped to {{PortNo|$xx6B}}, and Zilog-DMA mode is mapped to {{PortNo|$xx0B}}.

== Description ==
The normal Z80 DMA (Z8410) chip is a pipelined device and because of that it has numerous off-by-one idiosyncrasies and requirements on the order that certain commands should be carried out. These issues are not duplicated in the zxnDMA. You can continue to program the zxnDMA as if it is were a Z8410 DMA device but it can also be programmed in a simpler manner.

The single channel of the zxnDMA chip consists of two ports named A and B. Transfers can occur in either direction between ports A and B, each port can describe a target in memory or IO, and each can be configured to autoincrement, autodecrement or stay fixed after a byte is transferred.

A special feature of the zxnDMA can force each byte transfer to take a fixed amount of time so that the zxnDMA can be used to deliver sampled audio.

== Modes of Operation ==
The zxnDMA can operate in a z80-DMA compatibility mode.

'''REMOVED in core 3.1.2:''' <del>The z80-DMA compatibility mode is selected by setting bit 6 of nextreg 0x06. In this mode, all transfers involve length+1 bytes which is the same behaviour as the z80-DMA chip. In zxn-DMA mode, the transfer length is exactly the number of bytes programmed. This mode is mainly present to accommodate existing spectrum software that uses the z80-DMA and for cp/m programs that may have a z80-DMA option.</del>

'''Since core 3.1.2:''' the DMA mode is selected by port number, the {{PortNo|$xx6B}} works in zxnDMA mode, {{PortNo|$xx0B}} works in Zilog mode. The bit 6 in {{NextRegNo|$06}} is not DMA related any more and will be reused for something different.

The zxnDMA can also operate in either burst or continuous modes.

Continuous mode means the DMA chip runs to completion without allowing the CPU to run. When the CPU starts the DMA, the DMA operation will complete before the CPU executes its next instruction.

Burst mode nominally means the DMA lets the CPU run if either port is not ready. This condition can't happen in the zxnDMA chip except when operated in the special fixed time transfer mode. In this mode, the zxnDMA will let the CPU run while it waits for the fixed time to expire between bytes transferred.

Note that there is no byte transfer mode as in the Z80 DMA.

== Programming the zxnDMA ==
Like the Z80 DMA chip, the zxnDMA has seven write registers named WR0-WR6 that control the device. Each register WR0-WR6 can have zero or more parameters associated with it.

In a first write to the zxnDMA port, the write value is compared against a bitmask to determine which of the WR0-WR6 is the target. Remaining bits in the written value can contain data as well as a list of associated parameter bits. The parameter bits determine if further writes are expected to deliver parameter values. If there are multiple parameter bits set, the expected order of parameter values written is determined by parameter bit position from right to left (bit 0 through bit 7). Once all parameters are written, the zxnDMA again expects a regular register write selecting WR0-WR6.

The table below describes the registers and the bitmask required to select them on the zxnDMA.

{|
! Register Group
! Register Function Description
! Bitmask
! Notes
|-
| WR0
| Direction, Operation and Port A configuration
| <pre>0XXXXXAA</pre>
| AA must NOT be 00
|-
| WR1
| Port A configuration
| <pre>0XXXX100</pre>
|
|-
| WR2
| Port B configuration
| <pre>0XXXX000</pre>
|
|-
| WR3
| Activation
| <pre>1XXXXX00</pre>
| It’s best to use WR6
|-
| WR4
| Port B, Timing and Interrupt configuration
| <pre>1XXXXX01</pre>
|
|-
| WR5
| Ready and Stop configuration
| <pre>10XXX010</pre>
|
|-
| WR6
| Command Register
| <pre>1XXXXX11</pre>
|
|}

== zxnDMA Registers ==
These are described below following the same convention used by Zilog for its DMA chip:

=== WR0 – Write Register Group 0 ===

<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
0 | | | | | | |
| | | | | 0 0 Do not use
| | | | | 0 1 Transfer (Prefer this for Z80 DMA compatibility)
| | | | | 1 0 Do not use (Behaves like Transfer, Search on Z80 DMA)
| | | | |
| | | | | 1 1 Do not use (Behaves like Transfer, Search/Transfer on Z80 DMA)
| | | | |
| | | | 0 = Port B -> Port A (Byte transfer direction)
| | | | 1 = Port A -> Port B
| | | V
D7 D6 D5 D4 D3 D2 D1 D0 PORT A STARTING ADDRESS (LOW BYTE)
| | V
D7 D6 D5 D4 D3 D2 D1 D0 PORT A STARTING ADDRESS (HIGH BYTE)
| V
D7 D6 D5 D4 D3 D2 D1 D0 BLOCK LENGTH (LOW BYTE)
V
D7 D6 D5 D4 D3 D2 D1 D0 BLOCK LENGTH (HIGH BYTE)</pre>

Several registers are accessible from WR0. The first write to WR0 is to the base register byte. Bits D6:D3 are optionally set to indicate that associated registers in this group will be written next. The order the writes come in are from D3 to D6 (right to left). For example, if bits D6 and D3 are set, the next two writes will be directed to PORT A STARTING ADDRESS LOW followed by BLOCK LENGTH HIGH.

=== WR1 – Write Register Group 1 ===

<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
0 | | | | 1 0 0
| | | |
| | | 0 = Port A is memory
| | | 1 = Port A is IO
| | |
| 0 0 = Port A address decrements
| 0 1 = Port A address increments
| 1 0 = Port A address is fixed
| 1 1 = Port A address is fixed
|
V
D7 D6 D5 D4 D3 D2 D1 D0 PORT A VARIABLE TIMING BYTE
0 0 0 0 0 0 | |
0 0 = Cycle Length = 4
0 1 = Cycle Length = 3
1 0 = Cycle Length = 2
1 1 = Do not use
</pre>

The cycle length is the number of cycles used in a read or write operation. The first cycle asserts signals and the last cycle releases them. There is no half cycle timing for the control signals.

=== WR2 – Write Register Group 2 ===

<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
0 | | | | 0 0 0
| | | |
| | | 0 = Port B is memory
| | | 1 = Port B is IO
| | |
| 0 0 = Port B address decrements
| 0 1 = Port B address increments
| 1 0 = Port B address is fixed
| 1 1 = Port B address is fixed
|
V
D7 D6 D5 D4 D3 D2 D1 D0 PORT B VARIABLE TIMING BYTE
0 0 | 0 0 0 | |
| 0 0 = Cycle Length = 4
| 0 1 = Cycle Length = 3
| 1 0 = Cycle Length = 2
| 1 1 = Do not use
|
V
D7 D6 D5 D4 D3 D2 D1 D0 ZXN PRESCALAR (FIXED TIME TRANSFER)
</pre>
The ZXN PRESCALAR is a feature of the zxnDMA implementation. If non-zero, a delay will be inserted after each byte is transferred such that the total time needed for each transfer is determined by the prescalar. This works in both the continuous mode and the burst mode. If the DMA is operated in burst mode, the DMA will give up any waiting time to the CPU so that the CPU can run while the DMA is idle.

The rate of transfer is given by the formula “Frate = 875kHz / prescalar” or, rearranged, “prescalar = 875kHz / Frate”. The formula is framed in terms of a sample rate (Frate) but Frate can be inverted to set a transfer time for each byte instead. The 875kHz constant is a nominal value assuming a 28MHz system clock; the system clock actually varies from this depending on the video timing selected by the user (HDMI, VGA0-6) so for complete accuracy the constant should be prorated according to documentation for nextreg 0x11.

In a DMA audio setting, selecting a sample rate of 16kHz would mean setting the prescalar value to 55. This sample period is constant across changes in CPU speed.

=== WR3 – Write Register Group 3 ===

<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
1 | 0 0 0 0 0 0
|
1 = DMA Enable
</pre>
The Z80 DMA defines more fields but they are ignored by the zxnDMA. The two other registers defined by the Z80 DMA in this group on D4 and D3 are implemented by the zxnDMA but they do nothing.

It is preferred to start the DMA by writing an 'Enable DMA' command to WR6.

=== WR4 – Write Register Group 4 ===

<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
1 | | 0 | | 0 1
| | | |
0 0 = Do not use (Behaves like Continuous mode, Byte mode on Z80 DMA)
0 1 = Continuous mode
1 0 = Burst mode
1 1 = Do not use
| |
| V
D7 D6 D5 D4 D3 D2 D1 D0 PORT B STARTING ADDRESS (LOW BYTE)
|
V
D7 D6 D5 D4 D3 D2 D1 D0 PORT B STARTING ADDRESS (HIGH BYTE)
</pre>
The Z80 DMA defines three more registers in this group through D4 that define interrupt behaviour. Interrups and pulse generation are not implemented in the zxnDMA nor are these registers available for writing.

=== WR5 – Write Register Group 5 ===
<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
1 0 | | 0 0 1 0
| |
| 0 = /ce only
| 1 = /ce & /wait multiplexed
|
0 = Stop on end of block
1 = Auto restart on end of block
</pre>
The /ce & /wait mode is implemented in the zxnDMA but is not currently used. This mode has an external device using the DMA's /ce pin to insert wait states during the DMA's transfer.

The auto restart feature causes the DMA to automatically reload its source and destination addresses and reset its byte counter to zero to repeat the last transfer when a previous one is finished.

=== WR6 – Command Register ===
<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
1 ? ? ? ? ? 1 1
| | | | |
1 0 0 0 0 = 0xC3 = Reset
1 0 0 0 1 = 0xC7 = Reset Port A Timing
1 0 0 1 0 = 0xCB = Reset Port B Timing
0 1 1 0 0 = 0xB3 = Force Ready (irrelevant for zxnDMA)
0 1 1 1 1 = 0xBF = Read Status Byte
0 0 0 1 0 = 0x8B = Reinitialize Status Byte
0 1 0 0 1 = 0xA7 = Initialize Read Sequence
1 0 0 1 1 = 0xCF = Load
1 0 1 0 0 = 0xD3 = Continue
0 0 0 0 1 = 0x87 = Enable DMA
0 0 0 0 0 = 0x83 = Disable DMA
+-- 0 1 1 1 0 = 0xBB = Read Mask Follows
|
D7 D6 D5 D4 D3 D2 D1 D0 READ MASK
0 | | | | | | |
| | | | | | V
D7 D6 D5 D4 D3 D2 D1 D0 Status Byte
| | | | | |
| | | | | V
D7 D6 D5 D4 D3 D2 D1 D0 Byte Counter Low ("High" with core 3.0.5 = bug in core)
| | | | |
| | | | V
D7 D6 D5 D4 D3 D2 D1 D0 Byte Counter High ("Low" with core 3.0.5 = bug in core)
| | | |
| | | V
D7 D6 D5 D4 D3 D2 D1 D0 Port A Address Low
| | |
| | V
D7 D6 D5 D4 D3 D2 D1 D0 Port A Address High
| |
| V
D7 D6 D5 D4 D3 D2 D1 D0 Port B Address Low
|
V
D7 D6 D5 D4 D3 D2 D1 D0 Port B Address High
</pre>
Unimplemented Z80 DMA commands are ignored.

Prior to starting the DMA transfer, a LOAD command must be issued to copy the Port A and Port B addresses into the DMA's internal pointers. Then an 'Enable DMA' command is issued to start the DMA. The last LOAD command before ENABLE must be done with correct transfer direction set.

The 'Continue' command resets the DMA's byte counter so that a following 'Enable DMA' allows the DMA to repeat the last transfer but using the current internal address pointers. I.e. it continues from where the last copy operation left off.

Reset and Reset Port A/B Timing commands on zxnDMA do reset also prescalar value.

Registers can be read via an IO read from the DMA port after setting the read mask. (At power up the read mask is set to 0x7f). Register values are the current internal DMA counter values. So 'Port Address A Low' is the lower 8-bits of Port A’s next transfer address. Once the end of the read mask is reached, further reads loop around to the first one.

The format of the DMA status byte is as follows:

<pre>00E1101T</pre>

E is set to 0 if the total block length has been transferred at least once.

T is set to 1 if at least one byte has been transferred.

== Operating speed ==
The zxnDMA operates at the same speed as the CPU, that is 3.5MHz, 7MHz, 14MHz or 28Mhz. This is a contended clock that is modified by the ULA and the auto-slowdown by [[Layer 2|Layer2]] (which only occurred in Next core's 1 and 2, the limitation was lifted in core 3.0).

The (pre-core 3.0) auto-slowdown occurs without user intervention if speed exceeds 7Mhz and the active Layer2 display is being generated (higher speed operation resumes when the active Layer2 display is not generated). Programmers do NOT need to account for speed differences regarding DMA transfers as this happens automatically.

Because of this, the cycle lengths for Ports A and B can be set to their minimum values without ill effects. The cycle lengths specified for Ports A and B are intended to selectively slow down read or write cycles for hardware that cannot operate at the DMA's full speed.

== The DMA and Interrupts ==
The zxnDMA cannot currently generate [[Interrupts|interrupts]].

The other side of this is that while the DMA controls the bus, the Z80 cannot respond to interrupts. On the Z80, the NMI interrupt is edge triggered so if an NMI occurs the fact that it occurred is stored internally in the Z80 so that it will respond when it is woken up. On the other hand, maskable interrupts are level triggered. That is, the Z80 must be active to regularly sample the /INT line to determine if a maskable interrupt is occurring. On the Spectrum and the ZX Next, the ULA (and line interrupt) are only asserted for a fixed amount of time ~30 cycles at 3.5MHz. If the DMA is executing a transfer while the interrupt is asserted, the CPU will not be able to see this and it will most likely miss the interrupt. In burst mode, with large-enough prescalar value, the CPU will never miss these interrupts, although this may change if multiple channels are implemented.

'''Since core 3.1.8:''' the ability to interrupt DMA transfers was added, this is opt-in mechanism and must be configured through {{NextRegNo|$CC}}, {{NextRegNo|$CD}} and {{NextRegNo|$CE}} and requires "hw im2 mode" interrupts being set. Because interrupts are only sampled at the end of an instruction by the Z80, each time the dma is interrupted one instruction of progress is made in the main program (before the interrupt handler code is entered).

This means after starting the DMA transfer with last `out` instruction you must follow it by N instructions which don't affect the transfer (don't remap source data memory, select different sprite/copper/... index if that's target of transfer, don't write anything to zxnDMA port), either doing different kind of work with CPU or adding block of `nop` instructions, to have non-interfering block of code available to fire N interrupts during transfer. Chose N to accommodate for worst case scenario of how many times you will interrupt the running DMA transfer. Or you can read state of zxnDMA to see if transfer did finish, but (IMHO by ped7g) in most cases it will be performance-cheaper to just add block of nop instructions or do other work on CPU not interfering with transfer.

== Programming examples ==
A simple way to program the DMA is to walk down the list of registers WR0-WR5, sending desired settings to each. Then start the DMA by sending a LOAD command followed by an ENABLE_DMA command to WR6. Once more familiar with the DMA, you will discover that the amount of information sent can be reduced to what changes between transfers.

=== Assembly ===
Short example program to DMA memory to the screen, then DMA a sprite image from memory to sprite RAM, and then showing said sprite scrolling across the screen.

<pre>;------------------------------------------------------------------------------
; sjasmplus extra options to enable Z80N, stricter syntax and Next device
opt --zxnext --syntax=abf : device zxspectrumnext
;------------------------------------------------------------------------------
; DEFINE testing ; uncomment to produce NEX file (instead of DOT)
;------------------------------------------------------------------------------
; DMA (Register 6)
;
;------------------------------------------------------------------------------
;zxnDMA programming example
;------------------------------------------------------------------------------
;(c) Jim Bagley
;------------------------------------------------------------------------------
DMA_RESET equ $c3
DMA_RESET_PORT_A_TIMING equ $c7
DMA_RESET_PORT_B_TIMING equ $cb
DMA_LOAD equ $cf ; %11001111
DMA_CONTINUE equ $d3
DMA_DISABLE_INTERUPTS equ $af
DMA_ENABLE_INTERUPTS equ $ab
DMA_RESET_DISABLE_INTERUPTS equ $a3
DMA_ENABLE_AFTER_RETI equ $b7
DMA_READ_STATUS_BYTE equ $bf
DMA_REINIT_STATUS_BYTE equ $8b
DMA_START_READ_SEQUENCE equ $a7
DMA_FORCE_READY equ $b3
DMA_DISABLE equ $83
DMA_ENABLE equ $87
DMA_WRITE_REGISTER_COMMAND equ $bb
DMA_BURST equ %11001101
DMA_CONTINUOUS equ %10101101
ZXN_DMA_PORT equ $6b
SPRITE_STATUS_SLOT_SELECT equ $303B
SPRITE_IMAGE_PORT equ $5b
SPRITE_INFO_PORT equ $57
;------------------------------------------------------------------------------

IFDEF testing
org $5800
block 32*24, $38 ; default ULA attributes
org $6000
ELSE
org $2000
ENDIF

start
ld hl,$0000
ld de,$4000
ld bc,$800
call TransferDMA ; copy some random data to the screen pointing
; to ROM for now, for the purpose of showing
; how to do a DMA copy.
ld a,0 ; sprite image number we want to update
ld bc,SPRITE_STATUS_SLOT_SELECT
out (c),a ; set the sprite image number
ld bc,1*256 ; number to transfer (1)
ld hl,testsprite ; from
call TransferDMASprite ; transfer to sprite ram

nextreg 21,1 ; turn sprite on. for more info on this check
; out https://www.specnext.com/tbblue-io-port-system/
ld de,0
ld (xpos),de ; set initial X position ( doesn't need it for
; this demo, but if you run the .loop again it
; will continue from where it was
ld a,$20
ld (ypos),a ; set initial Y position

.loop
ld a,0 ; sprite number we want to position
ld bc,SPRITE_STATUS_SLOT_SELECT
out (c),a
ld de,(xpos)
ld hl,(ypos) ; ignores H so doing this rather than
; ld a,(ypos):ld l,a
ld bc,(image) ; not flipped or palette shifted
call SetSprite

halt

ld de,(xpos)
inc de
ld (xpos),de
ld a,d
cp $01
jr nz,.loop ; if high byte of xpos is not 1 (right of
; screen )
ld a,e
cp $20+1
jr nz,.loop ; if low byte is not $21 just off the right of
; the screen, $20 is off screen but as the
; INC DE is just above and not updated sprite
; after it, it needs to be $21
xor a
ret ; return back to basic with OK

xpos dw 0 ; x position
ypos db 0 ; y position
; these next two BITS and IMAGE are swapped
; as bits needs to go into B register
image db 0+$80 ; use image 0 (for the image we transfered)
; +$80 to set the sprite to active
bits db 0 ; not flipped or palette shifted

c1 = %11100000
c2 = %11000000
c3 = %10100000
c4 = %10000000
c5 = %01100000
c6 = %01000000
c7 = %00100000
c8 = %00000000

testsprite
db c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1
db c1,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c1
db c1,c2,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c2,c1
db c1,c2,c3,c4,c4,c4,c4,c4,c4,c4,c4,c4,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c5,c5,c5,c5,c5,c5,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c6,c6,c6,c6,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c7,c7,c7,c7,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c7,c8,c8,c7,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c7,c8,c8,c7,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c7,c7,c7,c7,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c6,c6,c6,c6,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c5,c5,c5,c5,c5,c5,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c4,c4,c4,c4,c4,c4,c4,c4,c4,c3,c2,c1
db c1,c2,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c2,c1
db c1,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c1
db c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1

;-------------------------------------------------
; de = X
; l = Y
; b = bits
; c = sprite image
SetSprite
push bc
ld bc,SPRITE_INFO_PORT
out (c),e ; Xpos
out (c),l ; Ypos
pop hl
ld a,d
and 1
or h
out (c),a
ld a,l:or $80
out (c),a ; image
ret

;--------------------------------
; hl = source
; de = destination
; bc = length
;--------------------------------
TransferDMA
di
ld (DMASource),hl
ld (DMADest),de
ld (DMALength),bc
ld hl,DMACode
ld b,DMACode_Len
ld c,ZXN_DMA_PORT
otir
ei
ret

DMACode db DMA_DISABLE
db %01111101 ; R0-Transfer mode, A -> B, write adress
; + block length
DMASource dw 0 ; R0-Port A, Start address
; (source address)
DMALength dw 0 ; R0-Block length (length in bytes)
db %01010100 ; R1-write A time byte, increment, to
; memory, bitmask
db %00000010 ; 2t
db %01010000 ; R2-write B time byte, increment, to
; memory, bitmask
db %00000010 ; R2-Cycle length port B
db DMA_CONTINUOUS ; R4-Continuous mode (use this for block
; transfer), write dest adress
DMADest dw 0 ; R4-Dest address (destination address)
db %10000010 ; R5-Restart on end of block, RDY active
; LOW
db DMA_LOAD ; R6-Load
db DMA_ENABLE ; R6-Enable DMA

DMACode_Len equ $-DMACode

;------------------------------------------------------------------------------
; hl = source
; bc = length
; set port to write to with TBBLUE_REGISTER_SELECT
; prior to call
;------------------------------------------------------------------------------
TransferDMAPort
di
ld (DMASourceP),hl
ld (DMALengthP),bc
ld hl,DMACodeP
ld b,DMACode_LenP
ld c,ZXN_DMA_PORT
otir
ei
ret

DMACodeP db DMA_DISABLE
db %01111101 ; R0-Transfer mode, A -> B, write adress
; + block length
DMASourceP dw 0 ; R0-Port A, Start address (source address)
DMALengthP dw 0 ; R0-Block length (length in bytes)
db %01010100 ; R1-read A time byte, increment, to
; memory, bitmask
db %00000010 ; R1-Cycle length port A
db %01101000 ; R2-write B time byte, increment, to
; memory, bitmask
db %00000010 ; R2-Cycle length port B
db %10101101 ; R4-Continuous mode (use this for block
; transfer), write dest adress
dw $253b ; R4-Dest address (destination address)
db %10000010 ; R5-Restart on end of block, RDY active
; LOW
db DMA_LOAD ; R6-Load
db DMA_ENABLE ; R6-Enable DMA

DMACode_LenP equ $-DMACodeP
;------------------------------------------------------------------------------
; hl = source
; bc = length
;------------------------------------------------------------------------------
TransferDMASprite
di
ld (DMASourceS),hl
ld (DMALengthS),bc
ld hl,DMACodeS
ld b,DMACode_LenS
ld c,ZXN_DMA_PORT
otir
ei
ret

DMACodeS db DMA_DISABLE
db %01111101 ; R0-Transfer mode, A -> B, write adress
; + block length
DMASourceS dw 0 ; R0-Port A, Start address (source address)
DMALengthS dw 0 ; R0-Block length (length in bytes)
db %01010100 ; R1-read A time byte, increment, to
; memory, bitmask
db %00000010 ; R1-Cycle length port A
db %01101000 ; R2-write B time byte, increment, to
; memory, bitmask
db %00000010 ; R2-Cycle length port B
db %10101101 ; R4-Continuous mode (use this for block
; transfer), write dest adress
dw SPRITE_IMAGE_PORT ; R4-Dest address (destination address)
db %10000010 ; R5-Restart on end of block, RDY active
; LOW
db DMA_LOAD ; R6-Load
db DMA_ENABLE ; R6-Enable DMA
DMACode_LenS equ $-DMACodeS
;------------------------------------------------------------------------------
; de = dest, a = fill value, bc = lenth
;------------------------------------------------------------------------------
DMAFill
di
ld (FillValue),a
ld (DMACDest),de
ld (DMACLength),bc
ld hl,DMACCode
ld b,DMACCode_Len
ld c,ZXN_DMA_PORT
otir
ei
ret

FillValue db 22
DMACCode db DMA_DISABLE
db %01111101
DMACSource dw FillValue
DMACLength dw 0
db %00100100,%00010000,%10101101
DMACDest dw 0
db DMA_LOAD,DMA_ENABLE
DMACCode_Len equ $-DMACCode

;------------------------------------------------------------------------------
; End of file
;------------------------------------------------------------------------------

IFDEF testing
savenex open "DMAtest.nex", start, $FF00
savenex bank 5
ELSE
fin
savebin "DMATEST",start,fin-start
ENDIF
</pre>

Based on original text by: Allen Albright & Mike Dailly with input by Jim Bagley, Lyndon J Sharp and Phoebus R. Dokos

== Technical details (core 3.1.3+) ==

The Zilog/zxnDMA mode is now selected by using the particular I/O port number ({{PortNo|$xx6B}} for zxnDMA mode, {{PortNo|$xx0B}} for Zilog mode). The bit 6 in {{NextRegNo|$06}} is not DMA related any more and will be reused for something different.

The "counter" RR1-RR2 read back after transfer has correct byte order since core 3.1.4.

Other differences described below in "3.0.5" remains (but from practical point of view the Zilog DMA emulation in 3.1.4 is near-perfect, all the remaining differences are very minor).

== Technical details (core 3.0.5) ==

=== Zilog DMA compatibility mode ===
In Zilog DMA compatibility mode (bit 6 of {{NextRegNo|$06}}) the zxnDMA will mostly work as expected, but there are few differences in behaviour which may eventually throw off some rare SW, here is the list of the known differences (most of them describe also how the zxnDMA mode works):

The LOAD command must be issued with correct transfer direction, loading addresses in opposite direction and flipping direction afterward will mismatch the source/destination address data (Zilog/UA858D DMA chips are also sensitive to direction flip after LOAD, but the resulting transfer quirks in different way, reading source data byte after write, offsetting whole transfer by one and damaging start/end of sequence).
(does apply also to zxnDMA mode)

The LOAD command will NOT destroy the already issued "Initialize Read Sequence" - this is how even the original Zilog documentation describes the DMA chip operation, but the real Zilog DMA and UA858D (clone chip) both destroy read sequence upon LOAD command (zxnDMA is better).
(does apply also to zxnDMA mode)

The content of registers read back after finished transfer differs: the counter has swapped LSB with MSB byte, and both addresses will be adjusted length+1 times (Zilog/UA858D will return destination address adjusted only length-many times).
(does apply also to zxnDMA mode, except addresses are adjusted only "length" times of course, counter has still swapped bytes)

<del>Any read of zxnDMA port without pending read request (commands "Read Status Byte" or "Initialize Read Sequence") will return status byte (Zilog will return random value vaguely similar to status byte, but incorrect, UA858D will return zero).
(does apply also to zxnDMA mode)</del>
2026-03-30: any read of zxnDMA port without pending read request will return next byte in read sequence, the default read mask is 0x7F after power on (based on reading the VHDL, needs to verify with HW).

<del>Status byte doesn't have bit 0 set (the "T" bit in description above).
(does apply also to zxnDMA mode)</del>
2026-03-30: going by [https://gitlab.com/SpectrumNext/ZX%20Spectrum%20Next%20FPGA/-/blob/master/cores/zxnext/src/device/dma.vhd?ref%20type=heads VHDL source] this seems to be now fixed, needs to verify with HW and guess in which version of core this was fixed

The command 0xBB setting read mask will cause implicit 0xA7 Initialize Read Sequence.

Be aware that both custom timing cycles count, and prescalar values are preserved in zxnDMA even when future write to WR1/WR2 does skip these particular bytes. To reset prescalar or cycles timing, write explicitly zero into prescalar register or use commands reset/reset-port-timing.
(does apply also to zxnDMA mode, the prescalar works only in zxnDMA mode)

The destination port address is LOAD-ed even when it is "fixed" type (Contrary to Zilog DMA, which requires you to load such port as "source", flip the direction after and re-LOAD again with correct direction. UA858D chip does also load destination port address in any case, just like zxnDMA).
(does apply also to zxnDMA mode)

=== zxnDMA mode vs Zilog mode ===

In zxnDMA mode length of transfer is equal to the length written to WR0 register, port addresses are adjusted also only length-times.

Prescalar value will affect speed of transfer (use zero to switch prescalar off) (in burst mode during the extra idle time the CPU receives control back and can execute further instructions, in continuous mode the transfer will keep blocking CPU even when "slow" transfer is being done).

Assemblers

2026-03-16T21:41:57Z

Ped7g: sjasmplus version bump

Any Z80 assembler can produce code suitable for the Next. However the raw blocks of Z80 code may be not as convenient to use with Next or emulators, so a Next specific tools may be useful for creating one of the supported [[File Formats]].

== Cross-platform tools (running on PC) ==

=== ''[http://www.desdes.com/products/oldfiles/zeus.htm Zeus-ish]'' ===
: Provides a complete Z80 IDE and Macro assembler, scripted disassember plus an integrated Z80 emulator for a range of machines including partial Next support
: Supports the Next opcodes directly
: Supports remote debugging on the Next using ParaSys across a serial link
: Supports MMU paging in the integrated emulator
: Supports sprites (core versions prior to 2.00.26) in the integrated emulator

=== ''[http://pasmo.speccy.org/ Pasmo]'' ===
: A long established Z80 assembler, but has been out of development for a long time
: Supports all currently known Next extension opcodes through this [https://www.facebook.com/groups/specnext/512169722473686/ modified Pasmo from Russ McNulty and Tony Thompson] and also now supports outputting .sna files to use with CSpect, thanks to Russ McNulty

=== ''SNasm'' ===
: Included with the [https://mdf200.itch.io/cspect #CSpect] emulator
: Full macro assembler
: Full bank control via Segment management
: Supports the Next extension opcodes directly
: Generates full 24bit map files for use in CSpect

=== ''z80asm'' ===
: Part of [https://github.com/z88dk/z88dk Z88dk]''
: Supports the Next extension opcodes directly, linking assembler with large z80 library, targets any memory configuration

=== ''[https://github.com/z00m128/sjasmplus z00m's fork of sjasmplus]'' ===
: Supports all (core2.00.28) Next extension opcodes, ZXN memory model (8 memory slots with 8ki pages and 1.75MiB virtual device memory), SAVENEX to build NEX files directly from ASM source (NEX version V1.2 (and experimental extension "V1.3")), MAP files for [https://mdf200.itch.io/cspect #CSpect] emulator, SLD tracing files for [https://github.com/maziac/DeZog DeZog] and [https://github.com/Ckirby101/NDS-NextDevSystem NDS-NextDevSystem] and it is under active development (feedback is welcome).
: Open source project ("BSD-3-Clause" license), '''windows executables available at [https://github.com/z00m128/sjasmplus/releases/latest releases]''', mac and linux users are expected to simply build from source (both make and CMake are supported).
: [http://z00m128.github.io/sjasmplus/documentation.html Documentation], latest stable release v1.22.0 2026-03-15

=== ''zmac'' ===

: [http://48k.ca/zmac.html zmac - Z-80 Macro Cross Assembler]

=== ''[https://github.com/CatpainBlack/FantASM FantASM]'' ===
: FantASM is a two pass non optimising assembler for the Z80 processor by [https://github.com/CatpainBlack Guy 'CatpainBlack' Black].

:It supports all undocumented op-codes and the extended instruction set of the ZX Next and additional pseudo opcodes used by the CSpect emulator to control debugging.

== Native tools (running on Next) ==

=== ''[https://gitlab.com/next-tools/odin Odin]'' ===

Work-in-progress Next-specific assembler written by Matt Davies, used also in video tutorials presented by Jim Bagley, the best way to acquire the binary is to join the official ZX Next discord server and check channel <code>#odin</code> - pinned messages, where you can also discuss any issues and get how-to hints.

: supports most of the undocumented opcodes, all official Z80 and Next-extended instructions
: supports nested includes and binary includes
: source is stored in tokenised form (smaller file), up to 48kiB of source in single file
: assembling can produce 32kiB of machine code (enough to produce simpler dot command)
: includes also editor and console modules (debugger is planned)

=== ''[https://www.solarisite.com/spectrumnext.html Sol]'' ===

Sol is an assembler and editor written by Solaris, that runs natively on the Next. Manual, assembler binary and assembler source can be downloaded [https://www.solarisite.com/spectrumnext.html here].

=== ''[https://gitlab.com/thesmog358/tbblue/-/tree/master/tools/dev/Zeus ZEUS]'' ===

Classic ZEUS native assembler by Simon Brattel, extended and included directly in the ZX Next distro.

=== ''[https://gitlab.com/thesmog358/tbblue/-/tree/master/tools/dev/SPED SPED]'' ===

Classic SPED assembler by César Hernández Bañó, included directly in the ZX Next distro, see [https://gitlab.com/thesmog358/tbblue/-/raw/master/docs/apps/dev/SPED53readme.txt README].

=== ''[https://taylorza.itch.io/nextbasic-inline-assembler NextBASIC Inline Assembler]''===
Enables you to write inline assembly code in your NextBASIC application. The assembler can be downloaded from [https://taylorza.itch.io/nextbasic-inline-assembler HERE] with documentation available [https://github.com/taylorza/zxn-inlineasm-doc/blob/main/README.md HERE]

Audio / Music

2026-01-23T00:41:12Z

Ped7g: Adding link to Jamie's tutorial

= Music trackers, players and related tools =

{| class="wikitable sortable"
! Tool !! Description !! Platform / Notes !! Links
|-
| '''[https://www.julien-nevo.com/arkostracker/ Arkos Tracker 3]'''
| Cross-platform modern chiptune/sampled music tracker with support for 9-channel AY tracking and various player routines (also for the Next).
| Win / Linux / Mac ||
[https://www.julien-nevo.com/arkostracker/index.php/player-availability/ Player Routines]
|-
| '''[https://zx.remysharp.com/audio AYFX Editor and Driver]'''
| Web-based AY sound effect editor based on [https://shiru.untergrund.net/files/ayfxedit.zip Shiru's AYFX Editor (Windows only)]. Works fully offline, export effects for use in NextBASIC via AYFX driver.
| Web ||
[https://zx.remysharp.com/audio Link]
[https://github.com/Threetwosevensixseven/ayfxedit-improved Assembly routines]
|-
| '''[https://nextdaw.biasillo.com/ NextDAW]'''
| Modern DAW-style interface for the ZX Spectrum Next supporting 3 AY chips (9 channels), piano roll, arranger, and realtime recording.
| ZX Spectrum Next (mouse required) ||
[https://nextdaw.biasillo.com/ Link]
|-
| '''[https://volutar.myds.me/vortextracker/ Vortex Tracker]'''
| Multi-AY capable tracker for Windows. Can export in ProTracker format for Next playback. Supports 1, 2 or 3 AYs
| Windows ||
[https://github.com/Volutar/vortextracker/tree/TS3/ GitHub]
|-
| '''[https://www.pouet.net/prod.php?which=105234 AYT Sound Format]'''
| AYT (AY Turbo) is a format for Sound Player for AY 8910/8912 and YM2149 chipsets. AYT files are produced from YM files (dump of AY registry values), but are substantially smaller, players are very fast and have constant time of execution.
| Z80A players PC/web tools ||
[https://github.com/Logon-System Format definition and tools] 
[https://amstrad.neocities.org/menuayt Web tools] 
[https://blog.logonsystem.eu/welcome-to-ayters-eng/ More info]
|-
| '''[https://github.com/mikedailly/mod_player/ MOD Player]'''
| 4-channel MOD player for ZX Spectrum Next (Z80) by Mike Dailly. Compose with any Amiga tracker. Limited effect support (No CIA, only effects 1xx,2xx,Axx,Cxx,Dxx & Fxx). Updates once per interrupt filling a buffer that is played back via the DMA so could be used in game.
| ZX Spectrum Next ||
[https://github.com/mikedailly/mod_player/ GitHub]
|-
| '''[https://github.com/em00k/NXModPlayer NXModPlayer]'''
| 4-channel MOD player for ZX Spectrum Next (Z80) by njoi. Mod engine by 9bitcolor, interface by em00k. Full MOD support, all effects CIA timings. 4 Channel Stereo. Takes more processing time but results match that of the Amiga. Included on the official distro
| ZX Spectrum Next ||
[https://github.com/em00k/NXMod-src GitHub engine source]
|}

= Resources, tutorials and other links =

{| class="wikitable sortable"
! Related tool !! Type of resource !! Resource itself and description
|-
| Vortex Tracker || Youtube video || '''[https://www.youtube.com/watch?v=L4KV1V3Hul0 How I Make Spectrum Next Video Game Music With Vortex Tracker]''' by Jamie Mallender
|}

Development Tools:Linux setup

2026-01-21T21:48:36Z

Ped7g: Adding MAME source retrieval and compilation notes

== General ==

This page collects summaries of installation process of various tools related to ZX Spectrum Next software development for linux OS users.

As usual with linux, most of the suggestions are in the form of command line command to be used from terminal.

== sjasmplus assembler ==

You can also check the [https://www.youtube.com/watch?v=c6I4kdErEwE video] of installing sjasmplus on freshly reinstalled KDE neon 5.20 linux, where is also extended info how to run the automated tests of sjasmplus, and opening it in KDevelop IDE to eventually write your own modifications.

=== Prerequisites ===

On Debian based systems make sure you have these packages installed (git-cola and cmake are optional, but often handy):
<nowiki>sudo apt-get install git build-essential g++ git-cola cmake</nowiki>

=== Retrieving the sjasmplus source ===

Use git to clone the [https://github.com/z00m128/sjasmplus z00m's sjasmplus repository]:
<nowiki>git clone --recursive -j8 https://github.com/z00m128/sjasmplus.git</nowiki>

To update already cloned repository, do inside the sjasmplus folder:
<nowiki>git pull</nowiki>
- or use your favourite GIT client app to update the cloned repository.

=== Building the executable binary ===

The GNU make and common C++ compiler (gcc or clang) should be enough to build the binary:
<nowiki>make clean && make</nowiki>

To verify the binary was built ("dot slash" prefix to force running of binary in current folder, not system one):
<nowiki>./sjasmplus --version</nowiki>

=== Installing the executable ===

If you already have sjasmplus installed, use <code>which sjasmplus</code> to see where the installed executable is (and which installed executable has precedence), you can use this command also after installing the new executable to verify it is being picked up by the system.

Installing the binary in system-wide fashion:
<nowiki>sudo make install</nowiki>

Or you can install the binary only locally for your user (without root/sudo permissions):
<nowiki>mkdir -p ~/.local/bin
make PREFIX=~/.local install</nowiki>
- then make sure you have <code>~/.local/bin</code> in your user <code>PATH</code> environment variable (on some distros there is already script in .profile to add this to PATH if the dir does exist, so you may need to only logout/restart after creating it to get it active).

=== Checking if it all works ===

Open your terminal and type (in any directory):
<nowiki>sjasmplus --version</nowiki>

You should see version of the freshly built sjasmplus executable like this:
<nowiki>SjASMPlus Z80 Cross-Assembler v1.17.0 (https://github.com/z00m128/sjasmplus)</nowiki>

== hdfmonkey tool ==

The hdfmonkey tool can manipulate card-images, helping to write new builds of your project into NextZXOS card-image, to boot the emulators with full file system. (it's also possible to mount the images directly into linux by other means, to operate on them with regular file manager/etc, but hdfmonkey suits better use-case when the build script does update the image)

=== Prerequisites ===

On Debian based systems make sure you have these packages installed:
<nowiki>sudo apt-get install git build-essential g++ autoconf</nowiki>

=== Retrieving the hdfmonkey source ===

Use git to clone the [https://github.com/ped7g/hdfmonkey hdfmonkey repository with patched 0.5.7 <code>jjjs version</code> sources]:
<nowiki>git clone https://github.com/ped7g/hdfmonkey.git</nowiki>
(make sure you are on the default branch <code>"jjjs-variant"</code> to build the improved version, it should be checked out by default after clone)

* to update already cloned repository, do inside the hdfmonkey folder:
<nowiki>git pull</nowiki>
* or use your favourite GIT client app to update the cloned repository.
* if you cloned original gasman's repository before, you may want to clone and rebuild here mentioned <code>jjjs version</code> to get multiple fixes and convenience features.

=== Building the executable binary ===

The hdfmonkey is using autoconf/autotools to build final Makefile, check the hdfmonkey README for "from git" installation notes, at the moment of writing this page, the steps were:
<nowiki>cd hdfmonkey
autoheader
aclocal
autoconf
automake -a
./configure
make</nowiki>

To verify the binary was built:
<nowiki>src/hdfmonkey help</nowiki>

=== Installing the executable ===

If you already have hdfmonkey installed, use <code>which hdfmonkey</code> to see where the installed executable is (and which installed executable has precedence), you can use this command also after installing the new executable to verify it is being picked up by the system.

Installing the binary in system-wide fashion:
<nowiki>sudo make install</nowiki>

Or you can install the binary only locally for your user (without root/sudo permissions):
<nowiki>make prefix=~/.local install</nowiki>
- then make sure you have <code>~/.local/bin</code> in your user <code>PATH</code> environment variable.

=== Checking if it all works ===

Open your terminal and type (in any directory):
<nowiki>hdfmonkey help</nowiki>

You should see help of the freshly built hdfmonkey `jjjs version` executable like this:
<nowiki>hdfmonkey: utility for manipulating HDF disk images v0.5.7 jjjs

usage: hdfmonkey <command> [args]
...</nowiki>

== Extracting all files from the sd-card image ==

7-zip is the most convenient tool to extract the the files from the existing image.

To install 7-zip on a Debian system use <code>sudo apt install 7zip</code>.

To extract all the files from an existing image <code>tbblue.img</code> to a new subdirectory <code>myfiles</code>:

<nowiki>7z x tbblue.img -omyfiles</nowiki>

== Creating new sd-card image with hdfmonkey ==

This example:

* downloads the archive from the specnext.com
* unpacks it to the subdirectory <code>tmptb</code>
* creates a new SD image (with the space for 2GB files) from all the files
* deletes the subdirectory <code>tmptb</code>
* shows that the new image uses much less than 2GB
* starts listing the content of the newly created image

<nowiki>
wget https://www.specnext.com/distro/24.11/sn-complete-24.11.zip
7z x sn-complete-24.11.zip -otmptb
hdfmonkey create tbblue.img 2GB
hdfmonkey putdir tbblue.img tmptb /
rm -rf tmptb
du -h tbblue.img
7z l tbblue.img | more</nowiki>

=== Creating new sd-card image without hdfmonkey ===

It's possible to use gnu coreutils and dosfstools to create card image without hdfmonkey, but depending on exact size of image these may be less compatible with various emulator, following example for 1GB card image works in MAME but fails in CSpect (while images created by hdfmonkey tool should work for both emulator, so using '''hdfmonkey is recommended''')

<nowiki>
truncate -s 1G NextZXOS.img
parted NextZXOS.img mklabel msdos
parted NextZXOS.img mkpart primary fat32 2048s 100%
mkfs.fat -F 32 --offset=2048 NextZXOS.img
# and now to copy files to image you have to either mount it or use hdfmonkey:
# hdfmonkey putdir NextZXOS.img tmptb /</nowiki>

== Mounting sd-card image directly ==

Sometimes it may be useful to mount the card image directly, to be able to browse it and manipulate with common tools. But make sure you are not using mounted card image also in emulator at the same time, to prevent any data damage by parallel access.

=== Prerequisites ===

On Debian based systems make sure you have these packages installed:
<nowiki>sudo apt-get install fdisk mount</nowiki>

Prepare empty directory to mount the card image into (let's call it "next-card") and have the image file around ("tbblue.mmc" in following examples)
<nowiki>mkdir -p next-card</nowiki>

=== Mounting the card image ===

To mount the card image you need to know the exact byte-offset where the FAT partition starts, it's possible to read it from "fdisk" or "parted" tools outputs:
<nowiki>fdisk -l -o Start tbblue.mmc
# prints value in sector units, like:
# Start
# 63
# This has to be multiplied by 512 to get byte offset: 63*512 = 32256

# or

parted tbblue.mmc unit B print
# prints values in bytes with "B" suffix in "Start" column</nowiki>

But the fdisk output can be incorporated directly into mount command, which needs root permissions, example with sudo:
<nowiki>sudo mount tbblue.mmc next-card/ -o loop,offset=$((`fdisk -l -o Start tbblue.mmc | tail -1` * 512)),user,uid=`id -u`,gid=`id -g`

# or you can enter the offset yourself

sudo mount tbblue.mmc next-card/ -o loop,offset=32256,user,uid=`id -u`,gid=`id -g`</nowiki>

The uid and gid options will mount the filesystem under your regular user, so you can now browse it with file manager, text editors, etc.

Do not run the emulator yet, before unmounting the image (after you are done manipulating the files)!

=== Unmount the image before using it in emulator ===

<nowiki>sudo umount next-card/</nowiki>

Check the result. If the unmounting fails (probably with "target is busy"), find which process is still accessing/viewing the files in the next-card directory, and try to unmount it again.

== Mounting sd-card image with losetup ==

Alternative using losetup to use local "loop" device for mounting the image. This method can automatically detect partitions inside the image and exposes them as loop devices.

Prepare mounting dir and make sure you have <code>mount</code> and <code>losetup</code> available, Ubuntu based systems packages:
<nowiki>sudo apt-get install util-linux mount</nowiki>

=== Use losetup to attach image and scan its partitions ===

<nowiki>sudo losetup --partscan --show --find NextZXOS.img
# this will print new loop device and automatically create partition devices like /dev/loop0p1
# now mount the desired FAT32 partition:
sudo mount /dev/loop0p1 next-card/</nowiki>

=== Unmounting and cleanup of loop device ===

When finished:
<nowiki>sudo umount next-card/
sudo losetup -d /dev/loop0
# or `sudo losetup -D` to detach *ALL* loop devices</nowiki>

This detaches the loop device and frees all associated /dev/loop* entries.

Notes and gotchas:
* Do not use the image in an emulator while it is mounted.
* If the image has no partition table, --partscan will not create /dev/loop0p1.
* If multiple loop devices are active, check <code>losetup -a</code> to confirm which one is yours.

== Mounting sd‑card image with udisksctl ==

The <code>udisksctl</code> tool provides a desktop‑friendly way to attach loop devices and mount filesystems without manually calculating offsets or using <code>losetup</code>. It integrates with system services such as UDisks2, and on many desktop Linux systems it allows non‑root users (who are in the correct group) to mount images safely.

=== Prerequisites ===

On Debian‑based systems install the UDisks2 tools:

<nowiki>sudo apt-get install udisks2</nowiki>

To run <code>udisksctl</code> without <code>sudo</code>, your user must belong to the '''disk''', '''storage''', or '''udisks''' policy group (varies by distribution). If unsure, simply use <code>sudo</code> in the examples below.

=== Attaching the image as a loop device ===

Use <code>udisksctl loop-setup</code> to create a loop device for the image:

<nowiki>udisksctl loop-setup --file NextZXOS.img
# prints something like:
# Mapped file NextZXOS.img as /dev/loop2.
# UDisks automatically scans the partition table and exposes partitions as:
# /dev/loop2p1
# /dev/loop2p2
# ...</nowiki>

=== Mounting the FAT32 partition ===

Mount the desired partition:

<nowiki>udisksctl mount --block-device /dev/loop2p1
# This prints the mount point, for example:
# Mounted /dev/loop2p1 at /media/youruser/NextZXOS.</nowiki>

You can now browse and edit the filesystem normally using your file manager or command‑line tools.

=== Unmounting and cleanup ===

<nowiki>udisksctl unmount --block-device /dev/loop2p1
udisksctl loop-delete --block-device /dev/loop2</nowiki>

This cleanly detaches the loop device and removes all <code>/dev/loop*</code> entries created for the image.

=== Notes and gotchas ===

* Do not use the image in an emulator while it is mounted, parallel access may corrupt data.
* If the image has no partition table, UDisks will not create '''/dev/loopXp1''' and you must mount manually using an offset.
* Mount points are created under <code>/media/$USER/</code> unless overridden by system policy.
* UDisks may auto‑mount partitions immediately after '''loop‑setup''' depending on desktop environment settings.

== MAME emulator ==

MAME got Next emulation and it got improved a lot around end of 2025, turning it into probably most accurate and performant Next emulator currently available. But as that shift is quite recent, the developers community haven’t transitioned to it yet in large numbers and the tutorials and examples are non-existent. This section provides a basic Linux setup guide.

This chapter focuses only on installing MAME from source code git repository, so you can update to latest work in progress or even contribute to the development yourself. The stable binary releases already contain decent Next emulation, but bug fixes and improvements are still coming often and stable releases trail a few weeks behind.

At the moment, the primary developer working on Next emulation in MAME is Andrei Holub, so his fork repo will be used as default source.

=== Prerequisites ===

You need C++17 compiler (GCC 10.3+ or clang 11+), GNU make and few more development tools and common libraries, for specific list for your distro and up to date information check [https://docs.mamedev.org/initialsetup/compilingmame.html Compiling MAME] web page from official docs.

Keep this page around as the example here is quick hint and not meant as replacement for full documentation.

=== Retrieving the MAME source ===

Use git to clone the [https://github.com/holub/mame holub's MAME repository] and add the [https://github.com/mamedev/mame official MAME repository] as an additional remote:
<nowiki>git clone --origin holubdev https://github.com/holub/mame.git
cd mame
git remote add -f --tags mamedev https://github.com/mamedev/mame.git</nowiki>

To update already cloned repository checked out at master branch, do inside the mame folder (WARNING: this will drop any local changes in the repository, as MAME devs often rewrite already published commits and you need to reset your local clone to latest state - if you are developer working on MAME sources, you should know yourself how to work with git to preserve your changes and rebase/merge):
<nowiki>git fetch --all --force
git reset --hard master</nowiki>
Or use your favourite GIT client app to update the cloned repository.

=== Building the executable binary ===

To '''rebuild''' '''only''' Next emulation (''"tbblue"'' machine) and get executable named <code>tbblue</code>, run <code>make</code> like this:
<nowiki># make sure there are no remnants from previous builds
make clean
# If you want to, you can change to TOOLS=1 to build also "various additional tools, such as chdman"
# The name of resulting binary is affected by SUBTARGET=tbblue, leave it out if you want "mame"
make REGENIE=1 EMULATOR=1 TOOLS=0 SOURCES=sinclair/specnext.cpp SUBTARGET=tbblue -j $(nproc)
# check the build output to confirm that compilation succeeded. To list binary:
ls -lh tbblue</nowiki>

This may take a considerable amount of time depending on how powerful your PC is.

If you are developing MAME yourself, you can do incremental build (after REGENIE=1 was used to "generate project files" in previous build and your source code changes don't require full rebuild) - this will be lot faster of course as usual:
<nowiki>make SUBTARGET=tbblue -j $(nproc)</nowiki>

To rebuild full MAME including all other emulation targets (computers and arcade machines) - which will take even much longer - use:
<nowiki>make clean && make REGENIE=1 EMULATOR=1 TOOLS=0 -j $(nproc)
# check existence of new binary (the line above will produce default name "mame")
ls -lh mame</nowiki>

=== Installing the executable and configuration ===

TODO

=== Checking if it all works ===

TODO

== #CSpect emulator ==

The #CSpect is Mike Dailly's ZX Spectrum Next emulator, written in C# making it cross-platform (sort of, where the mono framework is available). It is non-free (closed-source, custom license) project, but available for usage without any payment (it's possible to use it internally to develop also commercial titles, but you can not distribute/sell the emulator itself, not even packaged with your game - for such agreement contact the author first and get his permission).

Currently it is most performant and user friendly emulator of ZX Spectrum Next, with good emulation accuracy (see [https://wiki.specnext.dev/CSpect:known_bugs CSpect:known_bugs] page for more detailed report).

=== Prerequisites ===

On Debian based systems make sure you have these packages installed:
<nowiki>sudo apt-get install mono-complete libopenal1 libsdl2-dev</nowiki>

=== Retrieving the #CSpect package ===

Use web browser to visit itch.io dedicated to CSpect project [https://mdf200.itch.io/cspect mdf200.itch.io/cspect] and download latest release.

You may get warnings from your browser or antivirus about the page itself and about the zip/binary files. The #CSpect has long record of triggering false positives of AV engines due to the executable being not digitally signed and because of the code using features of OS which are normal for emulator, but may look wonky for AV heuristic. Whether you trust the executable is virus free is up to you, in the end.

=== Installing the executable ===

Unzip the retrieved zip file (I personally use KDE Dolphin file manager, the file context menu ''"Extract -> Extract archive here, autodetect subfolder"''), and place the unzipped directory to target destination (<code>~/zx/emulators/CSpect/CSpect2_13_0</code> in my case). I prefer to keep every version in its own directory, and have general symbolic link pointing to the one I want use by default:
<nowiki>cd ~/zx/emulators/CSpect
ln -s CSpect2_13_0 CSpect_current</nowiki>

Then I create launcher bash-scripts in my <code>~/.local/bin</code> like this (name of script <code>runCSpect</code>):
<nowiki>#!/bin/bash
# personal script of Ped to launch "#CSpect" emulator in "current directory" (with arguments like: "runCSpect file.nex")
MONO_IOMAP=all mono ~/zx/emulators/CSpect/CSpect_current/CSpect.exe -tv -zxnext -s28 -w4 -mmc=./ "$@"</nowiki>

Notes: I don't know any more what <code>MONO_IOMAP=all</code> helps with, I believe it was suggested to help with any filesystem windows-like paths containing backslashes, you can try to do your own research. The <code>-tv</code> switch will switch off "scanlines" shader effect and generally switch off any GPU shaders, which makes CSpect more compatible with graphics drivers (try it, if you get only black screen or instant crash during init). The <code>-w4</code> will make the window quite large - 4x scale, the <code>-zxnext -s28</code> switch #CSpect into ZX Next emulation mode and set 28Mhz speed of OS as default. And finally the <code>-mmc=./ "$@"</code> will set ''current directory'' for esxdos emulation to the directory where you use the script to launch the emulator, and pass any remaining command line options entered by user, like the name of the SNA/NEX file. Other noteworthy options are <code>-debug -brk -map=file.map</code>, the -debug entering the debugger just ahead of the first instruction, -brk enables CSpect specific two-byte tag 0xDD 0x01 to work as breakpoint and the -map option allows you to load into debugger the symbol table from your assembler (directive CSPECTMAP in sjasmplus), making labels visible in disassembly.

=== Checking if it all works ===

Go to some directory with SNA/SNX/NEX file (there are also some demo files right in the CSpect directory) and use the launcher script, like:
<nowiki>runCSpect beast.nex</nowiki>

You should see #CSpect emulator window running the beast.nex demo (or whatever else you did want to launch and entered as argument).

[[File:Cspect_test_run.png|frameless|Running CSpect from directory with test snapshots]]

MAME:Installing

2026-01-21T16:55:33Z

Ped7g: Moving Linux related mounting details to dev tools page, making this article simpler and less technical (especially for Win/Mac users)

[https://www.mamedev.org/ MAME] (formerly an acronym of Multiple Arcade Machine Emulator) is a free and open-source emulator designed to emulate the hardware of arcade games, later expanded to include video game consoles, old computers and other systems in software on modern personal computers and other platforms.

MAME has supported the ZX Spectrum Next since version 0.267. The existing implementation is based on the v3.02.01 core and implements most of the features.

= Installation =

You will need to install MAME, provide it with the Next firmware ('ROM'), and get the NextZXOS image:

=== 1. Get MAME ===
Start with these official MAME releases. If you encounter crashes or other bugs, try replacing the MAME executable with holub's latest Continuous Integration (CI) builds as described at the end of this article.

* '''Windows:''' Download [https://www.mamedev.org/release.html MAME for Windows].
* '''macOS:''' Download [https://sdlmame.lngn.net/ MAME for macOS].
* '''Linux:''' Install MAME from the flatpak repositories by running:
<pre>sudo flatpak install org.mamedev.MAME</pre>

Note that Windows and macOS will likely prevent you from launching MAME directly for security reasons. See below on how to solve this.

Alternatively, for the MAME platform as a whole, you can also check your package manager, or [https://docs.mamedev.org/initialsetup/compilingmame.html build from sources].

Git of official MAME: [https://github.com/mamedev/mame/ https://github.com/mamedev/mame/] [https://github.com/mamedev/mame/blob/master/src/mame/sinclair/specnext.cpp specnext.cpp]

Git of holub's fork: [https://github.com/holub/mame https://github.com/holub/mame] [https://github.com/holub/mame/blob/master/src/mame/sinclair/specnext.cpp specnext.cpp] (may contain extra fixes and features before they are merged to official repository)

=== 2. Get TBBLUE (the Next 'boot ROM') ===
Put the file [https://github.com/Threetwosevensixseven/NexCreator/raw/master/bootroms/tbblue.zip tbblue.zip] into MAME's <code>roms</code> folder. Don't extract it; MAME will look for the zip file when the "tbblue" machine is selected.

Note: The ROMs in this zip are what is embedded inside the FPGA core on real Next hardware. They're different from any ZX Spectrum machine ROMs you may be used to using, that are on the distro, SD card or SD image file.

=== 3. Get the NextZXOS Image ===
Get an SD card image file of [https://www.specnext.com/latestdistro/ NextZXOS]. Note that currently some published disk images on the official SpecNext.com site (the <code>latestdistro</code> link points to the official location where the latest distribution can be found) do not work with some emulators, but all images from <code>https://zxnext.uk/hosted/</code> work with both MAME and CSpect, like [https://zxnext.uk/hosted/index_files/hdfimages/cspect-next-2gb.zip this SD card image in the zip archive]. Extract the image <code>cspect-next-2gb.img</code> from the archive to use it, then point MAME to this SD card image with the <code>-hard1</code> option (or select that file from the menu inside MAME).

= Usage =
MAME looks for its configuration and helper files in specific (configurable) folders. By default, these are relative to the current working directory (cwd), i.e., from where you launched the executable. The <code>mame.ini</code> file and folders like <code>roms, bgfx, plugins, language, ...</code> are expected there, unless the <code>mame.ini</code> file specifies other paths. When launching through a desktop icon or menu, depending on the OS, the working directory is often defined by the properties of that launch shortcut. When launching MAME from the command line, the current directory is "cwd" (doh). On Linux, MAME will look for <code>mame.ini</code> first in the <code>~/.mame</code> folder. You can use the option <code>-inipath</code> to point MAME to a different path for the <code>mame.ini</code> file.

However, the fastest way to run a machine with a desired configuration is from the command prompt, without requiring a <code>mame.ini</code> file. Most of the features are also available through MAME's UI, although that takes more time to configure.

As an example, this invocation enables the UI, uses "crisp pixels", starts in a window, doesn't display the starting gameinfo window (it can still be displayed interactively from the UI), disables the mouse, confirms before exiting MAME, and specifies the disk image (remember to adjust the path to it):

<pre>mame -ui_active -nounevenstretch -aspect 2:1 -video bgfx -bgfx_screen_chains unfiltered -window -skip_gameinfo -mouse_device none -confirm_quit tbblue -hard1 /path/to/cspect-next-2gb.img</pre>

Let's cover some useful options:

<ol start="1">

<li>
Run inside a window and with no mouse support, until you get familiar with the UI keys:
<pre>> mame tbblue -window -mouse_device none -hard1 /path/to/next-distribution.img</pre>
To launch the Linux flatpak version using the same options:
<pre>> flatpak run org.mamedev.MAME tbblue -window -mouse_device none -hard1 /path/to/next-distribution.img</pre>
</li>

<li>
Activate UI keys on startup:
<pre>> ... -ui_active</pre>
</li>

<li>
Don't show the info popup on startup:
<pre>> ... -skip_gameinfo</pre>
</li>

<li>Run with debugger. If you don't request this on startup, you won't have access to it:
<pre>> ... -debug</pre>
</li>

<li>Use "crisp" pixels:
<pre>> ... -nounevenstretch -aspect 2:1 -video bgfx -bgfx_screen_chains unfiltered</pre>
</li>

<li>No joystick connected to PC (having this may slightly speed up MAME's startup, but ''remember to remove this part from the command line and the corresponding setting in the ini file if you do want to use a joystick''):
<pre>> ... -joystickprovider none</pre>
</li>

<li>Ask for confirmation when exiting MAME (otherwise it's easy to exit MAME accidentally by hitting ESC, especially when playing games or navigating menus):
<pre>> ... -confirm_quit</pre>
</ol>

Check the [https://docs.mamedev.org/commandline/commandline-all.html#mame-commandline-universal official MAME documentation] for more advanced usage.

= Security: Allowing MAME to Run on Windows and macOS =

'''On Windows,''' you will need to confirm that you want to launch MAME by clicking "Run Anyway" on first launch. ''(More details needed here.)''

'''On macOS,''' MAME will not open at first. Instead, a dialog will appear saying:

''“mame” Not Opened. Apple could not verify “mame” is free of malware that may harm your Mac or compromise your privacy.''

Click “Done”. Then open '''System Settings -> Privacy & Security''', and scroll down to the message ''mame was blocked to protect your Mac.'' Click “Allow Anyway”.

Now launch MAME again. A dialog will ask once more if you want to open “mame”. Click “Open Anyway”, and enter your password or use Touch ID when prompted by macOS.

From now on, you can launch this version of MAME without warnings. However, you '''will''' need to repeat this each time you update MAME.

= Keys =

Keys are emulated in two modes: either to control the MAME emulator or completely dedicated to the emulated system (the Next). You can toggle between these two keyboard modes with ScrLk (on Win and Linux) or fn+delete (on Mac).

Some UI keys:
* F3 - soft reset
* Shift+F3 - hard reset
* F4 - sprites/tiles/font viewer (Enter, ], [)
* F5 - pause emulation
* F6 - save state
* F7 - load state
* Tab - emulator settings
* ~ - menu
* ` (backtick) - debugger (when enabled by starting MAME with <code>-debug</code> or <code>-d</code> on the command line)
* PgDwn (Linux/Mac), fn-Downarrow (MacBooks) or Insert (Win) - hold down to fast-forward emulation at maximum speed, e.g., to speed up booting the Next
* Esc - exit (exits menus but also the entire emulator - see <code>-confirm_quit</code> option above)
* F11 - DivMMC NMI
* F12 - Multiface NMI

Check [https://docs.mamedev.org/usingmame/defaultkeys.html default keys documentation] for more.

= Changing the UI toggle key =

Some laptops don't have a Scroll Lock key, so you may not be able to exit MAME if you run it in full-screen mode. In these cases, you can change the UI toggle key as follows:

* Run MAME without any command line arguments (except maybe -window) to open its GUI.
* Push TAB and enter the General Settings menu.
* Go to Input Assignments -> User Interface -> Toggle UI controls and select a new key. I use Right Alt / Alt GR.
* Return to the previous menu twice, then choose Save Settings

= Creating and manipulating NextZXOS SD card image =

Most users wanting to emulate the Next using MAME will be fine using a pre-built SD card image downloaded from the specnext website. The following guide is provided for anyone wanting to create a NextZXOS SD card image from scratch.

Download the [https://www.specnext.com/latestdistro/ latest NextZXOS distribution zip file] (named something like sn-complete-WX.YZ.zip) and extract it into a new, empty directory.

== Creating and populating a SD card image using hdfmonkey jjjs build ==

The [https://www.specnext.com/forum/viewtopic.php?t=2604 hdfmonkey "jjjs build"] is a variant of hdfmonkey tool which includes some unique features and its main archive (at the previously given link) also contains pre-built binaries for Windows x64, MacOS x64, MacOS Apple Silicon and Linux x64. (Alternatively, the process to build a local Linux version of the executable is described [[Development_Tools:Linux_setup#hdfmonkey_tool | here]] )

If you extracted sn-complete-WX.YZ.zip into a subdirectory named <code>snWXYZ</code>, and you want to create a 1GB image called <code>NextZXOS.img</code> and you have a jjjs build" of hdfmonkey, then it's enough to do:

<pre>
hdfmonkey create NextZXOS.img 1G
hdfmonkey putdir NextZXOS.img snWXYZ /
</pre>

The first line creates an empty 1GB image and formats it with the best FAT parameters suited to the size of the image.

The second line recursively copies all the content of the directory <code>snWXYZ</code> to the image, preserving the directory structure inside, starting from the <code>/</code> in the image.

One of the advantages of this method is that even if the image has a capacity of 1GB, it will use much less space on your hard drive until you fill up the image. On Linux or MacOS, a command <code>du -h NextZXOS.img</code> shows the actual amount of disk space used by the image. On Windows the same information can be seen in the File Properties dialog.

The fastest way to transfer a file or a directory (including its content, recursively) into an image is by using a single <code>put</code> (or <code>putdir</code>, if it's to transfer the directory file content to an existing directory) command of hdfmonkey.

The most convenient tool to copy of all the content from the image to a folder outside of the image is 7-zip. On Windows, just use the 7-zip GUI. On MacOS and Linux, see: [[Development_Tools:Linux_setup#Extracting_all_files_from_the_sd-card_image]].

=MAME Plugins and Scripts=

Some MAME plugins and scripts that may be useful for Next developers and end users are listed [[MAME:Plugins_and_Scripts|here]]. They let you speed up the Next boot time, profile your NextBASIC or assembler code, and more.

=Continuous Integration MAME Builds=

MAME is updated on a release schedule, but due to the ongoing nature of development, including for the MAME Next machine, it can sometimes be useful to install a more recent build if it contains a new feature or bugfix you are interested in. Sometimes, this ongoing work is discussed on social media, such as the [https://discordapp.com/channels/556228195767156758/752197165891321886 Next Developer Discord].

Continuous Integration (CI) builds are available from both the [https://github.com/mamedev/mame/actions primary MAME repo] and [https://github.com/holub/mame/actions holub's GitHub repo]. Both are considered bleeding-edge, with the primary MAME repo slightly less so. MAME CI builds are available for Windows, Linux, and macOS and are updated automatically whenever code is committed by a maintainer or pushed to the primary repo.

To try out a CI build (more precisely, the resulting binary executable, which is a produced "artifact" of the build process) , first do a full MAME install from the [https://www.mamedev.org/release.html latest release] if you have not already done so. Then back up your main binary from its installation location - these are called something like <code>mame.exe</code> or <code>mame</code>. You can always restore these if the CI build doesn't work, or if you don't like how it behaves.

'''You need to be logged in to github''' to download CI artifacts, so [https://github.com/login sign in] or [https://github.com/signup sign up].

Then visit one of the links above and find a workflow run item for your platform. Workflow items are the things in the list. The tags are flagged as <code>CI (Windows)</code>, <code>CI (Linux)</code>, or <code>CI (macOS)</code> in the second row of each workflow item in the list (not the filter in the left hand nav menu). Click on a completed workfow item (only items with green checkmarks will have created downloadable binaries yet), find the Artifacts section at the bottom, then click the Download button. Unzip the downloaded file and find the main binary (with the same name as above). Copy the main binary to the install location, overwriting the original one, and run MAME the same way you were running it before. On Windows and macOS, you need to repeat the security steps above to trust the new MAME executable.

= More MAME related links =

MAME [https://docs.mamedev.org/ documentation].

Report any issues with MAME on the [https://mametesters.org/ bugtracker].

For '''Linux''' users there are more tips (how to compile MAME from source, how to configure it to not use CWD as starting path for resource directories, how to mount or create image file) at [[Development_Tools:Linux_setup]] page.

Development Tools:Linux setup

2026-01-21T16:46:26Z

Ped7g: add placeholder for MAME lore

Development Tools:Linux setup

2026-01-21T16:32:41Z

Ped7g: adding mount card with udisksctl and change losetup -D advice

Development Tools:Linux setup

2026-01-21T15:59:28Z

Ped7g: adding mount card with losetup

Development Tools:Linux setup

2026-01-21T00:00:13Z

Ped7g: adding alternative way to create card image documenting compatibility caveat

Assemblers

2026-01-16T19:57:30Z

Ped7g: bump sj stable version

Any Z80 assembler can produce code suitable for the Next. However the raw blocks of Z80 code may be not as convenient to use with Next or emulators, so a Next specific tools may be useful for creating one of the supported [[File Formats]].

== Cross-platform tools (running on PC) ==

=== ''[http://www.desdes.com/products/oldfiles/zeus.htm Zeus-ish]'' ===
: Provides a complete Z80 IDE and Macro assembler, scripted disassember plus an integrated Z80 emulator for a range of machines including partial Next support
: Supports the Next opcodes directly
: Supports remote debugging on the Next using ParaSys across a serial link
: Supports MMU paging in the integrated emulator
: Supports sprites (core versions prior to 2.00.26) in the integrated emulator

=== ''[http://pasmo.speccy.org/ Pasmo]'' ===
: A long established Z80 assembler, but has been out of development for a long time
: Supports all currently known Next extension opcodes through this [https://www.facebook.com/groups/specnext/512169722473686/ modified Pasmo from Russ McNulty and Tony Thompson] and also now supports outputting .sna files to use with CSpect, thanks to Russ McNulty

=== ''SNasm'' ===
Included with the [https://mdf200.itch.io/cspect #CSpect] emulator
: Full macro assembler
: Full bank control via Segment management
: Supports the Next extension opcodes directly
: Generates full 24bit map files for use in CSpect

=== ''z80asm'' ===
Part of [https://github.com/z88dk/z88dk Z88dk]''
: Supports the Next extension opcodes directly, linking assembler with large z80 library, targets any memory configuration

=== ''[https://github.com/z00m128/sjasmplus z00m's fork of sjasmplus]'' ===
: Supports all (core2.00.28) Next extension opcodes, ZXN memory model (8 memory slots with 8ki pages and 1.75MiB virtual device memory), SAVENEX to build NEX files directly from ASM source (NEX version V1.2 (and experimental extension "V1.3")), MAP files for [https://mdf200.itch.io/cspect #CSpect] emulator, SLD tracing files for [https://github.com/maziac/DeZog DeZog] and [https://github.com/Ckirby101/NDS-NextDevSystem NDS-NextDevSystem] and it is under active development (feedback is welcome).
: Open source project ("BSD-3-Clause" license), '''windows executables available at [https://github.com/z00m128/sjasmplus/releases/latest releases]''', mac and linux users are expected to simply build from source (both make and CMake are supported).
: [http://z00m128.github.io/sjasmplus/documentation.html Documentation], latest stable release v1.21.1 2026-01-16

=== ''[https://github.com/CatpainBlack/FantASM FantASM]'' ===
FantASM is a two pass non optimising assembler for the Z80 processor by [https://github.com/CatpainBlack Guy 'CatpainBlack' Black].

It supports all undocumented op-codes and the extended instruction set of the ZX Next and additional pseudo opcodes used by the CSpect emulator to control debugging.

== Native tools (running on Next) ==

=== ''[https://gitlab.com/next-tools/odin Odin]'' ===

Work-in-progress Next-specific assembler written by Matt Davies, used also in video tutorials presented by Jim Bagley, the best way to acquire the binary is to join the official ZX Next discord server and check channel <code>#odin</code> - pinned messages, where you can also discuss any issues and get how-to hints.

: supports most of the undocumented opcodes, all official Z80 and Next-extended instructions
: supports nested includes and binary includes
: source is stored in tokenised form (smaller file), up to 48kiB of source in single file
: assembling can produce 32kiB of machine code (enough to produce simpler dot command)
: includes also editor and console modules (debugger is planned)

=== ''[https://www.solarisite.com/spectrumnext.html Sol]'' ===

Sol is an assembler and editor written by Solaris, that runs natively on the Next. Manual, assembler binary and assembler source can be downloaded [https://www.solarisite.com/spectrumnext.html here].

=== ''[https://gitlab.com/thesmog358/tbblue/-/tree/master/tools/dev/Zeus ZEUS]'' ===

Classic ZEUS native assembler by Simon Brattel, extended and included directly in the ZX Next distro.

=== ''[https://gitlab.com/thesmog358/tbblue/-/tree/master/tools/dev/SPED SPED]'' ===

Classic SPED assembler by César Hernández Bañó, included directly in the ZX Next distro, see [https://gitlab.com/thesmog358/tbblue/-/raw/master/docs/apps/dev/SPED53readme.txt README].

=== ''[https://taylorza.itch.io/nextbasic-inline-assembler NextBASIC Inline Assembler]''===
Enables you to write inline assembly code in your NextBASIC application. The assembler can be downloaded from [https://taylorza.itch.io/nextbasic-inline-assembler HERE] with documentation available [https://github.com/taylorza/zxn-inlineasm-doc/blob/main/README.md HERE]

Audio / Music

2025-12-30T09:35:54Z

Ped7g: pruning Arkos Tracker urls

{| class="wikitable sortable"
! Tool !! Description !! Platform / Notes !! Links
|-
| '''[https://www.julien-nevo.com/arkostracker/ Arkos Tracker 3]'''
| Cross-platform modern chiptune/sampled music tracker with support for 9-channel AY tracking and various player routines (also for the Next).
| Win / Linux / Mac ||
[https://www.julien-nevo.com/arkostracker/index.php/player-availability/ Player Routines]
|-
| '''[https://zx.remysharp.com/audio AYFX Editor and Driver]'''
| Web-based AY sound effect editor based on [https://shiru.untergrund.net/files/ayfxedit.zip Shiru's AYFX Editor (Windows only)]. Works fully offline, export effects for use in NextBASIC via AYFX driver.
| Web ||
[https://zx.remysharp.com/audio Link]
[https://github.com/Threetwosevensixseven/ayfxedit-improved Assembly routines]
|-
| '''[https://nextdaw.biasillo.com/ NextDAW]'''
| Modern DAW-style interface for the ZX Spectrum Next supporting 3 AY chips (9 channels), piano roll, arranger, and realtime recording.
| ZX Spectrum Next (mouse required) ||
[https://nextdaw.biasillo.com/ Link]
|-
| '''[https://volutar.myds.me/vortextracker/ Vortex Tracker]'''
| Multi-AY capable tracker for Windows. Can export in ProTracker format for Next playback. Supports 1, 2 or 3 AYs
| Windows ||
[https://github.com/Volutar/vortextracker/tree/TS3/ GitHub]
|-
| '''[https://www.pouet.net/prod.php?which=105234 AYT Sound Format]'''
| AYT (AY Turbo) is a format for Sound Player for AY 8910/8912 and YM2149 chipsets. AYT files are produced from YM files (dump of AY registry values), but are substantially smaller, players are very fast and have constant time of execution.
| Z80A players PC/web tools ||
[https://github.com/Logon-System Format definition and tools] 
[https://amstrad.neocities.org/menuayt Web tools] 
[https://blog.logonsystem.eu/welcome-to-ayters-eng/ More info]
|-
| '''[https://github.com/mikedailly/mod_player/ MOD Player]'''
| 4-channel MOD player for ZX Spectrum Next (Z80) by Mike Dailly. Compose with any Amiga tracker. Limited effect support (No CIA, only effects 1xx,2xx,Axx,Cxx,Dxx & Fxx). Updates once per interrupt filling a buffer that is played back via the DMA so could be used in game.
| ZX Spectrum Next ||
[https://github.com/mikedailly/mod_player/ GitHub]
|-
| '''[https://github.com/em00k/NXModPlayer NXModPlayer]'''
| 4-channel MOD player for ZX Spectrum Next (Z80) by njoi. Mod engine by 9bitcolor, interface by em00k. Full MOD support, all effects CIA timings. 4 Channel Stereo. Takes more processing time but results match that of the Amiga. Included on the official distro
| ZX Spectrum Next ||
[https://github.com/em00k/NXMod-src GitHub engine source]
|}

Audio / Music

2025-12-22T22:58:10Z

Ped7g: Adding AYT format info

{| class="wikitable sortable"
! Tool !! Description !! Platform / Notes !! Links
|-
| '''[https://www.julien-nevo.com/arkostracker/ Arkos Tracker 2]'''
| Cross-platform modern chiptune/sampled music tracker with support for 9-channel AY tracking and various player routines for the Next.
| Win / Linux / Mac ||
[http://www.julien-nevo.com/arkostracker/index.php/the-players/ Player Routines],
<s>[http://ped.7gods.org/ZX_Spectrum_Next.aks ZX Next Template (.aks)]</s>,
<s>[http://ped.7gods.org/song_properties.jpg Song Properties]</s>,
<s>[http://ped.7gods.org/psg_settings.jpg PSG Settings]</s>

|-
| '''[https://zx.remysharp.com/audio AYFX Editor and Driver]'''
| Web-based AY sound effect editor based on [https://shiru.untergrund.net/files/ayfxedit.zip Shiru's AYFX Editor (Windows only)]. Works fully offline, export effects for use in NextBASIC via AYFX driver.
| Web ||
[https://zx.remysharp.com/audio Link]
[https://github.com/Threetwosevensixseven/ayfxedit-improved Assembly routines]
|-
| '''[https://nextdaw.biasillo.com/ NextDAW]'''
| Modern DAW-style interface for the ZX Spectrum Next supporting 3 AY chips (9 channels), piano roll, arranger, and realtime recording.
| ZX Spectrum Next (mouse required) ||
[https://nextdaw.biasillo.com/ Link]
|-
| '''[https://volutar.myds.me/vortextracker/ Vortex Tracker]'''
| Multi-AY capable tracker for Windows. Can export in ProTracker format for Next playback. Supports 1, 2 or 3 AYs
| Windows ||
[https://volutar.myds.me/vortextracker/ GitHub]
|-
| '''[https://www.pouet.net/prod.php?which=105234 AYT Sound Format]'''
| AYT (AY Turbo) is a format for Sound Player for AY 8910/8912 and YM2149 chipsets. AYT files are produced from YM files (dump of AY registry values), but are substantially smaller, players are very fast and have constant time of execution.
| Z80A players PC/web tools ||
[https://github.com/Logon-System Format definition and tools] 
[https://amstrad.neocities.org/menuayt Web tools] 
[https://blog.logonsystem.eu/welcome-to-ayters-eng/ More info]
|-
| '''[https://github.com/mikedailly/mod_player/ MOD Player]'''
| 4-channel MOD player for ZX Spectrum Next (Z80) by Mike Dailly. Compose with any Amiga tracker. Limited effect support (No CIA, only effects 1xx,2xx,Axx,Cxx,Dxx & Fxx). Updates once per interrupt filling a buffer that is played back via the DMA so could be used in game.
| ZX Spectrum Next ||
[https://github.com/mikedailly/mod_player/ GitHub]
|-
| '''[https://github.com/em00k/NXModPlayer NXModPlayer]'''
| 4-channel MOD player for ZX Spectrum Next (Z80) by njoi. Mod engine by 9bitcolor, interface by em00k. Full MOD support, all effects CIA timings. 4 Channel Stereo. Takes more processing time but results match that of the Amiga. Included on the official distro
| ZX Spectrum Next ||
[https://github.com/em00k/NXMod-src GitHub engine source]
|}

MAME:Installing

2025-12-22T20:09:04Z

Ped7g: change url anchor to follow edits

[https://www.mamedev.org/ MAME] (formerly an acronym of Multiple Arcade Machine Emulator) is a free and open-source emulator designed to emulate the hardware of arcade games, later expanded to include video game consoles, old computers and other systems in software on modern personal computers and other platforms.

MAME has supported the ZX Spectrum Next since version 0.267. The existing implementation is based on the v3.02.01 core and implements most of the features.

= Installation =

You will need to install MAME, provide it with the Next firmware ('ROM'), and get the NextZXOS image:

=== 1. Get MAME ===
Start with these official MAME releases. If you encounter crashes or other bugs, try replacing the MAME executable with holub's latest Continuous Integration (CI) builds as described at the end of this article.

* '''Windows:''' Download [https://www.mamedev.org/release.html MAME for Windows].
* '''macOS:''' Download [https://sdlmame.lngn.net/ MAME for macOS].
* '''Linux:''' Install MAME from the flatpak repositories by running:
<pre>sudo flatpak install org.mamedev.MAME</pre>

Note that Windows and macOS will likely prevent you from launching MAME directly for security reasons. See below on how to solve this.

Alternatively, for the MAME platform as a whole, you can also check your package manager, or [https://docs.mamedev.org/initialsetup/compilingmame.html build from sources].

Git of official MAME: [https://github.com/mamedev/mame/ https://github.com/mamedev/mame/] [https://github.com/mamedev/mame/blob/master/src/mame/sinclair/specnext.cpp specnext.cpp]

Git of holub's fork: [https://github.com/holub/mame https://github.com/holub/mame] [https://github.com/holub/mame/blob/master/src/mame/sinclair/specnext.cpp specnext.cpp] (may contain extra fixes and features before they are merged to official repository)

=== 2. Get TBBLUE (the Next 'boot ROM') ===
Put the file [https://github.com/Threetwosevensixseven/NexCreator/raw/master/bootroms/tbblue.zip tbblue.zip] into MAME's <code>roms</code> folder. Don't extract it; MAME will look for the zip file when the "tbblue" machine is selected.

Note: The ROMs in this zip are what is embedded inside the FPGA core on real Next hardware. They're different from any ZX Spectrum machine ROMs you may be used to using, that are on the distro, SD card or SD image file.

=== 3. Get the NextZXOS Image ===
Get an SD card image file of [https://www.specnext.com/latestdistro/ NextZXOS]. Note that currently some published disk images on the official SpecNext.com site (the <code>latestdistro</code> link points to the official location where the latest distribution can be found) do not work with some emulators, but all images from <code>https://zxnext.uk/hosted/</code> work with both MAME and CSpect, like [https://zxnext.uk/hosted/index_files/hdfimages/cspect-next-2gb.zip this SD card image in the zip archive]. Extract the image <code>cspect-next-2gb.img</code> from the archive to use it, then point MAME to this SD card image with the <code>-hard1</code> option (or select that file from the menu inside MAME).

= Usage =
MAME looks for its configuration and helper files in specific (configurable) folders. By default, these are relative to the current working directory (cwd), i.e., from where you launched the executable. The <code>mame.ini</code> file and folders like <code>roms, bgfx, plugins, language, ...</code> are expected there, unless the <code>mame.ini</code> file specifies other paths. When launching through a desktop icon or menu, depending on the OS, the working directory is often defined by the properties of that launch shortcut. When launching MAME from the command line, the current directory is "cwd" (doh). On Linux, MAME will look for <code>mame.ini</code> first in the <code>~/.mame</code> folder. You can use the option <code>-inipath</code> to point MAME to a different path for the <code>mame.ini</code> file.

However, the fastest way to run a machine with a desired configuration is from the command prompt, without requiring a <code>mame.ini</code> file. Most of the features are also available through MAME's UI, although that takes more time to configure.

As an example, this invocation enables the UI, uses "crisp pixels", starts in a window, doesn't display the starting gameinfo window (it can still be displayed interactively from the UI), disables the mouse, confirms before exiting MAME, and specifies the disk image (remember to adjust the path to it):

<pre>mame -ui_active -nounevenstretch -aspect 2:1 -video bgfx -bgfx_screen_chains unfiltered -window -skip_gameinfo -mouse_device none -confirm_quit tbblue -hard1 /path/to/cspect-next-2gb.img</pre>

Let's cover some useful options:

<ol start="1">

<li>
Run inside a window and with no mouse support, until you get familiar with the UI keys:
<pre>> mame tbblue -window -mouse_device none -hard1 /path/to/next-distribution.img</pre>
To launch the Linux flatpak version using the same options:
<pre>> flatpak run org.mamedev.MAME tbblue -window -mouse_device none -hard1 /path/to/next-distribution.img</pre>
</li>

<li>
Activate UI keys on startup:
<pre>> ... -ui_active</pre>
</li>

<li>
Don't show the info popup on startup:
<pre>> ... -skip_gameinfo</pre>
</li>

<li>Run with debugger. If you don't request this on startup, you won't have access to it:
<pre>> ... -debug</pre>
</li>

<li>Use "crisp" pixels:
<pre>> ... -nounevenstretch -aspect 2:1 -video bgfx -bgfx_screen_chains unfiltered</pre>
</li>

<li>No joystick connected to PC (having this may slightly speed up MAME's startup, but ''remember to remove this part from the command line and the corresponding setting in the ini file if you do want to use a joystick''):
<pre>> ... -joystickprovider none</pre>
</li>

<li>Ask for confirmation when exiting MAME (otherwise it's easy to exit MAME accidentally by hitting ESC, especially when playing games or navigating menus):
<pre>> ... -confirm_quit</pre>
</ol>

Check the [https://docs.mamedev.org/commandline/commandline-all.html#mame-commandline-universal official MAME documentation] for more advanced usage.

= Security: Allowing MAME to Run on Windows and macOS =

'''On Windows,''' you will need to confirm that you want to launch MAME by clicking "Run Anyway" on first launch. ''(More details needed here.)''

'''On macOS,''' MAME will not open at first. Instead, a dialog will appear saying:

''“mame” Not Opened. Apple could not verify “mame” is free of malware that may harm your Mac or compromise your privacy.''

Click “Done”. Then open '''System Settings -> Privacy & Security''', and scroll down to the message ''mame was blocked to protect your Mac.'' Click “Allow Anyway”.

Now launch MAME again. A dialog will ask once more if you want to open “mame”. Click “Open Anyway”, and enter your password or use Touch ID when prompted by macOS.

From now on, you can launch this version of MAME without warnings. However, you '''will''' need to repeat this each time you update MAME.

= Keys =

Keys are emulated in two modes: either to control the MAME emulator or completely dedicated to the emulated system (the Next). You can toggle between these two keyboard modes with ScrLk (on Win and Linux) or fn+delete (on Mac).

Some UI keys:
* F3 - soft reset
* Shift+F3 - hard reset
* F4 - sprites/tiles/font viewer (Enter, ], [)
* F5 - pause emulation
* F6 - save state
* F7 - load state
* Tab - emulator settings
* ~ - menu
* ` (backtick) - debugger (when enabled by starting MAME with <code>-debug</code> or <code>-d</code> on the command line)
* PgDwn (Linux/Mac), fn-Downarrow (MacBooks) or Insert (Win) - hold down to fast-forward emulation at maximum speed, e.g., to speed up booting the Next
* Esc - exit (exits menus but also the entire emulator - see <code>-confirm_quit</code> option above)
* F11 - DivMMC NMI
* F12 - Multiface NMI

Check [https://docs.mamedev.org/usingmame/defaultkeys.html default keys documentation] for more.

= Changing the UI toggle key =

Some laptops don't have a Scroll Lock key, so you may not be able to exit MAME if you run it in full-screen mode. In these cases, you can change the UI toggle key as follows:

* Run MAME without any command line arguments (except maybe -window) to open its GUI.
* Push TAB and enter the General Settings menu.
* Go to Input Assignments -> User Interface -> Toggle UI controls and select a new key. I use Right Alt / Alt GR.
* Return to the previous menu twice, then choose Save Settings

= Creating a NextZXOS SD card image =

Most users wanting to emulate the Next using MAME will be fine using a pre-built SD card image downloaded from the specnext website. The following guide is provided for anyone wanting to create a NextZXOS SD card image from scratch.

Download the [https://www.specnext.com/latestdistro/ latest NextZXOS distribution zip file] (named something like sn-complete-WX.YZ.zip) and extract it into a new, empty directory.

== Creating and populating a SD card image using hdfmonkey jjjs build ==

The [[https://www.specnext.com/forum/viewtopic.php?t=2604 | <code>hdfmonkey "jjjs build"</code>]] is a variant of hdfmonkey tool which includes some unique features and its main archive (at the previously given link) also contains pre-built binaries for Windows x64, MacOS x64, MacOS Apple Silicon and Linux x64. (Alternatively, the process to build a local Linux version of the executable is described [[Development_Tools:Linux_setup#Building_the_executable_binary_2 | here]] )

If you extracted sn-complete-WX.YZ.zip into a subdirectory named <code>snWXYZ</code>, and you want to create a 1GB image called <code>NextZXOS.img</code> and you have a jjjs build" of hdfmonkey, then it's enough to do:

<pre>
hdfmonkey create NextZXOS.img 1G
hdfmonkey putdir NextZXOS.img snWXYZ /
</pre>

The first line creates an empty 1GB image and formats it with the best FAT parameters suited to the size of the image.

The second line recursively copies all the content of the directory <code>snWXYZ</code> to the image, preserving the directory structure inside, starting from the <code>/</code> in the image.

One of the advantages of this method is that even if the image has a capacity of 1GB, it will use much less space on your hard drive until you fill up the image. On Linux or MacOS, a command <code>du -h NextZXOS.img</code> shows the actual amount of disk space used by the image. On Windows the same information can be seen in the File Properties dialog.

The fastest way to transfer a file or a directory (including its content, recursively) into an image is by using a single <code>put</code> (or <code>putdir</code>, if it's to transfer the directory file content to an existing directory) command of hdfmonkey.

The most convenient tool to copy of all the content from the image to a folder outside of the image is 7-zip. On Windows, just use the 7-zip GUI. On MacOS and Linux, see: [[Development_Tools:Linux_setup#Extracting_all_files_from_the_sd-card_image]].

== Creating and populating a SD card image using Linux ==

While using hdfmonkey jjjs build works on Linux and the pre-built binary for Intel x64 exists, and using it creates an image which will have high compatibility, it is also possible to use more common Linux tools to create a SD image. Note however that the resulting image of this method, if the parameters of different steps aren't carefully chosen and matched, could be out of the official FAT specifications and/or the expectations of some of the existing programs or systems. This method creates an image which is incompatible with the current (as of 2025-12-13) CSpect version, at least for some sizes of the image:

Create a disk image of at least 256 MB. The current complete NextZXOS distro requires at least 130 MB of disk space. This command will create a 256 MB SD card image; change the <code>count</code> value to make the image file as big as you want in megabytes:

<pre>dd if=/dev/zero of=NextZXOS.img bs=1M count=256</pre>

The rest of the commands in this guide must be run as the root user or using sudo.

You will need to install the dosfstools and parted packages if they are not already installed. Debian and Ubuntu Linux users can install these using this apt command:

<pre>apt install dosfstools parted</pre>

Mount the SD card image loopback device:

<pre>losetup --partscan --show --find NextZXOS.img</pre>

Create a FAT32 partition:

<pre>parted /dev/loop0 mklabel msdos
parted /dev/loop0 mkpart primary fat32 1MB 100%</pre>

Format and mount the partition under /mnt:

<pre>mkfs.vfat -F 32 /dev/loop0p1
mount /dev/loop0p1 /mnt</pre>

You can now copy all of the files you extracted from sn-complete-WX.YZ.zip into /mnt.

After copying the files, unmount and detach the loopback device (the SD card image):

<pre>umount /mnt/
losetup -D</pre>

= Mounting SD card images under Linux =

Under Linux, you can use <code>losetup</code> to mount SD card images as loop devices. This lets you copy files to and from the image and perform other file management tasks as you would using any other filesystem.

Run the following commands as the root user to mount an image called sn-emulator-22.10a.img under the /mnt directory:

<pre>losetup --partscan --show --find cspect-next-2gb.img
mount /dev/loop0p1 /mnt/</pre>

After you are finished modifying the SD card image, cd out of /mnt, then unmount and detach the loopback device:

<pre>umount /mnt/
losetup -D</pre>

=MAME Plugins and Scripts=

Some MAME plugins and scripts that may be useful for Next developers and end users are listed [[MAME:Plugins_and_Scripts|here]]. They let you speed up the Next boot time, profile your NextBASIC or assembler code, and more.

=Continuous Integration MAME Builds=

MAME is updated on a release schedule, but due to the ongoing nature of development, including for the MAME Next machine, it can sometimes be useful to install a more recent build if it contains a new feature or bugfix you are interested in. Sometimes, this ongoing work is discussed on social media, such as the [https://discordapp.com/channels/556228195767156758/752197165891321886 Next Developer Discord].

Continuous Integration (CI) builds are available from both the [https://github.com/mamedev/mame/actions primary MAME repo] and [https://github.com/holub/mame/actions holub's GitHub repo]. Both are considered bleeding-edge, with the primary MAME repo slightly less so. MAME CI builds are available for Windows, Linux, and macOS and are updated automatically whenever code is committed by a maintainer or pushed to the primary repo.

To try out a CI build (more precisely, the resulting binary executable, which is a produced "artifact" of the build process) , first do a full MAME install from the [https://www.mamedev.org/release.html latest release] if you have not already done so. Then back up your main binary from its installation location - these are called something like <code>mame.exe</code> or <code>mame</code>. You can always restore these if the CI build doesn't work, or if you don't like how it behaves.

'''You need to be logged in to github''' to download CI artifacts, so [https://github.com/login sign in] or [https://github.com/signup sign up].

Then visit one of the links above and find a workflow run item for your platform. Workflow items are the things in the list. The tags are flagged as <code>CI (Windows)</code>, <code>CI (Linux)</code>, or <code>CI (macOS)</code> in the second row of each workflow item in the list (not the filter in the left hand nav menu). Click on a completed workfow item (only items with green checkmarks will have created downloadable binaries yet), find the Artifacts section at the bottom, then click the Download button. Unzip the downloaded file and find the main binary (with the same name as above). Copy the main binary to the install location, overwriting the original one, and run MAME the same way you were running it before. On Windows and macOS, you need to repeat the security steps above to trust the new MAME executable.

= More MAME links =

MAME [https://docs.mamedev.org/ documentation].

Report any issues with MAME on the [https://mametesters.org/ bugtracker].

Development Tools:Linux setup

2025-12-22T20:05:19Z

Ped7g: unifying usage of tags and terms in main titles

Sprites

2025-12-22T17:33:51Z

Ped7g: Refresh info about incomplete sprite rendering

The Spectrum Next has a hardware sprite system with the following characteristics:

* Total of 128 sprites
* Display surface is 320×256 overlapping the ULA screen by 32 pixels on each side
* Minimum of 100 sprites per scanline&dagger;
* Choice of 512 colours for each pixel
* Size of each sprite is 16×16 pixels but sprites can be magnified 2x, 4x or 8x horizontally and vertically
* Sprites can be mirrored and rotated
* Sprites can be grouped together to form larger sprites under the control of a single anchor
* A 16K pattern memory can contain 64 8-bit sprite images or 128 4-bit sprite images and combinations in-between
* A per sprite palette offset allows sprites to share images but colour them differently
* A nextreg interface allows the copper to move sprites during the video frame

&dagger; A minimum of 100 16×16 (at 1x scale) sprites is guaranteed to be displayed in any scanline. <s>Any additional sprites will not be displayed with the hardware ensuring sprites are not partially plotted.</s> Since core 3.02.02 the HW keeps drawing until full pixel bandwidth is exhausted including incomplete span of sprite. Before core 3.02.02 there was bug in the code preventing incomplete draws, causing less than 100 sprites being shown per line.

The actual limit is determined by how many 28MHz clock cycles there are in a scanline. The sprite hardware is able to plot one pixel cycle and uses one cycle to qualify each sprite. Since the number of cycles there are in a scanline varies with video timing (HDMI, VGA), the number of pixels that can be plotted also varies but the minimum will be 1600 pixels per line including overhead cycles needed to qualify 100 sprites. Since sprites magnified horizontally involve plotting more pixels, x2 x4 x8 sprites will take more cycles to plot and the presence of these sprites in a line will reduce the total number of sprites that can be plotted.

== Sprite Patterns ==
Sprite patterns are the images that each sprite can take on. The images are stored in a 16K memory internal to the FPGA and are identified by pattern number. A particular sprite chooses a pattern by storing a pattern number in its attributes.

All sprites are 16×16 pixels in size but the come in two flavours: 4-bit and 8-bit. The bit width describes how many bits are used to code the colour of each pixel.

An 8-bit sprite uses a full byte to colour each of its pixels so that each pixel can be one of 256 colours. In this case, a 16×16 sprite requires 256 bytes of pattern memory to store its image.

A 4-bit sprite uses a nibble to colour each of its pixels so that each pixel can be one of 16 colours. In this case, a 16×16 sprite requires just 128 bytes of pattern memory to store its image.

The 16K pattern memory can contain any combination of these images, whether they are 128 bytes or 256 bytes and their locations in the pattern memory are described by a pattern number. This pattern number is 7 bits with bits named as follows:

=== Pattern Number ===
<pre>N5 N4 N3 N2 N1 N0 N6
N6, despite the name, is the least significant bit.</pre>

This 7-bit pattern number can identify 128 patterns in the 16k pattern memory, each of which are 128 bytes in size. The full 7-bits are therefore used for 4-bit sprites.

For 8-bit sprites, N6=0 always. The remaining 6 bits can identify 64 patterns, each of which is 256 bytes in size.

The N5:N0,N6 bits are stored in a particular sprite’s attributes to identify which image a sprite uses.

=== 8-Bit Sprite Patterns ===
The 16×16 pixel image uses 8-bits for each pixel so that each pixel can be one of 256 colours. One colour indicates transparency and this is programmed into the Sprite Transparency Index register (nextreg 0x4B). By default the transparent index is 0xE3.

As an example of an 8-bit sprite, let’s have a look at the sprite below:

[[File:Sprite_1.png|frame|center|Pattern example]]

Using the default palette, which is initialised with RGB332 colours from 0-255, the hexadecimal values for this pattern arranged in a 16×16 array are shown below:

<pre>04040404040404E3E3E3E3E3E3E3E3E3
04FFFFFFFFFF04E3E3E3E3E3E3E3E3E3
04FFFBFBFBFF04E3E3E3E3E3E3E3E3E3
04FFFBF5F5FBFF04E3E3E3E3E3E3E3E3
04FFFBF5A8A8FBFF04E3E3E3E3E3E3E3
04FFFFFBA844A8FBFF04E3E3E3E3E3E3
040404FFFBA844A8FBFF04E3E3E3E3E3
E3E3E304FFFBA84444FBFF04E304E3E3
E3E3E3E304FFFB444444FBFF044D04E3
E3E3E3E3E304FFFB44444444FA4D04E3
E3E3E3E3E3E304FFFB44FFF54404E3E3
E3E3E3E3E3E3E304FF44F5A804E3E3E3
E3E3E3E3E3E3E3E304FA4404A804E3E3
E3E3E3E3E3E3E3044D4D04E304F504E3
E3E3E3E3E3E3E3E30404E3E3E304FA04
E3E3E3E3E3E3E3E3E3E3E3E3E3E30404</pre>

Here 0xE3 is used as the transparent index.

These 256 bytes would be stored in pattern memory in left to right, top to bottom order.

=== 4-Bit Sprite Patterns ===
The 16×16 pixel image uses 4-bits for each pixel so that each pixel can be one of 16 colours. One colour indicates transparency and this is programmed into the lower 4-bits of the Sprite Transparency Index register (nextreg 0x4B). By default the transparency value is 0x3. Note that the same register is shared with 8-bit patterns to identify the transparent index.

Since each pixel only occupies 4-bits, two pixels are stored in each byte. The leftmost pixel is stored in the upper 4-bits and the rightmost pixel is stored in the lower 4-bits.

As an example we will use the same sprite image as was given in the 8-bit pattern example. Here only the lower 4 bits of each pixel is retained to confine each pixel’s colour to 4-bits:

<pre>4444444333333333
4FFFFF4333333333
4FBBBF4333333333
4FB55BF433333333
4FB588BF43333333
4FFB848BF4333333
444FB848BF433333
3334FB844BF43433
33334FB444BF4D43
333334FB4444AD43
3333334FB4F54433
33333334F4584333
333333334A448433
33333334DD434543
33333333443334A4
3333333333333344</pre>

0x3 is used as the transparent index.

These 128 bytes would be stored in pattern memory in left to right, top to bottom order.

The actual colour that will appear on screen will depend on the palette, described below. The default palette will not likely generate suitable colours for 4-bit sprites.

=== Sprite Palette ===
Each pixel of a sprite image is 8-bit for 8-bit patterns or 4-bit for 4-bit patterns. The pixel value is known as a pixel colour index. This colour index is combined with the sprite’s palette offset. The palette offset is a 4-bit value added to the top 4-bits of the pixel colour index. The purpose of the palette offset is to allow a sprite to change the colour of an image.

The final sprite colour index generated by the sprite hardware is then the sum of the pixel index and the 4-bit palette offset. In pictures using binary math:

<pre>8-bit Sprite
PPPP0000
+ IIIIIIII
----------
SSSSSSSS

4-bit Sprite
PPPP0000
+ 0000IIII
----------
SSSSSSSS = PPPPIIII</pre>

Where “PPPP” is the 4-bit palette offset from the sprite’s attributes and the “I”s represent the pixel value from the sprite pattern. The final sprite index is represented by the 8-bit value “SSSSSSSS”.

For 4-bit sprites the palette offset can be thought of as selecting one of 16 different 16-colour palettes.

This final 8-bit sprite index is then passed through the sprite palette which acts like a lookup table that returns the 9-bit RGB333 colour associated with the sprite index.

At power up, the sprite palette is initialized such that the sprite index passes through unchanged and is therefore interpreted as an RGB332 colour. The missing third blue bit is generated as the logical OR of the two other blue bits. In short, for 8-bit sprites, the sprite index also acts like the colour when using the default palette.

=== Sprite Attributes ===
A sprite’s attributes is a list of properties that determine how and where the sprite is drawn.

Each sprite is described by either 4 or 5 attribute bytes listed below:

==== Sprite Attribute 0 ====
<pre>X X X X X X X X</pre>
The least significant eight bits of the sprite’s X coordinate. The ninth bit is found in sprite attribute 2.

==== Sprite Attribute 1 ====
<pre>Y Y Y Y Y Y Y Y</pre>
The least significant eight bits of the sprite’s Y coordinate. The ninth bit is optional and is found in attribute 4.

==== Sprite Attribute 2 ====
<pre>P P P P XM YM R X8/PR</pre>

P = 4-bit Palette Offset 
XM = 1 to mirror the sprite image horizontally 
YM = 1 to mirror the sprite image vertically 
R = 1 to rotate the sprite image 90 degrees clockwise 
X8 = Ninth bit of the sprite’s X coordinate 
PR = 1 to indicate P is relative to the anchor’s palette offset (relative sprites only)

Rotation is applied before mirroring. 
Relative sprites, described below, replace X8 with PR.

[[File:Sprite_flags.png|frame|center|All possibilities of Rotate, Mirror X and Mirror Y flags.]]

==== Sprite Attribute 3 ====
<pre>V E N5 N4 N3 N2 N1 N0</pre>
V = 1 to make the sprite visible 
E = 1 to enable attribute byte 4 
N = Sprite pattern to use 0-63

If E=0, the sprite is fully described by sprite attributes 0-3. The sprite pattern is an 8-bit one identified by pattern N=0-63. The sprite is an anchor and cannot be made relative. The sprite is displayed as if sprite attribute 4 is zero.

If E=1, the sprite is further described by sprite attribute 4.

==== Sprite Attribute 4 ====
===== A. Extended Anchor Sprite =====
<pre>H N6 T X X Y Y Y8</pre>
H = 1 if the sprite pattern is 4-bit 
N6 = 7th pattern bit if the sprite pattern is 4-bit 
T = 0 if relative sprites are composite type else 1 for unified type 
XX = Magnification in the X direction (00 = 1x, 01 = 2x, 10 = 4x, 11 = 8x) 
YY = Magnification in the Y direction (00 = 1x, 01 = 2x, 10 = 4x, 11 = 8x) 
Y8 = Ninth bit of the sprite’s Y coordinate

{H,N6} must not equal {0,1} as this combination is used to indicate a relative sprite.

===== B. Relative Sprite, Composite Type =====
<pre>0 1 N6 X X Y Y PO</pre>
N6 = 7th pattern bit if the sprite pattern is 4-bit 
XX = Magnification in the X direction (00 = 1x, 01 = 2x, 10 = 4x, 11 = 8x) 
YY = Magnification in the Y direction (00 = 1x, 01 = 2x, 10 = 4x, 11 = 8x) 
PO = 1 to indicate the sprite pattern number is relative to the anchor’s

===== C. Relative Sprite, Unified Type =====
<pre>0 1 N6 0 0 0 0 PO</pre>
N6 = 7th pattern bit if the sprite pattern is 4-bit 
PO = 1 to indicate the sprite pattern number is relative to the anchor’s

The display surface for sprites is 320×256. The X coordinate of the sprite is nine bits, ranging over 0-511, and the Y coordinate is optionally nine bits again ranging over 0-511 or is eight bits ranging over 0-255. The full extent 0-511 wraps on both axes, meaning a sprite 16 pixels wide plotted at X coordinate 511 would see its first pixel not displayed (coordinate 511) and the following pixels displayed in coordinates 0-14.

The full display area is visible in VGA. However, the HDMI display is vertically shorter so the top eight pixel rows (Y = 0-7) and the bottom eight pixel rows (Y = 248-255) will not be visible on an HDMI display.

Sprites can be fully described by sprite attributes 0-3 if the E bit in sprite attribute 3 is zero. These sprites are compatible with the original sprite module from core versions prior to 2.00.26.

If the E bit is set then a fifth sprite attribute, sprite attribute 4, becomes active. This attribute introduces scaling, 4-bit patterns, and relative sprites. Scaling is self-explanatory and 4-bit patterns were described in the last section. Relative sprites are described in the next section.

=== Relative Sprites ===
Normal sprites (sprites that are not relative) are known as anchor sprites. As the sprite module draws sprites in the order 0-127 (there are 128 sprites), it internally stores characteristics of the last anchor sprite seen. If following sprites are relative, they inherit some of these characteristics, which allows relative sprites to have, among other things, coordinates relative to the anchor. This means moving the anchor sprite also causes its relatives to move with it.

There are two types of relative sprites supported known as “Composite Sprites” and “Unified Sprites”. The type is determined by the anchor in the T bit of sprite attribute 4.

==== A. Composite Sprites ====
The sprite module records the following information from the anchor:

* Anchor.visible
* Anchor.X
* Anchor.Y
* Anchor.palette_offset
* Anchor.N (pattern number)
* Anchor.H (indicates if the sprite uses 4-bit patterns)

These recorded items are not used by composite sprites:

* Anchor.rotate
* Anchor.xmirror
* Anchor.ymirror
* Anchor.xscale
* Anchor.yscale

The anchor determines if all its relative sprites use 4-bit patterns or not.

The visibility of a particular relative sprite is the result of ANDing the anchor’s visibility with the relative sprite’s visibility. In other words, if the anchor is invisible then so are all its relatives.

Relative sprites only have 8-bit X and Y coordinates (the ninth bits are taken for other purposes). These are signed offsets from the anchor’s X,Y coordinate. Moving the anchor moves all its relatives along with it.

If the relative sprite has its PR bit set in sprite attribute 2, then the anchor’s palette offset is added to the relative sprite’s to determine the active palette offset for the relative sprite. Otherwise the relative sprite uses its own palette offset as usual.

If the relative sprite has its PO bit set in sprite attribute 4, then the anchor’s pattern number is added to the relative sprite’s to determine the pattern used for display. Otherwise the relative sprite uses its own pattern number as usual. The intention is to supply a method to easily animate a large sprite by manipulating the pattern number in the anchor.

A composite sprite is like a collection of independent sprites tied to an anchor.

==== B. Unified Sprites ====
Unified sprites are a further extension of the composite type. The same information is recorded from the anchor and the same behaviour as described under composite sprites applies.

The difference is the collection of anchor and relatives is treated as if it were a single 16×16 sprite. The anchor’s rotation, mirror, and scaling bits apply to all its relatives. Rotating the anchor causes all the relatives to rotate around the anchor. Mirroring the anchor causes the relatives to mirror around the anchor. The sprite hardware will automatically adjust X,Y coords and rotation, scaling and mirror bits of all relatives according to settings in the anchor.

Unified sprites should be defined as if all its parts are 16×16 in size with the anchor controlling the look of the whole.

A unified sprite is like a big version of an individual 16×16 sprite controlled by the anchor.

=== Programming Sprites ===
Sprites are created via three I/O ports and a nextreg interface.

{{PortNo|$303B}} (W)

<pre>X S S S S S S S
N6 X N N N N N N</pre>

A write to this port has two effects.

One is it selects one of 128 sprites for writing sprite attributes via port 0x57.

The other is it selects one of 128 4-bit patterns in pattern memory for writing sprite patterns via port 0x5B. The N6 bit shown is the least significant in the 7-bit pattern number and should always be zero when selecting one of 64 8-bit patterns indicated by N.

{{PortNo|$xx57}} (W)

Once a sprite is selected via port 0x303B, its attributes can be written to this port one byte after another. Sprites can have either four or five attribute bytes and the internal attribute pointer will move onto the next sprite after those four or five attribute bytes are written. This means you can select a sprite via port 0x303B and write attributes for as many sequential sprites as desired. The attribute pointer will roll over from sprite 127 to sprite 0.

{{PortNo|$xx5B}} (W)

Once a pattern number is selected via port 0x303B, the 256-byte or 128-byte pattern can be written to this port. The internal pattern pointer auto-increments after each write so as many sequential patterns as desired can be written. The internal pattern pointer will roll over from pattern 127 to pattern 0 (4-bit patterns) or from pattern 63 to pattern 0 (8-bit patterns) automatically.

{{PortNo|$303B}} (R)

<pre>0 0 0 0 0 0 M C</pre>

M = 1 if the maximum number of sprites per line was exceeded 
C = 1 if any two displayed sprites collide on screen

Reading this port automatically resets the M and C bits.

Besides the i/o interface, there is a nextreg interface to sprite attributes. The nextreg interface allows the copper to manipulate sprites and grants the program random access to a sprite’s individual attribute bytes.

(R/W) 0x34 (52) => Sprite Number 
If the sprite number is in lockstep with io port 0x303B (nextreg 0x09 bit 4 is set) 
bits 7 = Pattern address offset (Add 128 to pattern address) 
bits 6-0 = Sprite number 0-127, Pattern number 0-63 
Selects which sprite has its attributes connected to the following registers. 
Effectively performs an out to port 0x303B with the same value 
Otherwise 
bit 7 = Ignored 
bits 6-0 = Sprite number 0-127 
Selects which sprite has its attributes connected to the following registers. 
Bit 7 always reads back as zero.

This nextreg can operate in two modes.

If nextreg 0x09 bit 4 is set, then this register is kept in lockstep with i/o port 0x303B. A write to this nextreg is equivalent to a write to port 0x303B and vice versa. In this mode, the i/o interface and nextreg interface are exactly equivalent.

If nextreg 0x09 bit 4 is reset, then the nextreg interface is decoupled from i/o port 0x303B. This nextreg is used to select a particular sprite 0-127 and this is completely independent from the sprite selected for the i/o interface. This independence allows the copper, for example, to manipulate different sprites than the cpu using the i/o interface.

(W) 0x35 (53) => Sprite Attribute 0 
(W) 0x75 (117) => Sprite Attribute 0 with automatic post increment of Sprite Number 
bits 7-0 = LSB of X coordinate

A write to nextreg 0x75 also increases the selected sprite in nextreg 0x34.

(W) 0x36 (54) => Sprite Attribute 1 
(W) 0x76 (118) => Sprite Attribute 1 with automatic post increment of Sprite Number 
bits 7-0 = LSB of Y coordinate

A write to nextreg 0x76 also increases the selected sprite in nextreg 0x34.

(W) 0x37 (55) => Sprite Attribute 2 
(W) 0x77 (119) => Sprite Attribute 2 with automatic post increment of Sprite Number 
bits 7-4 = Palette offset added to top 4 bits of sprite colour index 
bit 3 = X mirror 
bit 2 = Y mirror 
bit 1 = Rotate 
bit 0 = MSB of X coordinate

A write to nextreg 0x77 also increases the selected sprite in nextreg 0x34.

(W) 0x38 (56) => Sprite Attribute 3 
(W) 0x78 (120) => Sprite Attribute 3 with automatic post increment of Sprite Number 
bit 7 = Visible flag (1 = displayed) 
bit 6 = Extended attribute (1 = Sprite Attribute 4 is active) 
bits 5-0 = Pattern used by sprite (0-63)

A write to nextreg 0x78 also increases the selected sprite in nextreg 0x34.

(W) 0x39 (57) => Sprite Attribute 4 
(W) 0x79 (121) => Sprite Attribute 4 with automatic post increment of Sprite Number 
4-bit Sprites 
bit 7 = H (1 = sprite uses 4-bit patterns) 
bit 6 = N6 (0 = use the first 128 bytes of the pattern else use the last 128 bytes) 
bit 5 = 1 if relative sprites are composite, 0 if relative sprites are unified 
Scaling 
bits 4-3 = X scaling (00 = 1x, 01 = 2x, 10 = 4x, 11 = 8x) 
bits 2-1 = Y scaling (00 = 1x, 01 = 2x, 10 = 4x, 11 = 8x) 
bit 0 = MSB of Y coordinate 
A relative mode is enabled if H,N6 = 01. The byte format for relative sprites is described above.

A write to nextreg 0x79 also increases the selected sprite in nextreg 0x34.

=== Global Control of Sprites ===
The following nextreg are also of interest for sprites.

{{NextRegNo|$09}} (09) 
bit 7 = Mono setting for AY 2 (1 = mono, 0 default) 
bit 6 = Mono setting for AY 1 (1 = mono, 0 default) 
bit 5 = Mono setting for AY 0 (1 = mono, 0 default) 
bit 4 = Sprite id lockstep (1 = Nextreg 0x34 and IO Port 0x303B are in lockstep, 0 default) 
bit 3 = Disables Kempston port ($DF) if set 
bit 2 = Disables divMMC ports ($E3, $E7, $EB) if set 
bits 1-0 = scanlines (0 after a PoR or Hard-reset) 
00 = scanlines off 
01 = scanlines 75% 
10 = scanlines 50% 
11 = scanlines 25%

Bit 4 determines if the i/o interface and nextreg interface operate in lockstep.

{{NextRegNo|$15}} (21) 
bit 7 = LoRes mode, 128 x 96 x 256 colours (1 = enabled) 
bit 6 = Sprite priority (1 = sprite 0 on top, 0 = sprite 127 on top) 
bit 5 = Enable sprite clipping in over border mode (1 = enabled) 
bits 4-2 = set layers priorities: 
Reset default is 000, sprites over the Layer 2, over the ULA graphics 
000 – S L U 
001 – L S U 
010 – S U L 
011 – L U S 
100 – U S L 
101 – U L S 
110 – S(U+L) ULA and Layer 2 combined, colours clamped to 7 
111 – S(U+L-5) ULA and Layer 2 combined, colours clamped to [0,7] 
bit 1 = Over border (1 = yes) (Back to 0 after a reset) 
bit 0 = Sprites visible (1 = visible) (Back to 0 after a reset)

Bit 0 must be set for sprites to be visible.

Bit 1 set allows sprites to be visible in the border area. When this bit is reset, sprites will not display outside the 256×192 area of the ULA display.

Bit 5 set enables clipping when sprites are visible in the border area. If reset, no clipping is applied and sprites will be visible in the full 320×256 space.

The sprite module draws sprites in the order 0-127 in each scanline. Bit 6 determines whether sprite 0 is topmost or sprite 127 is topmost.

Bits 4:2 determine layer priority and how sprites overlay or are obscured by other layers.

{{NextRegNo|$19}} (25) 
bits 7-0 = Coord. of the clip window 
1st write – X1 position 
2nd write – X2 position 
3rd write – Y1 position 
4rd write – Y2 position 
The values are 0,255,0,191 after a Reset 
Reads do not advance the clip position 
When the clip window is enabled for sprites in “over border” mode, the X coords are internally doubled and the clip window origin is moved to the sprite origin inside the border.

Sprites will only be visible inside the clipping window. When not in over-border mode (bit 1 of nextreg 0x15) the clipping window is given in ULA screen coordinates with 0,0 corresponding to the top left corner of the ULA screen. In over-border mode, the clipping window’s origin is moved to the sprite coordinate origin 32 pixels to the left and 32 pixels above the ULA screen origin.

Regardless, sprite position is always in sprite coordinates with 32,32 corresponding to the top left corner of the ULA screen.

{{NextRegNo|$1C}} (28) (W) 
bits 7-4 = Reserved, must be 0 
bit 3 – reset the tilemap clip index 
bit 2 – reset the ULA/LoRes clip index. 
bit 1 – reset the sprite clip index. 
bit 0 – reset the Layer 2 clip index.

Can be used to reset nextreg 0x19.

{{NextRegNo|$43}} (67) 
bit 7 = ‘1’ to disable palette write auto-increment. 
bits 6-4 = Select palette for reading or writing: 
000 = ULA first palette 
100 = ULA second palette 
001 = Layer 2 first palette 
101 = Layer 2 second palette 
010 = Sprites first palette 
110 = Sprites second palette 
011 = Tilemap first palette 
111 = Tilemap second palette 
bit 3 = Select Sprites palette (0 = first palette, 1 = second palette) 
bit 2 = Select Layer 2 palette (0 = first palette, 1 = second palette) 
bit 1 = Select ULA palette (0 = first palette, 1 = second palette) 
bit 0 = Enable ULANext mode if 1. (0 after a reset)

Sprites have two associated palettes which can be selected in this nextreg.

{{NextRegNo|$40}} (64) 
bits 7-0 = Select the palette index to change the associated colour. 
For the ULA only, INKs are mapped to indices 0-7, Bright INKS to indices 8-15, PAPERs to indices 16-23 and Bright PAPERs to indices 24-31.
In ULANext mode, INKs come from a subset of indices 0-127 and PAPERs come from
a subset of indices 128-255. The number of active indices depends on the number
of attribute bits assigned to INK and PAPER out of the attribute byte.
The ULA always takes border colour from paper.

Select the starting palette index if writing the sprite palette.

Palette values can be written in either 8-bit or 9-bit form:

{{NextRegNo|$41}} (65) 
bits 7-0 = Colour for the palette index selected by the register 0x40. 
(Format is RRRGGGBB – the lower blue bit of the 9-bit colour will be a logical OR of blue bits 1 and 0 of this 8-bit value.)
After the write, the palette index is auto-incremented to the next index if the auto-increment is enabled at reg 0x43. Reads do not auto-increment.

{{NextRegNo|$44}} (68) 
Two consecutive writes are needed to write the 9 bit colour 
1st write: 
bits 7-0 = RRRGGGBB 
2nd write. 
If writing a L2 palette 
———————————————————————– 
bit 7 = 1 for L2 priority colour, 0 for normal 
Priority colour will always be on top even on an SLU priority arrangement. If you need the exact same colour on priority and non priority locations you will need to program the same colour twice changing bit 7 to 0 for the second colour 
bits 6-1 = Reserved, must be 0 
bit 0 = lsb B

If writing another palette 
———————————————————————– 
bits 7-1 = Reserved, must be 0 
bit 0 = lsb B

After the two consecutive writes the palette index is auto-incremented if the auto-increment is enabled by reg 0x43.

Reads only return the 2nd byte and do not auto-increment.

{{NextRegNo|$4B}} (75) 
bits 7-0 = Set the index value (0xE3 after reset) 
For 4-bit sprites only the bottom 4-bits are relevant.

Determines the transparent colour index used for sprites.

MAME:Installing

2025-12-22T01:50:11Z

Ped7g: Adding url to MAME docs with default keys

[https://www.mamedev.org/ MAME] (formerly an acronym of Multiple Arcade Machine Emulator) is a free and open-source emulator designed to emulate the hardware of arcade games, later expanded to include video game consoles, old computers and other systems in software on modern personal computers and other platforms.

MAME has supported the ZX Spectrum Next since version 0.267. The existing implementation is based on the v3.02.01 core and implements most of the features.

= Installation =

You will need to install MAME, provide it with the Next firmware ('ROM'), and get the NextZXOS image:

=== 1. Get MAME ===
Start with these official MAME releases. If you encounter crashes or other bugs, try replacing the MAME executable with holub's latest Continuous Integration (CI) builds as described at the end of this article.

* '''Windows:''' Download [https://www.mamedev.org/release.html MAME for Windows].
* '''macOS:''' Download [https://sdlmame.lngn.net/ MAME for macOS].
* '''Linux:''' Install MAME from the flatpak repositories by running:
<pre>sudo flatpak install org.mamedev.MAME</pre>

Note that Windows and macOS will likely prevent you from launching MAME directly for security reasons. See below on how to solve this.

Alternatively, for the MAME platform as a whole, you can also check your package manager, or [https://docs.mamedev.org/initialsetup/compilingmame.html build from sources].

Git of official MAME: [https://github.com/mamedev/mame/ https://github.com/mamedev/mame/] [https://github.com/mamedev/mame/blob/master/src/mame/sinclair/specnext.cpp specnext.cpp]

Git of holub's fork: [https://github.com/holub/mame https://github.com/holub/mame] [https://github.com/holub/mame/blob/master/src/mame/sinclair/specnext.cpp specnext.cpp] (may contain extra fixes and features before they are merged to official repository)

=== 2. Get TBBLUE (the Next 'boot ROM') ===
Put the file [https://github.com/Threetwosevensixseven/NexCreator/raw/master/bootroms/tbblue.zip tbblue.zip] into MAME's <code>roms</code> folder. Don't extract it; MAME will look for the zip file when the "tbblue" machine is selected.

Note: The ROMs in this zip are what is embedded inside the FPGA core on real Next hardware. They're different from any ZX Spectrum machine ROMs you may be used to using, that are on the distro, SD card or SD image file.

=== 3. Get the NextZXOS Image ===
Get an SD card image file of [https://www.specnext.com/latestdistro/ NextZXOS]. Note that currently some published disk images on the official SpecNext.com site (the <code>latestdistro</code> link points to the official location where the latest distribution can be found) do not work with some emulators, but all images from <code>https://zxnext.uk/hosted/</code> work with both MAME and CSpect, like [https://zxnext.uk/hosted/index_files/hdfimages/cspect-next-2gb.zip this SD card image in the zip archive]. Extract the image <code>cspect-next-2gb.img</code> from the archive to use it, then point MAME to this SD card image with the <code>-hard1</code> option (or select that file from the menu inside MAME).

= Usage =
MAME looks for its configuration and helper files in specific (configurable) folders. By default, these are relative to the current working directory (cwd), i.e., from where you launched the executable. The <code>mame.ini</code> file and folders like <code>roms, bgfx, plugins, language, ...</code> are expected there, unless the <code>mame.ini</code> file specifies other paths. When launching through a desktop icon or menu, depending on the OS, the working directory is often defined by the properties of that launch shortcut. When launching MAME from the command line, the current directory is "cwd" (doh). On Linux, MAME will look for <code>mame.ini</code> first in the <code>~/.mame</code> folder. You can use the option <code>-inipath</code> to point MAME to a different path for the <code>mame.ini</code> file.

However, the fastest way to run a machine with a desired configuration is from the command prompt, without requiring a <code>mame.ini</code> file. Most of the features are also available through MAME's UI, although that takes more time to configure.

As an example, this invocation enables the UI, uses "crisp pixels", starts in a window, doesn't display the starting gameinfo window (it can still be displayed interactively from the UI), disables the mouse, confirms before exiting MAME, and specifies the disk image (remember to adjust the path to it):

<pre>mame -ui_active -nounevenstretch -aspect 2:1 -video bgfx -bgfx_screen_chains unfiltered -window -skip_gameinfo -mouse_device none -confirm_quit tbblue -hard1 /path/to/cspect-next-2gb.img</pre>

Let's cover some useful options:

<ol start="1">

<li>
Run inside a window and with no mouse support, until you get familiar with the UI keys:
<pre>> mame tbblue -window -mouse_device none -hard1 /path/to/next-distribution.img</pre>
To launch the Linux flatpak version using the same options:
<pre>> flatpak run org.mamedev.MAME tbblue -window -mouse_device none -hard1 /path/to/next-distribution.img</pre>
</li>

<li>
Activate UI keys on startup:
<pre>> ... -ui_active</pre>
</li>

<li>
Don't show the info popup on startup:
<pre>> ... -skip_gameinfo</pre>
</li>

<li>Run with debugger. If you don't request this on startup, you won't have access to it:
<pre>> ... -debug</pre>
</li>

<li>Use "crisp" pixels:
<pre>> ... -nounevenstretch -aspect 2:1 -video bgfx -bgfx_screen_chains unfiltered</pre>
</li>

<li>No joystick connected to PC (having this may slightly speed up MAME's startup, but ''remember to remove this part from the command line and the corresponding setting in the ini file if you do want to use a joystick''):
<pre>> ... -joystickprovider none</pre>
</li>

<li>Ask for confirmation when exiting MAME (otherwise it's easy to exit MAME accidentally by hitting ESC, especially when playing games or navigating menus):
<pre>> ... -confirm_quit</pre>
</ol>

Check the [https://docs.mamedev.org/commandline/commandline-all.html#mame-commandline-universal official MAME documentation] for more advanced usage.

= Security: Allowing MAME to Run on Windows and macOS =

'''On Windows,''' you will need to confirm that you want to launch MAME by clicking "Run Anyway" on first launch. ''(More details needed here.)''

'''On macOS,''' MAME will not open at first. Instead, a dialog will appear saying:

''“mame” Not Opened. Apple could not verify “mame” is free of malware that may harm your Mac or compromise your privacy.''

Click “Done”. Then open '''System Settings -> Privacy & Security''', and scroll down to the message ''mame was blocked to protect your Mac.'' Click “Allow Anyway”.

Now launch MAME again. A dialog will ask once more if you want to open “mame”. Click “Open Anyway”, and enter your password or use Touch ID when prompted by macOS.

From now on, you can launch this version of MAME without warnings. However, you '''will''' need to repeat this each time you update MAME.

= Keys =

Keys are emulated in two modes: either to control the MAME emulator or completely dedicated to the emulated system (the Next). You can toggle between these two keyboard modes with ScrLk (on Win and Linux) or fn+delete (on Mac).

Some UI keys:
* F3 - soft reset
* Shift+F3 - hard reset
* F4 - sprites/tiles/font viewer (Enter, ], [)
* F5 - pause emulation
* F6 - save state
* F7 - load state
* Tab - emulator settings
* ~ - menu
* ` (backtick) - debugger (when enabled by starting MAME with <code>-debug</code> or <code>-d</code> on the command line)
* PgDwn (Linux/Mac), fn-Downarrow (MacBooks) or Insert (Win) - hold down to fast-forward emulation at maximum speed, e.g., to speed up booting the Next
* Esc - exit (exits menus but also the entire emulator - see <code>-confirm_quit</code> option above)
* F11 - DivMMC NMI
* F12 - Multiface NMI

Check [https://docs.mamedev.org/usingmame/defaultkeys.html default keys documentation] for more.

= Changing the UI toggle key =

Some laptops don't have a Scroll Lock key, so you may not be able to exit MAME if you run it in full-screen mode. In these cases, you can change the UI toggle key as follows:

* Run MAME without any command line arguments (except maybe -window) to open its GUI.
* Push TAB and enter the General Settings menu.
* Go to Input Assignments -> User Interface -> Toggle UI controls and select a new key. I use Right Alt / Alt GR.
* Return to the previous menu twice, then choose Save Settings

= Creating a NextZXOS SD card image =

Most users wanting to emulate the Next using MAME will be fine using a pre-built SD card image downloaded from the specnext website. The following guide is provided for anyone wanting to create a NextZXOS SD card image from scratch.

Download the [https://www.specnext.com/latestdistro/ latest NextZXOS distribution zip file] (named something like sn-complete-WX.YZ.zip) and extract it into a new, empty directory.

== Creating and populating a SD card image using hdfmonkey jjjs build ==

The [[https://www.specnext.com/forum/viewtopic.php?t=2604 | <code>hdfmonkey "jjjs build"</code>]] is a variant of hdfmonkey tool which includes some unique features and its main archive (at the previously given link) also contains pre-built binaries for Windows x64, MacOS x64, MacOS Apple Silicon and Linux x64. (Alternatively, the process to build a local Linux version of the executable is described [[Development_Tools:Linux_setup#Building_the_executable_binary_2 | here]] )

If you extracted sn-complete-WX.YZ.zip into a subdirectory named <code>snWXYZ</code>, and you want to create a 1GB image called <code>NextZXOS.img</code> and you have a jjjs build" of hdfmonkey, then it's enough to do:

<pre>
hdfmonkey create NextZXOS.img 1G
hdfmonkey putdir NextZXOS.img snWXYZ /
</pre>

The first line creates an empty 1GB image and formats it with the best FAT parameters suited to the size of the image.

The second line recursively copies all the content of the directory <code>snWXYZ</code> to the image, preserving the directory structure inside, starting from the <code>/</code> in the image.

One of the advantages of this method is that even if the image has a capacity of 1GB, it will use much less space on your hard drive until you fill up the image. On Linux or MacOS, a command <code>du -h NextZXOS.img</code> shows the actual amount of disk space used by the image. On Windows the same information can be seen in the File Properties dialog.

The fastest way to transfer a file or a directory (including its content, recursively) into an image is by using a single <code>put</code> (or <code>putdir</code>, if it's to transfer the directory file content to an existing directory) command of hdfmonkey.

The most convenient tool to copy of all the content from the image to a folder outside of the image is 7-zip. On Windows, just use the 7-zip GUI. On MacOS and Linux, see: [[Development_Tools:Linux_setup#Extracting_all_files_from_the_SD_image]].

== Creating and populating a SD card image using Linux ==

While using hdfmonkey jjjs build works on Linux and the pre-built binary for Intel x64 exists, and using it creates an image which will have high compatibility, it is also possible to use more common Linux tools to create a SD image. Note however that the resulting image of this method, if the parameters of different steps aren't carefully chosen and matched, could be out of the official FAT specifications and/or the expectations of some of the existing programs or systems. This method creates an image which is incompatible with the current (as of 2025-12-13) CSpect version, at least for some sizes of the image:

Create a disk image of at least 256 MB. The current complete NextZXOS distro requires at least 130 MB of disk space. This command will create a 256 MB SD card image; change the <code>count</code> value to make the image file as big as you want in megabytes:

<pre>dd if=/dev/zero of=NextZXOS.img bs=1M count=256</pre>

The rest of the commands in this guide must be run as the root user or using sudo.

You will need to install the dosfstools and parted packages if they are not already installed. Debian and Ubuntu Linux users can install these using this apt command:

<pre>apt install dosfstools parted</pre>

Mount the SD card image loopback device:

<pre>losetup --partscan --show --find NextZXOS.img</pre>

Create a FAT32 partition:

<pre>parted /dev/loop0 mklabel msdos
parted /dev/loop0 mkpart primary fat32 1MB 100%</pre>

Format and mount the partition under /mnt:

<pre>mkfs.vfat -F 32 /dev/loop0p1
mount /dev/loop0p1 /mnt</pre>

You can now copy all of the files you extracted from sn-complete-WX.YZ.zip into /mnt.

After copying the files, unmount and detach the loopback device (the SD card image):

<pre>umount /mnt/
losetup -D</pre>

= Mounting SD card images under Linux =

Under Linux, you can use <code>losetup</code> to mount SD card images as loop devices. This lets you copy files to and from the image and perform other file management tasks as you would using any other filesystem.

Run the following commands as the root user to mount an image called sn-emulator-22.10a.img under the /mnt directory:

<pre>losetup --partscan --show --find cspect-next-2gb.img
mount /dev/loop0p1 /mnt/</pre>

After you are finished modifying the SD card image, cd out of /mnt, then unmount and detach the loopback device:

<pre>umount /mnt/
losetup -D</pre>

=MAME Plugins and Scripts=

Some MAME plugins and scripts that may be useful for Next developers and end users are listed [[MAME:Plugins_and_Scripts|here]]. They let you speed up the Next boot time, profile your NextBASIC or assembler code, and more.

=Continuous Integration MAME Builds=

MAME is updated on a release schedule, but due to the ongoing nature of development, including for the MAME Next machine, it can sometimes be useful to install a more recent build if it contains a new feature or bugfix you are interested in. Sometimes, this ongoing work is discussed on social media, such as the [https://discordapp.com/channels/556228195767156758/752197165891321886 Next Developer Discord].

Continuous Integration (CI) builds are available from both the [https://github.com/mamedev/mame/actions primary MAME repo] and [https://github.com/holub/mame/actions holub's GitHub repo]. Both are considered bleeding-edge, with the primary MAME repo slightly less so. MAME CI builds are available for Windows, Linux, and macOS and are updated automatically whenever code is committed by a maintainer or pushed to the primary repo.

To try out a CI build (more precisely, the resulting binary executable, which is a produced "artifact" of the build process) , first do a full MAME install from the [https://www.mamedev.org/release.html latest release] if you have not already done so. Then back up your main binary from its installation location - these are called something like <code>mame.exe</code> or <code>mame</code>. You can always restore these if the CI build doesn't work, or if you don't like how it behaves.

'''You need to be logged in to github''' to download CI artifacts, so [https://github.com/login sign in] or [https://github.com/signup sign up].

Then visit one of the links above and find a workflow run item for your platform. Workflow items are the things in the list. The tags are flagged as <code>CI (Windows)</code>, <code>CI (Linux)</code>, or <code>CI (macOS)</code> in the second row of each workflow item in the list (not the filter in the left hand nav menu). Click on a completed workfow item (only items with green checkmarks will have created downloadable binaries yet), find the Artifacts section at the bottom, then click the Download button. Unzip the downloaded file and find the main binary (with the same name as above). Copy the main binary to the install location, overwriting the original one, and run MAME the same way you were running it before. On Windows and macOS, you need to repeat the security steps above to trust the new MAME executable.

= More MAME links =

MAME [https://docs.mamedev.org/ documentation].

Report any issues with MAME on the [https://mametesters.org/ bugtracker].

MAME:Installing

2025-12-22T01:45:51Z

Ped7g: moving full usage example to top of the section, the individual options explanations can follow after

[https://www.mamedev.org/ MAME] (formerly an acronym of Multiple Arcade Machine Emulator) is a free and open-source emulator designed to emulate the hardware of arcade games, later expanded to include video game consoles, old computers and other systems in software on modern personal computers and other platforms.

MAME has supported the ZX Spectrum Next since version 0.267. The existing implementation is based on the v3.02.01 core and implements most of the features.

= Installation =

You will need to install MAME, provide it with the Next firmware ('ROM'), and get the NextZXOS image:

=== 1. Get MAME ===
Start with these official MAME releases. If you encounter crashes or other bugs, try replacing the MAME executable with holub's latest Continuous Integration (CI) builds as described at the end of this article.

* '''Windows:''' Download [https://www.mamedev.org/release.html MAME for Windows].
* '''macOS:''' Download [https://sdlmame.lngn.net/ MAME for macOS].
* '''Linux:''' Install MAME from the flatpak repositories by running:
<pre>sudo flatpak install org.mamedev.MAME</pre>

Note that Windows and macOS will likely prevent you from launching MAME directly for security reasons. See below on how to solve this.

Alternatively, for the MAME platform as a whole, you can also check your package manager, or [https://docs.mamedev.org/initialsetup/compilingmame.html build from sources].

Git of official MAME: [https://github.com/mamedev/mame/ https://github.com/mamedev/mame/] [https://github.com/mamedev/mame/blob/master/src/mame/sinclair/specnext.cpp specnext.cpp]

Git of holub's fork: [https://github.com/holub/mame https://github.com/holub/mame] [https://github.com/holub/mame/blob/master/src/mame/sinclair/specnext.cpp specnext.cpp] (may contain extra fixes and features before they are merged to official repository)

=== 2. Get TBBLUE (the Next 'boot ROM') ===
Put the file [https://github.com/Threetwosevensixseven/NexCreator/raw/master/bootroms/tbblue.zip tbblue.zip] into MAME's <code>roms</code> folder. Don't extract it; MAME will look for the zip file when the "tbblue" machine is selected.

Note: The ROMs in this zip are what is embedded inside the FPGA core on real Next hardware. They're different from any ZX Spectrum machine ROMs you may be used to using, that are on the distro, SD card or SD image file.

=== 3. Get the NextZXOS Image ===
Get an SD card image file of [https://www.specnext.com/latestdistro/ NextZXOS]. Note that currently some published disk images on the official SpecNext.com site (the <code>latestdistro</code> link points to the official location where the latest distribution can be found) do not work with some emulators, but all images from <code>https://zxnext.uk/hosted/</code> work with both MAME and CSpect, like [https://zxnext.uk/hosted/index_files/hdfimages/cspect-next-2gb.zip this SD card image in the zip archive]. Extract the image <code>cspect-next-2gb.img</code> from the archive to use it, then point MAME to this SD card image with the <code>-hard1</code> option (or select that file from the menu inside MAME).

= Usage =
MAME looks for its configuration and helper files in specific (configurable) folders. By default, these are relative to the current working directory (cwd), i.e., from where you launched the executable. The <code>mame.ini</code> file and folders like <code>roms, bgfx, plugins, language, ...</code> are expected there, unless the <code>mame.ini</code> file specifies other paths. When launching through a desktop icon or menu, depending on the OS, the working directory is often defined by the properties of that launch shortcut. When launching MAME from the command line, the current directory is "cwd" (doh). On Linux, MAME will look for <code>mame.ini</code> first in the <code>~/.mame</code> folder. You can use the option <code>-inipath</code> to point MAME to a different path for the <code>mame.ini</code> file.

However, the fastest way to run a machine with a desired configuration is from the command prompt, without requiring a <code>mame.ini</code> file. Most of the features are also available through MAME's UI, although that takes more time to configure.

As an example, this invocation enables the UI, uses "crisp pixels", starts in a window, doesn't display the starting gameinfo window (it can still be displayed interactively from the UI), disables the mouse, confirms before exiting MAME, and specifies the disk image (remember to adjust the path to it):

<pre>mame -ui_active -nounevenstretch -aspect 2:1 -video bgfx -bgfx_screen_chains unfiltered -window -skip_gameinfo -mouse_device none -confirm_quit tbblue -hard1 /path/to/cspect-next-2gb.img</pre>

Let's cover some useful options:

<ol start="1">

<li>
Run inside a window and with no mouse support, until you get familiar with the UI keys:
<pre>> mame tbblue -window -mouse_device none -hard1 /path/to/next-distribution.img</pre>
To launch the Linux flatpak version using the same options:
<pre>> flatpak run org.mamedev.MAME tbblue -window -mouse_device none -hard1 /path/to/next-distribution.img</pre>
</li>

<li>
Activate UI keys on startup:
<pre>> ... -ui_active</pre>
</li>

<li>
Don't show the info popup on startup:
<pre>> ... -skip_gameinfo</pre>
</li>

<li>Run with debugger. If you don't request this on startup, you won't have access to it:
<pre>> ... -debug</pre>
</li>

<li>Use "crisp" pixels:
<pre>> ... -nounevenstretch -aspect 2:1 -video bgfx -bgfx_screen_chains unfiltered</pre>
</li>

<li>No joystick connected to PC (having this may slightly speed up MAME's startup, but ''remember to remove this part from the command line and the corresponding setting in the ini file if you do want to use a joystick''):
<pre>> ... -joystickprovider none</pre>
</li>

<li>Ask for confirmation when exiting MAME (otherwise it's easy to exit MAME accidentally by hitting ESC, especially when playing games or navigating menus):
<pre>> ... -confirm_quit</pre>
</ol>

Check the [https://docs.mamedev.org/commandline/commandline-all.html#mame-commandline-universal official MAME documentation] for more advanced usage.

= Security: Allowing MAME to Run on Windows and macOS =

'''On Windows,''' you will need to confirm that you want to launch MAME by clicking "Run Anyway" on first launch. ''(More details needed here.)''

'''On macOS,''' MAME will not open at first. Instead, a dialog will appear saying:

''“mame” Not Opened. Apple could not verify “mame” is free of malware that may harm your Mac or compromise your privacy.''

Click “Done”. Then open '''System Settings -> Privacy & Security''', and scroll down to the message ''mame was blocked to protect your Mac.'' Click “Allow Anyway”.

Now launch MAME again. A dialog will ask once more if you want to open “mame”. Click “Open Anyway”, and enter your password or use Touch ID when prompted by macOS.

From now on, you can launch this version of MAME without warnings. However, you '''will''' need to repeat this each time you update MAME.

= Keys =

Keys are emulated in two modes: either to control the MAME emulator or completely dedicated to the emulated system (the Next). You can toggle between these two keyboard modes with ScrLk (on Win and Linux) or fn+delete (on Mac).

Some UI keys:
* F3 - soft reset
* Shift+F3 - hard reset
* F4 - sprites/tiles/font viewer (Enter, ], [)
* F5 - pause emulation
* F6 - save state
* F7 - load state
* Tab - emulator settings
* ~ - menu
* ` (backtick) - debugger (when enabled by starting MAME with <code>-debug</code> or <code>-d</code> on the command line)
* PgDwn (Linux/Mac), fn-Downarrow (MacBooks) or Insert (Win) - hold down to fast-forward emulation at maximum speed, e.g., to speed up booting the Next
* Esc - exit (exits menus but also the entire emulator - see <code>-confirm_quit</code> option above)
* F11 - DivMMC NMI
* F12 - Multiface NMI

= Changing the UI toggle key =

Some laptops don't have a Scroll Lock key, so you may not be able to exit MAME if you run it in full-screen mode. In these cases, you can change the UI toggle key as follows:

* Run MAME without any command line arguments (except maybe -window) to open its GUI.
* Push TAB and enter the General Settings menu.
* Go to Input Assignments -> User Interface -> Toggle UI controls and select a new key. I use Right Alt / Alt GR.
* Return to the previous menu twice, then choose Save Settings

= Creating a NextZXOS SD card image =

Most users wanting to emulate the Next using MAME will be fine using a pre-built SD card image downloaded from the specnext website. The following guide is provided for anyone wanting to create a NextZXOS SD card image from scratch.

Download the [https://www.specnext.com/latestdistro/ latest NextZXOS distribution zip file] (named something like sn-complete-WX.YZ.zip) and extract it into a new, empty directory.

== Creating and populating a SD card image using hdfmonkey jjjs build ==

The [[https://www.specnext.com/forum/viewtopic.php?t=2604 | <code>hdfmonkey "jjjs build"</code>]] is a variant of hdfmonkey tool which includes some unique features and its main archive (at the previously given link) also contains pre-built binaries for Windows x64, MacOS x64, MacOS Apple Silicon and Linux x64. (Alternatively, the process to build a local Linux version of the executable is described [[Development_Tools:Linux_setup#Building_the_executable_binary_2 | here]] )

If you extracted sn-complete-WX.YZ.zip into a subdirectory named <code>snWXYZ</code>, and you want to create a 1GB image called <code>NextZXOS.img</code> and you have a jjjs build" of hdfmonkey, then it's enough to do:

<pre>
hdfmonkey create NextZXOS.img 1G
hdfmonkey putdir NextZXOS.img snWXYZ /
</pre>

The first line creates an empty 1GB image and formats it with the best FAT parameters suited to the size of the image.

The second line recursively copies all the content of the directory <code>snWXYZ</code> to the image, preserving the directory structure inside, starting from the <code>/</code> in the image.

One of the advantages of this method is that even if the image has a capacity of 1GB, it will use much less space on your hard drive until you fill up the image. On Linux or MacOS, a command <code>du -h NextZXOS.img</code> shows the actual amount of disk space used by the image. On Windows the same information can be seen in the File Properties dialog.

The fastest way to transfer a file or a directory (including its content, recursively) into an image is by using a single <code>put</code> (or <code>putdir</code>, if it's to transfer the directory file content to an existing directory) command of hdfmonkey.

The most convenient tool to copy of all the content from the image to a folder outside of the image is 7-zip. On Windows, just use the 7-zip GUI. On MacOS and Linux, see: [[Development_Tools:Linux_setup#Extracting_all_files_from_the_SD_image]].

== Creating and populating a SD card image using Linux ==

While using hdfmonkey jjjs build works on Linux and the pre-built binary for Intel x64 exists, and using it creates an image which will have high compatibility, it is also possible to use more common Linux tools to create a SD image. Note however that the resulting image of this method, if the parameters of different steps aren't carefully chosen and matched, could be out of the official FAT specifications and/or the expectations of some of the existing programs or systems. This method creates an image which is incompatible with the current (as of 2025-12-13) CSpect version, at least for some sizes of the image:

Create a disk image of at least 256 MB. The current complete NextZXOS distro requires at least 130 MB of disk space. This command will create a 256 MB SD card image; change the <code>count</code> value to make the image file as big as you want in megabytes:

<pre>dd if=/dev/zero of=NextZXOS.img bs=1M count=256</pre>

The rest of the commands in this guide must be run as the root user or using sudo.

You will need to install the dosfstools and parted packages if they are not already installed. Debian and Ubuntu Linux users can install these using this apt command:

<pre>apt install dosfstools parted</pre>

Mount the SD card image loopback device:

<pre>losetup --partscan --show --find NextZXOS.img</pre>

Create a FAT32 partition:

<pre>parted /dev/loop0 mklabel msdos
parted /dev/loop0 mkpart primary fat32 1MB 100%</pre>

Format and mount the partition under /mnt:

<pre>mkfs.vfat -F 32 /dev/loop0p1
mount /dev/loop0p1 /mnt</pre>

You can now copy all of the files you extracted from sn-complete-WX.YZ.zip into /mnt.

After copying the files, unmount and detach the loopback device (the SD card image):

<pre>umount /mnt/
losetup -D</pre>

= Mounting SD card images under Linux =

Under Linux, you can use <code>losetup</code> to mount SD card images as loop devices. This lets you copy files to and from the image and perform other file management tasks as you would using any other filesystem.

Run the following commands as the root user to mount an image called sn-emulator-22.10a.img under the /mnt directory:

<pre>losetup --partscan --show --find cspect-next-2gb.img
mount /dev/loop0p1 /mnt/</pre>

After you are finished modifying the SD card image, cd out of /mnt, then unmount and detach the loopback device:

<pre>umount /mnt/
losetup -D</pre>

=MAME Plugins and Scripts=

Some MAME plugins and scripts that may be useful for Next developers and end users are listed [[MAME:Plugins_and_Scripts|here]]. They let you speed up the Next boot time, profile your NextBASIC or assembler code, and more.

=Continuous Integration MAME Builds=

MAME is updated on a release schedule, but due to the ongoing nature of development, including for the MAME Next machine, it can sometimes be useful to install a more recent build if it contains a new feature or bugfix you are interested in. Sometimes, this ongoing work is discussed on social media, such as the [https://discordapp.com/channels/556228195767156758/752197165891321886 Next Developer Discord].

Continuous Integration (CI) builds are available from both the [https://github.com/mamedev/mame/actions primary MAME repo] and [https://github.com/holub/mame/actions holub's GitHub repo]. Both are considered bleeding-edge, with the primary MAME repo slightly less so. MAME CI builds are available for Windows, Linux, and macOS and are updated automatically whenever code is committed by a maintainer or pushed to the primary repo.

To try out a CI build (more precisely, the resulting binary executable, which is a produced "artifact" of the build process) , first do a full MAME install from the [https://www.mamedev.org/release.html latest release] if you have not already done so. Then back up your main binary from its installation location - these are called something like <code>mame.exe</code> or <code>mame</code>. You can always restore these if the CI build doesn't work, or if you don't like how it behaves.

'''You need to be logged in to github''' to download CI artifacts, so [https://github.com/login sign in] or [https://github.com/signup sign up].

Then visit one of the links above and find a workflow run item for your platform. Workflow items are the things in the list. The tags are flagged as <code>CI (Windows)</code>, <code>CI (Linux)</code>, or <code>CI (macOS)</code> in the second row of each workflow item in the list (not the filter in the left hand nav menu). Click on a completed workfow item (only items with green checkmarks will have created downloadable binaries yet), find the Artifacts section at the bottom, then click the Download button. Unzip the downloaded file and find the main binary (with the same name as above). Copy the main binary to the install location, overwriting the original one, and run MAME the same way you were running it before. On Windows and macOS, you need to repeat the security steps above to trust the new MAME executable.

= More MAME links =

MAME [https://docs.mamedev.org/ documentation].

Report any issues with MAME on the [https://mametesters.org/ bugtracker].

MAME:Installing

2025-12-22T01:42:22Z

Ped7g: Moving git urls also to "1. Get MAME" section, I want them here to find them quickly

[https://www.mamedev.org/ MAME] (formerly an acronym of Multiple Arcade Machine Emulator) is a free and open-source emulator designed to emulate the hardware of arcade games, later expanded to include video game consoles, old computers and other systems in software on modern personal computers and other platforms.

MAME has supported the ZX Spectrum Next since version 0.267. The existing implementation is based on the v3.02.01 core and implements most of the features.

= Installation =

You will need to install MAME, provide it with the Next firmware ('ROM'), and get the NextZXOS image:

=== 1. Get MAME ===
Start with these official MAME releases. If you encounter crashes or other bugs, try replacing the MAME executable with holub's latest Continuous Integration (CI) builds as described at the end of this article.

* '''Windows:''' Download [https://www.mamedev.org/release.html MAME for Windows].
* '''macOS:''' Download [https://sdlmame.lngn.net/ MAME for macOS].
* '''Linux:''' Install MAME from the flatpak repositories by running:
<pre>sudo flatpak install org.mamedev.MAME</pre>

Note that Windows and macOS will likely prevent you from launching MAME directly for security reasons. See below on how to solve this.

Alternatively, for the MAME platform as a whole, you can also check your package manager, or [https://docs.mamedev.org/initialsetup/compilingmame.html build from sources].

Git of official MAME: [https://github.com/mamedev/mame/ https://github.com/mamedev/mame/] [https://github.com/mamedev/mame/blob/master/src/mame/sinclair/specnext.cpp specnext.cpp]

Git of holub's fork: [https://github.com/holub/mame https://github.com/holub/mame] [https://github.com/holub/mame/blob/master/src/mame/sinclair/specnext.cpp specnext.cpp] (may contain extra fixes and features before they are merged to official repository)

=== 2. Get TBBLUE (the Next 'boot ROM') ===
Put the file [https://github.com/Threetwosevensixseven/NexCreator/raw/master/bootroms/tbblue.zip tbblue.zip] into MAME's <code>roms</code> folder. Don't extract it; MAME will look for the zip file when the "tbblue" machine is selected.

Note: The ROMs in this zip are what is embedded inside the FPGA core on real Next hardware. They're different from any ZX Spectrum machine ROMs you may be used to using, that are on the distro, SD card or SD image file.

=== 3. Get the NextZXOS Image ===
Get an SD card image file of [https://www.specnext.com/latestdistro/ NextZXOS]. Note that currently some published disk images on the official SpecNext.com site (the <code>latestdistro</code> link points to the official location where the latest distribution can be found) do not work with some emulators, but all images from <code>https://zxnext.uk/hosted/</code> work with both MAME and CSpect, like [https://zxnext.uk/hosted/index_files/hdfimages/cspect-next-2gb.zip this SD card image in the zip archive]. Extract the image <code>cspect-next-2gb.img</code> from the archive to use it, then point MAME to this SD card image with the <code>-hard1</code> option (or select that file from the menu inside MAME).

= Usage =
MAME looks for its configuration and helper files in specific (configurable) folders. By default, these are relative to the current working directory (cwd), i.e., from where you launched the executable. The <code>mame.ini</code> file and folders like <code>roms, bgfx, plugins, language, ...</code> are expected there, unless the <code>mame.ini</code> file specifies other paths. When launching through a desktop icon or menu, depending on the OS, the working directory is often defined by the properties of that launch shortcut. When launching MAME from the command line, the current directory is "cwd" (doh). On Linux, MAME will look for <code>mame.ini</code> first in the <code>~/.mame</code> folder. You can use the option <code>-inipath</code> to point MAME to a different path for the <code>mame.ini</code> file.

However, the fastest way to run a machine with a desired configuration is from the command prompt, without requiring a <code>mame.ini</code> file. Most of the features are also available through MAME's UI, although that takes more time to configure.

Let's cover some useful options:

<ol start="1">

<li>
Run inside a window and with no mouse support, until you get familiar with the UI keys:
<pre>> mame tbblue -window -mouse_device none -hard1 /path/to/next-distribution.img</pre>
To launch the Linux flatpak version using the same options:
<pre>> flatpak run org.mamedev.MAME tbblue -window -mouse_device none -hard1 /path/to/next-distribution.img</pre>
</li>

<li>
Activate UI keys on startup:
<pre>> ... -ui_active</pre>
</li>

<li>
Don't show the info popup on startup:
<pre>> ... -skip_gameinfo</pre>
</li>

<li>Run with debugger. If you don't request this on startup, you won't have access to it:
<pre>> ... -debug</pre>
</li>

<li>Use "crisp" pixels:
<pre>> ... -nounevenstretch -aspect 2:1 -video bgfx -bgfx_screen_chains unfiltered</pre>
</li>

<li>No joystick connected to PC (having this may slightly speed up MAME's startup, but ''remember to remove this part from the command line and the corresponding setting in the ini file if you do want to use a joystick''):
<pre>> ... -joystickprovider none</pre>
</li>

<li>Ask for confirmation when exiting MAME (otherwise it's easy to exit MAME accidentally by hitting ESC, especially when playing games or navigating menus):
<pre>> ... -confirm_quit</pre>
</ol>

Check the [https://docs.mamedev.org/commandline/commandline-all.html#mame-commandline-universal official MAME documentation] for more advanced usage.

As an example, this invocation enables the UI, uses "crisp pixels", starts in a window, doesn't display the starting gameinfo window (it can still be displayed interactively from the UI), disables the mouse, confirms before exiting MAME, and specifies the disk image (remember to adjust the path to it):

<pre>mame -ui_active -nounevenstretch -aspect 2:1 -video bgfx -bgfx_screen_chains unfiltered -window -skip_gameinfo -mouse_device none -confirm_quit tbblue -hard1 /path/to/cspect-next-2gb.img</pre>

= Security: Allowing MAME to Run on Windows and macOS =

'''On Windows,''' you will need to confirm that you want to launch MAME by clicking "Run Anyway" on first launch. ''(More details needed here.)''

'''On macOS,''' MAME will not open at first. Instead, a dialog will appear saying:

''“mame” Not Opened. Apple could not verify “mame” is free of malware that may harm your Mac or compromise your privacy.''

Click “Done”. Then open '''System Settings -> Privacy & Security''', and scroll down to the message ''mame was blocked to protect your Mac.'' Click “Allow Anyway”.

Now launch MAME again. A dialog will ask once more if you want to open “mame”. Click “Open Anyway”, and enter your password or use Touch ID when prompted by macOS.

From now on, you can launch this version of MAME without warnings. However, you '''will''' need to repeat this each time you update MAME.

= Keys =

Keys are emulated in two modes: either to control the MAME emulator or completely dedicated to the emulated system (the Next). You can toggle between these two keyboard modes with ScrLk (on Win and Linux) or fn+delete (on Mac).

Some UI keys:
* F3 - soft reset
* Shift+F3 - hard reset
* F4 - sprites/tiles/font viewer (Enter, ], [)
* F5 - pause emulation
* F6 - save state
* F7 - load state
* Tab - emulator settings
* ~ - menu
* ` (backtick) - debugger (when enabled by starting MAME with <code>-debug</code> or <code>-d</code> on the command line)
* PgDwn (Linux/Mac), fn-Downarrow (MacBooks) or Insert (Win) - hold down to fast-forward emulation at maximum speed, e.g., to speed up booting the Next
* Esc - exit (exits menus but also the entire emulator - see <code>-confirm_quit</code> option above)
* F11 - DivMMC NMI
* F12 - Multiface NMI

= Changing the UI toggle key =

Some laptops don't have a Scroll Lock key, so you may not be able to exit MAME if you run it in full-screen mode. In these cases, you can change the UI toggle key as follows:

* Run MAME without any command line arguments (except maybe -window) to open its GUI.
* Push TAB and enter the General Settings menu.
* Go to Input Assignments -> User Interface -> Toggle UI controls and select a new key. I use Right Alt / Alt GR.
* Return to the previous menu twice, then choose Save Settings

= Creating a NextZXOS SD card image =

Most users wanting to emulate the Next using MAME will be fine using a pre-built SD card image downloaded from the specnext website. The following guide is provided for anyone wanting to create a NextZXOS SD card image from scratch.

Download the [https://www.specnext.com/latestdistro/ latest NextZXOS distribution zip file] (named something like sn-complete-WX.YZ.zip) and extract it into a new, empty directory.

== Creating and populating a SD card image using hdfmonkey jjjs build ==

The [[https://www.specnext.com/forum/viewtopic.php?t=2604 | <code>hdfmonkey "jjjs build"</code>]] is a variant of hdfmonkey tool which includes some unique features and its main archive (at the previously given link) also contains pre-built binaries for Windows x64, MacOS x64, MacOS Apple Silicon and Linux x64. (Alternatively, the process to build a local Linux version of the executable is described [[Development_Tools:Linux_setup#Building_the_executable_binary_2 | here]] )

If you extracted sn-complete-WX.YZ.zip into a subdirectory named <code>snWXYZ</code>, and you want to create a 1GB image called <code>NextZXOS.img</code> and you have a jjjs build" of hdfmonkey, then it's enough to do:

<pre>
hdfmonkey create NextZXOS.img 1G
hdfmonkey putdir NextZXOS.img snWXYZ /
</pre>

The first line creates an empty 1GB image and formats it with the best FAT parameters suited to the size of the image.

The second line recursively copies all the content of the directory <code>snWXYZ</code> to the image, preserving the directory structure inside, starting from the <code>/</code> in the image.

One of the advantages of this method is that even if the image has a capacity of 1GB, it will use much less space on your hard drive until you fill up the image. On Linux or MacOS, a command <code>du -h NextZXOS.img</code> shows the actual amount of disk space used by the image. On Windows the same information can be seen in the File Properties dialog.

The fastest way to transfer a file or a directory (including its content, recursively) into an image is by using a single <code>put</code> (or <code>putdir</code>, if it's to transfer the directory file content to an existing directory) command of hdfmonkey.

The most convenient tool to copy of all the content from the image to a folder outside of the image is 7-zip. On Windows, just use the 7-zip GUI. On MacOS and Linux, see: [[Development_Tools:Linux_setup#Extracting_all_files_from_the_SD_image]].

== Creating and populating a SD card image using Linux ==

While using hdfmonkey jjjs build works on Linux and the pre-built binary for Intel x64 exists, and using it creates an image which will have high compatibility, it is also possible to use more common Linux tools to create a SD image. Note however that the resulting image of this method, if the parameters of different steps aren't carefully chosen and matched, could be out of the official FAT specifications and/or the expectations of some of the existing programs or systems. This method creates an image which is incompatible with the current (as of 2025-12-13) CSpect version, at least for some sizes of the image:

Create a disk image of at least 256 MB. The current complete NextZXOS distro requires at least 130 MB of disk space. This command will create a 256 MB SD card image; change the <code>count</code> value to make the image file as big as you want in megabytes:

<pre>dd if=/dev/zero of=NextZXOS.img bs=1M count=256</pre>

The rest of the commands in this guide must be run as the root user or using sudo.

You will need to install the dosfstools and parted packages if they are not already installed. Debian and Ubuntu Linux users can install these using this apt command:

<pre>apt install dosfstools parted</pre>

Mount the SD card image loopback device:

<pre>losetup --partscan --show --find NextZXOS.img</pre>

Create a FAT32 partition:

<pre>parted /dev/loop0 mklabel msdos
parted /dev/loop0 mkpart primary fat32 1MB 100%</pre>

Format and mount the partition under /mnt:

<pre>mkfs.vfat -F 32 /dev/loop0p1
mount /dev/loop0p1 /mnt</pre>

You can now copy all of the files you extracted from sn-complete-WX.YZ.zip into /mnt.

After copying the files, unmount and detach the loopback device (the SD card image):

<pre>umount /mnt/
losetup -D</pre>

= Mounting SD card images under Linux =

Under Linux, you can use <code>losetup</code> to mount SD card images as loop devices. This lets you copy files to and from the image and perform other file management tasks as you would using any other filesystem.

Run the following commands as the root user to mount an image called sn-emulator-22.10a.img under the /mnt directory:

<pre>losetup --partscan --show --find cspect-next-2gb.img
mount /dev/loop0p1 /mnt/</pre>

After you are finished modifying the SD card image, cd out of /mnt, then unmount and detach the loopback device:

<pre>umount /mnt/
losetup -D</pre>

=MAME Plugins and Scripts=

Some MAME plugins and scripts that may be useful for Next developers and end users are listed [[MAME:Plugins_and_Scripts|here]]. They let you speed up the Next boot time, profile your NextBASIC or assembler code, and more.

=Continuous Integration MAME Builds=

MAME is updated on a release schedule, but due to the ongoing nature of development, including for the MAME Next machine, it can sometimes be useful to install a more recent build if it contains a new feature or bugfix you are interested in. Sometimes, this ongoing work is discussed on social media, such as the [https://discordapp.com/channels/556228195767156758/752197165891321886 Next Developer Discord].

Continuous Integration (CI) builds are available from both the [https://github.com/mamedev/mame/actions primary MAME repo] and [https://github.com/holub/mame/actions holub's GitHub repo]. Both are considered bleeding-edge, with the primary MAME repo slightly less so. MAME CI builds are available for Windows, Linux, and macOS and are updated automatically whenever code is committed by a maintainer or pushed to the primary repo.

To try out a CI build (more precisely, the resulting binary executable, which is a produced "artifact" of the build process) , first do a full MAME install from the [https://www.mamedev.org/release.html latest release] if you have not already done so. Then back up your main binary from its installation location - these are called something like <code>mame.exe</code> or <code>mame</code>. You can always restore these if the CI build doesn't work, or if you don't like how it behaves.

'''You need to be logged in to github''' to download CI artifacts, so [https://github.com/login sign in] or [https://github.com/signup sign up].

Then visit one of the links above and find a workflow run item for your platform. Workflow items are the things in the list. The tags are flagged as <code>CI (Windows)</code>, <code>CI (Linux)</code>, or <code>CI (macOS)</code> in the second row of each workflow item in the list (not the filter in the left hand nav menu). Click on a completed workfow item (only items with green checkmarks will have created downloadable binaries yet), find the Artifacts section at the bottom, then click the Download button. Unzip the downloaded file and find the main binary (with the same name as above). Copy the main binary to the install location, overwriting the original one, and run MAME the same way you were running it before. On Windows and macOS, you need to repeat the security steps above to trust the new MAME executable.

= More MAME links =

MAME [https://docs.mamedev.org/ documentation].

Report any issues with MAME on the [https://mametesters.org/ bugtracker].

ULA Palette Control Register

2025-12-11T08:38:02Z

Ped7g: Add reference to Tilemap control reg for tilemap palette select.

{{NextRegister
|Number=$43
|Readable=Yes
|Writable=Yes
|ShortDesc=Enables or disables Enhanced ULA interpretation of attribute values and toggles active palette.
}}
{| class="wikitable"
! Bit !! Function
|-
| 7 || 1 to disable palette index write auto-increment
|-
| 6-4 || Select palette for reading or writing
|-
| 3 || Select Sprites palette (0 = first palette, 1 = second palette)
|-
| 2 || Select Layer 2 palette (0 = first palette, 1 = second palette)
|-
| 1 || Select ULA palette (0 = first palette, 1 = second palette)
|-
| 0 || Enable ULANext mode if 1. (0 after a reset)
|}

n.b. Bits 6-4 select palette for reading or writing whereas bits 3-1 select the palette for the display signal generator.

Possible bits 6-4 for palette select (bit 6 selects first/second, 5-4 select type):
{| class="wikitable"
! Bits 6-4 !! selects
|-
| %000 || ULA first palette
|-
| %100 || ULA second palette
|-
| %001 || Layer 2 first palette
|-
| %101 || Layer 2 second palette
|-
| %010 || Sprites first palette
|-
| %110 || Sprites second palette
|-
| %011 || Tilemap first palette
|-
| %111 || Tilemap second palette
|}

Write will also reset the index of {{NextRegNo|$44}}, so the next write there will be considered as first byte of colour.

To select Tilemap active palette use {{NextRegNo|$6B}}.

DMA

2025-12-06T22:25:50Z

Ped7g: adding info about hw im2 mode interrupts executing extra instructions on "main thread"

== Overview ==
The ZX Spectrum Next DMA (zxnDMA) is a single channel DMA device that implements a subset of the Z80 DMA functionality. The subset is large enough to be compatible with common uses of the similar Datagear interface available for standard ZX Spectrum computers and compatibles. It also adds a burst mode capability that can deliver audio at programmable sample rates to the DAC device.

== Accessing the zxnDMA ==
<del>The zxnDMA is mapped to a single Read/Write IO Port 0x6B which is the same one used by the Datagear but unlike the Datagear it doesn't also map itself to a second port 0x0B similar to the MB-02 interface.</del>

Since core 3.1.2 the zxnDMA is mapped to {{PortNo|$xx6B}}, and Zilog-DMA mode is mapped to {{PortNo|$xx0B}}.

== Description ==
The normal Z80 DMA (Z8410) chip is a pipelined device and because of that it has numerous off-by-one idiosyncrasies and requirements on the order that certain commands should be carried out. These issues are not duplicated in the zxnDMA. You can continue to program the zxnDMA as if it is were a Z8410 DMA device but it can also be programmed in a simpler manner.

The single channel of the zxnDMA chip consists of two ports named A and B. Transfers can occur in either direction between ports A and B, each port can describe a target in memory or IO, and each can be configured to autoincrement, autodecrement or stay fixed after a byte is transferred.

A special feature of the zxnDMA can force each byte transfer to take a fixed amount of time so that the zxnDMA can be used to deliver sampled audio.

== Modes of Operation ==
The zxnDMA can operate in a z80-DMA compatibility mode.

'''REMOVED in core 3.1.2:''' <del>The z80-DMA compatibility mode is selected by setting bit 6 of nextreg 0x06. In this mode, all transfers involve length+1 bytes which is the same behaviour as the z80-DMA chip. In zxn-DMA mode, the transfer length is exactly the number of bytes programmed. This mode is mainly present to accommodate existing spectrum software that uses the z80-DMA and for cp/m programs that may have a z80-DMA option.</del>

'''Since core 3.1.2:''' the DMA mode is selected by port number, the {{PortNo|$xx6B}} works in zxnDMA mode, {{PortNo|$xx0B}} works in Zilog mode. The bit 6 in {{NextRegNo|$06}} is not DMA related any more and will be reused for something different.

The zxnDMA can also operate in either burst or continuous modes.

Continuous mode means the DMA chip runs to completion without allowing the CPU to run. When the CPU starts the DMA, the DMA operation will complete before the CPU executes its next instruction.

Burst mode nominally means the DMA lets the CPU run if either port is not ready. This condition can't happen in the zxnDMA chip except when operated in the special fixed time transfer mode. In this mode, the zxnDMA will let the CPU run while it waits for the fixed time to expire between bytes transferred.

Note that there is no byte transfer mode as in the Z80 DMA.

== Programming the zxnDMA ==
Like the Z80 DMA chip, the zxnDMA has seven write registers named WR0-WR6 that control the device. Each register WR0-WR6 can have zero or more parameters associated with it.

In a first write to the zxnDMA port, the write value is compared against a bitmask to determine which of the WR0-WR6 is the target. Remaining bits in the written value can contain data as well as a list of associated parameter bits. The parameter bits determine if further writes are expected to deliver parameter values. If there are multiple parameter bits set, the expected order of parameter values written is determined by parameter bit position from right to left (bit 0 through bit 7). Once all parameters are written, the zxnDMA again expects a regular register write selecting WR0-WR6.

The table below describes the registers and the bitmask required to select them on the zxnDMA.

{|
! Register Group
! Register Function Description
! Bitmask
! Notes
|-
| WR0
| Direction, Operation and Port A configuration
| <pre>0XXXXXAA</pre>
| AA must NOT be 00
|-
| WR1
| Port A configuration
| <pre>0XXXX100</pre>
|
|-
| WR2
| Port B configuration
| <pre>0XXXX000</pre>
|
|-
| WR3
| Activation
| <pre>1XXXXX00</pre>
| It’s best to use WR6
|-
| WR4
| Port B, Timing and Interrupt configuration
| <pre>1XXXXX01</pre>
|
|-
| WR5
| Ready and Stop configuration
| <pre>10XXX010</pre>
|
|-
| WR6
| Command Register
| <pre>1XXXXX11</pre>
|
|}

== zxnDMA Registers ==
These are described below following the same convention used by Zilog for its DMA chip:

=== WR0 – Write Register Group 0 ===

<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
0 | | | | | | |
| | | | | 0 0 Do not use
| | | | | 0 1 Transfer (Prefer this for Z80 DMA compatibility)
| | | | | 1 0 Do not use (Behaves like Transfer, Search on Z80 DMA)
| | | | |
| | | | | 1 1 Do not use (Behaves like Transfer, Search/Transfer on Z80 DMA)
| | | | |
| | | | 0 = Port B -> Port A (Byte transfer direction)
| | | | 1 = Port A -> Port B
| | | V
D7 D6 D5 D4 D3 D2 D1 D0 PORT A STARTING ADDRESS (LOW BYTE)
| | V
D7 D6 D5 D4 D3 D2 D1 D0 PORT A STARTING ADDRESS (HIGH BYTE)
| V
D7 D6 D5 D4 D3 D2 D1 D0 BLOCK LENGTH (LOW BYTE)
V
D7 D6 D5 D4 D3 D2 D1 D0 BLOCK LENGTH (HIGH BYTE)</pre>

Several registers are accessible from WR0. The first write to WR0 is to the base register byte. Bits D6:D3 are optionally set to indicate that associated registers in this group will be written next. The order the writes come in are from D3 to D6 (right to left). For example, if bits D6 and D3 are set, the next two writes will be directed to PORT A STARTING ADDRESS LOW followed by BLOCK LENGTH HIGH.

=== WR1 – Write Register Group 1 ===

<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
0 | | | | 1 0 0
| | | |
| | | 0 = Port A is memory
| | | 1 = Port A is IO
| | |
| 0 0 = Port A address decrements
| 0 1 = Port A address increments
| 1 0 = Port A address is fixed
| 1 1 = Port A address is fixed
|
V
D7 D6 D5 D4 D3 D2 D1 D0 PORT A VARIABLE TIMING BYTE
0 0 0 0 0 0 | |
0 0 = Cycle Length = 4
0 1 = Cycle Length = 3
1 0 = Cycle Length = 2
1 1 = Do not use
</pre>

The cycle length is the number of cycles used in a read or write operation. The first cycle asserts signals and the last cycle releases them. There is no half cycle timing for the control signals.

=== WR2 – Write Register Group 2 ===

<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
0 | | | | 0 0 0
| | | |
| | | 0 = Port B is memory
| | | 1 = Port B is IO
| | |
| 0 0 = Port B address decrements
| 0 1 = Port B address increments
| 1 0 = Port B address is fixed
| 1 1 = Port B address is fixed
|
V
D7 D6 D5 D4 D3 D2 D1 D0 PORT B VARIABLE TIMING BYTE
0 0 | 0 0 0 | |
| 0 0 = Cycle Length = 4
| 0 1 = Cycle Length = 3
| 1 0 = Cycle Length = 2
| 1 1 = Do not use
|
V
D7 D6 D5 D4 D3 D2 D1 D0 ZXN PRESCALAR (FIXED TIME TRANSFER)
</pre>
The ZXN PRESCALAR is a feature of the zxnDMA implementation. If non-zero, a delay will be inserted after each byte is transferred such that the total time needed for each transfer is determined by the prescalar. This works in both the continuous mode and the burst mode. If the DMA is operated in burst mode, the DMA will give up any waiting time to the CPU so that the CPU can run while the DMA is idle.

The rate of transfer is given by the formula “Frate = 875kHz / prescalar” or, rearranged, “prescalar = 875kHz / Frate”. The formula is framed in terms of a sample rate (Frate) but Frate can be inverted to set a transfer time for each byte instead. The 875kHz constant is a nominal value assuming a 28MHz system clock; the system clock actually varies from this depending on the video timing selected by the user (HDMI, VGA0-6) so for complete accuracy the constant should be prorated according to documentation for nextreg 0x11.

In a DMA audio setting, selecting a sample rate of 16kHz would mean setting the prescalar value to 55. This sample period is constant across changes in CPU speed.

=== WR3 – Write Register Group 3 ===

<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
1 | 0 0 0 0 0 0
|
1 = DMA Enable
</pre>
The Z80 DMA defines more fields but they are ignored by the zxnDMA. The two other registers defined by the Z80 DMA in this group on D4 and D3 are implemented by the zxnDMA but they do nothing.

It is preferred to start the DMA by writing an 'Enable DMA' command to WR6.

=== WR4 – Write Register Group 4 ===

<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
1 | | 0 | | 0 1
| | | |
0 0 = Do not use (Behaves like Continuous mode, Byte mode on Z80 DMA)
0 1 = Continuous mode
1 0 = Burst mode
1 1 = Do not use
| |
| V
D7 D6 D5 D4 D3 D2 D1 D0 PORT B STARTING ADDRESS (LOW BYTE)
|
V
D7 D6 D5 D4 D3 D2 D1 D0 PORT B STARTING ADDRESS (HIGH BYTE)
</pre>
The Z80 DMA defines three more registers in this group through D4 that define interrupt behaviour. Interrups and pulse generation are not implemented in the zxnDMA nor are these registers available for writing.

=== WR5 – Write Register Group 5 ===
<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
1 0 | | 0 0 1 0
| |
| 0 = /ce only
| 1 = /ce & /wait multiplexed
|
0 = Stop on end of block
1 = Auto restart on end of block
</pre>
The /ce & /wait mode is implemented in the zxnDMA but is not currently used. This mode has an external device using the DMA's /ce pin to insert wait states during the DMA's transfer.

The auto restart feature causes the DMA to automatically reload its source and destination addresses and reset its byte counter to zero to repeat the last transfer when a previous one is finished.

=== WR6 – Command Register ===
<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
1 ? ? ? ? ? 1 1
| | | | |
1 0 0 0 0 = 0xC3 = Reset
1 0 0 0 1 = 0xC7 = Reset Port A Timing
1 0 0 1 0 = 0xCB = Reset Port B Timing
0 1 1 0 0 = 0xB3 = Force Ready (irrelevant for zxnDMA)
0 1 1 1 1 = 0xBF = Read Status Byte
0 0 0 1 0 = 0x8B = Reinitialize Status Byte
0 1 0 0 1 = 0xA7 = Initialize Read Sequence
1 0 0 1 1 = 0xCF = Load
1 0 1 0 0 = 0xD3 = Continue
0 0 0 0 1 = 0x87 = Enable DMA
0 0 0 0 0 = 0x83 = Disable DMA
+-- 0 1 1 1 0 = 0xBB = Read Mask Follows
|
D7 D6 D5 D4 D3 D2 D1 D0 READ MASK
0 | | | | | | |
| | | | | | V
D7 D6 D5 D4 D3 D2 D1 D0 Status Byte
| | | | | |
| | | | | V
D7 D6 D5 D4 D3 D2 D1 D0 Byte Counter Low ("High" with core 3.0.5 = bug in core)
| | | | |
| | | | V
D7 D6 D5 D4 D3 D2 D1 D0 Byte Counter High ("Low" with core 3.0.5 = bug in core)
| | | |
| | | V
D7 D6 D5 D4 D3 D2 D1 D0 Port A Address Low
| | |
| | V
D7 D6 D5 D4 D3 D2 D1 D0 Port A Address High
| |
| V
D7 D6 D5 D4 D3 D2 D1 D0 Port B Address Low
|
V
D7 D6 D5 D4 D3 D2 D1 D0 Port B Address High
</pre>
Unimplemented Z80 DMA commands are ignored.

Prior to starting the DMA transfer, a LOAD command must be issued to copy the Port A and Port B addresses into the DMA's internal pointers. Then an 'Enable DMA' command is issued to start the DMA. The last LOAD command before ENABLE must be done with correct transfer direction set.

The 'Continue' command resets the DMA's byte counter so that a following 'Enable DMA' allows the DMA to repeat the last transfer but using the current internal address pointers. I.e. it continues from where the last copy operation left off.

Reset and Reset Port A/B Timing commands on zxnDMA do reset also prescalar value.

Registers can be read via an IO read from the DMA port after setting the read mask. (At power up the read mask is set to 0x7f). Register values are the current internal DMA counter values. So 'Port Address A Low' is the lower 8-bits of Port A’s next transfer address. Once the end of the read mask is reached, further reads loop around to the first one.

The format of the DMA status byte is as follows:

<pre>00E1101T</pre>

E is set to 0 if the total block length has been transferred at least once.

T is set to 1 if at least one byte has been transferred.

== Operating speed ==
The zxnDMA operates at the same speed as the CPU, that is 3.5MHz, 7MHz, 14MHz or 28Mhz. This is a contended clock that is modified by the ULA and the auto-slowdown by [[Layer 2|Layer2]] (which only occurred in Next core's 1 and 2, the limitation was lifted in core 3.0).

The (pre-core 3.0) auto-slowdown occurs without user intervention if speed exceeds 7Mhz and the active Layer2 display is being generated (higher speed operation resumes when the active Layer2 display is not generated). Programmers do NOT need to account for speed differences regarding DMA transfers as this happens automatically.

Because of this, the cycle lengths for Ports A and B can be set to their minimum values without ill effects. The cycle lengths specified for Ports A and B are intended to selectively slow down read or write cycles for hardware that cannot operate at the DMA's full speed.

== The DMA and Interrupts ==
The zxnDMA cannot currently generate [[Interrupts|interrupts]].

The other side of this is that while the DMA controls the bus, the Z80 cannot respond to interrupts. On the Z80, the NMI interrupt is edge triggered so if an NMI occurs the fact that it occurred is stored internally in the Z80 so that it will respond when it is woken up. On the other hand, maskable interrupts are level triggered. That is, the Z80 must be active to regularly sample the /INT line to determine if a maskable interrupt is occurring. On the Spectrum and the ZX Next, the ULA (and line interrupt) are only asserted for a fixed amount of time ~30 cycles at 3.5MHz. If the DMA is executing a transfer while the interrupt is asserted, the CPU will not be able to see this and it will most likely miss the interrupt. In burst mode, with large-enough prescalar value, the CPU will never miss these interrupts, although this may change if multiple channels are implemented.

'''Since core 3.1.8:''' the ability to interrupt DMA transfers was added, this is opt-in mechanism and must be configured through {{NextRegNo|$CC}}, {{NextRegNo|$CD}} and {{NextRegNo|$CE}} and requires "hw im2 mode" interrupts being set. Because interrupts are only sampled at the end of an instruction by the Z80, each time the dma is interrupted one instruction of progress is made in the main program (before the interrupt handler code is entered).

This means after starting the DMA transfer with last `out` instruction you must follow it by N instructions which don't affect the transfer (don't remap source data memory, select different sprite/copper/... index if that's target of transfer, don't write anything to zxnDMA port), either doing different kind of work with CPU or adding block of `nop` instructions, to have non-interfering block of code available to fire N interrupts during transfer. Chose N to accommodate for worst case scenario of how many times you will interrupt the running DMA transfer. Or you can read state of zxnDMA to see if transfer did finish, but (IMHO by ped7g) in most cases it will be performance-cheaper to just add block of nop instructions or do other work on CPU not interfering with transfer.

== Programming examples ==
A simple way to program the DMA is to walk down the list of registers WR0-WR5, sending desired settings to each. Then start the DMA by sending a LOAD command followed by an ENABLE_DMA command to WR6. Once more familiar with the DMA, you will discover that the amount of information sent can be reduced to what changes between transfers.

=== Assembly ===
Short example program to DMA memory to the screen, then DMA a sprite image from memory to sprite RAM, and then showing said sprite scrolling across the screen.

<pre>;------------------------------------------------------------------------------
; sjasmplus extra options to enable Z80N, stricter syntax and Next device
opt --zxnext --syntax=abf : device zxspectrumnext
;------------------------------------------------------------------------------
; DEFINE testing ; uncomment to produce NEX file (instead of DOT)
;------------------------------------------------------------------------------
; DMA (Register 6)
;
;------------------------------------------------------------------------------
;zxnDMA programming example
;------------------------------------------------------------------------------
;(c) Jim Bagley
;------------------------------------------------------------------------------
DMA_RESET equ $c3
DMA_RESET_PORT_A_TIMING equ $c7
DMA_RESET_PORT_B_TIMING equ $cb
DMA_LOAD equ $cf ; %11001111
DMA_CONTINUE equ $d3
DMA_DISABLE_INTERUPTS equ $af
DMA_ENABLE_INTERUPTS equ $ab
DMA_RESET_DISABLE_INTERUPTS equ $a3
DMA_ENABLE_AFTER_RETI equ $b7
DMA_READ_STATUS_BYTE equ $bf
DMA_REINIT_STATUS_BYTE equ $8b
DMA_START_READ_SEQUENCE equ $a7
DMA_FORCE_READY equ $b3
DMA_DISABLE equ $83
DMA_ENABLE equ $87
DMA_WRITE_REGISTER_COMMAND equ $bb
DMA_BURST equ %11001101
DMA_CONTINUOUS equ %10101101
ZXN_DMA_PORT equ $6b
SPRITE_STATUS_SLOT_SELECT equ $303B
SPRITE_IMAGE_PORT equ $5b
SPRITE_INFO_PORT equ $57
;------------------------------------------------------------------------------

IFDEF testing
org $5800
block 32*24, $38 ; default ULA attributes
org $6000
ELSE
org $2000
ENDIF

start
ld hl,$0000
ld de,$4000
ld bc,$800
call TransferDMA ; copy some random data to the screen pointing
; to ROM for now, for the purpose of showing
; how to do a DMA copy.
ld a,0 ; sprite image number we want to update
ld bc,SPRITE_STATUS_SLOT_SELECT
out (c),a ; set the sprite image number
ld bc,1*256 ; number to transfer (1)
ld hl,testsprite ; from
call TransferDMASprite ; transfer to sprite ram

nextreg 21,1 ; turn sprite on. for more info on this check
; out https://www.specnext.com/tbblue-io-port-system/
ld de,0
ld (xpos),de ; set initial X position ( doesn't need it for
; this demo, but if you run the .loop again it
; will continue from where it was
ld a,$20
ld (ypos),a ; set initial Y position

.loop
ld a,0 ; sprite number we want to position
ld bc,SPRITE_STATUS_SLOT_SELECT
out (c),a
ld de,(xpos)
ld hl,(ypos) ; ignores H so doing this rather than
; ld a,(ypos):ld l,a
ld bc,(image) ; not flipped or palette shifted
call SetSprite

halt

ld de,(xpos)
inc de
ld (xpos),de
ld a,d
cp $01
jr nz,.loop ; if high byte of xpos is not 1 (right of
; screen )
ld a,e
cp $20+1
jr nz,.loop ; if low byte is not $21 just off the right of
; the screen, $20 is off screen but as the
; INC DE is just above and not updated sprite
; after it, it needs to be $21
xor a
ret ; return back to basic with OK

xpos dw 0 ; x position
ypos db 0 ; y position
; these next two BITS and IMAGE are swapped
; as bits needs to go into B register
image db 0+$80 ; use image 0 (for the image we transfered)
; +$80 to set the sprite to active
bits db 0 ; not flipped or palette shifted

c1 = %11100000
c2 = %11000000
c3 = %10100000
c4 = %10000000
c5 = %01100000
c6 = %01000000
c7 = %00100000
c8 = %00000000

testsprite
db c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1
db c1,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c1
db c1,c2,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c2,c1
db c1,c2,c3,c4,c4,c4,c4,c4,c4,c4,c4,c4,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c5,c5,c5,c5,c5,c5,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c6,c6,c6,c6,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c7,c7,c7,c7,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c7,c8,c8,c7,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c7,c8,c8,c7,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c7,c7,c7,c7,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c6,c6,c6,c6,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c5,c5,c5,c5,c5,c5,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c4,c4,c4,c4,c4,c4,c4,c4,c4,c3,c2,c1
db c1,c2,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c2,c1
db c1,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c1
db c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1

;-------------------------------------------------
; de = X
; l = Y
; b = bits
; c = sprite image
SetSprite
push bc
ld bc,SPRITE_INFO_PORT
out (c),e ; Xpos
out (c),l ; Ypos
pop hl
ld a,d
and 1
or h
out (c),a
ld a,l:or $80
out (c),a ; image
ret

;--------------------------------
; hl = source
; de = destination
; bc = length
;--------------------------------
TransferDMA
di
ld (DMASource),hl
ld (DMADest),de
ld (DMALength),bc
ld hl,DMACode
ld b,DMACode_Len
ld c,ZXN_DMA_PORT
otir
ei
ret

DMACode db DMA_DISABLE
db %01111101 ; R0-Transfer mode, A -> B, write adress
; + block length
DMASource dw 0 ; R0-Port A, Start address
; (source address)
DMALength dw 0 ; R0-Block length (length in bytes)
db %01010100 ; R1-write A time byte, increment, to
; memory, bitmask
db %00000010 ; 2t
db %01010000 ; R2-write B time byte, increment, to
; memory, bitmask
db %00000010 ; R2-Cycle length port B
db DMA_CONTINUOUS ; R4-Continuous mode (use this for block
; transfer), write dest adress
DMADest dw 0 ; R4-Dest address (destination address)
db %10000010 ; R5-Restart on end of block, RDY active
; LOW
db DMA_LOAD ; R6-Load
db DMA_ENABLE ; R6-Enable DMA

DMACode_Len equ $-DMACode

;------------------------------------------------------------------------------
; hl = source
; bc = length
; set port to write to with TBBLUE_REGISTER_SELECT
; prior to call
;------------------------------------------------------------------------------
TransferDMAPort
di
ld (DMASourceP),hl
ld (DMALengthP),bc
ld hl,DMACodeP
ld b,DMACode_LenP
ld c,ZXN_DMA_PORT
otir
ei
ret

DMACodeP db DMA_DISABLE
db %01111101 ; R0-Transfer mode, A -> B, write adress
; + block length
DMASourceP dw 0 ; R0-Port A, Start address (source address)
DMALengthP dw 0 ; R0-Block length (length in bytes)
db %01010100 ; R1-read A time byte, increment, to
; memory, bitmask
db %00000010 ; R1-Cycle length port A
db %01101000 ; R2-write B time byte, increment, to
; memory, bitmask
db %00000010 ; R2-Cycle length port B
db %10101101 ; R4-Continuous mode (use this for block
; transfer), write dest adress
dw $253b ; R4-Dest address (destination address)
db %10000010 ; R5-Restart on end of block, RDY active
; LOW
db DMA_LOAD ; R6-Load
db DMA_ENABLE ; R6-Enable DMA

DMACode_LenP equ $-DMACodeP
;------------------------------------------------------------------------------
; hl = source
; bc = length
;------------------------------------------------------------------------------
TransferDMASprite
di
ld (DMASourceS),hl
ld (DMALengthS),bc
ld hl,DMACodeS
ld b,DMACode_LenS
ld c,ZXN_DMA_PORT
otir
ei
ret

DMACodeS db DMA_DISABLE
db %01111101 ; R0-Transfer mode, A -> B, write adress
; + block length
DMASourceS dw 0 ; R0-Port A, Start address (source address)
DMALengthS dw 0 ; R0-Block length (length in bytes)
db %01010100 ; R1-read A time byte, increment, to
; memory, bitmask
db %00000010 ; R1-Cycle length port A
db %01101000 ; R2-write B time byte, increment, to
; memory, bitmask
db %00000010 ; R2-Cycle length port B
db %10101101 ; R4-Continuous mode (use this for block
; transfer), write dest adress
dw SPRITE_IMAGE_PORT ; R4-Dest address (destination address)
db %10000010 ; R5-Restart on end of block, RDY active
; LOW
db DMA_LOAD ; R6-Load
db DMA_ENABLE ; R6-Enable DMA
DMACode_LenS equ $-DMACodeS
;------------------------------------------------------------------------------
; de = dest, a = fill value, bc = lenth
;------------------------------------------------------------------------------
DMAFill
di
ld (FillValue),a
ld (DMACDest),de
ld (DMACLength),bc
ld hl,DMACCode
ld b,DMACCode_Len
ld c,ZXN_DMA_PORT
otir
ei
ret

FillValue db 22
DMACCode db DMA_DISABLE
db %01111101
DMACSource dw FillValue
DMACLength dw 0
db %00100100,%00010000,%10101101
DMACDest dw 0
db DMA_LOAD,DMA_ENABLE
DMACCode_Len equ $-DMACCode

;------------------------------------------------------------------------------
; End of file
;------------------------------------------------------------------------------

IFDEF testing
savenex open "DMAtest.nex", start, $FF00
savenex bank 5
ELSE
fin
savebin "DMATEST",start,fin-start
ENDIF
</pre>

Based on original text by: Allen Albright & Mike Dailly with input by Jim Bagley, Lyndon J Sharp and Phoebus R. Dokos

== Technical details (core 3.1.3+) ==

The Zilog/zxnDMA mode is now selected by using the particular I/O port number ({{PortNo|$xx6B}} for zxnDMA mode, {{PortNo|$xx0B}} for Zilog mode). The bit 6 in {{NextRegNo|$06}} is not DMA related any more and will be reused for something different.

The "counter" RR1-RR2 read back after transfer has correct byte order since core 3.1.4.

Other differences described below in "3.0.5" remains (but from practical point of view the Zilog DMA emulation in 3.1.4 is near-perfect, all the remaining differences are very minor).

== Technical details (core 3.0.5) ==

=== Zilog DMA compatibility mode ===
In Zilog DMA compatibility mode (bit 6 of {{NextRegNo|$06}}) the zxnDMA will mostly work as expected, but there are few differences in behaviour which may eventually throw off some rare SW, here is the list of the known differences (most of them describe also how the zxnDMA mode works):

The LOAD command must be issued with correct transfer direction, loading addresses in opposite direction and flipping direction afterward will mismatch the source/destination address data (Zilog/UA858D DMA chips are also sensitive to direction flip after LOAD, but the resulting transfer quirks in different way, reading source data byte after write, offsetting whole transfer by one and damaging start/end of sequence).
(does apply also to zxnDMA mode)

The LOAD command will NOT destroy the already issued "Initialize Read Sequence" - this is how even the original Zilog documentation describes the DMA chip operation, but the real Zilog DMA and UA858D (clone chip) both destroy read sequence upon LOAD command (zxnDMA is better).
(does apply also to zxnDMA mode)

The content of registers read back after finished transfer differs: the counter has swapped LSB with MSB byte, and both addresses will be adjusted length+1 times (Zilog/UA858D will return destination address adjusted only length-many times).
(does apply also to zxnDMA mode, except addresses are adjusted only "length" times of course, counter has still swapped bytes)

Any read of zxnDMA port without pending read request (commands "Read Status Byte" or "Initialize Read Sequence") will return status byte (Zilog will return random value vaguely similar to status byte, but incorrect, UA858D will return zero).
(does apply also to zxnDMA mode)

Status byte doesn't have bit 0 set (the "T" bit in description above).
(does apply also to zxnDMA mode)

Be aware that both custom timing cycles count, and prescalar values are preserved in zxnDMA even when future write to WR1/WR2 does skip these particular bytes. To reset prescalar or cycles timing, write explicitly zero into prescalar register or use commands reset/reset-port-timing.
(does apply also to zxnDMA mode, the prescalar works only in zxnDMA mode)

The destination port address is LOAD-ed even when it is "fixed" type (Contrary to Zilog DMA, which requires you to load such port as "source", flip the direction after and re-LOAD again with correct direction. UA858D chip does also load destination port address in any case, just like zxnDMA).
(does apply also to zxnDMA mode)

=== zxnDMA mode vs Zilog mode ===

In zxnDMA mode length of transfer is equal to the length written to WR0 register, port addresses are adjusted also only length-times.

Prescalar value will affect speed of transfer (use zero to switch prescalar off) (in burst mode during the extra idle time the CPU receives control back and can execute further instructions, in continuous mode the transfer will keep blocking CPU even when "slow" transfer is being done).

DMA

2025-12-02T09:36:40Z

Ped7g: Adding one more note about prescalar being reset by reset commands to make it easier to find.

== Overview ==
The ZX Spectrum Next DMA (zxnDMA) is a single channel DMA device that implements a subset of the Z80 DMA functionality. The subset is large enough to be compatible with common uses of the similar Datagear interface available for standard ZX Spectrum computers and compatibles. It also adds a burst mode capability that can deliver audio at programmable sample rates to the DAC device.

== Accessing the zxnDMA ==
<del>The zxnDMA is mapped to a single Read/Write IO Port 0x6B which is the same one used by the Datagear but unlike the Datagear it doesn't also map itself to a second port 0x0B similar to the MB-02 interface.</del>

Since core 3.1.2 the zxnDMA is mapped to {{PortNo|$xx6B}}, and Zilog-DMA mode is mapped to {{PortNo|$xx0B}}.

== Description ==
The normal Z80 DMA (Z8410) chip is a pipelined device and because of that it has numerous off-by-one idiosyncrasies and requirements on the order that certain commands should be carried out. These issues are not duplicated in the zxnDMA. You can continue to program the zxnDMA as if it is were a Z8410 DMA device but it can also be programmed in a simpler manner.

The single channel of the zxnDMA chip consists of two ports named A and B. Transfers can occur in either direction between ports A and B, each port can describe a target in memory or IO, and each can be configured to autoincrement, autodecrement or stay fixed after a byte is transferred.

A special feature of the zxnDMA can force each byte transfer to take a fixed amount of time so that the zxnDMA can be used to deliver sampled audio.

== Modes of Operation ==
The zxnDMA can operate in a z80-DMA compatibility mode.

'''REMOVED in core 3.1.2:''' <del>The z80-DMA compatibility mode is selected by setting bit 6 of nextreg 0x06. In this mode, all transfers involve length+1 bytes which is the same behaviour as the z80-DMA chip. In zxn-DMA mode, the transfer length is exactly the number of bytes programmed. This mode is mainly present to accommodate existing spectrum software that uses the z80-DMA and for cp/m programs that may have a z80-DMA option.</del>

'''Since core 3.1.2:''' the DMA mode is selected by port number, the {{PortNo|$xx6B}} works in zxnDMA mode, {{PortNo|$xx0B}} works in Zilog mode. The bit 6 in {{NextRegNo|$06}} is not DMA related any more and will be reused for something different.

The zxnDMA can also operate in either burst or continuous modes.

Continuous mode means the DMA chip runs to completion without allowing the CPU to run. When the CPU starts the DMA, the DMA operation will complete before the CPU executes its next instruction.

Burst mode nominally means the DMA lets the CPU run if either port is not ready. This condition can't happen in the zxnDMA chip except when operated in the special fixed time transfer mode. In this mode, the zxnDMA will let the CPU run while it waits for the fixed time to expire between bytes transferred.

Note that there is no byte transfer mode as in the Z80 DMA.

== Programming the zxnDMA ==
Like the Z80 DMA chip, the zxnDMA has seven write registers named WR0-WR6 that control the device. Each register WR0-WR6 can have zero or more parameters associated with it.

In a first write to the zxnDMA port, the write value is compared against a bitmask to determine which of the WR0-WR6 is the target. Remaining bits in the written value can contain data as well as a list of associated parameter bits. The parameter bits determine if further writes are expected to deliver parameter values. If there are multiple parameter bits set, the expected order of parameter values written is determined by parameter bit position from right to left (bit 0 through bit 7). Once all parameters are written, the zxnDMA again expects a regular register write selecting WR0-WR6.

The table below describes the registers and the bitmask required to select them on the zxnDMA.

{|
! Register Group
! Register Function Description
! Bitmask
! Notes
|-
| WR0
| Direction, Operation and Port A configuration
| <pre>0XXXXXAA</pre>
| AA must NOT be 00
|-
| WR1
| Port A configuration
| <pre>0XXXX100</pre>
|
|-
| WR2
| Port B configuration
| <pre>0XXXX000</pre>
|
|-
| WR3
| Activation
| <pre>1XXXXX00</pre>
| It’s best to use WR6
|-
| WR4
| Port B, Timing and Interrupt configuration
| <pre>1XXXXX01</pre>
|
|-
| WR5
| Ready and Stop configuration
| <pre>10XXX010</pre>
|
|-
| WR6
| Command Register
| <pre>1XXXXX11</pre>
|
|}

== zxnDMA Registers ==
These are described below following the same convention used by Zilog for its DMA chip:

=== WR0 – Write Register Group 0 ===

<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
0 | | | | | | |
| | | | | 0 0 Do not use
| | | | | 0 1 Transfer (Prefer this for Z80 DMA compatibility)
| | | | | 1 0 Do not use (Behaves like Transfer, Search on Z80 DMA)
| | | | |
| | | | | 1 1 Do not use (Behaves like Transfer, Search/Transfer on Z80 DMA)
| | | | |
| | | | 0 = Port B -> Port A (Byte transfer direction)
| | | | 1 = Port A -> Port B
| | | V
D7 D6 D5 D4 D3 D2 D1 D0 PORT A STARTING ADDRESS (LOW BYTE)
| | V
D7 D6 D5 D4 D3 D2 D1 D0 PORT A STARTING ADDRESS (HIGH BYTE)
| V
D7 D6 D5 D4 D3 D2 D1 D0 BLOCK LENGTH (LOW BYTE)
V
D7 D6 D5 D4 D3 D2 D1 D0 BLOCK LENGTH (HIGH BYTE)</pre>

Several registers are accessible from WR0. The first write to WR0 is to the base register byte. Bits D6:D3 are optionally set to indicate that associated registers in this group will be written next. The order the writes come in are from D3 to D6 (right to left). For example, if bits D6 and D3 are set, the next two writes will be directed to PORT A STARTING ADDRESS LOW followed by BLOCK LENGTH HIGH.

=== WR1 – Write Register Group 1 ===

<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
0 | | | | 1 0 0
| | | |
| | | 0 = Port A is memory
| | | 1 = Port A is IO
| | |
| 0 0 = Port A address decrements
| 0 1 = Port A address increments
| 1 0 = Port A address is fixed
| 1 1 = Port A address is fixed
|
V
D7 D6 D5 D4 D3 D2 D1 D0 PORT A VARIABLE TIMING BYTE
0 0 0 0 0 0 | |
0 0 = Cycle Length = 4
0 1 = Cycle Length = 3
1 0 = Cycle Length = 2
1 1 = Do not use
</pre>

The cycle length is the number of cycles used in a read or write operation. The first cycle asserts signals and the last cycle releases them. There is no half cycle timing for the control signals.

=== WR2 – Write Register Group 2 ===

<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
0 | | | | 0 0 0
| | | |
| | | 0 = Port B is memory
| | | 1 = Port B is IO
| | |
| 0 0 = Port B address decrements
| 0 1 = Port B address increments
| 1 0 = Port B address is fixed
| 1 1 = Port B address is fixed
|
V
D7 D6 D5 D4 D3 D2 D1 D0 PORT B VARIABLE TIMING BYTE
0 0 | 0 0 0 | |
| 0 0 = Cycle Length = 4
| 0 1 = Cycle Length = 3
| 1 0 = Cycle Length = 2
| 1 1 = Do not use
|
V
D7 D6 D5 D4 D3 D2 D1 D0 ZXN PRESCALAR (FIXED TIME TRANSFER)
</pre>
The ZXN PRESCALAR is a feature of the zxnDMA implementation. If non-zero, a delay will be inserted after each byte is transferred such that the total time needed for each transfer is determined by the prescalar. This works in both the continuous mode and the burst mode. If the DMA is operated in burst mode, the DMA will give up any waiting time to the CPU so that the CPU can run while the DMA is idle.

The rate of transfer is given by the formula “Frate = 875kHz / prescalar” or, rearranged, “prescalar = 875kHz / Frate”. The formula is framed in terms of a sample rate (Frate) but Frate can be inverted to set a transfer time for each byte instead. The 875kHz constant is a nominal value assuming a 28MHz system clock; the system clock actually varies from this depending on the video timing selected by the user (HDMI, VGA0-6) so for complete accuracy the constant should be prorated according to documentation for nextreg 0x11.

In a DMA audio setting, selecting a sample rate of 16kHz would mean setting the prescalar value to 55. This sample period is constant across changes in CPU speed.

=== WR3 – Write Register Group 3 ===

<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
1 | 0 0 0 0 0 0
|
1 = DMA Enable
</pre>
The Z80 DMA defines more fields but they are ignored by the zxnDMA. The two other registers defined by the Z80 DMA in this group on D4 and D3 are implemented by the zxnDMA but they do nothing.

It is preferred to start the DMA by writing an 'Enable DMA' command to WR6.

=== WR4 – Write Register Group 4 ===

<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
1 | | 0 | | 0 1
| | | |
0 0 = Do not use (Behaves like Continuous mode, Byte mode on Z80 DMA)
0 1 = Continuous mode
1 0 = Burst mode
1 1 = Do not use
| |
| V
D7 D6 D5 D4 D3 D2 D1 D0 PORT B STARTING ADDRESS (LOW BYTE)
|
V
D7 D6 D5 D4 D3 D2 D1 D0 PORT B STARTING ADDRESS (HIGH BYTE)
</pre>
The Z80 DMA defines three more registers in this group through D4 that define interrupt behaviour. Interrups and pulse generation are not implemented in the zxnDMA nor are these registers available for writing.

=== WR5 – Write Register Group 5 ===
<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
1 0 | | 0 0 1 0
| |
| 0 = /ce only
| 1 = /ce & /wait multiplexed
|
0 = Stop on end of block
1 = Auto restart on end of block
</pre>
The /ce & /wait mode is implemented in the zxnDMA but is not currently used. This mode has an external device using the DMA's /ce pin to insert wait states during the DMA's transfer.

The auto restart feature causes the DMA to automatically reload its source and destination addresses and reset its byte counter to zero to repeat the last transfer when a previous one is finished.

=== WR6 – Command Register ===
<pre>D7 D6 D5 D4 D3 D2 D1 D0 BASE REGISTER BYTE
1 ? ? ? ? ? 1 1
| | | | |
1 0 0 0 0 = 0xC3 = Reset
1 0 0 0 1 = 0xC7 = Reset Port A Timing
1 0 0 1 0 = 0xCB = Reset Port B Timing
0 1 1 0 0 = 0xB3 = Force Ready (irrelevant for zxnDMA)
0 1 1 1 1 = 0xBF = Read Status Byte
0 0 0 1 0 = 0x8B = Reinitialize Status Byte
0 1 0 0 1 = 0xA7 = Initialize Read Sequence
1 0 0 1 1 = 0xCF = Load
1 0 1 0 0 = 0xD3 = Continue
0 0 0 0 1 = 0x87 = Enable DMA
0 0 0 0 0 = 0x83 = Disable DMA
+-- 0 1 1 1 0 = 0xBB = Read Mask Follows
|
D7 D6 D5 D4 D3 D2 D1 D0 READ MASK
0 | | | | | | |
| | | | | | V
D7 D6 D5 D4 D3 D2 D1 D0 Status Byte
| | | | | |
| | | | | V
D7 D6 D5 D4 D3 D2 D1 D0 Byte Counter Low ("High" with core 3.0.5 = bug in core)
| | | | |
| | | | V
D7 D6 D5 D4 D3 D2 D1 D0 Byte Counter High ("Low" with core 3.0.5 = bug in core)
| | | |
| | | V
D7 D6 D5 D4 D3 D2 D1 D0 Port A Address Low
| | |
| | V
D7 D6 D5 D4 D3 D2 D1 D0 Port A Address High
| |
| V
D7 D6 D5 D4 D3 D2 D1 D0 Port B Address Low
|
V
D7 D6 D5 D4 D3 D2 D1 D0 Port B Address High
</pre>
Unimplemented Z80 DMA commands are ignored.

Prior to starting the DMA transfer, a LOAD command must be issued to copy the Port A and Port B addresses into the DMA's internal pointers. Then an 'Enable DMA' command is issued to start the DMA. The last LOAD command before ENABLE must be done with correct transfer direction set.

The 'Continue' command resets the DMA's byte counter so that a following 'Enable DMA' allows the DMA to repeat the last transfer but using the current internal address pointers. I.e. it continues from where the last copy operation left off.

Reset and Reset Port A/B Timing commands on zxnDMA do reset also prescalar value.

Registers can be read via an IO read from the DMA port after setting the read mask. (At power up the read mask is set to 0x7f). Register values are the current internal DMA counter values. So 'Port Address A Low' is the lower 8-bits of Port A’s next transfer address. Once the end of the read mask is reached, further reads loop around to the first one.

The format of the DMA status byte is as follows:

<pre>00E1101T</pre>

E is set to 0 if the total block length has been transferred at least once.

T is set to 1 if at least one byte has been transferred.

== Operating speed ==
The zxnDMA operates at the same speed as the CPU, that is 3.5MHz, 7MHz, 14MHz or 28Mhz. This is a contended clock that is modified by the ULA and the auto-slowdown by [[Layer 2|Layer2]] (which only occurred in Next core's 1 and 2, the limitation was lifted in core 3.0).

The (pre-core 3.0) auto-slowdown occurs without user intervention if speed exceeds 7Mhz and the active Layer2 display is being generated (higher speed operation resumes when the active Layer2 display is not generated). Programmers do NOT need to account for speed differences regarding DMA transfers as this happens automatically.

Because of this, the cycle lengths for Ports A and B can be set to their minimum values without ill effects. The cycle lengths specified for Ports A and B are intended to selectively slow down read or write cycles for hardware that cannot operate at the DMA's full speed.

== The DMA and Interrupts ==
The zxnDMA cannot currently generate [[Interrupts|interrupts]].

The other side of this is that while the DMA controls the bus, the Z80 cannot respond to interrupts. On the Z80, the NMI interrupt is edge triggered so if an NMI occurs the fact that it occurred is stored internally in the Z80 so that it will respond when it is woken up. On the other hand, maskable interrupts are level triggered. That is, the Z80 must be active to regularly sample the /INT line to determine if a maskable interrupt is occurring. On the Spectrum and the ZX Next, the ULA (and line interrupt) are only asserted for a fixed amount of time ~30 cycles at 3.5MHz. If the DMA is executing a transfer while the interrupt is asserted, the CPU will not be able to see this and it will most likely miss the interrupt. In burst mode, with large-enough prescalar value, the CPU will never miss these interrupts, although this may change if multiple channels are implemented.

== Programming examples ==
A simple way to program the DMA is to walk down the list of registers WR0-WR5, sending desired settings to each. Then start the DMA by sending a LOAD command followed by an ENABLE_DMA command to WR6. Once more familiar with the DMA, you will discover that the amount of information sent can be reduced to what changes between transfers.

=== Assembly ===
Short example program to DMA memory to the screen, then DMA a sprite image from memory to sprite RAM, and then showing said sprite scrolling across the screen.

<pre>;------------------------------------------------------------------------------
; sjasmplus extra options to enable Z80N, stricter syntax and Next device
opt --zxnext --syntax=abf : device zxspectrumnext
;------------------------------------------------------------------------------
; DEFINE testing ; uncomment to produce NEX file (instead of DOT)
;------------------------------------------------------------------------------
; DMA (Register 6)
;
;------------------------------------------------------------------------------
;zxnDMA programming example
;------------------------------------------------------------------------------
;(c) Jim Bagley
;------------------------------------------------------------------------------
DMA_RESET equ $c3
DMA_RESET_PORT_A_TIMING equ $c7
DMA_RESET_PORT_B_TIMING equ $cb
DMA_LOAD equ $cf ; %11001111
DMA_CONTINUE equ $d3
DMA_DISABLE_INTERUPTS equ $af
DMA_ENABLE_INTERUPTS equ $ab
DMA_RESET_DISABLE_INTERUPTS equ $a3
DMA_ENABLE_AFTER_RETI equ $b7
DMA_READ_STATUS_BYTE equ $bf
DMA_REINIT_STATUS_BYTE equ $8b
DMA_START_READ_SEQUENCE equ $a7
DMA_FORCE_READY equ $b3
DMA_DISABLE equ $83
DMA_ENABLE equ $87
DMA_WRITE_REGISTER_COMMAND equ $bb
DMA_BURST equ %11001101
DMA_CONTINUOUS equ %10101101
ZXN_DMA_PORT equ $6b
SPRITE_STATUS_SLOT_SELECT equ $303B
SPRITE_IMAGE_PORT equ $5b
SPRITE_INFO_PORT equ $57
;------------------------------------------------------------------------------

IFDEF testing
org $5800
block 32*24, $38 ; default ULA attributes
org $6000
ELSE
org $2000
ENDIF

start
ld hl,$0000
ld de,$4000
ld bc,$800
call TransferDMA ; copy some random data to the screen pointing
; to ROM for now, for the purpose of showing
; how to do a DMA copy.
ld a,0 ; sprite image number we want to update
ld bc,SPRITE_STATUS_SLOT_SELECT
out (c),a ; set the sprite image number
ld bc,1*256 ; number to transfer (1)
ld hl,testsprite ; from
call TransferDMASprite ; transfer to sprite ram

nextreg 21,1 ; turn sprite on. for more info on this check
; out https://www.specnext.com/tbblue-io-port-system/
ld de,0
ld (xpos),de ; set initial X position ( doesn't need it for
; this demo, but if you run the .loop again it
; will continue from where it was
ld a,$20
ld (ypos),a ; set initial Y position

.loop
ld a,0 ; sprite number we want to position
ld bc,SPRITE_STATUS_SLOT_SELECT
out (c),a
ld de,(xpos)
ld hl,(ypos) ; ignores H so doing this rather than
; ld a,(ypos):ld l,a
ld bc,(image) ; not flipped or palette shifted
call SetSprite

halt

ld de,(xpos)
inc de
ld (xpos),de
ld a,d
cp $01
jr nz,.loop ; if high byte of xpos is not 1 (right of
; screen )
ld a,e
cp $20+1
jr nz,.loop ; if low byte is not $21 just off the right of
; the screen, $20 is off screen but as the
; INC DE is just above and not updated sprite
; after it, it needs to be $21
xor a
ret ; return back to basic with OK

xpos dw 0 ; x position
ypos db 0 ; y position
; these next two BITS and IMAGE are swapped
; as bits needs to go into B register
image db 0+$80 ; use image 0 (for the image we transfered)
; +$80 to set the sprite to active
bits db 0 ; not flipped or palette shifted

c1 = %11100000
c2 = %11000000
c3 = %10100000
c4 = %10000000
c5 = %01100000
c6 = %01000000
c7 = %00100000
c8 = %00000000

testsprite
db c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1
db c1,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c1
db c1,c2,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c2,c1
db c1,c2,c3,c4,c4,c4,c4,c4,c4,c4,c4,c4,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c5,c5,c5,c5,c5,c5,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c6,c6,c6,c6,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c7,c7,c7,c7,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c7,c8,c8,c7,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c7,c8,c8,c7,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c7,c7,c7,c7,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c6,c6,c6,c6,c6,c6,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c5,c5,c5,c5,c5,c5,c5,c5,c4,c3,c2,c1
db c1,c2,c3,c4,c4,c4,c4,c4,c4,c4,c4,c4,c4,c3,c2,c1
db c1,c2,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c3,c2,c1
db c1,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c2,c1
db c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1,c1

;-------------------------------------------------
; de = X
; l = Y
; b = bits
; c = sprite image
SetSprite
push bc
ld bc,SPRITE_INFO_PORT
out (c),e ; Xpos
out (c),l ; Ypos
pop hl
ld a,d
and 1
or h
out (c),a
ld a,l:or $80
out (c),a ; image
ret

;--------------------------------
; hl = source
; de = destination
; bc = length
;--------------------------------
TransferDMA
di
ld (DMASource),hl
ld (DMADest),de
ld (DMALength),bc
ld hl,DMACode
ld b,DMACode_Len
ld c,ZXN_DMA_PORT
otir
ei
ret

DMACode db DMA_DISABLE
db %01111101 ; R0-Transfer mode, A -> B, write adress
; + block length
DMASource dw 0 ; R0-Port A, Start address
; (source address)
DMALength dw 0 ; R0-Block length (length in bytes)
db %01010100 ; R1-write A time byte, increment, to
; memory, bitmask
db %00000010 ; 2t
db %01010000 ; R2-write B time byte, increment, to
; memory, bitmask
db %00000010 ; R2-Cycle length port B
db DMA_CONTINUOUS ; R4-Continuous mode (use this for block
; transfer), write dest adress
DMADest dw 0 ; R4-Dest address (destination address)
db %10000010 ; R5-Restart on end of block, RDY active
; LOW
db DMA_LOAD ; R6-Load
db DMA_ENABLE ; R6-Enable DMA

DMACode_Len equ $-DMACode

;------------------------------------------------------------------------------
; hl = source
; bc = length
; set port to write to with TBBLUE_REGISTER_SELECT
; prior to call
;------------------------------------------------------------------------------
TransferDMAPort
di
ld (DMASourceP),hl
ld (DMALengthP),bc
ld hl,DMACodeP
ld b,DMACode_LenP
ld c,ZXN_DMA_PORT
otir
ei
ret

DMACodeP db DMA_DISABLE
db %01111101 ; R0-Transfer mode, A -> B, write adress
; + block length
DMASourceP dw 0 ; R0-Port A, Start address (source address)
DMALengthP dw 0 ; R0-Block length (length in bytes)
db %01010100 ; R1-read A time byte, increment, to
; memory, bitmask
db %00000010 ; R1-Cycle length port A
db %01101000 ; R2-write B time byte, increment, to
; memory, bitmask
db %00000010 ; R2-Cycle length port B
db %10101101 ; R4-Continuous mode (use this for block
; transfer), write dest adress
dw $253b ; R4-Dest address (destination address)
db %10000010 ; R5-Restart on end of block, RDY active
; LOW
db DMA_LOAD ; R6-Load
db DMA_ENABLE ; R6-Enable DMA

DMACode_LenP equ $-DMACodeP
;------------------------------------------------------------------------------
; hl = source
; bc = length
;------------------------------------------------------------------------------
TransferDMASprite
di
ld (DMASourceS),hl
ld (DMALengthS),bc
ld hl,DMACodeS
ld b,DMACode_LenS
ld c,ZXN_DMA_PORT
otir
ei
ret

DMACodeS db DMA_DISABLE
db %01111101 ; R0-Transfer mode, A -> B, write adress
; + block length
DMASourceS dw 0 ; R0-Port A, Start address (source address)
DMALengthS dw 0 ; R0-Block length (length in bytes)
db %01010100 ; R1-read A time byte, increment, to
; memory, bitmask
db %00000010 ; R1-Cycle length port A
db %01101000 ; R2-write B time byte, increment, to
; memory, bitmask
db %00000010 ; R2-Cycle length port B
db %10101101 ; R4-Continuous mode (use this for block
; transfer), write dest adress
dw SPRITE_IMAGE_PORT ; R4-Dest address (destination address)
db %10000010 ; R5-Restart on end of block, RDY active
; LOW
db DMA_LOAD ; R6-Load
db DMA_ENABLE ; R6-Enable DMA
DMACode_LenS equ $-DMACodeS
;------------------------------------------------------------------------------
; de = dest, a = fill value, bc = lenth
;------------------------------------------------------------------------------
DMAFill
di
ld (FillValue),a
ld (DMACDest),de
ld (DMACLength),bc
ld hl,DMACCode
ld b,DMACCode_Len
ld c,ZXN_DMA_PORT
otir
ei
ret

FillValue db 22
DMACCode db DMA_DISABLE
db %01111101
DMACSource dw FillValue
DMACLength dw 0
db %00100100,%00010000,%10101101
DMACDest dw 0
db DMA_LOAD,DMA_ENABLE
DMACCode_Len equ $-DMACCode

;------------------------------------------------------------------------------
; End of file
;------------------------------------------------------------------------------

IFDEF testing
savenex open "DMAtest.nex", start, $FF00
savenex bank 5
ELSE
fin
savebin "DMATEST",start,fin-start
ENDIF
</pre>

Based on original text by: Allen Albright & Mike Dailly with input by Jim Bagley, Lyndon J Sharp and Phoebus R. Dokos

== Technical details (core 3.1.3+) ==

The Zilog/zxnDMA mode is now selected by using the particular I/O port number ({{PortNo|$xx6B}} for zxnDMA mode, {{PortNo|$xx0B}} for Zilog mode). The bit 6 in {{NextRegNo|$06}} is not DMA related any more and will be reused for something different.

The "counter" RR1-RR2 read back after transfer has correct byte order since core 3.1.4.

Other differences described below in "3.0.5" remains (but from practical point of view the Zilog DMA emulation in 3.1.4 is near-perfect, all the remaining differences are very minor).

== Technical details (core 3.0.5) ==

=== Zilog DMA compatibility mode ===
In Zilog DMA compatibility mode (bit 6 of {{NextRegNo|$06}}) the zxnDMA will mostly work as expected, but there are few differences in behaviour which may eventually throw off some rare SW, here is the list of the known differences (most of them describe also how the zxnDMA mode works):

The LOAD command must be issued with correct transfer direction, loading addresses in opposite direction and flipping direction afterward will mismatch the source/destination address data (Zilog/UA858D DMA chips are also sensitive to direction flip after LOAD, but the resulting transfer quirks in different way, reading source data byte after write, offsetting whole transfer by one and damaging start/end of sequence).
(does apply also to zxnDMA mode)

The LOAD command will NOT destroy the already issued "Initialize Read Sequence" - this is how even the original Zilog documentation describes the DMA chip operation, but the real Zilog DMA and UA858D (clone chip) both destroy read sequence upon LOAD command (zxnDMA is better).
(does apply also to zxnDMA mode)

The content of registers read back after finished transfer differs: the counter has swapped LSB with MSB byte, and both addresses will be adjusted length+1 times (Zilog/UA858D will return destination address adjusted only length-many times).
(does apply also to zxnDMA mode, except addresses are adjusted only "length" times of course, counter has still swapped bytes)

Any read of zxnDMA port without pending read request (commands "Read Status Byte" or "Initialize Read Sequence") will return status byte (Zilog will return random value vaguely similar to status byte, but incorrect, UA858D will return zero).
(does apply also to zxnDMA mode)

Status byte doesn't have bit 0 set (the "T" bit in description above).
(does apply also to zxnDMA mode)

Be aware that both custom timing cycles count, and prescalar values are preserved in zxnDMA even when future write to WR1/WR2 does skip these particular bytes. To reset prescalar or cycles timing, write explicitly zero into prescalar register or use commands reset/reset-port-timing.
(does apply also to zxnDMA mode, the prescalar works only in zxnDMA mode)

The destination port address is LOAD-ed even when it is "fixed" type (Contrary to Zilog DMA, which requires you to load such port as "source", flip the direction after and re-LOAD again with correct direction. UA858D chip does also load destination port address in any case, just like zxnDMA).
(does apply also to zxnDMA mode)

=== zxnDMA mode vs Zilog mode ===

In zxnDMA mode length of transfer is equal to the length written to WR0 register, port addresses are adjusted also only length-times.

Prescalar value will affect speed of transfer (use zero to switch prescalar off) (in burst mode during the extra idle time the CPU receives control back and can execute further instructions, in continuous mode the transfer will keep blocking CPU even when "slow" transfer is being done).

MAME:Plugins and Scripts

2025-11-29T08:42:41Z

Ped7g: adding first version of usage notes (TODO verify and cross-link with installation notes / mame.ini lore)

To load a plugin/script you can use options -plugin and -script on command line, example:
<pre>
mame -plugin skipstartupframes -script profiler
</pre>
Or you can select them from the MAME UI (make sure the files are in corresponding plugins/ and scripts/ folders).

These MAME plugins and scripts may be of interest to Next developers and end-users:

=Plugins=

== [https://github.com/Threetwosevensixseven/MAMENextPlugins nextfaststart] ==
Minimizes MAME Next Machine boot time, by allowing code running inside the emulator to control MAME execution speed. Useful for developers.
Release: [https://github.com/Threetwosevensixseven/MAMENextPlugins/releases/latest Yes]
Source: [https://github.com/Threetwosevensixseven/MAMENextPlugins/blob/main/src/plugins/nextfaststart/init.lua Yes]

== [https://github.com/Jakobud/skipstartupframes skipstartupframes ] ==
Another plugin to speedup MAME boot time, by specifying a number of frames to run at full speed for each machine being emulated. More general, and useful for end-users or developers.
Release: [https://github.com/Jakobud/skipstartupframes/releases/tag/v3.0.0 Yes]
Source: [https://github.com/Jakobud/skipstartupframes/tree/main/src Yes]

== [https://github.com/Threetwosevensixseven/MAMENextPlugins debugstart] ==
Allows to use the MAME debugger later, without compromising startup speed or needing keys to be pressed to continue at startup.
Release: [https://github.com/Threetwosevensixseven/MAMENextPlugins/releases/latest Yes]
Source: [https://github.com/Threetwosevensixseven/MAMENextPlugins/blob/main/src/plugins/debugstart/init.lua Yes]

=Scripts=

== [https://github.com/taylorza/MAMEScripts/tree/main/scripts profiler.lua] ==
A simple on-screen profiler (overlay) designed for the ZX Spectrum Next that tracks up to 8 timers using writes to NEXTREG 127 (0x7F) to control the timers.
[https://github.com/taylorza/MAMEScripts/blob/main/README.md#profilerlua Documentation]

MAME:Installing

2025-11-29T08:34:50Z

Ped7g: fix plugins page name after it was renamed

Miscellaneous

2025-11-27T01:25:31Z

Ped7g: hijacking hdfmonkey github repo to my patched fork

=== ''[http://simon.mooli.org.uk/nextech/ Simon N Goodwin's Spectrum Next Page]'' ===
: A host of utilites for NextBasic written by Simon, NextPort, Nextramon,
: Next MGT Reader amongst other treasures.

=== ''[https://github.com/kounch/vscode_zx Visual Studio Code Tasks and Scripts]'' ===
: Some VSC goodies by kounch to work with NextBasic and ZX Basic

=== ''[https://github.com/stefanbylund/zxnext_bmp_tools Next BMP Tools]'' ===
: The Next BMP tools are BMP image conversion tools targeting the Sinclair ZX Spectrum Next written
: by Stefan Bylund

=== ''[https://wiki.twistedraven.net/index.php?title=Downloads Octarine Studio]'' ===
: Octarine Studio by Guy Black is a PC based editing tool that currently supports palettes and tiles.

=== ''[https://www.specnext.com/forum/viewtopic.php?f=7&t=351 UDGeedNext Sprite Editor]'' ===
: Windows based sprite editor written by some guy I have never heard of. Currently supports 8 bit
: palettes. 9 bit and 4 bit sprites should be added at some point....

=== ''[http://worldofpaul.com/speccyart/ Speccy Art]'' ===
: An online drawing experience that aims to help you create Sinclair ZX Spectrum-like images.
: Supports the classic ULA mode (256x192 pixels with 8x8 attribute squares and 15 classic ZX colours)
: Supports the Timex HiColour mode (256x192 pixels with 8x1 attribute rectangles and 15 classic ZX colours)
: Images can be saved and loaded through TAP files or exported into SCR/SHC files.

=== ''[https://github.com/varmfskii/zxnext_tools ZX Spectrum Next tools by Theodore (Alex) Evans]'' ===
: Multiple tools for various graphics conversions and processing
: zxnftp for transferring files between PC and Next via the ESP WiFi module

=== ''[https://gitlab.com/zxnexttools/nim Next Image Manipulator by Matt Davies]'' ===
: windows command line tool to convert various image and palette formats to custom "nip/nim" binary formats which are simple enough to parse (or include directly into source with assemblers supporting binary includes)
: this is early version (already working, build it from source), but further expansion to support also tiles/etc may happen in future

=== ''[https://github.com/ped7g/hdfmonkey hdfmonkey (with jjjs patch applied)]'' ===
: A Swiss Army Knife for working with FAT partitions on Spectrum emulator HDF images.
: The [https://www.specnext.com/forum/viewtopic.php?p=16108 jjjs builds by johnnyo] also support the [https://www.specnext.com/latestdistro/ imperfect SD card images of the distribution for emulators from specnext.com], and the forum post includes executable binaries for Windows, Linux, and macOS.
: Original [https://github.com/gasman/hdfmonkey gasman's version] (missing the jjjs fixes)

=== ''[https://zeroonetwenty.com/blueharvest/ Blue Harvest]'' ===
: A convenient macOS tool to keep SD cards free from macOS metadata. Free 30-day trial.

=== ''[https://github.com/MrKWatkins/ZXSpectrumNextTests ZXSpectrumNextTests by Kevin Watkins and Peter Helcmanovsky]'' ===
: Suite of tests exercising various aspects of ZX Spectrum Next
: Tests for: Next registers, Copper, Sprites, Layer2, ULA modes, Extended ULA, Layers mixing modes, Z80N instructions, ...
: ASM Sources for each test (sjasmplus assembler syntax)

=== ''[https://github.com/Threetwosevensixseven/ZXSpectrumNextTests ZXSpectrumNextTests by Robin Verhagen-Guest]'' ===
: Suite of tests exercising various aspects of ZX Spectrum Next (yes, one more :) )
: Tests for: DMA, MMU paging, Layers mixing modes
: ASM Sources for each test (Zeus assembler syntax)

=== ''<div id="WASPtools" name="WASPtools">WASPtools by Phoebus Dokos</div>'' ===
WASPtools is a suite of tools comprised of a palette manipulator, a sprite editor, a graphics converter, and tilemap editor (both virtual tilemaps for say Layer2, and the hardware tilemap mode).

=== ''[https://zx.remysharp.com Online sprite, palette and tilemap editor by Remy Sharp]'' ===
: Browser based tooling that works fully offline
: Sprite editor with import and export tools
: Tile map editor with 16x16 and 8x8 tile support
: Full 512 palette import and export
: Also includes image conversion tools from PNG to 8 bit BMP and SL2 formats

=== ''[https://zingot.itch.io/palette-knife Palette knife by Zingot]'' ===
: Windows GUI tool to create, combine and edit palettes
: Supports different file formats and bit depths (also Next unrelated)

=== ''[https://marketplace.visualstudio.com/items?itemName=remysharp.nextbasic NextBASIC extension for VS Code by Remy Sharp]'' ===
: Syntax highlighting, folding and definition jumping
: Export and import .bas to .txt and visa versa
: Inline help, line number completion and inline error checking
: Launches Cspect with minimal configuration

=== ''[https://www.specnext.com/forum/viewtopic.php?f=17&t=1715 NextSync WiFi file transferring by Jari Komppa]'' ===
: Run "server" code on your local PC (python 3 required)
: Run ".sync" on the Next
: Changed files will be copied from PC to Next by ESP WiFi module

=== ''[[NXtel:Introduction|NXtel by Robin Verhagen Guest]]'' ===
: Comprises a TCP/IP Videotext server, a Next client, and a page editor website
: Content is community created and supervised by a small team of editors.

Miscellaneous

2025-11-27T01:20:17Z

Ped7g: adding palette knife link (some obsolete version was posted on specnext forum, but the project evolved and is hosted on itchio now)

=== ''[http://simon.mooli.org.uk/nextech/ Simon N Goodwin's Spectrum Next Page]'' ===
: A host of utilites for NextBasic written by Simon, NextPort, Nextramon,
: Next MGT Reader amongst other treasures.

=== ''[https://github.com/kounch/vscode_zx Visual Studio Code Tasks and Scripts]'' ===
: Some VSC goodies by kounch to work with NextBasic and ZX Basic

=== ''[https://github.com/stefanbylund/zxnext_bmp_tools Next BMP Tools]'' ===
: The Next BMP tools are BMP image conversion tools targeting the Sinclair ZX Spectrum Next written
: by Stefan Bylund

=== ''[https://wiki.twistedraven.net/index.php?title=Downloads Octarine Studio]'' ===
: Octarine Studio by Guy Black is a PC based editing tool that currently supports palettes and tiles.

=== ''[https://www.specnext.com/forum/viewtopic.php?f=7&t=351 UDGeedNext Sprite Editor]'' ===
: Windows based sprite editor written by some guy I have never heard of. Currently supports 8 bit
: palettes. 9 bit and 4 bit sprites should be added at some point....

=== ''[http://worldofpaul.com/speccyart/ Speccy Art]'' ===
: An online drawing experience that aims to help you create Sinclair ZX Spectrum-like images.
: Supports the classic ULA mode (256x192 pixels with 8x8 attribute squares and 15 classic ZX colours)
: Supports the Timex HiColour mode (256x192 pixels with 8x1 attribute rectangles and 15 classic ZX colours)
: Images can be saved and loaded through TAP files or exported into SCR/SHC files.

=== ''[https://github.com/varmfskii/zxnext_tools ZX Spectrum Next tools by Theodore (Alex) Evans]'' ===
: Multiple tools for various graphics conversions and processing
: zxnftp for transferring files between PC and Next via the ESP WiFi module

=== ''[https://gitlab.com/zxnexttools/nim Next Image Manipulator by Matt Davies]'' ===
: windows command line tool to convert various image and palette formats to custom "nip/nim" binary formats which are simple enough to parse (or include directly into source with assemblers supporting binary includes)
: this is early version (already working, build it from source), but further expansion to support also tiles/etc may happen in future

=== ''[https://github.com/gasman/hdfmonkey hdfmonkey]'' ===
: A Swiss Army Knife for working with FAT partitions on Spectrum emulator HDF images. The more recent [https://www.specnext.com/forum/viewtopic.php?p=16108 hdfmonkey jjjs builds by johnnyo] also support the [https://www.specnext.com/latestdistro/ imperfect SD card images of the distribution for emulators from specnext.com], and they include executable binaries for Windows, Linux, and macOS.

=== ''[https://zeroonetwenty.com/blueharvest/ Blue Harvest]'' ===
: A convenient macOS tool to keep SD cards free from macOS metadata. Free 30-day trial.

=== ''[https://github.com/MrKWatkins/ZXSpectrumNextTests ZXSpectrumNextTests by Kevin Watkins and Peter Helcmanovsky]'' ===
: Suite of tests exercising various aspects of ZX Spectrum Next
: Tests for: Next registers, Copper, Sprites, Layer2, ULA modes, Extended ULA, Layers mixing modes, Z80N instructions, ...
: ASM Sources for each test (sjasmplus assembler syntax)

=== ''[https://github.com/Threetwosevensixseven/ZXSpectrumNextTests ZXSpectrumNextTests by Robin Verhagen-Guest]'' ===
: Suite of tests exercising various aspects of ZX Spectrum Next (yes, one more :) )
: Tests for: DMA, MMU paging, Layers mixing modes
: ASM Sources for each test (Zeus assembler syntax)

=== ''<div id="WASPtools" name="WASPtools">WASPtools by Phoebus Dokos</div>'' ===
WASPtools is a suite of tools comprised of a palette manipulator, a sprite editor, a graphics converter, and tilemap editor (both virtual tilemaps for say Layer2, and the hardware tilemap mode).

=== ''[https://zx.remysharp.com Online sprite, palette and tilemap editor by Remy Sharp]'' ===
: Browser based tooling that works fully offline
: Sprite editor with import and export tools
: Tile map editor with 16x16 and 8x8 tile support
: Full 512 palette import and export
: Also includes image conversion tools from PNG to 8 bit BMP and SL2 formats

=== ''[https://zingot.itch.io/palette-knife Palette knife by Zingot]'' ===
: Windows GUI tool to create, combine and edit palettes
: Supports different file formats and bit depths (also Next unrelated)

=== ''[https://marketplace.visualstudio.com/items?itemName=remysharp.nextbasic NextBASIC extension for VS Code by Remy Sharp]'' ===
: Syntax highlighting, folding and definition jumping
: Export and import .bas to .txt and visa versa
: Inline help, line number completion and inline error checking
: Launches Cspect with minimal configuration

=== ''[https://www.specnext.com/forum/viewtopic.php?f=17&t=1715 NextSync WiFi file transferring by Jari Komppa]'' ===
: Run "server" code on your local PC (python 3 required)
: Run ".sync" on the Next
: Changed files will be copied from PC to Next by ESP WiFi module

=== ''[[NXtel:Introduction|NXtel by Robin Verhagen Guest]]'' ===
: Comprises a TCP/IP Videotext server, a Next client, and a page editor website
: Content is community created and supervised by a small team of editors.

Development Tools:Linux setup

2025-11-27T01:01:15Z

Ped7g: Switching hdfmonkey to ped7g's github repo archiving jjjs patched version

MAME:Installing

2025-11-18T00:25:20Z

Ped7g: Moving download links of tbblue.zip and image under "Get" chapter, added more info about where MAME looks for ini and other files and adding few more links to "links" part.

MAME:Tricks

2025-11-15T23:31:18Z

Ped7g:

== HOW-TO ==

=== Save state for quick loading of desired file through browser ===

# launch from command line: mame tbblue ... -d
# F5 - unpause emulation to boot NextZXOS
# Select Browser
# Go to the folder where the *.nex file will be... move the cursor to this file (we'll go here after the soft reset)
# F3 - soft reset (you can do this in the debugger)
# F5 - let's go
# Set breakpoint bp 2411
# Wait for the menu... select Browser
# The breakpoint 2411 should trigger
# Set the cursor to 2424 (enter from the keyboard polling cycle)
# F4 - run to cursor
# statesave n
# Ctrl+Q exit MAME (TODO check the key, it's debugger hotkey I guess?)

=== Load saved state ===

# launch from command line: mame tbblue ... -state n
# test your code
# exit MAME
# Copy the new version of the super game to the image file
# Repeat

MAME:Tricks

2025-11-15T23:26:33Z

Ped7g: Save/Load state trick to speed up startup of MAME (skipping Next's boot sequence)

= HOW-TO =

== Save state for quick loading of desired file through browser ==

# launch from command line: mame tbblue ... -d
# F5 - unpause emulation to boot NextZXOS
# Select Browser
# Go to the folder where the *.nex file will be... move the cursor to this file (we'll go here after the soft reset)
# F3 - soft reset (you can do this in the debugger)
# F5 - let's go
# Set breakpoint bp 2411
# Wait for the menu... select Browser
# The breakpoint 2411 should trigger
# Set the cursor to 2424 (enter from the keyboard polling cycle)
# F4 - run to cursor
# statesave n
# Ctrl+Q exit MAME (TODO check the key, it's debugger hotkey I guess?)

== Load saved state ==

# launch from command line: mame tbblue ... -state n
# test your code
# exit MAME
# Copy the new version of the super game to the image file
# Repeat

MAME:Installing

2025-11-15T23:13:20Z

Ped7g:

MAME:Installing

2025-11-15T22:56:08Z

Ped7g:

Emulators

2025-11-15T22:47:49Z

Ped7g:

===== WARNING: =====

The current Next emulators are work-in-progress, missing several features of real HW Next, and emulating other features in less than cycle-accurate way (which become a "norm" for classic ZX Spectrum after two decades of emulators development). The differences in results between real Next and CSpect or ZEsarUX are to be expected - as a developer test your SW also with real HW to find any problems early. It may also help to read the known-bugs pages to have some rough idea what works and how accurately. There're also multiple test-suites and free games and demos which you can try to go through and compare the emulator output with real machine, to get familiar with the differences and adjust your workflow and expectations.
 

Also make sure to explore the command line options and configuration of each emulator, as there are multiple ways how to run them with different fidelity of emulation. When in doubt, you are welcome to join the official ZX Spectrum Next discord chat and ask for help at #emulator-help channel.
 

Currently the most UI and performance friendly emulator seems to be #CSpect, the most accurate and performant emulator is MAME.

{| class="wikitable"
!Name||Author||Known bugs||Description||OS||Source||Maintained
|-
|[https://mdf200.itch.io/cspect CSpect]||[https://lemmings.info/about/ Mike Dailly]||[[CSpect:known bugs|List]]||Emulates many features of the Next and includes a fully featured debugger, complete with 24bit breakpoints and an assembler||Windows ([https://lemmings.info/installing-cspect-on-a-mac/ mac]/[[Development_Tools:Linux_setup##CSpect_emulator|linux]] with mono - mostly works)||No||[https://www.patreon.com/posts/crash-and-cspect-143597332 Statement of maintenance and support]
|-
|[https://www.mamedev.org/ MAME]||[https://github.com/holub holub] (Next), many contributors (MAME)||[[MAME:known bugs|List]]‎||Mature multi-system emulator with relatively recent Next support. See [[MAME:Installing|installation notes]].||Any||[https://github.com/mamedev/mame Yes]||Yes
|-
|[https://gitlab.com/garrylancaster/zenext ZENext]||[https://github.com/chernandezba César Hernández Bañó], [https://gitlab.com/garrylancaster Garry Lancaster]|| |||ZX Next-only fork of ZEsarUX emulating most of the core 3.1.10 features to make it run NextZXOS 2.07 (and possibly 2.08/2.09) (missing some features like CTC timers).||Any||[https://gitlab.com/garrylancaster/zenext Yes]||Occasionally
|-
|[https://github.com/chernandezba/zesarux/releases ZEsarUX]||César Hernández Bañó|||[[ZEsarUX:known bugs|List]]||A full feature emulator including a debugger - sometimes updated to support Next (TBBlue)||Any||[https://github.com/chernandezba/zesarux Yes]||Yes
|-
|[https://github.com/ped7g/zesarux/tree/tbblue_small_fixes2 ZESERUse]||César Hernández Bañó, [https://github.com/ped7g Peter Helcmanovsky]||[[ZESERUse:known bugs|List]]||Fork of older ZEsarUX 8.2 with improved emulation accuracy of (rather old) core 3.1.5||Any||[https://github.com/ped7g/zesarux/tree/tbblue_small_fixes2 Yes]||Rarely
|-
|[http://www.desdes.com/products/oldfiles/zeus.htm Zeus]||[https://www.desdes.com/ Simon Brattel]|| || A PC cross-assembler which includes an IDE and Spectrum 48/128/+2/+3 emulator. Includes support for Next MMU banking, sprites and UART only, with remote debugging on Next hardware.||Windows||No||No
|}

MAME:Installing

2025-11-15T22:44:29Z

Ped7g: .typos

Emulators

2025-11-11T18:01:20Z

Ped7g: Refresh some outdated info and rewording some to make it more concise (dropping details which are useless now, since things like ZESERUse is hopelessly out of date)

===== WARNING: =====

The current Next emulators are work-in-progress, missing several features of real HW Next, and emulating other features in less than cycle-accurate way (which become a "norm" for classic ZX Spectrum after two decades of emulators development). The differences in results between real Next and CSpect or ZEsarUX are to be expected - as a developer test your SW also with real HW to find any problems early. It may also help to read the known-bugs pages to have some rough idea what works and how accurately. There're also multiple test-suites and free games and demos which you can try to go through and compare the emulator output with real machine, to get familiar with the differences and adjust your workflow and expectations.
 

Also make sure to explore the command line options and configuration of each emulator, as there are multiple ways how to run them with different fidelity of emulation. When in doubt, you are welcome to join the official ZX Spectrum Next discord chat and ask for help at #emulator-help channel.
 

Currently the most UI and performance friendly emulator seems to be #CSpect, the most accurate emulator is MAME.

{| class="wikitable"
!Name||Author||Known bugs||Description||OS||Source||Maintained
|-
|CSpect||[https://lemmings.info/about/ Mike Dailly]||[[CSpect:known bugs|List]]||Emulates many features of the Next and includes a fully featured debugger, complete with 24bit breakpoints and an assembler||Windows ([https://lemmings.info/installing-cspect-on-a-mac/ mac]/[[Development_Tools:Linux_setup##CSpect_emulator|linux]] with mono - mostly works)||No||[https://www.patreon.com/posts/change-of-143208075 Yes, privately]
|-
|[https://www.mamedev.org/ MAME]||[https://github.com/holub holub] (Next), many contributors (MAME)||[[MAME:known bugs|List]]‎||Mature multi-system emulator with relatively recent Next support. See [[MAME:Installing|installation notes]].||Any||[https://github.com/mamedev/mame Yes] ([https://github.com/holub/mame bleeding-edge Next])||Yes
|-
|[https://gitlab.com/garrylancaster/zenext ZENext]||[https://github.com/chernandezba César Hernández Bañó], [https://gitlab.com/garrylancaster Garry Lancaster]|| |||ZX Next-only fork of ZEsarUX emulating most of the core 3.1.10 features to make it run NextZXOS 2.07 (and possibly 2.08/2.09) (missing some features like CTC timers).||Any||[https://gitlab.com/garrylancaster/zenext Yes]||Occasionally
|-
|[https://github.com/chernandezba/zesarux/releases ZEsarUX]||César Hernández Bañó|||[[ZEsarUX:known bugs|List]]||A full feature emulator including a debugger - sometimes updated to support Next (TBBlue)||Any||[https://github.com/chernandezba/zesarux Yes]||Yes
|-
|[https://github.com/ped7g/zesarux/tree/tbblue_small_fixes2 ZESERUse]||César Hernández Bañó, [https://github.com/ped7g Peter Helcmanovsky]||[[ZESERUse:known bugs|List]]||Fork of older ZEsarUX 8.2 with improved emulation accuracy of (rather old) core 3.1.5||Any||[https://github.com/ped7g/zesarux/tree/tbblue_small_fixes2 Yes]||Rarely
|-
|[http://www.desdes.com/products/oldfiles/zeus.htm Zeus]||[https://www.desdes.com/ Simon Brattel]|| || A PC cross-assembler which includes an IDE and Spectrum 48/128/+2/+3 emulator. Includes support for Next MMU banking, sprites and UART only, with remote debugging on Next hardware.||Windows||No||No
|}

Copper

2025-10-10T11:56:59Z

Ped7g:

The '''Copper''' is a simple programmed system which allows certain [[Board feature control|Next Registers]] to be altered automatically at certain scanline positions.

"Copper" is a strangulation of "co-processor" and is a term taken from the Amiga which had a similar function. The copper on the Spectrum Next is not associated with the [[RPi0 Acceleration|Raspberry Pi 'coprocessor']].

A program is uploaded to the Copper by sending it, byte by byte, to {{NextRegNo|$60}}. Each Copper instruction is 16 bits wide and there are 2 opcodes with a single bit in an instruction determines the operation and two special case opcodes. In total the four operations are:

{| class="wikitable"
! Opcode !! Bit pattern !! Effect
|-
| WAIT || %1hhhhhhv %vvvvvvvv || Wait for raster line v (0-311) and horizontal position h*8 (h is 0-55) (duration 1 CLOCK)
|-
| MOVE || %0rrrrrrr %vvvvvvvv || Write value '''v''' to Next register '''r''' (duration 2 CLOCKS)
|-
| NOOP || %00000000 %00000000 || Special case of "value 0 to port 0" works as "no operation" (duration 1 CLOCK)
|-
| HALT || %11111111 %11111111 || Special case of "WAIT 63,511" works as "halt" instruction
|}

The copper's program storage is 2k big; since each instruction is 2 bytes it can store exactly 1024 instructions, numbered 0-1023. The copper is controlled by a word accessed through Next Registers {{NextRegNo|$61}} and {{NextRegNo|$62}}. The internal "program counter" ('''CPC''') has 10 bits (0-1023), auto-incrementing it after each instruction, wrapping around after last one back to first one.

The copper control word has the structure: %cc000iii %iiiiiiii. '''I''' is the storage position (0-2047) (for writing instructions with {{NextRegNo|$60}}), and '''c''' is used to set the behaviour mode of the copper, as follows:

{| class="wikitable"
! C bits !! Effect
|-
| %00 || STOP, copper does nothing (CPC keeps its current value)
|-
| %01 || reset CPC to 0, then START
|-
| %10 || START (resumes from current CPC)
|-
| %11 || reset CPC to 0, then START; Also VBLANK does reset CPC to 0
|}

When '''c''' bits are identical to previously written value, the control mode is ignored, and only write-index '''I''' is modified.

If you don't want the copper program to loop infinitely, then you can mark the "end" of the copper program by waiting for a line higher than 311 ("HALT" instruction). Since these lines will never be reached, the copper will essentially halt until reset.

The precise timing and many more details are currently documented in distribution file [https://gitlab.com/thesmog358/tbblue/blob/a0d25589bd28b05c510e528332bcd192bc414ebb/docs/extra-hw/copper/COPPER-v0.1c.TXT "/docs/extra-hw/copper/COPPER-v0.1c.TXT"].

(core 2.0) the copper code is executed at 14MHz, and the COPPER-v0.1c.TXT document above describes timing of the core 2.0. 

(core 3.0) the copper code is executed at 28MHz, the precise timing is not documented yet

From practical test (with the Swedish-flags copper test) the coordinates for WAIT are identical, MOVE is twice as fast (flags are half of original width because each pixel is created by single MOVE instruction).

Important values affecting pixel display are now sampled at the same moment when the pixel is drawn (no test yet to describe what does that mean at sub-pixel accuracy terms and in which order the copper MOVEs should be done with what kind of lead in case you want to set for example 6 different display-affecting registers, by theoretical approach of single MOVE taking half-pixel width you should start precisely 3 pixels ahead of the edge where all values should be set, but YMMV) (overall it's probably much wiser to avoid situations where you need sub-pixel precision, or test with the real board heavily)

Extra notes based on discussion with AA at Next discord: 
The copper is 16-bit:
* it fetches its 16-bit instruction in 1 T (16b atomic fetch from copper code memory) and executes it
* NOOP (alias MOVE without writing nextreg) takes thus 1 T in total
* MOVE with writing nextreg is finished in first T state, but then there is 1 T delay to not 100% occupy nextreg logic (starving CPU/DMA of access). So MOVE instruction takes 2 T in total and nextreg reads new value 2 T after MOVE execution.

Copper

2025-10-10T11:53:28Z

Ped7g:

The '''Copper''' is a simple programmed system which allows certain [[Board feature control|Next Registers]] to be altered automatically at certain scanline positions.

"Copper" is a strangulation of "co-processor" and is a term taken from the Amiga which had a similar function. The copper on the Spectrum Next is not associated with the [[RPi0 Acceleration|Raspberry Pi 'coprocessor']].

A program is uploaded to the Copper by sending it, byte by byte, to {{NextRegNo|$60}}. Each Copper instruction is 16 bits wide and there are 2 opcodes with a single bit in an instruction determines the operation and two special case opcodes. In total the four operations are:

{| class="wikitable"
! Opcode !! Bit pattern !! Effect
|-
| WAIT || %1hhhhhhv %vvvvvvvv || Wait for raster line v (0-311) and horizontal position h*8 (h is 0-55) (duration 1 CLOCK)
|-
| MOVE || %0rrrrrrr %vvvvvvvv || Write value '''v''' to Next register '''r''' (duration 2 CLOCKS)
|-
| NOOP || %00000000 %00000000 || Special case of "value 0 to port 0" works as "no operation" (duration 1 CLOCK)
|-
| HALT || %11111111 %11111111 || Special case of "WAIT 63,511" works as "halt" instruction
|}

The copper's program storage is 2k big; since each instruction is 2 bytes it can store exactly 1024 instructions, numbered 0-1023. The copper is controlled by a word accessed through Next Registers {{NextRegNo|$61}} and {{NextRegNo|$62}}. The internal "program counter" ('''CPC''') has 10 bits (0-1023), auto-incrementing it after each instruction, wrapping around after last one back to first one.

The copper control word has the structure: %cc000iii %iiiiiiii. '''I''' is the storage position (0-2047) (for writing instructions with {{NextRegNo|$60}}), and '''c''' is used to set the behaviour mode of the copper, as follows:

{| class="wikitable"
! C bits !! Effect
|-
| %00 || STOP, copper does nothing (CPC keeps its current value)
|-
| %01 || reset CPC to 0, then START
|-
| %10 || START (resumes from current CPC)
|-
| %11 || reset CPC to 0, then START; Also VBLANK does reset CPC to 0
|}

When '''c''' bits are identical to previously written value, the control mode is ignored, and only write-index '''I''' is modified.

If you don't want the copper program to loop infinitely, then you can mark the "end" of the copper program by waiting for a line higher than 311 ("HALT" instruction). Since these lines will never be reached, the copper will essentially halt until reset.

The precise timing and many more details are currently documented in distribution file [https://gitlab.com/thesmog358/tbblue/blob/a0d25589bd28b05c510e528332bcd192bc414ebb/docs/extra-hw/copper/COPPER-v0.1c.TXT "/docs/extra-hw/copper/COPPER-v0.1c.TXT"].

(core 2.0) the copper code is executed at 14MHz, and the COPPER-v0.1c.TXT document above describes timing of the core2.0.
(core 3.0) the copper code is executed at 28MHz, the precise timing is not documented yet

From practical test (with the Swedish-flags copper test) the coordinates for WAIT are identical, MOVE is twice as fast (flags are half of original width because each pixel is created by single MOVE instruction).

Important values affecting pixel display are now sampled at the same moment when the pixel is drawn (no test yet to describe what does that mean at sub-pixel accuracy terms and in which order the copper MOVEs should be done with what kind of lead in case you want to set for example 6 different display-affecting registers, by theoretical approach of single MOVE taking half-pixel width you should start precisely 3 pixels ahead of the edge where all values should be set, but YMMV) (overall it's probably much wiser to avoid situations where you need sub-pixel precision, or test with the real board heavily)

Extra notes based on discussion with AA at Next discord: 
The copper is 16-bit:
* it fetches its 16-bit instruction in 1 T (16b atomic fetch from copper code memory) and executes it
* NOOP (alias MOVE without writing nextreg) takes thus 1 T in total
* MOVE with writing nextreg is finished in first T state, but then there is 1 T delay to not 100% occupy nextreg logic (starving CPU/DMA of access). So MOVE instruction takes 2 T in total and nextreg reads new value 2 T after MOVE execution.

Copper

2025-10-10T10:05:53Z

Ped7g:

The '''Copper''' is a simple programmed system which allows certain [[Board feature control|Next Registers]] to be altered automatically at certain scanline positions.

"Copper" is a strangulation of "co-processor" and is a term taken from the Amiga which had a similar function. The copper on the Spectrum Next is not associated with the [[RPi0 Acceleration|Raspberry Pi 'coprocessor']].

A program is uploaded to the Copper by sending it, byte by byte, to {{NextRegNo|$60}}. Each Copper instruction is 16 bits wide and there are 2 opcodes with a single bit in an instruction determines the operation and two special case opcodes. In total the four operations are:

{| class="wikitable"
! Opcode !! Bit pattern !! Effect
|-
| WAIT || %1hhhhhhv %vvvvvvvv || Wait for raster line v (0-311) and horizontal position h*8 (h is 0-55) (duration 1 CLOCK)
|-
| MOVE || %0rrrrrrr %vvvvvvvv || Write value '''v''' to Next register '''r''' (duration 2 CLOCKS)
|-
| NOOP || %00000000 %00000000 || Special case of "value 0 to port 0" works as "no operation" (duration 1 CLOCK)
|-
| HALT || %11111111 %11111111 || Special case of "WAIT 63,511" works as "halt" instruction
|}

The copper's program storage is 2k big; since each instruction is 2 bytes it can store exactly 1024 instructions, numbered 0-1023. The copper is controlled by a word accessed through Next Registers {{NextRegNo|$61}} and {{NextRegNo|$62}}. The internal "program counter" ('''CPC''') has 10 bits (0-1023), auto-incrementing it after each instruction, wrapping around after last one back to first one.

The copper control word has the structure: %cc000iii %iiiiiiii. '''I''' is the storage position (0-2047) (for writing instructions with {{NextRegNo|$60}}), and '''c''' is used to set the behaviour mode of the copper, as follows:

{| class="wikitable"
! C bits !! Effect
|-
| %00 || STOP, copper does nothing (CPC keeps its current value)
|-
| %01 || reset CPC to 0, then START
|-
| %10 || START (resumes from current CPC)
|-
| %11 || reset CPC to 0, then START; Also VBLANK does reset CPC to 0
|}

When '''c''' bits are identical to previously written value, the control mode is ignored, and only write-index '''I''' is modified.

If you don't want the copper program to loop infinitely, then you can mark the "end" of the copper program by waiting for a line higher than 311 ("HALT" instruction). Since these lines will never be reached, the copper will essentially halt until reset.

The precise timing and many more details are currently documented in distribution file [https://gitlab.com/thesmog358/tbblue/blob/a0d25589bd28b05c510e528332bcd192bc414ebb/docs/extra-hw/copper/COPPER-v0.1c.TXT "/docs/extra-hw/copper/COPPER-v0.1c.TXT"].

(core 2.0) the copper code is executed at 14MHz, and the COPPER-v0.1c.TXT document above describes timing of the core2.0.
(core 3.0) the copper code is executed at 28MHz, the precise timing is not documented yet

From practical test (with the Swedish-flags copper test) the coordinates for WAIT are identical, MOVE is twice as fast (flags are half of original width because each pixel is created by single MOVE instruction).

Important values affecting pixel display are now sampled at the same moment when the pixel is drawn (no test yet to describe what does that mean at sub-pixel accuracy terms and in which order the copper MOVEs should be done with what kind of lead in case you want to set for example 6 different display-affecting registers, by theoretical approach of single MOVE taking half-pixel width you should start precisely 3 pixels ahead of the edge where all values should be set, but YMMV) (overall it's probably much wiser to avoid situations where you need sub-pixel precision, or test with the real board heavily)

Extra notes based on discussion with AA at Next discord:
The copper is 16-bit :
- it fetches its 16-bit instruction in 1 T (16b atomic fetch from copper code memory) and executes it
- NOOP (alias MOVE without writing nextreg) takes thus 1 T in total
- MOVE with writing nextreg is finished in first T state, but then there is 1 T delay to not 100% occupy nextreg logic (starving CPU/DMA of access). So MOVE instruction takes 2 T in total and nextreg reads new value 2 T after MOVE execution.

Copper

2025-10-10T00:45:17Z

Ped7g:

The '''Copper''' is a simple programmed system which allows certain [[Board feature control|Next Registers]] to be altered automatically at certain scanline positions.

"Copper" is a strangulation of "co-processor" and is a term taken from the Amiga which had a similar function. The copper on the Spectrum Next is not associated with the [[RPi0 Acceleration|Raspberry Pi 'coprocessor']].

A program is uploaded to the Copper by sending it, byte by byte, to {{NextRegNo|$60}}. Each Copper instruction is 16 bits wide and there are 2 opcodes with a single bit in an instruction determines the operation and two special case opcodes. In total the four operations are:

{| class="wikitable"
! Opcode !! Bit pattern !! Effect
|-
| WAIT || %1hhhhhhv %vvvvvvvv || Wait for raster line v (0-311) and horizontal position h*8 (h is 0-55) (duration 1 CLOCK)
|-
| MOVE || %0rrrrrrr %vvvvvvvv || Write value '''v''' to Next register '''r''' (duration 2 CLOCKS)
|-
| NOOP || %00000000 %00000000 || Special case of "value 0 to port 0" works as "no operation" (duration 1 CLOCK)
|-
| HALT || %11111111 %11111111 || Special case of "WAIT 63,511" works as "halt" instruction
|}

The copper's program storage is 2k big; since each instruction is 2 bytes it can store exactly 1024 instructions, numbered 0-1023. The copper is controlled by a word accessed through Next Registers {{NextRegNo|$61}} and {{NextRegNo|$62}}. The internal "program counter" ('''CPC''') has 10 bits (0-1023), auto-incrementing it after each instruction, wrapping around after last one back to first one.

The copper control word has the structure: %cc000iii %iiiiiiii. '''I''' is the storage position (0-2047) (for writing instructions with {{NextRegNo|$60}}), and '''c''' is used to set the behaviour mode of the copper, as follows:

{| class="wikitable"
! C bits !! Effect
|-
| %00 || STOP, copper does nothing (CPC keeps its current value)
|-
| %01 || reset CPC to 0, then START
|-
| %10 || START (resumes from current CPC)
|-
| %11 || reset CPC to 0, then START; Also VBLANK does reset CPC to 0
|}

When '''c''' bits are identical to previously written value, the control mode is ignored, and only write-index '''I''' is modified.

If you don't want the copper program to loop infinitely, then you can mark the "end" of the copper program by waiting for a line higher than 311 ("HALT" instruction). Since these lines will never be reached, the copper will essentially halt until reset.

The precise timing and many more details are currently documented in distribution file [https://gitlab.com/thesmog358/tbblue/blob/a0d25589bd28b05c510e528332bcd192bc414ebb/docs/extra-hw/copper/COPPER-v0.1c.TXT "/docs/extra-hw/copper/COPPER-v0.1c.TXT"].

(core 2.0) the copper code is executed at 14MHz, and the COPPER-v0.1c.TXT document above describes timing of the core2.0.
(core 3.0) the copper code is executed at 28MHz, the precise timing is not documented yet

From practical test (with the Swedish-flags copper test) the coordinates for WAIT are identical, MOVE is twice as fast (flags are half of original width because each pixel is created by single MOVE instruction).

Important values affecting pixel display are now sampled at the same moment when the pixel is drawn (no test yet to describe what does that mean at sub-pixel accuracy terms and in which order the copper MOVEs should be done with what kind of lead in case you want to set for example 6 different display-affecting registers, by theoretical approach of single MOVE taking half-pixel width you should start precisely 3 pixels ahead of the edge where all values should be set, but YMMV) (overall it's probably much wiser to avoid situations where you need sub-pixel precision, or test with the real board heavily)

Extra note from discord by AA: The copper is 16-bit :- it fetches its 16-bit instruction in 1 T and actually all move instructions take 1 T. However if the move is writing to nextreg (ie it's not a nop) then there is a 1 T delay for it to go through the nextreg path for the nextreg write to take effect. While that goes on, the next copper intruction is already executing.

Wiki TODO list

2025-10-07T09:17:22Z

Ped7g: more specific info about what was deleted and is gone

2025-10-06 update: SemanticWiki plugin was removed due to SW security issues and high maintenance effort requirements. This broke lot of the wiki functionality, like there's no more auto-generated list of next registers, etc. The source data used by the plugin to generate remaining content and format it are still available as individual wiki pages, check [[Special:AllPages]] (but if something is missing also here, then it's gone, AFAIK only SemanticWiki code, templates and auto-generation of final page look is gone, so all the Next specific info should be still somewhere in source articles). At this moment I'm not aware of any attempt to improve current state, but if you feel like you want to give it a go, maybe sync on the Next discord at #wiki-wizards-and-hosting-heros channel first to have most current info on situation.

--- older notes, which now after ages sounds to me like "improve everything" ---

These items are known to lack in information amount or accuracy (and anyone having spare time and required information is welcome to improve them):
* [[Sprites]] - main article is up to date, seems also formatted well, still somebody checking if it holds against actual users and what can be improved...
* various main articles: check wording, if they are in sync with official docs/manual (memory page vs bank, port vs register, etc...)

Wiki TODO list

2025-10-07T09:00:48Z

Ped7g: update about SemanticWiki plugin removal

2025-10-06 update: SemanticWiki plugin was removed due to SW security issues and high maintenance effort requirements. This broke lot of the wiki functionality, like there's no more auto-generated list of next registers, etc. The source data used by the plugin to generate remaining content and format it are still available as individual wiki pages, check [[Special:AllPages]] (but if something is missing also here, then it's gone). At this moment I'm not aware of any attempt to improve current state, but if you feel like you want to give it a go, maybe sync on the Next discord at #wiki-wizards-and-hosting-heros channel first to have most current info on situation.

These items are known to lack in information amount or accuracy (and anyone having spare time and required information is welcome to improve them):
* [[Sprites]] - main article is up to date, seems also formatted well, still somebody checking if it holds against actual users and what can be improved...
* various main articles: check wording, if they are in sync with official docs/manual (memory page vs bank, port vs register, etc...)

CSpect:known bugs

2025-09-23T14:41:57Z

Ped7g: DMA WR3 enable bit bug reported by Holub, tested with dmaDebug.sna test and by checking VHDL

CSpect V2.19.1.0
* intentional for performance reasons:
** sprites: the collision bit is not implemented
** sprites rendering is not one-scanline-buffer delayed and all changes in sprites affect current scanline
** modifications to NextRegs done in copper propagate to rendering usually only once per scanline, the state for rendering is sampled after right border area (ahead of copper wait h=39), affecting previous line instead of next (palette changes, X/Y offsets, etc)
** modifications to NextRegs done by CPU propagate to rendering usually only once per scanline, usually retroactively for whole current scanline
* major differences / missing features
** blending modes: improved greatly in V2.19.0.3, blending only L2 priority colours wrongly.
** NextZXOS streaming API doesn't work (the initialization of stream fails - rst 8 service 0x86 ; DISK_STRMSTART)
** DMA: Zilog mode is not implemented (port 0x0B) (but zxnDMA does listen to both ports, so SW using 0x0B will get one byte shorter transfers)
* subtle differences
** sprites: in border vs tiles in modes 3,4 and 5 are not drawn same weird way as HW
** sprites: the wrap-around the 512x512 coordinate space is only partially implemented in extreme cases (relative sprite so far from anchor that x8 scale wraps it back onto screen)
** NextReg $02 implementation of soft-reset does something, but not the same thing like HW
** NextBASIC SPECTRUM command may load SNA file with wrong ROM paged in (very likely related to SW NMI trigger emulation <code>nextreg 2,8</code> ROM2 $0aab)
** NextZXOS browser is unable to load SNA/SNX/Z80 files in latest distribution (does work with older 3.1.5 core NextZXOS) (may be related to SW NMI)
** More >> ZX80 and ZX81 modes reset and hangs on a black screen while launching the Paul Farrow emulators. (may be related to soft-reset)
** More >> 128K BASIC launches but gets no keypresses on 2.19.0.2. On V2.16.6.0 it hangs on a black screen and border. (may be related to soft-reset)
** DMA: reading-registers are a bit off (for example status bit5+0 not reset correctly after LOAD, probably few more (but core 3.1.5 also reads bit0 wrongly, so always test own code with all target platforms))
** DMA: setting WR3 enable bit does NOT start transfer (ie. CSpect is emulating the East Germany clone chip, HW Next and Zilog DMA chips will start the transfer after such write like WR3 = 0xC0)
** NextRegs $09, $34, $41, $8E read incorrectly (reads after certain writes produce wrong value) (but also the test is checking 3.1.5 behaviour, needs update to 3.1.10)
** debugger: the step-over F8 does run interrupt handler every 16-20ms (as part of debug-live-screen-view drawing), so it's almost after every F8 press
** Z80: <code>di : halt</code> doesn't put CPU in infinite loop waiting for NMI, but proceeds further
** Z80: block of prefixes/instructions 0xDD/0xFD/EI does not inhibit masked interrupts
* recently fixed:
** <del>L2 mode 320x256 and 640x256 could crash when clip.X2 > clip.X1</del>
** <del>CTC timing is affected by the Z80N clock speed. It should be using a constant 28Mhz reference clock.</del>
** <del>vertical ULA clipping is not working in Timex modes</del>
** <del>ULA scroll and half-width scroll is not implemented in Timex modes</del>
** <del>Z80: when masked interrupt handler is entered, the interrupts remain enabled (IFF1=1, IFF2=1)</del>
** <del>divMMC automap-enabled traps certain addresses even when RAM is mapped to MMU0/MMU1</del>
** <del>something not completely right about Enhanced ULA colours (test TFalBUla.sna)</del>
** <del>F3 reset does not autodetect NextZXOS 2.06 vs 2.07 when running with card-image, so 2.06 image ends with purple stripes.</del>
** <del>some NextRegs read as zero until they are written into first (quick-boot mode with SNA file without full NextZXOS image)</del>
** <del>Layer2 640x256x4bpp clipping is broken</del> (V2.19.0.3 does fix this correctly, was still broken before)

not verified in V2.19.1.0 (but known bugs of older versions, may be still present):
* CTC time constant of 0 causes incorrect code execution.
* the initial file-import sequence of CP/M BIOS fails. (get cpm-a.p3d file from somebody with a working clean CP/M installation and copy that into c:/NextZXOS, or use other emulator to create the file)
* default ULA palette after power on (quick boot without NextZXOS) is slightly different
* (should be improved now, to be tested) without the full NextZXOS card image the esxdos services are provided by open source [https://github.com/mikedailly/CSpectPlugins CSpect plugins], the implementation is limited and crude - some of the returned values are incorrect/etc, but loading files works.
* direct loading of NEX files does not support all combinations of loading-screen type and palette on/off (but V2.12.9 does load more files than V2.12.5, all common ones should work)
* sprites: something something about default clipping... just set clip windows explicitly in your SW.
* sprites: clipping in non-over-border configuration is maybe wrong (probably fixed, needs more testing with 2.19.1.0 or later)
* fixed by V2.19.0.3 <del>stencil mode is not implemented</del>, needs more testing

Platform Specific (may be already fixed):
* Mac: Mouse does not work / behaves erratically
* Mac: after launch keyboard being irresponsive - try "alt+tab" to other app and back
* Linux: (some/all?) plugin windows like nextregisters (ctrl+alt+r) does not refresh while in debugger
* Linux: (some/all?) plugin windows like nextregisters (ctrl+alt+r) does draw hover-hint tooltip only for one frame, then it becomes invisible

Not a bug:
* CSpect works with "-sound" (does switch sounds OFF), but shows only black screen without it:
** you forgot to install OpenAL, check the ReadMe.txt of the emulator.

Assemblers

2025-03-17T00:23:30Z

Ped7g:

Any Z80 assembler can produce code suitable for the Next. However the raw blocks of Z80 code may be not as convenient to use with Next or emulators, so a Next specific tools may be useful for creating one of the supported [[File Formats]].

== Cross-platform tools (running on PC) ==

=== ''[http://www.desdes.com/products/oldfiles/zeus.htm Zeus-ish]'' ===
: Provides a complete Z80 IDE and Macro assembler, scripted disassember plus an integrated Z80 emulator for a range of machines including partial Next support
: Supports the Next opcodes directly
: Supports remote debugging on the Next using ParaSys across a serial link
: Supports MMU paging in the integrated emulator
: Supports sprites (core versions prior to 2.00.26) in the integrated emulator

=== ''[http://pasmo.speccy.org/ Pasmo]'' ===
: A long established Z80 assembler, but has been out of development for a long time
: Supports all currently known Next extension opcodes through this [https://www.facebook.com/groups/specnext/512169722473686/ modified Pasmo from Russ McNulty and Tony Thompson] and also now supports outputting .sna files to use with CSpect, thanks to Russ McNulty

=== ''SNasm'' ===
Included with the [https://mdf200.itch.io/cspect #CSpect] emulator
: Full macro assembler
: Full bank control via Segment management
: Supports the Next extension opcodes directly
: Generates full 24bit map files for use in CSpect

=== ''z80asm'' ===
Part of [https://github.com/z88dk/z88dk Z88dk]''
: Supports the Next extension opcodes directly, linking assembler with large z80 library, targets any memory configuration

=== ''[https://github.com/z00m128/sjasmplus z00m's fork of sjasmplus]'' ===
: Supports all (core2.00.28) Next extension opcodes, ZXN memory model (8 memory slots with 8ki pages and 1.75MiB virtual device memory), SAVENEX to build NEX files directly from ASM source (NEX version V1.2 (and experimental extension "V1.3")), MAP files for [https://mdf200.itch.io/cspect #CSpect] emulator, SLD tracing files for [https://github.com/maziac/DeZog DeZog] and [https://github.com/Ckirby101/NDS-NextDevSystem NDS-NextDevSystem] and it is under active development (feedback is welcome).
: Open source project ("BSD-3-Clause" license), '''windows executables available at [https://github.com/z00m128/sjasmplus/releases/latest releases]''', mac and linux users are expected to simply build from source (both make and CMake are supported).
: [http://z00m128.github.io/sjasmplus/documentation.html Documentation], latest stable release v1.21.0 2025-03-15

=== ''[https://github.com/CatpainBlack/FantASM FantASM]'' ===
FantASM is a two pass non optimising assembler for the Z80 processor by [https://github.com/CatpainBlack Guy 'CatpainBlack' Black].

It supports all undocumented op-codes and the extended instruction set of the ZX Next and additional pseudo opcodes used by the CSpect emulator to control debugging.

== Native tools (running on Next) ==

=== ''[https://gitlab.com/next-tools/odin Odin]'' ===

Work-in-progress Next-specific assembler written by Matt Davies, used also in video tutorials presented by Jim Bagley, the best way to acquire the binary is to join the official ZX Next discord server and check channel <code>#odin</code> - pinned messages, where you can also discuss any issues and get how-to hints.

: supports most of the undocumented opcodes, all official Z80 and Next-extended instructions
: supports nested includes and binary includes
: source is stored in tokenised form (smaller file), up to 48kiB of source in single file
: assembling can produce 32kiB of machine code (enough to produce simpler dot command)
: includes also editor and console modules (debugger is planned)

=== ''[https://www.solarisite.com/spectrumnext.html Sol]'' ===

Sol is an assembler and editor written by Solaris, that runs natively on the Next. Manual, assembler binary and assembler source can be downloaded [https://www.solarisite.com/spectrumnext.html here].

=== ''[https://gitlab.com/thesmog358/tbblue/-/tree/master/tools/dev/Zeus ZEUS]'' ===

Classic ZEUS native assembler by Simon Brattel, extended and included directly in the ZX Next distro.

=== ''[https://gitlab.com/thesmog358/tbblue/-/tree/master/tools/dev/SPED SPED]'' ===

Classic SPED assembler by César Hernández Bañó, included directly in the ZX Next distro, see [https://gitlab.com/thesmog358/tbblue/-/raw/master/docs/apps/dev/SPED53readme.txt README].

=== ''[https://taylorza.itch.io/nextbasic-inline-assembler NextBASIC Inline Assembler]''===
Enables you to write inline assembly code in your NextBASIC application. The assembler can be downloaded from [https://taylorza.itch.io/nextbasic-inline-assembler HERE] with documentation available [https://github.com/taylorza/zxn-inlineasm-doc/blob/main/README.md HERE]