Skip to main content

Crate norbert

Crate norbert 

Source
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. ui owns all terminal output and the Human/Machine (--quiet) split; voice holds 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::FlashError stays generic in the core; this non-generic type is what handlers return and ui renders.
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.

Functions§

run
Parse the command line, build the Ui, and dispatch the selected subcommand, returning the process exit code.