doca-erasure-coding

DOCA Erasure Coding

示例

• “磁盘故障了；我能从校验数据重建吗？”——如果布局是 Reed-Solomon N+K，则属于适用范围。规划恢复大小前，先查询 doca_ec_cap_*。
• “一个数据块发生了变化；不重新编码就能更新校验数据吗？”——使用更新任务。不要将此操作转给复制或网络 FEC。

快速解答：能力检查和示例选择

编写代码前，先查询设备：针对所需任务，查询 doca_ec_cap_task_create_is_supported、doca_ec_cap_task_update_is_supported 或 doca_ec_cap_task_recover_is_supported，然后查询 doca_ec_cap_get_max_block_size 和 doca_ec_cap_get_max_buf_list_len 以确定块大小。请从 /opt/mellanox/doca/samples/doca_erasure_coding/ 下该任务随附的示例开始（先复制；切勿修改已安装的示例）。对于发生变化的数据块，使用更新任务刷新校验数据，而不是对所有内容重新编码。

说明

请遵循下方的加载顺序。有关配置／恢复／调试，请打开任务配套文件。有关创建／恢复／更新和矩阵策略，请打开能力配套文件。无需打开所有配套文件。

从这里开始： 此技能假定 DOCA 已安装，且用户正在 BlueField／ConnectX／主机上亲自进行纠删码工作。如果用户想要执行某项操作（配置／构建／修改／运行／测试／调试），请打开任务配套文件；如果问题是此版本的 DOCA Erasure Coding 能表达什么，请打开能力配套文件。如果用户尚未安装 DOCA，请先转到 doca-setup/SKILL.md。如果用户询问*“这里到底该不该用纠删码，还是直接复制数据？”*，请首先查看

Capabilities and modes

中的路径选择规则——纠删码是存储弹性原语（RAID-6／分布式文件系统校验／对象存储纠删码存储桶），不是网络原语，也不能替代复制。

如何使用此技能。 阅读此文件，然后在配套文件中查找问题所需的 ## <name> 标题，并阅读整个章节。仅依据该文件完整作答，只引用其中的符号和命令。不要浏览文档；请使用 doca-public-knowledge-map 中的入口点。将环境检查写成用户 DOCA 主机上执行的命令。对于超出范围的请求，指出负责该请求的技能并停止。

此技能擅长回答的示例问题

此技能旨在回答 DOCA Erasure Coding 问题的各个类别，每类均附有一个完整示例。Agent 应将 类别 视为核心内容——完整示例只是其中一个实例。

• “我应该将此纠删码任务卸载到 DOCA，还是在 CPU 上执行——或者直接复制数据？”——完整示例： “我正在编写一个分布式对象存储，想要在 12 块磁盘上实现类似 RAID-6 的容错能力；doca-erasure-coding 是合适的基本操作吗，还是我应该保留三份副本？”。答案见

  Capabilities and modes 中的路径选择表

  • Safety policy 中的 “何时不应使用 doca-erasure-coding” 要点。

• “我的设备是否支持我想用的 EC 任务类型、块大小、N+K 布局和矩阵类型？”——完整示例：“这台 BlueField 是否支持 doca_ec_task_create，最大块大小是多少，N+K 上限是多少，而且设备是否声明支持 Vandermonde Reed-Solomon 矩阵？”。答案见

  Capabilities and modes 中按任务、矩阵和大小查询能力的规则

  （doca_ec_cap_task_create_is_supported、 _task_recover_is_supported、_task_update_is_supported、 _task_galois_mul_is_supported——这是 EC 加速器上第 4 个公开任务； doca_ec_cap_get_max_block_size、 doca_ec_cap_get_max_buf_list_len，以及各变体的 doca_ec_matrix_create() 构造函数是否成功——公开头文件并未提供 doca_ec_cap_get_matrix_* 系列函数）

  • configure 中的发现步骤。

