/jetson-customize-mgbe

name: jetson-customize-mgbe
description: >-
  Enable Jetson Thor 25G/10G/1G MGBE QSFP via kernel-DT overlay.
  Do NOT use for UPHY lane allocation or ODMDATA edits.
version: 0.0.1
license: "Apache-2.0"
metadata:
  data-classification: public
  author: "Jetson Team"
  tags:
    - bsp
    - phase-2
    - io
    - mgbe
    - ethernet
  domain: meta
  permissions:
    file_read:
      - "{workspace}/target-platform/"
      - "{source.root_path}/"
      - "{bsp_image.root_path}/Linux_for_Tegra/"
      - "{documents.root_path}/"
    file_write:
      - "{workspace}/target-platform/"
      - "{source.root_path}/bsp_sources/hardware/nvidia/"
    shell:
      - "dtc"
      - "fdtoverlay"
      - "cpp"
      - "git"

Customize 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.

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.

Procedure

See `references/procedure.md` for the full step-by-step procedure (Steps 1–8). Summary:

1. **Resolve active target + documents.** Validate active profile, custom_carrier, overlay tracker; locate the relevant Adaptation Guide chapter and pinmap. 2. **Per-controller question loop.** AskUserQuestion driven by `questions.json` (controller, phy_mode, attach kind, I²C bus/addr, reset GPIO, compatible_list). 3. **Derive max-speed from phy_mode.** Decompile the BPMP DTB to pick sub-node vs top-level token grammar; cite the inspection in notes. 4. **Verify HSIO pins + auto-fix.** Run `pin_verifier.py` for MDC/MDIO/RESET/INT; surface mismatches and route to `/jetson-customize-pinmux`. 5. **(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. 6. **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. 7. **(Reserved.)** Sibling-skill ordering / cross-cutting validation. 8. **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.

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