jetson-customize-uphy

Files (8)

• BENCHMARK.md
• SKILL.md
• evals.json · evals/
• gotchas.md · references/
• procedure.md · references/
• run-state-sidecar.md · references/
• skill-card.md
• skill.oms.sig

SKILL.md (first lines)

# 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

- Active target-platform profile with `reference_devkit:` and
  `custom_carrier:`.
- `<source.root_path>/Linux_for_Tegra/.git` initialized
  (`/jetson-init-source`).
- Forked carrier conf present (`/jetson-derive-carrier`).
- Reachable Adaptation Guide via `documents.adaptation_guide` ->
  `documents.bsp_developer_guide` -> web fetch -> Step-1 prompt
  fallback.
- **When `custom_carrier:` is present, both
  `documents.custom_carrier_schematic` AND
  `documents.custom_carrier_pinmux_xls` are REQUIRED.** The skill
  refuses to run if either is missing — routing decisions for the
  custom carrier cannot be guessed. Reference-devkit-only profiles
  (no `custom_carrier:` block) do not require these.

## 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

- User says "configure UPHY", "uphy lane allocation",
  "set uphy0-config-N", "change MGBE speed", or asks to remap
  PCIe / MGBE / USB3 / UFS on a custom carrier.
- A UPHY-fed controller doesn't enumerate after flash, OR cold boot
  dies in BL31 SError / `BPMP firmware is not ready`.
- A downstream skill reports FMON fault or BPMP-DTB lane mismatch.

## 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).

From NVIDIA/skills, Apache-2.0.

More from NVIDIA/skills