docs: correct the size figures for the configured variants

The headline numbers described the stock deployments but claimed "every configured variant of them", which the matrix contradicts: choosing the software UART where the chip has a USART costs 8-46 B, so the megas reach 460-462 rather than 452, and the 1284s' software-serial build is 546 B — inside their 1 KiB boot sector, but not inside 512. Also names the actual tightest chip. The 1284 looks like it at 506, but it deploys in 1 KiB with 478 B spare; against its own budget the ATmega328P has the least room, 50 B. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
pureboot: no SPM buffer discard, the host repairs instead
2026-07-22 17:08:24 +02:00 · 2026-07-22 16:29:27 +02:00 · 2026-07-21 23:42:57 +02:00 · 2026-07-21 23:42:57 +02:00 · 2026-07-21 23:42:57 +02:00 · 2026-07-21 21:55:15 +02:00
20 changed files with 940 additions and 1831 deletions
--- a/.gitmodules
+++ b/.gitmodules
@@ -0,0 +1,3 @@
 [submodule "libavr"]
 	path = libavr
 	url = ../libavr.git
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -8,6 +8,9 @@ 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()
@@ -150,10 +153,7 @@ if(PROJECT_IS_TOP_LEVEL)
 	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> ${PUREBOOT_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)
@@ -234,13 +234,12 @@ if(PROJECT_IS_TOP_LEVEL)
 	endif()
 	# The size matrix: every configuration axis that could move the image
-	# size — the serial backend (different code), the USART instance
+	# size — the serial backend (different code), the clock and its ladder
-	# (different registers), the clock (different constants), and the baud
+	# baud (different constants and divisor shapes), the USART instance
-	# through the shapes its bit timing takes — each combination must still
+	# (different register class) — each combination must still fit the
-	# fit the chip's slot budget. Pins are size-neutral (port and bit are
+	# chip's slot budget. Pins are size-neutral (port and bit are immediate
-	# immediate operands) and the timeout is a constant, so neither adds an
+	# operands) and the timeout is a constant, so neither adds an axis. The
-	# axis. The stock build is one point of this matrix and already has its
+	# stock build is one point of this matrix and already has its test.
 	# test.
 	function(pureboot_size_variant name)
 		pureboot_add_loader(${name} ${ARGN})
 		add_test(NAME ${name}.size
@@ -248,90 +247,23 @@ if(PROJECT_IS_TOP_LEVEL)
 		                 -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()
 	foreach(_matrix_hz IN LISTS _matrix_clocks)
 		math(EXPR _matrix_khz "${_matrix_hz} / 1000")
 		if(PUREBOOT_HAS_USART OR NOT _matrix_hz EQUAL _pb_stock_hz)
 			pureboot_size_variant(pureboot_sw_${_matrix_khz}k CLOCK ${_matrix_hz} SERIAL software)
 		endif()
 		if(PUREBOOT_HAS_USART AND NOT _matrix_hz EQUAL _pb_stock_hz)
 			pureboot_size_variant(pureboot_hw_${_matrix_khz}k CLOCK ${_matrix_hz} SERIAL hardware)
 		endif()
 	endforeach()
 	if(PUREBOOT_HAS_USART1)
 		pureboot_size_variant(pureboot_usart1 USART 1)
 	endif()
@@ -386,28 +318,4 @@ if(PROJECT_IS_TOP_LEVEL)
 		                 ${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
@@ -6,7 +6,7 @@
   "hidden": true,
   "generator": "Ninja",
   "binaryDir": "${sourceDir}/build/${presetName}",
-   "toolchainFile": "$env{LIBAVR_ROOT}/cmake/avr-toolchain.cmake",
+   "toolchainFile": "${sourceDir}/libavr/cmake/avr-toolchain.cmake",
   "cacheVariables": {
    "CMAKE_BUILD_TYPE": "Release",
    "CMAKE_EXPORT_COMPILE_COMMANDS": "ON",
--- a/1
+++ b/1
--- a/pureboot/CMakeLists.txt
+++ b/pureboot/CMakeLists.txt
@@ -1,16 +1,27 @@
-# pureboot as a consumable CMake unit: the per-chip geometry, the default baud
+# pureboot as a consumable CMake unit: the per-chip geometry, the default
-# ladder, and pureboot_add_loader() — the one way a loader target is created.
+# baud ladder, and pureboot_add_loader() — the one way a loader target is
-# A downstream project brings its usual libavr setup (the `libavr` target and
+# created, both by this port's own build and by a downstream project. A
 # downstream project brings its usual libavr setup (the `libavr` target and
 # the LIBAVR_MCU toolchain preset), adds this directory, and states its
-# deployment; every argument is optional (README.md):
+# deployment:
 #
 #   add_subdirectory(bootloader/pureboot)
 #   pureboot_add_loader(myboot CLOCK 1000000 SERIAL software TX pb1 RX pb5)
 #
 # Every argument is optional — CLOCK defaults to the family assumption
 # below, BAUD to the fastest standard rate the clock reaches within 2.5 %
 # (the ladder), SERIAL to the chip's hardware USART where it has one
 # (`hardware`/`software` force a backend, USART 1 picks the second
 # instance), RX/TX to pb0/pb1 for the software UART, TIMEOUT to 8 s.
 # Infeasible picks fail the build by name: libavr's baud-error and
 # software-UART cycle-floor static asserts re-check whatever is passed.
-# Per-family geometry, deployment defaults, and the linker wrap the PC modulo
+# Per-family geometry: flash/page/EEPROM sizes and the linker wrap the PC
-# needs. The slot is 512 bytes on every chip. The USART flags mirror the
+# modulo needs, the loader slot (each chip's smallest boot sector — 1 KiB on
-# hardware inventory the loader's own static asserts check — the plain 644 is
+# the word-addressed 1284s), and the deployment defaults (crystal assumption
-# the x4 family's one single-USART die (Atmel-2593).
+# on the megas, calibrated RC on the tinies). The USART flags mirror the
 # hardware inventory the loader's own static asserts check (the plain 644 is
 # the x4 family's one single-USART die, Atmel-2593).
 set(_pb_has_usart 1)
 set(_pb_has_usart1 0)
 if(LIBAVR_MCU MATCHES "^attiny13a?$")
@@ -80,9 +91,10 @@ elseif(LIBAVR_MCU MATCHES "^atmega324(a|p|pa)$")
 	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
+	# 64 KiB is exactly the 16-bit byte space: plain LPM reaches everything,
-	# everything and the wire stays byte-addressed. The plain 644 is the
+	# and the smallest boot section (1 KiB) holds the loader and its staging
-	# family's one single-USART die.
+	# slot together (see README.md). The plain 644 is the family's one
 	# single-USART die.
 	set(_pb_flash 65536)
 	set(_pb_wrap -Wl,--pmem-wrap-around=64k)
 	set(_pb_page 256)
@@ -92,25 +104,33 @@ elseif(LIBAVR_MCU MATCHES "^atmega644(a|p|pa)?$")
 		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
+	# 128 KiB: wire flash addresses are word addresses, reads go through
-	# modulo wrap exceeds what --pmem-wrap-around models.
+	# ELPM, and the PC's modulo wrap exceeds what --pmem-wrap-around models.
 	# The slot is 1 KiB — this chip's own smallest boot sector; the far
 	# machinery cannot fit 512 B (see README.md).
 	set(_pb_flash 131072)
 	set(_pb_wrap "")
 	set(_pb_page 256)
 	set(_pb_hz 16000000)
 	set(_pb_eeprom 4096)
 	set(_pb_slot 1024)
 	set(_pb_limit 1024)
 	set(_pb_has_usart1 1)
 else()
 	message(FATAL_ERROR "pureboot: no geometry for ${LIBAVR_MCU}")
 endif()
-set(_pb_slot 512)
+if(NOT DEFINED _pb_slot)
 	set(_pb_slot 512)
 endif()
 math(EXPR _pb_base "${_pb_flash} - ${_pb_slot}")
 math(EXPR _pb_base_hex "${_pb_base}" OUTPUT_FORMAT HEXADECIMAL)
 # Patched-vector chips hand over through the trampoline word below the slot,
 # which is also the slot's own last word — their budget is slot − 2.
 if(LIBAVR_MCU MATCHES "^atmega" AND NOT LIBAVR_MCU MATCHES "^atmega48")
 	set(_pb_app 0)
-	set(_pb_limit ${_pb_slot})
+	if(NOT DEFINED _pb_limit)
 		set(_pb_limit ${_pb_slot})
 	endif()
 else()
 	math(EXPR _pb_app "${_pb_base} - 2")
 	math(EXPR _pb_limit "${_pb_slot} - 2")
@@ -146,67 +166,48 @@ 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.
+# The fastest standard rate the clock reaches within 2.5 % — the same
-set_property(GLOBAL PROPERTY PUREBOOT_BAUD_LADDER 115200 57600 38400 19200 9600)
+# best-of-U2X-and-plain divisor search libavr's solve_baud runs, so a
-
+# default never trips the compile-time error it is checked against. A
-# Whether <baud> is reachable from <clock> within 2.5 %, by the same
+# software build additionally requires the polled receiver's 100-cycles-a-bit
-# best-of-U2X-and-plain divisor search libavr's solve_baud runs, so a build
+# floor (its own static assert): at low clocks the U2X divisor still reaches
-# never trips the compile-time error it is checked against. A software build
+# rates the bit-banged sampler cannot, so the backend gates the ladder.
-# also needs the polled receiver's 100-cycles-a-bit floor: at low clocks the
+function(pureboot_default_baud clock software outvar)
-# U2X divisor reaches rates the bit-banged sampler cannot.
+	foreach(baud 115200 57600 38400 19200 9600)
-function(pureboot_baud_feasible clock baud software outvar)
+		math(EXPR _cycles "${clock} / ${baud}")
-	set(${outvar} 0 PARENT_SCOPE)
+		if(software AND _cycles LESS 100)
 	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})")
+		foreach(divisor 8 16)
-		math(EXPR _delta "${_actual} - ${baud}")
+			math(EXPR _step "${divisor} * ${baud}")
-		if(_delta LESS 0)
+			math(EXPR _n "(${clock} + ${_step} / 2) / ${_step}")
-			math(EXPR _delta "-(${_delta})")
+			if(_n LESS 1 OR _n GREATER 4096)
-		endif()
+				continue()
-		math(EXPR _error_bp "${_delta} * 10000 / ${baud}")
+			endif()
-		if(_error_bp LESS_EQUAL 250)
+			math(EXPR _actual "${clock} / (${divisor} * ${_n})")
-			set(${outvar} 1 PARENT_SCOPE)
+			math(EXPR _delta "${_actual} - ${baud}")
-			return()
+			if(_delta LESS 0)
-		endif()
+				math(EXPR _delta "-(${_delta})")
 			endif()
 			math(EXPR _error_bp "${_delta} * 10000 / ${baud}")
 			if(_error_bp LESS_EQUAL 250)
 				set(${outvar} ${baud} PARENT_SCOPE)
 				return()
 			endif()
 		endforeach()
 	endforeach()
-endfunction()
+	message(FATAL_ERROR "pureboot: no standard baud rate fits a ${clock} Hz clock within 2.5 %")
 # 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>]
+#                     [SERIAL auto|hardware|software] [USART <n>]
 #                     [RX <pin>] [TX <pin>] [TIMEOUT <s>])
 #
-# The loader target plus its flashable images (<name>.hex for a programmer,
+# Creates the loader target plus its flashable images (<name>.hex for a
-# <name>.bin for --update-loader). The resolved deployment is stamped on the
+# programmer, <name>.bin for --update-loader) and stamps the resolved
-# target as PUREBOOT_HZ / PUREBOOT_BAUD / PUREBOOT_LINK (the link spelled
+# deployment on the target: the PUREBOOT_HZ, PUREBOOT_BAUD and PUREBOOT_LINK
-# usart0, usart1 or sw:<RX>,<TX>) — what a test harness speaks to it with.
+# properties (the link as usart0/usart1/sw:<RX>,<TX> — what a test harness
-#
+# needs to speak to the build).
 # 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)
@@ -228,8 +229,8 @@ function(pureboot_add_loader name)
 	if(NOT PB_SERIAL)
 		set(PB_SERIAL auto)
 	endif()
-	if(DEFINED PB_USART AND NOT PB_SERIAL MATCHES "^(auto|hardware)$")
+	if(DEFINED PB_USART AND PB_SERIAL STREQUAL "software")
-		message(FATAL_ERROR "pureboot_add_loader(${name}): USART ${PB_USART} contradicts SERIAL ${PB_SERIAL}")
+		message(FATAL_ERROR "pureboot_add_loader(${name}): USART ${PB_USART} contradicts SERIAL software")
 	endif()
 	if(DEFINED PB_USART)
 		set(PB_SERIAL hardware)
@@ -258,7 +259,7 @@ function(pureboot_add_loader name)
 				set(PB_SERIAL software)
 			endif()
 		endif()
-		if(PB_SERIAL MATCHES "^(software|autobaud)$")
+		if(PB_SERIAL STREQUAL "software")
 			if(NOT PB_RX)
 				set(PB_RX pb0)
 			endif()
@@ -270,12 +271,9 @@ function(pureboot_add_loader name)
 					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_SOFT_SERIAL PUREBOOT_RX=${PB_RX} PUREBOOT_TX=${PB_TX})
-				set(_serial_defines PUREBOOT_AUTOBAUD PUREBOOT_RX=${PB_RX} PUREBOOT_TX=${PB_TX})
+			# The link spec a test harness drives a GPIO bridge with: sw:<RX>,<TX>
-			else()
+			# as the port letter and bit, the loader's own pin naming upcased.
 				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)
@@ -290,34 +288,27 @@ function(pureboot_add_loader name)
 		endif()
 	endif()
-	if(PB_SERIAL STREQUAL "autobaud")
+	set(_defines PUREBOOT_CLOCK_HZ=${PB_CLOCK} PUREBOOT_BAUD=${PB_BAUD} PUREBOOT_TIMEOUT=${PB_TIMEOUT}
-		# No clock and no baud reach the image; the window is a poll budget.
+	    ${_serial_defines})
 		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
+	# Codegen shaping for the loader TU only, worth ~40 B on every chip and
-	# byte-stream loops' counters into end-pointer forms that cost registers
+	# what carries the far-flash 1284 build under 512. At -Os GCC otherwise
-	# (-fno-ivopts, -fno-split-wide-types), leaves register pressure on the
+	# rewrites the byte-stream loops' counters into end-pointer forms that
-	# table with the default allocator (-fira-algorithm=priority), and keeps
+	# cost registers (-fno-ivopts, -fno-split-wide-types), leaves register
-	# expression temporaries in registers (-fno-tree-ter) — but every loop body
+	# pressure on the table with the default allocator
-	# here contains a call, so a register held across it costs more than the
+	# (-fira-algorithm=priority), and spends bytes on rewrites a
-	# load-immediate it saves. The set is fitted to the loader's body and has to
+	# straight-line loader gains nothing from.
 	# 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)
