jetson-customize-clocks

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

Prerequisites

Resolve the active profile per `../../context/target-platform-contract.md`. Refuse and route in these cases:

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.

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

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:

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:

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

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.

1. `/jetson-flash-image` — flashes the updated bsp_image to the

device. nvpower.service runs the new script on the next boot.

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

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

Troubleshooting

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.