/doca-compress

license: Apache-2.0
name: doca-compress
description: >
  Hardware compression offload with DOCA Compress on a BlueField DPU,
  ConnectX NIC, or host: DEFLATE compress and decompress, plus LZ4
  decompress (stream and block; LZ4 encode is NOT supported), instead of
  CPU zlib / zstd. Trigger on "offload this gzip", "decompress incoming
  network data on the NIC", "compress task returns INVALID_VALUE on
  alloc_init", "submitted a task but no completion arrives", or
  "decompress LZ4 on the BlueField", even without naming DOCA Compress.
  Covers enabling compress-deflate, decompress-deflate,
  decompress-lz4-stream and decompress-lz4-block tasks on a doca_compress
  context, sizing source / destination doca_buf against the per-task cap
  query, mmap permissions, offload vs CPU decisions, a round-trip smoke,
  and DOCA_ERROR_* from Compress calls. Refuse and route elsewhere for
  zstd / Snappy / brotli, LZ4 encode (a CPU LZ4 library), pure
  mmap-to-mmap copies (doca-dma), or DOCA Core lifecycle internals.
metadata:
  author: NVIDIA <doca-feedback@nvidia.com>
  kind: library
  doca_version: "3.5"
  tags:
    - doca
    - compress
    - deflate
compatibility: >
  Requires DOCA SDK installed at /opt/mellanox/doca on Linux
  (Ubuntu 22.04/24.04 or RHEL/SLES) with a BlueField DPU or
  ConnectX NIC attached. Reads the user's local install via
  `pkg-config doca-compress` and inspects
  /opt/mellanox/doca/{lib,include,samples,applications}.
  The validation steps require a live DOCA install.

DOCA Compress

Examples

• **"Offload this gzip on the BlueField."** — this is in scope if

the codec is DEFLATE (or LZ4 decompress). Do not invent LZ4 encode or zstd offload.

• **"Compress task returns INVALID_VALUE on alloc_init."** — size

the `doca_buf` against the per-task cap query before changing the algorithm.

Instructions

Follow Loading order below. Open the tasks companion for configure / test / debug. Open the capabilities companion for codec support and buffer-size policy. Do not open every companion file.

**Where to start:** This skill assumes DOCA is already installed and the user is doing **hands-on Compress work** (bulk DEFLATE compression or decompression) 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 Compress 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 offload this compression to the accelerator?"*, the size-threshold path-selection rule in

Capabilities and modes

is the first stop — bulk compress is the canonical fit, tiny one-shot is not.

Example questions this skill answers well

The CLASSES of DOCA Compress 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 compression to DOCA Compress, or just

zlib/zstd on the CPU?"** — worked example: *"I am compressing a 4 MiB log buffer before writing it to storage; is doca-compress worth the setup vs zlib on the CPU?"*. Answered by the size-threshold path-selection rule in

Capabilities and modes

• the *"when NOT to use doca-compress"* bullets in

Safety policy.

• **"Does my device support the compress (or decompress) task I

want, and how big a buffer can it move per submission?"** — worked example: *"is `doca_compress_task_compress_deflate` on this BlueField, and what is the max source size per task?"*. Answered by the per-task capability-query rule (`doca_compress_cap_task_compress_deflate_is_supported`, `_decompress_deflate_is_supported`, the matching `_get_max_buf_size` queries) in

Capabilities and modes

• the discovery step in

configure.

• **"I just need to decompress incoming network data — is that a

valid standalone use of doca-compress?"** — worked example: *"my client receives DEFLATE-compressed payloads and never produces any compressed output of its own"*. Answered by the *"decompression-only"* note in

Capabilities and modes

task-type table + the per-task configuration matrix in

configure step 5.

• **"What permissions does the source / destination mmap need?"** —

worked example: *"my `doca_compress_task_compress_deflate` returns `DOCA_ERROR_NOT_PERMITTED`"*. Answered by the permission matrix in

Safety policy

• the mmap-set-permissions checklist in

test.

• **"Is this DOCA Compress API available on my installed DOCA

version?"** — worked example: *"is `doca_compress_task_decompress_deflate` in the DOCA I have installed?"*. Answered by the version-compatibility overlay in

Version compatibility,

which cross-links the canonical detection chain in `doca-version/SKILL.md` and adds the Compress-specific *"discover per-task support, do not assume"* bullets.

• **"What does this `DOCA_ERROR_*` from a Compress call mean and

which layer caused it?"** — worked example: *"`DOCA_ERROR_INVALID_VALUE` on `doca_compress_task_compress_deflate_alloc_init`"*. Answered by the Compress overlay on the cross-library taxonomy in

Error taxonomy

• the layered ladder in

debug that escalates to

`doca-debug/SKILL.md`.

Audience

This skill serves **external developers building applications that consume the DOCA Compress library** — i.e., users whose code calls `doca_compress_*` (directly in C/C++, or through FFI/bindings from another language) to offload bulk DEFLATE compression or decompression onto a BlueField DPU or ConnectX accelerator. It is *not* for NVIDIA developers contributing to DOCA Compress itself.

**Language scope.** DOCA Compress ships as a C library with `pkg-config` module name `doca-compress`. The shipped samples are written in C. C and C++ consumers are the canonical case and th