Back to Details

jetson-customize-nvpmodel

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Modify nvpmodel Power Mode (BSP-side)

修改nvpmodel电源模式（BSP侧）

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).
编辑单板nvpmodel配置，使设备开机时设置为所需的电源模式、CPU/GPU/EMC/TPC频率限制以及默认模式。仅限BSP侧操作——所有写入操作均存入overlay tracker，上游
bsp_image
副本为只读状态。
本技能负责在BSP侧编辑单板nvpmodel配置文件：添加模式、删除模式、编辑CPU/GPU/EMC/TPC频率限制，以及修改开机默认模式。适用于Jetson / Tegra平台（T234 Orin、T264 Thor）。

File format (canonical, per the BSP file header)

文件格式（标准格式，源自BSP文件头）

undefined
undefined

1. PARAM definitions — declare named knobs and their sysfs paths

1. PARAM定义——声明命名控制项及其sysfs路径

< 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>
< 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变体 MAX_FREQ_KNEXT </sysfs/.../max_freq> MIN_FREQ_KNEXT </sysfs/.../min_freq>

2. POWER_MODEL definitions — one block per profile

2. POWER_MODEL定义——每个配置文件对应一个代码块

< POWER_MODEL ID=<int> NAME=<string> > PARAM_NAME ARG_NAME <value> ...
< POWER_MODEL ID=<int> NAME=<string> > PARAM_NAME ARG_NAME <value> ...

3. PM_CONFIG — mandatory; selects boot default

3. PM_CONFIG——必填项；选择开机默认模式

< 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.
< PM_CONFIG DEFAULT=<id> >

规则：

- 对于`TYPE=FILE`，`<value>`为**字符串**（如`0`、`1`、`on`、`auto`等）。
- 对于`TYPE=CLOCK`，`<value>`为**整数**（时钟为赫兹值，掩码为原始整数）。
- CLOCK值为`-1`表示**INT_MAX**（无上限）。
- 头部`< … >`行必须从第0列开始，且`<`和`>`前后需有空格，格式严格。
- POWER_MODEL中引用的每个`PARAM_NAME`必须已在上方声明。
- **频率值必须来自对应时钟的内核`available_frequencies`表**——不在表中的值会被自动取整。
- `CORE_0`不能离线；每个配置文件中必须至少保留一个CPU核心在线。
- **严格复制现有POWER_MODEL代码块中的PARAM名称**——不同芯片系列的命名不同（T234 Orin使用`CPU_A78_<n>`表示CPU集群；T264 Thor使用不同的命名规则），请勿自行创造。

Prerequisites

前置条件

Resolve the active profile per 
../../context/target-platform-contract.md
. Refuse and route in these cases:
ConditionRefuse 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.
根据
../../context/target-platform-contract.md
解析当前激活的配置文件。在以下情况下拒绝操作并引导至对应流程：
条件拒绝提示并引导至
无激活配置文件，或
active: NA
引导至
/jetson-set-target
或
/jetson-init-target
。
配置文件缺少
bsp_image:
代码块		引导至
/jetson-init-image
。
<bsp_image.root_path>/Linux_for_Tegra/
不存在		引导至
/jetson-init-image
。
<source.root_path>/Linux_for_Tegra/
不存在或不是git仓库		引导至
/jetson-init-source
。
解析路径：
  • <bsp_image.root_path>
    优先从
    bsp_image.root_path:
    获取，否则使用
    <workspace>/Image
    。
  • <source.root_path>
    优先从
    source.root_path:
    获取，否则使用
    <workspace>/Source
    。
<bsp_image.root_path>
对本技能而言为只读；所有写入操作均存储在
<source.root_path>
（overlay tracker）下。这是
../../context/bsp-customization-workflow.md#workflow-invariants
中定义的工作流不变量——手动编辑上游文件会悄无声息地破坏差异追踪，导致
/jetson-promote-image
无法生效。

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:
RoleLocationSkill 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.
本技能编辑的配置文件相对路径为：
Linux_for_Tegra/rootfs/etc/nvpmodel/nvpmodel_<active-sku>.conf
该文件存在于两个根目录下；本技能会遍历这两个目录：
角色位置技能是否写入？
检测 + 原始源文件
<bsp_image.root_path>/Linux_for_Tegra/rootfs/etc/nvpmodel/
否——只读
覆盖编辑目标 + git提交
<source.root_path>/Linux_for_Tegra/rootfs/etc/nvpmodel/
是
后续章节中提到的单板配置文件均指
<source.root_path>
下的覆盖副本。操作1–4均针对该覆盖副本进行读取、编辑和保存。
<bsp_image.root_path>
下的副本仅在“解析
<active-sku>
”检测步骤和覆盖编辑流程的原始导入步骤中读取一次，之后不再触碰。

