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.
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.
Locate "Configure the UPHY Lane" in the Adaptation Guide (PDF /
HTML mirror / WebFetch). Cross-check Module Design Guide + SoC TRM.
Cross-reference the carrier schematic. Cite UPHY net names
(MGBE2_TX_P/N, PEX5_LN0+-, etc.). Zero matching nets = unrouted.
Enumerate matching UPHY options. Surface every documented
uphy0-config-N (and Thor uphy1-config-N) index.
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).
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).
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.
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.
1---2name: jetson-customize-uphy3description: Configure Jetson UPHY lane allocation (uphy0/uphy1-config) on Orin/Thor custom carriers. Do NOT use for pinmux or PCIe-only edits.4version: 0.0.25license: "Apache-2.0"6metadata:7 source: https://skillmd.com/skills/nvidia/jetson-customize-uphy8 data-classification: public9 author: "Jetson Team"10 tags:11 - bsp12 - phase-213 - io14 - uphy15 domain: meta16---1718# Customize UPHY lane allocation1920## Purpose2122Select a UPHY lane allocation on a Jetson custom carrier and edit the23carrier flash-conf fork's `ODMDATA="..."` to apply the chosen24`uphyX-config-N` token(s) (plus the `UPHY_CONFIG=""` clear required for25`uphy0-config-6`). Kernel-DT alignment per controller is **not** done26here — after the ODMDATA commit lands, this skill dispatches to the27per-controller skills (`/jetson-customize-pcie`,28`/jetson-customize-mgbe`, `/jetson-customize-usb`), each of which must29compare the chosen allocation against the **reference kernel DTB**30node-by-node and emit an overlay fragment only when the K-stock value31disagrees with the chosen allocation. Discovery is agentic: options,32lanes, and controllers come from the Adaptation Guide, carrier33schematic, and Module / SoC TRM at run time — never hard-coded. Every34user-visible step renders its data as a markdown table, and the final35summary includes a changes-summary table.3637## Prerequisites3839- Active target-platform profile with `reference_devkit:` and40 `custom_carrier:`.41- `<source.root_path>/Linux_for_Tegra/.git` initialized42 (`/jetson-init-source`).43- Forked carrier conf present (`/jetson-derive-carrier`).44- Reachable Adaptation Guide via `documents.adaptation_guide` ->45 `documents.bsp_developer_guide` -> web fetch -> Step-1 prompt46 fallback.47- **When `custom_carrier:` is present, both48 `documents.custom_carrier_schematic` AND49 `documents.custom_carrier_pinmux_xls` are REQUIRED.** The skill50 refuses to run if either is missing — routing decisions for the51 custom carrier cannot be guessed. Reference-devkit-only profiles52 (no `custom_carrier:` block) do not require these.5354## Overview5556UPHY (unified PHY) is the shared high-speed PHY pool on Tegra264 (Thor)57and Tegra234 (Orin). Lane allocation is selected by `ODMDATA` tokens58(`uphy0-config-N`, Thor also `uphy1-config-N`) parsed at flash time by59`tegraflash_impl_t264.py::tegraflash_update_bpmp_dtb()` and written60into `/uphy/uphy{0,1}-config` of the BPMP DTB.6162Output is a **single atomic ODMDATA commit** in63`<source.root_path>/Linux_for_Tegra/` carrying the chosen64`uphyX-config-N` token(s), the `UPHY_CONFIG=""` clear (for65`uphy0-config-6`), AND every per-controller ODMDATA token derived66from the chosen allocation (`pcie@N_status=*`, `mgbeN-speed-*`, USB SS67per-port tokens). Sub-skills (`/jetson-customize-pcie`,68`/jetson-customize-mgbe`, `/jetson-customize-usb`) own only the69kernel-DT overlay fragments — they MUST NOT touch ODMDATA. All70commits follow the batched pristine + customization pattern in71`../../context/bsp-customization-workflow.md`. Upstream BSP at72`<bsp_image.root_path>/` is never edited.7374## When to invoke7576- User says "configure UPHY", "uphy lane allocation",77 "set uphy0-config-N", "change MGBE speed", or asks to remap78 PCIe / MGBE / USB3 / UFS on a custom carrier.79- A UPHY-fed controller doesn't enumerate after flash, OR cold boot80 dies in BL31 SError / `BPMP firmware is not ready`.81- A downstream skill reports FMON fault or BPMP-DTB lane mismatch.8283## Procedure (summary)8485Eight steps; full detail in `references/procedure.md`.86871. **Resolve target + docs.** Refuse without active profile, custom88 carrier, source-tree git, or forked carrier conf. Resolve Adaptation89 Guide / schematic / Module Design Guide / SoC TRM.902. **Locate "Configure the UPHY Lane"** in the Adaptation Guide (PDF /91 HTML mirror / `WebFetch`). Cross-check Module Design Guide + SoC TRM.923. **Cross-reference the carrier schematic.** Cite UPHY net names93 (`MGBE2_TX_P/N`, `PEX5_LN0+-`, etc.). Zero matching nets = unrouted.944. **Enumerate matching UPHY options.** Surface every documented95 `uphy0-config-N` (and Thor `uphy1-config-N`) index.965. **Ask the user which config (HARD GATE).** Print tables first, then97 `AskUserQuestion` — one per UPHY surface, plus carrier-routing98 confirmation if any allocated lane is unrouted. Persist answers to99 the JSON sidecar (`references/run-state-sidecar.md`).1006. **Edit carrier flash-conf fork (atomic ODMDATA commit).** This skill101 owns every ODMDATA token for the run. One `ODMDATA="..."` line, one102 commit, all tokens. Sub-skills MUST NOT touch ODMDATA.103104 Decompile the BPMP DTB at105 `<bsp_image.root_path>/Linux_for_Tegra/bootloader/generic/<BPFDTB_FILE>`106 (`BPFDTB_FILE` from the carrier conf) to snapshot stock state, then107 emit tokens in this order:108109 a. **UPHY surface tokens** — every chosen `uphyX-config-N` (Thor:110 both surfaces, even if one equals the guide default). Order111 `uphy0` then `uphy1`; separator `,`.112 b. **Per-controller tokens** — one per row whose plan-state differs113 from BPMP-stock. Match-rows get no token (redundant tokens can114 drop the whole line).115 - PCIe: `pcie@N_status=okay|disabled`.116 - MGBE: `mgbeN-speed-<rate>` on allocate, **`mgbeN-speed-del`**117 on disable. FMON arms on the controller's own clocks118 regardless of UPHY allocation — missing `del` ⇒ BL31 SError119 reboot loop. Single most common post-flash failure on Thor.120 - USB SS: per-port tokens when the SoC grammar exposes them.121 c. **`UPHY_CONFIG=""` clear** when `uphy0-config-6` is selected122 (BCT pinmux clear per Adaptation Guide).1237. **Build the per-controller allocation table and dispatch.** Derive124 one row per UPHY-fed controller (PCIe / MGBE / USB SS / UFS) with125 `{class, instance, allocated?, BPMP-stock, K-stock, routed?,126 Desired K state}`. This table drives both (a) Step 6's ODMDATA127 tokens and (b) the sub-skills' overlay fragments — build it128 before Step 6 commits.129130 Then invoke `/jetson-customize-pcie`, `/jetson-customize-mgbe`, and131 `/jetson-customize-usb` for **kernel-DT overlay fragments only**132 (no ODMDATA edits — Step 6 owns the line). Each sub-skill re-reads133 K-stock from134 `<bsp_image.root_path>/Linux_for_Tegra/kernel/dtb/tegra<soc>-*-nv.dtb`135 and skips emission when K-stock matches Desired K state. UFS136 handling stays inline here (no UFS sub-skill).137138 Invoke all three whenever their controller class is present on139 this SoC (e.g. skip MGBE on Orin). Ask the operator first; on140 `yes`, run the sub-skill inline.1418. **Summary + next-step chain.** Headline, breakdown, **choices table**142 (UPHY surface | chosen config | lane summary | UPHY_CONFIG-clear),143 **changes-summary table** (file | repo | commit SHA | one-line144 summary covering this skill's commit + every dispatched sub-skill's145 commit), then drive the downstream chain (more I/O? build & promote?146 flash? validate?) via sequential `AskUserQuestion` prompts per147 `references/procedure.md` Step 8. Never substitute a printed148 "Next step: …" line for the prompts.149150## Limitations151152- Only supports Tegra234 (Orin) and Tegra264 (Thor) UPHY surfaces.153- Does not edit pinmux, PCIe-only DT properties absent from BPMP DTB154 (`num-lanes`, `pcie-mode`), or upstream BSP files.155- Does not flash, build, or promote — chain into `/jetson-build-source`156 and downstream skills.157- Hard-coded option tables are forbidden; if no Adaptation Guide158 source resolves the skill refuses rather than guessing.159- Not table-driven across releases: every run re-reads the Guide for160 the active BSP version.161162## Troubleshooting163164- **Cold boot reboot loop / BL31 `plat_setup.c:726` / `BPMP firmware165 is not ready`** after `uphy0-config-6`: a later166 `^UPHY_CONFIG=` line in the carrier conf re-overrode the clear.167 Comment it (see `references/procedure.md` Step 6).168- **`wait-for-device failed` at flash, BPMP DTB unchanged**: an169 ODMDATA token had wrong shape (e.g. `mgbe0-speed-0`). One bad token170 drops the whole `ODMDATA="..."` line. Inspect grammar in171 `references/procedure.md`.172- **BL31 SError reboot loop after disabling an MGBE**: missing173 `mgbeN-speed-del`. FMON arms on the controller's own clocks174 regardless of UPHY allocation.175- **Newly-routed controller doesn't enumerate**: stock kernel DTB had176 `status="disabled"`. Overlay must emit `status="okay"` (matrix177 row 4 in `references/procedure.md`).178- **Pinmap delta=0 but board still misbehaves**: UPHY differential179 pairs are absent from pinmux `.xlsm`. Drive decisions off schematic180 net names, not the pinmap.181- **Duplicate `pcie@<addr>` fragments**: another skill182 (`jetson-customize-pcie`) already owns that node. Scope this skill183 to MGBE / UFS / USB3 SS / PCIe-status-only and cite the other184 overlay.185186## References187188- `references/procedure.md` — full eight-step procedure.189- `references/gotchas.md` — cross-cutting gotchas.190- `references/run-state-sidecar.md` — JSON sidecar schema + idempotency.191- `../../references/platform_template.yaml` — `documents:` schema.192- `../../context/bsp-customization-workflow.md` — overlay edit protocol.193- `../../references/bsp-customization-kernel-dtb.md` — composite-overlay194 filename / append protocol.195- `../jetson-derive-carrier/SKILL.md` — produces the conf this skill196 edits.197- `../jetson-init-source/SKILL.md` — produces the two git repos this198 skill commits into.199- `../jetson-generate-kb/SKILL.md` — KB consulted for chip family +200 file locations.