avr/bootloader
1
0 Fork 0
Code Issues Pull Requests Releases Wiki Activity

tsb: the protocol the tiers share is written once, and its bytes by name

Browse Source 
tsb/tsb.hpp holds the link, the handshake and command bytes, the guard
policy and SPM interlock, the boot geometry, act_min/comm_window and a
consteval builder for the 16-byte info block, whose BUILDSTATE and ATmega
marker bytes are now named rather than commented. Every tier's image is
byte-identical to before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
BlackMarkandClaude Opus 5.5 committed 2026-10-24 12:24:12 +02:00
1 parent 44db419c4b
commit e395c0344f
5 files changed
+191 -293
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

tsb/tsb.hpp
+106
View File
@@ -0,0 +1,106 @@
// The TinySafeBoot native-UART fixed-baud protocol, as every tier speaks it:
// the link, the handshake and command bytes, the boot geometry and the
// device-info block the host reads on activation.
#pragma once
#include <libavr/libavr.hpp>
namespace tsb {
using namespace avr::literals;
namespace spm = avr::spm;
namespace ee = avr::eeprom;
constexpr auto clock = 16_MHz;
constexpr auto baud_rate = 115200_Bd;
// Fixed 8N1; the library solves UBRR + U2X from clock and baud.
constexpr auto baud = avr::uart::solve_baud(clock, baud_rate, 8, avr::uart::parity::none);
// One bit time on the wire: the turn-around a shared-line peer needs to stop
// driving before this one starts.
constexpr auto guard_cycles = static_cast<std::uint32_t>(clock.hz / baud.actual);
// 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;
// Strict request/response: every SPM operation is waited out before the next
// byte moves, so no flash operation is ever in flight at an EEPROM access -
// the write procedure's step 2 has nothing to guard, the omission the
// datasheet grants (DS40002061B section 8.6.3).
constexpr auto no_spm = ee::spm_interlock::omitted;
constexpr std::uint8_t confirm = '!';
constexpr std::uint8_t request = '?';
constexpr std::uint8_t knock = '@';
constexpr std::uint8_t activation_knocks = 3;
namespace command {
constexpr std::uint8_t read_flash = 'f';
constexpr std::uint8_t write_flash = 'F';
constexpr std::uint8_t read_eeprom = 'e';
constexpr std::uint8_t write_eeprom = 'E';
constexpr std::uint8_t read_config = 'c';
constexpr std::uint8_t write_config = 'C';
} // namespace command
// The lockout-proof floor for the receive window: the oracle's F_CPU/1MHz.
constexpr auto act_min = static_cast<std::uint8_t>(clock.hz / 1'000'000);
// Post-activation window: the host gets seconds, not milliseconds, mid-session.
constexpr std::uint8_t comm_window = 200;
constexpr std::uint16_t page = spm::page_bytes;
constexpr std::uint16_t eeprom_end = avr::hw::db.mem.eeprom_size - 1;
// The config page (TSB's LASTPAGE), one page below the boot section: the
// application's jump vector, then these.
consteval std::uint16_t config_page(std::uint16_t boot_bytes)
{
return spm::flash_bytes - boot_bytes - page;
}
constexpr std::uint8_t timeout_at = 2;
constexpr std::uint8_t password_at = 3;
// The firmware version stamp, in the encoding the host decodes.
consteval std::uint16_t date_stamp(std::uint16_t year, std::uint16_t month, std::uint16_t day)
{
return year * 512 + month * 32 + day;
}
// BUILDSTATE F3: the native-UART fixed-baud lineage.
constexpr std::uint8_t build_state = 0xF3;
constexpr std::uint8_t atmega_marker = 0xAA;
consteval auto info_block(std::uint16_t build_date, std::uint16_t app_end)
{
const auto low = [](std::uint16_t word) { return static_cast<std::uint8_t>(word); };
const auto high = [](std::uint16_t word) { return static_cast<std::uint8_t>(word >> 8); };
const std::uint16_t app_end_words = app_end / 2;
return std::to_array<std::uint8_t>({
'T',
'S',
'B',
low(build_date),
high(build_date),
build_state,
avr::hw::db.signature[0],
avr::hw::db.signature[1],
avr::hw::db.signature[2],
page / 2,
low(app_end_words),
high(app_end_words),
low(eeprom_end),
high(eeprom_end),
atmega_marker,
atmega_marker,
});
}
inline const std::uint8_t *flash_ptr(std::uint16_t addr)
{
return reinterpret_cast<const std::uint8_t *>(addr);
}
} // namespace tsb
tsb/tsb_asm.cpp
+18 -74
View File
@@ -30,82 +30,26 @@
// line safe: the device drives it only between a received command and its // line safe: the device drives it only between a received command and its
// reply, and releases it (RXEN0 only) whenever it waits. // reply, and releases it (RXEN0 only) whenever it waits.
#include <libavr/libavr.hpp> #include "tsb.hpp"
#include <avr/io.h> // SPMCSR's I/O address for the page-store routine #include <avr/io.h> // SPMCSR's I/O address for the page-store routine
using namespace avr::literals;
namespace spm = avr::spm;
namespace ee = avr::eeprom;
namespace hw = avr::hw; namespace hw = avr::hw;
namespace tsb { namespace tsb {
namespace { namespace {
// The loader is purely polled - it never enables interrupts - so every SPM and // The boot section: 512 B, BOOTSZ=11.
// EEPROM lock folds to nothing under this posture.
constexpr auto off = avr::irq::guard_policy::unused;
// Strict request/response: every SPM operation is waited out before the next
// byte moves, so no flash operation is ever in flight at an EEPROM access -
// the write procedure's step 2 has nothing to guard, the omission the
// datasheet grants (DS40002061B section 8.6.3).
constexpr auto no_spm = ee::spm_interlock::omitted;
constexpr std::uint8_t confirm = '!';
constexpr std::uint8_t request = '?';
constexpr std::uint8_t knock = '@';
constexpr auto clock = 16_MHz;
// Boot geometry for the 512 B boot section (BOOTSZ=11); 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 = 512; constexpr std::uint16_t boot_bytes = 512;
constexpr std::uint16_t app_end = spm::flash_bytes - boot_bytes - page; constexpr std::uint16_t app_end = config_page(boot_bytes);
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, so [[gnu::progmem]] constexpr auto info = info_block(date_stamp(26, 7, 20), app_end);
// it follows the clock rather than restating it.
constexpr auto act_min = static_cast<std::uint8_t>(clock.hz / 1'000'000);
// Post-activation window: the host gets seconds, not milliseconds, mid-session.
constexpr std::uint8_t comm_window = 200;
constexpr std::uint16_t build_date = 26 * 512 + 7 * 32 + 20;
// Fixed 115200 8N1; the library solves UBRR + U2X from clock and baud.
constexpr auto baud = avr::uart::solve_baud(clock, 115200_Bd, 8, avr::uart::parity::none);
// One bit time on the wire: the turn-around a shared-line peer needs to stop
// driving before this one starts. Derived from the solved rate, so it follows
// the link rather than a count measured against one.
constexpr auto guard_cycles = static_cast<std::uint32_t>(clock.hz / baud.actual);
// The 16-byte device-info block, streamed out on activation.
// clang-format off
[[gnu::progmem]] constexpr auto info = std::to_array<std::uint8_t>({
'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,
eeprom_end & 0xFF, eeprom_end >> 8,
0xAA, 0xAA,
});
// clang-format on
register std::uint16_t g_addr asm("r28"); register std::uint16_t g_addr asm("r28");
register std::uint8_t g_cnt asm("r16"); register std::uint8_t g_cnt asm("r16");
register std::uint8_t g_window asm("r7"); register std::uint8_t g_window asm("r7");
register std::uint8_t g_receiving asm("r6"); register std::uint8_t g_receiving asm("r6");
const std::uint8_t *flash_ptr(std::uint16_t addr)
{
return reinterpret_cast<const std::uint8_t *>(addr);
}
// Bounded byte receive (asm 1 of 2): release the one-wire line on a direction // Bounded byte receive (asm 1 of 2): release the one-wire line on a direction
// change, poll RXC0 under the oracle's nested X-register countdown seeded from // change, poll RXC0 under the oracle's nested X-register countdown seeded from
// g_window (floored against lockout), byte or 0-on-silence in r24. Z survives // g_window (floored against lockout), byte or 0-on-silence in r24. Z survives
@@ -288,23 +232,23 @@ extern "C" [[noreturn]] void tsb_app(); // the application's reset vector: --def
// same reason. // same reason.
g_receiving = 0; g_receiving = 0;
// Activation: 3x'@', each inside the config page's timeout window (rx // Activation: activation_knocks '@', each inside the config page's timeout
// floors it so a corrupt page cannot lock the loader out); anything else - // window (rx floors it so a corrupt page cannot lock the loader out);
// including silence - hands over. // anything else - including silence - hands over.
g_window = avr::flash_load(flash_ptr(app_end + 2)); g_window = avr::flash_load(flash_ptr(app_end + timeout_at));
for (std::uint8_t k = 3; k; --k) { for (std::uint8_t k = activation_knocks; k; --k) {
if (rx() != knock) { if (rx() != knock) {
appjump(); appjump();
} }
} }
g_window = comm_window; g_window = comm_window;
// Password gate (config page from app_end+3, 0xff-terminated; a blank // Password gate (config page from password_at, 0xff-terminated; a blank
// page is no password). A wrong byte blanks the comparison and drains the // 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 // 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; // emergency erase behind two confirms. On pass the info block goes out;
// the emergency path skips it and drops into the command loop. // the emergency path skips it and drops into the command loop.
g_addr = app_end + 3; g_addr = app_end + password_at;
std::uint8_t mask = 0xff; std::uint8_t mask = 0xff;
for (;;) { for (;;) {
std::uint8_t expected = avr::flash_load(flash_ptr(g_addr)) & mask; std::uint8_t expected = avr::flash_load(flash_ptr(g_addr)) & mask;
@@ -340,7 +284,7 @@ extern "C" [[noreturn]] void tsb_app(); // the application's reset vector: --def
tx(confirm); // Mainloop ready tx(confirm); // Mainloop ready
g_addr = 0; g_addr = 0;
switch (rx()) { switch (rx()) {
case 'f': // read application flash, one page per host '!' case command::read_flash: // one page per host '!'
for (;;) { for (;;) {
if (rx() != confirm) { if (rx() != confirm) {
break; break;
@@ -352,13 +296,13 @@ extern "C" [[noreturn]] void tsb_app(); // the application's reset vector: --def
} }
} }
break; break;
case 'F': // erase the application, then take pages behind '?' case command::write_flash: // erase the application, then take pages behind '?'
erase_application(); // leaves g_addr = 0, the write start erase_application(); // leaves g_addr = 0, the write start
while (rcnf() == confirm) { while (rcnf() == confirm) {
store_flash(); store_flash();
} }
break; break;
case 'e': // read EEPROM, one page per host '!', until the host stops case command::read_eeprom: // one page per host '!', until the host stops
for (;;) { for (;;) {
if (rx() != confirm) { if (rx() != confirm) {
break; break;
@@ -369,7 +313,7 @@ extern "C" [[noreturn]] void tsb_app(); // the application's reset vector: --def
} while (--g_cnt); } while (--g_cnt);
} }
break; break;
case 'E': // take EEPROM pages behind '?' case command::write_eeprom: // pages behind '?'
while (rcnf() == confirm) { while (rcnf() == confirm) {
g_cnt = page; g_cnt = page;
do { do {
@@ -377,13 +321,13 @@ extern "C" [[noreturn]] void tsb_app(); // the application's reset vector: --def
} while (--g_cnt); } while (--g_cnt);
} }
break; break;
case 'c': // read the config page case command::read_config:
read_config: read_config:
g_addr = app_end; g_addr = app_end;
g_cnt = page; g_cnt = page;
sendf(); sendf();
break; break;
case 'C': // replace the config page, then echo it back to verify case command::write_config: // then echo it back to verify
if (rcnf() != confirm) { if (rcnf() != confirm) {
break; break;
} }
tsb/tsb_policy.cpp
+20 -70
View File
@@ -19,19 +19,15 @@
// its reply, and releases it (the library's half-duplex choreography) // its reply, and releases it (the library's half-duplex choreography)
// whenever it waits. // whenever it waits.
#include <libavr/libavr.hpp> #include "tsb.hpp"
using namespace avr::literals; using dev = avr::device<{.clock = tsb::clock}>;
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. // One-wire: RX and TX share the line, exactly as the native-UART TSB expects.
// 115200 at 16 MHz lands +2.1 % off, past the receiver-tolerance table the // 115200 at 16 MHz lands +2.1 % off, past the receiver-tolerance table the
// solver holds rates to - the oracle's own deployment has run there for a // solver holds rates to - the oracle's own deployment has run there for a
// decade, so the override states that it is meant. // decade, so the override states that it is meant.
constexpr avr::uart::config link{ constexpr avr::uart::config link{
.baud = 115200_Bd, .baud = tsb::baud_rate,
.allow_baud_error = true, .allow_baud_error = true,
.half_duplex = true, .half_duplex = true,
}; };
@@ -41,61 +37,16 @@ inline constexpr serial_t serial{};
namespace tsb { namespace tsb {
namespace { namespace {
// The loader is purely polled - it never enables interrupts - so every SPM and // The boot section: 1 KB, BOOTSZ=10.
// EEPROM lock folds to nothing under this posture.
constexpr auto off = avr::irq::guard_policy::unused;
// Strict request/response: every SPM operation is waited out before the next
// byte moves, so no flash operation is ever in flight at an EEPROM access -
// the write procedure's step 2 has nothing to guard, the omission the
// datasheet grants (DS40002061B section 8.6.3).
constexpr auto no_spm = ee::spm_interlock::omitted;
// 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 boot_bytes = 1024;
constexpr std::uint16_t app_end = spm::flash_bytes - boot_bytes - page; constexpr std::uint16_t app_end = config_page(boot_bytes);
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, so [[gnu::progmem]] constexpr auto info = info_block(date_stamp(26, 7, 27), app_end);
// it follows the clock rather than restating it.
constexpr auto act_min = static_cast<std::uint8_t>(dev::clock.hz / 1'000'000);
// 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 auto info = std::to_array<std::uint8_t>({
'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 // 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. // crt to clear a .bss image, and run() stores it before the first receive.
[[gnu::section(".noinit")]] std::uint8_t window; [[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 // 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 // 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 // command - so a silent host unwinds the loader to the application from
@@ -219,23 +170,23 @@ extern "C" [[noreturn]] void tsb_app(); // the application's reset vector: --def
avr::hw::ucsr0a::write(avr::hw::ucsr0a::u2x0(1)); avr::hw::ucsr0a::write(avr::hw::ucsr0a::u2x0(1));
} }
// Activation: 3x'@', each inside the config page's timeout window // Activation: activation_knocks '@', each inside the config page's timeout
// (floored so a corrupt page cannot lock the loader out); anything else - // window (floored so a corrupt page cannot lock the loader out); anything
// including silence - hands over. // else - including silence - hands over.
window = avr::flash_load(flash_ptr(app_end + 2)) | act_min; window = avr::flash_load(flash_ptr(app_end + timeout_at)) | act_min;
for (std::uint8_t k = 3; k; --k) { for (std::uint8_t k = activation_knocks; k; --k) {
if (rx() != knock) { if (rx() != knock) {
appjump(); appjump();
} }
} }
window = comm_window; window = comm_window;
// Password gate (config page from app_end+3, 0xff-terminated; a blank // Password gate (config page from password_at, 0xff-terminated; a blank
// page is no password). A wrong byte blanks the comparison and drains the // 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 // 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; // emergency erase behind two confirms. On pass the info block goes out;
// the emergency path skips it and drops into the command loop. // the emergency path skips it and drops into the command loop.
std::uint16_t at = app_end + 3; std::uint16_t at = app_end + password_at;
std::uint8_t mask = 0xff; std::uint8_t mask = 0xff;
for (;;) { for (;;) {
const std::uint8_t expected = avr::flash_load(flash_ptr(at)) & mask; const std::uint8_t expected = avr::flash_load(flash_ptr(at)) & mask;
@@ -266,9 +217,8 @@ extern "C" [[noreturn]] void tsb_app(); // the application's reset vector: --def
for (;;) { for (;;) {
tx(confirm); // Mainloop ready tx(confirm); // Mainloop ready
const auto command = rx(); switch (rx()) {
switch (command) { case command::read_flash: // one page per host '!'
case 'f': // read application flash, one page per host '!'
for (std::uint16_t a = 0; a < app_end; a += page) { for (std::uint16_t a = 0; a < app_end; a += page) {
if (rx() != confirm) { if (rx() != confirm) {
break; break;
@@ -276,7 +226,7 @@ extern "C" [[noreturn]] void tsb_app(); // the application's reset vector: --def
send_block(false, a, page); send_block(false, a, page);
} }
break; break;
case 'e': // read EEPROM, one page per host '!', until the host stops case command::read_eeprom: // one page per host '!', until the host stops
for (std::uint16_t a = 0;; a += page) { for (std::uint16_t a = 0;; a += page) {
if (rx() != confirm) { if (rx() != confirm) {
break; break;
@@ -284,14 +234,14 @@ extern "C" [[noreturn]] void tsb_app(); // the application's reset vector: --def
send_block(true, a, page); send_block(true, a, page);
} }
break; break;
case 'F': { // erase the application, then take pages behind '?' case command::write_flash: { // erase the application, then take pages behind '?'
std::uint16_t a = erase_application(); std::uint16_t a = erase_application();
for (; rcnf() == confirm; a += page) { for (; rcnf() == confirm; a += page) {
store_flash_page(a); store_flash_page(a);
} }
break; break;
} }
case 'E': // take EEPROM pages behind '?', each write host-paced case command::write_eeprom: // pages behind '?', each write host-paced
for (std::uint16_t a = 0; rcnf() == confirm;) { for (std::uint16_t a = 0; rcnf() == confirm;) {
std::uint8_t count = page; std::uint8_t count = page;
do { do {
@@ -300,11 +250,11 @@ extern "C" [[noreturn]] void tsb_app(); // the application's reset vector: --def
} while (--count); } while (--count);
} }
break; break;
case 'c': // read the config page case command::read_config:
read_config: read_config:
send_block(false, app_end, page); send_block(false, app_end, page);
break; break;
case 'C': // replace the config page, then echo it back to verify case command::write_config: // then echo it back to verify
if (rcnf() != confirm) { if (rcnf() != confirm) {
break; break;
} }
tsb/tsb_pure.cpp
+26 -73
View File
@@ -9,19 +9,15 @@
// The one-wire wiring, the flash-resident info block, every SPM/EEPROM lock and // The one-wire wiring, the flash-resident info block, every SPM/EEPROM lock and
// the crt-free reset entry are libavr's to handle. // the crt-free reset entry are libavr's to handle.
#include <libavr/libavr.hpp> #include "tsb.hpp"
using namespace avr::literals; using dev = avr::device<{.clock = tsb::clock}>;
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. // One-wire: RX and TX share the line, exactly as the native-UART TSB expects.
// 115200 at 16 MHz lands +2.1 % off, past the receiver-tolerance table the // 115200 at 16 MHz lands +2.1 % off, past the receiver-tolerance table the
// solver holds rates to - the oracle's own deployment has run there for a // solver holds rates to - the oracle's own deployment has run there for a
// decade, so the override states that it is meant. // decade, so the override states that it is meant.
using serial_t = dev::uart0<{ using serial_t = dev::uart0<{
.baud = 115200_Bd, .baud = tsb::baud_rate,
.allow_baud_error = true, .allow_baud_error = true,
.half_duplex = true, .half_duplex = true,
}>; }>;
@@ -30,53 +26,15 @@ inline constexpr serial_t serial{};
namespace tsb { namespace tsb {
namespace { namespace {
// The loader is purely polled - it never enables interrupts - so every SPM and // The boot section: 1 KB, BOOTSZ=10.
// EEPROM lock folds to nothing under this posture.
constexpr auto off = avr::irq::guard_policy::unused;
// Strict request/response: every SPM operation is waited out before the next
// byte moves, so no flash operation is ever in flight at an EEPROM access -
// the write procedure's step 2 has nothing to guard, the omission the
// datasheet grants (DS40002061B section 8.6.3).
constexpr auto no_spm = ee::spm_interlock::omitted;
// 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 (the LASTPAGE holding the app-jump vector, activation timeout and
// password), 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 boot_bytes = 1024;
constexpr std::uint16_t app_end = spm::flash_bytes - boot_bytes - page; constexpr std::uint16_t app_end = config_page(boot_bytes);
constexpr std::uint16_t eeprom_end = avr::hw::db.mem.eeprom_size - 1;
// Firmware version stamp: YY*512 + MM*32 + DD, the encoding the host decodes. // A flash_table keeps the info block in progmem with no .data image (there is
constexpr std::uint16_t build_date = 26 * 512 + 7 * 32 + 20; // no crt to copy one).
inline constexpr auto info_data = info_block(date_stamp(26, 7, 20), app_end);
// The 16-byte device-info block the host reads on activation. A flash_table
// keeps it in progmem with no .data image (there is no crt to copy one).
// clang-format off
inline constexpr auto info_data = std::to_array<std::uint8_t>({
'T', 'S', 'B',
build_date & 0xFF, build_date >> 8,
0xF3, // status byte (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
using info = avr::flash_table<info_data>; using info = avr::flash_table<info_data>;
// The lockout-proof floor for the receive window: the oracle's F_CPU/1MHz, so
// it follows the clock rather than restating it.
constexpr auto act_min = static_cast<std::uint8_t>(dev::clock.hz / 1'000'000);
// The receive window, pre-floored where it is set. In .noinit: there is no crt // 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. // to clear a .bss image, and run() stores it before the first receive.
[[gnu::section(".noinit")]] std::uint8_t window; [[gnu::section(".noinit")]] std::uint8_t window;
@@ -107,11 +65,6 @@ void tx(std::uint8_t byte)
serial.write(byte); serial.write(byte);
} }
const std::uint8_t *flash_ptr(std::uint16_t addr)
{
return reinterpret_cast<const std::uint8_t *>(addr);
}
// Stream `count` bytes to the host, from flash (LPM) or from EEPROM. // Stream `count` bytes to the host, from flash (LPM) or from EEPROM.
void send_flash(std::uint16_t addr, std::uint8_t count) void send_flash(std::uint16_t addr, std::uint8_t count)
{ {
@@ -187,8 +140,8 @@ extern "C" [[noreturn]] void tsb_app();
tsb_app(); tsb_app();
} }
// 'f': stream the application flash back, one page per host '!'. Self-terminates // Stream the application flash back, one page per host '!'. Self-terminates at
// at the application boundary; the host normally stops earlier with a non-'!'. // the application boundary; the host normally stops earlier with a non-'!'.
void read_flash() void read_flash()
{ {
for (std::uint16_t a = 0; a < app_end; a += page) { for (std::uint16_t a = 0; a < app_end; a += page) {
@@ -199,7 +152,7 @@ void read_flash()
} }
} }
// 'e': stream EEPROM back, one page per host '!', until the host stops. // Stream EEPROM back, one page per host '!', until the host stops.
void read_eeprom() void read_eeprom()
{ {
for (std::uint16_t a = 0;; a += page) { for (std::uint16_t a = 0;; a += page) {
@@ -210,8 +163,8 @@ void read_eeprom()
} }
} }
// 'F': erase the whole application first, then take pages the host offers // Erase the whole application first, then take pages the host offers behind
// behind '?'. // '?'.
void write_flash() void write_flash()
{ {
erase_application(); erase_application();
@@ -220,7 +173,7 @@ void write_flash()
} }
} }
// 'E': take pages the host offers behind '?' into EEPROM. // Take pages the host offers behind '?' into EEPROM.
void write_eeprom() void write_eeprom()
{ {
for (std::uint16_t a = 0; request_confirm(); a += page) { for (std::uint16_t a = 0; request_confirm(); a += page) {
@@ -228,7 +181,7 @@ void write_eeprom()
} }
} }
// 'C': replace the config page, then echo it back for the host to verify. // Replace the config page, then echo it back for the host to verify.
void write_config() void write_config()
{ {
if (!request_confirm()) { if (!request_confirm()) {
@@ -253,7 +206,7 @@ void emergency_erase()
spm::rww_enable<off>(); spm::rww_enable<off>();
} }
// The password gate. The config page holds the password at app_end+3, // The password gate. The config page holds the password at password_at,
// terminated by 0xff (a blank page means no password). A byte of 0 requests // terminated by 0xff (a blank page means no password). A byte of 0 requests
// emergency erase; a wrong byte hangs the loader, still draining the line, so a // emergency erase; a wrong byte hangs the loader, still draining the line, so a
// wrong password can never fall through to the erase. // wrong password can never fall through to the erase.
@@ -261,7 +214,7 @@ enum class gate : std::uint8_t { pass, emergency };
gate password_gate() gate password_gate()
{ {
for (const std::uint8_t *pw = flash_ptr(app_end + 3);; ++pw) { for (const std::uint8_t *pw = flash_ptr(app_end + password_at);; ++pw) {
const auto expected = avr::flash_load(pw); const auto expected = avr::flash_load(pw);
if (expected == 0xff) { if (expected == 0xff) {
return gate::pass; return gate::pass;
@@ -288,14 +241,14 @@ gate password_gate()
avr::init<serial_t>(); avr::init<serial_t>();
// Activation: the host knocks three '@' inside a window whose length is the // Activation: the host knocks activation_knocks times inside a window whose length is the
// config page's timeout byte, floored so a corrupt page can never lock the // config page's timeout byte, floored so a corrupt page can never lock the
// loader out. An idle port times out and boots the application; the same // loader out. An idle port times out and boots the application; the same
// window then bounds every receive of the session. // window then bounds every receive of the session.
window = avr::flash_load(flash_ptr(app_end + 2)) | act_min; window = avr::flash_load(flash_ptr(app_end + timeout_at)) | act_min;
__uint24 idle = static_cast<__uint24>(window) << 16; __uint24 idle = static_cast<__uint24>(window) << 16;
std::uint8_t knocks = 0; std::uint8_t knocks = 0;
while (knocks < 3) { while (knocks < activation_knocks) {
if (auto byte = serial.read()) { if (auto byte = serial.read()) {
knocks = *byte == knock ? knocks + 1 : 0; knocks = *byte == knock ? knocks + 1 : 0;
} else if (--idle == 0) { } else if (--idle == 0) {
@@ -318,22 +271,22 @@ gate password_gate()
for (;;) { for (;;) {
tx(confirm); // Mainloop ready tx(confirm); // Mainloop ready
switch (rx()) { switch (rx()) {
case 'f': case command::read_flash:
read_flash(); read_flash();
break; break;
case 'F': case command::write_flash:
write_flash(); write_flash();
break; break;
case 'e': case command::read_eeprom:
read_eeprom(); read_eeprom();
break; break;
case 'E': case command::write_eeprom:
write_eeprom(); write_eeprom();
break; break;
case 'c': case command::read_config:
send_flash(app_end, page); send_flash(app_end, page);
break; break;
case 'C': case command::write_config:
write_config(); write_config();
break; break;
default: default:
tsb/tsb_tricks.cpp
+21 -76
View File
@@ -29,80 +29,24 @@
// line safe: the device drives it only between a received command and its // line safe: the device drives it only between a received command and its
// reply, and releases it (RXEN0 only) whenever it waits. // reply, and releases it (RXEN0 only) whenever it waits.
#include <libavr/libavr.hpp> #include "tsb.hpp"
using namespace avr::literals;
namespace spm = avr::spm;
namespace ee = avr::eeprom;
namespace hw = avr::hw; namespace hw = avr::hw;
namespace tsb { namespace tsb {
namespace { namespace {
// The loader is purely polled - it never enables interrupts - so every SPM and // The boot section: 1 KB, BOOTSZ=10.
// EEPROM lock folds to nothing under this posture.
constexpr auto off = avr::irq::guard_policy::unused;
// Strict request/response: every SPM operation is waited out before the next
// byte moves, so no flash operation is ever in flight at an EEPROM access -
// the write procedure's step 2 has nothing to guard, the omission the
// datasheet grants (DS40002061B section 8.6.3).
constexpr auto no_spm = ee::spm_interlock::omitted;
constexpr std::uint8_t confirm = '!';
constexpr std::uint8_t request = '?';
constexpr std::uint8_t knock = '@';
constexpr auto clock = 16_MHz;
// 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 boot_bytes = 1024;
constexpr std::uint16_t app_end = spm::flash_bytes - boot_bytes - page; constexpr std::uint16_t app_end = config_page(boot_bytes);
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, so [[gnu::progmem]] constexpr auto info = info_block(date_stamp(26, 7, 20), app_end);
// it follows the clock rather than restating it.
constexpr auto act_min = static_cast<std::uint8_t>(clock.hz / 1'000'000);
// Post-activation window: the host gets seconds, not milliseconds, mid-session.
constexpr std::uint8_t comm_window = 200;
constexpr std::uint16_t build_date = 26 * 512 + 7 * 32 + 20;
// Fixed 115200 8N1; the library solves UBRR + U2X from clock and baud.
constexpr auto baud = avr::uart::solve_baud(clock, 115200_Bd, 8, avr::uart::parity::none);
// One bit time on the wire: the turn-around a shared-line peer needs to stop
// driving before this one starts. Derived from the solved rate, so it follows
// the link rather than a count measured against one.
constexpr auto guard_cycles = static_cast<std::uint32_t>(clock.hz / baud.actual);
// The 16-byte device-info block, streamed out on activation.
// clang-format off
[[gnu::progmem]] constexpr auto info = std::to_array<std::uint8_t>({
'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,
eeprom_end & 0xFF, eeprom_end >> 8,
0xAA, 0xAA,
});
// clang-format on
register std::uint16_t g_addr asm("r28"); register std::uint16_t g_addr asm("r28");
register std::uint8_t g_cnt asm("r16"); register std::uint8_t g_cnt asm("r16");
register std::uint8_t g_window asm("r7"); register std::uint8_t g_window asm("r7");
register std::uint8_t g_receiving asm("r6"); register std::uint8_t g_receiving asm("r6");
const std::uint8_t *flash_ptr(std::uint16_t addr)
{
return reinterpret_cast<const std::uint8_t *>(addr);
}
// Bounded byte receive, the oracle's shape: release the one-wire line on a // Bounded byte receive, the oracle's shape: release the one-wire line on a
// direction change, poll RXC0 under nested countdowns, 0 on silence. The 0 // direction change, poll RXC0 under nested countdowns, 0 on silence. The 0
// then falls through every compare - not a knock, not a confirm, not a // then falls through every compare - not a knock, not a confirm, not a
@@ -157,7 +101,8 @@ const std::uint8_t *flash_ptr(std::uint16_t addr)
return rx(); return rx();
} }
// One flash byte <- [g_addr++] (the advance right before ret - see header). // One flash byte <- [g_addr++] (the advance right before ret - see the top of
// this file).
[[gnu::noinline, gnu::noclone]] std::uint8_t sflash() [[gnu::noinline, gnu::noclone]] std::uint8_t sflash()
{ {
const auto byte = avr::flash_load(flash_ptr(g_addr)); const auto byte = avr::flash_load(flash_ptr(g_addr));
@@ -206,7 +151,7 @@ extern "C" [[noreturn]] void tsb_app(); // the application's reset vector: --def
// Step g_addr one page down and erase that page. The decrement lives in here, // Step g_addr one page down and erase that page. The decrement lives in here,
// before the erase's own use of it, not in the caller's loop where a following // before the erase's own use of it, not in the caller's loop where a following
// call would get it deleted (see header). // call would get it deleted (see the top of this file).
[[gnu::noinline, gnu::noclone]] void erase_below() [[gnu::noinline, gnu::noclone]] void erase_below()
{ {
g_addr -= page; g_addr -= page;
@@ -262,23 +207,23 @@ extern "C" [[noreturn]] void tsb_app(); // the application's reset vector: --def
// same reason. // same reason.
g_receiving = 0; g_receiving = 0;
// Activation: 3x'@', each inside the config page's timeout window (rx // Activation: activation_knocks '@', each inside the config page's timeout
// floors it so a corrupt page cannot lock the loader out); anything else - // window (rx floors it so a corrupt page cannot lock the loader out);
// including silence - hands over. // anything else - including silence - hands over.
g_window = avr::flash_load(flash_ptr(app_end + 2)); g_window = avr::flash_load(flash_ptr(app_end + timeout_at));
for (std::uint8_t k = 3; k; --k) { for (std::uint8_t k = activation_knocks; k; --k) {
if (rx() != knock) { if (rx() != knock) {
appjump(); appjump();
} }
} }
g_window = comm_window; g_window = comm_window;
// Password gate (config page from app_end+3, 0xff-terminated; a blank // Password gate (config page from password_at, 0xff-terminated; a blank
// page is no password). A wrong byte blanks the comparison and drains the // 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 // 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; // emergency erase behind two confirms. On pass the info block goes out;
// the emergency path skips it and drops into the command loop. // the emergency path skips it and drops into the command loop.
g_addr = app_end + 3; g_addr = app_end + password_at;
std::uint8_t mask = 0xff; std::uint8_t mask = 0xff;
for (;;) { for (;;) {
std::uint8_t expected = avr::flash_load(flash_ptr(g_addr)) & mask; std::uint8_t expected = avr::flash_load(flash_ptr(g_addr)) & mask;
@@ -314,7 +259,7 @@ extern "C" [[noreturn]] void tsb_app(); // the application's reset vector: --def
tx(confirm); // Mainloop ready tx(confirm); // Mainloop ready
g_addr = 0; g_addr = 0;
switch (rx()) { switch (rx()) {
case 'f': // read application flash, one page per host '!' case command::read_flash: // one page per host '!'
for (;;) { for (;;) {
if (rx() != confirm) { if (rx() != confirm) {
break; break;
@@ -326,13 +271,13 @@ extern "C" [[noreturn]] void tsb_app(); // the application's reset vector: --def
} }
} }
break; break;
case 'F': // erase the application, then take pages behind '?' case command::write_flash: // erase the application, then take pages behind '?'
erase_application(); // leaves g_addr = 0, the write start erase_application(); // leaves g_addr = 0, the write start
while (rcnf() == confirm) { while (rcnf() == confirm) {
store_flash(); store_flash();
} }
break; break;
case 'e': // read EEPROM, one page per host '!', until the host stops case command::read_eeprom: // one page per host '!', until the host stops
for (;;) { for (;;) {
if (rx() != confirm) { if (rx() != confirm) {
break; break;
@@ -343,7 +288,7 @@ extern "C" [[noreturn]] void tsb_app(); // the application's reset vector: --def
} while (--g_cnt); } while (--g_cnt);
} }
break; break;
case 'E': // take EEPROM pages behind '?' case command::write_eeprom: // pages behind '?'
while (rcnf() == confirm) { while (rcnf() == confirm) {
g_cnt = page; g_cnt = page;
do { do {
@@ -351,13 +296,13 @@ extern "C" [[noreturn]] void tsb_app(); // the application's reset vector: --def
} while (--g_cnt); } while (--g_cnt);
} }
break; break;
case 'c': // read the config page case command::read_config:
read_config: read_config:
g_addr = app_end; g_addr = app_end;
g_cnt = page; g_cnt = page;
sendf(); sendf();
break; break;
case 'C': // replace the config page, then echo it back to verify case command::write_config: // then echo it back to verify
if (rcnf() != confirm) { if (rcnf() != confirm) {
break; break;
} }