| 名称 | jetson-customize-clocks |
| 描述 | 用于通过编辑 BPMP DTB 和 nvpower.sh，在刷写前锁定/限制 Jetson CPU/GPU/EMC 时钟、切换 EMC/CPU DVFS，或更改 cpufreq 调控器。不用于实时调优或 nvpmodel 编辑。 |
| 版本 | 0.0.1 |
| 开源协议 | “Apache-2.0” metadata: data-classification: public |
| 作者 | “Jetson Team” tags: - clocks - cpu - gpu - emc - dvfs - bwmgr - bpmp - nvpower - cpufreq - devfreq domain: clocks |
自定义时钟
目的
在刷写镜像之前，通过编辑 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 的每设备 min / max / 静态频率。
常见触发条件：“锁定 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>（overlay tracker）下。这是 ../../context/bsp-customization-workflow.md#workflow-invariants 中的工作流不变式——手工编辑上游会悄然破坏 diff 跟踪，并使 /jetson-promote-image 变为空操作。
说明
- 解析上述先决条件（活动配置文件、已解压的 BSP image、已初始化的 source overlay tracker）。
- 从下表选择操作。
- 遵循链接的过程部分——操作1（BPMP DTB）、操作2（
nvpower.sh）或适用于两者的 MAXN 配方。 - 按照各操作的提交约定在 overlay tracker 中提交编辑。
- 使用
/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” |
| 限制设备频率范围但不定格 | nvpower.sh 中通过 sysfs 设置最小/最大值 |
“选择编辑” |
操作1 — BPMP DTB 编辑
遵循 ../../references/bsp-customization-bpmp-dtb.md 中的 BPMP-DTB 定制协议。该协议负责机制——首次接触时的 pristine 导入、dtc 反编译、重新编译、健全性检查、提交。本技能仅提供时钟特定内容（在协议的"编辑 DTS"步骤期间要编辑哪些节点和属性）。
编辑后的 .dtb 落在 <source.root_path>/Linux_for_Tegra/ overlay tracker 中。/jetson-promote-image 的通道 A 遍历 tracker 并将文件复制到 bsp_image。不要直接编辑 <bsp_image.root_path>/Linux_for_Tegra/bootloader/<bpmp-dtb>——那是 promote 的输出，不是输入。
解析 SKU 正确的 BPMP DTB
根据协议的"解析活动 BPMP DTB"部分，从活动 flash conf 读取 BPFDTB_FILE。对于常见的 Thor / 单 SKU conf 形状，这是 per-board .conf 中的静态 BPFDTB_FILE=... 行，值直接可信。
对于SKU 复用 conf 形状（Orin AGX devkit conf 链通过 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> 走 dispatch 链，并从 dispatch 输出读取 BPFDTB_FILE——不是 per-board .conf 的静态行。对于非复用 conf，静态值和 dispatch 值一致；仅当 conf 链有条件地覆盖 BPFDTB_FILE 时才必须进行 dispatch。
列出有效最大频率（检查）
在决定 max-rate-custom 值之前，检查运行时上限的两层——参见 references/clock-control-model.md#effective-runtime-ceiling。
检查食谱（BPMP 端反编译 + grep；nvpmodel 端对 boot 默认模式 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”、"在 overlay tracker 中暂存"和"清理"步骤处理其余部分。提交消息约定遵循协议：
<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
它存在于两个根中；操作同时处理两者：
| 角色 | 位置 | 技能是否写入？ |
|---|---|---|
| 检测 + pristine 源 | <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> 副本在下面的 pristine 导入步骤中读取一次，之后不再触碰。
Overlay 编辑配方（在编辑 nvpower.sh 之前应用）
遵循工作流文档中的规范 Off-skill edits recipe，即 pristine 导入 + 自定义提交对，两者均受预览门控。nvpower.sh 是单个文件，没有传播集；一个 pristine 提交 + 一个自定义提交即可覆盖整个更改。
本技能的具体替换：
<rel>/<file>是rootfs/etc/systemd/nvpower.sh。- 建议的 pristine 导入消息：
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。
部署
overlay tracker 中的自定义提交不会自行到达设备。部署链：
/jetson-promote-image— 将 overlay 中每个被跟踪的文件复制到<bsp_image.root_path>/Linux_for_Tegra/。差异感知（跳过字节相同）；对rootfs/*目标使用sudo cp -p。/jetson-flash-image— 将更新后的bsp_image刷写到设备。nvpower.service将在下次启动时运行新脚本。- （替代，无需刷写）将
<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 两次往返协议）：
- BPMP DTB（"内容编辑：在命名时钟节点上的
max-rate-custom"步骤的内容）：保持每个 CPU / GPU / EMC 时钟上的max-rate-custom不设置；移除现有降低上限的max-rate-custom行。 - BPMP DTB（"内容编辑：禁用 / 启用 EMC DVFS"步骤的内容）：将 EMC 固定在其初始频率 —
bwmgr.enabled = 0、cactmon.enabled = 0，外加 T26x 上的/delete-node/ osp-controller（T23x 上跳过）。 - 在一次协议"编辑 DTS"调用中应用两个内容编辑，然后运行剩余的协议步骤（重新编译、健全性检查、覆盖两个内容编辑的单个自定义提交）。
- nvpower.sh（操作2）：无条件设置
desired_cpufreq_gov="performance"和desired_devfreq_gov="performance"；移除set_devfreq_governor中的 GPU/nvjpg 跳过。通过操作2的 overlay 编辑配方应用（"Overlay 编辑配方（在编辑 nvpower.sh 之前应用）"步骤）——这是 rootfs 脚本上的一个单独的 overlay-tracker pristine + 自定义提交对，与 BPMP-DTB 协议的提交分开。 - 通过
/jetson-customize-nvpmodel将 boot 默认 nvpmodel 模式设置为 MAXN——无论 BPMP DTB 内容如何，每个时钟的 nvpmodel 上限都会限制在max-rate-maxn以下。
部署 /jetson-promote-image → /jetson-flash-image 在下次刷写时通过 overlay tracker 获取新的 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 token 覆盖某个属性时，token 在刷写时覆盖直接 BPMP DTS 编辑。直接 BPMP DTS 编辑是没有 NVIDIA token 覆盖的属性的后备方案。
max-rate-maxn和lateinit不可触碰。max-rate-maxn是硅片上限（只读）。lateinit用于启动时时钟初始化，不是上限覆盖——不要修改它们。- BPMP DTB 可能为 SKU 复用。 在复合/派发 flash conf（Orin AGX devkit 链）上，
BPFDTB_FILE由board_sku/board_FAB通过update_flash_args_common选择。当链有条件地覆盖BPFDTB_FILE时，读取静态BPFDTB_FILE=行是错误的；请通过派发解析。
故障排除
| 错误 | 原因 | 解决方案 |
|---|---|---|
设置了 max-rate-custom，但 T23x GPU 上的时钟仍升至 max-rate-maxn |
仅对 nafll_gpusys 设了上限；nafll_gpcX 分区仍以 max-rate-maxn 运行，并主导有效上限。 |
将相同的 max-rate-custom 应用于 nafll_gpusys 以及 grep -nE '^\\s*nafll_gpc[0-9]+\\s*:' <decompiled.dts> 枚举的每个 nafll_gpcX 节点。 |
| EMC DVFS 禁用看似生效，但 EMC 在 T26x 上仍进行缩放 | 仅设置了 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>（overlay tracker），并通过 BPMP-DTB 协议提交。 |
| 上限在首次启动时生效，但电源模式更改后重置 | 活动 nvpmodel 模式的每时钟上限将频率限制在 max-rate-custom 以下。 |
检查两层；如果 nvpmodel 正在绑定，请通过 /jetson-customize-nvpmodel 提高（或移除）nvpmodel 上限。单独的 BPMP 上限不是运行时上限。 |
引用
../../references/bsp-customization-bpmp-dtb.md— 典型 BPMP-DTB 定制协议（pristine 导入、反编译、编辑、重新编译、健全性检查、提交）。本技能的操作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 上限之下。