jetson-customize-mgbe

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Customize MGBE / 25G QSFP

定制MGBE / 25G QSFP

Overview

概述

Thor T264 exposes mgbe0..mgbe3. On a custom carrier, the 25G QSFP cage (or 10G / 1G fiber path) is wired to one of them through SerDes — with or without an external MDIO PHY in front of the cage. This skill renders the kernel-DT overlay that pairs the BPMP allocation with kernel-side

status="okay"

+ PHY plumbing on

&mgbeN

Out of scope:

UPHY lane allocation — owned by
```
/jetson-customize-uphy
```
. Refuse if the chosen
```
uphy1-config-N
```
doesn't allocate the target MGBE.
All ODMDATA tokens (
```
mgbeN-speed-*
```
, sub-node
```
mgbeN_status=*
```
) — owned by
```
/jetson-customize-uphy
```
in its single atomic ODMDATA commit. This skill MUST NOT touch
```
ODMDATA=
```
.

Output is one commit to the composite custom overlay

.dts

in the

bsp_sources/

hardware repo.

/jetson-build-source

compiles the composite to

.dtbo

and owns its Makefile + flash-conf registration.

Thor T264暴露了mgbe0..mgbe3接口。在自定义载板上，25G QSFP笼（或10G/1G光纤通路）通过SerDes连接到其中一个接口，笼前可带或不带外部MDIO PHY。本Skill生成内核DT overlay，将BPMP分配与内核侧

status="okay"

配置以及

&mgbeN

上的PHY设置进行配对。

超出范围：

UPHY通道分配 — 由
```
/jetson-customize-uphy
```
负责。如果所选的
```
uphy1-config-N
```
未分配目标MGBE接口，请拒绝执行。
所有ODMDATA令牌（
```
mgbeN-speed-*
```
、子节点
```
mgbeN_status=*
```
） — 由
```
/jetson-customize-uphy
```
在其原子性ODMDATA提交中处理。本Skill绝对不能修改
```
ODMDATA=
```
。

输出结果是向

bsp_sources/

硬件仓库中的复合自定义overlay

.dts

文件提交一次变更。

/jetson-build-source

负责将复合文件编译为

.dtbo

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

When to invoke

调用时机

The user says "enable 25G", "configure QSFP", "set MGBE PHY mode", "wire MGBE to QSFP", or asks to bring up a 10G / 1G fiber path.
Cold boot succeeds but
```
ip link show mgbe<N>
```
reports
```
state DOWN
```
or
```
NO-CARRIER
```
on the configured controller, OR the controller never appears at all.
```
jetson-customize-uphy
```
ran with
```
uphy1-config-8
```
(or another config allocating MGBE) and you now need to bring up the per-controller side.

Prerequisites:

Active profile selected with
```
reference_devkit:
```
(Thor) +
```
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
```
chose a UPHY config that allocates the target MGBE controller's lanes (
```
uphy1-config-8
```
on Thor for MGBE0..3 25G).
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 — MGBE routing on a custom carrier cannot be guessed. Reference-devkit-only profiles skip this check.
```
dtc
```
on PATH.

用户提及“启用25G”、“配置QSFP”、“设置MGBE PHY模式”、“将MGBE连接到QSFP”，或询问如何启用10G/1G光纤通路时。
冷启动成功，但
```
ip link show mgbe<N>
```
报告已配置的控制器处于
```
state DOWN
```
或
```
NO-CARRIER
```
状态，或者控制器根本未出现。
```
jetson-customize-uphy
```
已使用
```
uphy1-config-8
```
（或其他分配MGBE的配置）运行，现在需要启用每个控制器的对应功能。

前提条件：

已选择包含
```
reference_devkit:
```
（Thor）和
```
custom_carrier:
```
块的活跃配置文件。

<source.root_path>/Linux_for_Tegra/.git

存在（由

/jetson-init-source

生成）。

