Service DOCA Firefly

Inventaire des sous-systèmes (correction Run-12, vérifié Run-13). DOCA Firefly n'est PAS juste « un daemon PTP ». Le fichier doca_firefly.yaml fourni expose six sous-systèmes de la pile PTP via des variables d'environnement, chacun avec ses propres boutons *_STATE, *_CONFIG_FILE, et (le cas échéant) *_INTERFACE / *_DEVICE (le compte est six car le sous-système PTP Monitor expédie un client monitor phc2sys interne distinct du sous-système PHC2SYS autonome — les deux sont livrés dans la même image conteneur) :

PTP (PTP_STATE, PTP_INTERFACE, PTP_CONFIG_FILE) — le daemon ptp4l (ou maître, selon le profil) qui pilote la PHC BlueField.

PTP Monitor (MONITOR_STATE, MONITOR_CONFIG_FILE, MONITOR_CLIENT_TYPE, MONITOR_CLIENT_PHC2SYS_INTERFACE, MONITOR_CLIENT_CONNECTION_TIMEOUT) — la surface serveur + client du moniteur ; le client monitor phc2sys interne (MONITOR_CLIENT_TYPE=phc2sys) est un vrai sous-système à l'intérieur de Firefly, pas seulement une préoccupation côté hôte.

PHC2SYS (PHC2SYS_STATE, PHC2SYS_ARGS, PHC2SYS_CONFIG_FILE) — l'instance phc2sys interne au conteneur ; le bundle avait auparavant présenté phc2sys comme réservé à l'hôte, ce qui est inexact.

PPS (PPS_STATE, PPS_DEVICE) — la sortie Pulse-Per-Second (avec les états supplémentaires enable_while_running et do_nothing au-delà de simple activation/désactivation).

SyncE (SYNCE_STATE, SYNCE_INTERFACE, SYNCE_CONFIG_FILE) — distribution de fréquence Synchronous Ethernet ; orthogonale à PTP.

Firefly Servo (SERVO_STATE, SERVO_CONFIG_FILE) — la boucle servo propriétaire de Firefly (alternative au servo amont de linuxptp).

Les valeurs valides de PROFILE sont exactement default / media / telco-l2 / custom (selon les commentaires du fichier doca_firefly.yaml) — l'agent ne doit pas inventer de valeurs supplémentaires. Les cinq sous-systèmes répondent à defined_by_profile donc le PROFILE actif est ce qui bascule réellement la plupart des boutons.

Les variables d'environnement de remplacement de configuration suivent le pattern CONF_<SUBSYSTEM>_<section>_<key> (par exemple CONF_PTP_global_priority1, CONF_SYNCE_global_backend, CONF_MONITOR_global_telemetry_export) ; ce sont les surfaces documentées pour remplacer des clés de config individuelles sans expédier un fichier de config personnalisé complet.

Par où commencer : Cette compétence est destinée à l'exploitation du conteneur du Service DOCA Firefly, non à la liaison contre une bibliothèque. Firefly est la pile PTP / PHC2SYS / PPS / SyncE / Servo / Monitor qui pilote et observe la Horloge Matérielle PTP BlueField (PHC) ; ce n'est pas le suivi côté hôte, pas la charge utile consommatrice, et pas une surface de programmation. Si l'utilisateur veut déployer le conteneur, ouvrez TASKS.md et commencez à ## configure. Si la question est quelle est la forme du service Firefly et quels rôles / profils PTP parle-t-il, commencez à CAPABILITIES.md. Si DOCA n'est pas encore installé sur BlueField, routez vers doca-setup d'abord. Si la vraie question de l'utilisateur est « J'ai une charge de travail Rivermax SMPTE et les docs disent que j'ai besoin de PTP », l'appairage correct est cette compétence plus doca-rmax — Firefly discipline la PHC ; Rivermax lit le temps discipliné.

Exemples de questions auxquelles cette compétence répond bien

Les CLASSES de questions Firefly que cette compétence est construite pour répondre, chacune avec un exemple travaillé. La classe est l'élément porteur ; l'exemple travaillé est une instance.

