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:
manifest.jsonmanifest.json.sig(only for an Ed25519-signed bundle)- 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