doca-erasure-coding

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

  • the recover smoke (encode → drop a block → recover → bit-compare) in ## 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 ## Safety policy
  • the mmap-set-permissions checklist in

  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

  Version compatibility,

  which cross-links the canonical detection chain in 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

  Error taxonomy

  • the layered ladder in

  debug that escalates to

  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 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 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/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:

• the capabilities companion — 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).
• the tasks companion — 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/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/SKILL.md, layered with the EC-specific overrides in

  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 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 the capabilities companion.
3. For step-by-step workflows — configure, build, modify, run, test, debug — see the tasks companion.

Both companion files cross-link to each other, doca-version/SKILL.md for the canonical version-handling rules, 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 "EC-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. 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/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/SKILL.md — canonical DOCA version-handling rules. This skill's ## 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/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-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/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.