```
/jetson-derive-carrier
```
已运行 — 载板烧录配置分支已在overlay跟踪器中。
```
/jetson-customize-uphy
```
已选择分配目标MGBE控制器通道的UPHY配置（Thor平台上的
```
uphy1-config-8
```
用于分配mgbe0..3的25G通道）。
已注册或在提示时提供权威文档：适配指南、模块设计指南、SoC技术参考手册（TRM）。
**当存在
```
custom_carrier:
```
时，必须同时提供
```
documents.custom_carrier_schematic
```
和
```
documents.custom_carrier_pinmux_xls
```
。**如果其中任何一个缺失，请拒绝执行 — 自定义载板上的MGBE路由无法猜测。仅使用参考开发板的配置文件可跳过此检查。
```
dtc
```
工具已在PATH环境变量中。

Procedure

步骤

See

references/procedure.md

for the full step-by-step procedure (Steps 1–8). Summary:

Resolve active target + documents. Validate active profile, custom_carrier, overlay tracker; locate the relevant Adaptation Guide chapter and pinmap.
Per-controller question loop. AskUserQuestion driven by
```
questions.json
```
(controller, phy_mode, attach kind, I²C bus/addr, reset GPIO, compatible_list).
Derive max-speed from phy_mode. Decompile the BPMP DTB to pick sub-node vs top-level token grammar; cite the inspection in notes.
Verify HSIO pins + auto-fix. Run
```
pin_verifier.py
```
for MDC/MDIO/RESET/INT; surface mismatches and route to
```
/jetson-customize-pinmux
```
.
(no ODMDATA edits.) MGBE ODMDATA tokens are emitted by
```
/jetson-customize-uphy
```
. Step 5 only records the BPMP DTB token-form inspection (sub-node vs top-level) in
```
notes[]
```
for audit.
Append composite-overlay fragments. Write one fragment per controller into the composite custom overlay
```
.dts
```
; obey the
```
/* custom-bsp: mgbe:mgbe... */
```
marker contract; run the cpp/dtc/fdtoverlay pre-flight.
(Reserved.) Sibling-skill ordering / cross-cutting validation.
Run-state sidecar + summary + next-step chain. Write
```
<profile-stem>.jetson-customize-mgbe.json
```
and emit the one-line + table summary, then drive the downstream chain via sequential
```
AskUserQuestion
```
prompts per
```
references/procedure.md
```
Step 8. Never substitute a printed "Next step: …" line for the prompts.

完整的分步流程（步骤1-8）请参见

references/procedure.md

。摘要：

确定活跃目标与文档。验证活跃配置文件、自定义载板、overlay跟踪器；找到相关的适配指南章节和引脚映射。
逐控制器提问循环。由
```
questions.json
```
驱动的AskUserQuestion（控制器、phy_mode、连接类型、I²C总线/地址、复位GPIO、兼容列表）。
从phy_mode推导最大速率。反编译BPMP DTB以选择子节点与顶层令牌语法；在备注中记录检查结果。
验证HSIO引脚并自动修复。针对MDC/MDIO/RESET/INT运行
```
pin_verifier.py
```
；显示不匹配项并引导至
```
/jetson-customize-pinmux
```
进行修复。
（不修改ODMDATA） MGBE的ODMDATA令牌由
```
/jetson-customize-uphy
```
生成。步骤5仅将BPMP DTB令牌格式检查（子节点 vs 顶层）记录在
```
notes[]
```
中用于审计。
追加复合overlay片段。为每个控制器向复合自定义overlay
```
.dts
```
文件写入一个片段；遵守
```
/* custom-bsp: mgbe:mgbe... */
```
标记约定；运行cpp/dtc/fdtoverlay预检查。
（预留） 兄弟Skill的执行顺序/跨领域验证。
运行状态辅助文件 + 摘要 + 后续步骤链。写入
```
<profile-stem>.jetson-customize-mgbe.json
```
并生成单行和表格摘要，然后根据
```
references/procedure.md
```
步骤8中的顺序
```
AskUserQuestion
```
提示驱动下游流程。切勿用打印的“下一步：…”替代提示。

