Ferrite

Developers

The update file (.ffw)

One file per update: the firmware image and its SPI flash parts, signed.

Ferrite's update file, .ffw (decision 335; manual UPD-20 - UPD-24): one file per update.

    python3 tools/ffw.py pack OUT.ffw --btf target/ferrite-tx.btf --parts target/parts --kind tx
    python3 tools/ffw.py check FILE.ffw [--dev-unsigned]   # the installers' checks, nothing written
    python3 tools/ffw.py manifest FILE.ffw > manifest.json  # the bytes the release key signs
    python3 tools/ffw.py add-sig FILE.ffw manifest.minisig  # put the signature in (CI)
    python3 tools/ffw.py build-id IMAGE.bin                 # the build ID a firmware image carries

The file is a zip. Its first entry, stored uncompressed, is manifest.json (format ferrite-update-1): the build ID, version, model, build kind, the SPI flash layout it needs, and every file with its size, SHA-256 and target (mcu for firmware.btf; spi with the address and the most it may take for each spi/ part). Then manifest.minisig when signed (the release key's minisign signature over the manifest's bytes), firmware.btf (the MCU image as today: another flasher can still take it out) and the spi/ parts. Every entry is stored, so any zip reader, a browser's included, opens it without inflating.

Installing (flash.py, Console): the signature and every hash are checked first; an unsigned file only with an explicit developer flag (--dev-unsigned). Then the backup as today, the MCU flashed, then the SPI parts over the link's raw write (LINK-60). A part aimed at calibration (0x00F000-0x00FFFF), the update area (0x300000 up), the layout header or the migration mark, or outside the layout 3 region parts may use, is refused whatever the manifest says (UPD-24).

SPI parts

SPI parts (decision 335, UPD-20 – UPD-23): data the firmware keeps on the SPI flash instead of its own, installed from the .ffw update file with every update (the text pack, the terminal's page templates, the boot logo, predictive text's words).

Each part starts with a 32-byte header (little-endian):

magic [4] | format u16 (1) | reserved u16 | build [16] (the build ID, SELF-5, NUL-padded) | len u32 (the body's
bytes) | crc u32 (CRC-32 of the body, zlib's)

then its body. The firmware uses a part only when the header is its kind's, the build ID is its own ([crate::BUILD]) and the CRC holds ([mount], once at power-on); otherwise every user of it falls back (a short built-in message, the plain command line, the wordmark without its logo).

Who reads the chip: the firmware sets [set_reader] once its store is made (reads straight from the W25Q, a program or erase suspended meanwhile); the simulator sets one over the part files it was given. With no reader, a host build (tests, the simulators by default) uses the parts built into it, so goldens keep the full text.

The parts this firmware has

Magic File SPI flash What
FTXT text-en.bin 0x090000-0x09FFFF (64 KB) The English text pack: layout 3's text region (64 KB at 0x090000).
FLGO logo.bin 0x240000-0x247FFF (32 KB) The boot logo's two masks: the first 32 KB of layout 3's boot screens region.
FVTP term-vt.bin 0x248000-0x24FFFF (32 KB) The terminal's page templates (TERM-47): the next 32 KB of the boot screens region.
FDIC words-en.bin 0x0B0000-0x0BFFFF (64 KB) Predictive text's words (decision 345): layout 3's dictionary region (64 KB at 0x0B0000).

The SPI flash map shows where the regions sit.

Made from ferrite/tools/ffw.py, ferrite/crates/ferrite-core/src/part.rs, ferrite/crates/ferrite-core/src/layout.rs by docs/tools/mkdev.py.