jetson-customize-usb

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Customize USB (per-port enable / disable / role)

定制USB（按端口启用/禁用/设置角色）

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.

在Jetson Thor（Tegra264）或Orin（Tegra234）定制载板上启用、禁用或更改USB2/USB3 SS端口的角色。捕获按端口的布线信息（角色、最大速率、VBUS-EN/OC GPIO、Type-C的CC1/CC2 GPIO、USB3 SS UPHY lane），解析内核自带DTB中的SS与USB2配套链路图，然后生成一个独立的kernel-DT overlay，同步在三个位置切换每个端口的状态（lane状态、端口状态、主机xHCI的

phys

phy-names

）。

UPHY lane分配属于

jetson-customize-uphy

的功能范围。请勿编辑ODMDATA。输出内容会作为一次提交，添加到硬件仓库

bsp_sources/

中的复合定制overlay

.dts

文件中。

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.

包含
```
reference_devkit:
```
+
```
custom_carrier:
```
块的活跃配置文件。

存在

<source.root_path>/Linux_for_Tegra/.git

（

/jetson-init-source

）。

已运行
```
/jetson-derive-carrier
```
——载板闪存配置分支已在overlay跟踪器中。
当任何启用的USB3 SS端口需要非默认UPHY lane分配时，需先运行
```
/jetson-customize-uphy
```
。其位于
```
<workspace>/target-platform/<profile-stem>.jetson-customize-uphy.json
```
的JSON辅助文件会被用于查询SS lane分配信息。
权威文档：适配指南 §“移植通用串行总线”、模块设计指南 §USB、SoC技术参考手册（xusb模块）。
**当存在
```
custom_carrier:
```
时，
```
documents.custom_carrier_schematic
```
和
```
documents.custom_carrier_pinmux_xls
```
均为必填项。**如果其中任意一项缺失则拒绝运行——无法猜测定制载板上的按端口路由（VBUS-EN/OC/CC GPIO、SS lane布线、集线器扩展）信息。仅包含参考开发板的配置文件可跳过此检查。
系统PATH中包含
```
dtc
```
、
```
fdtoverlay
```
工具。

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:

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.

Tegra平台上的USB涉及三个IP层面：

xusb_padctl

模块（USB2 OTG + USB3 SS PHY）、

tegra-xusb

xHCI主机控制器，以及可选的

tegra-xudc

设备控制器（连接到唯一支持OTG的USB2端口

usb2-0

）。

**按端口切换必须同步修改内核DT的三个位置。**任何遗漏都会导致主机xHCI探测失败，且所有端口的

lsusb

命令返回空（对原本正常的端口造成连带损坏）：

#	位置	路径	控制内容
1	Lane（PHY提供者）	`xusb_padctl/pads/usb<2\|3>/lanes/usb<2\|3>-N`	SS/OTG PHY硬件绑定。设置 `status="disabled"` 后，lane将停止提供PHY。
2	Port（控制器绑定）	`xusb_padctl/ports/usb<2\|3>-N`	按端口模式（主机/设备/OTG）、配套链路、VBUS/OC/CC引脚引用。设置 `status="disabled"` 后，端口会从用户可见的拓扑中移除。
3	主机xHCI物理列表	`bus@0/usb@<addr>.phys` + `.phy-names`	xHCI驱动遍历的句柄数组及名称。引用已禁用的PHY会返回 `-ENODEV` 并终止整个主机探测过程。

Thor基础DTB中NVIDIA默认禁用的

usb3-3

是标准示例——三个位置已同步切换。

在三位置模式之上还有两条额外规则：

**规则A——lane与端口配对。**Lane（位置1）和对应的端口（位置2）必须同步切换状态。
规则B——配套级联。
```
xusb_padctl/ports/usb3-N.nvidia,usb2-companion
```
引用了一个USB2端口的句柄。如果禁用该USB2端口但未同步禁用其SS配套端口，会出现
```
tegra-xusb: failed to enable PHYs: -19
```
错误。

采用智能驱动而非表格驱动——每个端口、控制器、lane、配套链路、phandle以及

__symbols__

查找均在运行时通过文档、DTB、载板引脚图和原理图解析得出。

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.

