doca-erasure-coding

DOCA Erasure Coding

例

• 「ディスクが故障しました。パリティから再構築できますか？」 — レイアウトが Reed-Solomon N+K であれば、対象範囲です。復旧サイズを決める前に doca_ec_cap_* を照会してください。
• 「1 つのデータブロックが変更されました。再エンコードせずにパリティを更新できますか？」 — update タスクを使用してください。これをレプリケーションやネットワーク FEC に振り分けないでください。

クイック回答：機能の確認とサンプルの選択

コードを書く前に、必要なタスクに応じてデバイスに doca_ec_cap_task_create_is_supported、doca_ec_cap_task_update_is_supported、または doca_ec_cap_task_recover_is_supported を照会し、次に doca_ec_cap_get_max_block_size と doca_ec_cap_get_max_buf_list_len を照会してブロックサイズを決めてください。/opt/mellanox/doca/samples/doca_erasure_coding/ にある、そのタスク用の同梱サンプルから始めてください（コピーして使用し、インストール済みのサンプルは編集しないでください）。すべてを再エンコードする代わりに、変更されたブロックのパリティを更新するには update タスクを使用してください。

手順

以下の読み込み順序に従ってください。configure／recover／debug については tasks のコンパニオンを開いてください。create／recover／update とマトリックスポリシーについては capabilities のコンパニオンを開いてください。コンパニオンファイルをすべて開かないでください。

最初に確認すること： このスキルは、DOCA がすでにインストールされており、ユーザーが BlueField／ConnectX／DOCA 搭載ホストでイレージャーコーディングを実際に操作していることを前提としています。ユーザーが何かを実行（configure／build／modify／run／test／debug）したい場合は tasks のコンパニオンを開いてください。現在のバージョンでDOCA Erasure Coding が何を表現できるかという質問の場合は capabilities のコンパニオンを開いてください。DOCA がまだインストールされていない場合は、まず doca-setup/SKILL.md に案内してください。ユーザーが**「ここではイレージャーコーディングを使うべきか、それともデータをレプリケーションするだけにすべきか」と尋ねている場合は、## Capabilities and modes にある方式選択のルールを最初に確認してください。イレージャーコーディングはストレージの耐障害性**のためのプリミティブ（RAID-6／分散ファイルシステムのパリティ／オブジェクトストレージのイレージャーコーディングバケット）であり、ネットワークのプリミティブでも、レプリケーションの代替でもありません。

このスキルの使い方。 このファイルを読み、次に質問に必要な ## <name> 見出しをコンパニオンファイル内で検索し、そのセクション全体を読んでください。回答はその内容だけを根拠にし、記号とコマンドのみを引用してください。ドキュメントは参照せず、doca-public-knowledge-map にあるエントリーポイントを使用してください。環境の確認には、ユーザーの DOCA ホストで実行するコマンドを示してください。対象範囲外の依頼については、担当するスキルを示してそこで終了してください。

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

このスキルが回答するよう構築されている DOCA Erasure Coding に関する質問のクラスと、それぞれの具体例です。エージェントは、回答の要となるのは クラス であり、具体例はその一例にすぎないものとして扱う必要があります。

