jetson-customize-clocks

自定义时钟

用途

在刷写镜像之前，编辑 Linux_for_Tegra/ 下的文件，以自定义 Jetson 目标设备上的 CPU、GPU 和 EMC 时钟行为。涉及两个层面：

• Linux_for_Tegra/bootloader/<BPFDTB_FILE> 中的 BPMP DTB — 各时钟的 max-rate-custom 上限，以及 EMC DVFS 门控（所有 SoC 上的 bwmgr + cactmon；仅 T26x 上的 osp-controller）。
• Linux_for_Tegra/rootfs/etc/systemd/nvpower.sh 中的 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 为只读）。

前置条件

根据 ../../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 成为空操作。

说明

1. 确认满足上述前置条件（活动配置文件、已提取 BSP 镜像、已初始化源覆盖层跟踪仓库）。
2. 从下表中选择操作。
3. 按照链接的流程章节执行 — 操作 1（BPMP DTB）、操作 2（nvpower.sh），或同时执行两者的 MAXN 方案。
4. 按照各操作的提交约定，在覆盖层跟踪仓库中提交修改。
5. 使用 /jetson-promote-image → /jetson-flash-image 进行部署。新的 BPMP DTB 和 nvpower.sh 将在下次启动时生效。

支持的操作

操作	修改位置	流程章节
将 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 DVFS	BPMP 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 中设置最小值 / 最大值	“选择修改项”

操作 1 — BPMP DTB 编辑

遵循 BPMP-DTB 自定义协议，详见 ../../references/bsp-customization-bpmp-dtb.md。 该协议负责具体操作——首次触及时导入原始文件、 反编译 dtc、重新编译、健全性检查、提交。本技能 仅提供时钟相关内容（在协议的“编辑 DTS”步骤中 要编辑哪些节点和属性）。

编辑后的 .dtb 将放入 <source.root_path>/Linux_for_Tegra/ 覆盖层跟踪目录。/jetson-promote-image 的 channel A 会遍历 该跟踪目录，并将文件复制到 bsp_image。不要直接编辑 <bsp_image.root_path>/Linux_for_Tegra/bootloader/<bpmp-dtb>—— 它是 promote 的输出，而不是输入。

确定与 SKU 匹配的 BPMP DTB

根据协议的“解析活动 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 时，才必须进行分派。

列出有效的最大速率（检查）

在确定 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”步骤中确定编辑值的前提。

内容编辑：对指定时钟节点设置 max-rate-custom

在协议的“编辑 DTS”步骤中，修改指定时钟节点内的属性——绝不要修改 lateinit。max-rate-custom 必须严格低于时钟的硬上限（如果定义了 max-rate-maxn，则采用该值；否则采用同一芯片 / SKU 的运行中目标设备 上实时读取的 max_rate）。

DTS 编辑格式、语义以及 nvpmodel ↔ BPMP 时钟节点映射见 references/bpmp-dtb-clock-edits.md。

然后将控制权交还给协议——其“重新编译”“检查重新编译后的 Blob 是否 健全”“暂存到覆盖层跟踪目录”和“清理”步骤会处理其余工作。 按照协议的提交消息约定： <BPMP_BASENAME>: jetson-customize-clocks — <clock-node> max-rate-custom = <value>。

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

默认行为（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 — 结果为零 ⇒ 采用 T23x 路径。完整 DTS 片段、保留节点导致的失败模式以及重新启用流程，见 references/emc-dvfs-disable.md。

完成多节点编辑后，按协议执行“重新编译”至“清理”步骤。提交信息约定： <BPMP_BASENAME>: jetson-customize-clocks — EMC DVFS disable (bwmgr + cactmon[+ osp-controller])。

禁用后会增加空闲功耗；此设置适用于压力 / 性能测试，不适用于生产 rootfs。

重新运行 + 幂等性

根据协议的“可重新运行”一节，使用相同目标值重新运行此 技能会产生一个空提交。使用不同值重新运行会重写同一属性 — git log -- $BPMP_REL 可显示每次运行的历史记录。要将时钟恢复到其 max-rate-maxn 上限，请编辑 DTS，移除 max-rate-custom 行，然后重新编译。

