doca-erasure-coding

# 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 copi