build: generated presets and a check entry point

tools/make_presets.py emits the uniform pipeline the hand-grown file had
drifted from — generated configure/build/test presets and workflows for
all 37 chips, reflect configure/build for libavr's 12-chip spot set —
and tools/check.sh runs every chip's workflow (--full adds the reflect
spot) as the port's gate.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_019553N6pLmaKhxEwkiCs3RX

.clang-format

@@ -7,9 +7,8 @@ TabWidth: 4
 UseTab: ForIndentation
 AlignEscapedNewlines: DontAlign
 AllowShortFunctionsOnASingleLine: Empty
-BreakTemplateDeclarations: Yes
+AlwaysBreakTemplateDeclarations: true
 BreakBeforeBraces: Custom
 BraceWrapping:
   AfterFunction: true
-InsertBraces: true
 ...

.clangd

@@ -1,38 +0,0 @@
-# Editor accommodations for the second frontend. No compilation database is
-# named here: this repo rides as a submodule in its consumers, and this file
-# travels with it — a consumer's own database then covers these sources, with
-# that project's loader flags. The checkout that is opened as a folder names
-# its build tree in .vscode/settings.json instead.
-CompileFlags:
-  Add:
-    # clang has no 24-bit integer and GCC's are keywords, not macros, so the
-    # editor needs a stand-in for avr::uint24_t. The next width up is the only
-    # one available — clang rejects _BitInt(24) on this target.
-    - -D__uint24=unsigned long
-    - -D__int24=long
-    # clangd forwards the driver's system includes but not its own header
-    # directory, so <stdint.h> resolves to avr-libc's, which still gates the
-    # limit and constant macros on the C++98 opt-in.
-    - -D__STDC_LIMIT_MACROS
-    - -D__STDC_CONSTANT_MACROS
-    # isr::emit spells a vector number into [[gnu::signal(N)]], which clang
-    # rejects rather than ignores — enough of them in one TU to reach the
-    # default limit of 19 inside the headers and truncate the parse.
-    - -ferror-limit=0
-  Remove:
-    # Codegen shaping the loader TUs carry and clang has no spelling for.
-    - -fira-algorithm=*
-    - -fno-split-wide-types
-    - -fno-tree-ter
-    - -fno-ivopts
-    - -fno-move-loop-invariants
-    # The build promotes warnings for the compiler that has to be right about
-    # them; in the editor the flag paints a second frontend's opinions in the
-    # colour reserved for things that do not compile.
-    - -Werror
-Diagnostics:
-  Suppress:
-    # clang's AVR `signal` attribute takes no arguments and it knows none of
-    # progmem, naked or OS_main. A misspelling is what the build is for.
-    - attribute_wrong_number_arguments
-    - unknown-attributes

.gitattributes

@@ -1,11 +1,8 @@
-# Line endings are the repository's, not the editing machine's: this checkout
-# is reached from two hosts, and a file rewritten by a Windows tool comes back
-# with every line changed unless something says otherwise. Naming the source
-# extensions left Markdown, Python, shell and CMake to whatever the writing
-# tool defaulted to, which is CRLF on one of the two.
-* text=auto eol=lf
-
-# Atmel Studio writes these and expects them back.
+*.h         eol=lf
+*.hpp       eol=lf
+*.c         eol=lf
+*.cpp       eol=lf
+.git*       eol=lf
 *.vcxproj*  eol=crlf
 *.cppproj   eol=crlf
 *.sln       eol=crlf

.gitignore

@@ -12,7 +12,6 @@ Debug
 
 # CMake / clangd
 /build/
-/local/
 compile_commands.json
 .cache/
 

.gitmodules

@@ -1,3 +0,0 @@
-[submodule "libavr"]
-	path = libavr
-	url = ../libavr.git

.vscode/extensions.json

@@ -1,6 +0,0 @@
-{
-	"recommendations": [
-		"llvm-vs-code-extensions.vscode-clangd",
-		"ms-vscode.cmake-tools"
-	]
-}

.vscode/settings.json

@@ -1,36 +0,0 @@
-{
-	// clangd is the language server; the cpptools engine would parse every file
-	// a second time and disagree, since nothing tells it about a cross
-	// compiler.
-	"C_Cpp.intelliSenseEngine": "disabled",
-
-	// --query-driver lets clangd ask the cross compiler for its own system
-	// includes and target. The database is named here rather than in .clangd
-	// because that file travels with the driver into a consumer's submodule,
-	// where a build tree of this repo's own need not exist.
-	"clangd.arguments": [
-		"--compile-commands-dir=${workspaceFolder}/build/atmega328p-generated",
-		"--query-driver=**avr-g++*",
-		"--header-insertion=never"
-	],
-
-	// The presets are the build interface, and the toolchain file inside the
-	// libavr submodule is the one place the compiler is chosen. **No prefix is
-	// named here**: a committed file may not name a path that is true of one
-	// machine (libavr guidance rule 50), so the gitignored local/machine.cmake
-	// at this repository's root is where a checkout says where its toolchain
-	// is - one file, and it answers for both hosts.
-	"cmake.useCMakePresets": "always",
-	"cmake.configureOnOpen": true,
-	"cmake.options.statusBarVisibility": "compact",
-
-	"files.watcherExclude": {
-		"**/build/**": true,
-		"**/libavr/**": true
-	},
-
-	"files.associations": {
-		".clangd": "yaml",
-		".clang-format": "yaml"
-	}
-}

CMakeLists.txt

@@ -2,78 +2,61 @@ cmake_minimum_required(VERSION 3.28)
 
 project(tsb_libavr LANGUAGES CXX)
 
-# libavr rides as the pinned submodule; LIBAVR_ROOT (cache or environment)
-# overrides it for tandem development against a working tree. The toolchain
-# file comes from the submodule via CMakePresets.json either way.
+# libavr from a local checkout (LIBAVR_ROOT) or the forge; the toolchain file
+# comes from the same checkout via CMakePresets.json.
+include(FetchContent)
 if(NOT LIBAVR_ROOT AND DEFINED ENV{LIBAVR_ROOT})
 	set(LIBAVR_ROOT $ENV{LIBAVR_ROOT})
 endif()
-if(NOT LIBAVR_ROOT)
-	set(LIBAVR_ROOT ${CMAKE_CURRENT_SOURCE_DIR}/libavr)
+if(LIBAVR_ROOT)
+	FetchContent_Declare(libavr SOURCE_DIR ${LIBAVR_ROOT})
+else()
+	FetchContent_Declare(libavr GIT_REPOSITORY git@git.blackmark.me:avr/libavr.git GIT_TAG main)
 endif()
-if(NOT EXISTS ${LIBAVR_ROOT}/CMakeLists.txt)
-	message(FATAL_ERROR "libavr not found at ${LIBAVR_ROOT} - run: git submodule update --init libavr")
-endif()
-add_subdirectory(${LIBAVR_ROOT} libavr-build)
-
-include(${LIBAVR_ROOT}/cmake/checks.cmake)
+FetchContent_MakeAvailable(libavr)
 
 if(PROJECT_IS_TOP_LEVEL)
 	add_compile_options(-Werror) # warnings are errors for the port's own code
 	enable_testing()
 
-	# Rules 11 and 33 over this repo's own sources. The oracle's assembly needs
-	# no exclusion: it is neither formatted nor ASCII-checked, being in neither
-	# glob, which is the right answer for a vendored reference whose text is
-	# the artifact.
-	libavr_format_test()
-
 	# The behavioral tests drive the real wire protocols over a simavr pty
-	# (as the host tools do) and actually flash the device. The runner is a
-	# host program built at configure time against libsimavr (C++23 - what the
-	# distribution's compiler speaks in full).
-	#
-	# **A host that cannot build it registers those tests anyway and skips
-	# them.** They used to be left out, which makes the suite a different size
-	# on a different machine - and a suite whose size is a property of the
-	# machine is one nothing can be compared against.
-	set(TSB_DEVICE ${CMAKE_BINARY_DIR}/tsb_device)
-	find_program(_host_cxx NAMES c++ g++)
-	set(_tsb_absent "${LIBAVR_NO_PYTHON}")
-	if(NOT _host_cxx)
-		set(_tsb_absent "no host C++ compiler on PATH, and the simavr device is a host program")
-	elseif(NOT _tsb_absent)
+	# (as the host tools do) and actually flash the device. The runners are
+	# host programs built at configure time against libsimavr; if they or
+	# Python are missing, only the size tests run.
+	find_program(_host_cc NAMES cc gcc)
+	find_package(Python3 COMPONENTS Interpreter)
+	if(_host_cc AND Python3_FOUND)
+		set(PB_DEVICE ${CMAKE_BINARY_DIR}/pureboot_device)
 		execute_process(
-		    COMMAND ${_host_cxx} -std=c++23 -Wall -Wextra -O2
-		            -I/usr/include/simavr -I/usr/include/simavr/parts
-		            -o ${TSB_DEVICE} ${CMAKE_CURRENT_SOURCE_DIR}/test/device.cpp
-		            -lsimavr -lsimavrparts -lelf
-		    RESULT_VARIABLE _dev_res ERROR_VARIABLE _dev_err)
-		if(NOT _dev_res EQUAL 0)
-			# One bounded line of it: this becomes a single argument on a
-			# command line, and the reading has to say what stopped the build
-			# rather than that something did.
-			string(REGEX REPLACE "[\r\n\t]+" " " _dev_err "${_dev_err}")
-			string(REPLACE ";" "," _dev_err "${_dev_err}")
-			string(LENGTH "${_dev_err}" _dev_len)
-			if(_dev_len GREATER 240)
-				string(SUBSTRING "${_dev_err}" 0 240 _dev_err)
-			endif()
-			set(_tsb_absent "test/device.cpp does not build here: ${_dev_err}")
+		    COMMAND ${_host_cc} -O2 -I/usr/include/simavr -I/usr/include/simavr/parts
+		            -o ${PB_DEVICE} ${CMAKE_CURRENT_SOURCE_DIR}/test/pureboot_device.c
+		            -lsimavr -lsimavrparts -lelf -lutil
+		    RESULT_VARIABLE _pbdev_res ERROR_VARIABLE _pbdev_err)
+		if(NOT _pbdev_res EQUAL 0)
+			message(STATUS "pureboot_device not built (${_pbdev_err}) — protocol tests skipped")
+			unset(PB_DEVICE)
+		endif()
+		if(LIBAVR_MCU STREQUAL "atmega328p")
+			set(TSB_DEVICE ${CMAKE_BINARY_DIR}/tsb_device)
+			execute_process(
+			    COMMAND ${_host_cc} -O2 -I/usr/include/simavr -I/usr/include/simavr/parts
+			            -o ${TSB_DEVICE} ${CMAKE_CURRENT_SOURCE_DIR}/test/device.c
+			            -lsimavr -lsimavrparts -lelf
+			    RESULT_VARIABLE _dev_res ERROR_VARIABLE _dev_err)
+			if(NOT _dev_res EQUAL 0)
+				message(STATUS "tsb_device not built (${_dev_err}) — protocol tests skipped")
+				unset(TSB_DEVICE)
+			endif()
 		endif()
-	endif()
-	libavr_launcher(_tsb_python "${_tsb_absent}" ${Python3_EXECUTABLE})
-	if(_tsb_absent)
-		message(STATUS "the protocol tests skip here - ${_tsb_absent}")
 	endif()
 endif()
 
-# The ELF is only a container (symbols, section headers) and is never flashed -
+# The ELF is only a container (symbols, section headers) and is never flashed —
 # and the host tool's load_image() dispatches on extension, so handing it one
 # would silently program the header bytes. Every loader image therefore gets
 # both flashable forms beside it at link time: .hex for avrdude, and .bin for
 # the host tool's raw path (which is what the reloc and update tests convert to
-# on the fly). .eeprom is dropped - EEPROM content is its own update.
+# on the fly). .eeprom is dropped — EEPROM content is its own update.
 function(add_image_outputs name)
 	add_custom_command(TARGET ${name} POST_BUILD
 	                   COMMAND ${CMAKE_OBJCOPY} -O ihex -R .eeprom
@@ -82,39 +65,35 @@ function(add_image_outputs name)
 	                           $<TARGET_FILE:${name}> $<TARGET_FILE:${name}>.bin)
 endfunction()
 
-# The TinySafeBoot protocol reimplemented on libavr in variants that trade
+# The TinySafeBoot protocol reimplemented on libavr in three variants that trade
 # clarity for size. Each links into the ATmega328P boot section (BOOTSZ selects
-# its size; BOOTRST vectors a reset to its base) with -nostartfiles - a polled
-# loader has no use for the crt or the vector table. The entry sits in
-# .vectors, laid first, and runs - avr::startup::entry on the policy tier,
-# the experiment tiers' own naked stubs elsewhere, each documented in its
-# source. The boot base is FLASHEND+1 minus the section size; the linker
-# section-start and the source's boot_bytes agree. tsb_app is
+# its size; BOOTRST vectors a reset to its base) with -nostartfiles — a polled
+# loader has no use for the crt or the vector table. The naked entry sits in
+# .vectors, laid first, and runs. The boot base is FLASHEND+1 minus the section
+# size; the linker section-start and the source's boot_bytes agree. tsb_app is
 # the application's reset vector, pinned to 0 here so the loaders jump to a
 # named function; --pmem-wrap-around lets relaxation turn that absolute jump
 # into the wrapped rjmp AVR's modulo-flash PC actually executes.
-# All four implement the full oracle feature set (see oracle/README.md):
+# All three implement the full oracle feature set (see oracle/README.md):
 # watchdog bail, one-wire half-duplex, config-page activation timeout, password
 # gate, emergency erase, config/flash/EEPROM read-write. They differ only in how,
-# and the size gradient is the cost of that "how".
-#   tsb_asm    - the tricks tier's C++ with exactly two routines in asm: the
-#                 bounded rx and the page-store loop, the two whose remaining
-#                 cost is the C ABI itself. Everything else, bring-up to
-#                 dispatch, is C++ on libavr.
-#   tsb_tricks - no asm at all: the whole-loader register allocation lives in
+# and the size gradient is the cost of that "how" — see dev/lessons.md.
+#   tsb_asm   — the tricks tier's C++ with exactly two routines in asm (the
+#                 bounded rx and the page-store loop — the two whose remaining
+#                 cost is the C ABI itself): 510 B in the 512 B section the
+#                 hand-written 500 B oracle occupies. Everything else, from
+#                 bring-up to dispatch, is C++ on libavr.
+#   tsb_tricks — no asm at all: the whole-loader register allocation lives in
 #                 global register variables (Y walks the page pointer), every
 #                 helper is a tiny noinline primitive placed by the
 #                 global-register store rules, pages stream straight to
-#                 SPM/EEPROM.
-#   tsb_pure   - pure idiomatic libavr, one function per command, TU-local
-#                 (internal linkage), streaming (no SRAM page buffer).
-#   tsb_policy - the policy floor: no inline assembly and no global register
-#                 variables, which is philosophy #5's own bound, and the
-#                 measured evidence that the 512 B fit is a property of the
-#                 mechanisms it bans.
-#
-# What each measures is oracle/README.md's table, which is the one place the
-# four numbers and the hand-written loader's own are compared.
+#                 SPM/EEPROM, and the bring-up is the two reset-non-default
+#                 registers only. 526 B in the 1 KB section (BOOTSZ=10) — 14
+#                 over the oracle's section, from 168 over at this tier's first
+#                 floor.
+#   tsb_pure  — pure idiomatic libavr, one function per command, TU-local
+#                 (internal linkage), streaming (no SRAM page buffer): 836 B in
+#                 the 1 KB section.
 #
 # add_tsb_variant(<name> <boot-section-bytes>)
 function(add_tsb_variant name bytes)
@@ -130,28 +109,194 @@ function(add_tsb_variant name bytes)
 		add_test(NAME ${name}.size
 		         COMMAND ${CMAKE_COMMAND} -DSIZE_TOOL=${CMAKE_SIZE} -DELF=$<TARGET_FILE:${name}>
 		                 -DLIMIT=${bytes} -P ${CMAKE_CURRENT_SOURCE_DIR}/test/check_size.cmake)
-		add_test(NAME ${name}.protocol
-		         COMMAND ${_tsb_python} ${CMAKE_CURRENT_SOURCE_DIR}/test/tsbtest.py
-		                 ${TSB_DEVICE} $<TARGET_FILE:${name}> ${base_hex})
+		if(DEFINED TSB_DEVICE)
+			add_test(NAME ${name}.protocol
+			         COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/test/tsbtest.py
+			                 ${TSB_DEVICE} $<TARGET_FILE:${name}> ${base_hex})
+		endif()
 	endif()
 endfunction()
 
-# The tiers reimplement the ATmega328P-only reference protocol, so the guard is
-# the whole of what this repo builds.
+# The tsb tiers reimplement the ATmega328P-only reference protocol; the other
+# chips build pureboot alone.
 if(LIBAVR_MCU STREQUAL "atmega328p")
 	add_tsb_variant(tsb_asm 512)
-	add_tsb_variant(tsb_policy 1024)
 	add_tsb_variant(tsb_pure 1024)
 	add_tsb_variant(tsb_tricks 1024)
-	# The policy tier's floor needs these two: a loader's loop bodies all
-	# contain calls, which is what makes hoisting an invariant out of one cost
-	# more than it saves. The other tiers keep the flag set their recorded
-	# floors were measured with - none.
-	target_compile_options(tsb_policy PRIVATE -fno-move-loop-invariants -fno-tree-ter)
 endif()
 
-# Every test registered above carries the marker a stubbed launcher prints, so
-# a check this host cannot run reads as Skipped rather than Failed.
+# pureboot — the pure-constraint port (see pureboot/README.md): one source,
+# no inline assembly, no global register variables, every libavr chip,
+# fitting each chip's smallest boot sector. The geometry and the
+# pureboot_add_loader() deployment function live in pureboot/CMakeLists.txt —
+# the unit a downstream project consumes; everything below is this port's
+# own build: the stock loaders, their tests, and the size matrix. The
+# distinct binary dir keeps the `pureboot` target's output name free.
+add_subdirectory(pureboot pureboot-cmake)
+
+# The stock loader: the family-default deployment (crystal/RC clock, the
+# chip's natural link, default pins). The activation window stays a cache
+# variable — re-timing a deployed loader is a self-update with a re-timed
+# build. pureboot9 is that re-timed build, and what the update test installs.
+set(PUREBOOT_TIMEOUT 8 CACHE STRING "pureboot activation window, seconds")
+pureboot_add_loader(pureboot TIMEOUT ${PUREBOOT_TIMEOUT})
 if(PROJECT_IS_TOP_LEVEL)
-	libavr_skip_unverified()
+	get_target_property(_pb_stock_hz pureboot PUREBOOT_HZ)
+	get_target_property(_pb_stock_baud pureboot PUREBOOT_BAUD)
+
+	add_test(NAME pureboot.size
+	         COMMAND ${CMAKE_COMMAND} -DSIZE_TOOL=${CMAKE_SIZE} -DELF=$<TARGET_FILE:pureboot>
+	                 -DLIMIT=${PUREBOOT_LIMIT} -P ${CMAKE_CURRENT_SOURCE_DIR}/test/check_size.cmake)
+	if(Python3_FOUND)
+		add_test(NAME pureboot.pi
+		         COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/test/check_pi.py
+		                 ${CMAKE_OBJDUMP} ${CMAKE_NM} $<TARGET_FILE:pureboot> ${PUREBOOT_BASE_HEX})
+		add_test(NAME pureboot.planner
+		         COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/test/test_planner.py
+		                 ${CMAKE_CURRENT_SOURCE_DIR}/pureboot/pureboot.py)
+	endif()
+
+	# The protocol test flashes this fixture through the loader with the real
+	# host tool and expects its banner after the hand-over; a normally linked
+	# application whose reset vector is what the tinies' surgery re-homes.
+	if(DEFINED PB_DEVICE)
+		add_executable(pbapp test/pbapp.cpp)
+		target_link_libraries(pbapp PRIVATE libavr)
+		add_custom_command(TARGET pbapp POST_BUILD
+		                   COMMAND ${CMAKE_OBJCOPY} -O binary $<TARGET_FILE:pbapp> $<TARGET_FILE:pbapp>.bin)
+		add_test(NAME pureboot.protocol
+		         COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/test/pbtest.py
+		                 ${PB_DEVICE} $<TARGET_FILE:pureboot> ${PUREBOOT_SIM_MCU} ${_pb_stock_hz}
+		                 ${PUREBOOT_BASE_HEX} ${PUREBOOT_PAGE} ${_pb_stock_baud} ${PUREBOOT_EEPROM}
+		                 $<TARGET_FILE:pbapp>.bin ${CMAKE_CURRENT_SOURCE_DIR}/pureboot/pureboot.py
+		                 ${CMAKE_BINARY_DIR}/pbtest-work)
+		set_tests_properties(pureboot.protocol PROPERTIES TIMEOUT 180)
+
+		# The position-independence acceptance test: the identical image,
+		# installed one slot lower, must serve the full command set.
+		add_test(NAME pureboot.reloc
+		         COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/test/pbreloc.py
+		                 ${PB_DEVICE} $<TARGET_FILE:pureboot> ${PUREBOOT_SIM_MCU} ${_pb_stock_hz}
+		                 ${PUREBOOT_BASE_HEX} ${PUREBOOT_PAGE} ${_pb_stock_baud}
+		                 ${CMAKE_CURRENT_SOURCE_DIR}/pureboot/pureboot.py
+		                 ${CMAKE_BINARY_DIR}/pbreloc-work)
+		set_tests_properties(pureboot.reloc PROPERTIES TIMEOUT 180
+		                     ENVIRONMENT "PB_OBJCOPY=${CMAKE_OBJCOPY}")
+
+		# Re-homing: a loader mistakenly programmed at address 0 (a raw .bin
+		# handed to a programmer) or sitting in the staging slot must heal
+		# into the canonical slot through the ordinary --update-loader flow.
+		# Patched-vector behavior, so one representative chip carries it.
+		if(LIBAVR_MCU STREQUAL "attiny85")
+			add_test(NAME pureboot.rehome
+			         COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/test/pbrehome.py
+			                 ${PB_DEVICE} $<TARGET_FILE:pureboot> $<TARGET_FILE:pureboot9>.bin
+			                 ${PUREBOOT_SIM_MCU} ${_pb_stock_hz} ${PUREBOOT_BASE_HEX} ${PUREBOOT_PAGE}
+			                 ${_pb_stock_baud} $<TARGET_FILE:pbapp>.bin
+			                 ${CMAKE_CURRENT_SOURCE_DIR}/pureboot/pureboot.py
+			                 ${CMAKE_BINARY_DIR}/pbrehome-work)
+			set_tests_properties(pureboot.rehome PROPERTIES TIMEOUT 180)
+		endif()
+
+		# The self-update end-to-end: the re-timed build (same source, only
+		# the timeout differs — a byte-different image) replaces the resident
+		# through --update-loader, with every power-fail phase rehearsed from
+		# the runner's flash dumps.
+		pureboot_add_loader(pureboot9 TIMEOUT 9)
+		add_test(NAME pureboot.update
+		         COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/test/pbupdate.py
+		                 ${PB_DEVICE} $<TARGET_FILE:pureboot> $<TARGET_FILE:pureboot9>
+		                 ${PUREBOOT_SIM_MCU} ${_pb_stock_hz} ${PUREBOOT_BASE_HEX} ${PUREBOOT_PAGE}
+		                 ${_pb_stock_baud} $<TARGET_FILE:pbapp>.bin
+		                 ${CMAKE_CURRENT_SOURCE_DIR}/pureboot/pureboot.py
+		                 ${CMAKE_BINARY_DIR}/pbupdate-work)
+		set_tests_properties(pureboot.update PROPERTIES TIMEOUT 600
+		                     ENVIRONMENT "PB_OBJCOPY=${CMAKE_OBJCOPY}")
+	endif()
+
+	# The size matrix: every configuration axis that could move the image
+	# size — the serial backend (different code), the clock and its ladder
+	# baud (different constants and divisor shapes), the USART instance
+	# (different register class) — each combination must still fit the
+	# chip's slot budget. Pins are size-neutral (port and bit are immediate
+	# operands) and the timeout is a constant, so neither adds an axis. The
+	# stock build is one point of this matrix and already has its test.
+	function(pureboot_size_variant name)
+		pureboot_add_loader(${name} ${ARGN})
+		add_test(NAME ${name}.size
+		         COMMAND ${CMAKE_COMMAND} -DSIZE_TOOL=${CMAKE_SIZE} -DELF=$<TARGET_FILE:${name}>
+		                 -DLIMIT=${PUREBOOT_LIMIT} -P ${CMAKE_CURRENT_SOURCE_DIR}/test/check_size.cmake)
+	endfunction()
+
+	# Clock points: the shipped-fuse floor (CKDIV8), the calibrated RC, and
+	# the crystal the stock build assumes (the tiny13's ladder is its own RC
+	# menu — it has no crystal option).
+	if(LIBAVR_MCU MATCHES "^attiny13")
+		set(_matrix_clocks 1200000 4800000 9600000)
+	else()
+		set(_matrix_clocks 1000000 8000000 16000000)
+	endif()
+	foreach(_matrix_hz IN LISTS _matrix_clocks)
+		math(EXPR _matrix_khz "${_matrix_hz} / 1000")
+		if(PUREBOOT_HAS_USART OR NOT _matrix_hz EQUAL _pb_stock_hz)
+			pureboot_size_variant(pureboot_sw_${_matrix_khz}k CLOCK ${_matrix_hz} SERIAL software)
+		endif()
+		if(PUREBOOT_HAS_USART AND NOT _matrix_hz EQUAL _pb_stock_hz)
+			pureboot_size_variant(pureboot_hw_${_matrix_khz}k CLOCK ${_matrix_hz} SERIAL hardware)
+		endif()
+	endforeach()
+	if(PUREBOOT_HAS_USART1)
+		pureboot_size_variant(pureboot_usart1 USART 1)
+	endif()
+
+	# One configured deployment end to end — a real board's shape rather
+	# than the stock assumption: the ATmega328P on its shipped 1 MHz fuses,
+	# the software UART on hand-picked pins (TX = PB1, RX = PB5), the ladder
+	# baud (9600). The full protocol suite runs against it, fixture
+	# application included, over the runner's GPIO bridge — proving the
+	# configuration plumbing produces a working loader, not just one that
+	# fits.
+	if(LIBAVR_MCU STREQUAL "atmega328p" AND DEFINED PB_DEVICE)
+		pureboot_size_variant(pureboot_custom CLOCK 1000000 SERIAL software RX pb5 TX pb1)
+		get_target_property(_custom_hz pureboot_custom PUREBOOT_HZ)
+		get_target_property(_custom_baud pureboot_custom PUREBOOT_BAUD)
+		get_target_property(_custom_link pureboot_custom PUREBOOT_LINK)
+		add_executable(pbapp_custom test/pbapp.cpp)
+		target_link_libraries(pbapp_custom PRIVATE libavr)
+		target_compile_definitions(pbapp_custom PRIVATE PUREBOOT_CLOCK_HZ=${_custom_hz}
+		                           PUREBOOT_BAUD=${_custom_baud} PUREBOOT_SOFT_SERIAL PUREBOOT_TX=pb1)
+		add_custom_command(TARGET pbapp_custom POST_BUILD
+		                   COMMAND ${CMAKE_OBJCOPY} -O binary
+		                           $<TARGET_FILE:pbapp_custom> $<TARGET_FILE:pbapp_custom>.bin)
+		add_test(NAME pureboot.custom
+		         COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/test/pbtest.py
+		                 ${PB_DEVICE} $<TARGET_FILE:pureboot_custom> ${PUREBOOT_SIM_MCU} ${_custom_hz}
+		                 ${PUREBOOT_BASE_HEX} ${PUREBOOT_PAGE} ${_custom_baud} ${PUREBOOT_EEPROM}
+		                 $<TARGET_FILE:pbapp_custom>.bin ${CMAKE_CURRENT_SOURCE_DIR}/pureboot/pureboot.py
+		                 ${CMAKE_BINARY_DIR}/pbcustom-work ${_custom_link})
+		set_tests_properties(pureboot.custom PROPERTIES TIMEOUT 180)
+	endif()
+
+	# The second USART, driven for real on one chip: instance selection is
+	# compile-checked everywhere, but only a live session proves the loader
+	# initialized and polls the USART it claims to. The fixture application
+	# banners on the same instance.
+	if(LIBAVR_MCU STREQUAL "atmega644a" AND DEFINED PB_DEVICE)
+		get_target_property(_usart1_hz pureboot_usart1 PUREBOOT_HZ)
+		get_target_property(_usart1_baud pureboot_usart1 PUREBOOT_BAUD)
+		add_executable(pbapp_usart1 test/pbapp.cpp)
+		target_link_libraries(pbapp_usart1 PRIVATE libavr)
+		target_compile_definitions(pbapp_usart1 PRIVATE PUREBOOT_CLOCK_HZ=${_usart1_hz}
+		                           PUREBOOT_BAUD=${_usart1_baud} PUREBOOT_USART=1)
+		add_custom_command(TARGET pbapp_usart1 POST_BUILD
+		                   COMMAND ${CMAKE_OBJCOPY} -O binary
+		                           $<TARGET_FILE:pbapp_usart1> $<TARGET_FILE:pbapp_usart1>.bin)
+		add_test(NAME pureboot.usart1
+		         COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/test/pbtest.py
+		                 ${PB_DEVICE} $<TARGET_FILE:pureboot_usart1> ${PUREBOOT_SIM_MCU} ${_usart1_hz}
+		                 ${PUREBOOT_BASE_HEX} ${PUREBOOT_PAGE} ${_usart1_baud} ${PUREBOOT_EEPROM}
+		                 $<TARGET_FILE:pbapp_usart1>.bin ${CMAKE_CURRENT_SOURCE_DIR}/pureboot/pureboot.py
+		                 ${CMAKE_BINARY_DIR}/pbusart1-work usart1)
+		set_tests_properties(pureboot.usart1 PROPERTIES TIMEOUT 180)
+	endif()
 endif()

ide/README.md

