bootloader/pureboot/autobaud.md

pureboot autobaud — findings and the version decision

The autobaud variant measures the host's bit timing at runtime from a calibration pulse, so the image carries no clock: one clock-agnostic binary per chip runs at any F_CPU and locks onto whatever baud the host sends. It exists for the software-serial deployments — the RC-oscillator parts (the tinies, internal-oscillator megas) whose exact clock is uncertain and drifts, so today each needs a per-clock build. Autobaud erases that axis. That is the win — deployment, not bytes.

This document records how the fit was established, why there are two source files under review, and what remains before either can ship.

The decision to make

Two complete autobaud loaders sit side by side for review. They implement the identical wire protocol and the identical command set; they differ in exactly two things, and the choice between them is a single tradeoff — the running-slot write guard vs. strict purity.

	pureboot_autobaud_pure.cpp	pureboot_autobaud_reg.cpp
measured unit lives in	GPIOR I/O scratch regs (RAM where absent)	one global register variable (r4)
running-slot write guard	dropped	kept
purity (no asm, no GRV)	yes	one GRV — the single break
ATmega1284P size	508 B (4 B spare)	512 B (exact)
all 37 chips	440–508 B	452–512 B

Both also take two shared, licensed simplifications (below): a slimmed info block and a single-byte activation knock.

The pure version keeps pureboot's defining constraint — "one C++ source, no inline assembly, no global register variables" (README.md) — intact, and pays for it by dropping the write guard, which the host compensates for. The register version keeps the guard by pinning the measured unit to a call-saved register, which is only expressible as a global register variable — the one thing the purity rule forbids.

Recommendation deferred to the owner. The pure version aligns with the stated constraints (purity mandated; relaxing host-guaranteed safety licensed); the register version keeps every feature at the cost of the purity claim and leaves the 1284 with zero margin.

The mechanism

The host sends calibration byte 0xC0 — a start bit plus six zero data bits form a single low pulse of seven bit-times. The loader counts that pulse in a poll loop the compiler emits at seven cycles an iteration, so the count is the pulse length in cycles ÷ 7 × 7 = one bit period in cycles, and count >> 2 is that period in _delay_loop_2's four-cycle iterations — the delay unit fed to every rx/tx bit. Numerically sound: the per-bit delay tracks the true period to < 0.2 % from 1–16 MHz at 9600 (worst seen −2.8 % at 128 kHz/1200, still inside UART tolerance).

The catch — codegen coupling. count >> 2 is exact only because the calibration pulse's bit-count (7) equals the poll loop's cycles/iter (7). That couples the on-wire calibration byte to what the compiler emits; a toolchain bump that reshapes the loop breaks it silently. This must be pinned by a sim timing test that fails on drift (see What remains).

The activation window is a fixed poll budget (PUREBOOT_AUTOBAUD_POLLS, default 4,000,000), not timeout × clock — with no clock, whole seconds cannot be timed. A __uint24 holds it; a std::uint32_t's fourth byte would cost two words at each countdown step.

How the target was found — the hand-assembly floor

Pure C++ first came out 560 B on the 1284 (full info + guard). To learn whether that was a hard floor or C++ overhead, a hand-optimal assembly loader was written with the full v4 protocol (all commands, the full 12-byte info block, the write guard, position independence) plus autobaud — local/scratch/autobaud/ in the libavr checkout, off-tree, a size probe.

The hand-asm floor is 506 B — it fits 512 with the full info block and the guard, no concessions. That proved a fit was possible and gave a target. The hand-asm achieves it two ways pure C++ cannot express directly:

1. The measured unit in a call-saved register (Y). rx/tx/spin read it directly — no argument, no movw. In C++ an outlined rx/tx can only receive the unit as a parameter (a movw at each of ~19 call sites, +38 B) or read it from RAM (an lds), unless it is a global register variable. That register is worth ~32 B and is exactly the impurity at issue.
2. A cheap PC-relative slot anchor (rcall .+0; pop; pop, ~10 B) where the C++ __builtin_return_address(0) costs ~18–26 B (GCC re-derives the stack slot and byteswaps).

Measured on identical C++ (the same loader, unit in a register vs. RAM):

unit home	1284 size
global register variable	528
RAM static	560
hand-asm (register + cheap anchor)	506

