Personnaliser les horloges

Objectif

Personnaliser le comportement des horloges CPU, GPU et EMC sur une cible Jetson en éditant les fichiers sous Linux_for_Tegra/ avant de flasher l'image. Deux couches sont concernées :

• Le BPMP DTB à Linux_for_Tegra/bootloader/<BPFDTB_FILE> — plafonds max-rate-custom par horloge, plus la porte EMC DVFS (bwmgr + cactmon sur tous les SoCs ; osp-controller sur T26x uniquement).
• nvpower.sh à Linux_for_Tegra/rootfs/etc/systemd/nvpower.sh — gouverneurs cpufreq / devfreq et (optionnellement) débits min / max / statiques par appareil écrits dans sysfs au démarrage.

Déclencheurs courants : « verrouiller la fréquence CPU/GPU/EMC », « épingler le GPU à Fmax », « épingler EMC à MAXN », « désactiver/activer EMC DVFS », « désactiver/activer CPU DVFS », « définir le débit max CPU/GPU », « changer le gouverneur cpufreq ».

Hors de portée : tuning d'horloge en temps réel sur une cible active (sans étape de flash), édits du mode puissance nvpmodel (utilisez la compétence sœur /jetson-customize-nvpmodel), et surrides de plafond silicium (max-rate-maxn est en lecture seule).

Prérequis

Résolvez le profil actif selon ../../context/target-platform-contract.md. Refusez et routez dans ces cas :

Résolvez les chemins :

• <bsp_image.root_path> depuis bsp_image.root_path: s'il existe, sinon <workspace>/Image.
• <source.root_path> depuis source.root_path: s'il existe, sinon <workspace>/Source.

