jetson-customize-pcie

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Customize PCIe (per-controller status / lanes / speed)

自定义PCIe（单控制器状态/通道/速度）

Overview

概述

PCIe on Tegra264 (Thor,

pcie@C0..C5

) and Tegra234 (Orin,

pcie@C0..C10

) is split across multiple controllers that share the UPHY lane pool with USB3 / MGBE / UFS. Each controller's runtime behavior is determined by two surfaces, both required:

Surface	Target	Authoritative for
ODMDATA `pcie@N_status=…` (+ `pcie@N_max-link-speed` , `pcie@N_pcie-mode` , `pcie@N_clk-scheme` , `pcie-cN-endpoint-enable` )	`/pcie/pcie@N` in BPMP DTB	UPHY lane power, refclk gating, controller-side power rails
Kernel-DT overlay on `&pcieN`	`/bus@0/pcie@<addr>` in kernel DTB	Kernel probe, lane width, link speed, RC/EP mode

Skipping the kernel overlay on a disable lets the kernel probe a powered-down PHY (link timeouts in dmesg). Skipping the ODMDATA token on a disable leaves BPMP holding the PHY hot.

Agentic, not table-driven — no controller table, no

questions.json

. Every controller, lane width, schematic-routed receptacle, and authoritative DT node address is discovered at runtime from the docs + DTB + carrier pinmap.

The output is a kernel-DT overlay commit only. Per-controller

fragment@N

blocks are appended to the composite custom overlay

.dts

per

../../references/bsp-customization-kernel-dtb.md

and committed to the

bsp_sources/

hardware repo.

/jetson-build-source

compiles the composite to

.dtbo

and owns its Makefile + flash-conf registration.

This skill MUST NOT edit
ODMDATA="..."
. All ODMDATA tokens (

pcie@N_status=…

pcie@N_max-link-speed

pcie@N_pcie-mode

pcie@N_clk-scheme

pcie-cN-endpoint-enable

, plus the

uphyX-config-N

surface tokens and

UPHY_CONFIG=""

clear) are emitted by

/jetson-customize-uphy

in a single atomic commit on the carrier flash-conf fork. The allocation table this skill consumes from the UPHY sidecar already tells the operator which controllers are

okay

disabled

/ per-lane sized; this skill only translates that table into kernel-DT overlay fragments and verifies that the overlay agrees with the ODMDATA already committed by

customize-uphy

(consistency check in Step 8 — disagreement is reported, not silently fixed).

Tegra264（Thor，

pcie@C0..C5

）和Tegra234（Orin，

pcie@C0..C10

