---

name: jetson-customize-nvpmodel description: >- Use when you need to add, remove, edit, list, or change the boot default of an nvpmodel power mode on a Jetson/Tegra (Orin, Thor) target. Triggers: edit power mode, tune frequency caps. version: 0.0.1 license: "Apache-2.0" metadata: data-classification: public author: "Jetson Team" tags: - power - nvpmodel - profile domain: power

Modify nvpmodel Power Mode (BSP-side)

Purpose

Edit the per-board nvpmodel configuration so the device boots with the desired power-mode set, CPU/GPU/EMC/TPC clamps, and default mode. BSP-side only — all writes land in the overlay tracker, the upstream bsp_image copy is read-only.

This skill handles BSP-side edits to the per-board nvpmodel configuration file: adding modes, removing modes, editing CPU/GPU/EMC/TPC clamps, and changing the boot default. Applies on Jetson / Tegra platforms (T234 Orin, T264 Thor).

File format (canonical, per the BSP file header)

# 1. PARAM definitions — declare named knobs and their sysfs paths
< PARAM TYPE=FILE  NAME=<param_name> >
<arg_name> </absolute/sysfs/path>
...
< PARAM TYPE=CLOCK NAME=<param_name> >
FREQ_TABLE        </sysfs/.../available_frequencies>
MAX_FREQ          </sysfs/.../max_freq>
MIN_FREQ          </sysfs/.../min_freq>
FREQ_TABLE_KNEXT  </sysfs/.../available_frequencies>     # kernel-NEXT variant
MAX_FREQ_KNEXT    </sysfs/.../max_freq>
MIN_FREQ_KNEXT    </sysfs/.../min_freq>

# 2. POWER_MODEL definitions — one block per profile
< POWER_MODEL ID=<int> NAME=<string> >
PARAM_NAME ARG_NAME <value>
...

# 3. PM_CONFIG — mandatory; selects boot default
< PM_CONFIG DEFAULT=<id> >

Rules:

• For TYPE=FILE, <value> is a string (0, 1, on, auto, …).
• For TYPE=CLOCK, <value> is an integer (Hz for clocks, raw integer for masks).
• -1 for a CLOCK value means INT_MAX (no cap).
• The header < … > line must start at column 0 with a space after < and before >. Strict.
• Every PARAM_NAME referenced in a POWER_MODEL must already be declared above.
• Frequency values must come from the kernel's available_frequencies table for that clock — values not in the table get silently rounded.
• CORE_0 cannot be offlined; at least one CPU core must remain online in every profile.
• Copy PARAM names verbatim from an existing POWER_MODEL block in the per-board file — chip families differ (T234 Orin uses CPU_A78_<n> for CPU clusters; T264 Thor uses a different convention). Don't invent.

Prerequisites

Resolve the active profile per ../../context/target-platform-contract.md. Refuse and route in these cases:

| Condition | Refuse with | |---|---| | No active profile, or active: NA | Route to /jetson-set-target or /jetson-init-target. | | Profile lacks bsp_image: block | Route to /jetson-init-image. | | <bsp_image.root_path>/Linux_for_Tegra/ missing | Route to /jetson-init-image. | | <source.root_path>/Linux_for_Tegra/ missing or not a git repo | Route to /jetson-init-source. |

Resolve paths:

• <bsp_image.root_path> from bsp_image.root_path: if present, else <workspace>/Image.
• <source.root_path> from source.root_path: if present, else <workspace>/Source.

<bsp_image.root_path> is read-only for this skill; every write lands under <source.root_path> (the overlay tracker). This is the workflow invariant in ../../context/bsp-customization-workflow.md#workflow-invariants — hand-editing upstream silently destroys the diff trail and makes /jetson-promote-image a noop.

The per-board file

The conf this skill edits has the relative path:

Linux_for_Tegra/rootfs/etc/nvpmodel/nvpmodel_<active-sku>.conf

It lives in two roots; the skill walks both:

| Role | Location | Skill writes? | |---|---|---| | Detection + pristine source | <bsp_image.root_path>/Linux_for_Tegra/rootfs/etc/nvpmodel/ | no — read-only | | Overlay edit target + git commit | <source.root_path>/Linux_for_Tegra/rootfs/etc/nvpmodel/ | yes |

Subsequent sections refer to the per-board file to mean the overlay copy under <source.root_path>. Operations 1–4 all read, edit, and save against that overlay copy. The <bsp_image.root_path> copy is read once during the "Resolving <active-sku>" detection step and once during the Overlay edit recipe's pristine-import step, then never touched again.

Resolving <active-sku> — which file to edit

The filename is not always module.id + "_" + module.sku. Variants exist:

• nvpmodel_p3767_0000_super.conf (super-mode SKU variant)
• nvpmodel_igx_orin.conf, nvpmodel_igx_orin_safety.conf (IGX, no SKU number)

At boot, nvpower.sh (at Linux_for_Tegra/rootfs/etc/systemd/nvpower.sh) reads the kernel DTB's root compatible string and maps it — plus super/safety state — to the nvpmodel filename. Replicate that mapping BSP-side, against <bsp_image.root_path>:

1. Resolve the SKU-correct kernel DTB under <bsp_image.root_path>/Linux_for_Tegra/ and read its root compatible (detect kernel DTB from the active flash conf).
2. Read <bsp_image.root_path>/Linux_for_Tegra/rootfs/etc/systemd/nvpower.sh to find the compatible-string → conf mapping, and apply it to the compatible from the previous step (factoring in super/safety flags).
3. Verify the resolved nvpmodel_<...>.conf exists under <bsp_image.root_path>/Linux_for_Tegra/rootfs/etc/nvpmodel/.

