jetson-customize-uphy

自定义 UPHY 通道分配

用途

为 Jetson 自定义载板选择 UPHY 通道分配，并编辑载板 flash-conf 分支中的 ODMDATA="..."，以应用所选的 uphyX-config-N 令牌（以及 uphy0-config-6 所需的 UPHY_CONFIG="" 清除操作）。这里不进行逐控制器的内核 DT 对齐——ODMDATA 提交完成后，此技能会分发到各个控制器技能（/jetson-customize-pcie、/jetson-customize-mgbe、/jetson-customize-usb），每个技能都必须逐节点比较所选分配与参考内核 DTB，并且仅当 K-stock 值与所选分配不一致时才生成覆盖片段。发现过程由 Agent 完成：选项、通道和控制器在运行时从 Adaptation Guide、载板原理图以及 Module / SoC TRM 获取，绝不硬编码。每个用户可见步骤都以 Markdown 表格呈现数据，最终摘要包含更改摘要表。

前提条件

• 已激活的目标平台配置文件，包含 reference_devkit: 和 custom_carrier:。
• <source.root_path>/Linux_for_Tegra/.git 已初始化（/jetson-init-source）。
• 已存在派生的载板 conf（/jetson-derive-carrier）。
• 可通过 documents.adaptation_guide -> documents.bsp_developer_guide -> 网页获取 -> 第 1 步提示词回退路径访问 Adaptation Guide。
• **存在 custom_carrier: 时，必须同时提供 documents.custom_carrier_schematic 和 documents.custom_carrier_pinmux_xls。**如果缺少任一项，技能将拒绝运行——无法猜测自定义载板的路由决策。仅含参考开发套件的配置文件（没有 custom_carrier: 块）无需提供这些文件。

概述

UPHY（统一 PHY）是 Tegra264（Thor）和 Tegra234（Orin）上的共享高速 PHY 池。通过 ODMDATA 令牌（uphy0-config-N，Thor 还包括 uphy1-config-N）选择通道分配；这些令牌会在刷写时由 tegraflash_impl_t264.py::tegraflash_update_bpmp_dtb() 解析，并写入 BPMP DTB 的 /uphy/uphy{0,1}-config。

输出是在 <source.root_path>/Linux_for_Tegra/ 中进行的一次原子 ODMDATA 提交，包含所选的 uphyX-config-N 令牌、UPHY_CONFIG="" 清除操作（针对 uphy0-config-6），以及从所选分配推导出的所有逐控制器 ODMDATA 令牌（pcie@N_status=*、mgbeN-speed-*、USB SS 逐端口令牌）。子技能（/jetson-customize-pcie、/jetson-customize-mgbe、/jetson-customize-usb）仅负责内核 DT 覆盖片段——绝不能修改 ODMDATA。所有提交均遵循 ../../context/bsp-customization-workflow.md 中批量处理的 pristine + customization 模式。绝不修改 <bsp_image.root_path>/ 下的上游 BSP。

何时调用

• 用户说“配置 UPHY”“UPHY 通道分配”“设置 uphy0-config-N”“更改 MGBE 速度”，或要求在自定义载板上重新映射 PCIe / MGBE / USB3 / UFS。
• 刷写后，UPHY 驱动的控制器未枚举，或者冷启动在 BL31 SError / BPMP firmware is not ready 处失败。
• 下游技能报告 FMON 故障或 BPMP-DTB 通道不匹配。

流程（摘要）

共八个步骤；完整详情见 references/procedure.md。

1. 解析目标和文档。 若没有活动配置文件、自定义载板、源代码树 Git 或派生的载板配置，则拒绝执行。解析 Adaptation Guide / schematic / Module Design Guide / SoC TRM。

2. 在 Adaptation Guide（PDF / HTML 镜像 / WebFetch）中查找“Configure the UPHY Lane”。与 Module Design Guide 和 SoC TRM 交叉核对。

3. 交叉参考载板原理图。 引用 UPHY 网络名称（MGBE2_TX_P/N、PEX5_LN0+- 等）。匹配网络数为零 = 未布线。

4. 枚举匹配的 UPHY 选项。 列出所有有文档记录的 uphy0-config-N（Thor 还包括 uphy1-config-N）索引。

5. 询问用户选择哪种配置（硬性门槛）。 先打印表格，然后调用 AskUserQuestion——每个 UPHY 面各一次；若有已分配的通道未布线，还要确认载板布线情况。将答案保存到 JSON 旁置文件（references/run-state-sidecar.md）。