）上的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@N`	UPHY通道供电、参考时钟门控、控制器侧电源轨
基于 `&pcieN` 的Kernel-DT overlay	内核DTB中的 `/bus@0/pcie@<addr>`	内核探测、通道宽度、链路速度、RC/EP模式

如果禁用时跳过内核overlay，内核会尝试探测已断电的PHY（dmesg中会出现链路超时）。如果禁用时跳过ODMDATA参数，BPMP会保持PHY处于热态。

基于智能代理而非表格驱动 — 无控制器表格，无

questions.json

。所有控制器、通道宽度、原理图布线插座、权威DT节点地址均在运行时从文档、DTB和载板引脚映射中自动发现。

输出仅为内核-DT overlay提交。单控制器的

fragment@N

块会附加到复合自定义overlay的

.dts

文件中，遵循

../../references/bsp-customization-kernel-dtb.md

的规范，并提交到

bsp_sources/

硬件仓库。

/jetson-build-source

负责将复合文件编译为

.dtbo

，并管理其Makefile和烧录配置注册。

本Skill严禁修改
ODMDATA="..."
。所有ODMDATA参数（

pcie@N_status=…

、

pcie@N_max-link-speed

、

pcie@N_pcie-mode

、

pcie@N_clk-scheme

、

pcie-cN-endpoint-enable

，以及

uphyX-config-N

层面参数和

UPHY_CONFIG=""

清空指令）均由

/jetson-customize-uphy

在载板烧录配置分支的单次原子提交中生成。本Skill从UPHY辅助文件中获取的分配表已告知操作人员哪些控制器处于

okay

disabled

/指定通道数状态；本Skill仅需将该表转换为内核-DT overlay片段，并验证overlay与

customize-uphy

已提交的ODMDATA一致（步骤8的一致性检查——若不一致则上报，而非静默修复）。

When to invoke

调用场景

The user says "configure PCIe", "enable PCIe controller", "set PCIe num-lanes", "change PCIe link speed", or asks to flip a
```
pcie@N_status
```
token.
A specific PCIe slot or M.2 receptacle doesn't enumerate after flash, OR the link trains at the wrong width / speed.
```
jetson-customize-uphy
```
ran and re-allocated lanes across PCIe controllers (e.g. switched from
```
uphy0-config-7
```
to
```
uphy0-config-6
```
enabling PCIe C3); the per-controller side now needs to be brought up.
```
jetson-customize-mgbe
```
reports the QSFP path is wired but the kernel doesn't probe its PCIe-side companion (rare; XFI configurations).

Prerequisites:

Active profile with
```
reference_devkit:
```
+
```
custom_carrier:
```
blocks.

<source.root_path>/Linux_for_Tegra/.git

exists (

/jetson-init-source

```
/jetson-derive-carrier
```
has run — carrier flash-conf fork is in the overlay tracker.

/jetson-customize-uphy

has run — its JSON sidecar at

<workspace>/target-platform/<profile-stem>.jetson-customize-uphy.json

drives the per-controller

enable

decision.

Source-of-truth docs registered or supplied at prompt: Adaptation Guide, Module Design Guide, SoC TRM.
When
custom_carrier:
is present, both
documents.custom_carrier_schematic
AND
documents.custom_carrier_pinmux_xls
are REQUIRED. Refuse the run if either is missing — routing on a custom carrier cannot be guessed. Reference-devkit-only profiles skip this check.
```
dtc
```
on PATH.

用户提及"配置PCIe"、"启用PCIe控制器"、"设置PCIe通道数"、"修改PCIe链路速度"，或要求修改
```
pcie@N_status
```
参数时。
特定PCIe插槽或M.2插座在烧录后未枚举，或链路协商的宽度/速度不正确时。
```
jetson-customize-uphy
```
已运行并重新分配了PCIe控制器间的通道（例如从
```
uphy0-config-7
```
切换到
```
uphy0-config-6
```
以启用PCIe C3），此时需要完成单控制器层面的配置。
```
jetson-customize-mgbe
```
报告QSFP路径已布线，但内核未探测到其PCIe侧配套设备（罕见情况，XFI配置）。

前置条件：

包含
```
reference_devkit:
```
+
```
custom_carrier:
```
块的活跃配置文件。

<source.root_path>/Linux_for_Tegra/.git

存在（由

/jetson-init-source

生成）。

```
/jetson-derive-carrier
```
已运行——载板烧录配置分支已加入overlay追踪器。

/jetson-customize-uphy

已运行——其JSON辅助文件位于

<workspace>/target-platform/<profile-stem>.jetson-customize-uphy.json

，用于驱动单控制器的

enable

决策。

已注册或在提示时提供权威文档：适配指南、模块设计指南、SoC技术参考手册（TRM）。
当存在
custom_carrier:
时，必须同时提供
documents.custom_carrier_schematic
和
documents.custom_carrier_pinmux_xls
。若任一缺失则拒绝运行——自定义载板的布线无法猜测。仅使用参考开发套件的配置文件可跳过此检查。
```
dtc
```
已添加到PATH环境变量。

Procedure (summary)

流程概述

Full step-by-step walkthrough lives in

references/procedure.md

. High-level flow:

Resolve active target + open source-of-truth documents (incl.
```
<carrier-pinmap>
```
,
```
<ref-dtb>
```
,
```
<uphy-state>
```
). Refuse if
```
<uphy-state>
```
is missing.
Diff PCIe topology — devkit vs custom carrier — by decompiling
```
<ref-dtb>
```
and grepping the schematic for
```
PEX<N>_*
```
net labels.
```
AskUserQuestion
```
(multiSelect) — which controllers to customize.
Per-controller verification: pinmap + schematic +
```
pin_verifier.py
```
for
```
PE<N>_CLKREQ_L
```
,
```
PE<N>_RST_L
```
, optional
```
PE<N>_WAKE_L
```
.
Auto-derive per-controller plan (
```
enable
```
from
```
<uphy-state>
```
,
```
lanes
```
/
```
speed
```
from Adaptation Guide,
```
mode
```
hard-pinned to
```
"rc"
```
) → mandatory confirm-or-customize gate.
Append per-controller
```
fragment@N
```
blocks (marker
```
/* custom-bsp: pcie:pcie@<addr> */
```
) to the composite custom overlay
```
.dts
```
in
```
bsp_sources/
```
. Pre-flight
```
dtc
```
+
```
fdtoverlay
```
. Commit via the workflow's preview gate. Do not edit
ODMDATA
—
```
/jetson-customize-uphy
```
already emitted
```
pcie@N_status=…
```
,
```
pcie@N_max-link-speed
```
,
```
pcie@N_pcie-mode
```
,
```
pcie@N_clk-scheme
```
, and
```
pcie-cN-endpoint-enable
```
in its single atomic ODMDATA commit. This skill only translates the per-controller plan into kernel-DT overlay fragments.
(Step folded into Step 6 — overlay-only emission.)
Cross-check ODMDATA vs overlay consistency. On a contradictory row, stop and ask the user how to recover the two commits. Never run
git reset --hard
autonomously.
Write run-state JSON sidecar at
```
<workspace>/target-platform/<profile-stem>.jetson-customize-pcie.json
```
- summary, then drive the downstream next-step chain via sequential
```
AskUserQuestion
```
  prompts per
```
references/procedure.md
```
  Step 9. Never substitute a printed "Next step: …" line for the prompts.

完整的分步指南请参阅

references/procedure.md

。高层级流程如下：

解析活跃目标并打开权威文档（含
```
<carrier-pinmap>
```
、
```
<ref-dtb>
```
、
```
<uphy-state>
```
）。若
```
<uphy-state>
```
缺失则拒绝运行。
对比PCIe拓扑——通过反编译
```
<ref-dtb>
```
并在原理图中搜索
```
PEX<N>_*
```
网络标签，对比开发套件与自定义载板的差异。
```
AskUserQuestion
```
（多选）——选择需要自定义的控制器。
单控制器验证：引脚映射+原理图+
```
pin_verifier.py
```
验证
```
PE<N>_CLKREQ_L
```
、
```
PE<N>_RST_L
```
、可选的
```
PE<N>_WAKE_L
```
。
自动推导单控制器配置方案（
```
enable
```
状态来自
```
<uphy-state>
```
，
```
lanes
```
/
```
speed
```
来自适配指南，
```
mode
```
固定为
```
"rc"
```
）→ 必须经过确认或自定义环节。
将单控制器的
```
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
```
。本Skill仅需将单控制器配置方案转换为内核-DT overlay片段。
（该步骤已整合到步骤6——仅生成overlay）
交叉检查ODMDATA与overlay的一致性。若出现矛盾项，立即停止并询问用户如何恢复这两次提交。严禁自主执行
git reset --hard
。
在
```
<workspace>/target-platform/<profile-stem>.jetson-customize-pcie.json
```
写入运行状态JSON辅助文件及摘要，然后根据
```
references/procedure.md
```
步骤9的提示，通过连续的
```
AskUserQuestion
```
引导下游后续步骤。严禁用打印的"下一步：…"替代交互提示。

Limitations

限制

Mode hard-pinned to RC. Endpoint mode is only emitted when the operator passes
```
mode_override="ep"
```
in Step 5c.
enable
is derived, not asked. UPHY-allocated controllers are mandatorily
```
okay
```
; non-allocated are mandatorily
```
disabled
```
.
No upstream BSP edits. Output lands in
```
Linux_for_Tegra/
```
+
```
bsp_sources/
```
only.
Pre-flight overlay merge is a sanity check, not the production build.
```
/jetson-build-source
```
is authoritative.
Flash-conf overlay registration is out of scope. Owned by
```
/jetson-build-source
```
Step 5.0a.

模式固定为RC。仅当操作人员在步骤5c中传入
```
mode_override="ep"
```
时，才会生成端点模式配置。
enable
状态为推导值，不接受用户输入。UPHY分配的控制器必须设为
```
okay
```
；未分配的必须设为
```
disabled
```
。
不修改上游BSP。输出仅写入
```
Linux_for_Tegra/
```
+
```
bsp_sources/
```
。
预执行overlay合并仅为 sanity 检查，而非生产构建。
```
/jetson-build-source
```
为权威构建环节。
烧录配置的overlay注册不在本Skill范围内。由
```
/jetson-build-source
```
步骤5.0a负责。

Troubleshooting

故障排查

<uphy-state>
missing → run
```
/jetson-customize-uphy
```
first.
Slot doesn't enumerate after flash → check
```
dmesg | grep pcie
```
; re-verify ODMDATA
```
pcie@<N>_status=okay
```
and the overlay fragment agree (Step 8 table in
```
references/procedure.md
```
).
Link trains at wrong width → confirm UPHY config in
```
<uphy-state>
```
allocates the expected lane count; the kernel fragment's
```
num-lanes
```
must match.
compatible
mismatch → fix the composite root, not the fragment. UEFI plugin-manager silently skips on mismatch.
Contradictory ODMDATA-vs-overlay row → ask the user; do not auto-
```
git reset --hard
```
. See gotchas.
Common pitfalls — see
```
references/gotchas.md
```
(RC pinning, node- address sourcing, stock-disabled controllers, intra-file handoff with
```
jetson-customize-uphy
```
).

<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插件管理器会在不匹配时静默跳过。
ODMDATA与overlay出现矛盾项 → 询问用户；严禁自主执行
```
git reset --hard
```
。参阅注意事项。
常见陷阱 — 请参阅
```
references/gotchas.md
```
（RC模式固定、节点地址来源、默认禁用的控制器、与
```
jetson-customize-uphy
```
的文件内交接）。

References

参考资料

```
references/procedure.md
```
— full nine- step procedure (topology diff, plan derivation, overlay append, ODMDATA cross-check, sidecar).
```
references/gotchas.md
```
— failure modes
- invariants (RC pinning, address sourcing, BPMP handoff).
```
../../scripts/pin_verifier.py
```
— shared HSIO pin verifier (Step 4).

../../references/platform_template.yaml

—

documents:

block consumed by Step 1.

```
../../context/bsp-customization-workflow.md
```
— overlay edit protocol + commit message preview gate.
```
../../references/bsp-customization-kernel-dtb.md
```
— composite overlay filename / skeleton / append protocol.
```
../jetson-customize-uphy/SKILL.md
```
— sibling skill that owns UPHY lane allocation; its sidecar drives the per-controller
```
enable
```
decision.
```
../jetson-customize-pinmux/SKILL.md
```
— sibling skill invoked by Step 4 (with operator confirmation) to fix HSIO pin SFIO mismatches.
```
../jetson-customize-mgbe/SKILL.md
```
— sibling for MGBE controllers; shares the two-surface (ODMDATA
- overlay) pattern.
```
../jetson-derive-carrier/SKILL.md
```
— must run first; produces the carrier flash-conf fork edited in Step 6.
```
../jetson-init-source/SKILL.md
```
— produces the overlay tracker + bsp_sources repo this skill commits into.

```
references/procedure.md
```
— 完整的九步流程（拓扑对比、方案推导、overlay附加、ODMDATA交叉检查、辅助文件）。
```
references/gotchas.md
```
— 故障模式与不变规则（RC模式固定、地址来源、BPMP交接）。
```
../../scripts/pin_verifier.py
```
— 共享HSIO引脚验证工具（步骤4）。

../../references/platform_template.yaml

— 步骤1使用的

documents:

块模板。

```
../../context/bsp-customization-workflow.md
```
— overlay编辑规范+提交信息预览环节。
```
../../references/bsp-customization-kernel-dtb.md
```
— 复合overlay的文件名/框架/附加规范。
```
../jetson-customize-uphy/SKILL.md
```
— 负责UPHY通道分配的兄弟Skill；其辅助文件驱动单控制器的
```
enable
```
决策。
```
../jetson-customize-pinmux/SKILL.md
```
— 步骤4调用的兄弟Skill（需操作人员确认），用于修复HSIO引脚SFIO不匹配问题。
```
../jetson-customize-mgbe/SKILL.md
```
— 针对MGBE控制器的兄弟Skill；采用相同的双层面（ODMDATA + overlay）模式。
```
../jetson-derive-carrier/SKILL.md
```
— 必须先运行；生成步骤6中编辑的载板烧录配置分支。
```
../jetson-init-source/SKILL.md
```
— 生成本Skill提交所需的overlay追踪器和bsp_sources仓库。