doca-sha

DOCA SHA

例

• 「SHA-256 を BlueField にオフロードする。」 — これは対象範囲内です。SHA-1／SHA-256／SHA-512 のいずれを選ぶか決める前に、同梱の SHA サンプルと 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 に関する質問の種類と、それぞれの回答例です。エージェントは、回答の要となるのは「種類」であり、回答例はその一例にすぎないと捉えてください。

• 「このハッシュ計算を DOCA SHA にオフロードすべきですか。それとも CPU で計算すればよいですか？」 — 回答例：「4 GiB のイメージのファイル整合性を検証しています。CPU で OpenSSL を使う場合と比べて、doca-sha のセットアップに見合う価値はありますか？」。## Capabilities and modes のパス選択表と、## Safety policy の 「doca-sha を使わないほうがよい場合」 の箇条書きで回答します。
• 「デバイスは使いたい SHA アルゴリズムをサポートしていますか？」 — 回答例：「この BlueField のアクセラレーターで SHA-256 は利用できますか。また、そのために必要な宛先バッファーの最小サイズはいくつですか？」。## Capabilities and modes のアルゴリズムおよびバッファーサイズの能力照会ルール（ワンショットパスでは 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 です」。## Capabilities and modes のワンショットと部分ハッシュの比較表、および## modify のタスク設定ワークフローで回答します。
• 「ソース／宛先の mmap にはどのような権限が必要ですか？」 — 回答例：「doca_sha_task_hash が DOCA_ERROR_NOT_PERMITTED を返します」。## Safety policy の権限マトリックスと、## test の mmap 権限設定チェックリストで回答します。
• 「この DOCA SHA API は、インストール済みの DOCA バージョンで利用できますか？」 — 回答例：「インストール済みの DOCA で doca_sha_task_partial_hash は使えますか？」。## Version compatibility のバージョン互換性オーバーレイで回答します。このオーバーレイは doca-version/SKILL.md にある標準の検出手順への相互リンクに加え、SHA 固有の 「仮定せずに検出する」 という箇条書きを追加します。
• 「SHA 呼び出しで返されたこの DOCA_ERROR_* は何を意味し、どのレイヤーで発生したのですか？」 — 回答例：「doca_sha_task_hash_alloc_init で DOCA_ERROR_INVALID_VALUE が発生しました」。## Error taxonomy のライブラリー横断の分類に対する SHA オーバーレイと、doca-debug/SKILL.md へのエスカレーションを含む## debug の段階的な手順で回答します。

対象読者

このスキルは、DOCA SHA ライブラリーを利用するアプリケーションを開発する外部開発者を対象としています。つまり、BlueField-2 の SHA エンジン（BlueField-3 には搭載されていません）に SHA ハッシュ計算をオフロードするため、コードから doca_sha_* を呼び出すユーザーです（C/C++ から直接呼び出す場合、または他の言語から FFI／バインディング経由で呼び出す場合を含みます）。DOCA SHA 自体に貢献する NVIDIA の開発者向けではありません。

対応言語の範囲。 DOCA SHA は、pkg-config のモジュール名が doca-sha の C ライブラリーとして提供されています。付属のサンプルは C で記述されています。C および C++ の利用者が標準的な対象であり、タスクの補足資料にある回答例もこの利用方法を前提としています。他の言語（Rust、Go、Python など）の利用者も、FFI または言語固有のバインディングを介して同じ *.so を使用します。その場合、このスキルではライフサイクル、能力検出、権限、エラー分類、ワンショットと部分ハッシュの使い分けに関するガイダンスを言語に依存しない形で提供し、最終的にあらゆるラッパーが呼び出すことになる、正式なインターフェイスとしての公開 C ABI をエージェントに案内します。

このスキルを読み込むタイミング

ユーザーが使用言語を問わず、DOCA SHA の実作業を行っているときにこのスキルを読み込みます。具体的には、次のような場合です。

• doca_dev 上で doca_sha コンテキストを初期化し、doca_ctx_start() の前に少なくとも 1 種類のタスク（doca_sha_task_hash および／または doca_sha_task_partial_hash）を設定する。
• ユーザーのデータ形状に応じて、ワンショットタスク（doca_sha_task_hash — 入力が単一のソースバッファーに収まり、出力ダイジェストが単一の宛先バッファーに格納される）と、部分／インクリメンタルタスク（doca_sha_task_partial_hash — 入力をチャンク単位でストリーミングし、個別に確定する）のどちらを使うか選択する。
• ソースバッファーには最低限 DOCA_ACCESS_FLAG_LOCAL_READ_ONLY、宛先バッファーには DOCA_ACCESS_FLAG_LOCAL_READ_WRITE を指定し、doca_mmap のアクセス権限を正しく設定する。
• 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 など）を設計または拡張する。ライフサイクル、アクセス権限、機能、ワンショットと部分タスクの選択に関するルールをラッパーで守る必要があります。

