Back to Details

jetson-customize-clocks

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Customize Clocks

定制时钟

Purpose

用途

Customize CPU, GPU, and EMC clock behavior on a Jetson target by editing files under 
Linux_for_Tegra/
before flashing the image. Two layers are in scope:
  • The BPMP DTB at 
    Linux_for_Tegra/bootloader/<BPFDTB_FILE>
    — per-clock 
    max-rate-custom
    ceilings, plus the EMC DVFS gate (bwmgr + cactmon on all SoCs; osp-controller on T26x only).
  • nvpower.sh at 
    Linux_for_Tegra/rootfs/etc/systemd/nvpower.sh
    — cpufreq / devfreq governors and (optionally) per-device min / max / static rates written to sysfs at boot.
Common triggers: "lock CPU/GPU/EMC frequency", "pin GPU to Fmax", "pin EMC to MAXN", "disable/enable EMC DVFS", "disable/enable CPU DVFS", "set CPU/GPU max rate", "change cpufreq governor".
Out of scope: runtime clock tuning on a live target (no flash step), nvpmodel power-mode edits (use the sibling skill 
/jetson-customize-nvpmodel
), and silicon-ceiling overrides (
max-rate-maxn
is read-only).
通过在刷机前编辑
Linux_for_Tegra/
下的文件，定制Jetson目标设备上的CPU、GPU和EMC时钟行为。涉及两个层面的配置：
  • BPMP DTB：位于
    Linux_for_Tegra/bootloader/<BPFDTB_FILE>
    —— 针对每个时钟的
    max-rate-custom
    上限，以及EMC DVFS控制（所有SoC上的bwmgr + cactmon；仅T26x上的osp-controller）。
  • nvpower.sh：位于
    Linux_for_Tegra/rootfs/etc/systemd/nvpower.sh
    —— cpufreq / devfreq调控器，以及（可选）在启动时写入sysfs的设备专属最小/最大/固定速率。
常见使用场景："锁定CPU/GPU/EMC频率"、"将GPU固定在Fmax"、"将EMC固定在MAXN"、"禁用/启用EMC DVFS"、"禁用/启用CPU DVFS"、"设置CPU/GPU最大速率"、"更改cpufreq调控器"。
不适用场景：对运行中的目标设备进行实时时钟调优（无需刷机步骤）、nvpmodel功耗模式编辑（使用关联技能
/jetson-customize-nvpmodel
）、以及硅上限覆盖（
max-rate-maxn
为只读）。

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 (Operation 1's BPMP DTB and Operation 2's 
nvpower.sh
) 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>
对此技能而言是只读的；所有写入操作（操作1的BPMP DTB和操作2的
nvpower.sh
）均存储在
<source.root_path>
（覆盖跟踪器）下。这是
../../context/bsp-customization-workflow.md#workflow-invariants
中规定的工作流不变量——手动编辑上游内容会静默破坏差异追踪，导致
/jetson-promote-image
无法生效。

Instructions

操作步骤

  1. Resolve the prerequisites above (active profile, BSP image extracted, source overlay tracker initialized).
  2. Pick the operation from the table below.
  3. Follow the linked procedure section — Operation 1 (BPMP DTB), Operation 2 (
    nvpower.sh
    ), or the MAXN recipe for both.
  4. Commit the edit inside the overlay tracker per each Operation's commit convention.
  5. Deploy with 
    /jetson-promote-image
    → 
    /jetson-flash-image
    . The new BPMP DTB and 
    nvpower.sh
    take effect on the next boot.
  1. 完成上述前置条件（激活配置文件、提取BSP镜像、初始化源码覆盖跟踪器）。
  2. 从下表中选择对应的操作。
  3. 遵循链接的步骤章节——操作1（BPMP DTB）、操作2（
    nvpower.sh
    ），或同时执行两者的MAXN方案。
  4. 根据每个操作的提交规范，在覆盖跟踪器中提交编辑内容。
  5. 通过
    /jetson-promote-image
    → 
    /jetson-flash-image
    部署。新的BPMP DTB和
    nvpower.sh
    将在下次启动时生效。

Supported operations

支持的操作

