/jetson-customize-clocks

name: jetson-customize-clocks
description: 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.
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

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`](../../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>` 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`](../../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`](../../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`](../../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 [`re