pureboot 3: a 512-byte slot on every chip, the 1284s included

The word-addressed 1284s were the one family deploying in a 1 KiB slot, because the far-flash machinery (ELPM reads, RAMPZ page commands, a word-addressed wire) did not fit 512 B. It does now: 478 B stock, 494 B in the heaviest configuration the build can produce. They take the 644s' geometry, where the smallest boot section holds the resident slot and its staging slot together. The loader's version goes to 3; the host tool did not change, so its own version stays 2 and only the window it speaks widens. Most of the saving is one restructure. The info block and a flash read are the same act, so giving all four streamed commands one address-and-count path leaves exactly one call site for the flash streamer: it inlines into the never-returning command loop and its 24-bit cursor stops being saved and restored around every transmit. Around it, the ack byte moved out of line, the wire's byte pair is bit_cast into the word it already is, the fuse loop ends on its count, the info block's in-slot offset is taken as the one-byte relocation it is, and -fno-expensive-optimizations gives way to -fno-move-loop-invariants -fno-tree-ter. Every chip shrank 14-18 B. The size matrix grew the axes it was missing: the USART1 instance across the whole clock ladder, and the shape a slow baud gives a software UART — past 255 delay iterations libavr takes the 16-bit delay loop, which the ladder default never selects and which was 4 B over the 1284's slot the first time it was built. The protocol fixture stopped deriving the loader entry from the flash size; on the 1284s it had been jumping a slot low and reaching the loader only because erased flash walked it up. Docs and comments were consolidated across the port in the same pass: the README carries a per-chip size table instead of prose, and prose that restated the code is gone — 190 lines, no behaviour with it. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-07-22 19:02:59 +02:00
parent 6f3eb06233
commit 8f106b636d
13 changed files with 594 additions and 752 deletions
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -231,12 +231,13 @@ if(PROJECT_IS_TOP_LEVEL)
 	endif()
 	# The size matrix: every configuration axis that could move the image
-	# size — the serial backend (different code), the clock and its ladder
+	# size — the serial backend (different code), the USART instance
-	# baud (different constants and divisor shapes), the USART instance
+	# (different registers), the clock (different constants), and the baud
-	# (different register class) — each combination must still fit the
+	# through the two shapes its bit timing takes — each combination must
-	# chip's slot budget. Pins are size-neutral (port and bit are immediate
+	# still fit the chip's slot budget. Pins are size-neutral (port and bit
-	# operands) and the timeout is a constant, so neither adds an axis. The
+	# are immediate operands) and the timeout is a constant, so neither adds
-	# stock build is one point of this matrix and already has its test.
+	# an axis. The stock build is one point of this matrix and already has
 	# its test.
 	function(pureboot_size_variant name)
 		pureboot_add_loader(${name} ${ARGN})
 		add_test(NAME ${name}.size
@@ -260,11 +261,26 @@ if(PROJECT_IS_TOP_LEVEL)
 		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()
 	if(PUREBOOT_HAS_USART1)
 		pureboot_size_variant(pureboot_usart1 USART 1)
 	endif()
 	# The baud axis, whose one size-bearing shape the ladder never picks: a
 	# software UART spins out each bit with _delay_loop_1 while the count
 	# fits a byte and with the 16-bit _delay_loop_2 beyond it, two words more
 	# setup at every one of its five sites — the largest image the
 	# configuration space produces. The ladder default takes the *fastest*
 	# rate a clock reaches, which always lands in the byte, so the wide form
 	# needs the slowest ladder rate against the fastest clock to appear. The
 	# hardware USART has no such shape: its baud is a divisor constant, and
 	# the ladder's U2X solutions are already its larger form.
 	list(GET _matrix_clocks -1 _matrix_top_hz)
 	pureboot_size_variant(pureboot_sw_wide CLOCK ${_matrix_top_hz} BAUD 9600 SERIAL software)
 	# One configured deployment end to end — a real board's shape rather
 	# than the stock assumption: the ATmega328P on its shipped 1 MHz fuses,
 	# the software UART on hand-picked pins (TX = PB1, RX = PB5), the ladder
--- a/pureboot/CMakeLists.txt
+++ b/pureboot/CMakeLists.txt
@@ -1,27 +1,16 @@
-# pureboot as a consumable CMake unit: the per-chip geometry, the default
+# pureboot as a consumable CMake unit: the per-chip geometry, the default baud
-# baud ladder, and pureboot_add_loader() — the one way a loader target is
+# ladder, and pureboot_add_loader() — the one way a loader target is created.
-# created, both by this port's own build and by a downstream project. A
+# A downstream project brings its usual libavr setup (the `libavr` target and
 # downstream project brings its usual libavr setup (the `libavr` target and
 # the LIBAVR_MCU toolchain preset), adds this directory, and states its
-# deployment:
+# deployment; every argument is optional (README.md):
 #
 #   add_subdirectory(bootloader/pureboot)
 #   pureboot_add_loader(myboot CLOCK 1000000 SERIAL software TX pb1 RX pb5)
 #
 # Every argument is optional — CLOCK defaults to the family assumption
 # below, BAUD to the fastest standard rate the clock reaches within 2.5 %
 # (the ladder), SERIAL to the chip's hardware USART where it has one
 # (`hardware`/`software` force a backend, USART 1 picks the second
 # instance), RX/TX to pb0/pb1 for the software UART, TIMEOUT to 8 s.
 # Infeasible picks fail the build by name: libavr's baud-error and
 # software-UART cycle-floor static asserts re-check whatever is passed.
-# Per-family geometry: flash/page/EEPROM sizes and the linker wrap the PC
+# Per-family geometry, deployment defaults, and the linker wrap the PC modulo
-# modulo needs, the loader slot (each chip's smallest boot sector — 1 KiB on
+# needs. The slot is 512 bytes on every chip. The USART flags mirror the
-# the word-addressed 1284s), and the deployment defaults (crystal assumption
+# hardware inventory the loader's own static asserts check — the plain 644 is
-# on the megas, calibrated RC on the tinies). The USART flags mirror the
+# the x4 family's one single-USART die (Atmel-2593).
 # 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?$")
@@ -91,10 +80,9 @@ 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: plain LPM reaches everything,
+	# 64 KiB is exactly the 16-bit byte space, so plain LPM still reaches
-	# and the smallest boot section (1 KiB) holds the loader and its staging
+	# everything and the wire stays byte-addressed. The plain 644 is the
-	# slot together (see README.md). The plain 644 is the family's one
+	# family's one single-USART die.
 	# single-USART die.
 	set(_pb_flash 65536)
 	set(_pb_wrap -Wl,--pmem-wrap-around=64k)
 	set(_pb_page 256)
@@ -104,33 +92,25 @@ elseif(LIBAVR_MCU MATCHES "^atmega644(a|p|pa)?$")
 		set(_pb_has_usart1 1)
 	endif()
 elseif(LIBAVR_MCU MATCHES "^atmega1284p?$")
-	# 128 KiB: wire flash addresses are word addresses, reads go through
+	# 128 KiB: wire addresses are words, reads go through ELPM, and the PC's
-	# ELPM, and the PC's modulo wrap exceeds what --pmem-wrap-around models.
+	# modulo wrap exceeds what --pmem-wrap-around models.
 	# The slot is 1 KiB — this chip's own smallest boot sector; the far
 	# machinery cannot fit 512 B (see README.md).
 	set(_pb_flash 131072)
 	set(_pb_wrap "")
 	set(_pb_page 256)
 	set(_pb_hz 16000000)
 	set(_pb_eeprom 4096)
 	set(_pb_slot 1024)
 	set(_pb_limit 1024)
 	set(_pb_has_usart1 1)
 else()
 	message(FATAL_ERROR "pureboot: no geometry for ${LIBAVR_MCU}")
 endif()
-if(NOT DEFINED _pb_slot)
+set(_pb_slot 512)
 	set(_pb_slot 512)
 endif()
 math(EXPR _pb_base "${_pb_flash} - ${_pb_slot}")
 math(EXPR _pb_base_hex "${_pb_base}" OUTPUT_FORMAT HEXADECIMAL)
 # Patched-vector chips hand over through the trampoline word below the slot,
 # which is also the slot's own last word — their budget is slot − 2.
 if(LIBAVR_MCU MATCHES "^atmega" AND NOT LIBAVR_MCU MATCHES "^atmega48")
 	set(_pb_app 0)
 	if(NOT DEFINED _pb_limit)
 	set(_pb_limit ${_pb_slot})
 	endif()
 else()
 	math(EXPR _pb_app "${_pb_base} - 2")
 	math(EXPR _pb_limit "${_pb_slot} - 2")
@@ -166,12 +146,11 @@ set(PUREBOOT_HAS_USART ${_pb_has_usart} PARENT_SCOPE)
 set(PUREBOOT_HAS_USART1 ${_pb_has_usart1} PARENT_SCOPE)
 set(PUREBOOT_SIM_MCU ${_pb_sim_mcu} PARENT_SCOPE)
-# The fastest standard rate the clock reaches within 2.5 % — the same
+# The fastest standard rate the clock reaches within 2.5 %, by the same
-# best-of-U2X-and-plain divisor search libavr's solve_baud runs, so a
+# best-of-U2X-and-plain divisor search libavr's solve_baud runs, so a default
-# default never trips the compile-time error it is checked against. A
+# never trips the compile-time error it is checked against. A software build
-# software build additionally requires the polled receiver's 100-cycles-a-bit
+# also needs the polled receiver's 100-cycles-a-bit floor: at low clocks the
-# floor (its own static assert): at low clocks the U2X divisor still reaches
+# U2X divisor reaches rates the bit-banged sampler cannot.
 # rates the bit-banged sampler cannot, so the backend gates the ladder.
 function(pureboot_default_baud clock software outvar)
 	foreach(baud 115200 57600 38400 19200 9600)
 		math(EXPR _cycles "${clock} / ${baud}")
@@ -203,11 +182,10 @@ endfunction()
 #                     [SERIAL auto|hardware|software] [USART <n>]
 #                     [RX <pin>] [TX <pin>] [TIMEOUT <s>])
 #
-# Creates the loader target plus its flashable images (<name>.hex for a
+# The loader target plus its flashable images (<name>.hex for a programmer,
-# programmer, <name>.bin for --update-loader) and stamps the resolved
+# <name>.bin for --update-loader). The resolved deployment is stamped on the
-# deployment on the target: the PUREBOOT_HZ, PUREBOOT_BAUD and PUREBOOT_LINK
+# target as PUREBOOT_HZ / PUREBOOT_BAUD / PUREBOOT_LINK (the link spelled
-# properties (the link as usart0/usart1/sw:<RX>,<TX> — what a test harness
+# usart0, usart1 or sw:<RX>,<TX>) — what a test harness speaks to it with.
 # needs to speak to the build).
 function(pureboot_add_loader name)
 	cmake_parse_arguments(PB "" "CLOCK;BAUD;SERIAL;USART;RX;TX;TIMEOUT" "" ${ARGN})
 	if(PB_UNPARSED_ARGUMENTS)
@@ -272,8 +250,7 @@ function(pureboot_add_loader name)
 				endif()
 			endforeach()
 			set(_serial_defines PUREBOOT_SOFT_SERIAL PUREBOOT_RX=${PB_RX} PUREBOOT_TX=${PB_TX})
-			# The link spec a test harness drives a GPIO bridge with: sw:<RX>,<TX>
+			# sw:<RX>,<TX> as port letter and bit, upcased.
 			# as the port letter and bit, the loader's own pin naming upcased.
 			string(SUBSTRING ${PB_RX} 1 2 _rx_pin)
 			string(SUBSTRING ${PB_TX} 1 2 _tx_pin)
 			string(TOUPPER "sw:${_rx_pin},${_tx_pin}" _link)
@@ -294,21 +271,22 @@ function(pureboot_add_loader name)
 	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, worth ~40 B on every chip and
+	# Codegen shaping for the loader TU only, worth 14–36 B depending on the
-	# what carries the far-flash 1284 build under 512. At -Os GCC otherwise
+	# chip. At -Os GCC otherwise rewrites the byte-stream loops' counters into
-	# rewrites the byte-stream loops' counters into end-pointer forms that
+	# end-pointer forms that cost registers (-fno-ivopts,
-	# cost registers (-fno-ivopts, -fno-split-wide-types), leaves register
+	# -fno-split-wide-types), leaves register pressure on the table with the
-	# pressure on the table with the default allocator
+	# default allocator (-fira-algorithm=priority), and keeps loop-invariant
-	# (-fira-algorithm=priority), and spends bytes on rewrites a
+	# immediates and expression temporaries in registers
-	# straight-line loader gains nothing from.
+	# (-fno-move-loop-invariants, -fno-tree-ter) — but every loop body here
 	# contains a call, so a register held across it costs more than the
 	# load-immediate it saves.
 	target_compile_options(${name} PRIVATE
-	    -fno-ivopts -fira-algorithm=priority -fno-expensive-optimizations -fno-split-wide-types)
+	    -fno-ivopts -fira-algorithm=priority -fno-move-loop-invariants -fno-tree-ter -fno-split-wide-types)
 	target_link_options(${name} PRIVATE -nostartfiles -Wl,--section-start=.text=${_base_hex}
 	                    -Wl,--defsym=pureboot_app=${_app} ${_wrap})
 	add_custom_command(TARGET ${name} POST_BUILD COMMAND ${CMAKE_SIZE} $<TARGET_FILE:${name}>)
