SpecNext Wiki - Recent changes [en-gb]

Bibliography

Johnnyo — Sun, 31 May 2026 10:18:15 GMT

ZX Spectrum Books and Documentation: ZX Spectrum BASIC Programming

← Older revision		Revision as of 11:18, 31 May 2026
(3 intermediate revisions by the same user not shown)
Line 22:		Line 22:
	= ZX Spectrum Books and Documentation =		= ZX Spectrum Books and Documentation =
	Many books were written since 1982, this is just a selection.		Many books were written since 1982, this is just a selection.

			== ''Sinclair ZX Spectrum BASIC Programming'' by Steven Vickers (1982) ==

			* https://worldofspectrum.net/ZXBasicManual/ The book included in the original package of ZX Spectrum 48K. Wealth of information in a single book.

			== ''Step-by-Step Programming ZX Spectrum'' Series ==
			* Book One, by Ian Graham (1984) https://worldofspectrum.net/item/2001330/
			* Book Two, by Ian Graham (1984) https://worldofspectrum.net/item/2001331/
			* Book Three, by Piers Letcher (1985) https://worldofspectrum.net/item/2000385/
			* Book Four, by Piers Letcher (1985) https://worldofspectrum.net/item/2000460/

	== ''How to Write Spectrum Games'' by Jonathan Cauldwell ==		== ''How to Write Spectrum Games'' by Jonathan Cauldwell ==
	* https://jonathan-cauldwell.itch.io/how-to-write-spectrum-games (Since 2006, updated recently)		* https://jonathan-cauldwell.itch.io/how-to-write-spectrum-games (Since 2006, updated recently)

Layer 2

Johnnyo — Wed, 20 May 2026 00:39:10 GMT

rewording

← Older revision		Revision as of 01:39, 20 May 2026
(2 intermediate revisions by the same user not shown)
Line 3:		Line 3:
	The palette used to show the Layer 2 is selected by the bit 2 of the {{NextRegNo\|$43}}.		The palette used to show the Layer 2 is selected by the bit 2 of the {{NextRegNo\|$43}}.

	The Layer 2 screen occupies 48kiB or 80kiB, ~~which is stored in~~ 3 (or 5) consecutive [[Memory map\|banks]]. By NextZXOS/NextBASIC default, banks 9-11 are used for the visible and "shadow" Layer 2 screen (the HW after power-on defaults to 8-10 for displayed and 11-13 for shadow screen, but ~~that gets~~ modified by NextZXOS ~~booting up~~). ~~These~~ can be ~~set~~ using {{NextRegNo\|$12}} and {{NextRegNo\|$13}} (avoid banks 5, 7 and 8 ~~to be used as~~ Layer 2 screen, unless you are familiar with SRAM and BRAM of the board and how the ULA screen memory has special treatment in Next's FPGA).		The Layer 2 screen occupies 48kiB or 80kiB, spreading over 3, or 5, consecutive 16K [[Memory map\|banks]]. By the NextZXOS/NextBASIC default, the same banks 9-11 are used for both the visible and the "shadow" Layer 2 screen (the core, after power-on but before the NextZXOS boots set its defaults to 8-10 for the displayed Layer 2 screen and 11-13 for the shadow screen, but these settings are modified during the boot of NextZXOS). The starting bank of the main Layer 2 screen can be changed using {{NextRegNo\|$12}} and and the starting bank for the shadow Layer 2 screen can be changed using {{NextRegNo\|$13}} (avoid using banks 5, 7 and 8 for the Layer 2 screen, unless you are familiar with SRAM and BRAM of the board and how the ULA screen memory has special treatment in Next's FPGA).

	Each pixel of Layer 2 takes one byte of video memory in 8bpp modes or half a byte in 4bpp mode, so the Layer 2 needs 48kiB for 256x192 mode or 80kiB for 320x256-8bit or 640x256-4bit mode. The Layer 2 256x192 mode is divided '''horizontally''' into 3 16kiB banks of 64 '''lines''' each. The modes 320x256 and 640x256 are divided '''vertically''' into 5 16kiB banks of 64 '''columns''' each for 320x256 mode or 128 '''columns''' each for 640x256 mode.		Each pixel of Layer 2 takes one byte of video memory in 8bpp modes or half a byte in 4bpp mode, so the Layer 2 needs 48kiB for 256x192 mode or 80kiB for 320x256-8bit or 640x256-4bit mode. The Layer 2 256x192 mode is divided '''horizontally''' into 3 16kiB banks of 64 '''lines''' each. The modes 320x256 and 640x256 are divided '''vertically''' into 5 16kiB banks of 64 '''columns''' each for 320x256 mode or 128 '''columns''' each for 640x256 mode.