OperationWhere the edit livesProcedure section
Lock a CPU / GPU clock to a specific rateBPMP DTB 
max-rate-custom
on the clock node + 
nvpower.sh
governor 
performance
"Content edit: 
max-rate-custom
" + "Pick the edit"
Lock EMC at its init rate (disable EMC DVFS)BPMP DTB: 
bwmgr.enabled = 0
, 
cactmon.enabled = 0
, plus 
/delete-node/ osp-controller
on T26x only		"Content edit: EMC DVFS disable / enable"
Re-enable EMC DVFSBPMP DTB: 
bwmgr.enabled = 1
, 
cactmon.enabled = 1
, restore 
osp-controller
on T26x		"Content edit: EMC DVFS disable / enable"
Pin everything to MAXN for stress runsCombine the above + nvpmodel MAXN as boot defaultsee Recipe
Lower a clock's hard ceiling without lockingBPMP DTB 
max-rate-custom
only		"Content edit: 
max-rate-custom
"
Bound a device's rate without pinning
nvpower.sh
min/max via sysfs		"Pick the edit"
操作编辑位置步骤章节
将CPU/GPU时钟锁定至特定速率BPMP DTB中时钟节点的
max-rate-custom
+ 
nvpower.sh
调控器设为
performance
"内容编辑：
max-rate-custom
" + "选择编辑项"
将EMC锁定在初始速率（禁用EMC DVFS）BPMP DTB：
bwmgr.enabled = 0
，
cactmon.enabled = 0
；仅T26x需添加
/delete-node/ osp-controller
"内容编辑：禁用/启用EMC DVFS"
重新启用EMC DVFSBPMP DTB：
bwmgr.enabled = 1
，
cactmon.enabled = 1
；恢复T26x的
osp-controller
节点		"内容编辑：禁用/启用EMC DVFS"
将所有组件固定在MAXN模式以进行压力测试结合上述操作 + 将nvpmodel MAXN设为启动默认模式查看方案
降低时钟硬上限但不锁定仅修改BPMP DTB的
max-rate-custom
"内容编辑：
max-rate-custom
"
限制设备速率但不固定通过sysfs在
nvpower.sh
中设置最小/最大速率		"选择编辑项"

Operation 1 — BPMP DTB edits

操作1 —— BPMP DTB编辑