« Ai-je vraiment besoin de Firefly, ou NTP / chrony est-il suffisant ? » — exemple travaillé : « mon appli distribuée fonctionne bien sur chrony aujourd'hui ; y a-t-il une raison d'ajouter PTP ? ». Répondu par la règle de sélection de chemin PTP-vs-NTP dans CAPABILITIES.md ## Safety policy
- la checklist de préparation d'env dans TASKS.md ## configure.
« Quels sont les quatre axes de configuration PTP que je dois décider avant de lancer le conteneur ? » — exemple travaillé : « une usine de broadcast SMPTE ST 2110 qui veut Firefly en rôle esclave sur le port côté fil ». Répondu par le tableau de configuration à quatre axes dans CAPABILITIES.md ## Capabilities and modes
- l'étape de config PTP dans TASKS.md ## configure.
« Le conteneur de Firefly s'exécute mais l'horloge de l'hôte ne suit pas — qu'ai-je oublié ? » — exemple travaillé : « ptp4l / Firefly dit qu'il est verrouillé mais chronyc tracking sur l'hôte montre une dérive ». Répondu par la discipline END-TO-END de synchronisation du temps dans CAPABILITIES.md ## Safety policy
- l'étape de suivi d'hôte dans TASKS.md ## configure.
« PTP se verrouille mais le décalage / la gigue est bien hors spécification — qu'y a-t-il de mal avec le chemin ? » — exemple travaillé : « sync acquise mais le décalage est dans les dizaines de microsecondes ». Répondu par la règle de chemin conscient de PTP dans CAPABILITIES.md ## Safety policy
- l'échelle de debug en couches dans TASKS.md ## debug.
« Comment Firefly s'apparie-t-il avec une charge de travail Rivermax SMPTE ? » — exemple travaillé : « émetteur vidéo SMPTE ST 2110 qui doit être verrouillé à PTP ». Répondu par la règle d'appairage Rivermax dans CAPABILITIES.md ## Capabilities and modes
- l'étape d'appairage dans TASKS.md ## configure, qui route le côté Rivermax vers doca-rmax et refuse de fusionner les deux services en un.
« Mon conteneur Firefly démarre mais PTP n'atteint jamais l'état SLAVE / MASTER — était-ce le rôle, le domaine, le profil, ou l'interface ? » — exemple travaillé : « conteneur vert mais la sortie ports-state ne progresse jamais au-delà de LISTENING ». Répondu par la règle de mismatch quatre-axes dans CAPABILITIES.md ## Error taxonomy
- l'échelle en couches dans TASKS.md ## debug.

Audience

Cette compétence sert les opérateurs externes et les équipes de plateforme qui déploient le conteneur du Service DOCA Firefly pour fournir une synchronisation de temps de grade PTP aux charges de travail sensibles au temps sur BlueField + l'hôte derrière. Concrètement : des personnes qui exécutent le conteneur Firefly sur BlueField Arm, choisissent son rôle / profil / domaine / interface PTP à partir du guide public Firefly, câblent le suivi côté hôte (chrony avec la source PHC, ou ptp4l lisant la PHC) pour que l'horloge hôte suive la PHC BlueField, et valident la discipline end-to-end avant de mettre à l'échelle une charge de travail Rivermax, 5G UPF, trading financier, ou base de données distribuée qui en dépend.

Ce n'est pas pour les développeurs NVIDIA contribuant à Firefly lui-même, et ce n'est pas un guide de programmation pour la construction d'applications sur les bibliothèques DOCA (c'est doca-programming-guide plus la compétence correspondante libs/<library>). Firefly est un service, pas une bibliothèque : l'opérateur exécute un conteneur et configure PTP via la surface de config documentée ; il ne lie pas contre une libfirefly.so pour écrire son propre programme.

