DOCA 文档 v2.10.0
NVIDIA 文档中心  NVIDIA 网络  BlueField DPU / SuperNIC 和 DOCA  DOCA 文档 v2.10.0  DOCA Compress

本页内容

DOCA Compress

本指南提供关于如何使用 DOCA Compress API 的说明。

简介

DOCA Compress 库提供了一个 API，用于使用硬件加速压缩和解压缩数据，同时支持主机和 NVIDIA® BlueField® DPU 内存区域。

该库提供了一个 API，用于在 DOCA 缓冲区上执行压缩操作，这些缓冲区可以位于 DPU 内存或主机内存中。

使用 DOCA Compress，可以以优化的、硬件加速的方式轻松执行压缩和解压缩内存操作。

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

前提条件

DOCA Compress 库遵循 DOCA Core Context 的架构。建议在继续之前阅读以下章节

与之前版本的更改

2.9.0 版本中的更改

不适用

环境

基于 DOCA Compress 的应用程序可以在主机或 BlueField DPU 目标上运行。

Compress 只能在配置为 DPU 模式的 DPU 上运行，如BlueField 操作模式中所述。

架构

DOCA Compress 是 DOCA Core 定义的 DOCA Context。 有关更多信息，请参阅NVIDA DOCA Core Context。

DOCA Compress 利用 DOCA Core 架构来公开异步任务，这些任务被卸载到硬件。

dst-buf-src-buf-version-1-modificationdate-1728202309237-api-v2.png

支持的压缩/解压缩算法

对于 BlueField-2 设备，此库支持

  • 使用 deflate 算法的压缩操作

  • 使用 deflate 算法的解压缩操作

对于 BlueField-3 设备，此库支持

  • 使用 deflate 算法的解压缩操作

  • 使用 LZ4 算法的解压缩操作

支持的校验和方法

根据任务类型，会生成以下校验和方法，并且可以使用相关的 getter 函数检索这些方法

  • Adler – 由 deflate 压缩和解压缩任务生成

  • CRC – 由所有任务生成

  • xxHash – 由 LZ4 解压缩任务生成

有关更多信息，请参阅“任务”部分。

对象

设备和设备表示

该库需要 DOCA 设备才能运行，该设备用于访问内存并执行实际的复制。 有关信息，请参阅DOCA Core 设备发现。

对于同一 BlueField DPU，使用哪个设备（PF/VF/SF）并不重要，因为所有这些设备都使用相同的硬件组件。 如果有多个 DPU，则可以为每个 DPU 创建一个 Compress 实例，为每个实例提供来自不同 DPU 的设备。

要访问非本地内存（从主机到 DPU 或反之），则应用程序的 DPU 端必须选择具有适当表示的设备。 请参阅DOCA Core 设备表示发现。

只要 Compress 实例未被销毁，设备就必须保持有效。

内存缓冲区

所有压缩/解压缩任务都需要两个 DOCA 缓冲区，分别包含目标和源。 根据缓冲区的分配模式，请参阅库存类型表。

在压缩/解压缩操作期间，不得修改或读取缓冲区。

源和目标位置

DOCA Compress 可以处理位于主机、DPU 或两者上的 DOCA 缓冲区。

本地主机

源缓冲区和目标缓冲区都位于主机上，并且压缩库在主机上运行。

本地 DPU

源缓冲区和目标缓冲区都位于 DPU 上，并且压缩库在 DPU 上运行。

远程

主机上的源，DPU 上的目标

  • 源位于主机上，并导出（DOCA mmap 导出）到 DPU

  • 目标位于 DPU 上

  • 压缩库在 DPU 上运行，并将主机源压缩/解压缩到 DPU 目标

DPU 上的源，主机上的目标

  • 源位于 DPU 上

  • 目标位于主机上，并导出（DOCA mmap 导出）到 DPU

  • 压缩库在 DPU 上运行，并将 DPU 源压缩/解压缩到主机目标

