/doca-public-knowledge-map

doca-public-knowledge-map — routing tables

Full enumerated routing tables moved out of SKILL.md to keep the loader within the per-file size budget. The agent opens this file when it needs the concrete docs.nvidia.com / on-disk / GitHub entries.

Example questions this skill answers well

These are the question SHAPES this skill is designed to route, with one worked example each. A productive A/B test against this skill probes the shape, not the literal wording.

• "Where can I read about DOCA <library/service/tool/concept>?" — worked example: "Where can I read about DOCA Flow Connection Tracking?" Answered by walking the ## Library- and module-specific guides, ## DOCA services, or ## DOCA tools routing tables to the matching docs.nvidia.com/doca/sdk/... entry.
• "Which DOCA libraries do I have installed and at what version?" — worked example: "How do I confirm the box has DOCA Flow 3.3 installed?" Answered by combining ## Layout of an installed DOCA package and ## Where to find the version, with cross-link to the layered version-detection rules in doca-setup ## Capabilities and modes.
• "Where is sample <X> on disk and where is its source on GitHub?" — worked example: "Where is the doca_flow sample that exercises ACL pipes?" Answered by combining ## Layout of an installed DOCA package (local) with ## Public source code: GitHub (remote) — both sections name the canonical paths.
• "What does this on-disk path mean, what should I cite from it?" — worked example: "What's in /opt/mellanox/doca/applications/ that the customer can actually run?" Answered by ## Layout of an installed DOCA package, plus the "no source-tree paths" ground rule above.
• "This URL I have 404s — what's the new one?" — worked example: "The Comm Channel page is gone in DOCA 2.5+." Answered by the URL-rename rule at the top of ## Public documentation entry points, plus the ## URL audit footer at the bottom of this file.
• "Where is the customer-facing place to ask for help on this?" — worked example: "What's the developer forum's DOCA category?" Answered from the developer-forum entry in ## Public documentation entry points, never internal NVIDIA channels (see ground rule above).

If the question fits a different shape (how to write code, how to set up an env, how to debug a crash), route to the matching skill instead — see AGENTS.md for the routing table.

Library- and module-specific guides

Each DOCA library has its own subtree under /doca/sdk/. Use the matching guide once the user's question is narrow enough to be about a single library.

First — the umbrella. The DOCA SDK ships dozens of libraries; the table below names the ones agents most often need to route directly. If the user's library is not listed, the canonical first stop is the DOCA Libraries umbrella page, which lists every public library with its quality level (GA / Beta / Alpha) and links to its programming guide. Always consult the umbrella before telling a user a library does not exist or before guessing a URL. The umbrella is also the right answer for "what DOCA libraries are available for X?"-style discovery questions.

There is no current single "DOCA Samples Overview" page in the v3.x docs. Samples are documented per-library inside each library's programming guide (see "Sample" sections inside the URLs above) and ship on disk under /opt/mellanox/doca/samples/doca_<library>/. Earlier (v1.x / v2.x) docs did have a single overview page — those URLs are now archived and will return 404 on docs.nvidia.com/doca/sdk/. Do not link the archived page; route the user to the per-library "Sample" sections plus the on-disk samples directory.

If the user asks about a DOCA library that is not in the table above, do not guess the URL. Open the DOCA Libraries umbrella page first to confirm the library exists and to find its canonical guide URL. Only after that, fall back to the user's installed sample directory (see "Layout of an installed DOCA package" below).

DOCA services

DOCA ships a set of services — long-running daemons / containers documented separately from the libraries. Per-service skills (where they exist) live under skills/services/<svc>; the URLs below are the public guides in docs.nvidia.com/doca/sdk/.

First — the umbrella. When the user's service is not listed below, the canonical first stop is the DOCA Services umbrella page, which lists every public DOCA service with its purpose and links to its service guide.

Non-goals. Externally-productized NVIDIA services that are NOT in doca/services/ at the bundle's currently-aligned DOCA release — DOCA Telemetry Service (DTS) as-deployed, BlueMan, HBN, SNAP, Virtio-net — are intentionally out of scope for this bundle, which is strictly 1:1 with doca/services/. See AGENTS.md ## Non-goals for the policy rationale. If a user asks about one of these external services, use the ## Externally-productized DOCA software — not in this bundle, but here is where to route table below to give them the authoritative public docs URL, service-specific common gotchas, and the Developer Forum entry point. Refusing without routing violates the bundle's own contract.