<bsp_image.root_path> est en lecture seule pour cette compétence ; chaque écriture (BPMP DTB de l'opération 1 et nvpower.sh de l'opération 2) se fait sous <source.root_path> (le traceur d'overlay). C'est l'invariant du flux de travail dans ../../context/bsp-customization-workflow.md#workflow-invariants — l'édition manuelle en amont détruit silencieusement la trace diff et rend /jetson-promote-image inefficace.

Instructions

1. Résolvez les prérequis ci-dessus (profil actif, image BSP extraite, traceur d'overlay source initialisé).
2. Choisissez l'opération dans le tableau ci-dessous.
3. Suivez la section de procédure liée — Opération 1 (BPMP DTB), Opération 2 (nvpower.sh), ou la recette MAXN pour les deux.
4. Committez l'édition à l'intérieur du traceur d'overlay selon la convention de commit de chaque opération.
5. Déployez avec /jetson-promote-image → /jetson-flash-image. Le nouveau BPMP DTB et nvpower.sh prennent effet au prochain démarrage.

Opérations supportées

Opération 1 — Éditions BPMP DTB

Suivez le protocole de personnalisation BPMP-DTB dans ../../references/bsp-customization-bpmp-dtb.md. Le protocole possède la mécanique — import pristine à la première utilisation, décompilation dtc, recompilation, vérification de santé, commit. Cette compétence fournit uniquement le contenu spécifique à l'horloge (quels nœuds et propriétés éditer lors de l'étape « Éditer le DTS » du protocole).

Le .dtb édité atterrit dans le traceur d'overlay <source.root_path>/Linux_for_Tegra/. Le canal A de /jetson-promote-image parcourt le traceur et copie le fichier dans bsp_image. N'éditez pas directement <bsp_image.root_path>/Linux_for_Tegra/bootloader/<bpmp-dtb> — c'est la sortie de promote, pas une entrée.

Résoudre le BPMP DTB correct pour la SKU

Selon la section « Resolving the active BPMP DTB » du protocole, lisez BPFDTB_FILE depuis la conf de flash active. Pour les formes de conf Thor / SKU unique courantes, c'est la ligne statique BPFDTB_FILE=... dans le .conf par carte et la valeur est autoritaire telle quelle.

Pour les formes de conf multiplexées par SKU (chaîne de conf Orin AGX devkit qui sélectionne un BPMP DTB différent par board_sku/board_FAB via update_flash_args_common — voir ../../context/bsp-customization-software-layers.md#per-board-conf-dispatch--update_flash_args_common), parcourez la chaîne de dispatch avec board_sku=<module.sku> et board_FAB=<module.revision ou vide> du profil actif, et lisez BPFDTB_FILE depuis la sortie du dispatch — pas depuis la ligne statique du .conf par carte. Les valeurs statique et dispatchée coïncident pour les confs non multiplexées ; le dispatch est obligatoire seulement si la chaîne de conf surride conditionnellement BPFDTB_FILE.

Énumérer les débits max effectifs (inspection)

Inspectez les deux couches du plafond d'exécution — voir references/clock-control-model.md#effective-runtime-ceiling — avant de décider d'une valeur max-rate-custom.

Le livre de recettes d'inspection (décompile côté BPMP + grep ; côté nvpmodel awk sur le mode par défaut de démarrage) se trouve dans references/bpmp-dtb-clock-edits.md#inspection-cookbook.

Pour la couche nvpmodel voir /jetson-customize-nvpmodel.

Cette étape ne mute pas l'état — c'est une précondition pour dimensionner l'édition à l'étape « Édition de contenu : max-rate-custom sur un nœud horloge nommé ».

Édition de contenu : max-rate-custom sur un nœud horloge nommé

Lors de l'étape « Éditer le DTS » du protocole, modifiez la propriété à l'intérieur du nœud horloge nommé — jamais lateinit. max-rate-custom doit être strictement en dessous du plafond dur de l'horloge (max-rate-maxn s'il est défini, sinon le max_rate vivant d'une cible active de la même puce / SKU).

La forme d'édition DTS, la sémantique et le mappage nœud-horloge nvpmodel ↔ BPMP vivent dans references/bpmp-dtb-clock-edits.md.

Ensuite, redonnez le contrôle au protocole — ses étapes « Recompile », « Sanity-check the recompiled blob », « Stage in the overlay tracker » et « Cleanup » couvrent le reste. Convention de message de commit selon le protocole : <BPMP_BASENAME>: jetson-customize-clocks — <clock-node> max-rate-custom = <value>.

Édition de contenu : désactiver / activer EMC DVFS

Le comportement par défaut (EMC DVFS activé) ne nécessite aucune édition. Désactiver EMC DVFS est une édition multi-nœud appliquée à l'intérieur de la même étape « Éditer le DTS » du protocole, pas un toggle bwmgr :

Détection : dtc -I dtb -O dts <bpmp-dtb> | grep -c osp-controller — zéro résultats ⇒ chemin T23x. Les DTS snippets complets, les modes d'échec de chemins survivants et la procédure de réactivation se trouvent dans references/emc-dvfs-disable.md.

Appliquez les étapes « Recompile » à « Cleanup » du protocole une fois que l'édition multi-nœud est en place. Convention de message de commit : <BPMP_BASENAME>: jetson-customize-clocks — EMC DVFS disable (bwmgr + cactmon[+ osp-controller]).

La désactivation augmente la puissance d'inactivité ; destinée aux tests de charge / performance, non à la rootfs de production.

Relancer + idempotence

Selon la section « Re-runnability » du protocole, relancer cette compétence avec la même valeur cible produit un commit sans-op. Relancer avec une valeur différente réécrit la même propriété — git log -- $BPMP_REL montre l'historique par exécution. Pour ramener une horloge à son plafond max-rate-maxn, éditez le DTS pour supprimer la ligne max-rate-custom et recompilez.

Opération 2 — Éditions nvpower.sh

Édite nvpower.sh, qui s'exécute au démarrage via nvpower.service pour définir les gouverneurs et débits cpufreq / devfreq.

Le fichier par script

Le script qu'édite cette opération a le chemin relatif :

Linux_for_Tegra/rootfs/etc/systemd/nvpower.sh

Il vit dans deux racines ; l'opération parcourt les deux :

Les sous-étapes suivantes se réfèrent au fichier par script pour signifier la copie overlay sous <source.root_path>. La copie <bsp_image.root_path> est lue une fois lors de l'étape d'import pristine ci-dessous, puis jamais retouchée.

Recette d'édition overlay (appliquer avant d'éditer nvpower.sh)

Suivez la recette des éditions hors compétence canonique dans le doc du flux de travail — import pristine + paire de commit de personnalisation, tous deux contrôlés par la porte de prévisualisation. nvpower.sh est un fichier unique sans ensemble de propagation ; un commit pristine + un commit de personnalisation couvre l'ensemble de la modification.

Substitutions concrètes pour cette compétence :

• <rel>/<file> est rootfs/etc/systemd/nvpower.sh.
• Message d'import pristine suggéré : import pristine: rootfs/etc/systemd/nvpower.sh, corps Source: <bsp_image.root_path>/Linux_for_Tegra/ (BSP <bsp_image.version>).
• En-tête de commit de personnalisation suggéré : jetson-customize-clocks: nvpower.sh <summary>, lignes de corps comme set_cpufreq_governor: desired_cpufreq_gov "schedutil" -> "performance".

Choisir l'édition

Les localisations de fonctions (set_cpufreq_governor, set_devfreq_governor), les recettes d'édition courantes (épingler à Fmax, débit statique, bornes min/max), et la mise en garde de l'upgrade du paquet nvidia-l4t-init vivent dans references/nvpower-sh-edits.md.

Déployer

Le commit de personnalisation du traceur d'overlay ne reach pas l'appareil de lui-même. La chaîne de déploiement :

1. /jetson-promote-image — copie chaque fichier tracé du traceur overlay dans <bsp_image.root_path>/Linux_for_Tegra/. Conscient du diff (ignorer les octets identiques) ; utilise sudo cp -p pour les destinations rootfs/*.
2. /jetson-flash-image — flashe le bsp_image mis à jour sur l'appareil. nvpower.service exécute le nouveau script au prochain démarrage.
3. (Alternatif, sans flash) Copiez <source.root_path>/Linux_for_Tegra/rootfs/etc/systemd/nvpower.sh directement dans /etc/systemd/nvpower.sh de la cible active, puis sudo systemctl restart nvpower.service (ou redémarrage).

L'édition de <source.root_path>/... sans commit — ou l'édition directe de <bsp_image.root_path>/... — ne fait rien pour /jetson-promote-image et est silencieusement perdu au prochain /jetson-init-image ré-extract.

Recette — épingler tout à MAXN pour les tests de charge / performance

Combine les opérations 1 + 2. Les éditions BPMP de l'opération 1 s'écoulent toutes à travers une ronde du protocole (un seul cycle décompile / édition multi-nœud / recompilation / commit — ne parcourez pas le protocole deux fois pour le même .dtb) :

1. BPMP DTB (contenu de l'étape « Édition de contenu : max-rate-custom sur un nœud horloge nommé ») : laissez max-rate-custom non défini sur chaque horloge CPU / GPU / EMC ; supprimez les lignes max-rate-custom existantes qui abaissent le plafond.
2. BPMP DTB (contenu de l'étape « Édition de contenu : désactiver / activer EMC DVFS ») : épinglez EMC à son débit d'initialisation — bwmgr.enabled = 0, cactmon.enabled = 0, plus /delete-node/ osp-controller sur T26x (ignorer sur T23x).
3. Appliquez les deux éditions de contenu à l'intérieur d'une seule invocation « Éditer le DTS » du protocole, puis exécutez les étapes de protocole restantes (recompile, sanity-check, un commit de personnalisation unique couvrant les deux éditions de contenu).
4. nvpower.sh (opération 2) : définissez desired_cpufreq_gov="performance" et desired_devfreq_gov="performance" inconditionnellement ; supprimez le skip GPU/nvjpg dans set_devfreq_governor. S'applique via la recette d'édition overlay de l'opération 2 (l'étape « Recette d'édition overlay (appliquer avant d'éditer nvpower.sh) ») — une paire pristine + commit de personnalisation overlay distincte sur le script rootfs, différente du commit du protocole BPMP-DTB.
5. Définissez le mode nvpmodel par défaut de démarrage à MAXN via /jetson-customize-nvpmodel — le plafond par horloge du nvpmodel serre en dessous de max-rate-maxn quel que soit le contenu du BPMP DTB.

Le déploiement /jetson-promote-image → /jetson-flash-image récupère le nouveau BPMP DTB (via le traceur d'overlay) et le nvpower.sh édité (via le même traceur d'overlay) au prochain flash.

Limitations

• Image-build-time only. Toutes les éditions atterrissent sous <source.root_path>/Linux_for_Tegra/ et reach l'appareil uniquement via /jetson-promote-image → /jetson-flash-image. Le tuning live-target est hors de portée.
• max-rate-custom abaisse seulement le plafond. Il doit être strictement en dessous de max-rate-maxn ; élever le plafond silicium n'est pas supporté.
• Le plafond effectif est deux couches. Le plafond d'exécution est min(plafond BPMP, plafond mode-nvpmodel actif). Le plafond nvpmodel est détenu par /jetson-customize-nvpmodel ; cette compétence ne l'édite pas.
• Porte EMC DVFS conditionnelle SoC. Désactiver EMC DVFS nécessite d'éditer des ensembles de nœuds différents sur T23x (bwmgr + cactmon) vs T26x (bwmgr + cactmon + supprimer osp-controller). Une mauvaise détection produit un comportement indéfini.
• Le plafond GPU T23x est multi-nœud. L'horloge GPU est scindée sur nafll_gpusys et chaque nafll_gpcX ; le plafond lie seulement quand appliqué à tous.
• nvpower.sh est géré par paquet. Il est livré dans nvidia-l4t-init ; les upgrades de paquet écrasent les édits sur place. Les configurations de longue durée devraient préférer une drop-in systemd ou un helper sœur.
• ODMDATA gagne. Quand un token ODMDATA couvre une propriété, le token surride les édits directs BPMP DTS au moment du flash. Les édits directs BPMP DTS sont la solution de secours pour les propriétés qu'aucun token NVIDIA n'atteint.
• max-rate-maxn et lateinit sont interdits. max-rate-maxn est le plafond silicium (lecture seule). lateinit est pour l'init d'horloge de démarrage, pas pour les overrides de plafond — ne touchez jamais aux deux.
• BPMP DTB peut être multiplexé par SKU. Sur les confs de flash composées / dispatchées (chaîne Orin AGX devkit), BPFDTB_FILE est sélectionné par board_sku / board_FAB via update_flash_args_common. Lire la ligne statique BPFDTB_FILE= est faux quand la chaîne le surride conditionnellement ; résolvez via le dispatch.

Dépannage

Références

• ../../references/bsp-customization-bpmp-dtb.md — protocole de personnalisation BPMP-DTB canonique (import pristine, décompile, édition, recompilation, sanity-check, commit). L'opération 1 de cette compétence est un consommateur contenu-uniquement ; le protocole détient la mécanique.
• references/clock-control-model.md — pile de couches, aperçu deux-plafonds, formule effective-runtime-ceiling.
• references/bpmp-dtb-clock-edits.md — sémantique deux-plafonds, forme d'édition DTS, mappage nœud-horloge nvpmodel ↔ BPMP, livre de recettes d'inspection.
• references/emc-dvfs-disable.md — procédure complète de désactivation EMC DVFS conditionnelle SoC avec DTS snippets, détection, réactivation.
• references/nvpower-sh-edits.md — localisations de fonction nvpower.sh + recettes d'édition courantes + mise en garde d'upgrade de paquet.
• /jetson-customize-nvpmodel — compétence sœur : modes puissance nvpmodel. Le plafond par horloge du mode actif serre en dessous du plafond BPMP DTB.