So even with a GRV, C++ carries ~22 B over hand-asm; with RAM, ~54 B. The compiler flag axis was spent (the tuned -f set is optimal; -fipa-ra, -fipa-icf, -ftree-tail-merge, -flto, -fwhole-program all gave nothing — GCC's AVR ABI passes arguments in fixed registers regardless).

The pure lever — GPIOR

The register cost is the RAM home's lds/sts (two words each) plus .bss and its __do_clear_bss. The general-purpose I/O scratch registers (GPIOR1:GPIOR2, adjacent) are reached by in/out — one word — through libavr's named register surface: no inline asm, no global register variable, fully pure. Storing the unit there sidesteps .bss and halves each access. Where a chip has no GPIOR (the t13, m8, m16/32) the pure version falls back to a plain static; those chips have ample headroom.

GPIOR alone did not close the gap (the write guard's slot_high machinery is the bulk). The pure version fits by combining GPIOR storage with the licensed simplifications; the register version fits by pinning the unit and so affording the guard.

The ablation (1284, all pure except the GRV row)

config	GPIOR unit	GRV unit
full info + guard + 2-knock	550	528
slim info + guard + 2-knock	540	518
slim info + guard + 1-knock	—	512 ✓
slim info + no guard + 2-knock	514	—
slim info + no guard + 1-knock	508 ✓	—

The pivotal cost is the write guard's slot_high (__builtin_return_address, ~26 B), removable only when the info block is slim (so nothing else needs slot_high) and the guard is gone. That is why the pure version drops the guard and the register version keeps it.

Sizes — every chip, both versions

Both build and size-test green on all 37 (patched-vector budget 510, else 512):

chip class	pure	register	budget
ATtiny13/13A	446	452	510
ATtiny25/45/85	440–444	456–460	510
ATmega8/8A	472	476	512
ATmega16/32	476	478	512
ATmega48 family	440	456	510
ATmega88/168/328	462–466	476–478	512
ATmega164/324/644	466	478	512
ATmega1284/P	508	512	512

The 1284 is the tight one — the far-flash machinery (ELPM/RAMPZ, word-addressed wire) it alone carries. The pureboot_autobaud_*.size tests run per chip in the port's build.

The shared simplifications, and why each is licensed

• Slimmed info block. 'b' returns the version and the three signature bytes — the loader's identity and the chip's — as immediates, instead of the full 12-byte block read from flash. The host derives page size, loader base, EEPROM size and the addressing flags from the signature via its own chip database. This drops the flash-resident table and, with the guard also gone in the pure version, the entire slot_high anchor. Owner-approved: "keep version + chip type, simplify the rest; the host derives geometry."
• Single-byte knock. One 'p' activates; the calibration pulse has already proven a host is present. (Fixed-baud pureboot needs p+b because it has no prior proof.)
• No running-slot write guard (pure version only). The guard stops a buggy host from programming the loader's own slot; the host is guaranteed never to do so (it knows the loader's location). Licensed by "the host guarantees safety" (README.md). Self-update still works — it is the safety net against host bugs that is lost, not a functional path.

Host tool and simulation — done

Both are wired and green, for both variants.

• Host tool. pureboot.py --autobaud sends the 0xC0 calibration pulse and a single knock at the host's chosen baud, then reads the slimmed info block and derives the full geometry from the signature (AUTOBAUD_GEOMETRY, a table over every chip pureboot targets). The rest of the tool — flash, EEPROM, fuses, hand-over, verify — is unchanged: once connected, the derived Info presents the same geometry the fixed-baud path reads off the wire. The pure version's dropped write guard is host-transparent (the tool already never targets the running slot).
• Sim test (test/pbautobaud.py, pureboot.autobaud_pure / pureboot.autobaud_reg). Drives each variant over the GPIO⇄pty software-UART bridge through the calibration handshake, a flash + EEPROM + fuse round-trip cross-checked against the simulator's ground-truth memory, and a hand-over to the fixture application — then repeats at double the F_CPU with the same binary, which is the clock-agnostic property autobaud exists for. Run on the near-flash 328P and the word-addressed 1284P (both flash-addressing classes). Because the lock fails a flash/verify if the measured unit is wrong, this test also pins the codegen-coupled calibration constant (0xC0 against the 7-cycle poll loop): a toolchain bump that reshaped the loop would fail it.

What remains

The decider is answered (pure C++ fits 512 on every chip) and both variants pass in simulation. One item remains before shipping the chosen variant:

• Real-hardware acceptance. Autobaud exists for what a cycle-exact simulator cannot produce: a real RC oscillator at ±10 % with drift and jitter. simavr proves the arithmetic and the fit at exact clocks; only silicon proves the feature does its job. Drive an internal-oscillator ATtiny from the host at a fixed baud; confirm lock plus a full flash + verify (Windows environment, hardware present — confirm first). Deferred until the variant is chosen.

Files

• pureboot_autobaud_pure.cpp — the pure version (GPIOR/RAM unit, no guard).
• pureboot_autobaud_reg.cpp — the register version (GRV unit, guard kept).
• pureboot.py — --autobaud: the calibration handshake, slim info, and the signature→geometry table both variants rely on.
• test/pbautobaud.py — the end-to-end sim test; CMakeLists.txt runs it for both variants on the 328P and 1284P, and pureboot_add_autobaud() size-tests both on every chip.
• local/scratch/autobaud/floor_1284.S (libavr checkout) — the hand-asm floor probe, off-tree and gitignored; not sim-verified, a size reference only.