Bibliography

Johnnyo — Tue, 19 May 2026 23:40:18 GMT

ZX Spectrum Next Documentation

← Older revision		Revision as of 00:40, 20 May 2026
(6 intermediate revisions by the same user not shown)
Line 1:		Line 1:
	= ZX Spectrum Next Documentation =		= ZX Spectrum Next Documentation =

			The Next project is continuously improved, so it's a good practice to check for the most recent updates of the manuals, documents and Next-specific books.

	== ZX Spectrum Next Manual ==		== ZX Spectrum Next Manual ==
Line 6:		Line 8:

	== ''docs'' Directory of the Distribution ==		== ''docs'' Directory of the Distribution ==
	* https://gitlab.com/thesmog358/tbblue/-/tree/master/docs , especially note the [https://gitlab.com/thesmog358/tbblue/-/tree/master/docs/nextzxos nextzxos] folder.		* https://gitlab.com/thesmog358/tbblue/-/tree/master/docs , especially note the [https://gitlab.com/thesmog358/tbblue/-/tree/master/docs/nextzxos nextzxos] folder written and kept up to date by the author of NextZXOS and NextBASIC.

	= Next-specific Books =		= Next-specific Books =

			(The Next specific books are typically written under assumption that the reader is already familiar enough with the low-level hardware programming aspects relevant to the original ZX Spectrum, so the readers who aren't should also check the books about the "classic" ZX Spectrum too)

	== ''ZX Spectrum Next Assembly Developer Guide'' by Tomaž Kragelj ==		== ''ZX Spectrum Next Assembly Developer Guide'' by Tomaž Kragelj ==
	* Available as a free to download PDF https://github.com/tomaz/zx-next-dev-guide/ or a printed coil bound book.		* Available as a free to download PDF https://github.com/tomaz/zx-next-dev-guide/ or as a printed coil bound book.

	== ''ZX Spectrum Next Programming Notes'' by Theodore (Alex) Evans ==		== ''ZX Spectrum Next Programming Notes'' by Theodore (Alex) Evans ==
	* https://github.com/varmfskii/zxnext_code/tree/master/zx_next_notes		* https://github.com/varmfskii/zxnext_code/tree/master/zx_next_notes

	= ZX Spectrum Books and Documentation =		= ZX Spectrum Books and Documentation =
			Many books were written since 1982, this is just a selection.
	== ''How to Write Spectrum Games'' by Jonathan Cauldwell ==		== ''How to Write Spectrum Games'' by Jonathan Cauldwell ==
	* https://jonathan-cauldwell.itch.io/how-to-write-spectrum-games		* https://jonathan-cauldwell.itch.io/how-to-write-spectrum-games (Since 2006, updated recently)
	== ''comp.sys.sinclair FAQ'' ==		== ''comp.sys.sinclair FAQ'' ==
	* https://worldofspectrum.org/faq/reference/reference.htm		* https://worldofspectrum.org/faq/reference/reference.htm
			== ''First Steps in Z80 Assembly Language'' (for ZX Spectrum) by Darryl Sloan (2020) ==
			* The motivation for writing this book in 2020 was the release of the Sinclair ZX Spectrum Next, even if it (mostly?) covers the assembly which would work on the original ZX Spectrum: http://ped.7gods.org/z80.pdf
			== ''Understanding Your Spectrum'' by Dr. Ian Logan (1982) ==
			* https://spectrumcomputing.co.uk/entry/2000400/Book/Understanding_Your_Spectrum

Compilers

Johnnyo — Thu, 14 May 2026 11:13:20 GMT

ZX Basic Studio: link to a text

← Older revision		Revision as of 12:13, 14 May 2026
(2 intermediate revisions by the same user not shown)
Line 1:		Line 1:
	== BASIC ==		== BASIC ==

	=== ''[https://zxbasic.readthedocs.io/ ZX Basic]'' ===		=== ''[https://zxbasic.readthedocs.io/ Boriel Basic (ZX Basic)]'' ===
	: A Basic to Z80 compiler with extensions added to Sinclair Basic.		: A Basic to Z80 compiler with extensions added to Sinclair Basic.

			=== ''[https://github.com/boriel-basic/ZXBasicStudio/releases ZX Basic Studio]'' ===
			: A multiplatform IDE for Boriel BASIC, with itegration with emulators for ZX Spectrum Next (CSpect, ZEsarUX and MAME), GDU and font editor, Sprite editor with import from external images, Colour palette editor for ZX Spectrum Next. Its [https://boriel-basic.net/page/preparing-the-development-environment installer] allows an easy start on Windows, Linux and MacOS.

	=== ''[https://github.com/em00k/NextBuild NextBuild v7]'' ===		=== ''[https://github.com/em00k/NextBuild NextBuild v7]'' ===

Hw im2 mode

Johnnyo — Tue, 12 May 2026 19:25:38 GMT

bit 0

← Older revision		Revision as of 20:25, 12 May 2026
(3 intermediate revisions by the same user not shown)
Line 1:		Line 1:
	hw im2 mode is enabled by the bit 0 of {{NextRegNo\|$C0}}.		hw im2 mode is enabled by the bit 0 of {{NextRegNo\|$C0}}.

	If not in hw im2 mode, ie normal ~~spectrum~~ behaviour, then all devices that generate an interrupt do it by asserting /int low for around 30 cycles and that's it.		If not in hw im2 mode, i.e. normal Spectrum behaviour, then all devices that generate an interrupt do it by asserting /int low for around 30 cycles and that's it.

	If you are in hw im2 mode, then all interrupting devices including the ~~ula has~~ an im2 state machine attached. If an interrupt is generated, the state machine remembers this as it moves to an assert /int state. Recognition of RETI for the specific device moves the state machine to a place where another /int from the device can be accepted.		If you are in hw im2 mode, then all interrupting devices including the ULA have an im2 state machine attached. If an interrupt is generated, the state machine remembers this as it moves to an assert /int state. Recognition of RETI for the specific device moves the state machine to a place where another /int from the device can be accepted.

	For recognition of RETI:		For recognition of RETI:

	reti instruction has been detected active in T3 for rising edge of T4		reti instruction has been detected active in T3 for rising edge of T4
Line 11:		Line 11:
	so on rising edge of T4, the hw will move to a state where it will see a new int event from the device. /int events are edge detected so you can't hold /int low forever and keep generating interrupts.		so on rising edge of T4, the hw will move to a state where it will see a new int event from the device. /int events are edge detected so you can't hold /int low forever and keep generating interrupts.

	That does mean, eg, that if multiple events occur while the isr still hasn't executed RETI then you're not going to see more than the one current ~~int~~. If the ~~dma~~ is taking a long time, multiple ~~ctc ints~~ on a channel only ~~generates~~ one channel interrupt when the dma ultimately gives up the bus. If you have the ~~ctc~~ interrupting ~~dma~~ op, then you'll see them all most likely		That does mean, e.g., that if multiple events occur while the isr still hasn't executed RETI then you're not going to see more than the one current interrupt. If the DMA is taking a long time, multiple CTC interrupts on a channel only generate one channel interrupt when the dma ultimately gives up the bus. If you have the CTC interrupting DMA op, then you'll see them all most likely.

			= The background =

			Zilog defines what IM2 mode is.. the hardware is in a physically ordered daisy chain with each interrupting device using that chain to know which has highest priority. The devices put vectors on the bus during int ack so that the z80 can jump directly to a specific device's ISR.

			Sinclair does not support that and instead the ula is a like a traditional 8080 device with one int signal going to one ISR in im1 mode. There is no intelligence in the ula for interrupts, just a notion of asserting the int line low for about 30 cycles.

			Even when you put the z80 in im2 mode, the devices don't obey Zilog's im2 scheme. That's why you need 257 bytes in the vector table that are all the same. The ula does not provide a vector.

			For backwards compatibility, the Next's devices normally work in the spectrum mode where they know nothing about interrupts other than pulling into low for about 30 cycles.

			You can choose to operate in hw im2 mode where the hw switches to implementing Zilog's im2 scheme via the bit 0 in {{NextRegNo\|$C0}}. That's when you have prioritized interrupts and unique vectors/ISRs for each interrupting device. What's new in the Next is that these interrupts can also be set to interrupt a dma operation via nextreg in the CC range (see e.g. {{NextRegNo\|$CC}}) AFAIK (says AA) that's not been done anywhere else.

MAME:Installing

Orcmeal — Tue, 12 May 2026 16:24:05 GMT

Added info about required SDL3 library when installing on macOS.

← Older revision		Revision as of 17:24, 12 May 2026
(One intermediate revision by the same user not shown)
Line 9:		Line 9:
	=== 1. Get MAME ===		=== 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.		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.

			MAME for macOS now requires the SDL3 library.

	* '''Windows:''' Download [https://www.mamedev.org/release.html MAME for Windows].		* '''Windows:''' Download [https://www.mamedev.org/release.html MAME for Windows].
	* '''macOS:''' Download [https://sdlmame.lngn.net/ MAME for macOS].		* '''macOS:''' Download the [https://github.com/libsdl-org/SDL/releases/latest SDL3 library], and copy its '''SDL3.xcframework''' and '''share''' folders to ~/Library/Frameworks, as instructed in the included INSTALL.md file. Then download [https://sdlmame.lngn.net/ MAME for macOS].
	* '''Linux:''' Install MAME from the flatpak repositories by running:		* '''Linux:''' Install MAME from the flatpak repositories by running:
	<pre>sudo flatpak install org.mamedev.MAME</pre>		<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.		Note that Windows and macOS will likely prevent you from launching MAME (and the SDL3 framework) 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].		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].
Line 91:		Line 93:
	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.		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.		You will then need to '''repeat this process for the SDL3 framework.'''

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

	= Keys =		= Keys =

Layer 2

Johnnyo — Thu, 07 May 2026 15:46:33 GMT

half a byte

← Older revision		Revision as of 16:46, 7 May 2026
(One intermediate revision by the same user not shown)
Line 5:		Line 5:
	The Layer 2 screen occupies 48kiB or 80kiB, which is stored in 3 (or 5) consecutive [[Memory map\|banks]]. By NextZXOS/NextBASIC default, banks 9-11 are used for the visible and "shadow" Layer 2 screen (the HW after power-on defaults to 8-10 for displayed and 11-13 for shadow screen, but that gets modified by NextZXOS booting up). These can be set using {{NextRegNo\|$12}} and {{NextRegNo\|$13}} (avoid banks 5, 7 and 8 to be used as Layer 2 screen, unless you are familiar with SRAM and BRAM of the board and how the ULA screen memory has special treatment in Next's FPGA).		The Layer 2 screen occupies 48kiB or 80kiB, which is stored in 3 (or 5) consecutive [[Memory map\|banks]]. By NextZXOS/NextBASIC default, banks 9-11 are used for the visible and "shadow" Layer 2 screen (the HW after power-on defaults to 8-10 for displayed and 11-13 for shadow screen, but that gets modified by NextZXOS booting up). These can be set using {{NextRegNo\|$12}} and {{NextRegNo\|$13}} (avoid banks 5, 7 and 8 to be used as Layer 2 screen, unless you are familiar with SRAM and BRAM of the board and how the ULA screen memory has special treatment in Next's FPGA).

	Each pixel of Layer 2 ~~is assigned 1~~ byte of video memory (in 8bpp modes~~). This means~~ Layer 2 ~~consumes a total of~~ 48kiB (256x192) or 80kiB (320x256). ~~Since the Spectrum banks are 16kiB,~~ Layer 2 256x192 mode is divided horizontally into 3 banks of 64 lines each~~, each of which is exactly 16kiB~~. The ~~mode~~ 320x256 (and 640x256~~) is~~ divided vertically into 5 banks of 64 (128) columns each.		Each pixel of Layer 2 takes one byte of video memory in 8bpp modes or half a byte in 4bpp mode, so the Layer 2 needs 48kiB for 256x192 mode or 80kiB for 320x256-8bit or 640x256-4bit mode. The Layer 2 256x192 mode is divided '''horizontally''' into 3 16kiB banks of 64 '''lines''' each. The modes 320x256 and 640x256 are divided '''vertically''' into 5 16kiB banks of 64 '''columns''' each for 320x256 mode or 128 '''columns''' each for 640x256 mode.

	Layer 2 is controlled via {{PortNo\|$123B}} and {{NextRegNo\|$70}}, the port is bit mapped as follows:		Layer 2 is controlled via {{PortNo\|$123B}} and {{NextRegNo\|$70}}, the port is bit mapped as follows:

Pi:dev build environment

SirCliveSinclairbot — Tue, 05 May 2026 18:07:52 GMT

via /pi-wiki-publish

← Older revision		Revision as of 19:07, 5 May 2026
Line 33:		Line 33:
	sudo apt-get install -y debootstrap qemu-user-static binfmt-support		sudo apt-get install -y debootstrap qemu-user-static binfmt-support
	</syntaxhighlight>		</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:		Verify:
Line 44:		Line 42:

	=== 2. Add the apt signing key ===		=== 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">		<syntaxhighlight lang="bash">
Line 69:		Line 65:
	</syntaxhighlight>		</syntaxhighlight>

	~~debootstrap downloads ~50 MB of~~ <code>~~.deb~~</code>~~s, extracts them, and ends with this warning:~~		Ends with <code>W: Failure while configuring required packages</code>. Continue.

	~~<pre>~~		=== 4. Neutralise segfaulting postinsts and force-install ===
	~~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.~~		<syntaxhighlight lang="bash">
			for pkg in systemd plymouth mountall; do
	~~=== 4. Force~~-~~install the unconfigured packages ===~~		printf '#!/bin/sh\nexit 0\n' \
			\| sudo tee /srv/nextpi-buildroot/var/lib/dpkg/info/${pkg}.postinst > /dev/null
	~~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:~~		sudo chmod +x /srv/nextpi-buildroot/var/lib/dpkg/info/${pkg}.postinst
			done

	~~<syntaxhighlight lang="bash">~~
	sudo chroot /srv/nextpi-buildroot \		sudo chroot /srv/nextpi-buildroot \
	/usr/bin/env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin LANG=C \		/usr/bin/env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin LANG=C \
Line 88:		Line 81:
	</syntaxhighlight>		</syntaxhighlight>

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

	Verify:

	<syntaxhighlight lang="bash">		<syntaxhighlight lang="bash">
Line 108:		Line 99:
	</syntaxhighlight>		</syntaxhighlight>

	~~These are session~~-only; see [[#Persistent mounts\|Persistent mounts]] ~~below~~ for fstab.		Session-only; see [[#Persistent mounts\|Persistent mounts]] 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:~~		=== 6. Hold systemd, plymouth, mountall ===

	<syntaxhighlight lang="bash">		<syntaxhighlight lang="bash">
Line 120:		Line 109:
	</syntaxhighlight>		</syntaxhighlight>

	=== 7. Install ~~build dependencies~~ ===		=== 7. Install the NextPi 1.92D package set + dev variants ===

	<syntaxhighlight lang="bash">		<syntaxhighlight lang="bash">
	sudo chroot /srv/nextpi-buildroot \		sudo chroot /srv/nextpi-buildroot \
	/usr/bin/env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin LANG=C HOME=/root \		/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 \		/bin/bash -c "
	~~autoconf automake libtool libtool-bin pkg-config \~~		apt-get update -qq && \
	~~libbz2-dev libaudiofile-dev~~ \		wget -q -O /tmp/buildroot.packages https://zx.xalior.com/nextpi_dev/buildroot.packages && \
	~~wget git ca-certificates~~"		DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
			\$(cat /tmp/buildroot.packages)
			"
	</syntaxhighlight>		</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~~.		~50 s on Pi 5 / NVMe; chroot grows to ~2.0 GB. Toolchain check:

	~~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">		<syntaxhighlight lang="bash">
Line 159:		Line 146:
	</syntaxhighlight>		</syntaxhighlight>

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

	<syntaxhighlight lang="bash">		<syntaxhighlight lang="bash">
Line 165:		Line 152:
	# ELF 32-bit LSB shared object, ARM, EABI5 version 1 (SYSV), dynamically linked		# ELF 32-bit LSB shared object, ARM, EABI5 version 1 (SYSV), dynamically linked
	</syntaxhighlight>		</syntaxhighlight>

	~~Chroot is ready.~~

	== Persistent mounts ==		== Persistent mounts ==

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

	<syntaxhighlight lang="text">		<syntaxhighlight lang="text">
Line 179:		Line 164:
	</syntaxhighlight>		</syntaxhighlight>

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

			== Sources ==

			* Apt mirror: <code>http://zx.xalior.com/nextpi_dev stretch main contrib non-free rpi firmware</code>.
			* Signing key: https://zx.xalior.com/nextpi_dev/debian_nextpi.key — sha256 <code>ca59cd4f2bcbc3a1d41ba6815a02a8dc5c175467a59bd87edeac458f4a5345de</code>. Byte-identical to https://archive.raspbian.org/raspbian.public.key.
			* Package list: https://zx.xalior.com/nextpi_dev/buildroot.packages — 369 entries (NextPi 1.92D installed set, less firmware/kernel/Pi-hardware, plus available <code>-dev</code> variants).
			* Smoke-test source: libspectrum 1.6.0 from https://sourceforge.net/projects/fuse-emulator/files/libspectrum/.

Pi:dev build environment

Xalior — Tue, 05 May 2026 17:15:46 GMT

← Older revision		Revision as of 18:15, 5 May 2026
(One intermediate revision by the same user not shown)
Line 1:		Line 1:
	'''~~Early~~ draft.''' Procedure validated 2026-05-05 on Pi OS Bookworm / Pi 5~~. Corrections welcome on the talk page~~.		'''Working draft.''' Procedure re-validated 2026-05-05 on Pi OS Bookworm / Pi 5.

	----		----

Pi:dev build environment

SirCliveSinclairbot — Tue, 05 May 2026 17:14:43 GMT

via /pi-wiki-publish

← Older revision		Revision as of 18:14, 5 May 2026
Line 1:		Line 1:
	~~{{Note\|~~'''Early draft.''' Procedure validated 2026-05-05 on Pi OS Bookworm / Pi 5. Corrections welcome on the talk page.}}		'''Early draft.''' Procedure 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.''		''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.''

Pi:dev build environment

SirCliveSinclairbot — Tue, 05 May 2026 17:13:35 GMT

via /pi-wiki-publish

New page

{{Note|'''Early draft.''' Procedure 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

Xalior — Tue, 05 May 2026 13:58:13 GMT

← Older revision		Revision as of 14:58, 5 May 2026
Line 5:		Line 5:
	== Prerequisits ==		== Prerequisits ==

	* NextPi Version: 1.~~93A~~		* NextPi Version: 1.91D

	== Backend ==		== Backend ==

Assemblers

Johnnyo — Tue, 05 May 2026 08:03:44 GMT

Native tools (running on Next): specasm

← Older revision		Revision as of 09:03, 5 May 2026
Line 62:		Line 62:

	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].		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://github.com/markdryan/specasm specasm]'' ===

			Mark Ryan's specasm assembler suite which includes an editor, an assembler, a linker and a tap file generator.
			.specasm command launches an integrated editor/assembler.
			Supports all the Z80n instructions. All mnemonics are entered in lower case. The edited files are .x files, which are annotated object files, with the instructions pre-assembled.

	=== ''[https://taylorza.itch.io/nextbasic-inline-assembler NextBASIC Inline Assembler]''===		=== ''[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]		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]

Layer 2

Johnnyo — Mon, 04 May 2026 13:40:39 GMT

palette detail

← Older revision		Revision as of 14:40, 4 May 2026
Line 1:		Line 1:
	Layer 2 provides an additional screen layer at 256x192 256 colours, 320x256 256 colours or 640x256 16 colours in which every pixel is individually coloured. Layer 2 may appear in place of, behind, or above the ULA-generated/Tilemap layer.		Layer 2 provides an additional screen layer at 256x192 256 colours, 320x256 256 colours or 640x256 16 colours in which every pixel is individually coloured. Layer 2 may appear in place of, behind, or above the ULA-generated/Tilemap layer.

			The palette used to show the Layer 2 is selected by the bit 2 of the {{NextRegNo\|$43}}.

	The Layer 2 screen occupies 48kiB or 80kiB, which is stored in 3 (or 5) consecutive [[Memory map\|banks]]. By NextZXOS/NextBASIC default, banks 9-11 are used for the visible and "shadow" Layer 2 screen (the HW after power-on defaults to 8-10 for displayed and 11-13 for shadow screen, but that gets modified by NextZXOS booting up). These can be set using {{NextRegNo\|$12}} and {{NextRegNo\|$13}} (avoid banks 5, 7 and 8 to be used as Layer 2 screen, unless you are familiar with SRAM and BRAM of the board and how the ULA screen memory has special treatment in Next's FPGA).		The Layer 2 screen occupies 48kiB or 80kiB, which is stored in 3 (or 5) consecutive [[Memory map\|banks]]. By NextZXOS/NextBASIC default, banks 9-11 are used for the visible and "shadow" Layer 2 screen (the HW after power-on defaults to 8-10 for displayed and 11-13 for shadow screen, but that gets modified by NextZXOS booting up). These can be set using {{NextRegNo\|$12}} and {{NextRegNo\|$13}} (avoid banks 5, 7 and 8 to be used as Layer 2 screen, unless you are familiar with SRAM and BRAM of the board and how the ULA screen memory has special treatment in Next's FPGA).

ZENext:Installing

Johnnyo — Sat, 02 May 2026 16:15:16 GMT

Run

← Older revision		Revision as of 17:15, 2 May 2026
(One intermediate revision by the same user not shown)
Line 28:		Line 28:
	Read how to download or create the SD card image on the: [[MAME:Installing#Creating_and_manipulating_NextZXOS_SD_card_image]] page		Read how to download or create the SD card image on the: [[MAME:Installing#Creating_and_manipulating_NextZXOS_SD_card_image]] page

	Notes: The upstream zesarux can't use big images because it loads them into RAM - but zenext doesn't do/suffer that. zenext does non-exclusive file locking, so you can mount from OS and emulator at same time.		Notes: The upstream zesarux can't use big images because it loads them into RAM - but zenext doesn't do/suffer that. zenext does non-exclusive file locking, so you can mount from OS and emulator at same time (also note: using such mounting increases chances for accidental corruption of the image or inconsistent views).

Pi:CLI

SirCliveSinclairbot — Sat, 02 May 2026 08:50:50 GMT

via /pi-wiki-publish

← Older revision		Revision as of 09:50, 2 May 2026
Line 25:		Line 25:
	* nextpi-admin_disable		* nextpi-admin_disable
	* nextpi-admin_enable		* nextpi-admin_enable
	* nextpi-admin_pupextract		* [[Pi:admin_pupextract\|nextpi-admin_pupextract]]
	* nextpi-admin_report		* nextpi-admin_report
	* nextpi-admin_uihelper		* nextpi-admin_uihelper

Pi:admin pupextract

SirCliveSinclairbot — Sat, 02 May 2026 08:50:33 GMT

via /pi-wiki-publish

New page

== 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.93A

== 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:9e2a321f-e57d-4fed-8d36-c226abdead75

SirCliveSinclairbot — Sat, 02 May 2026 08:48:50 GMT

via /pi-wiki-publish

← Older revision		Revision as of 09:48, 2 May 2026
Line 1:		Line 1:
	== ~~Sandbox~~ ==		== Abstract ==

	~~This page is a~~ transient synthetic test ~~for~~ the ~~[[Pi:CLI\|nextpi~~-]] wiki ~~publisher tooling~~. It ~~exists only to exercise the publish gate~~ and may be deleted at any time.		A transient synthetic test target used during Phase 3 verification of the `pi-wiki-publish` skill. It does not document a real frontend and may be deleted at any time.

	== ~~Frontends~~ ==		== Prerequisits ==

	~~The sandbox does not document a real frontend. See [[Pi~~:~~CLI]] for the index of supported frontends.~~		* NextPi Version: any

	~~[[Category~~:~~Sandbox]]~~		== Backend ==
			* Binary: none (synthetic test target)

			== Options ==

			None.

Pi:9e2a321f-e57d-4fed-8d36-c226abdead75

SirCliveSinclairbot — Sat, 02 May 2026 08:45:26 GMT

via /pi-wiki-publish

New page

== Sandbox ==

This page is a transient synthetic test for the [[Pi:CLI|nextpi-]] wiki publisher tooling. It exists only to exercise the publish gate and may be deleted at any time.

== Frontends ==

The sandbox does not document a real frontend. See [[Pi:CLI]] for the index of supported frontends.

[[Category:Sandbox]]

User:SirCliveSinclairbot

Xalior — Sat, 02 May 2026 08:44:47 GMT

Xalior changed group membership for SirCliveSinclairbot from (none) to bot