⚡

JetsonUPHY自定义配置Skill jetson-customize-uphy

本技能用于在Jetson Orin/Thor定制载板上配置UPHY通道分配。它通过编辑载板flash-conf分支中的ODMDATA（如uphy0-config-N、uphy1-config-N）实现，包括文档解析、通道选项枚举、用户确认、原子ODMDATA提交，并派发PCIe/MGBE/USB等子技能生成内核DT overlay片段。同时提供限制说明和故障排查指引。关键词：UPHY, Jetson, Orin, Thor, ODMDATA, 载板定制, BSP, 通道分配, PCIe, MGBE, USB, UFS, uphy0-config, uphy1-config

BSP与板级支持 0 次安装 0 次浏览 更新于 9/6/2026
名称 jetson-customize-uphy
描述 在Orin/Thor定制载板上配置Jetson UPHY通道分配（uphy0/uphy1-config）。不要用于引脚复用或纯PCIe修改。
版本 0.0.2
开源协议 “Apache-2.0” metadata: data-classification: public
作者 “Jetson Team” tags: - bsp - phase-2 - io - uphy domain: meta

自定义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值与所选分配不一致时发出overlay片段。发现过程是智能体式的：选项、通道和控制器来自适配指南、载板原理图以及模组/SoC TRM，在运行时确定——绝不硬编码。每个面向用户的步骤都以Markdown表格形式呈现数据，最终摘要包含变更汇总表。

先决条件

  • 活动目标平台配置文件中包含reference_devkit:和custom_carrier:。
  • <source.root_path>/Linux_for_Tegra/.git已初始化（/jetson-init-source）。
  • 已存在Forked载板配置（/jetson-derive-carrier）。
  • 可通过documents.adaptation_guide -> documents.bsp_developer_guide -> 网络获取 -> 步骤1提示回退，访问到适配指南。
  • 当存在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 overlay片段——它们绝不能改动ODMDATA。所有提交遵循../../context/bsp-customization-workflow.md中的“批量原始+定制”模式。上游BSP位于<bsp_image.root_path>/，从不编辑。

何时调用

  • 用户说“配置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或forked载板配置，则拒绝执行。解析适配指南 / 原理图 / 模块设计指南 / SoC TRM。

  2. 在适配指南中定位“Configure the UPHY Lane”（PDF / HTML镜像 / WebFetch）。并交叉核对模块设计指南和SoC TRM。

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

  4. 枚举匹配的UPHY选项。 展示所有记录的uphy0-config-N（Thor还有uphy1-config-N）索引。

  5. 询问用户选择哪个配置（硬性门禁）。 首先打印表格，然后AskUserQuestion——每个UPHY表面一个，且如果任何分配的通道未布线则需载板布线确认。将答案持久化到JSON sidecar（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**。FMON始终在控制器自己的时钟上布防，与UPHY分配无关——缺少del ⇒ BL31 SError重启循环。这是Thor上最常见的烧写后故障。
    • USB SS：当SoC语法暴露每端口标记时使用。 c. UPHY_CONFIG=""清除当选择了uphy0-config-6时（根据适配指南进行BCT引脚复用清除）。

  7. 构建每控制器分配表并分派。 为每个UPHY供应的控制器（PCIe / MGBE / USB SS / UFS）派生一行，包含{类别, 实例, 已分配?, BPMP库存, K库存, 已布线?, 期望K状态}。该表同时驱动(a)第6步的ODMDATA标记和(b)子技能的overlay片段——在第6步提交之前构建它。

    然后调用/jetson-customize-pcie、/jetson-customize-mgbe和/jetson-customize-usb仅用于内核DT overlay片段（不做ODMDATA编辑——第6步拥有该行）。每个子技能从<bsp_image.root_path>/Linux_for_Tegra/kernel/dtb/tegra<soc>-*-nv.dtb重新读取K库存，当K库存与期望K状态匹配时跳过发出。UFS处理保持内联此处（无UFS子技能）。

    当控制器类别在此SoC上存在时，调用所有三个（例如在Orin上跳过MGBE）。先询问操作员；若yes，则内联运行该子技能。

  8. 摘要+下一步链。 标题、细分、选择表（UPHY表面 | 所选配置 | 通道摘要 | UPHY_CONFIG清除）、变更摘要表（文件 | 仓库 | 提交SHA | 单行摘要，涵盖此技能的提交+每个派发子技能的提交），然后根据references/procedure.md第8步通过连续AskUserQuestion提示驱动下游链（更多I/O？构建与提升？烧写？验证？）。绝不要用打印出的“下一步：…”行替代提示。

限制

  • 仅支持Tegra234 (Orin)和Tegra264 (Thor)的UPHY表面。
  • 不编辑引脚复用、BPMP DTB中不存在的纯PCIe DT属性（num-lanes、pcie-mode）或上游BSP文件。
  • 不烧写、不构建、不提升——请链接到/jetson-build-source及下游技能。
  • 禁止硬编码选项表；如果没有适配指南源可供解析，技能会拒绝执行而不是猜测。
  • 不支持跨版本的表驱动：每次运行都会针对活动BSP版本重新读取指南。

故障排查

  • 在uphy0-config-6之后冷启动重启循环 / BL31 plat_setup.c:726 / BPMP firmware is not ready：载板配置中后面的一行^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。FMON在控制器自己的时钟上布防，与UPHY分配无关。
  • 新布线的控制器无法枚举：库存内核DTB中为status="disabled"。Overlay必须发出status="okay"（见references/procedure.md中的矩阵第4行）。
  • Pinmap delta=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 — 为芯片系列+文件位置咨询的知识库。