Przejdź do treści
Biblioteka skilli
Programowanie · Nauka i wyjaśnianie

doca-common

/doca-common

Pokazuje podstawy programowania DOCA na BlueField i ConnectX: cykl życia doca_ctx, wykrywanie urządzeń, bufory i logowanie.

Repozytorium
skills ↗
Licencja
Apache-2.0
Ostatnia zmiana repozytorium
12.11.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
8
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 12.11.2026, bez odwołań do wycofanych modeli i API.

Licencja

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

Co robi i kiedy

Pokazuje podstawy programowania DOCA na BlueField i ConnectX: cykl życia doca_ctx, wykrywanie urządzeń, bufory i logowanie.

Wyzwalacze z opisu

DOCA Common
Oryginalny opis (EN)

Use this skill whenever the user is doing hands-on DOCA programming on a BlueField DPU or ConnectX NIC and needs the foundation primitives every per-library context rests on — walking the doca_ctx lifecycle, discovering doca_dev / doca_devinfo and gating on doca_*_cap_* before trusting a feature, wiring doca_mmap / doca_buf_inventory / doca_buf for zero-copy I/O across libraries, driving doca_pe for completions, or DOCA Log's two-tier (--sdk-log-level vs app-side) model. Trigger even when the user does not say "DOCA Common" — typical implicit phrasings include "my tasks submit but nothing comp

Jak działa

  1. Examples
  2. Instructions
  3. Example questions this skill answers well
  4. Audience
  5. Language scope
  6. When to load this skill
  7. What this skill provides
  8. What this skill deliberately does not ship
  9. Loading order
  10. Related skills
Sekcje z nagłówków SKILL.md, w oryginale · 280 linii, 1 877 słów
Podgląd SKILL.md
---
license: Apache-2.0
name: doca-common
description: >
  Use this skill whenever the user is doing hands-on DOCA programming on
  a BlueField DPU or ConnectX NIC and needs the foundation primitives
  every per-library context rests on — walking the doca_ctx lifecycle,
  discovering doca_dev / doca_devinfo and gating on doca_*_cap_* before
  trusting a feature, wiring doca_mmap / doca_buf_inventory / doca_buf
  for zero-copy I/O across libraries, driving doca_pe for completions,
  or DOCA Log's two-tier (--sdk-log-level vs app-side) model. Trigger
  even when the user does not say "DOCA Common" — typical implicit
  phrasings include "my tasks submit but nothing completes",
  "DOCA_ERROR_BAD_STATE from doca_ctx_start", "--sdk-log-level does
  nothing for my DOCA_LOG_DBG lines", "share a buf between doca_dma and
  doca_rdma", or "crashes far from the offending line". Refuse and route
  elsewhere for per-library questions in isolation (load doca-flow /
  doca-rdma / doca-eth alongside), installing DOCA (doca-setup), or doc
  lookup (doca-public-knowledge-map).
metadata:
  author: NVIDIA <doca-feedback@nvidia.com>
  kind: library
  doca_version: "3.5"
  tags:
    - doca
    - common
    - core