配置阶段

要开始使用该库，用户必须经历一个配置阶段，如DOCA Core Context 配置阶段中所述。

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

配置

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

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

强制配置

应用程序必须在尝试启动上下文之前设置以下配置

  • 必须配置至少一个任务/事件类型。 请参阅任务的配置。

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

设备支持

DOCA Compress 需要设备才能运行。 要选择设备，请参阅DOCA Core 设备发现。

由于设备功能在未来可能会发生变化（请参阅DOCA Core 设备支持），建议使用以下 API 选择您的设备

支持的任务

  • doca_compress_cap_task_compress_deflate_is_supported

  • doca_compress_cap_task_decompress_deflate_is_supported

  • doca_compress_cap_task_decompress_lz4_stream_is_supported

  • doca_compress_cap_task_decompress_lz4_block_is_supported

支持的缓冲区大小

  • doca_compress_cap_task_compress_deflate_get_max_buf_size

  • doca_compress_cap_task_decompress_deflate_get_max_buf_size

  • doca_compress_cap_task_decompress_lz4_stream_get_max_buf_size

  • doca_compress_cap_task_decompress_lz4_block_get_max_buf_size

缓冲区支持

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

缓冲区类型

源缓冲区

目标缓冲区

链表缓冲区

是

否

本地 mmap 缓冲区

是

是

来自 PCI 导出缓冲区的 mmap

是

是

来自 RDMA 导出缓冲区的 mmap

否

否


执行阶段

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

任务

任务批处理

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

信息

有关任务批处理的更多信息，请参阅DOCA Core 任务。

DOCA Compress 仅支持 DOCA_TASK_SUBMIT_FLAG_NONE, DOCA_TASK_SUBMIT_FLAG_FLUSH 标志。

Compress Deflate 任务

此任务有助于使用 deflate 算法压缩内存，并使用“缓冲区支持”部分中描述的缓冲区。

注意

DOCA compress 仅返回有效负载。 要创建压缩文件（例如，gzip），开发人员必须添加 gzip 标头/尾部。

任务配置

描述

设置配置的 API

查询支持的 API

启用任务

doca_compress_task_compress_deflate_set_conf

doca_compress_cap_task_compress_deflate_is_supported

任务数

doca_compress_task_compress_deflate_set_conf

doca_compress_get_max_num_tasks（最大总任务数）

最大缓冲区大小

–

doca_compress_cap_task_compress_deflate_get_max_buf_size

最大缓冲区列表大小

–

doca_compress_cap_task_compress_deflate_get_max_buf_list_len


任务输入

如DOCA Core 任务中所述的通用输入。

名称

描述

注释

源缓冲区

指向要压缩的内存的缓冲区

仅压缩数据段中的数据

目标缓冲区

指向将存储压缩内存的位置的缓冲区

数据被压缩到尾部段，从而扩展数据段


任务输出

如DOCA Core 任务中所述的通用输出。

任务完成成功

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

  • 源数据被压缩到目标

  • 目标缓冲区数据段被扩展以包含压缩数据

  • 可以通过调用 doca_compress_task_compress_deflate_get_adler_cs 来检索 Adler

  • 可以通过调用 doca_compress_task_compress_deflate_get_crc_cs 来检索 CRC

任务完成失败

如果任务中途失败

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

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

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

任务限制

  • 该操作不是原子性的

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

  • 源和目标不得重叠

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

Decompress Deflate 任务

此任务有助于使用 deflate 算法解压缩内存，并使用“缓冲区支持”部分中描述的缓冲区。

注意

DOCA decompress 仅期望有效负载。 要解压缩文件（例如 gzip），开发人员必须剥离标头/尾部。

任务配置

描述

设置配置的 API

查询支持的 API

启用任务

doca_compress_task_decompress_deflate_set_conf

doca_compress_cap_task_decompress_deflate_is_supported

