doca-erasure-coding

Files (8)

• BENCHMARK.md
• CAPABILITIES.md
• SKILL.md
• SKILLCARD.yaml
• TASKS.md
• evals.json · evals/
• skill-card.md
• skill.oms.sig

SKILL.md (first lines)

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

From NVIDIA/skills, Apache-2.0.

More from NVIDIA/skills