• 「この消失訂正を DOCA にオフロードすべきですか、それとも CPU で処理すべきですか。それとも、データを複製するだけにすべきですか？」 — 具体例： 「12 台のディスクにまたがって RAID-6 のような耐障害性を確保する分散オブジェクトストアを書いています。doca-erasure-coding は適切なプリミティブですか、それとも 3 つのコピーを保持するだけにすべきですか？」。回答は、## Capabilities and modes のパス選択表と、## Safety policy の 「doca-erasure-coding を使用すべきでない場合」 の箇条書きで示します。
• 「使用したい EC タスクタイプ、ブロックサイズ、N+K レイアウト、行列タイプをデバイスがサポートしていますか？」 — 具体例：「この BlueField で doca_ec_task_create は使えますか。最大ブロックサイズはいくつですか。N+K の上限はいくつですか。また、デバイスは Vandermonde Reed-Solomon 行列を通知していますか？」。回答は、タスクごと + 行列 + サイズの機能照会ルール（doca_ec_cap_task_create_is_supported、_task_recover_is_supported、_task_update_is_supported、_task_galois_mul_is_supported — EC アクセラレーター上の 4 つ目の公開タスク、doca_ec_cap_get_max_block_size、doca_ec_cap_get_max_buf_list_len、およびバリアントごとの doca_ec_matrix_create() コンストラクターの成功 — 公開ヘッダーには doca_ec_cap_get_matrix_* ファミリーは含まれていません）を ## Capabilities and modes で示し、## configure の検出手順を加えて回答します。
• 「ソースブロックが 1 つ変更されました。パリティを最初からすべて再計算する必要がありますか？」 — 具体例：「ディスク上にデータブロック 8 個 + パリティブロック 4 個があります。データブロックが 1 つ書き換えられました。完全なエンコードを再実行せずにパリティを更新するにはどうすればよいですか？」。回答は、## Capabilities and modes のタスクタイプ表にある doca_ec_task_update の行、## Safety policy の更新と再エンコードの使い分けルール、および ## modify の create タスクと update タスクを切り替えるサンプル変更スロットで示します。
• 「N+K ブロックのうち K 個が失われました。再構築するにはどうすればよいですか？」 — 具体例：「ディスクが故障しました。データブロック 8 個は正常ですが、パリティブロック 4 個のうち 2 個が失われています。DOCA で復元できますか？」。回答は、## Capabilities and modes のタスクタイプ表にある doca_ec_task_recover の行と、## test のリカバリースモークテスト（エンコード → ブロックを破棄 → 復元 → ビット単位で比較）で示します。
• 「ソース／宛先の mmap にはどのような権限が必要ですか？」 — 具体例：「doca_ec_task_create が DOCA_ERROR_NOT_PERMITTED を返します」。回答は、## Safety policy の権限マトリックスと、## test の mmap 権限設定チェックリストで示します。
• 「この DOCA Erasure Coding API は、インストール済みの DOCA バージョンで利用できますか？」 — 具体例：「インストール済みの DOCA に doca_ec_task_update はありますか。それともパリティを最初から再計算する必要がありますか？」。回答は、## Version compatibility のバージョン互換性の補足で示します。これは doca-version/SKILL.md の標準的な検出手順への相互リンクを含み、EC 固有の 「cap クエリでタスクごとのサポート状況 + 行列タイプを検出する」 という箇条書きを追加しています。
• 「EC 呼び出しでこの DOCA_ERROR_* が示す意味と、原因となったレイヤーを教えてください」 — 具体例：「ブロックサイズが 4 MiB のとき、doca_ec_task_create_allocate_init で DOCA_ERROR_INVALID_VALUE が発生しました」。回答は、## Error taxonomy のライブラリー横断的なエラー分類に対する EC の補足と、doca-debug/SKILL.md まで段階的にエスカレーションする ## debug の手順で示します。

対象ユーザー

このスキルは、DOCA Erasure Coding ライブラリを利用するアプリケーションを構築する外部開発者、つまり、BlueField DPU または ConnectX アクセラレーターにリード・ソロモン消失訂正符号処理をオフロードするため、doca_ec_* を直接（C/C++ で）または FFI／バインディング経由（別の言語から）で呼び出すコードを記述するユーザーを対象としています。DOCA Erasure Coding 自体に貢献する NVIDIA の開発者向けではありません。

主な対象領域は分散ストレージです。たとえば、RAID-6 形式のブロック配置、分散ファイルシステムのパリティ、オブジェクトストレージの消失訂正符号化バケット、そして N 個のデータブロックと K 個の冗長ブロックからなるモデルによって、データを失うことなく同時に K 個のブロック損失に耐えられる、あらゆるデータ耐久性ワークロードが該当します。このスキルは、エージェントがその領域に沿って判断できるようにします。消失訂正符号化は、M 個の完全なコピーを保持する単純なレプリケーションとも、N=k、K=2 のケースを具体化した一例にすぎないディスク配置方式である RAID-6 とも、運用上は異なります。これらを混同すると、誤った推奨につながります。

言語の対象範囲。 DOCA Erasure Coding は、pkg-config のモジュール名が doca-erasure-coding の C ライブラリとして提供されています。付属のサンプルは C で記述されています。C および C++ の利用者が主な対象であり、タスクのコンパニオンにある実例もこの利用方法を前提としています。ほかの言語（Rust、Go、Python など）の利用者は、同じ *.so を FFI または言語固有のバインディング経由で利用します。その場合、このスキルでは、ライフサイクル、機能の検出、権限、エラー分類、create-vs-recover-vs-update に関するガイダンスを言語に依存しない形で提供し、最終的にあらゆるラッパーが呼び出すことになる正式な C ABI を権威あるインターフェースとしてエージェントに案内します。

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

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