Resolving 
<active-sku>
— which file to edit

解析
<active-sku>
——确定要编辑的文件

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.
文件名不一定是
module.id + "_" + module.sku
。存在以下变体：
  • nvpmodel_p3767_0000_super.conf
    （超级模式SKU变体）
  • nvpmodel_igx_orin.conf
    、
    nvpmodel_igx_orin_safety.conf
    （IGX系列，无SKU编号）
开机时，
nvpower.sh
（位于
Linux_for_Tegra/rootfs/etc/systemd/nvpower.sh
）会读取内核DTB的根
compatible
字符串，并结合超级/安全状态映射到对应的nvpmodel文件名。在BSP侧，针对
<bsp_image.root_path>
复制该映射逻辑：
  1. 在
    <bsp_image.root_path>/Linux_for_Tegra/
    下找到与当前烧录配置匹配的SKU专属内核DTB，并读取其根
    compatible
    字段。
  2. 读取
    <bsp_image.root_path>/Linux_for_Tegra/rootfs/etc/systemd/nvpower.sh
    ，找到compatible字符串与配置文件的映射关系，并将上一步获取的compatible字段应用到该映射中（需考虑超级/安全标志）。
  3. 验证解析得到的
    nvpmodel_<...>.conf
    是否存在于
    <bsp_image.root_path>/Linux_for_Tegra/rootfs/etc/nvpmodel/
    下。
快捷方式：筛选
<bsp_image.root_path>/Linux_for_Tegra/rootfs/etc/nvpmodel/
下的
nvpmodel_<module.id>_<module.sku>*.conf
；对于超级模式烧录配置，选择带
_super
后缀的变体。仅当文件名无歧义时使用此快捷方式；否则回退到DTB方法。
请勿盲目拼接
nvpmodel_<id>_<sku>.conf
——必须验证文件确实存在。

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.
当前激活的SKU配置文件很少是唯一需要自定义的配置文件。编辑完成后，需将相同的编辑操作应用到同步集合中的所有同级文件，确保无论启动哪个模块/基板SKU，修改都能生效：
  • 参考平台的nvpmodel配置文件——当前文件派生自的上游配置文件（通过激活配置文件中的
    reference_devkit
    或
    jetson-derive-carrier
    派生谱系解析）。对于仅包含参考平台（无派生基板）的BSP，此文件与当前激活文件相同，规则自动失效。
  • 所有基板派生的nvpmodel配置文件——每个由
    jetson-derive-carrier
    为同一模块SKU的自定义基板生成的
    nvpmodel_*.conf
    文件。
  • 若存在
    _super
    同级文件（如
    nvpmodel_p3767_0000_super.conf
    ）——仅应用结构性编辑（新增POWER_MODEL代码块、删除代码块、修改
    PM_CONFIG DEFAULT=
    、重命名NAME），但需保留超级配置文件更高的MAX_FREQ / MIN_FREQ上限。这些提升的上限正是
    _super
    变体存在的意义；直接覆盖非超级文件的内容会悄无声息地抹平超级模式的频率范围。
“应用相同编辑”≠ 直接复制文件。需将修改后的POWER_MODEL / PARAM行移植到每个同级文件中；保留其他所有行。仅当两个配置文件在编辑前完全相同时，直接复制才是安全的。否则需针对每个目标文件重新验证规则（时钟值需在available-frequencies表中、ID唯一、
PM_CONFIG DEFAULT=
引用的ID存在）——同级配置文件可能包含SKU专属的
available_frequencies
表，无法兼容当前文件的频率值。

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)
    .
