doca-compress

DOCA Compress

示例

• “将这个 gzip 任务卸载到 BlueField 上。” — 如果编解码器是 DEFLATE（或 LZ4 解压），则属于支持范围。不要臆造 LZ4 编码或 zstd 卸载功能。
• “Compress 任务在 alloc_init 时返回 INVALID_VALUE。” — 在更改算法之前，先根据每任务上限查询结果调整 doca_buf 的大小。

说明

请遵循下方的加载顺序。打开任务配套文件以进行配置／测试／调试。打开能力配套文件以了解编解码器支持和缓冲区大小策略。不要打开所有配套文件。

从这里开始： 此技能假设已安装 DOCA，且用户正在 BlueField／ConnectX／装有 DOCA 的主机上实际操作 Compress（批量 DEFLATE 压缩或解压）。如果用户想要执行某项操作（配置／构建／修改／运行／测试／调试），请打开任务配套文件；如果用户的问题是当前版本的 DOCA Compress 能实现什么功能，请打开能力配套文件。如果用户尚未安装 DOCA，请先转到 doca-setup/SKILL.md。如果用户在问*“我是否应该将此压缩任务卸载到加速器？”*，请首先查看

能力与模式

中的大小阈值路径选择规则——批量压缩是典型适用场景，单次微小任务则不是。

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

此技能旨在回答的 DOCA Compress 问题类别，每类附带一个完整示例。Agent 应将类别视为关键所在——完整示例只是其中一个具体实例。

• “我应该将此压缩任务卸载到 DOCA Compress，还是直接在 CPU 上用 zlib/zstd？” — 完整示例：“我要在将 4 MiB 日志缓冲区写入存储前对其进行压缩；与在 CPU 上用 zlib 相比，doca-compress 值得进行这番设置吗？”。答案见

  能力与模式

  中的大小阈值路径选择规则，以及

  安全策略

  中*“何时不应使用 doca-compress”*的要点。
• “我的设备是否支持我需要的压缩（或解压）任务？每次提交最多能处理多大的缓冲区？” — 完整示例：“这台 BlueField 是否支持 doca_compress_task_compress_deflate，每个任务的最大源数据大小是多少？”。答案见

  能力与模式

  中的每任务能力查询规则（doca_compress_cap_task_compress_deflate_is_supported、 _decompress_deflate_is_supported 以及对应的 _get_max_buf_size 查询），以及

  配置

  中的发现步骤。
• “我只需要解压收到的网络数据——将 doca-compress 单独用于此用途是否有效？” — 完整示例：“我的客户端接收经过 DEFLATE 压缩的有效载荷，但从不生成任何压缩输出。”。答案见

  能力与模式

  的任务类型表中*“仅解压”*的说明，以及

  配置

  第 5 步中的每任务配置矩阵。
• “源／目标 mmap 需要什么权限？” — 完整示例：“我的 doca_compress_task_compress_deflate 返回 DOCA_ERROR_NOT_PERMITTED。”。答案见

  安全策略

  中的权限矩阵，以及

  测试

  中设置 mmap 权限的检查清单。
• “我安装的 DOCA 版本是否提供此 DOCA Compress API？” — 完整示例：“我安装的 DOCA 中是否包含 doca_compress_task_decompress_deflate？”。答案见

  版本兼容性

  中的版本兼容性补充说明，其中交叉引用了 doca-version/SKILL.md 中的规范检测流程，并补充了 Compress 专属的*“发现每任务支持情况，不要想当然”*要点。
• “Compress 调用返回的这个 DOCA_ERROR_* 是什么意思？是哪个层导致的？” — 完整示例：“doca_compress_task_compress_deflate_alloc_init 返回 DOCA_ERROR_INVALID_VALUE。”。答案见

  错误分类

  中针对跨库分类法的 Compress 补充说明，以及

  调试

  中会逐步升级处理、最终转至 doca-debug/SKILL.md 的分层阶梯。

受众

此技能面向使用 DOCA Compress 库构建应用的外部开发者——也就是说，他们的代码会调用 doca_compress_*（直接使用 C/C++，或通过其他语言的 FFI/绑定），将批量 DEFLATE 压缩或解压任务卸载到 BlueField DPU 或 ConnectX 加速器。此技能不面向为 DOCA Compress 本身做贡献的 NVIDIA 开发者。