+	    -fno-ivopts -fira-algorithm=priority -fno-expensive-optimizations -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
+	# The ELF is a container (symbols, section headers), never flashed; the
-	# slot's bare bytes) for --update-loader.
+	# flashable forms sit beside it: .hex for a programmer, .bin (the slot's
 	# bare bytes) for the host tool's raw path and --update-loader.
 	add_custom_command(TARGET ${name} POST_BUILD
 	                   COMMAND ${CMAKE_OBJCOPY} -O ihex -R .eeprom
 	                           $<TARGET_FILE:${name}> $<TARGET_FILE:${name}>.hex
@@ -326,4 +317,3 @@ function(pureboot_add_loader name)
 	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,72 +2,52 @@
 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 and compiler flags allowed), built for **every chip libavr
-targets — all 37**. The device speaks primitives; every composite — verify,
+targets — all 37 — in 512 bytes each**: 434 B on the tiny13s, 438–442 B on
-erase, reset-vector surgery, updating the loader itself — lives in the host
+the tiny25/45/85, 412–452 B across the megas, and 506 B on the
-tool (`pureboot.py`).
+ATmega1284/1284P, whose far-flash machinery (ELPM reads, RAMPZ page commands,
 word-addressed wire) is the heaviest. Those are the stock deployments;
 choosing the software UART where the chip has a USART costs 8–46 B more (a
 bit-bang against a peripheral), which every chip still absorbs inside its
 slot — on the 1284s that means their 1 KiB boot sector, where the
 software-serial image lands at 546 B. Bringing the 1284's default build
 under 512 at all is what the loop-placement attributes on the byte streamers
 (`pureboot.cpp`) and the codegen flags on the loader TU (`CMakeLists.txt`)
 are for; measured against each chip's own budget the tightest is the
 ATmega328P, 50 B spare. Clock, baud, serial backend and
 pins are per-build configuration (below); the size matrix in the test suite
 holds every combination inside its slot. The device speaks primitives; every
 composite — verify, erase, reset-vector surgery, updating the loader itself —
 lives in the host tool (`pureboot.py`).
 The 1284s still *deploy* in a 1 KiB slot, their smallest boot sector being
 512 words; at 506 B the image would also fit the 644's
 two-512-byte-slots-per-boot-sector geometry.
 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 slot the
-is *running* in (from the runtime return address), nothing else is
+code is *running* in (from the runtime return address), the info block is
-flash-resident to address at all, and the application jump is an indirect call
+addressed from that same anchor, and the application jump is an indirect
-to an absolute entry. The identical binary therefore runs from any slot with
+call to an absolute entry. The identical binary therefore runs from any
-every command intact, which makes pureboot **its own staging loader**: the host
+slot with every command intact — which makes pureboot **its own staging
-installs the same binary one slot below the resident, jumps into it, and lets
+loader**: the host installs the same binary one slot below the resident,
-it rewrite the resident. The lint holds it to that literally — the image must
+jumps into it, and lets it rewrite the resident. The slot is 512 bytes
-come out byte-identical linked at a different base.
+(1 KiB on the word-addressed large chips, matching their boot-sector
-
+minimum); on the tinies the budget is 510, not 512: a slot's last word
-## Chips
+belongs to the host-managed trampoline (below).
 Sizes are the default configuration: the hardware USART0 at 115200 8N1 on a
 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
 per build — see *Configuration*. The autobaud column is the clock-free build,
 which is the largest the space produces and the tightest fit in the matrix;
 it carries the calibration machinery and no clock at all.
 | Chip | Flash | Loader at | Link | Stock | Autobaud |
 |---|---|---|---|---|---|
 | 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
+Every deployment axis is a build parameter, resolved by the CMake function
-`pureboot/CMakeLists.txt`) — the one way a loader target is created, by this
+`pureboot_add_loader()` (in `pureboot/CMakeLists.txt`) — the one way a
-repo's build and by a downstream project alike:
+loader target is created, by this repo's own build and by a downstream
 project alike:
 | Argument | Meaning | Default |
 |---|---|---|
 | `CLOCK <hz>` | the clock the board runs | 16 MHz megas, 8 MHz t25/45/85, 9.6 MHz t13s |
 | `BAUD <bd>` | the wire rate | the ladder below |
-| `SERIAL auto\|hardware\|software\|autobaud` | the link backend | `auto`: the hardware USART where the chip has one |
+| `SERIAL auto\|hardware\|software` | the link backend | `auto`: the hardware USART where the chip has one |
 | `USART <n>` | the USART instance (x4 megas carry two) | 0 |
 | `RX <pin>`, `TX <pin>` | software-UART pins | `pb0`, `pb1` |
 | `TIMEOUT <s>` | the activation window | 8 |
@@ -75,25 +55,15 @@ repo's build and by a downstream project alike:
 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
+receiver's 100-cycles-a-bit floor. 16 MHz lands 115200, 8 MHz 57600,
-re-checked in the compile: an infeasible combination, or a USART the chip does
+1 MHz 9600. Whatever is picked or overridden is re-checked in the compile:
-not have, fails with a named static assert.
+an infeasible clock/baud/backend 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
+A downstream project brings its usual libavr setup (the `libavr` target,
-at run time, so `CLOCK` and `BAUD` are not build parameters there and one
+the chip via the `LIBAVR_MCU` toolchain preset), consumes this directory,
-binary per chip serves every clock and every rate. It is for the deployments
+and states its deployment — for example an ATmega328P on its shipped
-whose clock is not known at build time and does not hold still — the internal
+1 MHz fuses with the software UART on hand-picked pins:
 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)
@@ -104,187 +74,149 @@ 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
+`myboot.bin` (the self-update image), prints the size, and stamps the
-deployment on the target as the `PUREBOOT_HZ`, `PUREBOOT_BAUD` and
+resolved deployment on the target as the `PUREBOOT_HZ`, `PUREBOOT_BAUD`
-`PUREBOOT_LINK` properties — what a flashing script or test harness needs to
+and `PUREBOOT_LINK` properties — what a flashing script or test harness
-speak to the build. This exact deployment runs the full protocol suite in CI
+needs to speak to the build. This exact example deployment runs the full
-(`pureboot.custom`).
+protocol suite in CI (`pureboot.custom`).
 ## Link
 The stock builds assume the family's natural deployment; any axis moves
 per build (above).
 | Chip | Serial | Baud | Clock assumed |
 |---|---|---|---|
 | every ATmega | the hardware USART (USART0), RXD/TXD per pinout | 115200 8N1 | 16 MHz crystal |
 | ATtiny25/45/85 | software UART, RX = PB0, TX = PB1 | 57600 8N1 | 8 MHz internal RC |
 | ATtiny13/13A | software UART, RX = PB0, TX = PB1 | 57600 8N1 | 9.6 MHz internal RC |
 The software-UART RX pin has its pull-up enabled; TX idles high. All
 multi-byte quantities on the wire are little-endian.
 ## Activation
