Lar
jetson-customize-clocks
NVIDIA/skills
Bloqueie, limite ou personalize o comportamento dos relógios da CPU, da GPU e do EMC em dispositivos NVIDIA Jetson editando o BPMP DTB e o nvpower.sh antes da gravação do firmware.
...Expandir tudoPersonalizar relógios
Objetivo
Personalizar o comportamento dos relógios da CPU, GPU e EMC em um alvo Jetson, editando os arquivos na pasta Linux_for_Tegra/ antes de gravar a imagem. Duas camadas estão em questão:
- O DTB do BPMP em
Linux_for_Tegra/bootloader/— limites máximos por relógiomax-rate-custom, além do gate DVFS do EMC (bwmgr + cactmon em todos os SoCs; osp-controller apenas no T26x). - nvpower.sh em
Linux_for_Tegra/rootfs/etc/systemd/nvpower.sh— reguladores cpufreq / devfreq e (opcionalmente) taxas mínimas / máximas / estáticas por dispositivo gravadas no sysfs na inicialização.
Gatilhos comuns: “bloquear frequência da CPU/GPU/EMC”, “fixar GPU em Fmax”, “fixar EMC em MAXN”, “desativar/ativar DVFS do EMC”, “desativar/ativar DVFS da CPU”, “definir taxa máxima da CPU/GPU”, “alterar regulador cpufreq”.
Fora do escopo: ajuste de clock em tempo de execução em um alvo ativo (sem etapa de flash), edições do modo de energia no nvpmodel (use a habilidade irmã /jetson-customize-nvpmodel) e substituições do limite máximo do silício (max-rate-maxn é somente leitura).
Pré-requisitos
Resolva o perfil ativo de acordo com
../../context/target-platform-contract.md.
Recuse e redirecione nos seguintes casos:
| Condição | Recusar com |
|---|---|
Sem perfil ativo, ou active: NA |
Encaminhar para /jetson-set-target ou /jetson-init-target. |
O perfil não possui bsp_image: bloqueio |
Rota para /jetson-init-image. |
|
Rota para /jetson-init-image. |
|
Rota para /jetson-init-source. |
Resolver caminhos:
bsp_image.root_path:se estiver presente, caso contrário/Image source.root_path:se houver, caso contrário/Source
nvpower.sh) vai para
../../context/bsp-customization-workflow.md#workflow-invariants —
a edição manual a montante destrói silenciosamente o rastro de diferenças e transforma
/jetson-promote-image uma operação nula.
Instruções
- Resolva os pré-requisitos acima (perfil ativo, imagem BSP extraída, rastreador de sobreposição de código-fonte inicializado).
- Escolha a operação na tabela abaixo.
- Siga a seção de procedimento vinculada — Operação 1 (BPMP DTB), Operação 2 (
nvpower.sh) ou a receita MAXN para ambas. - Confirme a edição no rastreador de sobreposição de acordo com a convenção de confirmação de cada Operação.
- Implemente com
/jetson-promote-image→/jetson-flash-image. O novo DTB do BPMP envpower.shentrarão em vigor na próxima inicialização.
Operações compatíveis
| Operação | Onde a edição está localizada | Seção de procedimentos |
|---|---|---|
| Bloquear o clock da CPU/GPU em uma frequência específica | BPMP DTB max-rate-custom no nó de clock + nvpower.sh governador performance |
"Edição de conteúdo: max-rate-custom" + "Selecionar a edição" |
| Bloquear o EMC em sua taxa inicial (desativar o DVFS do EMC) | DTB do BPMP: bwmgr.enabled = 0, cactmon.enabled = 0, além de /delete-node/ osp-controller apenas no T26x |
"Edição de conteúdo: desativar/ativar o EMC DVFS" |
| Reativar o EMC DVFS | BPMP DTB: bwmgr.enabled = 1, cactmon.enabled = 1, restaurar osp-controller no T26x |
"Edição de conteúdo: Desativar/ativar o EMC DVFS" |
| Configure tudo para MAXN para testes de estresse | Combinar o acima exposto com nvpmodel MAXN como padrão de inicialização | veja a receita |
| Reduzir o limite máximo fixo do clock sem bloqueio | DTB do BPMP max-rate-custom apenas |
“Edição de conteúdo: max-rate-custom" |
| Limitar a taxa de um dispositivo sem fixar | nvpower.sh mín./máx. via sysfs |
"Selecionar a edição" |
Operação 1 — Edições no DTB do BPMP
Siga o protocolo de personalização do BPMP-DTB em
../../references/bsp-customization-bpmp-dtb.md.
O protocolo define os procedimentos — importação original na primeira vez,
dtc descompilação, recompilação, verificação de integridade e confirmação. Esta habilidade
fornece apenas o conteúdo específico do clock (quais nós e
propriedades devem ser editados durante a etapa “Editar o DTS” do protocolo).
Os .dtb é direcionado para o /jetson-promote-imageO canal A percorre o
rastreador e copia o arquivo para bsp_image.
Não edite o `
Resolva o DTB do BPMP com o SKU correto
De acordo com a seção “Resolvendo o DTB BPMP ativo” do protocolo, leia
BPFDTB_FILE a configuração do flash ativo. Para as formas comuns de configuração do Thor /
SKU único, essa é a linha estática BPFDTB_FILE=... linha
na configuração por placa .conf e o valor é definitivo tal como está.
Para configurações com multiplexação de SKU (cadeia de configuração do kit de desenvolvimento Orin AGX
que seleciona um DTB BPMP diferente por board_sku/board_FAB
via update_flash_args_common — veja
../../context/bsp-customization-software-layers.md#per-board-conf-dispatch--update_flash_args_common),
percorra a cadeia de despacho com board_sku= e
board_FAB= a partir do perfil ativo,
e leia BPFDTB_FILE da saída de despacho — e não da
linha estática da configuração por placa .conf. Os valores estáticos e despachados
coincidem para configurações não multiplexadas; o despacho é
obrigatório apenas quando a cadeia de configuração substitui condicionalmente
BPFDTB_FILE.
Lista de taxas máximas efetivas (inspeção)
Inspecione ambas as camadas do limite de tempo de execução — consulte references/clock-control-model.md#effective-runtime-ceiling — antes de decidir sobre um max-rate-custom valor.
O manual de inspeção (descompilação do lado do BPMP + grep; awk do lado do nvpmodel sobre o modo padrão de inicialização) está em references/bpmp-dtb-clock-edits.md#inspection-cookbook.
Para a camada nvpmodel, consulte /jetson-customize-nvpmodel.
Esta etapa não altera o estado — é uma pré-condição para dimensionar
a edição na etapa “Edição de conteúdo: max-rate-custom em um nó de relógio nomeado”.
Edição de conteúdo: max-rate-custom em um nó de relógio nomeado
Durante a etapa “Editar o DTS” do protocolo, modifique a propriedade
dentro do nó de relógio nomeado — nunca lateinit. max-rate-custom
deve estar estritamente abaixo do limite máximo do relógio (max-rate-maxn se
definido; caso contrário, o max_rate de um alvo em execução do
mesmo chip / SKU).
O formulário de edição do DTS, a semântica e o mapeamento nvpmodel ↔ BPMP do nó de relógio
estão disponíveis em references/bpmp-dtb-clock-edits.md.
Em seguida, devolva o controle ao protocolo — suas etapas “Recompilar”, “Verificar a validade
do blob recompilado”, “Inserir no rastreador de sobreposição” e “Limpeza”
cuidam do restante.
Convenção de mensagem de commit conforme o protocolo:
Edição de conteúdo: desativação/ativação do EMC DVFS
O comportamento padrão (EMC DVFS ativado) não requer edição. Desativar o EMC
DVFS é uma edição em múltiplos nós aplicada dentro da mesma etapa “Editar o DTS” do
protocolo, não uma bwmgr alternância:
| # | Editar | Escopo |
|---|---|---|
| 1 | bwmgr.enabled = <0x00> |
Todos os SoCs, obrigatório |
| 2 | cactmon.enabled = <0x00> |
Todos os SoCs, obrigatório |
| 3 | /delete-node/ osp-controller |
T26x (Thor) obrigatório — T23x (Orin) não possui esse nó, pular |
Detecção: dtc -I dtb -O dts
— zero ocorrências ⇒ caminho T23x. Trechos completos do DTS, os caminhos de sobrevivência,
os modos de falha e o procedimento de reativação estão em
references/emc-dvfs-disable.md.
Aplique as etapas do protocolo de “Recompilar” a “Limpeza” assim que a edição em vários nós estiver
concluída. Convenção de mensagem de commit:
A desativação aumenta o consumo de energia em modo inativo; destinada a testes de estresse/desempenho, não a rootfs de produção.
Reexecução + idempotência
De acordo com a seção “Reexecutabilidade” do protocolo, reexecutar esta
habilidade com o mesmo valor-alvo produz um commit sem efeito. Reexecutar
com um valor diferente reescreve a mesma propriedade — git log -- $BPMP_REL mostra o histórico por execução. Para retornar um relógio
ao seu max-rate-maxn limite máximo, edite o DTS para remover a
max-rate-custom linha e recompilar.
Operação 2 — edições no nvpower.sh
As edições nvpower.sh, que é executado na inicialização por meio de nvpower.service para definir
os reguladores e as taxas cpufreq / devfreq.
O arquivo do script
O script que esta Operação edita tem o caminho relativo:
Linux_for_Tegra/rootfs/etc/systemd/nvpower.sh
Ele está localizado em duas raízes; a Operação percorre ambas:
| Função | Local | A habilidade grava? |
|---|---|---|
| Detecção + fonte original | |
não — somente leitura |
| Alvo de edição de sobreposição + commit no Git | |
sim |
As subetapas subsequentes se referem ao arquivo por script para indicar a sobreposição
copiada em
Receita de edição de sobreposição (aplique antes de editar o nvpower.sh)
Siga a receita canônica
de edições fora da especialidade
no documento do fluxo de trabalho — par de importação pristine + commit de personalização, ambos
controlados pelo gate de pré-visualização. nvpower.sh É um único arquivo sem
conjunto de propagação; um commit original + um commit de personalização abrangem
toda a alteração.
Substituições específicas para esta skill:
/ rootfs/etc/systemd/nvpower.sh.- Mensagem sugerida para a importação original:
import pristine: rootfs/etc/systemd/nvpower.sh, corpoSource:./Linux_for_Tegra/ (BSP ) - Cabeçalho sugerido para o commit de personalização:
jetson-customize-clocks: nvpower.sh, linhas do corpo comoset_cpufreq_governor: desired_cpufreq_gov "schedutil" -> "performance".
Escolha a edição
(set_cpufreq_governor, set_devfreq_governor), receitas comuns de edição (fixação no Fmax, taxa estática, limites mínimo/máximo) e a nvidia-l4t-init advertência sobre atualização de pacotes estão localizadas em references/nvpower-sh-edits.md.
Implantação
O commit de personalização no rastreador de overlay não chega ao dispositivo por conta própria. A cadeia de implantação:
/jetson-promote-image— copia todos os arquivos rastreados na sobreposição para/Linux_for_Tegra/ sudo cp -ppararootfs/*destinos./jetson-flash-image— grava a versão atualizadabsp_imagepara o dispositivo.nvpower.serviceexecuta o novo script na próxima inicialização.- (Alternativa, sem gravação) Copie
/Linux_for_Tegra/rootfs/etc/systemd/nvpower.sh /etc/systemd/nvpower.sh, depoissudo systemctl restart nvpower.service(ou reinicie).
Editar /jetson-promote-image
e é perdida silenciosamente na próxima /jetson-init-image reextração.
Receita — fixe tudo no MAXN para testes de carga/desempenho
Combina as Operações 1 + 2. O BPMP da Operação 1 edita todo o fluxo
em uma única rodada do protocolo (um único ciclo de descompilação / edição em múltiplos nós
/ recompilação / confirmação — não faça o protocolo percorrer o ciclo
duas vezes para o mesmo .dtb):
- DTB do BPMP (o conteúdo da etapa “Edição de conteúdo:
max-rate-customem um nó de relógio nomeado”): deixemax-rate-customdesativado em todos os relógios de CPU / GPU / EMC; remova asmax-rate-customque reduzam o limite máximo. - DTB do BPMP (conteúdo da etapa “Edição de conteúdo: desativação/ativação do DVFS do EMC”): fixe o EMC em sua taxa de inicialização —
bwmgr.enabled = 0,cactmon.enabled = 0, mais/delete-node/ osp-controllerno T26x (ignore no T23x). - Aplique ambas as edições de conteúdo dentro de uma única invocação do protocolo “Editar o DTS” e, em seguida, execute as etapas restantes do protocolo (recompilar, verificação de integridade, commit único de personalização abrangendo ambas as edições de conteúdo).
- nvpower.sh (Operação 2): defina
desired_cpufreq_gov="performance"edesired_devfreq_gov="performance"incondicionalmente; remova a omissão de GPU/nvjpg emset_devfreq_governor. Aplique por meio da receita de edição de sobreposição da Operação 2 (a etapa “Receita de edição de sobreposição (aplique antes de editar o nvpower.sh)”) — um par separado de commit “pristine” + personalização no script do rootfs, distinto do commit do protocolo BPMP-DTB. - Defina o modo nvpmodel padrão de inicialização como MAXN por meio de
/jetson-customize-nvpmodel— os limites máximos do nvpmodel por clock ficam abaixo demax-rate-maxn, independentemente do conteúdo do DTB do BPMP.
Implemente /jetson-promote-image → /jetson-flash-image pega o novo DTB do BPMP (por meio do rastreador de overlay) e o nvpower.sh (por meio do mesmo rastreador de sobreposição) na próxima atualização de flash.
Limitações
- Apenas no momento da compilação da imagem. Todas as edições ficam sob
/Linux_for_Tegra/ /jetson-promote-image→/jetson-flash-image. O ajuste em tempo real do alvo está fora do escopo. max-rate-customapenas reduz o limite máximo. Deve estar estritamente abaixo demax-rate-maxn; o aumento do limite do silício não é suportado.- O limite máximo efetivo é de duas camadas. O limite máximo em tempo de execução é
min(BPMP cap, active-nvpmodel-mode cap). O limite do nvpmodel pertence a/jetson-customize-nvpmodel; esta habilidade não o altera. - Porta EMC DVFS condicional ao SoC. Desativar o EMC DVFS requer a edição de conjuntos de nós diferentes no T23x (bwmgr + cactmon) em comparação com o T26x (bwmgr + cactmon + delete
osp-controller). Uma detecção incorreta gera comportamento indefinido. - O limite da GPU no T23x é multinó. O clock da GPU é dividido entre
nafll_gpusyse cadanafll_gpcX; o limite só se aplica quando aplicado a todos eles. nvpower.shé gerenciado por pacote. Ele vem incluído emnvidia-l4t-init; atualizações do pacote sobrescrevem as edições no local. Configurações de longa duração devem preferir um substituto direto para o systemd ou um auxiliar equivalente.- O ODMDATA prevalece. Quando um token ODMDATA abrange uma propriedade, o token substitui as edições diretas no DTS do BPMP no momento da gravação na memória flash. As edições diretas no DTS do BPMP são o recurso alternativo para propriedades que nenhum token da NVIDIA alcança.
max-rate-maxnelateinitestão fora dos limites.max-rate-maxné o limite máximo do chip (somente leitura).lateinité para a inicialização do relógio na inicialização do sistema, não para substituições do limite máximo — nunca mexa em nenhum dos dois.- O BPMP DTB pode ser multiplexado por SKU. Em configurações de flash compostas/distribuídas (cadeia do kit de desenvolvimento Orin AGX),
BPFDTB_FILEé selecionado porboard_sku/board_FABviaupdate_flash_args_common. A leitura da linha estáticaBPFDTB_FILE=é incorreto quando a cadeia a substitui condicionalmente; resolva por meio do despacho.
Solução de problemas
| Erro | Causa | Solução |
|---|---|---|
max-rate-custom definido, mas o clock ainda atinge max-rate-maxn ativado na GPU T23x |
Apenas nafll_gpusys foi limitado; as nafll_gpcX partições ainda rodam a max-rate-maxn e dominam o limite efetivo. |
Aplique o mesmo max-rate-custom a nafll_gpusys e a cada nafll_gpcX nó enumerado por grep -nE '^\s*nafll_gpc[0-9]+\s*:' . |
| A desativação do EMC DVFS parece ter efeito, mas o EMC ainda escala no T26x | Apenas bwmgr.enabled = <0x00> foi definido; osp-controller permanece ativo e reemite alterações de frequência pelo caminho de QoS. |
Adicionar edições nº 2 (cactmon.enabled = <0x00>) e nº 3 (/delete-node/ osp-controller) dentro da mesma etapa “Editar o DTS”. Verifique osp-controller por meio de dtc -I dtb -O dts → espera-se 0. |
A desativação do EMC DVFS foi rejeitada no T23x com a mensagem “nó não encontrado” para osp-controller |
T23x (Orin) Os DTBs do BPMP não contêm osp-controller; a edição nº 3 deve ser ignorada no T23x. |
Detectar a família de SoC com a grep -c osp-controller etapa; aplique a edição nº 3 somente quando a contagem for ≥1. |
O BPMP se recusa a carregar o DTB após a edição: max-rate-custom >= max-rate-maxn |
max-rate-custom foi definido igual ou acima do limite máximo do silício. |
Reduzir max-rate-custom estritamente abaixo max-rate-maxn. Se max-rate-maxn estiver ausente do nó, consulte o limite ativo em um alvo em execução: cat /sys/kernel/debug/bpmp/debug/clk/. |
osp-controller reaparece após status = "disabled" |
status = "disabled" não remove o nó da árvore de dispositivos; o BPMP ainda o percorre. |
Substitua por /delete-node/ osp-controller; — o nó não deve existir para que o BPMP ignore o caminho. |
Alterações em nvpower.sh perdidas após apt upgrade |
nvpower.sh pertencem ao nvidia-l4t-init deb e são sobrescritas na atualização. |
Para configurações de teste de longa duração, insira as alterações no pacote em um drop-in do systemd ou em um arquivo auxiliar irmão referenciado por nvpower.sh, em vez de editar nvpower.sh no próprio arquivo. |
/jetson-promote-image é uma operação nula após a edição do DTB do BPMP |
A edição foi aplicada a /jetson-promote-imagesaída de — e não sua entrada. |
Mova a edição para |
| O limite parece ser aplicado na primeira inicialização e, em seguida, é reinicializado após uma mudança no modo de energia | O limite por clock do modo nvpmodel ativo é restrito abaixo de max-rate-custom. |
Inspecione ambas as camadas; se o nvpmodel estiver limitando, aumente (ou remova) o limite do nvpmodel por meio de /jetson-customize-nvpmodel. O limite do BPMP, por si só, não é o teto de tempo de execução. |
Referências
../../references/bsp-customization-bpmp-dtb.md— protocolo canônico de personalização do BPMP-DTB (importação original, descompilação, edição, recompilação, verificação de integridade, commit). A Operação 1 desta habilidade é um consumidor apenas de conteúdo; o protocolo é responsável pela mecânica.references/clock-control-model.md— pilha de camadas, visão geral dos dois limites máximos, fórmula do limite máximo efetivo de tempo de execução.references/bpmp-dtb-clock-edits.md— semântica dos dois limites máximos, formulário de edição DTS, mapeamento nvpmodel ↔ BPMP de nós de relógio, manual de inspeção.references/emc-dvfs-disable.md— procedimento completo de desativação do EMC DVFS condicional ao SoC com trechos de DTS, detecção e reativação.references/nvpower-sh-edits.md—nvpower.shlocalizações de funções + receitas de edição comum + advertência sobre atualização de pacotes./jetson-customize-nvpmodel— habilidade relacionada: modos de potência do nvpmodel. O limite por clock do modo ativo é restrito abaixo do limite do DTB do 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 os arquivos
9 arquivosInstalar jetson-customize-clocks
Baixe e extraia os arquivos das habilidades para o diretório .claude/skills/.
Baixar ZIPClone o repositório e copie os arquivos da habilidade para o seu projeto.
git clone https://github.com/NVIDIA/skills/tree/main/skills/jetson-customize-clocks # Copy SKILL.md to your .claude/skills/ directory
Copiar
