Validate BSP Image

Status: the DUT-access contract is stable; the rest of the validation procedure is a skeleton.

Purpose

Confirm that a freshly customized BSP landed correctly — both as a static artifact on disk and as a running system on the target — without re-promoting or re-flashing. Forms the validation tail of Deploy in the Setup → Customize → Build → Deploy pipeline (see

../../context/bsp-customization-workflow.md

for the pipeline view) and is independently re-runnable.

Prerequisites

Active target-platform profile with
```
bsp_image:
```
resolved (run
```
/jetson-init-image
```
first).
For static-only scope: nothing further; the skill reads
```
<bsp_image.root_path>
```
directly.
For on-target scope:
- ```
/jetson-flash-image
```
  already pushed the staged BSP to the DUT.
- ```
dut_access:
```
  block authored in the active profile (or filled interactively at runtime — see
  ## DUT access
  ).
- Host tooling per transport:
```
ssh
```
  +
```
sshpass
```
  for SSH; Python 3.6+ with
```
pyserial
```
  for UART.
- Required env vars resolvable on the host when
```
auth=password
```
  or
```
sudo.method=password
```
  (
```
password_env
```
  /
```
sudo.password_env
```
  name the env var; never inline the secret in YAML).

When to invoke

After
```
jetson-flash-image
```
has put the BSP onto a target.
The user explicitly asks to validate, test, or run smoke / regression checks on a flashed device.
As a CI gate before declaring a customization batch shippable.

Instructions

The procedure below is a skeleton.

Read the active target per the prerequisite contract.
Choose validation scope — static (against
```
bsp_image
```
on disk, no DUT needed) and/or on-target (DUT must be booted from the just-flashed image).
Static checks (if in scope):
- Required artifacts present at expected paths in
```
<bsp_image.root_path>/Linux_for_Tegra/
```
  .
- DTB / module checksum or signature verification.
- Partition-layout sanity vs. the per-board
```
.conf
```
  's XML.
- Cross-check overlay-staged outputs against
```
bsp_image
```
  (they should be identical post-promotion).
- Initramfs ↔ kernel + rootfs module coherence. Extract
```
<bsp_image>/Linux_for_Tegra/bootloader/l4t_initrd.img
```
  and
```
<bsp_image>/Linux_for_Tegra/rootfs/boot/initrd
```
  ; verify three invariants against the promoted
```
bsp_image
```
  state: (a)
```
<bsp_image>/Linux_for_Tegra/kernel/Image
```
  matches
```
<bsp_image>/Linux_for_Tegra/rootfs/boot/Image
```
  byte-for- byte — drift here means the "Mirror kernel Image into rootfs" step was skipped and any subsequent initramfs refresh built against the previous kernel. (b) for each module path the two initrd images ship, the bytes / md5 match the file under
```
<bsp_image>/Linux_for_Tegra/rootfs/lib/modules/<ver>/
```
  — any drift means modules will be shadowed at early boot. (c) the vermagic stamped on every initramfs
```
*.ko
```
  matches the
```
UTS_RELEASE
```
  reachable from
```
<bsp_image>/Linux_for_Tegra/kernel/Image
```
  (e.g. parse the
```
Linux version …
```
  string with
```
strings
```
  ) — a vermagic skew means the kernel
```
Image
```
  was refreshed without rerunning
```
l4t_update_initrd.sh
```
  , and modules will fail to load with "disagrees about version of symbol …". All three failure modes are closed by
```
/jetson-promote-image
```
  's gate on either
```
kernel/Image
```
  or
```
rootfs/lib/modules/
```
  plus the kernel-Image mirror; surface drift here and route the user back to a clean promote. See
  ../jetson-promote-image/SKILL.md
  .
On-target checks (if in scope):
- Connect to the DUT per the
  ## DUT access
  section below — resolve transport (ssh / uart), credentials, and sudo method from the active profile's
```
dut_access:
```
  block (with interactive fallback when fields are missing / marked
```
prompt
```
  ), then run the connection probe and refuse if it fails.
- Confirm boot reached userspace.
- Run the selected test suite (smoke, regression, focused per-customization, ad-hoc).
- Loaded-module srcversion drift. For modules a customization is known to have rebuilt, compare
```
cat /sys/module/<name>/srcversion
```
  on the DUT against the
