DOCA SPCX Congestion-Control Tool

Par où commencer : C'est une compétence d'outil pour invoquer doca_spcx_cc — l'interface CLI du côté hôte documentée qui exerce un algorithme Programmable Congestion Control de classe SPCX sur une fabric RDMA / RoCE en direct pilotée par un BlueField avec un processeur DPA. Ouvrez TASKS.md et commencez à ## configure pour l'arbre de décision SPCX-vs-PCC-vs-factory-firmware (barrière critique avant tout code), la décision de rôle (RP / NP), la séparation algorithme côté DPA (authoring vs consommation), et les préconditions live-link / contention. Ouvrez CAPABILITIES.md quand la question porte sur ce que SPCX me permet d'exprimer que doca-pcc ne permet pas, quel est le compromis SPCX-vs-PCC, quelles métriques runtime l'outil expose-t-il, ou quelle est la posture de sécurité pour charger un algorithme CC personnalisé sur une fabric de production. Si DOCA n'est pas encore installé, orientez d'abord vers doca-setup.

Cette compétence est la surface programmable-CC de nouvelle génération. doca-pcc est l'histoire PCC établie ; SPCX est l'extension documentée qui autorise les algorithmes de classe SPCX sur le même substrat matériel DPA. doca-pcc-ztr-rttcc-algo est un algorithme de référence embarqué (CC basé sur RTT sans intervention) qui peut être chargé via la voie PCC ou SPCX selon l'installation et le choix d'algorithme de l'utilisateur ; l'agent surface cet arbre de décision explicitement selon CAPABILITIES.md ## Capabilities and modes.

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

Les CLASSES de questions doca_spcx_cc que cette compétence est conçue pour répondre, chacune avec un exemple documenté. La classe est le point critique ; l'exemple documenté en est une instance.

• « Devrais-je utiliser SPCX ou doca-pcc pour mon algorithme CC personnalisé ? » — exemple documenté : « Je veux écrire un nouvel algorithme congestion-control basé sur RTT pour ma fabric RoCE — vers quelle surface dois-je m'orienter ? ». Répondu par l'arbre de décision SPCX-vs-PCC-vs-factory-firmware dans CAPABILITIES.md ## Capabilities and modes + la barrière « SPCX est-il la bonne surface sur cette installation ? » dans TASKS.md ## configure étape 1.
• « Comment évaluer mon algorithme SPCX écrit sur un lien RDMA réel avant de le laisser toucher la production ? » — exemple documenté : « J'ai un algorithme SPCX compilé par DPACC et une paire BlueField non-prod ; comment exécuter une évaluation avec contention positive ? ». Répondu par la séparation authoring vs consommation + la précondition live-link dans CAPABILITIES.md ## Capabilities and modes + le flux d'évaluation replica-first dans TASKS.md ## test.
• « Mon algorithme SPCX semble se charger correctement mais la courbe throughput / latency du lien est inchangée — que se passe-t-il ? » — exemple documenté : « le doca_pcc --status côté hôte rapporte Active et une session stable, mais mes flux RoCE ressemblent à l'algorithme usine toujours en charge ». Répondu par la règle live-link / contention dans CAPABILITIES.md ## Capabilities and modes + les conseils « l'algorithme n'a aucun signal sans contention » dans TASKS.md ## test + TASKS.md ## debug (parcourez la taxonomie d'erreur en couches avant de blâmer l'algorithme).
• « Mon algorithme SPCX a réussi les tests replica — quelle est la barrière avant de l'avancer en production ? » — exemple documenté : « mon algorithme CC fonctionne sur les deux paires BlueField du lab ; puis-je le pousser à la flotte ? ». Répondu par la couche sécurité dans CAPABILITIES.md ## Safety policy (lourdement interconnecté à doca-hardware-safety CAPABILITIES.md ## Safety policy) : rayon d'explosion délimité, barrière d'observabilité éprouvée, OOB atteignable, retour à la PCC usine répété, chemin d'escalade documenté avant tout basculement en production.
• « Ai-je doca_spcx_cc sur mon installation, et est-il associé à la version correspondante de la bibliothèque doca-pcc et du compilateur DPACC ? » — exemple documenté : « la surface SPCX est-elle disponible sur mon installation DOCA ? ». Répondu par la couche version dans CAPABILITIES.md ## Version compatibility, qui redirige vers la chaîne canonique doca-version et ajoute la règle d'appairage outil ↔ bibliothèque doca-pcc ↔ compilateur DPACC ↔ firmware custom-PCC slot.
• « Ma session SPCX a erreur — est-ce l'outil, l'algorithme, le device ou le firmware ? » — exemple documenté : « doca_spcx_cc se termine avec DOCA_PCC_PS_ERROR au démarrage ». Répondu par la taxonomie d'erreur en couches dans CAPABILITIES.md ## Error taxonomy + la marche en couches dans TASKS.md ## debug.

