mcpField
J
jetson-customize-pcie

jetson-customize-pcie

github.com/nvidia开发3.8k1.1k 次安装今天更新
代码仓库

关于 jetson-customize-pcie

面向 Jetson BSP 开发者的定制技能，用于配置 Tegra264 Thor 和 Tegra234 Orin 的各 PCIe 控制器行为。它根据载板资料和 UPHY 分配数据生成内核设备树覆盖片段，并检查其与另一技能管理的 ODMDATA 是否一致。

主要功能

  1. 01从板级资料发现 PCIe 拓扑
  2. 02推导控制器启用状态与通道设置
  3. 03生成内核设备树覆盖片段
  4. 04使用 dtc 和 fdtoverlay 验证覆盖
  5. 05核对与现有 ODMDATA 的一致性
  6. 06记录运行状态侧车文件

适用场景

  1. 01UPHY 通道重新分配后配置 PCIe 控制器
  2. 02排查刷写后插槽未能枚举的问题
  3. 03调整 PCIe 链路宽度或速度
  4. 04启用已布线的 PCIe 配套路径

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/nvidia/skills --skill jetson-customize-pcie

安装后在 Claude Code 中输入/jetson-customize-pcie确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

BENCHMARK.md
skill-card.md
skill.oms.sig
evals/
evals.json
references/
gotchas.md
procedure.md

详细介绍

自定义 PCIe（每个控制器的状态／通道数／速度）

概述

Tegra264（Thor，[email protected]）和 Tegra234（Orin，[email protected]）上的 PCIe 分布在多个控制器中，这些控制器与 USB3／MGBE／UFS 共用 UPHY 通道池。每个控制器的运行行为由两个配置面共同决定，缺一不可：

配置面目标权威控制项
ODMDATA pcie@N_status=…（以及 pcie@N_max-link-speed、pcie@N_pcie-mode、pcie@N_clk-scheme、pcie-cN-endpoint-enable）BPMP DTB 中的 /pcie/pcie@NUPHY 通道供电、参考时钟门控、控制器侧电源轨
&pcieN 上的内核 DT overlay内核 DTB 中的 /bus@0/pcie@<addr>内核探测、通道宽度、链路速度、RC/EP 模式

禁用控制器时若跳过内核 overlay，内核仍会探测已断电的 PHY（dmesg 中出现链路超时）。禁用控制器时若跳过 ODMDATA token，BPMP 会让 PHY 保持启用状态。

由 Agent 决策，而非查表驱动——没有控制器表，也没有 questions.json。每个控制器、通道宽度、原理图布线的插槽，以及权威 DT 节点地址，都要在运行时根据文档、DTB 和载板引脚映射发现。

输出仅为内核 DT overlay 提交。每个控制器的 fragment@N 块会追加到组合自定义 overlay .dts 中，具体方式参见 ../../references/bsp-customization-kernel-dtb.md， 然后提交到硬件仓库 bsp_sources/。 /jetson-build-source 负责编译组合 overlay 为 .dtbo，并管理其 Makefile 和 flash-conf 注册。

此技能不得编辑 ODMDATA="..."。 所有 ODMDATA token（pcie@N_status=…、pcie@N_max-link-speed、pcie@N_pcie-mode、pcie@N_clk-scheme、pcie-cN-endpoint-enable，以及 UPHY 侧面的 uphyX-config-N token 和用于清除配置的 UPHY_CONFIG=""）均由 /jetson-customize-uphy 在载板 flash-conf fork 上通过一次原子提交写入。此技能使用的 UPHY 侧边栏分配表已经告知操作人员哪些控制器为 okay／disabled 或采用了逐通道配置；此技能只会将该表转换为内核 DT overlay 片段，并验证 overlay 是否与 customize-uphy 已提交的 ODMDATA 一致（第 8 步执行一致性检查——发现不一致时会报告，不会静默修正）。

何时调用

  • 用户说“配置 PCIe”“启用 PCIe 控制器”“设置 PCIe num-lanes”“更改 PCIe 链路速度”，或要求切换 pcie@N_status token。
  • 刷写后某个 PCIe 插槽或 M.2 插槽未枚举，或者链路训练后的通道宽度／速度不正确。
  • jetson-customize-uphy 已运行，并重新分配了 PCIe 控制器之间的通道（例如从 uphy0-config-7 切换到启用 PCIe C3 的 uphy0-config-6）；现在需要启用相应的单控制器配置。
  • jetson-customize-mgbe 报告 QSFP 路径已布线，但内核未探测其 PCIe 侧配套设备（少见；XFI 配置）。