任务数

doca_compress_task_decompress_deflate_set_conf

doca_compress_get_max_num_tasks（最大总任务数）

最大缓冲区大小

–

doca_compress_cap_task_decompress_deflate_get_max_buf_size

最大缓冲区列表大小

–

doca_compress_cap_task_decompress_deflate_get_max_buf_list_len


任务输入

如DOCA Core 任务中所述的通用输入。

名称

描述

注释

源缓冲区

指向要解压缩的内存的缓冲区

仅解压缩数据段中的数据

目标缓冲区

指向将存储解压缩内存的位置的缓冲区

数据被解压缩到尾部段，从而扩展数据段


任务输出

如DOCA Core 任务中所述的通用输出。

任务完成成功

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

  • 源数据被解压缩到目标

  • 目标缓冲区数据段被扩展以包含解压缩数据

  • 可以通过调用 doca_compress_task_decompress_deflate_get_adler_cs 来检索 Adler

  • 可以通过调用 doca_compress_task_decompress_deflate_get_crc_cs 来检索 CRC

任务完成失败

如果任务中途失败

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

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

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

任务限制

  • 该操作不是原子性的

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

  • 源和目标不得重叠

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

Decompress LZ4 任务

这些任务有助于使用 LZ4 算法解压缩内存，并使用“缓冲区支持”部分中描述的缓冲区。

任务之间的主要区别在于输入数据格式 –

  • decompress LZ4 stream 任务期望一个或多个块的流，而不包含帧（即，魔数、帧描述符和内容校验和）

  • decompress LZ4 block 任务期望单个、压缩的、仅数据块（即，不包含块大小或块校验和）

Decompress LZ4 Stream 任务

此任务有助于使用 LZ4 算法解压缩内存，并使用“缓冲区支持”部分中描述的缓冲区。

注意

decompress LZ4 stream 任务期望一个或多个块的流，而不包含帧（即，魔数、帧描述符和内容校验和）。

任务配置

描述

设置配置的 API

查询支持的 API

启用任务

doca_compress_task_decompress_lz4_stream_set_conf

doca_compress_cap_task_decompress_lz4_stream_is_supported

任务数

doca_compress_task_decompress_lz4_stream_set_conf

doca_compress_get_max_num_tasks（最大总任务数）

最大缓冲区大小

–

doca_compress_cap_task_decompress_lz4_stream_get_max_buf_size

最大缓冲区列表大小

–

doca_compress_cap_task_decompress_lz4_stream_get_max_buf_list_len


任务输入

如DOCA Core 任务中所述的通用输入。

名称

描述

注释

具有块校验和标志

一个标志，用于指示流中的块是否具有校验和

如果任务应期望流中的块具有校验和，则为 1；否则为 0

块是否独立标志

一个标志，用于指示每个块是否依赖于流中之前的块

如果任务应期望块是独立的，则为 1；否则为 0（相关块）

源缓冲区

指向要解压缩的内存的缓冲区

仅解压缩数据段中的数据

目标缓冲区

指向将存储解压缩内存的位置的缓冲区

数据被解压缩到尾部段，从而扩展数据段


任务输出

如DOCA Core 任务中所述的通用输出。

任务完成成功

任务成功完成后

  • 源数据被解压缩到目标

  • 目标缓冲区数据段被扩展以包含解压缩数据

  • 可以通过调用 doca_compress_task_decompress_lz4_stream_get_crc_cs 来检索 CRC

  • 可以通过调用 doca_compress_task_decompress_lz4_stream_get_xxh_cs 来检索 xxHash

任务完成失败

如果任务中途失败

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

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

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

任务限制

  • 该操作不是原子性的

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

  • 源和目标不得重叠

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

Decompress LZ4 Block 任务

此任务有助于使用 LZ4 算法解压缩内存，并使用“缓冲区支持”部分中描述的缓冲区。

注意

