build: emit an Intel-HEX beside every loader image

avrdude programs Intel-HEX, not ELF, and the build produced only ELFs — so flashing a loader to a real chip meant running objcopy by hand. add_hex_output() hangs a POST_BUILD objcopy on each loader image: the three tsb tiers through add_tsb_variant, pureboot, and the re-timed pureboot9. .eeprom is dropped, being its own avrdude update. It uses the toolchain file's CMAKE_OBJCOPY rather than a hardcoded path, so every chip preset emits hex, not just the mega. pbapp keeps its ELF alone: the update test converts it to a raw binary itself, and it is not a flashing target. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
pureboot: PI lint, tightened gates, and the self-update test suite
2026-07-20 21:57:26 +02:00 · 2026-07-20 19:37:57 +02:00 · 2026-07-20 19:37:43 +02:00 · 2026-07-20 19:37:10 +02:00 · 2026-07-20 10:45:19 +02:00 · 2026-07-20 10:43:56 +02:00
21 changed files with 910 additions and 4879 deletions
--- a/.gitmodules
+++ b/.gitmodules
@@ -1,3 +0,0 @@
 [submodule "libavr"]
 	path = libavr
 	url = ../libavr.git
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -8,9 +8,6 @@ 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)
 endif()
 if(LIBAVR_ROOT)
 	FetchContent_Declare(libavr SOURCE_DIR ${LIBAVR_ROOT})
 else()
@@ -54,18 +51,13 @@ if(PROJECT_IS_TOP_LEVEL)
 	endif()
 endif()
-# The ELF is only a container (symbols, section headers) and is never flashed —
+# avrdude programs Intel-HEX; the ELF is only a container (symbols, section
-# and the host tool's load_image() dispatches on extension, so handing it one
+# headers) and is never flashed. Every loader image therefore gets a .hex beside
-# would silently program the header bytes. Every loader image therefore gets
+# it at link time. .eeprom is dropped — EEPROM content is its own avrdude update.
-# both flashable forms beside it at link time: .hex for avrdude, and .bin for
+function(add_hex_output name)
 # 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.
 function(add_image_outputs name)
 	add_custom_command(TARGET ${name} POST_BUILD
 	                   COMMAND ${CMAKE_OBJCOPY} -O ihex -R .eeprom
-	                           $<TARGET_FILE:${name}> $<TARGET_FILE:${name}>.hex
+	                           $<TARGET_FILE:${name}> $<TARGET_FILE:${name}>.hex)
 	                   COMMAND ${CMAKE_OBJCOPY} -O binary -R .eeprom
 	                           $<TARGET_FILE:${name}> $<TARGET_FILE:${name}>.bin)
 endfunction()
 # The TinySafeBoot protocol reimplemented on libavr in three variants that trade
@@ -107,7 +99,7 @@ function(add_tsb_variant name bytes)
 	target_link_options(${name} PRIVATE -nostartfiles -Wl,--section-start=.text=${base_hex}
 	                    -Wl,--defsym=tsb_app=0 -Wl,--pmem-wrap-around=32k)
 	add_custom_command(TARGET ${name} POST_BUILD COMMAND ${CMAKE_SIZE} $<TARGET_FILE:${name}>)
-	add_image_outputs(${name})
+	add_hex_output(${name})
 	if(PROJECT_IS_TOP_LEVEL)
 		add_test(NAME ${name}.size
 		         COMMAND ${CMAKE_COMMAND} -DSIZE_TOOL=${CMAKE_SIZE} -DELF=$<TARGET_FILE:${name}>
@@ -129,34 +121,70 @@ if(LIBAVR_MCU STREQUAL "atmega328p")
 endif()
 # pureboot — the pure-constraint port (see pureboot/README.md): one source,
-# no inline assembly, no global register variables, every libavr chip,
+# no inline assembly, no global register variables, every libavr chip, 512
-# fitting each chip's smallest boot sector. The geometry and the
+# bytes each. The loader owns the top 512 bytes of flash on every chip; the
-# pureboot_add_loader() deployment function live in pureboot/CMakeLists.txt —
+# application entry symbol is address 0 on the mega (reset re-vectors to the
-# the unit a downstream project consumes; everything below is this port's
+# loader through BOOTRST, so word 0 stays the application's own vector) and
-# own build: the stock loaders, their tests, and the size matrix. The
+# the trampoline word just below the loader on the tinies (host-side vector
-# distinct binary dir keeps the `pureboot` target's output name free.
+# surgery points it at the application). --pmem-wrap-around models AVR's
-add_subdirectory(pureboot pureboot-cmake)
+# modulo-flash PC where the flash is big enough to need it.
-
+#
-# The stock loader: the family-default deployment (crystal/RC clock, the
+# The image is position-independent (check_pi.py asserts the two link-time
-# chip's natural link, default pins). The activation window stays a cache
+# facts that make it so), and on the tinies its budget is 510, not 512: the
-# variable — re-timing a deployed loader is a self-update with a re-timed
+# slot's last word is the trampoline the host composes — the resident slot's
-# build. pureboot9 is that re-timed build, and what the update test installs.
+# holds the application entry, and a staging copy's holds the jump through
 # which it reaches the loader it installed. The activation window is a
 # compile-time constant; a different PUREBOOT_TIMEOUT builds the re-timed
 # binary a self-update then installs.
 set(PUREBOOT_TIMEOUT 8 CACHE STRING "pureboot activation window, seconds")
-pureboot_add_loader(pureboot TIMEOUT ${PUREBOOT_TIMEOUT})
+if(LIBAVR_MCU STREQUAL "attiny13a")
-if(PROJECT_IS_TOP_LEVEL)
+	set(_pb_flash 1024)
-	get_target_property(_pb_stock_hz pureboot PUREBOOT_HZ)
+	set(_pb_wrap "")
-	get_target_property(_pb_stock_baud pureboot PUREBOOT_BAUD)
+	set(_pb_page 32)
 	set(_pb_hz 9600000)
 	set(_pb_baud 57600)
 	set(_pb_eeprom 64)
 	set(_pb_limit 510)
 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_baud 57600)
 	set(_pb_eeprom 512)
 	set(_pb_limit 510)
 else()
 	set(_pb_flash 32768)
 	set(_pb_wrap -Wl,--pmem-wrap-around=32k)
 	set(_pb_page 128)
 	set(_pb_hz 16000000)
 	set(_pb_baud 115200)
 	set(_pb_eeprom 1024)
 	set(_pb_limit 512)
 endif()
 math(EXPR _pb_base "${_pb_flash} - 512")
 math(EXPR _pb_base_hex "${_pb_base}" OUTPUT_FORMAT HEXADECIMAL)
 if(LIBAVR_MCU STREQUAL "atmega328p")
 	set(_pb_app 0)
 else()
 	math(EXPR _pb_app "${_pb_base} - 2")
 endif()
 add_executable(pureboot pureboot/pureboot.cpp)
 target_link_libraries(pureboot PRIVATE libavr)
 target_compile_definitions(pureboot PRIVATE PUREBOOT_TIMEOUT=${PUREBOOT_TIMEOUT})
 target_link_options(pureboot PRIVATE -nostartfiles -Wl,--section-start=.text=${_pb_base_hex}
                    -Wl,--defsym=pureboot_app=${_pb_app} ${_pb_wrap})
 add_custom_command(TARGET pureboot POST_BUILD COMMAND ${CMAKE_SIZE} $<TARGET_FILE:pureboot>)
 add_hex_output(pureboot)
 if(PROJECT_IS_TOP_LEVEL)
 	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)
+	                 -DLIMIT=${_pb_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_OBJCOPY} ${CMAKE_CXX_COMPILER} ${LIBAVR_MCU}
+		                 ${CMAKE_OBJDUMP} ${CMAKE_NM} $<TARGET_FILE:pureboot> ${_pb_base_hex})
 		                 $<TARGET_FILE:pureboot>
 		                 ${CMAKE_BINARY_DIR}/CMakeFiles/pureboot.dir/pureboot/pureboot.cpp.obj
 		                 ${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)
@@ -172,9 +200,9 @@ if(PROJECT_IS_TOP_LEVEL)
 		                   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}
+		                 ${PB_DEVICE} $<TARGET_FILE:pureboot> ${LIBAVR_MCU} ${_pb_hz} ${_pb_base_hex}
-		                 ${PUREBOOT_BASE_HEX} ${PUREBOOT_PAGE} ${_pb_stock_baud} ${PUREBOOT_EEPROM}
+		                 ${_pb_page} ${_pb_baud} ${_pb_eeprom} $<TARGET_FILE:pbapp>.bin
-		                 $<TARGET_FILE:pbapp>.bin ${CMAKE_CURRENT_SOURCE_DIR}/pureboot/pureboot.py
+		                 ${CMAKE_CURRENT_SOURCE_DIR}/pureboot/pureboot.py
 		                 ${CMAKE_BINARY_DIR}/pbtest-work)
 		set_tests_properties(pureboot.protocol PROPERTIES TIMEOUT 180)
@@ -182,235 +210,29 @@ if(PROJECT_IS_TOP_LEVEL)
 		# 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}
+		                 ${PB_DEVICE} $<TARGET_FILE:pureboot> ${LIBAVR_MCU} ${_pb_hz} ${_pb_base_hex}
-		                 ${PUREBOOT_BASE_HEX} ${PUREBOOT_PAGE} ${_pb_stock_baud}
+		                 ${_pb_page} ${_pb_baud} ${CMAKE_CURRENT_SOURCE_DIR}/pureboot/pureboot.py
 		                 ${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}")
 		# Entering the loader from a running application with no reset
 		# between, over a page buffer the application dirtied — the case the
 		# loader declines to guard and the host repairs. Hardware forbids the
 		# state here (SPM runs only from the boot section); simavr does not,
 		# which is what makes it constructible.
 		if(LIBAVR_MCU STREQUAL "atmega328p")
 			add_test(NAME pureboot.dirty
 			         COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/test/pbdirty.py
 			                 ${PB_DEVICE} $<TARGET_FILE:pureboot> ${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}/pbdirty-work)
 			set_tests_properties(pureboot.dirty PROPERTIES TIMEOUT 180)
 		endif()
 		# 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
+		# PUREBOOT_TIMEOUT differs — a byte-different image) replaces the
-		# through --update-loader, with every power-fail phase rehearsed from
+		# resident through --update-loader, with every power-fail phase
-		# the runner's flash dumps.
+		# rehearsed from the runner's flash dumps.
-		pureboot_add_loader(pureboot9 TIMEOUT 9)
+		add_executable(pureboot9 pureboot/pureboot.cpp)
 		target_link_libraries(pureboot9 PRIVATE libavr)
 		target_compile_definitions(pureboot9 PRIVATE PUREBOOT_TIMEOUT=9)
 		target_link_options(pureboot9 PRIVATE -nostartfiles -Wl,--section-start=.text=${_pb_base_hex}
 		                    -Wl,--defsym=pureboot_app=${_pb_app} ${_pb_wrap})
 		add_hex_output(pureboot9)
 		add_test(NAME pureboot.update
 		         COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/test/pbupdate.py
-		                 ${PB_DEVICE} $<TARGET_FILE:pureboot> $<TARGET_FILE:pureboot9>
+		                 ${PB_DEVICE} $<TARGET_FILE:pureboot> $<TARGET_FILE:pureboot9> ${LIBAVR_MCU}
-		                 ${PUREBOOT_SIM_MCU} ${_pb_stock_hz} ${PUREBOOT_BASE_HEX} ${PUREBOOT_PAGE}
+		                 ${_pb_hz} ${_pb_base_hex} ${_pb_page} ${_pb_baud} $<TARGET_FILE:pbapp>.bin
 		                 ${_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 USART instance
 	# (different registers), the clock (different constants), and the baud
 	# through the shapes its bit timing takes — 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()
 	# The autobaud loader: one clock-agnostic image per chip, so it has no
 	# clock x baud axis of its own — the matrix below sweeps those for the
 	# fixed-baud builds, and this one binary has to serve all of them at run
 	# time. Size-tested against the same per-chip budget as every other variant.
 	pureboot_add_loader(pureboot_autobaud SERIAL autobaud)
 	add_test(NAME pureboot_autobaud.size
 	         COMMAND ${CMAKE_COMMAND} -DSIZE_TOOL=${CMAKE_SIZE} -DELF=$<TARGET_FILE:pureboot_autobaud>
 	                 -DLIMIT=${PUREBOOT_LIMIT} -P ${CMAKE_CURRENT_SOURCE_DIR}/test/check_size.cmake)
 	# One point of the exhaustive matrix, named from its resolved parameters
 	# so the enumeration cannot collide with itself. Unreachable rates drop
 	# out here rather than aborting the configure.
 	function(pureboot_matrix_point hz baud link)
 		if(link STREQUAL "software")
 			pureboot_baud_feasible(${hz} ${baud} 1 _ok)
 			set(_args SERIAL software)
 		else()
 			pureboot_baud_feasible(${hz} ${baud} 0 _ok)
 			set(_args USART ${link})
 		endif()
 		if(_ok)
 			pureboot_size_variant(pbm_${hz}_${baud}_${link} CLOCK ${hz} BAUD ${baud} ${_args})
 		endif()
 	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)
 		set(_full_clocks 128000 600000 1200000 4800000 9600000)
 	else()
 		set(_matrix_clocks 1000000 8000000 16000000)
 		set(_full_clocks 128000 1000000 1843200 2000000 3686400 4000000 7372800 8000000
 		                 11059200 12000000 14745600 16000000 18432000 20000000)
 	endif()
 	# The exhaustive cross product: every clock a deployment plausibly runs
 	# — the internal oscillators, the shipped CKDIV8 floor, the plain
 	# crystals and the UART crystals — against every rate, against every
 	# backend. Beyond the ladder the list carries the slow rates a
 	# sub-megahertz oscillator is left with, which no ladder rate reaches
 	# (16000 Bd is the only rate the 128 kHz oscillator holds exactly); at
 	# the fast clocks those same rates also select the software UART's
 	# 16-bit _delay_loop_2 bit spin (two words more setup at each of its five
 	# sites), the largest image the space produces and a shape the ladder
 	# default — always the *fastest* rate a clock reaches — never picks.
 	#
 	# Every chip runs the full cross product: the size-bearing classes (flash
 	# addressing, hand-over shape, page size, USART inventory) are what make
 	# the image differ, and a chip outside them is expected to match its class
 	# — but "expected" is what a matrix is for, and the whole sweep is cheap
 	# enough to run rather than reason about. PUREBOOT_FULL_MATRIX is what
 	# selects it; the compact matrix below is the per-commit default.
 	get_property(_full_bauds GLOBAL PROPERTY PUREBOOT_BAUD_LADDER)
 	list(APPEND _full_bauds 16000 4800 2400 1200)
 	if(DEFINED ENV{PUREBOOT_FULL_MATRIX})
 		foreach(_matrix_hz IN LISTS _full_clocks)
 			foreach(_matrix_baud IN LISTS _full_bauds)
 				pureboot_matrix_point(${_matrix_hz} ${_matrix_baud} software)
 				if(PUREBOOT_HAS_USART)
 					pureboot_matrix_point(${_matrix_hz} ${_matrix_baud} 0)
 				endif()
 				if(PUREBOOT_HAS_USART1)
 					pureboot_matrix_point(${_matrix_hz} ${_matrix_baud} 1)
 				endif()
 			endforeach()
 		endforeach()
 	else()
 		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()
 			if(PUREBOOT_HAS_USART1 AND NOT _matrix_hz EQUAL _pb_stock_hz)
 				pureboot_size_variant(pureboot_usart1_${_matrix_khz}k CLOCK ${_matrix_hz} USART 1)
 			endif()
 		endforeach()
 		list(GET _matrix_clocks -1 _matrix_top_hz)
 		pureboot_size_variant(pureboot_sw_wide CLOCK ${_matrix_top_hz} BAUD 9600 SERIAL software)
 	endif()
 	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()
 	# The autobaud variants driven end to end over the software-UART bridge (both
 	# under review — pureboot/autobaud.md): the host sends the 0xC0 calibration
 	# pulse, the loader times it, locks, and programs. Run on the near-flash 328P
 	# and the word-addressed 1284P — the two flash-addressing classes — and each
 	# at two clocks with the one binary, which is the clock-agnostic property
 	# autobaud exists for (test/pbautobaud.py). The fixture application banners
 	# over the same software link at the first clock's rate.
 	if(LIBAVR_MCU MATCHES "^atmega(328p|1284p)$" AND DEFINED PB_DEVICE)
 		add_executable(pbapp_autobaud test/pbapp.cpp)
 		target_link_libraries(pbapp_autobaud PRIVATE libavr)
 		target_compile_definitions(pbapp_autobaud PRIVATE PUREBOOT_CLOCK_HZ=1000000
 		                           PUREBOOT_BAUD=9600 PUREBOOT_SOFT_SERIAL PUREBOOT_TX=pb1)
 		add_custom_command(TARGET pbapp_autobaud POST_BUILD
 		                   COMMAND ${CMAKE_OBJCOPY} -O binary
 		                           $<TARGET_FILE:pbapp_autobaud> $<TARGET_FILE:pbapp_autobaud>.bin)
 		add_test(NAME pureboot.autobaud
 		         COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/test/pbautobaud.py
 		                 ${PB_DEVICE} $<TARGET_FILE:pureboot_autobaud> ${PUREBOOT_SIM_MCU}
 		                 ${PUREBOOT_BASE_HEX} ${PUREBOOT_PAGE} $<TARGET_FILE:pbapp_autobaud>.bin
 		                 1000000 9600 ${CMAKE_CURRENT_SOURCE_DIR}/pureboot/pureboot.py
 		                 ${CMAKE_BINARY_DIR}/pbautobaud-work)
 		set_tests_properties(pureboot.autobaud PROPERTIES TIMEOUT 240)
 	endif()
 endif()
--- a/CMakePresets.json
+++ b/CMakePresets.json
--- a/1
+++ b/1
--- a/pureboot/CMakeLists.txt
+++ b/pureboot/CMakeLists.txt
@@ -1,329 +0,0 @@
 # 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.
 # A downstream project brings its usual libavr setup (the `libavr` target and
 # the LIBAVR_MCU toolchain preset), adds this directory, and states its
 # deployment; every argument is optional (README.md):
 #
 #   add_subdirectory(bootloader/pureboot)
 #   pureboot_add_loader(myboot CLOCK 1000000 SERIAL software TX pb1 RX pb5)
 # Per-family geometry, deployment defaults, and the linker wrap the PC modulo
 # needs. The slot is 512 bytes on every chip. 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, so plain LPM still reaches
 	# everything and the wire stays byte-addressed. 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 addresses are words, reads go through ELPM, and the PC's
 	# modulo wrap exceeds what --pmem-wrap-around models.
 	set(_pb_flash 131072)
 	set(_pb_wrap "")
 	set(_pb_page 256)
 	set(_pb_hz 16000000)
 	set(_pb_eeprom 4096)
 	set(_pb_has_usart1 1)
 else()
 	message(FATAL_ERROR "pureboot: no geometry for ${LIBAVR_MCU}")
 endif()
 set(_pb_slot 512)
 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)
 	set(_pb_limit ${_pb_slot})
 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 rates a default may pick, fastest first.
 set_property(GLOBAL PROPERTY PUREBOOT_BAUD_LADDER 115200 57600 38400 19200 9600)
 # Whether <baud> is reachable from <clock> within 2.5 %, by the same
 # best-of-U2X-and-plain divisor search libavr's solve_baud runs, so a build
 # never trips the compile-time error it is checked against. A software build
 # also needs the polled receiver's 100-cycles-a-bit floor: at low clocks the
 # U2X divisor reaches rates the bit-banged sampler cannot.
 function(pureboot_baud_feasible clock baud software outvar)
 	set(${outvar} 0 PARENT_SCOPE)
 	math(EXPR _cycles "${clock} / ${baud}")
 	if(software AND _cycles LESS 100)
 		return()
 	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} 1 PARENT_SCOPE)
 			return()
 		endif()
 	endforeach()
 endfunction()
 # The fastest ladder rate the clock reaches.
 function(pureboot_default_baud clock software outvar)
 	get_property(_ladder GLOBAL PROPERTY PUREBOOT_BAUD_LADDER)
 	foreach(baud ${_ladder})
 		pureboot_baud_feasible(${clock} ${baud} ${software} _ok)
 		if(_ok)
 			set(${outvar} ${baud} PARENT_SCOPE)
 			return()
 		endif()
 	endforeach()
 	message(FATAL_ERROR "pureboot: no standard baud rate fits a ${clock} Hz clock within 2.5 % "
 	        "— pass BAUD <rate> to deploy a non-standard one")
 endfunction()
 # pureboot_add_loader(<name> [CLOCK <hz>] [BAUD <bd>]
 #                     [SERIAL auto|hardware|software|autobaud] [USART <n>]
 #                     [RX <pin>] [TX <pin>] [TIMEOUT <s>])
 #
 # The loader target plus its flashable images (<name>.hex for a programmer,
 # <name>.bin for --update-loader). The resolved deployment is stamped on the
 # target as PUREBOOT_HZ / PUREBOOT_BAUD / PUREBOOT_LINK (the link spelled
 # usart0, usart1 or sw:<RX>,<TX>) — what a test harness speaks to it with.
 #
 # SERIAL autobaud measures the host's bit timing at run time, so the image
 # carries no clock and no baud: CLOCK and BAUD are not build parameters there,
 # and one binary per chip serves every F_CPU and every rate. The stamped
 # PUREBOOT_HZ/PUREBOOT_BAUD then record what a harness should *drive* it at,
 # not what it was built for.
 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 NOT PB_SERIAL MATCHES "^(auto|hardware)$")
 		message(FATAL_ERROR "pureboot_add_loader(${name}): USART ${PB_USART} contradicts SERIAL ${PB_SERIAL}")
 	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 MATCHES "^(software|autobaud)$")
 			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()
 			if(PB_SERIAL STREQUAL "autobaud")
 				set(_serial_defines PUREBOOT_AUTOBAUD PUREBOOT_RX=${PB_RX} PUREBOOT_TX=${PB_TX})
 			else()
 				set(_serial_defines PUREBOOT_SOFT_SERIAL PUREBOOT_RX=${PB_RX} PUREBOOT_TX=${PB_TX})
 			endif()
 			# sw:<RX>,<TX> as port letter and bit, 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()
 	if(PB_SERIAL STREQUAL "autobaud")
 		# No clock and no baud reach the image; the window is a poll budget.
 		set(_defines ${_serial_defines})
 	else()
 		set(_defines PUREBOOT_CLOCK_HZ=${PB_CLOCK} PUREBOOT_BAUD=${PB_BAUD} PUREBOOT_TIMEOUT=${PB_TIMEOUT}
 		    ${_serial_defines})
 	endif()
 	add_executable(${name} ${CMAKE_CURRENT_FUNCTION_LIST_DIR}/pureboot.cpp)
 	target_link_libraries(${name} PRIVATE libavr)
 	target_compile_definitions(${name} PRIVATE ${_defines})
 	# Codegen shaping for the loader TU only. At -Os GCC otherwise rewrites the
 	# byte-stream loops' counters into end-pointer forms that cost registers
 	# (-fno-ivopts, -fno-split-wide-types), leaves register pressure on the
 	# table with the default allocator (-fira-algorithm=priority), and keeps
 	# expression temporaries in registers (-fno-tree-ter) — but every loop body
 	# here contains a call, so a register held across it costs more than the
 	# load-immediate it saves. The set is fitted to the loader's body and has to
 	# be re-measured when that body changes: -fno-move-loop-invariants belonged
 	# here while the command loop carried four transfer bodies and costs bytes
 	# now that it carries one.
 	target_compile_options(${name} PRIVATE
 	    -fno-ivopts -fira-algorithm=priority -fno-tree-ter -fno-split-wide-types)
 	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, never flashed: .hex for a programmer, .bin (the
 	# slot's bare bytes) for --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()
--- a/pureboot/README.md
+++ b/pureboot/README.md
@@ -2,291 +2,104 @@
 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 and compiler flags allowed), **512 bytes on every chip libavr