遵循工作流文档中的标准离线编辑流程——原始导入与自定义提交配对，均需通过预览 gate。每次运行执行一次，覆盖本次运行涉及的所有单板配置文件（当前激活配置文件以及同步集合中的所有同级文件）。
针对本技能的具体替换：
  • <rel>/<file>
    为
    rootfs/etc/nvpmodel/<conf>
    。
  • 建议的原始导入提交信息：
    import pristine: <逗号分隔的导入配置文件相对路径>
    ，正文为
    Source: <bsp_image.root_path>/Linux_for_Tegra/ (BSP <bsp_image.version>)
    。
  • 建议的自定义提交标题：
    jetson-customize-nvpmodel: <摘要>
    ，正文示例为
    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.
选择与用户意图匹配的操作，并遵循对应的子章节。所有写入类操作（1–4）必须先执行覆盖编辑流程。
  • 操作1——添加新电源模式（基于NVIDIA Power Estimator生成）。
  • 操作2——删除电源模式。
  • 操作3——编辑现有电源模式（频率限制、核心在线状态、NAME）。
  • 操作4——修改开机默认模式（
    PM_CONFIG DEFAULT=
    ）。
  • 操作5——列出已定义的电源模式（只读）。
执行任何写入类操作后，运行部署链（
## 部署
）将修改应用到设备上。

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
从Power Estimator导出的文件中添加新的30W电源模式，并将其设置为P3767-0001目标设备的开机默认模式：
/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
通过修改开机默认模式，将Thor目标设备限制在MAXN电源范围内（无需调整频率范围）：
/jetson-customize-nvpmodel
> set PM_CONFIG DEFAULT to the MAXN profile's ID
列出当前激活SKU已定义的电源模式以及开机默认模式：
/jetson-customize-nvpmodel
> list defined power modes

Operation 1 — Add a new power mode

操作1——添加新电源模式

Apply the Overlay edit recipe first.
先执行覆盖编辑流程。

Generate the profile via the Power Estimator

通过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.
禁止从现有配置文件插值或外推频率来估算功耗。
对于任何非标准电源范围（自定义功耗预算、自定义工作负载），请使用NVIDIA Power Estimator：
https://jetson-tools.nvidia.com/powerestimator/
  • 选择精确的模块SKU和JetPack版本。
  • 输入工作负载（CPU核心、GPU使用率、EMC、编解码器、摄像头、显示器）。
  • 估算功耗预算。
  • 下载自定义
    nvpmodel.conf
    文件。
  • 提供下载的
    nvpmodel.conf
    文件路径。

Append the POWER_MODEL block

追加POWER_MODEL代码块

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.
在单板配置文件中，将新代码块插入到最后一个
< PARAM … >
声明之后（POWER_MODEL必须引用已声明的PARAM），且在最终的
< PM_CONFIG ... >
行之前。代码块结构遵循上文的“文件格式”；频率值来自Power Estimator输出（见“通过Power Estimator生成配置文件”）。
检查
ID
是否唯一；
NAME
应为大写，无空格。每个数值型
MAX_FREQ
/ 
MIN_FREQ
值必须符合
available_frequencies
规则（见规则）。若要将此模式设置为开机默认模式，请执行操作4。

Operation 2 — Remove a power mode

操作2——删除电源模式

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:
    bash
    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.
先执行覆盖编辑流程。
  1. 在单板配置文件中，删除整个
    < POWER_MODEL ID=<n> NAME=... >
    代码块，包括其所有参数行，直到（但不包含）下一个
    < POWER_MODEL ... >
    或
    < PM_CONFIG ... >
    标记。
  2. 如果删除的ID与尾部
    < PM_CONFIG … >
    行中的当前
    DEFAULT=<id>
    值匹配，请将
    DEFAULT=
    指向一个剩余的ID——否则nvpmodel将无法在开机时应用默认模式。
  3. 在rootfs脚本中搜索硬编码引用，确认修改安全后再执行：
    bash
    grep -rn "nvpmodel -m" \
  Linux_for_Tegra/rootfs/etc \
  Linux_for_Tegra/rootfs/opt 2>/dev/null
ID允许存在间隙——无需重新编号剩余模式。

