/doca-sha

DOCA SHA capabilities, version overlay, errors, observability, safety

Where to start: Pick the H2 anchor that matches your question (capabilities / version / errors / observability / safety) and read that section end-to-end. The tables in each section are the load-bearing content; the prose around them is interpretation.

Read this file when the loader sent you here from SKILL.md. For the how of executing each pattern (the verbs configure / build / modify / run / test / debug), jump to TASKS.md. For the canonical DOCA version-handling rules that this skill layers a SHA overlay on top of, see doca-version.

Pattern overview

Every DOCA SHA question this skill teaches resolves into one of FIVE patterns. The patterns are CLASSES — they apply across every SHA release and every BlueField / ConnectX device the accelerator runs on.

Two cross-cutting rules that apply to every pattern above:

• Discover the version-installed surface, do not assume. Every pattern above gates on pkg-config --modversion doca-sha and on the doca_sha_cap_* capability queries against the active doca_devinfo. Quoting an algorithm enum, a digest size, or a max source buffer size without checking is the most common hallucination failure mode.
• Validate against a published test vector before bulk. The cheapest way to confirm the configured SHA context produces a correct digest is to hash a small fixed input (e.g. the empty string, "abc", or the million-a input from the NIST SHA test vectors) and compare against the published digest, before submitting any user data.

Capabilities and modes

