Agent Skill · NVIDIA NIM

jetson-customize-usb

Enable/disable Jetson USB2/USB3 SS ports via kernel-DT overlay. Do NOT use for UPHY lane allocation or ODMDATA edits.

View SKILL.md on GitHub → Source repository Provider profile
Provider: NVIDIA NIM Path in repo: skills/jetson-customize-usb/SKILL.md

Skill body

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

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):

# Place Path What it controls
1 Lane (PHY provider) xusb_padctl/pads/usb<2\|3>/lanes/usb<2\|3>-N SS / OTG PHY hardware-binding. status="disabled" then lane stops providing a PHY.
2 Port (controller-binding) xusb_padctl/ports/usb<2\|3>-N Per-port mode (host/device/otg), companion link, VBUS / OC / CC pin refs. status="disabled" then port removed from user-facing topology.
3 Host xHCI phys-list bus@0/usb@<addr>.phys + .phy-names Array of phandles + names the xHCI driver iterates. A ref to a disabled PHY returns -ENODEV and aborts the whole host probe.

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:

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

Procedure (summary)

The full step-by-step procedure lives in references/procedure.md.

  1. Step 1 — resolve active target + open source-of-truth docs.
  2. Step 2 — build the USB topology + companion graph from the in-tree DTB.
  3. Step 3 — AskUserQuestion for port(s) to enable / disable; surface companion cascade + on-carrier hub fan-out explicitly.
  4. Step 4 — per-port verify (module + carrier + UPHY lane) and capture wiring (VBUS-EN / OC / CC GPIOs via pin_verifier.py).
  5. 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/.
  6. 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.

Limitations

Troubleshooting

References

Skill frontmatter

version: 0.0.1 license: Apache-2.0 metadata: {"data-classification" => "public", "author" => "Jetson Team", "tags" => ["bsp", "phase-2", "io", "usb"], "domain" => "meta"}