--- name: jetson-validate-image description: >- Use after jetson-flash-image to run static BSP checks, on-target smoke/regression tests on a flashed DUT, or both. Not for build or flash steps. Triggers: validate bsp, on-target validation. version: 0.0.1 license: "Apache-2.0" metadata: data-classification: public author: "Jetson Team" tags: - bsp - validation - test - deploy domain: meta --- # 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`](../../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 `` 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`](#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. 1. **Read the active target** per the prerequisite contract. 2. **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). 3. **Static checks** (if in scope): - Required artifacts present at expected paths in `/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 `/Linux_for_Tegra/bootloader/l4t_initrd.img` and `/Linux_for_Tegra/rootfs/boot/initrd`; verify three invariants against the *promoted* `bsp_image` state: (a) `/Linux_for_Tegra/kernel/Image` matches `/Linux_for_Tegra/rootfs/boot/Image` byte-for- byte — drift here means [the "Mirror kernel Image into rootfs" step](../jetson-promote-image/SKILL.md#mirror-kernel-image-into-rootfs-when-kernel-changed) 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 `/Linux_for_Tegra/rootfs/lib/modules//` — any drift means modules will be shadowed at early boot. (c) the vermagic stamped on every initramfs `*.ko` matches the `UTS_RELEASE` reachable from `/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`](../jetson-promote-image/SKILL.md#refresh-initramfs-when-kernel-or-modules-changed). 4. **On-target checks** (if in scope): - **Connect to the DUT** per the [`## DUT access`](#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//srcversion` on the DUT against the `modinfo /lib/modules/$(uname -r)/.../.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//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. 5. **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`](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 [--baud ] --user --password-env [--sudo-password-env ] [--shell-prompt ] [--lock-strategy refuse\|wait] [...]` | 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`](references/dut-access.md#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 =...` 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 ` 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 `/target-platform/.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`](references/dut-access.md) — full DUT-access contract: profile schema, resolution order, probe, file transfer, sudo, UART implementation, security. - [`../../context/target-platform-contract.md`](../../context/target-platform-contract.md) — target-platform contract. - [`../../context/bsp-customization-workflow.md`](../../context/bsp-customization-workflow.md#workflow-invariants) — Workspace edit protocol (this skill is the Deploy tail). - [`../jetson-build-source/SKILL.md`](../jetson-build-source/SKILL.md) — Build builder; produces the artifacts this skill validates.