Expand description
Norbert — a patient SPI-NOR flasher for the Pico de Gallo USB bridge.
Norbert identifies, erases, programs, verifies, and reads back raw SPI-NOR flash chips over a Pico de Gallo v1.1 USB-to-SPI bridge. It reads a chip’s JEDEC ID and, where available, its SFDP tables to learn the real geometry (page size, address width, erase menu) before touching a single byte — falling back to a small built-in table for parts that do not self-describe. It never guesses.
Norbert ships as a thin binary over this library; these docs describe its internal modules rather than a stable public API. The pieces fit together like this:
cli— the command-line surface (global flags + subcommands). Parsing only.commands— one handler per subcommand, plus the bus-session helpers (with_bus/with_cancel) that guarantee the shared bus is always released.flash— the hardware-agnostic flashing core: RDID, SFDP probing, erase planning, page programming, verification.device— binds the flashing core to the Pico de Gallo HAL over a fixed pin map and drives the flash’s control lines.profile/sfdp/catalog— the flash geometry model, the SFDP byte parser, and the human-name + no-SFDP fallback tables.ui/voice— presentation.uiowns all terminal output and the Human/Machine (--quiet) split;voiceholds the personality text.
run only parses arguments, builds the Ui, and dispatches; personality
lives in voice, output in ui.
Modules§
- catalog 🔒
- “Norbert’s book”: human names for flash chips + the no-SFDP fallback table. Pure tables; extend freely.
- cli 🔒
- Command-line surface: global flags + subcommands. Parsing only.
- commands 🔒
- Command handlers + the bus-session helpers that guarantee bus release.
- device 🔒
- Pico de Gallo glue over a fixed pin map: binds the HAL’s SpiDevice + GPIOs to the flash core, drives the flash’s static control lines (/WP, /HOLD) high, and implements an optional CRESET-based bus hold.
- error 🔒
- The single application-level error.
flash::FlashErrorstays generic in the core; this non-generic type is what handlers return anduirenders. - flash 🔒
- Hardware-agnostic iCE40HX8K-EVB SPI-NOR flashing core.
- profile 🔒
- Flash geometry model + the pure erase planner. No I/O, no SFDP bytes.
- sfdp 🔒
- SFDP byte parsing: header, parameter headers, and the Basic Flash Parameter Table.
- ui 🔒
- Norbert’s presentation layer: the only module that writes to the terminal.
Handlers gather data and sequence these methods; personality text comes from
voice; this module owns layout and the Human/Machine decision. - voice 🔒
- Norbert’s voice — the ONLY module with personality.