jetson-derive-carrier

jetson-derive-carrier

Customize first-run gate for any customize-* skill on a custom
carrier. Resolve the active target per
target-platform-contract.md.
Refuse if no custom_carrier: block, or if
<source.root_path>/Linux_for_Tegra/.git is missing
(jetson-init-source first). Template file create/copy rows land in a
single overlay-tracker commit and copy directly to the
custom-carrier-renamed target path — reference-named pristine files
are never staged (see Fork plan for the local rule, which
overrides the standard pristine + customization split from the
workflow);
conf-chain discovery follows
per-board conf dispatch.
Kernel base DTB is not forked — carrier deltas layer as a DT
overlay wired via OVERLAY_DTB_FILE.

Identifiers (from active profile): <chip> from
reference_devkit.module.id via
catalogue (unknown →
warn, fallback tegra234); <module-id>/<module-sku> from
reference_devkit.module; <carrier-id>/<carrier-sku> from
reference_devkit.carrier; <custom-id>/<custom-sku>/
<custom-flash-conf> from custom_carrier. <real-conf> =
readlink <bsp_image.root_path>/Linux_for_Tegra/<reference_devkit.flash_config>
(NVIDIA convention <devkit>.conf → <carrier>-<module>-a<rev>.conf;
warn + treat top-level as real + skip symlink-wrapper row if not a
symlink).

<custom-id> is a custom carrier board token, not necessarily an
NVIDIA-style pNNNN ID. Use it verbatim in dash-form filenames and DT
compatible strings. When a target file family uses p-stripped numeric
tokens, derive <custom-id-file-token> as NNNN only if <custom-id>
matches ^p[0-9]{4}$; otherwise use <custom-id> unchanged. Do not
reject custom carrier IDs merely because they do not start with p.

Instructions

The fork plan below is the instruction set: one discovery pass, then a
row-by-row fork of the per-board fileset, gated by the commit-message
preview before each git commit.

Fork plan

Every git commit produced by this skill — in the overlay tracker
(Linux_for_Tegra/) or the hardware/ source repo — runs through
the
commit message preview gate.
Surface the staged file list + proposed message to the operator
and require accept / edit / cancel before each git commit; on
cancel leave the index staged for manual resolution.

Materialize renamed forks even when bytes do not change. For every
accepted fork-plan row, create and track the custom-carrier target path;
do not skip a missing target because the fork is only a rename/copy or is
byte-identical to the reference. This includes BCT forks such as pinmux,
GPIO/GPIOINT, padvoltage/PMC, misc, and MB2 misc. Skip only when the
Acceptance column allows it, the source is an explicit warn-and-skip
miss, or the expected target path is already tracked; in the last case,
report it as already derived and do not create an empty commit.

Template file create/copy rows squash into one overlay-tracker
commit, and reference-named pristine files are never staged. All
rows that materialize a new (template-derived) file in the overlay
tracker — board flash-conf, flash-conf symlink, MB1 BCT (pinmux,
GPIO/GPIOINT, padvoltage/PMC, misc), MB2 BCT (misc), BPMP DTB (when
opted in), nvpmodel, nvfancontrol — copy directly from
<bsp_image.root_path>/Linux_for_Tegra/<rel>/<reference-name> to
<source.root_path>/Linux_for_Tegra/<rel>/<custom-name> with any
content edits applied before staging. The reference-named
(<carrier-id>-<carrier-sku>-keyed) filename is never staged or
committed in the overlay tracker — only the custom-carrier-renamed
file is tracked. This overrides the standard pristine + customization
split from
commit batching.
All such rows land in a single overlay-tracker commit that adds:
(i) the custom-carrier-named files at their target paths with content
already applied, (ii) the flash-conf symlink, and (iii) the targeted
flash-conf content rewrites inside the renamed flash-conf for
PINMUX_CONFIG / GPIO_CONFIG / GPIOINT_CONFIG / PMC_CONFIG /
MISC_CONFIG / MB2_BCT (plus BPFDTB_FILE when BPMP DTB is opted
in). Rows that edit existing upstream files instead of creating
templates — the nvpower.sh patch — and the overlay wire-up
(OVERLAY_DTB_FILE+= append to the just-created flash-conf fork,
treated as a temporally distinct phase per
commit batching)
remain separate commits per their own rows. The DT overlay skeleton
commits in bsp_sources/hardware/, not the overlay tracker, so it is
unaffected. The commit message preview gate fires once on the
squashed commit; warn-and-skipped rows do not contribute, and if every
row in the bundle is already tracked the commit is omitted entirely.