Follow the BPMP-DTB customization protocol in 
../../references/bsp-customization-bpmp-dtb.md
. The protocol owns the mechanics — pristine import on first touch, 
dtc
decompile, recompile, sanity-check, commit. This skill supplies only the clock-specific content (which nodes and properties to edit during the protocol's "Edit the DTS" step).
The edited 
.dtb
lands in the 
<source.root_path>/Linux_for_Tegra/
overlay tracker. 
/jetson-promote-image
's channel A walks the tracker and copies the file into 
bsp_image
. Do not edit 
<bsp_image.root_path>/Linux_for_Tegra/bootloader/<bpmp-dtb>
directly — that's the promote output, not an input.
遵循
../../references/bsp-customization-bpmp-dtb.md
中的BPMP-DTB定制协议。该协议负责具体操作流程——首次操作时导入原始文件、使用
dtc
反编译、重新编译、完整性检查、提交。本技能仅提供时钟相关的内容（即在协议的"编辑DTS"步骤中需要修改的节点和属性）。
编辑后的
.dtb
文件存储在
<source.root_path>/Linux_for_Tegra/
覆盖跟踪器中。
/jetson-promote-image
的通道A会遍历跟踪器并将文件复制到
bsp_image
中。请勿直接编辑
<bsp_image.root_path>/Linux_for_Tegra/bootloader/<bpmp-dtb>
——这是推送操作的输出，而非输入。

Resolve the SKU-correct BPMP DTB

解析与SKU匹配的BPMP DTB

Per the protocol's "Resolving the active BPMP DTB" section, read 
BPFDTB_FILE
from the active flash conf. For the common Thor / single-SKU conf shapes this is the static 
BPFDTB_FILE=...
line in the per-board 
.conf
and the value is authoritative as-is.
For SKU-multiplexed conf shapes (Orin AGX devkit conf chain that selects a different BPMP DTB per 
board_sku
/
board_FAB
via 
update_flash_args_common
— see 
../../context/bsp-customization-software-layers.md#per-board-conf-dispatch--update_flash_args_common
), walk the dispatch chain with 
board_sku=<module.sku>
and 
board_FAB=<module.revision or empty>
from the active profile, and read 
BPFDTB_FILE
from the dispatch output — not from the static line of the per-board 
.conf
. Static and dispatched values match for non-multiplexed confs; the dispatch is mandatory only when the conf chain conditionally overrides 
BPFDTB_FILE
.
根据协议的"解析激活的BPMP DTB"章节，从激活的刷机配置文件中读取
BPFDTB_FILE
。对于常见的Thor/单一SKU配置文件，这是单板
.conf
文件中的静态
BPFDTB_FILE=...
行，其值即为权威值。
对于SKU多路复用配置文件（Orin AGX开发板配置链，通过
update_flash_args_common
根据
board_sku
/
board_FAB
选择不同的BPMP DTB——详见
../../context/bsp-customization-software-layers.md#per-board-conf-dispatch--update_flash_args_common
），需结合激活配置文件中的
board_sku=<module.sku>
和
board_FAB=<module.revision or empty>
遍历调度链，从调度输出中读取
BPFDTB_FILE
——不要从单板
.conf
的静态行中读取。对于非多路复用配置文件，静态值和调度值一致；仅当配置链有条件地覆盖
BPFDTB_FILE
时，才必须使用调度方式解析。

List effective max rates (inspection)

查看有效最大速率（检查）

Inspect both layers of the runtime ceiling — see 
references/clock-control-model.md#effective-runtime-ceiling
 — before deciding on a 
max-rate-custom
value.
Inspection cookbook (BPMP-side decompile + grep; nvpmodel-side awk over the boot default mode) is in 
references/bpmp-dtb-clock-edits.md#inspection-cookbook
.
For the nvpmodel layer see 
/jetson-customize-nvpmodel
.
This step does not mutate state — it's a precondition for sizing the edit in the "Content edit: 
max-rate-custom
on a named clock node" step.
在决定
max-rate-custom
值之前，检查运行时上限的两个层面——详见
references/clock-control-model.md#effective-runtime-ceiling
。
检查方法（BPMP侧反编译+ grep；nvpmodel侧通过awk分析启动默认模式）详见
references/bpmp-dtb-clock-edits.md#inspection-cookbook
。
关于nvpmodel层面的内容，请查看
/jetson-customize-nvpmodel
。
此步骤不会改变系统状态——是"内容编辑：指定时钟节点的
max-rate-custom
"步骤中确定编辑内容的前置条件。

Content edit: 
max-rate-custom
on a named clock node

内容编辑：指定时钟节点的
max-rate-custom

During the "Edit the DTS" step of the protocol, modify the property inside the named clock node — never 
lateinit
. 
max-rate-custom
must be strictly below the clock's hard cap (
max-rate-maxn
if defined, otherwise the live 
max_rate
from a running target of the same chip / SKU).
DTS edit form, semantics, and the nvpmodel ↔ BPMP clock-node mapping live in 
references/bpmp-dtb-clock-edits.md
.
Then hand control back to the protocol — its "Recompile", "Sanity-check the recompiled blob", "Stage in the overlay tracker", and "Cleanup" steps cover the rest. Commit-message convention per the protocol: 
<BPMP_BASENAME>: jetson-customize-clocks — <clock-node> max-rate-custom = <value>
.
在协议的"编辑DTS"步骤中，修改指定时钟节点内的属性——切勿修改
lateinit
。
max-rate-custom
必须严格低于时钟的硬上限（若定义了
max-rate-maxn
则以此为准，否则以同芯片/SKU的运行中设备的实时
max_rate
为准）。
DTS编辑格式、语义以及nvpmodel ↔ BPMP时钟节点映射详见
references/bpmp-dtb-clock-edits.md
。
之后将控制权交还给协议——其"重新编译"、"检查重新编译后的二进制文件完整性"、"在覆盖跟踪器中暂存"和"清理"步骤会处理后续操作。提交消息需遵循协议规范：
<BPMP_BASENAME>: jetson-customize-clocks — <clock-node> max-rate-custom = <value>
。

Content edit: EMC DVFS disable / enable

内容编辑：禁用/启用EMC DVFS

Default behavior (EMC DVFS on) requires no edit. Disabling EMC DVFS is a multi-node edit applied inside the same "Edit the DTS" step of the protocol, not a 
bwmgr
toggle:
#EditScope
1
bwmgr.enabled = <0x00>
All SoCs, mandatory
2
cactmon.enabled = <0x00>
All SoCs, mandatory
3
/delete-node/ osp-controller
T26x (Thor) mandatory — T23x (Orin) has no such node, skip
Detection: 
dtc -I dtb -O dts <bpmp-dtb> | grep -c osp-controller
— zero hits ⇒ T23x path. Full DTS snippets, the surviving-paths failure modes, and the re-enable procedure are in 
references/emc-dvfs-disable.md
.
Apply the protocol's "Recompile" through "Cleanup" steps once the multi-node edit is in place. Commit-message convention: 
<BPMP_BASENAME>: jetson-customize-clocks — EMC DVFS disable (bwmgr + cactmon[+ osp-controller])
.
Disabling raises idle power; intended for stress / performance tests, not production rootfs.
默认行为（EMC DVFS启用）无需编辑。禁用EMC DVFS是多节点编辑，需在协议的同一"编辑DTS"步骤中完成，不能仅切换
bwmgr
：
序号编辑内容适用范围
1
bwmgr.enabled = <0x00>
所有SoC，必填
2
cactmon.enabled = <0x00>
所有SoC，必填
3
/delete-node/ osp-controller
仅T26x (Thor) 必填 —— T23x (Orin) 无此节点，跳过
检测方法：
dtc -I dtb -O dts <bpmp-dtb> | grep -c osp-controller
—— 结果为0 ⇒ 采用T23x流程。完整的DTS代码片段、可能出现的失败场景以及重新启用的步骤详见
references/emc-dvfs-disable.md
。
完成多节点编辑后，执行协议的"重新编译"至"清理"步骤。提交消息规范：
<BPMP_BASENAME>: jetson-customize-clocks — EMC DVFS disable (bwmgr + cactmon[+ osp-controller])
。
禁用EMC DVFS会增加 idle 功耗；仅适用于压力/性能测试，不适用于生产根文件系统。

