DOCA 纠删码

本指南提供有关如何使用 DOCA 纠删码 API 的说明。

DOCA 纠删码（也称为前向纠错或 FEC）库提供了一个 API，用于使用硬件加速对数据进行编码和解码，同时支持主机和 NVIDIA® BlueField®-3（及更高版本）DPU 内存区域。

DOCA 纠删码通过创建通用冗余片段（备份）来恢复丢失的数据片段。库创建的每个冗余块都可以帮助恢复原始数据中的任何块，以防止片段完全丢失。这增加了数据冗余并减少了数据开销。

该库提供了一个 API，用于在 DPU 或主机内存中的 DOCA 缓冲区上执行纠删码 (EC) 操作。

本文档适用于希望加速其应用程序 EC 内存操作的软件开发人员。

词汇表

以下术语有助于理解本页上的信息

DOCA 纠删码库遵循 DOCA Core Context 的架构，建议先阅读以下部分

• DOCA Core 执行模型

• DOCA Core 设备

• DOCA Core 内存子系统

2.10.0 版本中的更改

不适用

基于 DOCA 纠删码的应用程序可以在主机或 BlueField 目标（NVIDIA® BlueField®-3 及更高版本）上运行。

纠删码可以在配置为 NIC 或 DPU 模式的 BlueField 上运行（如BlueField 运行模式中所述）。

DOCA 纠删码是 DOCA Core 定义的DOCA Context。此库利用 DOCA Core 架构来公开异步任务/事件，这些任务/事件被卸载到硬件。

下图显示了 EC 传输流程的高级视图

1. M 个数据包从源发送（本例中为 8 个）。

2. 在源发送数据包之前，源通过向其添加 T 个冗余数据包（本例中为 4 个）来编码数据。

3. 数据包通过 UDP 协议传输到目的地。某些数据包丢失，并接收到 N' 个数据包（在本例中，丢失了 4 个数据包，接收到 8 个）。

4. 目的地使用所有可用数据包（绿色表示原始数据，红色表示冗余数据）解码数据，并取回 M 个原始数据包。

流程

常规 EC 流程包含以下元素

1. 从数据创建冗余块（EC 创建）。

2. 从更新的数据更新冗余块（EC 更新）。

3. 从冗余块恢复数据块（EC 恢复）。

以下部分检查 M:K（其中 M 是原始数据，K 是冗余）EC。

创建冗余块

用户必须执行以下操作

1. 通过 doca_buf 输入 M 个数据块（填充数据，每个块大小为 B）。

2. 通过 doca_buf 输出 K 个空块（每个块大小为 B）。

3. 使用 DOCA 纠删码通过 doca_buf 创建 M x K 的编码矩阵。

4. 使用 DOCA 纠删码创建任务以获取 K 个输出冗余块。

   注意

   此步骤可以在流用例中重复执行，因为 DPU 不会是恢复或更新点。

恢复块

用户必须执行以下操作

1. 通过 doca_buf 输入 M-L 个原始块（未损坏的块）。

2. 通过 doca_buf 输入 L≤K（任意数量）个冗余块（源自创建/更新任务的冗余块）。

3. 输入位掩码或数组，指示要恢复哪些块。

4. 通过 doca_buf 输出 L 个空块（与数据块大小相同）。

5. 使用 DOCA 纠删码通过 doca_buf 创建 M x L 的恢复编码矩阵（每个位掩码唯一）。

6. 使用 DOCA 纠删码恢复任务以获取 L 个输出恢复的数据块。

对象

设备和设备表示

DOCA 纠删码库需要 DOCA 设备才能运行。该设备用于访问内存并执行编码和解码操作。请参阅DOCA Core 设备发现。

对于同一 Bluefield 卡，使用哪个设备（PF/VF/SF）并不重要，因为所有这些设备都使用相同的硬件组件。如果有多个 DPU，则可以为每个 DPU 创建一个 EC 实例，为每个实例提供来自不同 DPU 的设备。要访问非本地内存（从主机到 DPU，反之亦然），应用程序的 DPU 端必须选择具有适当表示的设备。请参阅DOCA Core 表示设备发现。

设备必须保持有效，直到 EC 实例被销毁。

内存缓冲区

执行任何 DOCA EC 任务都需要两个 DOCA 缓冲区：源缓冲区和目标缓冲区。

