doca-sha

DOCA SHA

示例

• “将 SHA-256 卸载到 BlueField。”——这属于本主题范围。使用随附的 SHA 示例，并在选择 SHA-1 / SHA-256 / SHA-512 之前调用 doca_sha_cap_*。
• “部分哈希返回 BAD_STATE。”——继续使用增量式 doca_sha_task_partial_hash 生命周期；不要在处理过程中切换到 CPU 哈希库。

说明

请遵循下文的加载顺序。打开任务配套文件，了解配置 / 构建 / 运行。打开能力配套文件，了解一次性哈希与部分哈希以及算法支持情况。不要打开所有配套文件。

从这里开始： 本技能假定 DOCA 已安装，且用户正在使用 DOCA 在 BlueField-2 DPU（Arm 侧或其主机）上实际进行 SHA 加速工作。BlueField-3 没有 SHA 引擎。如果用户想要执行某项操作（配置 / 构建 / 修改 / 运行 / 测试 / 调试），请打开任务配套文件；如果用户的问题是关于此版本的 DOCA SHA 能实现什么，请打开能力配套文件。如果用户尚未安装 DOCA，请先转到 doca-setup/SKILL.md。如果用户在问*“我到底该不该用加速器来做这类哈希？”*，请先查看 ## 功能与模式 中的路径选择规则。

如何使用此技能。 阅读本文件，然后在配套文件中搜索问题所需的 ## <name> 标题，并阅读该完整章节。完全依据该章节作答，只引用其中的符号和命令。不要浏览文档；请使用 doca-public-knowledge-map 中的入口。将环境检查写成面向用户 DOCA 主机的命令。对于超出范围的请求，指出负责处理的技能并停止。

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

此技能旨在回答以下 DOCA SHA 问题类别，每类都附有一个完整示例。Agent 应将 类别 视为核心要点——完整示例只是一个具体实例。

• “我应该将这个哈希计算卸载到 DOCA SHA，还是直接在 CPU 上计算？”——完整示例：“我正在验证一个 4 GiB 镜像的完整性；与在 CPU 上使用 OpenSSL 相比，配置 doca-sha 值得吗？”。答案见

  功能与模式

  中的路径选择表，以及

  安全策略

  中的 “何时不应使用 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），以及

  configure

  中的发现步骤。
• “如何选择单次处理哈希任务还是部分／增量哈希任务？”——完整示例：“我的输入是 1 GiB，设备能力上限显示源缓冲区最大为 64 MiB。”。答案见

  功能与模式

  中的单次处理与部分处理对比表，以及

  modify

  中的任务配置工作流。
• “源／目标 mmap 需要哪些权限？”——完整示例：“我的 doca_sha_task_hash 返回了 DOCA_ERROR_NOT_PERMITTED。”。答案见

  安全策略

  中的权限矩阵，以及

  test

  中的 mmap 权限设置检查清单。
• “我安装的 DOCA 版本支持这个 DOCA SHA API 吗？” ——完整示例：“我安装的 DOCA 中有 doca_sha_task_partial_hash 吗？”。答案见

  版本兼容性

  中的版本兼容性说明，其中交叉引用了 doca-version/SKILL.md 中的标准检测流程，并补充了 SHA 专属的 “先发现，不要假设” 条目。
• “SHA 调用返回的这个 DOCA_ERROR_* 是什么意思？是由哪一层导致的？”——完整示例：“doca_sha_task_hash_alloc_init 返回了 DOCA_ERROR_INVALID_VALUE。”。答案见

  错误分类

  中针对跨库错误分类的 SHA 说明，以及

  debug

  中逐层深入的排查步骤；该步骤会升级到 doca-debug/SKILL.md。

适用对象

此技能面向构建使用 DOCA SHA 库的应用程序的外部开发者——也就是代码会（直接在 C/C++ 中，或通过其他语言的 FFI／绑定）调用 doca_sha_*，以将 SHA 哈希计算卸载到 BlueField-2 SHA 引擎上的用户（BlueField-3 不含该引擎）。此技能不面向为 DOCA SHA 本身做贡献的 NVIDIA 开发者。

语言范围。 DOCA SHA 以 C 库的形式提供，pkg-config 模块名为 doca-sha。随附示例使用 C 编写。C 和 C++ 用户是典型情况，任务配套内容中的完整示例也假设采用该路径。其他语言（Rust、Go、 Python，等等）的用户通过 FFI 或特定语言的绑定使用相同的 *.so；在这种情况下，此技能的作用是确保生命周期、能力发现、权限、错误分类，以及单次处理与部分处理相关的指导不受语言限制，并引导 Agent 将公共 C ABI 作为权威接口，因为任何封装最终都会调用该接口。

何时加载此技能

当用户正以任何语言亲自进行 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) 确定源缓冲区大小。
• 通过 doca_sha_cap_task_hash_get_supported(devinfo, algorithm) 和 doca_sha_cap_task_partial_hash_get_supported(devinfo, algorithm)，检查当前设备的加速器支持哪些 SHA 算法枚举（DOCA_SHA_ALGORITHM_SHA1、DOCA_SHA_ALGORITHM_SHA256、DOCA_SHA_ALGORITHM_SHA512）— 这两个调用都会同时检查任务支持情况和算法支持情况。
• 在将批量输入交给加速器处理前，使用已发布的测试向量验证摘要。
• 调试 SHA 调用返回的 DOCA_ERROR_*（生命周期、缓冲区大小、权限或不支持的算法问题），以及进度引擎上的任务完成事件。
• 设计或扩展封装 SHA C ABI 的非 C 语言绑定（Rust、Go、Python 等），并遵循封装必须满足的生命周期、权限、能力和单次与部分任务选择规则。

