用途:在 Jetson Thor(Tegra264)或 Orin(Tegra234)的自定义载板上,按端口启用、禁用或更改 USB2 / USB3 SS 端口的角色。它会记录每个端口的接线信息(角色、最大速率、VBUS-EN / OC GPIO、Type-C 的 CC1/CC2 GPIO、USB3 SS UPHY 通道),从源码树内 DTB 解析 SS 与 USB2 伴随(companion)关系,然后生成自包含的内核设备树 overlay,在三处同步翻转端口动作(lane 状态、port 状态、host xHCI 的 phys + phy-names)。UPHY 通道分配由 jetson-customize-uphy 负责,本技能不编辑 ODMDATA,输出为对 bsp_sources/ 硬件仓库中复合自定义 overlay .dts 的一次提交。
主要能力与规则:每次端口翻转必须同步修改三处内核 DT,否则 host xHCI 探测会崩溃、所有端口 lsusb 为空。规则 A:lane 与对应 port 必须一起翻转;规则 B:禁用 USB2 端口时若被其 USB3 SS 伴随引用,需级联处理,否则报 tegra-xusb: failed to enable PHYS: -19。所有端口、控制器、lane、伴随链接、phandle 与 symbols 查找均在运行时依据文档、DTB、载板 pinmap 与原理图解析,而非表驱动。
使用条件:需具备带 reference_devkit: 与 custom_carrier: 块的活跃 profile;<source.root_path>/Linux_for_Tegra/.git 存在;已运行 /jetson-derive-carrier;当已启用的 USB3 SS 端口需要非标准 UPHY 通道分配时需先运行 /jetson-customize-uphy;PATH 中有 dtc、fdtoverlay。存在 custom_carrier: 时,custom_carrier_schematic 与 custom_carrier_pinmux_xls 均为必需,缺失则拒绝运行;仅参考开发板的 profile 跳过此检查。
适用场景:用户要求启用/禁用 USB、配置 USB3 SS、设置 USB 角色、接 VBUS-EN、处理 tegra-xusb / xudc / dr_mode,或在自定义载板上拉起/关闭 USB 控制器;载板 USB 口烧录后不枚举,或此前 jetson-customize-usb 尝试造成连带 USB 损坏(lsusb 空)需修复;jetson-customize-uphy 重新分配 UPHY 通道影响 USB3 SS 端口后需跟进端口 DT。
限制:仅负责内核 DT overlay;不分配 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 均为 host-only。完整步骤见 references/procedure.md,失败模式见 references/gotchas.md。