-	# The ELF is a container (symbols, section headers), never flashed; the
+	# The ELF is a container, never flashed: .hex for a programmer, .bin (the
-	# flashable forms sit beside it: .hex for a programmer, .bin (the slot's
+	# slot's bare bytes) for --update-loader.
 	# 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
--- a/pureboot/README.md
+++ b/pureboot/README.md
@@ -2,46 +2,61 @@
 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), built for **every chip libavr
+(attributes and compiler flags allowed), **512 bytes on every chip libavr
-targets — all 37 — in 512 bytes each**: 434 B on the tiny13s, 438–442 B on
+targets — all 37**. The device speaks primitives; every composite — verify,
-the tiny25/45/85, 412–452 B across the megas, and 506 B on the
+erase, reset-vector surgery, updating the loader itself — lives in the host
-ATmega1284/1284P, whose far-flash machinery (ELPM reads, RAMPZ page commands,
+tool (`pureboot.py`).
 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
 read/write paths take wire addresses, the write guard protects the slot the
 code is *running* in (from the runtime return address), the info block is
-addressed from that same anchor, and the application jump is an indirect
+addressed from that same anchor, and the application jump is an indirect call
-call to an absolute entry. The identical binary therefore runs from any
+to an absolute entry. The identical binary therefore runs from any slot with
-slot with every command intact — which makes pureboot **its own staging
+every command intact, which makes pureboot **its own staging loader**: the
-loader**: the host installs the same binary one slot below the resident,
+host installs the same binary one slot below the resident, jumps into it, and
-jumps into it, and lets it rewrite the resident. The slot is 512 bytes
+lets it rewrite the resident.
-(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 largest image any of them produces is a
 software UART at a slow baud, which on the 1284s is 494 B, the tightest fit in
 the whole matrix at 18 B spare.
 | Chip | Flash | Loader at | Link | Size |
 |---|---|---|---|---|
 | ATtiny13, ATtiny13A † | 1 KiB | 0x0200 | software | 416 B |
 | ATtiny25 † | 2 KiB | 0x0600 | software | 420 B |
 | ATtiny45 † | 4 KiB | 0x0e00 | software | 424 B |
 | ATtiny85 † | 8 KiB | 0x1e00 | software | 424 B |
 | ATmega8, 8A | 8 KiB | 0x1e00 | USART0 | 396 B |
 | ATmega16, 16A | 16 KiB | 0x3e00 | USART0 | 400 B |
 | ATmega32, 32A | 32 KiB | 0x7e00 | USART0 | 400 B |
 | ATmega48, 48A, 48P, 48PA † | 4 KiB | 0x0e00 | USART0 | 414 B |
 | ATmega88, 88A, 88P, 88PA | 8 KiB | 0x1e00 | USART0 | 434 B |
 | ATmega168, 168A, 168P, 168PA | 16 KiB | 0x3e00 | USART0 | 438 B |
 | ATmega328, 328P | 32 KiB | 0x7e00 | USART0 | 438 B |
 | ATmega164A, 164P, 164PA | 16 KiB | 0x3e00 | USART0 | 438 B |
 | ATmega324A, 324P, 324PA | 32 KiB | 0x7e00 | USART0 | 438 B |
 | ATmega644, 644A, 644P, 644PA | 64 KiB | 0xfe00 | USART0 | 432 B |
 | ATmega1284, 1284P | 128 KiB | 0x1fe00 | USART0 | 478 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 1284s are the heaviest because they alone carry the far-flash machinery —
 ELPM reads, RAMPZ page commands, a word-addressed wire.
 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, resolved by the CMake function
+Every deployment axis is a build parameter of `pureboot_add_loader()` (in
-`pureboot_add_loader()` (in `pureboot/CMakeLists.txt`) — the one way a
+`pureboot/CMakeLists.txt`) — the one way a loader target is created, by this
-loader target is created, by this repo's own build and by a downstream
+repo's build and by a downstream project alike:
 project alike:
 | Argument | Meaning | Default |
 |---|---|---|
@@ -55,15 +70,14 @@ 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. 16 MHz lands 115200, 8 MHz 57600,
+receiver's 100-cycles-a-bit floor. Whatever is picked or overridden is
-1 MHz 9600. Whatever is picked or overridden is re-checked in the compile:
+re-checked in the compile: an infeasible combination, or a USART the chip does
-an infeasible clock/baud/backend combination, or a USART the chip does not
+not have, fails with a named static assert.
 have, fails with a named static assert.
-A downstream project brings its usual libavr setup (the `libavr` target,
+A downstream project brings its usual libavr setup (the `libavr` target, the
-the chip via the `LIBAVR_MCU` toolchain preset), consumes this directory,
+chip via the `LIBAVR_MCU` toolchain preset), consumes this directory, and
-and states its deployment — for example an ATmega328P on its shipped
+states its deployment — an ATmega328P on its shipped 1 MHz fuses with the
-1 MHz fuses with the software UART on hand-picked pins:
+software UART on hand-picked pins, say:
 ```cmake
 FetchContent_Declare(bootloader GIT_REPOSITORY git@git.blackmark.me:avr/bootloader.git GIT_TAG main)
@@ -74,57 +88,40 @@ 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
+`myboot.bin` (the self-update image), prints the size, and stamps the resolved
-resolved deployment on the target as the `PUREBOOT_HZ`, `PUREBOOT_BAUD`
+deployment on the target as the `PUREBOOT_HZ`, `PUREBOOT_BAUD` and
-and `PUREBOOT_LINK` properties — what a flashing script or test harness
+`PUREBOOT_LINK` properties — what a flashing script or test harness needs to
-needs to speak to the build. This exact example deployment runs the full
+speak to the build. This exact deployment runs the full protocol suite in CI
-protocol suite in CI (`pureboot.custom`).
+(`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 on the tinies and the boot-section-less m48s) — except a
+reset vector elsewhere) — except a watchdog reset, which hands straight to the
-watchdog reset, which hands straight to the application (the application
+application, since the application owns its watchdog and must clear WDRF
-owns its watchdog; it must clear WDRF itself, which also releases the
+itself.
 WDRF-forced WDE).
-The host then has one activation window per awaited byte to knock: `p` then
+The host then knocks `p` then `b`, each awaited byte under a fresh activation
-`b`. Each awaited byte gets a fresh window; any other byte is discarded and
+window; any other byte is discarded and awaited again, so line noise can delay
-awaited again (line noise cannot lock the loader, only delay it). A window
+the loader but never lock it. A window expiring on an idle line boots the
-expiring with an idle line boots the application.
+application.
-The window length is a compile-time constant — 8 s by default, another
+The window is a compile-time constant (`TIMEOUT`, 8 s by default), so the whole
-value via `pureboot_add_loader(... TIMEOUT <s>)` (the stock target keeps
+EEPROM belongs to the application — pureboot keeps no state of its own.
-the `PUREBOOT_TIMEOUT` cache variable) — so the whole EEPROM belongs to
+Re-timing a deployed loader is a self-update with a re-timed build.
 the application; pureboot never uses it for its own state. Re-timing a
 deployed loader is a self-update with a re-timed build (below).
 ## Session
 After the knock the loader stays in its command loop until `J` jumps away or
 the chip resets. Before reading each command it waits for any pending EEPROM
-write to finish and sends the prompt `+` (0x2b) — the prompt is therefore
+write and sends the prompt `+` (0x2b), which is therefore also the previous
-also the completion ack of the previous command. A session is: await `+`,
+command's completion ack. A session is: await `+`, send a command, read its
-send a command, read its reply, repeat.
+reply, repeat.
 On chips whose flash exceeds 64 KiB (the 1284s — info-block flag bit 1) the
 `R`/`W` flash addresses are **word** addresses; everywhere else they are byte
-addresses (the 644s' 64 KiB is exactly the 16-bit byte space and stays
+addresses (the 644s' 64 KiB is exactly the 16-bit byte space). EEPROM
-byte-addressed). EEPROM addresses are always bytes, counts always bytes.
+addresses and all counts are bytes.
 | Cmd | Arguments | Reply |
 |---|---|---|
@@ -137,101 +134,75 @@ byte-addressed). EEPROM addresses are always bytes, counts always bytes.
 | `J` | word address (16-bit) | `+`, then execution continues there |
 | other | — | ignored; the loop re-prompts (send a junk byte, await `+`, to resync) |
-`W` streams exactly one SPM page (size from the info block) into the buffer,
+`W` streams exactly one page-aligned SPM page (size from the info block) into
-then erases and programs; the address must be page-aligned. Pages inside the
+the buffer, then erases and programs — except pages inside the 512-byte slot
-512-byte slot the loader is *running* in are drained but never programmed — a
+the loader is *running* in, which are drained and left alone, so a broken host
-broken host cannot brick the running copy, and a staged copy may rewrite the
+cannot brick the running copy and a staged copy may rewrite the resident.
 resident slot.
