doca-compress

# 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 the
worked examples in `TASKS.md` assume that path. Other-language
consumers (Rust, Go, Python, …) consume the same `*.so` through
FFI or language-specific bindings; the skill's contribution in
that case is to keep the lifecycle, capability-discovery,
permission, error-taxonomy, and compress-vs-decompress guidance
language-neutral, and to route the agent to the public C ABI as
the authoritative surface that any wrapper will eventually call.

## When to load this skill

Load this skill when the user is doing hands-on DOCA Compress
work, in any language. Concretely:

- Initializing a `doca_compress` context on a `doca_dev` and
  configuring at least one task type
  (`doca_compress_task_compress_deflate` and/or
  `doca_compress_task_decompress_deflate`) before
  `doca_ctx_start()`.
- Choosing between the **compress** task and the **decompress**
  task for the user's data flow. The two task types are
  independent: a consumer that only decompresses inbound DEFLATE
  payloads is a valid shape and does not need to enable the
  compress task.
- Setting permissions on `doca_mmap` correctly for the source
  buffer (`DOCA_ACCESS_FLAG_LOCAL_READ_ONLY` at minimum) and the
  destination buffer (`DOCA_ACCESS_FLAG_LOCAL_READ_WRITE`).
- Sizing the source buffer against the per-task
  `doca_compress_cap_task_*_get_max_buf_size(devinfo)` ceiling
  and the destination buffer against the