+(attributes allowed), built for every chip libavr targets, **512 bytes on
-targets — all 37**. The device speaks primitives; every composite — verify,
+each** — 488 B on the ATtiny13A, 502 B on the ATtiny85, 504 B on the
-erase, reset-vector surgery, updating the loader itself — lives in the host
+ATmega328P. The device speaks primitives; every composite — verify, erase,
-tool (`pureboot.py`).
+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
-transfer paths take wire addresses, the write guard protects the slot the code
+read/write paths take wire addresses, the write guard protects the 512-byte
-is *running* in (from the runtime return address), nothing else is
+slot the code is *running* in (from the runtime return address), the info
-flash-resident to address at all, and the application jump is an indirect call
+block is addressed from that same anchor, and the application jump is an
-to an absolute entry. The identical binary therefore runs from any slot with
+indirect call to an absolute entry. The identical binary therefore runs from
-every command intact, which makes pureboot **its own staging loader**: the host
+any 512-byte slot with every command intact — which makes pureboot **its own
-installs the same binary one slot below the resident, jumps into it, and lets
+staging loader**: the host installs the same binary one slot below the
-it rewrite the resident. The lint holds it to that literally — the image must
+resident, jumps into it, and lets it rewrite the resident. On the tinies the
-come out byte-identical linked at a different base.
+budget is 510, not 512: a slot's last word belongs to the host-managed
 trampoline (below).
-## Chips
+## Link
-Sizes are the default configuration: the hardware USART0 at 115200 8N1 on a
+| Chip | Serial | Baud | Clock assumed |
-16 MHz crystal, or the software UART on RX = PB0 / TX = PB1 at 57600 8N1 on
+|---|---|---|---|
-the tinies' RC oscillator (9.6 MHz on the t13s, 8 MHz above). Every axis moves
+| ATmega328P | USART0, RXD/TXD = PD0/PD1 | 115200 8N1 | 16 MHz crystal |
-per build — see *Configuration*. The autobaud column is the clock-free build,
+| ATtiny85 | software UART, RX = PB0, TX = PB1 | 57600 8N1 | 8 MHz internal RC |
-which is the largest the space produces and the tightest fit in the matrix;
+| ATtiny13A | software UART, RX = PB0, TX = PB1 | 57600 8N1 | 9.6 MHz internal RC |
 it carries the calibration machinery and no clock at all.
-| Chip | Flash | Loader at | Link | Stock | Autobaud |
+The tiny RX pin has its pull-up enabled; TX idles high. All multi-byte
-|---|---|---|---|---|---|
+quantities on the wire are little-endian.
 | ATtiny13, ATtiny13A † | 1 KiB | 0x0200 | software | 402 B | 472 B |
 | ATtiny25 † | 2 KiB | 0x0600 | software | 406 B | 476 B |
 | ATtiny45 † | 4 KiB | 0x0e00 | software | 410 B | 480 B |
 | ATtiny85 † | 8 KiB | 0x1e00 | software | 410 B | 480 B |
 | ATmega8, 8A | 8 KiB | 0x1e00 | USART0 | 372 B | 486 B |
 | ATmega16, 16A | 16 KiB | 0x3e00 | USART0 | 374 B | 490 B |
 | ATmega32, 32A | 32 KiB | 0x7e00 | USART0 | 374 B | 490 B |
 | ATmega48, 48A, 48P, 48PA † | 4 KiB | 0x0e00 | USART0 | 400 B | 476 B |
 | ATmega88, 88A, 88P, 88PA | 8 KiB | 0x1e00 | USART0 | 410 B | 486 B |
 | ATmega168, 168A, 168P, 168PA | 16 KiB | 0x3e00 | USART0 | 412 B | 490 B |
 | ATmega328, 328P | 32 KiB | 0x7e00 | USART0 | 412 B | 490 B |
 | ATmega164A, 164P, 164PA | 16 KiB | 0x3e00 | USART0 | 412 B | 490 B |
 | ATmega324A, 324P, 324PA | 32 KiB | 0x7e00 | USART0 | 412 B | 490 B |
 | ATmega644, 644A, 644P, 644PA | 64 KiB | 0xfe00 | USART0 | 406 B | 484 B |
 | ATmega1284, 1284P | 128 KiB | 0x1fe00 | USART0 | 432 B | 510 B |
 † No hardware boot section: the host patches the reset vector, and the budget
 is 510 bytes, since the slot's last word is the trampoline.
 The tightest fit in the whole space is the 1284s' autobaud build, 510 of its
 512 — they alone carry the far-flash machinery (ELPM reads, RAMPZ page
 commands) and autobaud alone carries the calibration loop. Everything else has
 20 B of headroom or more. The flash bank riding in a transfer's selector byte
 keeps even those chips' addressing the same 16-bit form every other chip uses,
 which is why they are no longer the outlier they were.
 The software UART enables the RX pull-up; TX idles high. All multi-byte wire
 quantities are little-endian.
 ## Configuration
 Every deployment axis is a build parameter of `pureboot_add_loader()` (in
 `pureboot/CMakeLists.txt`) — the one way a loader target is created, by this
 repo's 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\|autobaud` | 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. Whatever is picked or overridden is
 re-checked in the compile: an infeasible combination, or a USART the chip does
 not have, fails with a named static assert.
 `SERIAL autobaud` takes neither: the loader **measures** the host's bit timing
 at run time, so `CLOCK` and `BAUD` are not build parameters there and one
 binary per chip serves every clock and every rate. It is for the deployments
 whose clock is not known at build time and does not hold still — the internal
 RC oscillator, ±10 % from the factory and moving with supply and temperature —
 where a fixed-baud software build has to be rebuilt per clock and still drifts
 out of tolerance. The cost is that it is software-serial only (a hardware USART
 needs its divisor programmed) and that activation counts poll iterations rather
 than seconds, since there is no clock to convert them against
 (`PUREBOOT_AUTOBAUD_POLLS`, default 4,000,000).
 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 — an ATmega328P on its shipped 1 MHz fuses with the
 software UART on hand-picked pins, say:
 ```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 deployment runs the full protocol suite in CI
 (`pureboot.custom`).
 ## Activation
-Reset enters the loader (BOOTRST on the boot-sectioned megas, the patched
+Reset enters the loader (BOOTRST on the mega, the patched reset vector on the
-reset vector elsewhere) — except a watchdog reset, which hands straight to the
+tinies) — except a watchdog reset, which hands straight to the application
-application with no activation window, since the application owns its watchdog.
+(the application owns its watchdog; it must clear WDRF itself, which also
-This is deliberate: it lets an application reboot itself instantly rather than
+releases the WDRF-forced WDE).
 sit through the window. The application must clear WDRF itself (libavr's
 `watchdog::disable()` does). **Gotcha:** WDRF is sticky (cleared only by
 software, not by a later reset), so an application that watchdog-resets and
 never clears it diverts *every* subsequent reset — external ones included —
 past the window too, and the loader becomes reachable only through an external
 programmer until the flag is cleared. A serial recovery path therefore assumes
 the application clears WDRF on its own reset path.
-The host then knocks `p` then `b`, each awaited byte under a fresh activation
+The host then has one activation window per awaited byte to knock: `p` then
-window; any other byte is discarded and awaited again, so line noise can delay
+`b`. Each awaited byte gets a fresh window; any other byte is discarded and
-the loader but never lock it. A window expiring on an idle line boots the
+awaited again (line noise cannot lock the loader, only delay it). A window
-application.
+expiring with an idle line boots the application.
-An autobaud build opens differently, because it has to learn the rate before it
+The window length is a compile-time constant — 8 s by default, another value
-can read a byte at all: the host sends the **calibration byte 0xC0** — a start
+via the `PUREBOOT_TIMEOUT` CMake cache variable — so the whole EEPROM belongs
-bit plus six zero data bits form one low pulse of seven bit-times — and the
+to the application; pureboot never uses it for its own state. Re-timing a
-loader times that pulse into its bit period. A single `p` then activates; the
+deployed loader is a self-update with a re-timed build (below).
 pulse has already proven a host is present, which the two-byte knock exists to
 establish elsewhere. Both waits are bounded, so a stray low pulse with no host
 behind it costs one window and then boots the application rather than holding
 the loader.
 The window is a compile-time constant (`TIMEOUT`, 8 s by default), so the whole
 EEPROM belongs to the application — pureboot keeps no state of its own.
 Re-timing a deployed loader is a self-update with a re-timed build. An autobaud
 build counts poll iterations instead (`PUREBOOT_AUTOBAUD_POLLS`), there being
 no clock to turn into seconds.
 ## 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 and sends the prompt `+` (0x2b), which is therefore also the previous
+write to finish and sends the prompt `+` (0x2b) — the prompt is therefore
-command's completion ack. A session is: await `+`, send a command, read its
+also the completion ack of the previous command. A session is: await `+`,
-reply, repeat.
+send a command, read its reply, repeat.
 Addresses are **byte addresses within a 64 KiB bank**, and the bank rides in
 the command's selector byte, so no command has to speak word addresses. `J` is
 the exception: it takes a word address, because that is what the hardware's own
 jump takes. EEPROM and data-space addresses and all counts are bytes.
 The loader trusts the host to keep addresses in range: it does not bound them
 against the chip. **Gotcha:** a write (or read) that runs past `E2END` wraps —
 EEAR is only as wide as the array, so an address past the end truncates onto
 low EEPROM and the write silently overwrites it. Keeping transfers within the
 real sizes is the host's job (the shipped tool does); the flash budget is
 better spent on features than on re-checking a bound the host already holds.
 | Cmd | Arguments | Reply |
 |---|---|---|
-| `b` | — | 4 bytes: the pureboot version, then the three signature bytes |
+| `b` | — | the 12-byte info block |
-| `G` | sel8, addr16, n8 | n bytes from the selected space (n = 0 means 256) |
+| `R` | addr16, n8 | n flash bytes (n = 0 means 256) |
-| `g` | sel8, addr16, n8, then n data bytes | `+` per byte, sent once its write has begun |
+| `W` | addr16, then one page of data | — (completion = next prompt) |
-| `W` | sel8, 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) |
-`G` and `g` are one letter in two cases, which is the whole command set for
+`W` streams exactly one SPM page (size from the info block) into the buffer,
-every memory: the **selector** byte's low nibble names the space and its high
+then erases and programs; the address must be page-aligned. Pages inside the
-nibble carries the flash bank.
+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.
-| Space | | |
+`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
-| 0 | flash | read-only here; it is written through `W` and the SPM space |
+known from the info block) and to move between loader copies during a
-| 1 | EEPROM | |
+self-update. A jump to a loader slot's base re-enters that copy's own
-| 2 | data | SRAM — and with it the register file and every I/O register, which share the data address space on AVR |
+startup; it must then be knocked afresh.
 | 3 | fuse and lock | index 0..3 in the hardware's own Z order: low, lock, extended, high |
 | 4 | SPM | write-only: the byte goes to SPMCSR and fires the instruction at the address |
-The data space is worth more than it looks. pureboot keeps **zero static RAM**
+The info block (`b`):
 and pushes no register, so at loader entry an application's SRAM is still
 whatever the application left there, bar the handful of bytes of return-address
 stack — which makes `G` over space 2 a post-mortem of a running application,
 not just a poke hole. The same address space carries the register file and the
 I/O registers, so peripheral state is readable too; reading some of those has
 side effects (reading UDR clears its flags), which is the host's business to
 know.
-Programming a page is therefore `W` to fill the buffer, then a `g` to the SPM
+| Offset | Content |
-space for the erase, another for the write, and on a boot-sectioned chip a
+|---|---|
-third to re-enable the RWW section — `0x03`, `0x05` and `0x11`, the SPMCSR
+| 0–2 | `'P'`, `'B'`, protocol version (1) |
-encodings every part pureboot targets shares. The loader carries no page-commit
+| 3–5 | device signature |
-logic of its own, and the same primitive reaches every other SPM operation,
+| 6 | SPM page size in bytes |
-lock bits included.
+| 7–8 | loader base — application flash ends here |
 | 9–10 | EEPROM size |
 | 11 | bit 0 set: host must patch the reset vector (no hardware boot section) |