-The loader never clears the SPM buffer before a fill, so **one `W` may
+The loader never clears the SPM buffer before a fill, so **one `W` may program
-program the wrong bytes, and the host is what fixes it**. The buffer is
+the wrong bytes, and the host is what fixes it**. The buffer is write-once per
-write-once per word until cleared, and two things leave words in it: a
+word until cleared, and two things leave words in it: a refused page, and —
-refused page (drained, never programmed) and — where SPM runs from anywhere,
+where SPM runs from anywhere, the tinies and the m48s — an application that
-the tinies and the m48s — an application that self-programmed before
+self-programmed before entering. The next `W` takes those stale words and
-entering. The next `W` takes those stale words, and clears them: a page write
+clears them, since a page write auto-erases the buffer (§26.2.1; §19.2 on the
-auto-erases the buffer (§26.2.1; §19.2 on the tinies), so repeating it
+tinies), so repeating it programs correctly. The host therefore verifies every
-programs correctly. The host therefore verifies every page it writes and
+page it writes and rewrites what comes back wrong (three retries, then it
-rewrites what comes back wrong (three retries, then it stops); a host that
+stops).
 programs without reading back cannot trust the first `W` after either event.
-`w` is host-paced: send the next byte only after the previous
+`w` is host-paced: send the next byte only after the previous byte's `+`. `F`
-byte's `+`. `F` returns the bytes in the hardware's Z order; on a chip
+returns the bytes in the hardware's Z order; on a chip without an extended
-without an extended fuse byte (the ATtiny13A) that slot carries no meaning.
+fuse byte that slot carries no meaning. Fuse *writing* does not exist — SPM
-Fuse *writing* does not exist: SPM reaches flash (and, on the mega, lock
+reaches flash and boot lock bits only.
 bits) only — fuse bytes are external-programming territory by hardware.
-`J` is the one control-transfer primitive: the host uses it to run the
+`J` is the one control-transfer primitive: it runs the application (word 0 or
-application (word 0 on the mega, the trampoline word on the tinies — both
+the trampoline word, both known from the info block) and moves between loader
-known from the info block) and to move between loader copies during a
+copies during a self-update. A jump to a slot's base re-enters that copy's own
-self-update. A jump to a loader slot's base re-enters that copy's own
+startup, which must then be knocked afresh.
 startup; it must then be knocked afresh.
 The info block (`b`):
 | Offset | Content |
 |---|---|
-| 0–2 | `'P'`, `'B'`, pureboot version (2) |
+| 0–2 | `'P'`, `'B'`, pureboot version (3) |
 | 3–5 | device signature |
 | 6 | SPM page size in bytes (0 means 256) |
 | 7–8 | loader base — application flash ends here (a word address when bit 1 is set) |
 | 9–10 | EEPROM size |
 | 11 | bit 0: host must patch the reset vector (no hardware boot section); bit 1: flash wire addresses are word addresses |
 Composites are the host's job: verify = read back and compare, erase =
 write `0xff` (per page for flash, per byte for EEPROM).
 ## Version
-The third byte of the info block is the **pureboot version** — the loader's
+The info block's third byte is the **pureboot version** — the loader's one
-one identity number, and the only way to tell what a deployed loader is.
+identity number, and the only way to tell what a deployed loader is. Nothing
-Nothing else is numbered: the wire protocol has no version of its own, a
+else is numbered: the wire protocol has no version, a pureboot version implies
-pureboot version implies its protocol, and the host tool is what holds that
+it, and the host tool holds that map. The tool states the window of loader
-map. It states the window of loader versions it speaks
+versions it speaks (`OLDEST_LOADER`/`NEWEST_LOADER` in `pureboot.py`), and a
-(`OLDEST_LOADER`/`NEWEST_LOADER` in `pureboot.py`); a version that changes
+version that changes the protocol becomes the new floor there. None has so
-the protocol becomes the new floor there. So far none has: pureboot 1 and 2
+far: 1 through 3 speak the identical session. A loader newer than the tool is
-speak the identical session, and a loader newer than the tool is refused by
+refused by name rather than decoded on the assumption that nothing moved.
 name rather than decoded on the assumption that nothing moved.
-The tool carries its own version, free to drift from the loader's:
+The tool carries its own version, free to drift; `--version` prints it and the
-`--version` prints both it and the window.
+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**:
+tests and objcopy, never flashed. The **.hex is the programmer artifact**: it
-it carries its own addresses and lands the loader in its top slot,
+carries its own addresses and lands the loader in its top slot, touching
-touching nothing else. The **.bin is the self-update image** — the slot's
+nothing else. The **.bin is the self-update image** — the slot's bare bytes.
 bare bytes with no addressing, which a programmer would put at address 0.
 On a boot-sectioned mega a copy at 0 is dead weight (SPM only executes
 from the boot section, so it cannot even heal itself — reflash the .hex);
 on the patched-vector chips it *runs* (the image is position-independent
 and reset enters word 0), reports its canonical geometry, and the ordinary
 `--update-loader` flow re-homes a build into the top slot from any
 position — the staging install and the word-0 redirect execute from
 copies outside page 0's slot, and a copy sitting in the staging slot
 itself is recognized as the installed staging copy and left in place (it
 streams the new resident like any staged copy, so an older build installs
 a newer one). `pureboot.rehome` is the acceptance test for both
 positions. Flashing the application afterwards overwrites the stale copy,
 vector surgery included.
-**Boot-sectioned megas**: program the loader at `flash − slot` with an
+**Boot-sectioned megas**: program the loader at `flash − 512` with an external
-external programmer. Every such mega has a BOOTSZ step whose boot section
+programmer. Every such mega has a BOOTSZ step whose boot section is exactly
-is exactly the loader slot — 512 B, the second-smallest step on the 8 KiB
+the 512-byte slot — the second-smallest step on the 8 KiB and 16 KiB chips,
-and 16 KiB chips (m8, m88, m16, m168, m164), the smallest on the 32 KiB
+the smallest on the 32 KiB ones — so the ATmega328P profiles below apply to
-ones (m32, m328, m324); on the 1284s that step is the smallest, 512 words,
+every one of them with its own addresses; the per-chip BOOTSZ ladders live in
-which is why their slot is 1 KiB — so the ATmega328P profiles below apply
+the host tool (`BOOT_FUSE`).
 to every one of them with its own addresses and slot size; the per-chip
 BOOTSZ ladders live in the host tool (`BOOT_FUSE`). The 1284s' numbers:
 standalone = BOOTSZ 512 words (reset at the loader base 0x1fc00);
 self-update = 1024 words, covering both 1 KiB slots, the loader-first
 reset landing at 0x1f800 — the staging slot, walked across when erased.
-The **644s** are the geometry's sweet spot: their smallest boot section
+The **644s and 1284s** are the geometry's sweet spot: their smallest boot
-(512 words = 1 KiB) is exactly *two* 512-byte slots, so the resident and
+section (512 words = 1 KiB) is exactly *two* slots, so the resident and its
-its staging slot both live inside the minimum section — self-update needs
+staging slot both live inside the minimum section. Self-update needs no fuse
-no fuse step up, and the standalone profile does not exist (reset lands at
+step up, and the standalone profile does not exist — reset lands one erased
-0xfc00, one erased slot below the loader: the loader-first walk built in).
+slot below the loader (0xfc00 / 0x1fc00) and walks up into it.
 ATmega328P profiles (addresses for its 32 KiB):
@@ -241,155 +212,135 @@ 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 — word 0 stays the application's own
+Applications are flashed unmodified here — 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
+**Patched-vector chips — the tinies and the m48s** (no boot section; the m48s'
-m48s' SPM runs from the entire flash, Atmel-8271 §26): program the loader
+SPM runs from the entire flash, Atmel-8271 §26): program the loader at
-at `flash − 512`; erased flash below it walks up into the loader, so a
+`flash − 512`; erased flash below it walks up into the loader, so a virgin
-virgin chip activates. When flashing an application the host performs
+chip activates. Flashing an application then takes reset-vector surgery: word
-reset-vector surgery: word 0 is rewritten to `rjmp` to the loader base, and
+0 becomes an `rjmp` to the loader base, and the application's own entry is
-the application's own entry is re-encoded as a trampoline `rjmp` in the
+re-encoded as a trampoline `rjmp` in the word just below the loader
-word just below the loader (`base − 2`, where the hand-over jumps). Every
+(`base − 2`, where the hand-over jumps). Every other vector stays the
-other vector stays the application's. The patched page 0 and the trampoline
+application's. The patched page 0 and the trampoline page are written *first*
-page are written *first*, so from the first write on an interrupted flash
+and an erase runs top-down, so from the first write on an interruption still
-still resets into the loader; an erase runs top-down for the same reason.
+resets into the loader.
-The m48s speak this profile over their hardware USART — no fuse preflight,
+
-BOOTRST does not exist there.
+A .bin programmed at address 0 by mistake is dead weight on a boot-sectioned
 mega (SPM only executes from the boot section — reflash the .hex), but *runs*
 on a patched-vector chip, and the ordinary `--update-loader` flow re-homes it
 into the top slot from there (`pureboot.rehome`).
 ## Updating the loader
 `pureboot.py --update-loader new_pureboot.bin` replaces the resident loader
 with any pureboot build — a re-timed window, a newer version — using the
 loader itself as its own staging loader. The image is the loader's own 512
-bytes as a raw binary, or the Intel HEX the build emits beside it, which
+bytes as a raw binary, or the Intel HEX the build emits beside it.
 links the loader at its base inside an otherwise blank flash image:
-The preflight refuses an image built for another chip: the info block
+The preflight refuses an image built for another chip: the info block embedded
-embedded in every pureboot binary (signature, page size, loader base,
+in every pureboot binary (signature, page size, loader base, EEPROM size,
-EEPROM size, flags) must match the device's own, and the error names both.
+flags) must match the device's own, and the error names both. Die revisions
-Die revisions share their base signature and geometry, so their images are
+share their base signature and geometry, so their images are interchangeable —
-interchangeable — as the silicon is. `loader_image()` also accepts a
+as the silicon is.
 padded image (a raw .bin padded from 0, or a whole-flash read-back with
 the loader resident) and peels it to the slot content by the embedded base.
-1. The staging slot `[base−slot, base)` is saved to a host-side state file
+1. The staging slot `[base−512, base)` is saved to a host-side state file (on
-   (on the 1 KB tiny13s that is the whole application, vectors included).
+   the 1 KB tiny13s that is the whole application, vectors included).
-2. The resident installs the identical update image there. On the
+2. The resident installs the update image there. On the patched-vector chips
-   patched-vector chips the host composes the slot's last word — the same
+   the host composes the slot's last word as a jump to the resident base, so
-   address as the resident's trampoline — as a jump to the resident base,
+   even an abandoned staging copy times out into a loader. A loader already
-   so even an abandoned staging copy times out into a loader, never into
+   sitting whole in the staging slot is left as the staging copy instead —
-   garbage. A loader already sitting whole in the staging slot (its info
+   rewriting it would only meet its own running-slot guard.
-   block in place, the slot unchanged since the update began) is left as
+3. `J` enters the staging copy, which rewrites the resident slot. Where a
-   the staging copy instead — rewriting it would only meet its own
+   patched reset vector routes through the resident, the host first re-aims
-   running-slot guard.
+   word 0 at the staging copy, so a power loss mid-rewrite still resets into a
-3. `J` enters the staging copy, which rewrites the resident slot. On the
+   loader; on the tiny13s the staging slot carries the reset vector itself.
   patched-vector chips whose staging slot sits away from page 0 the host
   first re-aims word 0 at the staging copy, so a power loss mid-rewrite
   still resets into a loader; on the tiny13s the staging slot carries the
   reset vector itself.
 4. `J` enters the new resident, which restores the staging slot's saved