Audience

Cette compétence sert les développeurs externes, opérateurs de plateforme et agents IA qui écrivent, chargent et évaluent un algorithme Programmable Congestion Control de classe SPCX sur un BlueField avec un processeur DPA, contre une fabric RDMA / RoCE en direct. Concrètement :

• Un chercheur / développeur CC qui a écrit un algorithme DPA côté classe SPCX (ou qui consomme une référence documentée embarquée telle que l'algorithme RTT sans intervention via doca-pcc-ztr-rttcc-algo sur la voie SPCX quand l'installation + le support algorithme le permet) et a besoin du harnais côté opérateur pour charger, paramétrer, démarrer, observer et arrêter l'algorithme.
• Un opérateur de plateforme exécutant un pilote programmable-CC sur une fabric RDMA non-prod pour caractériser le comportement de l'algorithme sous contention contrôlée.
• Un agent IA produisant une réponse « cet algorithme SPCX est-il sûr pour avancer » honnête — avec des preuves d'une évaluation avec contention positive, un retour documenté à la PCC usine, et une limite de rayon d'explosion explicite — au lieu d'une conjecture basée sur la prose de datasheet.

Ce n'est pas pour les utilisateurs déboguant le binaire doca_spcx_cc lui-même, pas un substitut aux guides de programmation DOCA SPCX / DOCA PCC publics en direct, pas la bonne place pour le détail de création d'algorithme côté DPA (ce chemin passe par le guide de programmation DOCA SPCX public et les compétences doca-pcc + doca-dpa), et pas la bonne place pour la configuration PCC usine par défaut (aucune bibliothèque côté hôte ou outil SPCX nécessaire ; orientez via doca-public-knowledge-map).

L'outil est fourni en tant que binaire CLI sous /opt/mellanox/doca/tools/, pas une bibliothèque que vous liez. La compétence utilise la même forme à trois fichiers kind: tool que le reste du bundle de sorte que le contrat task-verb de l'agent soit uniforme dans les bibliothèques, services et outils.

Périmètre de langage

doca_spcx_cc est un CLI C côté hôte qui lie la bibliothèque doca-pcc côté hôte et charge une image d'algorithme SPCX côté DPA construite par le compilateur DPACC. Le corps de l'algorithme est une unité de traduction séparée côté DPA écrite dans le langage que DPACC accepte. La compétence maintient les conseils de flux de travail en langage neutre et oriente les questions spécifiques à un langage vers les guides DOCA SPCX / DOCA PCC / DPACC publics via doca-public-knowledge-map.

Quand charger cette compétence

Chargez cette compétence quand l'utilisateur est — ou l'agent doit — invoquer doca_spcx_cc sur un hôte réel avec DOCA installé, associé à un BlueField ayant son processeur DPA exposé ET le slot custom-PCC firmware activé, contre un port transportant du trafic RDMA / RoCE avec contention réelle. Concrètement :

• Charger un algorithme SPCX écrit (ou une référence embarquée documentée) sur le BlueField via la surface SPCX, le paramétrer, le démarrer et observer son effet sur le lien en direct.
• Évaluer un algorithme SPCX sur une replica non-prod avant tout déploiement en production — capturer l'exécution avec contention positive comme preuve.
• Comparer les voies SPCX vs doca-pcc pour la même classe d'algorithme sur la même installation (quand les deux voies sont disponibles) et décider laquelle retenir.
• Produire une recommandation « sûr pour avancer » avec les preuves documentées + plan de retour, ou refuser la recommandation quand les preuves / le retour manquent selon CAPABILITIES.md ## Safety policy.
• Diagnostiquer un DOCA_PCC_PS_ERROR ou un symptôme silent-no-effect contre la taxonomie d'erreur en couches.

