SpecNext Wiki - User contributions [en-gb]

Pi:dev build environment

2026-05-05T17:15:46Z

Xalior:

'''Working draft.''' Procedure re-validated 2026-05-05 on Pi OS Bookworm / Pi 5.

----

''Reproducible procedure for setting up a build host that produces stretch-armhf binaries (compatible with the Raspbian-9 base used by NextPi) on any modern aarch64 Raspberry Pi running Pi OS Bookworm.''

== Why ==

NextPi releases ship as Raspbian 9 (stretch) armhf binaries. This procedure builds those binaries inside a stretch-armhf chroot hosted on a modern aarch64 Pi. aarch64 hardware can execute armhf userspace natively via aarch32 compat, so the build runs at host CPU speed without QEMU emulation, while the toolchain and libraries remain pinned to stretch for ABI compatibility with the deployment target. Apt sources point at the project's stretch mirror at <code>http://zx.xalior.com/nextpi_dev</code>, which keeps package versions deterministic across build hosts.

'''Measured speedup, libspectrum 1.6.0 build:'''

{| class="wikitable"
! Build host !! Time !! Ratio
|-
| Pi 3, 4× Cortex-A53 armv7l, SD card (native stretch) || 65 s || 1.0×
|-
| Pi 5, 4× Cortex-A76 aarch64, NVMe (chroot) || 11 s || 5.9×
|}

== Prerequisites ==

* Vanilla Pi OS Bookworm on a Pi 4 or Pi 5 with ~5 GB free disk.
* SSH access as a sudo-capable user.
* Network reach to <code>zx.xalior.com</code>.

== Procedure ==

=== 1. Install host tooling ===

<syntaxhighlight lang="bash">
sudo apt-get update
sudo apt-get install -y debootstrap qemu-user-static binfmt-support
</syntaxhighlight>

<code>qemu-user-static</code> + <code>binfmt-support</code> register handlers so debootstrap can run armhf binaries during second-stage configure. (On Pi 5 the host kernel can also execute armhf natively via aarch32 compat; binfmt-misc is the fallback.)

Verify:

<syntaxhighlight lang="bash">
dpkg --print-foreign-architectures # should list: armhf
ls /proc/sys/fs/binfmt_misc/ | grep qemu-arm
</syntaxhighlight>

=== 2. Add the apt signing key ===

The mirror is signed with the canonical Raspbian archive key (Mike Thompson, fingerprint <code>A0DA 38D0 D76E 8B5D 6388 7281 9165 938D 90FD DD2E</code>). Modern Pi OS Bookworm doesn't ship it, so add it explicitly:

<syntaxhighlight lang="bash">
curl -sL https://zx.xalior.com/nextpi_dev/debian_nextpi.key \
| sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/debian_nextpi.gpg
</syntaxhighlight>

Confirm:

<syntaxhighlight lang="bash">
sudo gpg --no-default-keyring --keyring /etc/apt/trusted.gpg.d/debian_nextpi.gpg --list-keys
# pub rsa2048 2012-04-01 [SC] A0DA38D0D76E8B5D638872819165938D90FDDD2E
# uid Mike Thompson (Raspberry Pi Debian armhf ARMv6+VFP)
</syntaxhighlight>

=== 3. Debootstrap the chroot ===

<syntaxhighlight lang="bash">
sudo debootstrap --arch=armhf --variant=buildd \
--keyring=/etc/apt/trusted.gpg.d/debian_nextpi.gpg \
stretch /srv/nextpi-buildroot/ \
http://zx.xalior.com/nextpi_dev
</syntaxhighlight>

debootstrap downloads ~50 MB of <code>.deb</code>s, extracts them, and ends with this warning:

<pre>
W: Failure while configuring required packages.
W: See /srv/nextpi-buildroot/debootstrap/debootstrap.log for details (possibly the package systemd is at fault)
</pre>

This is expected — stretch's <code>systemd</code> postinst segfaults under Pi 5's kernel via aarch32 compat. The next step works around it; systemd is never actually run inside a build chroot.

=== 4. Force-install the unconfigured packages ===

The systemd configure failure halts dpkg's pending-configure pass and leaves several packages (including <code>apt</code>) unpacked-but-not-installed. Force them through:

<syntaxhighlight lang="bash">
sudo chroot /srv/nextpi-buildroot \
/usr/bin/env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin LANG=C \
/bin/bash -c "dpkg --install --force-depends --force-confdef --force-confold --force-overwrite --force-bad-version --recursive /var/cache/apt/archives/"
</syntaxhighlight>

Errors on <code>systemd</code>, <code>plymouth</code>, <code>mountall</code> are expected and harmless.

Verify:

<syntaxhighlight lang="bash">
sudo chroot /srv/nextpi-buildroot \
/usr/bin/env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin LANG=C \
/bin/bash -c "type apt-get && type gcc"
</syntaxhighlight>

=== 5. Bind-mount runtime filesystems ===

<syntaxhighlight lang="bash">
for m in proc sys dev dev/pts; do
sudo mkdir -p /srv/nextpi-buildroot/$m
sudo mount --bind /$m /srv/nextpi-buildroot/$m
done
sudo cp /etc/resolv.conf /srv/nextpi-buildroot/etc/
</syntaxhighlight>