-   content (word 0 and the trampoline with it) and the state file is
+   content, and the state file is discarded.
   discarded.
-Every phase is idempotent and keyed off the actual flash state: re-running
+Every phase is idempotent and keyed off the actual flash state, so re-running
-the same command after any interruption resumes and completes. The state
+the same command after any interruption resumes and completes. The state file
-file carries the only bytes not recoverable from the device; if it is lost
+carries the only bytes not recoverable from the device; losing it mid-update
-mid-update the update still completes, and the staging region is restored by
+still completes the update, and the staging region comes back by reflashing
-reflashing the application. A boot-sectioned mega needs its fuses for the
+the application. A boot-sectioned mega needs its fuses for the preflight — read
-preflight (BOOTSZ gate, profile notes) — read from the device, or supplied
+from the device, or supplied with `--assume-fuses` where reading is impossible
-with `--assume-fuses` where reading is impossible (simulators); the
+(simulators).
 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
+platform-specific part: termios drives any tty on POSIX (a USB adapter as well
-well as a simavr pty), the Win32 serial API through `ctypes` drives a COM
+as a simavr pty), the Win32 serial API through `ctypes` drives a COM port on
-port on Windows (`--port COM6`; the `\\.\` form for two-digit ports is
+Windows (`--port COM6`; the `\\.\` form for two-digit ports is supplied by the
-supplied by the tool). Opening the port asserts DTR and RTS on both, so a
+tool). Opening the port asserts DTR and RTS on both, so a board that wires DTR
-board that wires DTR to reset gets its reset pulse and opens the activation
+to reset gets its reset pulse and opens the activation window by itself.
 window by itself.
    pureboot.py --port /dev/ttyUSB0 --baud 57600 \
        --info --fuses --flash app.hex
 Operations run in a fixed order within one session: info, fuses, loader
-update, flash (erase / program / read / verify), EEPROM (erase / program /
+update, flash (erase / program / read / verify), EEPROM (the same) — then the
-read / verify) — then the loader hands over to the application; `--stay`
+loader hands over to the application. `--stay` keeps the session alive
-keeps the session alive instead, and a later invocation reconnects into it
+instead, and a later invocation reconnects into it. `--flash` and `--eeprom`
-(the knock converges there too). `--flash` and `--eeprom` verify by
+verify by read-back unless `--no-verify`, and a flash page that reads back
-read-back unless `--no-verify`, and a flash page that reads back wrong is
+wrong is rewritten up to three times before the run stops (see `W` above).
-rewritten up to three times before the run stops — the loader leaves one
+`--verify-flash` only reports. Images are raw binary, or Intel HEX by
-recoverable way for a page to land wrong (see `W` above), and rewriting is
+extension. `--force` overrides the refusable safety checks — today, flashing
-what clears it. `--verify-flash` only reports. Images are raw binary, or
+application data into a mega's reset walk region.
 Intel HEX by extension. `--force` overrides the refusable safety checks (today: flashing
 application data into a mega's reset walk region).
-Readouts come one fact per line: `--info` prints the decoded info block
+Readouts come one fact per line: `--info` decodes the info block field by
-field by field, the loader's version first; `--fuses` each fuse byte on its
+field, `--fuses` each fuse byte plus, on a boot-sectioned mega, its decoded
-own line — plus, on a boot-sectioned mega, the decoded meaning (where the
+meaning. Transfers that take wire time draw a transient progress bar on stderr
-BOOTSZ section starts, what BOOTRST does to reset). Transfers that take
+when it is a tty. `-v`/`--verbose` adds the decisions as they happen: knock
-wire time — programming, reading, erasing, verifying, the update phases —
+counts, the programming plan, update state handling and per-phase page counts.
 draw a transient progress bar on stderr when it is a tty; logs and pipes
 see only the summary lines.
 `-v`/`--verbose` adds the decisions as they happen: knock counts, the
 programming plan (vector-surgery targets, skipped blank pages), update
 state handling and per-phase page counts.
 ## Tests
-`tools/check.sh` runs every chip's workflow (`tools/check.sh --full` adds
+`tools/check.sh` runs every chip's workflow (`--full` adds the reflect-mode
-the reflect-mode builds of libavr's spot set; `tools/make_presets.py`
+builds of libavr's spot set; `tools/make_presets.py` regenerates the presets).
-regenerates the presets). Per chip preset, `ctest` runs:
+Per chip preset, `ctest` runs:
- `pureboot.size` — the 510-byte (tinies) / 512-byte (mega) budget;
+- `pureboot.size` — the 510-byte (patched-vector) / 512-byte budget;
- `pureboot_*.size` — the size matrix: the serial backends × the clock
+- `pureboot_*.size` — the size matrix: the serial backends × the clock ladder
-  ladder (1/8/16 MHz; the t13s' own RC menu), plus the USART1 build on the
+  (1/8/16 MHz; the t13s' own RC menu), the USART1 instance across that same
-  x4 chips — every configuration axis that could move the image, each
+  ladder on the x4 chips, and `pureboot_sw_wide`, the slowest ladder rate at
-  variant against the same slot budget (pins are immediate operands and the
+  the fastest clock — where a software UART's per-bit spin outgrows its
-  timeout is a constant: size-neutral);
+  one-register delay loop and takes the 16-bit one. That is the largest image
- `pureboot.custom` (328P) — the configured-deployment acceptance test: the
+  the configuration space produces, and a shape the ladder default (always the
-  1 MHz software-serial TX=PB1/RX=PB5 build from the configuration example
+  *fastest* rate a clock reaches) never picks. Pins are immediate operands and
-  drives the full protocol suite through the runner's GPIO bridge, fixture
+  the timeout is a constant: neither is an axis;
-  application included;
+- `pureboot.pi` — the position-independence lint: no absolute `jmp`/`call`, the
- `pureboot.usart1` (644A) — the same protocol suite over the second
+  info block within the image's first 256 bytes;
-  hardware USART: instance selection is compile-checked everywhere, but
+- `pureboot.planner` — the host tool's pure logic: programming orders and their
-  only a live session proves the loader polls the USART it claims;
+  recovery properties, the surgery, the staging composition, the boot-fuse
- `pureboot.pi` — the position-independence lint: no absolute `jmp`/`call`
+  decode, the update preflight over synthetic fuse bytes, and the repairing
-  in the image, the info block within its first 256 bytes;
+  verify against a fake device;
 - `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's error/warning matrix over
  synthetic fuse bytes, and the repairing verify against a fake device — one
  bad write repaired in a single rewrite, a page that never comes good
  stopping after exactly three;
 - `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, selected with `-l` to match
+  GPIO⇄pty bridge for a software-UART build, plus the SPM/NVM module simavr's
-  the loader's link; plus the SPM/NVM module simavr's tiny cores lack)
+  tiny cores lack) driven by the real host tool through knock-from-reset,
-  driven by the real host tool through
+  program + verify of both memories, session reconnect, an external reset
-  knock-from-reset, program + verify of both memories, session reconnect, an
+  through the patched vector, and the hand-over to a fixture application whose
-  external reset through the patched vector, and the hand-over to a fixture
+  banner proves the launch — cross-checked against the simulator's
-  application whose banner proves the launch — cross-checked against the
+  ground-truth memory dumps and an independent decode of the surgery;
-  simulator's ground-truth memory dumps and an independent decode of the
+- `pureboot.reloc` — the identical image one slot below the resident serves the
-  surgery's rjmp words;
+  complete command set from there;
- `pureboot.reloc` — the identical image installed one slot below the
+- `pureboot.rehome` (t85) — a loader programmed at address 0 or in the staging
-  resident serves the complete command set from there (the
+  slot re-homes into the top slot through the ordinary update flow;
-  position-independence acceptance test);
+- `pureboot.custom` (328P) — the configuration example's 1 MHz software-serial
- `pureboot.dirty` (328P) — entering the loader from a running application
+  build driving the full protocol suite, proving the plumbing produces a
-  with no reset between, over an SPM page buffer the fixture deliberately
+  working loader and not just one that fits;
-  dirtied: the case the loader declines to guard against. A bare verify must
+- `pureboot.usart1` (644A) — the same suite over the second hardware USART:
-  see the corruption, the repairing verify must fix it in one rewrite, and a
+  instance selection is compile-checked everywhere, but only a live session
-  plain verify afterwards must pass. On the boot-sectioned megas hardware
+  proves the loader polls the USART it claims;
-  forbids the state outright (SPM runs only from the boot section, and reset
+- `pureboot.dirty` (328P) — entering the loader from a running application over
-  erases the buffer), but simavr dispatches SPM from anywhere — which is what
+  an SPM buffer it deliberately dirtied, the case the loader declines to guard:
-  makes the path constructible at all;
+  a bare verify must see the corruption and the repairing verify must fix it in
- `pureboot.update` — the full `--update-loader` flow to a re-timed build,
+  one rewrite. Hardware forbids the state here, but simavr dispatches SPM from
-  then every power-fail phase: the device is killed mid-write, restarted
+  anywhere, which is what makes the path constructible;
-  from its flash dump, and a re-run must complete the update with the
+- `pureboot.update` — the full `--update-loader` flow, then every power-fail
-  application intact throughout.
+  phase: the device is killed mid-write, restarted from its flash dump, and a
  re-run must complete the update with the application intact.
-`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,28 +1,14 @@
-// pureboot — a serial bootloader on libavr, pure by constraint: one C++
+// pureboot — a serial bootloader on libavr: one C++ source, no inline
-// source with no inline assembly and no global register variables, built for
+// assembly, no global register variables, 512 bytes on every chip libavr
-// every chip libavr targets, 512 bytes on each. The device speaks primitives
+// targets. The device speaks primitives; every composite (verify, erase,
-// — read/program flash, read/write EEPROM, fuse bytes, an info block, a jump
+// reset-vector surgery, self-update) lives in the host tool. Protocol,
-// — and everything composite (verify, erase, reset-vector surgery, updating
+// deployment and configuration: README.md next to this file.
 // the loader itself) lives in the host tool. Protocol reference: README.md
 // next to this file.
 //
-// The image is position-independent: control flow is PC-relative, the write
+// The image is position-independent — PC-relative control flow, wire
-// and read paths take wire addresses, the write guard refuses the 512-byte
+// addresses in, the write guard and the info block both anchored on the
-// slot the code is *running* in (taken from the runtime return address), the
+// runtime return address — so the identical binary runs from any slot. That
-// info block is read relative to that same anchor, and the application jump
+// is what makes a copy one slot below able to rewrite the resident one, and
-// is an indirect call to an absolute entry. The identical binary therefore
+// every change here has to keep it (test/check_pi.py).
 // 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>
@@ -33,17 +19,14 @@ namespace ee = avr::eeprom;
 namespace pureboot {
 namespace {
-// Purely polled — interrupts stay off, every guard folds to nothing.
+// Purely polled: every interrupt guard folds to nothing.
 constexpr auto off = avr::irq::guard_policy::unused;
 constexpr std::uint8_t ack = '+';
-// Per-deployment personality, passed in by the build — pureboot_add_loader()
+// Deployment parameters come from the build (pureboot_add_loader()). The
-// (the CMake function next to this file) resolves the defaults: the clock the
+// signature is not one of them: the chip database is the only universal
-// board actually runs, the wire baud, the serial backend and its pins. The
+// source — a tiny13A cannot read its own signature row from code.
 // device signature needs no configuring — it comes from the chip database
 // (avr::hw::db.signature), the only universal source, since the tiny13A
 // cannot even read its signature row from code.
 #if !defined(PUREBOOT_CLOCK_HZ) || !defined(PUREBOOT_BAUD)
 #error \
    "PUREBOOT_CLOCK_HZ and PUREBOOT_BAUD select this build's clock and baud — create loader targets with pureboot_add_loader() (README.md)"
@@ -59,76 +42,51 @@ consteval std::int16_t wdrf_field()
 	return avr::hw::db.field_index(reg, "WDRF");
 }
-// Geometry: the resident loader owns the top slot of flash — 512 bytes,
+// The loader owns the top 512 bytes; a staging copy goes in the slot below.
-// except on the >64 KiB chips whose own smallest boot sector is 1 KiB (the
+// Chips without a hardware boot section — the tinies and the m48s, whose SPM
-// 1284s): there the slot is 1 KiB, matching the hardware boundary the
+// runs from anywhere (Atmel-8271 §26) — keep the application's relocated
-// 512-byte figure comes from everywhere else. The word below the slot is
+// reset vector in the word under the slot.
-// the trampoline (the application's relocated reset vector) on chips
+constexpr std::uint16_t slot_bytes = 512;
 // 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 a byte address no longer fits the wire's 16 bits, so on the
+// Past 64 KiB a byte address no longer fits the wire's 16 bits, so flash
-// large chips every flash address on the wire — and all slot arithmetic —
+// addresses there are word addresses ('J' always was one). A slot is 256 of
-// is a word address instead ('J' always was one). A slot spans the same
+// those — one value of a wire address's high byte, where 512 bytes span two.
 // wire-high-byte pair in either unit (512 B = 2 x 256 bytes, 1 KiB =
 // 2 x 256 words), so the slot index is the high byte with its low bit
 // dropped everywhere.
 constexpr bool word_flash = spm::flash_bytes > 65536;
 constexpr std::uint16_t wire_base =
    word_flash ? static_cast<std::uint16_t>(base / 2) : static_cast<std::uint16_t>(base);
 constexpr std::uint16_t wire_page_mask = word_flash ? (page / 2 - 1) : (page - 1);
-// The activation window, in seconds, is a compile-time constant (the build
+// A compile-time window, so the whole EEPROM belongs to the application;
-// may override it): the whole EEPROM belongs to the application, and
+// re-timing a deployed loader is a self-update with a re-timed build.
 // re-timing the loader is a bootloader self-update with a re-timed binary.
 #if !defined(PUREBOOT_TIMEOUT)
 #define PUREBOOT_TIMEOUT 8
 #endif
 constexpr std::uint8_t timeout_seconds = PUREBOOT_TIMEOUT;
-// The pureboot version: the loader's one identity number, carried in the info
+// The loader's one identity number. The protocol carries none of its own —
-// block so a host can tell a deployed loader apart from another. The wire
+// a version implies it, and the host tool holds that map (README.md).
-// protocol has no number of its own — a version implies its protocol, and the
+constexpr std::uint8_t version = 3;
 // host tool is what holds that map (README.md).
 constexpr std::uint8_t version = 2;
-// The 12-byte info block the host reads with the 'b' command, flash-resident
+// The 'b' reply, byte for byte (layout: README.md). Flash-resident because
-// through flash_table (there is no crt to copy a .data image, and its storage
+// no crt copies a .data image — and flash_table's storage carries the word
-// carries the word alignment 'b' needs to halve the address on the large
+// alignment 'b' needs to halve the address on the large chips.
 // chips). The page byte is the wire count convention: 0 means 256.
 inline constexpr avr::flash_table<std::array<std::uint8_t, 12>{
-    'P',
+    'P', 'B', version, avr::hw::db.signature[0], avr::hw::db.signature[1], avr::hw::db.signature[2],
-    'B',
+    static_cast<std::uint8_t>(page), // 0 means 256
-    version, // magic, then the loader's version
+    wire_base & 0xff, wire_base >> 8, avr::hw::db.mem.eeprom_size & 0xff, avr::hw::db.mem.eeprom_size >> 8,
-    avr::hw::db.signature[0],
+    static_cast<std::uint8_t>((boot_section ? 0 : 1) | (word_flash ? 2 : 0)), // patch-vector, word-addressed
    avr::hw::db.signature[1],
    avr::hw::db.signature[2],
    static_cast<std::uint8_t>(page),
    wire_base & 0xff,
    wire_base >> 8, // app flash ends here; resident loader base (a word address on large chips)
    avr::hw::db.mem.eeprom_size & 0xff,
    avr::hw::db.mem.eeprom_size >> 8,
    // bit 0: host must patch the reset vector (no hardware boot section);
    // bit 1: flash wire addresses are word addresses
    static_cast<std::uint8_t>((boot_section ? 0 : 1) | (word_flash ? 2 : 0)),
 }>
    info_data;
-// The serial link. PUREBOOT_USART forces a hardware USART instance,
+// The serial link, per the build's PUREBOOT_USART / PUREBOOT_SOFT_SERIAL,
-// PUREBOOT_SOFT_SERIAL the polled software UART (no vector — the table
+// defaulting to the chip's USART0 where it has one. The software receiver is
-// belongs to the application) on PUREBOOT_RX/PUREBOOT_TX; with neither, the
+// the polled one: the vector table belongs to the application. Templates on
-// chip's first USART where it has one and the software UART elsewhere. Both
+// the clock, so only the selected backend instantiates. pending() is the
-// are class templates on the clock so only the selected backend is ever
+// cheap line test the activation window polls; drain() holds until the last
-// instantiated. pending() is the cheap line test the activation window
+// frame is off the wire, so a hand-over cannot let the target's re-init clip
-// polls; rx() then picks the byte up; drain() holds until the last
+// the ack.
 // transmitted frame is fully on the wire (the jump hand-over must not let
 // the target's re-init clip the ack).
 #if defined(PUREBOOT_SOFT_SERIAL) && defined(PUREBOOT_USART)
 #error "PUREBOOT_SOFT_SERIAL and PUREBOOT_USART select opposing serial backends"
 #endif
@@ -223,12 +181,10 @@ using link =
    std::conditional_t<avr::uart::has_usart<usart_digit>(), hardware_link<dev::clock>, software_link<dev::clock>>;
 #endif
-// The application's entry, an absolute address the linker pins (--defsym in
+// The application's entry, pinned by the linker (--defsym): word 0 on a
-// CMakeLists.txt): 0x0000 on the mega (word 0 stays the application's own
+// boot-sectioned mega, the trampoline at base − 2 elsewhere. Reaching it must
-// vector — BOOTRST re-vectors a reset into the loader in hardware) and the
+// not depend on where this copy runs, so the jump goes through a pointer, and
-// trampoline word at base - 2 on the tinies. Reaching it must not depend on
+// [[gnu::noipa]] keeps the constant from folding back into a relative call.
 // 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)())
@@ -242,10 +198,8 @@ extern "C" [[noreturn]] void pureboot_app();
 	jump(pureboot_app);
 }
-// One activation window is a single 32-bit poll countdown. The divisor is
+// The window as one 32-bit countdown, divided by the backend's counted
-// the backend's counted poll-loop cycles (its own comment reads them off the
+// poll-loop cycles. Whole seconds is all it promises.
 // compiled loop); whole-second precision is all the window promises, so the
 // nearest cycle count is plenty.
 consteval std::uint32_t window_polls()
 {
 	return timeout_seconds * static_cast<std::uint32_t>(dev::clock.hz / link::poll_cycles);
@@ -261,8 +215,8 @@ bool pending_before_deadline()
 	return false;
 }
-// A knock byte under the activation deadline: an idle line means no host is
+// A knock byte under the deadline: an idle window means no host, so the
-// there, and the application runs.
+// application runs.
 std::uint8_t rx_deadline()
 {
 	if (!pending_before_deadline())
@@ -270,22 +224,26 @@ std::uint8_t rx_deadline()
 	return link::rx();
 }
-// Inlined into its call sites: reading two bytes across a call otherwise
+// Inlined: read across a call, the first byte strands in a call-saved
-// strands the first in a call-saved register the caller must push/pop; folded
+// register the caller has to push and pop.
 // into the (noreturn) command loop that cost disappears.
 [[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 streamers take the count in the wire's 8-bit form: 0 means 256.
+// The wire's byte pair as the word it is — AVR is little-endian too, so the
-//
+// cast is the identity a shift-and-or spelling makes the compiler rediscover.
-// Two functions, because they want opposite placement and placement is an
+// Callers read into named variables first: the wire order is a sequence of
-// attribute: the byte-addressed loop is small enough to inline into both
+// reads, not an argument order.
-// callers, the word-addressed one stays out of line but flattened — a call to
+[[gnu::always_inline]] inline std::uint16_t word_of(std::array<std::uint8_t, 2> pair)
-// the transmit inside it would strand the 24-bit cursor in callee-saved
+{
-// registers. `word_flash` picks at the call site.
+	return std::bit_cast<std::uint16_t>(pair);
 }
 // Counts arrive in the wire's 8-bit form: 0 means 256. Both streamers fold
 // into the one command that reads flash, which is what lets the far one's
 // 24-bit cursor sit in the command loop's own call-saved registers.
 [[maybe_unused, gnu::always_inline]] inline void send_flash_near(std::uint16_t address, std::uint8_t count)
 {
 	do
@@ -293,17 +251,16 @@ std::uint8_t rx_deadline()
 	while (--count);
 }
-// The 24-bit cursor as the machine holds it: the RAMPZ byte and a 16-bit Z,
+// The 24-bit cursor as the machine holds it — the RAMPZ byte and a 16-bit Z,
-// carried explicitly (the reassembled 32-bit address folds away inside the
+// carried apart; the reassembled address folds away inside the far load.
-// inlined far load).
+[[maybe_unused, gnu::always_inline]] inline void send_flash_far(std::uint16_t address, std::uint8_t count)
 [[maybe_unused, gnu::flatten, gnu::noinline]] void send_flash_far(std::uint16_t address, std::uint8_t count)
 {
 	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
+		// Carrying the wrap is smaller than the flat 32-bit cursor GCC
-		// smaller than the flat 32-bit cursor GCC builds without it.
+		// builds without it.
 		if (++z == 0)
 			++rampz;
 	} while (--count);
@@ -317,6 +274,13 @@ std::uint8_t rx_deadline()
 		send_flash_near(address, count);
 }
 // Out of line: three sites send it, and a call is shorter than three
 // load-immediates.
 [[gnu::noinline]] void tx_ack()
 {
 	link::tx(ack);
 }
 void send_eeprom(std::uint16_t address, std::uint8_t count)
 {
 	do
@@ -324,74 +288,62 @@ void send_eeprom(std::uint16_t address, std::uint8_t count)
 	while (--count);
 }
-// EEPROM write, host-paced: each ack goes out once the byte's write has
+// Host-paced: the ack goes out once the write has begun, so the next byte
-// begun, so the next byte arrives while it completes and the following
+// arrives while it completes and nothing is missed without a buffer.
 // write's own ready-wait sees an idle line. Nothing is ever missed, on
 // either serial backend, without a buffer.
 void store_eeprom(std::uint16_t address, std::uint8_t count)
 {
 	do {
 		ee::write<off>(address++, link::rx());
-		link::tx(ack);
+		tx_ack();
 	} while (--count);
 }
-// One flash page: stream the bytes into the SPM buffer as little-endian
+// One page into the SPM buffer, then erase and program — except the slot
-// words, then erase and program — except the 512-byte slot this code runs
+// this code is running in (`slot_high`, from run()), which is drained and
-// in, which is drained but never programmed, so a copy can never erase
+// left alone. A broken host therefore cannot brick the running loader, and a
-// itself. `slot_high` is the high byte of that running slot's base (run()
+// copy one slot lower may rewrite the resident one.
-// 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
+// Nothing discards the buffer first: it is write-once per word (§26.2.1), so
-// updates itself.
+// 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 program_flash(std::uint16_t wire_address, std::uint8_t slot_high)
 {
-	// No discard before the fill: the buffer is write-once per word
+	// One induction either way: a byte-addressed wire address walks the page
-	// (§26.2.1), so filling over one a refused page or an application left
+	// itself (aligned, so the offset bits wrap to zero), while a word one
-	// dirty programs stale words — but a page write auto-erases the buffer
+	// becomes a byte cursor once. The slot index is the wire address's high
-	// (§26.2.1; §19.2 on the tinies), so that write clears the condition and
+	// byte — on byte-addressed chips the byte address's, with the low bit
-	// the host's read-back rewrites the page.
+	// dropped, since a slot is two of those.
 	// 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:
+		// A page is aligned, so it never crosses 64 KiB: RAMPZ is a per-page
-		// RAMPZ is a per-page constant and the fill cursor is a 16-bit Z
+		// constant and the 16-bit Z's low byte is the whole in-page offset.
 		// 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,
+			spm::fill<off>((static_cast<spm::flash_address_t>(rampz) << 16) | z, word_of({low, high}));
 			               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;
+		page_high = static_cast<std::uint8_t>(wire_address >> 8);
 	} 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)));