当用户提出“启用USB”、“禁用USB集线器”、“配置USB3 SS”、“设置USB角色”、“连接VBUS-EN”、“tegra-xusb/xudc/dr_mode”，或要求在定制载板上启动/关闭USB控制器时。
载板上的USB接口在闪存后无法枚举，或需要修复之前尝试
```
jetson-customize-usb
```
导致的USB连带损坏（
```
lsusb
```
返回空）时。
```
jetson-customize-uphy
```
重新分配了影响USB3 SS端口的UPHY lane，此时需要同步更新按端口的DT配置。

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.

完整的分步流程请查看

references/procedure.md

。

步骤1——解析活跃目标并打开权威文档。
步骤2——从内核自带DTB构建USB拓扑及配套链路图。
步骤3——调用
```
AskUserQuestion
```
询问要启用/禁用的端口；明确显示配套级联及载板上的集线器扩展信息。
步骤4——按端口验证（模块+载板+UPHY lane）并捕获布线信息（通过
```
pin_verifier.py
```
获取VBUS-EN/OC/CC GPIO）。
步骤5——使用三位置模式生成kernel-DT overlay，将片段（
```
usb:padctl
```
、
```
usb:xhci
```
、可选的
```
usb:xudc
```
）追加到复合定制overlay
```
.dts
```
文件中，运行
```
fdtoverlay
```
及三个合并后校验规则，提交到
```
bsp_sources/
```
。
步骤6——写入运行状态JSON辅助文件（格式参考
```
references/run-state-sidecar.md
```
），输出标题，然后按照
```
references/procedure.md
```
步骤6中的顺序通过
```
AskUserQuestion
```
提示驱动下游后续步骤。切勿用打印的“下一步：…”替代提示信息。

请查看

references/gotchas.md

了解关键故障模式。

Limitations

限制条件

Owns kernel-DT overlay only. ODMDATA does not expose a per-port USB
```
status
```
knob; do not edit it.
Does NOT allocate UPHY lanes —
```
jetson-customize-uphy
```
owns that. Refuse to commit an SS-enable until uphy run-state shows the lane allocated.
Does NOT directly patch the pinmux DTSI — routes SFIO mismatches to
```
/jetson-customize-pinmux set-pin
```
.
Does NOT compile the
```
.dtbo
```
or register
```
OVERLAY_DTB_FILE+=
```
—
```
/jetson-build-source
```
owns build + flash-conf registration.
Tegra platform invariant: only
```
usb2-0
```
is OTG-capable;
```
xudc
```
attaches there only. All other USB2 ports and all USB3 SS ports are host-only.

仅负责kernel-DT overlay。ODMDATA没有提供按端口设置USB
```
status
```
的选项；请勿编辑它。
不负责UPHY lane分配——该功能属于
```
jetson-customize-uphy
```
。在uphy运行状态显示lane已分配前，拒绝提交SS启用的修改。
不直接修补pinmux DTSI——将SFIO不匹配问题导向
```
/jetson-customize-pinmux set-pin
```
。
不编译
```
.dtbo
```
或注册
```
OVERLAY_DTB_FILE+=
```
——该功能属于
```
/jetson-build-source
```
的构建及闪存配置注册环节。
Tegra平台固定规则：仅
```
usb2-0
```
支持OTG；
```
xudc
```
仅连接到该端口。所有其他USB2端口及USB3 SS端口仅支持主机模式。

Troubleshooting

故障排查

Empty
lsusb
on every port, USB-eth at 192.168.55.1 still up: host xHCI bailed; three-place lockstep was broken. Inspect merged DTB; verify post-merge invariants in
```
references/procedure.md
```
Step 5d.
tegra-xusb: failed to enable PHYs: -19
: companion cascade (Rule B) violated — a USB2 was disabled without its SS companion.
no port found
or
Requested PHY is disabled
: Rule A violated — lane status and port status are mismatched.

FDT_ERR_NOTFOUND
from
fdtoverlay
: a fragment used

target = <&label>

for a node whose label is not in

__symbols__

(typical for host xHCI /

tegra-xudc

). Switch to

target-path = "/bus@0/usb@<addr>"