语言范围。 DOCA Compress 以 C 库形式提供，pkg-config 模块名称为 doca-compress。随附的示例使用 C 编写。C 和 C++ 是最典型的使用场景，任务配套材料中的示例也以此为前提。其他语言的使用者（Rust、Go、Python 等）通过 FFI 或特定语言绑定使用相同的 *.so；在这种情况下，此技能要做的是确保生命周期、能力发现、权限、错误分类，以及压缩与解压相关的指导与语言无关，并引导 Agent 将公共 C ABI 作为权威接口，最终所有封装器都会调用此接口。

何时加载此技能

当用户使用任何语言实际操作 DOCA Compress 时，加载此技能。具体包括：

• 在 doca_dev 上初始化 doca_compress 上下文，并在 doca_ctx_start() 前至少配置一种任务类型（doca_compress_task_compress_deflate 和／或 doca_compress_task_decompress_deflate）。
• 根据用户的数据流，在压缩任务和解压任务之间做出选择。两种任务类型彼此独立：只解压入站 DEFLATE 负载的使用者完全可行，无需启用压缩任务。
• 为 doca_mmap 正确设置权限：源缓冲区至少需要 DOCA_ACCESS_FLAG_LOCAL_READ_ONLY，目标缓冲区需要 DOCA_ACCESS_FLAG_LOCAL_READ_WRITE。
• 根据每种任务对应的 doca_compress_cap_task_*_get_max_buf_size(devinfo) 上限确定源缓冲区大小，并根据算法对此输入可能产生的最坏情况输出大小确定目标缓冲区大小。
• 通过 doca_compress_cap_task_compress_deflate_is_supported 和 doca_compress_cap_task_decompress_deflate_is_supported，检查该设备的加速器针对当前 doca_devinfo 支持哪些任务类型。
• 在将批量输入交由加速器处理前，使用往返测试验证（压缩 → 解压，或解压 → 与已知的 DEFLATE 编码样本比较）。
• 决定是否需要卸载任务——## 能力与模式中的大小阈值规则指出，doca-compress 只适用于批量输入（经验法则：≥ 数 KiB）；对于更小的输入，CPU 压缩速度更快，因为无需承担 DMA 到加速器的往返开销。
• 调试 Compress 调用返回的 DOCA_ERROR_*（生命周期、缓冲区大小、权限或不支持的任务），以及进度引擎上的任务完成事件。
• 设计或扩展封装 Compress C ABI 的非 C 绑定（Rust、Go、Python 等），并确保封装器遵循生命周期、权限、能力以及压缩与解压相关的规则。

对于一般的 DOCA 介绍、DOCA 本身的安装、在 CPU 上使用的非 DEFLATE 压缩库（使用 zlib、zstd 等），或其他 DOCA 库，不要加载此技能。对于这些情况，请使用 doca-public-knowledge-map/SKILL.md。

此技能提供的内容

这是一个轻量加载器。正文仅保留用于选择合适下一份文件所需的指引。特定于 Compress 的实质内容位于两个配套文件中：

• capabilities 配套文件——说明当前版本的 DOCA Compress 能实现什么：四种任务类型（compress-deflate、decompress-deflate、decompress-lz4-stream 和 decompress-lz4-block，每种任务类型均由独立的能力检查控制）、按任务划分的能力查询接口（用于查询任务支持情况和每次提交的最大缓冲区大小的 doca_compress_cap_*）、Compress 错误分类（映射到跨库的 DOCA_ERROR_* 集）、可观测性接口（进度引擎上的按任务完成事件）、用于控制源／目标 mmap 权限决策的安全策略，以及大小阈值路径选择规则（何时使用 doca-compress，而不是 CPU 压缩；以及在无需压缩、仅需复制时何时使用 doca-dma）。
• tasks 配套文件——涵盖六种适用的 Compress 操作的分步工作流：configure、build、modify、run、test、debug。此外还包括 ## rollback 覆盖章节（Compress 专用的五步拆除流程：在调用 doca_ctx_stop 前排空正在执行的任务，按注册顺序的反向顺序注销 mmap 区域，并通过往返冒烟测试重新验证设备路径），以及附加到 ## debug 的五阶段通用调试循环实例。另有一个 Deferred task verbs 区块，指出超出范围的问题应转到哪个后续技能。