• doca_dev 上で doca_ec コンテキストを初期化し、doca_ctx_start() の前に少なくとも 1 種類のタスクタイプ（doca_ec_task_create、doca_ec_task_recover、および／または doca_ec_task_update）を設定する。
• create タスク（N 個のデータブロックを K 個の冗長ブロックにエンコードする）、recover タスク（残存するブロック群から最大 K 個の欠損ブロックを再構築する）、update タスク（ソースブロックが 1 つ変更されたときに冗長ブロックを増分更新する。最初から再エンコードするよりはるかに低コスト）のいずれを使うか選択する。
• 符号化パラメーター（行列タイプ／符号化方式。Reed-Solomon では通常 Vandermonde または Cauchy）、N（データブロック数）、K（冗長ブロック数）、ブロックサイズ（すべてのブロックで同じサイズ）を選ぶ。
• ソースバッファー（create のデータブロック、recover のデータ＋パリティ）に対する doca_mmap のアクセス許可（最低でも DOCA_ACCESS_FLAG_LOCAL_READ_ONLY）と、宛先バッファー（create の冗長ブロック、recover の復元ブロック、update の更新済みパリティ）に対するアクセス許可（DOCA_ACCESS_FLAG_LOCAL_READ_WRITE）を正しく設定する。
• ブロックサイズを doca_ec_cap_get_max_block_size(devinfo) に照らして確認し、N+K を doca_ec_cap_get_max_buf_list_len(devinfo, &max_buf_list_len) に照らして確認する。
• doca_ec_cap_task_*_is_supported（4 番目のタスクである _task_galois_mul_is_supported を含む）を使って、このデバイスのアクセラレーターがサポートするタスクタイプと行列方式を確認する。また、バリアントごとに doca_ec_matrix_create() コンストラクターが成功するか確認する。公開ヘッダーには、アクティブな doca_devinfo に対する doca_ec_cap_get_matrix_* 系関数は含まれていません。
• アクセラレーターで大量のストレージデータを処理する前に、既知のベクトルを使った recover のスモークテストで検証する（小規模な N + K レイアウトをエンコードし、1 ブロックの損失をシミュレートして復元し、元のブロックとビット単位で比較する）。
• update タスクが適切なケース（既存の N + K レイアウトでソースブロックが 1 つ変更された場合）を見極める。doca_ec_task_update は、新しい doca_ec_task_create で K 個すべてのパリティブロックを再計算するよりはるかに低コストです。
• EC 呼び出しから返される DOCA_ERROR_*（ライフサイクル、ブロックサイズ、N+K、行列タイプ、アクセス許可、キューの逼迫）や、プログレスエンジン上のタスク完了イベントをデバッグする。
• EC C ABI をラップする非 C バインディング（Rust、Go、Python など）を設計または拡張する。ラッパーは、ライフサイクル、アクセス許可、機能、create／recover／update の選択に関するルールを遵守する必要があります。

一般的な DOCA の概要、DOCA 自体のインストール、Reed-Solomon 以外の消失訂正符号（fountain code、LDPC。これらは DOCA アクセラレーターではなく CPU ライブラリを使います）、純粋なレプリケーション／ミラーリング設計（コピーを 1 つ追加すればよい場合、消失訂正符号は適切な方式ではありません）、またはその他の DOCA ライブラリについては、このスキルを読み込まないでください。これらについては doca-public-knowledge-map/SKILL.md を使用してください。

このスキルで提供する内容

これは薄いローダーです。本文には、次に読むべきファイルを選ぶために必要な概要だけを記載しています。EC 固有の詳しい内容は、次の 2 つの関連ファイルにあります。

• capabilities 関連ファイル — このバージョンの DOCA Erasure Coding で実行できること：3 つのタスクタイプ（create／recover／update。それぞれ個別に機能が有効化されている必要があります）、matrix type + N + K + block size の設定項目、機能照会の一連の API（タスクのサポート状況、最大ブロックサイズ、最大 N+K、サポートされる matrix type を照会する doca_ec_cap_*）、EC エラーの分類（ライブラリ共通の DOCA_ERROR_* セットへのマッピング）、監視機能（進行エンジン上でタスクごとに完了イベントを通知）、ソース／宛先 mmap の権限を判断する安全ポリシー、およびパスの選択ルール（doca-erasure-coding、CPU EC ライブラリ、純粋なレプリケーション、ディスク上の RAID-6 のどれを使うべきか）。
• tasks 関連ファイル — 対象となる 6 つの EC 動詞（configure、build、modify、run、test、debug）の手順を説明するワークフロー。さらに、対象外の質問を適切な次のスキルへ案内する Deferred task verbs ブロックもあります。

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

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

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

