uspiflash

A generator of tiny, single-file C libraries that detect SPI flash chips and report their capabilities, built from the spiflash database, for early-boot and embedded code: Zephyr, MicroPython, the LiteX BIOS, bare-metal Cortex-M and RISC-V (down to WCH's CH32V003), and Linux spidev.

Every byte the library puts on a device is measured, across a wide range of GCC, LLVM and SDCC versions.

Size

For SPI NOR flash (--type nor, the default), compiled for cortex-m0 with Debian clang version 19.1.7 (3+b1) at -Os, the read level costs 11,275 bytes of flash and full 54,547 bytes, code and tables together, with no static RAM. Every configuration (all chip types, and NAND), every target, and how they are measured: sizes/README.md.

Output

A generated file's usf_print() and usf_print_json() print exactly what spiflash id and spiflash id --json print, byte for byte, less what the file was generated without: the from: line and per-opcode sources without sources, conflicts without conflicts, the datasheet line without datasheet, the JSON datasheets, records and records' at without datasheets, records and provenance, the sfdp: lines without sfdp_summary, and the JSON sfdp without sfdp_dumps. The tests check this against spiflash 0.0.post92 (uspiflash.VERIFIED_SPIFLASH). --with sfdp adds usf_sfdp_read(), which reads and decodes the chip's own SFDP tables (JESD216).

SPI NOR is the primary target: uspiflash generate keeps only SPI NOR chips unless told otherwise (--type nor --type nand keeps every chip, NAND included; --type nand only NAND).

On 16-bit targets (AVR, msp430, the 8051) the levels id to full fit, if the part has the flash (full is about 59 KB of code and tables); the datasheet, datasheets, records, provenance and jep106 extras do not, as their tables pass the 64 KiB a 16-bit pointer can address. On AVR, define USF_ROM as a flash address space (avr-gcc's __flash) to keep the tables in flash rather than copied to RAM.

Install

pip install uspiflash          # or: uv tool install uspiflash

Or, as a Debian package, from the signed apt repository at https://mith.ro/uspiflash/. There is one per suite (bookworm, trixie, forky and sid), and the package is Architecture: all, so it installs on any architecture. python3-uspiflash depends on python3-spiflash, which is not in this repository, so add spiflash's own apt repository first, then uspiflash's. Put your suite's name in place of trixie below (Raspberry Pi OS uses Debian's codenames):

sudo install -d -m0755 /etc/apt/keyrings
curl -fsSL https://mith.ro/spiflash/spiflash.gpg | sudo tee /etc/apt/keyrings/spiflash.gpg > /dev/null
echo "deb [signed-by=/etc/apt/keyrings/spiflash.gpg] https://mith.ro/spiflash/trixie/ ./" \
  | sudo tee /etc/apt/sources.list.d/spiflash.list

spiflash's repository's signing key is B528 6C61 A99A 9E6A 5B8A 8E5B 6B2D 7683 DE01 081D (gpg --show-keys /etc/apt/keyrings/spiflash.gpg shows it).

curl -fsSL https://mith.ro/uspiflash/uspiflash.gpg | sudo tee /etc/apt/keyrings/uspiflash.gpg > /dev/null
echo "deb [signed-by=/etc/apt/keyrings/uspiflash.gpg] https://mith.ro/uspiflash/trixie/ ./" \
  | sudo tee /etc/apt/sources.list.d/uspiflash.list

uspiflash's repository's signing key is 2E19 5D58 706D 44E8 5704 1566 04FA D17C 2A3B 8344 (gpg --show-keys /etc/apt/keyrings/uspiflash.gpg shows it).

sudo apt update
sudo apt install python3-uspiflash      # provides the uspiflash command

Work in progress: the design is in docs/superpowers/specs/.

License

Apache-2.0; see LICENSE.