Jetson Customize Mgbe Agent Skill

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.