不要在进行一般 DOCA 概览、安装 DOCA 本身、在 CPU 上使用非 SHA 哈希库（请使用 OpenSSL 或类似工具），或使用其他 DOCA 库时加载此技能。这些情况请使用 doca-public-knowledge-map/SKILL.md。

此技能提供的内容

这是一个轻量加载器。正文仅保留用于选择合适后续文件所需的概述。实质性的 SHA 专属资料位于两个配套文件中：

• 能力配套文件 — 介绍此版本的 DOCA SHA 能实现什么：两种任务类型（单次哈希和部分／增量哈希）、三个算法枚举、能力查询接口（用于算法支持和缓冲区大小的 doca_sha_cap_*）、SHA 错误分类（映射到跨库的 DOCA_ERROR_* 集合）、可观测性接口（进度引擎上的逐任务完成事件）、用于决定源／目标 mmap 权限的安全策略，以及路径选择规则（何时使用 doca-sha，而非 CPU 哈希或其他 DOCA 加密库）。
• 任务配套文件 — 针对六种适用的 SHA 操作提供分步工作流：configure、build、modify、run、test、debug。另有一个 Deferred task verbs 区块，将范围外的问题指向合适的后续技能。

此技能假设主机或 BlueField 上已在标准位置安装 DOCA，且用户拥有其公开安装配置所要求的权限。此技能不介绍 DOCA 的安装 — 该流程请参阅 doca-setup/SKILL.md。

本技能有意不包含的内容

本技能是Agent 指南，不是示例或模板包。为明确界定范围，本技能有意不包含以下内容，且不应通过拉取请求添加：

• **预先编写的 DOCA SHA 应用源代码，不限语言。**经过验证的 SHA 源代码是随附的 C 示例，位于 /opt/mellanox/doca/samples/doca_sha/，以及公共 DOCA SHA 指南链接的 File Integrity 参考应用。Agent 的工作是引导用户找到这些文件，并通过 doca-programming-guide/SKILL.md 中的通用修改示例工作流，在这些文件上进行最小差异修改，再叠加 ## modify 中针对 SHA 的专属覆盖规则。
• **任意输入的预计算摘要表。**本技能会指导 Agent 使用已发布的测试向量（例如 NIST SHA 测试向量中的空字符串、"abc" 和包含一百万个 a 的输入）作为已知向量冒烟测试；本技能本身不附带向量库。
• 独立的构建清单（meson.build、CMakeLists.txt、Cargo.toml，……），放置在技能目录中。Agent 会在用户的项目目录中，基于用户安装的 DOCA 构建清单，其中 pkg-config --modversion doca-sha 是权威依据。
• **任何形式的 samples/、bindings/ 或 reference/ 子目录。**本技能目录中的模拟或不完整产物，即使标为“参考”，也会造成误导：用户会以为它可以构建。

加载顺序

1. 首先阅读本技能，确认用户的问题属于适用范围。
2. 有关 SHA 能力矩阵、算法枚举、一次性与分段任务划分、能力查询规则、权限矩阵、错误分类、可观测性以及安全／路径选择策略，请参阅能力配套文档。
3. 有关分步工作流——配置、构建、修改、运行、测试、调试——请参阅任务配套文档。

两个配套文件相互交叉链接，也链接到包含规范版本处理规则的 doca-version/SKILL.md；若正确答案是“查阅公共文档或已安装软件包的目录布局”而非“SHA 专属指南”，则还会链接到 doca-public-knowledge-map/SKILL.md。

相关技能

• doca-public-knowledge-map/SKILL.md — 所有公共 DOCA 文档来源及已安装 DOCA 软件包磁盘布局的路由表。DOCA SHA 页面位于 docs.nvidia.com/doca/sdk/DOCA-SHA/；File Integrity 参考应用是规范的完整示例。
• doca-setup/SKILL.md — 环境准备、 安装验证，以及使用公共 NGC DOCA 容器的我还没有安装路径。本技能假定这些前提已满足。
• doca-version/SKILL.md — 规范的 DOCA 版本处理规则。本技能的 ## Version compatibility 会交叉链接四方匹配规则，并仅添加 SHA 专属的 *“通过能力查询发现算法和缓冲区大小”*覆盖规则。
• doca-structured-tools-contract/SKILL.md — 本工具包的结构化工具优先级规则（检测／优先使用／回退／报告）。任务配套文档中的命令附录遵循此约定。
• doca-programming-guide/SKILL.md — 所有库共用的通用 DOCA 编程模式：规范的 pkg-config + meson 构建模式、通用的优先修改随附示例来创建第一个应用的工作流、通用生命周期、跨库的 DOCA_ERROR_* 错误分类，以及程序侧调试顺序。本技能在此基础上叠加 SHA 专属内容。
• doca-debug/SKILL.md — 跨领域 调试阶梯（安装／版本／构建／链接／运行时／程序／驱动）。针对 SHA 的调试（不支持算法、目标缓冲区太小、分段哈希顺序错误）会叠加在该阶梯之上。