DOCA SHA is a DOCA Core Context. Every SHA instance follows the universal cfg-create → cfg-set-* → init → start → use → stop → destroy lifecycle (see doca-programming-guide CAPABILITIES.md ## Capabilities and modes). On top of that lifecycle, DOCA SHA layers its own task model and algorithm-selection surface.

The two task types. DOCA SHA exposes two task types; each has its own doca_sha_task_*_set_conf (enable the task) and its own matching doca_sha_cap_task_*_get_supported(devinfo, algorithm) (capability query) entry point. The agent must call the capability query before assuming the task type is available on the user's device.

Path selection — one-shot vs partial / incremental. Both task types can coexist on the same context; choose at least one before doca_ctx_start().

Path-selection — when to use DOCA SHA at all. The agent's rule:

• Use doca-sha when the input is bulk (rule of thumb: ≥ a few hundred KiB), the throughput requirement is high enough that freeing the CPU for other work is valuable, or the input is already pinned in doca_mmap memory because another DOCA library produced it. File integrity verification across many files, content addressing in a deduplication preprocessing pass, and storage workloads are the canonical fits.
• Do NOT use doca-sha when the input is a tiny one-shot hash (the per-call DMA-to-accelerator setup cost dominates; CPU is faster); when the user needs an algorithm not in the device's accelerator (use OpenSSL or a similar CPU library); or when the hash is part of a larger crypto flow that another DOCA library already covers (e.g. AES-GCM authentication tags via doca-aes-gcm).

Algorithm enum — the only public enum. DOCA SHA's algorithm enum surface advertises:

The agent must NOT add algorithm names beyond this enum (no MD5, no SHA-3, no Keccak, no Blake) unless doca_sha_cap_task_hash_get_supported(devinfo, algorithm) returns true for them on the user's device — the enum above is the public surface this skill commits to.

Capability discovery — the only rule. Before choosing an algorithm or sizing any buffer, call the matching doca_sha_cap_* query against the active doca_devinfo:

Configuration shape. Mandatory configurations before doca_ctx_start(): at least one task type enabled via doca_sha_task_hash_set_conf or doca_sha_task_partial_hash_set_conf, and the matching mmap permissions set on both source and destination buffers per the matrix in ## Safety policy. Optional configurations (queue sizing, doca_sha_task_*_set_conf queue depth) use the standard DOCA Core set_* family with defaults coming from the library; query the active value with doca_sha_cap_get_*.

Version compatibility

For the canonical DOCA version-detection chain, the four-way match rule, NGC container semantics, and the headers-win-over-docs rule, see doca-version. The body lives there; this skill does not duplicate it.

The SHA-specific overlay is:

• Algorithm enum membership is device-bound, not version-bound. The agent must not infer "DOCA version X includes SHA-Y" from release notes alone; the runtime authority is doca_sha_cap_task_hash_get_supported(devinfo, DOCA_SHA_ALGORITHM_*) against the active device (which folds task-support and algorithm-support into a single call). Per the cross-cutting cap-query rule in doca-version CAPABILITIES.md ## Observability, the cap query is the runtime authority — never quote an algorithm as available from agent memory.
• doca_sha_task_partial_hash is newer than the one-shot task. When the user reports "the partial-hash API I'm reading about isn't on my install", the first hypothesis is that the install pre-dates partial-hash support. Confirm via doca_sha_cap_task_partial_hash_get_supported(devinfo, algorithm) for each algorithm the user needs; if it returns anything other than DOCA_SUCCESS, route to doca-version TASKS.md ## debug before invoking the partial-hash codepath.
• doca-sha.pc plus doca-common.pc must both match doca_caps --version at the four-way-match check (per doca-version CAPABILITIES.md ## Version compatibility). A common partial-install pattern on hosts where the SHA package was installed separately from the rest of DOCA is that doca-sha.pc reports release X while doca-common.pc reports release Y; route to doca-version TASKS.md ## debug layer 2 before any SHA-layer diagnosis.

Error taxonomy

SHA-specific overlays on the cross-library DOCA_ERROR_* taxonomy. The cross-library taxonomy itself lives in doca-programming-guide CAPABILITIES.md ## Error taxonomy; the rows below are the SHA surface meaning that the agent must disambiguate before falling back to the cross-library response.

The agent's rule: never recommend a retry loop on DOCA_ERROR_* without first identifying which of the rows above is the cause. _AGAIN is the only one that wants a retry (after doca_pe_progress()); the others want investigation, not retry.

Observability

DOCA SHA observability is event-driven, not poll-driven. Every submitted task produces a completion event on the DOCA Core progress engine; there are no SHA-specific counters the way Flow has per-pipe counters.

Three primary signals the agent should reach for:

1. Task completion events on the PE. Every submitted SHA task (one-shot or partial) produces a completion event when it finishes (or errors). The completion carries the doca_error_t if it failed; the agent must inspect the per-task completion, not the doca_task_submit() return value alone. Submitted but no completion is almost always a missed doca_pe_progress() call in the user's main loop.
2. Capability snapshot at configure time. The output of every doca_sha_cap_* query is a snapshot of what the device's accelerator said was possible before any task was submitted. Save it as the baseline; if a task later returns DOCA_ERROR_NOT_SUPPORTED or DOCA_ERROR_INVALID_VALUE the diff against this snapshot is the bug.
3. Known-vector digest comparison. The cheapest correctness signal is to hash a small fixed input (a published NIST SHA test vector — the empty string, "abc", or the million-a input) and compare against the published digest. If the accelerator produces a different digest, the configuration is wrong; do not move on to bulk input.

For cross-cutting observability primitives (--sdk-log-level, the doca-<lib>-trace build flavor, the DOCA_LOG_LEVEL env var) see doca-debug CAPABILITIES.md ## Observability. For the install-tree observability (logger names, package layout) defer to doca-public-knowledge-map.

Safety policy

Overlay on the bundle-wide hardware-safety meta-policy. The rules below are this skill's per-artifact overlay on the cross-cutting rules in doca-hardware-safety CAPABILITIES.md ## Safety policy (specifically ### Per-artifact overlay pattern). When the two layers disagree, the stricter wins; when either layer says STOP, the agent stops.

DOCA SHA's safety surface is buffer-permission discipline plus path-selection discipline. The library reads from a source buffer and writes a digest into a destination buffer; an incorrect permission flag on either side surfaces as a submit-time error rather than silent corruption — but only when the matrix is correct. The agent's job is to verify both permission and the should I use the accelerator at all question before any submission.

The permission matrix the agent must walk for any new SHA setup:

Path-selection — when NOT to use doca-sha. Equally important:

• Tiny one-shot hashes. A single 64-byte hash on the CPU is faster than the DMA-to-accelerator setup. The agent should recommend doca-sha only when the input is ≥ a few hundred KiB or repeated, or the input is already pinned in doca_mmap memory because another DOCA library produced it.
• Unsupported algorithm. If doca_sha_cap_task_hash_get_supported(devinfo, algorithm) returns anything other than DOCA_SUCCESS for the user's intended algorithm on the active device, the answer is to use OpenSSL (or a similar CPU library), not to invent a partial-hash workaround.
• Hash is part of a larger crypto flow. If the user is computing the hash only to feed it into AES-GCM or a similar authenticated-encryption mode that DOCA already implements, doca-aes-gcm covers the combined surface; layering doca-sha on top is redundant.

The mmap must stay valid until the SHA context is destroyed. Destroying either the source or destination mmap before doca_ctx_destroy() is a use-after-free on the library's bookkeeping; symptoms include DOCA_ERROR_BAD_STATE from subsequent calls and undefined behavior on outstanding tasks.

Validate against a known vector BEFORE bulk submission. A single known-vector smoke (one short input with a published digest) catches algorithm mis-selection, endian assumptions, and buffer-sizing bugs before they corrupt a multi-GiB result.

Deferred topic boundaries

This skill scopes itself to the DOCA SHA library. Adjacent topics the agent will get asked but should route elsewhere:

• General cryptographic hash function background (collision resistance, length extension, why SHA-1 is deprecated for signatures, when SHA-3 is preferred) — outside this skill. Route to upstream NIST / IETF cryptography documentation; this skill assumes the user already knows which algorithm they want and is asking how to express it through the DOCA SHA API.
• DOCA Core context and progress engine internals — owned by doca-programming-guide. This skill uses the Core context lifecycle; it does not redefine it.
• Cross-cutting DOCA_ERROR_* taxonomy — owned by doca-programming-guide CAPABILITIES.md ## Error taxonomy. This skill adds the SHA overlay, not the taxonomy itself.
• Other DOCA crypto-acceleration libraries (DOCA AES-GCM, DOCA Compress, DOCA DMA) — separate libraries with their own skills (when they ship). Path-selection guidance in ## Capabilities and modes names them; the deep per-library substance lives in the matching skill.
• Cross-library doca_caps invocation patterns — owned by the cross-library doca-caps tool skill (when it ships). This skill references the SHA capability query family (doca_sha_cap_*), which is per-library; the cross-library capability snapshot tool (doca_caps --list-devs) is a separate surface.