/doca-erasure-coding

license: Apache-2.0
name: doca-erasure-coding
description: >
  Hardware-offloaded erasure coding with DOCA Erasure Coding
  (Reed-Solomon, doca_ec) on a BlueField DPU, ConnectX NIC, or host:
  generating parity for data blocks, rebuilding lost blocks from the
  survivors, and refreshing parity after a change. Trigger on "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", even without naming DOCA Erasure
  Coding. Covers bringing up a doca_ec context, the create / recover /
  update tasks, matrix type / N / K / block size, doca_ec_cap_* queries
  before sizing, doca_mmap src/dst permissions, and DOCA_ERROR_* from
  doca_ec_task_*. 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).
metadata:
  author: NVIDIA <doca-feedback@nvidia.com>
  kind: library
  doca_version: "3.5"
  tags:
    - doca
    - erasure-coding
    - reed-solomon
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}.
  The validation steps require a live DOCA install.

DOCA Erasure Coding

Examples

• **"A disk failed; can I rebuild from parity?"** — this is in

scope if the layout is Reed-Solomon N+K. Query `doca_ec_cap_*` before sizing recover.

• **"One data block changed; refresh parity without re-encoding."**

— use the update task. Do not route this to replication or network FEC.

Quick answer: capability check and sample choice

Before writing code, query the device: `doca_ec_cap_task_create_is_supported`, `doca_ec_cap_task_update_is_supported` or `doca_ec_cap_task_recover_is_supported` for the task you need, then `doca_ec_cap_get_max_block_size` and `doca_ec_cap_get_max_buf_list_len` to size blocks. Start from the shipped sample for that task under `/opt/mellanox/doca/samples/doca_erasure_coding/` (copy it; never edit the installed one). Use the update task to refresh parity for a changed block instead of re-encoding everything.

Instructions

Follow Loading order below. Open the tasks companion for configure / recover / debug. Open the capabilities companion for create / recover / update and matrix policy. Do not open every companion file.

**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 the tasks companion if the user wants to *do* something (configure / build / modify / run / test / debug); open the capabilities companion 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/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 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.

**How to use this skill.** Read this file, then search the companion file for the `## <name>` heading the question needs and read that whole section. Answer completely from it, quoting only its symbols and commands. Do not browse docs; use the entry points in `doca-public-knowledge-map`. Give environment checks as commands for the user's DOCA host. For out-of-scope requests, name the skill that owns them and stop.

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 and modes

• the *"when NOT to use doca-erasure-coding"* bullets in

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 and modes

• the discovery step in

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 and modes

• the update-vs-re-encode rule in

Safety policy

• the modify-from-sample slot for switching between create and

update tasks in

modify.

• **"K of my N+K