Gotchas

注意事项

Stock Thor BPMP DTB has no
/mgbe/mgbe@N
subtree — only
```
mgbe<N>-speed
```
under
```
/uphy
```
. The
```
mgbe<N>_status=disabled
```
sub-node token is silently rejected on these releases; the whole ODMDATA line is then dropped at flash time. Always decompile BPMP DTB (Step 3) before emitting; use the top-level dashed form (
```
mgbe<N>-speed-del
```
to remove,
```
mgbe<N>-speed-25G
```
to set) when the sub-node isn't there. Same wrong-form failure surface as
```
jetson-customize-uphy
```
.
mdio
child needs both
#address-cells = <1>
AND
#size-cells = <0>
when
```
phy_attach_kind=="phy"
```
. Missing either → kernel rejects
```
phy@<addr>
```
reg property at probe; MGBE never comes up.
Overlay root
compatible
must intersect live DT compatible. UEFI plugin-manager filters by compatible match. A mismatched overlay is silently skipped — flash succeeds, MGBE stays disabled, no error in dmesg. Always sanity-check against
```
/proc/device-tree/compatible
```
on a booted reference DUT.
OVERLAY_DTB_FILE
ordering is
jetson-build-source
's problem, not this skill's. This skill never touches the carrier flash conf. The composite custom overlay is registered (by
```
/jetson-build-source
```
Step 5.0a) AFTER the platform
```
*-dynamic.dtbo
```
, which is the correct ordering. If you find yourself appending
```
OVERLAY_DTB_FILE+=
```
in this skill, you're duplicating ownership — stop, and let the build skill do it.
UPHY lane allocation is
jetson-customize-uphy
's job. If the chosen
```
uphy1-config-N
```
doesn't allocate lanes for the target MGBE controller, BL31 SError (
```
fmon_update_config: detected fault 0x80
```
) on cold boot. Always run
```
/jetson-customize-uphy
```
first; cite the chosen
```
uphy1-config-N
```
in this skill's run-summary
```
notes[]
```
.
Don't disable a stock-okay controller via ODMDATA alone. Same rule as
```
jetson-customize-uphy
```
:
```
mgbe<N>_status=disabled
```
for a controller that's already disabled in BPMP DTB is a no-op the parser may treat as ambiguous → drops the rest of the ODMDATA line. Disable via the kernel-DT overlay (
```
status="disabled"
```
) only.
Don't touch the upstream BSP at
<bsp_image.root_path>
. All edits land in the overlay tracker /
```
bsp_sources
```
mono-repo under the pristine + customization commit pattern.
JSON sidecar is structured state, not authoritative. Same caveat as
```
jetson-customize-uphy
```
: ODMDATA + overlay
```
.dts
```
+ two git commits are the device-facing outputs; the sidecar is for tooling and idempotency only.

