jetson-customize-mgbe

自定义 MGBE / 25G QSFP

概述

Thor T264 提供 mgbe0..mgbe3。在自定义载板上，25G QSFP 笼子 （或 10G / 1G 光纤通路）通过 SerDes 连接到其中一个接口——笼子前方 可以有外部 MDIO PHY，也可以没有。此技能会生成内核 DT 覆盖层，将 BPMP 分配与 &mgbeN 上内核侧的 status="okay" 和 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 和 flash-conf 注册。

何时调用

• 用户说“启用 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 已运行——载板 flash-conf 分支已加入 覆盖层跟踪器。
• /jetson-customize-uphy 选择了可分配目标 MGBE 控制器通道的 UPHY 配置 （Thor 上 MGBE0..3 25G 对应 uphy1-config-8）。
• 已注册或在提示词中提供真实来源文档： Adaptation Guide、Module Design Guide、SoC TRM。
• 存在 custom_carrier: 时，必须提供 documents.custom_carrier_schematic 和 documents.custom_carrier_pinmux_xls。 如果缺少任一项，则拒绝运行—— 无法猜测自定义载板上的 MGBE 布线。仅使用参考开发套件的配置文件会跳过此检查。
• PATH 中有 dtc。

流程

完整的分步流程（步骤 1–8）见 references/procedure.md。摘要：

1. 解析活动目标和文档。 验证活动配置文件、自定义载板和覆盖层跟踪器；定位相关的 Adaptation Guide 章节和引脚映射。
2. 逐控制器提问。 根据 questions.json 提示用户回答（控制器、phy_mode、连接类型、I²C 总线/地址、复位 GPIO、compatible_list）。
3. 根据 phy_mode 推导 max-speed。 反编译 BPMP DTB，以确定使用子节点还是顶层标记语法；在备注中引用检查结果。
4. 验证 HSIO 引脚并自动修复。 对 MDC/MDIO/RESET/INT 运行 pin_verifier.py；显示不匹配项并转至 /jetson-customize-pinmux。
5. （不编辑 ODMDATA。） MGBE ODMDATA 标记由 /jetson-customize-uphy 生成。步骤 5 仅在 notes[] 中记录 BPMP DTB 标记格式检查结果（子节点还是顶层），供审计使用。
6. 追加组合覆盖层片段。 将每个控制器的一个片段写入组合自定义覆盖层 .dts；遵守 /* custom-bsp: mgbe:mgbe... */ 标记约定；运行 cpp/dtc/fdtoverlay 预检。
7. （预留。） 同级技能排序／跨领域验证。
8. 运行状态附属文件、摘要和后续步骤链。 写入 <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 中错误格式导致的故障表现相同。
• 当 phy_attach_kind=="phy" 时，mdio 子节点需要同时包含 #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 禁用原本状态为 okay 的控制器。 规则与 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 — documents: 块，由步骤 1 使用。
• ../../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 仓库，供此技能提交更改。