Files
alkane-os/docs/afw-format.md
T

7.0 KiB

.afw OS install bundle format

Status: schema 2. Released only by alkane-os. One .afw is valid for exactly one board family.

An .afw is a full OS install bundle: kernel, device tree, rootfs, the bootable image(s), the partition plan, the boot switch, the preflight rules and the network recovery path. It is not an application package.

Container

A strict POSIX ustar archive. No compression, no directory entries, no leading ./, no GNU long-name or pax members, and no links. Members are, in this exact order:

  1. manifest.json
  2. manifest.json.sig (only for an Ed25519-signed bundle)
  3. Each payload member named by manifest.images[].file, in manifest order.

Every member is a regular file. The manifest is at most 64 KiB. The verifier reads the tar itself: it checks the header checksum, rejects path traversal, absolute paths, duplicate names, non-regular members and truncated archives, and requires the two-block end marker. It verifies the manifest and every payload hash before any consumer may write to a board.

Manifest

Required members:

Field Meaning
schema 2
format afw
board One board family, for example cv1835
arch arm64 or armv7; must match the board profile
version Release version
build_date UTC ISO-8601
sdk_revision 40-character SDK git revision
os_revision 40-character alkane-os git revision
payload_type os
bootloader_policy include or preserve
signature Signature object, see below
partitions Partition plan, see below
images Payload images, see below
boot_switch How the preserved or written boot path selects the new OS
preflight Required commands, forbidden devices, free space, source OS list
recovery Network recovery command, held partition, golden copy location
marker String served by the installed OS, used by afw verify-live
kernel_version Kernel release the installed OS must report

notes is optional. Unknown keys are ignored by this schema so a future field does not break old readers.

Images

Each image entry has name, file, role, format, size, sha256, partition (or null) and install (bool). Roles are kernel, dtb, rootfs, bootloader, boot and component. Formats are fit, arm64-image, fdt, cpio-gzip, uimage and raw.

An image with install: true must name a partition and is the only kind the installer writes. Component images (kernel, dtb, rootfs) are carried for inspection and for boards whose installer composes them; for CV1835 they are also the inputs of the p1 FIT.

bootloader_policy: preserve means no image with role bootloader may be present. include means exactly one must be present. The toolkit refuses a bundle whose policy does not match its board module.

Partitions

Each partition entry has name, device, offset, size, secure, boot_critical, write_order and image (or null). Secure partitions and boot0 are declared so preflight can refuse them, never as write targets. write_order is 0 for a region that is not written and a positive order for an install target.

For CV1835 the plan is:

Region Device Size Secure Written
p1 /dev/mmcblk0p1 16 MiB no yes, order 1
p3 /dev/mmcblk0p3 32 MiB yes no
boot0 /dev/mmcblk0boot0 4 MiB yes no
boot1 /dev/mmcblk0boot1 4 MiB yes no

The p1 payload is the 16 MiB padded FIT. A FIT larger than the partition is a build failure. A wrong or missing FIT is a boot failure, not a write failure, as long as the held p1 backup is present.

Signatures

signature is always an object:

{"type": "unsigned", "member": null, "public_key_hex": null}

A signed bundle uses:

{"type": "ed25519", "member": "manifest.json.sig",
 "public_key_hex": "<64 hex characters>"}

manifest.json.sig is the 64-byte raw Ed25519 signature over the exact manifest.json bytes, and is the second member. The key is a 32-byte raw seed or 64 hex characters in a file named by the release environment; no key value is stored in this repository. Adding a signature changes only the member set, not the schema, so unsigned bundles remain readable.

Site use requires a signed bundle. The bench allows an unsigned bundle only with --allow-unsigned, which prints a warning and the payload SHA-256.

Build and check

The producer stages the manifest and payload, pads the CV p1 FIT to exactly 16 MiB, and packs the members. The checker is the release gate. Both are offline and use only the Python standard library, except that Ed25519 signing and verification use the cryptography package.

alkane-os/ci/make-afw.sh \
  --board cv1835 --version 0.1.0 \
  --input alkane-sdk/build/out/cv1835 \
  --sdk-revision "$(git -C alkane-sdk rev-parse HEAD)" \
  --os-revision "$(git -C alkane-os rev-parse HEAD)" \
  --output alkane-os/dist --allow-unsigned

python3 alkane-os/ci/check-afw.py \
  alkane-os/dist/alkane-os-0.1.0-cv1835-arm64.afw \
  --allow-unsigned --expect-board cv1835

The checker fails on a wrong board or arch, a missing image, an image larger than its partition, a bootloader member under preserve, a hash or size mismatch, a path-traversal member, a truncated tar, a signed bundle without a valid signature, or an unsigned bundle without the explicit flag.

Install rule

The toolkit verifies the whole bundle before opening a transport. It then preflights the board, holds the current p1 over the network, writes only the declared install partition, reads the whole partition back, and compares the hash before it reboots. No install step needs a serial console, an SD card, a U-Boot prompt, JTAG or a button.

AM335x (legacy-uImage, non-FIT)

am335x is the BeagleBone-class AM335x slice. The board already runs our non-RSA U-Boot, so the bundle preserves mtd0-5 (SPL, U-Boot, bootenv) and writes only:

Region Device Size Image Order
mtd8 /dev/mtd8 20 MiB type-3 ramdisk uImage 1
mtd6 /dev/mtd6 128 KiB dtb (FDT) 2
mtd7 /dev/mtd7 5 MiB type-2 kernel uImage 3

mtd0-5 are declared secure, image-free and outside the write order. Every partition offset is taken from the 12-entry map, including the unmapped 512 KiB hole at 0x780000-0x800000; mtd7 ends at 0x780000 and mtd8 starts at 0x800000, never 0x780000. The producer and both checkers refuse an offset in the hole, a write to mtd0-5, an image over its mtd ceiling, a bundle carrying an spl/u-boot member, a wrong arch, an oversize image, a truncated tar, or a traversal member. The images are legacy ARM uImages (kernel type 2, ramdisk type 3); a FIT is rejected.

alkane-os/ci/make-afw.sh \
  --board am335x --version 0.1.0 \
  --input alkane-sdk/build/out/am335x \
  --sdk-dir alkane-sdk --plan am335x-plan.json \
  --output alkane-os/dist --allow-unsigned

python3 alkane-os/ci/check-afw.py \
  alkane-os/dist/alkane-os-0.1.0-am335x-arm.afw \
  --allow-unsigned --expect-board am335x