bootloader/pureboot/autobaud.md

pureboot autobaud — findings, and how the version question settled itself

The autobaud loader 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 the two versions that were under review are both dead, and what the loader looks like now.

The decision, settled by measurement

Two autobaud loaders were built for review, differing in one tradeoff — the running-slot write guard against strict purity. pureboot_autobaud_pure.cpp landed at 508 B on the 1284P (4 B spare) and pureboot_autobaud_reg.cpp at 512 (zero spare).

Then hardware testing found a defect that neither could absorb.

A single spurious calibration pulse wedged the loader. run() budgeted only the start-edge wait inside measure(); the rx() that read the knock behind it was unbudgeted and blocked forever. One stray low pulse on an unattended device — EMI, or a host that opens the port and never knocks — held the loader in its activation loop and the application never ran. On a field device that is a hang, not a hiccup, and it is exactly the deployment autobaud is for.

The fix is to bound the whole activation: an expired knock budget returns a byte that cannot be the knock, so control falls back into the budgeted measure(), and a line that stays idle boots the application there. It costs about 22 bytes.

1284P, with the activation fix	size	512 B budget
pureboot_autobaud_pure.cpp	530	over by 18
pureboot_autobaud_reg.cpp	534	over by 22
pureboot_autobaud_uni.cpp	464	48 B spare

Both candidates were unshippable, and the margin they were competing over was never real — it was the space the missing fix should have occupied. So the choice is not between them. It is the third loader below, which fits with room to spare and carries features neither had. The two sources stay in the tree for the record; only the unified one is built.

The unified loader

The insight that paid was the one that had already paid once: merging command bodies removes cost that moving them around only redistributes. Folding R, r and w into a single address-and-count path had been worth 14 B earlier. Pushed further — one read command and one write command over named spaces — it is worth far more, because four transfer loops collapse into one.

pureboot_autobaud_uni.cpp is pureboot 5. It is strictly pure: no inline assembly, no global register variable, and no GPIOR either — the measured unit lives in a plain static, so the loader claims no chip resource an application might want, and the GPIOR-versus-static question disappears along with the chips that have no GPIOR.

The protocol

command	arguments
b	—	version, then the three signature bytes
J	addr16	ack, then jump (word address)
W	sel8, addr16, page bytes	fill the flash page buffer
G	sel8, addr16, n8	read n bytes (0 means 256)
g	sel8, addr16, n8, then n bytes	write, each byte acked

sel is space | bank << 4. The low nibble names the space; the high nibble is flash's third address byte, so every transfer speaks a byte address inside a 64 KiB bank and no command has to carry word addresses. The host must not span a bank boundary in one transfer — it already chunks by page, so nothing it does comes close.

space
0	flash	lpm/elpm
1	EEPROM
2	data	SRAM — and with it the register file and every I/O register, which share the data address space on AVR
3	fuse and lock
4	SPM	write-only: the data byte goes to SPMCSR and fires the instruction at the selected address

Three things follow from that table that the loader never had:

• RAM read and write, the missing feature. In a per-command design it would have cost a fresh dispatch arm and a fresh loop, ~30 B, on a loader with 4 B spare. As one more space on a shared loop it is a single ld/st. It also hands the host arbitrary I/O register access for free, because AVR maps the peripherals into the same address space.
• Host-driven SPM. W used to end with a hardcoded erase, write and RWW re-enable — 42 B. Those are now three writes to the SPM space, reusing the store path's own address, data byte and ack. The host pays three extra round-trips per page (18 wire bytes against 256 of data) and gains the ability to issue any SPM operation, lock bits included.
• W on the same footing as everything else. It takes the same selector and the same byte address instead of a word address of its own, which made flash addressing uniform across the protocol and was 20 B cheaper than keeping its private convention.

Read and write are G and g — the same letter, one bit apart — so the transfer loop picks its direction with a one-word skip rather than a compare.

Why the SPM space has to be one primitive

It is tempting to go further and expose a generic "poke this I/O register", from which the host could drive SPM itself. The hardware forbids it: out SPMCSR, x and the spm that follows must issue within four cycles, and EEPROM's EEMPE→EEPE window is the same shape. A host cannot hit a four-cycle window across a serial link. Atomicity is the floor, and the atomic unit must be resident. That is the real limit on how low-level a bootloader's primitives can go — not the byte count.

Where the bytes went

The starting point was the 508 B pure build, disassembled and attributed:

phase	bytes
link::rx + link::tx (bit-banged UART)	102
autobaud measure + knock	62
reset vector, pin init, WDRF check, jump, ack, EEPROM wait	50
command loop head + dispatch tree	42
W program flash page	98
R / r / w / F bodies, plus the shared address decode	122
b info, J jump	32

208 B — 41% — is physical layer and activation, which no protocol change can touch. The command bodies were the entire addressable surface, and they were four copies of one idea.

The route from a first attempt to the final loader, all on the 1284P:

step	size
unified G/P, load/store outlined, __uint24 cursor	600
…load/store inlined; unit in .noinit, not .bss	534
…16-bit cursor with the bank in the selector; direction as a command bit	510
…erase/write/RWW moved out to the SPM space	484
…W sharing the selector-and-address decode	464

