Doca Erasure Coding

---
license: Apache-2.0
name: doca-erasure-coding
description: >
  Use this skill when the user is doing hands-on DOCA Erasure Coding
  programming on a BlueField DPU, ConnectX NIC, or host — bringing
  up a doca_ec context, picking among the create / recover / update
  tasks, choosing matrix type / N / K / block size, querying
  doca_ec_cap_* before sizing, setting doca_mmap src/dst
  permissions, or debugging DOCA_ERROR_* returns from
  doca_ec_task_*. Trigger even when the user does not name "DOCA
  Erasure Coding" or "Reed-Solomon" — typical implicit phrasings
  include "one data block changed, how do I refresh parity without
  re-encoding", "a disk failed and 2 parity blocks are gone, can I
  rebuild", "RAID-6 resilience across 12 disks", "my
  doca_ec_task_create returns NOT_PERMITTED", or "is this N+K layout
  still recoverable". Refuse and route elsewhere for non-Reed-Solomon
  codes (fountain / LDPC / raptor), pure-replication designs,
  network FEC, or other DOCA accelerator libraries (SHA / Compress /
  AES-GCM / DMA) — those belong to other skills.
metadata:
  kind: library
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. Reads the user's local install via `pkg-config
  doca-erasure-coding` and inspects
  /opt/mellanox/doca/{lib,include,samples,applications}.
---

# DOCA Erasure Coding

**Where to start:** This skill assumes DOCA is already installed and
the user is doing **hands-on erasure-coding work** on a BlueField /
ConnectX / host with DOCA. Open [`TASKS.md`](TASKS.md) if the user
wants to *do* something (configure / build / modify / run / test /
debug); open [`CAPABILITIES.md`](CAPABILITIES.md) when the question
is *what can DOCA Erasure Coding express* on this version. If the
user has not installed DOCA yet, route to
[`doca-setup`](../../doca-setup/SKILL.md) first. If the user is
asking *"should I even use erasure coding here, or just replicate
the data?"*, the path-selection rule in
[`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
is the first stop — erasure coding is a **storage-resilience**
primitive (RAID-6 / distributed file system parity / object-storage
erasure-coded buckets), not a network primitive and not a
replication substitute.

## Example questions this skill answers well

The CLASSES of DOCA Erasure Coding 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.

- **"Should I offload this erasure coding to DOCA, or do it on the
  CPU — or just replicate the data instead?"** — worked example:
  *"I am writing a distributed object store that wants RAID-6-like
  resilience across 12 disks; is doca-erasure-coding the right
  primitive, or should I just keep three copies?"*. Answered by
  the path-selection table in
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  + the *"when NOT to use doca-erasure-coding"* bullets in
  [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy).
