Agent Skill · NVIDIA NIM

jetson-customize-clocks

Use to lock/cap Jetson CPU/GPU/EMC clocks, toggle EMC/CPU DVFS, or change cpufreq governors by editing BPMP DTB and nvpower.sh pre-flash. Do NOT use for live tuning or nvpmodel edits.

View SKILL.md on GitHub → Source repository Provider profile
Provider: NVIDIA NIM Path in repo: skills/jetson-customize-clocks/SKILL.md

Skill body

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:

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).

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> 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.

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.

Supported operations

Operation Where the edit lives Procedure section
Lock a CPU / GPU clock to a specific rate BPMP 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 DVFS BPMP DTB: bwmgr.enabled = 1, cactmon.enabled = 1, restore osp-controller on T26x “Content edit: EMC DVFS disable / enable”
Pin everything to MAXN for stress runs Combine the above + nvpmodel MAXN as boot default see Recipe
Lower a clock’s hard ceiling without locking BPMP 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”

Operation 1 — BPMP DTB edits

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.

Resolve the SKU-correct 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.

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.

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

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>.

Content edit: EMC DVFS disable / enable

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:

# Edit Scope
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.

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.

Operation 2 — nvpower.sh edits

Edits nvpower.sh, which runs at boot via nvpower.service to set cpufreq / devfreq governors and rates.

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:

Role Location Skill 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.

Overlay edit recipe (apply before editing 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:

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.

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.

Recipe — pin everything to MAXN for stress / performance runs

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.

Limitations

Troubleshooting

Error Cause Solution
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 T26x Only 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 change The 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.

References

Skill frontmatter

version: 0.0.1 license: Apache-2.0 metadata: {"data-classification" => "public", "author" => "Jetson Team", "tags" => ["clocks", "cpu", "gpu", "emc", "dvfs", "bwmgr", "bpmp", "nvpower", "cpufreq", "devfreq"], "domain" => "clocks"}