-The SPM store and the SPM instruction must issue within four cycles of each
+Composites are the host's job: verify = read back and compare, erase =
-other (§26.2), which no host can hit across a serial link — so this one
+write `0xff` (per page for flash, per byte for EEPROM).
 primitive is *fused* rather than being a poke of SPMCSR followed by a poke of
 something else. That four-cycle window is the floor on how low-level a
 bootloader's primitives can go; it is not a byte-count decision.
 An SPM command aimed at the 512-byte slot the loader is **running in** is
 dropped, so a broken host cannot brick the running copy, while a staged copy
 one slot lower may rewrite the resident — which is what a self-update is.
 The loader never clears the SPM buffer before a fill, so **one `W` may program
 the wrong bytes, and the host is what fixes it**. The buffer is write-once per
 word until cleared, and two things leave words in it: a refused page, and —
 where SPM runs from anywhere, the tinies and the m48s — an application that
 self-programmed before entering. The next page write takes those stale words
 and clears them, since a page write auto-erases the buffer (§26.2.1; §19.2 on
 the tinies), so repeating it programs correctly. The host therefore verifies
 every page it writes and rewrites what comes back wrong (three retries, then it
 stops).
 `g` is host-paced: send the next byte only after the previous byte's `+`. Fuse
 *writing* does not exist — SPM reaches flash and boot lock bits only.
 `J` is the one control-transfer primitive: it runs the application (word 0 or
 the trampoline word, both derived from the chip) and moves between loader
 copies during a self-update. A jump to a slot's base re-enters that copy's own
 startup, which must then be knocked afresh.
 `b` answers with the loader's identity — its version and the chip's signature —
 and nothing else. Everything else the host needs (page size, loader base,
 EEPROM size, whether the reset vector must be patched, how many flash banks)
 follows from the signature, and the host holds that table; the loader derived
 the same facts from its own chip database at build time, so nothing is guessed,
 it is simply not sent twice.
 An update image, though, is a bare 512-byte slot with no device to ask, and
 installing one built for another chip bricks the target. Every loader image
 therefore carries a six-byte **stamp** — `'P'`, `'B'`, the version, the three
 signature bytes — which the loader itself never reads and the host tool refuses
 to install a mismatch against.
 ## Version
 `b`'s first byte is the **pureboot version** — the loader's one identity
 number, and the only way to tell what a deployed loader is. Nothing else is
 numbered: the wire protocol has no version, a pureboot version implies it, and
 the host tool holds that map. The tool states the window of loader versions it
 speaks (`OLDEST_LOADER`/`NEWEST_LOADER` in `pureboot.py`), and a version that
 changes the protocol becomes the new floor there. A loader newer than the tool
 is refused by name rather than decoded on the assumption that nothing moved.
 Two generations exist. **1 through 4** speak one session — a 12-byte info block
 from `b`, and a command per memory (`R`/`W` flash, `r`/`w` EEPROM, `F` fuses).
 **5** replaced those with the single `G`/`g` pair over selector-named spaces
 above; the shipped tool speaks both, choosing on the version it reads, so a
 deployed pureboot 4 stays drivable and self-updatable to 5.
 Collapsing four command bodies into one transfer loop is what paid for the
 version: the data space, the host-issued SPM operations and the fuses now share
 the loop, the cursor and the argument decode that `R`/`r`/`w` each carried a
 copy of. The loader shrank while gaining all three.
 The tool carries its own version, free to drift; `--version` prints it and the
 window.
 ## Deployment
-The build leaves three artifacts per chip. The ELF is a container for the
+**ATmega328P**: program the loader at 0x7e00 with an external programmer.
-tests and objcopy, never flashed. The **.hex is the programmer artifact**: it
+Two fuse profiles, same binary:
 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.
 **Boot-sectioned megas**: program the loader at `flash − 512` with an external
 programmer. Every such mega has a BOOTSZ step whose boot section is exactly
 the 512-byte slot — the second-smallest step on the 8 KiB and 16 KiB chips,
 the smallest on the 32 KiB ones — so the ATmega328P profiles below apply to
 every one of them with its own addresses; the per-chip BOOTSZ ladders live in
 the host tool (`BOOT_FUSE`).
 The **644s and 1284s** are the geometry's sweet spot: their smallest boot
 section (512 words = 1 KiB) is exactly *two* 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 one erased
 slot below the loader (0xfc00 / 0x1fc00) and walks up into it.
 ATmega328P profiles (addresses for its 32 KiB):
 | BOOTSZ | BOOTRST | Behavior |
 |---|---|---|
@@ -294,160 +107,88 @@ ATmega328P profiles (addresses for its 32 KiB):
 | 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 here — word 0 stays the application's own
+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'
+**Tinies** (no boot section): program the loader at `flash − 512`; erased
-SPM runs from the entire flash, Atmel-8271 §26): program the loader at
+flash below it walks up into the loader, so a virgin chip activates. When
-`flash − 512`; erased flash below it walks up into the loader, so a virgin
+flashing an application the host performs reset-vector surgery: word 0 is
-chip activates. Flashing an application then takes reset-vector surgery: word
+rewritten to `rjmp` to the loader base, and the application's own entry is
 0 becomes an `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*
+application's. The patched page 0 and the trampoline page are written
-and an erase runs top-down, so from the first write on an interruption still
+*first*, so from the first write on an interrupted flash still resets into
-resets into the loader.
+the loader; an erase runs top-down for the same reason.
 A .bin programmed at address 0 by mistake is dead weight on a boot-sectioned
 mega (SPM only executes from the boot section — reflash the .hex), but *runs*
 on a patched-vector chip, and the ordinary `--update-loader` flow re-homes it
 into the top slot from there (`pureboot.rehome`).
 ## Updating the loader
 `pureboot.py --update-loader new_pureboot.bin` replaces the resident loader
-with any pureboot build — a re-timed window, a newer version — using the
+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
+loader itself as its own staging loader:
 bytes as a raw binary, or the Intel HEX the build emits beside it.
-The preflight refuses an image built for another chip: the stamp every pureboot
+1. The staging slot `[base−512, base)` is saved to a host-side state file
-binary carries must resolve to the device's own geometry, and the error names
+   (on the 1 KB tiny13A that is the whole application, vectors included).
-both. Die revisions share their base signature and geometry, so their images
+2. The resident installs the identical update image there. On the tinies the
-are interchangeable — as the silicon is.
+   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
-1. The staging slot `[base−512, base)` is saved to a host-side state file (on
+   copy times out into a loader, never into garbage.
-   the 1 KB tiny13s that is the whole application, vectors included).
+3. `J` enters the staging copy, which rewrites the resident slot. On the
-2. The resident installs the update image there. On the patched-vector chips
+   t85 the host first re-aims word 0 at the staging copy, so a power loss
-   the host composes the slot's last word as a jump to the resident base, so
+   mid-rewrite still resets into a loader; on the t13a the staging slot
-   even an abandoned staging copy times out into a loader. A loader already
+   carries the reset vector itself.
   sitting whole in the staging slot 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. Where a
   patched reset vector routes through the resident, 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, and the state file is discarded.
+   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, so re-running
+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
+the same command after any interruption resumes and completes. The state
-carries the only bytes not recoverable from the device; losing it mid-update
+file carries the only bytes not recoverable from the device; if it is lost
-still completes the update, and the staging region comes back by reflashing
+mid-update the update still completes, and the staging region is restored by
-the application. A boot-sectioned mega needs its fuses for the preflight — read
+reflashing the application. The mega needs its fuses for the preflight
-from the device, or supplied with `--assume-fuses` where reading is impossible
+(BOOTSZ gate, profile notes) — read from the device, or supplied with
-(simulators).
+`--assume-fuses` where reading is impossible (simulators).
 ## Host tool
-`pureboot.py` — Python 3, standard library only. The port layer is the one
+`pureboot.py` — Python 3, standard library only (termios drives any tty,
-platform-specific part: termios drives any tty on POSIX (a USB adapter as well
+a USB adapter as well as a simavr pty):
 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 (the same), then
+update, flash (erase / program / read / verify), EEPROM (erase / program /
-`--peek`/`--poke` — then the loader hands over to the application. `--stay` keeps the session alive
+read / verify) — then the loader hands over to the application; `--stay`
-instead, and a later invocation reconnects into it. `--flash` and `--eeprom`
+keeps the session alive instead, and a later invocation reconnects into it
-verify by read-back unless `--no-verify`, and a flash page that reads back
+(the knock converges there too). `--flash` and `--eeprom` verify by
-wrong is rewritten up to three times before the run stops (see `W` above).
+read-back unless `--no-verify`; images are raw binary, or Intel HEX by
-`--verify-flash` only reports. Images are raw binary, or Intel HEX by
+extension. `--force` overrides the refusable safety checks (today: flashing
-extension. `--force` overrides the refusable safety checks — today, flashing
+application data into a mega's reset walk region).
 application data into a mega's reset walk region.
 `--autobaud` opens with the calibration pulse instead of the plain knock, for a
 loader built `SERIAL autobaud`; the rest of the session is identical, at
 whatever `--baud` the host chose.
 `--peek ADDR[:N]` and `--poke ADDR:HEX` reach the data space (pureboot 5) —
 SRAM, and through the same address space the register file and every I/O
 register. Reading an I/O register can have side effects (reading UDR clears its
 flags), which is the caller's business to know.
 Readouts come one fact per line: `--info` prints the device's version and
 signature and the geometry that follows from them, `--fuses` each fuse byte
 plus, on a boot-sectioned mega, its decoded meaning. Transfers that take wire time draw a transient progress bar on stderr
 when it is a tty. `-v`/`--verbose` adds the decisions as they happen: knock
 counts, the programming plan, update state handling and per-phase page counts.
 ## Tests
 `tools/check.sh` runs every chip's workflow (`--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 (patched-vector) / 512-byte budget;
