/jetson-customize-uphy

name: jetson-customize-uphy
description: Configure Jetson UPHY lane allocation (uphy0/uphy1-config) on Orin/Thor custom carriers. Do NOT use for pinmux or PCIe-only edits.
version: 0.0.2
license: "Apache-2.0"
metadata:
  data-classification: public
  author: "Jetson Team"
  tags:
    - bsp
    - phase-2
    - io
    - uphy
  domain: meta

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