Operation 3 — Edit an existing power mode

操作3——编辑现有电源模式

Apply the Overlay edit recipe first.
  1. In the per-board file, edit the parameter lines inside the block. Keep 
    <param>
    and 
    <arg>
    names exactly matching the PARAM declarations.
  2. If the edit changes the power envelope (any CPU/GPU/EMC/PVA/DLA 
    MAX_FREQ
    / 
    MIN_FREQ
    , core-online count for a freq-bound mode, or TPC mask), re-run the NVIDIA Power Estimator (see "Generate the profile via the Power Estimator") to ground the new frequencies in a real per-component model. Do not interpolate from neighboring modes.
  3. Validate clock values per the 
    available_frequencies
    rule (see Rules).
Edits that only toggle core-online flags within an already-validated envelope, or only change 
NAME=
, don't need the Power Estimator pass.
先执行覆盖编辑流程。
  1. 在单板配置文件中，编辑代码块内的参数行。保持
    <param>
    和
    <arg>
    名称与PARAM声明完全一致。
  2. 如果修改涉及电源范围（任何CPU/GPU/EMC/PVA/DLA的
    MAX_FREQ
    / 
    MIN_FREQ
    、频率绑定模式下的核心在线数量、或TPC掩码），请重新运行NVIDIA Power Estimator（见“通过Power Estimator生成配置文件”），确保新频率基于真实的组件模型。禁止从相邻模式插值。
  3. 根据
    available_frequencies
    规则验证时钟值（见规则）。
仅在已验证的范围内切换核心在线状态，或仅修改
NAME=
的编辑操作，无需运行Power Estimator。

Operation 4 — Change the boot default

操作4——修改开机默认模式

Apply the Overlay edit recipe first.
Edit the 
< PM_CONFIG DEFAULT=<id> >
line at the bottom of the per-board file.
<id>
must reference an existing 
< POWER_MODEL ID=<id> … >
block in the same file. Pointing at an undefined ID makes nvpmodel fail to apply at boot.
先执行覆盖编辑流程。
编辑单板配置文件底部的
< PM_CONFIG DEFAULT=<id> >
行。
<id>
必须引用同一文件中已存在的
< POWER_MODEL ID=<id> … >
代码块。指向未定义的ID会导致nvpmodel在开机时无法应用默认模式。

Operation 5 — List defined power modes

操作5——列出已定义的电源模式

This is a read-only operation; no overlay-tracker setup is needed. Run against whichever copy you want to inspect (
<bsp_image.root_path>/...
for the pristine state, 
<source.root_path>/...
for the post-edit state):
bash
grep -E '^< POWER_MODEL ' <per-board file>
grep -E '^< PM_CONFIG '   <per-board file>
The first command prints every 
ID
/
NAME
; the second prints the current boot default. On a running target, 
nvpmodel -p --verbose
(or 
nvpmodel -q
) is authoritative.
此为只读操作；无需设置overlay tracker。可针对任意副本运行（
<bsp_image.root_path>/...
为原始状态，
<source.root_path>/...
为编辑后状态）：
bash
grep -E '^< POWER_MODEL ' <per-board file>
grep -E '^< PM_CONFIG '   <per-board file>
第一条命令会打印所有
ID
/
NAME
；第二条命令会打印当前开机默认模式。在运行中的目标设备上，
nvpmodel -p --verbose
（或
nvpmodel -q
）的输出为权威结果。

Limitations