Discovery (single batched pass)

Run one discovery pass; do not interleave with staging. Do not
truncate listings — every candidate filename in each scanned
directory must be visible to the matcher. head, tail, | head -N,
| tail -N, and any other row-limiting filter are out of bounds for
this step; use ls -1 / find unclipped, or grep on the full output.
Truncating risks false warn-and-skip calls when the matching file
sits past the cutoff. Capture:

• Flash-conf vars: DTB_FILE / TBCDTB_FILE / BPFDTB_FILE /
  PINMUX_CONFIG / PMC_CONFIG / GPIO_CONFIG / GPIOINT_CONFIG.
  DTB_FILE / TBCDTB_FILE are captured for reference only so
  the overlay wire-up can derive <dtb-stem> for the overlay
  filename — they are never rewritten by this skill.
• BCT .dts at bootloader/generic/BCT/; .dtsi siblings live
  one level up at bootloader/ — NOT alongside.
• nvpmodel: nvpmodel_<module-id>_<module-sku>*.conf. nvfancontrol:
  nvfancontrol_<module-id>_<module-sku>_<carrier-id>_<carrier-sku>.conf.
• nvpower.sh anchors for (a)–(d): <carrier-id> cvb branch,
  <module-id>-<module-sku> SKU elif, tegra<chip> nvpmodel
  cascade, tegra<chip> nvfancontrol cascade.

