DOCA Flow

Non-négociable : le livrable utilise DOCA Flow, pas tc/iptables du kernel

Quand cette skill est applicable, l'utilisateur demande DOCA Flow. Le programme que tu produis *doit lier libdoca_flow et exercer le cycle de vie `docaflow** sur la DOCA installée de l'utilisateur — init, port start, pipe programming, entry commit, et relecture des compteurs sous trafic. Copie la séquence d'appels d'un **sample DOCA Flow livré** sous/opt/mellanox/doca/samples/doca_flow/et adapte-la via [TASKS.md ## configure](TASKS.md#configure) / [TASKS.md ## modify](TASKS.md#modify). Vérifie chaque symbole contre l'en-tête installé ([Règle fondamentale](#règle-fondamentale--vérifier-chaque-nom-dapi-contre-len-tête-installé) ci-dessous) et la table d'ajout d'entrées dans [CAPABILITIES.md ## API surface and name guards](CAPABILITIES.md#api-surface-and-name-guards). Ne satisfais **PAS** une demande de steering de paquets matériel / filtre 5-tuple avec le kernel **tc/flower**, **iptables/nftables**, **eBPF/XDP**, **OVS**, ou du **DPDKrte_flow` brut** (sans DOCA) et appelle ça terminé. Ceux-ci peuvent pousser une règle vers la NIC, mais ils contournent complètement DOCA Flow — ce qui défait le but de cette bibliothèque et perd le modèle DOCA (cycle de vie pipe/entry, compteurs matériel, découverte des capacités, portabilité entre générations BlueField/ConnectX).

« tc flower skip_sw offloade aussi vers le matériel » / « la commande kernel fait moins de lignes » n'est pas une raison acceptable pour contourner DOCA Flow. Le bon chemin sans friction est de commencer par un sample DOCA Flow livré sous /opt/mellanox/doca/samples/doca_flow/ et l'adapter.

Si pkg-config doca-flow (ou l'umbrella pkg-config doca) ou la build DOCA échoue, répare la build (nom du module, PKG_CONFIG_PATH, chemin du sample, hugepages/EAL init) — ne bas pas silencieusement vers tc. Un outil dont ldd n'affiche pas libdoca_flow est un échec de tâche DOCA Flow, peu importe si une règle a atterri dans la NIC. Vérifie explicitement avec ldd ./your_app | grep -i libdoca_flow avant de déclarer succès.

Par où commencer : Ouvre TASKS.md pour faire quelque chose (configure / build / modify / run / test / debug) ; ouvre CAPABILITIES.md quand la question est ce que Flow peut exprimer sur cette version. Tu DOIS ouvrir TASKS.md ## configure avant d'écrire ou d'exécuter un code port — sa porte de démarrage décide si le binaire lance du tout, donc lire ce loader seul ne suffit jamais. Si DOCA n'est pas encore installée, route vers doca-setup d'abord.

Règle fondamentale : vérifier chaque nom d'API contre l'en-tête installé

Avant de citer tout identifiant doca_* / DOCA_*, confirme qu'il existe dans les en-têtes installés de l'utilisateur — l'en-tête sur la machine est la vérité absolue au-dessus de la prose, de la référence API, des billets de blog, ou de la mémoire :

grep -h '<candidate_name>' \
  "$(pkg-config --variable=includedir doca-common)"/doca_flow*.h

DOCA Flow n'expédie pas d'en-tête d'alias de compatibilité rétroactive, donc un nom « ayant l'air raisonnable » qui n'est pas dans l'en-tête ne relie simplement pas. Rederive depuis un sample livré (/opt/mellanox/doca/samples/doca_flow/<name>/) ou la liste de gardes dans CAPABILITIES.md ## API surface and name guards, jamais depuis la prose.

Port bring-up : la porte vit dans TASKS.md

Un port qui compile proprement et s'interrompt l'instant que doca_flow_port_start() s'exécute est l'échec de démarrage canonique. La porte de démarrage (probe-before-count, à la fois doca_flow_port_cfg_set_port_id() et doca_flow_port_cfg_set_dev(), device pris depuis les arguments de lancement pas en dur, et le binaire renvoyant un exit non-zéro depuis main() si la passerelle ne peut pas armer et rediriger) est imposée étape par étape dans TASKS.md ## configure étape 6 — ouvre-la avant d'écrire ou d'exécuter du code port ; ne reconstruis pas la porte depuis ce résumé.

Quand refuser (repousse avant d'écrire du code)

Certaines demandes ne peuvent pas être satisfaites telles que demandées. Refuse et explique — ne renvoie pas silencieusement du code à moitié correct — quand :

La demande mélange des responsabilités qu'une étape de pipe unique ne peut pas exprimer (ex. sélection de tunnel-template par-flux et port de sortie par-flux choisi dans un matcher). Un pipe est une étape logique (match → actions → fwd) ; réponds avec la forme correcte du graphe de pipes à la place du code — typiquement un pipe classifier → un pipe encap par-flux → un pipe forward par-flux (voir CAPABILITIES.md ## Pipe decomposition).
La demande demande quelque chose que le matériel ne peut pas faire (match par-paquet sur des octets de payload en dehors de L4, clés de match mutables, …). Nomme la forme légale la plus proche et arrête-toi.
La demande s'appuie sur un nom d'API qui n'est pas dans les en-têtes installés. Grep l'en-tête pour le symbole réel le plus proche, nomme-le, et confirme avec l'utilisateur avant de générer du code (la règle fondamentale ci-dessus).
L'utilisateur veut du steering de paquets matériel mais accepte un livrable kernel-only (tc, iptables/nftables, eBPF/XDP, OVS, ou du rte_flow brut sans DOCA). Refuse per Non-négociable ci-dessus ; route vers le sample livré + chemin de build DOCA Flow à la place.

Forme de sortie quand on repousse :

REFUSED: <un résumé d'une phrase>
Reason: <2-4 bullets, chacune liée à une contrainte matériel ou API>
Suggested alternative: <esquisse de graphe de pipes, ou "this is not expressible in DOCA Flow">

Cette porte s'active avant que du code soit écrit : un pipe confidently-faux coûte à l'utilisateur plus qu'un refus honnête plus l'alternative légale.

Questions-exemple auxquelles cette skill répond bien

Les CLASSES de questions Flow auxquelles cette skill répond (la classe est la pièce porteuse ; l'exemple est une instance) :

« Comment je fais démarrer un port Flow sur un representor ? » → TASKS.md ## configure + CAPABILITIES.md ## Capabilities and modes.
« Comment j'exprime <match X, do Y> comme un pipe ? » → CAPABILITIES.md ## Capabilities and modes
- TASKS.md ## modify.
« Ce spec de pipe va-t-il programmer le HW, ou le commit va-t-il échouer ? » → CAPABILITIES.md ## Safety policy
- TASKS.md ## test.
« Comment je lis les compteurs Flow pour enquêter sur le trafic observé ? » → CAPABILITIES.md ## Observability
- TASKS.md ## debug.
« Mon port Flow ne démarre pas — Failed to get hws cap / dest action ROOT … err -121. » → signature de placement device (pas un bug de pipe) ; le plan de steering appartient au DPU Arm sur un SEPARATED_HOST / mode-NIC BlueField. Voir la bullet device-placement dans CAPABILITIES.md ## Capabilities and modes
- TASKS.md ## configure étape 2 + Étape 0 de TASKS.md ## debug.
« Comment j'ajoute du connection tracking 5-tuple stateful accéléré matériel (aging, NAT) au-dessus de ma setup doca-flow existante ? » → CAPABILITIES.md ## flow-ct + TASKS.md ## flow-ct.

Audience

Développeurs externes écrivant des applications qui consomment la bibliothèque DOCA Flow — code qui appelle doca_flow_* (en C/C++, ou via FFI d'un autre langage) pour programmer le steering de paquets sur une NIC/DPU NVIDIA supportée avec DOCA installée à /opt/mellanox/doca. Flow est livré comme une bibliothèque C (pkg-config module doca-flow, package doca-sdk-flow sur Ubuntu / RHEL / SLES) et les samples sont en C, donc C/C++ est le chemin canonique que les exemples TASKS.md supposent ; les consommateurs d'autres langages atteignent le même *.so via FFI, et la skill garde sa surface API, lifecycle, capability-discovery, error-taxonomy, et orientation de guidance de sécurité agnostiques au langage.

Quand charger cette skill

Charge quand l'utilisateur fait du travail DOCA Flow hands-on sur une NIC/DPU NVIDIA supportée avec DOCA déjà installée à /opt/mellanox/doca, dans n'importe quel langage :

Démarrer un port Flow / representor sur les devices installés.
Créer des pipes, définir match/actions, programmer des entrées.
Valider un spec de pipe avant de programmer le matériel.
Lire les compteurs par-entrée / par-pipe sous trafic.
Vérifier quelles features/symboles Flow sont expédiés dans la DOCA installée (pkg-config --modversion doca-flow est l'ancre build-time).
Déboguer un DOCA_ERROR_* d'un appel Flow (erreur de config vs préalable manquant vs non-supporté sur ce matériel / install).
Concevoir des bindings non-C (Rust, Go, Python, …) sur la Flow C ABI.
Ajouter du CT stateful (doca_flow_ct.h) au-dessus d'un port existant (voir TASKS.md ## flow-ct).

Ne charge pas pour l'orientation DOCA générale, « où je trouve la doc », layout d'install, ou questions de bibliothèque non-Flow — utilise doca-public-knowledge-map.

Ce que cette skill fournit

C'est un loader fin ; la matière substantive vit dans deux fichiers compagnons :

CAPABILITIES.md — ce que Flow peut exprimer sur cette version : sortes de match et action supportées, règles de décomposition de pipes, la surface API + liste de gardes de noms communément inventés, l'overlay DOCA_ERROR_* de Flow, la surface d'observabilité par-entrée / par-pipe, notes de version, la politique de sécurité, et la surface de compagnon CT.
TASKS.md — workflows pour les six verbes applicables (configure, build, modify, run, test, debug), plus ## flow-ct (overlay CT-stateful), ## shared-resources (shared encap / decap / counter / meter / RSS / IPsec-SA / PSP overlay), ## rollback (snapshots de classe pipeline-edit), ## Command appendix, et Deferred task verbs pour router les questions d'install / deploy.

La skill suppose que DOCA est installée à /opt/mellanox/doca et que l'utilisateur peut ouvrir un doca_dev. L'installation DOCA, la setup hugepages, et la prep EAL dv_flow_en devargs vont via doca-setup ; les préalables runtime hugepages / devargs qu'un binaire doit avant qu'un port Flow démarre sont épinglés dans TASKS.md ## configure étape 5.

Ce que cette skill n'expédie délibérément pas

Cette skill est une guidance d'agent, pas un bundle de code : elle n'expédie pas du code d'application Flow pré-écrit, des manifests de build autonomes, ou une subtree samples/ / bindings/ / reference/. La source Flow vérifiée est le sample C livré à /opt/mellanox/doca/samples/doca_flow/<name>/ — l'agent route l'utilisateur là et prescrit une édition minimum-diff via le workflow modify-a-sample dans doca-programming-guide plus les overrides Flow dans TASKS.md ## build, et construit tout manifest dans le projet de l'utilisateur contre l'install de l'utilisateur, où pkg-config --modversion doca-flow est la source de vérité.

Ordre de chargement

Lis ce SKILL.md d'abord pour confirmer que la question est applicable.
Pour le schéma de spec de pipe, la matrice de capacité, la taxonomie d'erreur, l'observabilité, et la politique de sécurité, vois CAPABILITIES.md.
Pour les workflows étape par étape, vois TASKS.md.

Skills connexes

doca-public-knowledge-map — table de routing pour la doc DOCA publique et le layout on-disk d'un package installé.
doca-setup — prep env, vérification d'install, et le chemin pas encore d'install via le conteneur DOCA NGC.
doca-programming-guide — patterns DOCA généraux partagés par chaque bibliothèque : le pattern build pkg-config + meson, le workflow first-app modify-a-shipped-sample, le lifecycle universel, la taxonomie inter-bibliothèque DOCA_ERROR_*, et l'ordre de debug program-side. Cette skill couche des spécificités Flow par-dessus.
doca-flow-tune — inspection d'état programmé (read-only).
doca-hardware-safety — overlay requis pour les basculements mode-carte (ex. changement mlxconfig de SEPARATED_HOST à EMBEDDED_CPU).
doca-debug — l'échelle de debug cross-cutting (install / version / build / link / runtime / program / driver).