jetson-customize-usb

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

用途

在 Jetson Thor（Tegra264）或 Orin（Tegra234）自定义载板上启用、禁用或更改 USB2 / USB3 SS 端口的角色。记录每个端口的接线信息（角色、最高速度、VBUS-EN / OC GPIO、Type-C 的 CC1/CC2 GPIO、USB3 SS UPHY 通道），根据树内 DTB 解析 SS 到 USB2 配套端口的关系，然后生成一个独立的内核 DT overlay，在三个位置同步切换每个端口的操作（通道状态、端口状态、主机 xHCI phys + phy-names）。

UPHY 通道分配由 jetson-customize-uphy 负责。不编辑 ODMDATA。输出为对 bsp_sources/ 硬件仓库中的组合自定义 overlay .dts 提交一个 commit。

前提条件

• 活动配置文件中包含 reference_devkit: + custom_carrier: 块。
• <source.root_path>/Linux_for_Tegra/.git 存在 （/jetson-init-source）。
• 已运行 /jetson-derive-carrier — overlay 跟踪器中有载板 flash-conf fork。
• 当任何已启用的 USB3 SS 端口需要非默认 UPHY 通道分配时，已运行 /jetson-customize-uphy。其位于 <workspace>/target-platform/<profile-stem>.jetson-customize-uphy.json 的 JSON sidecar 用于查询 SS 通道分配。
• 事实来源文档：Adaptation Guide §"Port the Universal Serial Bus"、Module Design Guide §USB、SoC TRM（xusb 块）。
• 当存在 custom_carrier: 时，documents.custom_carrier_schematic 和 documents.custom_carrier_pinmux_xls 都是必需的。 如果缺少任一文档，则拒绝运行 — 自定义载板上的每端口布线（VBUS-EN / OC / CC GPIO、SS 通道接线、集线器扇出）无法推测。 仅参考开发套件的配置文件跳过此检查。
• PATH 中有 dtc、fdtoverlay。

概述

Tegra 上的 USB 涉及三个 IP 部分：xusb_padctl 块（USB2 OTG + USB3 SS PHY）、tegra-xusb xHCI 主机控制器，以及连接到唯一支持 OTG 的 USB2 端口（usb2-0）的可选 tegra-xudc 设备控制器。

每端口切换必须同步修改内核 DT 中的三个位置。 少于三个会导致主机 xHCI 探测崩溃，并使所有端口上的 lsusb 结果为空（连带影响默认正常的端口）：

#	位置	路径	控制内容
1	通道（PHY 提供者）	xusb_padctl/pads/usb<2|3>/lanes/usb<2|3>-N	SS / OTG PHY 硬件绑定。设置 status="disabled" 后，通道便不再提供 PHY。
2	端口（控制器绑定）	xusb_padctl/ports/usb<2|3>-N	每端口模式（host/device/otg）、配套链接、VBUS / OC / CC 引脚引用。设置 status="disabled" 后，端口会从面向用户的拓扑中移除。
3	主机 xHCI phys 列表	bus@0/usb@<addr>.phys + .phy-names	xHCI 驱动遍历的 phandle + 名称数组。引用已禁用 PHY 会返回 -ENODEV，并中止整个主机探测。

NVIDIA 的默认禁用端口 usb3-3（位于 Thor 基础 DTB 中）是标准模式 — 三个位置均同步切换。

在三处修改模式之上，还需遵守两条规则：

• 规则 A — 通道 + 端口配对。 通道（位置 1）和对应端口（位置 2）必须同时切换。
• 规则 B — 配套端口级联。 xusb_padctl/ports/usb3-N.nvidia,usb2-companion 引用一个 USB2 端口 phandle。禁用该 USB2 端口但未级联禁用其 SS 配套端口，会导致 tegra-xusb: failed to enable PHYs: -19。

由 Agent 执行，而非依赖表格 — 运行时根据文档 + DTB + 载板引脚映射 + 原理图解析每个端口、控制器、通道、配套链接、phandle 和 __symbols__ 查找项。

何时调用

