Jetson MGBE 25G QSFP 定制

问题背景

在 NVIDIA Jetson Thor（T264） 上，SoC 会暴露 mgbe0～mgbe3 四个 MGBE 控制器。定制载板若走 25G QSFP（或 10G/1G 光纤通路），SerDes 会接到其中一路；笼前可能有外部 MDIO PHY，也可能没有。冷启动能过，但 ip link show mgbe* 常出现 state DOWN / NO-CARRIER，或控制器在设备树里根本未启用——这通常不是「网线没插好」，而是 BPMP 侧分配与内核侧 status="okay" + &mgbeN 上的 PHY 描述没有对齐。

本技能不负责 UPHY 通道分配，也不编辑任何 ODMDATA 令牌（mgbeN-speed-*、mgbeN_status=* 等由 /jetson-customize-uphy 在单一原子 ODMDATA 提交里处理）。它的产出是：向 bsp_sources/ 硬件仓库中的复合定制叠加 .dts 追加片段，形成一次 git 提交；.dtbo 编译与烧录注册由 /jetson-build-source 负责。

技能如何工作

运行前需满足：/jetson-init-source 已就绪、/jetson-derive-carrier 已跑过、且 /jetson-customize-uphy 已选用分配了目标 MGBE 的 uphy1-config-N（例如 Thor 上 uphy1-config-8 对应 MGBE0..3 的 25G）。存在 custom_carrier: 时，载板原理图与 pinmux 表格为硬性输入，缺一则拒绝执行。

核心流程概要：

• 解析配置与文档，核对叠加跟踪器与适配指南、引脚映射。
• 按 questions.json 对每个控制器收集：PHY 模式、连接类型、I²C/复位 GPIO、compatible 等。
• 反编译 BPMP DTB，从 phy_mode 推导速率，并确认令牌应写子节点还是顶层连字符形式（老版本 BPMP 可能没有 /mgbe/mgbe@N 子树）。
• 用 pin_verifier.py 校验 MDC/MDIO/RESET/INT；不匹配时导向 /jetson-customize-pinmux。
• 向复合 .dts 写入带 /* custom-bsp: mgbe:mgbe... */ 约定的片段，并做 cpp/dtc/fdtoverlay 预检。
• 写入 .jetson-customize-mgbe.json 侧车并输出摘要，按 procedure 链式提示下游技能（不要用打印的「下一步」替代 AskUserQuestion）。

边界与坑点

• UPHY 未分配目标 MGBE 时本技能应拒绝；若强行烧录，可能出现 BL31 SError（fmonupdateconfig: fault 0x80）。
• mdio 子节点在 phy_attach_kind=="phy" 时必须同时有 #address-cells 与 #size-cells，否则内核探测会拒绝 phy@ 的 reg，MGBE 永远起不来。
• 叠加层根 compatible 必须与运行中 DT 的 compatible 相交，否则 UEFI 会静默跳过叠加——烧录成功但 MGBE 仍禁用。
• 不要在本技能里改 OVERLAY_DTB_FILE 或 ODMDATA；也不要仅靠 ODMDATA 去「禁用」本已正常的控制器——禁用应走内核叠加层 status="disabled"。
• JSON 侧车是工具状态，面向设备的权威输出仍是 ODMDATA（由 uphy 技能）+ 叠加 .dts + 对应 git 提交。