The bundle covers DOCA deployment via two sibling top-level cross-cutting skills, one per deployment path, plus a front-door routing decision in doca-setup ## recognize that lands the user on the right one:

• The Container Deployment Guide (https://docs.nvidia.com/doca/sdk/DOCA-Container-Deployment-Guide/index.html) is the cross-service reference for how DOCA service containers are deployed on BlueField. Covered cross-cuttingly by the doca-container-deployment skill — every in-bundle per-service skill above hands off to it for the kubelet-standalone static-pod manifests directory, image pull, and pod-spec drop pattern.
• The bare-metal hardware deployment path (a DOCA-linked application binary launched directly on host x86 or BlueField Arm bare-metal — no container) is covered by the doca-bare-metal-deployment skill. It owns the launch contract (direct / tmux / systemd), hardware-resource binding (PF/VF/representor + NUMA + CPU pinning
  • IRQ affinity), per-tenant isolation primitives, the bare-metal error taxonomy, and the restart-loop-is-HIGH-STAKES rule. The authoritative public references are the DOCA Programming Guide (build, link, runtime preconditions:

  https://docs.nvidia.com/doca/sdk/DOCA-Programming-Guide/index.html), the DPU / BlueField Platform Software Manual (PCIe topology, devlink, representor naming, mlxconfig device introspection: https://docs.nvidia.com/networking/display/bluefieldbsp4132), and the per-library guides listed below in this map.

• The front-door routing decision between the two — "which path applies to my workload?" — is owned by doca-setup ## recognize, which detects the system shape (host x86 / BlueField Arm bare-metal / DPU-only / fresh laptop) and asks the developer the minimum residual question before routing. Any deployment-shaped question ("how do I deploy", "my code is built, how do I run it", "I just got a BlueField, what now") loads ## recognize first.

Platform day-1 bring-up (before any app runs). Getting the DPU itself to a healthy OS + firmware state is a distinct layer below the two app-deployment paths above, and is covered by two platform-specific top-level skills:

• BlueField-3 (BF3) — the classic RShim/BFB path (bfb-install over RShim, TMFIFO 192.168.100.x, DPU vs separated-host mode via mlxconfig, post-BFB recovery) is covered by doca-bf3-deployment. Public reference: the DPU / BlueField Platform Software Manual (https://docs.nvidia.com/networking/display/bluefieldbsp4132).
• BlueField-4 (BF4) — the BMC-driven path (the three OS-ISO install methods UEFI-HTTP / PXE / Redfish Virtual Media, the PLDM firmware-update flow, and the Grace Ubuntu + cloud-init install) is covered by doca-bf4-deployment. Public references: the BlueField / DOCA docs on docs.nvidia.com; deep BSP/BFB internals stay in the BSP row below. Any mutating firmware/power-cycle step routes to doca-hardware-safety.

CollectX telemetry collection. Deploying/operating a CollectX (clx) telemetry-collection pipeline (providers/counters → schema → collector daemon → exporters: Prometheus / Fluent Bit / NetFlow / file-IPC) is covered by doca-collectx-deployment; the library reader/publisher APIs stay in doca-telemetry / doca-telemetry-exporter, and the productized DTS container is routed out as externally-productized.

If the user asks about a DOCA service that is not in this table, open the DOCA Services umbrella page to discover it. Do not guess service URLs.

Deploying DOCA services at scale — orchestration entry-point (persona/scale routing)

Pick the path by persona and scale, not by service. The deployment guidance for any DOCA service splits cleanly in two, and the agent should name which one the user is in before giving deployment steps:

• Developer / PoC / test / small-dev (single host or a handful of DPUs). For an in-bundle service (the six in the table above), use its per-service skill plus the two sibling deployment skills to deploy/configure it directly — doca-container-deployment for the kubelet-standalone static-pod path, or doca-bare-metal-deployment for a directly-launched DOCA binary. For an externally-productized service (HBN, BlueMan, SNAP, Virtio-net, DTS-as-deployed — not in this bundle), there is no in-tree skill: route to its guide via the routing table below and follow that guide's config keys / mlxconfig preconditions. Either way, this bundle's in-tree service skills are scoped to the developer/PoC persona.
• Admin / production / fleet-scale (racks of DPUs, declarative lifecycle, repeatable rollouts). Do not hand-roll per-host static pods or bfb-install loops at this scale. Route to the orchestration layer, which owns DPU provisioning, declarative DPUService deployment, and coordinated BFB/firmware rollouts:
  • DOCA Platform Framework (DPF) — the K8s-native DPU lifecycle + DPUService orchestrator (provisions BF-3, deploys services like HBN/BlueMan/SNAP declaratively across a fleet). Docs: https://docs.nvidia.com/networking/display/dpf25101 · source: https://github.com/NVIDIA/doca-platform. See the DOCA Platform Framework (DPF) row in the routing table below for failure-mode gotchas.
  • NVIDIA Network Operator — manages host-side NIC software (OFED driver, SR-IOV / RDMA device plugins, CNI) on regular k8s nodes; pairs with DPF. See its row in the table below. Docs: https://docs.nvidia.com/networking/display/kubernetes2611/index.html.
  • NVIDIA Kubernetes Launch Kit — an emerging aggregation/ integration layer that bundles orchestration (Network Operator today, DPF next) behind an agent-friendly discovery + deployment- generation interface: https://github.com/NVIDIA/k8s-launch-kit.

Agent contract for scale questions. When the user's intent is production/fleet-scale, the agent should prefer routing them to invoke the orchestration system (DPF / Network Operator / Launch Kit) rather than generating raw per-host deployment logic itself. The in-bundle service skills remain the right answer for the developer/PoC persona and for SDK-level integration; orchestration owns the production path. This split is the bundle's deliberate DOCA-SDK scope boundary — the orchestration systems above are externally owned and are routed, not re-implemented, here.

DOCA tools

DOCA ships a set of tools — small CLIs installed under /opt/mellanox/doca/tools/ on a real install, each documented on its own public page. Per-tool skills (where they exist) live under skills/tools/<tool>.

First — the umbrella. When the user's tool is not listed below, the canonical first stop is the DOCA Tools umbrella page, which lists every public DOCA tool and links to its tool guide.

Non-goals. Externally-productized NVIDIA tools that are NOT in doca/tools/ at the bundle's currently-aligned DOCA release — DOCA-DPACC-Compiler, DPA-Tools (DPA GDB Server / PS / Statistics), DOCA-DPU-CLI, DOCA-Ngauge, doca-hugepages helper — are intentionally out of scope for this bundle, which is strictly 1:1 with doca/tools/. See AGENTS.md ## Non-goals. If a user asks about one of these external tools, use the ## Externally-productized DOCA software — not in this bundle, but here is where to route table below for the authoritative docs URL, per-tool common gotchas, and the Developer Forum entry point. Refusing without routing violates the bundle's own contract.

If the user asks about a DOCA tool that is not in this table, open the DOCA Tools umbrella page to discover it. Do not guess tool URLs.

Externally-productized DOCA software — not in this bundle, but here is where to route

NVIDIA ships several DOCA-adjacent products outside the doca/{libs,services,tools} monorepo this bundle is 1:1 with. They are real, supported NVIDIA products — but because the bundle's strict alignment contract (see SKILLS.md and AGENTS.md ## Non-goals) forbids synthesizing answers about them from training knowledge, the bundle's job for these products is to route, not answer.

When the user asks about any product in the table below, the required response shape is the three-part contract spelled out in AGENTS.md ## Non-goals #7:

1. Recognize the class — name the product and state it is out of scope for this bundle, because it is not in the monorepo's doca/{services,tools}/ at the currently-aligned DOCA release.
2. Name the boundary honestly — the bundle is strictly 1:1 with the monorepo; products productized outside it (e.g. shipped as separate NGC containers, separate packages, or separate BSP utilities) are intentionally excluded.
3. Route with substance — provide the authoritative public URL for that specific product (most often under docs.nvidia.com/doca/sdk/ but, for BSP / BMC / k8s / fabric / firmware-tools / Cumulus / Spectrum-X / Rivermax-license-layer products, under docs.nvidia.com/networking/, docs.nvidia.com/networking-ethernet-software/, docs.nvidia.com/datacenter/, or network.nvidia.com/products/), name the most common gotcha class the user's symptom (if any) is likely hitting, and give the Developer Forum entry point as the escalation channel.

A refusal that names only (1) and (2) but skips (3) violates the bundle's contract. Use this table.

Hardware-safety overlay still applies. If the user's question about an externally-productized product touches live BlueField / NIC hardware state (mlxconfig writes, firmware burn, BFB reflash, SFC mode flip during HBN setup), load doca-hardware-safety alongside this routing step. The route covers where to read; safety covers how to change live state and is not waived by a non-goal refusal.

One worked example of the required response shape (for SNAP). When the user asks "how do I use DOCA SNAP to provision a host server — the host server never seems to be able to properly enumerate the NVMe device, or if it does it never is able to actually boot", the agent must answer with all three parts:

1. Recognize the class. "DOCA SNAP Services (SNAP-4 on BF-3, SNAP-3 on BF-2, SNAP Virtio-fs on BF-3) are externally-productized NVIDIA services — they ship as separate NGC containers / packages and are not in the doca/services/ monorepo this bundle is 1:1 with, so I don't have an in-tree SNAP skill to load."
2. Name the boundary. "The bundle's strict-1:1 alignment with doca/{services,tools}/ (see AGENTS.md ## Non-goals #7) intentionally excludes externally-productized services, because their cadence, packaging, and support model differ from the in-tree set the bundle was authored against."
3. Route with substance. "Your symptom — host can't enumerate the NVMe device, or enumerates but won't boot — is one of the four most-common SNAP gotcha classes: (a) NIC firmware not configured for SNAP / virtio (mlxconfig keys per the SNAP-4 Firmware Configuration section); (b) SNAP container not running on the BF (crictl ps -a \| grep snap); (c) no fabric target reachable from the BF management VRF; (d) BF BSP / SNAP version mismatched against host DOCA. Authoritative read: https://docs.nvidia.com/doca/sdk/DOCA-SNAP-Services/index.html (drill into SNAP-4 for BF-3). For real-customer threads with NVIDIA-staff answers: https://forums.developer.nvidia.com/c/infrastructure/doca/370, search 'SNAP'."

Skipping any of the three parts is a contract violation. The bundle's own deep-E2E suite tests for all three.

Response gate: Before sending an answer for any product in this table, verify it contains all three numbered parts above. If recognition, boundary, or substantive public routing is missing, revise the answer before sending; do not downgrade the contract to a bare refusal or an ungrounded URL.

Public source code: GitHub

NVIDIA publishes a small, deliberately scoped set of DOCA-adjacent code on GitHub. These are the public, customer-visible repositories.

Important: the bulk of DOCA — libraries, samples, applications, build system — is not on GitHub. It ships as packages and, for licensed users, as source archives downloaded from the Developer Zone. If the user asks for "the DOCA library X source on GitHub", correct them: the published sample for library X lives under /opt/mellanox/doca/samples/doca_<library>/ on an installed system, or in the downloadable source archive referenced from the Downloads page.

Layout of an installed DOCA package

When DOCA is installed from the official packages on a Linux host or on BlueField, an agent can rely on this on-disk layout. Use it instead of asking the user to share source code.

Useful enumeration commands to suggest to the user (read-only, safe):

ls /opt/mellanox/doca
ls /opt/mellanox/doca/samples
ls /opt/mellanox/doca/applications
pkg-config --list-all | grep -i doca

To build against DOCA from a user-owned directory, the canonical environment hint is to expose the DOCA pkg-config directory before running meson setup:

PCDIR="$(dirname "$(find /opt/mellanox/doca -name doca-common.pc -print -quit 2>/dev/null)")"
export PKG_CONFIG_PATH="${PCDIR}:${PKG_CONFIG_PATH}"  # commonly /opt/mellanox/doca/lib/<arch>-linux-gnu/pkgconfig on DOCA 3.3+; or /opt/mellanox/doca/infrastructure/lib/pkgconfig on legacy / split-profile installs

If pkg-config --modversion doca-common fails after that, treat it as a real environment problem (wrong package, wrong arch, missing dev package) and stop; do not silently change the user's environment. Load doca-setup with the captured command output to diagnose, repair, and prepare the environment.

Where to find the version

Load doca-version and run its canonical four-source detection chain; do not pick one convenient source and stop:

1. pkg-config --modversion doca-common.
2. cat /opt/mellanox/doca/applications/VERSION.
3. doca_caps --version.
4. On BlueField, the BFB-image version from the documented BlueField-side sources in doca-version TASKS.md ## configure (including bfver / /etc/mlnx-release where available).

Run every source available on the target and compare all observed values. If any available source disagrees, stop and route to doca-version TASKS.md ## debug; do not select a preferred value. If none of the canonical sources is available, stop and report that the version cannot be established. Always quote the versions actually observed; never assume "latest" and never route documentation by an assumed latest release.

URL audit

Every URL referenced by this routing map is HEAD-checked against the public NVIDIA documentation surface on every commit, so bundle releases always ship a routing map whose every URL was reachable at release time. If a URL on this page no longer resolves, that is the release's bug, not yours — fall back to the umbrella entry points listed in Public documentation entry points (DOCA SDK index, DOCA Libraries / Services / Tools umbrella pages) and search from there.

Ground rules for any agent using this skill

1. Prefer the local install over the web. If DOCA is installed on the machine, the files in /opt/mellanox/doca (Linux) are the exact bits the user is running. Web docs describe a release; local files are the release.
2. Check the version when quoting installed artifacts. When a DOCA install is present and the answer quotes installed API names, options, or sample filenames, find the installed version (see "Where to find the version" above) and use the matching documentation release. For a pure documentation lookup or a system without a local install, route from the public docs without claiming an installed version.
3. Never invent URLs, file paths, package names, pkg-config modules, library names, or sample names. If you do not see it in this map, in the user's local install, or in the official docs you fetched, say so and ask.
4. Public sources only. Reference NVIDIA documentation only on the public hosts listed in AGENTS.md ground rule #1. Anything else is not available to a customer agent and is rejected by an internal CI pipeline before the bundle ships.
5. No source-tree paths. Do not reference devtools/..., docs/ai/..., or any path that only exists inside the DOCA repository. Customers do not have those.

Hardware-safety meta-policy. Every per-artifact ## Safety policy in this bundle overlays the cross-cutting hardware-safety meta-policy. When the user's question touches a change to live DPU / NIC hardware state (mlxconfig writes, firmware burn, BlueField mode flip, BAR window change, IOMMU / hugepages kernel boot parameter, BFB reflash), load doca-hardware-safety alongside the per-artifact skill. Cross-cutting meta-policy lives there (pre-flight inventory, out-of-band access requirement, maintenance window, replica-first validation, rollback discipline, observability-before-workload, refuse-and-escalate when no rollback exists). Per-artifact overlays MUST NOT redefine it.

Upgrade / downgrade discipline. When the user is contemplating or recovering a DOCA upgrade or downgrade — moving a host to the next release, refreshing the BFB, bumping an NGC container tag, rolling back, or reacting to an accidental apt upgrade drift — load doca-upgrade. Its headline contract is detect → report → ASK → only-then guided upgrade; never auto-upgrade. It routes version detection to doca-version, every hardware / firmware / reboot step to doca-hardware-safety, and sunset / deprecation lifecycle lookups back to this map's Release Notes entry below. It does not redefine version detection or the hardware-touching discipline.

Public documentation entry points

Start here for any conceptual question. These are the canonical NVIDIA-hosted documents.

Rule when a URL in this skill returns 404. NVIDIA periodically renames doc pages and library slugs (the most recent example: Comm Channel → Comch in DOCA 2.5). If a URL listed here 404s during a real session: (1) tell the user explicitly that the skill's URL is stale; (2) try https://docs.nvidia.com/doca/sdk/ and look for a renamed link; (3) do not invent a replacement URL and do not silently point at an archive/ URL — those are version-pinned to old releases. If the index is also unreachable, state that the public documentation surface could not be reached, ask the user to retry after checking connectivity, and offer the Developer Forum entry point without inventing a replacement URL. File a fix against this skill (see "URL audit" footer for the last verification date and DOCA version).