根据缓冲区的分配模式，请参阅库存类型表。

在执行任何任务期间，不得修改或读取缓冲区。

要开始使用库，首先，您需要完成配置阶段，如DOCA Core Context 配置阶段中所述。

本节介绍如何配置和启动上下文，以允许执行任务和检索事件。

配置

可以配置上下文以匹配应用程序用例。

要查找是否支持某个配置，或者最小值/最大值是多少，请参阅设备支持。

强制配置

这些配置是强制性的，必须由应用程序在尝试启动上下文之前设置

• 至少需要配置 1 种任务/事件类型。请参阅任务配置。

• 必须在创建时提供具有适当支持的设备。

设备支持

DOCA 纠删码需要设备才能运行。有关选择设备的信息，请参阅DOCA Core 设备发现。

纠删码可以在 BlueField-3 中使用，但有一些限制（请参阅架构）。任何设备都可以使用 PF/VF/SF。

由于设备功能在未来可能会发生变化，因此建议使用以下方法选择您的设备

• doca_ec_cap_task_galois_mul_is_supported

• doca_ec_cap_task_create_is_supported

• doca_ec_cap_task_update_is_supported

• doca_ec_cap_task_recover_is_supported

某些设备可能允许以下不同的功能

• 最大缓冲区列表长度

• 最大块大小

缓冲区支持

任务支持具有以下功能的缓冲区

本节介绍如何使用 DOCA Core Progress Engine 在 CPU 或 DPU 上执行。

矩阵生成

所有任务都需要编码矩阵。

矩阵类型

DOCA EC 提供 2 种矩阵类型，将在以下小节中详细说明。

柯西

柯西编码矩阵的构造方式如下

.

其中

• 

• 

• 

• 

范德蒙

范德蒙编码矩阵的构造方式如下

.

其中

• 

• 

矩阵功能

创建

执行创建任务以创建冗余块时，编码矩阵是必需的。

用于更新和恢复的矩阵基于编码矩阵。

以下小节描述了创建矩阵的可用选项。

通用

通用创建使用 doca_ec_matrix_create() 函数，用于使用库提供的矩阵类型之一进行简单设置。

输入

自定义

自定义创建使用 doca_ec_matrix_create_from_raw() 函数，如果库未提供所需的矩阵类型，则可以使用此函数。

输入

更新

此矩阵是执行更新任务所必需的，以便在数据块发生更改后更新冗余块。

该矩阵使用 doca_ec_matrix_create_update() 函数创建。

输入

恢复

此矩阵是执行恢复任务所必需的，以便恢复原始数据块。

该矩阵使用 doca_ec_matrix_create_recover() 函数创建。

输入

任务

任务批处理

DOCA 纠删码支持任务批处理模式，这是一种任务提交工作模式，允许聚合多个相同类型的 DOCA 任务并将它们作为一个单元处理。

DOCA 纠删码支持标志 DOCA_TASK_SUBMIT_FLAG_NONE, DOCA_TASK_SUBMIT_FLAG_FLUSH 和 DOCA_TASK_SUBMIT_FLAG_OPTIMIZE_REPORTS。

伽罗瓦乘法任务

此任务执行原始块和编码矩阵之间的伽罗瓦乘法。

任务配置

任务输入

如DOCA Core 任务中所述的公共输入。

任务输出

如DOCA Core 任务中所述的公共输出。

任务完成成功

任务成功完成后，会发生以下情况

• 目标缓冲区保存包含所有乘法结果块的序列（例如，dst_block_1、dst_block_2 等）

• 目标缓冲区数据段被扩展以包含结果块

任务完成失败

如果任务中途失败

• 如果发生致命错误，上下文可能会进入停止状态

• 源和目标 doca_buf 对象未被修改

• 目标缓冲区内容可能会被修改

任务限制

• 该操作不是原子的

• 任务提交后，不应从源缓冲区和目标缓冲区读取/写入

• 源缓冲区和目标缓冲区不得重叠

• 其他限制在DOCA Core 任务中描述

创建任务

此任务使用给定的编码矩阵为给定的原始数据块创建冗余块。

任务配置

任务输入

如DOCA Core 任务中所述的公共输入。

任务输出

如DOCA Core 任务中所述的公共输出。

任务完成成功

任务成功完成后，会发生以下情况