Re-run + idempotency

重复执行与幂等性

Per the protocol's "Re-runnability" section, re-running this skill with the same target value produces a no-op commit. Re- running with a different value rewrites the same property — 
git log -- $BPMP_REL
shows the per-run history. To return a clock to its 
max-rate-maxn
ceiling, edit the DTS to remove the 
max-rate-custom
line and recompile.
根据协议的"可重复执行性"章节，使用相同目标值重复执行此技能会生成空提交。使用不同目标值重复执行会重写同一属性——
git log -- $BPMP_REL
可查看每次执行的历史记录。若要将时钟恢复至
max-rate-maxn
上限，需编辑DTS删除
max-rate-custom
行并重新编译。

Operation 2 — nvpower.sh edits

操作2 —— nvpower.sh编辑

Edits 
nvpower.sh
, which runs at boot via 
nvpower.service
to set cpufreq / devfreq governors and rates.
编辑
nvpower.sh
，该脚本通过
nvpower.service
在启动时运行，用于设置cpufreq / devfreq调控器和速率。

The per-script file

脚本文件路径

The script this Operation edits has the relative path:
Linux_for_Tegra/rootfs/etc/systemd/nvpower.sh
It lives in two roots; the Operation walks both:
RoleLocationSkill writes?
Detection + pristine source
<bsp_image.root_path>/Linux_for_Tegra/rootfs/etc/systemd/
no — read-only
Overlay edit target + git commit
<source.root_path>/Linux_for_Tegra/rootfs/etc/systemd/
yes
Subsequent sub-steps refer to the per-script file to mean the overlay copy under 
<source.root_path>
. The 
<bsp_image.root_path>
copy is read once during the pristine-import step below, then never touched again.
本操作编辑的脚本相对路径为：
Linux_for_Tegra/rootfs/etc/systemd/nvpower.sh
该脚本存在于两个路径下；本操作会遍历这两个路径：
角色位置技能是否可写入
检测与原始源文件
<bsp_image.root_path>/Linux_for_Tegra/rootfs/etc/systemd/
否 —— 只读
覆盖编辑目标与git提交
<source.root_path>/Linux_for_Tegra/rootfs/etc/systemd/
是
后续子步骤中提到的脚本文件均指
<source.root_path>
下的覆盖副本。
<bsp_image.root_path>
下的副本仅在原始导入步骤中读取一次，之后不再触碰。

Overlay edit recipe (apply before editing nvpower.sh)

覆盖编辑方案（编辑nvpower.sh前执行）

Follow the canonical Off-skill edits recipe in the workflow doc — pristine import + customization commit pair, both gated by the preview gate. 
nvpower.sh
is a single file with no propagation set; one pristine commit + one customization commit covers the entire change.
Concrete substitutions for this skill:
  • <rel>/<file>
    is 
    rootfs/etc/systemd/nvpower.sh
    .
  • Suggested pristine-import message: 
    import pristine: rootfs/etc/systemd/nvpower.sh
    , body 
    Source: <bsp_image.root_path>/Linux_for_Tegra/ (BSP <bsp_image.version>)
    .
  • Suggested customization-commit header: 
    jetson-customize-clocks: nvpower.sh <summary>
    , body lines like 
    set_cpufreq_governor: desired_cpufreq_gov "schedutil" -> "performance"
    .
