jetson-customize-mgbe
自定义 MGBE / 25G QSFP
概述
Thor T264 暴露出 mgbe0..mgbe3。在定制载板上，25G QSFP 笼（或 10G / 1G 光纤通路）通过 SerDes 连接到其中一个——笼前可能配有外部 MDIO PHY，也可能没有。本技能生成内核DT叠加层，将 BPMP 分配与内核侧的 status="okay" + &mgbeN 上的 PHY 连接相配对。
不在范围内：
- UPHY 通道分配——由
/jetson-customize-uphy负责。如果所选uphy1-config-N没有分配目标 MGBE，则拒绝执行。 - 所有 ODMDATA 令牌（
mgbeN-speed-*、子节点mgbeN_status=*）——由/jetson-customize-uphy在其单一原子 ODMDATA 提交中负责。本技能不得触碰ODMDATA=。
输出是 一个提交，提交到 bsp_sources/ 硬件仓库中的复合定制叠加 .dts 文件。/jetson-build-source 负责将复合文件编译为 .dtbo，并拥有其 Makefile 和烧录配置注册。
何时调用
- 用户说"启用 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已运行——载板烧录配置文件的分支已在叠加跟踪器中。/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 中可用。
操作步骤
完整的分步步骤见 references/procedure.md（步骤 1–8）。概要：
- 解析目标 + 文档。 验证活动配置文件、custom_carrier、叠加跟踪器；找到相关适配指南章节和引脚映射。
- 每个控制器的问题循环。 由
questions.json驱动的 AskUserQuestion（控制器、phy_mode、连接类型、I²C 总线/地址、复位 GPIO、兼容性列表）。 - 从 phy_mode 推导最大速度。 反编译 BPMP DTB 以选择子节点或顶层令牌语法；在 notes 中引用检查结果。
- 验证 HSIO 引脚 + 自动修复。 运行
pin_verifier.py检查 MDC/MDIO/RESET/INT；发现不匹配时导向/jetson-customize-pinmux。 - （不进行 ODMDATA 编辑。） MGBE ODMDATA 令牌由
/jetson-customize-uphy发出。步骤 5 仅将 BPMP DTB 令牌形式检查（子节点 vs 顶层）记录到notes[]中以供审计。 - 追加复合叠加片段。 为每个控制器向复合定制叠加
.dts写入一个片段；遵守/* custom-bsp: mgbe:mgbe... */标记约定；运行 cpp/dtc/fdtoverlay 预检。 - （保留。） 兄弟技能排序/交叉验证。
- 运行状态侧车 + 摘要 + 下一步链。 写入
<profile-stem>.jetson-customize-mgbe.json并输出单行 + 表格摘要，然后通过references/procedure.md步骤 8 中的顺序AskUserQuestion提示驱动下游链。切勿用打印的"下一步：..."行替代提示。
注意事项
- 原始 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相同的错误形式故障面。 mdio子节点在phy_attach_kind=="phy"时同时需要#address-cells = <1>和#size-cells = <0>。缺少任何一个都会导致内核在探测时拒绝phy@<addr>reg 属性；MGBE 永远无法启动。- 叠加层根
compatible必须与实时 DT 的 compatible 相交。 UEFI 插件管理器通过 compatible 匹配进行过滤。不匹配的叠加层会被静默跳过——烧录成功，MGBE 保持禁用，dmesg 中无错误。始终对照已启动参考 DUT 上的/proc/device-tree/compatible进行合理性检查。 OVERLAY_DTB_FILE的排序是jetson-build-source的问题，不是本技能的。 本技能从不接触载板烧录配置。复合定制叠加层在平台*-dynamic.dtbo之后注册（由/jetson-build-source步骤 5.0a 完成），这是正确的顺序。如果你发现自己在技能中追加OVERLAY_DTB_FILE+=，说明你在重复负责——立即停止，让构建技能来做。- UPHY 通道分配是
jetson-customize-uphy的工作。 如果选择的uphy1-config-N没有为目标 MGBE 控制器分配通道，冷启动时会出现 BL31 SError（fmon_update_config: detected fault 0x80）。始终先运行/jetson-customize-uphy；在本技能运行摘要的notes[]中引用所选的uphy1-config-N。 - 不要仅通过 ODMDATA 禁用出厂正常的控制器。 与
jetson-customize-uphy相同的规则：对已在 BPMP DTB 中禁用的控制器设置mgbe<N>_status=disabled是一个空操作，解析器可能视为歧义——导致丢弃 ODMDATA 行的其余部分。仅通过内核DT叠加层（status="disabled"）禁用。 - 不要触碰
<bsp_image.root_path>的上游 BSP。 所有编辑都在叠加跟踪器 /bsp_sources单一仓库中，遵循原始 + 定制提交模式。 - JSON 侧车是结构化状态，不是权威的。 与
jetson-customize-uphy相同的说明：ODMDATA + 叠加.dts+ 两个 git 提交才是面向设备的输出；侧车仅用于工具和幂等性。
参考
questions.json— Q-1..Q-8 提示模式，由步骤 2 使用。../../scripts/pin_verifier.py— 共享的 HSIO 引脚验证器（步骤 4）。../../references/platform_template.yaml— 由步骤 1 使用的documents:块。../../context/bsp-customization-workflow.md— 叠加编辑协议（批量原始 + 定制提交）。../jetson-customize-uphy/SKILL.md— 拥有 UPHY 通道分配的兄弟技能。必须在此技能之前运行，为 MGBE 分配配置设置uphy1-config-N。../jetson-customize-pinmux/SKILL.md— 由步骤 4（经操作员确认）调用的兄弟技能，用于修复引脚 SFIO 不匹配。../jetson-derive-carrier/SKILL.md— 必须先运行；产生步骤 5 中编辑的载板烧录配置文件分支以及本技能排序在其后的载板基础叠加层。../jetson-init-source/SKILL.md— 产生本技能提交到的叠加跟踪器 + bsp_sources 仓库。