前置条件：

  • 活动配置文件包含 reference_devkit: 和 custom_carrier: 区块。
  • <source.root_path>/Linux_for_Tegra/.git 存在（/jetson-init-source）。
  • /jetson-derive-carrier 已运行——载板 flash-conf fork 已加入 overlay 跟踪器。
  • /jetson-customize-uphy 已运行——其位于 <workspace>/target-platform/<profile-stem>.jetson-customize-uphy.json 的 JSON sidecar 决定每个控制器的 enable 状态。
  • 已注册或在提示词中提供真实来源文档：Adaptation Guide、Module Design Guide、SoC TRM。
  • 存在 custom_carrier: 时，必须同时提供 documents.custom_carrier_schematic 和 documents.custom_carrier_pinmux_xls。 若缺少其中任何一项，必须拒绝运行——不能猜测自定义载板上的布线。仅使用参考开发套件的配置文件可跳过此检查。
  • dtc 位于 PATH 中。

流程（摘要）

完整的分步说明请见 references/procedure.md。高级流程：

  1. 确定当前目标并打开权威文档（包括 <carrier-pinmap>、<ref-dtb>、<uphy-state>）。如果缺少 <uphy-state>，则拒绝继续。
  2. 对比 PCIe 拓扑——开发套件与自定义载板——方法是反编译 <ref-dtb>，并在原理图中搜索 PEX<N>_* 网络标签。
  3. 使用 AskUserQuestion（multiSelect）询问要自定义哪些控制器。
  4. 逐个控制器验证：对 PE<N>_CLKREQ_L、PE<N>_RST_L 及可选的 PE<N>_WAKE_L，使用引脚映射、原理图和 pin_verifier.py 进行验证。
  5. 自动推导每个控制器的方案（根据 <uphy-state> 确定 enable， 根据 Adaptation Guide 确定 lanes / speed，将 mode 硬性固定为 "rc"）→ 必须经过确认或自定义关卡。
  6. 将每个控制器的 fragment@N 块（标记为 /* custom-bsp: pcie:pcie@<addr> */）追加到 bsp_sources/ 中的复合自定义 overlay .dts。预先运行 dtc + fdtoverlay。 通过工作流的预览关卡提交。 不要编辑 ODMDATA — /jetson-customize-uphy 已在其单次原子性 ODMDATA 提交中写入 pcie@N_status=…、pcie@N_max-link-speed、pcie@N_pcie-mode、 pcie@N_clk-scheme 和 pcie-cN-endpoint-enable。 此技能只负责将每个控制器的方案转换为内核 DT overlay 片段。
  7. （此步骤已并入步骤 6 — 仅生成 overlay。）
  8. 交叉检查 ODMDATA 与 overlay 是否一致。若某一行存在矛盾，停止并询问用户如何恢复这两次提交。 切勿自行运行 git reset --hard。
  9. 将运行状态 JSON 旁文件写入 <workspace>/target-platform/<profile-stem>.jetson-customize-pcie.json 并生成摘要，然后按照 references/procedure.md 第 9 步，通过依次发送 AskUserQuestion 提示来推进后续步骤链。 切勿用打印一行“Next step: …”来代替这些提示。

限制

  • 模式硬性固定为 RC。 只有操作人员在步骤 5c 中传入 mode_override="ep" 时，才会生成 Endpoint 模式。
  • enable 由系统推导，不会询问。 分配了 UPHY 的控制器必须为 okay； 未分配的控制器必须为 disabled。
  • 不修改上游 BSP。 输出仅写入 Linux_for_Tegra/ + bsp_sources/。
  • overlay 合并预检仅用于健全性检查，并非生产构建。 /jetson-build-source 才是权威流程。
  • 不负责注册刷写配置中的 overlay。 该工作由 /jetson-build-source 步骤 5.0a 负责。

故障排除

  • 缺少 <uphy-state> → 先运行 /jetson-customize-uphy。
  • 刷写后插槽未枚举 → 检查 dmesg | grep pcie； 重新验证 ODMDATA 中的 pcie@<N>_status=okay 与 overlay 片段是否一致 （参见 references/procedure.md 中的步骤 8 表格）。
  • 链路训练后的宽度不正确 → 确认 <uphy-state> 中的 UPHY 配置分配了预期的通道数；内核片段中的 num-lanes 必须一致。
  • compatible 不匹配 → 修正复合根节点，而不是片段。UEFI plugin-manager 会在不匹配时静默跳过。
  • ODMDATA 与 overlay 行矛盾 → 询问用户；不要自动运行 git reset --hard。参见注意事项。
  • 常见陷阱 — 请参见 references/gotchas.md（RC 固定、节点地址来源、默认禁用的控制器，以及与 jetson-customize-uphy 在同一文件中的交接）。

参考资料

评论

支持 Markdown