@@ -1,67 +0,0 @@
-# Atmel Studio
-
-`master` carries `bootloader.atsln`, so this branch does too: `ide/bootloader.atsln`
-builds the loader from the same source Ninja does, to a **byte-identical
-`.text`** — the `tsb_asm` tier in its 512-byte section (`check-flags.py` below
-is what holds the flag sets equal, so the size is Ninja's own). CMake remains
-the build system; the solution is here so the port opens in Studio as its
-predecessor did.
-
-## One project, of four tiers
-
-A `.cppproj` is one binary at one set of flags. `tsb_asm` is the tier that
-occupies the same 512-byte section `master`'s `tsb` project targeted, which is
-the one worth opening in Studio.
-
-The other three tiers (`tsb_pure`, `tsb_tricks`, `tsb_policy`) are not here.
-They differ from `tsb_asm` in their source file, their section size, and — for
-`tsb_policy` — two loop flags; nothing about that is a Studio concern, and what
-they exist to demonstrate is a size gradient only the CMake size tests measure.
-Adding one is a copy of `tsb_asm/tsb_asm.cppproj` in its own directory, with its
-name, its GUID, its source path and its `--section-start` changed (`0x7c00` for
-the 1 KiB tiers), plus four lines in the solution.
-
-`avrdevice` is a project property, so each project gets its own directory:
-Studio builds into `<project dir>/<Configuration>` whatever `OutputDirectory`
-says, and two projects sharing a directory would share one object file.
-
-## Debug keeps `-Os`
-
-Both configurations compile at `-Os`; Debug adds only `-gdwarf-4`. The `.text`
-is therefore identical in both, which is the point — a loader's section is a
-**correctness** bound and not a budget. A debug configuration that silently
-overruns the section is worse than none, and DWARF costs no flash, so the
-optimisation level stays where correctness needs it.
-
-## What Studio needs from the machine
-
-libavr from the **submodule**, found at
-`$(MSBuildProjectDirectory)\..\..\libavr\include` — correct by construction, and
-anchored to the project because a plain relative path resolves against the
-generated makefile's directory (the configuration's output directory), not the
-project's. There is no `LIBAVR_ROOT` escape hatch: a variable exported in a
-shell is invisible to Studio launched from the Start menu, and the failure reads
-as a missing `libavr/libavr.hpp` — which is what the submodule answers.
-
-A GCC 16.1 toolchain registered as flavour `avr-g++-16.1.0`, nothing older
-reaching `-std=c++26`.
-
-## Generating and gating
-
-One generated file is required before the project will load at all, and one
-command checks the flags have not drifted (both from libavr's
-`tools/atmelstudio/`):
-
-```sh
-python libavr/tools/atmelstudio/componentinfo.py \
-    ide/tsb_asm/tsb_asm.componentinfo.xml --device ATmega328P
-python libavr/tools/atmelstudio/check-flags.py \
-    --solution ide/bootloader.atsln --project tsb_asm --target tsb_asm \
-    --compile-commands build/atmega328p-generated/compile_commands.json \
-    --log build/as-tsb_asm.log
-```
-
-Release is what the gate compares — the presets define no debug build, and
-Debug differs from Release only in `-gdwarf-4`.
-
-Legacy (the yazoalfa-era submodules) stays on `master`.

ide/bootloader.atsln

@@ -1,22 +0,0 @@
-
-Microsoft Visual Studio Solution File, Format Version 12.00
-# Atmel Studio Solution File, Format Version 11.00
-VisualStudioVersion = 14.0.23107.0
-MinimumVisualStudioVersion = 10.0.40219.1
-Project("{E66E83B9-2572-4076-B26E-6BE79FF3018A}") = "tsb_asm", "tsb_asm\tsb_asm.cppproj", "{6618D3BE-7EB3-49A2-9113-F128E396FF06}"
-EndProject
-Global
-	GlobalSection(SolutionConfigurationPlatforms) = preSolution
-		Debug|AVR = Debug|AVR
-		Release|AVR = Release|AVR
-	EndGlobalSection
-	GlobalSection(ProjectConfigurationPlatforms) = postSolution
-		{6618D3BE-7EB3-49A2-9113-F128E396FF06}.Debug|AVR.ActiveCfg = Debug|AVR
-		{6618D3BE-7EB3-49A2-9113-F128E396FF06}.Debug|AVR.Build.0 = Debug|AVR
-		{6618D3BE-7EB3-49A2-9113-F128E396FF06}.Release|AVR.ActiveCfg = Release|AVR
-		{6618D3BE-7EB3-49A2-9113-F128E396FF06}.Release|AVR.Build.0 = Release|AVR
-	EndGlobalSection
-	GlobalSection(SolutionProperties) = preSolution
-		HideSolutionNode = FALSE
-	EndGlobalSection
-EndGlobal

ide/tsb_asm/tsb_asm.cppproj

@@ -1,112 +0,0 @@
-<?xml version="1.0" encoding="utf-8"?>
-<Project DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003" ToolsVersion="14.0">
-  <PropertyGroup>
-    <SchemaVersion>2.0</SchemaVersion>
-    <ProjectVersion>7.0</ProjectVersion>
-    <ToolchainName>com.Atmel.AVRGCC8.CPP</ToolchainName>
-    <ProjectGuid>6618d3be-7eb3-49a2-9113-f128e396ff06</ProjectGuid>
-    <avrdevice>ATmega328P</avrdevice>
-    <avrdeviceseries>none</avrdeviceseries>
-    <OutputType>Executable</OutputType>
-    <Language>CPP</Language>
-    <OutputFileName>$(MSBuildProjectName)</OutputFileName>
-    <OutputFileExtension>.elf</OutputFileExtension>
-    <OutputDirectory>$(MSBuildProjectDirectory)\$(Configuration)</OutputDirectory>
-    <AssemblyName>tsb_asm</AssemblyName>
-    <Name>tsb_asm</Name>
-    <RootNamespace>tsb_asm</RootNamespace>
-    <ToolchainFlavour>avr-g++-16.1.0</ToolchainFlavour>
-    <KeepTimersRunning>true</KeepTimersRunning>
-    <OverrideVtor>false</OverrideVtor>
-    <CacheFlash>true</CacheFlash>
-    <ProgFlashFromRam>true</ProgFlashFromRam>
-    <RamSnippetAddress>0x20000000</RamSnippetAddress>
-    <UncachedRange />
-    <preserveEEPROM>true</preserveEEPROM>
-    <OverrideVtorValue>exception_table</OverrideVtorValue>
-    <BootSegment>2</BootSegment>
-    <ResetRule>0</ResetRule>
-    <eraseonlaunchrule>0</eraseonlaunchrule>
-    <EraseKey />
-    <AsfFrameworkConfig>
-      <framework-data xmlns="">
-  <options />
-  <configurations />
-  <files />
-  <documentation help="" />
-  <offline-documentation help="" />
-  <dependencies>
-    <content-extension eid="atmel.asf" uuidref="Atmel.ASF" version="3.52.0" />
-  </dependencies>
-</framework-data>
-    </AsfFrameworkConfig>
-  </PropertyGroup>
-  <PropertyGroup Condition=" '$(Configuration)' == 'Release' ">
-    <ToolchainSettings>
-      <AvrGccCpp>
-        <avrgcc.common.Device>-mmcu=atmega328p</avrgcc.common.Device>
-        <avrgcc.common.outputfiles.hex>True</avrgcc.common.outputfiles.hex>
-        <avrgcc.common.outputfiles.lss>True</avrgcc.common.outputfiles.lss>
-        <avrgcc.common.outputfiles.eep>True</avrgcc.common.outputfiles.eep>
-        <avrgcc.common.outputfiles.srec>True</avrgcc.common.outputfiles.srec>
-        <avrgcc.common.outputfiles.usersignatures>False</avrgcc.common.outputfiles.usersignatures>
-        <avrgcccpp.compiler.symbols.DefSymbols>
-          <ListValues>
-            <Value>NDEBUG</Value>
-          </ListValues>
-        </avrgcccpp.compiler.symbols.DefSymbols>
-        <avrgcccpp.compiler.directories.IncludePaths>
-          <ListValues>
-            <Value>$(MSBuildProjectDirectory)\..\..\libavr\include</Value>
-          </ListValues>
-        </avrgcccpp.compiler.directories.IncludePaths>
-        <avrgcccpp.compiler.optimization.level>Optimize for size (-Os)</avrgcccpp.compiler.optimization.level>
-        <avrgcccpp.compiler.optimization.PrepareFunctionsForGarbageCollection>True</avrgcccpp.compiler.optimization.PrepareFunctionsForGarbageCollection>
-        <avrgcccpp.compiler.optimization.PrepareDataForGarbageCollection>True</avrgcccpp.compiler.optimization.PrepareDataForGarbageCollection>
-        <avrgcccpp.compiler.warnings.AllWarnings>True</avrgcccpp.compiler.warnings.AllWarnings>
-        <avrgcccpp.compiler.miscellaneous.OtherFlags>-std=c++26 -Wextra -Werror -mrelax -fno-exceptions -fno-rtti -fno-threadsafe-statics</avrgcccpp.compiler.miscellaneous.OtherFlags>
-        <avrgcccpp.linker.optimization.GarbageCollectUnusedSections>True</avrgcccpp.linker.optimization.GarbageCollectUnusedSections>
-        <avrgcccpp.linker.miscellaneous.LinkerFlags>-mrelax -nostartfiles -Wl,--section-start=.text=0x7e00 -Wl,--defsym=tsb_app=0 -Wl,--pmem-wrap-around=32k</avrgcccpp.linker.miscellaneous.LinkerFlags>
-      </AvrGccCpp>
-    </ToolchainSettings>
-  </PropertyGroup>
-  <PropertyGroup Condition=" '$(Configuration)' == 'Debug' ">
-    <ToolchainSettings>
-      <AvrGccCpp>
-        <avrgcc.common.Device>-mmcu=atmega328p</avrgcc.common.Device>
-        <avrgcc.common.outputfiles.hex>True</avrgcc.common.outputfiles.hex>
-        <avrgcc.common.outputfiles.lss>True</avrgcc.common.outputfiles.lss>
-        <avrgcc.common.outputfiles.eep>True</avrgcc.common.outputfiles.eep>
-        <avrgcc.common.outputfiles.srec>True</avrgcc.common.outputfiles.srec>
-        <avrgcc.common.outputfiles.usersignatures>False</avrgcc.common.outputfiles.usersignatures>
-        <avrgcccpp.compiler.symbols.DefSymbols>
-          <ListValues>
-            <Value>DEBUG</Value>
-          </ListValues>
-        </avrgcccpp.compiler.symbols.DefSymbols>
-        <avrgcccpp.compiler.directories.IncludePaths>
-          <ListValues>
-            <Value>$(MSBuildProjectDirectory)\..\..\libavr\include</Value>
-          </ListValues>
-        </avrgcccpp.compiler.directories.IncludePaths>
-        <avrgcccpp.compiler.optimization.level>Optimize for size (-Os)</avrgcccpp.compiler.optimization.level>
-        <avrgcccpp.compiler.optimization.PrepareFunctionsForGarbageCollection>True</avrgcccpp.compiler.optimization.PrepareFunctionsForGarbageCollection>
-        <avrgcccpp.compiler.optimization.PrepareDataForGarbageCollection>True</avrgcccpp.compiler.optimization.PrepareDataForGarbageCollection>
-        <avrgcccpp.compiler.warnings.AllWarnings>True</avrgcccpp.compiler.warnings.AllWarnings>
-        <avrgcccpp.compiler.miscellaneous.OtherFlags>-std=c++26 -Wextra -Werror -mrelax -fno-exceptions -fno-rtti -fno-threadsafe-statics -gdwarf-4</avrgcccpp.compiler.miscellaneous.OtherFlags>
-        <avrgcccpp.linker.optimization.GarbageCollectUnusedSections>True</avrgcccpp.linker.optimization.GarbageCollectUnusedSections>
-        <avrgcccpp.linker.miscellaneous.LinkerFlags>-mrelax -nostartfiles -Wl,--section-start=.text=0x7e00 -Wl,--defsym=tsb_app=0 -Wl,--pmem-wrap-around=32k</avrgcccpp.linker.miscellaneous.LinkerFlags>
-      </AvrGccCpp>
-    </ToolchainSettings>
-  </PropertyGroup>
-  <ItemGroup>
-    <Compile Include="..\..\tsb\tsb_asm.cpp">
-      <SubType>compile</SubType>
-      <Link>tsb\tsb_asm.cpp</Link>
-    </Compile>
-  </ItemGroup>
-  <ItemGroup>
-    <Folder Include="tsb" />
-  </ItemGroup>
-  <Import Project="$(AVRSTUDIO_EXE_PATH)\Vs\Compiler.targets" />
-</Project>

oracle/README.md