+- `pureboot.size` — the 510-byte (tinies) / 512-byte (mega) budget;
- `pureboot_*.size` — the size matrix: the serial backends × the clock ladder
+- `pureboot.pi` — the position-independence lint: no absolute `jmp`/`call`
-  (1/8/16 MHz; the t13s' own RC menu), the USART1 instance across that same
+  in the image, the info block within its first 256 bytes;
-  ladder on the x4 chips, and `pureboot_sw_wide`, the slowest ladder rate at
+- `pureboot.planner` — the host tool's pure logic: programming orders and
-  the fastest clock — where a software UART's per-bit spin outgrows its
+  their recovery properties, the surgery, the staging composition, the
-  one-register delay loop and takes the 16-bit one. That is the largest image
+  boot-fuse decode, and the update preflight's error/warning matrix over
-  the configuration space produces, and a shape the ladder default (always the
+  synthetic fuse bytes;
  *fastest* rate a clock reaches) never picks. Pins are immediate operands and
  the timeout is a constant: neither is an axis;
 - `pureboot_autobaud.size` — the clock-free build, which has no clock or baud
  axis of its own: one binary per chip has to serve every point the matrix
  below sweeps;
 - `pbm_*.size` — with `PUREBOOT_FULL_MATRIX=1`, the exhaustive cross product
  replacing that compact matrix, on **every** chip: every plausible oscillator
  (the internal ones, the CKDIV8 floor, the plain and the UART crystals) ×
  every rate reachable from it × every backend, unreachable combinations
  dropping out rather than aborting the configure. Thousands of points per
  chip, and cheap enough to run rather than reason about;
 - `pureboot.pi` — the position-independence lint: no absolute `jmp`/`call`, no
  flash-resident section but `.text`, and the image byte-identical when linked
  at a different base — which is position independence itself rather than a
  proxy for it;
 - `pureboot.planner` — the host tool's pure logic: programming orders and their
  recovery properties, the surgery, the staging composition, the boot-fuse
  decode, the update preflight over synthetic fuse bytes, and the repairing
  verify against a fake device;
 - `pureboot.protocol` — end to end against a simavr device
-  (`test/pureboot_device.c`: a hardware USART as a pty, or a cycle-timed
+  (`test/pureboot_device.c` — the mega's USART as a pty; on the tinies a
-  GPIO⇄pty bridge for a software-UART build, plus the SPM/NVM module simavr's
+  cycle-timed GPIO⇄pty bridge for the software UART, plus the SPM/NVM module
-  tiny cores lack) driven by the real host tool through knock-from-reset,
+  simavr's tiny cores lack) driven by the real host tool through
-  program + verify of both memories, session reconnect, an external reset
+  knock-from-reset, program + verify of both memories, session reconnect, an
-  through the patched vector, and the hand-over to a fixture application whose
+  external reset through the patched vector, and the hand-over to a fixture
-  banner proves the launch — cross-checked against the simulator's
+  application whose banner proves the launch — cross-checked against the
-  ground-truth memory dumps and an independent decode of the surgery;
+  simulator's ground-truth memory dumps and an independent decode of the
- `pureboot.reloc` — the identical image one slot below the resident serves the
+  surgery's rjmp words;
-  complete command set from there;
+- `pureboot.reloc` — the identical image installed one slot below the
- `pureboot.rehome` (t85) — a loader programmed at address 0 or in the staging
+  resident serves the complete command set from there (the
-  slot re-homes into the top slot through the ordinary update flow;
+  position-independence acceptance test);
- `pureboot.custom` (328P) — the configuration example's 1 MHz software-serial
+- `pureboot.update` — the full `--update-loader` flow to a re-timed build,
-  build driving the full protocol suite, proving the plumbing produces a
+  then every power-fail phase: the device is killed mid-write, restarted
-  working loader and not just one that fits;
+  from its flash dump, and a re-run must complete the update with the
- `pureboot.usart1` (644A) — the same suite over the second hardware USART:
+  application intact throughout.
  instance selection is compile-checked everywhere, but only a live session
  proves the loader polls the USART it claims;
 - `pureboot.dirty` (328P) — entering the loader from a running application over
  an SPM buffer it deliberately dirtied, the case the loader declines to guard:
  a bare verify must see the corruption and the repairing verify must fix it in
  one rewrite. Hardware forbids the state here, but simavr dispatches SPM from
  anywhere, which is what makes the path constructible;
 - `pureboot.update` — the full `--update-loader` flow, 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;
 - `pureboot.autobaud` (328P, 1284P) — the clock-free build over the GPIO⇄pty
  bridge: the calibration handshake, a flash + EEPROM + fuse round trip against
  the simulator's own memory, a data-space round trip, the hand-over — then the
  same binary again at double the clock, which is the property the backend
  exists for. A lone calibration pulse with no knock behind it must still let
  the application boot, so no wait in activation can be unbounded.
 `size`, `pi` and `planner` are host logic and run anywhere; the
 simulator-driven targets need simavr and a pty, so they are POSIX-only.
--- a/pureboot/pureboot.cpp
+++ b/pureboot/pureboot.cpp
@@ -1,14 +1,27 @@
-// pureboot — a serial bootloader on libavr: one C++ source, no inline
+// pureboot — a serial bootloader on libavr, pure by constraint: one C++
-// assembly, no global register variables, 512 bytes on every chip libavr
+// source with no inline assembly and no global register variables, built for
-// targets. The device speaks primitives; every composite (verify, erase,
+// every chip libavr targets, 512 bytes on each. The device speaks primitives
-// reset-vector surgery, self-update) lives in the host tool. Protocol,
+// — read/program flash, read/write EEPROM, fuse bytes, an info block, a jump
-// deployment and configuration: README.md next to this file.
+// — 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 — PC-relative control flow, wire
+// The image is position-independent: control flow is PC-relative, the write
-// addresses in, the write guard and the info block both anchored on the
+// and read paths take wire addresses, the write guard refuses the 512-byte
-// runtime return address — so the identical binary runs from any slot. That
+// slot the code is *running* in (taken from the runtime return address), the
-// is what makes a copy one slot below able to rewrite the resident one, and
+// info block is read relative to that same anchor, and the application jump
-// every change here has to keep it (test/check_pi.py).
+// 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 mega; the
 // patched reset vector — or erased flash walking up into the loader — on the
 // tinies). 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>
@@ -19,156 +32,98 @@ namespace ee = avr::eeprom;
 namespace pureboot {
 namespace {
-// Purely polled: every interrupt guard folds to nothing.
+// Purely polled — interrupts stay off, every guard folds to nothing.
 constexpr auto off = avr::irq::guard_policy::unused;
 constexpr std::uint8_t ack = '+';
-// Deployment parameters come from the build (pureboot_add_loader()). The
+// Per-chip personality, from the chip database: the clocks the dogfood
-// signature is not one of them: the chip database is the only universal
+// boards run (16 MHz crystal on the mega, calibrated RC on the tinies) and
-// source — a tiny13A cannot read its own signature row from code. An autobaud
+// the device signature (compile-time data — the tiny13A cannot even read its
-// build carries no clock and no baud at all; it measures both.
+// signature row from code).
-#if !defined(PUREBOOT_AUTOBAUD) && (!defined(PUREBOOT_CLOCK_HZ) || !defined(PUREBOOT_BAUD))
+consteval avr::hertz_t clock()
 #error \
    "PUREBOOT_CLOCK_HZ and PUREBOOT_BAUD select this build's clock and baud — create loader targets with pureboot_add_loader(), or PUREBOOT_AUTOBAUD for a clock-free one (README.md)"
 #endif
 #if !defined(PUREBOOT_AUTOBAUD)
 using dev = avr::device<{.clock = avr::hertz_t{PUREBOOT_CLOCK_HZ}}>;
 constexpr avr::baud_t wire_baud{PUREBOOT_BAUD};
 #endif
 // 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};
+	if (avr::hw::db.name == "ATtiny13A")
-	return avr::hw::db.field_index(reg, "WDRF");
+		return 9.6_MHz;
 	if (avr::hw::db.name == "ATtiny85")
 		return 8_MHz;
 	return 16_MHz;
 }
-// The loader owns the top 512 bytes; a staging copy goes in the slot below.
+consteval std::array<std::uint8_t, 3> signature()
-// Chips without a hardware boot section — the tinies and the m48s, whose SPM
+{
-// runs from anywhere (Atmel-8271 §26) — keep the application's relocated
+	if (avr::hw::db.name == "ATtiny13A")
-// reset vector in the word under the slot.
+		return {0x1e, 0x90, 0x07};
-constexpr std::uint16_t slot_bytes = 512;
+	if (avr::hw::db.name == "ATtiny85")
 		return {0x1e, 0x93, 0x0b};
 	return {0x1e, 0x95, 0x0f};
 }
 using dev = avr::device<{.clock = clock()}>;
 // Geometry: the resident loader owns the top 512 bytes of flash; the word
 // below it is the trampoline (the application's relocated reset vector) on
 // chips without a hardware boot section. The RWWSRE bit marks a separate
 // boot section — on classic AVR the two capabilities coincide.
 constexpr std::uint16_t boot_bytes = 512;
 constexpr std::uint16_t base = static_cast<std::uint16_t>(spm::flash_bytes - boot_bytes);
 constexpr std::uint16_t page = spm::page_bytes;
-constexpr bool boot_section = avr::hw::curated::has_boot_section();
+constexpr bool boot_section = avr::hw::db.field_index("SPMCSR", "RWWSRE") >= 0;
-// Past 64 KiB one bank of flash does not cover the chip, so a transfer's
+// The activation window, in seconds, is a compile-time constant (the build
-// selector byte carries the bank and the wire address stays a byte address
+// may override it): the whole EEPROM belongs to the application, and
-// within it. 'J' is the exception: it is a word address everywhere, because
+// re-timing the loader is a bootloader self-update with a re-timed binary.
 // that is what the hardware's own jump takes.
 constexpr bool banked_flash = spm::flash_bytes > 65536;
 // A compile-time window, so the whole EEPROM belongs to the application;
 // re-timing a deployed loader is a self-update with a re-timed build. An
 // autobaud build has no clock to convert seconds against and counts polls.
 #if !defined(PUREBOOT_TIMEOUT)
 #define PUREBOOT_TIMEOUT 8
 #endif
 constexpr std::uint8_t timeout_seconds = PUREBOOT_TIMEOUT;
-#if !defined(PUREBOOT_AUTOBAUD_POLLS)
+// The 12-byte info block the host reads with the 'b' command; flash-resident
-#define PUREBOOT_AUTOBAUD_POLLS 4000000
+// (there is no crt to copy a .data image).
-#endif
+inline constexpr std::array<std::uint8_t, 12> info_data = {
-constexpr avr::uint24_t autobaud_budget = PUREBOOT_AUTOBAUD_POLLS;
+    'P',
-
+    'B',
-// The loader's one identity number. The protocol carries none of its own —
+    1, // magic, protocol version
-// a version implies it, and the host tool holds that map (README.md).
+    signature()[0],
-constexpr std::uint8_t version = 5;
+    signature()[1],
-
+    signature()[2],
-// The image's identity stamp, for the host tool rather than for the wire: an
+    static_cast<std::uint8_t>(page),
-// update image is a bare 512-byte slot, and without this nothing in it says
+    base & 0xff,
-// which chip it was built for. The tool refuses to install an image whose
+    base >> 8, // app flash ends here; resident loader base
-// stamp does not match the device — flashing a foreign loader bricks the
+    avr::hw::db.mem.eeprom_size & 0xff,
-// target, and the loader itself cannot check what has already replaced it.
+    avr::hw::db.mem.eeprom_size >> 8,
-//
+    boot_section ? 0 : 1, // bit 0: host must patch the reset vector (no hardware boot section)
 // Never read from flash by the loader — 'b' answers out of this array, but at
 // constant indices, so those fold to immediates and no runtime address of it
 // is ever formed. `used` keeps the compiler from dropping the copy the host
 // needs and `retain` keeps --gc-sections from collecting it.
 // clang-format off
 [[gnu::used, gnu::retain, gnu::section(".text.stamp")]]
 inline constexpr std::uint8_t identity_stamp[]{
    'P', 'B',                      // the magic the host scans an image for
    version,                       // and from here on, exactly what 'b' answers
    avr::hw::db.signature[0],
    avr::hw::db.signature[1],
    avr::hw::db.signature[2],
 };
-// clang-format on
+using info = avr::flash_table<info_data>;
 // Where the identity proper starts: past the magic the host scans for.
 constexpr std::uint8_t stamp_identity = 2;
-// The address spaces a transfer can name, in a selector byte's low nibble.
+// The serial link: the hardware USART where the chip has one, the polled
-// Flash is 0 so it is the cheapest to select.
+// software UART (no vector — the table belongs to the application) on PB0/PB1
-//
+// elsewhere. Both are class templates on the clock so only the selected
-// spm_ops is the one that is not memory: a write there hands its byte to
+// backend is ever instantiated. pending() is the cheap line test the
-// SPMCSR and fires the instruction at the transfer's address, which is how
+// activation window polls; rx() then picks the byte up; drain() holds until
-// page erase, page write and RWW re-enable reach the wire without the loader
+// the last transmitted frame is fully on the wire (the jump hand-over must
-// carrying a command for each. The hardware's four-cycle store-to-SPM window
+// not let the target's re-init clip the ack).
-// is why this is one fused primitive and not a poke of SPMCSR — no host can
+template <avr::hertz_t C>
-// hit that window across a serial link.
+consteval std::int16_t rxc_field()
 enum : std::uint8_t { sp_flash = 0, sp_eeprom = 1, sp_data = 2, sp_fuse = 3, sp_spm = 4 };
 // A selector's high nibble is the flash bank — the address bits above the
 // 16-bit wire address, RAMPZ on the chips that have one. Keeping it here
 // rather than widening the wire address is what lets one 16-bit cursor serve
 // every space: a 24-bit cursor would pay its extra byte on EEPROM and data
 // reads that can never need it.
 [[gnu::always_inline]] inline std::uint8_t space_of(std::uint8_t selector)
 {
-	return selector & 0x0f;
+	return avr::hw::db.field_index("UCSR0A", "RXC0");
 }
-[[gnu::always_inline]] inline std::uint8_t bank_of(std::uint8_t selector)
+template <avr::hertz_t C>
 consteval std::int16_t txc_field()
 {
-	return static_cast<std::uint8_t>(selector >> 4);
+	return avr::hw::db.field_index("UCSR0A", "TXC0");
 }
-// The slot a flash address falls in, as one byte. A slot is half as many words
+template <avr::hertz_t C>
-// as bytes, so the word address's high byte is exactly this index — which is
+consteval std::int16_t status_reg()
 // what lets the write guard compare a single byte, and what the running copy's
 // own return address yields for free.
 constexpr std::uint8_t slot_shift = std::countr_zero(slot_bytes);
 constexpr std::uint8_t bank_shift = 16 - slot_shift;
 [[gnu::always_inline]] inline std::uint8_t slot_of([[maybe_unused]] std::uint8_t bank, std::uint16_t at)
 {
-	const auto within = static_cast<std::uint8_t>(at >> slot_shift);
+	return avr::hw::db.reg_index("UCSR0A");
 	if constexpr (banked_flash)
 		return static_cast<std::uint8_t>((bank << bank_shift) | within);
 	else
 		return within;
 }
-// The serial link, per the build's PUREBOOT_USART / PUREBOOT_SOFT_SERIAL /
+template <avr::hertz_t C>
 // PUREBOOT_AUTOBAUD, defaulting to the chip's USART0 where it has one. The
 // software receiver is the polled one: the vector table belongs to the
 // application. Templates on the clock, so only the selected backend
 // instantiates. pending() is the cheap line test the activation window polls;
 // drain() holds until the last frame is off the wire, so a hand-over cannot
 // 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_AUTOBAUD) && defined(PUREBOOT_USART)
 #error "PUREBOOT_AUTOBAUD measures a software link; it cannot drive a hardware USART"
 #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
 template <avr::hertz_t C, avr::baud_t B>
 struct hardware_link {
-	using uart = avr::uart::usart<usart_digit, C, {.baud = B, .max_baud_error = 2.5_pct}>;
+	using uart = avr::uart::usart0<C, {.baud = 115200_Bd, .max_baud_error = 2.5_pct}>;
 	// The compiled idle poll: lds UCSR0A (2), sbrc skipping the exit (2),
 	// sbiw + sbci + sbci + brne (6).
@@ -181,7 +136,7 @@ struct hardware_link {
 	static bool pending()
 	{
-		return uart::rx_ready();
+		return avr::hw::field_impl<rxc_field<C>()>::test();
 	}
 	static std::uint8_t rx()
@@ -196,14 +151,22 @@ struct hardware_link {
 	static void drain()
 	{
-		uart::drain();
+		// write() leaves the byte draining behind it. Clear a stale TXC0
 		// first (W1C by writing the sampled status back — the store a hand
 		// assembler writes, keeping U2X0), then wait for the fresh
 		// completion; with a byte still ahead in the shifter TXC0 cannot
 		// re-set until the last pending byte has fully left.
 		using status = avr::hw::reg_impl<status_reg<C>()>;
 		status::write(status::read());
 		while (!avr::hw::field_impl<txc_field<C>()>::test()) {
 		}
 	}
 };
-template <avr::hertz_t C, avr::baud_t B>
+template <avr::hertz_t C>
 struct software_link {
-	using rx_t = avr::uart::software_rx_polled<C, avr::PUREBOOT_RX, B>;
+	using rx_t = avr::uart::software_rx_polled<C, avr::pb0, 57600_Bd>;
-	using tx_t = avr::uart::software_tx<C, avr::PUREBOOT_TX, B>;
+	using tx_t = avr::uart::software_tx<C, avr::pb1, 57600_Bd>;
 	// The compiled idle poll: sbis skipping the exit (2), sbiw + sbci +
 	// sbci + brne (6).
@@ -216,7 +179,7 @@ struct software_link {
 	static bool pending()
 	{
-		return rx_t::start_pending();
+		return !avr::io::input<avr::pb0>::read(); // a start bit has begun
 	}
 	static std::uint8_t rx()
@@ -235,50 +198,14 @@ struct software_link {
 	}
 };
-// The clock-free link: the bit period is measured from the host's calibration
+using link = std::conditional_t<avr::hw::db.has_reg("UDR0"), hardware_link<dev::clock>, software_link<dev::clock>>;
 // pulse instead of derived from a clock, so one image serves every F_CPU and
 // every rate. Activation differs in kind from the other two — there is no
 // clock to time a window against — so this backend brings its own, below.
 struct autobaud_link {
 	using uart = avr::uart::software_autobaud<avr::PUREBOOT_RX, avr::PUREBOOT_TX>;
-	static void init()
+// 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
-		avr::init<uart>();
+// 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]]
-	static std::uint8_t rx()
+// keeps the constant from folding back into a PC-relative call.
 	{
 		return uart::template read<off>();
 	}
 	static void tx(std::uint8_t byte)
 	{
 		uart::template write<off>(byte);
 	}
 	static void drain()
 	{
 		uart::drain();
 	}
 };
 #if defined(PUREBOOT_AUTOBAUD)
 using link = autobaud_link;
 #elif defined(PUREBOOT_USART)
 static_assert(avr::uart::has_usart<usart_digit>(), "PUREBOOT_USART selects a hardware USART this chip does not have");
 using link = hardware_link<dev::clock, wire_baud>;
 #elif defined(PUREBOOT_SOFT_SERIAL)
 using link = software_link<dev::clock, wire_baud>;
 #else
 using link = std::conditional_t<avr::uart::has_usart<usart_digit>(), hardware_link<dev::clock, wire_baud>,
                                software_link<dev::clock, wire_baud>>;
 #endif
 // The application's entry, pinned by the linker (--defsym): word 0 on a
 // boot-sectioned mega, the trampoline at base − 2 elsewhere. Reaching it must
 // not depend on where this copy runs, so the jump goes through a pointer, and
 // [[gnu::noipa]] keeps the constant from folding back into a relative call.
 extern "C" [[noreturn]] void pureboot_app();
 [[gnu::noipa, noreturn]] void jump(void (*target)())
@@ -292,29 +219,10 @@ extern "C" [[noreturn]] void pureboot_app();
 	jump(pureboot_app);
 }
-// Activation: a bounded wait for the host, then the knock. Both forms boot the
+// One activation window is a single 32-bit poll countdown. The divisor is
-// application when the window closes on an idle line, and both bound *every*
+// the backend's counted poll-loop cycles (its own comment reads them off the
-// wait — a knock awaited without a deadline would let one stray edge hold an
+// compiled loop); whole-second precision is all the window promises, so the
-// unattended device in the loader forever.
+// nearest cycle count is plenty.
 #if defined(PUREBOOT_AUTOBAUD)
 // The window is a fixed poll budget: with no clock, whole seconds cannot be
 // timed. A uint24_t holds it — a fourth byte would cost two words at every
 // countdown step for range never used.
 void await_host()
 {
 	for (;;) {
 		if (!link::uart::calibrate(autobaud_budget))
 			run_app();
 		// The calibration pulse has already proven a host is there, so one
 		// byte activates. A knock that never arrives falls back to calibrate(),
 		// whose own budget then boots the application.
 		if (link::uart::template read<off>(autobaud_budget) == 'p')
 			return;
 	}
 }
 #else
 // The window as one 32-bit countdown, divided by the backend's counted
 // poll-loop cycles. Whole seconds is all it promises.
 consteval std::uint32_t window_polls()
 {
 	return timeout_seconds * static_cast<std::uint32_t>(dev::clock.hz / link::poll_cycles);
@@ -330,8 +238,8 @@ bool pending_before_deadline()
 	return false;
 }
-// A knock byte under the deadline: an idle window means no host, so the
+// A knock byte under the activation deadline: an idle line means no host is
-// application runs.
+// there, and the application runs.
 std::uint8_t rx_deadline()
 {
 	if (!pending_before_deadline())
@@ -339,187 +247,163 @@ std::uint8_t rx_deadline()
 	return link::rx();
 }
-void await_host()
+std::uint16_t rx16()
 {
 	// 'p' then 'b', each under a fresh window; anything else is line noise.
 	while (rx_deadline() != 'p' || rx_deadline() != 'b') {
 	}
 }
 #endif
 // Inlined: read across a call, the first byte strands in a call-saved
 // register the caller has to push and pop.
 [[gnu::always_inline]] inline std::uint16_t rx16()
 {
 	std::uint16_t low = link::rx();
 	return static_cast<std::uint16_t>(low | (link::rx() << 8));
 }
-// The wire's byte pair as the word it is — AVR is little-endian too, so the
+const std::uint8_t *flash_ptr(std::uint16_t address)
 // cast is the identity a shift-and-or spelling makes the compiler rediscover.
 // Callers read into named variables first: the wire order is a sequence of
 // reads, not an argument order.
 [[gnu::always_inline]] inline std::uint16_t word_of(std::array<std::uint8_t, 2> pair)
 {
-	return std::bit_cast<std::uint16_t>(pair);
+	return reinterpret_cast<const std::uint8_t *>(address);
 }
-// Out of line: several sites send it, and a call is shorter than a
+// The streamers take the count in the wire's 8-bit form: 0 means 256.
-// load-immediate at each.
+// send_flash stays out of line: its two callers ('b' and 'R') otherwise each
-[[gnu::noinline]] void tx_ack()
+// inline a private copy of the loop.
 [[gnu::noinline]] void send_flash(std::uint16_t address, std::uint8_t count)
 {
 	do
 		link::tx(avr::flash_load(flash_ptr(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);
 }
-// A wire address and its selector's bank as the flash address they name.
+// One flash page: stream the bytes into the SPM buffer as little-endian
-[[gnu::always_inline]] inline spm::flash_address_t flash_address([[maybe_unused]] std::uint8_t bank, std::uint16_t at)
+// 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 address, std::uint8_t slot_high)
 {
-	if constexpr (banked_flash)
+	// A buffer word cannot be loaded twice without an erase (§26.2.1), so a
-		return (static_cast<spm::flash_address_t>(bank) << 16) | at;
+	// refused page's drained data must not linger for the next write:
-	else
+	// discard the buffer up front — CTPB on the tinies; on the mega writing
-		return at;
+	// RWWSRE aborts a pending load (§26.2.2).
 }
 // One byte out of any space. Every accessor shares the transfer's cursor, its
 // loop and its call site, so a space costs only its own instruction rather
 // than a body, a loop and a dispatch arm of its own.
 [[gnu::always_inline]] inline std::uint8_t load(std::uint8_t space, [[maybe_unused]] std::uint8_t bank,
                                                std::uint16_t at)
 {
 	if (space == sp_eeprom)
 		return ee::read(at);
 	if (space == sp_data)
 		return *reinterpret_cast<volatile std::uint8_t *>(at);
 	if (space == sp_fuse)
 		return spm::read_fuse<off>(static_cast<spm::fuse>(at));
 	if constexpr (banked_flash)
 		return avr::flash_load_far<std::uint8_t>(flash_address(bank, at));
 	else
 		return avr::flash_load(reinterpret_cast<const std::uint8_t *>(at));
 }
 // One byte into a writable space. Flash is not one of them — it arrives a
 // page at a time through 'W' and is committed through sp_spm — and the fuses
 // are not writable at all: SPM reaches flash and boot lock bits only.
 [[gnu::always_inline]] inline void store(std::uint8_t space, std::uint8_t bank, std::uint16_t at, std::uint8_t value,
                                         std::uint8_t slot_high)
 {
 	if (space == sp_data) {
 		*reinterpret_cast<volatile std::uint8_t *>(at) = value;
 		return;
 	}
 	if (space == sp_spm) {
 		// The running-slot write guard. An SPM command aimed at the slot this
 		// code executes from is dropped, so a broken host cannot brick the
 		// running loader — while a copy one slot lower may still rewrite the
 		// resident one, which is what a self-update is. Guarding the commit
 		// rather than the page fill covers erase and write both, and leaves a
 		// refused page's words in the buffer: harmless, since the next page
 		// write auto-erases it (§26.2.1).
 		if (slot_of(bank, at) != slot_high)
 			spm::command<off>(value, flash_address(bank, at));
 		// Only a boot-sectioned mega runs on while its RWW section programs;
 		// everywhere else the CPU halts through erase and write, so the wait
 		// is already over by the time it returns.
 	if constexpr (boot_section)
-			spm::wait();
+		spm::rww_enable<off>();
-		return;
+	else
-	}
+		spm::clear_buffer<off>();
-	// Host-paced: the ack goes out once the write has begun, so the next byte
+	// The address is the loop's only state: pages are aligned, so the walk
-	// arrives while it completes and nothing is missed without a buffer.
+	// ends when the offset bits wrap back to zero.
 	ee::write<off>(at, value);
 }
 // One page into the SPM buffer, and only that: the erase and the write that
 // commit it are host-issued sp_spm stores, which reach the same fused
 // store-and-SPM pair through the transfer path's own address and data.
 //
 // Nothing discards the buffer first: it is write-once per word (§26.2.1), so
 // filling over a refused page or an application's leavings programs stale
 // words — but a page write auto-erases it (§26.2.1; §19.2 on the tinies), so
 // that write clears the condition and the host's read-back rewrites the page.
 void fill_page(std::uint8_t bank, std::uint16_t at)
 {
 	// The address names a page, so its in-page bits are dropped and the walk
 	// starts at the page base; the low byte of the cursor is the whole in-page
 	// offset, since a page is aligned and never crosses a bank.
 	std::uint16_t z = at & ~static_cast<std::uint16_t>(page - 1);
 	do {
 		std::uint8_t low = link::rx();
 		std::uint8_t high = link::rx();
-		spm::fill<off>(flash_address(bank, z), word_of({low, high}));
+		spm::fill<off>(address, static_cast<std::uint16_t>(low | (high << 8)));
-		z += 2;
+		address += 2;
-	} while (static_cast<std::uint8_t>(z) & (page - 1));
+	} while (static_cast<std::uint8_t>(address) & (page - 1));
 	address -= 2; // back inside the page — erase and write ignore the word bits
 	const std::uint8_t page_high = static_cast<std::uint8_t>(address >> 8) & 0xfe;
 	if (page_high != slot_high) {
 		// The tinies halt the CPU through the erase and the write, so only
 		// the mega — running on while its RWW section programs — waits.
 		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
+	// A watchdog reset belongs to the application (whose watchdog stays
-	// on until it clears WDRF — no activation window in its way.
+	// forced on until it clears WDRF) — no activation window in its way.
-	if (avr::hw::field_impl<wdrf_field()>::test())
+	if (avr::hw::mcusr::wdrf.test())
 		run_app();
 	link::init();
-	// The slot this copy runs in, which the write guard follows: the return
+	// The high byte of the 512-byte-aligned base this copy runs at: the word
-	// address is a word address and a slot is half as many words as bytes, so
+	// return address's high byte is the byte address >> 9 (the slot index),
-	// its high byte is the slot index outright. No absolute address is ever
+	// doubled back into address terms. program_flash refuses this one slot
-	// formed, so the image stays position-independent.
+	// and the info block is addressed from it, so both follow wherever the
-	const auto return_words = reinterpret_cast<std::uint16_t>(__builtin_return_address(0));
+	// code was flashed.
-	const auto slot_high = static_cast<std::uint8_t>(return_words >> 8);
+	const std::uint8_t slot_high =
 	    static_cast<std::uint8_t>((reinterpret_cast<std::uint16_t>(__builtin_return_address(0)) >> 8) << 1);
-	await_host();
+	// 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: it blocks SPM and fuse reads
+		// No prompt while an EEPROM write runs: a pending write blocks SPM
-		// (§26.2.1), and the prompt is the previous command's completion ack.
+		// and fuse reads (§26.2.1), and the ack tells the host all is done.
 		ee::wait();
-		tx_ack();
+		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 is its offset in any slot, and the high byte of
 			// its runtime address is the running slot's. Built as a byte
 			// pair so no absolute 16-bit address is ever materialized.
 			const std::uint8_t low = static_cast<std::uint8_t>(reinterpret_cast<std::uint16_t>(info::storage.data()));
 			send_flash(std::bit_cast<std::uint16_t>(std::array{low, slot_high}), info::size());
 			break;
 		}
 		case 'J': { // jump to a wire word address: hand-over and staging transfer
 			auto target = reinterpret_cast<void (*)()>(rx16());
-			tx_ack();
+			link::tx(ack);
 			link::drain();
 			jump(target);
 		}
-		case 'b': // identity: the version, then the three signature bytes
+		case 'R':   // read flash: addr16, n8 (0 = 256)
-			// Straight out of the stamp, so the wire and the image can never
+		case 'r':   // read EEPROM: addr16, n8
-			// disagree about what this loader is. The indices are constant and
+		case 'w': { // write EEPROM: addr16, n8, then n bytes each acked
-			// the array is constexpr, so these are immediates, not flash reads:
+			std::uint16_t address = rx16();
 			// nothing here needs the stamp's runtime address.
 			for (std::uint8_t at = stamp_identity; at != sizeof identity_stamp; ++at)
 				link::tx(identity_stamp[at]);
 			break;
 		case 'W':   // fill one flash page buffer: sel8, addr16, then page bytes
 		case 'G':   // read:  sel8, addr16, n8 (0 = 256)
 		case 'g': { // write: sel8, addr16, n8, then n bytes, each acked
 			// One decode, one cursor and one loop for every space and both
 			// directions: a command per memory would carry a copy of all three
 			// each. 'W' joins the same decode rather than keeping an address
 			// form of its own, so flash addressing is uniform across every
 			// command that names it.
 			const std::uint8_t selector = link::rx();
 			const std::uint8_t space = space_of(selector);
 			const std::uint8_t bank = bank_of(selector);
 			std::uint16_t at = rx16();
 			if (command == 'W') {
 				fill_page(bank, at);
 				break;
 			}
 			std::uint8_t count = link::rx();
-			do {
+			if (command == 'R')
-				// Read and write are one letter apart in case, so the direction
+				send_flash(address, count);
-				// is a single bit and the loop picks it with a one-word skip.
+			else if (command == 'r')
-				if (command & 0x20) {
+				send_eeprom(address, count);
-					store(space, bank, at, link::rx(), slot_high);
+			else
-					tx_ack();
+				store_eeprom(address, count);
 				} else
 					link::tx(load(space, bank, at));
 				++at;
 			} while (--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;
 		}
--- a/pureboot/pureboot.py
+++ b/pureboot/pureboot.py
--- a/test/check_pi.py
+++ b/test/check_pi.py
@@ -1,75 +1,52 @@
 #!/usr/bin/env python3
-"""Position-independence lint: the property that lets the identical image run
+"""Position-independence lint for the pureboot image.
 from any slot, asserted from the built ELF and its object.
-  1. No absolute jmp/call — -mrelax normally guarantees it, but a branch that
+The self-staging design lets the identical binary run from any 512-byte
-     grows out of relaxation range would break it silently.
+slot, which holds only if nothing in the image addresses itself absolutely.
-  2. Nothing flash-resident to address: the image is .text alone, so there is
+Two link-time facts guarantee it, both asserted here from the built ELF:
     no table whose runtime address has to be reconstructed.
  3. The image is byte-identical when linked at a different base. This is
     position independence itself rather than a proxy for it — an absolute
     address anywhere in the image would move with the link and show up as a
     differing byte.
-Usage: check_pi.py <objdump> <objcopy> <cxx> <mcu> <elf> <object> <text_start_hex>
+  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 os
 import re
 import subprocess
 import sys
 import tempfile
 def fail(message):
    print(f"FAIL: {message}")
    sys.exit(1)
 def main():
-    objdump, objcopy, cxx, mcu, elf, obj, text_start = sys.argv[1:]
+    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)]
+    absolute = [
        line
        for line in listing.splitlines()
        if re.search(r"\t(jmp|call)\t", line)
    ]
    if absolute:
-        fail("absolute control flow in the image:\n" + "\n".join(absolute))
+        print("FAIL: absolute control flow in the image:")
        print("\n".join(absolute))
        sys.exit(1)
-    # Allocated flash beyond .text would be data the running copy has to find.
+    symbols = subprocess.run([nm, "-C", elf], capture_output=True, text=True, check=True).stdout
-    # Only ALLOC sections reach the device at all; .comment and the debug
+    info = [line for line in symbols.splitlines() if "flash_table" in line and "::storage" in line]
-    # sections ride along in the ELF container and are never flashed. objdump
+    if len(info) != 1:
-    # prints each section's flags on the line following its header.
+        print(f"FAIL: expected one info-block storage symbol, found {len(info)}")
-    headers = subprocess.run([objdump, "-h", elf], capture_output=True, text=True, check=True).stdout.splitlines()
+        sys.exit(1)
-    for index, line in enumerate(headers):
+    offset = int(info[0].split()[0], 16) - text_start
-        fields = line.split()
+    if not 0 <= offset < 256:
-        if len(fields) < 6 or not fields[0].isdigit():
+        print(f"FAIL: info block at image offset {offset:#x}, must sit in the first 256 bytes")
-            continue
+        sys.exit(1)
        name, size = fields[1], int(fields[2], 16)
        flags = headers[index + 1] if index + 1 < len(headers) else ""
        if "ALLOC" not in flags or not size:
            continue
        if name not in (".text", ".noinit", ".bss"):
            fail(f"flash-resident section {name} ({size} bytes): the image must be .text alone")
-    # Relink at a different base and compare the bytes.
+    print(f"PI lint: control flow PC-relative, info block at offset {offset:#x}")
    with tempfile.TemporaryDirectory() as work:
        elsewhere = text_start - 0x200 if text_start >= 0x200 else text_start + 0x200
        images = []
        for base, tag in ((text_start, "here"), (elsewhere, "there")):
            relinked = os.path.join(work, f"{tag}.elf")
            binary = os.path.join(work, f"{tag}.bin")
            subprocess.run(
                [cxx, f"-mmcu={mcu}", "-nostartfiles", f"-Wl,--section-start=.text={base:#x}",
                 "-Wl,--defsym=pureboot_app=0", "-mrelax", obj, "-o", relinked],
                check=True, capture_output=True)
            subprocess.run([objcopy, "-O", "binary", relinked, binary], check=True)
            images.append(open(binary, "rb").read())
        if images[0] != images[1]:
            differing = [i for i, (a, b) in enumerate(zip(*images)) if a != b]
            fail(f"the image changes when linked at {elsewhere:#x} instead of {text_start:#x}: "
                 f"{len(differing)} byte(s) differ, first at offset {differing[0]:#x}")
    print(f"PI lint: control flow PC-relative, .text only, identical linked at {text_start:#x} and {elsewhere:#x}")
 if __name__ == "__main__":
--- a/test/pbapp.cpp
+++ b/test/pbapp.cpp
@@ -4,16 +4,11 @@
 // 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
+// On the mega it then listens, and an 'L' makes it jump into the resident
-// the resident loader — the application-owned loader entry a
+// loader — the application-owned loader entry a BOOTRST-unprogrammed mega
-// BOOTRST-unprogrammed mega relies on (reset always boots the application
+// relies on (reset always boots the application there), exercised by the
-// there), exercised by the self-update tests. The software link idles:
+// self-update tests. The tinies idle: reset reaches their loader through
-// reset reaches those loaders through the patched vector (or the runner
+// the patched vector, so the application owes it nothing.
 // 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;
@@ -22,77 +17,33 @@ namespace {
 consteval avr::hertz_t clock()
 {
-#if defined(PUREBOOT_CLOCK_HZ)
+	if (avr::hw::db.name == "ATtiny13A")
 	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"))
+	if (avr::hw::db.name == "ATtiny85")
 		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()>
+template <avr::hertz_t C, bool Hardware = avr::hw::db.has_reg("UDR0")>
 struct link {
-#if defined(PUREBOOT_BAUD)
+	using tx_t = avr::uart::usart0<C, {.baud = 115200_Bd, .max_baud_error = 2.5_pct}>;
 	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 in the top slot — 512 bytes on every
+		for (;;)
-		// chip. The jump takes a word address, which is what makes the
+			if (tx_t::read_blocking() == 'L')
-		// >64 KiB chips' entry reachable through a 16-bit pointer at all.
+				reinterpret_cast<void (*)()>((avr::hw::db.mem.flash_size - 512) / 2)();
 		constexpr std::uint32_t slot = 512;
 		for (;;) {
 			auto command = tx_t::read_blocking();
 			if (command == 'L')
 				reinterpret_cast<void (*)()>(static_cast<std::uint16_t>((avr::hw::db.mem.flash_size - slot) / 2))();
 			// 'D' leaves every word of the SPM page buffer dirty, so that a
 			// following 'L' enters the loader with the buffer it never clears.
 			if (command == 'D') {
 				for (std::uint16_t at = 0; at < avr::spm::page_bytes; at += 2)
 					avr::spm::fill(at, 0xdead);
 				tx('D');
 			}
 		}
 	}
 };
 template <avr::hertz_t C>
 struct link<C, false> {
-#if defined(PUREBOOT_BAUD)
+	using tx_t = avr::uart::software_tx<C, avr::pb1, 57600_Bd>;
 	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));
--- a/test/pbautobaud.py
+++ b/test/pbautobaud.py
@@ -1,154 +0,0 @@
 #!/usr/bin/env python3
 """End-to-end autobaud test: drive an autobaud loader in simavr through the
 calibration handshake and a flash + EEPROM + fuse round-trip, cross-checked
 against the simulator's ground-truth memory — then repeat at a second F_CPU with
 the *same* loader binary, which is the property autobaud exists for: one
 clock-agnostic image that locks onto whatever rate the host sends.
 Usage: pbautobaud.py <device_bin> <loader_elf> <mcu> <base_hex> <page>
                     <app_bin> <app_hz> <app_baud> <tool_py> <workdir>
 The loader is a software-serial build on PB0/PB1 (pureboot_add_autobaud's
 default), so the runner drives it over the GPIO⇄pty bridge (-l sw:B0,B1). The
 app fixture is built for (app_hz, app_baud); the hand-over is checked at that
 point, and a second point at half the clock proves the lock is measured, not
 baked in.
 """
 import os
 import sys
 import time
 def fail(message):
    print(f"FAIL: {message}")
    sys.exit(1)
 def main():
    (device_bin, elf, mcu, base_hex, page, app_bin, app_hz, app_baud, tool, workdir) = sys.argv[1:]
    base, page, app_hz, app_baud = int(base_hex, 0), int(page), int(app_hz), int(app_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)
    ee_image = bytes(range(0xA0, 0xB0))
    ee_path = os.path.join(workdir, "ee.bin")
    open(ee_path, "wb").write(ee_image)
    # The geometry the surgery planner needs, from the chip class the runner is
    # told — the same derivation pbtest.py makes: the boot-sectioned megas need
    # no vector surgery, the tinies and the boot-section-less m48s do, and the
    # large chips speak word addresses.
    mega = mcu.startswith("atmega")
    patch = not mega or mcu.startswith("atmega48")
    word_flash = base + pb.SLOT > 0x10000
    wire_base = base // 2 if word_flash else base
    flags = (1 if patch else 0) | (2 if word_flash else 0)
    ground_truth = pb.Info(bytes([ord("P"), ord("B"), pb.NEWEST_LOADER, 0, 0, 0, page & 0xFF,
                                  wire_base & 0xFF, wire_base >> 8, 0, 0, flags]))
    def round_trip(hz, baud, label, hand_over):
        """One clock point: reset, calibrate + knock, program, verify against the
        simulator's own flash, and (at the app's point) hand over to the fixture."""
        dump = os.path.join(workdir, f"flash_{label}.bin")
        device = pbsim.Device(device_bin, elf, mcu, str(hz), base_hex, page, baud, dump, link="sw:B0,B1")
        try:
            # The host tool, in autobaud mode, sends the 0xC0 calibration pulse
            # and a single knock at `baud`; the loader locks to it.
            out = pbsim.run_tool(tool, device.pty, baud, "--autobaud", "--info", "--fuses",
                                 "--flash", app_bin, "--eeprom", ee_path, "--stay")
            for needed in ("version", "signature", "fuses", "verify:", "stays"):
                if needed not in out:
                    fail(f"{label}: session output lacks {needed!r}\n{out}")
            # Read both memories back over the locked link and check them.
            read_flash = os.path.join(workdir, f"rf_{label}.bin")
            read_eeprom = os.path.join(workdir, f"re_{label}.bin")
            out = pbsim.run_tool(tool, device.pty, baud, "--autobaud", "--verify-flash", app_bin,
                                 "--verify-eeprom", ee_path, "--read-flash", read_flash,
                                 "--read-eeprom", read_eeprom, "--stay")
            if out.count("verify:") != 2:
                fail(f"{label}: did not verify both memories\n{out}")
            if open(read_eeprom, "rb").read()[: len(ee_image)] != ee_image:
                fail(f"{label}: EEPROM read-back mismatch")
            if hand_over:
                # Regression: a calibration pulse with no knock behind it must
                # not wedge the loader. The knock's edge wait used to be
                # unbudgeted, so one stray low pulse — EMI, or a host that opens
                # the port and never knocks — held the loader forever and the
                # application never ran. The whole activation is bounded now, so
                # the window closes and the app boots; the banner is the proof.
                # (The pause lets the loader reach its measurement loop, so the
                # pulse is genuinely seen and the test cannot pass vacuously.)
                device.reset()
                port = pb.Port(device.pty, baud)
                try:
                    time.sleep(0.2)
                    port.write(bytes((pb.CALIBRATE,)))
                    # Accumulate rather than match exactly: the reset leaves the
                    # idle line a framing artefact ahead of the banner, which is
                    # noise here — the question is only whether the app ran.
                    seen = b""
                    deadline = time.monotonic() + 180.0
                    while b"APP" not in seen and time.monotonic() < deadline:
                        seen += port.read_available(1.0)
                    if b"APP" not in seen:
                        fail(f"{label}: lone calibration pulse wedged the loader — app never bannered, saw {seen!r}")
                    print(f"  {label}: lone calibration pulse does not wedge the loader")
                finally:
                    port.close()
                device.reset()
                port = pb.Port(device.pty, baud)
                try:
                    loader = pb.Loader(port)
                    live = loader.connect_autobaud(15)
                    if not pb.OLDEST_LOADER <= live.version <= pb.NEWEST_LOADER:
                        fail(f"{label}: loader reports pureboot {live.version}")
                    if loader.unified:
                        # pureboot 5's data space. 0x0200 is clear of the
                        # loader's own .noinit unit at the bottom of SRAM and of
                        # the stack at the top. Reading it back over the same
                        # locked link proves both directions of the new space.
                        probe = bytes(range(0x30, 0x40))
                        loader.write_ram(0x0200, probe)
                        if loader.read_ram(0x0200, len(probe)) != probe:
                            fail(f"{label}: RAM round-trip mismatch")
                        # The register file and the I/O space share the data
                        # address space on AVR, so the same command reaches a
                        # peripheral register. SPMCSR reads back as idle here.
                        verbose_ram = loader.read_ram(0x0200, 4)
                        print(f"  {label}: RAM read/write ok ({verbose_ram.hex()})")
                    loader.run_application()
                    banner = port.read_exact(3, 5.0)
                    if banner != b"APP":
                        fail(f"{label}: application banner was {banner!r}")
                finally:
                    port.close()
        finally:
            device.stop()
        # Ground truth (read after the runner exits and writes its dump): what
        # the tool programmed must be what the simulator actually holds.
        pages = pb.plan_flash(open(app_bin, "rb").read(), ground_truth)
        flash_true = open(dump, "rb").read()
        for address, data in pages.items():
            if flash_true[address : address + page] != data:
                fail(f"{label}: simulator flash differs from the programmed image at {address:#06x}")
        print(f"  {label}: locked at {hz} Hz / {baud} Bd, flash+EEPROM verified"
              + (", hand-over ok" if hand_over else ""))
    # The app fixture is built for one clock; the hand-over banners there. A
    # second point at double that clock, same loader binary, proves the lock is
    # measured, not baked in — the whole point of autobaud. (Doubling keeps the
    # bit period healthy; halving would drop it below the software UART's floor.)
    round_trip(app_hz, app_baud, "clock-a", hand_over=True)
    round_trip(app_hz * 2, app_baud, "clock-b", hand_over=False)
    print("pbautobaud: calibration lock and flash/EEPROM/fuse round-trip pass at both clocks")
 if __name__ == "__main__":
    main()
--- a/test/pbdirty.py
+++ b/test/pbdirty.py
@@ -1,88 +0,0 @@
 #!/usr/bin/env python3
 """Dirty-page-buffer acceptance test: with no discard in the loader, a page
 filled over words an earlier writer left takes those instead. The whole
 contract is asserted — a bare verify sees the corruption, the repairing
 verify fixes it in one rewrite, and it stays fixed.
 The state is reached the one way the loader cannot prevent: an application
 dirties the buffer and jumps in with no reset between. Boot-sectioned megas
 forbid that outright (SPM runs only from the boot section, Atmel-8271 §26.2),
 but simavr dispatches SPM from anywhere, which is what makes it constructible.
 Usage: pbdirty.py <device_bin> <pureboot_elf> <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 main():
    device_bin, elf, mcu, hz, base_hex, page, baud, app_bin, tool, workdir = sys.argv[1:]
    page, baud = 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)
    dump = os.path.join(workdir, "dump.bin")
    # Reset boots the application on a BOOTRST-unprogrammed mega; its 'L' is
    # the loader entry this test needs, reached without a reset.
    device = pbsim.Device(device_bin, elf, mcu, hz, base_hex, page, baud, dump, reset_hex="0")
    try:
        port = pb.Port(device.pty, baud)
        loader = pb.Loader(port)
        loader.connect(25)
        # Install the application and hand over to it.
        pb.op_flash(loader, app_bin, erase=False, verify=True)
        loader.run_application()
        if port.read_exact(3, 5.0) != b"APP":
            fail("the application did not start")
        port.write(b"D")
        if port.read_exact(1, 5.0) != b"D":
            fail("the application did not acknowledge dirtying the page buffer")
        port.write(b"L")
        loader = pb.Loader(port)
        loader.connect(25)
        # Program by hand, so the corruption is observable before anything
        # repairs it.
        pages = pb.plan_flash(open(app_bin, "rb").read(), loader.info)
        for address in sorted(pages):
            loader.write_page(address, pages[address])
        try:
            pb.verify_pages(loader, pages)
        except pb.Error as error:
            if "verify failed" not in str(error):
                fail(f"the read-back failed, but not at verify: {error}")
        else:
            # Either the fixture no longer dirties the buffer, or the loader
            # clears it again — in which case this test's premise is gone.
            fail("programming over a dirty page buffer came back clean")
        # What the programming path uses: one rewrite settles it, and it stays
        # settled.
        pb.verify_pages(loader, pages, repair=True)
        pb.verify_pages(loader, pages)
        # Ground truth beyond the loader's own read-back.
        loader.run_application()
        if port.read_exact(3, 5.0) != b"APP":
            fail("the application did not start after the recovered write")
        port.close()
    finally:
        device.stop()
    print("pbdirty: a dirty page buffer is caught by verify and cleared by the retry")
 if __name__ == "__main__":
    main()
--- a/test/pbrehome.py
+++ b/test/pbrehome.py
@@ -1,96 +0,0 @@
 #!/usr/bin/env python3
 """Re-homing acceptance test: an image programmed somewhere other than its
 canonical slot must still be a working loader, and the ordinary
 --update-loader flow must put a build into the top slot from there.
 Two positions. Address 0, a raw .bin handed to a programmer: the staging
 install and the word-0 redirect run from copies outside page 0's slot, so the
 running-slot guard never blocks them. And the staging slot itself, where a
 loader already sitting there IS the staging copy — recognized by its embedded
 block and left in place, then streaming the new resident like any staged copy.
 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 - pb.SLOT
    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()
--- a/test/pbreloc.py
+++ b/test/pbreloc.py
@@ -1,9 +1,11 @@
 #!/usr/bin/env python3
-"""Position-independence acceptance test: the identical binary, flashed one
+"""Position-independence acceptance test: the identical pureboot binary,
-slot below the resident, must serve the complete command set from there. The
+flashed one slot below the resident loader, must serve the complete command
-info block must come back byte-identical, the write guard must refuse the
+set from there. The resident installs it (through-word composed by the host
-staged copy's own slot and permit the resident's, and the staged copy must be
+layer), 'J' transfers control, and every command is exercised against the
-able to rewrite the resident verbatim.
+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>
@@ -22,7 +24,7 @@ def fail(message):
 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
+    stage = base - 512
    sys.path.insert(0, os.path.dirname(os.path.abspath(tool)))
    sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
    import pbsim
@@ -44,7 +46,6 @@ def main():
        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)
@@ -64,10 +65,8 @@ def main():
        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
+        # The guard, both ways: its own slot refused (drained, unchanged),
-        # resident slot writable. The refusal leaves its drained words in the
+        # the resident slot writable.
        # SPM buffer, so the write that follows may take them — and clears
        # them by writing, so the retry must not.
        before = loader.read_flash(stage, page)
        loader.write_page(stage, bytes(page))
        if loader.read_flash(stage, page) != before:
@@ -75,13 +74,11 @@ def main():
        marker = bytes((i * 3) & 0xFF for i in range(page))
        loader.write_page(base, marker)
        if loader.read_flash(base, page) != marker:
-            loader.write_page(base, marker)
+            fail("the staged copy could not write the resident slot")
            if loader.read_flash(base, page) != marker:
                fail("the staged copy could not write the resident slot, even on retry")
        # Restore the resident image through the staged copy, then 'J' back
        # into it and prove it lives.
-        resident = image + b"\xff" * (pb.SLOT - len(image))
+        resident = image + b"\xff" * (512 - len(image))
        pb.write_differing(loader, base, resident)
        back_info = loader.enter_copy(base, 25)
        if back_info.raw != resident_info:
--- a/test/pbsim.py
+++ b/test/pbsim.py
@@ -8,17 +8,10 @@ import subprocess
 class Device:
-    def __init__(self, binary, elf, mcu, hz, base_hex, page, baud, dump, reset_hex=None, resume=None, link=None):
+    def __init__(self, binary, elf, mcu, hz, base_hex, page, baud, dump, reset_hex=None, resume=None):
-        cmd = [binary]
+        cmd = [binary, elf, mcu, hz, base_hex, str(page), str(baud), dump]
        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
+            cmd.append(reset_hex if reset_hex is not None else ("0" if mcu != "atmega328p" else base_hex))
            # 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")
--- a/test/pbtest.py
+++ b/test/pbtest.py
@@ -1,17 +1,19 @@
 #!/usr/bin/env python3
-"""End-to-end protocol test: drive the simavr device with the real host tool
+"""End-to-end pureboot protocol test: spawn the simavr device, then drive it
-over its pty through flash, EEPROM, fuse and hand-over scenarios, and
+with the real host tool (pureboot.py, as a subprocess over the device's pty)
-cross-check the tool's view against the simulator's ground-truth dumps.
+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]
+                 <baud> <eeprom_size> <app_bin> <tool_py> <workdir>
-
+Exits 0 if every scenario passes.
 The optional link is the runner's -l spec (usart1, sw:B5,B1, ...), for a
 loader built off the chip's natural serial default.
 """
 import os
 import signal
 import subprocess
 import sys
 import time
 def fail(message):
@@ -31,14 +33,53 @@ def rjmp_decode(word, at, flash_words):
    return (at + 1 + offset) % flash_words
 class Device:
    def __init__(self, binary, elf, mcu, hz, base, page, baud, dump):
        self.proc = subprocess.Popen(
            [binary, elf, mcu, hz, base, str(page), str(baud), dump],
            stdout=subprocess.PIPE,
            stderr=subprocess.STDOUT,
            text=True,
        )
        self.dump = dump
        self.pty = None
        deadline = time.time() + 5
        while time.time() < deadline:
            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 stop(self):
        self.proc.terminate()
        try:
            self.proc.wait(timeout=3)
        except subprocess.TimeoutExpired:
            self.proc.kill()
 def run_tool(tool, pty, baud, *args):
    result = subprocess.run(
        [sys.executable, tool, "--port", pty, "--baud", str(baud), "--wait", "20", *args],
        capture_output=True,
        text=True,
        timeout=120,
    )
    print(result.stdout, end="")
    if result.returncode != 0:
        fail(f"tool exited {result.returncode}: {result.stderr.strip()}")
    return result.stdout
 def main():
-    args = sys.argv[1:]
+    (device_bin, elf, mcu, hz, base_hex, page, baud, eeprom_size, app_bin, tool, workdir) = 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)
@@ -49,50 +90,28 @@ def main():
    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 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")
    # Where SRAM begins: the x8 and x4 megas push it past their extended I/O
    # space, everything else starts right after the plain I/O registers. The
    # loader keeps no statics and its stack sits at RAMEND, so the first SRAM
    # byte is free for the data-space probe below.
    classic = mcu in ("atmega8", "atmega8a", "atmega16", "atmega16a", "atmega32", "atmega32a")
    ram_base = 0x0100 if mega and not classic else 0x0060
    word_flash = base + pb.SLOT > 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"), pb.NEWEST_LOADER, 0, 0, 0, page & 0xFF])
+        bytes([ord("P"), ord("B"), 1, 0, 0, 0, page])
-        + bytes([wire_base & 0xFF, wire_base >> 8, eeprom_size & 0xFF, eeprom_size >> 8])
+        + bytes([base & 0xFF, base >> 8, eeprom_size & 0xFF, eeprom_size >> 8])
-        + bytes([flags])
+        + bytes([0 if mcu == "atmega328p" else 1])
    )
-    device = pbsim.Device(device_bin, elf, mcu, hz, base_hex, page, baud, dump, link=link)
+    device = Device(device_bin, elf, mcu, hz, base_hex, page, baud, dump)
    try:
        # Session 1: knock from reset, identify, program everything, stay.
-        out = pbsim.run_tool(tool, device.pty, baud, "--info", "--fuses", "--flash", app_bin,
+        out = run_tool(tool, device.pty, baud, "--info", "--fuses", "--flash", app_bin,
                       "--eeprom", ee_path, "--stay")
-        for needed in ("version", "signature", "fuses", "verify:", "stays"):
+        for needed in ("device: 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, exercise
+        # Session 2: reconnect into the live session, verify, dump, hand over
-        # the data space; hand over is deferred — the pty must be reopened for
+        # is deferred — the pty must be reopened for the APP banner first.
-        # the APP banner first.
+        out = run_tool(tool, device.pty, baud, "--verify-flash", app_bin, "--verify-eeprom", ee_path,
-        probe = "c0ffee"
+                       "--read-flash", read_flash, "--read-eeprom", read_eeprom, "--stay")
        out = pbsim.run_tool(tool, device.pty, baud, "--verify-flash", app_bin, "--verify-eeprom", ee_path,
                             "--read-flash", read_flash, "--read-eeprom", read_eeprom,
                             "--poke", f"{ram_base:#x}:{probe}", "--peek", f"{ram_base:#x}:3", "--stay")
        if out.count("verify:") != 2:
            fail("session 2 did not verify both memories")
        # What went into SRAM must come back out of it: the data space is one
        # more selector on the same transfer as flash and EEPROM, so a wrong
        # selector decode would show up here and nowhere else.
        if probe not in out.replace(" ", ""):
            fail(f"data-space round trip at {ram_base:#x} did not read back {probe}\n{out}")
        eeprom_back = open(read_eeprom, "rb").read()
        if eeprom_back[: len(ee_image)] != ee_image:
@@ -109,34 +128,11 @@ def main():
        # 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()
+        device.proc.send_signal(signal.SIGUSR1)
        port = pb.Port(device.pty, baud)
        try:
            loader = pb.Loader(port)
-            live = loader.connect(15)
+            loader.connect(15)
            # The loader built from this tree must report a version the tool
            # beside it speaks — a bump the tool was never told about is a
            # loader it would refuse to talk to. Not equality with the newest:
            # the tool now spans two loader generations, the fixed-baud one
            # here and the unified autobaud loader that follows it.
            if not pb.OLDEST_LOADER <= live.version <= pb.NEWEST_LOADER:
                fail(f"loader reports pureboot {live.version}, the tool speaks "
                     f"{pb.OLDEST_LOADER}..{pb.NEWEST_LOADER}")
            # A W addressed inside a page rather than at its base must still
            # consume exactly one page and prompt. The loader's own slot is the
            # target — the guard refuses to commit it — and the payload is
            # erased-state bytes, so the probe can disturb neither the image nor
            # the page buffer it leaves behind. Hand-built rather than through
            # write_page(), which would follow the fill with its erase and
            # write; the point here is that the fill alone consumes exactly one
            # page whatever the address's low bits say.
            wire = base + 1
            port.write(bytes((ord("W"), pb.selector(pb.SP_FLASH, wire), wire & 0xFF, (wire >> 8) & 0xFF))
                       + b"\xff" * page)
            if port.read_exact(1, 5.0) != pb.PROMPT:
                fail("unaligned W did not return to the prompt")
            loader.run_application()
            banner = port.read_exact(3, 5.0)
            if banner != b"APP":
@@ -154,10 +150,9 @@ def main():
        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
+    # loader, the trampoline on the application's own entry.
-    # chips only — a boot-sectioned mega's word 0 stays the application's).
+    if mcu != "atmega328p":
-    if patch:
+        flash_words = (base + 512) // 2
        flash_words = (base + pb.SLOT) // 2
        app = open(app_bin, "rb").read()
        word0 = flash_true[0] | (flash_true[1] << 8)
        if rjmp_decode(word0, 0, flash_words) != base // 2:
--- a/test/pbupdate.py
+++ b/test/pbupdate.py
@@ -1,12 +1,16 @@
 #!/usr/bin/env python3
-"""Self-update end-to-end: an application is flashed, the loader replaces
+"""Self-update end-to-end: an application is flashed, then the loader
-itself with a re-timed build, and every power-fail phase is rehearsed by
+replaces itself with a re-timed build through the host tool's
-killing the device mid-write, restarting it from its flash dump, and letting
+--update-loader — and the power-fail phases of that update are rehearsed by
-a re-run complete the update.
+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 mega runs the BOOTRST-unprogrammed profile (reset boots the application;
-the application, whose 'L' is the application-owned loader entry — with
+the fixture application's 'L' jump is the application-owned loader entry),
--assume-fuses standing in for the fuse read simavr cannot model.
+with --assume-fuses standing in for the fuse read simavr cannot model. The
 tinies reset into a loader at every phase by construction — the t13a because
 its staging slot carries the reset vector itself, the t85 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>
@@ -37,21 +41,10 @@ class PowerFail(Exception):
    pass
-def assumed_fuses(pb, image):
+MEGA_FUSES = "ffffffdd"  # high 0xdd: BOOTSZ = 1 KB, BOOTRST unprogrammed
    """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 * pb.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):
+def make_fault_loader(pb, base, 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."""
@@ -66,7 +59,7 @@ def make_fault_loader(pb, base, slot, kill_region, kill_hits, device):
            if address >= base:
                phase = "resident"
                self.seen_resident = True
-            elif address >= base - slot:
+            elif address >= base - 512:
                phase = "stage_restore" if self.seen_resident else "stage"
            else:
                phase = "app"
@@ -84,17 +77,13 @@ def make_fault_loader(pb, base, slot, kill_region, kill_hits, device):
 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")
+    mega = mcu == "atmega328p"
-    # The m48s are megas without a boot section: patched vector, no fuse
+    reset_hex = "0" if mega else None  # the mega runs BOOTRST-unprogrammed here
    # preflight, and the same reset-to-0 the tinies get.
    patch = not mega or mcu.startswith("atmega48")
    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
    slot = pb.SLOT
    os.makedirs(workdir, exist_ok=True)
    objcopy = os.environ.get("PB_OBJCOPY", "avr-objcopy")
    images = {}
@@ -106,7 +95,7 @@ def main():
        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
+    fuses = bytes.fromhex(MEGA_FUSES) if mega else None
    def connect(device):
        port = pb.Port(device.pty, baud)
@@ -120,16 +109,16 @@ def main():
        return port, loader
    def padded(image):
-        return image + b"\xff" * (slot - len(image))
+        return image + b"\xff" * (512 - len(image))
    def resident_bytes(loader):
-        return loader.read_flash(base, slot)
+        return loader.read_flash(base, 256) + loader.read_flash(base + 256, 256)
    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
+        stage = base - 512
-        got = loader.read_flash(stage, slot)
+        got = loader.read_flash(stage, 256) + loader.read_flash(stage + 256, 256)
        for address, data in app_pages.items():
            if stage <= address < base:
                if got[address - stage : address - stage + page] != data:
@@ -146,8 +135,8 @@ def main():
        # A clean CLI update, resident -> v9.
        args = ["--update-loader", os.path.join(workdir, "v9.bin"), "--state", state, "--stay"]
-        if fuses:
+        if mega:
-            args += ["--assume-fuses", fuses.hex()]
+            args += ["--assume-fuses", MEGA_FUSES]
        out = pbsim.run_tool(tool, device.pty, baud, *args)
        if "loader updated" not in out:
            fail("update did not report success")
@@ -171,14 +160,14 @@ def main():
        # cost of that profile (README).
        for kill_region, kill_hits, kill_device in (
            ("stage", 2, True),
-            ("resident", 1, patch),
+            ("resident", 1, not mega),
            ("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 = make_fault_loader(pb, base, 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)
@@ -202,12 +191,12 @@ def main():
        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.
+    # on the tinies an independent decode of the reset routing.
    flash = open(dump, "rb").read()
-    if flash[base : base + slot] != padded(images[final]):
+    if flash[base : base + 512] != padded(images[final]):
        fail("ground-truth resident region does not match the final image")
-    if patch:
+    if not mega:
-        flash_words = (base + slot) // 2
+        flash_words = (base + 512) // 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")
--- a/test/pureboot_device.c
+++ b/test/pureboot_device.c
@@ -1,16 +1,12 @@
-// simavr "device" for the pureboot protocol tests, every chip. Loads the
+// simavr "device" for the pureboot protocol tests, all three chips. Loads
-// boot-linked ELF at the loader base, starts execution there (BOOTRST / the
+// the boot-linked ELF at the loader base, starts execution there (BOOTRST /
-// patched vector are not what is under test), and exposes the loader's
+// 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.
+//   - ATmega328P: the hardware USART0 through simavr's uart_pty.
-//   - Software UART builds: an 8N1 bridge between a pty and the GPIO pins,
+//   - Tinies: an 8N1 bridge between a pty and the GPIO software UART
-//     timed against the simulated cycle counter (drives the loader's RX,
+//     (drives PB0, the loader's RX; decodes PB1, its TX), timed against the
-//     decodes its TX).
+//     simulated cycle counter.
 //
 // 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
@@ -42,44 +38,17 @@
 static avr_t *avr;
 static uart_pty_t uart_pty;
-static int link_software;
+static int use_uart_pty;
 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);
@@ -95,15 +64,6 @@ static int fixed_flash_ioctl(avr_io_t *io, uint32_t ctl, void *param)
 		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);
 }
@@ -182,16 +142,9 @@ static avr_cycle_count_t tx_sample(avr_t *mcu, avr_cycle_count_t when, void *par
 {
 	(void)mcu;
 	(void)param;
 	if (tx_bit < 8) {
 	tx_shift = (uint8_t)((tx_shift >> 1) | (tx_level ? 0x80 : 0));
 	if (++tx_bit < 8)
 		return when + bit_cycles;
 		/* The byte is not delivered until its stop bit has passed. A real
 		 * receiver cannot answer sooner, and a host that did would put its
 		 * start bit on the wire while the device is still driving the stop
 		 * bit — which the device, transmitting, is not watching for. */
 		return when + bit_cycles;
 	}
 	if (write(pty_master, &tx_shift, 1) != 1)
 		fprintf(stderr, "device: pty write lost a byte\n");
 	tx_active = 0;
@@ -304,42 +257,29 @@ static void finish(int sig)
 			}
 		}
 	}
-	if (!link_software)
+	if (use_uart_pty)
 		uart_pty_stop(&uart_pty);
 	_exit(0);
 }
 int main(int argc, char *argv[])
 {
-	int link_given = 0;
+	if (argc < 8 || argc > 10) {
 	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>"
+		        "usage: %s <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 on the mega, 0 on the tinies)\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;
+	use_uart_pty = strcmp(mcu_name, "atmega328p") == 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) {
@@ -350,7 +290,7 @@ int main(int argc, char *argv[])
 	avr->frequency = (uint32_t)strtoul(argv[3], NULL, 0);
 	memset(avr->flash, 0xff, avr->flashend + 1); // real flash powers up erased
-	if (args > 8) {
+	if (argc > 9) {
 		// 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) {
@@ -366,13 +306,11 @@ int main(int argc, char *argv[])
 		}
 		memcpy(avr->flash + base, fw.flash, fw.flashsize);
 	}
-	// The boot-sectioned megas enter the loader in hardware (BOOTRST, not
+	// The mega enters the loader in hardware (BOOTRST, not modeled — the
-	// modeled — the argument picks the modeled fuse's target); the tinies
+	// argument picks the modeled fuse's target); the tinies reset to word 0
-	// and the boot-section-less m48s reset to word 0 like silicon — erased
+	// like silicon — erased flash walks up into the loader, and after the
-	// flash walks up into the loader, and after the host's surgery the
+	// host's surgery the patched vector routes there.
-	// patched vector routes there.
+	reset_pc = argc > 8 ? (uint32_t)strtoul(argv[8], NULL, 0) : (use_uart_pty ? base : 0);
 	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;
@@ -385,34 +323,27 @@ int main(int argc, char *argv[])
 		avr_ioctl(avr, AVR_IOCTL_EEPROM_SET, &seed);
 	}
-	// The megas carry simavr's avr_flash module (and its two gaps the wrap
+	if (use_uart_pty) {
 	// 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();
 		// 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('0'), &flags);
 		flags &= ~AVR_UART_FLAG_POLL_SLEEP;
 		avr_ioctl(avr, AVR_IOCTL_UART_SET_FLAGS('0'), &flags);
 		uart_pty_init(avr, &uart_pty);
 		uart_pty_connect(&uart_pty, '0');
 		printf("PB_PTY %s\n", uart_pty.pty.slavename);
 	} 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);
+		rx_pin = avr_io_getirq(avr, AVR_IOCTL_IOPORT_GETIRQ('B'), 0);
-		avr_irq_register_notify(avr_io_getirq(avr, AVR_IOCTL_IOPORT_GETIRQ(sw_tx_port), (unsigned)sw_tx_bit), tx_hook,
+		avr_irq_register_notify(avr_io_getirq(avr, AVR_IOCTL_IOPORT_GETIRQ('B'), 1), tx_hook, NULL);
 		                        NULL);
 		avr_raise_irq(rx_pin, 1); // idle line
 		int slave;
@@ -440,27 +371,18 @@ int main(int argc, char *argv[])
 			reset_requested = 0;
 			avr_reset(avr);
 			avr->pc = reset_pc;
-			if (!link_software) { // reset restores the pacing hack; re-clear it
+			if (use_uart_pty) { // reset restores the pacing hack; re-clear it
 				uint32_t flags = 0;
-				avr_ioctl(avr, AVR_IOCTL_UART_GET_FLAGS(uart_digit), &flags);
+				avr_ioctl(avr, AVR_IOCTL_UART_GET_FLAGS('0'), &flags);
 				flags &= ~AVR_UART_FLAG_POLL_SLEEP;
-				avr_ioctl(avr, AVR_IOCTL_UART_SET_FLAGS(uart_digit), &flags);
+				avr_ioctl(avr, AVR_IOCTL_UART_SET_FLAGS('0'), &flags);
 			} else {
 				bridge_reset();
 			}
 		}
-		if (link_software && ++since_poll >= 2000) {
+		if (!use_uart_pty && ++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);
--- a/test/test_planner.py
+++ b/test/test_planner.py
@@ -1,8 +1,9 @@
 #!/usr/bin/env python3
-"""Host-tool unit tests — the planning and policy logic, no simulator:
+"""Host-tool unit tests — the pure planning and policy logic, no simulator:
-programming orders and their recovery properties, the reset-vector surgery,
+the flash-programming orders and their recovery properties, the reset-vector
-the staging composition, the boot-fuse decode, and the update preflight over
+surgery, the staging-slot composition, the mega boot-fuse decode, and the
-fuse combinations simavr cannot model.
+update preflight's error/warning matrix (fuse combinations simavr cannot
 model reach it here as synthetic bytes).
 Usage: test_planner.py <tool_py>
 """
@@ -26,21 +27,11 @@ def expect_error(what, fn, *needles):
    fail(f"{what}: no error raised")
-def info_of(pb, base, page, patch, flash, signature=(0x1E, 0x93, 0x0B), word_flash=False, version=None):
+def info_of(pb, base, page, patch, flash):
-    scale = 2 if word_flash else 1
+    raw = bytes((0x50, 0x42, 1, 0x1E, 0x93, 0x0B, page, base & 0xFF, base >> 8,
-    wire_base = base // scale
+                 0, 2, 1 if patch else 0))
    flags = (1 if patch else 0) | (2 if word_flash else 0)
    # The EEPROM size comes from the signature, as it must: pureboot 5 derives
    # the whole geometry from the signature rather than sending it, so a
    # synthetic block that disagreed with its own signature would describe a
    # chip that cannot exist.
    eeprom = pb.CHIP_GEOMETRY[signature][2]
    raw = bytes((0x50, 0x42, pb.NEWEST_LOADER if version is None else version,
                 *signature, page & 0xFF, wire_base & 0xFF, wire_base >> 8,
                 eeprom & 0xFF, eeprom >> 8, flags))
    info = pb.Info(raw)
-    if info.flash_size != flash:
+    assert info.flash_size == flash
        fail(f"info_of({base:#x}) decodes to {info.flash_size:#x} of flash, not {flash:#x}")
    return info
@@ -59,67 +50,16 @@ def main():
    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 = info_of(pb, 0x7E00, 128, False, 0x8000)
-    # Versioning: the block's third byte is the loader's version, and the tool
+    # mega_boot: BOOTSZ words and the BOOTRST sense, DS40002061B §27.
-    # speaks a window of them. Every version in the window decodes, so an older
+    for bits, start in ((0b11, 0x7E00), (0b10, 0x7C00), (0b01, 0x7800), (0b00, 0x7000)):
-    # deployed loader stays usable; one above the window is refused by name,
+        prog, at = pb.mega_boot((0xF8 | (bits << 1)) & ~1)
    # since which version changed the protocol is knowledge only the tool
    # holds, and it holds none about a version it has never heard of.
    for version in range(pb.OLDEST_LOADER, pb.NEWEST_LOADER + 1):
        if info_of(pb, 0x1E00, 64, True, 0x2000, version=version).version != version:
            fail(f"pureboot {version} does not decode")
    expect_error(
        "unknown loader version",
        lambda: info_of(pb, 0x1E00, 64, True, 0x2000, version=pb.NEWEST_LOADER + 1),
        f"pureboot {pb.NEWEST_LOADER + 1}",
        "newer tool",
    )
    # 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:
        chip = info_of(pb, flash - pb.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}")
+            fail(f"mega_boot BOOTSZ={bits:02b} programmed: {prog} {at:#06x}")
-            fuses[which] |= 1
+        prog, at = pb.mega_boot(0xF8 | (bits << 1) | 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}")
+            fail(f"mega_boot BOOTSZ={bits:02b} unprogrammed: {prog} {at:#06x}")
    # Word-addressed info decode: the 1284P's base and page ride the wire
    # scaled — a 17-bit base halved into the block's two bytes, a 256-byte page
    # spelled 0 — and its slot is the same 512 bytes as everywhere else, so its
    # staging slot lands inside the 1 KiB minimum boot section.
    big = info_of(pb, 0x1FE00, 0, False, 0x20000, signature=(0x1E, 0x97, 0x05), word_flash=True)
    if big.page != 256 or big.base != 0x1FE00 or big.stage != 0x1FC00:
        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.
@@ -168,39 +108,13 @@ def main():
        fail("mega staging content should be the bare image")
    expect_error("mega staging size", lambda: pb.staging_content(image + b"!", mega), "512")
-    # The image stamp: found in a synthetic binary, absent in noise. pureboot
+    # The embedded info block: found in a synthetic binary, absent in noise.
-    # 5 stamps the magic, its version and the signature, and the geometry is
+    binary = bytes((0xAA,)) * 10 + tiny.raw + bytes((0xBB,)) * 10
    # looked up from there — so what comes back must equal what a live device
    # of the same chip reports.
    stamp = bytes((0x50, 0x42, pb.NEWEST_LOADER)) + bytes(tiny.signature)
    binary = bytes((0xAA,)) * 10 + stamp + bytes((0xBB,)) * 10
    found = pb.image_info(binary)
    if found is None or found.raw != tiny.raw:
-        fail(f"image_info misreads the v{pb.NEWEST_LOADER} stamp: "
+        fail("image_info misses the embedded block")
             f"{found.raw.hex() if found else None} != {tiny.raw.hex()}")
    if pb.image_info(bytes((0xAA,)) * 40) is not None:
        fail("image_info invents a block")
    # An older loader's image stays readable, so a deployed build can be
    # identified and installed like any other.
    old = info_of(pb, 0x1E00, 64, True, 0x2000, version=pb.OLDEST_LOADER)
    found_old = pb.image_info(bytes((0xAA,)) * 10 + old.raw)
    if found_old is None or found_old.version != pb.OLDEST_LOADER:
        fail("image_info misses an older loader's 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)
@@ -226,15 +140,6 @@ def main():
    if pb.update_preflight(bytes((0xAA,)) * 8 + tiny.raw, tiny, None) != []:
        fail("tiny preflight should pass without fuses")
    # The 1284s' smallest boot section (512 words) is exactly the resident
    # slot plus its staging slot, so self-update is possible at the minimum
    # BOOTSZ — no fuse step up, the 644's geometry. That holds only while a
    # slot is 512 B: at 1 KiB the staging slot would fall outside the section
    # and the preflight would refuse.
    notes = pb.update_preflight(bytes((0xAA,)) * 8 + big.raw, big, fuses(0xFE))
    if not any("staging slot" in n for n in notes):
        fail(f"1284 minimum-BOOTSZ notes: {notes}")
    # 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.
@@ -245,114 +150,6 @@ def main():
    pb.check_walk_region({0x7800: bytes((0xFF,)) * 128}, mega, fuses(0xFA), False)
    pb.check_walk_region(deep, mega, None, False)  # fuses unknown: no check
    # The repairing verify: a mismatched page is rewritten rather than raised,
    # bounded so a fault that is not self-clearing cannot spin.
    class FakeLoader:
        """A device whose first `bad` writes of any page land wrong."""
        def __init__(self, info, bad):
            self.info = info
            self.bad = bad
            self.flash = {}
            self.writes = 0
        def write_page(self, address, data):
            self.writes += 1
            self.flash[address] = bytes(len(data)) if self.bad > 0 else bytes(data)
            self.bad -= 1
        def read_flash(self, address, count):
            return self.flash.get(address, bytes(count))
    want = {0: bytes((i * 5) & 0xFF for i in range(128))}
    # One bad write, then good: repaired in place, and the caller never sees
    # an error. The rewrite is counted, so a silent no-op cannot pass.
    device = FakeLoader(info_of(pb, 0x7E00, 128, False, 0x8000), bad=1)
    device.write_page(0, want[0])
    pb.verify_pages(device, want, repair=True)
    if device.writes != 2:
        fail(f"repairing verify made {device.writes} writes, expected 2")
    # Without repair the same state raises, so the repair is what fixed it.
    device = FakeLoader(info_of(pb, 0x7E00, 128, False, 0x8000), bad=1)
    device.write_page(0, want[0])
    expect_error("verify without repair", lambda: pb.verify_pages(device, want), "verify failed")
    # A page that never comes good stops after RETRIES rewrites, and says so.
    device = FakeLoader(info_of(pb, 0x7E00, 128, False, 0x8000), bad=99)
    device.write_page(0, want[0])
    expect_error(
        "unrepairable page",
        lambda: pb.verify_pages(device, want, repair=True),
        "verify failed",
        f"after {pb.RETRIES} retries",
    )
    if device.writes != pb.RETRIES + 1:
        fail(f"unrepairable page took {device.writes} writes, expected {pb.RETRIES + 1}")
    # The knock handshake against a device that is not listening yet — the
    # state a port open leaves behind: it resets the chip into a fresh
    # activation window while the previous session's prompt is still in
    # flight, so the first knock is lost and a prompt arrives anyway.
    class FakePort:
        """A loader in its activation window, plus `lost` leading writes the
        reset swallows and one stale prompt still on the wire."""
        def __init__(self, info_raw, lost=0, stale=b"", active=False):
            self.info_raw = info_raw
            self.lost = lost
            self.inflight = bytearray(stale)
            self.rx = bytearray()
            self.active = active
            self.last = None
        def flush_input(self):
            self.rx.clear()
        def write(self, data):
            if self.lost:
                self.lost -= 1
                return
            for byte in bytes(data):
                if not self.active:
                    self.active = self.last == ord("p") and byte == ord("b")
                    self.last = byte
                    if self.active:
                        self.rx += pb.PROMPT
                elif byte == ord("b"):
                    self.rx += self.info_raw + pb.PROMPT
                else:
                    self.rx += pb.PROMPT
        def read_available(self, wait):
            self.rx = self.inflight + self.rx  # the stale prompt lands late
            self.inflight.clear()
            out, self.rx = bytes(self.rx), bytearray()
            return out
        def read_exact(self, count, timeout):
            if len(self.rx) < count:
                raise pb.Error(f"timeout: got {len(self.rx)} of {count} bytes")
            out, self.rx = bytes(self.rx[:count]), self.rx[count:]
            return out
    raw = info_of(pb, 0x7E00, 128, False, 0x8000).raw
    for what, port in (
        ("clean window", FakePort(raw)),
        ("stale prompt over a lost knock", FakePort(raw, lost=1, stale=pb.PROMPT)),
        ("live session", FakePort(raw, active=True)),
    ):
        info = pb.Loader(port).connect(5)
        if info.raw != raw:
            fail(f"connect ({what}) returned {info.raw.hex()}")
    # A device that never answers still says so, and a version the tool cannot
    # speak is reported as such rather than retried into a timeout.
    expect_error("dead device", lambda: pb.Loader(FakePort(raw, lost=99)).connect(0), "no answer")
    old = bytes(raw[:2]) + bytes((pb.NEWEST_LOADER + 1,)) + bytes(raw[3:])
    expect_error("unspeakable version", lambda: pb.Loader(FakePort(old)).connect(5), "needs a newer tool")
    print("test_planner: all planner and policy checks pass")
--- a/tools/check.sh
+++ b/tools/check.sh
@@ -1,39 +0,0 @@
 #!/bin/bash
 # 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) and swaps the compact size matrix for the exhaustive
 # clock × baud × backend cross product. LIBAVR_ROOT must point at the libavr
 # checkout.
 set -e
 cd "$(dirname "$0")/.."
 full=0
 [[ "$1" == "--full" ]] && { full=1; shift; export PUREBOOT_FULL_MATRIX=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
 	echo "==== $chip ===="
 	cmake --workflow --preset "$chip-generated" "$@"
 done
 if ((full)); then
 	for chip in "${REFLECT_SPOT[@]}"; do
 		echo "==== $chip reflect ===="
 		cmake --workflow --preset "$chip-reflect" "$@"
 	done
 fi
 echo "check: every chip green"
--- a/tools/make_presets.py
+++ b/tools/make_presets.py
@@ -1,90 +0,0 @@
 #!/usr/bin/env python3
 """Regenerate CMakePresets.json — one uniform pipeline per chip.
 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
 """
 import json
 import os
 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",
 ]
 # libavr's REFLECT_SPOT (tools/check.sh): one chip per hardware class and
 # pack vintage.
 REFLECT_SPOT = [
    "attiny13a", "attiny85", "atmega8", "atmega16a", "atmega32a",
    "atmega48pa", "atmega88", "atmega168pa", "atmega328p", "atmega164a",
    "atmega644p", "atmega1284",
 ]
 def main():
    configure = [{
        "name": "base",
        "hidden": True,
        "generator": "Ninja",
        "binaryDir": "${sourceDir}/build/${presetName}",
        "toolchainFile": "$env{LIBAVR_ROOT}/cmake/avr-toolchain.cmake",
        "cacheVariables": {
            "CMAKE_BUILD_TYPE": "Release",
            "CMAKE_EXPORT_COMPILE_COMMANDS": "ON",
            "CMAKE_COLOR_DIAGNOSTICS": "ON",
        },
    }]
    build, test, workflows = [], [], []
    def add(chip, mode):
        name = f"{chip}-{mode}"
        configure.append({
            "name": name,
            "inherits": "base",
            "cacheVariables": {
                "LIBAVR_MCU": chip,
                "LIBAVR_REFLECT": "ON" if mode == "reflect" else "OFF",
            },
        })
        build.append({"name": name, "configurePreset": name})
        steps = [{"type": "configure", "name": name}, {"type": "build", "name": name}]
        if mode == "generated":
            test.append({"name": name, "configurePreset": name, "output": {"outputOnFailure": True}})
            steps.append({"type": "test", "name": name})
        workflows.append({"name": name, "steps": steps})
    for chip in CHIPS:
        add(chip, "generated")
    for chip in REFLECT_SPOT:
        add(chip, "reflect")
    presets = {
        "version": 8,
        "configurePresets": configure,
        "buildPresets": build,
        "testPresets": test,
        "workflowPresets": workflows,
    }
    path = os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", "CMakePresets.json")
    with open(path, "w") as f:
        json.dump(presets, f, indent=1)
        f.write("\n")
    print(f"{len(CHIPS)} chips, {len(REFLECT_SPOT)} reflect: {os.path.normpath(path)}")
 if __name__ == "__main__":
    main()
Author	SHA1	Message	Date
BlackMark	19662d2386	build: emit an Intel-HEX beside every loader image avrdude programs Intel-HEX, not ELF, and the build produced only ELFs — so flashing a loader to a real chip meant running objcopy by hand. add_hex_output() hangs a POST_BUILD objcopy on each loader image: the three tsb tiers through add_tsb_variant, pureboot, and the re-timed pureboot9. .eeprom is dropped, being its own avrdude update. It uses the toolchain file's CMAKE_OBJCOPY rather than a hardcoded path, so every chip preset emits hex, not just the mega. pbapp keeps its ELF alone: the update test converts it to a raw binary itself, and it is not a flashing target. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>	2026-07-20 21:57:26 +02:00
BlackMark	f6598b0511	pureboot: PI lint, tightened gates, and the self-update test suite check_pi.py asserts the two link-time facts position independence rests on (no absolute jmp/call; the info block within the image's first 256 bytes); the size gates drop to 510 on the tinies for the trampoline word. New per-chip tests beside the reworked protocol test: the planner units (programming orders and their recovery properties, the surgery, staging composition, boot-fuse decode, and the update preflight's error/warning matrix over synthetic fuse bytes), the relocated-copy sweep (the identical image installed one slot lower serves the full command set — the PI acceptance test, and the one that caught the temporary-buffer trap), and the self-update end-to-end: --update-loader to a re-timed build (pureboot9, byte-different by PUREBOOT_TIMEOUT alone), then every power-fail phase killed mid-write, restarted from the runner's flash dump, and completed by a re-run with the application intact throughout. The mega rounds run the BOOTRST-unprogrammed profile: the fixture application's 'L' jump is the application-owned loader entry that profile relies on. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>	2026-07-20 19:37:57 +02:00
BlackMark	0604d3a0ad	pureboot: one position-independent binary — its own staging loader The image now runs from any 512-byte slot with every command intact: control flow stays PC-relative, the write guard keys on the running slot (the return-address anchor, computed once), the info block is addressed from that same anchor as a byte pair (no absolute 16-bit address in the image), and the application jump is an indirect call through a noipa- laundered pointer to the absolute entry. 'J' — jump to a wire word address, the one transfer primitive — replaces 'G': the host knows the application entry from the info block, and moving between loader copies needs arbitrary targets. The activation window is a compile-time 8 s (PUREBOOT_TIMEOUT overrides), counted as a single calibrated poll loop. A refused page no longer poisons the write-once temporary buffer (a real silicon trap: the next write would program the drained data): every page write discards the buffer first — CTPB on the tinies, on the mega the same RWWSRE store that re-enables RWW after programming. The tinies' post-op busy-waits go with it: their CPU halts through page erase and write. 488 / 502 / 504 B on t13a / t85 / mega — under the tinies' 510-byte budget, whose last slot word is the host-managed trampoline: the resident's holds the application entry, a staging copy's the jump through which an abandoned update still times out into a loader. The host tool updates the loader with itself: --update-loader installs the identical image one slot below the resident, jumps into it, lets it rewrite the resident, and restores the staging region from a state file — each phase idempotent off the flash state, resumable after any interruption (t13a: the staging slot carries the reset vector, written last in and first out; t85: word 0 redirected around the resident rewrite; mega: fuse-matrix preflight with a hard BOOTSZ gate and --assume-fuses for simulators). Application flashing recovers by reset from any interruption: patched page 0 and trampoline first, erase descending, and a walk-region refusal behind --force on BOOTRST-below-loader megas. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>	2026-07-20 19:37:43 +02:00
BlackMark	62a548cc09	pureboot: harden the sim device runner Cancel the GPIO bridge's cycle timers with the state they drive: avr_reset drops the TX latch, whose falling edge starts a spurious decode before bridge_reset runs, and the stale sampler then interleaves with the loader's first real answer through the shared shift state — the first post-reset replies came back corrupted and the knock retries burned the activation window into the application. Wrap the mega's registered flash ioctl to re-dispatch page erases with Z masked to the page boundary: simavr's PGERS handler erases spm_pagesize bytes from Z & ~1 (its PGWRT path masks correctly), wiping the neighbouring page when Z sits past the page start, which hardware permits (§26.8.1). Model the write-once temporary buffer in the tiny NVM module — silicon refuses a second load per word until the buffer clears, and a last-write- wins model masks real firmware bugs. Optional arguments select the reset vector (the mega's fuse profiles) and a raw flash image to resume from (power-fail tests re-enter a dumped state). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>	2026-07-20 19:37:10 +02:00
BlackMark	7d103ca957	pureboot: review-pass fixes to the host tool and device runner pureboot.py: reject an empty image file with a clear error instead of an IndexError deep in the vector-surgery planner; tighten the erase docstring (order is irrelevant there — every target byte is the same value, unlike a real flash where page 0 must go last). pureboot_device.c: the GPIO bridge's bit_cycles used plain truncating division where the firmware computes its own bit period with round-to-nearest (uart.hpp: (Clock.hz + Baud.bd/2)/Baud.bd) — one cycle off per bit on both tinies, harmless in practice but needless drift against a firmware built to a different constant. Matched exactly. Also clear the queued-bytes/decode-in-progress bridge state on the test-only reset signal, so a future reset-mid-transfer scenario can't feed a freshly reset chip bytes queued for its previous life. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AReSwkWkPX2A9Ym6grxRAh	2026-07-20 10:45:19 +02:00
BlackMark	eca7a41051	pureboot: gitignore python bytecode cache Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AReSwkWkPX2A9Ym6grxRAh	2026-07-20 10:43:56 +02:00
BlackMark	7314f7ab3b	pureboot: stop tracking the python bytecode cache A stray __pycache__/*.pyc from a local test run got swept into the previous commit's git add. Untracked and gitignored. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AReSwkWkPX2A9Ym6grxRAh	2026-07-20 10:43:36 +02:00
BlackMark	5b361904ab	pureboot: host tool and end-to-end protocol tests, all three chips pureboot.py (Python stdlib only): images as raw binary or Intel HEX, flash and EEPROM programming with read-back verify, erase composites, fuse and info readout, activation-timeout configuration, and the tinies' reset-vector surgery — the trampoline word below the loader, page 0 written last. The test spawns a simavr device (pureboot_device.c) — the mega's USART as a pty; on the tinies a cycle-timed GPIO<->pty bridge for the polled software UART plus the NVM module simavr's tiny cores lack (their SPM opcode ioctls into a void and silently does nothing) — and drives it with the real tool: knock from reset (erased-flash walk on the tinies), program and verify both memories, timeout write, session reconnect, an external reset through the patched vector, hand-over, and the fixture application's banner. Results are cross-checked against ground-truth memory dumps and an independent decode of the surgery's rjmp words, red-verified against a sabotaged encoder. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AReSwkWkPX2A9Ym6grxRAh	2026-07-20 05:54:15 +02:00
BlackMark	833e134e01	pureboot: the device — one pure C++ source, 512 bytes, every chip No inline assembly, no global register variables; libavr does the datasheet work. The device speaks primitives — flash read/page-program, EEPROM read/write, fuse read, info block, EEPROM-resident activation timeout, hand-over — and verify, erase, reset-vector surgery, and timeout configuration live in the host tool. 490 B on the ATtiny13A, 510 B on the ATtiny85, 484 B on the ATmega328P, each linked into the top 512 bytes of flash; per-chip size tests gate all three. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AReSwkWkPX2A9Ym6grxRAh	2026-07-20 05:33:28 +02:00
BlackMark	da730b7bb5	tsb: third size pass — restructure to the oracle's shape The second pass concluded the 168 B tricks->asm gap was per-call ABI cost. Most of it was structure. Rebuilt around the oracle's own shape — argless noinline primitives over a whole-loader call-saved register protocol (g_addr in Y, count r16, window r7, direction latch r6), a top-down erase_below whose loop tests against zero and hands callers g_addr = 0 for free, bounded rx everywhere (a silent host unwinds to the app from any state, as the oracle does), and a named tsb_app entry that --pmem-wrap-around=32k relaxes to the wrapped rjmp: tsb_asm 510 B in the 512 B section (oracle: 500), C++ except rx and the page-store loop — the two routines whose remaining cost is the calling convention itself (~30 asm lines, was ~280) tsb_tricks 526 B, no assembly at all (was 666) tsb_pure 836 B, still one readable function per command (was 842) Every g_* update placement works around a GCC 16.1 wrong-code bug (stores into global register variables deleted when only callees read them — repro and rules in libavr dev/lessons.md). Also fixes two latent hardware bugs all earlier tiers carried, masked by simavr's zeroed register file: the crt-less entries never established __zero_reg__ = 0, and the direction latch was read before written — power-on registers are undefined. All tiers full oracle feature parity, protocol tests green in both libavr modes, .text byte-identical across modes. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JYufebsiWvGkAJ2fLAB1gT	2026-07-20 01:00:27 +02:00
BlackMark	c351bee257	tsb: beat the first-pass size floors (tricks 666, pure 842) tricks 778->666: always_inline every single-call handler into the [[noreturn]] reset entry (which pays no prologue, so their push/pop of call-saved registers vanishes), walk the page pointer in Y (adiw, base recovered as g_addr-page) instead of recomputing Z=base+offset, bring the UART up in the two registers that are not already at their reset value, and seed the activation counter as __uint24. pure 896->842: TU-local internal linkage (proper hygiene, and it lets the compiler inline the one-call handlers), a byte-wide activation count, __uint24 timeout. Still one readable function per command. asm unchanged at 498: its C++-expressible parts are already C++; the core stays asm (the 666 B all-tricks tier is 168 B over — per-call ABI tax, not a feature). All three cross-mode byte-identical, protocol green. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UHeP42XU3wf6RfhyuxBTE5	2026-07-19 20:15:49 +02:00
BlackMark	34e7f1be34	tsb: drive each tier to its size floor asm 502->498 B (below the oracle's 500): the stack bring-up moves to plain C++, and a register is reserved for the config-page high byte instead of reloading it at each app-flash-boundary compare. tricks 808->778 B: shared erase/rww helpers plus the libavr half-duplex W1C fix. pure 950->896 B and no SRAM: streams rx->SPM/EEPROM instead of staging a 128 B page buffer. All three keep full oracle feature parity and stay byte-identical across modes; protocol tests (round-trip + password + emergency erase) green. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UHeP42XU3wf6RfhyuxBTE5	2026-07-19 18:47:38 +02:00
BlackMark	445e187722	tsb: document the three tiers at full parity in the build file Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UHeP42XU3wf6RfhyuxBTE5	2026-07-19 16:50:18 +02:00
BlackMark	250aba5cfb	tsb: protocol test covers the password gate and emergency erase Each scenario group now runs on its own freshly-reset device: the round-trip on a blank config page, plus a password-config device that must be sent the password after the knock to activate, and an emergency-erase device where a 0-byte + two confirms wipes flash, EEPROM and the config page (verified by reading all three back as 0xff). All three tiers pass every group. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UHeP42XU3wf6RfhyuxBTE5	2026-07-19 16:49:20 +02:00
BlackMark	5c900720e3	tsb: pure and tricks tiers reach full oracle feature parity Both tiers gain the features the asm tier already carries — one-wire half-duplex (via libavr's new .half_duplex), the config-page activation timeout, and emergency erase (password \0 + double-confirm wipes flash, EEPROM and the config page) — on top of the watchdog bail, password gate and config/flash/EEPROM read-write they already had. pure stays idiomatic (flash_table info block, one function per command) at 950 B; tricks keeps its compiler trickery (call-saved global-register page walk, unified runtime-flag paths pinned noinline/noclone, streaming stores, arithmetic command decode) at 808 B. Both byte-identical across generated and reflect modes; the size gradient across the three tiers is now 502 / 808 / 950 B. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UHeP42XU3wf6RfhyuxBTE5	2026-07-19 16:47:21 +02:00
BlackMark	7d6ef959b2	tsb: asm tier reaches full oracle feature parity at 502 B Rewrite the inline-asm tier so it matches the hand-written fixed-baud oracle's feature set inside the 512 B boot section: watchdog-reset bail, one-wire half-duplex (RXEN/TXEN toggled per direction, TX turnaround guard), config-page activation timeout, the password gate (wrong byte hangs draining the UART), emergency erase (password \0 + double-confirm wipes flash, EEPROM and the config page), and config/flash/EEPROM read-write. Every geometry, baud and info-block constant comes from libavr consteval; only the dense control flow is hand-written. 502 B, byte-identical across generated and reflect modes. Test harness: seed the config page from TSB_CONFIG so the password and emergency-erase paths are exercisable, and clear simavr's AVR_UART_FLAG_POLL_ SLEEP — a host-CPU-saving usleep(1)-per-idle-poll hack that models no hardware and paces a one-wire loader (which releases TX between bytes) in real time, distorting protocol timing. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UHeP42XU3wf6RfhyuxBTE5	2026-07-19 16:23:16 +02:00
BlackMark	11ffbce2e2	tsb: vendor the fixed-baud assembly oracle as the size/feature bar The Seed Robotics native-UART fixed-baud TinySafeBoot (GPLv3), reference only — not built. Assembles to 500 B with the full feature set, proving ≤512 B and full feature parity are simultaneously reachable. Also drops the stale empty stk500v2/ leftover. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01UHeP42XU3wf6RfhyuxBTE5	2026-07-19 15:29:58 +02:00
BlackMark	f32a27ff15	tsb: use the named register surface Direct register access now reads through the named surface (hw::mcusr::wdrf.test(), hw::ucsr0b::write(...)) instead of the string form, matching how libavr itself is written. Zero-overhead: pure 740 B, tricks 658 B, asm 508 B unchanged, all byte-identical across modes, protocol green. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-07-19 14:55:01 +02:00
BlackMark	57d94cf631	tsb: refactor the pure tier onto libavr sugar The showcase tier now leans on the helpers it fed back instead of reaching under them: the info block is an avr::flash_table (no raw [[gnu::progmem]]), a page is filled with spm::fill(addr, span) (no hand-packed lo\|hi<<8 loop), and the WDT-reset bail reads field<"MCUSR","WDRF">::test() (no read() & {}(1).value). Zero-overhead throughout: .text stays 740 B, byte-identical across generated and reflect modes, protocol test green. The info block streams through the existing address-based send_flash rather than a range-for over the flash_table — the range-for is a distinct loop that cannot share the loader's one flash streamer, so it would add 14 B for no functional gain. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-07-19 13:33:53 +02:00
BlackMark	8203a24f33	tsb: slim the port branch to the libavr reimplementation main carried the whole pre-libavr tree beside the port: the other-bootloader directories (blink, stk500v2), the Atmel Studio solution/project, and — dead in the tsb dir itself — four submodule links to the superseded io/flash/uart/type libraries the libavr sources never include. None are build inputs; CMake drives the three variants through FetchContent. master keeps the full legacy tree untouched. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-07-19 13:12:56 +02:00
BlackMark	2906da3272	tsb: drop the local -O3 strip, now handled by the libavr toolchain The -O3 leak is fixed upstream (cmake/release-os.cmake via CMAKE_PROJECT_INCLUDE), so the port no longer needs its own string(REPLACE); a Release build is -Os through the toolchain file. Verified: all three variants build at their sizes (508/658/740) and pass the size + protocol ctest. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-07-19 10:52:13 +02:00
BlackMark	64c1e484b5	tsb: reimplement TinySafeBoot on libavr in three size tiers The native-UART fixed-baud TinySafeBoot protocol, ported onto libavr as a crt-free boot-section loader, in three variants that trade clarity for size: tsb_pure 740 B idiomatic C++: SRAM page buffer, separate flash/EEPROM leaves, shared framing; the polled `unused` guard posture. tsb_tricks 658 B unified runtime-flag paths (noinline/noclone), call-saved global-register page walk — attributes only, no asm. tsb_asm 508 B streaming store + hand-rolled UART/SPM/EEPROM/erase loops; fits the 512 B boot section (BOOTSZ=11). Trims the optional password gate and WDT-reset bail — unreachable in C++ with both (hand-asm is ~15 % denser). Tiers 1-2 keep them and live in the 1 KB section they fit. All three are .text byte-identical across libavr's generated and reflect modes. The CMake build strips the leaked -O3 (a Release build is silently -O3, not the -Os this loader is measured against) and gates each variant's size against its section. A simavr harness (test/device.c + test/tsbtest.py) drives the real wire protocol over a pty and flashes the device; the size and protocol tests run in ctest. Verified byte-for-byte against the reference tsbloader_adv (C#/mono): activate, read info, flash write + verify. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-07-19 05:00:51 +02:00