These are session-only; see [[#Persistent mounts|Persistent mounts]] below for fstab.

=== 6. Hold the broken packages ===

So future <code>apt-get install</code> runs don't re-extract systemd and re-trigger the postinst:

<syntaxhighlight lang="bash">
sudo chroot /srv/nextpi-buildroot \
/usr/bin/env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin LANG=C \
/bin/bash -c "apt-mark hold systemd plymouth mountall"
</syntaxhighlight>

=== 7. Install build dependencies ===

<syntaxhighlight lang="bash">
sudo chroot /srv/nextpi-buildroot \
/usr/bin/env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin LANG=C HOME=/root \
/bin/bash -c "apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
autoconf automake libtool libtool-bin pkg-config \
libbz2-dev libaudiofile-dev \
wget git ca-certificates"
</syntaxhighlight>

<code>libtool-bin</code> is required separately on stretch — the <code>libtool</code> umbrella package no longer ships the <code>/usr/bin/libtool</code> script.

A <code>W: APT had planned for dpkg to do more than it reported back</code> warning about <code>systemd:armhf</code> will appear on every apt-get run; that's the hold doing its job.

Toolchain check:

<syntaxhighlight lang="bash">
sudo chroot /srv/nextpi-buildroot /usr/bin/env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin /bin/bash -c \
"gcc --version | head -1; automake --version | head -1; libtool --version | head -1; pkg-config --version"
</syntaxhighlight>

Expect: <code>gcc 6.3.0</code>, <code>automake 1.15</code>, <code>libtool 2.4.6</code>, <code>pkg-config 0.29</code>.

=== 8. Smoke test: build libspectrum 1.6.0 ===

<syntaxhighlight lang="bash">
sudo chroot /srv/nextpi-buildroot \
/usr/bin/env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin LANG=C HOME=/root \
/bin/bash -c '
cd /tmp && \
wget -q https://sourceforge.net/projects/fuse-emulator/files/libspectrum/1.6.0/libspectrum-1.6.0.tar.gz/download -O libspectrum-1.6.0.tar.gz && \
tar xzf libspectrum-1.6.0.tar.gz && \
cd libspectrum-1.6.0 && \
./configure --with-fake-glib --quiet && \
time make -s
'
</syntaxhighlight>

Wall-clock ~10–15 s on Pi 5 / NVMe. Verify:

<syntaxhighlight lang="bash">
file /srv/nextpi-buildroot/tmp/libspectrum-1.6.0/.libs/libspectrum.so.8.10.0
# ELF 32-bit LSB shared object, ARM, EABI5 version 1 (SYSV), dynamically linked
</syntaxhighlight>

Chroot is ready.

== Persistent mounts ==

The bind mounts in step 5 are session-only. For a long-lived build host, add to <code>/etc/fstab</code>:

<syntaxhighlight lang="text">
/proc /srv/nextpi-buildroot/proc none bind 0 0
/sys /srv/nextpi-buildroot/sys none bind 0 0
/dev /srv/nextpi-buildroot/dev none bind 0 0
/dev/pts /srv/nextpi-buildroot/dev/pts none bind 0 0
</syntaxhighlight>

(<code>/etc/resolv.conf</code> will need re-copying after host reboot regardless.)

Pi:dev build environment

2026-05-05T17:15:31Z

Xalior:

'''Working draft.''' Procedure re-validated 2026-05-05 on Pi OS Bookworm / Pi 5. Corrections welcome on the talk page.

----

''Reproducible procedure for setting up a build host that produces stretch-armhf binaries (compatible with the Raspbian-9 base used by NextPi) on any modern aarch64 Raspberry Pi running Pi OS Bookworm.''

== Why ==

NextPi releases ship as Raspbian 9 (stretch) armhf binaries. This procedure builds those binaries inside a stretch-armhf chroot hosted on a modern aarch64 Pi. aarch64 hardware can execute armhf userspace natively via aarch32 compat, so the build runs at host CPU speed without QEMU emulation, while the toolchain and libraries remain pinned to stretch for ABI compatibility with the deployment target. Apt sources point at the project's stretch mirror at <code>http://zx.xalior.com/nextpi_dev</code>, which keeps package versions deterministic across build hosts.

'''Measured speedup, libspectrum 1.6.0 build:'''

{| class="wikitable"
! Build host !! Time !! Ratio
|-
| Pi 3, 4× Cortex-A53 armv7l, SD card (native stretch) || 65 s || 1.0×
|-
| Pi 5, 4× Cortex-A76 aarch64, NVMe (chroot) || 11 s || 5.9×
|}

== Prerequisites ==

* Vanilla Pi OS Bookworm on a Pi 4 or Pi 5 with ~5 GB free disk.
* SSH access as a sudo-capable user.
* Network reach to <code>zx.xalior.com</code>.

== Procedure ==

=== 1. Install host tooling ===

<syntaxhighlight lang="bash">
sudo apt-get update
sudo apt-get install -y debootstrap qemu-user-static binfmt-support
</syntaxhighlight>

<code>qemu-user-static</code> + <code>binfmt-support</code> register handlers so debootstrap can run armhf binaries during second-stage configure. (On Pi 5 the host kernel can also execute armhf natively via aarch32 compat; binfmt-misc is the fallback.)

Verify:

<syntaxhighlight lang="bash">
dpkg --print-foreign-architectures # should list: armhf
ls /proc/sys/fs/binfmt_misc/ | grep qemu-arm
</syntaxhighlight>

=== 2. Add the apt signing key ===

The mirror is signed with the canonical Raspbian archive key (Mike Thompson, fingerprint <code>A0DA 38D0 D76E 8B5D 6388 7281 9165 938D 90FD DD2E</code>). Modern Pi OS Bookworm doesn't ship it, so add it explicitly:

<syntaxhighlight lang="bash">
curl -sL https://zx.xalior.com/nextpi_dev/debian_nextpi.key \
| sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/debian_nextpi.gpg
</syntaxhighlight>

Confirm:

<syntaxhighlight lang="bash">
sudo gpg --no-default-keyring --keyring /etc/apt/trusted.gpg.d/debian_nextpi.gpg --list-keys
# pub rsa2048 2012-04-01 [SC] A0DA38D0D76E8B5D638872819165938D90FDDD2E
# uid Mike Thompson (Raspberry Pi Debian armhf ARMv6+VFP)
</syntaxhighlight>

=== 3. Debootstrap the chroot ===

<syntaxhighlight lang="bash">
sudo debootstrap --arch=armhf --variant=buildd \
--keyring=/etc/apt/trusted.gpg.d/debian_nextpi.gpg \
stretch /srv/nextpi-buildroot/ \
http://zx.xalior.com/nextpi_dev
</syntaxhighlight>

debootstrap downloads ~50 MB of <code>.deb</code>s, extracts them, and ends with this warning:

<pre>
W: Failure while configuring required packages.
W: See /srv/nextpi-buildroot/debootstrap/debootstrap.log for details (possibly the package systemd is at fault)
</pre>

This is expected — stretch's <code>systemd</code> postinst segfaults under Pi 5's kernel via aarch32 compat. The next step works around it; systemd is never actually run inside a build chroot.

=== 4. Force-install the unconfigured packages ===

The systemd configure failure halts dpkg's pending-configure pass and leaves several packages (including <code>apt</code>) unpacked-but-not-installed. Force them through:

<syntaxhighlight lang="bash">
sudo chroot /srv/nextpi-buildroot \
/usr/bin/env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin LANG=C \
/bin/bash -c "dpkg --install --force-depends --force-confdef --force-confold --force-overwrite --force-bad-version --recursive /var/cache/apt/archives/"
</syntaxhighlight>

Errors on <code>systemd</code>, <code>plymouth</code>, <code>mountall</code> are expected and harmless.

Verify:

<syntaxhighlight lang="bash">
sudo chroot /srv/nextpi-buildroot \
/usr/bin/env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin LANG=C \
/bin/bash -c "type apt-get && type gcc"
</syntaxhighlight>

=== 5. Bind-mount runtime filesystems ===

<syntaxhighlight lang="bash">
for m in proc sys dev dev/pts; do
sudo mkdir -p /srv/nextpi-buildroot/$m
sudo mount --bind /$m /srv/nextpi-buildroot/$m
done
sudo cp /etc/resolv.conf /srv/nextpi-buildroot/etc/
</syntaxhighlight>

These are session-only; see [[#Persistent mounts|Persistent mounts]] below for fstab.

=== 6. Hold the broken packages ===

So future <code>apt-get install</code> runs don't re-extract systemd and re-trigger the postinst:

<syntaxhighlight lang="bash">
sudo chroot /srv/nextpi-buildroot \
/usr/bin/env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin LANG=C \
/bin/bash -c "apt-mark hold systemd plymouth mountall"
</syntaxhighlight>

=== 7. Install build dependencies ===

<syntaxhighlight lang="bash">
sudo chroot /srv/nextpi-buildroot \
/usr/bin/env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin LANG=C HOME=/root \
/bin/bash -c "apt-get update && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
autoconf automake libtool libtool-bin pkg-config \
libbz2-dev libaudiofile-dev \
wget git ca-certificates"
</syntaxhighlight>

<code>libtool-bin</code> is required separately on stretch — the <code>libtool</code> umbrella package no longer ships the <code>/usr/bin/libtool</code> script.

A <code>W: APT had planned for dpkg to do more than it reported back</code> warning about <code>systemd:armhf</code> will appear on every apt-get run; that's the hold doing its job.

Toolchain check:

<syntaxhighlight lang="bash">
sudo chroot /srv/nextpi-buildroot /usr/bin/env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin /bin/bash -c \
"gcc --version | head -1; automake --version | head -1; libtool --version | head -1; pkg-config --version"
</syntaxhighlight>

Expect: <code>gcc 6.3.0</code>, <code>automake 1.15</code>, <code>libtool 2.4.6</code>, <code>pkg-config 0.29</code>.

=== 8. Smoke test: build libspectrum 1.6.0 ===

<syntaxhighlight lang="bash">
sudo chroot /srv/nextpi-buildroot \
/usr/bin/env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin LANG=C HOME=/root \
/bin/bash -c '
cd /tmp && \
wget -q https://sourceforge.net/projects/fuse-emulator/files/libspectrum/1.6.0/libspectrum-1.6.0.tar.gz/download -O libspectrum-1.6.0.tar.gz && \
tar xzf libspectrum-1.6.0.tar.gz && \
cd libspectrum-1.6.0 && \
./configure --with-fake-glib --quiet && \
time make -s
'
</syntaxhighlight>

Wall-clock ~10–15 s on Pi 5 / NVMe. Verify:

<syntaxhighlight lang="bash">
file /srv/nextpi-buildroot/tmp/libspectrum-1.6.0/.libs/libspectrum.so.8.10.0
# ELF 32-bit LSB shared object, ARM, EABI5 version 1 (SYSV), dynamically linked
</syntaxhighlight>

Chroot is ready.

== Persistent mounts ==

The bind mounts in step 5 are session-only. For a long-lived build host, add to <code>/etc/fstab</code>:

<syntaxhighlight lang="text">
/proc /srv/nextpi-buildroot/proc none bind 0 0
/sys /srv/nextpi-buildroot/sys none bind 0 0
/dev /srv/nextpi-buildroot/dev none bind 0 0
/dev/pts /srv/nextpi-buildroot/dev/pts none bind 0 0
</syntaxhighlight>

(<code>/etc/resolv.conf</code> will need re-copying after host reboot regardless.)

Pi:admin pupextract

2026-05-05T13:58:13Z

Xalior:

== Abstract ==

`nextpi-admin_pupextract` validates a Pi Update Patch (`.PUP`) file's header and extracts its payload archive ready for a subsequent update step.

== Prerequisits ==

* NextPi Version: 1.91D

== Backend ==
* Binary: Proprietory

== Options ==
<code>-h</code> display usage information

<code>-vl</code> verbose logging (writes to <code>/tmp/puphelper.log</code>)

<code>-c</code> check the patch's version requirement against the running system without extracting

A single positional argument names the <code>.PUP</code> file to inspect.

== Behaviour ==

The first 512 bytes of the file are read as a PUP header. The header is rejected unless its signature reads <code>PUP</code>, its secondary signature byte is <code>254</code>, and its version field is <code>1</code>. If the header's <code>strict</code> flag is set, the header's <code>piMajor</code> and <code>piMinor</code> must match the running NextPi's major and minor version; otherwise the patch is refused.

On success, the payload that follows the header is copied to <code>/ram/update.tbz</code> in 1 MiB chunks, ready for a subsequent step in the update pipeline.

== Errors ==

* File of 512 bytes or fewer — too small to contain a header.
* Header signature mismatch — not a PUP, or unsupported version.
* Strict-mode version mismatch — the running NextPi does not satisfy the patch's version requirement.

Pi:CLI

2025-11-27T19:26:14Z

Xalior: (adding the missing ref to the speech API, to remind me that is another page I need to create)

== Abstract ==

The NextPi CLI API is a series of "supported" command-line tools designed to make performing specific Pi orientated tasks easier for Spectrum Next application developers.

The CLI API commands are built out of two parts - known as "Frontends" and "Backends". "Frontends" commands all begin with <code>nextpi-</code> and broken into logical groups (e.g. <code>nextpi-console_</code>, <code>nextpi-play_</code>, <code>nextpi-admin_</code>, etc) - this naming convention allows you to easily tell at a glance what kind of function a command will perform, and for you to know that your commands should continue to work in future NextPi patches.

== More About Frontends & Backends ==

The '''Frontend''' commands often perform their operations via the means of various internal system APIs - in a more traditional Linux setup these Frontends would be called "wrapper scripts". The underlying system tools used by Frontends are what we referred to as '''Backends''' - and you'll often see this term used on individual API CLI pages.

The use of a "formal CLI API" via these Frontend wrappers permits several things:
* The addition of extra options and commandline switches not present in the backends;
* The inclusion of default parameters for many of the commands, or to save boilerplate options; and
* A way of "future-proofing" should the backend need to change for any reason.

Many of the backends support additional options, which can be found by reading the documentation for the individual backends (not included in this wiki) - while this may provide you with extra functionality, it comes at the cost of no assurance that these "undocument features" will also continue to work in future NextPi patches.

== Defining "supported" ==

In the context of the CLI API "supported" means we will try with "best effort" to ensure that documented usage patterns will continue to work. It does not mean that they come with any warrenty of "technical support", actual or implied - to make these APIs work with your own code. Developer support is community provided, and if you're looking for help the best place to try is the Official Spectrum Next discord, found at https://zxn.gg/discord.

== CLI commands ==

* nextpi-admin_clean
* nextpi-admin_disable
* nextpi-admin_enable
* nextpi-admin_pupextract
* nextpi-admin_report
* nextpi-admin_uihelper
* nextpi-admin_update
* nextpi-admin_version
* nextpi-audio_loopback
* nextpi-cache
* nextpi-cache_bucket
* [[Pi:console_image|nextpi-console_image]]
* [[Pi:console_resolution|nextpi-console_resolution]]
* nextpi-dongle_disable
* nextpi-dongle_enable
* nextpi-echo_disable
* nextpi-echo_enable
* nextpi-file_delete
* nextpi-file_receive
* nextpi-file_rename
* nextpi-file_stream
* nextpi-file_transmit
* [[Pi:gpio_mode|nextpi-gpio_mode]]
* nextpi-input_xbox
* nextpi-play_midiLQ
* nextpi-play_midiHQ
* nextpi-play_midiMQ
* nextpi-play_mod
* nextpi-play_mp3
* nextpi-play_sid
* nextpi-play_silence
* nextpi-play_sndh
* nextpi-play_speech
* nextpi-play_stock
* nextpi-play_stop
* nextpi-plus_activate
* nextpi-plus_list
* nextpi-plus_lock
* nextpi-plus_unlock
* nextpi-tzx_load
* nextpi-ui_file
* nextpi-ui_texteditor
* nextpi-z88dk_switch

XADC register

2025-10-14T12:48:31Z

Xalior: Xalior moved page XADC register to XADC Register: match formal nextreg.txt name

#REDIRECT [[XADC Register]]

XADC Register

2025-10-14T12:48:31Z

Xalior: Xalior moved page XADC register to XADC Register: match formal nextreg.txt name

{{NextRegister
|Number=$F8
|Readable=Yes
|Writable=Yes
|ShortDesc=Issue 4 only
}}
bit 7 = 1 to write to XADC DRP port, 0 to read from XADC DRP port **
bits 6:0 = XADC DRP register address DADDR
* An XADC register read or write is initiated by writing to this register
* There must be at least six 28 MHz cycles after each r/w to this register
* ** Reads as 0

XADC D1

2025-10-14T12:48:00Z

Xalior: Xalior moved page XADC D1 to XADC D1 Register: match formal nextreg.txt name

#REDIRECT [[XADC D1 Register]]

XADC D1 Register

2025-10-14T12:48:00Z

Xalior: Xalior moved page XADC D1 to XADC D1 Register: match formal nextreg.txt name

{{NextRegister
|Number=$FA
|Readable=Yes
|Writable=Yes
|ShortDesc=Issue 4 only
}}
bits 7:0 = MSB data connected to XADC DRP data bus D15:8
DRP reads store result here, DRP writes take value from here

XADC D0

2025-10-14T12:47:49Z

Xalior: Xalior moved page XADC D0 to XADC D0 Register: match formal nextreg.txt name

#REDIRECT [[XADC D0 Register]]

XADC D0 Register

2025-10-14T12:47:49Z

Xalior: Xalior moved page XADC D0 to XADC D0 Register: match formal nextreg.txt name

{{NextRegister
|Number=$F9
|Readable=Yes
|Writable=Yes
|ShortDesc=Issue 4 only
}}
bits 7:0 = LSB data connected to XADC DRP data bus D7:0
* DRP reads store result here, DRP writes take value from here

I/O Trap Cause

2025-10-14T12:45:43Z

Xalior: Xalior moved page I/O Trap Cause to I/O Trap Cause Register: match formal nextreg.txt name

#REDIRECT [[I/O Trap Cause Register]]

I/O Trap Cause Register

2025-10-14T12:45:43Z

Xalior: Xalior moved page I/O Trap Cause to I/O Trap Cause Register: match formal nextreg.txt name

{{NextRegister
|Number=$DA
|Readable=Yes
|Writable=No
|ShortDesc=experimental
}}
0 = none (zero at the same time nextreg 0x02 bit 4 is 0)
1 = port_2ffd read
2 = port_3ffd read
3 = port_3ffd write
* If nextreg 0x02 bit 4 indicates an i/o cycle was trapped, this register indicates the cause

I/O Trap Write

2025-10-14T12:45:31Z

Xalior: Xalior moved page I/O Trap Write to I/O Trap Write Register: match formal nextreg.txt name

#REDIRECT [[I/O Trap Write Register]]

I/O Trap Write Register

2025-10-14T12:45:31Z

Xalior: Xalior moved page I/O Trap Write to I/O Trap Write Register: match formal nextreg.txt name

{{NextRegister
|Number=$D9
|Readable=Yes
|Writable=Yes
|ShortDesc=experimental
}}
Holds byte written during trapped i/o write cycle

I/O Traps

2025-10-14T12:45:13Z

Xalior: Xalior moved page I/O Traps to I/O Traps Register: match formal nextreg.txt name

#REDIRECT [[I/O Traps Register]]

I/O Traps Register

2025-10-14T12:45:13Z

Xalior: Xalior moved page I/O Traps to I/O Traps Register: match formal nextreg.txt name

{{NextRegister
|Number=$D8
|Readable=Yes
|Writable=Yes
|ShortDesc=experimental
}}
bits 7:1 = Reserved must be zero
bit 0 = 1 to enable +3 FDC traps on ports 0x2ffd and 0x3ffd
* An i/o trap generates a multiface nmi and is indicated in nextreg 0x02
* Traps cannot be triggered by the dma or while the multiface, divmmc or external nmi is active

Interrupt Enable 2

2025-10-14T12:43:32Z

Xalior: Xalior moved page Interrupt Enable 2 to Interrupt Enable 2 Register: match formal nextreg.txt name

#REDIRECT [[Interrupt Enable 2 Register]]

Interrupt Enable 2 Register

2025-10-14T12:43:32Z

Xalior: Xalior moved page Interrupt Enable 2 to Interrupt Enable 2 Register: match formal nextreg.txt name

{{NextRegister
|Number=$C6
|Readable=Yes
|Writable=Yes
|ShortDesc=UART interrupt enable control
}}
bit 7 = Reserved must be zero
bit 6 = UART1 Tx empty
bit 5 = UART1 Rx near full \ shared
bit 4 = UART1 Rx available / interrupt
bit 3 = Reserved must be zero
bit 2 = UART0 Tx empty
bit 1 = UART0 Rx near full \ shared
bit 0 = UART0 Rx available / interrupt
* Rx near full overrides Rx available
* If a device interrupt is disabled, it enters a polled mode

Soft reset = 0x00

Interrupt Enable 1

2025-10-14T12:43:24Z

Xalior: Xalior moved page Interrupt Enable 1 to Interrupt Enable 1 Register: match formal nextreg.txt name

#REDIRECT [[Interrupt Enable 1 Register]]

Interrupt Enable 1 Register

2025-10-14T12:43:24Z

Xalior: Xalior moved page Interrupt Enable 1 to Interrupt Enable 1 Register: match formal nextreg.txt name

{{NextRegister
|Number=$C5
|Readable=Yes
|Writable=Yes
|ShortDesc=ctc interrupt enable control
}}
bit 7 = ctc channel 7 zc/to
bit 6 = ctc channel 6 zc/to
bit 5 = ctc channel 5 zc/to
bit 4 = ctc channel 4 zc/to
bit 3 = ctc channel 3 zc/to
bit 2 = ctc channel 2 zc/to
bit 1 = ctc channel 1 zc/to
bit 0 = ctc channel 0 zc/to
* If a device interrupt is disabled, it enters a polled mode

soft reset = 0x00

Interrupt Enable 0

2025-10-14T12:43:17Z

Xalior: Xalior moved page Interrupt Enable 0 to Interrupt Enable 0 Register: match formal nextreg.txt name

#REDIRECT [[Interrupt Enable 0 Register]]

Interrupt Enable 0 Register

2025-10-14T12:43:17Z

Xalior: Xalior moved page Interrupt Enable 0 to Interrupt Enable 0 Register: match formal nextreg.txt name

{{NextRegister
|Number=$C4
|Readable=Yes
|Writable=Yes
|ShortDesc=Interrupt type enable control
}}
bit 7 = Expansion bus /INT (soft reset = 1)
bits 6:2 = Reserved must be 0
bit 1 = Line ** (soft reset = 0)
bit 0 = ULA ** (soft reset = 1)
* * If a device interrupt is disabled, it enters a polled mode
* ** Aliases of interrupt enable bits in nextreg 0x22

Soft reset = 0x81

Interrupt Status 2

2025-10-14T12:43:10Z

Xalior: Xalior moved page Interrupt Status 2 to Interrupt Status 2 Register: match formal nextreg.txt name

#REDIRECT [[Interrupt Status 2 Register]]

Interrupt Status 2 Register

2025-10-14T12:43:10Z

Xalior: Xalior moved page Interrupt Status 2 to Interrupt Status 2 Register: match formal nextreg.txt name

{{NextRegister
|Number=$CA
|Readable=Yes
|Writable=Yes
|ShortDesc=Has UART interrupt happened?
}}
bit 7 = Reserved must be zero
bit 6 = UART1 Tx empty
bit 5 = UART1 Rx half full \ shared
bit 4 = UART1 Rx available / interrupt
bit 3 = Reserved must be zero
bit 2 = UART0 Tx empty
bit 1 = UART0 Rx half full \ shared
bit 0 = UART0 Rx available / interrupt
* (R) Set bits indicate the device generated an interrupt in the past or an interrupt is pending
* (W) Set bits clear the status. In hw im2 mode the status will continue to read as set until the interrupt pending condition is cleared

Interrupt Status 1

2025-10-14T12:43:02Z

Xalior: Xalior moved page Interrupt Status 1 to Interrupt Status 1 Register: match formal nextreg.txt name

#REDIRECT [[Interrupt Status 1 Register]]

Interrupt Status 1 Register

2025-10-14T12:43:02Z

Xalior: Xalior moved page Interrupt Status 1 to Interrupt Status 1 Register: match formal nextreg.txt name

{{NextRegister
|Number=$C9
|Readable=Yes
|Writable=Yes
|ShortDesc=has ctc interrupt occurred?
}}
bit 7 = ctc channel 7 zc/to
bit 6 = ctc channel 6 zc/to
bit 5 = ctc channel 5 zc/to
bit 4 = ctc channel 4 zc/to
bit 3 = ctc channel 3 zc/to
bit 2 = ctc channel 2 zc/to
bit 1 = ctc channel 1 zc/to
bit 0 = ctc channel 0 zc/to
* (R) Set bits indicate the device generated an interrupt in the past or an interrupt is pending
* (W) Set bits clear the status. In hw im2 mode the status will continue to read as set until the interrupt pending condition is cleared

Interrupt Status 0

2025-10-14T12:42:55Z

Xalior: Xalior moved page Interrupt Status 0 to Interrupt Status 0 Register: match formal nextreg.txt name

#REDIRECT [[Interrupt Status 0 Register]]

Interrupt Status 0 Register

2025-10-14T12:42:55Z

Xalior: Xalior moved page Interrupt Status 0 to Interrupt Status 0 Register: match formal nextreg.txt name

{{NextRegister
|Number=$C8
|Readable=Yes
|Writable=Yes
|ShortDesc=has interrupt occurred?
}}
bits 7:2 = Reserved must be 0
bit 1 = Line
bit 0 = ULA
* (R) Set bits indicate the device generated an interrupt in the past or an interrupt is pending
* (W) Set bits clear the status. In hw im2 mode the status will continue to read as set until the interrupt pending condition is cleared

NMI Return Address MSB

2025-10-14T12:40:09Z

Xalior: Xalior moved page NMI Return Address MSB to NMI Return Address MSB Register: match formal nextreg.txt name

#REDIRECT [[NMI Return Address MSB Register]]

NMI Return Address MSB Register

2025-10-14T12:40:09Z

Xalior: Xalior moved page NMI Return Address MSB to NMI Return Address MSB Register: match formal nextreg.txt name

{{NextRegister
|Number=$C3
|Readable=Yes
|Writable=Yes
|ShortDesc=MSB of NMI return address
}}
Soft reset = 0x00

The return address written during an nmi acknowledge cycle is always stored in these registers.

NMI Return Address LSB

2025-10-14T12:40:00Z

Xalior: Xalior moved page NMI Return Address LSB to NMI Return Address LSB Register: match formal nextreg.txt name

#REDIRECT [[NMI Return Address LSB Register]]

NMI Return Address LSB Register

2025-10-14T12:40:00Z

Xalior: Xalior moved page NMI Return Address LSB to NMI Return Address LSB Register: match formal nextreg.txt name

{{NextRegister
|Number=$C2
|Readable=Yes
|Writable=Yes
|ShortDesc=LSB of NMI return address
}}
Soft reset = 0x00

The return address written during an nmi acknowledge cycle is always stored in these registers.

Interrupt Control

2025-10-14T12:39:25Z

Xalior: Xalior moved page Interrupt Control to Interrupt Control Register: match formal nextreg.txt name

#REDIRECT [[Interrupt Control Register]]

Interrupt Control Register

2025-10-14T12:39:25Z

Xalior: Xalior moved page Interrupt Control to Interrupt Control Register: match formal nextreg.txt name

{{NextRegister
|Number=$C0
|Readable=Yes
|Writable=Yes
}}
Soft reset = 0x00

bits 7:5 = Programmable portion of im2 vector*
bit 4 = Reserved must be 0
bit 3 = Enable stackless nmi response**
bits 2:1 = Current Z80 interrupt mode 0,1,2 (read only, write ignored)
bit 0 = Maskable interrupt mode: pulse (0) or hw im2 mode (1)

* * In hw im2 mode the interrupt vector generated is:
bits 7:5 = nextreg 0xC0 bits 7:5
bits 4:1 = 0 line interrupt (highest priority)
= 1 uart0 Rx
= 2 uart1 Rx
= 3-10 ctc channels 0-7
= 11 ula
= 12 uart0 Tx
= 13 uart1 Tx (lowest priority)
bit 0 = 0

* * In hw im2 mode the expansion bus is the lowest priority interrupter and if no vector is supplied externally then 0xFF is generated.

* ** The return address pushed during an nmi acknowledge cycle will be written to nextreg instead of memory (the stack pointer will be decremented) and the first RETN after the acknowledge will take its return address from nextreg instead of memory (the stack pointer will be incremented). If bit 3 = 0 and in other circumstances, RETN functions normally.

Extended MD Pad Buttons

2025-10-14T12:37:28Z

Xalior: Xalior moved page Extended MD Pad Buttons to Extended MD Pad Buttons Register: match formal nextreg.txt name

#REDIRECT [[Extended MD Pad Buttons Register]]

Extended MD Pad Buttons Register

2025-10-14T12:37:28Z

Xalior: Xalior moved page Extended MD Pad Buttons to Extended MD Pad Buttons Register: match formal nextreg.txt name

{{NextRegister
|Number=$B2
|Readable=Yes
|Writable=No
|ShortDesc=Reading additional buttons on MD pads (Joystick/Gamepad)
}}
bit 7 = 1 if Right Pad X pressed
bit 6 = 1 if Right Pad Z pressed
bit 5 = 1 if Right Pad Y pressed
bit 4 = 1 if Right Pad MODE pressed
bit 3 = 1 if Left Pad X pressed
bit 2 = 1 if Left Pad Z pressed
bit 1 = 1 if Left Pad Y pressed
bit 0 = 1 if Left Pad MODE pressed

Memory Mapping Mode

2025-10-14T12:33:23Z

Xalior: Xalior moved page Memory Mapping Mode to Memory Mapping Mode Register: match formal nextreg.txt name

#REDIRECT [[Memory Mapping Mode Register]]

Memory Mapping Mode Register

2025-10-14T12:33:23Z

Xalior: Xalior moved page Memory Mapping Mode to Memory Mapping Mode Register: match formal nextreg.txt name

{{NextRegister
|Number=$8F
|Readable=Yes
|Writable=Yes
|ShortDesc=Select memory mapping mode
}}
bits 7:2 = Reserved, must be zero
bits 1:0 = Mapping mode applied (hard reset = 0)
00 = Standard ZX 128k +3
01 = Reserved
10 = Pentagon 512K
11 = Pentagon 1024K (limited to 768K on 1MB machines)

* Standard ZX 128K +3 = principally ports 0x7ffd, 0xdffd, 0x1ffd
* Pentagon 512K = principally port 0x7ffd
* Pentagon 1024K = principally ports 0x7ffd, 0xeff7
** The mapping modes affect how ports 0x7ffd, 0xdffd, 0x1ffd and 0xeff7 carry out memory paging, see ports.txt

Alternate ROM

2025-10-14T12:31:52Z

Xalior: Xalior moved page Alternate ROM to Alternate ROM Register: match formal nextreg.txt name

#REDIRECT [[Alternate ROM Register]]

Alternate ROM Register

2025-10-14T12:31:52Z

Xalior: Xalior moved page Alternate ROM to Alternate ROM Register: match formal nextreg.txt name

{{NextRegister
|Number=$8C
|Readable=Yes
|Writable=Yes
|ShortDesc=Enable alternate ROM or lock 48k ROM
}}
{|class="wikitable"
! Bit !! Description
|-
| || Values affecting machine immediately
|-
| 7 || 1 to enable alternate ROM
|-
| 6 || 1 to make alternate ROM visible only during writes, 0 to make alternate ROM visible during reads
|-
| 5 || 1 to lock ROM1 (48K ROM)
|-
| 4 || 1 to lock ROM0 (128k ROM)
|-
| || After soft reset (will be copied to bits 7-4)
|-
| 3 || 1 to enable alternate ROM
|-
| 2 || 1 to make alternate ROM visible only during writes, 0 to make alternate ROM visible during reads
|-
| 1 || 1 to lock ROM1 (48K ROM)
|-
| 0 || 1 to lock ROM0 (128k ROM)
|}

Set to 0 upon hard reset.

The locking mechanism also applies if the alt rom is not enabled. For the +3 and zx next, if the two lock bits are not zero, then the corresponding rom page is locked in place. Other models use the bits to preferentially lock the corresponding 48K rom or the 128K rom.

Detailed explanation from Allen based on the VHDL implementation:

The altrom behaviour is slightly different depending on the machine type (48k, 128k, +3) which is connected to the personalities. The Next is a +3 type. If the Next hardware is chosen to be a 48K machine then the Next hardware becomes 48k type and the altrom is a little different. It has to be because a 48k type machine only gets a 48k rom loaded compared to the +3 which has 64k of rom loaded.

The hardware makes a decision about which rom will be seen in the bottom 16k and it makes a decision for both cases (altrom on or altrom off) because the altrom's enable status can't be known until a memory read or write is seen.

For a +3 type machine, ie the Next, if both lock rom bits are zero (bits 5:4 of nr 0x8c), then the rom selection is determined by ports 0x7ffd and 0x1ffd like normal:

sram_active_rom <= bit 2 of port 1ffd & bit 4 of port 7ffd
This is the two-bit rom number 0-3 selected if the altrom is disabled

sram_alt_128 <= not bit 4 of port 7ffd
If 1, this selects the 128k altrom else the 48k altrom when altrom is enabled.

If either of the lock rom bits are non-zero (bits 5:4 of nr 0x8c) then the rom locking feature takes effect. The rom selected by ports 7ffd and 1ffd is ignored.

sram_active_rom <= nr_8c_altrom_lock_rom1 & nr_8c_altrom_lock_rom0;
This is the two-bit rom number 1-3 selected if the altrom is disabled. Note you can't lock rom 0.

sram_alt_128 <= not nr_8c_altrom_lock_rom1;
If 1 this selects the 128k altorm else the 48k altrom when altrom is enabled.

The decision about whether the altrom is paged into the bottom 16k (sram_alt_128) or if it's the regular rom paged in (sram_active_rom) is made when the cpu read/write signal is seen:

altrom is disabled if:
: - bit 7 of nr 0x8c is 0
: OR
: - it's a memory read and bit 6 of nr 0x8c is 1
: OR
: - it's a memory write and bit 6 of nr 0x8c is 0

(new register since core 3.0.5, further slightly modified in 3.1.x cores)

(note: Next registers with number higher than $7F are inaccessible from Copper code)

Sprite port-mirror Attribute 4 (with INC) Register

2025-10-14T12:19:12Z

Xalior: Xalior moved page Sprite port-mirror Attribute 4 (with INC) Register to Sprite Attribute 4 (with INC) Register: match formal nextreg.txt name

#REDIRECT [[Sprite Attribute 4 (with INC) Register]]

Sprite Attribute 4 (with INC) Register

2025-10-14T12:19:12Z

Xalior: Xalior moved page Sprite port-mirror Attribute 4 (with INC) Register to Sprite Attribute 4 (with INC) Register: match formal nextreg.txt name

{{NextRegister
|Number=$79
|Readable=No
|Writable=Yes
|ShortDesc=The same as {{NextRegNo|$39}} (write fifth byte of sprite-attributes), plus increments {{NextRegNo|$34}}
}}
Byte 5 is bitmapped:
:For '''anchor''' sprites:
{|class="wikitable"
! Bit !! Description
|-
| 7-6 || "H N6" - "H" is 4/8 bit graphics selector, "N6" is sub-pattern selector for 4 bit modes. 
%00 = 8-bit colour patterns (256 bytes), this sprite is "'''anchor'''" 
%01 = this sprite is "'''relative'''" (4/8-bit colour is selected by "anchor" sprite) → see tables below 
%10 = 4-bit colour pattern (128 bytes) using bytes 0..127 of pattern slot, this sprite is "'''anchor'''" 
%11 = 4-bit colour pattern (128 bytes) using bytes 128..255 of pattern slot, this sprite is "'''anchor'''"
|-
| 5 || Type for following '''relative''' sprites: 0 = "composite", 1 = "big sprite"
|-
| 4-3 || x-axis scale factor: %00 = 1x (16 pixels), %01 = 2x, %10 = 4x, %11 = 8x (128 pixels)
|-
| 2-1 || y-axis scale factor: %00 = 1x (16 pixels), %01 = 2x, %10 = 4x, %11 = 8x (128 pixels)
|-
| 0 || MSB of Y coordinate
|}
:For '''composite relative''' sprites:
{|class="wikitable"
! Bit !! Description
|-
| 7-6 ||%01 = relative sprite
|-
| 5 || "N6" bit, in 4-bit colour mode 0 = using bytes 0..127 of pattern slot, 1 = using bytes 128..255 of pattern slot. In 8-bit mode use 0.
|-
| 4-3 || x-axis scale factor: %00 = 1x (16 pixels), %01 = 2x, %10 = 4x, %11 = 8x (128 pixels)
|-
| 2-1 || y-axis scale factor: %00 = 1x (16 pixels), %01 = 2x, %10 = 4x, %11 = 8x (128 pixels)
|-
| 0 || Enable relative pattern offset (1 = Pattern index is added to anchor pattern index, 0 = independent pattern index)
|}
:For '''big-sprite relative''' sprites:
{|class="wikitable"
! Bit !! Description
|-
| 7-6 ||%01 = relative sprite
|-
| 5 || "N6" bit, in 4-bit colour mode 0 = using bytes 0..127 of pattern slot, 1 = using bytes 128..255 of pattern slot. In 8-bit mode use 0.
|-
| 4-1 || use 0 (scaling is defined by '''anchor''' sprite)
|-
| 0 || Enable relative pattern offset (1 = Pattern index is added to anchor pattern index, 0 = independent pattern index)
|}

See {{PortNo|$xx57}} for extra notes about anchor/relative sprites, coordinates and clipping.

After write into sprite-attribute "byte 5" ({{PortNo|$xx57}}), the {{NextRegNo|$34}} is incremented (with all consequences stemming from such action). If the sprite 127 was modified, the result of the increment is officially "undefined behaviour", and code should explicitly set valid 0..127 sprite index before next sprite-attribute manipulation.

Sprite port-mirror Attribute 3 (with INC) Register

2025-10-14T12:19:04Z

Xalior: Xalior moved page Sprite port-mirror Attribute 3 (with INC) Register to Sprite Attribute 3 (with INC) Register

#REDIRECT [[Sprite Attribute 3 (with INC) Register]]

Sprite Attribute 3 (with INC) Register

2025-10-14T12:19:04Z

Xalior: Xalior moved page Sprite port-mirror Attribute 3 (with INC) Register to Sprite Attribute 3 (with INC) Register

{{NextRegister
|Number=$78
|Readable=No
|Writable=Yes
|ShortDesc=Same as {{NextRegNo|$38}} (write fourth byte of sprite-attributes), plus increments {{NextRegNo|$34}}
}}
Byte 4 is bitmapped:
{|class="wikitable"
! Bit !! Description
|-
| 7 || Enable visibility
|-
| 6 || Enable fifth sprite attribute byte
|-
| 5-0 || Pattern index ("Name")
|}

When the bit 6 is "0", the sprite renderer will ignore value written in fifth attribute byte, for example by {{NextRegNo|$39}}, and it will use zero for all the features of fifth attribute byte (it is safe to initialize only four bytes if you are planning to use 4-byte type of sprites).

If you want the value in fifth attribute byte to apply during rendering, bit 6 here must be set to "1".

After write into sprite-attribute "byte 4" ({{PortNo|$xx57}}), the {{NextRegNo|$34}} is incremented (with all consequences stemming from such action). If the sprite 127 was modified, the result of the increment is officially "undefined behaviour", and code should explicitly set valid 0..127 sprite index before next sprite-attribute manipulation.

Sprite port-mirror Attribute 2 (with INC) Register

2025-10-14T12:18:57Z

Xalior: Xalior moved page Sprite port-mirror Attribute 2 (with INC) Register to Sprite Attribute 2 (with INC) Register: match formal nextreg.txt name

#REDIRECT [[Sprite Attribute 2 (with INC) Register]]

Sprite Attribute 2 (with INC) Register

2025-10-14T12:18:57Z

Xalior: Xalior moved page Sprite port-mirror Attribute 2 (with INC) Register to Sprite Attribute 2 (with INC) Register: match formal nextreg.txt name

{{NextRegister
|Number=$77
|Readable=No
|Writable=Yes
|ShortDesc=Same as {{NextRegNo|$37}} (write third byte of sprite-attributes), plus increments {{NextRegNo|$34}}
}}
Byte 3 is bitmapped:
{|class="wikitable"
! Bit !! Description
|-
| 4-7 || Palette offset, added to each palette index from pattern before drawing
|-
| 3 || Enable X mirror
|-
| 2 || Enable Y mirror
|-
| 1 || Enable rotation
|-
| 0 || '''anchor''' sprite: MSB of X coordinate 
'''relative''' sprite: enable relative Palette offset (1 = the anchor Palette offset is added, 0 = independent Palette offset)
|}

After write into sprite-attribute "byte 3" ({{PortNo|$xx57}}), the {{NextRegNo|$34}} is incremented (with all consequences stemming from such action). If the sprite 127 was modified, the result of the increment is officially "undefined behaviour", and code should explicitly set valid 0..127 sprite index before next sprite-attribute manipulation.

Sprite port-mirror Attribute 1 (with INC) Register

2025-10-14T12:18:33Z

Xalior: Xalior moved page Sprite port-mirror Attribute 1 (with INC) Register to Sprite Attribute 1 (with INC) Register: match formal nextreg.txt name

#REDIRECT [[Sprite Attribute 1 (with INC) Register]]

Sprite Attribute 1 (with INC) Register

2025-10-14T12:18:33Z

Xalior: Xalior moved page Sprite port-mirror Attribute 1 (with INC) Register to Sprite Attribute 1 (with INC) Register: match formal nextreg.txt name

{{NextRegister
|Number=$76
|Readable=No
|Writable=Yes
|ShortDesc=Same as {{NextRegNo|$36}} (write second byte of sprite-attributes), plus increments {{NextRegNo|$34}}
}}
Eight low bits of Y position. MSB of Y-pos is in "byte 5".

After write into sprite-attribute "byte 2" ({{PortNo|$xx57}}), the {{NextRegNo|$34}} is incremented (with all consequences stemming from such action). If the sprite 127 was modified, the result of the increment is officially "undefined behaviour", and code should explicitly set valid 0..127 sprite index before next sprite-attribute manipulation.

Sprite port-mirror Attribute 0 (with INC) Register

2025-10-14T12:18:08Z

Xalior: Xalior moved page Sprite port-mirror Attribute 0 (with INC) Register to Sprite Attribute 0 (with INC) Register: match formal nextreg.txt name

#REDIRECT [[Sprite Attribute 0 (with INC) Register]]

Sprite Attribute 0 (with INC) Register

2025-10-14T12:18:08Z

Xalior: Xalior moved page Sprite port-mirror Attribute 0 (with INC) Register to Sprite Attribute 0 (with INC) Register: match formal nextreg.txt name

{{NextRegister
|Number=$75
|Readable=No
|Writable=Yes
|ShortDesc=Same as {{NextRegNo|$35}} (write first byte of sprite-attributes), plus increments {{NextRegNo|$34}}
}}
Eight low bits of X position. MSB of X-pos is in "byte 3".

After write into sprite-attribute "byte 1" ({{PortNo|$xx57}}), the {{NextRegNo|$34}} is incremented (with all consequences stemming from such action). If the sprite 127 was modified, the result of the increment is officially "undefined behaviour", and code should explicitly set valid 0..127 sprite index before next sprite-attribute manipulation.