About this skill
---
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-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
- Only supports Tegra234 (Orin) and Tegra264 (Thor) UPHY surfaces.
- Does not edit pinmux, PCIe-only DT properties absent from BPMP DTB
(`num-lanes`, `pcie-mode`), or upstream BSP files.
- Does not flash, build, or promote — chain into `/jetson-build-source`
and downstream skills.
- Hard-coded option tables are forbidden; if no Adaptation Guide
source resolves the skill refuses rather than guessing.
- Not table-driven across releases: every run re-reads the Guide for
the active BSP version.
## Troubleshooting
- **Cold boot reboot loop / BL31 `plat_setup.c:726` / `BPMP firmware
is not ready`** after `uphy0-config-6`: a later
`^UPHY_CONFIG=` line in the carrier conf re-overrode the clear.
Comment it (see `references/procedure.md` Step 6).
- **`wait-for-device failed` at flash, BPMP DTB unchanged**: an
ODMDATA token had wrong shape (e.g. `mgbe0-speed-0`). One bad token
drops the whole `ODMDATA="..."` line. Inspect grammar in
`references/procedure.md`.
- **BL31 SError reboot loop after disabling an MGBE**: missing
`mgbeN-speed-del`. FMON arms on the controller's own clocks
regardless of UPHY allocation.
- **Newly-routed controller doesn't enumerate**: stock kernel DTB had
`status="disabled"`. Overlay must emit `status="okay"` (matrix
row 4 in `references/procedure.md`).
- **Pinmap delta=0 but board still misbehaves**: UPHY differential
pairs are absent from pinmux `.xlsm`. Drive decisions off schematic
net names, not the pinmap.
- **Duplicate `pcie@<addr>` fragments**: another skill
(`jetson-customize-pcie`) already owns that node. Scope this skill
to MGBE / UFS / USB3 SS / PCIe-status-only and cite the other
overlay.
## References
- `references/procedure.md` — full eight-step procedure.
- `references/gotchas.md` — cross-cutting gotchas.
- `references/run-state-sidecar.md` — JSON sidecar schema + idempotency.
- `../../references/platform_template.yaml` — `documents:` schema.
- `../../context/bsp-customization-workflow.md` — overlay edit protocol.
- `../../references/bsp-customization-kernel-dtb.md` — composite-overlay
filename / append protocol.
- `../jetson-derive-carrier/SKILL.md` — produces the conf this skill
edits.
- `../jetson-init-source/SKILL.md` — produces the two git repos this
skill commits into.
- `../jetson-generate-kb/SKILL.md` — KB consulted for chip family +
file locations.