File / category	Discovery	Acceptance	Fork rule
Board flash conf	<real-conf>	Always	Filename sub <carrier-id>-<carrier-sku> → <custom-id>-<custom-sku>. Content sub is targeted, not blanket: rewrite RHS only for vars whose file this skill forks — PINMUX_CONFIG, PMC_CONFIG, GPIO_CONFIG / GPIOINT_CONFIG, MISC_CONFIG, MB2_BCT. Other carrier-keyed vars (DTB_FILE, TBCDTB_FILE, SCR_CONFIG, PMIC_CONFIG, DEVICEPROD_CONFIG, PROD_CONFIG, MINRATCHET_CONFIG, UPHY_CONFIG, dynamic OVERLAY_DTB_FILE+=) MUST stay at reference values — their files aren't forked here and a blanket sed would point them at nonexistent files. DTB_FILE / TBCDTB_FILE specifically: base DTB is not forked; the overlay row appends a new OVERLAY_DTB_FILE+= line instead. BPFDTB_FILE: opt-in extra commit. Never touch <chip>, <module-id>, xxxx.
Flash-conf symlink	Unconditional	Always (skip if <real-conf> not a symlink)	New symlink <custom-flash-conf> → flash-conf fork
MB1 BCT pinmux	PINMUX_CONFIG + #include follow ¶	Always	Rename rule †
MB1 BCT GPIO	GPIO_CONFIG/GPIOINT_CONFIG + #include follow ¶	Always	Rename rule †
MB1 BCT padvoltage	PMC_CONFIG + #include follow ¶	Always	Rename rule †
MB1 BCT misc	MISC_CONFIG + #include follow ¶	Always	Rename rule †
MB2 BCT misc	MB2_BCT + #include follow ¶	Always	Rename rule †
Kernel DTB + source DTS	(reference only — see header)	Never forked	Base DTB stays at reference. No pristine binary copy in the overlay tracker; no source DTS fork in bsp_sources/hardware/. Carrier deltas live entirely in the DT overlay (next row).
DT overlay skeleton (NEW)	Unconditional	Always	Create <source.root_path>/hardware/nvidia/<chip>/nv-public/overlay/<chip>-<custom-id>-<custom-sku>+<module-id>-<module-sku>.dts (skeleton ‡); commit in hardware/, push to origin
Per-dir Makefile registration	<source.root_path>/bsp_sources/hardware/nvidia/<chip>/nv-public/overlay/Makefile	Always	Append dtbo-y += <chip>-<custom-id>-<custom-sku>+<module-id>-<module-sku>.dtbo after the last literal-named dtbo-y += entry (BEFORE the $(addprefix $(makefile-path)/,$(dtbo-y)) prefix block — inserting after dtbo-y += $(old-dtbo) silently drops the .dtbo). Same position-sensitive idiom and snippet as the composite slot's Makefile patch in ../jetson-build-source/references/composite-registration.md#makefile-patch-idempotent-position-sensitive. Commit in hardware/. Without this row, nvidia-dtbs never produces the .dtbo referenced by the next row's OVERLAY_DTB_FILE+= line and flash.sh aborts mid-flash on the missing file.
Overlay wire-up	Unconditional	Always	Append OVERLAY_DTB_FILE+=",<chip>-<custom-id>-<custom-sku>+<module-id>-<module-sku>.dtbo" to flash-conf fork (extra commit)
nvpmodel config	rootfs/etc/nvpmodel/nvpmodel_<module-id-num>_<module-sku>.conf	Always	Filename: append _<custom-id-file-token>_<custom-sku>
nvfancontrol config	rootfs/etc/nvpower/nvfancontrol/nvfancontrol_<module-id-num>_<module-sku>_<carrier-id-num>_<carrier-sku>.conf	Always	Filename: substitute carrier portion (append _<custom-id-file-token>_<custom-sku> if source is module-keyed only)
nvpower.sh patch	rootfs/etc/systemd/nvpower.sh	Always	Pristine + single customization commit with 4 insertions: (a) cvb cascade elif [[ "${machine}" =~ "<custom-id>" ]]; then cvb="<custom-id-file-token>" before reference; (b) inside module-SKU branch set machine="<module-id>-<module-sku>-<custom-id>-<custom-sku>"; (c) nvpmodel cascade branch for composite machine key → conf_file= nvpmodel fork; (d) cvb-keyed nvfancontrol cascade branch → conf_file= nvfancontrol fork
BPMP DTB	prebuilt at bootloader/generic/<BPFDTB_FILE> (alt naming: no p prefix, xxxx SKU)	Opt-in y/N, default N — module-level, usually shared with reference	Fork binary: pristine + filename sub -<carrier-id-num>- → -<custom-id-file-token>- (content unchanged). Extra commit on flash-conf fork rewriting BPFDTB_FILE to the renamed binary.

¶ #include follow. Scan each captured .dts for #include "..." directives anywhere in the file (NVIDIA BSPs put them
inside BCT node bodies); carrier-keyed includes join the fork list.
Stop at one level.

† Rename rule. Carrier-keyed source (e.g.
…-p3834-xxxx-p4071-0000.dts) → filename sub
<carrier-id>-<carrier-sku> → <custom-id>-<custom-sku>; rewrite the
flash-conf variable (e.g. PINMUX_CONFIG) to the renamed filename in
the same customization commit. Module portion is preserved
verbatim from pristine — if pristine has p3834-xxxx, fork keeps
p3834-xxxx; if pristine has p3834-0008, fork keeps p3834-0008.
Never pin module-SKU on your own. Same rule for any other xxxx
wildcard in the carrier-SKU position when pristine uses it (e.g.
p4071-xxxx → p1234-xxxx). Module-keyed
source (e.g. …-p3767-dp-a03.dtsi) → append
_<custom-id-file-token>_<custom-sku> (underscore-form) or
-<custom-id>-<custom-sku> (dash-form) plus an extra commit on
flash-conf fork rewriting the variable (e.g. PINMUX_CONFIG) to the
suffixed name. Content never substituted by default; prompt if
content holds a literal carrier-id-sku self-reference.