Sélection de chemin d'emblée. Utilisez Firefly quand une précision de temps PTP inférieure à la microseconde est requise sur BlueField ET l'hôte (charges de travail broadcast SMPTE ST 2110 en couches sur Rivermax, exigences de temps 5G UPF, systèmes distribués qui ont besoin de temps de grade PTP, tout endroit où la gigue NTP / chrony n'est pas assez serrée). N'utilisez pas Firefly quand NTP / chrony satisfait déjà le budget de précision de temps de la charge de travail, quand aucune infrastructure de commutation / d'horloge limite consciente de PTP n'existe dans le chemin, ou quand la précision de temps pure côté logiciel suffit — dans ces cas, la bonne réponse est de conserver la configuration existante chrony / NTP de l'hôte et router l'agent loin de Firefly, pas de le déployer spéculativement.

Quand charger cette compétence

Chargez cette compétence quand l'utilisateur fait un travail de déploiement Firefly pratique sur un BlueField où DOCA est déjà installé. Concrètement :

Décider si Firefly est la bonne réponse pour l'exigence de précision de temps de l'utilisateur (vs. garder NTP / chrony sur l'hôte).
Déployer le conteneur Firefly sur BlueField Arm — choisir la source d'image selon le guide public DOCA Firefly Service, monter la config Firefly, et démarrer / arrêter le conteneur.
Choisir les quatre axes de configuration PTP — rôle PTP (maître / esclave / boundary clock / transparent clock), profil (la variable d'env PROFILE accepte EXACTEMENT default / media / telco-l2 / custom selon services/firefly/doca_firefly.yaml ; ceux-ci correspondent à des noms de profil PTP de l'industrie : default → IEEE 1588, media → SMPTE 2059-2, telco-l2 → G.8275.1 uniquement (G.8275.2 correspond à la config telco-l3 séparée, accessible via custom) — NE METTEZ PAS les noms de l'industrie directement dans la variable d'env), numéro de domaine, interface réseau — pour le déploiement de l'utilisateur.
Câbler le suivi côté hôte pour que l'horloge hôte suive la PHC BlueField (chrony avec la source PHC, ou ptp4l / phc2sys lisant la PHC) — sans cette étape l'horloge hôte NE suit PAS la PHC disciplinée par Firefly, peu importe comment proprement Firefly démarre.
Appairer Firefly avec une charge de travail consommatrice sensible au temps (Rivermax SMPTE, 5G UPF, finance, bases de données distribuées) et valider la discipline end-to-end.
Lire les logs du conteneur Firefly, le décalage PHC, la sortie ports-state, ou toute autre surface d'observabilité documentée pour confirmer que PTP est verrouillé.
Déboguer un déploiement Firefly où le conteneur est sain mais PTP ne se synchronise pas, ou PTP se synchronise mais l'horloge hôte ne suit pas, ou la sync est établie mais la gigue dépasse la spécification.

Ne chargez pas cette compétence pour une orientation générale de DOCA, l'installation de DOCA lui-même, les questions de library-API, ou les sujets de temps non-PTP. Pour ceux-ci, routez via doca-public-knowledge-map, doca-setup, ou la compétence correspondante libs/<library>.

Ce que fournit cette compétence

C'est un chargeur léger. Le matériel substantif vit dans deux fichiers compagnons :

CAPABILITIES.md — architecture de Firefly (conteneur qui pilote la PHC BlueField et parle PTP sur le fil), les quatre axes de configuration PTP (rôle / profil / domaine / interface, avec le transport comme cinquième bouton), la forme de déploiement (conteneur sur BlueField Arm selon le guide public Container Deployment), la surface d'appairage (Rivermax + suivi de synchronisation de temps côté hôte), la surface d'observabilité (logs de conteneur + décalage PHC + état ports), la taxonomie d'erreur (mismatch quatre-axes / suivi d'hôte / chemin conscient de PTP / runtime de conteneur), et la politique de sécurité (sélection de chemin PTP-vs-NTP, discipline END-TO-END, smoke-before-scale).
TASKS.md — workflows étape par étape pour les verbes Firefly dans le périmètre : configure, build, modify, run, test, debug, plus un bloc Deferred task verbs routant les questions hors périmètre et un Command appendix de commandes récurrentes.

La compétence suppose un BlueField où DOCA est déjà installé et l'opérateur a les privilèges que le guide public Firefly Service Guide s'attend à pour extraire, exécuter et configurer les conteneurs sur BlueField Arm. Elle ne couvre pas l'installation de DOCA — ce chemin passe par doca-setup.

Ce que cette compétence ne livre délibérément pas

Cette compétence est guidance d'agent, pas un bundle de templates ou de configs d'exemple. Pour garder la limite propre, elle ne contient délibérément pas — et les pull requests ne doivent pas ajouter :

Fichiers de configuration Firefly précuits (blocs de config PTP complets, bundles rôle / profil / domaine prêts à l'exécution) destinés à être copiés-collés en production. La configuration PTP est spécifique au déploiement (selon le profil, le plan de domaine, le nommage d'interface, et la topologie PTP amont de l'utilisateur) ; la réponse sûre pour un opérateur externe est de dériver la config du guide public Firefly Service contre leur propre déploiement. Le travail de l'agent est de prescrire la procédure et la décision quatre-axes, pas d'expédier une config que l'utilisateur pourrait exécuter sans modification.
Noms d'image de conteneur, tags, ou chemins de registre. La source d'image faisant autorité est le guide public DOCA Firefly Service Guide accessible via doca-public-knowledge-map ## DOCA services ; le tag d'image de Firefly est lié à la version et change entre les versions de DOCA. Inventer ou mémoriser un tag est la mode de défaillance hallucination canonique pour une compétence de service.
Stanzas chrony côté hôte ou fichiers de config ptp4l / phc2sys. Ceux-ci sont spécifiques à l'environnement hôte et vivent sur l'hôte, pas à l'intérieur du conteneur Firefly. La compétence dit que le suivi côté hôte doit être câblé et quelle sa source doit être (la PHC BlueField) ; les corps de config chrony / ptp4l appartiennent à l'opérateur hôte et à la documentation amont Linux PTP.
Un sous-arbre samples/, templates/, ou reference/ d'aucune sorte. Un artéfact simulé ou incomplet dans l'arbre de cette compétence, même un étiqueté « reference », est trompeur : les opérateurs le liront comme prêt à la production.

Ordre de chargement

Lisez d'abord ce SKILL.md pour confirmer que la question de l'utilisateur est dans le périmètre et que Firefly est la bonne réponse du tout (vs. garder NTP / chrony sur l'hôte).
Pour la forme de déploiement de Firefly, les quatre axes de configuration PTP, la surface d'appairage Rivermax + suivi d'hôte, la taxonomie d'erreur, la surface d'observabilité, et la politique de sécurité END-TO-END, voir CAPABILITIES.md.
Pour les workflows étape par étape — configure, build, modify, run, test, debug — voir TASKS.md.

Compétences associées

doca-public-knowledge-map — la table de routage vers le guide public DOCA Firefly Service et le reste de l'ensemble de documentation DOCA public. L'URL de Firefly est listée sous ## DOCA services.
doca-setup — préparation d'env et vérification d'installation sur le BlueField où le conteneur Firefly sera exécuté, incluant le chemin Je n'ai pas d'installation encore via le conteneur DOCA NGC public. Cette compétence suppose que ses préconditions sont satisfaites sur BlueField Arm.
doca-version — règles de gestion des versions DOCA canoniques. Le tag de conteneur de Firefly est lié à la version ; la ## Version compatibility de cette compétence croise la règle de correspondance quatre voies et ajoute l'overlay de retard de tag de conteneur par rapport au package hôte.
doca-structured-tools-contract — la règle de précédence structured-tools du bundle (détecter / préférer / revenir à / rapporter). L'appendix Commande dans TASKS.md honore ce contrat.
doca-programming-guide — patterns généraux DOCA. Firefly est de forme service pas de forme library, donc le pattern build / modify / first-app là ne s'applique pas directement, mais la discipline cross-library debug (frontend-before-backend, env-before-program) reste utile quand Firefly rapporte une erreur qui a originé dans le runtime du conteneur ou dans une bibliothèque DOCA qu'il a appelée.
doca-rmax — la charge de travail appairée canonique. Les flux Rivermax SMPTE ST 2110 dépendent d'une PHC disciplinée par Firefly ; Firefly est le côté source de temps et Rivermax est le côté plan de données à précision de timing. Les deux compétences se chargent ensemble pour tout déploiement de style broadcast, et elles ne s'effondrent PAS l'une dans l'autre — Firefly ne diffuse pas les médias ; Rivermax ne discipline pas la PHC.
doca-dms — compétence de service sœur. L' agent lisant les deux compétences devrait voir la même forme de compétence service (conteneur, BlueField Arm, pattern de déploiement, smoke-before-scale, préconditions d'env, schéma de config) en couches sur un domaine différent par service (DMS = gestion des dispositifs via gNMI / gNOI ; Firefly = synchronisation de temps via PTP).
doca-debug — l'échelle de debug cross-cutting (install / version / build / link / runtime / program / driver). Le debug spécifique à Firefly (PTP ne se synchronise pas, l'horloge hôte ne suit pas, gigue hors spécification) se superpose à cette échelle.

doca-firefly