Hogar
jetson-customize-clocks
NVIDIA/skills
Bloquea, limita o personaliza el comportamiento de los relojes de la CPU, la GPU y el EMC en los dispositivos NVIDIA Jetson editando el archivo DTB de BPMP y el script nvpower.sh antes de realizar el flasheo.
...Expandir todoPersonalizar relojes
Objetivo
Personalizar el comportamiento de los relojes de la CPU, la GPU y el EMC en un dispositivo Jetson editando los archivos de la carpeta Linux_for_Tegra/ antes de flashear la imagen. Se incluyen dos capas:
- El DTB de BPMP en
Linux_for_Tegra/bootloader/— losmax-rate-custom, además de la puerta DVFS de EMC (bwmgr + cactmon en todos los SoC; osp-controller solo en T26x). - nvpower.sh en
Linux_for_Tegra/rootfs/etc/systemd/nvpower.sh— reguladores cpufreq / devfreq y (opcionalmente) velocidades mínimas, máximas y estáticas por dispositivo escritas en sysfs al arrancar.
Desencadenantes comunes: «bloquear la frecuencia de la CPU/GPU/EMC», «fijar la GPU a Fmax», «fijar el EMC a MAXN», «desactivar/activar el DVFS del EMC», «desactivar/activar el DVFS de la CPU», «establecer la frecuencia máxima de la CPU/GPU», «cambiar el regulador cpufreq».
Fuera del alcance: ajuste del reloj en tiempo de ejecución en un dispositivo en funcionamiento (sin paso por flash), modificaciones del modo de energía en nvpmodel (utiliza la habilidad hermana /jetson-customize-nvpmodel) y las modificaciones del límite máximo del silicio (max-rate-maxn es de solo lectura).
Requisitos previos
Resolver el perfil activo según
../../context/target-platform-contract.md.
Rechazar y redirigir en estos casos:
| Condición | Rechazar con |
|---|---|
No hay perfil activo, o active: NA |
Derivar a /jetson-set-target o /jetson-init-target. |
El perfil carece de bsp_image: bloque |
Ruta a /jetson-init-image. |
|
Ruta a /jetson-init-image. |
|
Ruta a /jetson-init-source. |
Resolver rutas:
bsp_image.root_path:si existe, si no/Image source.root_path:si existe, si no/Source
nvpower.sh) se almacena en
../../context/bsp-customization-workflow.md#workflow-invariants —
la edición manual en las etapas anteriores destruye silenciosamente el historial de diferencias y convierte
/jetson-promote-image una operación nula.
Instrucciones
- Cumple los requisitos previos anteriores (perfil activo, imagen BSP extraída, rastreador de superposición de código fuente inicializado).
- Selecciona la operación de la tabla siguiente.
- Sigue la sección del procedimiento enlazada: Operación 1 (BPMP DTB), Operación 2 (
nvpower.sh) o la receta MAXN para ambas. - Confirma los cambios en el gestor de superposiciones según la convención de confirmación de cada operación.
- Implemente con
/jetson-promote-image→/jetson-flash-image. El nuevo DTB de BPMP ynvpower.shentrarán en vigor en el siguiente arranque.
Operaciones compatibles
| Operación | Dónde se encuentra la edición | Sección de procedimientos |
|---|---|---|
| Bloquear la frecuencia de un reloj de CPU/GPU a un valor específico | BPMP DTB max-rate-custom en el nodo de reloj + nvpower.sh regulador performance |
«Edición de contenido: max-rate-custom» + «Seleccionar la edición» |
| Bloquear el EMC a su frecuencia inicial (desactivar el DVFS del EMC) | DTB de BPMP: bwmgr.enabled = 0, cactmon.enabled = 0, además /delete-node/ osp-controller solo en T26x |
«Edición de contenido: desactivar/activar EMC DVFS» |
| Volver a activar EMC DVFS | BPMP DTB: bwmgr.enabled = 1, cactmon.enabled = 1, restaurar osp-controller en T26x |
«Edición de contenido: desactivación/activación de EMC DVFS» |
| Fijar todo en MAXN para pruebas de estrés | Combinar lo anterior con nvpmodel MAXN como valor predeterminado de arranque | Ver receta |
| Reducir el límite máximo fijo de una frecuencia de reloj sin bloquear | DTB de BPMP max-rate-custom únicamente |
«Edición de contenido: max-rate-custom" |
| Limitar la tasa de un dispositivo sin fijar | nvpower.sh mín./máx. a través de sysfs |
«Seleccionar la modificación» |
Operación 1 — Modificaciones en el DTB de BPMP
Sigue el protocolo de personalización de BPMP-DTB que se describe en
../../references/bsp-customization-bpmp-dtb.md.
El protocolo se encarga de los aspectos técnicos: importación sin modificaciones en la primera intervención,
dtc descompilación, recompilación, comprobación de integridad y confirmación. Esta habilidad
solo proporciona el contenido específico del reloj (qué nodos y
propiedades editar durante el paso «Editar el DTS» del protocolo).
Los .dtb se almacena en el /jetson-promote-imageEl canal A recorre el
rastreador y copia el archivo en bsp_image.
No edites directamente «
Resolver la DTB BPMP con el SKU correcto
Según la sección «Resolución del DTB BPMP activo» del protocolo, lee
BPFDTB_FILE la configuración de la memoria flash activa. Para las configuraciones habituales de Thor /
SKU único, se trata de la línea estática BPFDTB_FILE=... línea
de cada placa .conf y el valor es definitivo tal y como está.
Para configuraciones con multiplexación de SKU (cadena de configuración del kit de desarrollo Orin AGX
que selecciona un DTB de BPMP diferente por board_sku/board_FAB
vía update_flash_args_common — véase
../../context/bsp-customization-software-layers.md#per-board-conf-dispatch--update_flash_args_common),
recorre la cadena de despacho con board_sku= y
board_FAB= desde el perfil activo,
y lee BPFDTB_FILE de la salida de despacho —no de
la línea estática de la configuración por placa .conf. Los valores estáticos y los despachados
coinciden para configuraciones no multiplexadas; el despacho es
obligatorio únicamente cuando la cadena de configuración anula condicionalmente
BPFDTB_FILE.
Enumerar las tasas máximas efectivas (inspección)
Inspecciona ambas capas del límite máximo en tiempo de ejecución — véase references/clock-control-model.md#effective-runtime-ceiling — antes de decidir un max-rate-custom valor.
El manual de inspección (descompilación del lado de BPMP + grep; awk del lado de nvpmodel sobre el modo predeterminado de arranque) se encuentra en references/bpmp-dtb-clock-edits.md#inspection-cookbook.
Para la capa nvpmodel, véase /jetson-customize-nvpmodel.
Este paso no modifica el estado; es una condición previa para dimensionar
la edición en el paso «Edición de contenido: max-rate-custom en un nodo de reloj con nombre».
Edición de contenido: max-rate-custom en un nodo de reloj con nombre
Durante el paso «Editar el DTS» del protocolo, modifica la propiedad
dentro del nodo de reloj con nombre; nunca lateinit. max-rate-custom
debe estar estrictamente por debajo del límite máximo del reloj (max-rate-maxn si
está definido; de lo contrario, el max_rate de un destino en ejecución del
mismo chip / SKU).
El formulario de edición del DTS, la semántica y la correspondencia entre nvpmodel y el nodo de reloj BPMP
se encuentran en references/bpmp-dtb-clock-edits.md.
A continuación, devuelve el control al protocolo: sus pasos «Recompilar», «Comprobación de validez
del blob recompilado», «Incorporar al rastreador de superposición» y «Limpieza»
se encargan del resto.
Convención de mensajes de confirmación según el protocolo:
Edición de contenido: desactivación/activación de EMC DVFS
El comportamiento predeterminado (EMC DVFS activado) no requiere ninguna edición. Desactivar EMC
DVFS es una edición multinodo que se aplica dentro del mismo paso «Editar el DTS» del
protocolo, no un bwmgr cambio de estado:
| # | Edición | Ámbito |
|---|---|---|
| 1 | bwmgr.enabled = <0x00> |
Todos los SoC, obligatorio |
| 2 | cactmon.enabled = <0x00> |
Todos los SoC, obligatorio |
| 3 | /delete-node/ osp-controller |
T26x (Thor) obligatorio — T23x (Orin) no tiene ese nodo, omitir |
Detección: dtc -I dtb -O dts
— cero coincidencias ⇒ ruta T23x. Los fragmentos completos de DTS, los modos de fallo de las rutas supervivientes
y el procedimiento de reactivación se encuentran en
references/emc-dvfs-disable.md.
Aplica los pasos del protocolo desde «Recompilar» hasta «Limpieza» una vez que la edición multinodo esté
implementada. Convención del mensaje de confirmación:
La desactivación aumenta el consumo en reposo; está pensada para pruebas de estrés o de rendimiento, no para el sistema de archivos raíz de producción.
Reejecución + idempotencia
Según la sección «Reejecutabilidad» del protocolo, volver a ejecutar esta
habilidad con el mismo valor objetivo produce una confirmación sin efecto. Volver a
ejecutarla con un valor diferente reescribe la misma propiedad — git log -- $BPMP_REL lo que muestra el historial por ejecución. Para devolver un reloj
a su max-rate-maxn límite máximo, edita el DTS para eliminar la
max-rate-custom línea y recompilar.
Operación 2 — Modificaciones en nvpower.sh
Edita nvpower.sh, que se ejecuta al arrancar mediante nvpower.service para configurar
los reguladores y las frecuencias de cpufreq y devfreq.
El archivo del script
El script que edita esta Operación tiene la ruta relativa:
Linux_for_Tegra/rootfs/etc/systemd/nvpower.sh
Se encuentra en dos directorios raíz; la operación recorre ambos:
| Función | Ubicación | ¿Escribe Skill? |
|---|---|---|
| Detección + fuente original | |
no — solo lectura |
| Superponer objetivo de edición + confirmación de Git | |
sí |
Los pasos secundarios siguientes se refieren al archivo por script para indicar la superposición
copiada en
Receta de edición de superposición (aplicar antes de editar nvpower.sh)
Sigue la receta canónica
de ediciones «Off-skill»
del documento del flujo de trabajo: un par formado por una importación «pristine» y una confirmación de personalización, ambas
sujetas a la puerta de vista previa. nvpower.sh Es un único archivo sin
conjunto de propagación; una confirmación «pristine» + una confirmación de personalización cubren
todo el cambio.
Sustituciones concretas para esta skill:
/ rootfs/etc/systemd/nvpower.sh.- Mensaje sugerido para la importación sin modificaciones:
import pristine: rootfs/etc/systemd/nvpower.sh, cuerpoSource:./Linux_for_Tegra/ (BSP ) - Encabezado sugerido para la confirmación de personalización:
jetson-customize-clocks: nvpower.sh, líneas del cuerpo comoset_cpufreq_governor: desired_cpufreq_gov "schedutil" -> "performance".
Elige las ubicaciones de las
(set_cpufreq_governor, set_devfreq_governor), recetas de edición comunes (fijar a Fmáx, tasa estática, límites mín./máx.) y la nvidia-l4t-init advertencia sobre la actualización del paquete se encuentran en references/nvpower-sh-edits.md.
Deploy
La confirmación de personalización en el gestor de superposiciones no llega al dispositivo por sí sola. La cadena de implementación:
/jetson-promote-image— copia todos los archivos rastreados de la superposición en/Linux_for_Tegra/ sudo cp -ppararootfs/*los destinos./jetson-flash-image— flashea labsp_imageen el dispositivo.nvpower.serviceejecuta el nuevo script en el siguiente arranque.- (Alternativa, sin flasheo) Copiar
/Linux_for_Tegra/rootfs/etc/systemd/nvpower.sh /etc/systemd/nvpower.sh, y luegosudo systemctl restart nvpower.service(o reinicia).
Editar /jetson-promote-image
y se pierde sin aviso en la siguiente /jetson-init-image reextracción.
Receta: fija todo en MAXN para pruebas de estrés y rendimiento
Combina las operaciones 1 y 2. El BPMP de la operación 1 edita todo el flujo
a lo largo de una ronda del protocolo (un único ciclo de descompilación / edición multinodo
/ recompilación / confirmación; no se debe recorrer el protocolo
dos veces para el mismo .dtb):
- DTB de BPMP (el contenido del paso «Edición de contenido:
max-rate-customen un nodo de reloj con nombre»): dejamax-rate-customsin configurar en todos los relojes de CPU, GPU y EMC; elimina lasmax-rate-customlíneas existentes que reduzcan el límite máximo. - DTB del BPMP (contenido del paso «Edición de contenido: desactivación/activación de DVFS de EMC»): fija el EMC a su frecuencia de inicialización —
bwmgr.enabled = 0,cactmon.enabled = 0, más/delete-node/ osp-controlleren T26x (omitir en T23x). - Aplica ambas modificaciones de contenido dentro de una única invocación del protocolo «Editar el DTS» y, a continuación, ejecuta los pasos restantes del protocolo (recompilar, comprobación de validez, una única confirmación de personalización que abarque ambas modificaciones de contenido).
- nvpower.sh (Operación 2): establecer
desired_cpufreq_gov="performance"ydesired_devfreq_gov="performance"incondicionalmente; elimina el salto de GPU/nvjpg enset_devfreq_governor. Se aplica mediante la receta de edición de superposición de la Operación 2 (el paso «Receta de edición de superposición (aplicar antes de editar nvpower.sh)»): un par independiente de confirmaciones «pristine» + «personalización» del rastreador de superposición en el script del rootfs, distinto de la confirmación del protocolo BPMP-DTB. - Establece el modo nvpmodel predeterminado de arranque en MAXN mediante
/jetson-customize-nvpmodel— los límites máximos de nvpmodel por ciclo de reloj se fijan por debajo demax-rate-maxnindependientemente del contenido del DTB de BPMP.
Implementa /jetson-promote-image → /jetson-flash-image recoge el nuevo DTB de BPMP (a través del rastreador de superposiciones) y el nvpower.sh (a través del mismo rastreador de superposición) en la siguiente actualización de flash.
Limitaciones
- Solo en el momento de la compilación de la imagen. Todas las modificaciones se aplican
/Linux_for_Tegra/ /jetson-promote-image→/jetson-flash-image. El ajuste en tiempo real del objetivo queda fuera del alcance. max-rate-customsolo reduce el límite máximo. Debe estar estrictamente por debajo demax-rate-maxn; no se admite aumentar el límite máximo del silicio.- El límite máximo efectivo es de dos capas. El límite máximo en tiempo de ejecución es
min(BPMP cap, active-nvpmodel-mode cap). El límite de nvpmodel es propiedad de/jetson-customize-nvpmodel; esta habilidad no lo modifica. - Puerta EMC DVFS condicional al SoC. Para desactivar EMC DVFS es necesario modificar diferentes conjuntos de nodos en T23x (bwmgr + cactmon) frente a T26x (bwmgr + cactmon + eliminar
osp-controller). Una detección errónea provoca un comportamiento indefinido. - El límite de la GPU en T23x es multinodo. La frecuencia de la GPU se distribuye entre
nafll_gpusysy cadanafll_gpcX; el límite solo se aplica cuando se aplica a todos ellos. nvpower.shSe gestiona mediante paquetes. Se incluye ennvidia-l4t-init; las actualizaciones del paquete sobrescriben las modificaciones in situ. Las configuraciones de larga duración deberían dar preferencia a una solución compatible con systemd o a un programa auxiliar equivalente.- ODMDATA tiene prioridad. Cuando un token ODMDATA cubre una propiedad, dicho token anula las modificaciones directas del DTS de BPMP en el momento de la grabación en la memoria flash. Las modificaciones directas del DTS de BPMP son la alternativa para aquellas propiedades a las que no llega ningún token de NVIDIA.
max-rate-maxnylateinitestán fuera de los límites.max-rate-maxnes el límite máximo del chip (solo lectura).lateinites para la inicialización del reloj en el arranque, no para anular el límite máximo; no toques nunca ninguno de los dos.- El DTB de BPMP puede estar multiplexado por SKU. En configuraciones de flash compuestas o distribuidas (cadena del kit de desarrollo Orin AGX),
BPFDTB_FILEse selecciona medianteboard_sku/board_FABa través deupdate_flash_args_common. La lectura de la línea estáticaBPFDTB_FILE=es errónea cuando la cadena la anula de forma condicional; resuélvelo mediante el despacho en su lugar.
Solución de problemas
| Error | Causa | Solución |
|---|---|---|
max-rate-custom configurado, pero el reloj sigue acelerando hasta max-rate-maxn activado en la GPU T23x |
Solo nafll_gpusys se limitó; las nafll_gpcX particiones siguen funcionando a max-rate-maxn y dominan el límite máximo efectivo. |
Aplica lo mismo max-rate-custom a nafll_gpusys y a cada nafll_gpcX nodo enumerado por grep -nE '^\s*nafll_gpc[0-9]+\s*:' . |
| La desactivación de EMC DVFS parece aplicarse, pero EMC sigue escalando en T26x | Solo bwmgr.enabled = <0x00> se ha configurado; osp-controller se mantiene y vuelve a emitir los cambios de frecuencia a través de la ruta de QoS. |
Añadir modificaciones n.º 2 (cactmon.enabled = <0x00>) y n.º 3 (/delete-node/ osp-controller) dentro del mismo paso «Editar el DTS». Verifica osp-controller a través de dtc -I dtb -O dts → se espera 0. |
La desactivación de EMC DVFS se rechaza en el T23x con el mensaje «nodo no encontrado» para osp-controller |
T23x (Orin) Las DTB de BPMP no contienen osp-controller; hay que omitir la edición n.º 3 en T23x. |
Detectar la familia de SoC con el grep -c osp-controller paso; aplicar el n.º 3 solo cuando el recuento sea ≥1. |
BPMP se niega a cargar el DTB tras la edición: max-rate-custom >= max-rate-maxn |
max-rate-custom se ha establecido en un valor igual o superior al límite máximo del silicio. |
Reducir max-rate-custom estrictamente por debajo max-rate-maxn. Si max-rate-maxn no está presente en el nodo, consulta el límite en tiempo real en un objetivo en ejecución: cat /sys/kernel/debug/bpmp/debug/clk/. |
osp-controller vuelve a aparecer después de status = "disabled" |
status = "disabled" no elimina el nodo del árbol de dispositivos; BPMP sigue recorriéndolo. |
Sustituye por /delete-node/ osp-controller; — el nodo no debe existir para que BPMP omita la ruta. |
Las modificaciones en nvpower.sh «se ha perdido después de» apt upgrade |
nvpower.sh pertenece al nvidia-l4t-init deb y se sobrescriben al actualizar. |
Para configuraciones de prueba de larga duración, incorpora las modificaciones en un archivo «drop-in» de systemd o en un archivo auxiliar homólogo al que haga referencia nvpower.sh, en lugar de editar nvpower.sh directamente en el archivo original. |
/jetson-promote-image no tiene ningún efecto tras editar el DTB de BPMP |
La modificación se aplicó a /jetson-promote-imagela salida de — no su entrada. |
Mueve la modificación a |
| El límite parece aplicarse en el primer arranque y luego se restablece tras un cambio de modo de energía | El límite por ciclo del modo nvpmodel activo se fija por debajo de max-rate-custom. |
Inspecciona ambas capas; si nvpmodel está limitando, aumenta (o elimina) el límite de nvpmodel mediante /jetson-customize-nvpmodel. El límite de BPMP por sí solo no constituye el techo de tiempo de ejecución. |
Referencias
../../references/bsp-customization-bpmp-dtb.md— Protocolo canónico de personalización de BPMP-DTB (importación original, descompilación, edición, recompilación, comprobación de validez, confirmación). La operación 1 de esta habilidad se limita al contenido; el protocolo se encarga de la mecánica.references/clock-control-model.md— Pila de capas, visión general de los dos límites máximos, fórmula del límite máximo efectivo de tiempo de ejecución.references/bpmp-dtb-clock-edits.md— Semántica de los dos límites máximos, formulario de edición de DTS, mapeo nvpmodel ↔ BPMP de nodos de reloj, guía de inspección.references/emc-dvfs-disable.md— Procedimiento completo de desactivación de EMC DVFS condicional al SoC con fragmentos de DTS, detección y reactivación.references/nvpower-sh-edits.md—nvpower.shubicaciones de funciones + recetas de edición comunes + advertencia sobre la actualización de paquetes./jetson-customize-nvpmodel— Habilidad relacionada: modos de potencia de nvpmodel. El límite por ciclo del modo activo se mantiene por debajo del límite del DTB de BPMP.
---
name: jetson-customize-clocks
description: Lock, cap, or customize CPU, GPU, and EMC clock behavior on NVIDIA Jetson devices by editing BPMP DTB and nvpower.sh before flashing.
license: Apache-2.0
---
# 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 [`references/clock-control-model.md#effective-runtime-ceiling`](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`](references/bpmp-dtb-clock-edits.md#inspection-cookbook).
For the nvpmodel layer see [`/jetson-customize-nvpmodel`](../jetson-customize-nvpmodel/SKILL.md).
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`](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`](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](../../context/bsp-customization-workflow.md#off-skill-edits)
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`](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`](../jetson-customize-nvpmodel/SKILL.md) — the per-clock nvpmodel cap clamps below `max-rate-maxn` regardless of BPMP DTB content.
Deploy [`/jetson-promote-image`](../jetson-promote-image/SKILL.md) → [`/jetson-flash-image`](../jetson-flash-image/SKILL.md) 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
| 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
- [`../../references/bsp-customization-bpmp-dtb.md`](../../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`](references/clock-control-model.md) — layer stack, two-ceilings overview, effective-runtime-ceiling formula.
- [`references/bpmp-dtb-clock-edits.md`](references/bpmp-dtb-clock-edits.md) — two-ceilings semantics, DTS edit form, nvpmodel ↔ BPMP clock-node mapping, inspection cookbook.
- [`references/emc-dvfs-disable.md`](references/emc-dvfs-disable.md) — full SoC-conditional EMC DVFS disable procedure with DTS snippets, detection, re-enable.
- [`references/nvpower-sh-edits.md`](references/nvpower-sh-edits.md) — `nvpower.sh` function locations + common-edit recipes + package-upgrade caveat.
- [`/jetson-customize-nvpmodel`](../jetson-customize-nvpmodel/SKILL.md) — sibling skill: nvpmodel power modes. The active mode's per-clock cap clamps below the BPMP DTB cap.
Todos los archivos
9 archivosInstalar jetson-customize-clocks
Descarga y descomprime los archivos de habilidades en tu directorio .claude/skills/.
Descargar ZIPClona el repositorio y copia los archivos de la habilidad a tu proyecto.
git clone https://github.com/NVIDIA/skills/tree/main/skills/jetson-customize-clocks # Copy SKILL.md to your .claude/skills/ directory
Copiar
