tsb: vendor the fixed-baud assembly oracle as the size/feature bar
The Seed Robotics native-UART fixed-baud TinySafeBoot (GPLv3), reference only — not built. Assembles to 500 B with the full feature set, proving ≤512 B and full feature parity are simultaneously reachable. Also drops the stale empty stk500v2/ leftover. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
47
oracle/README.md
Normal file
47
oracle/README.md
Normal file
@@ -0,0 +1,47 @@
|
||||
# Oracle — the hand-written TinySafeBoot assembly
|
||||
|
||||
`tsb-fixedbaud.asm` is the reference implementation this port is measured
|
||||
against: the **native-UART, fixed-baud** TinySafeBoot bootloader, hand-written
|
||||
in AVR assembly. It is the size-and-feature bar for the port's `tsb_asm` tier.
|
||||
|
||||
- **Source**: <https://github.com/seedrobotics/tinysafeboot>
|
||||
(`firmware_ASM/latest_stable_release/20200727-fixedbaud/main.asm`), the Seed
|
||||
Robotics fixed-baud fork of Julien Thomas' TinySafeBoot.
|
||||
- **License**: GPLv3 (see the header in the file). It is vendored here **only as
|
||||
a reference oracle** — it is not compiled, linked, or distributed as part of
|
||||
the MIT-licensed port. Mere aggregation.
|
||||
|
||||
## Why this variant
|
||||
|
||||
The user chose the fixed-baud, hardware-UART variant deliberately: it is the one
|
||||
whose feature set the port must match. It fits the **complete** TSB feature set
|
||||
into the 512-byte ATmega boot section:
|
||||
|
||||
| Feature | Oracle routine |
|
||||
|---|---|
|
||||
| Watchdog-reset bail straight to the app | `RESET` (WDRF check) |
|
||||
| One-wire half-duplex (RX/TX shorted): RXEN/TXEN toggled per direction, TX turnaround guard | `SetRX` / `SetTX` / `TransmitByte` |
|
||||
| Activation timeout read from the config page, with a lockout-proof minimum | `WRX1To` (uses `utimeoutH`) |
|
||||
| 3×`@` activation knock | `ActCharRcvd` |
|
||||
| Password gate; wrong byte hangs (still draining the UART) | `CheckPassword` |
|
||||
| Emergency erase on password `\0` + double-confirm — wipes flash, EEPROM and the config page | `EmergencyErase` |
|
||||
| Device-info block (16 bytes) | `SendDeviceInfo` / `DEVICEINFO` |
|
||||
| App-flash read/write (`f`/`F`), EEPROM read/write (`e`/`E`), config read/write (`c`/`C`) | `CheckCommands` |
|
||||
|
||||
## Assembled size (the bar)
|
||||
|
||||
Assembled for the ATmega328P with `avra`:
|
||||
|
||||
```
|
||||
avra -I /usr/share/avra tsb-fixedbaud.asm # after uncommenting .include "m328Pdef.inc"
|
||||
# Code : 250 words (500 bytes) — the whole loader, all features, in the 512 B section
|
||||
```
|
||||
|
||||
**500 bytes with every feature** — the proof that ≤512 B and full feature parity
|
||||
are simultaneously reachable. The port's `tsb_asm` tier matches this bar; `tsb_pure`
|
||||
and `tsb_tricks` implement the same protocol at larger sizes in the 1 KB section,
|
||||
trading bytes for readability.
|
||||
|
||||
The oracle targets 20 MHz / 33333 baud; the port targets 16 MHz / 115200 baud
|
||||
(what the simavr protocol test drives). Baud and geometry differ, code size and
|
||||
feature set do not.
|
||||
Reference in New Issue
Block a user