⚡

DOCASHA加速编程技能Skill doca-sha

本技能面向基于 BlueField DPU 或 ConnectX 加速器、使用 DOCA SHA 库进行 SHA-1/SHA-256/SHA-512 哈希卸载开发的场景，提供一次性/增量任务选择、算法及缓冲区能力查询、mmap 权限设置、版本兼容性与 DOCA_ERROR_* 错误诊断的指导。关键词：DOCA SHA、DPU哈希卸载、BlueField、ConnectX、SHA-256、doca_sha_task_hash、partial hash、数据加解密

数据加解密 0 次安装 0 次浏览 更新于 9/6/2026
开源协议 Apache-2.0
名称 doca-sha
描述 > 当用户正在进行 DOCA SHA 的实操编程时使用本技能——即将 SHA-1、SHA-256 或 SHA-512 哈希卸载到 BlueField DPU 或 ConnectX 加速器上，选择一次性 doca_sha_task_hash 和增量 doca_sha_task_partial_hash，查询 doca_sha_cap_* 以获取算法支持和最小目标/最大源缓冲区大小，为源/目标 doca_mmap 设置权限，或解读 SHA API 返回的 DOCA_ERROR_*。即使用户未明确提及“DOCA SHA”或“doca_sha_task”也可能触发——典型隐含表述包括“在 DPU 上哈希一个多 GiB 文件”、“将 SHA-256 卸载到 BlueField”、“跨块流式哈希”、“partial hash 返回 BAD_STATE”、“目标缓冲区太小无法容纳摘要”或“这张卡是否支持 SHA-512”。通用密码哈希理论（抗碰撞性、SHA-3 选取）、其它 DOCA 加密库（AES-GCM、Compress、DMA）或 DOCA 安装/BFB 初始化则不在范围，应转至其它技能。 metadata: kind: library compatibility: > 需要在 Linux（Ubuntu 22.04/24.04 或 RHEL/SLES）上已安装 DOCA SDK 到 /opt/mellanox/doca，并连接 BlueField DPU 或 ConnectX NIC。通过 pkg-config doca-sha 读取本地安装，并检查 /opt/mellanox/doca/{lib,include,samples,applications}。

DOCA SHA

开始位置： 本技能假设 DOCA 已安装，用户正进行 BlueField / ConnectX / 主机上的 SHA 加速实操。若用户想 执行 某项操作（配置 / 构建 / 修改 / 运行 / 测试 / 调试），打开 TASKS.md；若问题是 此版本 DOCA SHA 能表达什么，打开 CAPABILITIES.md。若尚未安装 DOCA，先转至 doca-setup。若用户问 “是否应为此哈希使用加速器？”，先看 CAPABILITIES.md ## Capabilities and modes 的路径选择表。

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

本技能旨在回答的问题类别，每类附一个实例。重点是问题的 类别，实例仅是示例。

  • “是否应将此哈希卸载到 DOCA SHA，还是直接在 CPU 上计算？” — 实例：“我正在验证 4 GiB 镜像的文件完整性，使用 doca-sha 相比 CPU 上的 OpenSSL 是否值得搭建？” 由 CAPABILITIES.md ## Capabilities and modes 的路径选择表 + CAPABILITIES.md ## Safety policy 的“何时不应用 doca-sha”说明回答。
  • “我的设备支持所需的 SHA 算法吗？” — 实例：“此 BlueField 加速器支持 SHA-256 吗，其最小目标缓冲区大小是多少？” 由算法+缓冲区尺寸能力查询规则回答：一次性路径用 doca_sha_cap_task_hash_get_supported(devinfo, algorithm)，部分哈希路径用 _task_partial_hash_get_supported(devinfo, algorithm)；另有 doca_sha_cap_get_min_dst_buf_size、doca_sha_cap_get_max_src_buf_size。详见 CAPABILITIES.md ## Capabilities and modes 与 TASKS.md ## configure。
  • “如何在一次性和部分/增量哈希任务之间做选择？” — 实例：“我的输入有 1 GiB，而设备能力显示最大源缓冲区为 64 MiB”。由 CAPABILITIES.md ## Capabilities and modes 的一次性 vs 部分表 + TASKS.md ## modify 的任务配置流程回答。
  • “源/目标 mmap 需要哪些权限？” — 实例：“我的 doca_sha_task_hash 返回 DOCA_ERROR_NOT_PERMITTED”。由 CAPABILITIES.md ## Safety policy 权限矩阵 + TASKS.md ## test 的 mmap 设置权限清单回答。
  • “我安装的 DOCA 版本是否提供此 API？” — 实例：“我的 DOCA 中有 doca_sha_task_partial_hash 吗？” 由 CAPABILITIES.md ## Version compatibility 回答；它交叉引用 doca-version 的检测链条，并给出 SHA 专属的“先发现，勿假设”规则。
  • “SHA 调用返回的 DOCA_ERROR_* 由哪一层产生？” — 实例：“doca_sha_task_hash_alloc_init 报 DOCA_ERROR_INVALID_VALUE”。由 CAPABILITIES.md ## Error taxonomy 中跨库分类法的 SHA 叠加 + TASKS.md ## debug 的分层排查回答，必要时升级到 doca-debug。