```
modinfo /lib/modules/$(uname -r)/.../<name>.ko | awk '/srcversion/ {print $2}'
```
  reading. A mismatch means the kernel is running an older copy than the rootfs ships — almost always a stale initramfs (the bootloader-side initrd shipped a pre-customize module, it loaded first, and the rootfs copy cannot replace a live module). Recommend re-running
```
/jetson-promote-image
```
  and re-flashing. Note: some modules don't emit
```
srcversion
```
  ; fall back to an md5 check against the binary the kernel loaded by extracting the region under
```
/sys/module/<name>/sections/
```
  or by comparing behaviorally (printk / sysfs nodes / DT properties the new version is known to expose).
- Running kernel vs. rootfs kernel
  Image
  . Compare
```
cat /proc/version
```
  (or
```
uname -v
```
  ) on the DUT against the
```
Linux version …
```
  string extracted from
```
/boot/Image
```
  (
```
strings /boot/Image | grep -m1 'Linux version'
```
  ). A mismatch — usually the build timestamp /
```
LOCALVERSION
```
  — means the bootloader is running an older kernel
```
Image
```
  than the rootfs holds, almost certainly because a fresh
```
Image
```
  was promoted but the initramfs /
```
extlinux.conf
```
  / QSPI boot partition wasn't refreshed. Modules in the rootfs will then have a different vermagic and any subsequent
```
modprobe
```
  of a built-against-the-new-kernel
```
.ko
```
  will fail. Recommend
```
/jetson-promote-image
```
  and re-flash.
- Userspace dmesg readability. Ubuntu 22.04 sets
```
kernel.dmesg_restrict=1
```
  ; non-root
```
dmesg
```
  reads return "Operation not permitted" and silently zero hits. Every
```
dmesg
```
  -based check must run with
```
sudo
```
  (or temporarily lower the restriction via
```
sudo sysctl kernel.dmesg_restrict=0
```
  ). Surfacing this in the validate layer keeps printk-based customization checks honest.
- Collect results, logs, artifacts.
Summary: per-check pass/fail, overall verdict, where logs and artifacts landed.

DUT access

The on-target leg needs a way to reach the just-flashed DUT. Two transports are supported as full peers:

ssh

(primary) and

uart

(fallback for DUTs with no network).

The contract is locked in but lives in

references/dut-access.md

to keep this SKILL.md under the agent-routing budget. That reference covers:

The
```
dut_access:
```
profile schema (ssh, uart, sudo, workdir).
Resolution order (profile → env var → interactive prompt) with the full refusal-trigger table.
The mandatory connection probe (
```
uname -r
```
+
```
cat /etc/nv_tegra_release
```
) and its output-validation rules.
File transfer per transport (
```
scp
```
vs. base64-over-tty, with the >100 KB warning).
Sudo invocation matrix per
```
sudo.method
```
× transport.
UART implementation contract that
```
scripts/uart_session.py
```
honors (state machines for login / exec / push / pull, exit codes, robustness notes).
Security notes (password handling, host-key pinning).

Available Scripts

Script	Purpose	Arguments
`scripts/uart_session.py`	UART transport black box for the on-target leg: login, command exec (with optional sudo), and base64-over-tty file transfer. Replaces ssh when the DUT has no network or ssh is broken.	`--tty <dev> [--baud <n>] --user <name> --password-env <ENVVAR> [--sudo-password-env <ENVVAR>] [--shell-prompt <regex>] [--lock-strategy refuse\|wait] <probe\|exec\|push\|pull> [...]`

Invocation (the skill calls scripts as a subprocess —

run_script()

in agent-runtime terminology):

bash

# run_script: probe the DUT over UART
DUT_UART_PASSWORD_ENV=DUT_UART_PWD \
DUT_UART_PWD="$(read -rs -p 'UART login pw: '; echo "$REPLY")" \
  scripts/uart_session.py \
    --tty /dev/ttyACM0 --baud 115200 \
    --user ubuntu --password-env DUT_UART_PASSWORD_ENV \
    probe

# run_script: exec a sudo command and capture exit code
scripts/uart_session.py --tty /dev/ttyACM0 --user ubuntu \
  --password-env DUT_UART_PASSWORD_ENV \
  --sudo-password-env DUT_SUDO_PWD \
  exec --use-sudo 'dmesg | tail -200'

The script's exit code is the contract — see the exit-code table in

