build: the submodule is how libavr arrives; the era already carries it

The pin the whole history now encodes becomes the primary route: the
submodule default replaces FetchContent and the unpinned forge fallback,
LIBAVR_ROOT stays as the tandem-development override, the presets already
take the toolchain file from the submodule, and the Studio projects anchor
their include path there — correct by construction. The version tags and
the one-command historical build are documented beside the version map.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

CMakeLists.txt

@@ -2,21 +2,19 @@ cmake_minimum_required(VERSION 3.28)
 
 project(tsb_libavr LANGUAGES CXX)
 
-# libavr from a local checkout (LIBAVR_ROOT) or the forge; the toolchain file
-# comes from the same checkout via CMakePresets.json.
-include(FetchContent)
+# libavr rides as the pinned submodule; LIBAVR_ROOT (cache or environment)
+# overrides it for tandem development against a working tree. The toolchain
+# file comes from the submodule via CMakePresets.json either way.
 if(NOT LIBAVR_ROOT AND DEFINED ENV{LIBAVR_ROOT})
 	set(LIBAVR_ROOT $ENV{LIBAVR_ROOT})
 endif()
 if(NOT LIBAVR_ROOT)
 	set(LIBAVR_ROOT ${CMAKE_CURRENT_SOURCE_DIR}/libavr)
 endif()
-if(LIBAVR_ROOT)
-	FetchContent_Declare(libavr SOURCE_DIR ${LIBAVR_ROOT})
-else()
-	FetchContent_Declare(libavr GIT_REPOSITORY git@git.blackmark.me:avr/libavr.git GIT_TAG main)
+if(NOT EXISTS ${LIBAVR_ROOT}/CMakeLists.txt)
+	message(FATAL_ERROR "libavr not found at ${LIBAVR_ROOT} — run: git submodule update --init libavr")
 endif()
-FetchContent_MakeAvailable(libavr)
+add_subdirectory(${LIBAVR_ROOT} libavr-build)
 
 if(PROJECT_IS_TOP_LEVEL)
 	add_compile_options(-Werror) # warnings are errors for the port's own code
@@ -97,6 +95,10 @@ endfunction()
 #   tsb_pure  — pure idiomatic libavr, one function per command, TU-local
 #                 (internal linkage), streaming (no SRAM page buffer): 836 B in
 #                 the 1 KB section.
+#   tsb_policy — the policy floor: pureboot's rules (no asm, no register
+#                 variables) with every pureboot lesson applied. 638 B in the
+#                 1 KB section — the measured evidence that the 512 B fit is a
+#                 property of the mechanisms philosophy #5 bans.
 #
 # add_tsb_variant(<name> <boot-section-bytes>)
 function(add_tsb_variant name bytes)
@@ -124,8 +126,13 @@ endfunction()
 # chips build pureboot alone.
 if(LIBAVR_MCU STREQUAL "atmega328p")
 	add_tsb_variant(tsb_asm 512)
+	add_tsb_variant(tsb_policy 1024)
 	add_tsb_variant(tsb_pure 1024)
 	add_tsb_variant(tsb_tricks 1024)
+	# The policy tier's floor is measured with the loop flags pureboot's size
+	# work found (a loader's loop bodies all contain calls); the other tiers
+	# keep the flag set their recorded floors were measured with — none.
+	target_compile_options(tsb_policy PRIVATE -fno-move-loop-invariants -fno-tree-ter)
 endif()
 
 # pureboot — the pure-constraint port (see pureboot/README.md): one source,
@@ -160,6 +167,10 @@ if(PROJECT_IS_TOP_LEVEL)
 		add_test(NAME pureboot.planner
 		         COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/test/test_planner.py
 		                 ${CMAKE_CURRENT_SOURCE_DIR}/pureboot/pureboot.py)
+		add_test(NAME pureboot.handshake
+		         COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/test/test_handshake.py)
+		add_test(NAME pureboot.updatelink
+		         COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/test/test_update_link.py)
 	endif()
 
 	# The protocol test flashes this fixture through the loader with the real
@@ -238,12 +249,12 @@ if(PROJECT_IS_TOP_LEVEL)
 
 	# The size matrix: every configuration axis that could move the image
 	# size — the serial backend (different code), the USART instance
-	# (different registers), the clock (different constants), and the baud
-	# through the shapes its bit timing takes — each combination must still
-	# fit the chip's slot budget. Pins are size-neutral (port and bit are
-	# immediate operands) and the timeout is a constant, so neither adds an
-	# axis. The stock build is one point of this matrix and already has its
-	# test.
+	# (different registers), the clock (different constants), the baud
+	# through the shapes its bit timing takes, and the pins through the one
+	# thing they decide (whether a bit-banged link has to release the USART
+	# that owns them) — each combination must still fit the chip's slot
+	# budget. The timeout is a constant and adds no 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
@@ -261,18 +272,25 @@ if(PROJECT_IS_TOP_LEVEL)
 	                 -DLIMIT=${PUREBOOT_LIMIT} -P ${CMAKE_CURRENT_SOURCE_DIR}/test/check_size.cmake)
 
 	# One point of the exhaustive matrix, named from its resolved parameters
-	# so the enumeration cannot collide with itself. Unreachable rates drop
-	# out here rather than aborting the configure.
-	function(pureboot_matrix_point hz baud link)
+	# so the enumeration cannot collide with itself. `pins` is empty for the
+	# default pair, or the index of the USART whose own pins a bit-banged
+	# link sits on. Unreachable rates drop out here rather than aborting the
+	# configure.
+	function(pureboot_matrix_point hz baud link pins)
+		set(_name pbm_${hz}_${baud}_${link})
 		if(link STREQUAL "software")
 			pureboot_baud_feasible(${hz} ${baud} 1 _ok)
 			set(_args SERIAL software)
+			if(NOT pins STREQUAL "")
+				list(APPEND _args RX ${PUREBOOT_USART${pins}_RX} TX ${PUREBOOT_USART${pins}_TX})
+				set(_name ${_name}_on${pins})
+			endif()
 		else()
 			pureboot_baud_feasible(${hz} ${baud} 0 _ok)
 			set(_args USART ${link})
 		endif()
 		if(_ok)
-			pureboot_size_variant(pbm_${hz}_${baud}_${link} CLOCK ${hz} BAUD ${baud} ${_args})
+			pureboot_size_variant(${_name} CLOCK ${hz} BAUD ${baud} ${_args})
 		endif()
 	endfunction()
 
@@ -310,12 +328,14 @@ if(PROJECT_IS_TOP_LEVEL)
 	if(DEFINED ENV{PUREBOOT_FULL_MATRIX})
 		foreach(_matrix_hz IN LISTS _full_clocks)
 			foreach(_matrix_baud IN LISTS _full_bauds)
-				pureboot_matrix_point(${_matrix_hz} ${_matrix_baud} software)
+				pureboot_matrix_point(${_matrix_hz} ${_matrix_baud} software "")
 				if(PUREBOOT_HAS_USART)
-					pureboot_matrix_point(${_matrix_hz} ${_matrix_baud} 0)
+					pureboot_matrix_point(${_matrix_hz} ${_matrix_baud} software 0)
+					pureboot_matrix_point(${_matrix_hz} ${_matrix_baud} 0 "")
 				endif()
 				if(PUREBOOT_HAS_USART1)
-					pureboot_matrix_point(${_matrix_hz} ${_matrix_baud} 1)
+					pureboot_matrix_point(${_matrix_hz} ${_matrix_baud} software 1)
+					pureboot_matrix_point(${_matrix_hz} ${_matrix_baud} 1 "")
 				endif()
 			endforeach()
 		endforeach()
@@ -334,11 +354,42 @@ if(PROJECT_IS_TOP_LEVEL)
 		endforeach()
 		list(GET _matrix_clocks -1 _matrix_top_hz)
 		pureboot_size_variant(pureboot_sw_wide CLOCK ${_matrix_top_hz} BAUD 9600 SERIAL software)
+		# The pin axis at the widest software image — the slowest ladder rate
+		# against the fastest clock, whose bit spin needs the 16-bit delay
+		# loop — with the USART release on top of it. The exhaustive sweep
+		# above carries the same axis across its whole cross product.
+		if(PUREBOOT_HAS_USART)
+			pureboot_size_variant(pureboot_sw_wide_on_usart0 CLOCK ${_matrix_top_hz} BAUD 9600
+			                      SERIAL software RX ${PUREBOOT_USART0_RX} TX ${PUREBOOT_USART0_TX})
+		endif()
+		if(PUREBOOT_HAS_USART1)
+			pureboot_size_variant(pureboot_sw_wide_on_usart1 CLOCK ${_matrix_top_hz} BAUD 9600
+			                      SERIAL software RX ${PUREBOOT_USART1_RX} TX ${PUREBOOT_USART1_TX})
+		endif()
 	endif()
 	if(PUREBOOT_HAS_USART1)
 		pureboot_size_variant(pureboot_usart1 USART 1)
 	endif()
 
+	# The pin axis at its fixed points, in both matrix modes. The autobaud
+	# loader carries no clock and no baud, so the sweep has nothing to vary
+	# for it — yet it is the tightest image in the space, and on a USART's
+	# own pins it pays the release too: that combination is the one that
+	# overflowed the 1284's slot. The software build on those pins is the
+	# same deployment the mute test drives.
+	if(PUREBOOT_HAS_USART)
+		pureboot_size_variant(pureboot_sw_on_usart0 SERIAL software
+		                      RX ${PUREBOOT_USART0_RX} TX ${PUREBOOT_USART0_TX})
+		pureboot_size_variant(pureboot_autobaud_on_usart0 SERIAL autobaud
+		                      RX ${PUREBOOT_USART0_RX} TX ${PUREBOOT_USART0_TX})
+	endif()
+	if(PUREBOOT_HAS_USART1)
+		pureboot_size_variant(pureboot_sw_on_usart1 SERIAL software
+		                      RX ${PUREBOOT_USART1_RX} TX ${PUREBOOT_USART1_TX})
+		pureboot_size_variant(pureboot_autobaud_on_usart1 SERIAL autobaud
+		                      RX ${PUREBOOT_USART1_RX} TX ${PUREBOOT_USART1_TX})
+	endif()
+
 	# One configured deployment end to end — a real board's shape rather
 	# than the stock assumption: the ATmega328P on its shipped 1 MHz fuses,
 	# the software UART on hand-picked pins (TX = PB1, RX = PB5), the ladder
@@ -367,6 +418,33 @@ if(PROJECT_IS_TOP_LEVEL)
 		set_tests_properties(pureboot.custom PROPERTIES TIMEOUT 180)
 	endif()
 
+	# Hand-over with the USART that owns the loader's pins left enabled — the
+	# state an application reaches by jumping in without a reset, and the one
+	# that made a bit-banged loader on PD0/PD1 (where the Uno's USB bridge
+	# lands) receive and obey while answering nothing. Run where it was found
+	# on silicon; the runner supplies the pin ownership simavr has no model
+	# for, which is what lets this fail when the release is gone.
+	if(LIBAVR_MCU STREQUAL "atmega328p" AND DEFINED PB_DEVICE)
+		get_target_property(_mute_hz pureboot_sw_on_usart0 PUREBOOT_HZ)
+		get_target_property(_mute_baud pureboot_sw_on_usart0 PUREBOOT_BAUD)
+		get_target_property(_mute_link pureboot_sw_on_usart0 PUREBOOT_LINK)
+		add_executable(pbapp_handover test/pbapp.cpp)
+		target_link_libraries(pbapp_handover PRIVATE libavr)
+		target_compile_definitions(pbapp_handover PRIVATE PUREBOOT_CLOCK_HZ=${_mute_hz}
+		                           PUREBOOT_BAUD=${_mute_baud} PUREBOOT_HANDOVER)
+		add_custom_command(TARGET pbapp_handover POST_BUILD
+		                   COMMAND ${CMAKE_OBJCOPY} -O binary
+		                           $<TARGET_FILE:pbapp_handover> $<TARGET_FILE:pbapp_handover>.bin)
+		add_test(NAME pureboot.mute
+		         COMMAND ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/test/pbmute.py
+		                 ${PB_DEVICE} $<TARGET_FILE:pureboot_sw_on_usart0> ${PUREBOOT_SIM_MCU} ${_mute_hz}
+		                 ${PUREBOOT_BASE_HEX} ${PUREBOOT_PAGE} ${_mute_baud}
+		                 $<TARGET_FILE:pbapp_handover>.bin
+		                 ${CMAKE_CURRENT_SOURCE_DIR}/pureboot/pureboot.py
+		                 ${CMAKE_BINARY_DIR}/pbmute-work ${_mute_link})
+		set_tests_properties(pureboot.mute PROPERTIES TIMEOUT 180)
+	endif()
+
 	# The second USART, driven for real on one chip: instance selection is
 	# compile-checked everywhere, but only a live session proves the loader
 	# initialized and polls the USART it claims to. The fixture application

ide/README.md

