⚡

jetson-customize-usbSkill jetson-customize-usb

定制 Jetson Thor/Orin 载板 USB 端口：通过内核设备树 overlay 启用/禁用 USB2/USB3 SS 端口并设置角色，同步修改 lane、端口和 xHCI phys 列表，处理 USB2/USB3 companion 级联。关键词：Jetson、USB端口定制、内核DT Overlay、xHCI、UPHY、载板定制、BSP、tegra-xusb

BSP与板级支持 0 次安装 0 次浏览 更新于 9/6/2026
名称 jetson-customize-usb
描述 通过内核设备树覆盖层启用/禁用 Jetson USB2/USB3 SS 端口。请勿用于 UPHY 通道分配或 ODMDATA 修改。
版本 0.0.1
开源协议 “Apache-2.0” metadata: data-classification: public
作者 “Jetson Team” tags: - bsp - phase-2 - io - usb domain: meta

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

目的

在 Jetson Thor (Tegra264) 或 Orin (Tegra234) 定制载板上启用、禁用或更改 USB2 / USB3 SS 端口角色。捕获每端口接线（角色、最大速率、VBUS-EN / OC GPIO、Type-C 的 CC1/CC2 GPIO、USB3 SS UPHY 通道），从当前内核 DTB 中解析 SS 到 USB2 从属端口关系，然后生成一个自包含的内核设备树 overlay，以一锁步（lane 状态、端口状态、host xHCI phys + phy-names）在三个位置翻转每个端口操作。

UPHY 通道分配属于 jetson-customize-uphy。不进行 ODMDATA 编辑。输出是对 bsp_sources/ 硬件仓库中复合自定义 overlay .dts 的一个提交。

先决条件

  • 活动配置包含 reference_devkit: 与 custom_carrier: 块。
  • 存在 <source.root_path>/Linux_for_Tegra/.git（/jetson-init-source）。
  • 已运行 /jetson-derive-carrier —— overlay 跟踪器中的 carrier flash-conf 分叉。
  • 当任何启用的 USB3 SS 端口需要非标准的 UPHY 通道分配时，需运行 /jetson-customize-uphy。其 JSON sidecar 位于 <workspace>/target-platform/<profile-stem>.jetson-customize-uphy.json，用于查询 SS 通道分配。
  • 真值文档：适配指南 §“移植通用串行总线”、模块设计指南 §USB、SoC TRM (xusb 块)。
  • 当存在 custom_carrier: 时，documents.custom_carrier_schematic 和 documents.custom_carrier_pinmux_xls 均必需。 如果任一缺失则拒绝运行 —— 定制载板上的每端口布线（VBUS-EN / OC / CC GPIO、SS 通道布线、集线器扇出）无法猜测。仅参考开发套件（reference-devkit-only）配置跳过此检查。
  • dtc、fdtoverlay 在 PATH 中。

概述

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

每端口翻转必须同时触碰内核设备树中的三个位置。 缺少任何一个都会导致 host xHCI 探测崩溃，并使所有端口（包括原本正常的端口）lsusb 为空（附带损坏）：

# 位置 路径 控制内容
1 Lane（PHY 提供者） xusb_padctl/pads/usb<2|3>/lanes/usb<2|3>-N SS / OTG PHY 硬件绑定。status="disabled" 后该 lane 停止提供 PHY。
2 端口（控制器绑定） xusb_padctl/ports/usb<2|3>-N 每端口模式（host/device/otg）、从属连接、VBUS / OC / CC 引脚引用。status="disabled" 后端口从用户可见拓扑中移除。
3 主机 xHCI phys-list bus@0/usb@<addr>.phys + .phy-names xHCI 驱动迭代的 phandle 与名称数组。引用已禁用 PHY 返回 -ENODEV 并使整个主机探测中止。

NVIDIA 在 Thor 基础 DTB 中默认禁用的 usb3-3 是典型模式 —— 三个位置同步翻转。

顶部还有两条附加规则叠加在三位置模式上：

  • 规则 A — lane 与端口配对。 Lane（位置 1）和匹配端口（位置 2）必须同时翻转。
  • 规则 B — 从属级联。 xusb_padctl/ports/usb3-N.nvidia,usb2-companion 引用一个 USB2 端口 phandle。如果禁用该 USB2 而不级联到其 SS 从属端口，则会导致 tegra-xusb: failed to enable PHYs: -19。

智能体驱动，而非表驱动 —— 每个端口、控制器、lane、从属连接、phandle 和 __symbols__ 查找都在运行时从文档 + DTB + carrier pinmap + 原理图解析。

何时调用

  • 用户说“启用 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 通道，每端口设备树现在需要跟进。

流程（摘要）

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

  1. 步骤 1 — 解析活动目标 + 打开真值文档。
  2. 步骤 2 — 从当前内核 DTB 构建 USB 拓扑 + 从属连接图。
  3. 步骤 3 — AskUserQuestion 询问要启用 / 禁用的端口；显式呈现从属级联和板上集线器扇出。
  4. 步骤 4 — 每端口验证（模块 + 载板 + UPHY 通道）并通过 pin_verifier.py 捕获接线（VBUS-EN / OC / CC GPIO）。
  5. 步骤 5 — 使用三位置模式渲染内核设备树 overlay，将片段（usb:padctl、usb:xhci、可选 usb:xudc）附加到复合自定义 overlay .dts，运行 fdtoverlay + 三个合并后不变式，提交到 bsp_sources/。
  6. 步骤 6 — 写入运行状态 JSON sidecar（格式见 references/run-state-sidecar.md），发布标题，然后通过按顺序的 AskUserQuestion 提示驱动下游下一步链，如 references/procedure.md 步骤 6 所述。绝不要用打印的“下一步：……”行替代这些提示。

参见 references/gotchas.md 了解承重失效模式。

限制

  • 仅拥有内核设备树 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 负责构建和 flash-conf 注册。
  • Tegra 平台不变式：只有 usb2-0 支持 OTG；xudc 仅附加到该端口。所有其他 USB2 端口和所有 USB3 SS 端口仅主机模式。

疑难解答

  • 所有端口 lsusb 为空，USB-eth 在 192.168.55.1 仍然存在： host xHCI 退出；三位置锁步被破坏。检查合并后的 DTB；验证 references/procedure.md 步骤 5d 中的合并后不变式。
  • tegra-xusb: failed to enable PHYs: -19： 从属级联（规则 B）被违反 —— 禁用了 USB2 而没有其 SS 从属端口。
  • no port found 或 Requested PHY is disabled： 规则 A 被违反 —— lane 状态和端口状态不匹配。
  • fdtoverlay 报 FDT_ERR_NOTFOUND： 某个片段使用了 target = <&label>，但该节点的标签不在 __symbols__ 中（通常用于 host xHCI / tegra-xudc）。改用 target-path = "/bus@0/usb@<addr>"。
  • dtc 警告 phys_property: cell 0 is not a phandle reference： 良性；在 host phys 覆盖中使用原始整数 phandle 时预期出现。
  • 端口启动但 VBUS 始终未生效： vbus-supply 引用了不存在的 regulator 父节点。在引用之前确保固定 regulator 节点存在。
  • xHCI 启动时绑定了错误端口： host 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 — documents: 块，被步骤 1 使用。
  • ../../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 仓库。