-Reset enters the loader (BOOTRST on the boot-sectioned megas, the patched
+Reset enters the loader (BOOTRST on the boot-sectioned megas; the patched
-reset vector elsewhere) — except a watchdog reset, which hands straight to the
+reset vector on the tinies and the boot-section-less m48s) — except a
-application with no activation window, since the application owns its watchdog.
+watchdog reset, which hands straight to the application (the application
-This is deliberate: it lets an application reboot itself instantly rather than
+owns its watchdog; it must clear WDRF itself, which also releases the
-sit through the window. The application must clear WDRF itself (libavr's
+WDRF-forced WDE).
 `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
-can read a byte at all: the host sends the **calibration byte 0xC0** — a start
+value via `pureboot_add_loader(... TIMEOUT <s>)` (the stock target keeps
-bit plus six zero data bits form one low pulse of seven bit-times — and the
+the `PUREBOOT_TIMEOUT` cache variable) — so the whole EEPROM belongs to
-loader times that pulse into its bit period. A single `p` then activates; the
+the application; pureboot never uses it for its own state. Re-timing a
-pulse has already proven a host is present, which the two-byte knock exists to
+deployed loader is a self-update with a re-timed build (below).
 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
+On chips whose flash exceeds 64 KiB (the 1284s — info-block flag bit 1) the
-the command's selector byte, so no command has to speak word addresses. `J` is
+`R`/`W` flash addresses are **word** addresses; everywhere else they are byte
-the exception: it takes a word address, because that is what the hardware's own
+addresses (the 644s' 64 KiB is exactly the 16-bit byte space and stays
-jump takes. EEPROM and data-space addresses and all counts are bytes.
+byte-addressed). EEPROM addresses are always bytes, counts always 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.
-| Space | | |
+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
-| 0 | flash | read-only here; it is written through `W` and the SPM space |
+write-once per word until cleared, and two things leave words in it: a
-| 1 | EEPROM | |
+refused page (drained, never programmed) and — where SPM runs from anywhere,
-| 2 | data | SRAM — and with it the register file and every I/O register, which share the data address space on AVR |
+the tinies and the m48s — an application that self-programmed before
-| 3 | fuse and lock | index 0..3 in the hardware's own Z order: low, lock, extended, high |
+entering. The next `W` takes those stale words, and clears them: a page write
-| 4 | SPM | write-only: the byte goes to SPMCSR and fires the instruction at the address |
+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); a host that
 programs without reading back cannot trust the first `W` after either event.
-The data space is worth more than it looks. pureboot keeps **zero static RAM**
+`w` is host-paced: send the next byte only after the previous
-and pushes no register, so at loader entry an application's SRAM is still
+byte's `+`. `F` returns the bytes in the hardware's Z order; on a chip
-whatever the application left there, bar the handful of bytes of return-address
+without an extended fuse byte (the ATtiny13A) that slot carries no meaning.
-stack — which makes `G` over space 2 a post-mortem of a running application,
+Fuse *writing* does not exist: SPM reaches flash (and, on the mega, lock
-not just a poke hole. The same address space carries the register file and the
+bits) only — fuse bytes are external-programming territory by hardware.
 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
+`J` is the one control-transfer primitive: the host uses it to run the
-space for the erase, another for the write, and on a boot-sectioned chip a
+application (word 0 on the mega, the trampoline word on the tinies — both
-third to re-enable the RWW section — `0x03`, `0x05` and `0x11`, the SPMCSR
+known from the info block) and to move between loader copies during a
-encodings every part pureboot targets shares. The loader carries no page-commit
+self-update. A jump to a loader slot's base re-enters that copy's own
-logic of its own, and the same primitive reaches every other SPM operation,
+startup; it must then be knocked afresh.
 lock bits included.
-The SPM store and the SPM instruction must issue within four cycles of each
+The info block (`b`):
 other (§26.2), which no host can hit across a serial link — so this one
 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
+| Offset | Content |
-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.
+| 0–2 | `'P'`, `'B'`, protocol version (1) |
 | 3–5 | device signature |
 | 6 | SPM page size in bytes (0 means 256) |
 | 7–8 | loader base — application flash ends here (a word address when bit 1 is set) |
 | 9–10 | EEPROM size |
 | 11 | bit 0: host must patch the reset vector (no hardware boot section); bit 1: flash wire addresses are word addresses |
-The loader never clears the SPM buffer before a fill, so **one `W` may program
+Composites are the host's job: verify = read back and compare, erase =
-the wrong bytes, and the host is what fixes it**. The buffer is write-once per
+write `0xff` (per page for flash, per byte for EEPROM).
 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
-tests and objcopy, never flashed. The **.hex is the programmer artifact**: it
+tests and objcopy — never flashed. The **.hex is the programmer artifact**:
-carries its own addresses and lands the loader in its top slot, touching
+it carries its own addresses and lands the loader in its top slot,
-nothing else. The **.bin is the self-update image** — the slot's bare bytes.
+touching nothing else. The **.bin is the self-update image** — the slot's
 bare bytes with no addressing, which a programmer would put at address 0.
 On a boot-sectioned mega a copy at 0 is dead weight (SPM only executes
 from the boot section, so it cannot even heal itself — reflash the .hex);
 on the patched-vector chips it *runs* (the image is position-independent
 and reset enters word 0), reports its canonical geometry, and the ordinary
 `--update-loader` flow re-homes a build into the top slot from any
 position — the staging install and the word-0 redirect execute from
 copies outside page 0's slot, and a copy sitting in the staging slot
 itself is recognized as the installed staging copy and left in place (it
 streams the new resident like any staged copy, so an older build installs
 a newer one). `pureboot.rehome` is the acceptance test for both
 positions. Flashing the application afterwards overwrites the stale copy,
 vector surgery included.
-**Boot-sectioned megas**: program the loader at `flash − 512` with an external
+**Boot-sectioned megas**: program the loader at `flash − slot` with an
-programmer. Every such mega has a BOOTSZ step whose boot section is exactly
+external programmer. Every such mega has a BOOTSZ step whose boot section
-the 512-byte slot — the second-smallest step on the 8 KiB and 16 KiB chips,
+is exactly the loader slot — 512 B, the second-smallest step on the 8 KiB
-the smallest on the 32 KiB ones — so the ATmega328P profiles below apply to
+and 16 KiB chips (m8, m88, m16, m168, m164), the smallest on the 32 KiB
-every one of them with its own addresses; the per-chip BOOTSZ ladders live in
+ones (m32, m328, m324); on the 1284s that step is the smallest, 512 words,
-the host tool (`BOOT_FUSE`).
+which is why their slot is 1 KiB — so the ATmega328P profiles below apply
 to every one of them with its own addresses and slot size; the per-chip
 BOOTSZ ladders live in the host tool (`BOOT_FUSE`). The 1284s' numbers:
 standalone = BOOTSZ 512 words (reset at the loader base 0x1fc00);
 self-update = 1024 words, covering both 1 KiB slots, the loader-first
 reset landing at 0x1f800 — the staging slot, walked across when erased.
-The **644s and 1284s** are the geometry's sweet spot: their smallest boot
+The **644s** are the geometry's sweet spot: their smallest boot section
-section (512 words = 1 KiB) is exactly *two* slots, so the resident and its
+(512 words = 1 KiB) is exactly *two* 512-byte slots, so the resident and
-staging slot both live inside the minimum section. Self-update needs no fuse
+its staging slot both live inside the minimum section — self-update needs
-step up, and the standalone profile does not exist — reset lands one erased
+no fuse step up, and the standalone profile does not exist (reset lands at
-slot below the loader (0xfc00 / 0x1fc00) and walks up into it.
+0xfc00, one erased slot below the loader: the loader-first walk built in).
 ATmega328P profiles (addresses for its 32 KiB):
@@ -294,160 +226,154 @@ 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'
+**Patched-vector chips — the tinies and the m48s** (no boot section; the
-SPM runs from the entire flash, Atmel-8271 §26): program the loader at
+m48s' SPM runs from the entire flash, Atmel-8271 §26): program the loader
-`flash − 512`; erased flash below it walks up into the loader, so a virgin
+at `flash − 512`; erased flash below it walks up into the loader, so a
-chip activates. Flashing an application then takes reset-vector surgery: word
+virgin chip activates. When flashing an application the host performs
-0 becomes an `rjmp` to the loader base, and the application's own entry is
+reset-vector surgery: word 0 is rewritten to `rjmp` to the loader base, and
-re-encoded as a trampoline `rjmp` in the word just below the loader
+the application's own entry is re-encoded as a trampoline `rjmp` in the
-(`base − 2`, where the hand-over jumps). Every other vector stays the
+word just below the loader (`base − 2`, where the hand-over jumps). Every
-application's. The patched page 0 and the trampoline page are written *first*
+other vector stays the application's. The patched page 0 and the trampoline
-and an erase runs top-down, so from the first write on an interruption still
+page are written *first*, so from the first write on an interrupted flash
-resets into the loader.
+still resets into the loader; an erase runs top-down for the same reason.
-
+The m48s speak this profile over their hardware USART — no fuse preflight,
-A .bin programmed at address 0 by mistake is dead weight on a boot-sectioned
+BOOTRST does not exist there.
 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
-bytes as a raw binary, or the Intel HEX the build emits beside it.
+bytes as a raw binary, or the Intel HEX the build emits beside it, which
 links the loader at its base inside an otherwise blank flash image:
-The preflight refuses an image built for another chip: the stamp every pureboot
+The preflight refuses an image built for another chip: the info block
-binary carries must resolve to the device's own geometry, and the error names
+embedded in every pureboot binary (signature, page size, loader base,
-both. Die revisions share their base signature and geometry, so their images
+EEPROM size, flags) must match the device's own, and the error names both.
-are interchangeable — as the silicon is.
+Die revisions share their base signature and geometry, so their images are
 interchangeable — as the silicon is. `loader_image()` also accepts a
 padded image (a raw .bin padded from 0, or a whole-flash read-back with
 the loader resident) and peels it to the slot content by the embedded base.
-1. The staging slot `[base−512, base)` is saved to a host-side state file (on
+1. The staging slot `[base−slot, base)` is saved to a host-side state file
-   the 1 KB tiny13s that is the whole application, vectors included).
+   (on the 1 KB tiny13s that is the whole application, vectors included).
-2. The resident installs the update image there. On the patched-vector chips
+2. The resident installs the identical update image there. On the
-   the host composes the slot's last word as a jump to the resident base, so
+   patched-vector chips the host composes the slot's last word — the same
-   even an abandoned staging copy times out into a loader. A loader already
+   address as the resident's trampoline — as a jump to the resident base,
-   sitting whole in the staging slot is left as the staging copy instead —
+   so even an abandoned staging copy times out into a loader, never into
-   rewriting it would only meet its own running-slot guard.
+   garbage. A loader already sitting whole in the staging slot (its info
-3. `J` enters the staging copy, which rewrites the resident slot. Where a
+   block in place, the slot unchanged since the update began) is left as
-   patched reset vector routes through the resident, the host first re-aims
+   the staging copy instead — rewriting it would only meet its own
-   word 0 at the staging copy, so a power loss mid-rewrite still resets into a
+   running-slot guard.
-   loader; on the tiny13s the staging slot carries the reset vector itself.
+3. `J` enters the staging copy, which rewrites the resident slot. On the
   patched-vector chips whose staging slot sits away from page 0 the host
   first re-aims word 0 at the staging copy, so a power loss mid-rewrite
   still resets into a loader; on the tiny13s the staging slot carries the
   reset vector itself.
 4. `J` enters the new resident, which restores the staging slot's saved
-   content, 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. A boot-sectioned mega needs its fuses for the
-from the device, or supplied with `--assume-fuses` where reading is impossible
+preflight (BOOTSZ gate, profile notes) — read from the device, or supplied
-(simulators).
+with `--assume-fuses` where reading is impossible (simulators); the
 patched-vector chips need none.
 ## Host tool
 `pureboot.py` — Python 3, standard library only. The port layer is the one
-platform-specific part: termios drives any tty on POSIX (a USB adapter as well
+platform-specific part: termios drives any tty on POSIX (a USB adapter as
-as a simavr pty), the Win32 serial API through `ctypes` drives a COM port on
+well as a simavr pty), the Win32 serial API through `ctypes` drives a COM
-Windows (`--port COM6`; the `\\.\` form for two-digit ports is supplied by the
+port on Windows (`--port COM6`; the `\\.\` form for two-digit ports is
-tool). Opening the port asserts DTR and RTS on both, so a board that wires DTR
+supplied by the tool). Opening the port asserts DTR and RTS on both, so a
-to reset gets its reset pulse and opens the activation window by itself.
+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`, and a flash page that reads back wrong is
-`--verify-flash` only reports. Images are raw binary, or Intel HEX by
+rewritten up to three times before the run stops — the loader leaves one
-extension. `--force` overrides the refusable safety checks — today, flashing
+recoverable way for a page to land wrong (see `W` above), and rewriting is
-application data into a mega's reset walk region.
+what clears it. `--verify-flash` only reports. Images are raw binary, or
 Intel HEX by extension. `--force` overrides the refusable safety checks (today: flashing
 application data into a mega's reset walk region).
-`--autobaud` opens with the calibration pulse instead of the plain knock, for a
+Readouts come one fact per line: `--info` prints the decoded info block
-loader built `SERIAL autobaud`; the rest of the session is identical, at
+field by field, `--fuses` each fuse byte on its own line — plus, on a
-whatever `--baud` the host chose.
+boot-sectioned mega, the decoded meaning (where the BOOTSZ section starts,
-
+what BOOTRST does to reset). Transfers that take wire time — programming,
-`--peek ADDR[:N]` and `--poke ADDR:HEX` reach the data space (pureboot 5) —
+reading, erasing, verifying, the update phases — draw a transient progress
-SRAM, and through the same address space the register file and every I/O
+bar on stderr when it is a tty; logs and pipes see only the summary lines.
-register. Reading an I/O register can have side effects (reading UDR clears its
+`-v`/`--verbose` adds the decisions as they happen: knock counts, the
-flags), which is the caller's business to know.
+programming plan (vector-surgery targets, skipped blank pages), update
-
+state handling and per-phase page counts.
 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
+`tools/check.sh` runs every chip's workflow (`tools/check.sh --full` adds
-builds of libavr's spot set; `tools/make_presets.py` regenerates the presets).
+the reflect-mode builds of libavr's spot set; `tools/make_presets.py`
-Per chip preset, `ctest` runs:
+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_*.size` — the size matrix: the serial backends × the clock
-  (1/8/16 MHz; the t13s' own RC menu), the USART1 instance across that same
+  ladder (1/8/16 MHz; the t13s' own RC menu), plus the USART1 build on the
-  ladder on the x4 chips, and `pureboot_sw_wide`, the slowest ladder rate at
+  x4 chips — every configuration axis that could move the image, each
-  the fastest clock — where a software UART's per-bit spin outgrows its
+  variant against the same slot budget (pins are immediate operands and the
-  one-register delay loop and takes the 16-bit one. That is the largest image
+  timeout is a constant: size-neutral);
-  the configuration space produces, and a shape the ladder default (always the
+- `pureboot.custom` (328P) — the configured-deployment acceptance test: the
-  *fastest* rate a clock reaches) never picks. Pins are immediate operands and
+  1 MHz software-serial TX=PB1/RX=PB5 build from the configuration example
-  the timeout is a constant: neither is an axis;
+  drives the full protocol suite through the runner's GPIO bridge, fixture
- `pureboot_autobaud.size` — the clock-free build, which has no clock or baud
+  application included;
-  axis of its own: one binary per chip has to serve every point the matrix
+- `pureboot.usart1` (644A) — the same protocol suite over the second
-  below sweeps;
+  hardware USART: instance selection is compile-checked everywhere, but
- `pbm_*.size` — with `PUREBOOT_FULL_MATRIX=1`, the exhaustive cross product
+  only a live session proves the loader polls the USART it claims;
-  replacing that compact matrix, on **every** chip: every plausible oscillator
+- `pureboot.pi` — the position-independence lint: no absolute `jmp`/`call`
-  (the internal ones, the CKDIV8 floor, the plain and the UART crystals) ×
+  in the image, the info block within its first 256 bytes;
-  every rate reachable from it × every backend, unreachable combinations
+- `pureboot.planner` — the host tool's pure logic: programming orders and
-  dropping out rather than aborting the configure. Thousands of points per
+  their recovery properties, the surgery, the staging composition, the
-  chip, and cheap enough to run rather than reason about;
+  boot-fuse decode, the update preflight's error/warning matrix over
- `pureboot.pi` — the position-independence lint: no absolute `jmp`/`call`, no
+  synthetic fuse bytes, and the repairing verify against a fake device — one
-  flash-resident section but `.text`, and the image byte-identical when linked
+  bad write repaired in a single rewrite, a page that never comes good
-  at a different base — which is position independence itself rather than a
+  stopping after exactly three;
  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` — a hardware USART as a pty, or a cycle-timed
-  GPIO⇄pty bridge for a software-UART build, plus the SPM/NVM module simavr's
+  GPIO⇄pty bridge for a software-UART build, selected with `-l` to match
-  tiny cores lack) driven by the real host tool through knock-from-reset,
+  the loader's link; plus the SPM/NVM module simavr's tiny cores lack)
-  program + verify of both memories, session reconnect, an external reset
+  driven by the real host tool through
-  through the patched vector, and the hand-over to a fixture application whose
+  knock-from-reset, program + verify of both memories, session reconnect, an
-  banner proves the launch — cross-checked against the simulator's
+  external reset through the patched vector, and the hand-over to a fixture
-  ground-truth memory dumps and an independent decode of the surgery;
+  application whose banner proves the launch — cross-checked against the
- `pureboot.reloc` — the identical image one slot below the resident serves the
+  simulator's ground-truth memory dumps and an independent decode of the
-  complete command set from there;
+  surgery's rjmp words;
- `pureboot.rehome` (t85) — a loader programmed at address 0 or in the staging
+- `pureboot.reloc` — the identical image installed one slot below the
-  slot re-homes into the top slot through the ordinary update flow;
+  resident serves the complete command set from there (the
- `pureboot.custom` (328P) — the configuration example's 1 MHz software-serial
+  position-independence acceptance test);
-  build driving the full protocol suite, proving the plumbing produces a
+- `pureboot.dirty` (328P) — entering the loader from a running application
-  working loader and not just one that fits;
+  with no reset between, over an SPM page buffer the fixture deliberately
- `pureboot.usart1` (644A) — the same suite over the second hardware USART:
+  dirtied: the case the loader declines to guard against. A bare verify must
-  instance selection is compile-checked everywhere, but only a live session
+  see the corruption, the repairing verify must fix it in one rewrite, and a
-  proves the loader polls the USART it claims;
+  plain verify afterwards must pass. On the boot-sectioned megas hardware
- `pureboot.dirty` (328P) — entering the loader from a running application over
+  forbids the state outright (SPM runs only from the boot section, and reset
-  an SPM buffer it deliberately dirtied, the case the loader declines to guard:
+  erases the buffer), but simavr dispatches SPM from anywhere — which is what
-  a bare verify must see the corruption and the repairing verify must fix it in
+  makes the path constructible at all;
-  one rewrite. Hardware forbids the state here, but simavr dispatches SPM from
+- `pureboot.update` — the full `--update-loader` flow to a re-timed build,
-  anywhere, which is what makes the path constructible;
+  then every power-fail phase: the device is killed mid-write, restarted
- `pureboot.update` — the full `--update-loader` flow, then every power-fail
+  from its flash dump, and a re-run must complete the update with the
-  phase: the device is killed mid-write, restarted from its flash dump, and a
+  application intact throughout.
  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
+`size`, `pi`, and `planner` are host logic and run anywhere; the
-simulator-driven targets need simavr and a pty, so they are POSIX-only.
+simulator-driven targets need simavr and a pty, so they are POSIX-only —
 on Windows the tool is exercised against real hardware.
--- a/pureboot/pureboot.cpp
+++ b/pureboot/pureboot.cpp
@@ -1,14 +1,28 @@
-// 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
 // boot-sectioned megas; the patched reset vector — or erased flash walking
 // up into the loader — on the tinies and the boot-section-less m48s). A
 // watchdog reset hands straight to the application. Otherwise the
 // host has one activation window per awaited knock byte ("pb"); an idle line
 // boots the application. A session then stays in the command loop until 'J'
 // jumps away or the chip resets.
 #include <libavr/libavr.hpp>
@@ -19,24 +33,24 @@ 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-deployment personality, passed in by the build — pureboot_add_loader()
-// signature is not one of them: the chip database is the only universal
+// (the CMake function next to this file) resolves the defaults: the clock the
-// source — a tiny13A cannot read its own signature row from code. An autobaud
+// board actually runs, the wire baud, the serial backend and its pins. The
-// build carries no clock and no baud at all; it measures both.
+// device signature needs no configuring — it comes from the chip database
-#if !defined(PUREBOOT_AUTOBAUD) && (!defined(PUREBOOT_CLOCK_HZ) || !defined(PUREBOOT_BAUD))
+// (avr::hw::db.signature), the only universal source, since the tiny13A
 // cannot even read its signature row from code.
 #if !defined(PUREBOOT_CLOCK_HZ) || !defined(PUREBOOT_BAUD)
 #error \
-    "PUREBOOT_CLOCK_HZ and PUREBOOT_BAUD select this build's clock and baud — create loader targets with pureboot_add_loader(), or PUREBOOT_AUTOBAUD for a clock-free one (README.md)"
+    "PUREBOOT_CLOCK_HZ and PUREBOOT_BAUD select this build's clock and baud — create loader targets with pureboot_add_loader() (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()
@@ -45,115 +59,73 @@ consteval std::int16_t wdrf_field()
 	return avr::hw::db.field_index(reg, "WDRF");
 }
-// The loader owns the top 512 bytes; a staging copy goes in the slot below.
+// Geometry: the resident loader owns the top slot of flash — 512 bytes,
-// Chips without a hardware boot section — the tinies and the m48s, whose SPM
+// except on the >64 KiB chips whose own smallest boot sector is 1 KiB (the
-// runs from anywhere (Atmel-8271 §26) — keep the application's relocated
+// 1284s): there the slot is 1 KiB, matching the hardware boundary the
-// reset vector in the word under the slot.
+// 512-byte figure comes from everywhere else. The word below the slot is
-constexpr std::uint16_t slot_bytes = 512;
+// the trampoline (the application's relocated reset vector) on chips
 // without a hardware boot section — the tinies and the m48s, whose SPM
 // runs from anywhere (Atmel-8271 §26). A boot section also means the CPU
 // runs on while the RWW section programs; everywhere else it halts through
 // the operation.
 constexpr std::uint16_t slot_bytes = spm::flash_bytes > 65536 ? 1024 : 512;
 constexpr std::uint32_t base = spm::flash_bytes - slot_bytes;
 constexpr std::uint16_t page = spm::page_bytes;
 constexpr bool boot_section = avr::hw::curated::has_boot_section();