一般的な DOCA の概要、DOCA 自体のインストール、CPU 上の SHA 以外のハッシュライブラリー（OpenSSL などを使用）、またはその他の DOCA ライブラリーを扱う場合は、このスキルを読み込まないでください。その場合は doca-public-knowledge-map/SKILL.md を使用してください。

このスキルで提供される内容

これは薄いローダーです。本文には、適切な次のファイルを選ぶために必要な概要のみを記載しています。SHA 固有の詳細な情報は、2 つの関連ファイルにあります。

• capabilities 関連ファイル — このバージョンの DOCA SHA で利用できる機能：2 種類のタスク（ワンショットハッシュと部分／インクリメンタルハッシュ）、3 つのアルゴリズム列挙値、機能照会 API（アルゴリズムのサポートとバッファーサイズに関する doca_sha_cap_*）、SHA エラーの分類（ライブラリー間で共通の DOCA_ERROR_* セットへのマッピング）、観測 API（プログレスエンジン上のタスクごとの完了イベント）、ソース／宛先 mmap のアクセス権限を決める安全ポリシー、パス選択のルール（doca-sha と CPU ハッシュ、または別の DOCA 暗号ライブラリーの使い分け）。
• tasks 関連ファイル — 対象範囲内の 6 つの SHA 動詞（configure、build、modify、run、test、debug）の手順ごとのワークフロー。さらに、対象範囲外の質問を適切な次のスキルに案内する Deferred task verbs ブロックもあります。

このスキルは、DOCA が標準の場所にすでにインストールされ、ユーザーが公開されているインストールプロファイルで想定される権限を持つホストまたは BlueField を前提としています。DOCA のインストールは対象外です。その手順については doca-setup/SKILL.md を参照してください。

このスキルにあえて含めていないもの

このスキルはサンプルやテンプレートのバンドルではなく、エージェント向けガイダンスです。境界を明確にするため、意図的に次の内容は含めていません。また、プルリクエストで追加しないでください。

• DOCA SHA アプリケーションの、あらかじめ作成されたソースコード（言語を問いません）。 検証済みの SHA ソースコードとして提供されているのは、/opt/mellanox/doca/samples/doca_sha/ にある C サンプルと、公開 DOCA SHA ガイドからリンクされている File Integrity リファレンスアプリケーションです。エージェントの役割は、ユーザーをそれらのファイルに案内し、doca-programming-guide/SKILL.md にある汎用のサンプル変更ワークフローを使って、最小限の差分で変更するよう指示することです。さらに、SHA 固有のオーバーライドを ## modify で適用します。
• 任意の入力に対して事前計算されたダイジェストの表。 このスキルでは、既知のベクトルでスモークテストを行うため、公開済みのテストベクトル（空文字列、"abc"、100 万個の a の入力に対する NIST SHA テストベクトルなど）をエージェントが使うよう指示します。独自のベクトルバンクは提供しません。
• スタンドアロンのビルドマニフェスト（meson.build、CMakeLists.txt、Cargo.toml、…）をスキル内に置いたもの。エージェントは、ユーザーがインストールした 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 では、4 つの要素を一致させるルールに相互リンクし、SHA 固有の 「機能クエリでアルゴリズムとバッファーサイズを確認する」 という補足のみを追加しています。
• doca-structured-tools-contract/SKILL.md — バンドルの構造化ツールに関する優先順位ルール（検出／優先／フォールバック／報告）です。タスクに関するコンパニオンのコマンド付録は、この契約に従います。
• doca-programming-guide/SKILL.md — すべてのライブラリで共有される、一般的な DOCA プログラミングパターンです。正規の pkg-config + meson ビルドパターン、提供済みサンプルを変更する汎用の初回アプリケーションワークフロー、汎用のライフサイクル、ライブラリ横断の DOCA_ERROR_* エラー分類、プログラム側のデバッグ順序を扱います。このスキルは、その上に SHA 固有の内容を追加します。
• doca-debug/SKILL.md — インストール／バージョン／ビルド／リンク／実行時／プログラム／ドライバーを対象とする、分野横断的なデバッグ手順です。SHA 固有のデバッグ（アルゴリズム非対応、宛先バッファー不足、部分ハッシュの順序不正）は、この手順に重ねて適用します。