Shortcut: filter <bsp_image.root_path>/Linux_for_Tegra/rootfs/etc/nvpmodel/ to nvpmodel_<module.id>_<module.sku>*.conf; for super-mode flash configs pick the _super variant. Use only when unambiguous; otherwise fall back to the DTB method.

Don't blindly compose nvpmodel_<id>_<sku>.conf — verify the file actually exists.

Propagation set — confs to keep in sync

The active-SKU file is rarely the only conf that should carry a customization. After editing it, apply the same edit to every sibling in the propagation set so the change survives regardless of which module / baseboard SKU is booted:

• The reference platform's nvpmodel conf — the upstream conf the active file was forked from (resolve via reference_devkit in the active profile, or jetson-derive-carrier fork ancestry). For a BSP that contains only the reference (no derived carriers), this is the same file as the active and the rule reduces to a no-op.
• Every carrier-derived nvpmodel conf — each nvpmodel_*.conf produced by jetson-derive-carrier for a custom carrier on top of the same module SKU.
• _super siblings when present (e.g. nvpmodel_p3767_0000_super.conf) — apply the structural edit (new POWER_MODEL block, removed block, PM_CONFIG DEFAULT= flip, NAME rename) but preserve the super conf's higher MAX_FREQ / MIN_FREQ caps. Those elevated caps are the whole reason the _super variant exists; a blanket content overwrite from the non-super file would silently flatten the super envelope.

"Apply the same edit" ≠ blanket file copy. Port the changed POWER_MODEL / PARAM lines into each sibling; preserve every other line. Blanket-copying is safe only when both confs were byte-identical before the edit. Otherwise re-validate per the Rules on each target (available-frequencies table for clock values, ID uniqueness, PM_CONFIG DEFAULT= references a present ID) — sibling confs may carry SKU-specific available_frequencies tables that don't accept the active file's frequency values.

Overlay edit recipe (apply before any Operation)

Follow the canonical Off-skill edits recipe in the workflow doc — pristine import + customization commit pair, both gated by the preview gate. Apply once per run, covering every per-board file the run touches (the active conf plus every sibling in the Propagation set).

Concrete substitutions for this skill:

• <rel>/<file> is rootfs/etc/nvpmodel/<conf>.
• Suggested pristine-import message: import pristine: <comma-separated rel paths of imported confs>, body Source: <bsp_image.root_path>/Linux_for_Tegra/ (BSP <bsp_image.version>).
• Suggested customization-commit header: jetson-customize-nvpmodel: <summary>, body lines like nvpmodel_p3767_0001.conf: PM_CONFIG DEFAULT 2 -> 0 (MAXN).

Instructions

Pick the operation that matches the user's intent and follow the matching subsection. All write-side operations (1–4) must first apply the Overlay edit recipe.

• Operation 1 — Add a new power mode (drives the NVIDIA Power Estimator).
• Operation 2 — Remove a power mode.
• Operation 3 — Edit an existing power mode (clamps, core-online, NAME).
• Operation 4 — Change the boot default (PM_CONFIG DEFAULT=).
• Operation 5 — List defined power modes (read-only).

After any write-side operation, run the Deploy chain (## Deploy) to land the change on the device.

Examples

Add a new 30 W power mode from a Power Estimator export and pin it as the boot default on a P3767-0001 target:

/jetson-customize-nvpmodel
> add a new POWER_MODEL from ~/Downloads/nvpmodel_30W.conf as ID 8 NAME "30W_CUSTOM"
> set PM_CONFIG DEFAULT to 8

Cap a Thor target to the MAXN power envelope by flipping the boot default (no envelope tuning needed):

/jetson-customize-nvpmodel
> set PM_CONFIG DEFAULT to the MAXN profile's ID

List which power modes the active SKU currently defines and which is the boot default:

/jetson-customize-nvpmodel
> list defined power modes

Operation 1 — Add a new power mode

Apply the Overlay edit recipe first.

Generate the profile via the Power Estimator

Must not interpolate or extrapolate frequencies from existing profiles to estimate power.

For any non-stock power envelope (custom budget, custom workload), use the NVIDIA Power Estimator: https://jetson-tools.nvidia.com/powerestimator/

• Pick the exact module SKU and JetPack release.
• Enter workload (CPU cores, GPU usage, EMC, codecs, camera, display).
• Estimate power budget.
• Download custom nvpmodel.conf.
• Share the downloaded nvpmodel.conf file path.

Append the POWER_MODEL block

In the per-board file, insert the new block after the last < PARAM … > declaration (POWER_MODEL must reference declared PARAMs) and before the final < PM_CONFIG ... > line. The block structure is the File format shown above; frequency values come from the Power Estimator output (see "Generate the profile via the Power Estimator").

Check ID is unique; NAME should be uppercase, no whitespace. Each numeric MAX_FREQ / MIN_FREQ value must satisfy the available_frequencies rule (see Rules). If you intend this mode to be the boot default, follow Operation 4.

Operation 2 — Remove a power mode

Apply the Overlay edit recipe first.

1. In the per-board file, delete the entire < POWER_MODEL ID=<n> NAME=... > block including all its parameter lines, up to (but not including) the next < POWER_MODEL ... > or < PM_CONFIG ... > marker.
2. If the deleted ID matches the current DEFAULT=<id> value in the trailing < PM_CONFIG … > line, point DEFAULT= at a remaining ID — otherwise nvpmodel will fail to apply a default at boot.
3. Search for hard-coded references in the rootfs scripts before declaring the change safe:

   grep -rn "nvpmodel -m" \
     Linux_for_Tegra/rootfs/etc \
     Linux_for_Tegra/rootfs/opt 2>/dev/null
   

ID gaps are legal — you don't have to renumber remaining modes.

Operation 3 — Edit an existing power mode

Apply the Overlay edit recipe first.

1. In the per-board file, edit the paramete