Add a device-tree overlays developer reference; retire the field note - #481
Open
jetm wants to merge 12 commits into
Open
Add a device-tree overlays developer reference; retire the field note#481jetm wants to merge 12 commits into
jetm wants to merge 12 commits into
Conversation
Document the ENG-2134 device-tree-overlay feature as a draft field note: an extension declares an overlay under device_tree_overlays, and avocado build compiles it in the SDK and delivers the .dtbo into the OS bundle. Verified on raspberrypi5, where the FAT config.txt boot path lets stone write the overlay into boot.img and finalize os-bundle.aos end-to-end. qemuarm64 compiles and delivers the overlay but cannot finalize the bundle (no FAT boot medium; tracked in KOS-68), so the note stays draft until the clean-SDK image toolchain auto-provisions and the QEMU path closes. Signed-off-by: Javier Tia <javier@peridio.com>
…visioning The draft pinned cli=1.0.0-rc.1, but that released version does not carry the device-tree-overlay support: the note was verified with a from-source eng-2134 CLI that merely reports 1.0.0-rc.1. A reader on the real 1.0.0-rc.1 would fail, and the example omitted the sdk.packages the runtime image needs to finalize on a clean SDK, so a copied example would stop short of the bundle. Record the release and publish chain that gates reader reproduction in an internal repro_blockers field, correct the tested_against CLI provenance, and add the erofs/btrfs/zstd/stone sdk.packages block to the reproduce steps so a copied example finalizes until KOS-68 auto-provisions them. Signed-off-by: Javier Tia <javier@peridio.com>
The note claimed the feature at bundle level only: overlays compiled, were delivered, and the bundle finalized. Whether an overlay actually took effect on a running board was never shown, which is the claim a reader cares about. Jetson supplies it, and supplies the more interesting half of the argument. The platform has nowhere to put a loose .dtbo - no DTBO partition, an ESP carrying only the bootloader, and flash vars that the initrd-flash path never reads - so the overlay is merged into the device tree at build time instead. The project config does not change: same declaration, same .dtso, with the per-BSP hook absorbing the difference. That is a sharper illustration of the note's thesis than a second FAT-booting board would have been, because it shows the declaration surviving a mechanism swap. State the reflash consequence next to it. On the Pi an overlay change is an ordinary image update; on Jetson it changes the device tree and takes a reflash. A reader planning around this needs that before they plan, not after. Record the container-provisioning gap in repro_blockers as well. `avocado runtime provision` cannot flash a Jetson from its container today, so a reader-facing flash instruction cannot assume it works. Also mark what has cleared since the first draft - stone#28 and meta-avocado#245 are merged - so the remaining list is what actually still gates publication. Still draft: avocado-cli#183 and the two Jetson PRs are open, and the on-device MP4 is unrecorded. Signed-off-by: Javier Tia <javier@peridio.com>
nicksinas
reviewed
Aug 17, 2026
nicksinas
reviewed
Aug 17, 2026
nicksinas
reviewed
Aug 17, 2026
The field note argues why declarative overlays matter and reports what was verified; it is not something a reader can follow to ship one. Several things a user needs are missing from it entirely: the `params` key, the name-uniqueness and basename rules, what happens on a target with no delivery hook, and the `avocado-runtime` package a runtime must declare - whose omission produces a `u-boot.bin not found` failure at bundling that reads like a broken BSP and already cost two weeks of chasing a product bug that was a project-config omission. Put those in a guide alongside custom-kernel, sourced from the CLI and BSP code rather than from the note, and give verification its own section: a green build path is not evidence an overlay applied, which is how a Jetson booted with nothing applied through two full build rounds. The section asks for a paired positive/negative reading of /proc/device-tree per platform, because the delivery mechanism differs per board and a pass on one proves nothing about another. Ship it `draft: true` with a Release status table naming every PR and publish step that gates it, so the undraft condition is tracked on the page instead of in an issue thread. Drafts are dropped from the production build and a sidebar item naming a dropped doc fails that build, so the sidebar entry is deliberately withheld and recorded as an item in the same table. Signed-off-by: Javier Tia <javier@peridio.com>
Its mechanics are now in the developer reference, sourced from the CLI and BSP code rather than from the note, and they differ where the note was wrong: the example YAML omitted `avocado-runtime`, which is the omission that produces the `u-boot.bin not found` bundling failure a reader would then have to diagnose. Leaving a second, staler copy in place decides that outcome by whichever page the reader lands on first. The argument the note carried - that overlays are the interfaces-and-peripherals layer a board change actually costs you in - is not lost by deleting it. That framing has its own homes in ENG-2264 and ENG-2263, where it is the subject rather than a preamble to a mechanism walkthrough. Signed-off-by: Javier Tia <javier@peridio.com>
The table listed #293 as a separate gate and #183 as draft. #293 is closed - its Tegra BSP staging is the first commit of #292 now - and #183 left draft once the Jetson work supplied the motivation its last unexplained commit was missing. A gate list that names a closed PR teaches a reader to distrust the rest of it. Adding #276 is the substantive part rather than bookkeeping. The verification section asks the reader to read /proc/device-tree on the booted board, and a stock image sets root's password field to `*`, so the board boots to a prompt that cannot be satisfied and the check cannot be run at all. The page was describing a procedure its own supported images block. The dev-login kas overlays are what unblock it, so they are a dependency of this page in the same way the delivery hooks are. Say plainly that this makes the verified image differ from the shipped one. Neither overlay touches the device tree, so the result still holds, but a reader who notices the gap deserves the reasoning rather than having to reconstruct whether it invalidates the check. Signed-off-by: Javier Tia <javier@peridio.com>
…rest WIP The page was written Pi-first because that is the order the work happened in, not because the Pi is the target a reader should follow. Jetson is the only one confirmed on hardware - paired positive and negative against a running kernel - while the Pi has never been booted with a declared overlay and qemuarm64 delivers a blob that its u-boot cannot apply. A reader picking the first worked example on the page was being pointed at the least finished path. So the walkthrough is Jetson throughout, and the support table leads with a status column rather than burying readiness in prose. The two unfinished targets move below a heading that says what they are, each stating what it is waiting on. Say explicitly that the Pi's evidence is a green build and nothing else. That reads like hedging until you notice it is the exact shape of the Jetson bug: two full rounds of passing build markers while the board applied nothing. A build that goes green is the failure mode here, not the reassurance, so a page that implies otherwise for an unbooted target is teaching the wrong lesson. Also drop the claim that `params` is simply Raspberry-Pi-only. That was true and useless - the hook that would honor it is itself unverified, so the key has no confirmed consumer on any board. Signed-off-by: Javier Tia <javier@peridio.com>
…oling The page told readers to layer a kas fragment to reach a login prompt. kas is the maintainer path; a developer reference has no business sending someone to BitBake to run one of its own verification steps. That instruction was mine, and it came from a fixture I had hand-minimized down past the extensions a real project carries - so I hit a locked board, reached for the maintainer tool I had, and wrote the workaround down as if it were the product's answer. The consumer path already existed, in two halves that had never been documented together. `avocado-ext-sshd-dev` configures sshd to read /var/lib/ssh/authorized_keys, and runtime `var_files` puts a project file on the var partition. Either alone is useless: the extension listens with no credential that works, and the key has nothing reading it. Say why the pairing matters rather than just listing it. A board missing only the key still boots, still runs sshd, still accepts connections, and refuses every credential - indistinguishable from the feature being broken. That is the failure this page exists to teach people to distrust, so it earns the explanation. Item 8 records what is still unproven. The key is confirmed landing at the right path at build time; sshd accepting it has not been observed on hardware, and StrictModes could still reject it on mode or ownership. Dropping #276 as a gate follows from the same finding - the kas overlays it adds are no longer on this page's critical path, though they remain useful on their own. Signed-off-by: Javier Tia <javier@peridio.com>
…rofile The previous revision sent readers to stage an SSH public key through `var_files` to get a shell. That works, but it is not the answer the product gives: `avocado init` generates a `permissions` profile with an empty root password, and that alone yields a console login. A reader following the old text did extra work to reach a worse place than the default template already puts them. I reached for the key because I read the wrong file. `rootfs/image.rs` copies the sysroot to a work tree and applies the profile to the copy, so the sysroot's `root:*:` is the input to that step and says nothing about the result. Extracting the actual erofs shows `root::`, and a Jetson Orin Nano now boots to a root prompt on the console with no password, which is the evidence that should have been gathered before recommending anything. Keep the key as the network path rather than the primary one, and name the BSP extension alongside it. Dropping that extension to slim a project takes `kernel-module-realtek` with it, and the board then boots with no ethernet interface at all - confirmed on the same board, where `/sys/class/net` held only `lo` and `sit0` and dmesg never mentioned the NIC. Nothing about that symptom points back at a missing extension, so the warning is worth its line. Signed-off-by: Javier Tia <javier@peridio.com>
The page hedged the key half of network access as "verified only as far as placement", and listed confirming it as a release blocker. Both are now false: the key authenticates. Leaving the hedge in place would understate what a reader can rely on, and the blocker list is what decides when this page drops `draft: true`, so a stale entry there delays publication for nothing. The evidence is stated as `BatchMode=yes` rather than as a bare successful login. BatchMode refuses password and keyboard-interactive auth, so it distinguishes the key being accepted from a password prompt succeeding behind it - and this project has empty-password root enabled on the same image, which is exactly the confound a plain `ssh` result would leave open. Host-key churn is called out because it is the next thing a reader hits and it does not present as what it is: keys are generated on first boot rather than shipped, so every reflash makes the recorded entry stale and SSH reports that as a possible man-in-the-middle rather than as a new board. Signed-off-by: Javier Tia <javier@peridio.com>
jetm
force-pushed
the
developer-reference/device-tree-overlays
branch
from
August 17, 2026 21:24
6bbedbd to
7ff21c2
Compare
The page pointed at a tracker ID for the SDK image-build toolchain gap, and listed resolving that ticket as a release blocker. The ID was wrong - it resolved to nothing in the workspace - but repointing it at a real one was still the wrong fix. A reader of a public docs site has no tracker access, so any ID is a dead end for them, and it decays independently of the page. Both references now name the condition: the SDK does not ship the toolchain, and the blocker is shipping it. That is checkable by anyone who can run the build, which is the audience the page actually has.
jetm
force-pushed
the
developer-reference/device-tree-overlays
branch
from
August 17, 2026 21:38
7ff21c2 to
99874f2
Compare
Two review points, one change. The page carried step-by-step guidance for Raspberry Pi and qemuarm64 whose delivery paths have never been confirmed on a running kernel, and it carried a release-status section tracking pull requests, publication blockers and per-target evidence. Marking the untested targets WIP was not sufficient. The page's own argument is that a green build proves nothing about a board, so publishing a mechanism nobody has watched work contradicts the standard the page sets three sections earlier - and a reader who skips the label follows instructions no one has run. Those sections are removed rather than reworded; a board gets documented once it has been verified the way Jetson was. The release-status section was project tracking in a customer-facing page. Which PRs are open and what gates publication is real information, but its audience is the team, so it moves to the pull request instead. The support matrix keeps only rows that are settled: Jetson verified on hardware, x86 not applicable, everything else not documented yet. `params` is described as accepted-but-unconsumed, which is what it is on the one target this page now covers. Signed-off-by: Javier Tia <javier@peridio.com>
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
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
There was no page telling a reader how to ship a custom device-tree overlay. The
closest thing was a field note, and a note is the wrong container for this: what
a reader needs is the config surface, the failure modes, and a way to confirm the
overlay applied. That is reference material, and it goes stale in a dated piece.
The note was also wrong in the one place it mattered most. Its example
avocado.yamlomittedavocado-runtime, which is exactly the omission thatproduces
File 'u-boot.bin' not found in any input directory for FAT imageatbundling - a failure that reads like a broken BSP and was misdiagnosed as a
two-component product gap for two weeks before being traced back to project
config.
Solution
A developer-reference guide at
/developer-reference/device-tree-overlays,written against the CLI and BSP source rather than against the note, and the
note deleted so there is only one copy.
Jetson only. The page documents the one target whose overlay path has been
confirmed by reading
/proc/device-treeon a running board. Raspberry Pi andqemuarm64 guidance was cut rather than marked WIP: the page's own argument is
that a green build proves nothing about a board, so shipping a mechanism nobody
has watched work contradicts the standard it sets three sections earlier. Each
further board gets documented once it is verified the same way.
Shipped
draft: true- the feature is not reachable from released artifacts, sofollowing the page with a released CLI and SDK fails at
avocado install.Key changes
docs-guides/device-tree-overlays.md- new,draft: true, Jetson onlyfield-notes/2026-07-21-device-tree-overlays.mdx- deletedsidebars-guides.js- a comment recording why the page is deliberately absentfrom the Advanced category
Reviewer notes
The sidebar entry is withheld on purpose. Drafts are dropped from the
production build, and a sidebar item naming a dropped doc fails that build. It
lands in the same commit that flips the draft flag. Verified both directions:
npm run buildpasses, and the page is absent frombuild/while present in dev.On-device evidence, Jetson Orin Nano dev kit (P3767-0005). Paired positive
and negative on 2026-08-15:
/proc/device-tree/hello-overlay/avocado,markerreads the declared value on the running board, and the node is absent on a build
with the declaration removed and nothing else changed. On 2026-08-17 the access
mechanisms the page recommends were confirmed on the same board - console root
login via the
permissionsprofile, andssh -o BatchMode=yes root@<board>against a key placed by
var_files(BatchMode refuses password auth, so the keyitself is what was accepted).
What gates dropping
draft: trueMoved here from the page itself - this is team tracking, and it does not belong
in front of a customer.
Pull requests
files_appendFAT primitive563d462)device_tree_overlaysconfig surface and build orchestrationfdtoverlaymerge) and the Tegra BSP staging it readsMerge order is constrained only by #28 before #245; both are merged.
Beyond the PRs
avocadolinux/sdk:2024-edgewith the overlay compileravocado installcannot resolve the overlay compiler without it2024/edgefeed carryingavocado-dtc-overlay-deliver1.0.0-rc.1does not carry the overlay work, despite a from-source build reporting the same version stringavocado runtime provisioncannot flash a Jetson from its container today, so the documented CLI path is not the path that was verifiedsidebars-guides.jsdraft: true- a sidebar entry pointing at a draft doc breaks the production buildPer-board coverage
A reference project that each board's overlay path can be tested against, and
run in CI, is the better long-term shape for extending past Jetson - it gives
something to point people at as a starting point rather than prose describing an
unverified mechanism. Tracked separately from this PR.