+			spm::fill<off>(address, word_of({low, high}));
 			address += 2;
 		} while (static_cast<std::uint8_t>(address) & (page - 1));
 		address -= 2; // back inside the page — erase and write ignore the word bits
 		page_high = static_cast<std::uint8_t>(address >> 8) & 0xfe;
 	}
 	if (page_high != slot_high) {
-		// The tinies and the m48s halt the CPU through the erase and the
+		// Only a boot-sectioned mega runs on while its RWW section programs;
-		// write, so only the boot-sectioned megas — running on while their
+		// everywhere else the CPU halts through erase and write.
 		// RWW section programs — wait.
 		spm::erase_page<off>(address);
 		if constexpr (boot_section)
 			spm::wait();
@@ -399,89 +351,92 @@ void program_flash(std::uint16_t wire_address, std::uint8_t slot_high)
 		if constexpr (boot_section)
 			spm::wait();
 	}
-	// The megas program with their RWW section disabled; reads need it back
+	// Programming leaves the RWW section disabled; reads need it back on. The
-	// on. The same store discards the buffer (§26.2.2), so they never meet
+	// same store discards the buffer (§26.2.2), so a boot-sectioned mega never
-	// the stale-word case above. boot_section implies an RWW section.
+	// meets the stale-word case above.
 	if constexpr (boot_section)
 		spm::rww_enable<off>();
 }
