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:
- 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.
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.
References
1---2name: jetson-customize-mgbe3description: >-4 Enable Jetson Thor 25G/10G/1G MGBE QSFP via kernel-DT overlay.5 Do NOT use for UPHY lane allocation or ODMDATA edits.6version: 0.0.17license: "Apache-2.0"8metadata:9 source: https://skillmd.com/skills/nvidia/jetson-customize-mgbe10 data-classification: public11 author: "Jetson Team"12 tags:13 - bsp14 - phase-215 - io16 - mgbe17 - ethernet18 domain: meta19 permissions:20 file_read:21 - "{workspace}/target-platform/"22 - "{source.root_path}/"23 - "{bsp_image.root_path}/Linux_for_Tegra/"24 - "{documents.root_path}/"25 file_write:26 - "{workspace}/target-platform/"27 - "{source.root_path}/bsp_sources/hardware/nvidia/"28 shell:29 - "dtc"30 - "fdtoverlay"31 - "cpp"32 - "git"33---3435# Customize MGBE / 25G QSFP3637## Overview3839Thor T264 exposes mgbe0..mgbe3. On a custom carrier, the 25G QSFP cage40(or 10G / 1G fiber path) is wired to one of them through SerDes — with41or without an external MDIO PHY in front of the cage. This skill42renders the kernel-DT overlay that pairs the BPMP allocation with43kernel-side `status="okay"` + PHY plumbing on `&mgbeN`.4445**Out of scope:**46- UPHY lane allocation — owned by `/jetson-customize-uphy`. Refuse if47 the chosen `uphy1-config-N` doesn't allocate the target MGBE.48- All ODMDATA tokens (`mgbeN-speed-*`, sub-node `mgbeN_status=*`) —49 owned by `/jetson-customize-uphy` in its single atomic ODMDATA50 commit. This skill MUST NOT touch `ODMDATA=`.5152Output is **one commit** to the composite custom overlay `.dts` in the53`bsp_sources/` hardware repo. `/jetson-build-source` compiles the54composite to `.dtbo` and owns its Makefile + flash-conf registration.5556## When to invoke5758- The user says "enable 25G", "configure QSFP", "set MGBE PHY mode",59 "wire MGBE to QSFP", or asks to bring up a 10G / 1G fiber path.60- Cold boot succeeds but `ip link show mgbe<N>` reports `state DOWN`61 or `NO-CARRIER` on the configured controller, OR the controller62 never appears at all.63- `jetson-customize-uphy` ran with `uphy1-config-8` (or another config64 allocating MGBE) and you now need to bring up the per-controller65 side.6667**Prerequisites:**6869- Active profile selected with `reference_devkit:` (Thor) +70 `custom_carrier:` blocks.71- `<source.root_path>/Linux_for_Tegra/.git` exists72 (`/jetson-init-source`).73- `/jetson-derive-carrier` has run — carrier flash-conf fork is in74 the overlay tracker.75- `/jetson-customize-uphy` chose a UPHY config that allocates the target76 MGBE controller's lanes (`uphy1-config-8` on Thor for MGBE0..3 25G).77- Source-of-truth docs registered or supplied at prompt:78 Adaptation Guide, Module Design Guide, SoC TRM.79- **When `custom_carrier:` is present, both80 `documents.custom_carrier_schematic` AND81 `documents.custom_carrier_pinmux_xls` are REQUIRED.** Refuse the run82 if either is missing — MGBE routing on a custom carrier cannot be83 guessed. Reference-devkit-only profiles skip this check.84- `dtc` on PATH.8586## Procedure8788See `references/procedure.md` for the full step-by-step procedure (Steps 1–8). Summary:89901. **Resolve active target + documents.** Validate active profile, custom_carrier, overlay tracker; locate the relevant Adaptation Guide chapter and pinmap.912. **Per-controller question loop.** AskUserQuestion driven by `questions.json` (controller, phy_mode, attach kind, I²C bus/addr, reset GPIO, compatible_list).923. **Derive max-speed from phy_mode.** Decompile the BPMP DTB to pick sub-node vs top-level token grammar; cite the inspection in notes.934. **Verify HSIO pins + auto-fix.** Run `pin_verifier.py` for MDC/MDIO/RESET/INT; surface mismatches and route to `/jetson-customize-pinmux`.945. **(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.956. **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.967. **(Reserved.)** Sibling-skill ordering / cross-cutting validation.978. **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.9899## Gotchas100101- **Stock Thor BPMP DTB has no `/mgbe/mgbe@N` subtree** — only102 `mgbe<N>-speed` under `/uphy`. The `mgbe<N>_status=disabled`103 sub-node token is silently rejected on these releases; the whole104 ODMDATA line is then dropped at flash time. Always decompile BPMP105 DTB (Step 3) before emitting; use the top-level dashed form106 (`mgbe<N>-speed-del` to remove, `mgbe<N>-speed-25G` to set) when107 the sub-node isn't there. Same wrong-form failure surface as108 `jetson-customize-uphy`.109- **`mdio` child needs both `#address-cells = <1>` AND110 `#size-cells = <0>`** when `phy_attach_kind=="phy"`. Missing either111 → kernel rejects `phy@<addr>` reg property at probe; MGBE never112 comes up.113- **Overlay root `compatible` must intersect live DT compatible.**114 UEFI plugin-manager filters by compatible match. A mismatched115 overlay is silently skipped — flash succeeds, MGBE stays disabled,116 no error in dmesg. Always sanity-check against117 `/proc/device-tree/compatible` on a booted reference DUT.118- **`OVERLAY_DTB_FILE` ordering is `jetson-build-source`'s problem,119 not this skill's.** This skill never touches the carrier flash120 conf. The composite custom overlay is registered (by121 `/jetson-build-source` Step 5.0a) AFTER the platform122 `*-dynamic.dtbo`, which is the correct ordering. If you find123 yourself appending `OVERLAY_DTB_FILE+=` in this skill, you're124 duplicating ownership — stop, and let the build skill do it.125- **UPHY lane allocation is `jetson-customize-uphy`'s job.** If the chosen126 `uphy1-config-N` doesn't allocate lanes for the target MGBE127 controller, BL31 SError (`fmon_update_config: detected fault128 0x80`) on cold boot. Always run `/jetson-customize-uphy` first; cite the129 chosen `uphy1-config-N` in this skill's run-summary `notes[]`.130- **Don't disable a stock-okay controller via ODMDATA alone.** Same131 rule as `jetson-customize-uphy`: `mgbe<N>_status=disabled` for a132 controller that's already disabled in BPMP DTB is a no-op the133 parser may treat as ambiguous → drops the rest of the ODMDATA134 line. Disable via the kernel-DT overlay (`status="disabled"`) only.135- **Don't touch the upstream BSP at `<bsp_image.root_path>`.** All136 edits land in the overlay tracker / `bsp_sources` mono-repo under137 the pristine + customization commit pattern.138- **JSON sidecar is structured state, not authoritative.** Same139 caveat as `jetson-customize-uphy`: ODMDATA + overlay `.dts` + two git140 commits are the device-facing outputs; the sidecar is for tooling141 and idempotency only.142143## References144145- [`questions.json`](references/questions.json) — Q-1..Q-8 prompt schema146 consumed by Step 2.147- [`../../scripts/pin_verifier.py`](../../scripts/pin_verifier.py)148 — shared HSIO pin verifier (Step 4).149- [`../../references/platform_template.yaml`](../../references/platform_template.yaml)150 — `documents:` block consumed by Step 1.151- [`../../context/bsp-customization-workflow.md`](../../context/bsp-customization-workflow.md#commit-batching-in-the-overlay-tracker)152 — overlay edit protocol (batched pristine + customization commit).153- [`../jetson-customize-uphy/SKILL.md`](../jetson-customize-uphy/SKILL.md) — sibling154 skill that owns UPHY lane allocation. Must run before this skill to155 set `uphy1-config-N` for MGBE-allocated configurations.156- [`../jetson-customize-pinmux/SKILL.md`](../jetson-customize-pinmux/SKILL.md) —157 sibling skill invoked by Step 4 (with operator confirmation) to158 fix pin SFIO mismatches.159- [`../jetson-derive-carrier/SKILL.md`](../jetson-derive-carrier/SKILL.md)160 — must run first; produces the carrier flash-conf fork edited in161 Step 5 and the carrier base overlay this skill orders after.162- [`../jetson-init-source/SKILL.md`](../jetson-init-source/SKILL.md) —163 produces the overlay tracker + bsp_sources repo this skill commits164 into.