@@ -0,0 +1,77 @@
+# Atmel Studio
+
+`master` carries `bootloader.atsln`, so this branch does too: `ide/bootloader.atsln`
+builds the loaders from the same sources Ninja does, to a **byte-identical
+`.text`** — 404 B for the 328P pureboot loader, 510 B for the `tsb_asm` tier in
+its 512-byte section. CMake remains the build system; the solution is here so the
+port opens in Studio as its predecessor did.
+
+## The two projects, and why two
+
+pureboot is a chip × backend × clock × baud matrix — `pureboot_add_loader()`
+resolves a deployment into compile definitions — and a `.cppproj` is one binary
+at one set of flags, so a project can only ever be one point of it. `pureboot`
+is that point: the stock 328P deployment, USART0 at 115200 on a 16 MHz crystal,
+an 8-second activation window. `tsb_asm` is the TinySafeBoot tier that occupies
+the same 512-byte section `master`'s `tsb` project targeted.
+
+The other three tsb tiers (`tsb_pure`, `tsb_tricks`, `tsb_policy`) are not here.
+They differ from `tsb_asm` in their source file, their section size, and — for
+`tsb_policy` — two loop flags; nothing about that is a Studio concern, and what
+they exist to demonstrate is a size gradient only the CMake size tests measure.
+Adding one is a copy of `tsb_asm/tsb_asm.cppproj` in its own directory, with its
+name, its GUID, its source path and its `--section-start` changed (`0x7c00` for
+the 1 KiB tiers), plus four lines in the solution.
+
+`avrdevice` is a project property, so each project gets its own directory:
+Studio builds into `<project dir>/<Configuration>` whatever `OutputDirectory`
+says, and two projects sharing a directory would share one object file.
+
+## Debug keeps `-Os`
+
+Both configurations compile at `-Os`; Debug adds only `-gdwarf-4`. The `.text`
+is therefore identical in both, which is the point — a loader's section is a
+**correctness** bound and not a budget. `-Og` builds this same source to 590 B,
+and linking it at `--section-start=.text=0x7e00` on a 32 KiB part puts 78 bytes
+past flash end **without a diagnostic**: `rcall`/`rjmp` targets there wrap
+modulo flash size, so the image dies right after activation. A debug
+configuration that silently produces that is worse than none, and DWARF costs no
+flash, so the optimisation level stays where correctness needs it.
+
+## What Studio needs from the machine
+
+libavr from the **submodule**, found at
+`$(MSBuildProjectDirectory)\..\..\libavr\include` — correct by construction, and
+anchored to the project because a plain relative path resolves against the
+generated makefile's directory (the configuration's output directory), not the
+project's. There is no `LIBAVR_ROOT` escape hatch: a variable exported in a
+shell is invisible to Studio launched from the Start menu, and the failure reads
+as a missing `libavr/libavr.hpp` — which is what the submodule answers.
+
+A GCC 16.1 toolchain registered as flavour `avr-g++-16.1.0`, nothing older
+reaching `-std=c++26`.
+
+## Generating and gating
+
+One generated file is required before a project will load at all, and one command
+per project checks the flags have not drifted (both from libavr's
+`tools/atmelstudio/`):
+
+```sh
+for name in pureboot tsb_asm; do
+    python libavr/tools/atmelstudio/componentinfo.py \
+        "ide/$name/$name.componentinfo.xml" --device ATmega328P
+    python libavr/tools/atmelstudio/check-flags.py \
+        --solution ide/bootloader.atsln --project "$name" --target "$name" \
+        --compile-commands build/atmega328p-generated/compile_commands.json \
+        --log "build/as-$name.log"
+done
+```
+
+`--project` because one reference describes one binary; `--target` because
+`pureboot.cpp` is compiled by every point of the size matrix and the flags
+differ per point, so the basename alone does not name a reference. Release is
+what the gate compares — the presets define no debug build, and Debug differs
+from Release only in `-gdwarf-4`.
+
+Legacy (the yazoalfa-era submodules) stays on `master`.

ide/bootloader.atsln

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

ide/pureboot/pureboot.cppproj

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

ide/tsb_asm/tsb_asm.cppproj

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

pureboot/CMakeLists.txt

@@ -116,6 +116,17 @@ else()
 	math(EXPR _pb_limit "${_pb_slot} - 2")
 endif()
 
+# The pins each USART owns. A bit-banged link deployed on them has to release
+# that USART before it can drive the line, and those instructions are the one
+# way the choice of pins moves the image — so a size matrix needs them as an
+# axis even though pins are otherwise immediate operands. Uniform across every
+# mega libavr covers: USART0 (the classics' un-numbered USART included) on
+# PD0/PD1, USART1 on PD2/PD3.
+set(_pb_usart0_rx pd0)
+set(_pb_usart0_tx pd1)
+set(_pb_usart1_rx pd2)
+set(_pb_usart1_tx pd3)
+
 # simavr names its cores after the base dies; the A revisions run on them
 # (the 644PA on the 644P core).
 set(_pb_sim_mcu ${LIBAVR_MCU})
@@ -133,6 +144,8 @@ set_property(GLOBAL PROPERTY PUREBOOT_WRAP "${_pb_wrap}")
 set_property(GLOBAL PROPERTY PUREBOOT_DEFAULT_HZ ${_pb_hz})
 set_property(GLOBAL PROPERTY PUREBOOT_HAS_USART ${_pb_has_usart})
 set_property(GLOBAL PROPERTY PUREBOOT_HAS_USART1 ${_pb_has_usart1})
+set_property(GLOBAL PROPERTY PUREBOOT_USART0_TX ${_pb_usart0_tx})
+set_property(GLOBAL PROPERTY PUREBOOT_USART1_TX ${_pb_usart1_tx})
 
 # The port's own build (tests, the size matrix) reads the geometry from the
 # parent scope; a downstream consumer gets the same variables for free.
@@ -145,6 +158,10 @@ set(PUREBOOT_DEFAULT_HZ ${_pb_hz} PARENT_SCOPE)
 set(PUREBOOT_HAS_USART ${_pb_has_usart} PARENT_SCOPE)
 set(PUREBOOT_HAS_USART1 ${_pb_has_usart1} PARENT_SCOPE)
 set(PUREBOOT_SIM_MCU ${_pb_sim_mcu} PARENT_SCOPE)
+set(PUREBOOT_USART0_RX ${_pb_usart0_rx} PARENT_SCOPE)
+set(PUREBOOT_USART0_TX ${_pb_usart0_tx} PARENT_SCOPE)
+set(PUREBOOT_USART1_RX ${_pb_usart1_rx} PARENT_SCOPE)
+set(PUREBOOT_USART1_TX ${_pb_usart1_tx} PARENT_SCOPE)
 
 # The rates a default may pick, fastest first.
 set_property(GLOBAL PROPERTY PUREBOOT_BAUD_LADDER 115200 57600 38400 19200 9600)
@@ -200,7 +217,8 @@ endfunction()
 # The loader target plus its flashable images (<name>.hex for a programmer,
 # <name>.bin for --update-loader). The resolved deployment is stamped on the
 # target as PUREBOOT_HZ / PUREBOOT_BAUD / PUREBOOT_LINK (the link spelled
-# usart0, usart1 or sw:<RX>,<TX>) — what a test harness speaks to it with.
+# usart0, usart1, or sw:<RX>,<TX> with a trailing @<n> where those pins are a
+# USART's own) — what a test harness speaks to it with.
 #
 # SERIAL autobaud measures the host's bit timing at run time, so the image
 # carries no clock and no baud: CLOCK and BAUD are not build parameters there,
@@ -275,11 +293,21 @@ function(pureboot_add_loader name)
 			else()
 				set(_serial_defines PUREBOOT_SOFT_SERIAL PUREBOOT_RX=${PB_RX} PUREBOOT_TX=${PB_TX})
 			endif()
-			# sw:<RX>,<TX> as port letter and bit, upcased.
+			# sw:<RX>,<TX> as port letter and bit, upcased — with @<n> where
+			# the TX pin is a USART's own TXD, since a harness driving that
+			# link has to know the USART owns the pin until the loader
+			# releases it.
 			string(SUBSTRING ${PB_RX} 1 2 _rx_pin)
 			string(SUBSTRING ${PB_TX} 1 2 _tx_pin)
 			string(TOUPPER "sw:${_rx_pin},${_tx_pin}" _link)
 			string(REPLACE "SW" "sw" _link ${_link})
+			get_property(_tx0 GLOBAL PROPERTY PUREBOOT_USART0_TX)
+			get_property(_tx1 GLOBAL PROPERTY PUREBOOT_USART1_TX)
+			if(_usart AND PB_TX STREQUAL _tx0)
+				set(_link "${_link}@0")
+			elseif(_usart1 AND PB_TX STREQUAL _tx1)
+				set(_link "${_link}@1")
+			endif()
 		endif()
 	endif()
 	if(NOT PB_BAUD)

pureboot/README.md

@@ -28,31 +28,32 @@ it carries the calibration machinery and no clock at all.
 
 | Chip | Flash | Loader at | Link | Stock | Autobaud |
 |---|---|---|---|---|---|
-| ATtiny13, ATtiny13A † | 1 KiB | 0x0200 | software | 402 B | 472 B |
-| ATtiny25 † | 2 KiB | 0x0600 | software | 406 B | 476 B |
-| ATtiny45 † | 4 KiB | 0x0e00 | software | 410 B | 480 B |
-| ATtiny85 † | 8 KiB | 0x1e00 | software | 410 B | 480 B |
-| ATmega8, 8A | 8 KiB | 0x1e00 | USART0 | 372 B | 486 B |
-| ATmega16, 16A | 16 KiB | 0x3e00 | USART0 | 374 B | 490 B |
-| ATmega32, 32A | 32 KiB | 0x7e00 | USART0 | 374 B | 490 B |
-| ATmega48, 48A, 48P, 48PA † | 4 KiB | 0x0e00 | USART0 | 400 B | 476 B |
-| ATmega88, 88A, 88P, 88PA | 8 KiB | 0x1e00 | USART0 | 410 B | 486 B |
-| ATmega168, 168A, 168P, 168PA | 16 KiB | 0x3e00 | USART0 | 412 B | 490 B |
-| ATmega328, 328P | 32 KiB | 0x7e00 | USART0 | 412 B | 490 B |
-| ATmega164A, 164P, 164PA | 16 KiB | 0x3e00 | USART0 | 412 B | 490 B |
-| ATmega324A, 324P, 324PA | 32 KiB | 0x7e00 | USART0 | 412 B | 490 B |
-| ATmega644, 644A, 644P, 644PA | 64 KiB | 0xfe00 | USART0 | 406 B | 484 B |
-| ATmega1284, 1284P | 128 KiB | 0x1fe00 | USART0 | 432 B | 510 B |
+| ATtiny13, ATtiny13A † | 1 KiB | 0x0200 | software | 394 B | 464 B |
+| ATtiny25 † | 2 KiB | 0x0600 | software | 398 B | 468 B |
+| ATtiny45 † | 4 KiB | 0x0e00 | software | 402 B | 472 B |
+| ATtiny85 † | 8 KiB | 0x1e00 | software | 402 B | 472 B |
+| ATmega8, 8A | 8 KiB | 0x1e00 | USART0 | 364 B | 478 B |
+| ATmega16, 16A | 16 KiB | 0x3e00 | USART0 | 366 B | 482 B |
+| ATmega32, 32A | 32 KiB | 0x7e00 | USART0 | 366 B | 482 B |
+| ATmega48, 48A, 48P, 48PA † | 4 KiB | 0x0e00 | USART0 | 392 B | 468 B |
+| ATmega88, 88A, 88P, 88PA | 8 KiB | 0x1e00 | USART0 | 402 B | 478 B |
+| ATmega168, 168A, 168P, 168PA | 16 KiB | 0x3e00 | USART0 | 404 B | 482 B |
+| ATmega328, 328P | 32 KiB | 0x7e00 | USART0 | 404 B | 482 B |
+| ATmega164A, 164P, 164PA | 16 KiB | 0x3e00 | USART0 | 404 B | 482 B |
+| ATmega324A, 324P, 324PA | 32 KiB | 0x7e00 | USART0 | 404 B | 482 B |
+| ATmega644, 644A, 644P, 644PA | 64 KiB | 0xfe00 | USART0 | 398 B | 476 B |
+| ATmega1284, 1284P | 128 KiB | 0x1fe00 | USART0 | 424 B | 502 B |
 
 † No hardware boot section: the host patches the reset vector, and the budget
 is 510 bytes, since the slot's last word is the trampoline.
 
-The tightest fit in the whole space is the 1284s' autobaud build, 510 of its
-512 — they alone carry the far-flash machinery (ELPM reads, RAMPZ page
-commands) and autobaud alone carries the calibration loop. Everything else has
-20 B of headroom or more. The flash bank riding in a transfer's selector byte
-keeps even those chips' addressing the same 16-bit form every other chip uses,
-which is why they are no longer the outlier they were.
+The tightest fit in the whole space is the 1284s' autobaud build deployed on a
+USART's own pins, 506 of its 512 — they alone carry the far-flash machinery
+(ELPM reads, RAMPZ page commands), autobaud alone carries the calibration loop,
+and a bit-banged link on a USART's pins alone has to release it (below). The
+same build on the default pins is 502. The flash bank riding in a transfer's
+selector byte keeps even those chips' addressing the same 16-bit form every
+other chip uses, which is why they are no longer the outlier they were.
 
 The software UART enables the RX pull-up; TX idles high. All multi-byte wire
 quantities are little-endian.
@@ -79,6 +80,13 @@ receiver's 100-cycles-a-bit floor. Whatever is picked or overridden is
 re-checked in the compile: an infeasible combination, or a USART the chip does
 not have, fails with a named static assert.
 
+Putting a bit-banged link on a USART's own pins is a supported deployment, and
+the usual one where a board's USB bridge is wired to RXD/TXD: the link's `init`
+clears that USART's `UCSRnB` first, because while its `TXEN` is set the USART —
+not the port register — owns the TX pin, and a loader entered from an
+application that left it enabled would receive and obey while answering nothing
+(§20.2). It costs four bytes, and only on those pins.
+
 `SERIAL autobaud` takes neither: the loader **measures** the host's bit timing
 at run time, so `CLOCK` and `BAUD` are not build parameters there and one
 binary per chip serves every clock and every rate. It is for the deployments
@@ -90,6 +98,27 @@ needs its divisor programmed) and that activation counts poll iterations rather
 than seconds, since there is no clock to convert them against
 (`PUREBOOT_AUTOBAUD_POLLS`, default 4,000,000).
 
