Agent Skill · NVIDIA NIM

jetson-customize-uphy

Configure Jetson UPHY lane allocation (uphy0/uphy1-config) on Orin/Thor custom carriers. Do NOT use for pinmux or PCIe-only edits.

View SKILL.md on GitHub → Source repository Provider profile
Provider: NVIDIA NIM Path in repo: skills/jetson-customize-uphy/SKILL.md

Skill body

Customize UPHY lane allocation

Purpose

Select a UPHY lane allocation on a Jetson custom carrier and edit the carrier flash-conf fork’s ODMDATA="..." to apply the chosen uphyX-config-N token(s) (plus the UPHY_CONFIG="" clear required for uphy0-config-6). Kernel-DT alignment per controller is not done here — after the ODMDATA commit lands, this skill dispatches to the per-controller skills (/jetson-customize-pcie, /jetson-customize-mgbe, /jetson-customize-usb), each of which must compare the chosen allocation against the reference kernel DTB node-by-node and emit an overlay fragment only when the K-stock value disagrees with the chosen allocation. Discovery is agentic: options, lanes, and controllers come from the Adaptation Guide, carrier schematic, and Module / SoC TRM at run time — never hard-coded. Every user-visible step renders its data as a markdown table, and the final summary includes a changes-summary table.

Prerequisites

Overview

UPHY (unified PHY) is the shared high-speed PHY pool on Tegra264 (Thor) and Tegra234 (Orin). Lane allocation is selected by ODMDATA tokens (uphy0-config-N, Thor also uphy1-config-N) parsed at flash time by tegraflash_impl_t264.py::tegraflash_update_bpmp_dtb() and written into /uphy/uphy{0,1}-config of the BPMP DTB.

Output is a single atomic ODMDATA commit in <source.root_path>/Linux_for_Tegra/ carrying the chosen uphyX-config-N token(s), the UPHY_CONFIG="" clear (for uphy0-config-6), AND every per-controller ODMDATA token derived from the chosen allocation (pcie@N_status=*, mgbeN-speed-*, USB SS per-port tokens). Sub-skills (/jetson-customize-pcie, /jetson-customize-mgbe, /jetson-customize-usb) own only the kernel-DT overlay fragments — they MUST NOT touch ODMDATA. All commits follow the batched pristine + customization pattern in ../../context/bsp-customization-workflow.md. Upstream BSP at <bsp_image.root_path>/ is never edited.

When to invoke

Procedure (summary)

Eight steps; full detail in references/procedure.md.

  1. Resolve target + docs. Refuse without active profile, custom carrier, source-tree git, or forked carrier conf. Resolve Adaptation Guide / schematic / Module Design Guide / SoC TRM.
  2. Locate “Configure the UPHY Lane” in the Adaptation Guide (PDF / HTML mirror / WebFetch). Cross-check Module Design Guide + SoC TRM.
  3. Cross-reference the carrier schematic. Cite UPHY net names (MGBE2_TX_P/N, PEX5_LN0+-, etc.). Zero matching nets = unrouted.
  4. Enumerate matching UPHY options. Surface every documented uphy0-config-N (and Thor uphy1-config-N) index.
  5. Ask the user which config (HARD GATE). Print tables first, then AskUserQuestion — one per UPHY surface, plus carrier-routing confirmation if any allocated lane is unrouted. Persist answers to the JSON sidecar (references/run-state-sidecar.md).

  6. Edit carrier flash-conf fork (atomic ODMDATA commit). This skill owns every ODMDATA token for the run. One ODMDATA="..." line, one commit, all tokens. Sub-skills MUST NOT touch ODMDATA.

    Decompile the BPMP DTB at <bsp_image.root_path>/Linux_for_Tegra/bootloader/generic/<BPFDTB_FILE> (BPFDTB_FILE from the carrier conf) to snapshot stock state, then emit tokens in this order:

    a. UPHY surface tokens — every chosen uphyX-config-N (Thor: both surfaces, even if one equals the guide default). Order uphy0 then uphy1; separator ,. b. Per-controller tokens — one per row whose plan-state differs from BPMP-stock. Match-rows get no token (redundant tokens can drop the whole line).

    • PCIe: pcie@N_status=okay|disabled.
    • MGBE: mgbeN-speed-<rate> on allocate, mgbeN-speed-del on disable. FMON arms on the controller’s own clocks regardless of UPHY allocation — missing del ⇒ BL31 SError reboot loop. Single most common post-flash failure on Thor.
    • USB SS: per-port tokens when the SoC grammar exposes them. c. UPHY_CONFIG="" clear when uphy0-config-6 is selected (BCT pinmux clear per Adaptation Guide).

  7. Build the per-controller allocation table and dispatch. Derive one row per UPHY-fed controller (PCIe / MGBE / USB SS / UFS) with {class, instance, allocated?, BPMP-stock, K-stock, routed?, Desired K state}. This table drives both (a) Step 6’s ODMDATA tokens and (b) the sub-skills’ overlay fragments — build it before Step 6 commits.

    Then invoke /jetson-customize-pcie, /jetson-customize-mgbe, and /jetson-customize-usb for kernel-DT overlay fragments only (no ODMDATA edits — Step 6 owns the line). Each sub-skill re-reads K-stock from <bsp_image.root_path>/Linux_for_Tegra/kernel/dtb/tegra<soc>-*-nv.dtb and skips emission when K-stock matches Desired K state. UFS handling stays inline here (no UFS sub-skill).

    Invoke all three whenever their controller class is present on this SoC (e.g. skip MGBE on Orin). Ask the operator first; on yes, run the sub-skill inline.

  8. Summary + next-step chain. Headline, breakdown, choices table (UPHY surface | chosen config | lane summary | UPHY_CONFIG-clear), changes-summary table (file | repo | commit SHA | one-line summary covering this skill’s commit + every dispatched sub-skill’s commit), then drive the downstream chain (more I/O? build & promote? flash? validate?) via sequential AskUserQuestion prompts per references/procedure.md Step 8. Never substitute a printed “Next step: …” line for the prompts.

Limitations

Troubleshooting

References

Skill frontmatter

version: 0.0.2 license: Apache-2.0 metadata: {"data-classification" => "public", "author" => "Jetson Team", "tags" => ["bsp", "phase-2", "io", "uphy"], "domain" => "meta"}