• “一个源块发生了变化——我必须从头重新计算所有校验块吗？”——完整示例：“我有 8 个数据块和 4 个校验块存储在磁盘上；刚刚重写了一个数据块。如何表达校验块更新，而不必重新运行完整编码？”。答案见

  Capabilities and modes 的任务类型表中

  doca_ec_task_update 对应行

  • Safety policy 中更新与重新编码的规则

  • modify 中用于切换创建任务和更新任务的修改示例插槽。

• “我的 N+K 个块中有 K 个丢失了——如何重建它们？”——完整示例：“一块磁盘发生故障；8 个数据块完好，但 4 个校验块中有 2 个丢失了；DOCA 能恢复它们吗？”。答案见

  Capabilities and modes 的任务类型表中

  doca_ec_task_recover 对应行

  • test 中的恢复冒烟测试（编码 → 丢弃一个块 → 恢复 → 逐位比较）。

• “源/目标 mmap 需要哪些权限？”——完整示例： “我的 doca_ec_task_create 返回了 DOCA_ERROR_NOT_PERMITTED。”。答案见

  Safety policy 中的权限矩阵

  • test 中的 mmap 权限设置检查清单。

• “我安装的 DOCA 版本是否提供此 DOCA Erasure Coding API？”——完整示例：“我安装的 DOCA 是否包含 doca_ec_task_update，还是必须从头重新计算校验块？”。答案见

  Version compatibility 中的版本兼容性补充说明，

  其中交叉链接到 doca-version/SKILL.md 中的规范检测流程，并添加了 EC 专属的 “通过能力查询发现各任务的支持情况和矩阵类型” 要点。
• “EC 调用返回的这个 DOCA_ERROR_* 是什么意思？是哪一层导致的？”——完整示例：“doca_ec_task_create_allocate_init 在 block_size = 4 MiB 时返回 DOCA_ERROR_INVALID_VALUE。”。答案见

  Error taxonomy 中对跨库错误分类的 EC 补充说明

  • debug 中逐层排查的流程，其中会升级到

  doca-debug/SKILL.md。

受众

此技能面向构建使用 DOCA Erasure Coding 库的应用程序的外部开发者——也就是代码调用 doca_ec_*（直接使用 C/C++，或通过其他语言的 FFI/绑定调用），将 Reed-Solomon 纠删码卸载到 BlueField DPU 或 ConnectX 加速器上的用户。此技能不面向为 DOCA Erasure Coding 本身作贡献的 NVIDIA 开发者。

典型应用场景是分布式存储：类似 RAID-6 的块布局、分布式文件系统校验数据、对象存储纠删码存储桶，以及任何使用 N 个数据块 + K 个冗余块模型、并能在同时丢失 K 个块时避免数据丢失的数据持久性工作负载。此技能会让 Agent 始终聚焦于这一领域：纠删码在运作方式上不同于纯复制（保留 M 个完整副本），也不同于作为磁盘布局的 RAID-6（它只是 N=k、K=2 情况的一个具体实例）；混淆这些概念会导致错误的建议。

语言范围。 DOCA Erasure Coding 以 C 库的形式提供，pkg-config 模块名为 doca-erasure-coding。随附的示例使用 C 编写。C 和 C++ 用户是典型情况，任务配套内容中的示例也假设采用此方式。其他语言的用户（Rust、Go、Python 等）通过 FFI 或特定语言的绑定使用同一个 *.so；在这种情况下，此技能会提供与语言无关的生命周期、能力发现、权限、错误分类，以及创建与恢复和更新相关的指导，并引导 Agent 使用公共 C ABI 作为权威接口，因为任何包装层最终都会调用它。

何时加载此技能

当用户正在使用任何语言进行 DOCA Erasure Coding 实操时，加载此技能。具体包括：