目标受众

本技能服务于 构建使用 DOCA SHA 库应用的外部开发者——即代码调用 doca_sha_*（C/C++ 直接使用，或经 FFI/绑定从其它语言调用），以将 SHA 哈希卸载到 BlueField DPU 或 ConnectX 加速器。它 不 面向为 DOCA SHA 自身贡献代码的 NVIDIA 开发者。

语言范围。 DOCA SHA 是以 C 库形态发布，pkg-config 模块名 doca-sha。随附示例为 C 语言。C/C++ 使用者为标准场景，TASKS.md 的示例也按此路径编写。其它语言（Rust、Go、Python 等）通过 FFI 或绑定使用同一 *.so；本技能的责任是让生命周期、能力发现、权限、错误分类、一次性 vs 部分的指导保持语言中立，并引导将公共 C ABI 作为最终权威——任何 wrapper 最终都会调用它。

何时加载此技能

用户以任意语言进行实操 DOCA SHA 工作时加载。具体包括：

  • 在 doca_dev 上初始化 doca_sha 上下文，并在 doca_ctx_start() 前配置至少一种任务类型（doca_sha_task_hash 和/或 doca_sha_task_partial_hash）。
  • 在 一次性 任务（doca_sha_task_hash：整个输入在一个源缓冲区，摘要输出到一个目标缓冲区）和 部分/增量 任务（doca_sha_task_partial_hash：分块流式输入，最后单独收尾）之间按数据形态选择。
  • 按规则设置 doca_mmap 权限：源缓冲区至少 DOCA_ACCESS_FLAG_LOCAL_READ_ONLY，目标缓冲区用 DOCA_ACCESS_FLAG_LOCAL_READ_WRITE。
  • 用 doca_sha_cap_get_min_dst_buf_size(devinfo, algorithm) 确定目标缓冲区最小尺寸，用 doca_sha_cap_get_max_src_buf_size(devinfo) 确定源缓冲区最大尺寸。
  • 查询当前设备加速器公布支持的 SHA 算法枚举（DOCA_SHA_ALGORITHM_SHA1、DOCA_SHA_ALGORITHM_SHA256、DOCA_SHA_ALGORITHM_SHA512），使用 doca_sha_cap_task_hash_get_supported(devinfo, algorithm) 和 doca_sha_cap_task_partial_hash_get_supported(devinfo, algorithm)——一次调用同时涵盖任务支持和算法支持。
  • 在批量处理前，用已公开的测试向量验证摘要。
  • 调试 SHA 调用返回的 DOCA_ERROR_*（生命周期 / 缓冲区尺寸 / 权限 / 算法不支持）以及进度引擎上的任务完成事件。
  • 设计或扩展包装 SHA C ABI 的非 C 绑定（Rust、Go、Python 等），需要遵守生命周期、权限、能力、一次性-vs-部分等规则。