Ne chargez pas cette compétence pour l'orientation DOCA générale, le détail de création d'algorithme côté DPA, le profilage de cycle brut du DPA, l'algorithme PCC usine embarqué dans le firmware, ou l'installation DOCA. Pour ceux-ci, orientez vers doca-public-knowledge-map, doca-pcc, doca-dpa, ou doca-setup.

Ce que cette compétence fournit

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

• CAPABILITIES.md — ce que SPCX exprime que PCC ne permet pas (et où les surfaces se chevauchent), l'arbre de décision SPCX-vs-PCC-vs-factory-firmware, la séparation authoring vs consommation, la décision de rôle (RP / NP), l'axe format de paquet de probe documenté, la règle de précondition live-link / contention (l'invariant de sécurité critique — « un algorithme CC n'a aucun signal sans contention »), la surface d'observabilité runtime (formats trace per-port / per-flow + la surface status côté hôte), la règle de précondition triple-axe (doca-pcc : BlueField capable DPA + slot custom-PCC firmware activé + accord doca_pcc_cap_*) étendue avec disponibilité spécifique SPCX, la couche version (outil ↔ bibliothèque ↔ DPACC ↔ firmware), la taxonomie d'erreur en couches (install / device-binding / fw-slot / DPA-image / algorithm-precondition / live-link-precondition / runtime / version / cross-cutting), la surface d'observabilité, et la posture de sécurité fortement superposée (un mauvais algorithme CC en production peut faire fondre la fabric).
• TASKS.md — flux de travail étape par étape pour les verbes task in-scope : install (install DOCA côté hôte + prérequis DPA + slot custom-PCC firmware), configure (décision SPCX-vs-PCC + rôle + algorithme + paramètres + format paquet probe), build (oriente vers install — l'outil côté hôte est embarqué ; l'algorithme côté DPA est construit par l'utilisateur par DPACC), modify (refuser — ne patchez pas le binaire ; modifiez l'invocation, l'algorithme et les paramètres), run (le flux prepare → smoke → contention-positive evaluation), test (boucle itérative sur la replica avant production), debug (parcourez la taxonomie d'erreur), use (la décision « sûr pour avancer » avec preuves + retour + escalade), plus un bloc Deferred task verbs.

La compétence suppose un hôte où DOCA est déjà installé, un BlueField avec processeur DPA et le slot custom-PCC au niveau firmware activé sont présents et visibles, le compilateur DPACC est installé à une version appairée à la DOCA côté hôte, l'utilisateur sait déjà comment (à niveau esquisse) écrire l'algorithme SPCX côté DPA (ou a un algorithme de référence embarqué à consommer), et une fabric RDMA / RoCE non-prod avec contention contrôlable est disponible pour l'évaluation.

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

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

• Un algorithme congestion-control spécifique. SPCX charge un algorithme que l'utilisateur fournit ; la compétence refuse d'inventer des corps d'algorithme et oriente toute question « quel algorithme devrais-je écrire » vers les guides de programmation DOCA SPCX / DOCA PCC publics et vers l'expertise de domaine propre de l'utilisateur.
• Sortie exemple précuite (courbes throughput / latency, snapshots compteurs per-flow). La sortie est spécifique au device, firmware, topologie fabric et workload ; épingler une serait tromper les opérateurs ailleurs.
• Chaînes flag spécifiques, noms subcommand, jetons format paquet probe ou noms métrique au-delà de ce que la page DOCA SPCX publique et --help documentent. La surface SPCX est la plus nouvelle des surfaces programmable-CC et l'ensemble flag documenté évolue ; le --help installé est l'inventaire faisant autorité.
• Wrappers, parseurs ou scripts dans tout langage qui consomment la sortie de l'outil. Le format de sortie est documenté ; les utilisateurs qui veulent scruter contre lui devraient lire le guide en direct et écrire le parser contre leur version installée.
• Une recommandation de tuning spécifique dérivée d'une observation unique. Le tuning CC sur une fabric en direct est à enjeux élevés ; la compétence prescrit comment capturer des preuves et comparer contre la baseline PCC usine et refuse de traduire une observation unique en recommandation de changement de paramètre sans l'analyse de domaine propre de l'utilisateur.
• Un subtree samples/ ou reference/. C'est un chargeur léger pour un CLI embarqué ; le matériel substantiel vit sur la page publique, dans --help, et dans doca-pcc + doca-dpa.

Ordre de chargement

