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

```
questions.json
```
— Q-1..Q-8 prompt schema consumed by Step 2.
```
../../scripts/pin_verifier.py
```
— shared HSIO pin verifier (Step 4).

../../references/platform_template.yaml

—

documents:

block consumed by Step 1.

```
../../context/bsp-customization-workflow.md
```
— overlay edit protocol (batched pristine + customization commit).
```
../jetson-customize-uphy/SKILL.md
```
— sibling skill that owns UPHY lane allocation. Must run before this skill to set
```
uphy1-config-N
```
for MGBE-allocated configurations.
```
../jetson-customize-pinmux/SKILL.md
```
— sibling skill invoked by Step 4 (with operator confirmation) to fix pin SFIO mismatches.
```
../jetson-derive-carrier/SKILL.md
```
— must run first; produces the carrier flash-conf fork edited in Step 5 and the carrier base overlay this skill orders after.
```
../jetson-init-source/SKILL.md
```
— produces the overlay tracker + bsp_sources repo this skill commits into.

jetson-customize-mgbe

NPX Install

Tags

SKILL.md Content