Jetson Customize Uphy Agent Skill

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.