dtc warning
phys_property: cell 0 is not a phandle reference
: benign; expected when using raw integer phandles in the host phys override.
Port boots but VBUS never asserts:
```
vbus-supply
```
references a regulator parent node that does not exist. Ensure the fixed regulator node is present before referencing it.
xHCI binds the wrong port at boot: host
```
phys
```
element order was not preserved. Only elide disabled entries; never reorder kept ones.

**所有端口的
```
lsusb
```
返回空，但USB以太网仍在192.168.55.1运行：**主机xHCI启动失败；三位置同步规则被破坏。检查合并后的DTB；验证
```
references/procedure.md
```
步骤5d中的合并后校验规则。
**
```
tegra-xusb: failed to enable PHYs: -19
```
：**违反了配套级联规则（规则B）——禁用了USB2端口但未同步禁用其SS配套端口。
**
```
no port found
```
或
```
Requested PHY is disabled
```
：**违反了lane与端口配对规则（规则A）——lane状态与端口状态不匹配。
**
```
fdtoverlay
```
返回
```
FDT_ERR_NOTFOUND
```
：**某个片段使用了
```
target = <&label>
```
引用节点，但该节点的标签不在
```
__symbols__
```
中（主机xHCI/
```
tegra-xudc
```
常见此问题）。切换为
```
target-path = "/bus@0/usb@<addr>"
```
。
**dtc警告
```
phys_property: cell 0 is not a phandle reference
```
：**良性警告；在主机phys覆盖中使用原始整数句柄时会出现此情况。
端口启动但VBUS从未激活：
```
vbus-supply
```
引用了不存在的调节器父节点。确保在引用前已存在固定调节器节点。
**xHCI在启动时绑定了错误的端口：**主机
```
phys
```
元素顺序未保留。仅删除已禁用的条目；切勿重新排序保留的条目。

References

参考资料

```
references/procedure.md
```
— full step-by-step procedure.
```
references/gotchas.md
```
— load-bearing failure modes.
```
references/run-state-sidecar.md
```
— run-state JSON shape.

references/usb-architecture.md

— Tegra USB IP architecture notes (

xusb_padctl

tegra-xusb

xudc

```
references/usb-dt-bindings.md
```
— USB DT binding cheatsheet (lane / port / phys-list shapes).
```
../../scripts/pin_verifier.py
```
— shared HSIO pin verifier.

../../references/platform_template.yaml

—

documents:

block consumed by Step 1.

../../context/bsp-customization-workflow.md

— overlay edit protocol.

../../references/bsp-customization-kernel-dtb.md

— composite overlay append protocol.

```
../jetson-customize-uphy/SKILL.md
```
— sibling skill that owns UPHY lane allocation.
```
../jetson-customize-pinmux/SKILL.md
```
— sibling skill for VBUS-EN / OC / CC SFIO fixes.
```
../jetson-derive-carrier/SKILL.md
```
— must run first.

../jetson-init-source/SKILL.md

— produces the overlay tracker

```
bsp_sources
```
repo.

```
references/procedure.md
```
——完整分步流程。
```
references/gotchas.md
```
——关键故障模式。
```
references/run-state-sidecar.md
```
——运行状态JSON格式。

references/usb-architecture.md

——Tegra USB IP架构说明（

xusb_padctl

、

tegra-xusb

、

xudc

）。

```
references/usb-dt-bindings.md
```
——USB DT绑定速查表（lane/port/phys-list格式）。
```
../../scripts/pin_verifier.py
```
——共享HSIO引脚验证工具。

../../references/platform_template.yaml

——步骤1使用的

documents:

块。

../../context/bsp-customization-workflow.md

——overlay编辑协议。

../../references/bsp-customization-kernel-dtb.md

——复合overlay追加协议。

```
../jetson-customize-uphy/SKILL.md
```
——负责UPHY lane分配的关联技能文档。
```
../jetson-customize-pinmux/SKILL.md
```
——用于VBUS-EN/OC/CC SFIO修复的关联技能文档。
```
../jetson-derive-carrier/SKILL.md
```
——必须先运行此技能。

../jetson-init-source/SKILL.md

——生成overlay跟踪器及

bsp_sources

仓库。