‡ Overlay skeleton. DT plugin overlay (/plugin/;) with one
fragment@0 at target-path = "/"; inside __overlay__ set
model = "<custom_carrier.name> carrier board" and compatible = "nvidia,<custom-id>-<custom-sku>+<module-id>-<module-sku>", "nvidia,<chip>". nvpower.sh machine narrowing reads compatible.

Edit verification

Re-grep after every sed / patch. sed silently no-ops on miss;
exit code 0 proves nothing. Multi-line replacements: use Python
str.replace(old, new), not multi-line sed (brittle to whitespace
drift, silent no-ops). Refuse to commit on verification miss.

Summary. Print forks per repo (count + commit SHAs), BPMP-DTB
decision, warn-and-skipped rows (mandatory source file missing on
this BSP — don't fail the run), overlay path written.

Examples

Trigger phrases the operator might use:

derive custom carrier
bootstrap custom carrier
fork carrier board from reference devkit

Minimal custom_carrier: block in the active profile that the skill
expects to find:

custom_carrier:
  id: p1234            # any token; need not be NVIDIA pNNNN style
  sku: 0000
  flash_config: p1234.conf
  name: Acme Custom Carrier

Purpose

Customize the per-board fileset for a new carrier board so downstream
customize-* skills, nvpower.sh, and the boot chain land on the
custom carrier instead of the reference devkit. Base DTB stays at the
reference; carrier deltas live in a DT overlay so a re-derive against
a new reference BSP only needs to re-run this skill.

Prerequisites

• Active profile resolved per
  target-platform-contract.md
  with a custom_carrier: block (id, sku, flash-conf, friendly name).
• source.root_path/Linux_for_Tegra/.git initialized — run
  /jetson-init-source first; this skill refuses if the overlay
  tracker is missing.
• bsp_image.root_path populated by /jetson-init-image so the
  reference flash-conf symlink can be resolved.
• reference_devkit: populated (module + carrier) so the rename rule
  has carrier-id/sku tokens to substitute away from.

Limitations

• Kernel base DTB and its source DTS are not forked — carrier
  deltas must layer through the DT overlay wired via
  OVERLAY_DTB_FILE.
• BPMP DTB fork is opt-in (default OFF). Most carrier swaps share the
  reference BPMP DTB; only opt in when board power/clock topology
  diverges.
• Flash-conf content substitution is targeted, not blanket. Vars
  whose files this skill does not fork (DTB_FILE, TBCDTB_FILE,
  SCR_CONFIG, PMIC_CONFIG, DEVICEPROD_CONFIG, PROD_CONFIG,
  MINRATCHET_CONFIG, UPHY_CONFIG, dynamic OVERLAY_DTB_FILE+=)
  stay at reference values — rewriting them would point at files that
  do not exist.
• Custom-carrier IDs need not follow NVIDIA pNNNN style; the
  p-stripped numeric token is derived only when the ID matches
  ^p[0-9]{4}$.
• Does not customize module-level files. Use the relevant
  jetson-customize-* skill for pinmux, clocks, fan curves,
  nvpmodel, PCIe, UPHY, USB, MGBE, or camera deltas.

Troubleshooting

• Refuses with "no custom_carrier: block" — declare the block in
  the active profile before re-running; the skill will not infer it.
• Refuses with ".git missing in Linux_for_Tegra/" — overlay
  tracker not initialized. Run /jetson-init-source first.
• "<real-conf> not a symlink" — NVIDIA convention is a
  <devkit>.conf symlink to <carrier>-<module>-a<rev>.conf; if the
  top-level is the real conf, the skill warns, treats it as real, and
  skips the symlink-wrapper row. Not an error.
• sed reported success but the edit is missing — sed silently
  no-ops on miss. The skill re-greps after every patch and refuses to
  commit on verification miss; for multi-line replacements switch to
  Python str.replace.
• "chip: unknown" / fallback to tegra234 — module ID is not in
  the catalogue; update
  the catalogue rather than override in the profile.
• Commit message preview prompt blocks the run — expected gate per
  commit-batching;
  accept, edit, or cancel. On cancel the index is left staged for
  manual resolution.
• A mandatory source file is missing on this BSP — the row is
  recorded as warn-and-skipped in the summary; the rest of the run
  still completes.