compatibility: >
  Requires DOCA SDK installed at /opt/mellanox/doca on Linux (Ubuntu
  22.04/24.04 or RHEL/SLES) with a BlueField DPU or ConnectX NIC
  attached. doca-common is present on every healthy DOCA install;
  reads the user's local install via `pkg-config --modversion
  doca-common` and inspects /opt/mellanox/doca/{lib,include,samples,applications}.
  The validation steps require a live DOCA install.
---

# DOCA Common

## Examples

- **"Tasks submit but nothing completes."** — start at the progress
  engine and ctx lifecycle, not a per-library rewrite.
- **"DOCA_ERROR_BAD_STATE from doca_ctx_start."** — walk the Common
  lifecycle order before blaming Flow or RDMA.

## Instructions

Follow Loading order below. Open the tasks companion for configure /
build / run. Open the capabilities companion for ctx / buf / pe /
log. Do not open every companion file.

**Where to start:** This skill is the **foundation every DOCA app
loads first** — before doca-flow, doca-rdma, doca-eth, doca-comch, or
any other higher-level library. Every `doca_<library>_*` context is
built on top of `doca_ctx`, every device handle is a `doca_dev`
discovered through `doca_devinfo`, every zero-copy buffer is a
`doca_buf` from a `doca_buf_inventory` over a `doca_mmap`, every
task completion drains through a `doca_pe`, and every log line emits
through `doca_log`. Open the capabilities companion when
the question is *what does Common express* on this install; open
the tasks companion when the user wants to *do* something
(configure / build / modify / run / test / debug). If the user has
not installed DOCA yet, route to
`doca-setup/SKILL.md` first. If the user is
already past the foundation and asking a library-specific question
(e.g. *"how do I program a Flow pipe"*), load the matching per-library
skill alongside this one — they cross-link back here for the shared
primitives.

## Example questions this skill answers well

The CLASSES of doca-common questions this skill is built to answer,
each with one worked example. The agent should treat the *class* as
the load-bearing piece — the worked example is a single instance.

- **"What is the doca-common foundation I have to set up BEFORE I
  open a doca-flow / doca-rdma / doca-eth / … context?"** — worked
  example: *"I'm starting a brand-new DOCA Flow program on
  BlueField-3; what's the doca-common skeleton I need before I open
  the Flow port?"*. Answered by the universal foundation walk in
  ## configure +
  ## ctx +
  ## dev +
  ## progress engine.
- **"How do I discover a device and gate on its capabilities before
  trusting the public docs?"** — worked example: *"I want to use
  `doca_eth_txq` but the docs hint at a feature only on certain
  firmware bands"*. Answered by the capability-discovery rule
  (`doca_devinfo_create_list` → `doca_*_cap_*` against the active
  `doca_devinfo` is the runtime authority) in
  ## dev +
  ## use.
- **"What's the doca_buf / doca_mmap / doca_buf_inventory wiring
  for zero-copy I/O, and what's the lifecycle order?"** — worked
  example: *"I want to register a user-space buffer with my device,
  carve it into N data-plane buffers, and reference-count them
  across multiple DOCA libraries"*. Answered by the zero-copy
  buffer model in
  ## buf +
  the buffer-lifecycle walk in
  ## configure +
  ## use.
- **"How does the progress engine work and where do I have to call
  it?"** — worked example: *"my doca_rdma task submits cleanly but
  nothing completes — what loop am I missing?"*. Answered by the PE
  surface in
  ## progress engine
  + the run-loop pattern in ## run.
- **"Why don't my DOCA log lines appear at the level I expect, and
  what's the difference between `--sdk-log-level` and the app-side
  setter?"** — worked example: *"I set `--sdk-log-level 60` (DEBUG), my
  own `DOCA_LOG_DBG` lines still don't print"*. Answered by the
  two-tier log model in ## log
  + the tier-flip iteration in ## log.
- **"What does this `DOCA_ERROR_*` from a `doca_buf_*` / `doca_ctx_*`
  / `doca_dev_*` / `doca_pe_*` / `doca_log_*` call mean?"** —
  worked example: *"`DOCA_ERROR_BAD_STATE` from `doca_ctx_start`"*.
  Answered by the Common overlay on the cross-library `DOCA_ERROR_*`
  taxonomy in
  ## Error taxonomy
  + the layered ladder in
  ## debug that escalates to
  `doca-debug/SKILL.md`.

## Audience

This skill serves **every external developer building applications
that consume any DOCA library** — i.e., users whose code calls *any*
`doca_*` symbol (directly in C/C++, or through FFI/bindings from
another language). Whether the user's primary library is doca-flow,
doca-rdma, doca-eth, doca-comch, doca-dma, doca-rmax, doca-sha,
doca-aes-gcm, doca-erasure-coding, or any other, the doca-common
surface is *under* it and the user will hit `doca_buf`, `doca_ctx`,
`doca_dev`, `doca_pe`, and `doca_log` as part of the first-app
journey. It is *not* for NVIDIA developers contributing to DOCA
Common itself.

## Language scope

DOCA Common ships as a C library with `pkg-config` module name
`doca-common`. The shipped samples that demonstrate Common primitives
live *inside* every per-library samples tree (any
`/opt/mellanox/doca/samples/<library>/<sample>/*_main.c` is a worked
example of the universal foundation — `doca_devinfo_create_list`
→ `doca_dev_open` → per-library `doca_ctx` create → `doca_pe_create`
→ `doca_pe_connect_ctx` → `doca_ctx_start` → submit work → drive
`doca_pe_progress` → drain completions → `doca_ctx_stop` → destroy).
C and C++ consumers are the canonical case and the worked examples
in the tasks companion assume that path. Other-language consumers (Rust, Go,
Python, …) consume the same `*.so` through FFI or language-specific
bindings; the skill's contribution in that case is to keep the
universal foundation walk, the lifecycle, the capability-discovery
rule, the PE-drives-completion rule, and the two-tier log model
language-neutral, and to route the agent to the public C ABI as the
authoritative surface that any wrapper will eventually call.

## When to load this skill

Load this skill whenever the user is doing **any** hands-on DOCA
work — it is the foundation. Concretely:

- Setting up the universal DOCA-side skeleton before opening any
  per-library context (Flow, RDMA, Eth, Comch, DMA, Rmax, …).
- Discovering devices and representors and gating capability use
  on the active `doca_devinfo` via the `doca_*_cap_*` family.
- Wiring `doca_mmap` + `doca_buf_inventory` + `doca_buf` for
  zero-copy I/O that crosses libraries (e.g. doca-eth feeds
  doca-dma feeds doca-rdma — they share the same buf surface).
- Driving the progress engine (`doca_pe_create` /
  `doca_pe_connect_ctx` / `doca_pe_progress`) — the universal
  task-completion drain every DOCA Core context relies on.
- Wiring DOCA Log into a fresh app or modifying a shipped sample to
  add the user's own per-component log lines via the two-tier
  (`--sdk-log-level` vs app-side registry) model.
- Debugging a `DOCA_ERROR_*` returned from any `doca_buf_*` /
  `doca_ctx_*` / `doca_dev_*` / `doca_pe_*` / `doca_log_*` call —
  the Common surface is where most lifecycle / capability /
  permission errors first surface for higher-level libraries.
- Designing or extending non-C bindings (Rust, Go, Python, …) that
  wrap any DOCA library — for the universal foundation surface
  (buf, ctx, dev, pe, log) the wrapper has to expose first.

Do **not** load this skill for library-specific Flow, RDMA, Eth,
Comch, DMA, Rmax, … questions in isolation — load the matching
per-library skill alongside this one. Do **not** load this skill for
general DOCA orientation, install of DOCA itself, or
*"where do I find docs"*. For those, use
`doca-public-knowledge-map/SKILL.md`
or `doca-setup/SKILL.md`.

## What this skill provides

This is a **thin loader**. The body keeps only the orientation
needed to pick the right next file. The substantive Common material
lives in two companion files:

- the capabilities companion — what doca-common expresses on this install:
  the `## Capabilities and modes` overview of the universal
  primitives every DOCA application touches; the five subsystem
  H2s (`## log`, `## buf`, `## ctx`, `## dev`, `## progress
  engine`) that own the per-primitive surface; the
  `## Version compatibility` doca-common-specific overlay;
  the `## Error taxonomy` Common-side view of the universal
  `DOCA_ERROR_*` set; the `## Observability` surface (logs, PE
  events, capability snapshots); and the `## Safety policy` overlay
  on the bundle-wide hardware-safety meta-policy.
- the tasks companion — step-by-step workflows for the universal verbs
  (`configure`, `build`, `modify`, `run`, `test`, `debug`, `use`)
  PLUS a `## log` verb-side that covers the two-tier log model in
  workflow form. Plus a `Deferred task verbs` block that points
  install / deploy / rollback questions at the right next skill.

The skill assumes a host or BlueField where DOCA is already
installed at the standard location and the user has the privileges
their public install profile expects. It does not cover installing
DOCA — that path goes through
`doca-setup/SKILL.md`.

## What this skill deliberately does not ship

This skill is **agent guidance**, not a samples or templates
bundle. To keep the boundary clean, it deliberately does not
contain — and pull requests should not add:

- **Pre-written DOCA application source code, in any language.**
  The verified Common usage shows up inside every shipped DOCA
  sample at `/opt/mellanox/doca/samples/<library>/<sample>/*_main.c`
  and inside every shipped reference application. The agent's job
  is to route the user to those files and prescribe a minimum-diff
  modification on them via the universal modify-a-sample workflow
  in
  `doca-programming-guide/SKILL.md`.
- **Standalone build manifests** (`meson.build`,
  `CMakeLists.txt`, `Cargo.toml`, `setup.py`, `go.mod`, …) parked
  inside the skill. The agent constructs the build manifest *in
  the user's project directory* against the user's installed DOCA,
  where `pkg-config --modversion doca-common` is the source of
  truth.
- **A `samples/`, `bindings/`, or `reference/` subtree** of any
  kind. A mock or incomplete artifact in this skill's tree, even
  one labeled "reference", is misleading: users will read it as
  buildable.

## Loading order

1. Read this skill first to confirm the user's question is in
   scope.
2. **For the universal primitives (`log` / `buf` / `ctx` / `dev` /
   `progress engine`), the `pkg-config --modversion doca-common`
   anchor, the Common error overlay, observability, and safety
   policy, see the capabilities companion.**
3. **For step-by-step workflows — configure, build, modify, run,
   test, debug, use, log — see the tasks companion.**

Both companion files cross-link to each other,
`doca-version/SKILL.md` for the canonical
version-handling rules,
`doca-programming-guide/SKILL.md`
for the universal modify-a-shipped-sample workflow and the
cross-library `DOCA_ERROR_*` taxonomy,
`doca-debug/SKILL.md` for the cross-cutting
debug ladder, and
`doca-public-knowledge-map/SKILL.md`
whenever the right answer is "look it up in the public docs or the
installed package layout" rather than "Common-specific guidance".

## Related skills

- `doca-public-knowledge-map/SKILL.md` —
  the routing table for every public DOCA documentation source and
  the on-disk layout of an installed DOCA package. Always available
  alongside this skill; this skill expects to be able to defer
  documentation-finding and install-layout questions there instead
  of duplicating them.
- `doca-setup/SKILL.md` — env preparation,
  install verification, and the *I have no install yet* path with
  the public NGC DOCA container (`nvcr.io/nvidia/doca/doca`) as the
  universal Stage-1 fallback. This skill assumes its preconditions
  are satisfied.
- `doca-version/SKILL.md` — canonical DOCA
  version-handling rules (four-way match, NGC semantics,
  headers-win-over-docs). `pkg-config --modversion doca-common` is
  the build-time anchor *every* DOCA install carries; this skill's
  `## Version compatibility` overlays the Common-specific notes on
  top.
- `doca-programming-guide/SKILL.md` —
  general DOCA programming patterns shared by every library: the
  canonical `pkg-config` + meson build pattern, the universal
  modify-a-shipped-sample first-app workflow, the universal
  lifecycle, the cross-library `DOCA_ERROR_*` taxonomy, and the
  program-side debug order. This skill is the *primitives* layer
  the programming-guide patterns rest on.
- `doca-debug/SKILL.md` — the cross-cutting
  debug ladder (install / version / build / link / runtime /
  program / driver) and the verbosity-escalation surface. DOCA Log
  is the foundation `doca-debug` builds its runtime-debug story on;
  this skill is where the two-tier log model and the universal
  lifecycle errors first surface, and `doca-debug` cross-links here
  for both.
- `doca-structured-tools-contract/SKILL.md` —
  the bundle's structured-tools precedence rule (detect / prefer /
  fall back / report). The Command appendix in
  the tasks companion honors this contract.
- `doca-hardware-safety/SKILL.md` —
  the cross-cutting hardware-safety meta-policy this skill's
  `## Safety policy` overlays.
- Per-library skills (`doca-flow`, `doca-rdma`, `doca-eth`,
  `doca-comch`, `doca-dma`, `doca-rmax`, `doca-sha`, `doca-aes-gcm`,
  `doca-erasure-coding`, `doca-compress`, `doca-dpa`, `doca-gpunetio`,
  `doca-pcc`, `doca-sta`, `doca-telemetry`, `doca-urom`,
  `doca-verbs`, `doca-argp`, `doca-devemu`,
  `doca-dpdk-bridge`, …) — every per-library skill cross-links
  back to this skill for the foundation primitives. Loading this
  skill alongside any of them is the recommended default.
Pliki w paczce (8)
  • BENCHMARK.md 10 KB
  • CAPABILITIES.md 42 KB
  • SKILL.md 15 KB
  • SKILLCARD.yaml 3 KB
  • TASKS.md 35 KB
  • skill-card.md 4 KB
  • skill.oms.sig 5 KB
  • evals/evals.json 3 KB

Wersje

W bazie nie ma innych skilli o nazwie doca-common.

Migawka bazy z 13.11.2026 · wersja paczki 786a2db2dbd0 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100doca-mgmt
    Programuje zarządzanie urządzeniami BlueField i ConnectX w DOCA: kontekst reprezentatora, zapytania o możliwości, kwoty ICM i polecenia firmware.
  • 100doca-devemu
    Pomaga w emulacji urządzeń PCIe na DPU BlueField: własne urządzenie widoczne dla hosta i kod backendu po stronie DPU.
  • 100doca-bench-extension
    Pomaga pisać, budować i debugować wtyczkę do doca-bench, czyli bibliotekę współdzieloną mierzącą obciążenia spoza wbudowanych trybów.
  • 100doca-pcc-ztr-rttcc-algo
    Wdraża, dostraja i ocenia referencyjny algorytm ZTR RTTCC dla RoCE na DPA BlueField-3 przez przykład DOCA PCC.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.