• 言語を問わず、あらかじめ作成された DOCA EC アプリケーションのソースコード。 検証済みの EC ソースコードは、/opt/mellanox/doca/samples/doca_erasure_coding/ にある同梱の C サンプルです。エージェントの役割は、ユーザーをそれらのファイルに案内し、doca-programming-guide/SKILL.md の汎用的なサンプル変更ワークフローに、## modify の EC 固有の上書きルールを適用して、変更を最小限に抑えるよう指示することです。
• 任意の N + K 配置に対応する、事前計算済みパリティテーブル。 このスキルでは、バルク処理の前にスモークテストとして、既知のベクトルを使ったスモークを実行するようエージェントに指示します（固定入力から小さな N + K 配置をエンコードし、1 ブロックの損失をシミュレートしてリカバリーし、元データとビット単位で比較します）。独自のベクトル集は含めていません。
• スキル内に置かれたスタンドアロンのビルドマニフェスト（meson.build、CMakeLists.txt、Cargo.toml、…）。エージェントは、ユーザーのプロジェクトディレクトリ内で、ユーザーがインストールした DOCA に対するビルドマニフェストを作成します。その際、pkg-config --modversion doca-erasure-coding を正しい情報源とします。
• 種類を問わず、samples/、bindings/、reference/ のサブツリー。 このスキルのツリーにあるモックや不完全な成果物は、「reference」と表示されていても誤解を招きます。ユーザーがビルド可能なものとして受け取ってしまうためです。

読み込み順序

1. まずこのスキルを読み、ユーザーの質問が対象範囲内（ストレージ領域の耐障害性 — N 個のデータブロック + K 個の冗長ブロック）であり、ネットワークやレプリケーションの質問を誤ってイレージャーコーディングに分類したものではないことを確認します。
2. EC の機能マトリックス、3 つのタスクタイプ（create／recover／update）、matrix type + N + K + block size の設定項目、機能照会のルール、権限マトリックス、エラーの分類、監視機能、安全ポリシー／パス選択ポリシーについては、capabilities 関連ファイルを参照してください。
3. 手順を追ったワークフロー（configure、build、modify、run、test、debug）については、tasks 関連ファイルを参照してください。

どちらの関連ファイルからも、もう一方の関連ファイル、バージョン処理の正式なルールを定める doca-version/SKILL.md、および「EC 固有のガイダンス」ではなく「公開ドキュメントまたはインストール済みパッケージの構成を確認する」ことが適切な回答となる場合の doca-public-knowledge-map/SKILL.md にリンクしています。

関連スキル

• doca-public-knowledge-map/SKILL.md — すべての公開 DOCA ドキュメントソースのルーティングテーブルと、インストール済み DOCA パッケージのディスク上のレイアウトです。DOCA Erasure Coding のページは https://docs.nvidia.com/doca/sdk/DOCA-Erasure-Coding/index.html にあります。インストールツリーのレイアウト（サンプルディレクトリ、ヘッダーの場所）は、このスキルではなく公開ナレッジマップに記載されています。
• doca-setup/SKILL.md — 環境の準備、 インストールの検証、および公開 NGC DOCA コンテナーを使った まだインストールしていない場合 の手順です。このスキルでは、前提条件が満たされていることを想定しています。
• doca-version/SKILL.md — DOCA の 正式なバージョン処理ルールです。このスキルの ## Version compatibility では、4 つの要素を一致させるルールへの相互リンクに加え、EC 固有の 「タスクごとのサポート状況、サポートされる行列の種類、最大ブロックサイズ、cap クエリによる最大 N+K を確認する」 というオーバーレイのみを追加しています。
• doca-structured-tools-contract/SKILL.md — バンドルの構造化ツールの優先順位ルール（検出／優先／フォールバック／報告）です。タスク関連ドキュメントのコマンド付録は、この契約に従います。
• doca-programming-guide/SKILL.md — すべてのライブラリで共有される DOCA の一般的なプログラミングパターンです。正式な pkg-config + meson のビルドパターン、最初のアプリケーションとして付属サンプルを変更する汎用ワークフロー、汎用ライフサイクル、ライブラリ間で共通の DOCA_ERROR_* 分類、プログラム側のデバッグ順序が含まれます。このスキルは、その上に EC 固有の内容を重ねます。
• doca-debug/SKILL.md — 複数の分野にまたがる デバッグ手順（インストール／バージョン／ビルド／リンク／ランタイム／プログラム／ドライバー）です。EC 固有のデバッグ（タスク未対応、行列の種類が未対応、ブロックサイズが上限超過、N+K が上限超過、欠損が多すぎる状態からの復旧）は、この手順に重ねて適用します。