-// The four fuse/lock bytes in the hardware's own Z order: low, lock,
+// The four fuse and lock bytes in the hardware's own Z order: low, lock,
-// extended, high. Writing fuses is not a thing self-programming can do on
+// extended, high.
 // AVR — SPM reaches flash (and boot lock bits) only.
 void send_fuses()
 {
 	std::uint8_t which = 0;
 	do
 		link::tx(spm::read_fuse<off>(static_cast<spm::fuse>(which)));
-	while (++which & 3);
+	while (++which != 4);
 }
 [[noreturn]] void run()
 {
-	// A watchdog reset belongs to the application (whose watchdog stays
+	// A watchdog reset belongs to the application, whose watchdog stays forced
-	// forced on until it clears WDRF) — no activation window in its way.
+	// on until it clears WDRF — no activation window in its way.
 	// The flag register is MCUSR, or the classic megas' MCUCSR.
 	if (avr::hw::field_impl<wdrf_field()>::test())
 		run_app();
 	link::init();
-	// The high byte of the 512-byte-aligned base this copy runs at: the
+	// The high byte of the slot this copy runs at, which the write guard and
-	// return address is a word address, whose high byte is the 256-word slot
+	// the info block both follow: the return address is a word address, so its
-	// index — on byte-addressed chips doubled back into byte terms.
+	// high byte is the 256-word slot index, doubled back into byte terms where
-	// program_flash refuses this one slot and the info block is addressed
+	// the wire counts bytes. Taken as byteswap's low byte — the builtin already
-	// from it, so both follow wherever the code was flashed. The high byte is
+	// swaps the two stacked bytes, and the double swap folds away, where `>> 8`
-	// spelled as byteswap's low byte: the builtin's value is itself built by
+	// would leave the swap materialized.
 	// 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);
+	const std::uint8_t slot_high = word_flash ? ra_high : static_cast<std::uint8_t>(ra_high << 1);
-	// The knock: 'p' then 'b', each under a fresh window; any other byte is
+	// 'p' then 'b', each under a fresh window; anything else is line noise.
 	// line noise and waits again. Falling out of a window runs the app.
 	while (rx_deadline() != 'p' || rx_deadline() != 'b') {
 	}
 	for (;;) {
-		// No prompt while an EEPROM write runs: a pending write blocks SPM
+		// No prompt while an EEPROM write runs: it blocks SPM and fuse reads
-		// and fuse reads (§26.2.1), and the ack tells the host all is done.
+		// (§26.2.1), and the prompt is the previous command's completion ack.
 		ee::wait();
-		link::tx(ack);
+		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());
-			link::tx(ack);
+			tx_ack();
 			link::drain();
 			jump(target);
 		}
 		case 'b':   // info block, read relative to the running slot
 		case 'R':   // read flash: addr16, n8 (0 = 256)
 		case 'r':   // read EEPROM: addr16, n8
 		case 'w': { // write EEPROM: addr16, n8, then n bytes each acked
-			std::uint16_t address = rx16();
+			// One address-and-count path for all four: 'b' is a flash read
-			std::uint8_t count = link::rx();
+			// whose arguments the loader already knows, so it joins the
-			if (command == 'R')
+			// wire-argument three rather than streaming from a call site of its
-				send_flash(address, count);
+			// own. That leaves one flash streamer in the image, and lets its
-			else if (command == 'r')
+			// cursor live in this never-returning loop's own call-saved
 			// registers instead of being saved and restored around a call.
 			std::uint16_t address;
 			std::uint8_t count;
 			if (command == 'b') {
 				// The block sits in the image's first 256 bytes (check_pi.py
 				// asserts it) and slots are 512-aligned, so the low byte of its
 				// link address is its offset in any slot — halved where wire
 				// units are words. The high byte is runtime data, so no
 				// absolute address is ever materialized.
 				const auto link_byte =
 				    static_cast<std::uint8_t>(reinterpret_cast<std::uint16_t>(info_data.storage.data()));
 				const std::uint8_t low = word_flash ? static_cast<std::uint8_t>(link_byte >> 1) : link_byte;
 				address = static_cast<std::uint16_t>(low | (slot_high << 8));
 				count = static_cast<std::uint8_t>(info_data.size());
 			} else {
 				address = rx16();
 				count = link::rx();
 			}
 			if (command == 'r')
 				send_eeprom(address, count);
-			else
+			else if (command == 'w')
 				store_eeprom(address, count);
 			else
 				send_flash(address, count);
 			break;
 		}
 		case 'W': // program one flash page: addr16, page bytes
--- a/pureboot/pureboot.py
+++ b/pureboot/pureboot.py
@@ -1,24 +1,13 @@
 #!/usr/bin/env python3
-"""pureboot host tool — the smart half of the pureboot protocol (README.md).
+"""pureboot host tool — the smart half of the protocol (README.md).
-The device exposes primitives; this tool composes them: image loading (raw
+The device exposes primitives; everything composite is here: HEX/raw images,
-binary or Intel HEX), flash programming with read-back verification, erase as
+programming with repairing read-back verification, the reset-vector surgery
-writing 0xff, EEPROM programming, fuse and info readout, the hand-over jump,
+the boot-section-less chips need, and the self-update that stages the loader
-and — on chips without a hardware boot section — the reset-vector surgery
+one slot lower and lets it rewrite the resident.
 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.
-It also updates the loader itself (--update-loader): pureboot's image is
+Standard library only. The port is termios on POSIX and the Win32 serial API
-position-independent, so the tool installs the identical binary one 512-byte
+through ctypes on Windows, so any tty or COM port works.
 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
@@ -36,22 +25,19 @@ else:
 PROMPT = b"+"
 VERSION = 2  # this tool's own version — free to drift from a loader's
-# The loader versions this tool speaks to. A pureboot version implies its wire
+# The loader versions this tool speaks. A pureboot version implies its wire
-# protocol — the protocol carries no number of its own — so knowing which
+# protocol, which carries no number of its own, so this window is where that
-# versions speak what is the tool's job, and this window is where it says so:
+# map lives: every version so far speaks the same protocol, and one that
-# every pureboot so far speaks this protocol, and a version that changes it
+# changes it becomes the new floor here.
 # becomes the new floor here.
 OLDEST_LOADER = 1
-NEWEST_LOADER = 2
+NEWEST_LOADER = 3
-SLOT = 512  # the loader slot on byte-addressed chips; word-addressed ones (>64 KiB) use 1 KiB — their own smallest boot sector
+SLOT = 512  # the loader slot, on every chip
 RETRIES = 3  # rewrites of a page that reads back wrong, before the run stops
 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}")
@@ -61,11 +47,9 @@ class Error(Exception):
 class Progress:
