doca-compress

DOCA Compress

例

• 「この gzip を BlueField にオフロードしてください。」 — コーデックが DEFLATE（または LZ4 の解凍）であれば対象範囲です。LZ4 の圧縮や zstd のオフロードを、できると決めつけないでください。
• 「圧縮タスクが alloc_init で INVALID_VALUE を返します。」 — アルゴリズムを変更する前に、タスクごとの上限を取得し、それに合わせて doca_buf のサイズを設定してください。

手順

以下の読み込み順に従ってください。設定／テスト／デバッグを行う場合は、タスクの補足ファイルを開いてください。コーデックのサポート状況やバッファーサイズのポリシーについては、機能の補足ファイルを開いてください。補足ファイルをすべて開く必要はありません。

最初に確認すること： このスキルは、DOCA がすでにインストールされており、ユーザーが DOCA を使って BlueField／ConnectX／ホスト上で Compress を実際に扱う作業（バルク DEFLATE 圧縮または解凍）を行っていることを前提としています。ユーザーが何かを行いたい場合（設定／ビルド／変更／実行／テスト／デバッグ）はタスクの補足ファイルを開いてください。このバージョンで DOCA Compress が何を実現できるかについての質問には、機能の補足ファイルを開いてください。まだ DOCA をインストールしていない場合は、最初に doca-setup/SKILL.md に案内してください。*「この圧縮処理をアクセラレーターにオフロードすべきか？」*という質問では、

Capabilities and modes

にあるサイズしきい値によるパス選択ルールを最初に確認してください。バルク圧縮は典型的な適用例ですが、小さなデータを一度だけ処理する用途には適していません。

このスキルが適切に回答できる質問の例

このスキルが回答するために作られている DOCA Compress に関する質問の種類と、それぞれの具体例を示します。エージェントは、重要なのは質問の種類であり、具体例はその一例にすぎないと捉えてください。

• 「この圧縮処理を DOCA Compress にオフロードすべきでしょうか。それとも CPU 上で zlib／zstd を使うべきでしょうか？」 — 具体例：「ストレージに書き込む前に 4 MiB のログバッファーを圧縮しています。CPU 上で zlib を使う場合と比べて、doca-compress のセットアップには価値がありますか？」。## Capabilities and modes にあるサイズしきい値によるパス選択ルールと、## Safety policy にある*「doca-compress を使わない場合」*の箇条書きで回答します。
• 「使用したい圧縮（または解凍）タスクはデバイスでサポートされていますか。また、1 回の送信で処理できるバッファーのサイズはどれくらいですか？」 — 具体例：「この BlueField で doca_compress_task_compress_deflate は使えますか。また、タスクごとのソースの最大サイズはいくつですか？」。## Capabilities and modes にあるタスクごとの機能照会ルール（doca_compress_cap_task_compress_deflate_is_supported、_decompress_deflate_is_supported、対応する _get_max_buf_size 照会）と、## configure にある検出手順で回答します。
• 「受信したネットワークデータを解凍するだけです。doca-compress を単独で使うのは有効ですか？」 — 具体例：「クライアントは DEFLATE で圧縮されたペイロードを受信しますが、独自に圧縮データを生成することはありません」。## Capabilities and modes にあるタスク種別の表の*「解凍のみ」*の注記と、## configure step 5 にあるタスクごとの設定マトリクスで回答します。
• 「ソース／宛先の mmap には、どのような権限が必要ですか？」 — 具体例：「doca_compress_task_compress_deflate が DOCA_ERROR_NOT_PERMITTED を返します」。## Safety policy にある権限マトリクスと、## test にある mmap の権限設定チェックリストで回答します。
• 「この DOCA Compress API は、インストール済みの DOCA バージョンで利用できますか？」 — 具体例：「インストール済みの DOCA に doca_compress_task_decompress_deflate はありますか？」。## Version compatibility にあるバージョン互換性の補足で回答します。この補足は、doca-version/SKILL.md にある標準の検出手順を相互参照し、Compress 固有の*「タスクごとのサポートを検出し、決めつけない」*という項目を追加しています。
• 「Compress 呼び出しで返されたこの DOCA_ERROR_* は何を意味し、どの層が原因ですか？」 — 具体例：「doca_compress_task_compress_deflate_alloc_init で DOCA_ERROR_INVALID_VALUE が発生します」。## Error taxonomy にあるライブラリ横断の分類に対する Compress 固有の補足と、doca-debug/SKILL.md にエスカレーションする ## debug の段階的な手順で回答します。

対象読者