• 目标缓冲区保存包含所有冗余块的序列（rdnc_block_1、rdnc_block_2 等）

• 目标缓冲区数据段被扩展以包含冗余块

任务完成失败

如果任务中途失败

• 如果发生致命错误，上下文可能会进入停止状态

• 源和目标 doca_buf 对象未被修改

• 目标缓冲区内容可能会被修改

任务限制

• 该操作不是原子的

• 任务提交后，不应从源缓冲区和目标缓冲区读取/写入

• 源缓冲区和目标缓冲区不得重叠

• 其他限制在DOCA Core 任务中描述

更新任务

此任务使用更新编码矩阵更新给定原始数据块的冗余块。

任务配置

任务输入

如DOCA Core 任务中所述的公共输入。

任务输出

如DOCA Core 任务中所述的公共输出。

任务完成成功

任务成功完成后，会发生以下情况

• 目标缓冲区保存包含更新的冗余块的序列（rdnc_block_1、rdnc_block_2 等）

• 目标缓冲区数据段被扩展以包含更新的冗余块

任务完成失败

如果任务中途失败

• 如果发生致命错误，上下文可能会进入停止状态

• 源和目标 doca_buf 对象未被修改

• 目标缓冲区内容可能会被修改

任务限制

• 该操作不是原子的

• 任务提交后，不应从源缓冲区和目标缓冲区读取/写入

• 源缓冲区和目标缓冲区不得重叠

• 其他限制在DOCA Core 任务中描述

恢复任务

此任务使用给定的可用原始数据块和冗余块以及给定的编码矩阵执行数据块恢复。

任务配置

任务输入

如DOCA Core 任务中所述的公共输入。

任务输出

如DOCA Core 任务中所述的公共输出。

任务完成成功

任务成功完成后，数据将转换为目标。

任务完成失败

如果任务中途失败

• 如果发生致命错误，上下文可能会进入停止状态

• 源和目标 doca_buf 对象未被修改

• 目标缓冲区内容可能会被修改

任务限制

• 该操作不是原子的

• 任务提交后，不应从源缓冲区和目标缓冲区读取/写入

• 源和目标不得重叠

• 可以恢复的块数限制为创建的冗余块数

• 其他限制在DOCA Core 任务中描述

本节提供在 BlueField-3 DPU（及更高版本）之上实现的 DOCA 纠删码示例。

示例先决条件

不适用

运行示例

1. 请参阅以下文档

   • DOCA Linux 安装指南，了解有关如何安装 BlueField 相关软件的详细信息。

   • DOCA 故障排除，了解您在 DOCA 示例的安装、编译或执行中可能遇到的任何问题。

2. 要构建给定的示例

   复制

   已复制！

               
   
               
   cd /opt/mellanox/doca/samples/doca_erasure_coding/<sample_name>
   meson /tmp/build
   ninja -C /tmp/build
           

   信息

   二进制文件 doca_<sample_name> 在 /tmp/build/ 下创建。

3. 示例（例如，doca_erasure_coding_recover）用法

   复制

   已复制！

               
   
               
   Usage: doca_erasure_coding_recover [DOCA Flags] [Program Flags]
    
   DOCA Flags:
     -h, --help                        Print a help synopsis
     -v, --version                     Print program version information
     -l, --log-level                   Set the (numeric) log level for the program <10=DISABLE, 20=CRITICAL, 30=ERROR, 40=WARNING, 50=INFO, 60=DEBUG, 70=TRACE>
     --sdk-log-level                   Set the SDK (numeric) log level for the program <10=DISABLE, 20=CRITICAL, 30=ERROR, 40=WARNING, 50=INFO, 60=DEBUG, 70=TRACE>
     -j, --json <path>                 Parse all command flags from an input JSON file
    
   Program Flags:
     -p, --pci-addr                    DOCA device PCI device address - default: 03:00.0
     -i, --input                       Input file/folder to ec - default: self
     -o, --output                      Output file/folder to ec - default: /tmp
     -b, --both                        Do both (encode & decode) - default: false
     -x, --matrix                      Matrix - {cauchy, vandermonde} - default: cauchy
     -t, --data                        Data block count - default: 2
     -r, --rdnc                        Redundancy block count - default: 2
     -d, --delete-index                Indices of data blocks to delete; comma-separated (i.e., 0,3,4) - default: 0
           

   注意

   当前 BlueField-3 限制

   • 数据块计数范围 – 1-128

   • 冗余块计数 – 1-32

   • 块大小 – 64B-128MB