-    """A transient in-place bar on stderr for the operations that take wire
+    """A transient bar on stderr, drawn only for a tty and erased when done —
-    time. Drawn only when stderr is a tty — logs, pipes and the test harness
+    logs and pipes see only the summary line each operation prints. No label
-    see nothing — and erased once done; the summary line each operation
+    or a zero total disables it, so callers can pass one unconditionally."""
    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
@@ -330,18 +314,16 @@ class Info:
        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)
-        # Large chips speak word addresses for flash (bit 1); the host keeps
+        # Bit 1: flash addresses are words on the wire. Every address here
-        # every address in bytes and converts at the wire.
+        # stays a byte address 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.slot = 1024 if self.word_flash else SLOT
+        self.flash_size = self.base + SLOT
-        self.flash_size = self.base + self.slot
+        self.stage = self.base - SLOT  # where a staging copy of the loader goes
-        self.stage = self.base - self.slot  # where a staging copy of the loader goes
+        # The hand-over target as 'J' takes it: the trampoline below the
-        # The hand-over target, as the word address 'J' takes: the trampoline
+        # loader, or word 0 where BOOTRST re-vectors reset in hardware.
        # 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):
@@ -354,7 +336,7 @@ class Info:
        )
    def lines(self):
-        """The info block as one fact per line — what --info prints."""
+        """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:
@@ -365,7 +347,7 @@ class Info:
            f"flash        {self.flash_size} B, {self.page} B pages"
            + (", word-addressed wire" if self.word_flash else ""),
            f"application  0x0000..{self.base - 1:#06x} ({self.base} B)",
-            f"loader       {self.base:#06x} ({self.slot} B slot)",
+            f"loader       {self.base:#06x} ({SLOT} B slot)",
            f"staging      {self.stage:#06x}",
            f"EEPROM       {self.eeprom_size} B",
            f"hand-over    {hand_over}",
@@ -373,19 +355,18 @@ class Info:
 class Loader:
-    """A pureboot session. Between commands the loader has prompted `+` and
+    """A session. Between commands the loader has prompted and awaits a
-    awaits a command byte; every method restores that invariant — except
+    command byte; every method restores that, except jump() — after which the
-    jump(), after which the target must be knocked afresh."""
+    target must be knocked afresh."""
    def __init__(self, port):
        self.port = port
        self.info = None
    def connect(self, wait):
-        """Knock until the activation window answers, then read the info
+        """Knock until the window answers, then read the info block. Also
-        block. Also converges when the loader already sits in its command
+        converges into a live session: the knock bytes are ignored there and
-        loop: the knock bytes are ignored-or-executed there, and the drain
+        the drain absorbs whatever they produced."""
        absorbs whatever they produced."""
        self.port.flush_input()
        deadline = time.monotonic() + wait
        knocks = 0
@@ -471,16 +452,13 @@ class Loader:
        return self._command(b"F", 4, 2.0)
    def jump(self, word_address):
-        """'J': the device acks, then execution continues at the word
+        """The device acks, then execution continues at the word address."""
        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. Ending
+        """Jump into the loader copy at `byte_address` and knock it — a slot
-        up in the copy addressed is guaranteed by construction: a jump to a
+        base is that copy's entry stub, so it can only land there."""
        slot base lands in that slot's entry stub."""
        self.jump(byte_address // 2)
        return self.connect(wait)
@@ -576,15 +554,14 @@ def plan_flash(image, info):
 def covered(pages, info, skip_blank):
-    """Pages in programming order; optionally dropping all-0xff pages (sound
+    """Pages in programming order, optionally dropping all-0xff ones (sound
-    only over erased flash) — never a load-bearing one.
+    only over erased flash, and never a load-bearing page).
-    With a patched vector (tinies), the patched page 0 goes first and the
+    A patched vector puts page 0 first and the trampoline page second, so from
-    trampoline page second: from the first write on, a reset lands in the
+    the first write on a reset lands in the loader and its fall-through on the
-    loader and the loader's own fall-through lands on the application entry,
+    application entry — every interruption point recoverable. A hardware boot
-    so every interruption point of the flash is recoverable. With a hardware
+    section re-vectors reset regardless; page 0 goes last there, which
-    boot section a reset re-vectors to the loader regardless; ascending
+    maximizes what an interrupted image retains."""
    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]
@@ -650,10 +627,9 @@ def mega_boot(info, fuse_bytes):
 def image_info(image):
-    """The info block embedded in a pureboot binary, or None. Searched per
+    """The info block embedded in a pureboot binary, or None. Searched once
-    known loader version, so the magic stays three selective bytes rather than
+    per known version, so the magic stays three selective bytes rather than
-    two that code could carry by chance — and a binary this tool does not know
+    two that code could carry by chance."""
    the version of reads as no block at all, which is what it is to the tool."""
    for version in range(OLDEST_LOADER, NEWEST_LOADER + 1):
        at = image.find(b"PB" + bytes((version,)))
        if 0 <= at <= len(image) - 12:
@@ -662,12 +638,10 @@ def image_info(image):
 def loader_image(path):
-    """A loader update image, as the slot's own content. A raw binary is that
+    """An update image as the slot's own content: a raw binary already is,
-    already; an Intel HEX links the loader at its base inside an otherwise
+    while a HEX carries the blank below the loader's base, which is peeled off
-    blank flash image, and load_image() anchors every image at zero, so the
+    here. The base comes from the image's own block, not the device's, so a
-    blank below the base is dropped here. The base comes from the image's own
+    foreign image survives intact for the preflight to reject by name."""
    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:
@@ -676,18 +650,17 @@ def loader_image(path):
 def staging_content(image, info):
-    """The 512-byte staging-slot content: the image, padding, and — on
+    """The staging slot's content: the image, padding, and — where the
-    chips whose hand-over jumps through the word below the resident loader —
+    hand-over jumps through the word below the resident — that word, which for
-    that word, which for a staging copy is the slot's own last word: an rjmp
+    a staging copy is its own last one. Composed as an rjmp to the resident,
-    to the resident base. The staging copy's fall-through and 'J'-free exit
+    so an abandoned staging copy still falls through into a loader."""
-    both land in a loader instead of garbage."""
+    budget = SLOT - 2 if info.patch_vector else SLOT
-    slot = info.slot
+    if len(image) > budget:
-    if len(image) > (slot - 2 if info.patch_vector else slot):
+        raise Error(f"loader image is {len(image)} B, the slot holds {budget}")
-        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)))
    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)
@@ -713,7 +686,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 * info.slot} B, BOOTSZ) is "
+                f"— a boot section of at least two slots ({2 * SLOT} B, BOOTSZ) is "
                f"required, and only an external programmer can change fuses"
            )
        if not bootrst:
@@ -755,7 +728,7 @@ class UpdateState:
        self.data = {
            "signature": info.signature.hex(),
            "base": info.base,
-            "staging": loader.read_flash(info.stage, info.slot).hex(),
+            "staging": loader.read_flash(info.stage, SLOT).hex(),
            "page0": loader.read_flash(0, info.page).hex() if info.patch_vector else "",
        }
        with open(self.path, "w") as f:
@@ -774,9 +747,8 @@ class UpdateState:
 def write_differing(loader, base, content, order=None, label=None):
-    """Program the pages of `content` at `base` that differ from flash —
+    """Program the pages of `content` at `base` that differ from flash, so a
-    idempotent, so a resumed phase redoes only what an interruption left.
+    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
@@ -789,9 +761,8 @@ def write_differing(loader, base, content, order=None, label=None):
            bar.step()
    if label:
        verbose(f"{label}: {written} of {len(offsets)} pages differed")
-    # Page-wise read-back with the same bounded repair as verify_pages: this
+    # The same bounded repair as verify_pages: here a page left wrong is a
-    # is the loader-update path, where a page left wrong is a half-written
+    # half-written loader slot.
    # loader slot.
    for retry in range(RETRIES + 1):
        bad = [
            offset
@@ -813,8 +784,8 @@ def write_differing(loader, base, content, order=None, label=None):
 def patch_word0(loader, page0, target_base):
-    """Rewrite page 0 with its word 0 re-aimed at `target_base` — the
+    """Re-aim word 0 at `target_base` — the resume insurance around
-    resume insurance around rewriting a loader slot the reset path uses."""
+    rewriting a loader slot the reset path goes through."""
    info = loader.info
    patched = bytearray(page0)
    word = rjmp_to(0, target_base // 2, info.flash_size // 2)
@@ -824,10 +795,9 @@ 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 itself as
+    """Replace the resident loader with `path`, using the loader as its own
-    its own staging loader. Every phase is idempotent and keyed off the
+    staging loader. Every phase is idempotent and keyed off the flash state,
-    actual flash state, so a re-run after any interruption resumes; the
+    so a re-run resumes; the state file carries what the staging slot held."""
    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):
@@ -835,7 +805,7 @@ def op_update_loader(loader, wait, path, state_path, fuse_bytes):
    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] * (info.slot - len(image)))
+    resident = bytes(image) + bytes([0xFF] * (SLOT - len(image)))
    page = info.page
    state = UpdateState(state_path)
@@ -845,38 +815,29 @@ 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)
-    # Install the staging copy — unless a loader already sits whole in the
+    # A loader already sitting whole in the staging slot IS the staging copy:
-    # staging slot (a build programmed there by hand): that copy IS the
+    # rewriting it would only meet its own running-slot guard. Any pureboot
-    # installed staging copy, and rewriting it would only trip its own
+    # with the device's info block serves, since a staged copy only streams
-    # running-slot guard on the composed through-word. Any pureboot with
+    # pages. "Whole" needs both checks — the block where every image carries
-    # the device's own info block serves — the staged copy just streams
+    # it and matching byte for byte, and the slot unchanged since this update
-    # pages, so an older build installs a newer resident all the same. Two
+    # began, so a half-written install takes the path below instead.
-    # checks make "already a loader" mean a *complete* one: the block must
+    current = loader.read_flash(info.stage, SLOT)
    # sit where every image carries it (within the slot's first 256 bytes
    # — the build's position lint), matching the device's block byte for
    # byte, and the slot must be unchanged since this update began (the
    # 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:
-        # On a chip whose staging slot starts at address 0 (the 1 KB
+        # Where the staging slot starts at address 0 (the 1 KB tiny13s) its
-        # tiny13s), its first page carries the reset vector: written last,
+        # first page carries the reset vector, so it goes last: until then a
-        # so any earlier interruption still resets into the old resident,
+        # reset still reaches the old resident.
-        # and from then on resets enter the staging copy.
+        order = list(range(0, SLOT, page))
        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 slot. Where a patched reset
+    # Enter it and let it rewrite the resident. Where a patched reset vector
-    # vector routes through the resident (a tiny with the staging slot away
+    # routes through the resident, word 0 is re-aimed at the staging copy for
-    # from page 0), word 0 is re-aimed at the staging copy around the
+    # the rewrite, so a power loss mid-rewrite still resets into a loader.
    # 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
@@ -894,7 +855,7 @@ 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, info.slot, page))
+    order = list(range(0, SLOT, page))
    if info.stage == 0:
        order = [0] + order[1:]
    write_differing(loader, info.stage, state.staging, order, label="staging restore")
@@ -904,10 +865,9 @@ def op_update_loader(loader, wait, path, state_path, fuse_bytes):
 def check_walk_region(pages, info, fuse_bytes, force):
-    """With BOOTRST programmed but targeting below the loader, reset reaches
+    """BOOTRST programmed below the loader means reset reaches it only by
-    the loader only by walking across erased flash from the boot-section
+    walking across erased flash; application data in that span would divert
-    start; application data in that span would divert reset into itself.
+    reset into itself. Needs the fuses (--fuses or --assume-fuses)."""
    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)
@@ -926,10 +886,9 @@ def check_walk_region(pages, info, fuse_bytes, force):
 def op_erase_flash(loader):
-    """0xff over the whole application area. Descending on a patched-vector
+    """0xff over the application area, descending where the reset vector is
-    chip: page 0 — the patched reset vector — goes last, so an interrupted
+    patched: page 0 goes last, so an interrupted erase still resets into the
-    erase still resets into the loader, and once it is gone the whole area
+    loader — and once it is gone, the erased walk reaches it anyway."""
    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:
