jetson-customize-fan

Par nvidia · skills

À utiliser lorsque vous devez ajouter, supprimer, modifier, lister ou changer le profil de ventilateur par défaut au démarrage d'un profil de ventilateur nvfancontrol sur une cible Jetson/Tegra (Orin, Thor). Déclencheurs : modifier le profil de ventilateur, régler la courbe de ventilateur.

npx skills add https://github.com/nvidia/skills --skill jetson-customize-fan

Modifier le profil fan nvfancontrol (côté BSP)

Objectif

Éditer la configuration nvfancontrol par carte pour que l'appareil démarre avec la courbe fan / le mode de contrôle / le gouverneur / le profil par défaut souhaité. Côté BSP uniquement — toutes les écritures se font dans le tracker d'overlay, la copie bsp_image en amont est en lecture seule.

Cette skill gère les éditions côté BSP du fichier de configuration nvfancontrol par carte : ajouter des profils, supprimer des profils, éditer les courbes temp → PWM / RPM, changer le profil / mode de contrôle / gouverneur de démarrage par défaut, et lister les profils définis. S'applique sur les plateformes Jetson / Tegra (T234 Orin, T264 Thor).

Format de fichier (canonique, selon l'en-tête du fichier BSP)

POLLING_INTERVAL <seconds>

<FAN <index>>
    TMARGIN <ENABLED|DISABLED>
    FAN_GOVERNOR <type> {
        STEP_SIZE <int>
    }
    FAN_CONTROL <close_loop|open_loop> {
        RPM_TOLERANCE <rpm>
    }
    FAN_PROFILE <name> {
        # TEMP HYST PWM RPM
        <T0> <H0> <P0> <R0>
        ...
    }
    FAN_PROFILE <name> { ... }       # one or more profiles
    THERMAL_GROUP <id> {
        GROUP_MAX_TEMP <C>
        # zone-name <coeffs csv> <max-temp>
        <zone> <coeffs> <max-temp>
        ...
    }
    FAN_DEFAULT_CONTROL  <close_loop|open_loop>
    FAN_DEFAULT_PROFILE  <name>
    FAN_DEFAULT_GOVERNOR <type>
    KICKSTART_PWM <0..255>

Règles :

  • Les tuples de courbe de profil sont à 4 colonnes : TEMP HYST PWM RPM. Triez les points par ordre croissant de TEMP ; le démon interpole entre eux.
  • PWM est 0..255 (cycle utile 8 bits) ; RPM est la vitesse cible en boucle fermée. Une ligne 0 0 à la fin, en haut, bloque le ventilateur au-delà de GROUP_MAX_TEMP.
  • HYST est l'hystérésis (°C) à ce point — le contrôleur attend HYST degrés de refroidissement avant de descendre la courbe.
  • FAN_DEFAULT_PROFILE doit référencer un bloc FAN_PROFILE existant dans le même <FAN N>. nvfancontrol ne démarre pas si le profil par défaut pointe vers un profil manquant.
  • FAN_DEFAULT_CONTROL = close_loop (vise la RPM cible, nécessite un tachymètre) ou open_loop (écrit le PWM directement).
  • FAN_DEFAULT_GOVERNOR = cont (interpolation continue) et autres valeurs spécifiques à la famille ; copiez verbatim des fichiers existants par carte lors de l'introduction d'une nouvelle.
  • THERMAL_GROUP mappe les zones thermiques à l'entrée du contrôleur. Les coefficients sont un CSV à 20 éléments — copiez verbatim des entrées existantes ; les valeurs varient selon la famille de puces et la zone.
  • <FAN N> est un bloc par index de ventilateur (typique : <FAN 1>). Les délimiteurs de bloc <...> et {...} sont stricts ; préservez l'indentation correspondant aux lignes voisines.
  • Les courbes sont caractérisées, non inventées. Ajoutez ou éditez les courbes à partir de données thermiques-acoustiques réelles pour la plateforme ; n'interpolez pas à partir de profils voisins ou ne copiez pas entre familles de puces.

Prérequis

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

Condition Refuser avec
Pas de profil actif, ou active: NA Route vers /jetson-set-target ou /jetson-init-target.
Le profil manque le bloc bsp_image: Route vers /jetson-init-image.
<bsp_image.root_path>/Linux_for_Tegra/ manquant Route vers /jetson-init-image.
<source.root_path>/Linux_for_Tegra/ manquant ou pas un repo git Route vers /jetson-init-source.

Résolvez les chemins :

  • <bsp_image.root_path> depuis bsp_image.root_path: si présent, sinon <workspace>/Image.
  • <source.root_path> depuis source.root_path: si présent, sinon <workspace>/Source.

<bsp_image.root_path> est en lecture seule pour cette skill ; toute écriture se fait sous <source.root_path> (le tracker d'overlay). C'est l'invariant de workflow dans ../../context/bsp-customization-workflow.md#workflow-invariants — l'édition manuelle en amont détruit silencieusement la traçabilité du diff et rend /jetson-promote-image inopérant.

Le fichier par carte

Le fichier conf que cette skill édite a le chemin relatif :

Linux_for_Tegra/rootfs/etc/nvpower/nvfancontrol/nvfancontrol_<active-sku>.conf

Il existe dans deux racines ; la skill les parcourt toutes les deux :

Rôle Localisation La skill écrit ?
Détection + source vierge <bsp_image.root_path>/Linux_for_Tegra/rootfs/etc/nvpower/nvfancontrol/ non — en lecture seule
Cible d'édition d'overlay + commit git <source.root_path>/Linux_for_Tegra/rootfs/etc/nvpower/nvfancontrol/ oui

Les sections suivantes se réfèrent au fichier par carte pour signifier la copie d'overlay sous <source.root_path>. Les opérations 1–4 lisent, éditent et sauvegardent toutes cette copie d'overlay. La copie <bsp_image.root_path> est lue une fois pendant l'étape de détection « Résoudre <active-sku> » et une fois pendant l'étape d'import vierge de la Recette d'édition d'overlay, puis jamais touchée de nouveau.

Résoudre <active-sku> — quel fichier éditer

Les conventions de nommage varient par famille de produit :

  • nvfancontrol_<module.id>_<module.sku>.conf — la plupart des pièces Orin (ex. nvfancontrol_p3767_0000.conf, nvfancontrol_p3701_0008.conf).
  • nvfancontrol_<module.id>_<module.sku>_<carrier.id>_<carrier.sku>.conf — variantes Thor où le carrier lève l'ambiguïté (ex. nvfancontrol_p3834_0008_p4071_0000.conf).
  • nvfancontrol_<carrier>_<sku>_<rev>.conf — variantes IGX revision (ex. nvfancontrol_p3740_0002_b01.conf).

Le démon nvfancontrol résout le bon fichier au démarrage basé sur le compatible DT du matériel booted plus les IDs de carte (pas de script helper — c'est fait à l'intérieur du binaire). Pour mapper côté BSP sans une cible en exécution, contre <bsp_image.root_path> :

  1. Lister <bsp_image.root_path>/Linux_for_Tegra/rootfs/etc/nvpower/nvfancontrol/.
  2. Filtrer les noms de fichiers qui contiennent <module.id>_<module.sku> du profil actif.
  3. Si plusieurs candidats restent, affinez avec <carrier.id>_<carrier.sku> et (quand pertinent) l'étiquette de révision du carrier.
  4. Si toujours ambigu, exécutez la chaîne de dispatch de conf flash par carte pour lire le compatible du kernel DTB et choisir le fichier dont le nom s'aligne avec le carrier / carte résolu.
  5. Vérifiez que le fichier choisi existe réellement sous <bsp_image.root_path>/Linux_for_Tegra/rootfs/etc/nvpower/nvfancontrol/.

Ne composez pas aveuglément un nom de fichier — la convention de nommage varie par famille de produit.

Ensemble de propagation — confs à synchroniser

Le fichier SKU actif est rarement le seul conf qui devrait recevoir une personnalisation. Après l'avoir édité, appliquez la même édition à chaque frère dans l'ensemble de propagation pour que le changement survive quel que soit le module / SKU de baseboard qui démarre :

  • Le conf nvfancontrol de la plateforme de référence — le conf en amont duquel le fichier actif a été dérivé (résolvez via reference_devkit dans le profil actif, ou l'ascendance de fork jetson-derive-carrier). Pour un BSP qui contient seulement la référence (aucun carrier dérivé), c'est le même fichier que l'actif et la règle se réduit à une no-op.
  • Chaque conf nvfancontrol dérivé de carrier — chaque nvfancontrol_*.conf produit par jetson-derive-carrier pour un carrier personnalisé sur le même module SKU.

« Appliquer la même édition » ≠ copie de fichier en masse. Portez les lignes FAN_PROFILE / contrôle changées dans chaque frère ; préservez chaque autre ligne. Les confs frères détiennent souvent des deltas spécifiques au carrier (coefficients THERMAL_GROUP différents pour une solution thermique différente, plafonds RPM de tachymètre différents) qui doivent rester intacts — une surcharge en masse dés-accorderait le ventilateur sur ces carriers. La copie en masse est sûre seulement si les deux confs étaient byte-identiques avant l'édition.

Recette d'édition d'overlay (appliquer avant toute opération)

Suivez la Recette d'éditions hors-skill canonique dans le doc de workflow — import vierge + paire de commit de personnalisation, tous deux gardés par la porte de preview. Appliquez une fois par exécution, couvrant chaque fichier par carte que l'exécution touche (le conf actif plus chaque frère dans l'Ensemble de propagation).

Substitutions concrètes pour cette skill :

  • <rel>/<file> est rootfs/etc/nvpower/nvfancontrol/<conf>.
  • Message d'import vierge suggéré : import pristine: <chemins rel séparés par des virgules des confs importés>, corps Source: <bsp_image.root_path>/Linux_for_Tegra/ (BSP <bsp_image.version>).
  • En-tête de commit de personnalisation suggéré : jetson-customize-fan: <summary>, lignes de corps comme nvfancontrol_p3767_0000.conf: added FAN_PROFILE static (open-loop, PWM=255 flat), FAN_DEFAULT_CONTROL close_loop -> open_loop, FAN_DEFAULT_PROFILE quiet -> static.

Instructions

Choisissez l'opération qui correspond à l'intention de l'utilisateur et suivez la sous-section correspondante. Toutes les opérations côté écriture (1–4) doivent d'abord appliquer la Recette d'édition d'overlay.

  • Opération 1 — Ajouter un nouveau profil fan.
  • Opération 2 — Supprimer un profil fan.
  • Opération 3 — Éditer un profil fan existant (courbe, hystérésis).
  • Opération 4 — Changer le défaut de démarrage (contrôle / profil / gouverneur).
  • Opération 5 — Lister les profils fan définis (lecture seule).

Après toute opération côté écriture, exécutez la chaîne Deploy (## Deploy) pour placer le changement sur l'appareil.

Exemples

Ajouter un profil agressif à une cible P3767-0000 (kit dev Orin Nano) et le définir comme défaut de démarrage :

/jetson-customize-fan
> add a profile called "aggressive" with the curve {0:255, 40:150, 80:0}
> set FAN_DEFAULT_PROFILE to aggressive

Assouplir la rampe fan sur le profil existant quiet (augmenter HYST, baisser PWM au milieu) :

/jetson-customize-fan
> edit FAN_PROFILE quiet — raise HYST to 5 from 30 °C up, drop PWM at 60 °C to 80

Lister quels profils le SKU actif définit actuellement et lequel est le défaut de démarrage :

/jetson-customize-fan
> list defined fan profiles

Opération 1 — Ajouter un nouveau profil fan

Appliquez d'abord la Recette d'édition d'overlay.

  1. Dans le fichier par carte, à l'intérieur du bloc <FAN N>, ajoutez un nouveau FAN_PROFILE <name> { ... } entre les profils existants. L'ordre de parse du démon n'importe pas, mais le regroupement avec les frères garde le fichier lisible.
  2. Choisissez <name> en minuscules, sans espace blanc (ex. quiet, cool, aggressive).
  3. Remplissez le tableau de courbe — tuples 4-colonnes TEMP HYST PWM RPM, TEMP croissant. Terminez avec au moins une ligne au-dessus de GROUP_MAX_TEMP pour que le comportement à température excessive soit défini.

Squelette exemple :

FAN_PROFILE aggressive {
    #TEMP HYST PWM RPM
    0    0    255 6000
    20   2    255 6000
    40   2    150 3500
    60   2    50  1500
    80   0    0   0
    105  0    0   0
}

Validez (voir Règles) :

  • Chaque TEMP se trouve dans 0..GROUP_MAX_TEMP du THERMAL_GROUP.
  • PWM ∈ [0, 255] ; RPM ≤ le max rapporté par tachymètre de la plateforme (varie par pièce fan).
  • Les tuples sont triés en croissant par TEMP.

Si vous avez l'intention que le nouveau profil soit le défaut de démarrage, suivez l'opération 4.

Opération 2 — Supprimer un profil fan

Appliquez d'abord la Recette d'édition d'overlay.

  1. Dans le fichier par carte, supprimez le bloc entier FAN_PROFILE <name> { ... } y compris toutes les lignes de courbe et la fermeture }.
  2. Si le <name> supprimé correspond au FAN_DEFAULT_PROFILE en fin, pointez FAN_DEFAULT_PROFILE vers un profil restant — sinon le démon ne démarre pas.
  3. Cherchez les références en dur dans le rootfs avant de déclarer le changement sûr :
    grep -rn "nvfancontrol.*profile\|FAN_PROFILE" \
  Linux_for_Tegra/rootfs/etc 2>/dev/null

Les profils restants ne nécessitent pas de renommage.

Opération 3 — Éditer un profil fan existant

Appliquez d'abord la Recette d'édition d'overlay.

  1. Dans le fichier par carte, modifiez les lignes de courbe du FAN_PROFILE <name> cible. Conservez la forme 4-colonnes TEMP HYST PWM RPM.
  2. Maintenez l'ordre croissant de TEMP ; insérez ou supprimez des lignes selon les besoins.
  3. Ajustez HYST pour affiner l'anti-oscillation : trop bas → le ventilateur s'agite près d'un point de courbe ; trop haut → le ventilateur accuse du retard sur la réalité.
  4. Validez selon les règles de l'opération 1.

Les éditions à KICKSTART_PWM, RPM_TOLERANCE (à l'intérieur de FAN_CONTROL), ou STEP_SIZE (à l'intérieur de FAN_GOVERNOR) se situent en dehors des profils mais règlent le même ventilateur ; même fichier par carte.

Opération 4 — Changer le défaut de démarrage

Appliquez d'abord la Recette d'édition d'overlay.

Éditez les lignes de défaut en fin à l'intérieur du bloc <FAN N> :

FAN_DEFAULT_CONTROL  <close_loop|open_loop>
FAN_DEFAULT_PROFILE  <name>
FAN_DEFAULT_GOVERNOR <type>

FAN_DEFAULT_PROFILE doit référencer un FAN_PROFILE existant dans le même bloc <FAN N>. FAN_DEFAULT_CONTROL et FAN_DEFAULT_GOVERNOR doivent référencer des valeurs que le binaire supporte — copiez-les depuis les fichiers existants par carte lors d'un changement.

Opération 5 — Lister les profils fan définis

C'est une opération en lecture seule ; aucune configuration du tracker d'overlay n'est nécessaire. Exécutez-la contre la copie que vous souhaitez inspecter (<bsp_image.root_path>/... pour l'état vierge, <source.root_path>/... pour l'état post-édition) :

grep -E '^[[:space:]]*FAN_PROFILE ' <fichier par carte>
grep -E '^[[:space:]]*FAN_DEFAULT_'  <fichier par carte>

La première affiche tous les noms de profil du fichier ; la seconde affiche les défauts de démarrage (contrôle / profil / gouverneur).

Limitations

  • Scope côté BSP uniquement — cette skill ne touche jamais directement /etc/nvpower/nvfancontrol/ sur une cible en exécution. La tuning en direct nécessite un redémarrage via Deploy, ou le flux side-channel scp + systemctl restart décrit dans ## Deploy.
  • Les éditions se font uniquement dans la copie d'overlay sous <source.root_path> ; la copie <bsp_image.root_path> est en lecture seule et est réécrite par /jetson-promote-image. L'édition manuelle de bsp_image est silencieusement perdue au prochain /jetson-init-image re-extract.
  • Les tuples de courbe doivent refléter des données thermiques-acoustiques caractérisées pour la plateforme — cette skill n'interpole pas et ne copie pas les courbes entre familles de puces.
  • La propagation entre carriers frères (même module SKU) est partielle par design : seulement les lignes FAN_PROFILE / contrôle changées sont portées, jamais une surcharge de fichier en masse, car les confs frères peuvent détenir des THERMAL_GROUP / plafonds RPM spécifiques au carrier.
  • Les limites des points de courbe sont spécifiques à la famille ; copiez verbatim des confs existants lors de l'introduction de nouveaux coefficients THERMAL_GROUP ou valeurs FAN_DEFAULT_GOVERNOR.

Dépannage

Erreur Cause Solution
nvfancontrol.service ne démarre pas après édition FAN_DEFAULT_PROFILE référence un profil supprimé ou renommé Définissez FAN_DEFAULT_PROFILE sur un FAN_PROFILE <name> existant dans le même <FAN N>.
Le ventilateur s'agite près d'un point de courbe HYST trop bas Augmentez HYST sur la ligne affectée (typique 2–5 °C).
Le ventilateur accuse du retard sur la réalité HYST trop haut Baissez HYST sur la ligne affectée.
Le ventilateur ne démarre jamais à haute température Courbe manquant une ligne au-dessus de GROUP_MAX_TEMP, ou le 0 0 en fin tronque au-dessus de l'ambiance Ajoutez un tuple haute-temp avec PWM/RPM non-nul ; épinglez la ligne sur-temp seulement au-dessus de GROUP_MAX_TEMP.
L'erreur de parse du démon référence le nombre de colonnes La ligne de courbe n'est pas 4-colonnes TEMP HYST PWM RPM Restaurez la forme 4-colonnes ; supprimez les espaces traînants et les colonnes orphelines.
La cible RPM ne s'approche jamais en boucle fermée Cible au-dessus du max rapporté par tachymètre, ou FAN_CONTROL défini à open_loop Baissez RPM au-dedans du max mécanique du ventilateur, ou changez FAN_DEFAULT_CONTROL à close_loop.
Le changement a disparu après /jetson-init-image re-extract L'édition est tombée dans <bsp_image.root_path> au lieu d'overlay <source.root_path> Réappliquez via la Recette d'édition d'overlay pour que le changement soit commité dans le tracker d'overlay.
Le carrier frère démarre avec mauvais plafond de tachymètre après propagation La copie de fichier en masse a écrasé le THERMAL_GROUP / lignes RPM spécifiques au carrier Portez seulement les lignes changées selon l'Ensemble de propagation ; restaurez le THERMAL_GROUP original du carrier.

Deploy

Le commit de personnalisation dans le tracker d'overlay n'atteint pas l'appareil de lui-même. La chaîne Deploy :

  1. /jetson-promote-image — copie chaque fichier suivi dans l'overlay vers <bsp_image.root_path>/Linux_for_Tegra/. Aware du diff (saute byte-identique) ; utilise sudo cp -p pour les destinations rootfs/*.
  2. /jetson-flash-image — flash le bsp_image mis à jour sur l'appareil.
  3. (Alternatif, pas de flash) Copiez <source.root_path>/Linux_for_Tegra/rootfs/etc/nvpower/nvfancontrol/<conf> directement vers /etc/nvpower/nvfancontrol/<conf> de la cible en exécution, puis sudo systemctl restart nvfancontrol.service (ou redémarrage).

Éditer <source.root_path>/... sans committer — ou éditer <bsp_image.root_path>/... directement — ne fait rien pour /jetson-promote-image et est silencieusement perdu au prochain /jetson-init-image re-extract.

Skills similaires

llm-obs-eval-bootstrap
datadog-labs / agent-skills

Générer une suite d'évaluateurs prêts à l'emploi à partir de traces LLM en production.

134
agent-observability-eval-bootstrap
datadog-labs / agent-skills

Analyser des traces LLM de production pour générer et publier une suite d'évaluateurs Datadog.

134
jetson-init-target
nvidia / skills

Créer et initialiser un profil YAML de plateforme cible pour agent BSP Jetson.

1 686
jetson-customize-nvpmodel
nvidia / skills

Modifier les profils de puissance nvpmodel d'un Jetson dans l'overlay BSP source.

1 686
jetson-flash-image
nvidia / skills

Flasher une image BSP Jetson sur un DUT en mode RCM via les outils NVIDIA.

1 686