@@ -38,23 +38,11 @@ avra -I /usr/share/avra tsb-fixedbaud.asm   # after uncommenting .include "m328P
 ```
 
 **500 bytes with every feature** — the proof that ≤512 B and full feature parity
-are simultaneously reachable. The port's four tiers reach it from the other
-side, and the gradient between them is the cost of the mechanisms each is
-allowed:
-
-| tier | bytes | section | what it is allowed |
-|---|---|---|---|
-| oracle | 500 | 512 B | hand-written assembly, the reference |
-| `tsb_asm` | 512 | 512 B | C++ on libavr, two routines in asm |
-| `tsb_tricks` | 528 | 1 KB | no asm; global register variables |
-| `tsb_policy` | 630 | 1 KB | pureboot's rules: no asm, no register variables |
-| `tsb_pure` | 776 | 1 KB | idiomatic libavr throughout |
-
-The two routines `tsb_asm` keeps are the ones whose remaining cost is the
-calling convention itself: the bounded rx and the page-store loop. It fills
-its section exactly, with the same one-bit-time turn-around guard the oracle
-spends six bytes on - every tier implements the whole feature set, which is
-what makes the column a gradient rather than four different loaders.
+are simultaneously reachable. The port's `tsb_asm` tier meets the same bar at
+510 B in the same 512 B section, written in C++ on libavr except the two
+routines whose remaining cost is the calling convention itself (the bounded rx
+and the page-store loop); `tsb_tricks` needs no assembly at all at 526 B, and
+`tsb_pure` stays fully idiomatic at 836 B, both in the 1 KB section.
 
 The oracle targets 20 MHz / 33333 baud; the port targets 16 MHz / 115200 baud
 (what the simavr protocol test drives). Baud and geometry differ, code size and

pureboot/CMakeLists.txt

@@ -0,0 +1,310 @@
+# pureboot as a consumable CMake unit: the per-chip geometry, the default
+# baud ladder, and pureboot_add_loader() — the one way a loader target is
+# created, both by this port's own build and by a downstream project. A
+# downstream project brings its usual libavr setup (the `libavr` target and
+# the LIBAVR_MCU toolchain preset), adds this directory, and states its
+# deployment:
+#
+#   add_subdirectory(bootloader/pureboot)
+#   pureboot_add_loader(myboot CLOCK 1000000 SERIAL software TX pb1 RX pb5)
+#
+# Every argument is optional — CLOCK defaults to the family assumption
+# below, BAUD to the fastest standard rate the clock reaches within 2.5 %
+# (the ladder), SERIAL to the chip's hardware USART where it has one
+# (`hardware`/`software` force a backend, USART 1 picks the second
+# instance), RX/TX to pb0/pb1 for the software UART, TIMEOUT to 8 s.
+# Infeasible picks fail the build by name: libavr's baud-error and
+# software-UART cycle-floor static asserts re-check whatever is passed.
+
+# Per-family geometry: flash/page/EEPROM sizes and the linker wrap the PC
+# modulo needs, the loader slot (each chip's smallest boot sector — 1 KiB on
+# the word-addressed 1284s), and the deployment defaults (crystal assumption
+# on the megas, calibrated RC on the tinies). The USART flags mirror the
+# hardware inventory the loader's own static asserts check (the plain 644 is
+# the x4 family's one single-USART die, Atmel-2593).
+set(_pb_has_usart 1)
+set(_pb_has_usart1 0)
+if(LIBAVR_MCU MATCHES "^attiny13a?$")
+	set(_pb_flash 1024)
+	set(_pb_wrap "")
+	set(_pb_page 32)
+	set(_pb_hz 9600000)
+	set(_pb_eeprom 64)
+	set(_pb_has_usart 0)
+elseif(LIBAVR_MCU STREQUAL "attiny25")
+	set(_pb_flash 2048)
+	set(_pb_wrap "")
+	set(_pb_page 32)
+	set(_pb_hz 8000000)
+	set(_pb_eeprom 128)
+	set(_pb_has_usart 0)
+elseif(LIBAVR_MCU STREQUAL "attiny45")
+	set(_pb_flash 4096)
+	set(_pb_wrap "")
+	set(_pb_page 64)
+	set(_pb_hz 8000000)
+	set(_pb_eeprom 256)
+	set(_pb_has_usart 0)
+elseif(LIBAVR_MCU STREQUAL "attiny85")
+	set(_pb_flash 8192)
+	set(_pb_wrap -Wl,--pmem-wrap-around=8k)
+	set(_pb_page 64)
+	set(_pb_hz 8000000)
+	set(_pb_eeprom 512)
+	set(_pb_has_usart 0)
+elseif(LIBAVR_MCU MATCHES "^atmega48(a|p|pa)?$")
+	set(_pb_flash 4096)
+	set(_pb_wrap "")
+	set(_pb_page 64)
+	set(_pb_hz 16000000)
+	set(_pb_eeprom 256)
+elseif(LIBAVR_MCU MATCHES "^atmega8a?$" OR LIBAVR_MCU MATCHES "^atmega88(a|p|pa)?$")
+	set(_pb_flash 8192)
+	set(_pb_wrap -Wl,--pmem-wrap-around=8k)
+	set(_pb_page 64)
+	set(_pb_hz 16000000)
+	set(_pb_eeprom 512)
+elseif(LIBAVR_MCU MATCHES "^atmega16a?$" OR LIBAVR_MCU MATCHES "^atmega168(a|p|pa)?$")
+	set(_pb_flash 16384)
+	set(_pb_wrap -Wl,--pmem-wrap-around=16k)
+	set(_pb_page 128)
+	set(_pb_hz 16000000)
+	set(_pb_eeprom 512)
+elseif(LIBAVR_MCU MATCHES "^atmega164(a|p|pa)$")
+	set(_pb_flash 16384)
+	set(_pb_wrap -Wl,--pmem-wrap-around=16k)
+	set(_pb_page 128)
+	set(_pb_hz 16000000)
+	set(_pb_eeprom 512)
+	set(_pb_has_usart1 1)
+elseif(LIBAVR_MCU MATCHES "^atmega32a?$" OR LIBAVR_MCU MATCHES "^atmega328p?$")
+	set(_pb_flash 32768)
+	set(_pb_wrap -Wl,--pmem-wrap-around=32k)
+	set(_pb_page 128)
+	set(_pb_hz 16000000)
+	set(_pb_eeprom 1024)
+elseif(LIBAVR_MCU MATCHES "^atmega324(a|p|pa)$")
+	set(_pb_flash 32768)
+	set(_pb_wrap -Wl,--pmem-wrap-around=32k)
+	set(_pb_page 128)
+	set(_pb_hz 16000000)
+	set(_pb_eeprom 1024)
+	set(_pb_has_usart1 1)
+elseif(LIBAVR_MCU MATCHES "^atmega644(a|p|pa)?$")
+	# 64 KiB is exactly the 16-bit byte space: plain LPM reaches everything,
+	# and the smallest boot section (1 KiB) holds the loader and its staging
+	# slot together (see README.md). The plain 644 is the family's one
+	# single-USART die.
+	set(_pb_flash 65536)
+	set(_pb_wrap -Wl,--pmem-wrap-around=64k)
+	set(_pb_page 256)
+	set(_pb_hz 16000000)
+	set(_pb_eeprom 2048)
+	if(NOT LIBAVR_MCU STREQUAL "atmega644")
+		set(_pb_has_usart1 1)
+	endif()
+elseif(LIBAVR_MCU MATCHES "^atmega1284p?$")
+	# 128 KiB: wire flash addresses are word addresses, reads go through
+	# ELPM, and the PC's modulo wrap exceeds what --pmem-wrap-around models.
+	# The slot is 1 KiB — this chip's own smallest boot sector; the far
+	# machinery cannot fit 512 B (see README.md).
+	set(_pb_flash 131072)
+	set(_pb_wrap "")
+	set(_pb_page 256)
+	set(_pb_hz 16000000)
+	set(_pb_eeprom 4096)
+	set(_pb_slot 1024)
+	set(_pb_limit 1024)
+	set(_pb_has_usart1 1)
+else()
+	message(FATAL_ERROR "pureboot: no geometry for ${LIBAVR_MCU}")
+endif()
+if(NOT DEFINED _pb_slot)
+	set(_pb_slot 512)
+endif()
+math(EXPR _pb_base "${_pb_flash} - ${_pb_slot}")
+math(EXPR _pb_base_hex "${_pb_base}" OUTPUT_FORMAT HEXADECIMAL)
+# Patched-vector chips hand over through the trampoline word below the slot,
+# which is also the slot's own last word — their budget is slot − 2.
+if(LIBAVR_MCU MATCHES "^atmega" AND NOT LIBAVR_MCU MATCHES "^atmega48")
+	set(_pb_app 0)
+	if(NOT DEFINED _pb_limit)
+		set(_pb_limit ${_pb_slot})
+	endif()
+else()
+	math(EXPR _pb_app "${_pb_base} - 2")
+	math(EXPR _pb_limit "${_pb_slot} - 2")
+endif()
+
+# simavr names its cores after the base dies; the A revisions run on them
+# (the 644PA on the 644P core).
+set(_pb_sim_mcu ${LIBAVR_MCU})
+if(LIBAVR_MCU MATCHES "^atmega(8|16|32|48|88|164|168|644)a$")
+	string(REGEX REPLACE "a$" "" _pb_sim_mcu ${LIBAVR_MCU})
+elseif(LIBAVR_MCU STREQUAL "atmega644pa")
+	set(_pb_sim_mcu atmega644p)
+endif()
+
+# The function runs in its caller's scope, so everything it needs crosses
+# scopes as global properties.
+set_property(GLOBAL PROPERTY PUREBOOT_BASE_HEX ${_pb_base_hex})
+set_property(GLOBAL PROPERTY PUREBOOT_APP ${_pb_app})
+set_property(GLOBAL PROPERTY PUREBOOT_WRAP "${_pb_wrap}")
+set_property(GLOBAL PROPERTY PUREBOOT_DEFAULT_HZ ${_pb_hz})
+set_property(GLOBAL PROPERTY PUREBOOT_HAS_USART ${_pb_has_usart})
+set_property(GLOBAL PROPERTY PUREBOOT_HAS_USART1 ${_pb_has_usart1})
+
+# The port's own build (tests, the size matrix) reads the geometry from the
+# parent scope; a downstream consumer gets the same variables for free.
+set(PUREBOOT_BASE_HEX ${_pb_base_hex} PARENT_SCOPE)
+set(PUREBOOT_PAGE ${_pb_page} PARENT_SCOPE)
+set(PUREBOOT_SLOT ${_pb_slot} PARENT_SCOPE)
+set(PUREBOOT_LIMIT ${_pb_limit} PARENT_SCOPE)
+set(PUREBOOT_EEPROM ${_pb_eeprom} PARENT_SCOPE)
+set(PUREBOOT_DEFAULT_HZ ${_pb_hz} PARENT_SCOPE)
+set(PUREBOOT_HAS_USART ${_pb_has_usart} PARENT_SCOPE)
+set(PUREBOOT_HAS_USART1 ${_pb_has_usart1} PARENT_SCOPE)
+set(PUREBOOT_SIM_MCU ${_pb_sim_mcu} PARENT_SCOPE)
+
+# The fastest standard rate the clock reaches within 2.5 % — the same
+# best-of-U2X-and-plain divisor search libavr's solve_baud runs, so a
+# default never trips the compile-time error it is checked against. A
+# software build additionally requires the polled receiver's 100-cycles-a-bit
+# floor (its own static assert): at low clocks the U2X divisor still reaches
+# rates the bit-banged sampler cannot, so the backend gates the ladder.
+function(pureboot_default_baud clock software outvar)
+	foreach(baud 115200 57600 38400 19200 9600)
+		math(EXPR _cycles "${clock} / ${baud}")
+		if(software AND _cycles LESS 100)
+			continue()
+		endif()
+		foreach(divisor 8 16)
+			math(EXPR _step "${divisor} * ${baud}")
+			math(EXPR _n "(${clock} + ${_step} / 2) / ${_step}")
+			if(_n LESS 1 OR _n GREATER 4096)
+				continue()
+			endif()
+			math(EXPR _actual "${clock} / (${divisor} * ${_n})")
+			math(EXPR _delta "${_actual} - ${baud}")
+			if(_delta LESS 0)
+				math(EXPR _delta "-(${_delta})")
+			endif()
+			math(EXPR _error_bp "${_delta} * 10000 / ${baud}")
+			if(_error_bp LESS_EQUAL 250)
+				set(${outvar} ${baud} PARENT_SCOPE)
+				return()
+			endif()
+		endforeach()
+	endforeach()
+	message(FATAL_ERROR "pureboot: no standard baud rate fits a ${clock} Hz clock within 2.5 %")
+endfunction()
+
+# pureboot_add_loader(<name> [CLOCK <hz>] [BAUD <bd>]
+#                     [SERIAL auto|hardware|software] [USART <n>]
+#                     [RX <pin>] [TX <pin>] [TIMEOUT <s>])
+#
+# Creates the loader target plus its flashable images (<name>.hex for a
+# programmer, <name>.bin for --update-loader) and stamps the resolved
+# deployment on the target: the PUREBOOT_HZ, PUREBOOT_BAUD and PUREBOOT_LINK
+# properties (the link as usart0/usart1/sw:<RX>,<TX> — what a test harness
+# needs to speak to the build).
+function(pureboot_add_loader name)
+	cmake_parse_arguments(PB "" "CLOCK;BAUD;SERIAL;USART;RX;TX;TIMEOUT" "" ${ARGN})
+	if(PB_UNPARSED_ARGUMENTS)
+		message(FATAL_ERROR "pureboot_add_loader(${name}): unknown arguments ${PB_UNPARSED_ARGUMENTS}")
+	endif()
+	get_property(_hz GLOBAL PROPERTY PUREBOOT_DEFAULT_HZ)
+	get_property(_base_hex GLOBAL PROPERTY PUREBOOT_BASE_HEX)
+	get_property(_app GLOBAL PROPERTY PUREBOOT_APP)
+	get_property(_wrap GLOBAL PROPERTY PUREBOOT_WRAP)
+	get_property(_usart GLOBAL PROPERTY PUREBOOT_HAS_USART)
+	get_property(_usart1 GLOBAL PROPERTY PUREBOOT_HAS_USART1)
+
+	if(NOT PB_CLOCK)
+		set(PB_CLOCK ${_hz})
+	endif()
+	if(NOT PB_TIMEOUT)
+		set(PB_TIMEOUT 8)
+	endif()
+	if(NOT PB_SERIAL)
+		set(PB_SERIAL auto)
+	endif()
+	if(DEFINED PB_USART AND PB_SERIAL STREQUAL "software")
+		message(FATAL_ERROR "pureboot_add_loader(${name}): USART ${PB_USART} contradicts SERIAL software")
+	endif()
+	if(DEFINED PB_USART)
+		set(PB_SERIAL hardware)
+	elseif(PB_SERIAL STREQUAL "hardware")
+		set(PB_USART 0)
+	endif()
+
+	set(_serial_defines "")
+	if(PB_SERIAL STREQUAL "hardware")
+		if(PB_USART EQUAL 1 AND NOT _usart1)
+			message(FATAL_ERROR "pureboot_add_loader(${name}): ${LIBAVR_MCU} has no USART1")
+		elseif(NOT _usart)
+			message(FATAL_ERROR "pureboot_add_loader(${name}): ${LIBAVR_MCU} has no hardware USART")
+		endif()
+		set(_serial_defines PUREBOOT_USART=${PB_USART})
+		set(_link usart${PB_USART})
+	else()
+		if(PB_SERIAL STREQUAL "auto")
+			if(_usart AND (PB_RX OR PB_TX))
+				message(WARNING "pureboot_add_loader(${name}): RX/TX apply to the software UART, "
+				        "which auto does not pick on ${LIBAVR_MCU} — SERIAL software to force it")
+			endif()
+			if(_usart)
+				set(_link usart0)
+			else()
+				set(PB_SERIAL software)
+			endif()
+		endif()
+		if(PB_SERIAL STREQUAL "software")
+			if(NOT PB_RX)
+				set(PB_RX pb0)
+			endif()
+			if(NOT PB_TX)
+				set(PB_TX pb1)
+			endif()
+			foreach(_pin ${PB_RX} ${PB_TX})
+				if(NOT _pin MATCHES "^p[a-h][0-7]$")
+					message(FATAL_ERROR "pureboot_add_loader(${name}): pin '${_pin}' is not of the form pb1")
+				endif()
+			endforeach()
+			set(_serial_defines PUREBOOT_SOFT_SERIAL PUREBOOT_RX=${PB_RX} PUREBOOT_TX=${PB_TX})
+			# The link spec a test harness drives a GPIO bridge with: sw:<RX>,<TX>
+			# as the port letter and bit, the loader's own pin naming upcased.
+			string(SUBSTRING ${PB_RX} 1 2 _rx_pin)
+			string(SUBSTRING ${PB_TX} 1 2 _tx_pin)
+			string(TOUPPER "sw:${_rx_pin},${_tx_pin}" _link)
+			string(REPLACE "SW" "sw" _link ${_link})
+		endif()
+	endif()
+	if(NOT PB_BAUD)
+		if(PB_SERIAL STREQUAL "software")
+			pureboot_default_baud(${PB_CLOCK} 1 PB_BAUD)
+		else()
+			pureboot_default_baud(${PB_CLOCK} 0 PB_BAUD)
+		endif()
+	endif()
+
+	set(_defines PUREBOOT_CLOCK_HZ=${PB_CLOCK} PUREBOOT_BAUD=${PB_BAUD} PUREBOOT_TIMEOUT=${PB_TIMEOUT}
+	    ${_serial_defines})
+
+	add_executable(${name} ${CMAKE_CURRENT_FUNCTION_LIST_DIR}/pureboot.cpp)
+	target_link_libraries(${name} PRIVATE libavr)
+	target_compile_definitions(${name} PRIVATE ${_defines})
+	target_link_options(${name} PRIVATE -nostartfiles -Wl,--section-start=.text=${_base_hex}
+	                    -Wl,--defsym=pureboot_app=${_app} ${_wrap})
+	add_custom_command(TARGET ${name} POST_BUILD COMMAND ${CMAKE_SIZE} $<TARGET_FILE:${name}>)
+	# The ELF is a container (symbols, section headers), never flashed; the
+	# flashable forms sit beside it: .hex for a programmer, .bin (the slot's
+	# bare bytes) for the host tool's raw path and --update-loader.
+	add_custom_command(TARGET ${name} POST_BUILD
+	                   COMMAND ${CMAKE_OBJCOPY} -O ihex -R .eeprom
+	                           $<TARGET_FILE:${name}> $<TARGET_FILE:${name}>.hex
+	                   COMMAND ${CMAKE_OBJCOPY} -O binary -R .eeprom
+	                           $<TARGET_FILE:${name}> $<TARGET_FILE:${name}>.bin)
+	set_target_properties(${name} PROPERTIES PUREBOOT_HZ ${PB_CLOCK} PUREBOOT_BAUD ${PB_BAUD}
+	                      PUREBOOT_LINK ${_link})
+endfunction()

pureboot/README.md

@@ -0,0 +1,345 @@
+# pureboot
+
+A serial bootloader on [libavr](https://git.blackmark.me/avr/libavr), pure by
+constraint: one C++ source, no inline assembly, no global register variables
+(attributes allowed), built for **every chip libavr targets — all 37 —
+fitting each chip's smallest boot sector**: 512 bytes everywhere — 470 B on
+the tiny13s, ~484 B on the tiny25/45/85, 458–506 B across the megas and
+every configured variant of them (the m8's software-serial build is the
+fattest) — except the ATmega1284/1284P, whose smallest boot sector is 1 KiB
+and whose far-flash machinery (ELPM reads, RAMPZ page commands,
+word-addressed wire) lands at 556–562 B in a 1 KiB slot: the 512-byte
+figure is a hardware boundary those chips simply do not have, and no
+implementation of this feature set fits it there. Clock, baud, serial
+backend and pins are per-build configuration (below); the size matrix in
+the test suite holds every combination inside its slot. The device speaks
+primitives; every composite — verify, erase, reset-vector surgery, updating
+the loader itself — lives in the host tool (`pureboot.py`).
+
+The image is **position-independent**: control flow is PC-relative, the
+read/write paths take wire addresses, the write guard protects the slot the
+code is *running* in (from the runtime return address), the info block is
+addressed from that same anchor, and the application jump is an indirect
+call to an absolute entry. The identical binary therefore runs from any
+slot with every command intact — which makes pureboot **its own staging
+loader**: the host installs the same binary one slot below the resident,
+jumps into it, and lets it rewrite the resident. The slot is 512 bytes
+(1 KiB on the word-addressed large chips, matching their boot-sector
+minimum); on the tinies the budget is 510, not 512: a slot's last word
+belongs to the host-managed trampoline (below).
+
+## Configuration
+
+Every deployment axis is a build parameter, resolved by the CMake function
+`pureboot_add_loader()` (in `pureboot/CMakeLists.txt`) — the one way a
+loader target is created, by this repo's own build and by a downstream
+project alike:
+
+| Argument | Meaning | Default |
+|---|---|---|
+| `CLOCK <hz>` | the clock the board runs | 16 MHz megas, 8 MHz t25/45/85, 9.6 MHz t13s |
+| `BAUD <bd>` | the wire rate | the ladder below |
+| `SERIAL auto\|hardware\|software` | the link backend | `auto`: the hardware USART where the chip has one |
+| `USART <n>` | the USART instance (x4 megas carry two) | 0 |
+| `RX <pin>`, `TX <pin>` | software-UART pins | `pb0`, `pb1` |
+| `TIMEOUT <s>` | the activation window | 8 |
+
+The default baud is the fastest of 115200/57600/38400/19200/9600 the clock
+reaches within 2.5 % — the same U2X-included divisor search libavr's baud
+solver runs — and on a software build additionally within the polled
+receiver's 100-cycles-a-bit floor. 16 MHz lands 115200, 8 MHz 57600,
+1 MHz 9600. Whatever is picked or overridden is re-checked in the compile:
+an infeasible clock/baud/backend combination, or a USART the chip does not
+have, fails with a named static assert.
+
+A downstream project brings its usual libavr setup (the `libavr` target,
+the chip via the `LIBAVR_MCU` toolchain preset), consumes this directory,
+and states its deployment — for example an ATmega328P on its shipped
+1 MHz fuses with the software UART on hand-picked pins:
+
+```cmake
+FetchContent_Declare(bootloader GIT_REPOSITORY git@git.blackmark.me:avr/bootloader.git GIT_TAG main)
+FetchContent_MakeAvailable(bootloader)
+add_subdirectory(${bootloader_SOURCE_DIR}/pureboot pureboot)
+
+pureboot_add_loader(myboot CLOCK 1000000 SERIAL software TX pb1 RX pb5)
+```
+
+The function emits the ELF plus `myboot.hex` (the programmer artifact) and
+`myboot.bin` (the self-update image), prints the size, and stamps the
+resolved deployment on the target as the `PUREBOOT_HZ`, `PUREBOOT_BAUD`
+and `PUREBOOT_LINK` properties — what a flashing script or test harness
+needs to speak to the build. This exact example deployment runs the full
+protocol suite in CI (`pureboot.custom`).
+
+## Link
+
+The stock builds assume the family's natural deployment; any axis moves
+per build (above).
+
+| Chip | Serial | Baud | Clock assumed |
+|---|---|---|---|
+| every ATmega | the hardware USART (USART0), RXD/TXD per pinout | 115200 8N1 | 16 MHz crystal |
+| ATtiny25/45/85 | software UART, RX = PB0, TX = PB1 | 57600 8N1 | 8 MHz internal RC |
+| ATtiny13/13A | software UART, RX = PB0, TX = PB1 | 57600 8N1 | 9.6 MHz internal RC |
+
+The software-UART RX pin has its pull-up enabled; TX idles high. All
+multi-byte quantities on the wire are little-endian.
+
+## Activation
+
+Reset enters the loader (BOOTRST on the boot-sectioned megas; the patched
+reset vector on the tinies and the boot-section-less m48s) — except a
+watchdog reset, which hands straight to the application (the application
+owns its watchdog; it must clear WDRF itself, which also releases the
+WDRF-forced WDE).
+
+The host then has one activation window per awaited byte to knock: `p` then
+`b`. Each awaited byte gets a fresh window; any other byte is discarded and
+awaited again (line noise cannot lock the loader, only delay it). A window
+expiring with an idle line boots the application.
+
+The window length is a compile-time constant — 8 s by default, another
+value via `pureboot_add_loader(... TIMEOUT <s>)` (the stock target keeps
+the `PUREBOOT_TIMEOUT` cache variable) — so the whole EEPROM belongs to
+the application; pureboot never uses it for its own state. Re-timing a
+deployed loader is a self-update with a re-timed build (below).
+
+## Session
+
+After the knock the loader stays in its command loop until `J` jumps away or
+the chip resets. Before reading each command it waits for any pending EEPROM
+write to finish and sends the prompt `+` (0x2b) — the prompt is therefore
+also the completion ack of the previous command. A session is: await `+`,
+send a command, read its reply, repeat.
+
+On chips whose flash exceeds 64 KiB (the 1284s — info-block flag bit 1) the
+`R`/`W` flash addresses are **word** addresses; everywhere else they are byte
+addresses (the 644s' 64 KiB is exactly the 16-bit byte space and stays
+byte-addressed). EEPROM addresses are always bytes, counts always bytes.
+
+| Cmd | Arguments | Reply |
+|---|---|---|
+| `b` | — | the 12-byte info block |
+| `R` | addr16, n8 | n flash bytes (n = 0 means 256) |
+| `W` | addr16, then one page of data | — (completion = next prompt) |
+| `r` | addr16, n8 | n EEPROM bytes (n = 0 means 256) |
+| `w` | addr16, n8, then n data bytes | `+` per byte, sent once its write has begun |
+| `F` | — | 4 bytes: low fuse, lock, extended fuse, high fuse |
+| `J` | word address (16-bit) | `+`, then execution continues there |
+| other | — | ignored; the loop re-prompts (send a junk byte, await `+`, to resync) |
+
+`W` streams exactly one SPM page (size from the info block) into the buffer,
+then erases and programs; the address must be page-aligned. Pages inside the
+512-byte slot the loader is *running* in are drained but never programmed — a
+broken host cannot brick the running copy, and a staged copy may rewrite the
+resident slot. `w` is host-paced: send the next byte only after the previous
+byte's `+`. `F` returns the bytes in the hardware's Z order; on a chip
+without an extended fuse byte (the ATtiny13A) that slot carries no meaning.
+Fuse *writing* does not exist: SPM reaches flash (and, on the mega, lock
+bits) only — fuse bytes are external-programming territory by hardware.
+
+`J` is the one control-transfer primitive: the host uses it to run the
+application (word 0 on the mega, the trampoline word on the tinies — both
+known from the info block) and to move between loader copies during a
+self-update. A jump to a loader slot's base re-enters that copy's own
+startup; it must then be knocked afresh.
+
+The info block (`b`):
+
+| Offset | Content |
+|---|---|
+| 0–2 | `'P'`, `'B'`, protocol version (1) |
+| 3–5 | device signature |
+| 6 | SPM page size in bytes (0 means 256) |
+| 7–8 | loader base — application flash ends here (a word address when bit 1 is set) |
+| 9–10 | EEPROM size |
+| 11 | bit 0: host must patch the reset vector (no hardware boot section); bit 1: flash wire addresses are word addresses |
+
+Composites are the host's job: verify = read back and compare, erase =
+write `0xff` (per page for flash, per byte for EEPROM).
+
+## Deployment
+
+The build leaves three artifacts per chip. The ELF is a container for the
+tests and objcopy — never flashed. The **.hex is the programmer artifact**:
+it carries its own addresses and lands the loader in its top slot,
+touching nothing else. The **.bin is the self-update image** — the slot's
+bare bytes with no addressing, which a programmer would put at address 0.
+On a boot-sectioned mega a copy at 0 is dead weight (SPM only executes
+from the boot section, so it cannot even heal itself — reflash the .hex);
+on the patched-vector chips it *runs* (the image is position-independent
+and reset enters word 0), reports its canonical geometry, and the ordinary
+`--update-loader` flow re-homes a build into the top slot from any
+position — the staging install and the word-0 redirect execute from
+copies outside page 0's slot, and a copy sitting in the staging slot
+itself is recognized as the installed staging copy and left in place (it
+streams the new resident like any staged copy, so an older build installs
+a newer one). `pureboot.rehome` is the acceptance test for both
+positions. Flashing the application afterwards overwrites the stale copy,
+vector surgery included.
+
+**Boot-sectioned megas**: program the loader at `flash − slot` with an
+external programmer. Every such mega has a BOOTSZ step whose boot section
+is exactly the loader slot — 512 B, the second-smallest step on the 8 KiB
+and 16 KiB chips (m8, m88, m16, m168, m164), the smallest on the 32 KiB
+ones (m32, m328, m324); on the 1284s that step is the smallest, 512 words,
+which is why their slot is 1 KiB — so the ATmega328P profiles below apply
+to every one of them with its own addresses and slot size; the per-chip
+BOOTSZ ladders live in the host tool (`BOOT_FUSE`). The 1284s' numbers:
+standalone = BOOTSZ 512 words (reset at the loader base 0x1fc00);
+self-update = 1024 words, covering both 1 KiB slots, the loader-first
+reset landing at 0x1f800 — the staging slot, walked across when erased.
+
+The **644s** are the geometry's sweet spot: their smallest boot section
+(512 words = 1 KiB) is exactly *two* 512-byte slots, so the resident and
+its staging slot both live inside the minimum section — self-update needs
+no fuse step up, and the standalone profile does not exist (reset lands at
+0xfc00, one erased slot below the loader: the loader-first walk built in).
+
+ATmega328P profiles (addresses for its 32 KiB):
+
+| BOOTSZ | BOOTRST | Behavior |
+|---|---|---|
+| 256 words (512 B) | programmed | *Standalone*: reset always enters the loader; **self-update impossible** (the staging slot lies outside the boot section, where SPM is disabled). |
+| 512 words (1 KB) | unprogrammed | *Self-update, app-first*: reset always boots the application, which owns all 31.5 KB and must offer its own jump to 0x7e00 to reach the loader (a virgin chip reaches it by reset across erased flash). Updates are power-fail-safe except mid-rewrite of the resident slot itself (no reset path leads to the staging copy then). |
+| 512 words (1 KB) | programmed | *Self-update, loader-first*: reset lands at 0x7c00 — the staging slot, normally erased, so execution walks up into the loader; during an update it is the staging copy itself, so a mid-rewrite power loss recovers by reset. The loss windows move to the staging install/retire page writes instead (page-write scale). The host keeps `[0x7c00, 0x7e00)` clear of application data (`--force` overrides). |
+
+Applications are flashed unmodified — word 0 stays the application's own
+reset vector, and the hand-over jumps to 0.
+
+**Patched-vector chips — the tinies and the m48s** (no boot section; the
+m48s' SPM runs from the entire flash, Atmel-8271 §26): program the loader
+at `flash − 512`; erased flash below it walks up into the loader, so a
+virgin chip activates. When flashing an application the host performs
+reset-vector surgery: word 0 is rewritten to `rjmp` to the loader base, and
+the application's own entry is re-encoded as a trampoline `rjmp` in the
+word just below the loader (`base − 2`, where the hand-over jumps). Every
+other vector stays the application's. The patched page 0 and the trampoline
+page are written *first*, so from the first write on an interrupted flash
+still resets into the loader; an erase runs top-down for the same reason.
+The m48s speak this profile over their hardware USART — no fuse preflight,
+BOOTRST does not exist there.
+
+## Updating the loader
+
+`pureboot.py --update-loader new_pureboot.bin` replaces the resident loader
+with any pureboot build — a re-timed window, a newer protocol — using the
+loader itself as its own staging loader. The image is the loader's own 512
+bytes as a raw binary, or the Intel HEX the build emits beside it, which
+links the loader at its base inside an otherwise blank flash image:
+
+The preflight refuses an image built for another chip: the info block
+embedded in every pureboot binary (signature, page size, loader base,
+EEPROM size, flags) must match the device's own, and the error names both.
+Die revisions share their base signature and geometry, so their images are
+interchangeable — as the silicon is. `loader_image()` also accepts a
+padded image (a raw .bin padded from 0, or a whole-flash read-back with
+the loader resident) and peels it to the slot content by the embedded base.
+
+1. The staging slot `[base−slot, base)` is saved to a host-side state file
+   (on the 1 KB tiny13s that is the whole application, vectors included).
+2. The resident installs the identical update image there. On the
+   patched-vector chips the host composes the slot's last word — the same
+   address as the resident's trampoline — as a jump to the resident base,
+   so even an abandoned staging copy times out into a loader, never into
+   garbage. A loader already sitting whole in the staging slot (its info
+   block in place, the slot unchanged since the update began) is left as
+   the staging copy instead — rewriting it would only meet its own
+   running-slot guard.
+3. `J` enters the staging copy, which rewrites the resident slot. On the
+   patched-vector chips whose staging slot sits away from page 0 the host
+   first re-aims word 0 at the staging copy, so a power loss mid-rewrite
+   still resets into a loader; on the tiny13s the staging slot carries the
+   reset vector itself.
+4. `J` enters the new resident, which restores the staging slot's saved
+   content (word 0 and the trampoline with it) and the state file is
+   discarded.
+
+Every phase is idempotent and keyed off the actual flash state: re-running
+the same command after any interruption resumes and completes. The state
+file carries the only bytes not recoverable from the device; if it is lost
+mid-update the update still completes, and the staging region is restored by
+reflashing the application. A boot-sectioned mega needs its fuses for the
+preflight (BOOTSZ gate, profile notes) — read from the device, or supplied
+with `--assume-fuses` where reading is impossible (simulators); the
+patched-vector chips need none.
+
+## Host tool
+
+`pureboot.py` — Python 3, standard library only. The port layer is the one
+platform-specific part: termios drives any tty on POSIX (a USB adapter as
+well as a simavr pty), the Win32 serial API through `ctypes` drives a COM
+port on Windows (`--port COM6`; the `\\.\` form for two-digit ports is
+supplied by the tool). Opening the port asserts DTR and RTS on both, so a
+board that wires DTR to reset gets its reset pulse and opens the activation
+window by itself.
+
+    pureboot.py --port /dev/ttyUSB0 --baud 57600 \
+        --info --fuses --flash app.hex
+
+Operations run in a fixed order within one session: info, fuses, loader
+update, flash (erase / program / read / verify), EEPROM (erase / program /
+read / verify) — then the loader hands over to the application; `--stay`
+keeps the session alive instead, and a later invocation reconnects into it
+(the knock converges there too). `--flash` and `--eeprom` verify by
+read-back unless `--no-verify`; images are raw binary, or Intel HEX by
+extension. `--force` overrides the refusable safety checks (today: flashing
+application data into a mega's reset walk region).
+
+Readouts come one fact per line: `--info` prints the decoded info block
+field by field, `--fuses` each fuse byte on its own line — plus, on a
+boot-sectioned mega, the decoded meaning (where the BOOTSZ section starts,
+what BOOTRST does to reset). Transfers that take wire time — programming,
+reading, erasing, verifying, the update phases — draw a transient progress
+bar on stderr when it is a tty; logs and pipes see only the summary lines.
+`-v`/`--verbose` adds the decisions as they happen: knock counts, the
+programming plan (vector-surgery targets, skipped blank pages), update
+state handling and per-phase page counts.
+
+## Tests
+
+`tools/check.sh` runs every chip's workflow (`tools/check.sh --full` adds
+the reflect-mode builds of libavr's spot set; `tools/make_presets.py`
+regenerates the presets). Per chip preset, `ctest` runs:
+
+- `pureboot.size` — the 510-byte (tinies) / 512-byte (mega) budget;
+- `pureboot_*.size` — the size matrix: the serial backends × the clock
+  ladder (1/8/16 MHz; the t13s' own RC menu), plus the USART1 build on the
+  x4 chips — every configuration axis that could move the image, each
+  variant against the same slot budget (pins are immediate operands and the
+  timeout is a constant: size-neutral);
+- `pureboot.custom` (328P) — the configured-deployment acceptance test: the
+  1 MHz software-serial TX=PB1/RX=PB5 build from the configuration example
+  drives the full protocol suite through the runner's GPIO bridge, fixture
+  application included;
+- `pureboot.usart1` (644A) — the same protocol suite over the second
+  hardware USART: instance selection is compile-checked everywhere, but
+  only a live session proves the loader polls the USART it claims;
+- `pureboot.pi` — the position-independence lint: no absolute `jmp`/`call`
+  in the image, the info block within its first 256 bytes;
+- `pureboot.planner` — the host tool's pure logic: programming orders and
+  their recovery properties, the surgery, the staging composition, the
+  boot-fuse decode, and the update preflight's error/warning matrix over
+  synthetic fuse bytes;
+- `pureboot.protocol` — end to end against a simavr device
+  (`test/pureboot_device.c` — a hardware USART as a pty, or a cycle-timed
+  GPIO⇄pty bridge for a software-UART build, selected with `-l` to match
+  the loader's link; plus the SPM/NVM module simavr's tiny cores lack)
+  driven by the real host tool through
+  knock-from-reset, program + verify of both memories, session reconnect, an
+  external reset through the patched vector, and the hand-over to a fixture
+  application whose banner proves the launch — cross-checked against the
+  simulator's ground-truth memory dumps and an independent decode of the
+  surgery's rjmp words;
+- `pureboot.reloc` — the identical image installed one slot below the
+  resident serves the complete command set from there (the
+  position-independence acceptance test);
+- `pureboot.update` — the full `--update-loader` flow to a re-timed build,
+  then every power-fail phase: the device is killed mid-write, restarted
+  from its flash dump, and a re-run must complete the update with the
+  application intact throughout.
+
+`size`, `pi`, and `planner` are host logic and run anywhere; the
+simulator-driven targets need simavr and a pty, so they are POSIX-only —
+on Windows the tool is exercised against real hardware.

pureboot/pureboot.cpp

@@ -0,0 +1,492 @@
+// pureboot — a serial bootloader on libavr, pure by constraint: one C++
+// source with no inline assembly and no global register variables, built for
+// every chip libavr targets, 512 bytes on each. The device speaks primitives
+// — read/program flash, read/write EEPROM, fuse bytes, an info block, a jump
+// — and everything composite (verify, erase, reset-vector surgery, updating
+// the loader itself) lives in the host tool. Protocol reference: README.md
+// next to this file.
+//
+// The image is position-independent: control flow is PC-relative, the write
+// and read paths take wire addresses, the write guard refuses the 512-byte
+// slot the code is *running* in (taken from the runtime return address), the
+// info block is read relative to that same anchor, and the application jump
+// is an indirect call to an absolute entry. The identical binary therefore
+// runs from any 512-byte slot with every command intact: flashed one slot
+// below the resident loader it becomes the staging loader that rewrites the
+// resident — how pureboot updates itself, host-driven, with no other
+// firmware involved.
+//
+// Entry: reset lands in avr::startup::entry below (BOOTRST on the
+// boot-sectioned megas; the patched reset vector — or erased flash walking
+// up into the loader — on the tinies and the boot-section-less m48s). A
+// watchdog reset hands straight to the application. Otherwise the
+// host has one activation window per awaited knock byte ("pb"); an idle line
+// boots the application. A session then stays in the command loop until 'J'
+// jumps away or the chip resets.
+
+#include <libavr/libavr.hpp>
+
+using namespace avr::literals;
+namespace spm = avr::spm;
+namespace ee = avr::eeprom;
+
+namespace pureboot {
+namespace {
+
+// Purely polled — interrupts stay off, every guard folds to nothing.
+constexpr auto off = avr::irq::guard_policy::unused;
+
+constexpr std::uint8_t ack = '+';
+
+// Per-deployment personality, passed in by the build — pureboot_add_loader()
+// (the CMake function next to this file) resolves the defaults: the clock the
+// board actually runs, the wire baud, the serial backend and its pins. The
+// device signature needs no configuring — it comes from the chip database
+// (avr::hw::db.signature), the only universal source, since the tiny13A
+// cannot even read its signature row from code.
+#if !defined(PUREBOOT_CLOCK_HZ) || !defined(PUREBOOT_BAUD)
+#error \
+    "PUREBOOT_CLOCK_HZ and PUREBOOT_BAUD select this build's clock and baud — create loader targets with pureboot_add_loader() (README.md)"
+#endif
+
+using dev = avr::device<{.clock = avr::hertz_t{PUREBOOT_CLOCK_HZ}}>;
+constexpr avr::baud_t wire_baud{PUREBOOT_BAUD};
+
+// The watchdog reset flag's home: MCUSR, or the classic megas' MCUCSR.
+consteval std::int16_t wdrf_field()
+{
+	auto reg = std::string_view{avr::hw::db.regs[static_cast<std::size_t>(avr::power::detail::reset_reg())].name};
+	return avr::hw::db.field_index(reg, "WDRF");
+}
+
+// Geometry: the resident loader owns the top slot of flash — 512 bytes,
+// except on the >64 KiB chips whose own smallest boot sector is 1 KiB (the
+// 1284s): there the slot is 1 KiB, matching the hardware boundary the
+// 512-byte figure comes from everywhere else. The word below the slot is
+// the trampoline (the application's relocated reset vector) on chips
+// without a hardware boot section — the tinies and the m48s, whose SPM
+// runs from anywhere (Atmel-8271 §26). A boot section also means the CPU
+// runs on while the RWW section programs; everywhere else it halts through
+// the operation. The m48s still carry RWWSRE as their temporary-buffer
+// discard (§26.2), so the discard picks by that bit, not by the section.
+constexpr std::uint16_t slot_bytes = spm::flash_bytes > 65536 ? 1024 : 512;
+constexpr std::uint32_t base = spm::flash_bytes - slot_bytes;
+constexpr std::uint16_t page = spm::page_bytes;
+constexpr bool boot_section = avr::hw::curated::has_boot_section();
+constexpr bool rww_discard = spm::detail::has_rww();
+
+// Past 64 KiB a byte address no longer fits the wire's 16 bits, so on the
+// large chips every flash address on the wire — and all slot arithmetic —
+// is a word address instead ('J' always was one). A slot spans the same
+// wire-high-byte pair in either unit (512 B = 2 x 256 bytes, 1 KiB =
+// 2 x 256 words), so the slot index is the high byte with its low bit
+// dropped everywhere.
+constexpr bool word_flash = spm::flash_bytes > 65536;
+constexpr std::uint16_t wire_base =
+    word_flash ? static_cast<std::uint16_t>(base / 2) : static_cast<std::uint16_t>(base);
+constexpr std::uint16_t wire_page_mask = word_flash ? (page / 2 - 1) : (page - 1);
+
+// The activation window, in seconds, is a compile-time constant (the build
+// may override it): the whole EEPROM belongs to the application, and
+// re-timing the loader is a bootloader self-update with a re-timed binary.
+#if !defined(PUREBOOT_TIMEOUT)
+#define PUREBOOT_TIMEOUT 8
+#endif
+constexpr std::uint8_t timeout_seconds = PUREBOOT_TIMEOUT;
+
+// The 12-byte info block the host reads with the 'b' command; flash-resident
+// (there is no crt to copy a .data image), word-aligned so its wire (word)
+// address is exact on the large chips. The page byte is the wire count
+// convention: 0 means 256.
+[[gnu::progmem]] alignas(2) inline constexpr std::array<std::uint8_t, 12> info_data = {
+    'P',
+    'B',
+    1, // magic, protocol version
+    avr::hw::db.signature[0],
+    avr::hw::db.signature[1],
+    avr::hw::db.signature[2],
+    static_cast<std::uint8_t>(page),
+    wire_base & 0xff,
+    wire_base >> 8, // app flash ends here; resident loader base (a word address on large chips)
+    avr::hw::db.mem.eeprom_size & 0xff,
+    avr::hw::db.mem.eeprom_size >> 8,
+    // bit 0: host must patch the reset vector (no hardware boot section);
+    // bit 1: flash wire addresses are word addresses
+    static_cast<std::uint8_t>((boot_section ? 0 : 1) | (word_flash ? 2 : 0)),
+};
+
+// The serial link. PUREBOOT_USART forces a hardware USART instance,
+// PUREBOOT_SOFT_SERIAL the polled software UART (no vector — the table
+// belongs to the application) on PUREBOOT_RX/PUREBOOT_TX; with neither, the
+// chip's first USART where it has one and the software UART elsewhere. Both
+// are class templates on the clock so only the selected backend is ever
+// instantiated. pending() is the cheap line test the activation window
+// polls; rx() then picks the byte up; drain() holds until the last
+// transmitted frame is fully on the wire (the jump hand-over must not let
+// the target's re-init clip the ack).
+#if defined(PUREBOOT_SOFT_SERIAL) && defined(PUREBOOT_USART)
+#error "PUREBOOT_SOFT_SERIAL and PUREBOOT_USART select opposing serial backends"
+#endif
+#if !defined(PUREBOOT_RX)
+#define PUREBOOT_RX pb0
+#endif
+#if !defined(PUREBOOT_TX)
+#define PUREBOOT_TX pb1
+#endif
+#if defined(PUREBOOT_USART)
+constexpr char usart_digit = '0' + PUREBOOT_USART;
+#else
+constexpr char usart_digit = '0';
+#endif
+
+// Whether the chip carries the selected USART: the suffixed instance name,
+// or — for instance 0 — the classic megas' un-numbered block.
+consteval bool usart_exists()
+{
+	const char name[] = {'U', 'S', 'A', 'R', 'T', usart_digit};
+	if (avr::hw::db.has_instance(std::string_view{name, sizeof(name)}))
+		return true;
+	return usart_digit == '0' && avr::hw::db.has_instance("USART");
+}
+
+template <avr::hertz_t C>
+struct hardware_link {
+	using uart = avr::uart::usart<usart_digit, C, {.baud = wire_baud, .max_baud_error = 2.5_pct}>;
+
+	// The compiled idle poll: lds UCSR0A (2), sbrc skipping the exit (2),
+	// sbiw + sbci + sbci + brne (6).
+	static constexpr std::uint8_t poll_cycles = 10;
+
+	static void init()
+	{
+		avr::init<uart>();
+	}
+
+	static bool pending()
+	{
+		return uart::rx_ready();
+	}
+
+	static std::uint8_t rx()
+	{
+		return uart::read_blocking();
+	}
+
+	static void tx(std::uint8_t byte)
+	{
+		uart::write(byte);
+	}
+
+	static void drain()
+	{
+		uart::drain();
+	}
+};
+
+template <avr::hertz_t C>
+struct software_link {
+	using rx_t = avr::uart::software_rx_polled<C, avr::PUREBOOT_RX, wire_baud>;
+	using tx_t = avr::uart::software_tx<C, avr::PUREBOOT_TX, wire_baud>;
+
+	// The compiled idle poll: sbis skipping the exit (2), sbiw + sbci +
+	// sbci + brne (6).
+	static constexpr std::uint8_t poll_cycles = 8;
+
+	static void init()
+	{
+		avr::init<rx_t, tx_t>();
+	}
+
+	static bool pending()
+	{
+		return rx_t::start_pending();
+	}
+
+	static std::uint8_t rx()
+	{
+		return rx_t::template read_blocking<off>();
+	}
+
+	static void tx(std::uint8_t byte)
+	{
+		tx_t::template write<off>(byte);
+	}
+
+	static void drain()
+	{
+		// The software transmitter returns only after the stop bit.
+	}
+};
+
+#if defined(PUREBOOT_USART)
+static_assert(usart_exists(), "PUREBOOT_USART selects a hardware USART this chip does not have");
+using link = hardware_link<dev::clock>;
+#elif defined(PUREBOOT_SOFT_SERIAL)
+using link = software_link<dev::clock>;
+#else
+using link = std::conditional_t<usart_exists(), hardware_link<dev::clock>, software_link<dev::clock>>;
+#endif
+
+// The application's entry, an absolute address the linker pins (--defsym in
+// CMakeLists.txt): 0x0000 on the mega (word 0 stays the application's own
+// vector — BOOTRST re-vectors a reset into the loader in hardware) and the
+// trampoline word at base - 2 on the tinies. Reaching it must not depend on
+// where this copy runs, so the jump goes through a pointer: [[gnu::noipa]]
+// keeps the constant from folding back into a PC-relative call.
+extern "C" [[noreturn]] void pureboot_app();
+
+[[gnu::noipa, noreturn]] void jump(void (*target)())
+{
+	target();
+	__builtin_unreachable();
+}
+
+[[gnu::noinline, noreturn]] void run_app()
+{
+	jump(pureboot_app);
+}
+
+// One activation window is a single 32-bit poll countdown. The divisor is
+// the backend's counted poll-loop cycles (its own comment reads them off the
+// compiled loop); whole-second precision is all the window promises, so the
+// nearest cycle count is plenty.
+consteval std::uint32_t window_polls()
+{
+	return timeout_seconds * static_cast<std::uint32_t>(dev::clock.hz / link::poll_cycles);
+}
+
+bool pending_before_deadline()
+{
+	std::uint32_t polls = window_polls();
+	do {
+		if (link::pending())
+			return true;
+	} while (--polls);
+	return false;
+}
+
+// A knock byte under the activation deadline: an idle line means no host is
+// there, and the application runs.
+std::uint8_t rx_deadline()
+{
+	if (!pending_before_deadline())
+		run_app();
+	return link::rx();
+}
+
+std::uint16_t rx16()
+{
+	std::uint16_t low = link::rx();
+	return static_cast<std::uint16_t>(low | (link::rx() << 8));
+}
+
+// The streamers take the count in the wire's 8-bit form: 0 means 256.
+// send_flash stays out of line: its two callers ('b' and 'R') otherwise each
+// inline a private copy of the loop. On the large chips the address is a
+// word address and the read goes through ELPM (flash_load_far).
+[[gnu::noinline]] void send_flash(std::uint16_t address, std::uint8_t count)
+{
+	if constexpr (word_flash) {
+		// The 24-bit cursor as the machine holds it: the RAMPZ byte and a
+		// 16-bit Z, carried explicitly (the reassembled 32-bit address
+		// folds away inside the inlined far load). A single read never
+		// crosses a 64 KiB boundary — the protocol forbids it and the host
+		// splits its chunks there — so RAMPZ holds for the whole run.
+		std::uint8_t rampz = static_cast<std::uint8_t>(address >> 15);
+		std::uint16_t z = static_cast<std::uint16_t>(address << 1);
+		do {
+			link::tx(avr::flash_load_far<std::uint8_t>((static_cast<std::uint32_t>(rampz) << 16) | z));
+			if (++z == 0)
+				++rampz; // robustness for a host that reads across 64 KiB
+		} while (--count);
+	} else {
+		do
+			link::tx(avr::flash_load(reinterpret_cast<const std::uint8_t *>(address++)));
+		while (--count);
+	}
+}
+
+void send_eeprom(std::uint16_t address, std::uint8_t count)
+{
+	do
+		link::tx(ee::read(address++));
+	while (--count);
+}
+
+// EEPROM write, host-paced: each ack goes out once the byte's write has
+// begun, so the next byte arrives while it completes and the following
+// write's own ready-wait sees an idle line. Nothing is ever missed, on
+// either serial backend, without a buffer.
+void store_eeprom(std::uint16_t address, std::uint8_t count)
+{
+	do {
+		ee::write<off>(address++, link::rx());
+		link::tx(ack);
+	} while (--count);
+}
+
+// One flash page: stream the bytes into the SPM buffer as little-endian
+// words, then erase and program — except the 512-byte slot this code runs
+// in, which is drained but never programmed, so a copy can never erase
+// itself. `slot_high` is the high byte of that running slot's base (run()
+// derives it); a broken host thus cannot brick the running loader, and a
+// copy flashed one slot lower may rewrite the slot above it — how pureboot
+// updates itself. On the mega the RWW section is re-enabled so reads work
+// immediately.
+void program_flash(std::uint16_t wire_address, std::uint8_t slot_high)
+{
+	// A buffer word cannot be loaded twice without an erase (§26.2.1), so a
+	// refused page's drained data must not linger for the next write:
+	// discard the buffer up front — CTPB on the tinies; on the megas
+	// writing RWWSRE aborts a pending load (§26.2.2 — on the m48s that
+	// flush is the bit's whole documented job).
+	if constexpr (rww_discard)
+		spm::rww_enable<off>();
+	else
+		spm::clear_buffer<off>();
+	// One induction either way. On the byte-addressed chips the wire address
+	// itself walks the page (aligned, so the offset bits wrap to zero); on
+	// the word-addressed large chips the wire word address becomes a 32-bit
+	// byte cursor once, and their 256-byte page makes its low byte the whole
+	// in-page offset. The slot index is one high byte of the wire address —
+	// two values on byte-addressed chips (the & ~1), bits 16:9 re-packed on
+	// the large ones.
+	spm::flash_address_t address;
+	std::uint8_t page_high;
+	if constexpr (word_flash) {
+		// Pages are aligned, so one page never crosses a 64 KiB boundary:
+		// RAMPZ is a per-page constant and the fill cursor is a 16-bit Z
+		// whose low byte is the whole in-page offset (256-byte pages). The
+		// slot index is simply the wire word address's high byte.
+		const std::uint8_t rampz = static_cast<std::uint8_t>(wire_address >> 15);
+		const std::uint16_t z0 = static_cast<std::uint16_t>(wire_address << 1);
+		std::uint16_t z = z0;
+		do {
+			std::uint8_t low = link::rx();
+			std::uint8_t high = link::rx();
+			spm::fill<off>((static_cast<spm::flash_address_t>(rampz) << 16) | z,
+			               static_cast<std::uint16_t>(low | (high << 8)));
+			z += 2;
+		} while (static_cast<std::uint8_t>(z));
+		address = (static_cast<spm::flash_address_t>(rampz) << 16) | z0;
+		page_high = static_cast<std::uint8_t>(wire_address >> 8) & 0xfe;
+	} else {
+		address = static_cast<spm::flash_address_t>(wire_address);
+		do {
+			std::uint8_t low = link::rx();
+			std::uint8_t high = link::rx();
+			spm::fill<off>(address, static_cast<std::uint16_t>(low | (high << 8)));
+			address += 2;
+		} while (static_cast<std::uint8_t>(address) & (page - 1));
+		address -= 2; // back inside the page — erase and write ignore the word bits
+		page_high = static_cast<std::uint8_t>(address >> 8) & 0xfe;
+	}
+	if (page_high != slot_high) {
+		// The tinies and the m48s halt the CPU through the erase and the
+		// write, so only the boot-sectioned megas — running on while their
+		// RWW section programs — wait.
+		spm::erase_page<off>(address);
+		if constexpr (boot_section)
+			spm::wait();
+		spm::write_page<off>(address);
+		if constexpr (boot_section) {
+			spm::wait();
+			spm::rww_enable<off>();
+		}
+	}
+}
+
+// The four fuse/lock bytes in the hardware's own Z order: low, lock,
+// extended, high. Writing fuses is not a thing self-programming can do on
+// AVR — SPM reaches flash (and boot lock bits) only.
+void send_fuses()
+{
+	std::uint8_t which = 0;
+	do
+		link::tx(spm::read_fuse<off>(static_cast<spm::fuse>(which)));
+	while (++which & 3);
+}
+
+[[noreturn]] void run()
+{
+	// A watchdog reset belongs to the application (whose watchdog stays
+	// forced on until it clears WDRF) — no activation window in its way.
+	// The flag register is MCUSR, or the classic megas' MCUCSR.
+	if (avr::hw::field_impl<wdrf_field()>::test())
+		run_app();
+
+	link::init();
+
+	// The high byte of the 512-byte-aligned base this copy runs at: the
+	// return address is a word address, whose high byte is the 256-word slot
+	// index — on byte-addressed chips doubled back into byte terms.
+	// program_flash refuses this one slot and the info block is addressed
+	// from it, so both follow wherever the code was flashed. The high byte is
+	// spelled as byteswap's low byte: the builtin's value is itself built by
+	// swapping the two stacked bytes, and the double swap folds to the single
+	// byte pick a hand assembler writes — `>> 8` leaves the swap materialized.
+	const std::uint16_t ra_words = reinterpret_cast<std::uint16_t>(__builtin_return_address(0));
+	const std::uint8_t ra_high = static_cast<std::uint8_t>(std::byteswap(ra_words));
+	const std::uint8_t slot_high = word_flash ? ra_high & 0xfe : static_cast<std::uint8_t>(ra_high << 1);
+
+	// The knock: 'p' then 'b', each under a fresh window; any other byte is
+	// line noise and waits again. Falling out of a window runs the app.
+	while (rx_deadline() != 'p' || rx_deadline() != 'b') {
+	}
+
+	for (;;) {
+		// No prompt while an EEPROM write runs: a pending write blocks SPM
+		// and fuse reads (§26.2.1), and the ack tells the host all is done.
+		ee::wait();
+		link::tx(ack);
+		const std::uint8_t command = link::rx();
+		switch (command) {
+		case 'b': { // info block, read relative to the running slot
+			// The block sits in the image's first 256 bytes (the build lint
+			// asserts it), and slots are 512-aligned — so the low byte of its
+			// link address (in wire units: bytes, or words on the large
+			// chips) is its offset in any slot, and the high byte of its
+			// runtime address is the running slot's. Composed from the two
+			// bytes — the high half is runtime data, so no absolute address
+			// is ever materialized.
+			const auto link_low = reinterpret_cast<std::uint16_t>(info_data.data());
+			const std::uint8_t low =
+			    word_flash ? static_cast<std::uint8_t>(link_low >> 1) : static_cast<std::uint8_t>(link_low);
+			send_flash(static_cast<std::uint16_t>(low | (slot_high << 8)), static_cast<std::uint8_t>(info_data.size()));
+			break;
+		}
+		case 'J': { // jump to a wire word address: hand-over and staging transfer
+			auto target = reinterpret_cast<void (*)()>(rx16());
+			link::tx(ack);
+			link::drain();
+			jump(target);
+		}
+		case 'R':   // read flash: addr16, n8 (0 = 256)
+		case 'r':   // read EEPROM: addr16, n8
+		case 'w': { // write EEPROM: addr16, n8, then n bytes each acked
+			std::uint16_t address = rx16();
+			std::uint8_t count = link::rx();
+			if (command == 'R')
+				send_flash(address, count);
+			else if (command == 'r')
+				send_eeprom(address, count);
+			else
+				store_eeprom(address, count);
+			break;
+		}
+		case 'W': // program one flash page: addr16, page bytes
+			program_flash(rx16(), slot_high);
+			break;
+		case 'F': // fuse and lock bytes
+			send_fuses();
+			break;
+		default: // unknown bytes are ignored; the loop re-acks
+			break;
+		}
+	}
+}
+
+} // namespace
+} // namespace pureboot
+
+template struct avr::startup::entry<pureboot::run>;

test/check_pi.py

@@ -0,0 +1,53 @@
+#!/usr/bin/env python3
+"""Position-independence lint for the pureboot image.
+
+The self-staging design lets the identical binary run from any 512-byte
+slot, which holds only if nothing in the image addresses itself absolutely.
+Two link-time facts guarantee it, both asserted here from the built ELF:
+
+  1. No absolute jmp/call opcodes — all control flow is PC-relative
+     (rjmp/rcall/ijmp/icall). -mrelax normally guarantees this; a code
+     change that grows a branch out of relaxation range would break it
+     silently.
+  2. The info block sits within the image's first 256 bytes: the 'b'
+     command rebuilds its address as (running slot high byte : low byte of
+     the link address), which needs the offset to fit that low byte.
+
+Usage: check_pi.py <objdump> <nm> <elf> <text_start_hex>
+"""
+
+import re
+import subprocess
+import sys
+
+
+def main():
+    objdump, nm, elf, text_start = sys.argv[1:]
+    text_start = int(text_start, 0)
+
+    listing = subprocess.run([objdump, "-d", elf], capture_output=True, text=True, check=True).stdout
+    absolute = [
+        line
+        for line in listing.splitlines()
+        if re.search(r"\t(jmp|call)\t", line)
+    ]
+    if absolute:
+        print("FAIL: absolute control flow in the image:")
+        print("\n".join(absolute))
+        sys.exit(1)
+
+    symbols = subprocess.run([nm, "-C", elf], capture_output=True, text=True, check=True).stdout
+    info = [line for line in symbols.splitlines() if "info_data" in line]
+    if len(info) != 1:
+        print(f"FAIL: expected one info-block storage symbol, found {len(info)}")
+        sys.exit(1)
+    offset = int(info[0].split()[0], 16) - text_start
+    if not 0 <= offset < 256:
+        print(f"FAIL: info block at image offset {offset:#x}, must sit in the first 256 bytes")
+        sys.exit(1)
+
+    print(f"PI lint: control flow PC-relative, info block at offset {offset:#x}")
+
+
+if __name__ == "__main__":
+    main()

test/check_size.cmake

@@ -4,9 +4,6 @@ if(NOT _res EQUAL 0)
 endif()
 # avr-size line 2 is "<text> <data> <bss> <dec> <hex> <file>".
 string(REGEX MATCH "\n[ \t]*([0-9]+)" _m "${_out}")
-if(NOT _m)
-	message(FATAL_ERROR "could not read a .text size out of ${SIZE_TOOL}'s output for ${ELF}:\n${_out}")
-endif()
 set(_text ${CMAKE_MATCH_1})
 if(_text GREATER LIMIT)
 	message(FATAL_ERROR ".text is ${_text} bytes, over the ${LIMIT}-byte boot section")

test/device.c

@@ -7,122 +7,103 @@
 // SPM genuinely writes avr->flash on the mega cores, so on exit (or SIGTERM)
 // we dump the flash image to a file for a ground-truth cross-check against
 // what the client read back through the bootloader.
-#include <array>
-#include <csignal>
-#include <cstdint>
-#include <cstdio>
-#include <cstdlib>
-#include <cstring>
-#include <print>
-
+#include <signal.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
 #include <unistd.h>
 
-// The parts headers (uart_pty.h) carry no C++ linkage guards of their own,
-// unlike simavr's core headers - the block covers both harmlessly.
-extern "C" {
 #include "avr_uart.h"
 #include "sim_avr.h"
 #include "sim_elf.h"
 #include "uart_pty.h"
-}
 
-namespace {
+static avr_t *avr;
+static uart_pty_t uart_pty;
+static const char *dump_path;
 
-avr_t *avr;
-uart_pty_t uart_pty;
-const char *dump_path;
-
-[[noreturn]] void finish(int)
+static void finish(int sig)
 {
+	(void)sig;
 	if (dump_path) {
-		std::FILE *f = std::fopen(dump_path, "wb");
+		FILE *f = fopen(dump_path, "wb");
 		if (f) {
-			std::fwrite(avr->flash, 1, avr->flashend + 1, f);
-			std::fclose(f);
+			fwrite(avr->flash, 1, avr->flashend + 1, f);
+			fclose(f);
 		}
 	}
 	uart_pty_stop(&uart_pty);
 	_exit(0);
 }
 
-} // namespace
-
 int main(int argc, char *argv[])
 {
 	if (argc < 3) {
-		std::println(stderr, "usage: {} <tsb.elf> <boot_base_hex> [flash_dump.bin]", argv[0]);
+		fprintf(stderr, "usage: %s <tsb.elf> <boot_base_hex> [flash_dump.bin]\n", argv[0]);
 		return 2;
 	}
-	auto boot_base = static_cast<std::uint32_t>(std::strtoul(argv[2], nullptr, 0));
-	dump_path = argc >= 4 ? argv[3] : nullptr;
+	uint32_t boot_base = (uint32_t)strtoul(argv[2], NULL, 0);
+	dump_path = argc >= 4 ? argv[3] : NULL;
 
 	avr = avr_make_mcu_by_name("atmega328p");
 	if (!avr) {
-		std::println(stderr, "device: no ATmega328P core");
+		fprintf(stderr, "device: no ATmega328P core\n");
 		return 1;
 	}
 	avr_init(avr);
 	avr->frequency = 16000000;
 	// Real flash powers up erased (0xff); the app region must look erased
 	// before the bootloader programs it.
-	std::memset(avr->flash, 0xff, avr->flashend + 1);
+	memset(avr->flash, 0xff, avr->flashend + 1);
 
 	// simavr's ELF loader flattens the flash base to 0 (it expects an app at
 	// 0x0), but it hands back the boot code in fw.flash; place it at the boot
 	// section base ourselves and enter there (BOOTRST is not modelled).
-	elf_firmware_t fw{};
+	elf_firmware_t fw = {0};
 	if (elf_read_firmware(argv[1], &fw) != 0) {
-		std::println(stderr, "device: cannot read {}", argv[1]);
+		fprintf(stderr, "device: cannot read %s\n", argv[1]);
 		return 1;
 	}
-	// An image that runs past flash end cannot execute on hardware, and a
-	// naive copy of it would smash the heap beyond avr->flash - after which
-	// the simulation misbehaves in ways that point everywhere but here.
-	// Refuse it loudly instead.
-	if (boot_base + fw.flashsize > avr->flashend + 1) {
-		std::println(stderr, "device: {} B at {:#x} runs past flash end {:#x} - image does not fit its slot",
-		             fw.flashsize, boot_base, avr->flashend);
-		return 1;
-	}
-	std::memcpy(avr->flash + boot_base, fw.flash, fw.flashsize);
+	memcpy(avr->flash + boot_base, fw.flash, fw.flashsize);
 	avr->pc = boot_base;
 	avr->codeend = avr->flashend;
 
 	// Optional: seed the config page (one page below the boot section) with a
 	// hex byte string, so the password gate and emergency erase can be tested.
 	// Layout: [appjump lo][appjump hi][timeout][password...][0xff].
-	const char *cfg = std::getenv("TSB_CONFIG");
+	const char *cfg = getenv("TSB_CONFIG");
 	if (cfg) {
-		std::uint32_t app_end = boot_base - 128; // config page sits directly below the boot code
+		uint32_t app_end = boot_base - 128; // config page sits directly below the boot code
 		for (int i = 0; cfg[i] && cfg[i + 1]; i += 2) {
-			const std::array pair{cfg[i], cfg[i + 1], '\0'};
-			avr->flash[app_end + i / 2] = static_cast<std::uint8_t>(std::strtoul(pair.data(), nullptr, 16));
+			char b[3] = {cfg[i], cfg[i + 1], 0};
+			avr->flash[app_end + i / 2] = (uint8_t)strtoul(b, NULL, 16);
 		}
 	}
 
 	// POLL_SLEEP makes simavr usleep(1) on every status-register read while the
-	// UART is idle - a host-CPU-saving hack that models no hardware and paces a
+	// UART is idle — a host-CPU-saving hack that models no hardware and paces a
 	// tight-polling loader (one that releases TX between bytes, as one-wire does)
 	// in real time, distorting protocol timing. Clear it so the loader runs at
 	// true cycle speed.
-	std::uint32_t uflags = 0;
+	uint32_t uflags = 0;
 	avr_ioctl(avr, AVR_IOCTL_UART_GET_FLAGS('0'), &uflags);
 	uflags &= ~AVR_UART_FLAG_POLL_SLEEP;
 	avr_ioctl(avr, AVR_IOCTL_UART_SET_FLAGS('0'), &uflags);
 
 	uart_pty_init(avr, &uart_pty);
 	uart_pty_connect(&uart_pty, '0');
-	std::println("TSB_PTY {}", uart_pty.pty.slavename);
-	std::fflush(stdout);
+	printf("TSB_PTY %s\n", uart_pty.pty.slavename);
+	fflush(stdout);
 
-	std::signal(SIGTERM, finish);
-	std::signal(SIGINT, finish);
+	signal(SIGTERM, finish);
+	signal(SIGINT, finish);
 
 	for (;;) {
 		int state = avr_run(avr);
-		if (state == cpu_Done || state == cpu_Crashed) {
+		if (state == cpu_Done || state == cpu_Crashed)
 			break;
-		}
 	}
 	finish(0);
+	return 0;
 }

test/pbapp.cpp

@@ -0,0 +1,106 @@
+// Test-fixture application for the pureboot protocol tests: prints "APP" on
+// the chip's serial link (the same link the loader uses) — the proof that
+// the loader's hand-over, and on the tinies the host's reset-vector
+// surgery, actually launched it. Linked normally (crt, vectors at 0); on
+// the tinies its reset vector is the rjmp the host re-homes.
+//
+// On the hardware-USART link it then listens, and an 'L' makes it jump into
+// the resident loader — the application-owned loader entry a
+// BOOTRST-unprogrammed mega relies on (reset always boots the application
+// there), exercised by the self-update tests. The software link idles:
+// reset reaches those loaders through the patched vector (or the runner
+// models BOOTRST), so the application owes them nothing.
+//
+// The fixture speaks the deployment its loader was built for: the same
+// PUREBOOT_* defines configure it, and without them it assumes the stock
+// deployment (the crystal/RC clock table below, the chip's natural link).
+#include <libavr/libavr.hpp>
+
+using namespace avr::literals;
+
+namespace {
+
+consteval avr::hertz_t clock()
+{
+#if defined(PUREBOOT_CLOCK_HZ)
+	return avr::hertz_t{PUREBOOT_CLOCK_HZ};
+#else
+	auto name = std::string_view{avr::hw::db.name};
+	if (name.starts_with("ATtiny13"))
+		return 9.6_MHz;
+	if (name.starts_with("ATtiny"))
+		return 8_MHz;
+	return 16_MHz;
+#endif
+}
+
+#if !defined(PUREBOOT_TX)
+#define PUREBOOT_TX pb1
+#endif
+#if !defined(PUREBOOT_USART)
+#define PUREBOOT_USART 0
+#endif
+
+consteval bool use_hardware()
+{
+#if defined(PUREBOOT_SOFT_SERIAL)
+	return false;
+#else
+	return avr::hw::db.has_instance("USART0") || avr::hw::db.has_instance("USART");
+#endif
+}
+
+using dev = avr::device<{.clock = clock()}>;
+
+template <avr::hertz_t C, bool Hardware = use_hardware()>
+struct link {
+#if defined(PUREBOOT_BAUD)
+	static constexpr avr::baud_t baud{PUREBOOT_BAUD};
+#else
+	static constexpr avr::baud_t baud{115200};
+#endif
+	using tx_t = avr::uart::usart<'0' + PUREBOOT_USART, C, {.baud = baud, .max_baud_error = 2.5_pct}>;
+	static void tx(char c)
+	{
+		tx_t::write(static_cast<std::uint8_t>(c));
+	}
+	[[noreturn]] static void idle()
+	{
+		// 'L' hands back to the loader at the top slot — 512 bytes, or the
+		// 1 KiB the >64 KiB chips use.
+		constexpr std::uint32_t slot = avr::hw::db.mem.flash_size > 65536 ? 1024 : 512;
+		for (;;)
+			if (tx_t::read_blocking() == 'L')
+				reinterpret_cast<void (*)()>(static_cast<std::uint16_t>((avr::hw::db.mem.flash_size - slot) / 2))();
+	}
+};
+
+template <avr::hertz_t C>
+struct link<C, false> {
+#if defined(PUREBOOT_BAUD)
+	static constexpr avr::baud_t baud{PUREBOOT_BAUD};
+#else
+	static constexpr avr::baud_t baud{57600};
+#endif
+	using tx_t = avr::uart::software_tx<C, avr::PUREBOOT_TX, baud>;
+	static void tx(char c)
+	{
+		tx_t::write(static_cast<std::uint8_t>(c));
+	}
+	[[noreturn]] static void idle()
+	{
+		while (true) {
+		}
+	}
+};
+
+} // namespace
+
+int main()
+{
+	avr::init<typename link<dev::clock>::tx_t>();
+	link<dev::clock>::tx('A');
+	link<dev::clock>::tx('P');
+	link<dev::clock>::tx('P');
+	link<dev::clock>::idle();
+}

test/pbrehome.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+"""Re-homing acceptance test: a pureboot image programmed somewhere other
+than its canonical top slot must still be a working loader —
+position-independent, guarding its accidental slot — and the ordinary
+--update-loader flow must put a build into the top slot from there.
+
+Two positions are exercised. Address 0 (a raw .bin handed to a programmer,
+which defaults to offset 0): the staging install and the word-0 redirect
+both run from copies whose slots are not page 0's, so the running-slot
+guard never blocks the flow. The staging slot itself: a loader already
+sitting there IS the installed staging copy — the tool recognizes it by
+its embedded info block and leaves it in place instead of tripping the
+copy's own guard on the composed through-word — and that (older) copy
+streams the new resident like any staged copy. In both cases flashing an
+application through the healed resident overwrites the stale copy, vector
+surgery included, and the banner proves the launch.
+
+Usage: pbrehome.py <device_bin> <pureboot_elf> <update_bin> <mcu> <hz>
+                   <base_hex> <page> <baud> <app_bin> <tool_py> <workdir>
+"""
+
+import os
+import sys
+
+
+def fail(message):
+    print(f"FAIL: {message}")
+    sys.exit(1)
+
+
+def rehome_from(pbsim, pb, device_bin, elf, place_hex, guard_probe, update_bin, base, page, baud, app_bin, workdir,
+                mcu, hz):
+    """Place the loader at `place_hex`, heal through --update-loader, flash
+    the application, expect the banner."""
+    dump = os.path.join(workdir, f"dump-{place_hex}.bin")
+    state = os.path.join(workdir, f"rehome-{place_hex}.pbstate")
+    if os.path.exists(state):
+        os.unlink(state)
+    device = pbsim.Device(device_bin, elf, mcu, hz, place_hex, page, baud, dump, reset_hex="0")
+    try:
+        port = pb.Port(device.pty, baud)
+        loader = pb.Loader(port)
+        info = loader.connect(25)
+        if info.base != base:
+            fail(f"the misplaced copy reports base {info.base:#06x} — the info block must stay canonical")
+
+        # The accidental slot still guards itself; re-homing rides on the
+        # canonical slots being writable from it.
+        probe = int(guard_probe, 0)
+        before = loader.read_flash(probe, info.page)
+        loader.write_page(probe, bytes(info.page))
+        if loader.read_flash(probe, info.page) != before:
+            fail("the misplaced copy's guard let its own slot change")
+
+        # The ordinary update flow puts the build into the top slot.
+        pb.op_update_loader(loader, 25, update_bin, state, None)
+        update = open(update_bin, "rb").read()
+        if loader.read_flash(base, len(update)) != update:
+            fail("the canonical slot does not hold the update image")
+
+        # An application flashed through the healed resident overwrites the
+        # stale copy (surgery included) and launches.
+        pages = pb.plan_flash(open(app_bin, "rb").read(), loader.info)
+        for address in pb.covered(pages, loader.info, skip_blank=False):
+            loader.write_page(address, pages[address])
+        pb.verify_pages(loader, pages)
+        loader.run_application()
+        if port.read_exact(3, 5.0) != b"APP":
+            fail(f"application does not banner after the re-home from {place_hex}")
+        port.close()
+    finally:
+        device.stop()
+
+
+def main():
+    (device_bin, elf, update_bin, mcu, hz, base_hex, page, baud, app_bin, tool, workdir) = sys.argv[1:]
+    base, page, baud = int(base_hex, 0), int(page), int(baud)
+    sys.path.insert(0, os.path.dirname(os.path.abspath(tool)))
+    sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+    import pbsim
+    import pureboot as pb
+
+    os.makedirs(workdir, exist_ok=True)
+
+    # Address 0: the raw-.bin-to-a-programmer accident. The guard probe is
+    # the copy's own page 0.
+    rehome_from(pbsim, pb, device_bin, elf, "0x0", "0x0", update_bin, base, page, baud, app_bin, workdir, mcu, hz)
+    print("re-home from address 0: converged")
+
+    # The staging slot: erased flash with the loader sitting exactly where
+    # a staging copy would — the tool must leave it in place and let it
+    # stream the (different) update build into the resident slot.
+    stage = base - 512
+    rehome_from(pbsim, pb, device_bin, elf, hex(stage), hex(stage), update_bin, base, page, baud, app_bin, workdir,
+                mcu, hz)
+    print("re-home from the staging slot: converged")
+
+    print("pbrehome: a misplaced loader re-homes through the ordinary update flow")
+
+
+if __name__ == "__main__":
+    main()

test/pbreloc.py

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+"""Position-independence acceptance test: the identical pureboot binary,
+flashed one slot below the resident loader, must serve the complete command
+set from there. The resident installs it (through-word composed by the host
+layer), 'J' transfers control, and every command is exercised against the
+staged copy — the info block must come back byte-identical, the write guard
+must protect the staged copy's own slot and permit the resident's, and the
+staged copy must be able to rewrite the resident slot verbatim.
+
+Usage: pbreloc.py <device_bin> <pureboot_elf> <mcu> <hz> <base_hex> <page>
+                  <baud> <tool_py> <workdir>
+"""
+
+import os
+import subprocess
+import sys
+
+
+def fail(message):
+    print(f"FAIL: {message}")
+    sys.exit(1)
+
+
+def main():
+    device_bin, elf, mcu, hz, base_hex, page, baud, tool, workdir = sys.argv[1:]
+    base, page, baud = int(base_hex, 0), int(page), int(baud)
+    stage = None  # derived from the device's own info (slot-sized) below
+    sys.path.insert(0, os.path.dirname(os.path.abspath(tool)))
+    sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+    import pbsim
+    import pureboot as pb
+
+    os.makedirs(workdir, exist_ok=True)
+    objcopy = os.environ.get("PB_OBJCOPY", "avr-objcopy")
+    image_path = os.path.join(workdir, "pureboot.bin")
+    subprocess.run([objcopy, "-O", "binary", elf, image_path], check=True)
+    image = open(image_path, "rb").read()
+
+    device = pbsim.Device(device_bin, elf, mcu, hz, base_hex, page, baud, os.path.join(workdir, "dump.bin"))
+    try:
+        port = pb.Port(device.pty, baud)
+        loader = pb.Loader(port)
+        info = loader.connect(25)
+        if info.base != base:
+            fail(f"info reports base {info.base:#06x}")
+        resident_info = info.raw
+
+        # Install the staging copy exactly as the update flow would.
+        stage = info.stage
+        staged = pb.staging_content(image, info)
+        pb.write_differing(loader, stage, staged)
+
+        # Enter it; from here on, every command runs in the relocated copy.
+        staged_info = loader.enter_copy(stage, 25)
+        if staged_info.raw != resident_info:
+            fail(f"staged info {staged_info.raw.hex()} != resident info {resident_info.hex()}")
+
+        # 'R' from the staged copy already proved itself in the install
+        # verify; 'F' must answer 4 bytes (values are unmodeled in simavr).
+        if len(loader.read_fuses()) != 4:
+            fail("fuse read from the staged copy")
+
+        # EEPROM round-trip through the staged copy.
+        pattern = bytes(range(0x50, 0x60))
+        loader.write_eeprom(0, pattern)
+        if loader.read_eeprom(0, len(pattern)) != pattern:
+            fail("EEPROM round-trip through the staged copy")
+
+        # The guard, both ways: its own slot refused (drained, unchanged),
+        # the resident slot writable.
+        before = loader.read_flash(stage, page)
+        loader.write_page(stage, bytes(page))
+        if loader.read_flash(stage, page) != before:
+            fail("the staged copy's guard let its own slot change")
+        marker = bytes((i * 3) & 0xFF for i in range(page))
+        loader.write_page(base, marker)
+        if loader.read_flash(base, page) != marker:
+            fail("the staged copy could not write the resident slot")
+
+        # Restore the resident image through the staged copy, then 'J' back
+        # into it and prove it lives.
+        resident = image + b"\xff" * (info.slot - len(image))
+        pb.write_differing(loader, base, resident)
+        back_info = loader.enter_copy(base, 25)
+        if back_info.raw != resident_info:
+            fail("the restored resident does not serve its info block")
+        port.close()
+    finally:
+        device.stop()
+    print("pbreloc: the relocated copy serves the full command set")
+
+
+if __name__ == "__main__":
+    main()

test/pbsim.py

@@ -0,0 +1,68 @@
+"""Shared simavr harness for the pureboot tests: spawn the device runner,
+hand out its pty, restart it from a flash dump (the power-fail path), and
+keep its chatter out of undrained pipes."""
+
+import os
+import signal
+import subprocess
+
+
+class Device:
+    def __init__(self, binary, elf, mcu, hz, base_hex, page, baud, dump, reset_hex=None, resume=None, link=None):
+        cmd = [binary]
+        if link:
+            cmd += ["-l", link]
+        cmd += [elf, mcu, hz, base_hex, str(page), str(baud), dump]
+        if reset_hex is not None or resume is not None:
+            # Chips without a hardware boot section — the tinies and the
+            # m48s — reset to address 0 like silicon; the boot-sectioned
+            # megas re-vector to the loader base (BOOTRST).
+            patch = not mcu.startswith("atmega") or mcu.startswith("atmega48")
+            cmd.append(reset_hex if reset_hex is not None else ("0" if patch else base_hex))
+        if resume is not None:
+            cmd.append(resume)
+        self.log = open(dump + ".log", "a")
+        self.proc = subprocess.Popen(cmd, stdout=subprocess.PIPE, stderr=self.log, text=True)
+        self.dump = dump
+        self.pty = None
+        for _ in range(50):
+            line = self.proc.stdout.readline()
+            if not line:
+                break
+            if line.startswith("PB_PTY"):
+                self.pty = line.split()[1]
+                break
+        if not self.pty:
+            self.stop()
+            raise RuntimeError("device did not report a pty")
+
+    def reset(self):
+        """The external reset line: SIGUSR1 re-enters at the reset vector."""
+        self.proc.send_signal(signal.SIGUSR1)
+
+    def power_fail(self):
+        """SIGTERM: the runner dumps its flash and exits — the image a
+        restart resumes from."""
+        self.stop()
+        return self.dump
+
+    def stop(self):
+        self.proc.terminate()
+        try:
+            self.proc.wait(timeout=5)
+        except subprocess.TimeoutExpired:
+            self.proc.kill()
+        self.log.close()
+
+
+def run_tool(tool, pty, baud, *args, timeout=180):
+    result = subprocess.run(
+        [os.environ.get("PYTHON", "python3"), tool, "--port", pty, "--baud", str(baud), "--wait", "25", *args],
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+    )
+    print(result.stdout, end="")
+    if result.returncode != 0:
+        raise RuntimeError(f"tool exited {result.returncode}: {result.stderr.strip()}")
+    return result.stdout

test/pbtest.py

@@ -0,0 +1,144 @@
+#!/usr/bin/env python3
+"""End-to-end pureboot protocol test: spawn the simavr device, then drive it
+with the real host tool (pureboot.py, as a subprocess over the device's pty)
+through flash + EEPROM + fuse + hand-over scenarios, and cross-check
+the tool's view against the simulator's ground-truth memory dumps.
+
+Usage: pbtest.py <device_bin> <pureboot_elf> <mcu> <hz> <base_hex> <page>
+                 <baud> <eeprom_size> <app_bin> <tool_py> <workdir> [link]
+
+The optional link is the runner's -l spec (usart1, sw:B5,B1, ...) for a
+loader built off the chip's natural serial default.
+Exits 0 if every scenario passes.
+"""
+
+import os
+import sys
+
+
+def fail(message):
+    print(f"FAIL: {message}")
+    sys.exit(1)
+
+
+def rjmp_decode(word, at, flash_words):
+    """Where an rjmp word at word-address `at` lands — deliberately written
+    against the instruction-set definition (12-bit signed offset), not with
+    the host tool's encoder, so an encoding bug cannot verify itself."""
+    if word & 0xF000 != 0xC000:
+        fail(f"word at {at * 2:#06x} is {word:#06x}, not an rjmp")
+    offset = word & 0x0FFF
+    if offset >= 0x800:
+        offset -= 0x1000
+    return (at + 1 + offset) % flash_words
+
+
+def main():
+    args = sys.argv[1:]
+    link = args.pop() if len(args) == 12 else None
+    (device_bin, elf, mcu, hz, base_hex, page, baud, eeprom_size, app_bin, tool, workdir) = args
+    base, page, baud, eeprom_size = int(base_hex, 0), int(page), int(baud), int(eeprom_size)
+    sys.path.insert(0, os.path.dirname(os.path.abspath(tool)))
+    sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+    import pbsim
+    import pureboot as pb
+
+    os.makedirs(workdir, exist_ok=True)
+    ee_image = bytes(range(0xA0, 0xB0))
+    ee_path = os.path.join(workdir, "ee.bin")
+    open(ee_path, "wb").write(ee_image)
+    dump = os.path.join(workdir, "flash_dump.bin")
+    read_flash = os.path.join(workdir, "readback_flash.bin")
+    read_eeprom = os.path.join(workdir, "readback_eeprom.bin")
+
+    # The geometry the host will discover, for computing the expected image:
+    # the boot-sectioned megas need no vector surgery (the tinies and the
+    # boot-section-less m48s do), the large chips speak word addresses, and
+    # the page byte is the wire's 0-means-256.
+    mega = mcu.startswith("atmega")
+    patch = not mega or mcu.startswith("atmega48")
+    word_flash = base + 512 > 0x10000
+    wire_base = base // 2 if word_flash else base
+    flags = (1 if patch else 0) | (2 if word_flash else 0)
+    info = pb.Info(
+        bytes([ord("P"), ord("B"), 1, 0, 0, 0, page & 0xFF])
+        + bytes([wire_base & 0xFF, wire_base >> 8, eeprom_size & 0xFF, eeprom_size >> 8])
+        + bytes([flags])
+    )
+
+    device = pbsim.Device(device_bin, elf, mcu, hz, base_hex, page, baud, dump, link=link)
+    try:
+        # Session 1: knock from reset, identify, program everything, stay.
+        out = pbsim.run_tool(tool, device.pty, baud, "--info", "--fuses", "--flash", app_bin,
+                             "--eeprom", ee_path, "--stay")
+        for needed in ("signature", "fuses", "verify:", "stays"):
+            if needed not in out:
+                fail(f"session 1 output lacks {needed!r}")
+
+        # Session 2: reconnect into the live session, verify, dump, hand over
+        # is deferred — the pty must be reopened for the APP banner first.
+        out = pbsim.run_tool(tool, device.pty, baud, "--verify-flash", app_bin, "--verify-eeprom", ee_path,
+                             "--read-flash", read_flash, "--read-eeprom", read_eeprom, "--stay")
+        if out.count("verify:") != 2:
+            fail("session 2 did not verify both memories")
+
+        eeprom_back = open(read_eeprom, "rb").read()
+        if eeprom_back[: len(ee_image)] != ee_image:
+            fail("EEPROM read-back mismatch")
+
+        # The expected post-surgery flash, straight from the tool's planner.
+        pages = pb.plan_flash(open(app_bin, "rb").read(), info)
+        flash_back = open(read_flash, "rb").read()
+        for address, data in pages.items():
+            if flash_back[address : address + page] != data:
+                fail(f"flash read-back mismatch in page {address:#06x}")
+
+        # An external reset re-enters through the patched word 0 (tinies; the
+        # runner resets them to address 0 like silicon) or BOOTRST (mega).
+        # The loader must answer a fresh knock, and the 'J' hand-over must
+        # land in the application, which banners on the same link.
+        device.reset()
+        port = pb.Port(device.pty, baud)
+        try:
+            loader = pb.Loader(port)
+            loader.connect(15)
+            loader.run_application()
+            banner = port.read_exact(3, 5.0)
+            if banner != b"APP":
+                fail(f"application banner was {banner!r}")
+        finally:
+            port.close()
+    finally:
+        device.stop()
+
+    # Ground truth: the simulator's own memories, against the host's view.
+    flash_true = open(dump, "rb").read()
+    if flash_true[:base] != flash_back:
+        fail("host flash read-back differs from the simulator's flash")
+    if flash_true[base] == 0xFF and flash_true[base + 1] == 0xFF:
+        fail("loader region looks erased in the ground-truth dump")
+
+    # The surgery, decoded independently: the patched vector must land on the
+    # loader, the trampoline on the application's own entry (patched-vector
+    # chips only — a boot-sectioned mega's word 0 stays the application's).
+    if patch:
+        flash_words = (base + 512) // 2
+        app = open(app_bin, "rb").read()
+        word0 = flash_true[0] | (flash_true[1] << 8)
+        if rjmp_decode(word0, 0, flash_words) != base // 2:
+            fail("patched reset vector does not land on the loader base")
+        trampoline = flash_true[base - 2] | (flash_true[base - 1] << 8)
+        original = app[0] | (app[1] << 8)
+        if rjmp_decode(trampoline, (base - 2) // 2, flash_words) != rjmp_decode(original, 0, flash_words):
+            fail("trampoline does not land on the application's own entry")
+    ee_true_path = dump + ".eeprom"
+    if os.path.exists(ee_true_path):
+        ee_true = open(ee_true_path, "rb").read()
+        if ee_true[: len(ee_image)] != ee_image:
+            fail("ground-truth EEPROM does not match what was programmed")
+
+    print("pbtest: all scenarios pass")
+
+
+if __name__ == "__main__":
+    main()

test/pbupdate.py

@@ -0,0 +1,230 @@
+#!/usr/bin/env python3
+"""Self-update end-to-end: an application is flashed, then the loader
+replaces itself with a re-timed build through the host tool's
+--update-loader — and the power-fail phases of that update are rehearsed by
+killing the simulated device mid-write, restarting it from its flash dump,
+and letting a re-run complete the update.
+
+The boot-sectioned megas run the BOOTRST-unprogrammed profile (reset boots
+the application; the fixture application's 'L' jump is the application-owned
+loader entry), with --assume-fuses standing in for the fuse read simavr
+cannot model. The patched-vector chips — the tinies and the m48s — reset
+into a loader at every phase by construction: the t13a because its staging
+slot carries the reset vector itself, the others through the word-0 redirect
+the tool plants around the resident rewrite.
+
+Usage: pbupdate.py <device_bin> <pureboot_elf> <update_elf> <mcu> <hz>
+                   <base_hex> <page> <baud> <app_bin> <tool_py> <workdir>
+"""
+
+import os
+import subprocess
+import sys
+
+
+def fail(message):
+    print(f"FAIL: {message}")
+    sys.exit(1)
+
+
+def rjmp_decode(word, at, flash_words):
+    """Written against the instruction-set definition, not with the tool's
+    encoder, so an encoding bug cannot verify itself."""
+    if word & 0xF000 != 0xC000:
+        fail(f"word at {at * 2:#06x} is {word:#06x}, not an rjmp")
+    offset = word & 0x0FFF
+    if offset >= 0x800:
+        offset -= 0x1000
+    return (at + 1 + offset) % flash_words
+
+
+class PowerFail(Exception):
+    pass
+
+
+def assumed_fuses(pb, image):
+    """Synthetic 'F' bytes for --assume-fuses: the smallest boot section
+    covering both the resident and the staging slot (two slots — what a
+    self-update needs), BOOTRST unprogrammed — the per-chip BOOTSZ ladder
+    and fuse byte come from the tool's own table, keyed by the update
+    image's embedded signature."""
+    info = pb.image_info(image)
+    which, ladder = pb.BOOT_FUSE[bytes(info.signature[1:3])]
+    bits = min((b for b in ladder if ladder[b] * 2 >= 2 * info.slot), key=lambda b: ladder[b])
+    fuses = bytearray((0xFF, 0xFF, 0xFF, 0xFF))
+    fuses[which] = 0xF8 | (bits << 1) | 1
+    return bytes(fuses)
+
+
+def make_fault_loader(pb, base, slot, kill_region, kill_hits, device):
+    """A Loader whose write_page kills the device (or, with device=None,
+    just the host) at the Nth write into a region; the sequence
+    stage->resident->stage distinguishes the install from the restore."""
+
+    class FaultLoader(pb.Loader):
+        def __init__(self, port):
+            super().__init__(port)
+            self.seen_resident = False
+            self.hits = 0
+
+        def write_page(self, address, data):
+            if address >= base:
+                phase = "resident"
+                self.seen_resident = True
+            elif address >= base - slot:
+                phase = "stage_restore" if self.seen_resident else "stage"
+            else:
+                phase = "app"
+            if phase == kill_region:
+                self.hits += 1
+                if self.hits == kill_hits:
+                    if device is not None:
+                        device.power_fail()
+                    raise PowerFail(f"{kill_region} write {kill_hits}")
+            super().write_page(address, data)
+
+    return FaultLoader
+
+
+def main():
+    (device_bin, elf, update_elf, mcu, hz, base_hex, page, baud, app_bin, tool, workdir) = sys.argv[1:]
+    base, page, baud = int(base_hex, 0), int(page), int(baud)
+    mega = mcu.startswith("atmega")
+    # The m48s are megas without a boot section: patched vector, no fuse
+    # preflight, and the same reset-to-0 the tinies get.
+    patch = not mega or mcu.startswith("atmega48")
+    # Word-addressed (>64 KiB) chips use the 1 KiB slot; their loader base
+    # itself sits beyond the 16-bit byte space — the 644's base + slot only
+    # touches the 64 KiB boundary and stays byte-addressed.
+    slot = 1024 if base >= 0x10000 and mega else 512
+    reset_hex = "0" if mega else None  # the boot-sectioned mega runs BOOTRST-unprogrammed here
+    sys.path.insert(0, os.path.dirname(os.path.abspath(tool)))
+    sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+    import pbsim
+    import pureboot as pb
+
+    os.makedirs(workdir, exist_ok=True)
+    objcopy = os.environ.get("PB_OBJCOPY", "avr-objcopy")
+    images = {}
+    for name, source in (("v0", elf), ("v9", update_elf)):
+        path = os.path.join(workdir, name + ".bin")
+        subprocess.run([objcopy, "-O", "binary", source, path], check=True)
+        images[name] = open(path, "rb").read()
+    if images["v0"] == images["v9"]:
+        fail("the update image is byte-identical to the resident build")
+    dump = os.path.join(workdir, "dump.bin")
+    state = os.path.join(workdir, "update.pbstate")
+    fuses = assumed_fuses(pb, images["v0"]) if mega and not patch else None
+
+    def connect(device):
+        port = pb.Port(device.pty, baud)
+        if mega:
+            # Reset boots the application here; its 'L' is the loader entry.
+            # To a live loader the same byte is an ignored command.
+            port.read_available(0.5)
+            port.write(b"L")
+        loader = pb.Loader(port)
+        loader.connect(25)
+        return port, loader
+
+    def padded(image):
+        return image + b"\xff" * (slot - len(image))
+
+    def resident_bytes(loader):
+        return loader.read_flash(base, slot)
+
+    def assert_state(loader, image, app_pages):
+        if resident_bytes(loader) != padded(image):
+            fail("resident loader does not match the update image")
+        stage = base - slot
+        got = loader.read_flash(stage, slot)
+        for address, data in app_pages.items():
+            if stage <= address < base:
+                if got[address - stage : address - stage + page] != data:
+                    fail(f"staging region page {address:#06x} not restored")
+
+    device = pbsim.Device(device_bin, elf, mcu, hz, base_hex, page, baud, dump, reset_hex=reset_hex)
+    final = "v0"
+    try:
+        # The application first — its planner output is the restore truth.
+        pbsim.run_tool(tool, device.pty, baud, "--flash", app_bin, "--stay")
+        port, loader = connect(device)
+        app_pages = pb.plan_flash(open(app_bin, "rb").read(), loader.info)
+        port.close()
+
+        # A clean CLI update, resident -> v9.
+        args = ["--update-loader", os.path.join(workdir, "v9.bin"), "--state", state, "--stay"]
+        if fuses:
+            args += ["--assume-fuses", fuses.hex()]
+        out = pbsim.run_tool(tool, device.pty, baud, *args)
+        if "loader updated" not in out:
+            fail("update did not report success")
+        if os.path.exists(state):
+            fail("state file survived a completed update")
+        port, loader = connect(device)
+        assert_state(loader, images["v9"], app_pages)
+        loader.run_application()
+        if port.read_exact(3, 5.0) != b"APP":
+            fail("application does not banner after the update")
+        port.close()
+        final = "v9"
+        print("clean update: resident replaced, staging restored, application intact")
+
+        # Power-fail rehearsal: kill mid-phase, restart from the dump,
+        # re-run, and the update must still complete. Each round flips the
+        # direction so the flash is never already at its target. The mega's
+        # mid-resident-rewrite loss is exercised as a host crash instead:
+        # with BOOTRST unprogrammed and the resident mid-erase, a power loss
+        # there has no reset path into the staging copy — the documented
+        # cost of that profile (README).
+        for kill_region, kill_hits, kill_device in (
+            ("stage", 2, True),
+            ("resident", 1, patch),
+            ("stage_restore", 2, True),
+        ):
+            device.reset()  # the previous round left the application running
+            port, loader = connect(device)
+            target = "v9" if resident_bytes(loader) == padded(images["v0"]) else "v0"
+            image_path = os.path.join(workdir, target + ".bin")
+            injected = make_fault_loader(pb, base, slot, kill_region, kill_hits, device if kill_device else None)(port)
+            injected.info = loader.info
+            try:
+                pb.op_update_loader(injected, 25, image_path, state, fuses)
+                fail(f"{kill_region}: fault never triggered")
+            except PowerFail as event:
+                print(f"power fail injected: {event}")
+            port.close()
+            if kill_device:
+                device = pbsim.Device(device_bin, elf, mcu, hz, base_hex, page, baud, dump,
+                                      reset_hex=reset_hex, resume=dump)
+            port, loader = connect(device)
+            pb.op_update_loader(loader, 25, image_path, state, fuses)
+            assert_state(loader, images[target], app_pages)
+            loader.run_application()
+            if port.read_exact(3, 5.0) != b"APP":
+                fail(f"{kill_region}: application lost after the resumed update")
+            port.close()
+            final = target
+            print(f"resumed after {kill_region} loss: update completed, application intact")
+    finally:
+        device.stop()
+
+    # Ground truth: the simulator's own flash against the final state, and
+    # on the patched-vector chips an independent decode of the reset routing.
+    flash = open(dump, "rb").read()
+    if flash[base : base + slot] != padded(images[final]):
+        fail("ground-truth resident region does not match the final image")
+    if patch:
+        flash_words = (base + slot) // 2
+        word0 = flash[0] | (flash[1] << 8)
+        if rjmp_decode(word0, 0, flash_words) != base // 2:
+            fail("ground-truth reset vector does not land on the loader")
+        app = open(app_bin, "rb").read()
+        trampoline = flash[base - 2] | (flash[base - 1] << 8)
+        if rjmp_decode(trampoline, (base - 2) // 2, flash_words) != rjmp_decode(app[0] | (app[1] << 8), 0, flash_words):
+            fail("ground-truth trampoline does not land on the application entry")
+    print("pbupdate: clean update + all power-fail phases recovered")
+
+
+if __name__ == "__main__":
+    main()

test/pureboot_device.c

@@ -0,0 +1,461 @@
+// simavr "device" for the pureboot protocol tests, every chip. Loads the
+// boot-linked ELF at the loader base, starts execution there (BOOTRST / the
+// patched vector are not what is under test), and exposes the loader's
+// serial link as a pty for the real host tool:
+//
+//   - Hardware USART builds: simavr's uart_pty on the selected instance.
+//   - Software UART builds: an 8N1 bridge between a pty and the GPIO pins,
+//     timed against the simulated cycle counter (drives the loader's RX,
+//     decodes its TX).
+//
+// The link follows the chip's natural default (USART0 on the megas, the
+// software UART on PB0/PB1 elsewhere) unless -l overrides it: `-l usart1`
+// for the second instance, `-l sw:B5,B1` for a software build's RX,TX pins.
+//
+// simavr's tiny cores decode the SPM opcode but attach no NVM module — SPM
+// is a silent no-op (the mega's boot section has one, avr_flash). The
+// missing module is supplied here: the SPM ioctl reads SPMCSR/Z/r1:r0 and
+// implements buffer fill, page erase, page write, and CTPB, completing
+// instantly. RFLB's LPM diversion (fuse readout) stays unmodeled, so the
+// 'F' command answers with flash bytes — the tests assert transport only.
+//
+// On exit (or SIGTERM) the flash and EEPROM are dumped to files for a
+// ground-truth cross-check against what the host read back.
+#include <fcntl.h>
+#include <pty.h>
+#include <signal.h>
+#include <stdint.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <termios.h>
+#include <unistd.h>
+
+#include "avr_eeprom.h"
+#include "avr_flash.h"
+#include "avr_ioport.h"
+#include "avr_uart.h"
+#include "sim_avr.h"
+#include "sim_elf.h"
+#include "sim_io.h"
+#include "uart_pty.h"
+
+static avr_t *avr;
+static uart_pty_t uart_pty;
+static int link_software;
+static char uart_digit = '0';
+static char sw_rx_port = 'B', sw_tx_port = 'B';
+static int sw_rx_bit = 0, sw_tx_bit = 1;
+static const char *dump_path;
+static uint32_t reset_pc;
+static volatile sig_atomic_t reset_requested;
+
+static int parse_link(const char *spec)
+{
+	if (strcmp(spec, "usart0") == 0 || strcmp(spec, "usart1") == 0) {
+		link_software = 0;
+		uart_digit = spec[5];
+		return 0;
+	}
+	if (strncmp(spec, "sw", 2) == 0) {
+		link_software = 1;
+		if (spec[2] == '\0')
+			return 0;
+		if (sscanf(spec + 2, ":%c%d,%c%d", &sw_rx_port, &sw_rx_bit, &sw_tx_port, &sw_tx_bit) == 4)
+			return 0;
+	}
+	return -1;
+}
+
+// simavr 1.6's avr_flash PGERS handler erases spm_pagesize bytes starting at
+// Z & ~1 instead of the page containing Z (its PGWRT path masks correctly) —
+// hardware ignores the in-page bits (§26.8.1), so an erase issued with Z
+// anywhere inside the page wipes half the neighbouring page in simulation
+// only. Wrap the mega's registered flash ioctl and re-dispatch page erases
+// with Z forced to the page boundary; everything else passes through.
+//
+// A second gap on the boot-section-less m48s: their RWWSRE bit is the
+// temporary-buffer discard (Atmel-8271 §26.2/§26.3.1), but the stock model
+// gates its RWWSRE branch on AVR_SELFPROG_HAVE_RWW — absent on the m48
+// core — so the discard store falls through into the buffer-fill branch and
+// plants whatever Z/R1:R0 happen to hold. Perform the silicon's discard
+// here instead.
+static avr_flash_t *mega_flash;
+static int (*mega_flash_ioctl)(avr_io_t *io, uint32_t ctl, void *param);
+
+static int fixed_flash_ioctl(avr_io_t *io, uint32_t ctl, void *param)
+{
+	if (ctl == AVR_IOCTL_FLASH_SPM && avr_regbit_get(io->avr, mega_flash->pgers)) {
+		uint16_t z = (uint16_t)(io->avr->data[30] | (io->avr->data[31] << 8));
+		uint16_t masked = (uint16_t)(z & ~(mega_flash->spm_pagesize - 1));
+		io->avr->data[30] = (uint8_t)masked;
+		io->avr->data[31] = (uint8_t)(masked >> 8);
+		int result = mega_flash_ioctl(io, ctl, param);
+		io->avr->data[30] = (uint8_t)z;
+		io->avr->data[31] = (uint8_t)(z >> 8);
+		return result;
+	}
+	if (ctl == AVR_IOCTL_FLASH_SPM && !(mega_flash->flags & AVR_SELFPROG_HAVE_RWW) &&
+	    (io->avr->data[mega_flash->r_spm] & 0x11) == 0x11) { // RWWSRE|SELFPRGEN: the m48 buffer discard
+		for (int i = 0; i < mega_flash->spm_pagesize / 2; i++) {
+			mega_flash->tmppage[i] = 0xffff;
+			mega_flash->tmppage_used[i] = 0;
+		}
+		avr_regbit_clear(io->avr, mega_flash->selfprgen);
+		return 0;
+	}
+	return mega_flash_ioctl(io, ctl, param);
+}
+
+static void fix_mega_flash_erase(void)
+{
+	for (avr_io_t *io = avr->io_port; io; io = io->next) {
+		if (io->kind && strcmp(io->kind, "flash") == 0) {
+			mega_flash = (avr_flash_t *)io;
+			mega_flash_ioctl = io->ioctl;
+			io->ioctl = fixed_flash_ioctl;
+			return;
+		}
+	}
+	fprintf(stderr, "device: no flash module to fix — SPM page erases may misalign\n");
+}
+
+static void request_reset(int sig)
+{
+	(void)sig;
+	reset_requested = 1;
+}
+
+// ------------------------------------------------------------- tiny NVM ---
+
+typedef struct {
+	avr_io_t io;
+	uint8_t buffer[128];
+	uint8_t used[128]; // a buffer word loads once until erased — like silicon
+	unsigned page;
+} tiny_nvm_t;
+
+static tiny_nvm_t nvm;
+
+static int nvm_ioctl(avr_io_t *io, uint32_t ctl, void *param)
+{
+	(void)param;
+	if (ctl != AVR_IOCTL_FLASH_SPM)
+		return -1;
+	tiny_nvm_t *n = (tiny_nvm_t *)io;
+	avr_t *mcu = io->avr;
+	uint8_t command = mcu->data[0x57] & 0x1f; // SPMCSR, both tinies
+	uint16_t z = (uint16_t)(mcu->data[30] | (mcu->data[31] << 8));
+	uint32_t page_base = (uint32_t)(z & ~(n->page - 1)) % (mcu->flashend + 1);
+	if (command == 0x01) { // SPMEN alone: buffer fill from r1:r0
+		unsigned offset = z & (n->page - 1) & ~1u;
+		if (!n->used[offset]) { // first write wins until the buffer clears
+			n->buffer[offset] = mcu->data[0];
+			n->buffer[offset + 1] = mcu->data[1];
+			n->used[offset] = 1;
+		}
+	} else if (command == 0x03) { // PGERS
+		memset(mcu->flash + page_base, 0xff, n->page);
+	} else if (command == 0x05) { // PGWRT: programming only clears bits
+		for (unsigned i = 0; i < n->page; i++)
+			mcu->flash[page_base + i] &= n->buffer[i];
+		memset(n->buffer, 0xff, n->page);
+		memset(n->used, 0, n->page);
+	} else if (command == 0x11) { // CTPB
+		memset(n->buffer, 0xff, n->page);
+		memset(n->used, 0, n->page);
+	}
+	mcu->data[0x57] &= (uint8_t)~0x1f; // the operation completes instantly
+	return 0;
+}
+
+// ----------------------------------------------------------- GPIO bridge ---
+
+static int pty_master = -1;
+static avr_irq_t *rx_pin; // the loader's RX (PB0), driven from the pty
+static avr_cycle_count_t bit_cycles;
+
+static int tx_level = 1, tx_active, tx_bit;
+static uint8_t tx_shift;
+
+static avr_cycle_count_t tx_sample(avr_t *mcu, avr_cycle_count_t when, void *param)
+{
+	(void)mcu;
+	(void)param;
+	tx_shift = (uint8_t)((tx_shift >> 1) | (tx_level ? 0x80 : 0));
+	if (++tx_bit < 8)
+		return when + bit_cycles;
+	if (write(pty_master, &tx_shift, 1) != 1)
+		fprintf(stderr, "device: pty write lost a byte\n");
+	tx_active = 0;
+	return 0;
+}
+
+static void tx_hook(avr_irq_t *irq, uint32_t value, void *param)
+{
+	(void)irq;
+	(void)param;
+	int level = value & 1;
+	if (!tx_active && tx_level == 1 && level == 0) { // start edge
+		tx_active = 1;
+		tx_bit = 0;
+		avr_cycle_timer_register(avr, bit_cycles + bit_cycles / 2, tx_sample, NULL);
+	}
+	tx_level = level;
+}
+
+static uint8_t rx_queue[8192];
+static unsigned rx_head, rx_tail; // ring: head = next to send
+static int rx_active, rx_bit;
+static uint8_t rx_byte;
+
+static void rx_start_next(void);
+
+static avr_cycle_count_t rx_step(avr_t *mcu, avr_cycle_count_t when, void *param)
+{
+	(void)mcu;
+	(void)param;
+	if (rx_bit < 8) {
+		avr_raise_irq(rx_pin, (rx_byte >> rx_bit) & 1);
+		rx_bit++;
+		return when + bit_cycles;
+	}
+	if (rx_bit == 8) { // stop bit, plus one idle bit of margin
+		avr_raise_irq(rx_pin, 1);
+		rx_bit++;
+		return when + 2 * bit_cycles;
+	}
+	rx_active = 0;
+	rx_start_next();
+	return 0;
+}
+
+static void rx_start_next(void)
+{
+	if (rx_active || rx_head == rx_tail)
+		return;
+	rx_byte = rx_queue[rx_head];
+	rx_head = (rx_head + 1) % sizeof(rx_queue);
+	rx_active = 1;
+	rx_bit = 0;
+	avr_raise_irq(rx_pin, 0); // start bit
+	avr_cycle_timer_register(avr, bit_cycles, rx_step, NULL);
+}
+
+// A reset abandons whatever the bridge was mid-transfer: bytes still queued
+// for a chip that no longer has the context to receive them meaningfully,
+// and a decode in progress on a TX line the reset may have already changed.
+// The pending cycle timers must go with the state: avr_reset drops the TX
+// output latch, whose falling edge starts a spurious decode before this
+// runs, and a stale tx_sample would then interleave with the loader's first
+// real answer through the shared shift state, corrupting it.
+static void bridge_reset(void)
+{
+	avr_cycle_timer_cancel(avr, tx_sample, NULL);
+	avr_cycle_timer_cancel(avr, rx_step, NULL);
+	rx_head = rx_tail = 0;
+	rx_active = 0;
+	tx_active = 0;
+	tx_level = 1;
+	avr_raise_irq(rx_pin, 1); // idle line
+}
+
+static void poll_pty(void)
+{
+	uint8_t chunk[256];
+	ssize_t got = read(pty_master, chunk, sizeof(chunk));
+	for (ssize_t i = 0; i < got; i++) {
+		unsigned next = (rx_tail + 1) % sizeof(rx_queue);
+		if (next == rx_head)
+			break; // full: the host will retry on timeout
+		rx_queue[rx_tail] = chunk[i];
+		rx_tail = next;
+	}
+	if (got > 0)
+		rx_start_next();
+}
+
+// ------------------------------------------------------------------ main ---
+
+static void finish(int sig)
+{
+	(void)sig;
+	if (dump_path) {
+		FILE *f = fopen(dump_path, "wb");
+		if (f) {
+			fwrite(avr->flash, 1, avr->flashend + 1, f);
+			fclose(f);
+		}
+		avr_eeprom_desc_t ee = {.ee = NULL, .offset = 0, .size = 0};
+		if (avr_ioctl(avr, AVR_IOCTL_EEPROM_GET, &ee) == 0 && ee.ee && ee.size) {
+			char path[512];
+			snprintf(path, sizeof(path), "%s.eeprom", dump_path);
+			f = fopen(path, "wb");
+			if (f) {
+				fwrite(ee.ee, 1, ee.size, f);
+				fclose(f);
+			}
+		}
+	}
+	if (!link_software)
+		uart_pty_stop(&uart_pty);
+	_exit(0);
+}
+
+int main(int argc, char *argv[])
+{
+	int link_given = 0;
+	for (int opt; (opt = getopt(argc, argv, "l:")) != -1;) {
+		if (opt != 'l' || parse_link(optarg) != 0) {
+			fprintf(stderr, "device: bad link spec (usart0, usart1, sw, or sw:B0,B1 as RX,TX)\n");
+			return 2;
+		}
+		link_given = 1;
+	}
+	int args = argc - optind;
+	if (args < 7 || args > 9) {
+		fprintf(stderr,
+		        "usage: %s [-l link] <pureboot.elf> <mcu> <hz> <base_hex> <page> <baud> <flash_dump>"
+		        " [reset_hex] [resume_flash]\n"
+		        "  -l link:      usart0 | usart1 | sw[:B0,B1] (RX,TX); default: the chip's own\n"
+		        "  reset_hex:    reset vector (default: base with a boot section, else 0)\n"
+		        "  resume_flash: raw full-flash image loaded instead of the ELF — a prior\n"
+		        "                run's dump, for power-fail resume tests\n",
+		        argv[0]);
+		return 2;
+	}
+	argv += optind - 1; // argv[1] is the ELF again, whatever was parsed
+	const char *mcu_name = argv[2];
+	uint32_t base = (uint32_t)strtoul(argv[4], NULL, 0);
+	unsigned page = (unsigned)atoi(argv[5]);
+	unsigned baud = (unsigned)atoi(argv[6]);
+	dump_path = argv[7];
+	int is_mega = strncmp(mcu_name, "atmega", 6) == 0;
+	if (!link_given)
+		link_software = !is_mega; // the chips' natural links: USART0, or PB0/PB1
+
+	avr = avr_make_mcu_by_name(mcu_name);
+	if (!avr) {
+		fprintf(stderr, "device: no %s core\n", mcu_name);
+		return 1;
+	}
+	avr_init(avr);
+	avr->frequency = (uint32_t)strtoul(argv[3], NULL, 0);
+	memset(avr->flash, 0xff, avr->flashend + 1); // real flash powers up erased
+
+	if (args > 8) {
+		// Resume: the full flash image of an interrupted prior run.
+		FILE *f = fopen(argv[9], "rb");
+		if (!f || fread(avr->flash, 1, avr->flashend + 1, f) == 0) {
+			fprintf(stderr, "device: cannot read %s\n", argv[9]);
+			return 1;
+		}
+		fclose(f);
+	} else {
+		elf_firmware_t fw = {0};
+		if (elf_read_firmware(argv[1], &fw) != 0) {
+			fprintf(stderr, "device: cannot read %s\n", argv[1]);
+			return 1;
+		}
+		memcpy(avr->flash + base, fw.flash, fw.flashsize);
+	}
+	// The boot-sectioned megas enter the loader in hardware (BOOTRST, not
+	// modeled — the argument picks the modeled fuse's target); the tinies
+	// and the boot-section-less m48s reset to word 0 like silicon — erased
+	// flash walks up into the loader, and after the host's surgery the
+	// patched vector routes there.
+	int boot_section = is_mega && strncmp(mcu_name, "atmega48", 8) != 0;
+	reset_pc = args > 7 ? (uint32_t)strtoul(argv[8], NULL, 0) : (boot_section ? base : 0);
+	avr->pc = reset_pc;
+	avr->codeend = avr->flashend;
+
+	// Erased EEPROM, as hardware powers up (simavr zeroes it).
+	uint8_t blank[1024];
+	memset(blank, 0xff, sizeof(blank));
+	avr_eeprom_desc_t seed = {.ee = blank, .offset = 0, .size = 0};
+	if (avr_ioctl(avr, AVR_IOCTL_EEPROM_GET, &seed) == 0 && seed.size <= sizeof(blank)) {
+		seed.ee = blank;
+		avr_ioctl(avr, AVR_IOCTL_EEPROM_SET, &seed);
+	}
+
+	// The megas carry simavr's avr_flash module (and its two gaps the wrap
+	// above fixes); the tinies get the NVM module simavr lacks. Which serial
+	// bridge runs is the link's business, not the chip class's.
+	if (is_mega) {
+		fix_mega_flash_erase();
+	} else {
+		nvm.page = page;
+		memset(nvm.buffer, 0xff, sizeof(nvm.buffer));
+		nvm.io.kind = "tiny_nvm";
+		nvm.io.ioctl = nvm_ioctl;
+		avr_register_io(avr, &nvm.io);
+	}
+
+	if (!link_software) {
+		// POLL_SLEEP paces an idle-polling loader in host real time (a
+		// no-hardware CPU-saving hack); clear it so cycles run free.
+		uint32_t flags = 0;
+		avr_ioctl(avr, AVR_IOCTL_UART_GET_FLAGS(uart_digit), &flags);
+		flags &= ~AVR_UART_FLAG_POLL_SLEEP;
+		avr_ioctl(avr, AVR_IOCTL_UART_SET_FLAGS(uart_digit), &flags);
+		uart_pty_init(avr, &uart_pty);
+		uart_pty_connect(&uart_pty, uart_digit);
+		printf("PB_PTY %s\n", uart_pty.pty.slavename);
+	} else {
+		bit_cycles = (avr->frequency + baud / 2) / baud; // matches uart.hpp's own rounding exactly
+		rx_pin = avr_io_getirq(avr, AVR_IOCTL_IOPORT_GETIRQ(sw_rx_port), (unsigned)sw_rx_bit);
+		avr_irq_register_notify(avr_io_getirq(avr, AVR_IOCTL_IOPORT_GETIRQ(sw_tx_port), (unsigned)sw_tx_bit), tx_hook,
+		                        NULL);
+		avr_raise_irq(rx_pin, 1); // idle line
+
+		int slave;
+		struct termios raw;
+		cfmakeraw(&raw);
+		if (openpty(&pty_master, &slave, NULL, &raw, NULL) != 0) {
+			fprintf(stderr, "device: openpty failed\n");
+			return 1;
+		}
+		fcntl(pty_master, F_SETFL, O_NONBLOCK);
+		printf("PB_PTY %s\n", ttyname(slave));
+	}
+	fflush(stdout);
+
+	signal(SIGTERM, finish);
+	signal(SIGINT, finish);
+	signal(SIGUSR1, request_reset); // an external reset line, for the tests
+
+	long since_poll = 0;
+	for (;;) {
+		int state = avr_run(avr);
+		if (state == cpu_Done || state == cpu_Crashed)
+			break;
+		if (reset_requested) {
+			reset_requested = 0;
+			avr_reset(avr);
+			avr->pc = reset_pc;
+			if (!link_software) { // reset restores the pacing hack; re-clear it
+				uint32_t flags = 0;
+				avr_ioctl(avr, AVR_IOCTL_UART_GET_FLAGS(uart_digit), &flags);
+				flags &= ~AVR_UART_FLAG_POLL_SLEEP;
+				avr_ioctl(avr, AVR_IOCTL_UART_SET_FLAGS(uart_digit), &flags);
+			} else {
+				bridge_reset();
+			}
+		}
+		if (link_software && ++since_poll >= 2000) {
+			since_poll = 0;
+			poll_pty();
+			// An unthrottled idle simulation runs the activation window out
+			// from under the host's real-time knock cadence: a 1 MHz build's
+			// 8 s window is 8 M cycles — tens of wall milliseconds — so a
+			// first knock lost to an in-flight reset misses the window
+			// entirely. Pace the simulation only while the bridge is fully
+			// quiet (nothing decoding, nothing queued); transfers keep full
+			// speed, and a quiet window stretches toward real time.
+			if (!rx_active && !tx_active && rx_head == rx_tail)
+				usleep(200);
+		}
+	}
+	finish(0);
+	return 0;
+}

test/test_planner.py

@@ -0,0 +1,211 @@
+#!/usr/bin/env python3
+"""Host-tool unit tests — the pure planning and policy logic, no simulator:
+the flash-programming orders and their recovery properties, the reset-vector
+surgery, the staging-slot composition, the mega boot-fuse decode, and the
+update preflight's error/warning matrix (fuse combinations simavr cannot
+model reach it here as synthetic bytes).
+
+Usage: test_planner.py <tool_py>
+"""
+
+import sys
+
+
+def fail(message):
+    print(f"FAIL: {message}")
+    sys.exit(1)
+
+
+def expect_error(what, fn, *needles):
+    try:
+        fn()
+    except Exception as error:
+        for needle in needles:
+            if needle not in str(error):
+                fail(f"{what}: error lacks {needle!r}: {error}")
+        return
+    fail(f"{what}: no error raised")
+
+
+def info_of(pb, base, page, patch, flash, signature=(0x1E, 0x93, 0x0B), word_flash=False):
+    scale = 2 if word_flash else 1
+    wire_base = base // scale
+    flags = (1 if patch else 0) | (2 if word_flash else 0)
+    raw = bytes((0x50, 0x42, 1, *signature, page & 0xFF, wire_base & 0xFF, wire_base >> 8,
+                 0, 2, flags))
+    info = pb.Info(raw)
+    assert info.flash_size == flash
+    return info
+
+
+def rjmp_decode(word, at, flash_words):
+    if word & 0xF000 != 0xC000:
+        fail(f"not an rjmp: {word:#06x}")
+    offset = word & 0x0FFF
+    if offset >= 0x800:
+        offset -= 0x1000
+    return (at + 1 + offset) % flash_words
+
+
+def main():
+    import os
+    sys.path.insert(0, os.path.dirname(os.path.abspath(sys.argv[1])))
+    import pureboot as pb
+
+    tiny = info_of(pb, 0x1E00, 64, True, 0x2000)
+    mega = info_of(pb, 0x7E00, 128, False, 0x8000, signature=(0x1E, 0x95, 0x0F))
+
+    # mega_boot: BOOTSZ words and the BOOTRST sense per chip — the fuse byte
+    # index (EXTENDED on the x8 line except the m328s' HIGH, HIGH elsewhere)
+    # and the per-family ladders (Atmel-2486/2466/2503/2545/8271/DS40002065/
+    # 8272/8011/2593/42719). Synthetic 'F' replies: only the boot byte
+    # carries meaning.
+    cases = (
+        ((0x1E, 0x93, 0x07), 0x2000, 3, {0b11: 0x1F00, 0b10: 0x1E00, 0b01: 0x1C00, 0b00: 0x1800}),  # m8
+        ((0x1E, 0x94, 0x03), 0x4000, 3, {0b11: 0x3F00, 0b10: 0x3E00, 0b01: 0x3C00, 0b00: 0x3800}),  # m16
+        ((0x1E, 0x95, 0x02), 0x8000, 3, {0b11: 0x7E00, 0b10: 0x7C00, 0b01: 0x7800, 0b00: 0x7000}),  # m32
+        ((0x1E, 0x93, 0x0A), 0x2000, 2, {0b11: 0x1F00, 0b10: 0x1E00, 0b01: 0x1C00, 0b00: 0x1800}),  # m88
+        ((0x1E, 0x93, 0x0F), 0x2000, 2, {0b11: 0x1F00, 0b10: 0x1E00, 0b01: 0x1C00, 0b00: 0x1800}),  # m88P
+        ((0x1E, 0x94, 0x06), 0x4000, 2, {0b11: 0x3F00, 0b10: 0x3E00, 0b01: 0x3C00, 0b00: 0x3800}),  # m168/168A
+        ((0x1E, 0x94, 0x0B), 0x4000, 2, {0b11: 0x3F00, 0b10: 0x3E00, 0b01: 0x3C00, 0b00: 0x3800}),  # m168P
+        ((0x1E, 0x95, 0x14), 0x8000, 3, {0b11: 0x7E00, 0b10: 0x7C00, 0b01: 0x7800, 0b00: 0x7000}),  # m328
+        ((0x1E, 0x95, 0x0F), 0x8000, 3, {0b11: 0x7E00, 0b10: 0x7C00, 0b01: 0x7800, 0b00: 0x7000}),  # m328P
+        ((0x1E, 0x94, 0x0F), 0x4000, 3, {0b11: 0x3F00, 0b10: 0x3E00, 0b01: 0x3C00, 0b00: 0x3800}),  # m164A
+        ((0x1E, 0x94, 0x0A), 0x4000, 3, {0b11: 0x3F00, 0b10: 0x3E00, 0b01: 0x3C00, 0b00: 0x3800}),  # m164P
+        ((0x1E, 0x95, 0x15), 0x8000, 3, {0b11: 0x7E00, 0b10: 0x7C00, 0b01: 0x7800, 0b00: 0x7000}),  # m324A
+        ((0x1E, 0x96, 0x09), 0x10000, 3, {0b11: 0xFC00, 0b10: 0xF800, 0b01: 0xF000, 0b00: 0xE000}),  # m644
+        ((0x1E, 0x96, 0x0A), 0x10000, 3, {0b11: 0xFC00, 0b10: 0xF800, 0b01: 0xF000, 0b00: 0xE000}),  # m644P
+        ((0x1E, 0x97, 0x06), 0x20000, 3, {0b11: 0x1FC00, 0b10: 0x1F800, 0b01: 0x1F000, 0b00: 0x1E000}),  # 1284
+        ((0x1E, 0x97, 0x05), 0x20000, 3, {0b11: 0x1FC00, 0b10: 0x1F800, 0b01: 0x1F000, 0b00: 0x1E000}),  # 1284P
+    )
+    for signature, flash, which, ladder in cases:
+        # Word-addressed chips carry the 1 KiB slot (their smallest boot sector).
+        slot = 1024 if flash > 0x10000 else 512
+        chip = info_of(pb, flash - slot, 128 if flash < 0x20000 else 0, False, flash,
+                       signature=signature, word_flash=flash > 0x10000)
+        for bits, start in ladder.items():
+            fuses = bytearray((0xFF, 0xFF, 0xFF, 0xFF))
+            fuses[which] = (0xF8 | (bits << 1)) & ~1
+            prog, at = pb.mega_boot(chip, bytes(fuses))
+            if not prog or at != start:
+                fail(f"mega_boot {signature[1]:02x}{signature[2]:02x} BOOTSZ={bits:02b} programmed: {prog} {at:#07x}")
+            fuses[which] |= 1
+            prog, at = pb.mega_boot(chip, bytes(fuses))
+            if prog or at != start:
+                fail(f"mega_boot {signature[1]:02x}{signature[2]:02b} unprogrammed: {prog} {at:#07x}")
+
+    # Word-addressed info decode: the 1284P's base/page ride the wire scaled,
+    # and its slot is 1 KiB.
+    big = info_of(pb, 0x1FC00, 0, False, 0x20000, signature=(0x1E, 0x97, 0x05), word_flash=True)
+    if big.page != 256 or big.base != 0x1FC00 or big.stage != 0x1F800 or big.slot != 1024:
+        fail(f"word-addressed info decode: page {big.page}, base {big.base:#x}, stage {big.stage:#x}")
+
+    # Surgery: word 0 lands on the loader, the trampoline on the original
+    # entry — checked with an independent decoder.
+    app = bytes((0xC0 | 0x00, 0xC0)) + bytes((0x12,)) * 300  # rjmp .+0x00C0... entry word 0xC0C0
+    entry = rjmp_decode(app[0] | (app[1] << 8), 0, tiny.flash_size // 2)
+    pages = pb.plan_flash(app, tiny)
+    word0 = pages[0][0] | (pages[0][1] << 8)
+    if rjmp_decode(word0, 0, tiny.flash_size // 2) != tiny.base // 2:
+        fail("surgery: patched word 0 misses the loader")
+    tp = pages[tiny.base - 64]
+    tramp = tp[62] | (tp[63] << 8)
+    if rjmp_decode(tramp, (tiny.base - 2) // 2, tiny.flash_size // 2) != entry:
+        fail("surgery: trampoline misses the original entry")
+    expect_error("non-rjmp vector", lambda: pb.plan_flash(bytes((0x0C, 0x94)) + app[2:], tiny), "not an rjmp")
+    looped = bytearray(app)
+    word = pb.rjmp_to(0, tiny.base // 2, tiny.flash_size // 2)
+    looped[0], looped[1] = word & 0xFF, word >> 8
+    expect_error("read-back image", lambda: pb.plan_flash(bytes(looped), tiny), "read-back")
+    expect_error("oversize image", lambda: pb.plan_flash(bytes(0x1DFF), tiny), "application flash ends")
+
+    # Ordering: patched vector puts page 0 first and the trampoline second;
+    # a boot section puts page 0 last. Blank pages drop only when erased.
+    order = pb.covered(pages, tiny, skip_blank=False)
+    if order[0] != 0 or order[1] != tiny.base - 64:
+        fail(f"tiny order starts {order[:2]}, want page 0 then trampoline page")
+    if sorted(order[2:]) != order[2:]:
+        fail("tiny order tail not ascending")
+    mega_pages = pb.plan_flash(bytes((0xFF,)) * 600, mega)
+    morder = pb.covered(mega_pages, mega, skip_blank=False)
+    if morder[-1] != 0 or sorted(morder[:-1]) != morder[:-1]:
+        fail(f"mega order {morder}, want ascending with page 0 last")
+    blanky = {0: pages[0], 64: bytes((0xFF,)) * 64, 128: pages[128], tiny.base - 64: tp}
+    slim = pb.covered(blanky, tiny, skip_blank=True)
+    if 64 in slim or 0 not in slim or tiny.base - 64 not in slim:
+        fail(f"skip_blank order wrong: {slim}")
+
+    # Staging content: the identical image plus the through-word on a
+    # patched-vector chip; hard size clamps either way.
+    image = bytes(range(256)) * 2  # 512 B — too big for a tiny slot
+    expect_error("tiny staging size", lambda: pb.staging_content(image, tiny), "510")
+    staged = pb.staging_content(image[:508], tiny)
+    through = staged[510] | (staged[511] << 8)
+    if rjmp_decode(through, (tiny.base - 2) // 2, tiny.flash_size // 2) != tiny.base // 2:
+        fail("through-word misses the resident base")
+    if pb.staging_content(image, mega) != image:
+        fail("mega staging content should be the bare image")
+    expect_error("mega staging size", lambda: pb.staging_content(image + b"!", mega), "512")
+
+    # The embedded info block: found in a synthetic binary, absent in noise.
+    binary = bytes((0xAA,)) * 10 + tiny.raw + bytes((0xBB,)) * 10
+    found = pb.image_info(binary)
+    if found is None or found.raw != tiny.raw:
+        fail("image_info misses the embedded block")
+    if pb.image_info(bytes((0xAA,)) * 40) is not None:
+        fail("image_info invents a block")
+
+    # loader_image must peel a padded image down to the slot content: a raw
+    # .bin padded from address 0 (or a whole-flash read-back with the loader
+    # resident at base) yields the same bytes as the bare slot image.
+    import tempfile
+    slot_image = bytes((0xAA,)) * 10 + tiny.raw + bytes((0xCC,)) * 40
+    padded = bytes((0xFF,)) * tiny.base + slot_image
+    with tempfile.NamedTemporaryFile(suffix=".bin", delete=False) as f:
+        f.write(padded)
+        padded_path = f.name
+    try:
+        if pb.loader_image(padded_path) != slot_image:
+            fail("loader_image does not peel a padded image to the slot content")
+    finally:
+        os.unlink(padded_path)
+
+    # Update preflight: the full fuse matrix, plus target mismatch.
+    other = info_of(pb, 0x1E00, 32, True, 0x2000)
+    expect_error("wrong-target image", lambda: pb.update_preflight(binary, other, None), "another target")
+    expect_error("mega needs fuses", lambda: pb.update_preflight(bytes((0xAA,)) * 8 + mega.raw, mega, None),
+                 "--assume-fuses")
+    mega_image = bytes((0xAA,)) * 8 + mega.raw
+
+    def fuses(high):
+        return bytes((0xFF, 0xFF, 0xFF, high))
+
+    expect_error("BOOTSZ 512 B", lambda: pb.update_preflight(mega_image, mega, fuses(0xFE)),
+                 "cannot self-update", "BOOTSZ")
+    notes = pb.update_preflight(mega_image, mega, fuses(0xFD))  # 1 KB, BOOTRST unprogrammed
+    if not any("BOOTRST unprogrammed" in n for n in notes):
+        fail(f"1K/unprogrammed notes: {notes}")
+    notes = pb.update_preflight(mega_image, mega, fuses(0xFC))  # 1 KB, BOOTRST programmed
+    if not any("staging slot" in n for n in notes):
+        fail(f"1K/programmed notes: {notes}")
+    notes = pb.update_preflight(mega_image, mega, fuses(0xFA))  # 2 KB, BOOTRST programmed
+    if not any("application flash" in n for n in notes):
+        fail(f"2K/programmed notes: {notes}")
+    if pb.update_preflight(bytes((0xAA,)) * 8 + tiny.raw, tiny, None) != []:
+        fail("tiny preflight should pass without fuses")
+
+    # The walk-region refusal: BOOTRST aimed below the loader plus app data
+    # in the walk span errors without --force; erased spans and unprogrammed
+    # BOOTRST pass.
+    deep = {0x7800: bytes((1,)) * 128}
+    expect_error("walk region", lambda: pb.check_walk_region(deep, mega, fuses(0xFA), False), "--force")
+    pb.check_walk_region(deep, mega, fuses(0xFA), True)
+    pb.check_walk_region(deep, mega, fuses(0xFB), False)  # BOOTRST unprogrammed
+    pb.check_walk_region({0x7800: bytes((0xFF,)) * 128}, mega, fuses(0xFA), False)
+    pb.check_walk_region(deep, mega, None, False)  # fuses unknown: no check
+
+    print("test_planner: all planner and policy checks pass")
+
+
+if __name__ == "__main__":
+    main()

test/tsbtest.py

@@ -144,7 +144,7 @@ class Host:
         self._expect(CONFIRM, "C end")
         return echo
 
-    # Activation when the config page carries a password: 3x'@' then the
+    # Activation when the config page carries a password: 3×'@' then the
     # password bytes, then the info block + mainloop '!'.
     def activate_password(self, password):
         self.s.reset_input_buffer()
@@ -167,20 +167,6 @@ class Host:
         self._expect(CONFIRM, "emergency mainloop ready")
 
 
-    # A wrong password byte hangs the loader, still draining the line. Two
-    # things must not happen: it must not activate, and it must not fall
-    # through to the emergency erase - a byte the gate has already refused
-    # reaching the erase would let a guess wipe the part.
-    def refuse_password(self, byte):
-        self.s.reset_input_buffer()
-        self.s.write(bytes([KNOCK, KNOCK, KNOCK, byte]))
-        return self.s.read(1)
-
-    def say(self, byte):
-        self.s.write(bytes([byte]))
-        return self.s.read(1)
-
-
 def check(cond, msg):
     if not cond:
         raise AssertionError(msg)
@@ -195,7 +181,7 @@ PW_BYTES = bytes([0x50, 0x57])
 
 def scenario_roundtrip(host):
     """Activation + info block + flash/EEPROM/config read-write round-trips, on
-    a device with a blank (erased) config page - the usual no-password case."""
+    a device with a blank (erased) config page — the usual no-password case."""
     info = host.activate()
     check(info[0:3] == b"TSB", f"magic 'TSB' (got {info[0:3]!r})")
     check(info[6:9] == bytes([0x1E, 0x95, 0x0F]), f"signature 1E 95 0F (got {info[6:9].hex()})")
@@ -233,15 +219,6 @@ def scenario_emergency(host):
     check(host.read_eeprom(1) == b"\xff" * PAGE, "EEPROM wiped")
 
 
-def scenario_wrong_password(host):
-    """A wrong password byte neither activates the loader nor opens the
-    emergency erase behind it - the oracle carries a dedicated fix for the
-    second, and nothing here exercised either half."""
-    check(host.refuse_password(PW_BYTES[0] ^ 1) == b"", "a wrong password byte draws no reply")
-    check(host.say(0x00) == b"", "a 0 byte after it does not request the erase")
-    check(host.say(CONFIRM) == b"", "and neither does a confirm")
-
-
 def main():
     binary, elf, boot_base = sys.argv[1], sys.argv[2], sys.argv[3]
     failures = []
@@ -252,7 +229,6 @@ def main():
         ("round-trip", None, scenario_roundtrip),
         ("password activation", PW_CONFIG, scenario_password),
         ("emergency erase", PW_CONFIG, scenario_emergency),
-        ("wrong password", PW_CONFIG, scenario_wrong_password),
     ]
     for name, config, fn in groups:
         print(f"--- {name} ---")

tools/check.sh

@@ -1,60 +1,37 @@
 #!/bin/bash
-# The port's gate: the generated workflow - build, size tests, and the
-# simulator-driven protocol suite. --full adds the reflect build, which
-# compiles the same TUs through libavr's other producer. libavr resolves from
-# the `libavr/` submodule; LIBAVR_ROOT overrides it for a working tree.
+# The port's gate: every chip's generated workflow — build, size matrix, and
+# the simulator-driven protocol suites. --full adds the reflect-spot builds
+# (libavr's rule: reflect compiles are bounded to its spot set, never the
+# full matrix). LIBAVR_ROOT must point at the libavr checkout.
 set -e
 cd "$(dirname "$0")/.."
 
 full=0
 [[ "$1" == "--full" ]] && { full=1; shift; }
 
-# The chip lists come from the presets rather than being spelled a second time
-# here: a chip added to make_presets.py and missed in a copy of its list would
-# be a gate that silently never builds it, which is the one failure mode a gate
-# cannot report. tools/make_presets.py is the single source, CMakePresets.json
-# is its output, and this reads that.
-readarray -t WORKFLOWS < <(python3 -c '
-import json, sys
-presets = json.load(open("CMakePresets.json"))["workflowPresets"]
-print("\n".join(p["name"] for p in presets))')
-if ((${#WORKFLOWS[@]} == 0)); then
-	echo "no workflow presets in CMakePresets.json - run tools/make_presets.py" >&2
-	exit 1
-fi
-CHIPS=()
-REFLECT_SPOT=()
-for workflow in "${WORKFLOWS[@]}"; do
-	case $workflow in
-	*-generated) CHIPS+=("${workflow%-generated}") ;;
-	*-reflect) REFLECT_SPOT+=("${workflow%-reflect}") ;;
-	esac
-done
-
-# Every preset runs even after one goes red, and the gate fails at the end
-# naming all of them: stopping at the first failure turns a red - a stale size
-# canary above all - into an alibi for every chip behind it, and a loader can
-# ship on a chip this gate has not compiled since.
-red=()
-run_preset() {
-	echo "==== $1 ===="
-	cmake --workflow --preset "$1" "${@:2}" || red+=("$1")
-}
+CHIPS=(attiny13 attiny13a attiny25 attiny45 attiny85
+       atmega8 atmega8a atmega16 atmega16a atmega32 atmega32a
+       atmega48 atmega48a atmega48p atmega48pa
+       atmega88 atmega88a atmega88p atmega88pa
+       atmega168 atmega168a atmega168p atmega168pa
+       atmega328 atmega328p
+       atmega164a atmega164p atmega164pa
+       atmega324a atmega324p atmega324pa
+       atmega644 atmega644a atmega644p atmega644pa
+       atmega1284 atmega1284p)
+REFLECT_SPOT=(attiny13a attiny85 atmega8 atmega16a atmega32a atmega48pa
+              atmega88 atmega168pa atmega328p atmega164a atmega644p atmega1284)
 
 for chip in "${CHIPS[@]}"; do
-	run_preset "$chip-generated" "$@"
+	echo "==== $chip ===="
+	cmake --workflow --preset "$chip-generated" "$@"
 done
 
 if ((full)); then
 	for chip in "${REFLECT_SPOT[@]}"; do
-		run_preset "$chip-reflect" "$@"
+		echo "==== $chip reflect ===="
+		cmake --workflow --preset "$chip-reflect" "$@"
 	done
 fi
 
-if ((${#red[@]})); then
-	printf '==== red presets ====\n' >&2
-	printf '  %s\n' "${red[@]}" >&2
-	exit 1
-fi
-
 echo "check: every chip green"

tools/make_presets.py

@@ -1,27 +1,37 @@
 #!/usr/bin/env python3
-"""Regenerate CMakePresets.json - one uniform pipeline per chip.
+"""Regenerate CMakePresets.json — one uniform pipeline per chip.
 
-The tiers reimplement the ATmega328P-only reference protocol, so that is the
-whole chip list. It stays a generated file rather than a hand-written one
-because the shape - configure, build, test, workflow, and a reflect pair
-without tests - is the shape a second chip would need too.
+Every chip gets generated-mode configure/build/test presets and a workflow
+running all three. Reflect-mode presets (configure + build, no tests — the
+port's TUs compile identically; the sims prove nothing new there) exist for
+libavr's reflect spot set only, mirroring its rule: the full reflect matrix
+is never built, one chip per hardware class and pack vintage is.
 
-Run from the repo root: tools/make_presets.py - or with --check, which
-verifies the committed file matches this generator and edits nothing (the
-ctest entry `presets.generated` runs that, so drift reds the gate).
+Run from the repo root: tools/make_presets.py
 """
 
 import json
 import os
-import sys
 
 CHIPS = [
-    "atmega328p",
+    "attiny13", "attiny13a", "attiny25", "attiny45", "attiny85",
+    "atmega8", "atmega8a", "atmega16", "atmega16a", "atmega32", "atmega32a",
+    "atmega48", "atmega48a", "atmega48p", "atmega48pa",
+    "atmega88", "atmega88a", "atmega88p", "atmega88pa",
+    "atmega168", "atmega168a", "atmega168p", "atmega168pa",
+    "atmega328", "atmega328p",
+    "atmega164a", "atmega164p", "atmega164pa",
+    "atmega324a", "atmega324p", "atmega324pa",
+    "atmega644", "atmega644a", "atmega644p", "atmega644pa",
+    "atmega1284", "atmega1284p",
 ]
 
-# The reflect pair: the same chip, built in libavr's other mode.
+# libavr's REFLECT_SPOT (tools/check.sh): one chip per hardware class and
+# pack vintage.
 REFLECT_SPOT = [
-    "atmega328p",
+    "attiny13a", "attiny85", "atmega8", "atmega16a", "atmega32a",
+    "atmega48pa", "atmega88", "atmega168pa", "atmega328p", "atmega164a",
+    "atmega644p", "atmega1284",
 ]
 
 
@@ -31,7 +41,7 @@ def main():
         "hidden": True,
         "generator": "Ninja",
         "binaryDir": "${sourceDir}/build/${presetName}",
-        "toolchainFile": "${sourceDir}/libavr/cmake/avr-toolchain.cmake",
+        "toolchainFile": "$env{LIBAVR_ROOT}/cmake/avr-toolchain.cmake",
         "cacheVariables": {
             "CMAKE_BUILD_TYPE": "Release",
             "CMAKE_EXPORT_COMPILE_COMMANDS": "ON",
@@ -62,9 +72,6 @@ def main():
     for chip in REFLECT_SPOT:
         add(chip, "reflect")
 
-    # CMake rejects unknown fields in the presets root, $comment included, so
-    # the file cannot carry a generated-file marker; the --check ctest is the
-    # whole of rule 10's guard here.
     presets = {
         "version": 8,
         "configurePresets": configure,
@@ -72,19 +79,12 @@ def main():
         "testPresets": test,
         "workflowPresets": workflows,
     }
-    rendered = json.dumps(presets, indent=1) + "\n"
     path = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "CMakePresets.json")
-    if "--check" in sys.argv[1:]:
-        current = open(path).read() if os.path.exists(path) else ""
-        if current != rendered:
-            print("CMakePresets.json does not match its generator - run tools/make_presets.py")
-            return 1
-        return 0
     with open(path, "w") as f:
-        f.write(rendered)
+        json.dump(presets, f, indent=1)
+        f.write("\n")
     print(f"{len(CHIPS)} chips, {len(REFLECT_SPOT)} reflect: {os.path.normpath(path)}")
-    return 0
 
 
 if __name__ == "__main__":
-    sys.exit(main())
+    main()

tsb/tsb_asm.cpp

@@ -1,15 +1,14 @@
-// TinySafeBoot on libavr - tier 3: full feature parity in the 512-byte boot
+// TinySafeBoot on libavr — tier 3: full feature parity in the 512-byte boot
 // section, in C++ except where the C ABI itself is the cost.
 //
-// The complete TinySafeBoot feature set - watchdog-reset bail, one-wire
+// The complete TinySafeBoot feature set — watchdog-reset bail, one-wire
 // half-duplex UART, a config-page activation timeout, the password gate,
-// emergency erase, and config/flash/EEPROM read-write - inside the 512-byte
-// BOOTSZ=11 section the hand-written oracle occupies (oracle/README.md holds
-// what each tier measures, in one table rather than four). The
-// body is the tricks tier's C++ (same register protocol, same structure - see
-// tsb_tricks.cpp, including the global-register miscompile rules) with exactly
-// two routines kept in assembly, the two whose remaining cost *is* the calling
-// convention:
+// emergency erase, and config/flash/EEPROM read-write — at 510 bytes in the
+// 512-byte BOOTSZ=11 section the hand-written oracle occupies (500 B). This tier used to be one
+// monolithic inline-asm routine; it is now the tricks tier's C++ (same
+// register protocol, same structure — see tsb_tricks.cpp, including the
+// global-register miscompile rules) with exactly two routines kept in
+// assembly, the two whose remaining cost *is* the calling convention:
 //
 //   rx     the bounded receive: C++ must re-floor the timeout window on every
 //          call (the global-register-store miscompile) and split it across
@@ -17,12 +16,12 @@
 //          countdown.
 //   store  the page-store loop: C++ cannot hold the receive byte pair and the
 //          walked Z pointer across the rx calls without call-saved staging
-//          (push/pop + a Y->Z copy per word); the asm calls rx knowing exactly
+//          (push/pop + a Y→Z copy per word); the asm calls rx knowing exactly
 //          which registers it touches and walks Z live across the whole page.
 //
-// Everything else - bring-up, activation, password gate, emergency erase,
+// Everything else — bring-up, activation, password gate, emergency erase,
 // dispatch, every SPM/EEPROM/flash primitive, every geometry/baud/info
-// constant - is C++ on libavr, and the two asm routines splice into the same
+// constant — is C++ on libavr, and the two asm routines splice into the same
 // global-register protocol the C++ uses (g_addr in Y, g_cnt in r16, g_window
 // in r7, g_receiving in r6), so calls cross the boundary with no marshalling.
 //
@@ -42,16 +41,10 @@ namespace hw = avr::hw;
 namespace tsb {
 namespace {
 
-// The loader is purely polled - it never enables interrupts - so every SPM and
+// The loader is purely polled — it never enables interrupts — so every SPM and
 // EEPROM lock folds to nothing under this posture.
 constexpr auto off = avr::irq::guard_policy::unused;
 
-// Strict request/response: every SPM operation is waited out before the next
-// byte moves, so no flash operation is ever in flight at an EEPROM access -
-// the write procedure's step 2 has nothing to guard, the omission the
-// datasheet grants (DS40002061B section 8.6.3).
-constexpr auto no_spm = ee::spm_interlock::omitted;
-
 constexpr std::uint8_t confirm = '!';
 constexpr std::uint8_t request = '?';
 constexpr std::uint8_t knock = '@';
@@ -64,34 +57,28 @@ constexpr std::uint16_t boot_bytes = 512;
 constexpr std::uint16_t app_end = spm::flash_bytes - boot_bytes - page;
 constexpr std::uint16_t eeprom_end = avr::hw::db.mem.eeprom_size - 1;
 
-// Lockout-proof floor for the activation window: the oracle's F_CPU/1MHz, so
-// it follows the clock rather than restating it (rule 41).
-constexpr auto act_min = static_cast<std::uint8_t>((16_MHz).hz / 1'000'000);
+// Lockout-proof floor for the activation window (the oracle's F_CPU/1MHz).
+constexpr std::uint8_t act_min = 16;
 // Post-activation window: the host gets seconds, not milliseconds, mid-session.
 constexpr std::uint8_t comm_window = 200;
 
 constexpr std::uint16_t build_date = 26 * 512 + 7 * 32 + 20;
 
 // Fixed 115200 8N1; the library solves UBRR + U2X from clock and baud.
-constexpr auto baud = avr::uart::solve_baud(16_MHz, 115200_Bd, 8, avr::uart::parity::none);
-
-// One bit time on the wire: the turn-around a shared-line peer needs to stop
-// driving before this one starts. Derived from the solved rate, so it follows
-// the link rather than a count measured against one.
-constexpr auto guard_cycles = static_cast<std::uint32_t>((16_MHz).hz / baud.actual);
+constexpr auto baud = avr::uart::detail::solve_baud(16_MHz, 115200_Bd);
 
 // The 16-byte device-info block, streamed out on activation.
 // clang-format off
-[[gnu::progmem]] constexpr auto info = std::to_array<std::uint8_t>({
+[[gnu::progmem]] constexpr std::uint8_t info[16] = {
     'T', 'S', 'B',
     build_date & 0xFF, build_date >> 8,
     0xF3,             // status: native-UART fixed-baud lineage
-    avr::hw::db.signature[0], avr::hw::db.signature[1], avr::hw::db.signature[2],
+    0x1E, 0x95, 0x0F, // ATmega328P signature
     page / 2,         // page size in words
     (app_end / 2) & 0xFF, (app_end / 2) >> 8,
     eeprom_end & 0xFF, eeprom_end >> 8,
     0xAA, 0xAA,
-});
+};
 // clang-format on
 
 register std::uint16_t g_addr asm("r28");
@@ -107,7 +94,7 @@ const std::uint8_t *flash_ptr(std::uint16_t addr)
 // Bounded byte receive (asm 1 of 2): release the one-wire line on a direction
 // change, poll RXC0 under the oracle's nested X-register countdown seeded from
 // g_window (floored against lockout), byte or 0-on-silence in r24. Z survives
-// - the property the store's word loop rides on.
+// — the property the store's word loop rides on.
 [[gnu::noinline, gnu::noclone]] std::uint8_t rx()
 {
 	std::uint8_t byte;
@@ -128,7 +115,7 @@ const std::uint8_t *flash_ptr(std::uint16_t addr)
 	             "	brne	3b			\n\t"
 	             "	sbiw	r26, 1			\n\t"
 	             "	brcc	2b			\n\t"
-	             "	clr	%[b]			\n\t" // silence -> 0, which no compare accepts
+	             "	clr	%[b]			\n\t" // silence → 0, which no compare accepts
 	             "	rjmp	5f			\n\t"
 	             "4:	lds	%[b], %[udr0]		\n\t"
 	             "5:					\n\t"
@@ -142,13 +129,14 @@ const std::uint8_t *flash_ptr(std::uint16_t addr)
 // One-wire transmit: take the line (TXEN0 alone) on a direction change with a
 // turn-around guard, put the byte out, hold the line until the whole frame is
 // out (TXC0, not UDRE0), W1C TXC0 by storing the sampled status back (keeps
-// U2X0). Plain C++ - it compiles *smaller* than the oracle's routine.
+// U2X0). Plain C++ — it compiles *smaller* than the oracle's routine.
 [[gnu::noinline, gnu::noclone]] void tx(std::uint8_t byte)
 {
 	if (g_receiving) {
 		g_receiving = 0;
 		hw::ucsr0b::write(hw::ucsr0b::txen0(1));
-		avr::delay::cycles<guard_cycles>();
+		for (std::uint8_t guard = 46; guard; --guard)
+			;
 	}
 	hw::udr0::write(byte);
 	std::uint8_t status;
@@ -165,7 +153,7 @@ const std::uint8_t *flash_ptr(std::uint16_t addr)
 	return rx();
 }
 
-// One flash byte <- [g_addr++] (the advance right before ret - the
+// One flash byte ← [g_addr++] (the advance right before ret — the
 // global-register rule, see tsb_tricks.cpp).
 [[gnu::noinline, gnu::noclone]] std::uint8_t sflash()
 {
@@ -174,18 +162,18 @@ const std::uint8_t *flash_ptr(std::uint16_t addr)
 	return byte;
 }
 
-// One EEPROM byte <- [g_addr++].
+// One EEPROM byte ← [g_addr++].
 [[gnu::noinline, gnu::noclone]] std::uint8_t eerd()
 {
-	std::uint8_t byte = ee::read<no_spm>(g_addr);
+	std::uint8_t byte = ee::read(g_addr);
 	++g_addr;
 	return byte;
 }
 
-// One EEPROM byte -> [g_addr++].
+// One EEPROM byte → [g_addr++].
 [[gnu::noinline, gnu::noclone]] void eewr(std::uint8_t byte)
 {
-	ee::write<off, no_spm>(g_addr, byte);
+	ee::write<off>(g_addr, byte);
 	++g_addr;
 }
 
@@ -197,7 +185,7 @@ const std::uint8_t *flash_ptr(std::uint16_t addr)
 	} while (--g_cnt);
 }
 
-// Wait out a running SPM op, then re-open the RWW section - after every page
+// Wait out a running SPM op, then re-open the RWW section — after every page
 // op and before handing over, as the oracle does.
 [[gnu::noinline, gnu::noclone]] void settle()
 {
@@ -213,12 +201,12 @@ extern "C" [[noreturn]] void tsb_app(); // the application's reset vector: --def
 	tsb_app();
 }
 
-// Step g_addr one page down and erase that page (the decrement lives here  -
+// Step g_addr one page down and erase that page (the decrement lives here —
 // the global-register rule).
 [[gnu::noinline, gnu::noclone]] void erase_below()
 {
 	g_addr -= page;
-	spm::command<off>(spm::op::erase, g_addr);
+	spm::erase_page<off>(g_addr);
 	settle();
 }
 
@@ -233,7 +221,7 @@ extern "C" [[noreturn]] void tsb_app(); // the application's reset vector: --def
 }
 
 // Stream one host page into the erased flash page at g_addr (asm 2 of 2): the
-// word pair stages in r0:r1 straight from rx (whose register set is known  -
+// word pair stages in r0:r1 straight from rx (whose register set is known —
 // the cross-call liveness C++ cannot express), Z walks the page and PGWRT
 // programs it. g_addr is left at the next page base.
 [[gnu::noinline, gnu::noclone]] void store_flash()
@@ -268,15 +256,14 @@ extern "C" [[noreturn]] void tsb_app(); // the application's reset vector: --def
 {
 	// A watchdog reset hands straight back to the application, as the
 	// reference loader does, rather than re-entering the bootloader.
-	if (hw::mcusr::wdrf.test()) {
+	if (hw::mcusr::wdrf.test())
 		appjump();
-	}
 
 	// Lean bring-up from reset state: UCSR0C already reads 8N1, UBRR0H reads
-	// 0, and rx()/tx() raise RXEN0/TXEN0 on first use - only the divisor low
+	// 0, and rx()/tx() raise RXEN0/TXEN0 on first use — only the divisor low
 	// byte and U2X0 need a store. The library still does the datasheet work.
 	static_assert(baud.u2x && baud.ubrr < 256, "lean bring-up writes UBRR0L only, with U2X0");
-	hw::ubrr0::write(static_cast<std::uint8_t>(baud.ubrr));
+	hw::reg<"UBRR0">::write(static_cast<std::uint8_t>(baud.ubrr));
 	hw::ucsr0a::write(hw::ucsr0a::u2x0(1));
 	// General-purpose registers are undefined at power-on (no crt zeroes them);
 	// the direction latch must start "not receiving" so the first rx() enables
@@ -284,15 +271,13 @@ extern "C" [[noreturn]] void tsb_app(); // the application's reset vector: --def
 	// same reason.
 	g_receiving = 0;
 
-	// Activation: 3x'@', each inside the config page's timeout window (rx
-	// floors it so a corrupt page cannot lock the loader out); anything else  -
-	// including silence - hands over.
+	// Activation: 3×'@', each inside the config page's timeout window (rx
+	// floors it so a corrupt page cannot lock the loader out); anything else —
+	// including silence — hands over.
 	g_window = avr::flash_load(flash_ptr(app_end + 2));
-	for (std::uint8_t k = 3; k; --k) {
-		if (rx() != knock) {
+	for (std::uint8_t k = 3; k; --k)
+		if (rx() != knock)
 			appjump();
-		}
-	}
 	g_window = comm_window;
 
 	// Password gate (config page from app_end+3, 0xff-terminated; a blank
@@ -306,19 +291,17 @@ extern "C" [[noreturn]] void tsb_app(); // the application's reset vector: --def
 		std::uint8_t expected = avr::flash_load(flash_ptr(g_addr)) & mask;
 		++g_addr;
 		if (expected == 0xff) {
-			g_addr = reinterpret_cast<std::uint16_t>(info.data());
+			g_addr = reinterpret_cast<std::uint16_t>(&info[0]);
 			g_cnt = sizeof(info);
 			sendf();
 			break;
 		}
 		std::uint8_t got = rx();
 		if (got == 0) {
-			if (mask == 0) {
+			if (mask == 0)
 				continue;
-			}
-			if (rcnf() != confirm || rcnf() != confirm) {
+			if (rcnf() != confirm || rcnf() != confirm)
 				appjump();
-			}
 			erase_application(); // leaves g_addr = 0 for the EEPROM walk
 			do {
 				eewr(0xff);
@@ -327,9 +310,8 @@ extern "C" [[noreturn]] void tsb_app(); // the application's reset vector: --def
 			erase_below();
 			break;
 		}
-		if (got != expected) {
+		if (got != expected)
 			mask = 0;
-		}
 	}
 
 	for (;;) {
@@ -338,27 +320,23 @@ extern "C" [[noreturn]] void tsb_app(); // the application's reset vector: --def
 		switch (rx()) {
 		case 'f': // read application flash, one page per host '!'
 			for (;;) {
-				if (rx() != confirm) {
+				if (rx() != confirm)
 					break;
-				}
 				g_cnt = page;
 				sendf();
-				if (g_addr >= app_end) {
+				if (g_addr >= app_end)
 					break;
-				}
 			}
 			break;
 		case 'F':                // erase the application, then take pages behind '?'
 			erase_application(); // leaves g_addr = 0, the write start
-			while (rcnf() == confirm) {
+			while (rcnf() == confirm)
 				store_flash();
-			}
 			break;
 		case 'e': // read EEPROM, one page per host '!', until the host stops
 			for (;;) {
-				if (rx() != confirm) {
+				if (rx() != confirm)
 					break;
-				}
 				g_cnt = page;
 				do {
 					tx(eerd());
@@ -380,9 +358,8 @@ extern "C" [[noreturn]] void tsb_app(); // the application's reset vector: --def
 			sendf();
 			break;
 		case 'C': // replace the config page, then echo it back to verify
-			if (rcnf() != confirm) {
+			if (rcnf() != confirm)
 				break;
-			}
 			g_addr = app_end + page;
 			erase_below(); // leaves g_addr = app_end, the store target
 			store_flash();
@@ -396,6 +373,14 @@ extern "C" [[noreturn]] void tsb_app(); // the application's reset vector: --def
 } // namespace
 } // namespace tsb
 
-// Reset lands at the boot section base (BOOTRST): the entry stub in .vectors
-// is laid first and does the one line of crt a crt-less image needs.
-template struct avr::startup::entry<tsb::run, avr::startup::stack::hardware>;
+// Reset lands here: BOOTRST vectors to the boot section base and .vectors is
+// laid first, so this is the first instruction executed. No crt ran, so set
+// the stack pointer before anything is called.
+extern "C" [[gnu::naked, gnu::used, gnu::section(".vectors")]] void __boot_entry()
+{
+	SP = RAMEND;
+	// The one line of crt this loader needs: compiled code assumes
+	// __zero_reg__ (r1) is 0, and power-on registers are undefined.
+	asm volatile("clr __zero_reg__");
+	tsb::run();
+}

tsb/tsb_policy.cpp

@@ -1,329 +0,0 @@
-// TinySafeBoot on libavr - the policy floor: pureboot's rules, measured.
-//
-// The full TinySafeBoot feature set - watchdog bail, one-wire half-duplex,
-// config-page activation timeout, password gate, emergency erase, and
-// config/flash/EEPROM read-write - under philosophy #5 exactly as pureboot
-// obeys it: no assembly, no register variables; code, attributes, and flags
-// only. Every lesson pureboot's development produced is applied - the
-// library's half-duplex serial and startup entry, lean bring-up from reset
-// state, one merged send loop over both memories, oracle-shaped loop bounds,
-// locals threaded through noinline primitives, pureboot's codegen flags  -
-// and the result sits below the idiomatic tier and above the 512 B boot
-// section the tricks/asm tiers reach with the banned mechanisms
-// (oracle/README.md holds all four). This tier exists to keep that gap an
-// artifact
-// rather than a claim: the gap to 512 is the rent of policy-clean C++  -
-// helpers that hold a cursor across rx()/tx() pay push/pop and argument
-// threading where a global-register protocol pays nothing, and both
-// control-flow merges tried (a parametrized paged session, a merged store
-// loop) measured larger than the split cases they replaced. TSB's wire fixes
-// the per-command loop shapes on the device, so pureboot 5's one-transfer-
-// loop collapse has no purchase here.
-//
-// The wire protocol is strict request/response, which is what makes the
-// shared line safe: the device drives it only between a received command and
-// its reply, and releases it (the library's half-duplex choreography)
-// whenever it waits.
-
-#include <libavr/libavr.hpp>
-
-using namespace avr::literals;
-namespace spm = avr::spm;
-namespace ee = avr::eeprom;
-
-using dev = avr::device<{.clock = 16_MHz}>;
-// One-wire: RX and TX share the line, exactly as the native-UART TSB expects.
-// 115200 at 16 MHz lands +2.1 % off, past the receiver-tolerance table the
-// solver holds rates to - the oracle's own deployment has run there for a
-// decade, so the override states that it is meant.
-using serial_t = dev::uart0<{
-    .baud = 115200_Bd,
-    .allow_baud_error = true,
-    .half_duplex = true,
-}>;
-inline constexpr serial_t serial{};
-
-namespace tsb {
-namespace {
-
-// The loader is purely polled - it never enables interrupts - so every SPM and
-// EEPROM lock folds to nothing under this posture.
-constexpr auto off = avr::irq::guard_policy::unused;
-
-// Strict request/response: every SPM operation is waited out before the next
-// byte moves, so no flash operation is ever in flight at an EEPROM access -
-// the write procedure's step 2 has nothing to guard, the omission the
-// datasheet grants (DS40002061B section 8.6.3).
-constexpr auto no_spm = ee::spm_interlock::omitted;
-
-// The handshake bytes, identical across every TSB host.
-constexpr std::uint8_t confirm = '!';
-constexpr std::uint8_t request = '?';
-constexpr std::uint8_t knock = '@';
-
-// Boot geometry for the 1 KB boot section (BOOTSZ=10); the page size and the
-// flash/EEPROM extents are the chip database's to know. app_end is the config
-// page (TSB's LASTPAGE), one page below the boot section.
-constexpr std::uint16_t page = spm::page_bytes;
-constexpr std::uint16_t boot_bytes = 1024;
-constexpr std::uint16_t app_end = spm::flash_bytes - boot_bytes - page;
-constexpr std::uint16_t eeprom_end = avr::hw::db.mem.eeprom_size - 1;
-
-// Lockout-proof floor for the activation window: the oracle's F_CPU/1MHz, so
-// it follows the clock rather than restating it (rule 41).
-constexpr auto act_min = static_cast<std::uint8_t>(dev::clock.hz / 1'000'000);
-// Post-activation window: the host gets seconds, not milliseconds, mid-session.
-constexpr std::uint8_t comm_window = 200;
-
-// Firmware version stamp: YY*512 + MM*32 + DD, the encoding the host decodes.
-constexpr std::uint16_t build_date = 26 * 512 + 7 * 32 + 27;
-
-// The 16-byte device-info block, streamed out on activation.
-// clang-format off
-[[gnu::progmem]] constexpr auto info = std::to_array<std::uint8_t>({
-    'T', 'S', 'B',
-    build_date & 0xFF, build_date >> 8,
-    0xF3,             // status: native-UART fixed-baud lineage
-    avr::hw::db.signature[0], avr::hw::db.signature[1], avr::hw::db.signature[2],
-    page / 2,         // page size in words
-    (app_end / 2) & 0xFF, (app_end / 2) >> 8, // app-flash boundary, words
-    eeprom_end & 0xFF, eeprom_end >> 8,
-    0xAA, 0xAA,       // ATmega processor-type marker (bytes 14 == 15)
-});
-// clang-format on
-
-// The receive window, pre-floored where it is set. In .noinit: there is no
-// crt to clear a .bss image, and run() stores it before the first receive.
-[[gnu::section(".noinit")]] std::uint8_t window;
-
-const std::uint8_t *flash_ptr(std::uint16_t addr)
-{
-	return reinterpret_cast<const std::uint8_t *>(addr);
-}
-
-// Bounded byte receive: poll under nested countdowns, 0 on silence. The 0
-// then falls through every compare - not a knock, not a confirm, not a
-// command - so a silent host unwinds the loader to the application from
-// anywhere, and a mid-session cable pull cannot wedge it. The line release on
-// a direction change is the serial backend's.
-[[gnu::noinline]] std::uint8_t rx()
-{
-	std::uint16_t outer = static_cast<std::uint16_t>(window) << 8;
-	do {
-		std::uint8_t fine = 0;
-		do {
-			if (auto byte = serial.read()) {
-				return *byte;
-			}
-		} while (--fine);
-	} while (--outer);
-	return 0;
-}
-
-// One-wire transmit: the backend takes the line with a turn-around guard and
-// holds it until the whole frame is out.
-[[gnu::noinline]] void tx(std::uint8_t byte)
-{
-	serial.write(byte);
-}
-
-// '?', then hand back the host's reply for the callers' one-byte compare.
-[[gnu::noinline]] std::uint8_t rcnf()
-{
-	tx(request);
-	return rx();
-}
-
-// The one send loop: the info block, the config page, application flash and
-// EEPROM pages all stream through here.
-[[gnu::noinline]] void send_block(bool eep, std::uint16_t at, std::uint8_t count)
-{
-	do {
-		tx(eep ? ee::read<no_spm>(at) : avr::flash_load(flash_ptr(at)));
-		++at;
-	} while (--count);
-}
-
-// One EEPROM byte in - shared by the emergency wipe and the 'E' stream.
-[[gnu::noinline]] void eeput(std::uint16_t at, std::uint8_t value)
-{
-	ee::write<off, no_spm>(at, value);
-}
-
-// Wait out a running SPM op, then re-open the RWW section - after every page
-// op and before handing over, as the oracle does.
-[[gnu::noinline]] void settle()
-{
-	spm::wait();
-	spm::rww_enable<off>();
-}
-
-// One host page straight into the erased flash page at `at` - through the SPM
-// word buffer (low byte then high), no SRAM staging - then committed. `at`
-// names a page base, so the cursor's low byte reaching the boundary ends the
-// walk.
-[[gnu::noinline]] void store_flash_page(std::uint16_t at)
-{
-	const auto open = spm::page::begin<spm::from::boot_section, off>(at);
-	do {
-		std::uint8_t low = rx();
-		std::uint8_t high = rx();
-		spm::fill<off>(open, at, std::bit_cast<std::uint16_t>(std::array{low, high}));
-		at += 2;
-	} while (static_cast<std::uint8_t>(at) & (page - 1));
-	spm::command<off>(spm::op::write, at - page);
-	settle();
-}
-
-extern "C" [[noreturn]] void tsb_app(); // the application's reset vector: --defsym=tsb_app=0
-
-[[noreturn]] void appjump()
-{
-	settle();
-	tsb_app();
-}
-
-// Step one page down and erase it - the erase shared by the whole-app walk,
-// the config rewrite and the emergency wipe; hands the stepped address back.
-[[gnu::noinline]] std::uint16_t erase_below(std::uint16_t at)
-{
-	at -= page;
-	spm::command<off>(spm::op::erase, at);
-	settle();
-	return at;
-}
-
-// Erase the whole application, top-down like the oracle: the loop bound is a
-// compare with zero, and the returned 0 is the address every caller wants
-// next.
-[[gnu::noinline]] std::uint16_t erase_application()
-{
-	std::uint16_t at = app_end;
-	do {
-		at = erase_below(at);
-	} while (at != 0);
-	return at;
-}
-
-[[noreturn]] void run()
-{
-	// A watchdog reset hands straight back to the application, as the
-	// reference loader does, rather than re-entering the bootloader.
-	if (avr::hw::mcusr::wdrf.test()) {
-		appjump();
-	}
-
-	// Lean bring-up from reset state: UCSR0C already reads 8N1, UBRR0H reads
-	// 0, and the half-duplex write()/read() raise TXEN0/RXEN0 on first use  -
-	// only the divisor low byte and U2X0 need a store. The solver still does
-	// the datasheet work; the asserts pin the reset-state assumptions.
-	{
-		constexpr auto sol = avr::uart::solve_baud(dev::clock, 115200_Bd, 8, avr::uart::parity::none);
-		static_assert(sol.u2x && sol.ubrr < 256, "lean bring-up writes UBRR0L only, with U2X0");
-		avr::hw::ubrr0::write(static_cast<std::uint8_t>(sol.ubrr));
-		avr::hw::ucsr0a::write(avr::hw::ucsr0a::u2x0(1));
-	}
-
-	// Activation: 3x'@', each inside the config page's timeout window
-	// (floored so a corrupt page cannot lock the loader out); anything else  -
-	// including silence - hands over.
-	window = avr::flash_load(flash_ptr(app_end + 2)) | act_min;
-	for (std::uint8_t k = 3; k; --k) {
-		if (rx() != knock) {
-			appjump();
-		}
-	}
-	window = comm_window;
-
-	// Password gate (config page from app_end+3, 0xff-terminated; a blank
-	// page is no password). A wrong byte blanks the comparison and drains the
-	// line forever, so a wrong password can never fall through; a 0 requests
-	// emergency erase behind two confirms. On pass the info block goes out;
-	// the emergency path skips it and drops into the command loop.
-	std::uint16_t at = app_end + 3;
-	std::uint8_t mask = 0xff;
-	for (;;) {
-		std::uint8_t expected = avr::flash_load(flash_ptr(at)) & mask;
-		++at;
-		if (expected == 0xff) {
-			send_block(false, reinterpret_cast<std::uint16_t>(info.data()), info.size());
-			break;
-		}
-		std::uint8_t got = rx();
-		if (got == 0) {
-			if (mask == 0) {
-				continue;
-			}
-			if (rcnf() != confirm || rcnf() != confirm) {
-				appjump();
-			}
-			std::uint16_t a = erase_application();
-			do {
-				eeput(a, 0xff);
-			} while (++a <= eeprom_end);
-			erase_below(app_end + page);
-			break;
-		}
-		if (got != expected) {
-			mask = 0;
-		}
-	}
-
-	for (;;) {
-		tx(confirm); // Mainloop ready
-		const std::uint8_t command = rx();
-		switch (command) {
-		case 'f': // read application flash, one page per host '!'
-			for (std::uint16_t a = 0; a < app_end; a += page) {
-				if (rx() != confirm) {
-					break;
-				}
-				send_block(false, a, page);
-			}
-			break;
-		case 'e': // read EEPROM, one page per host '!', until the host stops
-			for (std::uint16_t a = 0;; a += page) {
-				if (rx() != confirm) {
-					break;
-				}
-				send_block(true, a, page);
-			}
-			break;
-		case 'F': { // erase the application, then take pages behind '?'
-			std::uint16_t a = erase_application();
-			for (; rcnf() == confirm; a += page) {
-				store_flash_page(a);
-			}
-			break;
-		}
-		case 'E': // take EEPROM pages behind '?', each write host-paced
-			for (std::uint16_t a = 0; rcnf() == confirm;) {
-				std::uint8_t count = page;
-				do {
-					eeput(a, rx());
-					++a;
-				} while (--count);
-			}
-			break;
-		case 'c': // read the config page
-		read_config:
-			send_block(false, app_end, page);
-			break;
-		case 'C': // replace the config page, then echo it back to verify
-			if (rcnf() != confirm) {
-				break;
-			}
-			store_flash_page(erase_below(app_end + page));
-			goto read_config;
-		default: // 'q' or any other byte runs the application
-			appjump();
-		}
-	}
-}
-
-} // namespace
-} // namespace tsb
-
-// Reset lands at the boot section base (BOOTRST): the entry stub in .vectors
-// is laid first and does the one line of crt a crt-less image needs.
-template struct avr::startup::entry<tsb::run, avr::startup::stack::hardware>;

tsb/tsb_pure.cpp

@@ -1,10 +1,10 @@
-// TinySafeBoot on libavr - tier 1: pure, idiomatic C++.
+// TinySafeBoot on libavr — tier 1: pure, idiomatic C++.
 //
 // A serial flash bootloader for the ATmega328P boot section, reimplementing the
 // TinySafeBoot native-UART fixed-baud protocol on libavr with the full feature
 // set of the hand-written oracle: a watchdog-reset bail, one-wire half-duplex,
 // a config-page activation timeout, the password gate, emergency erase, and
-// config/flash/EEPROM read-write. This variant is written for clarity  -
+// config/flash/EEPROM read-write. This variant is written for clarity —
 // well-factored functions, no compiler-specific size hacks, no inline assembly.
 // The one-wire wiring, the flash-resident info block and every SPM/EEPROM lock
 // are libavr's to handle; the only attribute is the naked reset entry that
@@ -20,29 +20,16 @@ namespace ee = avr::eeprom;
 
 using dev = avr::device<{.clock = 16_MHz}>;
 // One-wire: RX and TX share the line, exactly as the native-UART TSB expects.
-// 115200 at 16 MHz lands +2.1 % off, past the receiver-tolerance table the
-// solver holds rates to - the oracle's own deployment has run there for a
-// decade, so the override states that it is meant.
-using serial_t = dev::uart0<{
-    .baud = 115200_Bd,
-    .allow_baud_error = true,
-    .half_duplex = true,
-}>;
+using serial_t = dev::uart0<{.baud = 115200_Bd, .max_baud_error = 3_pct, .half_duplex = true}>;
 inline constexpr serial_t serial{};
 
 namespace tsb {
 namespace {
 
-// The loader is purely polled - it never enables interrupts - so every SPM and
+// The loader is purely polled — it never enables interrupts — so every SPM and
 // EEPROM lock folds to nothing under this posture.
 constexpr auto off = avr::irq::guard_policy::unused;
 
-// Strict request/response: every SPM operation is waited out before the next
-// byte moves, so no flash operation is ever in flight at an EEPROM access -
-// the write procedure's step 2 has nothing to guard, the omission the
-// datasheet grants (DS40002061B section 8.6.3).
-constexpr auto no_spm = ee::spm_interlock::omitted;
-
 // The handshake bytes, identical across every TSB host.
 constexpr std::uint8_t confirm = '!';
 constexpr std::uint8_t request = '?';
@@ -63,48 +50,26 @@ constexpr std::uint16_t build_date = 26 * 512 + 7 * 32 + 20;
 // The 16-byte device-info block the host reads on activation. A flash_table
 // keeps it in progmem with no .data image (there is no crt to copy one).
 // clang-format off
-inline constexpr auto info_data = std::to_array<std::uint8_t>({
+inline constexpr std::array<std::uint8_t, 16> info_data = {
     'T', 'S', 'B',
     build_date & 0xFF, build_date >> 8,
     0xF3,             // status byte (native-UART fixed-baud lineage)
-    avr::hw::db.signature[0], avr::hw::db.signature[1], avr::hw::db.signature[2],
+    0x1E, 0x95, 0x0F, // ATmega328P signature
     page / 2,         // page size in words
     (app_end / 2) & 0xFF, (app_end / 2) >> 8, // app-flash boundary, words
     eeprom_end & 0xFF, eeprom_end >> 8,
     0xAA, 0xAA, // ATmega processor-type marker (bytes 14 == 15)
-});
+};
 // clang-format on
 using info = avr::flash_table<info_data>;
 
-// The lockout-proof floor for the receive window: the oracle's F_CPU/1MHz, so
-// it follows the clock rather than restating it.
-constexpr auto act_min = static_cast<std::uint8_t>(dev::clock.hz / 1'000'000);
-
-// The receive window, pre-floored where it is set. In .noinit: there is no crt
-// to clear a .bss image, and run() stores it before the first receive.
-[[gnu::section(".noinit")]] std::uint8_t window;
-
-// Bounded byte read over the one-wire line - read() releases the line to the
-// receiver - answering 0 on silence. That 0 falls through every compare below:
-// not a knock, not a confirm, not a command, so a silent host unwinds the
-// loader to the application from anywhere and a mid-session cable pull cannot
-// wedge it. The oracle lists that timeout among its own fixes, and a blocking
-// read is how a tier loses it.
+// Blocking byte read/write over the one-wire line: read() releases the line to
+// the receiver, write() takes it and holds it until the frame is out.
 std::uint8_t rx()
 {
-	std::uint16_t outer = static_cast<std::uint16_t>(window) << 8;
-	do {
-		std::uint8_t fine = 0;
-		do {
-			if (auto byte = serial.read()) {
-				return *byte;
-			}
-		} while (--fine);
-	} while (--outer);
-	return 0;
+	return serial.read_blocking();
 }
 
-// write() takes the line and holds it until the frame is out.
 void tx(std::uint8_t byte)
 {
 	serial.write(byte);
@@ -118,16 +83,14 @@ const std::uint8_t *flash_ptr(std::uint16_t addr)
 // Stream `count` bytes to the host, from flash (LPM) or from EEPROM.
 void send_flash(std::uint16_t addr, std::uint8_t count)
 {
-	while (count--) {
+	while (count--)
 		tx(avr::flash_load(flash_ptr(addr++)));
-	}
 }
 
 void send_eeprom(std::uint16_t addr, std::uint8_t count)
 {
-	while (count--) {
-		tx(ee::read<no_spm>(addr++));
-	}
+	while (count--)
+		tx(ee::read(addr++));
 }
 
 // Prompt the host with '?' and report whether it answered '!'.
@@ -138,33 +101,32 @@ bool request_confirm()
 }
 
 // Stream one page from the host straight into the already-erased flash page at
-// `addr`, filling the SPM word buffer low byte then high - no SRAM staging, so
+// `addr`, filling the SPM word buffer low byte then high — no SRAM staging, so
 // receiving and programming are the same loop.
 void store_flash_page(std::uint16_t addr)
 {
-	const auto open = spm::page::begin<spm::from::boot_section, off>(addr);
 	for (std::uint16_t i = 0; i < page; i += 2) {
 		std::uint8_t lo = rx();
 		std::uint8_t hi = rx();
-		spm::fill<off>(open, addr + i, static_cast<std::uint16_t>(lo | (hi << 8)));
+		spm::fill<off>(addr + i, static_cast<std::uint16_t>(lo | (hi << 8)));
 	}
-	spm::write_page<spm::from::boot_section, off>(addr); // blocking: waits the write out
+	spm::write_page<off>(addr);
+	spm::wait();
 }
 
 // Stream one page from the host straight into EEPROM, byte by byte.
 void store_eeprom_page(std::uint16_t addr)
 {
-	for (std::uint16_t i = 0; i < page; ++i) {
-		ee::write<off, no_spm>(addr + i, rx());
-	}
+	for (std::uint16_t i = 0; i < page; ++i)
+		ee::write<off>(addr + i, rx());
 }
 
-// Erase one flash page, waited out by the blocking spelling - the erase step
-// shared by the whole-app erase, the config-page rewrite and the emergency
-// wipe.
+// Erase one flash page and wait it out — the erase step shared by the whole-app
+// erase, the config-page rewrite and the emergency wipe.
 void erase_page(std::uint16_t addr)
 {
-	spm::erase_page<spm::from::boot_section, off>(addr);
+	spm::erase_page<off>(addr);
+	spm::wait();
 }
 
 // Erase the whole application, one page at a time, top-down as the reference
@@ -195,9 +157,8 @@ extern "C" [[noreturn]] void tsb_app();
 void read_flash()
 {
 	for (std::uint16_t a = 0; a < app_end; a += page) {
-		if (rx() != confirm) {
+		if (rx() != confirm)
 			return;
-		}
 		send_flash(a, page);
 	}
 }
@@ -206,9 +167,8 @@ void read_flash()
 void read_eeprom()
 {
 	for (std::uint16_t a = 0;; a += page) {
-		if (rx() != confirm) {
+		if (rx() != confirm)
 			return;
-		}
 		send_eeprom(a, page);
 	}
 }
@@ -218,25 +178,22 @@ void read_eeprom()
 void write_flash()
 {
 	erase_application();
-	for (std::uint16_t a = 0; request_confirm(); a += page) {
+	for (std::uint16_t a = 0; request_confirm(); a += page)
 		store_flash_page(a);
-	}
 }
 
 // 'E': take pages the host offers behind '?' into EEPROM.
 void write_eeprom()
 {
-	for (std::uint16_t a = 0; request_confirm(); a += page) {
+	for (std::uint16_t a = 0; request_confirm(); a += page)
 		store_eeprom_page(a);
-	}
 }
 
 // 'C': replace the config page, then echo it back for the host to verify.
 void write_config()
 {
-	if (!request_confirm()) {
+	if (!request_confirm())
 		return;
-	}
 	erase_page(app_end);
 	store_flash_page(app_end);
 	spm::rww_enable<off>();
@@ -249,9 +206,8 @@ void write_config()
 void emergency_erase()
 {
 	erase_application();
-	for (std::uint16_t a = 0; a <= eeprom_end; ++a) {
-		ee::write<off, no_spm>(a, 0xff);
-	}
+	for (std::uint16_t a = 0; a <= eeprom_end; ++a)
+		ee::write<off>(a, 0xff);
 	erase_page(app_end);
 	spm::rww_enable<off>();
 }
@@ -266,18 +222,14 @@ gate password_gate()
 {
 	for (const std::uint8_t *pw = flash_ptr(app_end + 3);; ++pw) {
 		std::uint8_t expected = avr::flash_load(pw);
-		if (expected == 0xff) {
+		if (expected == 0xff)
 			return gate::pass;
-		}
 		std::uint8_t got = rx();
-		if (got == 0) {
+		if (got == 0)
 			return gate::emergency;
-		}
-		if (got != expected) {
-			for (;;) {
+		if (got != expected)
+			for (;;)
 				rx();
-			}
-		}
 	}
 }
 
@@ -285,25 +237,21 @@ gate password_gate()
 {
 	// A watchdog reset hands straight back to the application, as the reference
 	// loader does, rather than re-entering the bootloader.
-	if (avr::hw::mcusr::wdrf.test()) {
+	if (avr::hw::mcusr::wdrf.test())
 		appjump();
-	}
 
 	avr::init<serial_t>();
 
 	// Activation: the host knocks three '@' inside a window whose length is the
-	// config page's timeout byte, floored so a corrupt page can never lock the
-	// loader out. An idle port times out and boots the application; the same
-	// window then bounds every receive of the session.
-	window = avr::flash_load(flash_ptr(app_end + 2)) | act_min;
-	__uint24 idle = static_cast<__uint24>(window) << 16;
+	// config page's timeout byte (floored so a corrupt page can never lock the
+	// loader out). An idle port times out and boots the application.
+	__uint24 idle = static_cast<__uint24>(avr::flash_load(flash_ptr(app_end + 2)) | 16) << 16;
 	std::uint8_t knocks = 0;
 	while (knocks < 3) {
-		if (auto byte = serial.read()) {
+		if (auto byte = serial.read())
 			knocks = *byte == knock ? knocks + 1 : 0;
-		} else if (--idle == 0) {
+		else if (--idle == 0)
 			appjump();
-		}
 	}
 
 	switch (password_gate()) {
@@ -311,9 +259,8 @@ gate password_gate()
 		send_flash(reinterpret_cast<std::uint16_t>(info::storage.data()), info::size());
 		break;
 	case gate::emergency:
-		if (!request_confirm() || !request_confirm()) {
+		if (!request_confirm() || !request_confirm())
 			appjump();
-		}
 		emergency_erase();
 		break;
 	}
@@ -348,6 +295,14 @@ gate password_gate()
 } // namespace
 } // namespace tsb
 
-// Reset lands at the boot section base (BOOTRST): the entry stub in .vectors
-// is laid first and does the one line of crt a crt-less image needs.
-template struct avr::startup::entry<tsb::run, avr::startup::stack::hardware>;
+// Reset lands here: BOOTRST vectors to the boot section base and .vectors is
+// laid first, so this is the first instruction executed. No crt ran, so set the
+// stack pointer before anything is called.
+extern "C" [[gnu::naked, gnu::used, gnu::section(".vectors")]] void __boot_entry()
+{
+	SP = RAMEND;
+	// The one line of crt this loader needs: compiled code assumes
+	// __zero_reg__ (r1) is 0, and power-on registers are undefined.
+	asm volatile("clr __zero_reg__");
+	tsb::run();
+}

tsb/tsb_tricks.cpp

@@ -1,16 +1,16 @@
-// TinySafeBoot on libavr - tier 2: C++ with compiler trickery, no assembly.
+// TinySafeBoot on libavr — tier 2: C++ with compiler trickery, no assembly.
 //
-// The full TinySafeBoot feature set - watchdog bail, one-wire half-duplex,
+// The full TinySafeBoot feature set — watchdog bail, one-wire half-duplex,
 // config-page activation timeout, password gate, emergency erase, and
-// config/flash/EEPROM read-write - in pure C++, a little over the 512-byte boot
-// section the hand-written oracle fits (oracle/README.md holds what each tier
-// measures). The structure mirrors the oracle's: a handful of tiny noinline
+// config/flash/EEPROM read-write — in pure C++, 526 bytes: 14 over the 512-byte
+// boot section the hand-written oracle fits, from 168 over at this tier's first
+// floor. The structure mirrors the oracle's: a handful of tiny noinline
 // primitives sharing one whole-loader register allocation, expressed as global
 // register variables so no helper ever saves, spills, or reloads any of it.
 //
 // The register protocol (all call-saved, so calls preserve them by ABI):
-//   Y (r28:r29)  g_addr      the walked flash/EEPROM address - adiw-able
-//   r16          g_cnt       byte countdown of the running block - ldi-able
+//   Y (r28:r29)  g_addr      the walked flash/EEPROM address — adiw-able
+//   r16          g_cnt       byte countdown of the running block — ldi-able
 //   r7           g_window    rx timeout, roughly 30 ms units at 16 MHz
 //   r6           g_receiving one-wire direction latch, cleared at bring-up
 //                            (power-on registers are undefined)
@@ -18,10 +18,10 @@
 // GCC 16.1 miscompiles stores into global register variables: an update whose
 // remaining uses all hide inside callees is deleted whenever a CALL follows it
 // before any jump/ret (the backend's liveness walk lumps fixed registers with
-// call-clobbered ones - minimal repro in libavr's
-// test/upstream/gcc-avr-globalreg-repro.cpp). Every
+// call-clobbered ones — minimal repro in libavr's
+// local/scratch/probes/gcc-avr-globalreg-repro.cpp, lessons.md entry). Every
 // g_* update below therefore sits where a *local* read or a jump/ret follows
-// it - the helpers advance g_addr immediately before returning, and rx()
+// it — the helpers advance g_addr immediately before returning, and rx()
 // re-floors the window on every call instead of storing the floored value
 // once. The layout is load-bearing; do not "simplify" it.
 //
@@ -41,16 +41,10 @@ namespace hw = avr::hw;
 namespace tsb {
 namespace {
 
-// The loader is purely polled - it never enables interrupts - so every SPM and
+// The loader is purely polled — it never enables interrupts — so every SPM and
 // EEPROM lock folds to nothing under this posture.
 constexpr auto off = avr::irq::guard_policy::unused;
 
-// Strict request/response: every SPM operation is waited out before the next
-// byte moves, so no flash operation is ever in flight at an EEPROM access -
-// the write procedure's step 2 has nothing to guard, the omission the
-// datasheet grants (DS40002061B section 8.6.3).
-constexpr auto no_spm = ee::spm_interlock::omitted;
-
 constexpr std::uint8_t confirm = '!';
 constexpr std::uint8_t request = '?';
 constexpr std::uint8_t knock = '@';
@@ -63,34 +57,28 @@ constexpr std::uint16_t boot_bytes = 1024;
 constexpr std::uint16_t app_end = spm::flash_bytes - boot_bytes - page;
 constexpr std::uint16_t eeprom_end = avr::hw::db.mem.eeprom_size - 1;
 
-// Lockout-proof floor for the activation window: the oracle's F_CPU/1MHz, so
-// it follows the clock rather than restating it (rule 41).
-constexpr auto act_min = static_cast<std::uint8_t>((16_MHz).hz / 1'000'000);
+// Lockout-proof floor for the activation window (the oracle's F_CPU/1MHz).
+constexpr std::uint8_t act_min = 16;
 // Post-activation window: the host gets seconds, not milliseconds, mid-session.
 constexpr std::uint8_t comm_window = 200;
 
 constexpr std::uint16_t build_date = 26 * 512 + 7 * 32 + 20;
 
 // Fixed 115200 8N1; the library solves UBRR + U2X from clock and baud.
-constexpr auto baud = avr::uart::solve_baud(16_MHz, 115200_Bd, 8, avr::uart::parity::none);
-
-// One bit time on the wire: the turn-around a shared-line peer needs to stop
-// driving before this one starts. Derived from the solved rate, so it follows
-// the link rather than a count measured against one.
-constexpr auto guard_cycles = static_cast<std::uint32_t>((16_MHz).hz / baud.actual);
+constexpr auto baud = avr::uart::detail::solve_baud(16_MHz, 115200_Bd);
 
 // The 16-byte device-info block, streamed out on activation.
 // clang-format off
-[[gnu::progmem]] constexpr auto info = std::to_array<std::uint8_t>({
+[[gnu::progmem]] constexpr std::uint8_t info[16] = {
     'T', 'S', 'B',
     build_date & 0xFF, build_date >> 8,
     0xF3,             // status: native-UART fixed-baud lineage
-    avr::hw::db.signature[0], avr::hw::db.signature[1], avr::hw::db.signature[2],
+    0x1E, 0x95, 0x0F, // ATmega328P signature
     page / 2,         // page size in words
     (app_end / 2) & 0xFF, (app_end / 2) >> 8,
     eeprom_end & 0xFF, eeprom_end >> 8,
     0xAA, 0xAA,
-});
+};
 // clang-format on
 
 register std::uint16_t g_addr asm("r28");
@@ -105,8 +93,8 @@ const std::uint8_t *flash_ptr(std::uint16_t addr)
 
 // Bounded byte receive, the oracle's shape: release the one-wire line on a
 // direction change, poll RXC0 under nested countdowns, 0 on silence. The 0
-// then falls through every compare - not a knock, not a confirm, not a
-// command - so a silent host unwinds the loader to the application from
+// then falls through every compare — not a knock, not a confirm, not a
+// command — so a silent host unwinds the loader to the application from
 // anywhere, and a mid-session cable pull cannot wedge it.
 [[gnu::noinline, gnu::noclone]] std::uint8_t rx()
 {
@@ -114,25 +102,24 @@ const std::uint8_t *flash_ptr(std::uint16_t addr)
 		g_receiving = 1;
 		hw::ucsr0b::write(hw::ucsr0b::rxen0(1)); // RXEN0 alone: release and listen
 	}
-	// act_min ORs in here, per call, not once into g_window at setup - the
+	// act_min ORs in here, per call, not once into g_window at setup — the
 	// one placement the global-register-store miscompile cannot delete.
 	std::uint16_t outer = static_cast<std::uint16_t>(g_window | act_min) << 8;
 	do {
 		std::uint8_t fine = 0;
 		do {
 			auto status = hw::ucsr0a::read();
-			if (status & hw::ucsr0a::rxc0(1).value) {
+			if (status & hw::ucsr0a::rxc0(1).value)
 				return hw::udr0::read();
-			}
 		} while (--fine);
 	} while (--outer);
 	return 0;
 }
 
-// One-wire transmit: take the line (TXEN0 alone - the receiver must be off
+// One-wire transmit: take the line (TXEN0 alone — the receiver must be off
 // while driving) on a direction change, with a turn-around guard so a shorted
 // peer can switch first; then hold the line until the whole frame is out
-// (TXC0, not UDRE0 - the stop bit must be on the wire before a caller may
+// (TXC0, not UDRE0 — the stop bit must be on the wire before a caller may
 // release the line), and W1C TXC0 by storing the sampled status back, which
 // keeps U2X0.
 [[gnu::noinline, gnu::noclone]] void tx(std::uint8_t byte)
@@ -140,7 +127,8 @@ const std::uint8_t *flash_ptr(std::uint16_t addr)
 	if (g_receiving) {
 		g_receiving = 0;
 		hw::ucsr0b::write(hw::ucsr0b::txen0(1));
-		avr::delay::cycles<guard_cycles>();
+		for (std::uint8_t guard = 46; guard; --guard)
+			;
 	}
 	hw::udr0::write(byte);
 	std::uint8_t status;
@@ -157,7 +145,7 @@ const std::uint8_t *flash_ptr(std::uint16_t addr)
 	return rx();
 }
 
-// One flash byte <- [g_addr++] (the advance right before ret - see header).
+// One flash byte ← [g_addr++] (the advance right before ret — see header).
 [[gnu::noinline, gnu::noclone]] std::uint8_t sflash()
 {
 	std::uint8_t byte = avr::flash_load(flash_ptr(g_addr));
@@ -165,18 +153,18 @@ const std::uint8_t *flash_ptr(std::uint16_t addr)
 	return byte;
 }
 
-// One EEPROM byte <- [g_addr++].
+// One EEPROM byte ← [g_addr++].
 [[gnu::noinline, gnu::noclone]] std::uint8_t eerd()
 {
-	std::uint8_t byte = ee::read<no_spm>(g_addr);
+	std::uint8_t byte = ee::read(g_addr);
 	++g_addr;
 	return byte;
 }
 
-// One EEPROM byte -> [g_addr++].
+// One EEPROM byte → [g_addr++].
 [[gnu::noinline, gnu::noclone]] void eewr(std::uint8_t byte)
 {
-	ee::write<off, no_spm>(g_addr, byte);
+	ee::write<off>(g_addr, byte);
 	++g_addr;
 }
 
@@ -188,7 +176,7 @@ const std::uint8_t *flash_ptr(std::uint16_t addr)
 	} while (--g_cnt);
 }
 
-// Wait out a running SPM op, then re-open the RWW section - after every page
+// Wait out a running SPM op, then re-open the RWW section — after every page
 // op and before handing over, as the oracle does.
 [[gnu::noinline, gnu::noclone]] void settle()
 {
@@ -210,12 +198,12 @@ extern "C" [[noreturn]] void tsb_app(); // the application's reset vector: --def
 [[gnu::noinline, gnu::noclone]] void erase_below()
 {
 	g_addr -= page;
-	spm::command<off>(spm::op::erase, g_addr);
+	spm::erase_page<off>(g_addr);
 	settle();
 }
 
 // Erase the whole application, top-down like the oracle: the loop bound is a
-// compare with zero, and g_addr = 0 - the value every caller wants next - is
+// compare with zero, and g_addr = 0 — the value every caller wants next — is
 // handed back for free.
 [[gnu::noinline, gnu::noclone]] void erase_application()
 {
@@ -226,19 +214,18 @@ extern "C" [[noreturn]] void tsb_app(); // the application's reset vector: --def
 }
 
 // Stream one host page into the erased flash page at g_addr (SPM word buffer,
-// low byte then high) - no SRAM staging, receive and program are one loop.
+// low byte then high) — no SRAM staging, receive and program are one loop.
 // g_addr is left at the next page base.
 [[gnu::noinline, gnu::noclone]] void store_flash()
 {
-	const auto open = spm::page::begin<spm::from::boot_section, off>(g_addr);
 	g_cnt = page / 2;
 	do {
 		std::uint16_t word = rx();
 		word |= static_cast<std::uint16_t>(rx()) << 8;
-		spm::fill<off>(open, g_addr, word);
+		spm::fill<off>(g_addr, word);
 		g_addr += 2;
 	} while (--g_cnt);
-	spm::command<off>(spm::op::write, g_addr - page);
+	spm::write_page<off>(g_addr - page);
 	settle();
 }
 
@@ -246,15 +233,14 @@ extern "C" [[noreturn]] void tsb_app(); // the application's reset vector: --def
 {
 	// A watchdog reset hands straight back to the application, as the
 	// reference loader does, rather than re-entering the bootloader.
-	if (hw::mcusr::wdrf.test()) {
+	if (hw::mcusr::wdrf.test())
 		appjump();
-	}
 
 	// Lean bring-up from reset state: UCSR0C already reads 8N1, UBRR0H reads
-	// 0, and rx()/tx() raise RXEN0/TXEN0 on first use - only the divisor low
+	// 0, and rx()/tx() raise RXEN0/TXEN0 on first use — only the divisor low
 	// byte and U2X0 need a store. The library still does the datasheet work.
 	static_assert(baud.u2x && baud.ubrr < 256, "lean bring-up writes UBRR0L only, with U2X0");
-	hw::ubrr0::write(static_cast<std::uint8_t>(baud.ubrr));
+	hw::reg<"UBRR0">::write(static_cast<std::uint8_t>(baud.ubrr));
 	hw::ucsr0a::write(hw::ucsr0a::u2x0(1));
 	// General-purpose registers are undefined at power-on (no crt zeroes them);
 	// the direction latch must start "not receiving" so the first rx() enables
@@ -262,15 +248,13 @@ extern "C" [[noreturn]] void tsb_app(); // the application's reset vector: --def
 	// same reason.
 	g_receiving = 0;
 
-	// Activation: 3x'@', each inside the config page's timeout window (rx
-	// floors it so a corrupt page cannot lock the loader out); anything else  -
-	// including silence - hands over.
+	// Activation: 3×'@', each inside the config page's timeout window (rx
+	// floors it so a corrupt page cannot lock the loader out); anything else —
+	// including silence — hands over.
 	g_window = avr::flash_load(flash_ptr(app_end + 2));
-	for (std::uint8_t k = 3; k; --k) {
-		if (rx() != knock) {
+	for (std::uint8_t k = 3; k; --k)
+		if (rx() != knock)
 			appjump();
-		}
-	}
 	g_window = comm_window;
 
 	// Password gate (config page from app_end+3, 0xff-terminated; a blank
@@ -284,19 +268,17 @@ extern "C" [[noreturn]] void tsb_app(); // the application's reset vector: --def
 		std::uint8_t expected = avr::flash_load(flash_ptr(g_addr)) & mask;
 		++g_addr;
 		if (expected == 0xff) {
-			g_addr = reinterpret_cast<std::uint16_t>(info.data());
+			g_addr = reinterpret_cast<std::uint16_t>(&info[0]);
 			g_cnt = sizeof(info);
 			sendf();
 			break;
 		}
 		std::uint8_t got = rx();
 		if (got == 0) {
-			if (mask == 0) {
+			if (mask == 0)
 				continue;
-			}
-			if (rcnf() != confirm || rcnf() != confirm) {
+			if (rcnf() != confirm || rcnf() != confirm)
 				appjump();
-			}
 			erase_application(); // leaves g_addr = 0 for the EEPROM walk
 			do {
 				eewr(0xff);
@@ -305,9 +287,8 @@ extern "C" [[noreturn]] void tsb_app(); // the application's reset vector: --def
 			erase_below();
 			break;
 		}
-		if (got != expected) {
+		if (got != expected)
 			mask = 0;
-		}
 	}
 
 	for (;;) {
@@ -316,27 +297,23 @@ extern "C" [[noreturn]] void tsb_app(); // the application's reset vector: --def
 		switch (rx()) {
 		case 'f': // read application flash, one page per host '!'
 			for (;;) {
-				if (rx() != confirm) {
+				if (rx() != confirm)
 					break;
-				}
 				g_cnt = page;
 				sendf();
-				if (g_addr >= app_end) {
+				if (g_addr >= app_end)
 					break;
-				}
 			}
 			break;
 		case 'F':                // erase the application, then take pages behind '?'
 			erase_application(); // leaves g_addr = 0, the write start
-			while (rcnf() == confirm) {
+			while (rcnf() == confirm)
 				store_flash();
-			}
 			break;
 		case 'e': // read EEPROM, one page per host '!', until the host stops
 			for (;;) {
-				if (rx() != confirm) {
+				if (rx() != confirm)
 					break;
-				}
 				g_cnt = page;
 				do {
 					tx(eerd());
@@ -358,9 +335,8 @@ extern "C" [[noreturn]] void tsb_app(); // the application's reset vector: --def
 			sendf();
 			break;
 		case 'C': // replace the config page, then echo it back to verify
-			if (rcnf() != confirm) {
+			if (rcnf() != confirm)
 				break;
-			}
 			g_addr = app_end + page;
 			erase_below(); // leaves g_addr = app_end, the store target
 			store_flash();
@@ -374,6 +350,14 @@ extern "C" [[noreturn]] void tsb_app(); // the application's reset vector: --def
 } // namespace
 } // namespace tsb
 
-// Reset lands at the boot section base (BOOTRST): the entry stub in .vectors
-// is laid first and does the one line of crt a crt-less image needs.
-template struct avr::startup::entry<tsb::run, avr::startup::stack::hardware>;
+// Reset lands here: BOOTRST vectors to the boot section base and .vectors is
+// laid first, so this is the first instruction executed. No crt ran, so set
+// the stack pointer before anything is called.
+extern "C" [[gnu::naked, gnu::used, gnu::section(".vectors")]] void __boot_entry()
+{
+	SP = RAMEND;
+	// The one line of crt this loader needs: compiled code assumes
+	// __zero_reg__ (r1) is 0, and power-on registers are undefined.
+	asm volatile("clr __zero_reg__");
+	tsb::run();
+}