限制

  • BSP-side scope only — this skill never invokes 
    nvpmodel -m
    on a running target. Live mode switching requires reboot via Deploy, or the side-channel 
    scp + nvpmodel -m
    flow described in 
    ## Deploy
    .
  • Edits land in the overlay copy under 
    <source.root_path>
    only; the 
    <bsp_image.root_path>
    copy is read-only and is rewritten by 
    /jetson-promote-image
    . Hand-editing 
    bsp_image
    is silently lost on the next 
    /jetson-init-image
    re-extract.
  • Frequency values must come from the kernel's 
    available_frequencies
    table for the relevant clock — values outside the table get silently rounded. This skill does not validate against a live target's table; trust the per-board file's existing values and Power Estimator output.
  • Non-trivial envelope edits (any CPU/GPU/EMC/PVA/DLA 
    MAX_FREQ
    / 
    MIN_FREQ
    change) require the NVIDIA Power Estimator (
    https://jetson-tools.nvidia.com/powerestimator/
    ) — interpolation or extrapolation between existing modes is not supported.
  • Propagation across siblings is partial by design: only the changed 
    POWER_MODEL
    / 
    PARAM
    lines are ported, never a blanket file overwrite, since 
    _super
    siblings carry elevated 
    MAX_FREQ
    /
    MIN_FREQ
    caps that must stay intact.
  • PARAM names are chip-family-specific (e.g. 
    CPU_A78_<n>
    on T234, different on T264). Copy verbatim from existing POWER_MODEL blocks; invented names silently fail to apply.
  • 仅限BSP侧范围——本技能不会在运行中的目标设备上调用
    nvpmodel -m
    。实时切换模式需要通过部署链重启设备，或使用
    ## 部署
    中描述的
    scp + nvpmodel -m
    旁路流程。
  • 编辑仅会存入
    <source.root_path>
    下的覆盖副本；
    <bsp_image.root_path>
    下的副本为只读，会被
    /jetson-promote-image
    重写。手动编辑
    bsp_image
    会在下次
    /jetson-init-image
    重新提取时悄无声息地丢失。
  • 频率值必须来自对应时钟的内核
    available_frequencies
    表——不在表中的值会被自动取整。本技能不会针对运行中的目标设备的表进行验证；请信任单板配置文件中的现有值和Power Estimator输出。
  • 非 trivial 的范围编辑（任何CPU/GPU/EMC/PVA/DLA的
    MAX_FREQ
    / 
    MIN_FREQ
    修改）需要使用NVIDIA Power Estimator（
    https://jetson-tools.nvidia.com/powerestimator/
    ）——不支持在现有模式之间插值或外推。
  • 同级文件间的同步是部分同步：仅移植修改后的
    POWER_MODEL
    / 
    PARAM
    行，绝不会直接覆盖整个文件，因为
    _super
    同级文件包含更高的
    MAX_FREQ
    /
    MIN_FREQ
    上限，必须保留。
  • PARAM名称为芯片系列专属（如T234上的
    CPU_A78_<n>
    ，T264上的命名不同）。请严格复制现有POWER_MODEL代码块中的名称；自行创造的名称会悄无声息地失效。

Troubleshooting

故障排查