4. 有关每个示例的更多信息，请使用 -h 选项

   复制

   已复制！

               
   
               
   /tmp/build/doca_<sample_name> -h
           

示例

纠删码恢复

此示例说明如何使用 DOCA 纠删码 (EC) 库来编码和解码文件块（和整个文件）。

示例逻辑包括 3 个步骤

1. 编码 – 创建冗余。

2. 删除 – 模拟灾难。

3. 解码 – 恢复数据。

编码逻辑包括

1. 查找 DOCA 设备。

2. 初始化所需的 DOCA Core 结构，例如进度引擎 (PE)、内存映射和缓冲区清单。

3. 读取源原始数据文件并将其拆分为指定数量的块 <data block count>，为示例指定到输出目录。

4. 使用内存范围填充两个 DOCA 内存映射，一个用于源数据，一个用于结果。

5. 从 DOCA 缓冲区清单为每个内存范围分配缓冲区。

6. 创建 EC 对象。

7. 将 EC 上下文连接到 PE。

8. 为 PE 设置状态更改回调函数，其逻辑如下

   • 打印包含每次状态更改的日志

   • 指示用户可以在 PE 返回空闲状态后停止进度 PE

9. 将配置设置为 EC 创建任务，包括设置回调函数，如下所示

   • 成功完成回调

     1. 将生成的冗余块写入输出目录（计数由 <redundancy block count> 指定）。

     2. 释放任务。

     3. 保存任务和回调的结果。如果在步骤 a. 中出现错误，则保存相关的错误值。

     4. 停止上下文。

   • 失败完成回调

     1. 保存任务和回调的结果。

     2. 释放任务。

     3. 停止上下文。

10. 通过为示例指定的矩阵类型创建 EC 编码矩阵。

11. 分配并提交 EC 创建任务。

12. 推进 PE，直到上下文返回空闲状态，这可能是成功运行（其中所有任务都已成功完成）或致命错误的结果。

13. 销毁所有 EC 和 DOCA Core 结构。

删除逻辑包括

1. 删除使用 <indices of data blocks to delete> 指定的块文件。

解码逻辑包括

1. 查找 DOCA 设备。

2. 初始化所需的 DOCA Core 结构，例如 PE、内存映射和缓冲区清单。

3. 读取输出目录（源剩余数据）并确定块大小以及哪些块丢失（需要恢复）。

4. 使用内存范围填充两个 DOCA 内存映射，一个用于源数据，一个用于结果。

5. 从 DOCA 缓冲区清单为每个内存范围分配缓冲区。

6. 创建 EC 对象。

7. 将 EC 上下文连接到 PE。

8. 为 PE 设置状态更改回调函数，其逻辑如下

   • 打印包含每次状态更改的日志

   • 指示用户可以在 PE 返回空闲状态后停止进度 PE

9. 将配置设置为 EC 恢复任务，包括设置以下回调函数

   • 成功完成回调

     1. 将生成的恢复块写入输出目录。

     2. 将恢复的文件写入输出路径。

     3. 释放任务。

     4. 保存任务和回调的结果。如果在步骤 a. 中出现错误，则保存相关的错误值。

     5. 停止上下文。

   • 失败完成回调

     1. 保存任务和回调的结果。

     2. 释放任务。

     3. 停止上下文。

10. 通过为示例指定的矩阵类型创建 EC 编码矩阵。

11. 使用 doca_ec_matrix_create_recover() 和编码矩阵创建 EC 解码矩阵。

12. 分配并提交 EC 恢复任务。

13. 推进 PE，直到上下文返回空闲状态，这可能是成功运行（其中所有任务都已成功完成）或致命错误的结果。

14. 销毁所有 DOCA EC 和 DOCA Core 结构。

参考

• /opt/mellanox/doca/samples/doca_erasure_coding/doca_erasure_coding_recover/erasure_coding_recover_sample.c

• /opt/mellanox/doca/samples/doca_erasure_coding/doca_erasure_coding_recover/erasure_coding_recover_main.c

• /opt/mellanox/doca/samples/doca_erasure_coding/doca_erasure_coding_recover/meson.build