-// Past 64 KiB one bank of flash does not cover the chip, so a transfer's
+// Past 64 KiB a byte address no longer fits the wire's 16 bits, so on the
-// selector byte carries the bank and the wire address stays a byte address
+// large chips every flash address on the wire — and all slot arithmetic —
-// within it. 'J' is the exception: it is a word address everywhere, because
+// is a word address instead ('J' always was one). A slot spans the same
-// that is what the hardware's own jump takes.
+// wire-high-byte pair in either unit (512 B = 2 x 256 bytes, 1 KiB =
-constexpr bool banked_flash = spm::flash_bytes > 65536;
+// 2 x 256 words), so the slot index is the high byte with its low bit
 // dropped everywhere.
 constexpr bool word_flash = spm::flash_bytes > 65536;
 constexpr std::uint16_t wire_base =
    word_flash ? static_cast<std::uint16_t>(base / 2) : static_cast<std::uint16_t>(base);
 constexpr std::uint16_t wire_page_mask = word_flash ? (page / 2 - 1) : (page - 1);
-// A compile-time window, so the whole EEPROM belongs to the application;
+// The activation window, in seconds, is a compile-time constant (the build
-// re-timing a deployed loader is a self-update with a re-timed build. An
+// may override it): the whole EEPROM belongs to the application, and
-// autobaud build has no clock to convert seconds against and counts polls.
+// re-timing the loader is a bootloader self-update with a re-timed binary.
 #if !defined(PUREBOOT_TIMEOUT)
 #define PUREBOOT_TIMEOUT 8
 #endif
 constexpr std::uint8_t timeout_seconds = PUREBOOT_TIMEOUT;
-#if !defined(PUREBOOT_AUTOBAUD_POLLS)
+// The 12-byte info block the host reads with the 'b' command, flash-resident
-#define PUREBOOT_AUTOBAUD_POLLS 4000000
+// through flash_table (there is no crt to copy a .data image, and its storage
-#endif
+// carries the word alignment 'b' needs to halve the address on the large
-constexpr avr::uint24_t autobaud_budget = PUREBOOT_AUTOBAUD_POLLS;
+// chips). The page byte is the wire count convention: 0 means 256.
-
+inline constexpr avr::flash_table<std::array<std::uint8_t, 12>{
-// The loader's one identity number. The protocol carries none of its own —
+    'P',
-// a version implies it, and the host tool holds that map (README.md).
+    'B',
-constexpr std::uint8_t version = 5;
+    1, // magic, protocol version
 // The image's identity stamp, for the host tool rather than for the wire: an
 // update image is a bare 512-byte slot, and without this nothing in it says
 // which chip it was built for. The tool refuses to install an image whose
 // stamp does not match the device — flashing a foreign loader bricks the
 // target, and the loader itself cannot check what has already replaced it.
 //
 // 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],
-};
+    static_cast<std::uint8_t>(page),
-// clang-format on
+    wire_base & 0xff,
-// Where the identity proper starts: past the magic the host scans for.
+    wire_base >> 8, // app flash ends here; resident loader base (a word address on large chips)
-constexpr std::uint8_t stamp_identity = 2;
+    avr::hw::db.mem.eeprom_size & 0xff,
    avr::hw::db.mem.eeprom_size >> 8,
    // bit 0: host must patch the reset vector (no hardware boot section);
    // bit 1: flash wire addresses are word addresses
    static_cast<std::uint8_t>((boot_section ? 0 : 1) | (word_flash ? 2 : 0)),
 }>
    info_data;
-// The address spaces a transfer can name, in a selector byte's low nibble.
+// The serial link. PUREBOOT_USART forces a hardware USART instance,
-// Flash is 0 so it is the cheapest to select.
+// PUREBOOT_SOFT_SERIAL the polled software UART (no vector — the table
-//
+// belongs to the application) on PUREBOOT_RX/PUREBOOT_TX; with neither, the
-// spm_ops is the one that is not memory: a write there hands its byte to
+// chip's first USART where it has one and the software UART elsewhere. Both
-// SPMCSR and fires the instruction at the transfer's address, which is how
+// are class templates on the clock so only the selected backend is ever
-// page erase, page write and RWW re-enable reach the wire without the loader
+// instantiated. pending() is the cheap line test the activation window
-// carrying a command for each. The hardware's four-cycle store-to-SPM window
+// polls; rx() then picks the byte up; drain() holds until the last
-// is why this is one fused primitive and not a poke of SPMCSR — no host can
+// transmitted frame is fully on the wire (the jump hand-over must not let
-// hit that window across a serial link.
+// the target's re-init clip the ack).
 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;
 }
 [[gnu::always_inline]] inline std::uint8_t bank_of(std::uint8_t selector)
 {
 	return static_cast<std::uint8_t>(selector >> 4);
 }
 // The slot a flash address falls in, as one byte. A slot is half as many words
 // as bytes, so the word address's high byte is exactly this index — which is
 // 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);
 	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 /
 // 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
@@ -166,30 +138,9 @@ constexpr char usart_digit = '0' + PUREBOOT_USART;
 constexpr char usart_digit = '0';
 #endif
-// Release a hardware USART the application may have left enabled onto a
+template <avr::hertz_t C>
 // bit-banged link's pins. A software transmitter drives its TX pin through the
 // port register, but while that USART's TXEN is set the USART owns the pin and
 // the port write does nothing — the loader would receive and obey yet never
 // answer. Writing UCSRnB zero hands the pin back to the port. Guarded on the
 // pin actually being a USART's TXD, so a link on non-USART pins emits nothing.
 template <char Inst, avr::io::pin Tx>
 [[gnu::always_inline]] inline void release_usart_on()
 {
 	if constexpr (avr::uart::has_usart<Inst>())
 		if constexpr (avr::uart::detail::usart_pin<Inst>("TXD") == Tx)
 			avr::hw::reg_impl<avr::uart::detail::ureg<Inst, "UCSR#B">()>::write(0);
 }
 template <avr::io::pin Tx>
 [[gnu::always_inline]] inline void release_usarts_on()
 {
 	release_usart_on<'0', Tx>();
 	release_usart_on<'1', Tx>();
 }
 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::usart<usart_digit, C, {.baud = wire_baud, .max_baud_error = 2.5_pct}>;
 	// The compiled idle poll: lds UCSR0A (2), sbrc skipping the exit (2),
 	// sbiw + sbci + sbci + brne (6).
@@ -221,10 +172,10 @@ struct hardware_link {
 	}
 };
-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::PUREBOOT_RX, wire_baud>;
-	using tx_t = avr::uart::software_tx<C, avr::PUREBOOT_TX, B>;
+	using tx_t = avr::uart::software_tx<C, avr::PUREBOOT_TX, wire_baud>;
 	// The compiled idle poll: sbis skipping the exit (2), sbiw + sbci +
 	// sbci + brne (6).
@@ -233,7 +184,6 @@ struct software_link {
 	static void init()
 	{
 		avr::init<rx_t, tx_t>();
 		release_usarts_on<avr::PUREBOOT_TX>();
 	}
 	static bool pending()
@@ -257,51 +207,22 @@ struct software_link {
 	}
 };
-// The clock-free link: the bit period is measured from the host's calibration
+#if defined(PUREBOOT_USART)
 // 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()
 	{
 		avr::init<uart>();
 		release_usarts_on<avr::PUREBOOT_TX>();
 	}
 	static std::uint8_t rx()
 	{
 		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>;
+using link = hardware_link<dev::clock>;
 #elif defined(PUREBOOT_SOFT_SERIAL)
-using link = software_link<dev::clock, wire_baud>;
+using link = software_link<dev::clock>;
 #else
-using link = std::conditional_t<avr::uart::has_usart<usart_digit>(), hardware_link<dev::clock, wire_baud>,
+using link =
-                                software_link<dev::clock, wire_baud>>;
+    std::conditional_t<avr::uart::has_usart<usart_digit>(), hardware_link<dev::clock>, software_link<dev::clock>>;
 #endif
-// The application's entry, pinned by the linker (--defsym): word 0 on a
+// The application's entry, an absolute address the linker pins (--defsym in
-// boot-sectioned mega, the trampoline at base − 2 elsewhere. Reaching it must
+// CMakeLists.txt): 0x0000 on the mega (word 0 stays the application's own
-// not depend on where this copy runs, so the jump goes through a pointer, and
+// vector — BOOTRST re-vectors a reset into the loader in hardware) and the
-// [[gnu::noipa]] keeps the constant from folding back into a relative call.
+// trampoline word at base - 2 on the tinies. Reaching it must not depend on
 // where this copy runs, so the jump goes through a pointer: [[gnu::noipa]]
 // keeps the constant from folding back into a PC-relative call.
 extern "C" [[noreturn]] void pureboot_app();
 [[gnu::noipa, noreturn]] void jump(void (*target)())
@@ -315,29 +236,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);
@@ -353,8 +255,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())
@@ -362,186 +264,226 @@ std::uint8_t rx_deadline()
 	return link::rx();
 }
