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