このスキルは、DOCA Compress ライブラリを利用するアプリケーションを開発する外部開発者を対象としています。つまり、BlueField DPU または ConnectX アクセラレーターにバルク DEFLATE 圧縮や解凍をオフロードするため、doca_compress_* を呼び出すコードを記述するユーザーです（C/C++ から直接呼び出す場合も、別の言語から FFI／バインディング経由で呼び出す場合も含みます）。DOCA Compress 自体にコントリビュートする NVIDIA の開発者向けではありません。

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

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

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

• doca_dev 上で doca_compress コンテキストを初期化し、doca_ctx_start() の前に少なくとも 1 種類のタスク（doca_compress_task_compress_deflate および／または doca_compress_task_decompress_deflate）を設定する。
• ユーザーのデータフローに応じて、圧縮タスクと解凍タスクのどちらを使うか選択する。2 種類のタスクは独立しています。受信した DEFLATE ペイロードのみを解凍する利用形態も有効であり、圧縮タスクを有効にする必要はありません。
• ソースバッファー（最低限 DOCA_ACCESS_FLAG_LOCAL_READ_ONLY）と宛先バッファー（DOCA_ACCESS_FLAG_LOCAL_READ_WRITE）について、doca_mmap の権限を正しく設定する。
• ソースバッファーのサイズを、タスクごとの doca_compress_cap_task_*_get_max_buf_size(devinfo) の上限以下にし、宛先バッファーのサイズを、アルゴリズムがこの入力に対して生成し得る最悪ケースの出力サイズに合わせる。
• アクティブな doca_devinfo に対して、doca_compress_cap_task_compress_deflate_is_supported と doca_compress_cap_task_decompress_deflate_is_supported を使い、このデバイスのアクセラレーターがどのタスクタイプをサポートしているか確認する。
• バルク入力をアクセラレーターに送る前に、往復テスト（圧縮 → 解凍、または解凍 → 既知の DEFLATE エンコード済みフィクスチャとの比較）で検証する。
• オフロードするかどうかを判断する。## Capabilities and modes に記載されているサイズしきい値のルールによれば、doca-compress が適しているのはバルク入力のみです（目安：数 KiB 以上）。それより小さい場合は、アクセラレーターまで DMA で往復するより CPU 圧縮の方が高速です。
• Compress の呼び出しで返される DOCA_ERROR_*（ライフサイクル、バッファーサイズ、権限、未サポートのタスクのいずれに関するものか）や、プログレスエンジン上のタスク完了イベントをデバッグする。
• Compress C ABI をラップする、C 以外のバインディング（Rust、Go、Python、…）を設計または拡張する。ラッパーは、ライフサイクル、権限、機能、圧縮と解凍に関するルールに従う必要があります。

一般的な DOCA の概要、DOCA 自体のインストール、CPU 上で動作する DEFLATE 以外の圧縮ライブラリ（zlib／zstd など）、または他の DOCA ライブラリについては、このスキルを読み込まないでください。それらについては doca-public-knowledge-map/SKILL.md を使用してください。

このスキルでできること

これは薄いローダーです。本体には、次に適切なファイルを選ぶために必要な概要だけを残しています。Compress 固有の詳細は、次の2つの補助ファイルに記載されています。

• capabilities 補助ファイル — このバージョンで DOCA Compress が実行できる内容：4種類のタスク（compress-deflate、decompress-deflate、decompress-lz4-stream、decompress-lz4-block。各タスクの機能は個別に確認が必要です）、タスクごとの機能クエリ API（タスクのサポート状況と、各送信における最大バッファーサイズを確認する doca_compress_cap_*）、Compress のエラー分類（ライブラリ共通の DOCA_ERROR_* セットへのマッピング）、可観測性の仕組み（プログレスエンジン上のタスクごとの完了イベント）、送信元／送信先 mmap の権限判断を制御する安全ポリシー、およびサイズしきい値に基づくパス選択ルール（doca-compress と CPU 圧縮のどちらを使うか、また圧縮せずにコピーする場合に doca-dma をいつ使うか）。
• tasks 補助ファイル — 対象範囲内の Compress 動詞6つ（configure、build、modify、run、test、debug）の手順を示すワークフロー。さらに、## rollback オーバーレイ（doca_ctx_stop の前に処理中のタスクを完了させ、mmap 領域を登録と逆の順序で登録解除し、ラウンドトリップのスモークテストでデバイスパスを再確認する、Compress 固有の5段階のティアダウン）と、## debug に追加される5段階の汎用デバッグループの具体例も記載されています。また、対象範囲外の質問を適切な次のスキルに案内する Deferred task verbs ブロックもあります。

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

このスキルに意図的に含めていないもの

このスキルはエージェント向けのガイダンスであり、サンプルやテンプレートをまとめたものではありません。範囲を明確に保つため、意図的に次のものを含めていません。プルリクエストでも追加しないでください。