decompress LZ4 block 任务期望单个、压缩的、仅数据块（即，不包含块大小或块校验和）。

任务配置

描述

设置配置的 API

查询支持的 API

启用任务

doca_compress_task_decompress_lz4_block_set_conf

doca_compress_cap_task_decompress_lz4_block_is_supported

任务数

doca_compress_task_decompress_lz4_block_set_conf

doca_compress_get_max_num_tasks（最大总任务数）

最大缓冲区大小

–

doca_compress_cap_task_decompress_lz4_block_get_max_buf_size

最大缓冲区列表大小

–

doca_compress_cap_task_decompress_lz4_block_get_max_buf_list_len


任务输入

如DOCA Core 任务中所述的通用输入。

名称

描述

注释

源缓冲区

指向要解压缩的内存的缓冲区

仅解压缩数据段中的数据

目标缓冲区

指向将存储解压缩内存的位置的缓冲区

数据被解压缩到尾部段，从而扩展数据段


任务输出

如DOCA Core 任务中所述的通用输出。

任务完成成功

任务成功完成后

  • 源数据被解压缩到目标

  • 目标缓冲区数据段被扩展以包含解压缩数据

  • 可以通过调用 doca_compress_task_decompress_lz4_block_get_crc_cs 来检索 CRC

  • 可以通过调用 doca_compress_task_decompress_lz4_bloxk_get_xxh_cs 来检索 xxHash

任务完成失败

如果任务中途失败

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

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

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

任务限制

  • 该操作不是原子性的

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

  • 源和目标不得重叠

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

事件

DOCA Compress 公开异步事件，以根据 DOCA Core 架构通知意外发生的更改。

DOCA Compress 公开的唯一事件是通用事件（DOCA CTX 状态已更改）。 有关更多信息，请参阅DOCA Core 事件。

状态机

DOCA Compress 库遵循DOCA Core Context 状态机中描述的 Context 状态机。

本节介绍如何移动状态以及每个状态允许的操作。

状态

空闲

在此状态下，应用程序应执行以下操作

  • 销毁上下文

  • 启动上下文

允许的操作

  • 根据配置配置上下文

  • 启动上下文

可以通过以下方式达到此状态

之前的状态

转换操作

无

创建上下文

运行中

在确保所有任务都已释放后调用 stop

停止中

调用 progress 直到所有任务都已完成并释放


启动中

无法达到此状态。

运行中

在此状态下，应用程序应执行以下操作

  • 分配和提交任务

  • 调用 progress 以完成任务和/或接收事件

允许的操作

  • 分配先前配置的任务

  • 提交任务

  • 调用 stop

可以通过以下方式达到此状态

之前的状态

转换操作

空闲

配置后调用 start


停止中

在此状态下，应用程序应执行以下操作

  • 调用 progress 以完成所有正在进行的任务（任务将完成并失败）

  • 释放任何已完成的任务

允许的操作

  • 调用 progress

可以通过以下方式达到此状态

之前的状态

转换操作

运行中

调用 progress 且发生致命错误

运行中

调用 stop 而不释放所有任务

替代数据路径选项

DOCA Compress 仅支持 CPU 上的数据路径，请参阅执行阶段。

DOCA Compress 示例

以下示例说明如何使用 DOCA Compress API 来压缩和解压缩文件。

注意

除非使用 zc 标志（仅适用于 deflate 示例），否则 DOCA Compress 仅处理有效负载。 在这种情况下，压缩时会添加 zlib 标头和尾部，并且在解压缩时将其视为输入的一部分。

信息

本节中描述的所有 DOCA 示例均受 BSD-3 软件许可协议管辖。

运行示例

  1. 请参阅以下文档

  2. 要构建给定的示例

    复制
    已复制！
                
    
            
    cd /opt/mellanox/doca/samples/doca_compress/<sample_name>