+**Pick the rate by cycles a bit, and leave the oscillator room.** What the
+calibration can measure is bounded by how many clock cycles one bit lasts, so a
+rate is only ever sensible relative to the clock. Two different floors matter:
+
+| | cycles a bit |
+|---|---|
+| the logic's floor — exact clock, simulated | solid to ~36, fails outright by ~31 (`pureboot.autobaud` gates a point here) |
+| a factory-trimmed internal RC, measured on an ATtiny13A | reliable at ~118; already locking 1 attempt in 5 by ~59 |
+
+The gap is the oscillator's own jitter, and no exact-clock simulation shows it.
+So on an RC part, **budget about 100 cycles a bit** — the same order as the
+fixed-baud software receiver's floor — rather than the logic's ~36. Measured
+envelope on that ATtiny13A, with an application resident: 9.6 and 4.8 MHz reach
+115200, 1.2 MHz reaches 9600, 600 kHz reaches 4800, 128 kHz reaches 2400.
+
+One trap in testing this: on a patched-vector chip an **erased** application
+region walks straight back up into the loader, so every expired window opens
+another one and the host's retries eventually catch the pulse. That reads as far
+more reliable than the same part with an application resident, which gets one
+window per reset. Measure with an application in place.
+
 A downstream project brings its usual libavr setup (the `libavr` target, the
 chip via the `LIBAVR_MCU` toolchain preset), consumes this directory, and
 states its deployment — an ATmega328P on its shipped 1 MHz fuses with the
@@ -258,6 +287,14 @@ from `b`, and a command per memory (`R`/`W` flash, `r`/`w` EEPROM, `F` fuses).
 above; the shipped tool speaks both, choosing on the version it reads, so a
 deployed pureboot 4 stays drivable and self-updatable to 5.
 
+Every closed generation is tagged in this repo at its era's last commit — the
+commit just before the next version bump, so a tag holds everything its
+version ever gained — and each tag carries the `libavr/` submodule pinned to
+the libavr that loader was built against, as the whole libavr era does commit
+by commit. `git checkout v3 && git submodule update --init libavr` followed by
+the usual preset build therefore reproduces the v3 loader exactly; the open
+generation is `main`.
+
 Collapsing four command bodies into one transfer loop is what paid for the
 version: the data space, the host-issued SPM operations and the fuses now share
 the loop, the cursor and the argument decode that `R`/`r`/`w` each carried a
@@ -320,6 +357,23 @@ 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.
 
+One thing the image cannot tell the host: **which link it speaks.** The update
+works by entering copies of the *new* image (steps 3 and 4 below), so a build
+made for another baud or another backend answers on that one and not on the
+session's — and 512 bytes of position-independent code carry no header to read
+it from. Where the new image's link differs, name it:
+
+```sh
+# a 57600 fixed-baud resident, replaced by an autobaud build
+pureboot.py --port … --baud 57600 --update-loader ab.bin --staged-autobaud
+# …or by a 38400 build of the same backend
+pureboot.py --port … --baud 57600 --update-loader sw38400.bin --staged-baud 38400
+```
+
+The host retunes on the open port, so no DTR pulse resets the copy it is talking
+to. Omit them against a changed link and the update stops after installing the
+staging copy, saying so and naming this as the cause.
+
 The preflight refuses an image built for another chip: the stamp every pureboot
 binary carries must resolve to the device's own geometry, and the error names
 both. Die revisions share their base signature and geometry, so their images
@@ -340,10 +394,15 @@ are interchangeable — as the silicon is.
    content, and the state file is discarded.
 
 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 file
-carries the only bytes not recoverable from the device; losing it mid-update
-still completes the update, and the staging region comes back by reflashing
-the application. A boot-sectioned mega needs its fuses for the preflight — read
+the same command after any interruption resumes and completes — with one
+qualification, which is the link again: from step 2 on, the copy the re-run has
+to reach is the *new* image, so a resumed run needs the same `--staged-*` as the
+first one. On a patched-vector part step 3 also re-aims word 0 at the staging
+copy, so after that point a reset reaches the new image's link and **only** that
+one; a re-run on the resident's link finds nothing at all. The state file carries
+the only bytes not recoverable from the device; losing it mid-update still
+completes the update, and the staging region comes back by reflashing the
+application. A boot-sectioned mega needs its fuses for the preflight — read
 from the device, or supplied with `--assume-fuses` where reading is impossible
 (simulators).
 
@@ -378,6 +437,21 @@ SRAM, and through the same address space the register file and every I/O
 register. Reading an I/O register can have side effects (reading UDR clears its
 flags), which is the caller's business to know.
 
+Reads are safe anywhere; **two small regions cannot be written without ending the
+session,** because they are what the loader is standing on:
+
+- the **top of SRAM**, where its stack lives — a handful of bytes below RAMEND;
+- on an **autobaud** build, the **two bytes at RAMSTART**: the measured bit
+  period, in `.noinit`, which is the whole of that loader's static RAM. Overwrite
+  it and its next reply is timed against garbage. On an ATtiny13A that is
+  `0x60..0x61`, and the symptom is a mangled prompt byte rather than any error —
+  the loader is fine, it simply is no longer speaking the agreed rate.
+
+Both are self-inflicted rather than defects, and a reset clears them. Note also
+that `--poke` can write OSCCAL, which does take effect — but a session can only
+survive a step or two of it before the clock walks the link out of the rate
+autobaud locked to, and OSCCAL reverts on reset regardless.
+
 Readouts come one fact per line: `--info` prints the device's version and
 signature and the geometry that follows from them, `--fuses` each fuse byte
 plus, on a boot-sectioned mega, its decoded meaning. Transfers that take wire time draw a transient progress bar on stderr
@@ -386,8 +460,11 @@ counts, the programming plan, update state handling and per-phase page counts.
 
 ## Tests
 
-`tools/check.sh` runs every chip's workflow (`--full` adds the reflect-mode
-builds of libavr's spot set; `tools/make_presets.py` regenerates the presets).
+libavr rides as the `libavr/` submodule (`git submodule update --init libavr`);
+`LIBAVR_ROOT` (cache or environment) overrides it for tandem development
+against a working tree. `tools/check.sh` runs every chip's workflow (`--full`
+adds the reflect-mode builds of libavr's spot set; `tools/make_presets.py`
+regenerates the presets).
 Per chip preset, `ctest` runs:
 
 - `pureboot.size` — the 510-byte (patched-vector) / 512-byte budget;
@@ -397,8 +474,10 @@ Per chip preset, `ctest` runs:
   the fastest clock — where a software UART's per-bit spin outgrows its
   one-register delay loop and takes the 16-bit one. That is the largest image
   the configuration space produces, and a shape the ladder default (always the
-  *fastest* rate a clock reaches) never picks. Pins are immediate operands and
-  the timeout is a constant: neither is an axis;
+  *fastest* rate a clock reaches) never picks. Pins are an axis for one reason
+  only, and it is enough: a bit-banged link on a USART's own pins has to
+  release that USART, so `pureboot_{sw,autobaud}_on_usart{0,1}` build there
+  too. The timeout is a constant and is no axis;
 - `pureboot_autobaud.size` — the clock-free build, which has no clock or baud
   axis of its own: one binary per chip has to serve every point the matrix
   below sweeps;
@@ -412,6 +491,14 @@ Per chip preset, `ctest` runs:
   flash-resident section but `.text`, and the image byte-identical when linked
   at a different base — which is position independence itself rather than a
   proxy for it;
+- `pureboot.handshake` — the host tool's activation must not hang on a target
+  that never falls quiet: the drain after a prompt is bounded by the handshake
+  deadline, and a well-behaved loader still connects;
+- `pureboot.updatelink` — an update whose image changes the baud or the backend
+  must follow the staging copy onto *its* link, since that copy is the new image;
+  and where nothing was declared, the failure must name the link rather than
+  report a bare activation timeout, because by then the staging slot is written
+  and on a 1 KiB tiny that was the application;
 - `pureboot.planner` — the host tool's pure logic: programming orders and their
   recovery properties, the surgery, the staging composition, the boot-fuse
   decode, the update preflight over synthetic fuse bytes, and the repairing
@@ -434,6 +521,12 @@ Per chip preset, `ctest` runs:
 - `pureboot.usart1` (644A) — the same suite over the second hardware USART:
   instance selection is compile-checked everywhere, but only a live session
   proves the loader polls the USART it claims;
+- `pureboot.mute` (328P) — a software link on USART0's own pins, entered from an
+  application that handed over with that USART still enabled: the loader must
+  still answer, which it does only because it releases it. The pin ownership is
+  the runner's, not simavr's — simavr wires a USART through IRQs and never takes
+  the pin from the port, so without that model the state under test could not
+  arise at all;
 - `pureboot.dirty` (328P) — entering the loader from a running application over
   an SPM buffer it deliberately dirtied, the case the loader declines to guard:
   a bare verify must see the corruption and the repairing verify must fix it in
@@ -449,5 +542,45 @@ Per chip preset, `ctest` runs:
   exists for. A lone calibration pulse with no knock behind it must still let
   the application boot, so no wait in activation can be unbounded.
 
-`size`, `pi` and `planner` are host logic and run anywhere; the
+`size`, `pi`, `planner` and `handshake` are host logic and run anywhere; the
 simulator-driven targets need simavr and a pty, so they are POSIX-only.
+
+## Hardware
+
+The suite above proves the protocol on every chip; it cannot prove a *board*.
+Two things live only on silicon: an RC oscillator that is not on its nominal, and
+a reset edge that has to come from somewhere. `tools/pbrig.py` and
+`tools/pbhw.py` cover that, and know nothing per-board — every deployment fact
+is a flag or a `PUREBOOT_*` environment variable.
+
+```sh
+export PUREBOOT_PROGRAMMER=atmelice_isp PUREBOOT_PART=t13 PUREBOOT_PORT=COM6
+tools/pbrig.py backup rig-backup/          # verified, before anything is written
+tools/pbhw.py --autobaud --loader build/ab.bin --app build/pbapp.hex --marker APP
+```
+
+`pbrig.py` is the primitives — `signature`, `reset`, `flash`, `fuses`, `backup`,
+`rate` — and the module `pbhw.py` builds on. Two rig facts are encoded in it
+because neither is guessable: an **ISP access is the reset edge** (the part runs
+the moment the programmer releases it, which is the only edge available when the
+adapter's DTR is not wired to reset, so a session begins with an ISP touch and
+knocks immediately after), and **avrdude splits `-U` on colons**, so a Windows
+path's drive letter breaks the spec and every file is passed as a bare name with
+avrdude run in its own directory.
+
+`pbrig.py rate` is the one that turns "the loader is silent, so the wiring must
+be wrong" into a number. Against a fixture built with `PUREBOOT_HEARTBEAT` — a
+*fixed* cycles-per-bit transmitter — it sweeps the host rate, and the band where
+the marker still decodes brackets the part's true bit rate; with the clock the
+image was built for, that is the clock the part is really running at. No
+instrument beyond the adapter already attached. An ATtiny13A measured this way
+came out at 9.072 MHz against its 9.6 MHz nominal, −5.5 % — inside the
+datasheet's ±10 % and outside what an 8N1 frame survives, which is the whole
+case for the autobaud backend on such a part.
+
+`pbhw.py` takes its bounds from the info block the loader reports, so one run
+covers a 1 KiB tiny and a 128 KiB mega alike: identity, the EEPROM round trip
+and erase, an application flashed and verified and then *seen running*, the
+application region read and erased, the loader slot proven intact across that
+erase by an independent ISP read, and an oversized image refused. It overwrites
+the application flash and EEPROM, which is why `backup` comes first.

pureboot/pureboot.cpp

@@ -166,6 +166,27 @@ constexpr char usart_digit = '0' + PUREBOOT_USART;
 constexpr char usart_digit = '0';
 #endif
 