• 在 doca_dev 上初始化 doca_ec 上下文，并在调用 doca_ctx_start() 前配置至少一种任务类型（doca_ec_task_create、doca_ec_task_recover 和／或 doca_ec_task_update）。
• 在 create 任务（将 N 个数据块编码为 K 个冗余块）、recover 任务（根据存活的子集重建最多 K 个缺失块）和 update 任务（在一个源块发生变化时增量更新冗余块，开销远低于从头重新编码）之间进行选择。
• 选择编码参数：矩阵类型／编码方案（Reed-Solomon 通常使用 Vandermonde 或 Cauchy）、N（数据块数量）、K（冗余块数量）和块大小（所有块大小必须相同）。
• 为源缓冲区正确设置 doca_mmap 权限：create 任务的源缓冲区为数据块，recover 任务的源缓冲区为数据块和校验块，最低需要设置为 DOCA_ACCESS_FLAG_LOCAL_READ_ONLY；目标缓冲区包括 create 任务的冗余块、recover 任务的恢复块和 update 任务的更新后校验块，需要设置为 DOCA_ACCESS_FLAG_LOCAL_READ_WRITE。
• 根据 doca_ec_cap_get_max_block_size(devinfo) 设置块大小，并根据 doca_ec_cap_get_max_buf_list_len(devinfo, &max_buf_list_len) 设置 N+K。
• 检查此设备的加速器支持哪些任务类型和矩阵方案：调用 doca_ec_cap_task_*_is_supported（包括第 4 种任务 _task_galois_mul_is_supported），并检查每种变体的 doca_ec_matrix_create() 构造函数是否成功；公开头文件并未提供可用于当前 doca_devinfo 的 doca_ec_cap_get_matrix_* 系列函数。
• 在通过加速器处理批量存储数据前，使用已知向量执行 recover 冒烟测试进行验证（编码小型 N + K 布局，模拟一个块丢失，执行恢复，并与原始块逐位比较）。
• 判断何时应使用 update 任务（现有 N + K 布局中的单个源块发生变化时，doca_ec_task_update 的开销远低于通过新的 doca_ec_task_create 重新计算全部 K 个校验块）。
• 调试 EC 调用返回的 DOCA_ERROR_*（生命周期、块大小、N+K、矩阵类型、权限或队列压力问题），以及进度引擎上的任务完成事件。
• 设计或扩展非 C 绑定（Rust、Go、Python 等），用于封装 EC C ABI；封装必须遵守生命周期、权限、能力以及 create、recover、update 任务之间的规则。

以下情况不要加载此技能：一般性的 DOCA 入门、安装 DOCA 本身、非 Reed-Solomon 擦除码（喷泉码、LDPC——这些应使用 CPU 库，而不是 DOCA 加速器）、纯复制／镜像设计（如果多保留一份副本就能解决问题，擦除编码并非合适的基础方案），或其他 DOCA 库。对于这些情况，请使用 doca-public-knowledge-map/SKILL.md。

此技能提供的内容

这是一个轻量加载器。正文只保留了帮助选择下一份文件所需的指引。实质性的 EC 专属内容位于两个配套文件中：

• capabilities 配套文件——说明此版本的 DOCA Erasure Coding 能实现什么：三种任务类型（create / recover / update，各自独立受功能支持情况限制）、矩阵类型 + N + K + 块大小的配置范围、能力查询系列（doca_ec_cap_*，用于查询任务支持情况、最大块大小、最大 N+K、支持的矩阵类型）、EC 错误分类（映射到跨库的 DOCA_ERROR_* 集合）、可观测性范围（通过进度引擎报告每个任务的完成事件）、用于决定源 / 目标 mmap 权限的安全策略，以及路径选择规则（何时使用 doca-erasure-coding、CPU EC 库、纯复制或磁盘上的 RAID-6）。
• tasks 配套文件——针对六种适用的 EC 动词提供分步工作流：configure、build、modify、run、test、debug。此外还有一个 Deferred task verbs 区块，将范围外的问题指向合适的下一项技能。

此技能假定主机或 BlueField 已在标准位置安装 DOCA，且用户具有其公开安装配置所预期的权限。此技能不涉及安装 DOCA——安装流程请参阅 doca-setup/SKILL.md。

此技能有意不包含的内容