6. 编辑载板 flash-conf 派生文件（以原子方式提交 ODMDATA）。 本技能负责本次运行中的所有 ODMDATA 令牌。只允许一行 ODMDATA="..."，只提交一次，包含所有令牌。子技能不得修改 ODMDATA。

   反编译以下路径中的 BPMP DTB，以快照记录原始状态： <bsp_image.root_path>/Linux_for_Tegra/bootloader/generic/<BPFDTB_FILE> （BPFDTB_FILE 来自载板配置），然后按以下顺序生成令牌：

   a. UPHY 面令牌——每个已选定的 uphyX-config-N（Thor：两个面都要写入，即使其中一个与指南默认值相同）。 按 uphy0、再 uphy1 的顺序排列；分隔符为 ,。 b. 每控制器令牌——计划状态与 BPMP 原始状态不同的每一行各一个。匹配的行不需要令牌（冗余令牌可能导致整行被删除）。

   • PCIe：pcie@N_status=okay|disabled。
   • MGBE：分配时使用 mgbeN-speed-<rate>，禁用时使用 mgbeN-speed-del。无论是否分配 UPHY，FMON 都会在控制器自身的时钟上启用——缺少 del ⇒ BL31 SError 重启循环。这是 Thor 刷写后最常见的故障。
   • USB SS：当 SoC 语法支持时，使用每端口令牌。 c. 当选中 uphy0-config-6 时，清除 UPHY_CONFIG=""（根据 Adaptation Guide 清除 BCT pinmux）。

7. 构建每控制器分配表并派发任务。 为每个由 UPHY 驱动的控制器（PCIe / MGBE / USB SS / UFS）生成一行，包含 {class, instance, allocated?, BPMP-stock, K-stock, routed?, Desired K state}。此表同时用于 (a) 第 6 步的 ODMDATA 令牌和 (b) 子技能的 overlay 片段——必须在第 6 步提交前构建。

   然后调用 /jetson-customize-pcie、/jetson-customize-mgbe 和 /jetson-customize-usb，仅生成 kernel-DT overlay 片段（不得编辑 ODMDATA——该行由第 6 步负责）。每个子技能都会重新从 <bsp_image.root_path>/Linux_for_Tegra/kernel/dtb/tegra<soc>-*-nv.dtb 读取 K-stock；如果 K-stock 与 Desired K state 相同，则跳过生成。UFS 处理仍在此处内联完成（不使用 UFS 子技能）。

   只要 SoC 上存在相应控制器类别，就调用这三个子技能（例如 Orin 上跳过 MGBE）。先询问操作员；收到 yes 后，在当前流程中运行子技能。

8. 摘要和后续步骤链。 包括标题、详细说明、选择表（UPHY 面 | 所选配置 | 通道摘要 | 是否清除 UPHY_CONFIG）、更改摘要表（文件 | 仓库 | 提交 SHA | 一行摘要，涵盖本技能的提交和每个已派发子技能的提交），然后通过 references/procedure.md 第 8 步中依次发起的 AskUserQuestion 提示，推进后续流程（更多 I/O？构建并晋级？刷写？验证？）。绝不可用打印的“下一步：……”替代这些提示。

局限

• 仅支持 Tegra234（Orin）和 Tegra264（Thor）的 UPHY 接口。
• 不会编辑 pinmux、BPMP DTB 中缺失的 PCIe 专属 DT 属性（num-lanes、pcie-mode），也不会编辑上游 BSP 文件。
• 不会刷写、构建或晋升——请串联 /jetson-build-source 和下游技能。
• 禁止使用硬编码的选项表；如果无法从 Adaptation Guide 中找到来源，该技能会拒绝操作，而不是猜测。
• 不会跨版本使用表驱动方式：每次运行都会重新读取当前 BSP 版本对应的 Guide。

故障排查

• 冷启动后陷入重启循环 / BL31 plat_setup.c:726 / BPMP firmware is not ready，出现在 uphy0-config-6 之后：载板配置文件中后续的 ^UPHY_CONFIG= 行重新覆盖了清除操作。将其注释掉（参见 references/procedure.md 第 6 步）。
• 刷写时出现 wait-for-device failed，且 BPMP DTB 未更改：某个 ODMDATA 令牌格式错误（例如 mgbe0-speed-0）。一个错误令牌就会导致整行 ODMDATA="..." 被丢弃。请检查 references/procedure.md 中的语法。
• 禁用 MGBE 后 BL31 出现 SError 并陷入重启循环：缺少 mgbeN-speed-del。无论 UPHY 分配如何，FMON 都会基于控制器自身时钟启动。
• 新布线的控制器未枚举：默认内核 DTB 中的 status="disabled"。Overlay 必须设置 status="okay"（references/procedure.md 中的矩阵第 4 行）。
• Pinmap 差异为 0，但板卡仍然异常：UPHY 差分对未包含在 pinmux .xlsm 文件中。应依据原理图中的网络名称做出判断，而不是依据 pinmap。
• 出现重复的 pcie@<addr> 片段：另一个技能（jetson-customize-pcie）已负责该节点。此技能应仅处理 MGBE / UFS / USB3 SS / 仅 PCIe 状态，并引用另一个 Overlay。

参考资料

• references/procedure.md — 完整的八步流程。
• references/gotchas.md — 跨领域注意事项。
• references/run-state-sidecar.md — JSON sidecar 架构和幂等性。
• ../../references/platform_template.yaml — documents: 架构。
• ../../context/bsp-customization-workflow.md — Overlay 编辑协议。
• ../../references/bsp-customization-kernel-dtb.md — 复合 Overlay 文件名和追加协议。
• ../jetson-derive-carrier/SKILL.md — 生成此技能要编辑的配置文件。
• ../jetson-init-source/SKILL.md — 生成此技能要提交到的两个 git 仓库。
• ../jetson-generate-kb/SKILL.md — 查询芯片系列和文件位置的知识库。