+// Release a hardware USART the application may have left enabled onto a
+// bit-banged link's pins. A software transmitter drives its TX pin through the
+// port register, but while that USART's TXEN is set the USART owns the pin and
+// the port write does nothing — the loader would receive and obey yet never
+// answer. Writing UCSRnB zero hands the pin back to the port. Guarded on the
+// pin actually being a USART's TXD, so a link on non-USART pins emits nothing.
+template <char Inst, avr::io::pin Tx>
+[[gnu::always_inline]] inline void release_usart_on()
+{
+	if constexpr (avr::uart::has_usart<Inst>())
+		if constexpr (avr::uart::detail::usart_pin<Inst>("TXD") == Tx)
+			avr::hw::reg_impl<avr::uart::detail::ureg<Inst, "UCSR#B">()>::write(0);
+}
+
+template <avr::io::pin Tx>
+[[gnu::always_inline]] inline void release_usarts_on()
+{
+	release_usart_on<'0', Tx>();
+	release_usart_on<'1', Tx>();
+}
+
 template <avr::hertz_t C, avr::baud_t B>
 struct hardware_link {
 	using uart = avr::uart::usart<usart_digit, C, {.baud = B, .max_baud_error = 2.5_pct}>;
@@ -212,6 +233,7 @@ struct software_link {
 	static void init()
 	{
 		avr::init<rx_t, tx_t>();
+		release_usarts_on<avr::PUREBOOT_TX>();
 	}
 
 	static bool pending()
@@ -245,6 +267,7 @@ struct autobaud_link {
 	static void init()
 	{
 		avr::init<uart>();
+		release_usarts_on<avr::PUREBOOT_TX>();
 	}
 
 	static std::uint8_t rx()
@@ -465,8 +488,7 @@ void fill_page(std::uint8_t bank, std::uint16_t at)
 	// address is a word address and a slot is half as many words as bytes, so
 	// its high byte is the slot index outright. No absolute address is ever
 	// formed, so the image stays position-independent.
-	const auto return_words = reinterpret_cast<std::uint16_t>(__builtin_return_address(0));
-	const auto slot_high = static_cast<std::uint8_t>(return_words >> 8);
+	const auto slot_high = avr::startup::caller_page();
 
 	await_host();
 

pureboot/pureboot.py

@@ -24,7 +24,7 @@ else:
     import termios
 
 PROMPT = b"+"
-VERSION = 4  # this tool's own version — free to drift from a loader's
+VERSION = 5  # this tool's own version — free to drift from a loader's
 # The loader versions this tool speaks. A pureboot version implies its wire
 # protocol, which carries no number of its own, so this window is where that
 # map lives: every version so far speaks the same protocol, and one that
@@ -146,6 +146,13 @@ class Progress:
 class PosixPort:
     """A raw serial port with deadline-based reads, over termios."""
 
+    @staticmethod
+    def _speed(baud):
+        try:
+            return getattr(termios, f"B{baud}")
+        except AttributeError:
+            raise Error(f"unsupported baud rate {baud}") from None
+
     def __init__(self, path, baud):
         self.fd = os.open(path, os.O_RDWR | os.O_NOCTTY)
         attrs = termios.tcgetattr(self.fd)
@@ -153,14 +160,20 @@ class PosixPort:
         attrs[1] = 0  # oflag
         attrs[2] = termios.CREAD | termios.CLOCAL | termios.CS8  # cflag
         attrs[3] = 0  # lflag
-        try:
-            speed = getattr(termios, f"B{baud}")
-        except AttributeError:
-            raise Error(f"unsupported baud rate {baud}") from None
-        attrs[4] = attrs[5] = speed
+        attrs[4] = attrs[5] = self._speed(baud)
         attrs[6][termios.VMIN] = 0
         attrs[6][termios.VTIME] = 0
         termios.tcsetattr(self.fd, termios.TCSANOW, attrs)
+        self.baud = baud
+
+    def set_baud(self, baud):
+        """Retune the port without closing it — the fd stays open, so no DTR
+        pulse and no reset. That matters: the only caller is mid-session with a
+        loader copy that a reset would throw away."""
+        attrs = termios.tcgetattr(self.fd)
+        attrs[4] = attrs[5] = self._speed(baud)
+        termios.tcsetattr(self.fd, termios.TCSANOW, attrs)
+        self.baud = baud
 
     def close(self):
         os.close(self.fd)
@@ -289,6 +302,7 @@ if os.name == "nt":
                 # timeout would otherwise stay at the driver's default — which
                 # may be "wait forever" — until the first read.
                 self._deadline(_GAP_MS, 1000)
+                self.baud = baud
             except Error:
                 # An open port outlives the exception otherwise, and a COM
                 # handle is exclusive: the next attempt would meet its own
@@ -296,6 +310,21 @@ if os.name == "nt":
                 self.close()
                 raise
 
+        def set_baud(self, baud):
+            """Retune the port on its live handle — SetCommState only, so the
+            handle is never reopened and DTR never drops. That matters: the only
+            caller is mid-session with a loader copy a reset would throw away."""
+            if baud < 50:
+                raise Error(f"unsupported baud rate {baud}")
+            dcb = _DCB()
+            dcb.DCBlength = ctypes.sizeof(_DCB)
+            if not _k32.GetCommState(self.handle, ctypes.byref(dcb)):
+                _fail("cannot read the port state")
+            dcb.BaudRate = baud
+            if not _k32.SetCommState(self.handle, ctypes.byref(dcb)):
+                _fail(f"cannot retune the port to {baud} baud")
+            self.baud = baud
+
         def close(self):
             _k32.CloseHandle(self.handle)
 
@@ -457,6 +486,10 @@ class Loader:
         # Set once a session is established over an autobaud link, so a
         # re-entry after 'J' repeats the handshake that worked.
         self.autobaud = False
+        # The link this session is speaking. It moves when the host follows a
+        # staging copy built for another one (enter_copy).
+        self.baud = getattr(port, "baud", None)
+        self._link_declared = False
 
     def _read_identity(self):
         """The 'b' reply, in either of the two layouts a loader may send.
@@ -484,8 +517,13 @@ class Loader:
             self.port.write(knock)
             knocks += 1
             if PROMPT in self.port.read_available(0.4):
+                # Settle: absorb a real loader's trailing bytes before asking
+                # for the identity. Bounded by the deadline so a target that
+                # never falls quiet — a board stuck in a reset loop, whose
+                # garbage carries a stray prompt — cannot spin here forever.
                 while self.port.read_available(0.3):
-                    pass
+                    if time.monotonic() > deadline:
+                        break
                 self.port.write(b"b")
                 try:
                     # A version the tool cannot speak is the loader's own
@@ -659,12 +697,41 @@ class Loader:
         self.port.write(bytes((ord("J"), word_address & 0xFF, word_address >> 8)))
         self._expect_prompt()
 
-    def enter_copy(self, byte_address, wait):
+    def enter_copy(self, byte_address, wait, link=None):
         """Jump into the loader copy at `byte_address` and knock it — a slot
-        base is that copy's entry stub, so it can only land there."""
-        autobaud = self.autobaud
+        base is that copy's entry stub, so it can only land there.
+
+        `link` is that copy's own `(baud, autobaud)`, for when it is not this
+        session's. A staging copy *is* the new image, so it speaks the rate and
+        backend it was built for; the host has to be told which, because 512
+        bytes of position-independent code carry no header to read it from.
+        Retuning goes through the open port, so no DTR pulse resets the copy that
+        is now running — and the session keeps the new link afterwards, since
+        every later jump lands in the same image.
+        """
+        baud, autobaud = link if link is not None else (self.baud, self.autobaud)
+        if link is not None:
+            self._link_declared = True
         self.jump(byte_address // 2)
-        return self.connect_autobaud(wait) if autobaud else self.connect(wait)
+        if baud is not None and baud != self.baud:
+            self.port.set_baud(baud)
+            self.baud = baud
+        self.autobaud = autobaud
+        try:
+            return self.connect_autobaud(wait) if autobaud else self.connect(wait)
+        except Error as unheard:
+            if self._link_declared:
+                raise
+            # The bare activation timeout sends the operator to look at wiring,
+            # while on a patched-vector part the application region is already
+            # gone. Name the one cause that fits: the copy answers on its own
+            # link, not the resident's.
+            raise Error(
+                f"the copy at {byte_address:#06x} did not answer on this session's "
+                f"link ({baud} Bd, {'autobaud' if autobaud else 'fixed baud'}). An "
+                f"image built for another baud or backend speaks that one instead — "
+                f"say which with --staged-baud / --staged-autobaud"
+            ) from unheard
 
     def run_application(self):
         self.jump(self.info.app_entry_word)
@@ -1012,10 +1079,16 @@ def patch_word0(loader, page0, target_base):
     return bytes(patched)
 
 
-def op_update_loader(loader, wait, path, state_path, fuse_bytes):
+def op_update_loader(loader, wait, path, state_path, fuse_bytes, staged_link=None):
     """Replace the resident loader with `path`, using the loader as its own
     staging loader. Every phase is idempotent and keyed off the flash state,
-    so a re-run resumes; the state file carries what the staging slot held."""
+    so a re-run resumes; the state file carries what the staging slot held.
+
+    `staged_link` is the new image's own `(baud, autobaud)` where it differs from
+    this session's — the copies the host enters *are* that image, so they answer
+    on its link and not the resident's. Note what this does to the idempotence
+    above: once the staging copy is installed, the resumable state is only
+    reachable on the new link, so a re-run has to name it too."""
     info = loader.info
     image = loader_image(path)
     for warning in update_preflight(image, info, fuse_bytes):
@@ -1060,7 +1133,7 @@ def op_update_loader(loader, wait, path, state_path, fuse_bytes):
     # routes through the resident, word 0 is re-aimed at the staging copy for
     # the rewrite, so a power loss mid-rewrite still resets into a loader.
     verbose(f"entering the staging copy at {info.stage:#06x}")
-    loader.enter_copy(info.stage, wait)
+    loader.enter_copy(info.stage, wait, link=staged_link)
     redirect = info.patch_vector and info.stage != 0
     if redirect:
         verbose("word 0 re-aimed at the staging copy for the rewrite")
@@ -1297,6 +1370,15 @@ def main():
     parser.add_argument("--fuses", action="store_true", help="read the fuse and lock bytes")
     parser.add_argument("--update-loader", metavar="FILE", help="replace the loader with this pureboot binary")
     parser.add_argument("--state", metavar="FILE", help="update state file (default: FILE.pbstate)")
+    # The update enters the staging copy, which is the new image and so speaks
+    # the link *it* was built for. Nothing in the image says which, so where it
+    # differs from this session's these name it and the host follows.
+    parser.add_argument("--staged-baud", metavar="BD", type=int,
+                        help="the baud the --update-loader image was built for, where it "
+                             "differs from --baud")
+    parser.add_argument("--staged-autobaud", action=argparse.BooleanOptionalAction, default=None,
+                        help="whether that image is an autobaud build, where it differs "
+                             "from --autobaud")
     parser.add_argument("--assume-fuses", metavar="HEX8", help="fuse bytes low,lock,ext,high as 8 hex digits "
                         "(overrides reading them — e.g. under a simulator that cannot)")
     parser.add_argument("--erase-flash", action="store_true", help="0xff over the application flash")
@@ -1346,7 +1428,14 @@ def main():
                 fuse_bytes = read
         if args.update_loader:
             state = args.state or args.update_loader + ".pbstate"
-            op_update_loader(loader, args.wait, args.update_loader, state, fuse_bytes)
+            staged_link = None
+            if args.staged_baud is not None or args.staged_autobaud is not None:
+                staged_link = (
+                    args.staged_baud if args.staged_baud is not None else args.baud,
+                    args.staged_autobaud if args.staged_autobaud is not None else args.autobaud,
+                )
+            op_update_loader(loader, args.wait, args.update_loader, state, fuse_bytes,
+                             staged_link)
         if args.flash:
             op_flash(loader, args.flash, args.erase_flash, not args.no_verify, fuse_bytes, args.force)
         elif args.erase_flash:

test/device.c

@@ -65,6 +65,15 @@ int main(int argc, char *argv[])
 		fprintf(stderr, "device: cannot read %s\n", argv[1]);
 		return 1;
 	}
+	// An image that runs past flash end cannot execute on hardware, and a
+	// naive copy of it would smash the heap beyond avr->flash — after which
+	// the simulation misbehaves in ways that point everywhere but here.
+	// Refuse it loudly instead.
+	if (boot_base + fw.flashsize > avr->flashend + 1) {
+		fprintf(stderr, "device: %u B at 0x%x runs past flash end 0x%x — image does not fit its slot\n",
+		        (unsigned)fw.flashsize, boot_base, avr->flashend);
+		return 1;
+	}
 	memcpy(avr->flash + boot_base, fw.flash, fw.flashsize);
 	avr->pc = boot_base;
 	avr->codeend = avr->flashend;

test/pbapp.cpp

@@ -11,6 +11,10 @@
 // reset reaches those loaders through the patched vector (or the runner
 // models BOOTRST), so the application owes them nothing.
 //
+// PUREBOOT_HANDOVER drops the listening and jumps straight in, leaving the
+// USART enabled behind it — the hand-over state a loader bit-banging on that
+// USART's own pins has to survive.
+//
 // The fixture speaks the deployment its loader was built for: the same
 // PUREBOOT_* defines configure it, and without them it assumes the stock
 // deployment (the crystal/RC clock table below, the chip's natural link).
@@ -64,16 +68,29 @@ struct link {
 	{
 		tx_t::write(static_cast<std::uint8_t>(c));
 	}
+	// The loader sits in the top slot — 512 bytes on every chip. The jump
+	// takes a word address, which is what makes the >64 KiB chips' entry
+	// reachable through a 16-bit pointer at all.
+	static void enter_loader()
+	{
+		constexpr std::uint32_t slot = 512;
+		reinterpret_cast<void (*)()>(static_cast<std::uint16_t>((avr::hw::db.mem.flash_size - slot) / 2))();
+	}
+
 	[[noreturn]] static void idle()
 	{
-		// 'L' hands back to the loader in the top slot — 512 bytes on every
-		// chip. The jump takes a word address, which is what makes the
-		// >64 KiB chips' entry reachable through a 16-bit pointer at all.
-		constexpr std::uint32_t slot = 512;
+#if defined(PUREBOOT_HANDOVER)
+		// Hand back at once, with this USART still enabled — the state that
+		// leaves a bit-banged loader on its pins mute unless the loader
+		// releases it. Unconditional because there is no command wire to
+		// wait on: that loader's link is the pins, not this peripheral.
+		enter_loader();
+		__builtin_unreachable();
+#else
 		for (;;) {
 			auto command = tx_t::read_blocking();
 			if (command == 'L')
-				reinterpret_cast<void (*)()>(static_cast<std::uint16_t>((avr::hw::db.mem.flash_size - slot) / 2))();
+				enter_loader();
 			// 'D' leaves every word of the SPM page buffer dirty, so that a
 			// following 'L' enters the loader with the buffer it never clears.
 			if (command == 'D') {
@@ -82,6 +99,7 @@ struct link {
 				tx('D');
 			}
 		}
+#endif
 	}
 };
 
@@ -99,8 +117,27 @@ struct link<C, false> {
 	}
 	[[noreturn]] static void idle()
 	{
+#if defined(PUREBOOT_HEARTBEAT)
+		// Repeat the banner forever, which turns the fixture into a fixed
+		// cycles-per-bit transmitter: `tools/pbrig.py rate` sweeps the host rate
+		// against it to find the part's true bit rate, and from that the clock
+		// its RC oscillator is really running at. Only the *bit* timing carries
+		// the measurement — the delay merely spaces the lines out, so its own
+		// error does not matter. Software link only: the hardware-link idle owes
+		// the self-update tests a command loop, and a crystal deployment has
+		// nothing to measure.
+		while (true) {
+			tx('A');
+			tx('P');
+			tx('P');
+			tx('\r');
+			tx('\n');
+			dev::delay<50_ms>();
+		}
+#else
 		while (true) {
 		}
+#endif
 	}
 };
 
@@ -109,8 +146,13 @@ struct link<C, false> {
 int main()
 {
 	avr::init<typename link<dev::clock>::tx_t>();
+#if !defined(PUREBOOT_HANDOVER)
 	link<dev::clock>::tx('A');
 	link<dev::clock>::tx('P');
 	link<dev::clock>::tx('P');
+#endif
+	// The hand-over fixture stays silent: nothing is listening on the USART it
+	// brings up — the loader it hands to speaks those pins directly — so its
+	// banner would be a write into a peer that does not exist.
 	link<dev::clock>::idle();
 }

test/pbautobaud.py

@@ -141,13 +141,45 @@ def main():
         print(f"  {label}: locked at {hz} Hz / {baud} Bd, flash+EEPROM verified"
               + (", hand-over ok" if hand_over else ""))
 
+    def must_lock(hz, baud, label):
+        """The calibration alone, at a tight bit period. Nothing is programmed —
+        the question is only whether the loader can still measure the pulse."""
+        dump = os.path.join(workdir, f"flash_{label}.bin")
+        device = pbsim.Device(device_bin, elf, mcu, str(hz), base_hex, page, baud, dump,
+                              link="sw:B0,B1")
+        try:
+            port = pb.Port(device.pty, baud)
+            try:
+                live = pb.Loader(port).connect_autobaud(15)
+                if live.version != pb.NEWEST_LOADER:
+                    fail(f"{label}: loader reports pureboot {live.version}")
+            finally:
+                port.close()
+        finally:
+            device.stop()
+        print(f"  {label}: locked at {hz} Hz / {baud} Bd ({hz / baud:.0f} cycles a bit)")
+
     # The app fixture is built for one clock; the hand-over banners there. A
     # second point at double that clock, same loader binary, proves the lock is
     # measured, not baked in — the whole point of autobaud. (Doubling keeps the
     # bit period healthy; halving would drop it below the software UART's floor.)
     round_trip(app_hz, app_baud, "clock-a", hand_over=True)
     round_trip(app_hz * 2, app_baud, "clock-b", hand_over=False)
-    print("pbautobaud: calibration lock and flash/EEPROM/fuse round-trip pass at both clocks")
+
+    # Both points above sit near 100 cycles a bit, which is comfortable. The
+    # calibration's real floor is far tighter, and it is worth a gate: measured
+    # here, the lock is solid down to ~36 cycles a bit and fails outright by ~31
+    # — a sharp edge, not a fraying one. This pins the tightest standard rate the
+    # fixture's clock reaches, so a change that raises the floor is caught.
+    #
+    # It does *not* bound what a real deployment can use. On silicon the
+    # oscillator's own jitter costs roughly a factor of two: an ATtiny13A on its
+    # factory RC trim was reliable at ~118 cycles a bit and already locking only
+    # 1 attempt in 5 by ~59, which no exact-clock simulation can show. The
+    # deployable envelope is a README matter; this is the logic's floor.
+    must_lock(app_hz, app_baud * 2, "tight-bit")
+    print("pbautobaud: calibration lock and flash/EEPROM/fuse round-trip pass at both clocks, "
+          "and the tight bit period still locks")
 
 
 if __name__ == "__main__":

test/pbmute.py

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+"""Hand-over with a USART left enabled on the loader's own pins.
+
+A software or autobaud link deployed on a USART's TxD is mute if an
+application hands over with that USART still enabled: TXEN keeps the USART
+owning the pin, so the bit-banged transmitter's port writes go nowhere and the
+loader receives and obeys while answering nothing. The link's init releases it.
+
+The state is reached the way silicon reaches it — an application that sets up
+its USART and jumps in with no reset between, so nothing clears UCSRnB for it.
+The pin ownership itself is modelled by the device runner: simavr wires a
+USART through IRQs alone and never takes the pin from the port, so without
+that the mute could not happen here at all (test/pureboot_device.c).
+
+Usage: pbmute.py <device_bin> <pureboot_elf> <mcu> <hz> <base_hex> <page>
+                 <baud> <app_bin> <tool_py> <workdir> <link>
+"""
+
+import os
+import sys
+
+
+def fail(message):
+    print(f"FAIL: {message}")
+    sys.exit(1)
+
+
+def main():
+    device_bin, elf, mcu, hz, base_hex, page, baud, app_bin, tool, workdir, link = sys.argv[1:]
+    page, baud = int(page), int(baud)
+    sys.path.insert(0, os.path.dirname(os.path.abspath(tool)))
+    sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+    import pbsim
+    import pureboot as pb
+
+    if "@" not in link:
+        fail(f"the link {link} names no owning USART — nothing would be under test")
+
+    os.makedirs(workdir, exist_ok=True)
+    dump = os.path.join(workdir, "dump.bin")
+
+    device = pbsim.Device(device_bin, elf, mcu, hz, base_hex, page, baud, dump, link=link)
+    try:
+        port = pb.Port(device.pty, baud)
+        loader = pb.Loader(port)
+        loader.connect(25)
+        resident = loader.info.version
+
+        # Install the fixture and let it take over. It brings up the USART
+        # that owns these pins and jumps straight back in.
+        pb.op_flash(loader, app_bin, erase=False, verify=True)
+        loader.run_application()
+
+        # The loader is running again with that USART enabled behind it. Only
+        # the release makes it audible; without it the connect times out.
+        loader = pb.Loader(port)
+        try:
+            loader.connect(25)
+        except pb.Error as error:
+            fail(f"the loader never answered after the hand-over — the USART still owns its TX pin ({error})")
+        if loader.info.version != resident:
+            fail(f"identity changed across the hand-over: {resident} then {loader.info.version}")
+
+        # Answering is not enough: it has to still be a working loader.
+        pb.verify_pages(loader, pb.plan_flash(open(app_bin, "rb").read(), loader.info))
+        port.close()
+    finally:
+        device.stop()
+    print("pbmute: a loader on a USART's own pins answers after a hand-over that left it enabled")
+
+
+if __name__ == "__main__":
+    main()

test/pureboot_device.c

@@ -10,7 +10,9 @@
 //
 // The link follows the chip's natural default (USART0 on the megas, the
 // software UART on PB0/PB1 elsewhere) unless -l overrides it: `-l usart1`
-// for the second instance, `-l sw:B5,B1` for a software build's RX,TX pins.
+// for the second instance, `-l sw:B5,B1` for a software build's RX,TX pins,
+// and `-l sw:D0,D1@0` where those pins are a USART's own — see the pin
+// ownership the bridge models below.
 //
 // simavr's tiny cores decode the SPM opcode but attach no NVM module — SPM
 // is a silent no-op (the mega's boot section has one, avr_flash). The
@@ -46,6 +48,7 @@ static int link_software;
 static char uart_digit = '0';
 static char sw_rx_port = 'B', sw_tx_port = 'B';
 static int sw_rx_bit = 0, sw_tx_bit = 1;
+static char sw_tx_owner = 0; // the USART whose TXD the software link sits on
 static const char *dump_path;
 static uint32_t reset_pc;
 static volatile sig_atomic_t reset_requested;
@@ -61,8 +64,12 @@ static int parse_link(const char *spec)
 		link_software = 1;
 		if (spec[2] == '\0')
 			return 0;
-		if (sscanf(spec + 2, ":%c%d,%c%d", &sw_rx_port, &sw_rx_bit, &sw_tx_port, &sw_tx_bit) == 4)
+		char owner = 0;
+		int fields = sscanf(spec + 2, ":%c%d,%c%d@%c", &sw_rx_port, &sw_rx_bit, &sw_tx_port, &sw_tx_bit, &owner);
+		if (fields == 4 || fields == 5) {
+			sw_tx_owner = owner;
 			return 0;
+		}
 	}
 	return -1;
 }
@@ -198,10 +205,50 @@ static avr_cycle_count_t tx_sample(avr_t *mcu, avr_cycle_count_t when, void *par
 	return 0;
 }
 
+// A USART owns its TxD pin whenever its transmitter is enabled, and the port
+// register cannot drive it (§20.2 / Atmel-8271 §19.2) — which is why a
+// bit-banged link deployed on those pins is mute until it clears UCSRnB.
+// simavr wires a USART entirely through IRQs and never touches the port pin
+// model, so the ownership does not exist there and the mute cannot happen:
+// supply it, or the very state this models is untestable. The link spec's
+// trailing @n names the USART; without one the pins are nobody's.
+static avr_uart_t *tx_owner;
+
+static int tx_pin_taken(void)
+{
+	return tx_owner && avr_regbit_get(avr, tx_owner->txen);
+}
+
+// simavr leaves TXEN set in UCSRnB out of reset, where silicon clears the
+// whole register (§20.11.3) — which would hand the pin to a USART no code has
+// enabled, making a freshly reset chip mute for reasons hardware does not
+// have. Reset it the way the datasheet does, so the ownership starts from
+// nobody's and only an application that really enables the USART takes it.
+static void reset_tx_owner(void)
+{
+	if (tx_owner)
+		avr_regbit_clear(avr, tx_owner->txen);
+}
+
+static void find_tx_owner(void)
+{
+	for (avr_io_t *io = avr->io_port; io; io = io->next)
+		if (io->kind && strcmp(io->kind, "uart") == 0 && ((avr_uart_t *)io)->name == sw_tx_owner) {
+			tx_owner = (avr_uart_t *)io;
+			reset_tx_owner();
+			return;
+		}
+	fprintf(stderr, "device: no USART%c to own the software link's TX pin\n", sw_tx_owner);
+}
+
 static void tx_hook(avr_irq_t *irq, uint32_t value, void *param)
 {
 	(void)irq;
 	(void)param;
+	if (tx_pin_taken()) { // the USART holds the line; the port write goes nowhere
+		tx_level = 1;
+		return;
+	}
 	int level = value & 1;
 	if (!tx_active && tx_level == 1 && level == 0) { // start edge
 		tx_active = 1;
@@ -324,7 +371,8 @@ int main(int argc, char *argv[])
 		fprintf(stderr,
 		        "usage: %s [-l link] <pureboot.elf> <mcu> <hz> <base_hex> <page> <baud> <flash_dump>"
 		        " [reset_hex] [resume_flash]\n"
-		        "  -l link:      usart0 | usart1 | sw[:B0,B1] (RX,TX); default: the chip's own\n"
+		        "  -l link:      usart0 | usart1 | sw[:B0,B1[@0]] (RX,TX, then the USART owning\n"
+		        "                them); default: the chip's own\n"
 		        "  reset_hex:    reset vector (default: base with a boot section, else 0)\n"
 		        "  resume_flash: raw full-flash image loaded instead of the ELF — a prior\n"
 		        "                run's dump, for power-fail resume tests\n",
@@ -410,6 +458,8 @@ int main(int argc, char *argv[])
 		printf("PB_PTY %s\n", uart_pty.pty.slavename);
 	} else {
 		bit_cycles = (avr->frequency + baud / 2) / baud; // matches uart.hpp's own rounding exactly
+		if (sw_tx_owner)
+			find_tx_owner();
 		rx_pin = avr_io_getirq(avr, AVR_IOCTL_IOPORT_GETIRQ(sw_rx_port), (unsigned)sw_rx_bit);
 		avr_irq_register_notify(avr_io_getirq(avr, AVR_IOCTL_IOPORT_GETIRQ(sw_tx_port), (unsigned)sw_tx_bit), tx_hook,
 		                        NULL);
@@ -447,6 +497,7 @@ int main(int argc, char *argv[])
 				avr_ioctl(avr, AVR_IOCTL_UART_SET_FLAGS(uart_digit), &flags);
 			} else {
 				bridge_reset();
+				reset_tx_owner();
 			}
 		}
 		if (link_software && ++since_poll >= 2000) {

test/test_handshake.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+"""Host-tool activation handshake: it must not hang on a flooding target.
+
+`_handshake` drains the line after it sees a prompt, to absorb a real loader's
+trailing bytes before it asks for the identity. That drain must be bounded: a
+target that never falls quiet — a board stuck in a reset loop presents exactly
+this, ~60 reboots/s of UART-reset garbage in which a stray 0x2b reads as a
+prompt — otherwise spins the tool forever. Regression for that hang, plus a
+control that a well-behaved loader still connects.
+
+Stdlib only, no device: host-tool logic, so it runs on every chip's preset
+beside pureboot.planner.
+"""
+import importlib.util
+import pathlib
+import threading
+import time
+
+PB = pathlib.Path(__file__).resolve().parents[1] / "pureboot" / "pureboot.py"
+_spec = importlib.util.spec_from_file_location("pureboot", PB)
+pb = importlib.util.module_from_spec(_spec)
+_spec.loader.exec_module(pb)
+
+P = F = 0
+
+
+def check(name, ok):
+    global P, F
+    P, F = P + (1 if ok else 0), F + (0 if ok else 1)
+    print(f"  [{'PASS' if ok else 'FAIL'}] {name}")
+
+
+class FloodPort:
+    """A line that never falls quiet: read_available always returns bytes, and
+    they contain a prompt. No identity ever completes."""
+
+    def flush_input(self):
+        pass
+
+    def write(self, data):
+        pass
+
+    def read_available(self, wait):
+        time.sleep(0.01)  # a real read waits; keep the busy loop off a core
+        return b"+\x00\xff"
+
+    def read_exact(self, count, timeout):
+        raise pb.Error("no identity")
+
+
+class LoaderPort:
+    """A well-behaved pureboot 5: one prompt to the knock, then quiet, then the
+    slim identity (version 5 + m328p signature) and a closing prompt."""
+
+    def __init__(self):
+        self.reads = self.exacts = 0
+
+    def flush_input(self):
+        pass
+
+    def write(self, data):
+        pass
+
+    def read_available(self, wait):
+        self.reads += 1
+        return b"+" if self.reads == 1 else b""  # prompt once, then settle quiet
+
+    def read_exact(self, count, timeout):
+        self.exacts += 1
+        return b"\x05\x1e\x95\x0f" if self.exacts == 1 else b"+"  # identity, then prompt
+
+
+def terminates(port, wait, budget):
+    """Run connect_autobaud in a thread; True if it returns/raises within
+    `budget` seconds rather than hanging."""
+    done = threading.Event()
+
+    def run():
+        try:
+            pb.Loader(port).connect_autobaud(wait)
+        except Exception:
+            pass
+        finally:
+            done.set()
+
+    threading.Thread(target=run, daemon=True).start()
+    return done.wait(budget)
+
+
+def main():
+    # the hang: a flooding target must not spin the drain forever. With wait=0.5
+    # the whole handshake has to give up well inside a few seconds.
+    check("flooding target: handshake terminates, drain is bounded",
+          terminates(FloodPort(), wait=0.5, budget=4.0))
+
+    # the control: a real loader still connects and reads identity.
+    info = pb.Loader(LoaderPort()).connect_autobaud(2.0)
+    check("well-behaved loader still connects (version 5)", info.version == 5)
+
+    print(f"\n  {P} passed, {F} failed")
+    return 1 if F else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

test/test_update_link.py

@@ -0,0 +1,167 @@
+#!/usr/bin/env python3
+"""Self-update across a link change: the host must follow the staging copy.
+
+`--update-loader` installs the new image in the staging slot and then *enters
+it* to have it rewrite the resident. That copy is the new image, so it speaks the
+new image's baud and backend — but the host was talking to the *resident*. Where
+the two differ, the host kept knocking at the old rate in the old mode, the
+staging copy never answered, and the update stranded: staging installed, resident
+untouched, and on a 1 KiB tiny the application region (which *is* the staging
+slot there) already gone.
+
+The wire cannot be probed for this — 512 bytes of position-independent code carry
+no header saying what rate they were built for — so the operator declares it, and
+a mismatch with nothing declared has to say so instead of reporting a bare
+timeout.
+
+Stdlib only, no device: host-tool logic, so it runs on every chip's preset beside
+pureboot.planner.
+"""
+import importlib.util
+import pathlib
+
+PB = pathlib.Path(__file__).resolve().parents[1] / "pureboot" / "pureboot.py"
+_spec = importlib.util.spec_from_file_location("pureboot", PB)
+pb = importlib.util.module_from_spec(_spec)
+_spec.loader.exec_module(pb)
+
+IDENTITY = b"\x05\x1e\x95\x0f"  # pureboot 5 + m328p signature
+P = F = 0
+
+
+def check(name, ok, detail=""):
+    global P, F
+    P, F = P + (1 if ok else 0), F + (0 if ok else 1)
+    print(f"  [{'PASS' if ok else 'FAIL'}] {name}" + (f" — {detail}" if detail else ""))
+
+
+class TwoLinkPort:
+    """A board whose resident and staging copy answer on different links.
+
+    Only the rate currently set decides who can be heard, which is the physical
+    truth: a loader's bit timing is a cycle count, so a copy built for another
+    rate is unreadable until the host retunes. The knock bytes carry the mode, so
+    a backend mismatch is caught the same way.
+    """
+
+    def __init__(self, resident=(57600, False), staged=(38400, False)):
+        self.resident, self.staged = resident, staged
+        self.baud = resident[0]
+        self.entered = False        # a 'J' has handed control to the staging copy
+        self.switches = []          # every retune the host asked for
+        self.pending = bytearray()  # what the device has queued to send
+
+    # --- the part under test needs this to exist at all
+    def set_baud(self, baud):
+        self.baud = baud
+        self.switches.append(baud)
+
+    def flush_input(self):
+        self.pending.clear()
+
+    def _audible(self, knock=None):
+        baud, autobaud = self.staged if self.entered else self.resident
+        if self.baud != baud:
+            return False
+        if knock is None:
+            return True
+        return knock == (bytes((pb.CALIBRATE, ord("p"))) if autobaud else b"pb")
+
+    def write(self, data):
+        data = bytes(data)
+        if data[:1] == b"J" and len(data) == 3:
+            # The resident acks the jump, then control moves to the copy.
+            if self._audible():
+                self.pending += pb.PROMPT
+            self.entered = True
+        elif data in (b"pb", bytes((pb.CALIBRATE, ord("p")))):
+            if self._audible(data):
+                self.pending += pb.PROMPT
+        elif data == b"b":
+            if self._audible():
+                self.pending += IDENTITY + pb.PROMPT
+
+    def read_available(self, wait):
+        out, self.pending = bytes(self.pending), bytearray()
+        return out
+
+    def read_exact(self, count, timeout):
+        if len(self.pending) < count:
+            raise pb.Error(f"timeout: got {len(self.pending)} of {count} bytes")
+        out, self.pending = bytes(self.pending[:count]), self.pending[count:]
+        return out
+
+
+def connected(port):
+    """A Loader already in session with the resident."""
+    loader = pb.Loader(port)
+    loader.connect(2.0)
+    return loader
+
+
+def main():
+    # The control first: where the staged image keeps the resident's link, the
+    # flow works and needs no retune. This is the case that always passed, and
+    # it is what made the bug look like "self-update is broken" rather than
+    # "self-update cannot change the link".
+    port = TwoLinkPort(resident=(57600, False), staged=(57600, False))
+    loader = connected(port)
+    try:
+        loader.enter_copy(0x7C00, 2.0)
+        check("same link: staging copy entered", True)
+    except pb.Error as error:
+        check("same link: staging copy entered", False, str(error))
+
+    # A baud change, declared. The host must retune before knocking.
+    port = TwoLinkPort(resident=(57600, False), staged=(38400, False))
+    loader = connected(port)
+    try:
+        loader.enter_copy(0x7C00, 2.0, link=(38400, False))
+        check("baud change declared: entered after retuning", 38400 in port.switches,
+              f"switches={port.switches}")
+    except (pb.Error, TypeError) as error:
+        check("baud change declared: entered after retuning", False, repr(error))
+
+    # A backend change, declared: the knock itself has to become the calibration
+    # pulse, or an autobaud staging copy never hears a thing.
+    port = TwoLinkPort(resident=(57600, False), staged=(57600, True))
+    loader = connected(port)
+    try:
+        loader.enter_copy(0x7C00, 2.0, link=(57600, True))
+        check("backend change declared: entered as autobaud", True)
+    except (pb.Error, TypeError) as error:
+        check("backend change declared: entered as autobaud", False, repr(error))
+
+    # Nothing declared against a changed link: it still cannot work, but the
+    # error has to name the cause. A bare "no answer" sent the operator looking
+    # at the wiring while the application region sat erased.
+    port = TwoLinkPort(resident=(57600, False), staged=(38400, False))
+    loader = connected(port)
+    try:
+        loader.enter_copy(0x7C00, 0.3)
+        check("undeclared mismatch: reported", False, "unexpectedly succeeded")
+    except pb.Error as error:
+        text = str(error).lower()
+        check("undeclared mismatch: error names the link, not just a timeout",
+              "link" in text or "baud" in text or "backend" in text, str(error))
+    except TypeError as error:
+        check("undeclared mismatch: error names the link, not just a timeout",
+              False, repr(error))
+
+    # The resident's own link must be restored for the caller: a declared
+    # staging link is for the copy, and the tool talks to the new resident after.
+    port = TwoLinkPort(resident=(57600, False), staged=(38400, False))
+    loader = connected(port)
+    try:
+        loader.enter_copy(0x7C00, 2.0, link=(38400, False))
+        check("session records the link it is now speaking", loader.baud == 38400,
+              f"loader.baud={getattr(loader, 'baud', None)}")
+    except (pb.Error, TypeError, AttributeError) as error:
+        check("session records the link it is now speaking", False, repr(error))
+
+    print(f"\n  {P} passed, {F} failed")
+    return 1 if F else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tools/check.sh

@@ -3,8 +3,8 @@
 # the simulator-driven protocol suites. --full adds the reflect-spot builds
 # (libavr's rule: reflect compiles are bounded to its spot set, never the
 # full matrix) and swaps the compact size matrix for the exhaustive
-# clock × baud × backend cross product. LIBAVR_ROOT must point at the libavr
-# checkout.
+# clock × baud × backend cross product. libavr resolves from the `libavr/`
+# submodule; LIBAVR_ROOT overrides it for a working tree.
 set -e
 cd "$(dirname "$0")/.."
 

tools/pbhw.py

@@ -0,0 +1,210 @@
+#!/usr/bin/env python3
+"""Hardware acceptance suite for a pureboot deployment.
+
+`tools/check.sh` proves the protocol under simavr on every chip. This proves one
+*board*: that the loader actually installed on it answers, that the memories
+round-trip over the real link, that the application it flashes runs afterwards,
+and that the refusals which keep a 512-byte slot alive still fire. Run it once
+when a board is brought up, and again whenever the deployment moves — a new
+clock, a new backend, new pins.
+
+Every check derives its bounds from the info block the loader itself reports, so
+nothing here is per-chip: the same run covers a 1 KiB tiny whose application
+region is 510 usable bytes and a 128 KiB mega whose flash needs a bank in the
+selector.
+
+**This overwrites the board's application flash and EEPROM.** Capture them first
+with `pbrig.py backup`, which verifies what it captured.
+
+    tools/pbhw.py --programmer atmelice_isp --part t13 --port COM6 \
+                  --autobaud --loader build/ab.bin --app build/pbapp.hex \
+                  --marker APP
+"""
+
+from __future__ import annotations
+
+import argparse
+import pathlib
+import sys
+import tempfile
+
+sys.path.insert(0, str(pathlib.Path(__file__).resolve().parent))
+import pbrig  # noqa: E402
+
+
+class Suite:
+    def __init__(self, rig: pbrig.Rig, work: pathlib.Path):
+        self.rig = rig
+        self.work = work
+        self.results: list[tuple[str, bool, str]] = []
+
+    def check(self, name: str, ok: bool, detail: str = "") -> bool:
+        self.results.append((name, ok, detail))
+        print(f"  {'PASS' if ok else 'FAIL'}  {name}" + (f"   {detail}" if detail else ""))
+        return ok
+
+    @staticmethod
+    def _brief(text: str, limit: int = 78) -> str:
+        return " | ".join(l.strip() for l in text.splitlines() if l.strip())[:limit]
+
+    # ----------------------------------------------------------------- checks
+
+    def identity(self) -> object | None:
+        """The info block, which every later check takes its bounds from."""
+        module = pbrig.load_pureboot(self.rig.d.pureboot)
+        self.rig.reset()
+        port = module.Port(self.rig.d.port, self.rig.d.baud)
+        try:
+            loader = module.Loader(port)
+            if self.rig.d.autobaud:
+                loader.connect_autobaud(self.rig.d.wait)
+            else:
+                loader.connect(self.rig.d.wait)
+            info = loader.info
+            self.check("identity read", True, info.describe())
+            return info
+        except Exception as error:  # noqa: BLE001 — a dead link is a result
+            self.check("identity read", False, str(error)[:70])
+            return None
+        finally:
+            try:
+                port.close()
+            except Exception:
+                pass
+
+    def eeprom(self, info) -> None:
+        size = info.eeprom_size
+        if not size:
+            print("  skip  EEPROM (this part has none)")
+            return
+        # A pattern no erase or partial write could produce by accident.
+        pattern = bytes((i * 7 + 3) & 0xFF for i in range(size))
+        image = self.work / "ee.bin"
+        image.write_bytes(pattern)
+
+        rc, out = self.rig.pureboot("--eeprom", str(image), "--verify-eeprom", str(image))
+        self.check(f"EEPROM write + verify ({size} B)", rc == 0, self._brief(out))
+
+        back = self.work / "ee-back.bin"
+        rc, out = self.rig.pureboot("--read-eeprom", str(back))
+        got = back.read_bytes() if back.exists() else b""
+        self.check("EEPROM reads back what was written", got == pattern, f"{len(got)} B")
+
+        self.rig.pureboot("--erase-eeprom")
+        erased = self.work / "ee-erased.bin"
+        self.rig.pureboot("--read-eeprom", str(erased))
+        got = erased.read_bytes() if erased.exists() else b""
+        self.check("EEPROM erase leaves 0xff", got == b"\xff" * size, f"{len(got)} B")
+
+    def application(self, info, app: pathlib.Path, marker: str) -> None:
+        rc, out = self.rig.pureboot("--flash", str(app), "--verify-flash", str(app))
+        self.check(f"application flash + verify ({app.name})", rc == 0, self._brief(out))
+
+        if marker:
+            # The tool hands over as it ends its session, so the application is
+            # already running; opening the port does not reset a board whose DTR
+            # is unwired, so this simply listens.
+            data = self.rig.capture(seconds=2.5)
+            seen = marker.encode() in data
+            sample = "".join(chr(b) if 32 <= b < 127 else "." for b in data[:40])
+            self.check(f"application runs (emits {marker!r})", seen, f"|{sample}|")
+
+        back = self.work / "app-back.bin"
+        rc, out = self.rig.pureboot("--read-flash", str(back))
+        got = back.read_bytes() if back.exists() else b""
+        self.check("application flash reads back", rc == 0 and len(got) == info.base,
+                   f"{len(got)} B of {info.base}")
+
+    def erase_and_guard(self, info, loader_image: pathlib.Path | None) -> None:
+        rc, out = self.rig.pureboot("--erase-flash")
+        self.check("application region erases", rc == 0, self._brief(out))
+
+        # The slot must be untouched by an application erase, which only an
+        # independent read can show — so this one goes over ISP, not the link.
+        whole = self.work / "whole.bin"
+        if not self.rig.read_memory("flash", whole, "r"):
+            self.check("loader slot survives the erase", False, "ISP read failed")
+            return
+        image = whole.read_bytes()
+        image += b"\xff" * (info.flash_size - len(image))
+
+        # Erased application flash, up to the trampoline word the host composes
+        # on a patched-vector part.
+        limit = info.base - 2 if info.patch_vector else info.base
+        self.check("erased application region is 0xff",
+                   set(image[0:limit]) <= {0xFF}, f"0x0000..{limit:#06x}")
+
+        if loader_image and loader_image.exists():
+            want = loader_image.read_bytes()
+            got = image[info.base:info.base + len(want)]
+            self.check("loader slot survives the erase", got == want,
+                       f"{len(want)} B at {info.base:#06x}")
+        else:
+            print("  skip  loader slot comparison (pass --loader <image.bin>)")
+
+    def refusals(self, info) -> None:
+        # One word too many: a patched-vector part spends the slot's last word
+        # on the trampoline, so its application stops two bytes short.
+        limit = info.base - 2 if info.patch_vector else info.base
+        oversized = self.work / "oversized.bin"
+        oversized.write_bytes(bytes(limit + 2))
+        rc, out = self.rig.pureboot("--flash", str(oversized))
+        self.check(f"image over {limit} B refused", rc != 0, self._brief(out))
+
+    # ------------------------------------------------------------------- run
+
+    def run(self, app: pathlib.Path | None, loader_image: pathlib.Path | None,
+            marker: str) -> int:
+        print("identity")
+        info = self.identity()
+        if info is None:
+            print("\nthe loader never answered; nothing below can be trusted")
+            return 1
+
+        print("\nEEPROM")
+        self.eeprom(info)
+
+        if app:
+            print("\napplication")
+            self.application(info, app, marker)
+        else:
+            print("\nskip  application checks (pass --app <image.hex>)")
+
+        print("\nerase and the write guard")
+        self.erase_and_guard(info, loader_image)
+
+        print("\nrefusals")
+        self.refusals(info)
+
+        passed = sum(1 for _, ok, _ in self.results if ok)
+        print(f"\n{passed}/{len(self.results)} passed")
+        return 0 if passed == len(self.results) else 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="hardware acceptance suite for one pureboot deployment",
+        epilog="overwrites the board's application flash and EEPROM — back them up first")
+    pbrig.Deployment.add_arguments(parser)
+    parser.add_argument("--app", type=pathlib.Path,
+                        help="application image to flash (test/pbapp.cpp built for this deployment)")
+    parser.add_argument("--loader", type=pathlib.Path,
+                        help="the resident loader's .bin, to prove the slot survives an erase")
+    parser.add_argument("--marker", default="",
+                        help="text the application emits when it runs, e.g. APP")
+    args = parser.parse_args(argv)
+
+    rig = pbrig.Rig(pbrig.Deployment.from_args(args))
+    print(f"rig: {args.part} on {args.programmer}, link {args.port} at {args.baud} Bd"
+          f"{' (autobaud)' if args.autobaud else ''}")
+    print("this overwrites the application flash and EEPROM\n")
+    with tempfile.TemporaryDirectory(prefix="pbhw-") as temporary:
+        return Suite(rig, pathlib.Path(temporary)).run(args.app, args.loader, args.marker)
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except pbrig.Error as error:
+        print(f"error: {error}", file=sys.stderr)
+        sys.exit(2)

tools/pbrig.py

@@ -0,0 +1,427 @@
+#!/usr/bin/env python3
+"""Hardware rig driver for pureboot: an ISP programmer beside a serial link.
+
+The simulated suites (`test/pb*.py`) prove the protocol; this drives the same
+loader on real silicon, where the things a cycle-exact simulator cannot model
+live — an RC oscillator off its nominal, a reset edge that has to come from
+somewhere, a serial bridge with its own idea of what a baud is.
+
+Nothing here knows a port name, a part or a programmer. Every deployment fact
+arrives from the command line or the environment, so the same script serves any
+board: see `Deployment`. As a module it is the reset/flash/talk primitives that
+`pbhw.py` builds its acceptance suite from; as a command it is the handful of
+one-shot operations worth having on a rig — most importantly `backup`, which is
+the only thing standing between a fuse experiment and an unrecoverable part.
+
+Two rig facts are encoded here because they are not guessable and cost a
+session each to learn:
+
+* **An ISP access resets the part**, and it runs again the moment the programmer
+  releases it. That is the only reset edge available when the serial adapter's
+  DTR is not wired to reset — so a loader session begins with an ISP touch and
+  knocks immediately after, which is what `Rig.pureboot()` does.
+* **avrdude splits `-U memory:op:file:format` on colons**, so a Windows path's
+  drive letter breaks the spec. Every file argument is therefore passed as a
+  bare filename with avrdude run in that file's own directory.
+"""
+
+from __future__ import annotations
+
+import argparse
+import dataclasses
+import importlib.util
+import os
+import pathlib
+import subprocess
+import sys
+import time
+
+HERE = pathlib.Path(__file__).resolve().parent
+DEFAULT_PUREBOOT = HERE.parent / "pureboot" / "pureboot.py"
+
+# Memories worth capturing before an experiment, and the format each is read in.
+# Fuses and lock are per-part: a part without an extended fuse simply fails that
+# one read, which `backup` reports and steps over rather than aborting on.
+BACKUP_MEMORIES = (
+    ("flash", "i", "hex"),
+    ("flash", "r", "bin"),
+    ("eeprom", "i", "hex"),
+    ("eeprom", "r", "bin"),
+    ("lfuse", "h", "hex"),
+    ("hfuse", "h", "hex"),
+    ("efuse", "h", "hex"),
+    ("lock", "h", "hex"),
+    ("calibration", "h", "hex"),
+)
+
+
+class Error(Exception):
+    pass
+
+
+def bitclock_for(hz: int) -> str:
+    """A safe ISP bitclock for a part *currently running* at `hz`.
+
+    SCK must stay under a quarter of the target clock, so the bitclock follows
+    the clock in force — not the one about to be fused in. Halving that ceiling
+    again costs nothing on a link that moves a few hundred bytes and buys margin
+    against an oscillator that is already known to be off its nominal.
+    """
+    ceiling = hz // 8
+    for candidate in (1000, 4000, 8000, 32000, 125000, 400000):
+        if candidate <= ceiling:
+            best = candidate
+        else:
+            break
+    else:
+        best = 400000
+    if ceiling < 1000:
+        raise Error(f"a part at {hz} Hz is too slow to reach over ISP safely")
+    return f"{best // 1000}kHz"
+
+
+@dataclasses.dataclass
+class Deployment:
+    """Everything about one board. No default names a real device."""
+
+    port: str = ""              # serial device the loader speaks on
+    baud: int = 57600           # host rate; for autobaud, the rate to drive
+    autobaud: bool = False      # send the calibration pulse instead of p+b
+    programmer: str = ""        # avrdude -c
+    part: str = ""              # avrdude -p
+    avrdude: str = "avrdude"
+    bitclock: str = "125kHz"    # see bitclock_for()
+    pureboot: pathlib.Path = DEFAULT_PUREBOOT
+    wait: int = 12              # seconds the host keeps knocking
+
+    @classmethod
+    def from_env(cls) -> "Deployment":
+        """Environment defaults, so a rig's facts live in one place per machine."""
+        return cls(
+            port=os.environ.get("PUREBOOT_PORT", ""),
+            baud=int(os.environ.get("PUREBOOT_BAUD", "57600")),
+            autobaud=os.environ.get("PUREBOOT_AUTOBAUD", "") not in ("", "0"),
+            programmer=os.environ.get("PUREBOOT_PROGRAMMER", ""),
+            part=os.environ.get("PUREBOOT_PART", ""),
+            avrdude=os.environ.get("AVRDUDE", "avrdude"),
+            bitclock=os.environ.get("PUREBOOT_BITCLOCK", "125kHz"),
+            pureboot=pathlib.Path(os.environ.get("PUREBOOT_TOOL", str(DEFAULT_PUREBOOT))),
+        )
+
+    @staticmethod
+    def add_arguments(parser: argparse.ArgumentParser) -> None:
+        """Deployment flags, shared by this tool and pbhw.py."""
+        env = Deployment.from_env()
+        parser.add_argument("--port", default=env.port, help="serial device the loader speaks on")
+        parser.add_argument("--baud", type=int, default=env.baud,
+                            help="host rate (for autobaud, the rate to drive)")
+        parser.add_argument("--autobaud", action="store_true", default=env.autobaud,
+                            help="send the calibration pulse instead of the p+b knock")
+        parser.add_argument("--programmer", default=env.programmer, help="avrdude -c, e.g. atmelice_isp")
+        parser.add_argument("--part", default=env.part, help="avrdude -p, e.g. t13 or m328p")
+        parser.add_argument("--avrdude", default=env.avrdude, help="path to avrdude")
+        parser.add_argument("--bitclock", default=env.bitclock, help="ISP bitclock, e.g. 125kHz or 8kHz")
+        parser.add_argument("--pureboot", type=pathlib.Path, default=env.pureboot,
+                            help="path to pureboot.py")
+        parser.add_argument("--wait", type=int, default=env.wait, help="seconds to keep knocking")
+
+    @classmethod
+    def from_args(cls, args: argparse.Namespace) -> "Deployment":
+        return cls(port=args.port, baud=args.baud, autobaud=args.autobaud,
+                   programmer=args.programmer, part=args.part, avrdude=args.avrdude,
+                   bitclock=args.bitclock, pureboot=args.pureboot, wait=args.wait)
+
+
+def load_pureboot(path: pathlib.Path = DEFAULT_PUREBOOT):
+    """The host tool as a module — its Port and Loader, not a subprocess.
+
+    Used where a subprocess cannot express what is needed: a poke followed by a
+    peek in the *same* session, or a raw read at an arbitrary baud.
+    """
+    spec = importlib.util.spec_from_file_location("pureboot", path)
+    if spec is None or spec.loader is None:
+        raise Error(f"cannot load the host tool from {path}")
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module
+
+
+class Rig:
+    """One board: its programmer on one side, its serial link on the other."""
+
+    def __init__(self, deployment: Deployment):
+        self.d = deployment
+        if not deployment.programmer or not deployment.part:
+            raise Error("a rig needs --programmer and --part")
+
+    # ------------------------------------------------------------- programmer
+
+    def avrdude(self, *args: str, cwd: pathlib.Path | None = None,
+                bitclock: str | None = None, timeout: int = 300) -> subprocess.CompletedProcess:
+        command = [self.d.avrdude, "-c", self.d.programmer, "-p", self.d.part,
+                   "-B", bitclock or self.d.bitclock, *args]
+        return subprocess.run(command, capture_output=True, text=True,
+                              cwd=None if cwd is None else str(cwd), timeout=timeout)
+
+    @staticmethod
+    def _ok(result: subprocess.CompletedProcess) -> bool:
+        return result.returncode == 0
+
+    def reset(self, bitclock: str | None = None) -> None:
+        """An ISP access, which resets the part; it runs when avrdude exits."""
+        self.avrdude("-U", "signature:r:-:h", bitclock=bitclock)
+
+    def signature(self, bitclock: str | None = None) -> str:
+        result = self.avrdude("-U", "signature:r:-:h", bitclock=bitclock)
+        for line in reversed(result.stdout.splitlines()):
+            if line.strip().startswith("0x"):
+                return line.strip()
+        raise Error(f"no signature read: {(result.stderr or result.stdout).strip()[:200]}")
+
+    def read_memory(self, memory: str, destination: pathlib.Path, fmt: str = "r",
+                    bitclock: str | None = None) -> bool:
+        """Read `memory` into `destination`, whose directory avrdude runs in."""
+        destination = pathlib.Path(destination).resolve()
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        result = self.avrdude("-U", f"{memory}:r:{destination.name}:{fmt}",
+                              cwd=destination.parent, bitclock=bitclock)
+        # A memory the part does not have (a tiny's extended fuse) leaves avrdude
+        # happy and the file empty. An empty capture is a miss, not a backup.
+        return self._ok(result) and destination.exists() and destination.stat().st_size > 0
+
+    def write_memory(self, memory: str, source: pathlib.Path, fmt: str = "i",
+                     erase: bool = False, bitclock: str | None = None) -> bool:
+        source = pathlib.Path(source).resolve()
+        args = ["-U", f"{memory}:w:{source.name}:{fmt}"]
+        if erase:
+            args.insert(0, "-e")
+        result = self.avrdude(*args, cwd=source.parent, bitclock=bitclock)
+        return "verified" in (result.stdout + result.stderr)
+
+    def flash_hex(self, image: pathlib.Path, erase: bool = True,
+                  bitclock: str | None = None) -> bool:
+        return self.write_memory("flash", image, "i", erase=erase, bitclock=bitclock)
+
+    def read_fuses(self, bitclock: str | None = None) -> dict[str, str]:
+        out: dict[str, str] = {}
+        for fuse in ("lfuse", "hfuse", "efuse", "lock"):
+            result = self.avrdude("-U", f"{fuse}:r:-:h", bitclock=bitclock)
+            values = [l.strip() for l in result.stdout.splitlines() if l.strip().startswith("0x")]
+            if values:
+                out[fuse] = values[-1]
+        return out
+
+    def write_fuses(self, bitclock: str | None = None, **fuses: str) -> bool:
+        """Write named fuses. A fuse change moves the clock the *next* access is
+        timed against, so pass a bitclock safe for both sides of the change."""
+        args: list[str] = []
+        for name, value in fuses.items():
+            args += ["-U", f"{name}:w:{value}:m"]
+        if not args:
+            return True
+        result = self.avrdude(*args, bitclock=bitclock)
+        text = result.stdout + result.stderr
+        return "verified" in text or "written" in text
+
+    # ------------------------------------------------------------ backup
+
+    def backup(self, directory: pathlib.Path, prefix: str = "") -> dict[str, bool]:
+        """Capture every memory worth keeping, then prove it by a second read.
+
+        A backup nobody verified is a guess. Each memory is read twice and the
+        two reads compared; a mismatch is reported rather than quietly stored.
+        """
+        directory = pathlib.Path(directory).resolve()
+        directory.mkdir(parents=True, exist_ok=True)
+        stem = prefix or self.d.part
+        status: dict[str, bool] = {}
+        for memory, fmt, extension in BACKUP_MEMORIES:
+            name = f"{stem}-{memory}.{extension}"
+            if not self.read_memory(memory, directory / name, fmt):
+                status[f"{memory}.{extension}"] = False
+                continue
+            if extension == "bin":  # only the raw form is worth comparing byte-wise
+                again = directory / f".{name}.again"
+                self.read_memory(memory, again, fmt)
+                same = again.exists() and again.read_bytes() == (directory / name).read_bytes()
+                again.unlink(missing_ok=True)
+                status[f"{memory}.{extension}"] = same
+            else:
+                status[f"{memory}.{extension}"] = True
+        return status
+
+    # ------------------------------------------------------------ serial link
+
+    def pureboot(self, *args: str, reset_first: bool = True, baud: int | None = None,
+                 autobaud: bool | None = None, timeout: int = 300,
+                 bitclock: str | None = None) -> tuple[int, str]:
+        """Reset, then knock immediately — see the module docstring.
+
+        Returns the host tool's exit status and its combined output, so a caller
+        can assert on what it printed as well as on whether it succeeded.
+        """
+        if reset_first:
+            self.reset(bitclock=bitclock)
+        command = [sys.executable, str(self.d.pureboot), "--port", self.d.port,
+                   "--baud", str(self.d.baud if baud is None else baud),
+                   "--wait", str(self.d.wait)]
+        if self.d.autobaud if autobaud is None else autobaud:
+            command.append("--autobaud")
+        command += [str(a) for a in args]
+        try:
+            result = subprocess.run(command, capture_output=True, text=True, timeout=timeout)
+        except subprocess.TimeoutExpired as expired:
+            return 99, f"TIMEOUT after {timeout}s\n{expired.stdout or ''}{expired.stderr or ''}"
+        return result.returncode, (result.stdout or "") + (result.stderr or "")
+
+    def capture(self, seconds: float = 2.0, baud: int | None = None) -> bytes:
+        """Listen to whatever the board is saying, at an arbitrary rate.
+
+        Opening the port does not reset a board whose DTR is unwired, so this can
+        sample a running application repeatedly without disturbing it — which is
+        what makes the rate sweep below possible.
+        """
+        module = load_pureboot(self.d.pureboot)
+        port = module.Port(self.d.port, self.d.baud if baud is None else baud)
+        try:
+            data = b""
+            deadline = time.monotonic() + seconds
+            while time.monotonic() < deadline:
+                chunk = port.read_available(0.2)
+                if chunk:
+                    data += chunk
+            return data
+        finally:
+            try:
+                port.close()
+            except Exception:
+                pass
+
+
+def measure_rate(rig: Rig, marker: bytes, built_baud: int, nominal_hz: int | None = None,
+                 span_percent: float = 12.0, step_percent: float = 0.5,
+                 seconds: float = 0.75) -> dict:
+    """Find a transmitting board's true bit rate, using only the serial port.
+
+    The board must be emitting something recognisable at a *fixed* cycles-per-bit
+    — `test/pbapp.cpp` built with PUREBOOT_HEARTBEAT does. Since its bit timing is
+    a cycle count, its wire rate scales with its actual clock, so the host rates
+    at which `marker` still decodes bracket that rate; the centre of the band is
+    the answer, and with the clock the image was built for it gives the real one.
+
+    This is the measurement that turns "the loader is silent, so the wiring must
+    be wrong" into a number, and it needs no instrument beyond the adapter
+    already attached.
+    """
+    steps = int(span_percent / step_percent)
+    clean: list[int] = []
+    samples: list[tuple[int, int, bool]] = []
+    for index in range(-steps, steps + 1):
+        baud = int(round(built_baud * (1 + index * step_percent / 100.0)))
+        if baud <= 0:
+            continue
+        data = rig.capture(seconds=seconds, baud=baud)
+        hit = marker in data
+        samples.append((baud, len(data), hit))
+        if hit:
+            clean.append(baud)
+    result: dict = {"samples": samples, "clean": clean, "built_baud": built_baud}
+    if clean:
+        low, high = min(clean), max(clean)
+        centre = (low + high) / 2.0
+        result |= {"low": low, "high": high, "centre": centre,
+                   "half_width_percent": (high - low) / 2.0 / centre * 100.0,
+                   "error_percent": (centre / built_baud - 1.0) * 100.0}
+        if nominal_hz:
+            result["measured_hz"] = nominal_hz * centre / built_baud
+    return result
+
+
+# ------------------------------------------------------------------- command
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="pureboot hardware rig: ISP reset/flash beside the serial link")
+    Deployment.add_arguments(parser)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    sub.add_parser("signature", help="read the part signature over ISP")
+    sub.add_parser("reset", help="reset the part (an ISP access) and let it run")
+    sub.add_parser("fuses", help="read the fuse and lock bytes")
+
+    p = sub.add_parser("flash", help="program a hex image over ISP")
+    p.add_argument("image", type=pathlib.Path)
+    p.add_argument("--no-erase", action="store_true", help="do not chip-erase first")
+
+    p = sub.add_parser("backup", help="capture and verify every memory")
+    p.add_argument("directory", type=pathlib.Path)
+    p.add_argument("--prefix", default="", help="filename stem (default: the part name)")
+
+    p = sub.add_parser("rate", help="measure the board's true bit rate and clock")
+    p.add_argument("--marker", default="APP", help="text the board emits (default: APP)")
+    p.add_argument("--built-baud", type=int, required=True,
+                   help="the baud the running image was built for")
+    p.add_argument("--nominal-hz", type=int, default=0,
+                   help="the clock the image was built for, to report the real one")
+    p.add_argument("--span", type=float, default=12.0, help="sweep +-this many percent")
+    p.add_argument("--step", type=float, default=0.5, help="sweep step in percent")
+    p.add_argument("--verbose", action="store_true", help="print every step")
+
+    p = sub.add_parser("bitclock", help="a safe ISP bitclock for a clock in force")
+    p.add_argument("hz", type=int)
+
+    args = parser.parse_args(argv)
+
+    if args.command == "bitclock":
+        print(bitclock_for(args.hz))
+        return 0
+
+    rig = Rig(Deployment.from_args(args))
+
+    if args.command == "signature":
+        print(rig.signature())
+    elif args.command == "reset":
+        rig.reset()
+        print("reset")
+    elif args.command == "fuses":
+        for name, value in rig.read_fuses().items():
+            print(f"{name:<6} {value}")
+    elif args.command == "flash":
+        ok = rig.flash_hex(args.image, erase=not args.no_erase)
+        print(f"{args.image.name}: {'verified' if ok else 'FAILED'}")
+        return 0 if ok else 1
+    elif args.command == "backup":
+        status = rig.backup(args.directory, args.prefix)
+        for name, ok in status.items():
+            print(f"  {'ok  ' if ok else 'FAIL'} {name}")
+        missing = [n for n, ok in status.items() if not ok]
+        # Fuses a part does not have are expected misses, not failures.
+        fatal = [n for n in missing if not n.startswith(("efuse", "calibration"))]
+        print(f"\n{len(status) - len(missing)}/{len(status)} captured into {args.directory}")
+        return 1 if fatal else 0
+    elif args.command == "rate":
+        result = measure_rate(rig, args.marker.encode(), args.built_baud,
+                              args.nominal_hz or None, args.span, args.step)
+        if args.verbose:
+            for baud, size, hit in result["samples"]:
+                print(f"  {baud:7d} Bd  {size:5d} B  {'MARKER' if hit else ''}")
+        if not result["clean"]:
+            print(f"no capture contained {args.marker!r} at any rate — is the board "
+                  f"transmitting, and on the pin this port is wired to?")
+            return 1
+        print(f"clean band  {result['low']}..{result['high']} Bd")
+        print(f"centre      {result['centre']:.0f} Bd "
+              f"(+-{result['half_width_percent']:.1f} %)")
+        print(f"vs built    {result['built_baud']} Bd ({result['error_percent']:+.1f} %)")
+        if "measured_hz" in result:
+            print(f"true clock  {result['measured_hz'] / 1e6:.3f} MHz")
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        sys.exit(main())
+    except Error as error:
+        print(f"error: {error}", file=sys.stderr)
+        sys.exit(2)

tools/sizes.py

@@ -0,0 +1,160 @@
+#!/usr/bin/env python3
+"""What the loader images actually measure, and whether the README still agrees.
+
+The size matrix asserts every image fits its slot; it says nothing about the
+numbers the README prints, and those drift. Every row of that table was eight
+bytes stale once `startup::caller_page()` landed — common code, so every build
+moved at once and no test noticed, because none of them was over budget.
+
+Two questions, both answered from built trees:
+
+  sizes.py max            the largest image per chip, and anything over budget
+  sizes.py check-readme   the README's per-chip table against what is built
+
+Nothing here knows a chip's geometry. The (image, budget) pairs come from each
+build's own `CTestTestfile.cmake` — the same values the gate checks — so the
+slot rules stay where they belong, in `pureboot/CMakeLists.txt`, and a chip
+added or a budget changed needs no edit here. Only trees a configure preset
+still owns are read: a stale directory keeps its last build, and a loader built
+before a slot changed will happily report a size that was true once
+(`tools/prune-build-trees.sh` in libavr removes them).
+
+Sizes come from `avr-size`, and a target is only as current as its last build —
+run the gate first if you want the table checked against today's source.
+"""
+
+from __future__ import annotations
+
+import argparse
+import pathlib
+import re
+import shutil
+import subprocess
+import sys
+
+ROOT = pathlib.Path(__file__).resolve().parents[1]
+# add_test(<name>.size ... -DELF=<path> ... -DLIMIT=<n> ...) — the gate's own
+# pairing of an image with the budget it must fit.
+# ctest writes the name as a bracket argument ([=[name.size]=]) and quotes the
+# rest, so the name starts after the bracket and the path ends at the quote.
+SIZE_TEST = re.compile(r'add_test\(\s*\[=\[(?P<name>[^\]]+?)\.size\]=\][^\n]*?'
+                       r'-DELF=(?P<elf>[^"\s]+)[^\n]*?-DLIMIT=(?P<limit>\d+)')
+
+
+def avr_size() -> str:
+    for env in (ROOT / "../../toolchain").resolve().glob("avr-gcc-*/bin/avr-size"):
+        if env.is_file():
+            return str(env)
+    found = shutil.which("avr-size")
+    if not found:
+        sys.exit("no avr-size found (build the toolchain, or put it on PATH)")
+    return found
+
+
+def preset_dirs() -> list[pathlib.Path]:
+    """Build trees a configure preset still owns, newest-listed first."""
+    listing = subprocess.run(["cmake", "--list-presets"], cwd=ROOT, capture_output=True, text=True)
+    names = re.findall(r'^\s*"(.+)"$', listing.stdout, re.MULTILINE)
+    if not names:
+        sys.exit("cmake --list-presets returned nothing — run from a configured checkout")
+    return [d for d in (ROOT / "build" / n for n in names) if (d / "CTestTestfile.cmake").is_file()]
+
+
+def measure(paths: list[str], tool: str) -> dict[str, int]:
+    """.text per ELF, in one avr-size call per batch."""
+    sizes: dict[str, int] = {}
+    for start in range(0, len(paths), 400):
+        batch = [p for p in paths[start:start + 400] if pathlib.Path(p).is_file()]
+        if not batch:
+            continue
+        out = subprocess.run([tool, *batch], capture_output=True, text=True).stdout
+        for line in out.splitlines()[1:]:
+            fields = line.split()
+            if len(fields) >= 6 and fields[0].isdigit():
+                sizes[fields[5]] = int(fields[0])
+    return sizes
+
+
+def collect() -> dict[str, list[tuple[str, int, int]]]:
+    """chip -> [(target, text, limit)], from every owned build tree."""
+    tool = avr_size()
+    found: dict[str, list[tuple[str, str, int]]] = {}
+    for tree in preset_dirs():
+        chip = tree.name.split("-")[0]
+        for match in SIZE_TEST.finditer((tree / "CTestTestfile.cmake").read_text()):
+            found.setdefault(chip, []).append((match["name"], match["elf"], int(match["limit"])))
+    sizes = measure([elf for rows in found.values() for _, elf, _ in rows], tool)
+    measured = {
+        chip: sorted(((name, sizes[elf], limit) for name, elf, limit in rows if elf in sizes),
+                     key=lambda row: -row[1])
+        for chip, rows in sorted(found.items())
+    }
+    # A configured-but-unbuilt preset registers its tests with no images behind
+    # them; it is not a chip with nothing to say, it is a chip not built yet.
+    return {chip: rows for chip, rows in measured.items() if rows}
+
+
+def cmd_max(args) -> int:
+    measured = collect()
+    if not measured:
+        sys.exit("nothing built — configure and build a preset first")
+    over = []
+    print(f"{'chip':<13} {'largest image':<34} {'.text':>6} {'budget':>7}  headroom")
+    for chip, rows in measured.items():
+        name, text, limit = rows[0]
+        flag = "OVER" if text > limit else f"{limit - text:>5} B"
+        print(f"{chip:<13} {name:<34} {text:>6} {limit:>7}  {flag}")
+        over += [(chip, n, t, l) for n, t, l in rows if t > l]
+    total = sum(len(rows) for rows in measured.values())
+    print(f"\n{total} images across {len(measured)} chips")
+    if over:
+        print("\nOVER BUDGET:")
+        for chip, name, text, limit in over:
+            print(f"  {chip} {name}: {text} > {limit}")
+        return 1
+    tightest = min(((chip, n, t, l) for chip, rows in measured.items() for n, t, l in rows),
+                   key=lambda row: row[3] - row[2])
+    chip, name, text, limit = tightest
+    print(f"tightest fit: {chip} {name} — {text} of {limit}, {limit - text} B spare")
+    return 0
+
+
+def cmd_check_readme(args) -> int:
+    """The README's per-chip table, against the stock and autobaud builds."""
+    readme = (ROOT / "pureboot" / "README.md").read_text()
+    measured = collect()
+    rows = re.findall(r"^\|\s*(AT\w+[^|]*?)\s*\|[^|]*\|[^|]*\|[^|]*\|\s*(\d+) B\s*\|\s*(\d+) B\s*\|$",
+                      readme, re.MULTILINE)
+    if not rows:
+        sys.exit("no size table found in pureboot/README.md")
+    bad = skipped = 0
+    for chips, stock_doc, auto_doc in rows:
+        # "ATmega48, 48A, 48P, 48PA †" — the first name is the family's base.
+        chip = re.sub(r"[^a-z0-9]", "", chips.split(",")[0].strip().lower())
+        built = {name: text for name, text, _ in measured.get(chip, [])}
+        for target, documented in (("pureboot", stock_doc), ("pureboot_autobaud", auto_doc)):
+            if target not in built:
+                skipped += 1
+                continue
+            if built[target] != int(documented):
+                print(f"  {chip:<12} {target:<18} README says {documented} B, built is {built[target]} B")
+                bad += 1
+    if bad:
+        print(f"\n{bad} row(s) stale — update pureboot/README.md")
+        return 1
+    print(f"README size table matches every built image ({len(rows)} rows"
+          + (f", {skipped} not built" if skipped else "") + ")")
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    subs = parser.add_subparsers(dest="cmd", required=True)
+    subs.add_parser("max", help="largest image per chip, and anything over budget")
+    subs.add_parser("check-readme", help="the README's size table against what is built")
+    args = parser.parse_args()
+    return {"max": cmd_max, "check-readme": cmd_check_readme}[args.cmd](args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

tsb/tsb_policy.cpp

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