Three of those steps are worth keeping as lessons:

• Outlining load/store cost more than the four bodies they replaced. As functions they were 110 B against the 106 B of inline bodies — the AVR ABI's argument marshalling plus prologue ate the entire saving. Inlined into the one shared loop they cost only their own instructions. The call-site lesson cuts both ways: merging call sites pays, creating one does not.
• A .bss static drags in __do_clear_bss — 18 B of startup code to zero a variable that is always measured before it is read. .noinit is correct here and free.
• A three-byte cursor taxes every space. Widening the shared cursor so flash could reach past 64 KiB put an extra increment on EEPROM and RAM reads that never need it. Moving the bank into the selector byte kept the cursor at sixteen bits and cost nothing on the wire.

What did not work

• Encoding the space in the command byte (so dispatch becomes masking rather than a compare tree) cannot carry the bank's four bits alongside a space. The cheap half of the idea survived as the direction bit; the rest lost to the selector byte, which is also more extensible.
• A generic primitive interpreter — a loader with no logic at all, driven entirely by the host — is not reachable on AVR. Harvard architecture means the program counter cannot fetch from data space, so the classic "upload a flash algorithm into RAM and jump to it" bootstrap is impossible, and on every boot-sectioned part SPM only takes effect from the boot section anyway. What remains is a fixed primitive set: still a protocol, still logic, only at a different granularity. debugWIRE reaches that design point only because its interpreter is in silicon; it costs the loader nothing because it is not in the loader.
• Below 512 B the saved bytes are largely unspendable on the boot-sectioned chips: the 328P's smallest boot section is exactly 512 B, and the 1284P's is 1024 B, of which pureboot already occupies only the top half. The margin matters as headroom for correctness fixes — as this defect showed — not as flash returned to the application. On the patch-vector parts, which have no boot section, it is returned: on the ATtiny13 the loader is 43% of a 1 KiB part, and every byte is real.

The codegen coupling, still load-bearing

count >> 2 is exact only because the calibration pulse's bit-count (7, from the 0xC0 byte) equals the poll loop's cycles per iteration (7 — sbis 1, rjmp 2, adiw 2, rjmp 2). The loop shape survived every restructuring here, verified in the disassembly, but a toolchain bump that reshapes it would break the lock silently. test/pbautobaud.py is what pins it: a wrong unit fails the flash verify.

Sizes — every chip

Budget 510 B on the patch-vector parts, 512 elsewhere. The 1284P is no longer the tight one: the bank nibble made far flash cheaper than the near-flash arithmetic it replaced.

size	chips	budget	spare
444	ATtiny13, 13A	510	66
448	ATmega48, 48A, 48P, 48PA; ATtiny25	510	62
452	ATtiny45, 85	510	58
460	ATmega644, 644A, 644P, 644PA	512	52
464	ATmega1284, 1284P; ATmega8, 8A, 88, 88A, 88P, 88PA	512	48
466	ATmega16, 16A, 32, 32A; 164A/P/PA, 168/A/P/PA, 324A/P/PA, 328, 328P	512	46

All 37 chips build and size-test green, plus the 12-preset reflect spot set (guidance rule 4 — the reflect matrix is never run in full), which matches its generated counterpart byte for byte on every chip in the set. Worst case across the whole set is 466 B, 46 under budget.

Host tool and simulation

• pureboot.py speaks both generations. Info.version >= 5 selects the unified path; everything below it keeps the four-command protocol, so the fixed-baud loader is untouched. --autobaud sends the 0xC0 pulse and one knock, then derives full geometry from the signature. New: --peek ADDR[:N] and --poke ADDR:HEX reach the data space.
• test/pbautobaud.py drives the loader over the GPIO⇄pty software-UART bridge through the calibration handshake, a flash + EEPROM + fuse round-trip cross-checked against the simulator's own memory, a RAM read/write round-trip, 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.
• It also pins the activation hang: the test sends a lone calibration pulse with no knock behind it and requires the application to boot. Against the unfixed loader that assertion never returns.

What remains

• Real-hardware acceptance. A cycle-exact simulator cannot produce what autobaud exists for: 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. Drive an internal-oscillator ATtiny at a fixed host baud and confirm lock plus a full flash and verify.
• A generic spm::command() in libavr. The SPM space issues a runtime command through spm::detail::page_command where RAMPZ exists, and falls back to a dispatch over the known operations where it does not — the one preprocessor branch in the file. A two-line library addition would make it uniform and save a few bytes on the 36 non-RAMPZ chips, none of which are tight.
• Retire or revive the two dead variants. They are kept only as the record of the measurement; nothing builds them.

Files

• pureboot_autobaud_uni.cpp — the loader. pureboot 5.
• pureboot_autobaud_pure.cpp, pureboot_autobaud_reg.cpp — superseded, not built; 530 and 534 B on the 1284P once the activation hang is fixed.
• pureboot.py — --autobaud, the unified transfer path, --peek/--poke.
• test/pbautobaud.py — the end-to-end sim test and the hang regression.
• local/scratch/autobaud/floor_1284.S (libavr checkout) — the hand-asm floor probe at 506 B, off-tree and gitignored; a size reference only. The unified loader is 42 B under it, with features the probe never had.