• DOCA Compress アプリケーションのソースコード（言語を問いません）。 検証済みの Compress ソースコードは、同梱されている C サンプル（/opt/mellanox/doca/samples/doca_compress/）と、公開 DOCA Compress ガイドからリンクされている File Compression リファレンスアプリケーションです。エージェントの役割は、ユーザーをそれらのファイルに案内し、doca-programming-guide/SKILL.md の汎用的なサンプル変更ワークフローと、## modify の Compress 固有のオーバーライドを適用して、最小限の差分で変更する方法を指示することです。
• 任意の入力に対する、あらかじめエンコードされた DEFLATE テストデータ。 このスキルでは、既知の正常なスモークテストとしてラウンドトリップ検証（圧縮 → 展開して元データと比較する、または zlib など公開されている CPU エンコーダーで生成した既知の DEFLATE データを展開する）をエージェントに指示します。独自のテストデータ集は含めていません。
• 独立したビルドマニフェスト（meson.build、CMakeLists.txt、Cargo.toml など）。スキル内には配置しません。エージェントは、ユーザーがインストールした DOCA を使い、pkg-config --modversion doca-compress を信頼できる情報源として、ユーザーのプロジェクトディレクトリ内にビルドマニフェストを作成します。
• いかなる種類の samples/、bindings/、reference/ サブツリーも含めません。 このスキルのツリー内にある模擬的または不完全な成果物は、「リファレンス」と表示されていても誤解を招きます。ユーザーがビルド可能なものとして受け取るためです。

読み込み順

1. ユーザーの質問が対象範囲内であることを確認するため、まずこのスキルを読みます。
2. Compress の機能マトリックス、compress / decompress のタスク分割（単独の形式としての decompress のみの場合を含む）、タスクごとの機能クエリのルール、権限マトリックス、エラー分類、可観測性、安全性とパス選択のポリシーについては、機能に関する補足資料を参照してください。
3. 設定、ビルド、変更、実行、テスト、デバッグの手順ごとのワークフローについては、タスクに関する補足資料を参照してください。

どちらの補足ファイルからも、相互のファイル、正式なバージョン処理ルールを記載した doca-version/SKILL.md、および「Compress 固有のガイダンス」ではなく「公開ドキュメントまたはインストール済みパッケージのレイアウトを調べる」が適切な回答となる場合の doca-public-knowledge-map/SKILL.md にリンクしています。

関連スキル

• doca-public-knowledge-map/SKILL.md — すべての公開 DOCA ドキュメントソースと、インストール済み DOCA パッケージのディスク上のレイアウトを示すルーティングテーブルです。DOCA Compress のページは docs.nvidia.com/doca/sdk/DOCA-Compress/ にあります。File Compression リファレンスアプリケーションは、正式な実例です。
• doca-setup/SKILL.md — 環境の準備、 インストールの検証、そして公開 NGC DOCA コンテナを使用する「まだインストールしていない」場合の手順を扱います。このスキルでは、その前提条件が満たされているものとします。
• doca-version/SKILL.md — 正式な DOCA バージョン処理ルールです。このスキルの ## Version compatibility では、4 つの要素を一致させるルールへの相互リンクに加え、「cap query を介してタスクごとのサポート状況とタスクごとの最大バッファーサイズを確認する」という Compress 固有の追加ルールのみを記載しています。
• doca-structured-tools-contract/SKILL.md — このバンドルの構造化ツールにおける優先順位ルール（検出／優先／フォールバック／報告）です。タスクに関する補足資料の Command 付録は、この契約に従います。
• doca-programming-guide/SKILL.md — すべてのライブラリで共通する、一般的な DOCA プログラミングパターンを扱います。正式な pkg-config + meson ビルドパターン、提供サンプルの変更から始める共通の初回アプリケーションワークフロー、共通のライフサイクル、ライブラリ横断の DOCA_ERROR_* 分類、プログラム側のデバッグ順序が含まれます。このスキルは、これらに Compress 固有の内容を追加します。
• doca-dma/SKILL.md — 圧縮が不要で、データフローが mmap から mmap への純粋なコピーである場合に適したライブラリです。このスキルのパス選択ルールでは、Compress が適切な解決策ではない場合（たとえば、ユーザーがエンコードではなく、バイトの移動だけを望んでいる場合）に DMA を選択します。
• doca-debug/SKILL.md — インストール／バージョン／ビルド／リンク／ランタイム／プログラム／ドライバーにまたがる、共通のデバッグ手順です。タスクがサポートされない、ソースバッファーが大きすぎる、宛先バッファーが小さすぎる、といった Compress 固有のデバッグ内容は、この手順に追加されます。