UART implementation contract

Examples

Static-only validation (no DUT needed):

/jetson-validate-image
> static checks only against the staged BSP

On-target validation over SSH after a freshly flashed DUT:

/jetson-flash-image
   ↓
/jetson-validate-image
> on-target checks via dut_access.ssh

On-target validation over UART (no network on the DUT):

/jetson-validate-image
> use the uart transport at /dev/ttyACM0; the dut_access.uart block
  in the profile already has the tty and login_password_env wired up

Limitations

Placeholder skill — only the DUT-access contract and the
```
uart_session.py
```
helper are locked in. The static-check list, test-suite selection, result-sink layout, and pass/fail policy are tracked under
```
## Open items
```
and may change.
UART file transfer is byte-banged base64 at ~10 KB/s on 115200 baud — emits a warning for sources > 100 KB but proceeds. For high-volume transfers, switch to the SSH transport.
```
uart_session.py
```
opens and closes the tty per subcommand invocation (~1–2 s login per call). Validation passes running

10 commands amortize poorly on UART; prefer SSH.
SSH uses
```
StrictHostKeyChecking=accept-new
```
with a per-profile
```
known_hosts
```
file. A fingerprint change refuses — typically means the DUT was reflashed (host keys regenerated) or the IP was reassigned. Remove the per-profile entry manually rather than auto-accepting.
Passwords are never inlined in the profile YAML — only
```
password_env
```
(env-var name) is persisted.
```
auth=prompt
```
/
```
sudo.method=prompt
```
exposes the password in the conversation log, which is the user's responsibility to manage.
```
transport=uart
```
with
```
lock_strategy=steal
```
is not implemented (would require sending control characters that could corrupt the holder's state).

Troubleshooting

Error	Cause	Solution
`no DUT transport configured` (refuse)	On-target scope requested but `dut_access.transport` unresolved across profile / env / interactive prompt	Author `dut_access:` in the active profile, or rerun with static-only scope.
`$PASSWORD_ENV is unset` (refuse)	`auth=password` (or `sudo.method=password` ) names an env var that isn't exported on the host	`export <ENVVAR>=...` before invoking the skill; do NOT inline the password in YAML.
`tty held by another process` (refuse, exit 3)	`lock_strategy=refuse` and `fuser` reports another holder (minicom, picocom, getty)	Close the holding process ( `sudo fuser -k <tty>` only if you know what's there), or rerun with `lock_strategy=wait` .
`pyserial import failed` (exit 4)	UART transport selected but `pyserial` not installed in the skill's Python	`apt install python3-serial` or `pip install pyserial` .
SSH fingerprint refused	DUT's host keys changed since the per-profile `known_hosts` was pinned (typically a reflash)	Remove the matching line from `<workspace>/target-platform/<profile-stem>.known_hosts` and rerun — the new key will be accepted on first connect.
`login failed` (exit 128)	UART probe couldn't match a login or shell prompt within timeout	Confirm the DUT is powered + booted to userspace; check `--shell-prompt` override if the DUT carries an unusual `PS1` ; verify the `--user` matches a real account.
`DUT not booted from the just-flashed BSP` (warn / refuse)	`/etc/nv_tegra_release` on the DUT doesn't match `bsp_image.version`	Re-run `/jetson-flash-image` and confirm the DUT actually power-cycled into the new BSP, not the previous one.
`sudo prompt detected but no sudo password configured` (exit 130)	`--use-sudo` passed to `uart_session.py exec` but `--sudo-password-env` not set, and DUT user lacks NOPASSWD	Set `sudo.method=password` + `sudo.password_env` in the profile, or grant NOPASSWD on the DUT via `/etc/sudoers.d/` .
`command timed out` (exit 129)	Long-running DUT command exceeded the script's timeout	Run the command directly via `ssh` transport, or split into shorter steps.

References

```
references/dut-access.md
```
— full DUT-access contract: profile schema, resolution order, probe, file transfer, sudo, UART implementation, security.

../../context/target-platform-contract.md

— target-platform contract.

```
../../context/bsp-customization-workflow.md
```
— Workspace edit protocol (this skill is the Deploy tail).
```
../jetson-build-source/SKILL.md
```
— Build builder; produces the artifacts this skill validates.

jetson-validate-image

NPX Install

Tags

SKILL.md Content