操作 2 — 编辑 nvpower.sh

编辑 nvpower.sh，该脚本会在启动时通过 nvpower.service 运行，以设置 cpufreq / devfreq 调速器和频率。

每脚本文件

此操作编辑的脚本相对路径为：

Linux_for_Tegra/rootfs/etc/systemd/nvpower.sh

该文件位于两个根目录下；此操作会遍历这两个目录：

角色	位置	技能会写入吗？
检测 + 原始源文件	<bsp_image.root_path>/Linux_for_Tegra/rootfs/etc/systemd/	否 — 只读
Overlay 编辑目标 + git 提交	<source.root_path>/Linux_for_Tegra/rootfs/etc/systemd/	是

后续子步骤中提到的每脚本文件，指 <source.root_path> 下的 Overlay 副本。下面的原始导入步骤会读取一次 <bsp_image.root_path> 副本，此后不再触碰。

Overlay 编辑流程（编辑 nvpower.sh 前应用）

按照工作流文档中的规范 技能外编辑流程 — 原始文件导入 + 定制提交配对，并且两者 都受预览关卡约束。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"。

选择编辑内容

函数位置（set_cpufreq_governor、set_devfreq_governor）、常见编辑流程（固定为 Fmax、静态频率、最小 / 最大范围）以及 nvidia-l4t-init 软件包升级注意事项，见 references/nvpower-sh-edits.md。

部署

覆盖层跟踪器中的自定义提交不会自动到达设备。部署流程：

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 重新解压时会被静默丢弃。

操作方案 — 压力测试／性能测试时将所有设置固定为 MAXN

结合操作 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 前应用的覆盖层编辑方案”步骤）——在 rootfs 脚本上单独进行一对覆盖层跟踪器原始提交与自定义提交，与 BPMP-DTB 协议的提交相互独立。
5. 通过 /jetson-customize-nvpmodel 将 nvpmodel 的默认启动模式设为 MAXN——无论 BPMP DTB 内容如何，nvpmodel 的每时钟上限都会将频率限制在 max-rate-maxn 以下。

部署 /jetson-promote-image → /jetson-flash-image，下次刷写时即可通过覆盖层跟踪器应用新的 BPMP DTB 和编辑后的 nvpower.sh。

局限性

• 仅限镜像构建时。 所有编辑都位于 <source.root_path>/Linux_for_Tegra/ 下，且只有通过 /jetson-promote-image → /jetson-flash-image 才会应用到设备。实时目标设备调优不在范围内。
• max-rate-custom 只能降低上限。 它必须严格低于 max-rate-maxn；不支持提高芯片上限。
• 有效上限分为两层。 运行时上限为 min(BPMP cap, active-nvpmodel-mode cap)。nvpmodel 上限由 /jetson-customize-nvpmodel 管理；此技能不会编辑它。
• SoC 条件式 EMC DVFS 门控。 禁用 EMC DVFS 时，T23x（bwmgr + cactmon）与 T26x（bwmgr + cactmon + 删除 osp-controller）需要编辑不同的节点集合。检测错误会导致未定义行为。
• T23x GPU 上限涉及多个节点。 GPU 时钟分布在 nafll_gpusys 和每个 nafll_gpcX 中；只有对所有这些节点应用上限后才会生效。
• nvpower.sh 由软件包管理。 它包含在 nvidia-l4t-init 中；软件包升级会覆盖原地编辑。对于长期使用的设置，建议优先采用 systemd drop-in 或同级辅助脚本。
• ODMDATA 优先。 当某个 ODMDATA 令牌涵盖某项属性时，该令牌会在刷写时覆盖直接的 BPMP DTS 编辑。直接编辑 BPMP DTS 是 NVIDIA 令牌无法覆盖属性时的后备方案。
• 禁止修改 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= 行是错误的；应通过分派逻辑解析。

故障排除

错误	原因	解决方案
在 T23x GPU 上设置了 max-rate-custom，但时钟仍升至 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。
在 T26x 上禁用 EMC DVFS 看似生效，但 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 时，因 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 drop-in 或由 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/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 上限。