Cleave: cleave-binman

A Crystal replacement for the parts of U-Boot's Python binman that TI K3 boards and the x86 QEMU ROM use, so BQ2 (no Python) can build the BeagleY-AI boot chain and U-Boot's qemu-x86_64 u-boot.rom.

shards build                 # bin/cleave-binman
crystal spec                 # unit specs
CLEAVE_REFERENCE=... CLEAVE_UBOOT=... crystal spec   # also compare with binman

Use in a U-Boot build

U-Boot's Makefile ends its build by running $(srctree)/tools/binman/binman build .... cleave-binman accepts that command line, so put it at that path before make:

ln -sf "$(command -v cleave-binman)" tools/binman/binman

Then build the R5 and A53 passes as listed in bsp/beagley-ai/manifest.md. U-Boot's own tools/mkimage is not needed for these images.

What it covers

binman feature	Crystal
reading the `/binman` node, `multiple-images`, `insert-template`	`src/cleave/binman.cr`
`ti-board-config` (YAML + `schema.yaml` → binary, combined headers)	`src/cleave/ti_board_config.cr`
`ti-secure`, `ti-secure-rom` (combined and plain) x509 certificates	`src/cleave/ti_x509.cr`, `src/cleave/rsa_key.cr` (libcrypto)
`fit` with embedded data, `hash` nodes (crc32, sha1, sha256), `timestamp`	`src/cleave/binman.cr`, `src/cleave/fdt.cr`
blobs: `blob`, `blob-ext`, `u-boot*`, `atf-bl31`, `tee-os`, `ti-dm`, entry args `-a NAME-path=`	`src/cleave/binman.cr`
layout: `offset`, `size`, `pad-before`, `pad-after`, `min-size`, `pad-byte`, `sort-by-offset`, `skip-at-start`, `end-at-4gb`, with binman's overlap and size errors	`src/cleave/binman.cr`
x86: `u-boot(-spl,-tpl)-with-ucode-ptr` (without microcode), `u-boot-dtb-with-ucode`, `x86-start16`, `x86-reset16`, `files` (no matches)	`src/cleave/binman.cr`
`fdtmap`, `image-header`, and `-u`: offset, size and image-pos written into U-Boot's device tree as libfdt writes them	`src/cleave/binman.cr`, `src/cleave/fdt_edit.cr`
`_binman_*` symbols written into SPL, TPL and VPL from their ELF (`__image_copy_start` as base)	`src/cleave/binman.cr`, `src/cleave/elf.cr`

These are refused with an error rather than silently mishandled: align*, overlap, extend-size, offset-unset, write-symbols, compression, FIT signing and encryption, microcode (an ELF with _dt_ucode_base_size), files entries that match files, and any other entry type.

The K3 images are unchanged by all this. Their entries carry no layout properties, so they are still concatenated in order; the R5 SPL's ELF has no __image_copy_start, so binman writes no symbols there; and FIT contents are built before symbols are written, as in binman. With -u on two local BeagleY-AI builds, tiboot3.bin, tispl.bin and u-boot.img came out byte-identical to the previous cleave-binman.

Differences from binman output

Scope of -u and symbols: only images and section/files entries are walked. binman also gives the entries inside FITs and certificates offsets, which only show in the device tree, and nothing here embeds that for K3.
Missing ELF: if an SPL's ELF cannot be found, its symbols are left as they are (binman stops with an error).
bootph: where a node gets both bootph-all and bootph-some-ram, binman's order depends on Python's set order; here bootph-all is added first.
No Python oracle for x86: the layout, fdtmap, image-header, -u and symbols follow binman's Python (U-Boot 2026.07) and the specs in spec/binman_spec.cr; booting the ROM in QEMU is the real test.
Certificates: binman gets a random serial number and the current time from openssl req. Here the serial comes from a hash of the extensions, and the time from SOURCE_DATE_EPOCH when it is set. With it set, builds are byte-for-byte reproducible. RSA PKCS #1 v1.5 signatures are deterministic.
FIT layout: property order differs (libfdt puts new properties first), and there's no trailing free space in the FDT. U-Boot reads FITs by name, so neither matters.

Checked against binman

Armbian's linux-u-boot-beagley-ai-vendor_26.8.3 holds tiboot3.bin, tispl.bin and u-boot.img built by binman from beagleboard/u-boot v2025.07-am6232-pocketbeagle2. With their payloads as inputs:

Every certificate matches field for field: name, key, algorithm and every extension. Only the serial number, validity dates and signature differ.
combined-tifs-cfg and combined-dm-cfg, compiled from board/beagle/beagley-ai/*.yaml, are byte-identical.
Run on the real u-boot.dtb's /binman node with U-Boot's Makefile arguments, tispl.bin and u-boot.img have the same images, configurations and payloads.