遵循工作流文档中的标准非技能编辑方案——原始导入+定制提交的组合，均受预览门控。
nvpower.sh
是单个无传播设置的文件；一次原始提交+一次定制提交即可覆盖所有修改。
针对本技能的具体替换：
  • <rel>/<file>
    为
    rootfs/etc/systemd/nvpower.sh
    。
  • 建议的原始导入提交消息：
    import pristine: rootfs/etc/systemd/nvpower.sh
    ，提交说明为
    Source: <bsp_image.root_path>/Linux_for_Tegra/ (BSP <bsp_image.version>)
    。
  • 建议的定制提交标题：
    jetson-customize-clocks: nvpower.sh <summary>
    ，提交说明示例：
    set_cpufreq_governor: desired_cpufreq_gov "schedutil" -> "performance"
    。

Pick the edit

选择编辑项

Function locations (
set_cpufreq_governor
, 
set_devfreq_governor
), common-edit recipes (pin to Fmax, static rate, min/max bounds), and the 
nvidia-l4t-init
package-upgrade caveat live in 
references/nvpower-sh-edits.md
.
函数位置（
set_cpufreq_governor
、
set_devfreq_governor
）、常见编辑方案（固定在Fmax、固定速率、最小/最大限制）以及
nvidia-l4t-init
包升级注意事项详见
references/nvpower-sh-edits.md
。

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. 
    nvpower.service
    runs the new script on the next boot.
  3. (Alternate, no flash) Copy 
    <source.root_path>/Linux_for_Tegra/rootfs/etc/systemd/nvpower.sh
    directly to the running target's 
    /etc/systemd/nvpower.sh
    , then 
    sudo systemctl restart nvpower.service
    (or reboot).
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.
覆盖跟踪器中的定制提交不会自动同步到设备。部署流程如下：
  1. /jetson-promote-image
     —— 将覆盖跟踪器中所有跟踪的文件复制到
    <bsp_image.root_path>/Linux_for_Tegra/
    。支持差异识别（跳过字节完全相同的文件）；对
    rootfs/*
    目标使用
    sudo cp -p
    。
  2. /jetson-flash-image
     —— 将更新后的
    bsp_image
    刷入设备。
    nvpower.service
    会在下次启动时运行新脚本。
  3. （无需刷机的替代方案）将
    <source.root_path>/Linux_for_Tegra/rootfs/etc/systemd/nvpower.sh
    直接复制到运行中设备的
    /etc/systemd/nvpower.sh
    ，然后执行
    sudo systemctl restart nvpower.service
    （或重启设备）。
若编辑
<source.root_path>/...
但未提交——或直接编辑
<bsp_image.root_path>/...
——则
/jetson-promote-image
不会识别这些修改，且在下次
/jetson-init-image
重新提取时会静默丢失。

Recipe — pin everything to MAXN for stress / performance runs

方案——将所有组件固定在MAXN模式以进行压力/性能测试

Combines Operations 1 + 2. Operation 1's BPMP edits all flow through one round of the protocol (a single decompile / multi-node edit / recompile / commit cycle — don't round-trip the protocol twice for the same 
.dtb
):
  1. BPMP DTB (the "Content edit: 
    max-rate-custom
    on a named clock node" step content): leave 
    max-rate-custom
    unset on every CPU / GPU / EMC clock; remove existing 
    max-rate-custom
    lines that lower the ceiling.
  2. BPMP DTB (the "Content edit: EMC DVFS disable / enable" step content): pin EMC at its init rate — 
    bwmgr.enabled = 0
    , 
    cactmon.enabled = 0
    , plus 
    /delete-node/ osp-controller
    on T26x (skip on T23x).
  3. Apply both content edits inside one protocol "Edit the DTS" invocation, then run the remaining protocol steps (recompile, sanity-check, single customization commit covering both content edits).
  4. nvpower.sh (Operation 2): set 
    desired_cpufreq_gov="performance"
    and 
    desired_devfreq_gov="performance"
    unconditionally; remove the GPU/nvjpg skip in 
    set_devfreq_governor
    . Applies via Operation 2's overlay edit recipe (the "Overlay edit recipe (apply before editing nvpower.sh)" step) — a separate overlay-tracker pristine + customization commit pair on the rootfs script, distinct from the BPMP-DTB protocol's commit.
  5. Set the boot-default nvpmodel mode to MAXN via 
    /jetson-customize-nvpmodel
     — the per-clock nvpmodel cap clamps below 
    max-rate-maxn
    regardless of BPMP DTB content.
Deploy 
/jetson-promote-image
 → 
/jetson-flash-image
 picks up the new BPMP DTB (via the overlay tracker) and the edited 
nvpower.sh
(via the same overlay tracker) on the next flash.
结合操作1和操作2。操作1的BPMP编辑需通过一轮协议完成（单次反编译/多节点编辑/重新编译/提交周期——请勿对同一
.dtb
重复执行协议）：
  1. BPMP DTB（"内容编辑：指定时钟节点的
    max-rate-custom
    "步骤内容）：所有CPU/GPU/EMC时钟均不设置
    max-rate-custom
    ；删除所有降低上限的现有
    max-rate-custom
    行。
  2. BPMP DTB（"内容编辑：禁用/启用EMC DVFS"步骤内容）：将EMC固定在初始速率——
    bwmgr.enabled = 0
    ，
    cactmon.enabled = 0
    ；T26x需添加
    /delete-node/ osp-controller
    （T23x跳过）。
  3. 在一次协议的"编辑DTS"调用中完成上述两项内容编辑，然后执行协议的剩余步骤（重新编译、完整性检查、涵盖两项内容编辑的单次定制提交）。
  4. nvpower.sh（操作2）：无条件设置
    desired_cpufreq_gov="performance"
    和
    desired_devfreq_gov="performance"
    ；删除
    set_devfreq_governor
    中的GPU/nvjpg跳过逻辑。通过操作2的覆盖编辑方案（"覆盖编辑方案（编辑nvpower.sh前执行）"步骤）应用——对根文件系统脚本进行单独的覆盖跟踪器原始+定制提交，与BPMP-DTB协议的提交分开。
  5. 通过
    /jetson-customize-nvpmodel
    将启动默认nvpmodel模式设为MAXN——无论BPMP DTB内容如何，每个时钟的nvpmodel上限都会低于
    max-rate-maxn
    。
部署时，
/jetson-promote-image
→ 
/jetson-flash-image
会在下次刷机时读取覆盖跟踪器中的新BPMP DTB和编辑后的
nvpower.sh
。

Limitations

限制

  • Image-build-time only. All edits land under 
    <source.root_path>/Linux_for_Tegra/
    and reach the device only via 
    /jetson-promote-image
    → 
    /jetson-flash-image
    . Live-target tuning is out of scope.
  • max-rate-custom
    only lowers the ceiling.     It must be strictly below 
    max-rate-maxn
    ; raising the silicon cap is not supported.
  • Effective ceiling is two-layer. The runtime ceiling is 
    min(BPMP cap, active-nvpmodel-mode cap)
    . The nvpmodel cap is owned by 
    /jetson-customize-nvpmodel
    ; this skill does not edit it.
  • SoC-conditional EMC DVFS gate. Disabling EMC DVFS requires editing different node sets on T23x (bwmgr + cactmon) vs T26x (bwmgr + cactmon + delete 
    osp-controller
    ). Mis-detection produces undefined behavior.
  • T23x GPU cap is multi-node. The GPU clock is split across 
    nafll_gpusys
    and every 
    nafll_gpcX
    ; the cap binds only when applied to all of them.
  • nvpower.sh
    is package-managed.     It ships in 
    nvidia-l4t-init
    ; package upgrades clobber in-place edits. Long-lived setups should prefer a systemd drop-in or sibling helper.
  • ODMDATA wins. When an ODMDATA token covers a property, the token overrides direct BPMP DTS edits at flash time. Direct BPMP DTS edits are the fallback for properties no NVIDIA token reaches.
  • max-rate-maxn
    and 
    lateinit
    are off-limits.     
    max-rate-maxn
    is the silicon ceiling (read-only). 
    lateinit
    is for boot-time clock init, not ceiling overrides — never touch either.
  • BPMP DTB may be SKU-multiplexed. On compound / dispatched flash confs (Orin AGX devkit chain), 
    BPFDTB_FILE
    is selected by 
    board_sku
    / 
    board_FAB
    via 
    update_flash_args_common
    . Reading the static 
    BPFDTB_FILE=
    line is wrong when the chain conditionally overrides it; resolve via the dispatch instead.
  • 仅支持镜像构建时操作。所有编辑均存储在
    <source.root_path>/Linux_for_Tegra/
    下，仅能通过
    /jetson-promote-image
    → 
    /jetson-flash-image
    同步到设备。不支持对运行中设备进行调优。
  • max-rate-custom
    仅能降低上限    。必须严格低于
    max-rate-maxn
    ；不支持提高硅上限。
  • 有效上限为双层机制。运行时上限为
    min(BPMP上限, 激活的nvpmodel模式上限)
    。nvpmodel上限由
    /jetson-customize-nvpmodel
    负责；本技能不编辑该上限。
  • EMC DVFS控制因SoC而异。禁用EMC DVFS在T23x（bwmgr + cactmon）和T26x（bwmgr + cactmon + 删除
    osp-controller
    ）上需要编辑不同的节点集。检测错误会导致未定义行为。
  • T23x GPU上限为多节点。GPU时钟分为
    nafll_gpusys
    和所有
    nafll_gpcX
    ；必须对所有节点应用上限才能生效。
  • nvpower.sh
    受包管理控制    。它属于
    nvidia-l4t-init
    包；包升级会覆盖本地编辑。长期使用的环境应优先使用systemd扩展配置或关联辅助脚本。
  • ODMDATA优先级更高。当ODMDATA令牌涵盖某个属性时，该令牌会在刷机时覆盖直接的BPMP DTS编辑。直接的BPMP DTS编辑仅作为NVIDIA令牌未覆盖属性的 fallback 方案。
  • max-rate-maxn
    和
    lateinit
    不可修改    。
    max-rate-maxn
    是硅上限（只读）。
    lateinit
    用于启动时时钟初始化，而非上限覆盖——切勿修改两者。
  • BPMP DTB可能为SKU多路复用。在复合/调度刷机配置文件（Orin AGX开发板链）中，
    BPFDTB_FILE
    通过
    update_flash_args_common
    根据
    board_sku
    /
    board_FAB
    选择。当配置链有条件地覆盖该值时，读取静态
    BPFDTB_FILE=
    行是错误的；需通过调度方式解析。

Troubleshooting

故障排除

ErrorCauseSolution
max-rate-custom
set but clock still ramps to 
max-rate-maxn
on T23x GPU		Only 
nafll_gpusys
was capped; the 
nafll_gpcX
partitions still run at 
max-rate-maxn
and dominate the effective ceiling.		Apply the same 
max-rate-custom
to 
nafll_gpusys
and every 
nafll_gpcX
node enumerated by 
grep -nE '^\s*nafll_gpc[0-9]+\s*:' <decompiled.dts>
.
EMC DVFS disable appears to apply but EMC still scales on T26xOnly 
bwmgr.enabled = <0x00>
was set; 
osp-controller
survives and re-issues frequency changes via the QoS path.		Add edits #2 (
cactmon.enabled = <0x00>
) and #3 (
/delete-node/ osp-controller
) inside the same "Edit the DTS" step. Verify 
osp-controller
via 
dtc -I dtb -O dts <bpmp-dtb> | grep -c osp-controller
→ expect 0.
EMC DVFS disable rejected on T23x with "node not found" for 
osp-controller
T23x (Orin) BPMP DTBs do not contain 
osp-controller
; edit #3 must be skipped on T23x.		Detect SoC family with the 
grep -c osp-controller
step; only apply #3 when the count is ≥1.
BPMP refuses to load DTB after edit: 
max-rate-custom >= max-rate-maxn
max-rate-custom
was set to or above the silicon ceiling.		Lower 
max-rate-custom
strictly below 
max-rate-maxn
. If 
max-rate-maxn
is absent from the node, query the live cap on a running target: 
cat /sys/kernel/debug/bpmp/debug/clk/<clock>/max_rate
.
osp-controller
re-appears after 
status = "disabled"
status = "disabled"
does not remove the node from the device tree; BPMP still walks it.		Replace with 
/delete-node/ osp-controller;
— the node must not exist for BPMP to skip the path.
Edits to 
nvpower.sh
lost after 
apt upgrade
nvpower.sh
is owned by the 
nvidia-l4t-init
deb and gets overwritten on upgrade.		For long-lived test setups, package edits into a systemd drop-in or a sibling helper file referenced by 
nvpower.sh
, rather than editing 
nvpower.sh
in place.
/jetson-promote-image
is a no-op after editing the BPMP DTB		The edit was applied to 
<bsp_image.root_path>/Linux_for_Tegra/
, which is 
/jetson-promote-image
's output — not its input.		Move the edit to 
<source.root_path>/Linux_for_Tegra/bootloader/<BPFDTB_FILE>
(the overlay tracker) and commit through the BPMP-DTB protocol.
Cap appears to apply on first boot then resets after a power-mode changeThe active nvpmodel mode's per-clock cap clamps below 
max-rate-custom
.		Inspect both layers; if nvpmodel is binding, raise (or remove) the nvpmodel cap via 
/jetson-customize-nvpmodel
. The BPMP cap alone is not the runtime ceiling.
错误原因解决方案
设置了
max-rate-custom
但T23x GPU仍会升至
max-rate-maxn
仅限制了
nafll_gpusys
；
nafll_gpcX
分区仍以
max-rate-maxn
运行，主导有效上限。		对
nafll_gpusys
以及 通过
grep -nE '^\s*nafll_gpc[0-9]+\s*:' <decompiled.dts>
枚举的所有
nafll_gpcX
节点应用相同的
max-rate-custom
。
已禁用EMC DVFS但T26x的EMC仍会缩放仅设置了
bwmgr.enabled = <0x00>
；
osp-controller
仍存在并通过QoS路径重新下发频率更改。		在同一"编辑DTS"步骤中添加编辑项2（
cactmon.enabled = <0x00>
）和编辑项3（
/delete-node/ osp-controller
）。通过
dtc -I dtb -O dts <bpmp-dtb> | grep -c osp-controller
验证
osp-controller
——预期结果为0。
在T23x上禁用EMC DVFS时提示"node not found" for 
osp-controller
T23x (Orin) BPMP DTB不含
osp-controller
；T23x需跳过编辑项3。		通过
grep -c osp-controller
步骤检测SoC系列；仅当计数≥1时才应用编辑项3。
编辑后BPMP拒绝加载DTB：
max-rate-custom >= max-rate-maxn
max-rate-custom
被设置为等于或高于硅上限。		将
max-rate-custom
严格降低至
max-rate-maxn
以下。若节点中无
max-rate-maxn
，可在运行中设备上查询实时上限：
cat /sys/kernel/debug/bpmp/debug/clk/<clock>/max_rate
。
设置
status = "disabled"
后
osp-controller
仍存在
status = "disabled"
不会从设备树中删除节点；BPMP仍会遍历该节点。		替换为
/delete-node/ osp-controller;
——只有节点不存在时，BPMP才会跳过该路径。
apt upgrade
后
nvpower.sh
的编辑内容丢失
nvpower.sh
属于
nvidia-l4t-init
deb包，升级时会被覆盖。		对于长期测试环境，将编辑内容打包到systemd扩展配置或
nvpower.sh
引用的关联辅助文件中，而非直接编辑
nvpower.sh
。
编辑BPMP DTB后
/jetson-promote-image
无任何操作		编辑内容被应用到
<bsp_image.root_path>/Linux_for_Tegra/
，这是
/jetson-promote-image
的输出——而非输入。		将编辑内容移至
<source.root_path>/Linux_for_Tegra/bootloader/<BPFDTB_FILE>
（覆盖跟踪器）并通过BPMP-DTB协议提交。
首次启动时上限生效，但更改功耗模式后重置激活的nvpmodel模式的时钟上限低于
max-rate-custom
。		检查两个层面；若nvpmodel起限制作用，通过
/jetson-customize-nvpmodel
提高（或移除）nvpmodel上限。仅BPMP上限并非运行时上限。

References

参考资料

  • ../../references/bsp-customization-bpmp-dtb.md
     — canonical BPMP-DTB customization protocol (pristine import, decompile, edit, recompile, sanity-check, commit). Operation 1 of this skill is a content-only consumer; the protocol owns the mechanics.
  • references/clock-control-model.md
     — layer stack, two-ceilings overview, effective-runtime-ceiling formula.
  • references/bpmp-dtb-clock-edits.md
     — two-ceilings semantics, DTS edit form, nvpmodel ↔ BPMP clock-node mapping, inspection cookbook.
  • references/emc-dvfs-disable.md
     — full SoC-conditional EMC DVFS disable procedure with DTS snippets, detection, re-enable.
  • references/nvpower-sh-edits.md
     — 
    nvpower.sh
    function locations + common-edit recipes + package-upgrade caveat.
  • /jetson-customize-nvpmodel
     — sibling skill: nvpmodel power modes. The active mode's per-clock cap clamps below the BPMP DTB cap.
  • ../../references/bsp-customization-bpmp-dtb.md
     —— 标准BPMP-DTB定制协议（原始导入、反编译、编辑、重新编译、完整性检查、提交）。本技能的操作1仅使用该协议的内容部分；协议负责具体流程。
  • references/clock-control-model.md
     —— 层级架构、双层上限概述、运行时有效上限公式。
  • references/bpmp-dtb-clock-edits.md
     —— 双层上限语义、DTS编辑格式、nvpmodel ↔ BPMP时钟节点映射、检查方法。
  • references/emc-dvfs-disable.md
     —— 完整的因SoC而异的EMC DVFS禁用流程，包含DTS代码片段、检测方法、重新启用步骤。
  • references/nvpower-sh-edits.md
     —— 
    nvpower.sh
    函数位置+常见编辑方案+包升级注意事项。
  • /jetson-customize-nvpmodel
     —— 关联技能：nvpmodel功耗模式。激活模式的时钟上限会低于BPMP DTB上限。