-void await_host()
+// Inlined into its call sites: reading two bytes across a call otherwise
-{
+// strands the first in a call-saved register the caller must push/pop; folded
-	// 'p' then 'b', each under a fresh window; anything else is line noise.
+// into the (noreturn) command loop that cost disappears.
 	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
+// The streamers take the count in the wire's 8-bit form: 0 means 256.
-// 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
+// Two functions, because they want opposite placement and placement is an
-// reads, not an argument order.
+// attribute: the byte-addressed loop is small enough to inline into both
-[[gnu::always_inline]] inline std::uint16_t word_of(std::array<std::uint8_t, 2> pair)
+// callers, the word-addressed one stays out of line but flattened — a call to
 // the transmit inside it would strand the 24-bit cursor in callee-saved
 // registers. `word_flash` picks at the call site.
 [[maybe_unused, gnu::always_inline]] inline void send_flash_near(std::uint16_t address, std::uint8_t count)
 {
-	return std::bit_cast<std::uint16_t>(pair);
+	do
 		link::tx(avr::flash_load(reinterpret_cast<const std::uint8_t *>(address++)));
 	while (--count);
 }
-// Out of line: several sites send it, and a call is shorter than a
+// The 24-bit cursor as the machine holds it: the RAMPZ byte and a 16-bit Z,
-// load-immediate at each.
+// carried explicitly (the reassembled 32-bit address folds away inside the
-[[gnu::noinline]] void tx_ack()
+// inlined far load).
 [[maybe_unused, gnu::flatten, gnu::noinline]] void send_flash_far(std::uint16_t address, std::uint8_t count)
 {
-	link::tx(ack);
+	std::uint8_t rampz = static_cast<std::uint8_t>(address >> 15);
 	std::uint16_t z = static_cast<std::uint16_t>(address << 1);
 	do {
 		link::tx(avr::flash_load_far<std::uint8_t>((static_cast<std::uint32_t>(rampz) << 16) | z));
 		// The protocol never reads across 64 KiB, but carrying the wrap is
 		// smaller than the flat 32-bit cursor GCC builds without it.
 		if (++z == 0)
 			++rampz;
 	} while (--count);
 }
-// A wire address and its selector's bank as the flash address they name.
+[[gnu::always_inline]] inline void send_flash(std::uint16_t address, std::uint8_t count)
 [[gnu::always_inline]] inline spm::flash_address_t flash_address([[maybe_unused]] std::uint8_t bank, std::uint16_t at)
 {
-	if constexpr (banked_flash)
+	if constexpr (word_flash)
-		return (static_cast<spm::flash_address_t>(bank) << 16) | at;
+		send_flash_far(address, count);
 	else
-		return at;
+		send_flash_near(address, count);
 }
-// One byte out of any space. Every accessor shares the transfer's cursor, its
+void send_eeprom(std::uint16_t address, std::uint8_t count)
 // 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)
+	do
-		return ee::read(at);
+		link::tx(ee::read(address++));
-	if (space == sp_data)
+	while (--count);
 		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
+// EEPROM write, host-paced: each ack goes out once the byte's write has
-// page at a time through 'W' and is committed through sp_spm — and the fuses
+// begun, so the next byte arrives while it completes and the following
-// are not writable at all: SPM reaches flash and boot lock bits only.
+// write's own ready-wait sees an idle line. Nothing is ever missed, on
-[[gnu::always_inline]] inline void store(std::uint8_t space, std::uint8_t bank, std::uint16_t at, std::uint8_t value,
+// either serial backend, without a buffer.
-                                         std::uint8_t slot_high)
+void store_eeprom(std::uint16_t address, std::uint8_t count)
 {
-	if (space == sp_data) {
+	do {
-		*reinterpret_cast<volatile std::uint8_t *>(at) = value;
+		ee::write<off>(address++, link::rx());
-		return;
+		link::tx(ack);
 	} while (--count);
 }
 // One flash page: stream the bytes into the SPM buffer as little-endian
 // words, then erase and program — except the 512-byte slot this code runs
 // in, which is drained but never programmed, so a copy can never erase
 // itself. `slot_high` is the high byte of that running slot's base (run()
 // derives it); a broken host thus cannot brick the running loader, and a
 // copy flashed one slot lower may rewrite the slot above it — how pureboot
 // updates itself.
 void program_flash(std::uint16_t wire_address, std::uint8_t slot_high)
 {
 	// No discard before the fill: the buffer is write-once per word
 	// (§26.2.1), so filling over one a refused page or an application left
 	// dirty programs stale words — but a page write auto-erases the buffer
 	// (§26.2.1; §19.2 on the tinies), so that write clears the condition and
 	// the host's read-back rewrites the page.
 	// One induction either way. On the byte-addressed chips the wire address
 	// itself walks the page (aligned, so the offset bits wrap to zero); on
 	// the word-addressed large chips the wire word address becomes a 32-bit
 	// byte cursor once, and their 256-byte page makes its low byte the whole
 	// in-page offset. The slot index is one high byte of the wire address —
 	// two values on byte-addressed chips (the & ~1), bits 16:9 re-packed on
 	// the large ones.
 	spm::flash_address_t address;
 	std::uint8_t page_high;
 	if constexpr (word_flash) {
 		// Pages are aligned, so one page never crosses a 64 KiB boundary:
 		// RAMPZ is a per-page constant and the fill cursor is a 16-bit Z
 		// whose low byte is the whole in-page offset (256-byte pages). The
 		// slot index is simply the wire word address's high byte.
 		const std::uint8_t rampz = static_cast<std::uint8_t>(wire_address >> 15);
 		const std::uint16_t z0 = static_cast<std::uint16_t>(wire_address << 1);
 		std::uint16_t z = z0;
 		do {
 			std::uint8_t low = link::rx();
 			std::uint8_t high = link::rx();
 			spm::fill<off>((static_cast<spm::flash_address_t>(rampz) << 16) | z,
 			               static_cast<std::uint16_t>(low | (high << 8)));
 			z += 2;
 		} while (static_cast<std::uint8_t>(z));
 		address = (static_cast<spm::flash_address_t>(rampz) << 16) | z0;
 		page_high = static_cast<std::uint8_t>(wire_address >> 8) & 0xfe;
 	} else {
 		address = static_cast<spm::flash_address_t>(wire_address);
 		do {
 			std::uint8_t low = link::rx();
 			std::uint8_t high = link::rx();
 			spm::fill<off>(address, static_cast<std::uint16_t>(low | (high << 8)));
 			address += 2;
 		} while (static_cast<std::uint8_t>(address) & (page - 1));
 		address -= 2; // back inside the page — erase and write ignore the word bits
 		page_high = static_cast<std::uint8_t>(address >> 8) & 0xfe;
 	}
-	if (space == sp_spm) {
+	if (page_high != slot_high) {
-		// The running-slot write guard. An SPM command aimed at the slot this
+		// The tinies and the m48s halt the CPU through the erase and the
-		// code executes from is dropped, so a broken host cannot brick the
+		// write, so only the boot-sectioned megas — running on while their
-		// running loader — while a copy one slot lower may still rewrite the
+		// RWW section programs — wait.
-		// resident one, which is what a self-update is. Guarding the commit
+		spm::erase_page<off>(address);
-		// rather than the page fill covers erase and write both, and leaves a
+		if constexpr (boot_section)
-		// refused page's words in the buffer: harmless, since the next page
+			spm::wait();
-		// write auto-erases it (§26.2.1).
+		spm::write_page<off>(address);
 		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();
 		return;
 	}
-	// Host-paced: the ack goes out once the write has begun, so the next byte
+	// The megas program with their RWW section disabled; reads need it back
-	// arrives while it completes and nothing is missed without a buffer.
+	// on. The same store discards the buffer (§26.2.2), so they never meet
-	ee::write<off>(at, value);
+	// the stale-word case above. boot_section implies an RWW section.
 	if constexpr (boot_section)
 		spm::rww_enable<off>();
 }
-// One page into the SPM buffer, and only that: the erase and the write that
+// The four fuse/lock bytes in the hardware's own Z order: low, lock,
-// commit it are host-issued sp_spm stores, which reach the same fused
+// extended, high. Writing fuses is not a thing self-programming can do on
-// store-and-SPM pair through the transfer path's own address and data.
+// AVR — SPM reaches flash (and boot lock bits) only.
-//
+void send_fuses()
 // 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
+	std::uint8_t which = 0;
-	// starts at the page base; the low byte of the cursor is the whole in-page
+	do
-	// offset, since a page is aligned and never crosses a bank.
+		link::tx(spm::read_fuse<off>(static_cast<spm::fuse>(which)));
-	std::uint16_t z = at & ~static_cast<std::uint16_t>(page - 1);
+	while (++which & 3);
 	do {
 		std::uint8_t low = link::rx();
 		std::uint8_t high = link::rx();
 		spm::fill<off>(flash_address(bank, z), word_of({low, high}));
 		z += 2;
 	} while (static_cast<std::uint8_t>(z) & (page - 1));
 }
 [[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.
 	// The flag register is MCUSR, or the classic megas' MCUCSR.
 	if (avr::hw::field_impl<wdrf_field()>::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
-	// address is a word address and a slot is half as many words as bytes, so
+	// return address is a word address, whose high byte is the 256-word slot
-	// its high byte is the slot index outright. No absolute address is ever
+	// index — on byte-addressed chips doubled back into byte terms.
-	// formed, so the image stays position-independent.
+	// program_flash refuses this one slot and the info block is addressed
-	const auto slot_high = avr::startup::caller_page();
+	// from it, so both follow wherever the code was flashed. The high byte is
 	// spelled as byteswap's low byte: the builtin's value is itself built by
 	// swapping the two stacked bytes, and the double swap folds to the single
 	// byte pick a hand assembler writes — `>> 8` leaves the swap materialized.
 	const std::uint16_t ra_words = reinterpret_cast<std::uint16_t>(__builtin_return_address(0));
 	const std::uint8_t ra_high = static_cast<std::uint8_t>(std::byteswap(ra_words));
 	const std::uint8_t slot_high = word_flash ? ra_high & 0xfe : static_cast<std::uint8_t>(ra_high << 1);
-	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 (in wire units: bytes, or words on the large
 			// chips) is its offset in any slot, and the high byte of its
 			// runtime address is the running slot's. Composed from the two
 			// bytes — the high half is runtime data, so no absolute address
 			// is ever materialized.
 			const auto link_low = reinterpret_cast<std::uint16_t>(info_data.storage.data());
 			const std::uint8_t low =
 			    word_flash ? static_cast<std::uint8_t>(link_low >> 1) : static_cast<std::uint8_t>(link_low);
 			send_flash(static_cast<std::uint16_t>(low | (slot_high << 8)), static_cast<std::uint8_t>(info_data.size()));
 			break;
 		}
 		case 'J': { // jump to a wire word address: hand-over and staging transfer
 			auto target = reinterpret_cast<void (*)()>(rx16());
-			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
@@ -1,13 +1,24 @@
 #!/usr/bin/env python3
-"""pureboot host tool — the smart half of the protocol (README.md).
+"""pureboot host tool — the smart half of the pureboot protocol (README.md).
-The device exposes primitives; everything composite is here: HEX/raw images,
+The device exposes primitives; this tool composes them: image loading (raw
-programming with repairing read-back verification, the reset-vector surgery
+binary or Intel HEX), flash programming with read-back verification, erase as
-the boot-section-less chips need, and the self-update that stages the loader
+writing 0xff, EEPROM programming, fuse and info readout, the hand-over jump,
-one slot lower and lets it rewrite the resident.
+and — on chips without a hardware boot section — the reset-vector surgery
 that re-homes the application's entry through the trampoline word below the
 loader. Page 0 and the trampoline are written first, so every interruption
 point of a flash leaves the chip reset-recoverable into the loader.
-Standard library only. The port is termios on POSIX and the Win32 serial API
+It also updates the loader itself (--update-loader): pureboot's image is
-through ctypes on Windows, so any tty or COM port works.
+position-independent, so the tool installs the identical binary one 512-byte
 slot below the resident loader, jumps into that staging copy, lets it rewrite
 the resident slot, and restores what the staging slot held — resumable at
 every phase from the flash state plus a host-side state file carrying the
 saved bytes.
 Python standard library only; the serial port is driven with termios on POSIX
 and the Win32 serial API (through ctypes) on Windows, so any tty or COM port
 works — a USB adapter as well as a simavr pty.
 """
 import argparse
@@ -24,79 +35,16 @@ else:
    import termios
 PROMPT = b"+"
-VERSION = 5  # this tool's own version — free to drift from a loader's
+PROTOCOL_VERSION = 1
-# The loader versions this tool speaks. A pureboot version implies its wire
+SLOT = 512  # the loader slot on byte-addressed chips; word-addressed ones (>64 KiB) use 1 KiB — their own smallest boot sector
 # protocol, which carries no number of its own, so this window is where that
 # map lives: every version so far speaks the same protocol, and one that
 # changes it becomes the new floor here.
 OLDEST_LOADER = 1
 NEWEST_LOADER = 5
 SLOT = 512  # the loader slot, on every chip
 RETRIES = 3  # rewrites of a page that reads back wrong, before the run stops
 # pureboot 5 replaced the four per-memory commands with one pair: 'G' reads and
 # 'g' writes, each taking a selector byte, a 16-bit address and a count, over
 # the spaces below. The loader carries one transfer loop instead of four bodies
 # — which is what buys the data space and the host-issued SPM operations.
 UNIFIED_LOADER = 5
 SP_FLASH, SP_EEPROM, SP_RAM, SP_FUSE, SP_SPM = 0, 1, 2, 3, 4
 # A selector's high nibble is the flash bank — the address bits above the 16-bit
 # wire address — so a transfer names a byte address within one 64 KiB bank and
 # no command has to speak word addresses. No single transfer may cross a bank
 # boundary; the host chunks to keep that true.
 def selector(space, address):
    return space | ((address >> 16) << 4)
 # The SPM operations pureboot 5 leaves to the host: a write to SP_SPM hands its
 # byte to SPMCSR and fires the instruction at the selected flash address. Every
 # part pureboot targets agrees on these encodings.
 SPM_ERASE, SPM_WRITE, SPM_RWWSRE = 0x03, 0x05, 0x11
 # Calibration byte for an autobaud loader: 0xC0 is a start bit plus six zero
 # data bits — one low pulse of seven bit-times, which the loader times into its
 # per-bit unit. Sent at whatever baud the host chose; the loader locks to it.
 CALIBRATE = 0xC0
 # pureboot 5 answers 'b' with its version and the chip signature; the host
 # derives the rest of the geometry from the signature rather than reading a
 # table off the device. flash, page, eeprom, patch-vector per distinct
 # signature, over every chip pureboot targets (the loader computes the same
 # from its chip database at build time). Die revisions that share a signature
 # share this row, as they share the silicon.
 CHIP_GEOMETRY = {
    #  signature  : (flash, page, eeprom, patch_vector)
    (0x1E, 0x90, 0x07): (1024, 32, 64, True),      # ATtiny13/13A
    (0x1E, 0x91, 0x08): (2048, 32, 128, True),     # ATtiny25
    (0x1E, 0x92, 0x06): (4096, 64, 256, True),     # ATtiny45
    (0x1E, 0x93, 0x0B): (8192, 64, 512, True),     # ATtiny85
    (0x1E, 0x92, 0x05): (4096, 64, 256, True),     # ATmega48/48A
    (0x1E, 0x92, 0x0A): (4096, 64, 256, True),     # ATmega48P/48PA
    (0x1E, 0x93, 0x07): (8192, 64, 512, False),    # ATmega8/8A
    (0x1E, 0x93, 0x0A): (8192, 64, 512, False),    # ATmega88/88A
    (0x1E, 0x93, 0x0F): (8192, 64, 512, False),    # ATmega88P/88PA
    (0x1E, 0x94, 0x03): (16384, 128, 512, False),  # ATmega16/16A
    (0x1E, 0x94, 0x06): (16384, 128, 512, False),  # ATmega168/168A
    (0x1E, 0x94, 0x0B): (16384, 128, 512, False),  # ATmega168P/168PA
    (0x1E, 0x94, 0x0A): (16384, 128, 512, False),  # ATmega164P/164PA
    (0x1E, 0x94, 0x0F): (16384, 128, 512, False),  # ATmega164A
    (0x1E, 0x95, 0x02): (32768, 128, 1024, False), # ATmega32/32A
    (0x1E, 0x95, 0x0F): (32768, 128, 1024, False), # ATmega328P
    (0x1E, 0x95, 0x14): (32768, 128, 1024, False), # ATmega328
    (0x1E, 0x95, 0x08): (32768, 128, 1024, False), # ATmega324P
    (0x1E, 0x95, 0x11): (32768, 128, 1024, False), # ATmega324PA
    (0x1E, 0x95, 0x15): (32768, 128, 1024, False), # ATmega324A
    (0x1E, 0x96, 0x09): (65536, 256, 2048, False), # ATmega644/644A
    (0x1E, 0x96, 0x0A): (65536, 256, 2048, False), # ATmega644P/644PA
    (0x1E, 0x97, 0x05): (131072, 256, 4096, False),# ATmega1284P
    (0x1E, 0x97, 0x06): (131072, 256, 4096, False),# ATmega1284
 }
 VERBOSE = False
 def verbose(message):
    """Detail printed only under --verbose: decisions and derived facts, not
    per-byte chatter — the progress bar carries the bulk transfers."""
    if VERBOSE:
        print(f"  {message}")
@@ -106,9 +54,11 @@ class Error(Exception):
 class Progress:
-    """A transient bar on stderr, drawn only for a tty and erased when done —
+    """A transient in-place bar on stderr for the operations that take wire
-    logs and pipes see only the summary line each operation prints. No label
+    time. Drawn only when stderr is a tty — logs, pipes and the test harness
-    or a zero total disables it, so callers can pass one unconditionally."""
+    see nothing — and erased once done; the summary line each operation
    prints afterwards is the persistent record. A zero total (or no label)
    disables it, so callers can pass one through unconditionally."""
    def __init__(self, label, total, unit="pages"):
        self.label, self.total, self.unit = label, total, unit
@@ -360,62 +310,27 @@ Port = WindowsPort if os.name == "nt" else PosixPort
 class Info:
    """The 12-byte info block."""
    @classmethod
    def from_identity(cls, raw):
        """pureboot 5's reply: the version and the chip signature. The rest of
        the geometry is looked up from the signature — the loader derived the
        same facts from its chip database at build time, so nothing is guessed,
        it is simply not sent. Reconstructs a block in the older layout, so
        every derived attribute below is shared with the loaders that do send
        one.
        The base is where application flash ends, which is a property of the
        chip and not of the copy answering: a loader staged one slot lower
        reports the same geometry the resident one does, exactly as the loaders
        that send a block do. Which slot a copy runs in matters only to its own
        write guard, which is the loader's business."""
        if len(raw) != 4:
            raise Error(f"bad identity reply: {raw.hex()}")
        version, signature = raw[0], tuple(raw[1:4])
        geometry = CHIP_GEOMETRY.get(signature)
        if geometry is None:
            sig = " ".join(f"{b:02x}" for b in signature)
            raise Error(f"unknown signature {sig} — this tool has no geometry for it")
        flash, page, eeprom, patch = geometry
        base = flash - SLOT
        word_flash = flash > 0x10000
        wire_base = base // 2 if word_flash else base
        flags = (1 if patch else 0) | (2 if word_flash else 0)
        raw12 = bytes((ord("P"), ord("B"), version, *signature, page & 0xFF,
                       wire_base & 0xFF, wire_base >> 8, eeprom & 0xFF, eeprom >> 8, flags))
        return cls(raw12)
    def __init__(self, raw):
        if len(raw) != 12 or raw[0:2] != b"PB":
            raise Error(f"bad info block: {raw.hex()}")
-        self.version = raw[2]
+        if raw[2] != PROTOCOL_VERSION:
-        if not OLDEST_LOADER <= self.version <= NEWEST_LOADER:
+            raise Error(f"protocol version {raw[2]}, tool speaks {PROTOCOL_VERSION}")
            raise Error(
                f"pureboot {self.version}: this tool (version {VERSION}) speaks pureboot "
                f"{OLDEST_LOADER}..{NEWEST_LOADER} — a newer loader needs a newer tool"
            )
        self.raw = bytes(raw)
        self.signature = raw[3:6]
        self.page = raw[6] or 256  # the wire count convention: 0 means 256
        self.patch_vector = bool(raw[11] & 1)
-        # Bit 1: the flash runs past what one 16-bit address covers. Through
+        # Large chips speak word addresses for flash (bit 1); the host keeps
-        # pureboot 4 that made flash addresses words on the wire; pureboot 5
+        # every address in bytes and converts at the wire.
        # keeps them bytes and carries the bank in the selector instead. Every
        # address in this tool stays a byte address either way and converts at
        # the wire.
        self.word_flash = bool(raw[11] & 2)
        scale = 2 if self.word_flash else 1
        self.base = (raw[7] | (raw[8] << 8)) * scale
        self.eeprom_size = raw[9] | (raw[10] << 8)
-        self.flash_size = self.base + SLOT
+        self.slot = 1024 if self.word_flash else SLOT
-        self.stage = self.base - SLOT  # where a staging copy of the loader goes
+        self.flash_size = self.base + self.slot
-        # The hand-over target as 'J' takes it: the trampoline below the
+        self.stage = self.base - self.slot  # where a staging copy of the loader goes
-        # loader, or word 0 where BOOTRST re-vectors reset in hardware.
+        # The hand-over target, as the word address 'J' takes: the trampoline
        # below the loader (tinies), or word 0 (mega — the application's own
        # reset vector; BOOTRST re-vectors a reset into the loader instead).
        self.app_entry_word = (self.base - 2) // 2 if self.patch_vector else 0
    def describe(self):
@@ -428,18 +343,17 @@ class Info:
        )
    def lines(self):
-        """One fact per line — what --info prints."""
+        """The info block as one fact per line — what --info prints."""
        if self.patch_vector:
            hand_over = f"host-patched reset vector, trampoline at {self.base - 2:#06x}"
        else:
            hand_over = "hardware boot section, jump to word 0"
        return (
            f"version      pureboot {self.version}",
            f"signature    {' '.join(f'{b:02x}' for b in self.signature)}",
            f"flash        {self.flash_size} B, {self.page} B pages"
-            + (", past one 16-bit bank" if self.word_flash else ""),
+            + (", word-addressed wire" if self.word_flash else ""),
            f"application  0x0000..{self.base - 1:#06x} ({self.base} B)",
-            f"loader       {self.base:#06x} ({SLOT} B slot)",
+            f"loader       {self.base:#06x} ({self.slot} B slot)",
            f"staging      {self.stage:#06x}",
            f"EEPROM       {self.eeprom_size} B",
            f"hand-over    {hand_over}",
@@ -447,81 +361,36 @@ class Info:
 class Loader:
-    """A session. Between commands the loader has prompted and awaits a
+    """A pureboot session. Between commands the loader has prompted `+` and
-    command byte; every method restores that, except jump() — after which the
+    awaits a command byte; every method restores that invariant — except
-    target must be knocked afresh."""
+    jump(), after which the target must be knocked afresh."""
    def __init__(self, port):
        self.port = port
        self.info = None
        # Set once a session is established over an autobaud link, so a
        # re-entry after 'J' repeats the handshake that worked.
        self.autobaud = False
-    def _read_identity(self):
+    def connect(self, wait):
-        """The 'b' reply, in either of the two layouts a loader may send.
+        """Knock until the activation window answers, then read the info
-        pureboot 5 answers with its version and the signature; older loaders
+        block. Also converges when the loader already sits in its command
-        answer with a 12-byte block. The version byte cannot be mistaken for
+        loop: the knock bytes are ignored-or-executed there, and the drain
-        the older block's 'P', so four bytes are enough to tell them apart."""
+        absorbs whatever they produced."""
-        head = self.port.read_exact(4, 2.0)
+        self.port.flush_input()
        if head[0:2] == b"PB":
            return Info(head + self.port.read_exact(8, 2.0))
        return Info.from_identity(head)
    def _handshake(self, wait, knock, what):
        """One activation, retried until the loader answers or the window
        closes. The identity reply is what proves the loader is listening — a
        prompt byte alone does not, since one left over from a previous session
        can still be in the pipeline while the port opening resets the device
        into a fresh window, where a command without its knock is discarded.
        Each attempt is therefore the whole handshake. This also converges into
        an already-live session: the knock bytes are ignored there and the
        drain absorbs whatever they produced."""
        deadline = time.monotonic() + wait
        knocks = 0
        while True:
-            self.port.flush_input()
+            self.port.write(b"pb")
            self.port.write(knock)
            knocks += 1
            if PROMPT in self.port.read_available(0.4):
-                # Settle: absorb a real loader's trailing bytes before asking
+                break
                # for the identity. Bounded by the deadline so a target that
                # never falls quiet — a board stuck in a reset loop, whose
                # garbage carries a stray prompt — cannot spin here forever.
                while self.port.read_available(0.3):
                    if time.monotonic() > deadline:
                        break
                self.port.write(b"b")
                try:
                    # A version the tool cannot speak is the loader's own
                    # answer, not a failed knock: Info reports it rather than
                    # sending the tool round the loop again.
                    self.info = self._read_identity()
                except Error as failed:
                    if "pureboot" in str(failed):
                        raise
                    self.info = None
                if self.info is not None:
                    self._expect_prompt()
                    verbose(f"loader answered {what} {knocks}; identity read")
                    return self.info
            if time.monotonic() > deadline:
                raise Error("no answer — reset the device within its activation window")
-
+        while self.port.read_available(0.3):
-    def connect(self, wait):
+            pass
-        """Knock 'p' then 'b' and read the identity."""
+        self.port.write(b"b")
-        return self._handshake(wait, b"pb", "knock")
+        self.info = Info(self.port.read_exact(12, 2.0))
-
+        self._expect_prompt()
-    def connect_autobaud(self, wait):
+        verbose(f"loader answered knock {knocks}; info block read")
-        """The autobaud handshake. In place of the p+b knock the host sends the
+        return self.info
        calibration pulse — one seven-bit-time low pulse at the host's chosen
        baud, which the loader times into its per-bit unit — then a single 'p'
        the loader decodes at the rate it just measured. A lost pulse, or a
        knock landing while the loader is mid-frame, simply fails to answer and
        leaves the measurement loop waiting for the next pulse, so the retry in
        _handshake covers it."""
        self.autobaud = True
        return self._handshake(wait, bytes((CALIBRATE, ord("p"))), "calibration")
    def _expect_prompt(self, timeout=2.0):
        byte = self.port.read_exact(1, timeout)
@@ -545,58 +414,7 @@ class Loader:
            count -= chunk
        return data
    @property
    def unified(self):
        """pureboot 5 and later: one 'G'/'g' pair over selector-named spaces."""
        return self.info is not None and self.info.version >= UNIFIED_LOADER
    def _read_space(self, space, address, count):
        """A run out of any space, chunked to 256 bytes and to bank bounds."""
        data = b""
        while count:
            chunk = min(count, 256, 0x10000 - (address & 0xFFFF))
            head = bytes((ord("G"), selector(space, address), address & 0xFF,
                          (address >> 8) & 0xFF, chunk & 0xFF))
            data += self._command(head, chunk, 5.0)
            address += chunk
            count -= chunk
        return data
    def _write_space(self, space, address, data, progress=None):
        """A run into any space. Each byte is acked as its write begins — an
        EEPROM cell and an SPM operation both need that pacing, and the ack is
        what the loader sends in place of a completion status."""
        offset = 0
        while offset < len(data):
            chunk = data[offset : offset + min(256, 0x10000 - (address & 0xFFFF))]
            head = bytes((ord("g"), selector(space, address), address & 0xFF,
                          (address >> 8) & 0xFF, len(chunk) & 0xFF))
            self.port.write(head)
            for byte in chunk:
                self.port.write(bytes((byte,)))
                self._expect_prompt()
                if progress:
                    progress.step()
            self._expect_prompt()  # the next command prompt
            address += len(chunk)
            offset += len(chunk)
    def spm(self, operation, address):
        """One SPM operation at a flash address — the erase, write and RWW
        re-enable that pureboot 4 ran inside 'W' and pureboot 5 leaves here."""
        self._write_space(SP_SPM, address, bytes((operation,)))
    def read_ram(self, address, count):
        """Data space: SRAM, and with it the register file and every I/O
        register, which share the address space on AVR. New in pureboot 5."""
        return self._read_space(SP_RAM, address, count)
    def write_ram(self, address, data):
        self._write_space(SP_RAM, address, data)
    def read_flash(self, address, count):
        if self.unified:
            return self._read_space(SP_FLASH, address, count)
        if not self.info.word_flash:
            return self._stream_read("R", address, count)
        # Word-addressed wire: widen to even bounds and never let one read
@@ -614,32 +432,15 @@ class Loader:
        return data[address - start : address - start + count]
    def read_eeprom(self, address, count):
        if self.unified:
            return self._read_space(SP_EEPROM, address, count)
        return self._stream_read("r", address, count)
    def write_page(self, address, data):
        assert len(data) == self.info.page and address % self.info.page == 0
        if self.unified:
            # 'W' fills the page buffer and stops there; the erase and the write
            # are host-issued SPM operations. Only a chip with a boot section
            # has RWW to re-enable — on the others bit 4 of SPMCSR means
            # something else entirely, so it must not be sent.
            head = bytes((ord("W"), selector(SP_FLASH, address), address & 0xFF, (address >> 8) & 0xFF))
            self._command(head + data, 0, 2.0)
            self.spm(SPM_ERASE, address)
            self.spm(SPM_WRITE, address)
            if not self.info.patch_vector:
                self.spm(SPM_RWWSRE, address)
            return
        wire = address // (2 if self.info.word_flash else 1)
        head = bytes((ord("W"), wire & 0xFF, wire >> 8))
        self._command(head + data, 0, 2.0)
    def write_eeprom(self, address, data, progress=None):
        if self.unified:
            self._write_space(SP_EEPROM, address, data, progress)
            return
        offset = 0
        while offset < len(data):
            chunk = data[offset : offset + 256]
@@ -655,21 +456,21 @@ class Loader:
            offset += len(chunk)
    def read_fuses(self):
        if self.unified:
            return self._read_space(SP_FUSE, 0, 4)
        return self._command(b"F", 4, 2.0)
    def jump(self, word_address):
-        """The device acks, then execution continues at the word address."""
+        """'J': the device acks, then execution continues at the word
        address — a loader slot's base (whose copy must then be knocked
        afresh) or the application entry."""
        self.port.write(bytes((ord("J"), word_address & 0xFF, word_address >> 8)))
        self._expect_prompt()
    def enter_copy(self, byte_address, wait):
-        """Jump into the loader copy at `byte_address` and knock it — a slot
+        """Jump into the loader copy at `byte_address` and knock it. Ending
-        base is that copy's entry stub, so it can only land there."""
+        up in the copy addressed is guaranteed by construction: a jump to a
-        autobaud = self.autobaud
+        slot base lands in that slot's entry stub."""
        self.jump(byte_address // 2)
-        return self.connect_autobaud(wait) if autobaud else self.connect(wait)
+        return self.connect(wait)
    def run_application(self):
        self.jump(self.info.app_entry_word)
@@ -763,14 +564,15 @@ def plan_flash(image, info):
 def covered(pages, info, skip_blank):
-    """Pages in programming order, optionally dropping all-0xff ones (sound
+    """Pages in programming order; optionally dropping all-0xff pages (sound
-    only over erased flash, and never a load-bearing page).
+    only over erased flash) — never a load-bearing one.
-    A patched vector puts page 0 first and the trampoline page second, so from
+    With a patched vector (tinies), the patched page 0 goes first and the
-    the first write on a reset lands in the loader and its fall-through on the
+    trampoline page second: from the first write on, a reset lands in the
-    application entry — every interruption point recoverable. A hardware boot
+    loader and the loader's own fall-through lands on the application entry,
-    section re-vectors reset regardless; page 0 goes last there, which
+    so every interruption point of the flash is recoverable. With a hardware
-    maximizes what an interrupted image retains."""
+    boot section a reset re-vectors to the loader regardless; ascending
    order, page 0 last, maximizes what an interrupted image retains."""
    trampoline_page = info.base - info.page if info.patch_vector else None
    first = [0, trampoline_page] if info.patch_vector else []
    rest = [a for a in sorted(pages) if a not in first]
@@ -836,35 +638,18 @@ def mega_boot(info, fuse_bytes):
 def image_info(image):
-    """What a pureboot binary says about itself, or None.
+    """The info block embedded in a pureboot binary, or None."""
-
+    at = image.find(b"PB" + bytes((PROTOCOL_VERSION,)))
-    An update image is a bare slot: nothing about it names the chip it was
+    return Info(image[at : at + 12]) if 0 <= at <= len(image) - 12 else None
    built for, and installing a foreign one bricks the target — so every
    loader carries a stamp for this. Through pureboot 4 the stamp is the
    12-byte info block the device also serves; pureboot 5 serves its identity
    from immediates and carries a 6-byte stamp (magic, version, signature)
    that only this exists for, from which the geometry is looked up exactly as
    it is for a live device.
    Searched once per known version, so the magic stays three selective bytes
    rather than two that code could carry by chance."""
    for version in range(OLDEST_LOADER, NEWEST_LOADER + 1):
        at = image.find(b"PB" + bytes((version,)))
        if at < 0:
            continue
        if version >= UNIFIED_LOADER:
            if at <= len(image) - 6:
                return Info.from_identity(image[at + 2 : at + 6])
        elif at <= len(image) - 12:
            return Info(image[at : at + 12])
    return None
 def loader_image(path):
-    """An update image as the slot's own content: a raw binary already is,
+    """A loader update image, as the slot's own content. A raw binary is that
-    while a HEX carries the blank below the loader's base, which is peeled off
+    already; an Intel HEX links the loader at its base inside an otherwise
-    here. The base comes from the image's own block, not the device's, so a
+    blank flash image, and load_image() anchors every image at zero, so the
-    foreign image survives intact for the preflight to reject by name."""
+    blank below the base is dropped here. The base comes from the image's own
    info block rather than the device's, so an image built for somewhere else
    survives intact and the preflight can say so."""
    image = load_image(path)
    embedded = image_info(image)
    if embedded and len(image) > embedded.base:
@@ -873,17 +658,18 @@ def loader_image(path):
 def staging_content(image, info):
-    """The staging slot's content: the image, padding, and — where the
+    """The 512-byte staging-slot content: the image, padding, and — on
-    hand-over jumps through the word below the resident — that word, which for
+    chips whose hand-over jumps through the word below the resident loader —
-    a staging copy is its own last one. Composed as an rjmp to the resident,
+    that word, which for a staging copy is the slot's own last word: an rjmp
-    so an abandoned staging copy still falls through into a loader."""
+    to the resident base. The staging copy's fall-through and 'J'-free exit
-    budget = SLOT - 2 if info.patch_vector else SLOT
+    both land in a loader instead of garbage."""
-    if len(image) > budget:
+    slot = info.slot
-        raise Error(f"loader image is {len(image)} B, the slot holds {budget}")
+    if len(image) > (slot - 2 if info.patch_vector else slot):
-    content = bytearray(image) + bytearray([0xFF] * (SLOT - len(image)))
+        raise Error(f"loader image is {len(image)} B, the slot holds {slot - 2 if info.patch_vector else slot}")
    content = bytearray(image) + bytearray([0xFF] * (slot - len(image)))
    if info.patch_vector:
        through = rjmp_to((info.base - 2) // 2, info.base // 2, info.flash_size // 2)
-        content[SLOT - 2], content[SLOT - 1] = through & 0xFF, through >> 8
+        content[slot - 2], content[slot - 1] = through & 0xFF, through >> 8
    return bytes(content)
@@ -891,10 +677,7 @@ def update_preflight(image, info, fuse_bytes):
    """Errors and warnings before any flash is touched. Returns warnings."""
    embedded = image_info(image)
    if embedded is None:
-        raise Error(
+        raise Error("no pureboot info block in the update image — not a pureboot binary?")
            "no pureboot info block in the update image — not a pureboot binary, "
            f"or a version this tool ({VERSION}) does not know"
        )
    if embedded.raw[3:] != info.raw[3:]:
        raise Error(
            f"update image is for another target: it declares "
@@ -909,7 +692,7 @@ def update_preflight(image, info, fuse_bytes):
            raise Error(
                f"cannot self-update: the staging slot {info.stage:#06x} lies below the "
                f"boot section ({bls_start:#06x}) where SPM is disabled "
-                f"— a boot section of at least two slots ({2 * SLOT} B, BOOTSZ) is "
+                f"— a boot section of at least two slots ({2 * info.slot} B, BOOTSZ) is "
                f"required, and only an external programmer can change fuses"
            )
        if not bootrst:
@@ -951,7 +734,7 @@ class UpdateState:
        self.data = {
            "signature": info.signature.hex(),
            "base": info.base,
-            "staging": loader.read_flash(info.stage, SLOT).hex(),
+            "staging": loader.read_flash(info.stage, info.slot).hex(),
            "page0": loader.read_flash(0, info.page).hex() if info.patch_vector else "",
        }
        with open(self.path, "w") as f:
@@ -970,8 +753,9 @@ class UpdateState:
 def write_differing(loader, base, content, order=None, label=None):
-    """Program the pages of `content` at `base` that differ from flash, so a
+    """Program the pages of `content` at `base` that differ from flash —
-    resumed phase redoes only what an interruption left."""
+    idempotent, so a resumed phase redoes only what an interruption left.
    A label puts the compare-and-program loop on the progress bar."""
    page = loader.info.page
    offsets = list(order) if order is not None else list(range(0, len(content), page))
    written = 0
@@ -984,8 +768,9 @@ def write_differing(loader, base, content, order=None, label=None):
            bar.step()
    if label:
        verbose(f"{label}: {written} of {len(offsets)} pages differed")
-    # The same bounded repair as verify_pages: here a page left wrong is a
+    # Page-wise read-back with the same bounded repair as verify_pages: this
-    # half-written loader slot.
+    # is the loader-update path, where a page left wrong is a half-written
    # loader slot.
    for retry in range(RETRIES + 1):
        bad = [
            offset
@@ -1007,8 +792,8 @@ def write_differing(loader, base, content, order=None, label=None):
 def patch_word0(loader, page0, target_base):
-    """Re-aim word 0 at `target_base` — the resume insurance around
+    """Rewrite page 0 with its word 0 re-aimed at `target_base` — the
-    rewriting a loader slot the reset path goes through."""
+    resume insurance around rewriting a loader slot the reset path uses."""
    info = loader.info
    patched = bytearray(page0)
    word = rjmp_to(0, target_base // 2, info.flash_size // 2)
@@ -1018,17 +803,16 @@ def patch_word0(loader, page0, target_base):
 def op_update_loader(loader, wait, path, state_path, fuse_bytes):
-    """Replace the resident loader with `path`, using the loader as its own
+    """Replace the resident loader with `path`, using the loader itself as
-    staging loader. Every phase is idempotent and keyed off the flash state,
+    its own staging loader. Every phase is idempotent and keyed off the
-    so a re-run resumes; the state file carries what the staging slot held."""
+    actual flash state, so a re-run after any interruption resumes; the
    state file carries the bytes the staging slot held."""
    info = loader.info
    image = loader_image(path)
    for warning in update_preflight(image, info, fuse_bytes):
        print(f"note: {warning}")
    update = image_info(image)  # the preflight proved it is there
    verbose(f"installing pureboot {update.version} over pureboot {info.version}")
    staged = staging_content(image, info)
-    resident = bytes(image) + bytes([0xFF] * (SLOT - len(image)))
+    resident = bytes(image) + bytes([0xFF] * (info.slot - len(image)))
    page = info.page
    state = UpdateState(state_path)
@@ -1038,32 +822,38 @@ def op_update_loader(loader, wait, path, state_path, fuse_bytes):
        verbose(f"saving the staging slot to {state_path}")
    state.load_or_save(loader)
-    # A loader already sitting whole in the staging slot IS the staging copy:
+    # Install the staging copy — unless a loader already sits whole in the
-    # rewriting it would only meet its own running-slot guard. Any pureboot
+    # staging slot (a build programmed there by hand): that copy IS the
-    # with the device's info block serves, since a staged copy only streams
+    # installed staging copy, and rewriting it would only trip its own
-    # pages. "Whole" needs both checks — the block where every image carries
+    # running-slot guard on the composed through-word. Any pureboot with
-    # it and matching byte for byte, and the slot unchanged since this update
+    # the device's own info block serves — the staged copy just streams
-    # began, so a half-written install takes the path below instead.
+    # pages, so an older build installs a newer resident all the same. Two
-    current = loader.read_flash(info.stage, SLOT)
+    # checks make "already a loader" mean a *complete* one: the block must
-    # The whole slot is searched: a loader's stamp sits wherever its image put
+    # sit where every image carries it (within the slot's first 256 bytes
-    # it, which is the end of the code on pureboot 5 and the front of it
+    # — the build's position lint), matching the device's block byte for
-    # before that.
+    # byte, and the slot must be unchanged since this update began (the
-    staged_loader = image_info(current)
+    # state file's snapshot) — a resumed, half-written install differs
    # from its snapshot and takes the install path below, which completes
    # it page by page.
    current = loader.read_flash(info.stage, info.slot)
    staged_loader = image_info(current[:268])
    if staged_loader is not None and staged_loader.raw == info.raw and current == state.staging:
        print("staging slot already holds a loader — left in place")
    else:
-        # Where the staging slot starts at address 0 (the 1 KB tiny13s) its
+        # On a chip whose staging slot starts at address 0 (the 1 KB
-        # first page carries the reset vector, so it goes last: until then a
+        # tiny13s), its first page carries the reset vector: written last,
-        # reset still reaches the old resident.
+        # so any earlier interruption still resets into the old resident,
-        order = list(range(0, SLOT, page))
+        # and from then on resets enter the staging copy.
        order = list(range(0, info.slot, page))
        if info.stage == 0:
            order = order[1:] + [0]
        if write_differing(loader, info.stage, staged, order, label="staging copy"):
            print(f"staging copy installed at {info.stage:#06x}")
-    # Enter it and let it rewrite the resident. Where a patched reset vector
+    # Enter it and let it rewrite the resident slot. Where a patched reset
-    # routes through the resident, word 0 is re-aimed at the staging copy for
+    # vector routes through the resident (a tiny with the staging slot away
-    # the rewrite, so a power loss mid-rewrite still resets into a loader.
+    # from page 0), word 0 is re-aimed at the staging copy around the
    # rewrite, so a power failure mid-rewrite still resets into a loader.
    verbose(f"entering the staging copy at {info.stage:#06x}")
    loader.enter_copy(info.stage, wait)
    redirect = info.patch_vector and info.stage != 0
@@ -1081,19 +871,20 @@ def op_update_loader(loader, wait, path, state_path, fuse_bytes):
    if redirect:
        verbose("word 0 restored")
        write_differing(loader, 0, state.page0)
-    order = list(range(0, SLOT, page))
+    order = list(range(0, info.slot, page))
    if info.stage == 0:
        order = [0] + order[1:]
    write_differing(loader, info.stage, state.staging, order, label="staging restore")
    state.discard()
-    print(f"loader updated: pureboot {update.version}, {len(image)} B at {info.base:#06x}, staging region restored")
+    print(f"loader updated: {len(image)} B at {info.base:#06x}, staging region restored")
 def check_walk_region(pages, info, fuse_bytes, force):
-    """BOOTRST programmed below the loader means reset reaches it only by
+    """With BOOTRST programmed but targeting below the loader, reset reaches
-    walking across erased flash; application data in that span would divert
+    the loader only by walking across erased flash from the boot-section
-    reset into itself. Needs the fuses (--fuses or --assume-fuses)."""
+    start; application data in that span would divert reset into itself.
    Only checkable when the fuses are known (--fuses or --assume-fuses)."""
    if info.patch_vector or fuse_bytes is None:
        return
    bootrst, bls_start = mega_boot(info, fuse_bytes)
@@ -1112,9 +903,10 @@ def check_walk_region(pages, info, fuse_bytes, force):
 def op_erase_flash(loader):
-    """0xff over the application area, descending where the reset vector is
+    """0xff over the whole application area. Descending on a patched-vector
-    patched: page 0 goes last, so an interrupted erase still resets into the
+    chip: page 0 — the patched reset vector — goes last, so an interrupted
-    loader — and once it is gone, the erased walk reaches it anyway."""
+    erase still resets into the loader, and once it is gone the whole area
    is erased and the reset walk reaches the loader anyway."""
    blank = bytes([0xFF] * loader.info.page)
    addresses = range(0, loader.info.base, loader.info.page)
    with Progress("erase", len(addresses)) as bar:
@@ -1150,10 +942,11 @@ def op_flash(loader, path, erase, verify, fuse_bytes=None, force=False):
 def verify_pages(loader, pages, repair=False):
-    """Read every page back and compare. With `repair`, a mismatch is
+    """Read every page back and compare. With `repair`, a mismatched page is
-    rewritten and re-read up to RETRIES times first: a page filled over a
+    rewritten and re-read, up to RETRIES times before it is raised: a page
-    dirty SPM buffer takes stale words, and the write that took them cleared
+    filled over a dirty SPM buffer takes stale words, and the write that took
-    the buffer, so one rewrite settles it. Anything still wrong is not that."""
+    them cleared the buffer, so one rewrite settles it. Anything still wrong
    after three is not that, and stops the run."""
    repaired = 0
    with Progress("verify", len(pages)) as bar:
        for address in sorted(pages):
@@ -1231,37 +1024,6 @@ def op_read_eeprom(loader, path):
    print(f"read EEPROM: {len(data)} B -> {path}")
 def _require_unified(loader, what):
    if not loader.unified:
        raise Error(f"{what} needs pureboot {UNIFIED_LOADER} or later; this loader is {loader.info.version}")
 def _peek_spec(spec):
    """ADDR[:N] — addresses and counts in any Python integer base."""
    address, _, count = spec.partition(":")
    return int(address, 0), int(count, 0) if count else 1
 def op_peek(loader, spec):
    _require_unified(loader, "--peek")
    address, count = _peek_spec(spec)
    data = loader.read_ram(address, count)
    for offset in range(0, len(data), 16):
        row = data[offset : offset + 16]
        text = "".join(chr(b) if 0x20 <= b < 0x7F else "." for b in row)
        print(f"{address + offset:#06x}  {row.hex(' '):<47}  {text}")
 def op_poke(loader, spec):
    _require_unified(loader, "--poke")
    address, _, payload = spec.partition(":")
    if not payload:
        raise Error("--poke needs ADDR:HEX, for example 0x200:deadbeef")
    data = bytes.fromhex(payload.replace(" ", ""))
    loader.write_ram(int(address, 0), data)
    print(f"poke: {len(data)} B at {int(address, 0):#06x}")
 def op_fuses(loader):
    low, lock, extended, high = loader.read_fuses()
    print("fuses:")
@@ -1290,14 +1052,9 @@ def main():
    parser = argparse.ArgumentParser(
        description="pureboot host tool", epilog="operations run in the order listed above"
    )
    parser.add_argument("--version", action="version", version=f"%(prog)s {VERSION} "
                        f"(speaks pureboot {OLDEST_LOADER}..{NEWEST_LOADER})")
    parser.add_argument("--port", required=True, help="serial device: COM6, /dev/ttyUSB0, or a simavr pty")
    parser.add_argument("--baud", type=int, default=115200, help="115200 mega, 57600 tinies")
    parser.add_argument("--wait", type=float, default=30.0, help="seconds to keep knocking")
    parser.add_argument("--autobaud", action="store_true",
                        help="drive an autobaud loader: send the 0xC0 calibration pulse and a single "
                             "knock, and take geometry from the signature (no clock/baud baked in)")
    parser.add_argument("--info", action="store_true", help="print the device info block")
    parser.add_argument("--fuses", action="store_true", help="read the fuse and lock bytes")
    parser.add_argument("--update-loader", metavar="FILE", help="replace the loader with this pureboot binary")
@@ -1313,10 +1070,6 @@ def main():
    parser.add_argument("--eeprom", metavar="FILE", help="program the EEPROM (bin or ihex)")
    parser.add_argument("--read-eeprom", metavar="FILE", help="dump the EEPROM")
    parser.add_argument("--verify-eeprom", metavar="FILE", help="compare EEPROM against an image")
    parser.add_argument("--peek", metavar="ADDR[:N]", help="read N bytes of data space (SRAM, registers, "
                                                          "I/O) — pureboot 5 and later")
    parser.add_argument("--poke", metavar="ADDR:HEX", help="write hex bytes into data space — "
                                                          "pureboot 5 and later")
    parser.add_argument("--force", action="store_true", help="override refusable safety checks")
    parser.add_argument("--stay", action="store_true", help="leave the loader in its session")
    parser.add_argument("-v", "--verbose", action="store_true",
@@ -1339,7 +1092,7 @@ def main():
    verbose(f"{args.port}: {args.baud} Bd 8N1, DTR/RTS asserted")
    try:
        loader = Loader(port)
-        info = loader.connect_autobaud(args.wait) if args.autobaud else loader.connect(args.wait)
+        info = loader.connect(args.wait)
        if args.info:
            print("device:")
            for line in info.lines():
@@ -1368,10 +1121,6 @@ def main():
            op_read_eeprom(loader, args.read_eeprom)
        if args.verify_eeprom:
            op_verify_eeprom(loader, args.verify_eeprom)
        if args.poke:
            op_poke(loader, args.poke)
        if args.peek:
            op_peek(loader, args.peek)
        if args.stay:
            print("loader stays in its session (reset to leave)")
        else:
--- a/test/check_pi.py
+++ b/test/check_pi.py
@@ -1,75 +1,53 @@
 #!/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):
+    address = int(info[0].split()[0], 16)
-        fields = line.split()
+    offset = address - text_start
-        if len(fields) < 6 or not fields[0].isdigit():
+    if not 0 <= offset < 256:
-            continue
+        print(f"FAIL: info block at image offset {offset:#x}, must sit in the first 256 bytes")
-        name, size = fields[1], int(fields[2], 16)
+        sys.exit(1)
        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
@@ -66,10 +66,9 @@ struct link {
 	}
 	[[noreturn]] static void idle()
 	{
-		// 'L' hands back to the loader in the top slot — 512 bytes on every
+		// 'L' hands back to the loader at the top slot — 512 bytes, or the
-		// chip. The jump takes a word address, which is what makes the
+		// 1 KiB the >64 KiB chips use.
-		// >64 KiB chips' entry reachable through a 16-bit pointer at all.
+		constexpr std::uint32_t slot = avr::hw::db.mem.flash_size > 65536 ? 1024 : 512;
 		constexpr std::uint32_t slot = 512;
 		for (;;) {
 			auto command = tx_t::read_blocking();
 			if (command == 'L')
--- 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,13 +1,15 @@
 #!/usr/bin/env python3
-"""Dirty-page-buffer acceptance test: with no discard in the loader, a page
+"""Dirty-page-buffer acceptance test: the loader carries no buffer discard,
-filled over words an earlier writer left takes those instead. The whole
+so a page filled over words an earlier writer left behind programs those
-contract is asserted — a bare verify sees the corruption, the repairing
+instead. This asserts the whole contract — the corruption is real and a bare
-verify fixes it in one rewrite, and it stays fixed.
+verify sees it, the repairing verify fixes it in one rewrite (the write that
 took the stale words auto-erased the buffer), and it stays fixed.
-The state is reached the one way the loader cannot prevent: an application
+The state is reached the way the loader cannot prevent: an application
-dirties the buffer and jumps in with no reset between. Boot-sectioned megas
+dirties the buffer and jumps in with no reset between. Real boot-sectioned
-forbid that outright (SPM runs only from the boot section, Atmel-8271 §26.2),
+megas forbid that outright — SPM executes only from the boot section
-but simavr dispatches SPM from anywhere, which is what makes it constructible.
+(Atmel-8271 §26.2) — but simavr dispatches SPM from anywhere, which is what
 makes the path constructible at all.
 Usage: pbdirty.py <device_bin> <pureboot_elf> <mcu> <hz> <base_hex> <page>
                  <baud> <app_bin> <tool_py> <workdir>
--- a/test/pbrehome.py
+++ b/test/pbrehome.py
@@ -1,13 +1,19 @@
 #!/usr/bin/env python3
-"""Re-homing acceptance test: an image programmed somewhere other than its
+"""Re-homing acceptance test: a pureboot image programmed somewhere other
-canonical slot must still be a working loader, and the ordinary
+than its canonical top slot must still be a working loader —
 position-independent, guarding its accidental slot — and the ordinary
 --update-loader flow must put a build into the top slot from there.
-Two positions. Address 0, a raw .bin handed to a programmer: the staging
+Two positions are exercised. Address 0 (a raw .bin handed to a programmer,
-install and the word-0 redirect run from copies outside page 0's slot, so the
+which defaults to offset 0): the staging install and the word-0 redirect
-running-slot guard never blocks them. And the staging slot itself, where a
+both run from copies whose slots are not page 0's, so the running-slot
-loader already sitting there IS the staging copy — recognized by its embedded
+guard never blocks the flow. The staging slot itself: a loader already
-block and left in place, then streaming the new resident like any staged copy.
+sitting there IS the installed staging copy — the tool recognizes it by
 its embedded info block and leaves it in place instead of tripping the
 copy's own guard on the composed through-word — and that (older) copy
 streams the new resident like any staged copy. In both cases flashing an
 application through the healed resident overwrites the stale copy, vector
 surgery included, and the banner proves the launch.
 Usage: pbrehome.py <device_bin> <pureboot_elf> <update_bin> <mcu> <hz>
                   <base_hex> <page> <baud> <app_bin> <tool_py> <workdir>
@@ -84,7 +90,7 @@ def main():
    # 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
+    stage = base - 512
    rehome_from(pbsim, pb, device_bin, elf, hex(stage), hex(stage), update_bin, base, page, baud, app_bin, workdir,
                mcu, hz)
    print("re-home from the staging slot: converged")
--- 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>
@@ -81,7 +83,7 @@ def main():
        # 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" * (info.slot - len(image))
        pb.write_differing(loader, base, resident)
        back_info = loader.enter_copy(base, 25)
        if back_info.raw != resident_info:
--- a/test/pbtest.py
+++ b/test/pbtest.py
@@ -1,13 +1,15 @@
 #!/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]
-The optional link is the runner's -l spec (usart1, sw:B5,B1, ...), for a
+The optional link is the runner's -l spec (usart1, sw:B5,B1, ...) for a
 loader built off the chip's natural serial default.
 Exits 0 if every scenario passes.
 """
 import os
@@ -55,17 +57,11 @@ def main():
    # 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
+    word_flash = base + 512 > 0x10000
    # 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 & 0xFF])
        + bytes([wire_base & 0xFF, wire_base >> 8, eeprom_size & 0xFF, eeprom_size >> 8])
        + bytes([flags])
    )
@@ -75,24 +71,16 @@ def main():
        # Session 1: knock from reset, identify, program everything, stay.
        out = pbsim.run_tool(tool, device.pty, baud, "--info", "--fuses", "--flash", app_bin,
                             "--eeprom", ee_path, "--stay")
-        for needed in ("version", "signature", "fuses", "verify:", "stays"):
+        for needed in ("signature", "fuses", "verify:", "stays"):
            if needed not in out:
                fail(f"session 1 output lacks {needed!r}")
-        # Session 2: reconnect into the live session, verify, dump, 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.
        probe = "c0ffee"
        out = pbsim.run_tool(tool, device.pty, baud, "--verify-flash", app_bin, "--verify-eeprom", ee_path,
-                             "--read-flash", read_flash, "--read-eeprom", read_eeprom,
+                             "--read-flash", read_flash, "--read-eeprom", read_eeprom, "--stay")
                             "--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:
@@ -113,30 +101,7 @@ def main():
        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":
@@ -157,7 +122,7 @@ def main():
    # loader, the trampoline on the application's own entry (patched-vector
    # chips only — a boot-sectioned mega's word 0 stays the application's).
    if patch:
-        flash_words = (base + pb.SLOT) // 2
+        flash_words = (base + 512) // 2
        app = open(app_bin, "rb").read()
        word0 = flash_true[0] | (flash_true[1] << 8)
        if rjmp_decode(word0, 0, flash_words) != base // 2:
--- a/test/pbupdate.py
+++ b/test/pbupdate.py
@@ -1,12 +1,17 @@
 #!/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 boot-sectioned megas run the BOOTRST-unprogrammed profile (reset boots
-the application, whose 'L' is the application-owned loader entry — with
+the application; the fixture application's 'L' jump is the application-owned
--assume-fuses standing in for the fuse read simavr cannot model.
+loader entry), with --assume-fuses standing in for the fuse read simavr
 cannot model. The patched-vector chips — the tinies and the m48s — reset
 into a loader at every phase by construction: the t13a because its staging
 slot carries the reset vector itself, the others through the word-0 redirect
 the tool plants around the resident rewrite.
 Usage: pbupdate.py <device_bin> <pureboot_elf> <update_elf> <mcu> <hz>
                   <base_hex> <page> <baud> <app_bin> <tool_py> <workdir>
@@ -45,7 +50,7 @@ def assumed_fuses(pb, image):
    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])
+    bits = min((b for b in ladder if ladder[b] * 2 >= 2 * info.slot), key=lambda b: ladder[b])
    fuses = bytearray((0xFF, 0xFF, 0xFF, 0xFF))
    fuses[which] = 0xF8 | (bits << 1) | 1
    return bytes(fuses)
@@ -88,13 +93,16 @@ def main():
    # The m48s are megas without a boot section: patched vector, no fuse
    # preflight, and the same reset-to-0 the tinies get.
    patch = not mega or mcu.startswith("atmega48")
    # Word-addressed (>64 KiB) chips use the 1 KiB slot; their loader base
    # itself sits beyond the 16-bit byte space — the 644's base + slot only
    # touches the 64 KiB boundary and stays byte-addressed.
    slot = 1024 if base >= 0x10000 and mega else 512
    reset_hex = "0" if mega else None  # the boot-sectioned mega runs BOOTRST-unprogrammed here
    sys.path.insert(0, os.path.dirname(os.path.abspath(tool)))
    sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
    import pbsim
    import pureboot as pb
    slot = pb.SLOT
    os.makedirs(workdir, exist_ok=True)
    objcopy = os.environ.get("PB_OBJCOPY", "avr-objcopy")
    images = {}
--- a/test/pureboot_device.c
+++ b/test/pureboot_device.c
@@ -182,16 +182,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));
-		tx_shift = (uint8_t)((tx_shift >> 1) | (tx_level ? 0x80 : 0));
+	if (++tx_bit < 8)
 		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;
--- a/test/test_handshake.py
+++ b/test/test_handshake.py
@@ -1,104 +0,0 @@
 #!/usr/bin/env python3
 """Host-tool activation handshake: it must not hang on a flooding target.
 `_handshake` drains the line after it sees a prompt, to absorb a real loader's
 trailing bytes before it asks for the identity. That drain must be bounded: a
 target that never falls quiet — a board stuck in a reset loop presents exactly
 this, ~60 reboots/s of UART-reset garbage in which a stray 0x2b reads as a
 prompt — otherwise spins the tool forever. Regression for that hang, plus a
 control that a well-behaved loader still connects.
 Stdlib only; run with `python test/test_handshake.py`. Not yet wired into ctest.
 """
 import importlib.util
 import pathlib
 import threading
 import time
 PB = pathlib.Path(__file__).resolve().parents[1] / "pureboot" / "pureboot.py"
 _spec = importlib.util.spec_from_file_location("pureboot", PB)
 pb = importlib.util.module_from_spec(_spec)
 _spec.loader.exec_module(pb)
 P = F = 0
 def check(name, ok):
    global P, F
    P, F = P + (1 if ok else 0), F + (0 if ok else 1)
    print(f"  [{'PASS' if ok else 'FAIL'}] {name}")
 class FloodPort:
    """A line that never falls quiet: read_available always returns bytes, and
    they contain a prompt. No identity ever completes."""
    def flush_input(self):
        pass
    def write(self, data):
        pass
    def read_available(self, wait):
        time.sleep(0.01)  # a real read waits; keep the busy loop off a core
        return b"+\x00\xff"
    def read_exact(self, count, timeout):
        raise pb.Error("no identity")
 class LoaderPort:
    """A well-behaved pureboot 5: one prompt to the knock, then quiet, then the
    slim identity (version 5 + m328p signature) and a closing prompt."""
    def __init__(self):
        self.reads = self.exacts = 0
    def flush_input(self):
        pass
    def write(self, data):
        pass
    def read_available(self, wait):
        self.reads += 1
        return b"+" if self.reads == 1 else b""  # prompt once, then settle quiet
    def read_exact(self, count, timeout):
        self.exacts += 1
        return b"\x05\x1e\x95\x0f" if self.exacts == 1 else b"+"  # identity, then prompt
 def terminates(port, wait, budget):
    """Run connect_autobaud in a thread; True if it returns/raises within
    `budget` seconds rather than hanging."""
    done = threading.Event()
    def run():
        try:
            pb.Loader(port).connect_autobaud(wait)
        except Exception:
            pass
        finally:
            done.set()
    threading.Thread(target=run, daemon=True).start()
    return done.wait(budget)
 def main():
    # the hang: a flooding target must not spin the drain forever. With wait=0.5
    # the whole handshake has to give up well inside a few seconds.
    check("flooding target: handshake terminates, drain is bounded",
          terminates(FloodPort(), wait=0.5, budget=4.0))
    # the control: a real loader still connects and reads identity.
    info = pb.Loader(LoaderPort()).connect_autobaud(2.0)
    check("well-behaved loader still connects (version 5)", info.version == 5)
    print(f"\n  {P} passed, {F} failed")
    return 1 if F else 0
 if __name__ == "__main__":
    raise SystemExit(main())
--- 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,14 @@ 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, signature=(0x1E, 0x93, 0x0B), word_flash=False):
    scale = 2 if word_flash else 1
    wire_base = base // scale
    flags = (1 if patch else 0) | (2 if word_flash else 0)
-    # The EEPROM size comes from the signature, as it must: pureboot 5 derives
+    raw = bytes((0x50, 0x42, 1, *signature, page & 0xFF, wire_base & 0xFF, wire_base >> 8,
-    # the whole geometry from the signature rather than sending it, so a
+                 0, 2, flags))
    # 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
@@ -61,21 +55,6 @@ def main():
    tiny = info_of(pb, 0x1E00, 64, True, 0x2000)
    mega = info_of(pb, 0x7E00, 128, False, 0x8000, signature=(0x1E, 0x95, 0x0F))
    # Versioning: the block's third byte is the loader's version, and the tool
    # speaks a window of them. Every version in the window decodes, so an older
    # deployed loader stays usable; one above the window is refused by name,
    # 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/
@@ -100,7 +79,9 @@ def main():
        ((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,
+        # Word-addressed chips carry the 1 KiB slot (their smallest boot sector).
        slot = 1024 if flash > 0x10000 else 512
        chip = info_of(pb, flash - slot, 128 if flash < 0x20000 else 0, False, flash,
                       signature=signature, word_flash=flash > 0x10000)
        for bits, start in ladder.items():
            fuses = bytearray((0xFF, 0xFF, 0xFF, 0xFF))
@@ -113,12 +94,10 @@ def main():
            if prog or at != start:
                fail(f"mega_boot {signature[1]:02x}{signature[2]:02b} unprogrammed: {prog} {at:#07x}")
-    # Word-addressed info decode: the 1284P's base and page ride the wire
+    # Word-addressed info decode: the 1284P's base/page ride the wire scaled,
-    # scaled — a 17-bit base halved into the block's two bytes, a 256-byte page
+    # and its slot is 1 KiB.
-    # spelled 0 — and its slot is the same 512 bytes as everywhere else, so its
+    big = info_of(pb, 0x1FC00, 0, False, 0x20000, signature=(0x1E, 0x97, 0x05), word_flash=True)
-    # staging slot lands inside the 1 KiB minimum boot section.
+    if big.page != 256 or big.base != 0x1FC00 or big.stage != 0x1F800 or big.slot != 1024:
    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
@@ -168,24 +147,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
@@ -226,15 +194,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.
@@ -291,68 +250,6 @@ def main():
    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
@@ -2,14 +2,12 @@
 # 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
+# full matrix). LIBAVR_ROOT must point at the libavr checkout.
 # 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; }
+[[ "$1" == "--full" ]] && { full=1; shift; }
 CHIPS=(attiny13 attiny13a attiny25 attiny45 attiny85
       atmega8 atmega8a atmega16 atmega16a atmega32 atmega32a