• 用户提到“启用 USB”“禁用 USB 集线器”“配置 USB3 SS”“设置 USB 角色”“连接 VBUS-EN”“tegra-xusb / xudc / dr_mode”，或要求在自定义载板上启用 / 禁用 USB 控制器。
• 刷写后，载板上的 USB 插座无法枚举，或者需要修复 USB 连带损坏（此前尝试 jetson-customize-usb 后 lsusb 结果为空）。
• jetson-customize-uphy 重新分配了影响 USB3 SS 端口的 UPHY 通道，因此每端口 DT 也需要相应更新。

流程（摘要）

完整的分步流程见 references/procedure.md。

1. 步骤 1 — 确定当前目标 + 打开权威文档。
2. 步骤 2 — 根据树内 DTB 构建 USB 拓扑 + companion 图。
3. 步骤 3 — 使用 AskUserQuestion 询问要启用/禁用的端口； 明确说明 companion 级联 + 载板上的 Hub 分支。
4. 步骤 4 — 逐端口验证（模块 + 载板 + UPHY 通道），并通过 pin_verifier.py 捕获接线信息（VBUS-EN / OC / CC GPIO）。
5. 步骤 5 — 使用三处模式生成 kernel-DT overlay，将片段 （usb:padctl、usb:xhci、可选的 usb:xudc）追加到组合自定义 overlay .dts， 运行 fdtoverlay + 三项合并后不变量检查，并提交到 bsp_sources/。
6. 步骤 6 — 编写运行状态 JSON 旁文件（格式见 references/run-state-sidecar.md），输出概要，然后根据 references/procedure.md 步骤 6，通过依次发起 AskUserQuestion 提示来执行 下游后续步骤链。切勿用打印一行“下一步：……”代替这些提示。

承载关键失败模式的说明见 references/gotchas.md。

限制

• 仅负责 kernel-DT overlay。ODMDATA 不提供按端口设置 USB status 的选项；不要修改它。
• 不负责分配 UPHY 通道——这由 jetson-customize-uphy 负责。 在 uphy 运行状态显示通道已分配之前，拒绝提交启用 SS 的更改。
• 不直接修补 pinmux DTSI——将 SFIO 不匹配问题转交给 /jetson-customize-pinmux set-pin。
• 不编译 .dtbo，也不注册 OVERLAY_DTB_FILE+=—— /jetson-build-source 负责构建 + 刷机配置注册。
• Tegra 平台不变量：只有 usb2-0 支持 OTG；xudc 只能连接到该端口。所有其他 USB2 端口和所有 USB3 SS 端口都仅用于主机模式。

故障排查

• 所有端口的 lsusb 输出为空，但 192.168.55.1 上的 USB 以太网仍然正常： 主机 xHCI 已退出；三处锁步已被破坏。检查合并后的 DTB；验证 references/procedure.md 步骤 5d 中的合并后不变量。
• tegra-xusb: failed to enable PHYs: -19： 违反了 companion 级联 （规则 B）——禁用了 USB2，却没有禁用其 SS companion。
• no port found 或 Requested PHY is disabled： 违反了规则 A ——通道状态与端口状态不匹配。
• fdtoverlay 报错 FDT_ERR_NOTFOUND： 某个片段对标签不在 __symbols__ 中的节点使用了 target = <&label>（主机 xHCI / tegra-xudc 中很常见）。改用 target-path = "/bus@0/usb@<addr>"。
• dtc 警告 phys_property: cell 0 is not a phandle reference： 无害；在主机 phys 覆盖中使用原始整数 phandle 时，出现此警告是预期行为。
• 端口启动了，但 VBUS 始终未使能： vbus-supply 引用了一个不存在的稳压器父节点。确保固定稳压器节点存在，然后再引用它。
• xHCI 启动时绑定了错误的端口： 主机 phys 元素顺序未得到保留。只省略已禁用的条目；绝不要重新排列保留的条目。

参考资料

• 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 通道的 同系列技能。
• ../jetson-customize-pinmux/SKILL.md — 用于修复 VBUS-EN / OC / CC SFIO 的 同系列技能。
• ../jetson-derive-carrier/SKILL.md — 必须先运行。
• ../jetson-init-source/SKILL.md — 生成 overlay 跟踪文件 和 bsp_sources 仓库。