Customize USB (per-port enable / disable / role)
Purpose
Enable, disable, or change the role of USB2 / USB3 SS ports on a
Jetson Thor (Tegra264) or Orin (Tegra234) custom carrier. Captures
per-port wiring (role, max speed, VBUS-EN / OC GPIOs, CC1/CC2 GPIOs
for Type-C, USB3 SS UPHY lane), resolves the SS to USB2 companion
graph from the in-tree DTB, then renders a self-contained kernel-DT
overlay that flips every port action in three places in lockstep
(lane status, port status, host xHCI phys + phy-names).
UPHY lane allocation belongs to jetson-customize-uphy. No ODMDATA
edit. Output is one commit to the composite custom overlay .dts in
the bsp_sources/ hardware repo.
Prerequisites
- Active profile with
reference_devkit: + custom_carrier: blocks.
<source.root_path>/Linux_for_Tegra/.git exists
(/jetson-init-source).
/jetson-derive-carrier has run — carrier flash-conf fork in the
overlay tracker.
/jetson-customize-uphy has run when any enabled USB3 SS port
needs a non-stock UPHY lane allocation. Its JSON sidecar at
<workspace>/target-platform/<profile-stem>.jetson-customize-uphy.json
is consulted for SS lane allocation.
- Source-of-truth docs: Adaptation Guide §"Port the Universal Serial
Bus", Module Design Guide §USB, SoC TRM (xusb block).
- When
custom_carrier: is present, both
documents.custom_carrier_schematic AND
documents.custom_carrier_pinmux_xls are REQUIRED. Refuse the run
if either is missing — per-port routing (VBUS-EN / OC / CC GPIOs, SS
lane wiring, hub fan-out) on a custom carrier cannot be guessed.
Reference-devkit-only profiles skip this check.
dtc, fdtoverlay on PATH.
Overview
USB on Tegra spans three IP surfaces: the xusb_padctl block (USB2
OTG + USB3 SS PHYs), the tegra-xusb xHCI host controller, and an
optional tegra-xudc device controller attached to the single
OTG-capable USB2 port (usb2-0).
A per-port flip MUST touch three kernel-DT places in lockstep.
Anything less crashes the host xHCI probe and leaves lsusb empty
on every port (collateral damage to stock-okay ports):
NVIDIA's stock-disabled usb3-3 in the Thor base DTB is the canonical
pattern — all three places flipped in lockstep.
Two extra rules ride on top of the three-place pattern:
- Rule A — lane + port pairing. Lane (place 1) and matching port
(place 2) MUST flip together.
- Rule B — companion cascade.
xusb_padctl/ports/usb3-N.nvidia,usb2-companion references a USB2
port phandle. Disabling that USB2 without cascading to its SS
companion then tegra-xusb: failed to enable PHYs: -19.
Agentic, not table-driven — every port, controller, lane,
companion link, phandle, and __symbols__ lookup is resolved at
runtime from docs + DTB + carrier pinmap + schematic.
When to invoke
- The user says "enable USB", "disable USB hub", "configure USB3 SS",
"set USB role", "wire VBUS-EN", "tegra-xusb / xudc / dr_mode", or
asks to bring up / take down a USB controller on a custom carrier.
- A USB receptacle on the carrier doesn't enumerate after flash, OR
collateral USB damage (
lsusb empty after a previous
jetson-customize-usb attempt) needs to be fixed.
jetson-customize-uphy re-allocated UPHY lanes affecting USB3 SS
ports and per-port DT now needs to follow.
Procedure (summary)
The full step-by-step procedure lives in references/procedure.md.
- Step 1 — resolve active target + open source-of-truth docs.
- Step 2 — build the USB topology + companion graph from the
in-tree DTB.
- Step 3 —
AskUserQuestion for port(s) to enable / disable;
surface companion cascade + on-carrier hub fan-out explicitly.
- Step 4 — per-port verify (module + carrier + UPHY lane) and
capture wiring (VBUS-EN / OC / CC GPIOs via
pin_verifier.py).
- Step 5 — render the kernel-DT overlay using the three-place
pattern, append fragments (
usb:padctl, usb:xhci, optional
usb:xudc) to the composite custom overlay .dts, run
fdtoverlay + the three post-merge invariants, commit to
bsp_sources/.
- Step 6 — write run-state JSON sidecar (shape in
references/run-state-sidecar.md), emit headline, then drive the
downstream next-step chain via sequential AskUserQuestion prompts
per references/procedure.md Step 6. Never substitute a printed
"Next step: …" line for the prompts.
See references/gotchas.md for the load-bearing failure modes.