- **"Does my device support the EC task type, block size, N+K
  layout, and matrix type I want?"** — worked example: *"is
  `doca_ec_task_create` on this BlueField, what is the maximum
  block size, what is the cap on N+K, and does the device
  advertise a Vandermonde Reed-Solomon matrix?"*. Answered by
  the per-task + matrix + size capability-query rule
  (`doca_ec_cap_task_create_is_supported`,
  `_task_recover_is_supported`, `_task_update_is_supported`,
  `_task_galois_mul_is_supported` — the 4th public task on the
  EC accelerator, `doca_ec_cap_get_max_block_size`,
  `doca_ec_cap_get_max_buf_list_len`, and per-variant
  `doca_ec_matrix_create()` constructor success — the public
  header does NOT ship a `doca_ec_cap_get_matrix_*` family) in
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  + the discovery step in
  [`TASKS.md ## configure`](TASKS.md#configure).
- **"One source block changed — do I have to recompute all the
  parity from scratch?"** — worked example: *"I have 8 data + 4
  parity blocks on disk; one data block was just rewritten. How
  do I express the parity update without re-running the full
  encode?"*. Answered by the `doca_ec_task_update` row in the
  task-type table in
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  + the update-vs-re-encode rule in
  [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy)
  + the modify-from-sample slot for switching between create and
  update tasks in
  [`TASKS.md ## modify`](TASKS.md#modify).
- **"K of my N+K blocks went missing — how do I reconstruct
  them?"** — worked example: *"a disk failed; the 8 data blocks
  are intact but 2 of the 4 parity blocks are gone; can DOCA
  recover them?"*. Answered by the
  `doca_ec_task_recover` row in the task-type table in
  [`CAPABILITIES.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)
  + the recover smoke (encode → drop a block → recover → bit-compare)
  in [`TASKS.md ## test`](TASKS.md#test).
- **"What permissions does the source / destination mmap need?"** —
  worked example: *"my `doca_ec_task_create` returns
  `DOCA_ERROR_NOT_PERMITTED`"*. Answered by the permission matrix
  in [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy)
  + the mmap-set-permissions checklist in
  [`TASKS.md ## test`](TASKS.md#test).
- **"Is this DOCA Erasure Coding API available on my installed
  DOCA version?"** — worked example: *"is `doca_ec_task_update` in
  the DOCA I have installed, or do I have to recompute parity from
  scratch?"*. Answered by the version-compatibility overlay in
  [`CAPABILITIES.md ## Version compatibility`](CAPABILITIES.md#version-compatibility),
  which cross-links the canonical detection chain in
  [`doca-version`](../../doca-version/SKILL.md) and adds the
  EC-specific *"discover per-task support + matrix type via cap
  query"* bullets.
- **"What does this `DOCA_ERROR_*` from an EC call mean and which
  layer caused it?"** — worked example: *"`DOCA_ERROR_INVALID_VALUE`
  on `doca_ec_task_create_allocate_init` with block_size = 4 MiB"*.
  Answered by the EC overlay on the cross-library taxonomy in
  [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy)
  + the layered ladder in
  [`TASKS.md ## debug`](TASKS.md#debug) that escalates to
  [`doca-debug`](../../doca-debug/SKILL.md).

## Audience

This skill serves **external developers building applications that
consume the DOCA Erasure Coding library** — i.e., users whose code
calls `doca_ec_*` (directly in C/C++, or through FFI/bindings from
another language) to offload Reed-Solomon erasure coding onto a
BlueField DPU or ConnectX accelerator. It is *not* for NVIDIA
developers contributing to DOCA Erasure Coding itself.

The canonical fit is **distributed storage**: RAID-6-style block
layouts, distributed file system parity, object-storage
erasure-coded buckets, and any data-durability workload where the
N data + K redundancy block model lets the system tolerate K
simultaneous block losses without data loss. The skill keeps the
agent oriented to that domain: erasure coding is operationally
distinct from pure replication (which keeps M whole copies) and
from RAID-6 the disk layout (which is one specific instance of
the N=k, K=2 case); confusing them produces wrong recommendations.

**Language scope.** DOCA Erasure Coding ships as a C library with
`pkg-config` module name `doca-erasure-coding`. The shipped samples
are written in C. C and C++ consumers are the canonical case and
the worked examples in `TASKS.md` 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 lifecycle, capability-discovery,
permission, error-taxonomy, and create-vs-recover-vs-update
guidance 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 when the user is doing hands-on DOCA Erasure
Coding work, in any language. Concretely:

- Initializing a `doca_ec` context on a `doca_dev` and configuring
  at least one task type (`doca_ec_task_create`,
  `doca_ec_task_recover`, and/or `doca_ec_task_update`) before
  `doca_ctx_start()`.
- Choosing between the **create** task (encode N data blocks into
  K redundancy blocks), the **recover** task (reconstruct up to K
  missing blocks given the surviving subset), and the **update**
  task (incrementally update redundancy blocks when one source
  block changes — much cheaper than re-encoding from scratch).
- Picking the coding parameters: matrix type / coding scheme
  (typically Vandermonde or Cauchy for Reed-Solomon), N (number
  of data blocks), K (number of redundancy blocks), and block
  size (all blocks the same size).
- Setting permissions on `doca_mmap` correctly for the source
  buffers — data blocks for create, data + parity for recover —
  (`DOCA_ACCESS_FLAG_LOCAL_READ_ONLY` at minimum) and the
  destination buffers — redundancy blocks for create, recovered
  blocks for recover, updated parity for update —
  (`DOCA_ACCESS_FLAG_LOCAL_READ_WRITE`).
- Sizing blocks against
  `doca_ec_cap_get_max_block_size(devinfo)` and N+K against
  `doca_ec_cap_get_max_buf_list_len(devinfo, &max_buf_list_len)`.
- Checking which task types and matrix schemes this device's
  accelerator advertises via the
  `doca_ec_cap_task_*_is_supported` (including the 4th task
  `_task_galois_mul_is_supported`) and per-variant
  `doca_ec_matrix_create()` constructor success — the public
  header does NOT ship a `doca_ec_cap_get_matrix_*`
  families against the active `doca_devinfo`.
- Validating against a known-vector recover smoke (encode a small
  N + K layout, simulate one block loss, recover, bit-compare
  against the original block) before pushing bulk storage data
  through the accelerator.
- Recognising when **update** is the right task (single source
  block changed in an existing N + K layout — `doca_ec_task_update`
  is far cheaper than recomputing all K parity blocks via a fresh
  `doca_ec_task_create`).
- Debugging a `DOCA_ERROR_*` returned from an EC call (lifecycle
  vs. block-size vs. N+K vs. matrix-type vs. permission vs.
  queue pressure) and the task-completion event on the progress
  engine.
- Designing or extending non-C bindings (Rust, Go, Python, …)
  that wrap the EC C ABI — for the lifecycle, permission,
  capability, and create-vs-recover-vs-update rules the wrapper
  must honor.

Do **not** load this skill for general DOCA orientation, install
of DOCA itself, non-Reed-Solomon erasure codes (fountain codes,
LDPC — those belong on a CPU library, not the DOCA accelerator),
pure replication / mirroring designs (erasure coding is the wrong
primitive when one extra copy is the right answer), or other
DOCA libraries. For those, use
[`doca-public-knowledge-map`](../../doca-public-knowledge-map/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
EC-specific material lives in two companion files:

- `CAPABILITIES.md` — what DOCA Erasure Coding can express on
  this version: the three task types (create / recover / update,
  each independently capability-gated), the matrix-type + N + K +
  block-size configuration surface, the capability-query family
  (`doca_ec_cap_*` for task support, max block size, max N+K,
  supported matrix types), the EC error taxonomy (mapped onto
  the cross-library `DOCA_ERROR_*` set), the observability
  surface (per-task completion events on the progress engine),
  the safety policy that gates source / destination mmap
  permission decisions, and the path-selection rule (when to use
  doca-erasure-coding versus a CPU EC library versus pure
  replication versus RAID-6 on disk).
- `TASKS.md` — step-by-step workflows for the six in-scope EC
  verbs: `configure`, `build`, `modify`, `run`, `test`, `debug`.
  Plus a `Deferred task verbs` block that points out-of-scope
  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`](../../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 EC application source code, in any
  language.** The verified EC source code is the shipped C
  samples at `/opt/mellanox/doca/samples/doca_erasure_coding/`.
  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`](../../doca-programming-guide/SKILL.md),
  layered with the EC-specific overrides in
  [`TASKS.md ## modify`](TASKS.md#modify).
- **Pre-computed parity tables for arbitrary N + K layouts.**
  The skill tells the agent to use a *known-vector* smoke
  (encode a tiny N + K layout from a fixed input, simulate
  losing one block, recover, bit-compare against the original)
  as the smoke before bulk; it does not ship a vector bank of
  its own.
- **Standalone build manifests** (`meson.build`,
  `CMakeLists.txt`, `Cargo.toml`, …) 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-erasure-coding` 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.md` first to confirm the user's question is in
   scope (storage-domain resilience — N data + K redundancy
   blocks — and not a network or replication question
   misclassified as erasure coding).
2. **For the EC capability matrix, the three task types
   (create / recover / update), the matrix-type + N + K +
   block-size configuration surface, the capability-query rules,
   permission matrix, error taxonomy, observability, and safety /
   path-selection policy, see [CAPABILITIES.md](CAPABILITIES.md).**
3. **For step-by-step workflows — configure, build, modify, run,
   test, debug — see [TASKS.md](TASKS.md).**

Both companion files cross-link to each other,
[`doca-version`](../../doca-version/SKILL.md) for the canonical
version-handling rules, and
[`doca-public-knowledge-map`](../../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 "EC-specific guidance".

## Related skills

- [`doca-public-knowledge-map`](../../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. The DOCA
  Erasure Coding page lives at
  <https://docs.nvidia.com/doca/sdk/DOCA-Erasure-Coding/index.html>;
  the install-tree layout (samples directory, header location)
  belongs to the public knowledge map, not to this skill.
- [`doca-setup`](../../doca-setup/SKILL.md) — env preparation,
  install verification, and the *I have no install yet* path
  with the public NGC DOCA container. This skill assumes its
  preconditions are satisfied.
- [`doca-version`](../../doca-version/SKILL.md) — canonical DOCA
  version-handling rules. This skill's
  [`## Version compatibility`](CAPABILITIES.md#version-compatibility)
  cross-links the four-way match rule and adds only the
  EC-specific *"discover per-task support + supported matrix
  types + max block size + max N+K via cap query"* overlay.
- [`doca-structured-tools-contract`](../../doca-structured-tools-contract/SKILL.md) —
  the bundle's structured-tools precedence rule (detect / prefer
  / fall back / report). The Command appendix in
  [TASKS.md](TASKS.md) honors this contract.
- [`doca-programming-guide`](../../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 layers EC specifics on
  top.
- [`doca-debug`](../../doca-debug/SKILL.md) — the cross-cutting
  debug ladder (install / version / build / link / runtime /
  program / driver). EC-specific debug (task-not-supported,
  matrix-type-unsupported, block-size-over-max, N+K-over-max,
  recover-with-too-many-missing) overlays on top of that ladder.