ErrorCauseSolution
nvpmodel fails to apply default at boot
PM_CONFIG DEFAULT=<id>
references a deleted or missing POWER_MODEL ID		Point 
DEFAULT=
at an existing 
< POWER_MODEL ID=<n> ... >
in the same file.
Frequency value silently doesn't take effectValue not in the kernel's 
available_frequencies
table for that clock		Replace with the nearest legal value from the running target's 
available_frequencies
(or Power Estimator output).
MAX_FREQ -1
does nothing
-1
on a 
TYPE=FILE
PARAM (only valid for 
TYPE=CLOCK
)		Use 
-1
only on CLOCK params; for FILE params, write the actual string the sysfs node expects.
Module dies / fails to boot after edit
CORE_0
was offlined, or the mode dropped below the platform's minimum quiescent envelope		Keep 
CORE_0
online; floor 
MIN_FREQ
per the Power Estimator's lowest-power profile for the SKU.
nvpmodel -m <id>
returns "ID not found" at runtime		Mode ID was removed or renumbered but a rootfs script still references the old ID
grep -rn 'nvpmodel -m' rootfs/etc rootfs/opt
and update / remove the stale references.
Change vanished after 
/jetson-init-image
re-extract		Edit landed in 
<bsp_image.root_path>
instead of 
<source.root_path>
overlay		Re-apply via the Overlay edit recipe so the change is committed in the overlay tracker.
_super
sibling lost elevated caps after propagation		Blanket file copy clobbered 
_super
's higher 
MAX_FREQ
/
MIN_FREQ
Port only the structural change; preserve 
_super
's caps per Propagation set.
Parser rejects new POWER_MODEL blockHeader 
< … >
not at column 0, missing space after 
<
or before 
>
, or PARAM not declared earlier		Restore strict header formatting; ensure every referenced 
PARAM_NAME
appears in a 
< PARAM ... >
block above.
错误原因解决方案
nvpmodel开机时无法应用默认模式
PM_CONFIG DEFAULT=<id>
引用了已删除或不存在的POWER_MODEL ID		将
DEFAULT=
指向同一文件中已存在的
< POWER_MODEL ID=<n> ... >
。
频率值悄无声息地未生效值不在对应时钟的内核
available_frequencies
表中		替换为运行中目标设备
available_frequencies
中的最近合法值（或Power Estimator输出）。
MAX_FREQ -1
无效果
-1
用于
TYPE=FILE
类型的PARAM（仅对
TYPE=CLOCK
有效）		仅在CLOCK类型的PARAM中使用
-1
；对于FILE类型的PARAM，请写入sysfs节点所需的实际字符串。
编辑后模块死机/无法开机
CORE_0
被设置为离线，或模式低于平台的最低静态功耗范围		保持
CORE_0
在线；根据Power Estimator为该SKU提供的最低功耗配置文件设置
MIN_FREQ
下限。
运行时
nvpmodel -m <id>
返回“ID not found”		模式ID已被删除或重命名，但rootfs脚本仍引用旧ID执行
grep -rn 'nvpmodel -m' rootfs/etc rootfs/opt
并更新/移除过时的引用。
/jetson-init-image
重新提取后修改消失		编辑存入了
<bsp_image.root_path>
而非
<source.root_path>
的覆盖副本		通过覆盖编辑流程重新应用修改，确保变更提交到overlay tracker中。
同步后
_super
同级文件丢失了提升的上限		直接复制文件覆盖了
_super
的更高
MAX_FREQ
/
MIN_FREQ
值		仅移植结构性修改；根据同步集合保留
_super
的上限。
解析器拒绝新的POWER_MODEL代码块头部
< … >
不在第0列、
<
或
>
前后缺少空格、或PARAM未提前声明		恢复严格的头部格式；确保所有引用的
PARAM_NAME
都出现在上方的
< PARAM ... >
代码块中。

Deploy

部署

The customization commit in the overlay tracker does not reach the device on its own. The Deploy chain:
  1. /jetson-promote-image
     — copies every tracked file in the overlay into 
    <bsp_image.root_path>/Linux_for_Tegra/
    . Diff-aware (skip byte-identical); uses 
    sudo cp -p
    for 
    rootfs/*
    destinations.
  2. /jetson-flash-image
     — flashes the updated 
    bsp_image
    to the device.
  3. (Alternate, no flash) Copy 
    <source.root_path>/Linux_for_Tegra/rootfs/etc/nvpmodel/<conf>
    directly to the running target's 
    /etc/nvpmodel/<conf>
    , then 
    sudo nvpmodel -m <id>
    (or reboot to pick up the new 
    DEFAULT=
    ).
Editing 
<source.root_path>/...
without committing — or editing 
<bsp_image.root_path>/...
directly — does nothing for 
/jetson-promote-image
and is silently lost on the next 
/jetson-init-image
re-extract.
overlay tracker中的自定义提交不会自动同步到设备上。部署链步骤如下：
  1. /jetson-promote-image
    ——将overlay中所有被追踪的文件复制到
    <bsp_image.root_path>/Linux_for_Tegra/
    。支持差异感知（跳过完全相同的文件）；针对
    rootfs/*
    目标使用
    sudo cp -p
    。
  2. /jetson-flash-image
    ——将更新后的
    bsp_image
    烧录到设备上。
  3. （替代方案，无需烧录）将
    <source.root_path>/Linux_for_Tegra/rootfs/etc/nvpmodel/<conf>
    直接复制到运行中目标设备的
    /etc/nvpmodel/<conf>
    ，然后执行
    sudo nvpmodel -m <id>
    （或重启设备以应用新的
    DEFAULT=
    ）。
编辑
<source.root_path>/...
但未提交——或直接编辑
<bsp_image.root_path>/...
——对
/jetson-promote-image
无任何作用，且会在下次
/jetson-init-image
重新提取时悄无声息地丢失。