/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