此技能是Agent 指引，不是示例或模板合集。为明确边界，此技能有意不包含以下内容，拉取请求也不应添加：

• 任何语言的预编写 DOCA EC 应用程序源代码。 已验证的 EC 源代码是随附的 C 示例，位于 /opt/mellanox/doca/samples/doca_erasure_coding/。Agent 的职责是引导用户找到这些文件，并通过 doca-programming-guide/SKILL.md 中的通用示例修改工作流，在其基础上进行最小差异修改，再叠加 ## modify 中针对 EC 的专属调整。
• 适用于任意 N + K 布局的预计算校验表。 此技能会指引 Agent 在批量处理前，先通过 已知向量 冒烟测试（对固定输入编码一个小型 N + K 布局，模拟丢失一个块，再进行恢复，并逐位与原始数据比较）；但它本身不提供向量库。
• 单独的构建清单（meson.build、CMakeLists.txt、Cargo.toml 等），存放在技能目录中。Agent 会在用户的项目目录中，针对用户已安装的 DOCA 构建清单，其中 pkg-config --modversion doca-erasure-coding 是事实依据。
• 任何形式的 samples/、bindings/ 或 reference/ 子目录。在此技能目录中放置模拟或不完整的产物，即使标注为“reference”，也会造成误导：用户会以为它们可以构建。

加载顺序

1. 首先阅读此技能，确认用户的问题在适用范围内（存储域弹性——N 个数据块 + K 个冗余块），而不是被误归类为纠删码问题的网络或复制问题。
2. 有关 EC 能力矩阵、三种任务类型（create / recover / update）、矩阵类型 + N + K + 块大小的配置范围、能力查询规则、权限矩阵、错误分类、可观测性以及安全 / 路径选择策略，请参阅 capabilities 配套文件。
3. 有关分步工作流——configure、build、modify、run、test、debug——请参阅 tasks 配套文件。

两个配套文件均互相交叉链接，还链接到 doca-version/SKILL.md，以查阅规范的版本处理规则；并在适当答案是“查阅公开文档或已安装的软件包目录结构”而非“EC 专属指引”时，链接到 doca-public-knowledge-map/SKILL.md。

相关技能

• doca-public-knowledge-map/SKILL.md — 所有公开 DOCA 文档来源的路由表，以及已安装 DOCA 软件包的磁盘布局。DOCA Erasure Coding 页面位于 https://docs.nvidia.com/doca/sdk/DOCA-Erasure-Coding/index.html； 安装目录布局（samples 目录、头文件位置） 属于公开知识地图，而非此技能。
• doca-setup/SKILL.md — 环境准备、 安装验证，以及 我还没有安装 的处理路径 （使用公开的 NGC DOCA 容器）。此技能假定 已满足其前置条件。
• doca-version/SKILL.md — DOCA 版本处理的规范规则。此技能的 ## Version compatibility 会链接到四方匹配规则，并仅补充 EC 专属的 “通过 cap 查询发现每项任务的支持情况 + 受支持的矩阵类型 + 最大块大小 + 最大 N+K” 覆盖规则。
• doca-structured-tools-contract/SKILL.md — 此套件的结构化工具优先级规则（检测 / 优先使用 / 回退 / 报告）。任务配套文档中的 Command 附录遵循 此契约。
• doca-programming-guide/SKILL.md — 所有库共用的通用 DOCA 编程模式：规范的 pkg-config + meson 构建模式、通用的 从修改随附示例开始的首个应用工作流、通用生命周期、跨库的 DOCA_ERROR_* 错误分类，以及 程序端调试顺序。此技能在此基础上叠加 EC 专属内容。
• doca-debug/SKILL.md — 跨领域的 调试阶梯（安装 / 版本 / 构建 / 链接 / 运行时 / 程序 / 驱动程序）。EC 专属调试（不支持任务、 不支持矩阵类型、块大小超过上限、N+K 超过上限、 缺失项过多导致无法恢复）叠加在此阶梯之上。