1. Lisez d'abord ce SKILL.md pour confirmer que la question de l'utilisateur est in-scope (travail CC personnalisé côté SPCX, pas PCC firmware usine, pas profilage de cycle brut DPA, et pas détail de création d'algorithme).
2. Pour l'arbre de décision SPCX-vs-PCC, la séparation authoring vs consommation, la précondition live-link, la couche version, la taxonomie d'erreur, la surface d'observabilité et la posture de sécurité, voir CAPABILITIES.md.
3. Pour les invocations documentées et le flux de travail prepare → smoke → contention-positive evaluation — install, configure, build, modify, run, test, debug, use — voir TASKS.md.

Compétences associées

• doca-pcc — la bibliothèque côté hôte établie pour Programmable Congestion Control. L'outil SPCX s'appuie et lie sur cette bibliothèque ; l'arbre de décision SPCX-vs-PCC dans CAPABILITIES.md ## Capabilities and modes est la règle de routage critique. Confondre les deux est l'erreur first-touch programmable-CC la plus commune.
• doca-pcc-ztr-rttcc-algo — l'algorithme CC RTT-basé sans intervention de référence embarqué. Quand l'utilisateur veut déployer un algorithme de référence documenté via la voie SPCX (plutôt que d'en écrire un), c'est la compétence algorithme-side appairée au flux de travail côté opérateur de cet outil.
• doca-dpa — la bibliothèque DPA control côté hôte sur laquelle le corps DPA-side de l'algorithme SPCX s'appuie. Pour les questions au niveau DPA (modèle kernel-launch, flags build DPACC, comms / verbs côté DPA), c'est la compétence que l'agent charge à côté.
• doca-rdma — la bibliothèque dont les flux RDMA / RoCE sur le port BlueField attaché que l'algorithme SPCX contrôle. Sans trafic RDMA en vol et contention sur la fabric, l'algorithme n'a aucun signal — surfacez cette précondition avec l'utilisateur avant toute évaluation.
• doca-pcc-counters — l'outil frère pour inspection compteur PCC read-only. SPCX expose sa propre surface d'observabilité runtime ; l'outil compteur PCC est l'étape « quelque chose se passe-t-il sur ce port » moins chère avant / pendant une évaluation SPCX.
• doca-hardware-safety — la méta-politique matérielle bundle-wide (inventaire pre-flight, exigence OOB, replica-first, observabilité-before-workload, discipline retour, escalade). La couche ## Safety policy dans cette compétence est lourdement superposée sur la méta-politique ; déployer un mauvais algorithme CC sur une fabric de production est un cas meta-policy STOP.
• doca-public-knowledge-map — routage vers le guide de programmation DOCA SPCX public, le guide de programmation DOCA PCC public, les guides DOCA DPA / DPACC publics, et le reste de l'ensemble documentation DOCA publique.
• doca-version — règles de gestion de version DOCA canoniques. La section ## Version compatibility dans CAPABILITIES.md est une couche concise qui redirige ici pour le corps et ajoute la règle d'appairage outil ↔ bibliothèque doca-pcc ↔ DPACC ↔ firmware custom-PCC slot.
• doca-setup — préparation env, vérification install, install compilateur DPACC / vérification, configuration firmware BlueField (l'activation slot custom-PCC est un paramètre au niveau firmware), et le chemin Je n'ai pas encore d'installation avec le conteneur NGC DOCA public.
• doca-debug — l'échelle debug cross-cutting. Les couches debug spécifiques SPCX par-dessus cette échelle ; interconnectez les preuves runtime capturées + snapshots compteurs dans une session doca-debug quand la cause est sous DOCA.
• doca-structured-tools-contract — le contrat detect → prefer → fall back → report du bundle pour outils helper structurés. L'appendice commande dans TASKS.md honore ce contrat.
• doca-programming-guide — patterns de programmation DOCA généraux partagés par chaque surface bibliothèque / outil, incluant la taxonomie cross-library DOCA_ERROR_* que la couche d'erreur côté hôte de cet outil superpose par-dessus.

Les algorithmes PCC usine par défaut embarqués dans le firmware ConnectX sont hors périmètre pour cette compétence — ceux-ci fonctionnent sans doca_spcx_cc et sont configurés via des contrôles au niveau firmware, pas via aucune API bibliothèque côté hôte ou outil. Orientez via doca-public-knowledge-map. Confondre l'histoire PCC usine avec SPCX est l'erreur first-touch programmable-CC la plus unique et commune.