meson /tmp/build
ninja -C /tmp/build

    信息

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

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

    • 常用参数

      复制
      已复制！
                  
      
            
      Usage: doca_<sample_name> [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
  -f, --file                        Input file to compress/decompress
  -o, --output                      Output file
  -c, --output-checksum             Output checksum

    • 特定于示例的参数

      示例

      参数

      描述

      Compress/Decompress Deflate

      -wf, -with-frame

      写入/读取带有帧的文件，与默认 zlib 设置兼容

      Decompress LZ4 Stream

      -bc, --has-block-checksum

      指示块是否具有校验和的标志

      -bi, --are-blocks-independent

      指示块是否独立的标志

      -wf, -with-frame

      读取与 LZ4 帧兼容的文件

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

    复制
    已复制！
                
    
            
    /tmp/build/doca_<sample_name> -h

示例

Compress/Decompress Deflate

本示例说明如何使用 DOCA Compress 库来压缩或解压缩文件。

示例逻辑包括

  1. 定位 DOCA 设备。

  2. 初始化所需的 DOCA Core 结构。

  3. 使用两个相关缓冲区填充 DOCA 内存映射；一个用于源数据，一个用于结果。

  4. 为每个缓冲区在 DOCA 缓冲区库存中分配元素。

  5. 分配和初始化 DOCA Compress deflate 任务或 DOCA Decompress deflate 任务。

  6. 提交任务。

  7. 运行进度引擎直到任务完成。

  8. 将结果写入输出文件 out.txt。

  9. 销毁所有 DOCA Compress 和 DOCA Core 结构。

参考

  • /opt/mellanox/doca/samples/doca_compress/compress_deflate/compress_deflate_sample.c

  • /opt/mellanox/doca/samples/doca_compress/compress_deflate/compress_deflate_main.c

  • /opt/mellanox/doca/samples/doca_compress/compress_deflate/meson.build

  • /opt/mellanox/doca/samples/doca_compress/decompress_deflate/decompress_deflate_sample.c

  • /opt/mellanox/doca/samples/doca_compress/decompress_deflate/decompress_deflate_main.c

  • /opt/mellanox/doca/samples/doca_compress/decompress_deflate/meson.build

  • /opt/mellanox/doca/samples/doca_compress/compress_common.h

  • /opt/mellanox/doca/samples/doca_compress/compress_common.c

Decompress LZ4 Stream

本示例说明如何使用 DOCA Compress 库来使用 LZ4 stream 解压缩任务解压缩文件。

示例逻辑包括

  1. 定位 DOCA 设备。

  2. 初始化所需的 DOCA Core 结构。

  3. 使用两个相关缓冲区填充 DOCA 内存映射；一个用于源数据，一个用于结果。

  4. 为每个缓冲区在 DOCA 缓冲区库存中分配元素。

  5. 分配和初始化 DOCA Decompress LZ4 stream 任务。

  6. 提交任务。

  7. 运行进度引擎直到任务完成。

  8. 将结果写入输出文件 out.txt。

  9. 销毁所有 DOCA Compress 和 DOCA Core 结构。

参考

  • /opt/mellanox/doca/samples/doca_compress/decompress_lz4_stream/decompress_lz4_stream_sample.c

  • /opt/mellanox/doca/samples/doca_compress/decompress_lz4_stream/decompress_lz4_stream_main.c

  • /opt/mellanox/doca/samples/doca_compress/decompress_lz4_stream/meson.build

  • /opt/mellanox/doca/samples/doca_compress/compress_common.h

  • /opt/mellanox/doca/samples/doca_compress/compress_common.c

向后兼容性

Decompress LZ4 任务

d ecompress LZ4 任务已被删除。 要方便地使用 LZ4 算法解压缩内存，请改为使用 decompress LZ4 stream 任务或 decompress LZ4 block 任务。
© 版权所有 2025 NVIDIA。 上次更新于 2025 年 2 月 12 日。
content here