@@ -965,11 +924,10 @@ 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 mismatched page is
+    """Read every page back and compare. With `repair`, a mismatch is
-    rewritten and re-read, up to RETRIES times before it is raised: a page
+    rewritten and re-read up to RETRIES times first: a page filled over a
-    filled over a dirty SPM buffer takes stale words, and the write that took
+    dirty SPM buffer takes stale words, and the write that took them cleared
-    them cleared the buffer, so one rewrite settles it. Anything still wrong
+    the buffer, so one rewrite settles it. Anything still wrong is not that."""
    after three is not that, and stops the run."""
    repaired = 0
    with Progress("verify", len(pages)) as bar:
        for address in sorted(pages):
--- a/test/check_pi.py
+++ b/test/check_pi.py
@@ -1,17 +1,11 @@
 #!/usr/bin/env python3
-"""Position-independence lint for the pureboot image.
+"""Position-independence lint: the two link-time facts that let the identical
 image run from any slot, asserted from the built ELF.
-The self-staging design lets the identical binary run from any 512-byte
+  1. No absolute jmp/call — -mrelax normally guarantees it, but a branch that
-slot, which holds only if nothing in the image addresses itself absolutely.
+     grows out of relaxation range would break it silently.
-Two link-time facts guarantee it, both asserted here from the built ELF:
+  2. The info block within the image's first 256 bytes: 'b' rebuilds its
-
+     address as (running slot high byte : link address low byte).
  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>
 """
--- a/test/pbapp.cpp
+++ b/test/pbapp.cpp
@@ -66,9 +66,10 @@ struct link {
 	}
 	[[noreturn]] static void idle()
 	{
-		// 'L' hands back to the loader at the top slot — 512 bytes, or the
+		// 'L' hands back to the loader in the top slot — 512 bytes on every
-		// 1 KiB the >64 KiB chips use.
+		// chip. The jump takes a word address, which is what makes the
-		constexpr std::uint32_t slot = avr::hw::db.mem.flash_size > 65536 ? 1024 : 512;
+		// >64 KiB chips' entry reachable through a 16-bit pointer at all.
 		constexpr std::uint32_t slot = 512;
 		for (;;) {
 			auto command = tx_t::read_blocking();
 			if (command == 'L')
--- a/test/pbdirty.py
+++ b/test/pbdirty.py
@@ -1,15 +1,13 @@
 #!/usr/bin/env python3
-"""Dirty-page-buffer acceptance test: the loader carries no buffer discard,
+"""Dirty-page-buffer acceptance test: with no discard in the loader, a page
-so a page filled over words an earlier writer left behind programs those
+filled over words an earlier writer left takes those instead. The whole
-instead. This asserts the whole contract — the corruption is real and a bare
+contract is asserted — a bare verify sees the corruption, the repairing
-verify sees it, the repairing verify fixes it in one rewrite (the write that
+verify fixes it in one rewrite, and it stays fixed.
 took the stale words auto-erased the buffer), and it stays fixed.
-The state is reached the way the loader cannot prevent: an application
+The state is reached the one way the loader cannot prevent: an application
-dirties the buffer and jumps in with no reset between. Real boot-sectioned
+dirties the buffer and jumps in with no reset between. Boot-sectioned megas
-megas forbid that outright — SPM executes only from the boot section
+forbid that outright (SPM runs only from the boot section, Atmel-8271 §26.2),
-(Atmel-8271 §26.2) — but simavr dispatches SPM from anywhere, which is what
+but simavr dispatches SPM from anywhere, which is what makes it constructible.
 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,19 +1,13 @@
 #!/usr/bin/env python3
-"""Re-homing acceptance test: a pureboot image programmed somewhere other
+"""Re-homing acceptance test: an image programmed somewhere other than its
-than its canonical top slot must still be a working loader —
+canonical slot must still be a working loader, and the ordinary
 position-independent, guarding its accidental slot — and the ordinary
 --update-loader flow must put a build into the top slot from there.
-Two positions are exercised. Address 0 (a raw .bin handed to a programmer,
+Two positions. Address 0, a raw .bin handed to a programmer: the staging
-which defaults to offset 0): the staging install and the word-0 redirect
+install and the word-0 redirect run from copies outside page 0's slot, so the
-both run from copies whose slots are not page 0's, so the running-slot
+running-slot guard never blocks them. And the staging slot itself, where a
-guard never blocks the flow. The staging slot itself: a loader already
+loader already sitting there IS the staging copy — recognized by its embedded
-sitting there IS the installed staging copy — the tool recognizes it by
+block and left in place, then streaming the new resident like any staged copy.
 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>
@@ -90,7 +84,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 - 512
+    stage = base - pb.SLOT
    rehome_from(pbsim, pb, device_bin, elf, hex(stage), hex(stage), update_bin, base, page, baud, app_bin, workdir,
                mcu, hz)
    print("re-home from the staging slot: converged")
--- a/test/pbreloc.py
+++ b/test/pbreloc.py
@@ -1,11 +1,9 @@
 #!/usr/bin/env python3
-"""Position-independence acceptance test: the identical pureboot binary,
+"""Position-independence acceptance test: the identical binary, flashed one
-flashed one slot below the resident loader, must serve the complete command
+slot below the resident, must serve the complete command set from there. The
-set from there. The resident installs it (through-word composed by the host
+info block must come back byte-identical, the write guard must refuse the
-layer), 'J' transfers control, and every command is exercised against the
+staged copy's own slot and permit the resident's, and the staged copy must be
-staged copy — the info block must come back byte-identical, the write guard
+able to rewrite the resident verbatim.
 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>
@@ -83,7 +81,7 @@ def main():
        # Restore the resident image through the staged copy, then 'J' back
        # into it and prove it lives.
-        resident = image + b"\xff" * (info.slot - len(image))
+        resident = image + b"\xff" * (pb.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,15 +1,13 @@
 #!/usr/bin/env python3
-"""End-to-end pureboot protocol test: spawn the simavr device, then drive it
+"""End-to-end protocol test: drive the simavr device with the real host tool
-with the real host tool (pureboot.py, as a subprocess over the device's pty)
+over its pty through flash, EEPROM, fuse and hand-over scenarios, and
-through flash + EEPROM + fuse + hand-over scenarios, and cross-check
+cross-check the tool's view against the simulator's ground-truth dumps.
 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
@@ -57,7 +55,7 @@ def main():
    # the page byte is the wire's 0-means-256.
    mega = mcu.startswith("atmega")
    patch = not mega or mcu.startswith("atmega48")
-    word_flash = base + 512 > 0x10000
+    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(
@@ -127,7 +125,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 + 512) // 2
+        flash_words = (base + pb.SLOT) // 2
        app = open(app_bin, "rb").read()
        word0 = flash_true[0] | (flash_true[1] << 8)
        if rjmp_decode(word0, 0, flash_words) != base // 2:
--- a/test/pbupdate.py
+++ b/test/pbupdate.py
@@ -1,17 +1,12 @@
 #!/usr/bin/env python3
-"""Self-update end-to-end: an application is flashed, then the loader
+"""Self-update end-to-end: an application is flashed, the loader replaces
-replaces itself with a re-timed build through the host tool's
+itself with a re-timed build, and every power-fail phase is rehearsed by
--update-loader — and the power-fail phases of that update are rehearsed by
+killing the device mid-write, restarting it from its flash dump, and letting
-killing the simulated device mid-write, restarting it from its flash dump,
+a re-run complete the update.
 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; the fixture application's 'L' jump is the application-owned
+the application, whose 'L' is the application-owned loader entry — with
-loader entry), with --assume-fuses standing in for the fuse read simavr
+--assume-fuses standing in for the fuse read simavr cannot model.
 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>
@@ -50,7 +45,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 * info.slot), key=lambda b: ladder[b])
+    bits = min((b for b in ladder if ladder[b] * 2 >= 2 * pb.SLOT), key=lambda b: ladder[b])
    fuses = bytearray((0xFF, 0xFF, 0xFF, 0xFF))
    fuses[which] = 0xF8 | (bits << 1) | 1
    return bytes(fuses)
@@ -93,16 +88,13 @@ 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/test_planner.py
+++ b/test/test_planner.py
@@ -1,9 +1,8 @@
 #!/usr/bin/env python3
-"""Host-tool unit tests — the pure planning and policy logic, no simulator:
+"""Host-tool unit tests — the planning and policy logic, no simulator:
-the flash-programming orders and their recovery properties, the reset-vector
+programming orders and their recovery properties, the reset-vector surgery,
-surgery, the staging-slot composition, the mega boot-fuse decode, and the
+the staging composition, the boot-fuse decode, and the update preflight over
-update preflight's error/warning matrix (fuse combinations simavr cannot
+fuse combinations simavr cannot model.
 model reach it here as synthetic bytes).
 Usage: test_planner.py <tool_py>
 """
@@ -34,7 +33,8 @@ def info_of(pb, base, page, patch, flash, signature=(0x1E, 0x93, 0x0B), word_fla
    raw = bytes((0x50, 0x42, pb.NEWEST_LOADER if version is None else version,
                 *signature, page & 0xFF, wire_base & 0xFF, wire_base >> 8, 0, 2, flags))
    info = pb.Info(raw)
-    assert info.flash_size == flash
+    if info.flash_size != flash:
        fail(f"info_of({base:#x}) decodes to {info.flash_size:#x} of flash, not {flash:#x}")
    return info
@@ -94,9 +94,7 @@ def main():
        ((0x1E, 0x97, 0x05), 0x20000, 3, {0b11: 0x1FC00, 0b10: 0x1F800, 0b01: 0x1F000, 0b00: 0x1E000}),  # 1284P
    )
    for signature, flash, which, ladder in cases:
-        # Word-addressed chips carry the 1 KiB slot (their smallest boot sector).
+        chip = info_of(pb, flash - pb.SLOT, 128 if flash < 0x20000 else 0, False, flash,
        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))
@@ -109,10 +107,12 @@ 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/page ride the wire scaled,
+    # Word-addressed info decode: the 1284P's base and page ride the wire
-    # and its slot is 1 KiB.
+    # scaled — a 17-bit base halved into the block's two bytes, a 256-byte page
-    big = info_of(pb, 0x1FC00, 0, False, 0x20000, signature=(0x1E, 0x97, 0x05), word_flash=True)
+    # spelled 0 — and its slot is the same 512 bytes as everywhere else, so its
-    if big.page != 256 or big.base != 0x1FC00 or big.stage != 0x1F800 or big.slot != 1024:
+    # staging slot lands inside the 1 KiB minimum boot section.
    big = info_of(pb, 0x1FE00, 0, False, 0x20000, signature=(0x1E, 0x97, 0x05), word_flash=True)
    if big.page != 256 or big.base != 0x1FE00 or big.stage != 0x1FC00:
        fail(f"word-addressed info decode: page {big.page}, base {big.base:#x}, stage {big.stage:#x}")
    # Surgery: word 0 lands on the loader, the trampoline on the original
@@ -215,6 +215,15 @@ 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.