原生Thor BPMP DTB没有
/mgbe/mgbe@N
子树 — 仅在
```
/uphy
```
下有
```
mgbe<N>-speed
```
。在这些版本中，
```
mgbe<N>_status=disabled
```
子节点令牌会被静默拒绝；随后整个ODMDATA行在烧录时被丢弃。生成令牌前必须始终反编译BPMP DTB（步骤3）；当子节点不存在时，使用顶层短横线格式（
```
mgbe<N>-speed-del
```
用于移除，
```
mgbe<N>-speed-25G
```
用于设置）。与
```
jetson-customize-uphy
```
存在相同的格式错误风险。
当
phy_attach_kind=="phy"
时，
mdio
子节点需要同时设置
#address-cells = <1>
和
#size-cells = <0>
。缺少其中任何一个 → 内核在探测时会拒绝
```
phy@<addr>
```
的reg属性；MGBE永远无法启用。
Overlay根节点的
compatible
必须与当前DT的compatible相交。UEFI插件管理器会根据compatible匹配进行过滤。不匹配的overlay会被静默跳过 — 烧录成功，但MGBE保持禁用，dmesg中无错误。始终在已启动的参考DUT上针对
```
/proc/device-tree/compatible
```
进行 sanity 检查。
OVERLAY_DTB_FILE
的顺序是
jetson-build-source
的职责，而非本Skill。本Skill永远不会修改载板烧录配置。复合自定义overlay由
```
/jetson-build-source
```
步骤5.0a注册，且在平台
```
*-dynamic.dtbo
```
之后，这是正确的顺序。如果您发现自己在本Skill中添加
```
OVERLAY_DTB_FILE+=
```
，则是重复了职责 — 请停止，让构建Skill处理此事。
UPHY通道分配是
jetson-customize-uphy
的职责。如果所选的
```
uphy1-config-N
```
未为目标MGBE控制器分配通道，冷启动时会出现BL31 SError（
```
fmon_update_config: detected fault 0x80
```
）。必须先运行
```
/jetson-customize-uphy
```
；在本Skill的运行摘要
```
notes[]
```
中记录所选的
```
uphy1-config-N
```
。
不要仅通过ODMDATA禁用原生已启用的控制器。与
```
jetson-customize-uphy
```
相同的规则：对于已在BPMP DTB中禁用的控制器，设置
```
mgbe<N>_status=disabled
```
是无效操作，解析器可能将其视为歧义 → 丢弃ODMDATA行的其余部分。仅通过内核DT overlay（
```
status="disabled"
```
）进行禁用。
不要修改
<bsp_image.root_path>
下的上游BSP。所有修改都应在overlay跟踪器 /
```
bsp_sources
```
单仓库中，遵循原始提交 + 定制提交的模式。
JSON辅助文件是结构化状态，而非权威来源。与
```
jetson-customize-uphy
```
相同的警告：ODMDATA + overlay
```
.dts
```
+ 两次git提交是面向设备的输出；辅助文件仅用于工具和幂等性。

References

参考资料

```
questions.json
```
— Q-1..Q-8 prompt schema consumed by Step 2.
```
../../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 (batched pristine + customization commit).
```
../jetson-customize-uphy/SKILL.md
```
— sibling skill that owns UPHY lane allocation. Must run before this skill to set
```
uphy1-config-N
```
for MGBE-allocated configurations.
```
../jetson-customize-pinmux/SKILL.md
```
— sibling skill invoked by Step 4 (with operator confirmation) to fix pin SFIO mismatches.
```
../jetson-derive-carrier/SKILL.md
```
— must run first; produces the carrier flash-conf fork edited in Step 5 and the carrier base overlay this skill orders after.
```
../jetson-init-source/SKILL.md
```
— produces the overlay tracker + bsp_sources repo this skill commits into.

```
questions.json
```
— 步骤2使用的Q-1..Q-8提示 schema。
```
../../scripts/pin_verifier.py
```
— 步骤4使用的共享HSIO引脚验证工具。

../../references/platform_template.yaml

— 步骤1使用的

documents:

块。

```
../../context/bsp-customization-workflow.md
```
— overlay编辑协议（批量原始提交 + 定制提交）。
```
../jetson-customize-uphy/SKILL.md
```
— 负责UPHY通道分配的兄弟Skill。必须在本Skill之前运行，以设置分配MGBE的
```
uphy1-config-N
```
配置。
```
../jetson-customize-pinmux/SKILL.md
```
— 步骤4调用的兄弟Skill（需操作员确认），用于修复引脚SFIO不匹配问题。
```
../jetson-derive-carrier/SKILL.md
```
— 必须先运行；生成步骤5中编辑的载板烧录配置分支，以及本Skill依赖的载板基础overlay。
```
../jetson-init-source/SKILL.md
```
— 生成本Skill提交变更所用的overlay跟踪器 + bsp_sources仓库。",