本技能假设主机或 BlueField 已在标准位置安装 DOCA，且用户拥有其公开安装配置所要求的权限。本技能不涵盖安装 DOCA——相关流程请参阅 doca-setup/SKILL.md。

本技能有意不提供的内容

本技能是Agent 指引，而非示例或模板包。为明确划分范围，本技能有意不包含以下内容——也不应通过拉取请求添加：

• 预先编写的 DOCA Compress 应用程序源代码（任何语言均不例外）。 已验证的 Compress 源代码是 /opt/mellanox/doca/samples/doca_compress/ 中随附的 C 示例，以及公共 DOCA Compress 指南链接的文件压缩参考应用程序。Agent 的职责是引导用户找到这些文件，并通过 doca-programming-guide/SKILL.md 中的通用修改示例工作流，结合 ## modify 中特定于 Compress 的覆盖要求，对这些文件进行最小差异修改。
• 适用于任意输入的预编码 DEFLATE 测试数据。 本技能会指导 Agent 使用往返验证作为已知良好的冒烟测试（压缩 → 解压并与原始数据比较，或解压由公开发布的 CPU 编码器（如 zlib）生成的已知 DEFLATE 数据块）；本技能不会提供自己的测试数据集。
• 独立的构建清单（meson.build、CMakeLists.txt、Cargo.toml……）。Agent 会在用户的项目目录中，针对用户已安装的 DOCA 构建清单；其中 pkg-config --modversion doca-compress 是权威信息来源。
• 任何形式的 samples/、bindings/ 或 reference/ 子目录。 即使标注为“参考”的模拟或不完整内容放在本技能的目录树中也会造成误导：用户会误以为它可以构建。

加载顺序

1. 首先阅读此技能，确认用户的问题属于其适用范围。
2. 如需了解 Compress 能力矩阵、压缩／解压缩任务划分（包括作为独立形式的仅解压缩）、各任务的能力查询规则、权限矩阵、错误分类、可观测性以及安全／路径选择策略，请参阅能力配套文档。
3. 如需了解配置、构建、修改、运行、测试和调试的分步工作流，请参阅任务配套文档。

这两个配套文件互相链接，也链接到规范版本处理规则所在的 doca-version/SKILL.md，以及 doca-public-knowledge-map/SKILL.md，供需要“查阅公开文档或已安装的软件包布局”而非“查阅 Compress 专属指南”时使用。

相关技能

• doca-public-knowledge-map/SKILL.md — 所有公开 DOCA 文档源的路由表，以及已安装 DOCA 软件包的磁盘布局。DOCA Compress 页面位于 docs.nvidia.com/doca/sdk/DOCA-Compress/；File Compression 参考应用是规范示例。
• doca-setup/SKILL.md — 环境准备、 安装验证，以及使用公开 NGC DOCA 容器的 尚未安装 路径。此技能假定其前置条件已满足。
• doca-version/SKILL.md — 规范 DOCA 版本处理规则。此技能的 ## Version compatibility 链接到四方匹配规则，并仅补充 Compress 专属的 “通过能力查询发现各任务的支持情况和各任务的最大缓冲区大小”。
• doca-structured-tools-contract/SKILL.md — 此工具包的结构化工具优先级规则（检测／优先使用／回退／报告）。任务配套文档中的 Command 附录遵循此约定。
• doca-programming-guide/SKILL.md — 适用于所有库的通用 DOCA 编程模式：规范的 pkg-config + meson 构建模式、通用的先修改已发布示例再创建首个应用的工作流、通用生命周期、跨库 DOCA_ERROR_* 错误分类，以及程序端调试顺序。此技能在此基础上叠加 Compress 专属内容。
• doca-dma/SKILL.md — 当数据流是纯粹的 mmap 到 mmap 复制且不需要压缩时，应使用此库。此技能的路径选择规则会在 Compress 并非合适方案时引导至 DMA（例如，用户只想移动字节，而不想编码）。
• doca-debug/SKILL.md — 跨领域的调试步骤（安装／版本／构建／链接／运行时／程序／驱动）。Compress 专属调试（任务不受支持、源缓冲区过大、目标缓冲区过小）会叠加到这些步骤之上。