/doca-compress

license: Apache-2.0
name: doca-compress
description: >
  Use this skill for hands-on DOCA Compress programming on a
  BlueField DPU, ConnectX NIC, or host with DOCA — enabling
  compress-deflate, decompress-deflate, decompress-lz4-stream,
  or decompress-lz4-block tasks on a doca_compress context
  (the hardware supports DEFLATE both directions plus LZ4
  decompress; LZ4 encode is NOT supported), sizing source /
  destination doca_buf against the per-task cap query, setting
  mmap permissions, deciding offload vs CPU zlib / zstd,
  validating with a round-trip smoke, or debugging
  DOCA_ERROR_* from a Compress call. Trigger on phrasings
  like "offload this gzip", "decompress incoming network
  data", "compress task returns INVALID_VALUE on alloc_init",
  "submitted a task but no completion arrives", or "decompress
  LZ4 on the BlueField." Refuse and route elsewhere for
  non-DEFLATE / non-LZ4 algorithms (zstd / Snappy / brotli),
  LZ4 encode (route to a CPU LZ4 library), pure mmap-to-mmap
  copies (doca-dma), or DOCA Core lifecycle internals.
metadata:
  kind: library
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}.

DOCA Compress

**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 [`TASKS.md`](TASKS.md) if the user wants to *do* something (configure / build / modify / run / test / debug); open [`CAPABILITIES.md`](CAPABILITIES.md) when the question is *what can DOCA Compress express* on this version. If the user has not installed DOCA yet, route to [`doca-setup`](../../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.md ## Capabilities and modes`](CAPABILITIES.md#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.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)

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

[`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#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.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes)

• the discovery step in

[`TASKS.md ## configure`](TASKS.md#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.md ## Capabilities and modes`](CAPABILITIES.md#capabilities-and-modes) task-type table + the per-task configuration matrix in [`TASKS.md ## configure`](TASKS.md#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 [`CAPABILITIES.md ## Safety policy`](CAPABILITIES.md#safety-policy)

• the mmap-set-permissions checklist in

[`TASKS.md ## test`](TASKS.md#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 [`CAPABILITIES.md ## Version compatibility`](CAPABILITIES.md#version-compatibility), which cross-links the canonical detection chain in [`doca-version`](../../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 [`CAPABILITIES.md ## Error taxonomy`](CAPABILITIES.md#error-taxonomy)

• the layered ladder in

[`TASKS.md ## debug`](TASKS.md#debug) that escalates to [`doca-debug`](../../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