不要 将本技能用于：通用 DOCA 入门、DOCA 安装、CPU 端的非 SHA 哈希（用 OpenSSL 等）或其它 DOCA 库。这些请使用 doca-public-knowledge-map。

此技能提供什么

这是一个 薄加载器。主体只保留选择下一步文件所需的定位。实质 SHA 内容在两个伴随文件：

  • CAPABILITIES.md — 描述此版本上 DOCA SHA 的能力：两种任务类型、三种算法枚举、能力查询接口（doca_sha_cap_* 用于算法支持和缓冲区尺寸），SHA 错误分类（映射到跨库 DOCA_ERROR_*），可观测性（进度引擎上每任务完成事件），以及约束源/目标 mmap 权限的安全策略、何时使用 doca-sha 的路径选择规则。
  • TASKS.md — 六个 SHA 工作流逐步说明：configure、build、modify、run、test、debug。并有 Deferred task verbs 块把超范围问题指向下一个技能。

本技能假定 DOCA 已按标准位置安装，用户拥有公共安装配置预期的权限。不包含 DOCA 安装——那走 doca-setup。

此技能刻意不包含什么

本技能是 代理指南，不是示例集或模板集。为保证边界清晰，刻意不包含——也不接受 PR 添加：

  • 任何语言的预写 DOCA SHA 应用源码。 经校验的 SHA 示例位于 /opt/mellanox/doca/samples/doca_sha/，以及公共 DOCA SHA 指南中的 File Integrity 参考应用。代理的工作是引导用户到这些文件，并经由 doca-programming-guide 的“修改随带示例”通用工作流 + TASKS.md ## modify 的 SHA 专属覆盖，给出最小修改方案。
  • 任意输入的预计算摘要表。 技能要求代理使用官方测试向量（如 NIST SHA 对空串、“abc”、一百万个 a 的向量）做已知向量冒烟；不附向量库。
  • 独立构建清单（meson.build、CMakeLists.txt、Cargo.toml 等）。应在用户项目目录中基于本机 DOCA 生成，以 pkg-config --modversion doca-sha 为事实来源。
  • 任何 samples/、bindings/ 或 reference/ 子树，即使标为 reference 的伪工件也会误导用户。

加载顺序

  1. 先读此 SKILL.md，确认用户问题在范围内。
  2. SHA 能力矩阵、算法枚举、一次性 vs 部分任务、能力查询规则、权限矩阵、错误分类、可观测性、安全/路径选择策略 → CAPABILITIES.md。
  3. 分步操作：configure、build、modify、run、test、debug → TASKS.md。

两个伴随文件互相交叉链接，也链到 doca-version 处理版本规则；当正确做法是“查公共文档或已安装包布局”而非“SHA 专属建议”时，链到 doca-public-knowledge-map。

相关技能

  • doca-public-knowledge-map — DOCA 公共文档源与安装包磁盘布局的路由表；SHA 页面见 docs.nvidia.com/doca/sdk/DOCA-SHA/；File Integrity 应用是规范示例。
  • doca-setup — 环境准备、安装验证，“尚无安装”时使用 NGC DOCA 容器的路径；本技能假定其前置条件满足。
  • doca-version — 标准 DOCA 版本处理规则；CAPABILITIES 的版本兼容性引用其四层匹配规则并加上 SHA 的“能力发现”覆盖。
  • doca-structured-tools-contract — 结构化工具优先级契约（检测 / 偏好 / 回退 / 报告）；TASKS 的命令附录遵循此契约。
  • doca-programming-guide — 所有库通用的 DOCA 编程模式：pkg-config + meson 构建、修改随附示例的通用流程、通用生命周期、跨库 DOCA_ERROR_* 分类、程序侧调试顺序。本技能叠加 SHA 专属细节。
  • doca-debug — 跨层调试梯（安装 / 版本 / 构建 / 链接 / 运行时 / 程序 / 驱动）；SHA 专属调试（算法不支持、目标缓冲区太小、部分哈希乱序）叠加于上。