Provision and build declared device-tree overlays - #183
Open
jetm wants to merge 3 commits into
Open
Conversation
Shipping a custom device-tree overlay previously meant forking the BSP: the CLI had no notion of one, so a .dtbo could not be compiled from the project or routed onto the boot medium. Add a declarative path. An extension declares its overlays under `device_tree_overlays`, and the runtime build compiles each one, stages it, hands off to the board's delivery hook, and fails the build if anything went undelivered. Placement is at the extension level, alongside the sibling `overlay` key, because a runtime's `packages` list is frequently a bare list of names with nowhere to hang per-overlay objects. The name is a validated basename because it is reused verbatim as the .dtbo filename and the boot-loader argument. Compilation is generated into the in-container build script rather than run in Rust: the dtc/cpp toolchain, the kernel dt-bindings, and the delivery hook all live in the SDK container. The script calls the nativesdk-avocado-dtc-overlay wrapper per overlay, writes an overlays.manifest.json, runs the single fixed-path per-BSP hook ($OECORE_TARGET_SYSROOT/usr/libexec/avocado/device-tree-overlay-deliver), and passes the hook-emitted stone fragment through `stone bundle --overlay`. Two failure modes are hard errors, not silent successes: overlays declared with no hook installed, and overlays staged but left unclaimed by the hook. Fold the declarations and each .dtso's content hash into the runtime-build input hash. Overlays are compiled at runtime-build time, so without this an added or edited overlay would leave the stamp valid and ship the previous bundle unchanged. Signed-off-by: Javier Tia <javier@peridio.com>
When an extension declared device_tree_overlays, the CLI compiled and delivered the overlays at runtime-build time but never installed the tools that step needs: the nativesdk-avocado-dtc-overlay SDK wrapper and the per-BSP avocado-dtc-overlay-deliver hook had to be staged into the SDK by hand, so a clean install could not build a declared overlay. The target-sysroot install that would carry the hook was also gated on an active compile section, which a no-#include overlay does not require, so a pure path/phandle overlay got no target-sysroot at all. Scan the active extension set (not a single runtime's enabled list, since the SDK install spans every runtime) for device_tree_overlays and, when any declares them, add nativesdk-avocado-dtc-overlay to the SDK packages and avocado-dtc-overlay-deliver to the target-sysroot, widening the target-sysroot trigger to fire on a declaration as well as a compile section. nativesdk-dtc is pulled by the wrapper's RDEPENDS and stone is a baseline SDK package, so neither is listed. A BSP that ships no hook package now fails at install time rather than at the build-time backstop. Signed-off-by: Javier Tia <javier@peridio.com>
jetm
force-pushed
the
eng-2134-device-tree-overlays
branch
from
August 12, 2026 21:35
5d58ff7 to
208191e
Compare
A BSP's stone-<arch>.json references boot artifacts this build does not produce - u-boot.bin and bootfiles/ on Raspberry Pi - while the only input directory passed to stone is the runtime dir, which holds just what the build made: rootfs, kernel, initramfs, var. Anything else the manifest names fails resolution with "File 'u-boot.bin' not found in any input directory for FAT image", and the runtime build dies at finalize. Add the SDK's own stone dir as a second input. That is where a BSP recipe would stage artifacts it wants a manifest to be able to name, and it is already where the manifest itself is read from, so the two stay together. This is the consumer half of a two-part change and does nothing on its own: meta-avocado's avocado-sdk-target currently installs only the stone JSON there, so no new file resolves from the added directory yet. It is still the right half to land separately - stone resolves first-match-wins across -i directories, so an extra input carrying nothing cannot change what any current build resolves - but the finalize failure it targets stays until the BSP recipe stages u-boot.bin and bootfiles/ into that directory. The comment says so rather than leaving the next reader to conclude the gap is closed. Signed-off-by: Javier Tia <floss@jetm.me>
Contributor
Author
|
Producer half is up: avocado-linux/meta-avocado#274 stages Either half alone is inert and neither regresses a current build (stone resolves first-match-wins across |
jetm
marked this pull request as ready for review
August 15, 2026 19:35
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
The CLI had no support for the device-tree-overlay feature: it neither provisioned the SDK overlay tooling nor compiled and delivered overlays during a runtime build.
Solution
When an extension declares
device_tree_overlays, provision the SDK wrapper and per-BSP delivery hook duringsdk install, then compile and deliver each declared overlay duringavocado build.Key changes
sdk/install: provision device-tree-overlay tooling (nativesdk-avocado-dtc-overlayplus the delivery-hook package) from extension declarationsruntime/build: compile and deliver declared device-tree overlays into the OS bundleruntime/build: search the SDK stone dir for BSP boot artifacts - see the note below, this commit's motivation changed after it was writtenReviewer notes
Top of the device-tree-overlay stack (ENG-2134). Both dependencies are now merged - stone#28 and meta-avocado#245 - so this no longer waits on anything to be reviewable.
Why
aa2d49ais in this PRIt was written for a Raspberry Pi failure,
File 'u-boot.bin' not found in any input directory for FAT image, on the theory that nothing staged u-boot into stone's input dir. That theory was wrong. A real rpi5 build showedavocado-img-bootfilesalready shipsu-boot.binandbootfiles/*, reachable throughavocado-runtime's RDEPENDS; the project that failed simply had not declaredavocado-runtime. meta-avocado#274 chased the same wrong premise from the BSP side and is closed for that reason.The commit stays because a different consumer turned up and this time the gap is real. On Tegra the base DTB genuinely is absent from the runtime input dir - the
.dtbfiles underruntimes/<rt>/devicetree/are AGX Orin parts, and onlytegraflash-bspcarries the Orin Nano one - and the overlay delivery hook has to read it to merge overlays into it. meta-avocado#293 stages that BSP into the SDK stone dir; this commit is the half that reads it. Theruntime/build.rscomment describing itself as "the consumer half of a two-part change" is accurate, and #293 is the other half.Merge order is not a constraint: without #293 the directory holds nothing new, so the search is inert rather than broken.
Verification
.dtbo, hook delivers and claims it,os-bundle.aosfinalizes. Re-run green after the Jetson work as a regression gate./proc/device-tree/hello-overlay/avocado,markerreads the declared value on the running board; with the declaration removed and nothing else changed, the node is absent. Requires meta-avocado#292 and #293.The Jetson result is worth one line of emphasis for a reviewer of this PR specifically: every build-path assertion this code emits passed for two full rounds while the board booted with no overlay applied. The unclaimed-overlay guard here is what makes a missing delivery loud; it cannot detect a delivery that lands in the wrong place. Only reading the running kernel's device tree did.
Known gap, not introduced here
avocado runtime provisioncannot flash a Jetson from its container. The production path passes no--privileged- the occurrence inprovision.rsis inside#[cfg(test)]- so libusb fails atcould not retrieve chip ID. With--privilegedadded by hand, signing and RCM boot report success but the target never boots the pushed initrd or exports its LUN. The identical sequence run host-side succeeds every time, and every Jetson flash behind the verification above was host-side.This is pre-existing on
mainand out of scope here, but it means the documented CLI provisioning path is not the path the Jetson result was obtained through. Tracked separately.