doca-debug

Files (7)

• BENCHMARK.md
• CAPABILITIES.md
• SKILL.md
• TASKS.md
• evals.json · evals/
• skill-card.md
• skill.oms.sig

SKILL.md (first lines)

# DOCA debug

## Examples

- **"My DOCA build / link / runtime failed — which layer is
  it?"** — this is in scope. Walk the layered ladder; do not
  jump to library-internal debug first.
- **"How do I turn up verbosity for any DOCA library or
  tool?"** — use the log-level / trace-flavor surface, then
  capture state for a forum post.

## Instructions

An `undefined reference` is a **Link-layer symptom**, not proof of a
missing library or an application-code defect. Before recommending edits,
request these observations from the **same host/container and shell that
ran the failing build**:

- `pkg-config --modversion doca-common` and the selected library's version;
  for Flow, `pkg-config --modversion doca-flow`.
- `pkg-config --libs doca-<library>`; for Flow, `pkg-config --libs doca-flow`.
- The actual failing compiler/linker invocation from the build log and its
  full error output. `pkg-config` reports flags, not the command that failed.

**If these outputs are missing, request them and pause before prescribing a
repair.** Listing a check is not evidence that it passed. Do not append a
speculative fix, guessed `-L`/`-l` flags, predicted library filenames, or a
replacement compiler command to that capture request. Once evidence is
available, compare the original invocation with the complete observed
`pkg-config` output through the existing build system; do not hand-assemble
DOCA's version-dependent split libraries. Use `ldd` only if a relevant binary
was actually produced; a declaration in a header does not prove that a linked
shared object exports the symbol.

Follow `doca-version/TASKS.md#configure` for version coherence,
`doca-programming-guide/TASKS.md#debug` for the
environment-before-program investigation, and
`doca-public-knowledge-map/SKILL.md` for verified
install locations and public documentation. A bundle skill name is not an SDK
page slug: never construct a documentation URL from it. If no matching guide
has been verified, use the [DOCA SDK index](https://docs.nvidia.com/doca/sdk/index.html)
and say the specific page is not yet confirmed.
Then follow [TASKS.md](TASKS.md#debug) for the staged investigation; later
phases are conditional on observed results, not instructions to guess a fix.

**First reply when only a linker error is available (Flow example).**
Use this capture-only shape, adapting the library to the actual question:

> This is a link-time failure. An undefined-symbol message does not tell us
> the installed version or which build setting is wrong. From the same
> host/container and shell as the failing build, please paste these outputs:
>
> ```bash
> pkg-config --modversion doca-common
> pkg-config --modversion doca-flow
> pkg-config --libs doca-flow
> ```
>
> Also include the actual failing linker invocation, full error output and
> whether the build ran on the host or in a container. Do not change flags,
> packages or source yet. Phases 3–5 are pending this evidence; no repair has
> been selected. Once the observations are available, we can compare them,
> choose one justified correction and rerun the original build. The link
> check is successful only when that build exits cleanly without the missing
> symbols; it does not establish runtime or hardware correctness.

End that first reply at the evidence request and pending decision. Do not add
an example repair command after it, even with a disclaimer to verify it later.

**Where to start:** This skill is the canonical layered-ladder
reference both `doca-setup/SKILL.md`
and `doca-programming-guide/SKILL.md`
escalate to. If the symptom does not fit cleanly in env-class or
program-class, start at the tasks companion — the
full layered ladder lives there.

## Example questions this skill answers well

The CLASSES of debug questions this skill is built to answer, each
with one worked example.

- **"My DOCA build / link / runtime / program failed — which layer is
  it?"** — worked example: *"`ld` says `undefined reference to
  doca_flow_init` — which layer?"* Answered by the canonical layered
  ladder in the tasks companion (layer 4 = Link).
- **"How do I turn up verbosity for any DOCA library or tool?"** —
  worked example: *"My DOCA Flow program is silent — where do I get
  more log output?"* Answered by the trace-flavor / log-level surface
  in the capabilities companion
  + the run-with-verbosity workflow in
  the tasks companion.
- **"How do I capture state for a forum question or bug report?"** —
  worked example: *"I'd like to file a forum question with reproducible
  context — what should I include?"* Answered by the
  capture-a-reproducible-state workflow in
  the tasks companion.
- **"What does this DOCA tool's output mean / which tool answers
  this?"** — worked example: *"`doca_caps` returned nothing for RDMA
  — does that mean unsupported?"* Answered by the
  tool-vs-capability decision tree in
  the capabilities companion
  + cross-link to `doca-caps/SKILL.md`.
- **"I'm debugging inside the NGC container — what's
  observable?"** — worked example: *"`hugepages` is empty inside the
  container; is that a real problem or a container thing?"*
  Answered by the container-specific debug constraints in
  the capabilities companion
  + the tasks companion layer 5 (Runtime).
- **"Where do I ask for help with this?"** — worked example: *"Where
  is the customer-facing DOCA forum and what should the post
  contain?"* Answered by the Developer-Forum routing rule in
  the tasks companion plus
  `doca-public-knowledge-map/SKILL.md`.

If the symptom is purely env-class, route to
`doca-setup/SKILL.md`; if purely
program-class, route to
`doca-programming-guide/SKILL.md`.
This skill is the cross-cutting layer both call into.

From NVIDIA/skills, Apache-2.0.

More from NVIDIA/skills