doca-sta

DOCA STA（ストレージターゲットアクセラレーション）

例

• 「nvmf ターゲットを DPU にオフロードしてください。」 — これは対象範囲内です。doca_sta とサブシステム／名前空間をセットアップしてください。ここではイニシエーターのスタックを書き換えないでください。
• 「RoCE 経由で Identify Controller がタイムアウトします。」 — バックエンドディスクを変更する前に、doca_sta_cap_is_supported とキューのサイズを確認してください。

手順

以下の読み込み順序に従ってください。設定／ターゲット／デバッグについてはタスク用コンパニオンを開いてください。キューの上限と NVMe-oF の機能については、機能用コンパニオンを開いてください。すべてのコンパニオンファイルを開く必要はありません。

まず確認するもの： このスキルは、DOCA がすでにインストールされており、ユーザーが DOCA を使用して BlueField クラスのデバイス上で NVMe-over-Fabrics ストレージターゲットを実際に操作していることを前提としています。ユーザーが何かを実行したい（設定／変更／ビルド／実行／テスト／デバッグ）場合はタスク用コンパニオンを開いてください。このバージョンで DOCA STA が何を表現できるか についての質問には、機能用コンパニオンを開いてください。ユーザーがまだ DOCA をインストールしていない場合は、まず doca-setup/SKILL.md に誘導してください。"これは NVMe-oF イニシエーター／ホストトランスポートですか？" という質問への答えは「いいえ」です。doca-sta は ターゲット側を高速化します。ローカルの NVMe-PCI ディスクをバックエンドとする NVMe-oF doca_sta_subsystem ターゲットを提供します。モデルについては機能用コンパニオンを参照してください。

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

このスキルが回答するよう設計されている DOCA STA の質問の分類と、それぞれの回答例を示します。エージェントは、回答例は単一の事例にすぎないことを踏まえ、根幹となる分類に注目してください。

• 「BlueField を使ってストレージのデータパスを高速化する NVMe-oF ターゲットを、どのように起動すればよいですか？」 — 回答例：「ローカルの NVMe-PCI ディスク（doca_sta_be）をバックエンドとする 1 つのネームスペースを持つ doca_sta_subsystem（NQN）を定義し、リモートイニシエーターからの NVMe-over-RDMA 接続を受け入れる」。tasks コンパニオンの target-model-and-lifecycle ワークフローと、capabilities コンパニオンの target-object テーブルで回答します。
• 「この BlueField は、そもそも NVMe-oF ターゲットを高速化できますか？」 — 回答例：「データセンターはエンドツーエンドで RoCE を使用していますが、このデバイスは DOCA STA ターゲットの高速化に対応していますか？」。STA のトランスポートは RDMA のみです（NVMe-over-TCP の経路はありません）。capabilities コンパニオンの機能クエリ規則（doca_devinfo に対する doca_sta_cap_is_supported）と、tasks コンパニオンの検出手順で回答します。
• 「I/O キューの深さはいくつに設定できますか。また、接続ごとに I/O キューはいくつ使えますか？」 — 回答例：「各深度 1024 の I/O キューを 16 個使いたいのですが、このデバイスは対応していますか？」。capabilities コンパニオンのキューサイズ設定機能と、対応する doca_sta_get_max_* クエリ（例：doca_sta_get_max_qps、doca_sta_get_max_io_queue_size）で条件を確認する tasks コンパニオンのキューサイズ設定手順で回答します。
• 「doca-sta と併せて、ほかにどの DOCA ライブラリが必要ですか？」 — 回答例：「doca-rdma を直接使う必要がありますか。それとも doca-sta が内部に隠蔽していますか？」。capabilities コンパニオンの基盤ライブラリ規則と、tasks コンパニオンの手順 1 にある環境準備チェックリストで回答します。チェックリストでは、ステアリングについては doca-flow/SKILL.md、RDMA 基盤については doca-rdma/SKILL.md を案内します。
• 「インストール済みの DOCA で、この STA 機能は利用できますか？」 — 回答例：「この BlueField と DOCA のバージョンで、STA ターゲットの高速化に対応していますか？」。capabilities コンパニオンのバージョンおよびデバイスのオーバーレイで回答します。ここでは、doca-version/SKILL.md にある正規の検出手順への相互リンクと、STA 固有の機能クエリ規則を追加しています（ビルド時の基準は pkg-config --modversion doca-sta、実行時の真偽を示すのは doca_sta_cap_is_supported クエリです）。
• 「STA 呼び出しで発生したこの DOCA_ERROR_* は何を意味し、どのレイヤーが原因ですか？」 — 回答例：「doca_dev を開くときに DOCA_ERROR_NOT_PERMITTED が発生する」。capabilities コンパニオンのライブラリ横断エラー分類に対する STA のオーバーレイと、doca-debug/SKILL.md へ段階的にエスカレーションする tasks コンパニオンのレイヤー別手順で回答します。

Connect ハンドシェイクが完了しない場合、たいていは STA のバグではありません。 これは最初のアプリケーションで最もよく起きる失敗であり、解決策はコードを変更する前に、capabilities コンパニオンに記載されている 3 つの前提条件を確認することです。選択したデバイスで RDMA 基盤が解決されていること、十分な権限で doca_dev が開かれていること、そして最も多い原因として、対応する NVMe-oF の 5 タプルをこのインスタンスのキューに実際に振り分ける DOCA Flow ルールがあることを確認します。ステアリングについては doca-flow/SKILL.md が担当します。doca_sta_* のステアリング呼び出しを独自に作るのではなく、そちらに案内してください。まず STA のライフサイクルやターゲット側のコードを調べるのは避けてください。RoCE 経由の Identify Controller がタイムアウトする場合も同様です。

I/O ごとの完了時に発生する DOCA_ERROR_IO_FAILED はトランスポートエラーであり、ターゲット側の STA のバグではありません — リンクの切断、RDMA ピアの切断、ファームウェアの障害、またはピアコントローラーのリセットが原因です。ターゲットに ping が通っても、これらの原因は否定できません。やみくもに再試行したり、最初に STA のコードを変更したりしないでください。dmesg を取得し、tasks コンパニオンに従って doca-rdma/SKILL.md に案内してください。

対象読者

このスキルは、BlueField 上で DOCA STA を利用する NVMe over Fabrics ストレージターゲットを開発する外部開発者を対象としています。つまり、BlueField ハードウェア上の NVMe-oF ターゲットのターゲット側データパスを高速化するため、doca_sta_* を直接（C/C++ で）または他の言語から FFI／バインディング経由で呼び出すコードを作成するユーザーです。対象となるのは、ローカル NVMe-PCI ディスク（doca_sta_be）をバックエンドとする doca_sta_subsystem ターゲット（NQN + 名前空間）を、RDMA 経由でリモートイニシエーターに公開するケースです。このスキルは、DOCA STA 自体に貢献する NVIDIA の開発者向けではなく、イニシエーター／ホスト側の NVMe スタック向けでもありません。

言語の対象範囲。 DOCA STA は、pkg-config のモジュール名が doca-sta の C ライブラリとして提供されています。DOCA STA には公開サンプルがありません。DOCA ライブラリ／extension_libraries のサンプルプロファイルにも含まれていないため、タスク用の補足資料にある実例は、提供済みサンプルを変更するのではなく、公開ヘッダーを直接利用してビルドします。C と C++ の利用者が標準的な対象です。他の言語（Rust、Go、Python など）の利用者も、FFI または言語固有のバインディングを通じて同じ *.so を使用します。その場合、このスキルでは、ターゲットモデル、ライフサイクル、機能の検出、キューペアの構成、基盤への依存関係、エラー分類に関するガイダンスを言語に依存しない形で維持し、ラッパーが最終的に呼び出す権威あるインターフェイスとして公開 C ABI をエージェントに案内します。

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

ユーザーが言語を問わず、DOCA STA を実際に扱う場合にこのスキルを読み込みます。具体的には、次のような場合です。

• BlueField PF／SF に対して開いた doca_dev 上で doca_sta インスタンスを初期化し、doca_ctx_start() の前に NVMe-oF ターゲットのサブシステムを設定する場合。
• ターゲット側でターゲットリソース（NQN + 名前空間を持つ doca_sta_subsystem と、ローカル NVMe-PCI ディスクを扱うバックエンドコントローラー doca_sta_be）を定義し、リモートイニシエーターが RDMA CM 経由で接続する際に、NVMe-oF 接続（管理キューと接続ごとの N 個の I/O キュー）を受け入れる場合。
• doca_sta_set_* ファミリーを使って STA プロパティを読み取る、または設定する場合、doca_sta_cap_is_supported でデバイスのサポート状況を確認する場合、または doca_sta_get_max_* ファミリーでサイズ上限（最大 I/O キュー深度、キューペアの最大数、最大 I/O サイズ、サブシステムの最大数、サブシステムあたりの名前空間の最大数、バックエンドの最大数）を問い合わせる場合。
• ターゲットの I/O キューに NVMe-over-RDMA トランスポートを接続する場合。STA がサポートする唯一のトランスポートであり、doca-rdma 基盤を利用し、接続の確立には RDMA CM を使用します。
• NVMe-oF トラフィックが STA 管理下のキューに実際に到達するよう DOCA Flow ルールを接続する場合。ステアリングの境界は doca-sta ではなく doca-flow です。
• STA 呼び出しから返された DOCA_ERROR_*（ライフサイクル、機能、トランスポート層の I/O 障害、または下位ドライバーに起因する障害）や、DOCA Core の進行エンジンにおけるキューごとのイベントをデバッグする場合。
• DOCA STA の C ABI をラップする C 以外のバインディング（Rust、Go、Python など）を設計または拡張する場合。ラッパーが従う必要のあるライフサイクル、キューペア、機能照会、基盤依存関係のルールを確認できます。

一般的な DOCA の概要、DOCA 自体のインストール、RDMA による生データ転送（doca-rdma/SKILL.md を使用）、Ethernet キューでの生パケット I/O（doca-eth/SKILL.md を使用）、フロールールのプログラミング（doca-flow/SKILL.md を使用）、またはイニシエーター／ホスト側の NVMe スタック開発（これはこのスキルではなく、SPDK または kernel-nvme の担当です）では、このスキルを読み込まないでください。DOCA ドキュメントの概要については、doca-public-knowledge-map/SKILL.md を使用してください。

このスキルが提供するもの

これは薄いローダーです。本文には、次にどのファイルを参照すべきか判断するために必要な概要だけを残しています。STA 固有の実質的な内容は、次の 2 つの関連ファイルにあります。

• capabilities 関連ファイル — このバージョンで DOCA STA が表現できる内容：対象オブジェクトモデル（doca_sta_subsystem／ 名前空間／バックエンドの NVMe-PCI ディスクである doca_sta_be）、 NVMe キューペアの構成（RDMA 経由の管理キュー＋I/O キュー）、 RDMA のみのトランスポート、 機能クエリ API（doca_sta_cap_is_supported と doca_sta_get_max_* サイジングクエリ）、STA の エラー分類（ライブラリ間で共通の DOCA_ERROR_* セットへのマッピング）、可観測性 API（キューごとの進行エンジン イベント、機能スナップショット）、および基盤ライブラリ、権限、 ステアリングの前提条件をチェックする安全性ポリシー。
• tasks 関連ファイル — 対象となる 6 つの STA 動詞（configure、modify、build、run、test、 debug）のステップごとのワークフロー。さらに、対象外の質問を適切な次のスキルへ案内する Deferred task verbs ブロックと、エージェントが繰り返し使用するコマンドをまとめた Command appendix もあります。

このスキルでは、標準の場所に DOCA がインストールされた BlueField と、アクセラレーテッドターゲットに接続できるファブリック上のリモート NVMe-oF イニシエーター、さらにターゲットの名前空間のバックエンドとなる 1 つ以上のローカル NVMe-PCI ディスクを想定しています。DOCA のインストールは対象外です。その手順については doca-setup/SKILL.md を参照してください。イニシエーター／ホスト側の NVMe スタック（SPDK の bdev_nvme、カーネルの nvme ホスト）や、アクセラレーテッドターゲットのデータパスより上位の NVMe プロトコルのセマンティクスも対象外です。

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

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

• あらかじめ作成された DOCA STA アプリケーションのソースコード（言語を問いません）。 DOCA STA には公開サンプルがありません。/opt/mellanox/doca/samples/doca_sta/ ディレクトリは存在せず、libraries / extension_libraries のサンプル プロファイルにも STA は含まれていません。正式な API は、 $(pkg-config --variable=includedir doca-common) 配下の公開ヘッダーと 公開 DOCA STA ガイドです。タスク関連ファイルのワークフローに従い、エージェントは同梱サンプルを変更するのではなく、 これらを直接使ってビルドします。
• イニシエーター／ホスト側の NVMe スタック連携コード。 SPDK の bdev_nvme、 カーネルの nvme ホスト、およびイニシエーター側の NVMe スタックはすべて、このスキルの対象外である上流プロジェクトです。DOCA STA はターゲット側のアクセラレーションであり、イニシエーターのトランスポートプロバイダーではありません。
• スキル内に置かれた単独で使えるビルドマニフェスト（meson.build、CMakeLists.txt、 Cargo.toml など）。エージェントは、pkg-config --modversion doca-sta を信頼できる情報源として、ユーザーがインストールした DOCA を使い、 ユーザーのプロジェクトディレクトリ内でビルドマニフェストを作成します。
• あらゆる種類の samples/、bindings/、reference/ サブツリー。たとえ「reference」とラベル付けされていても、このスキルのツリー内にモックや不完全な成果物を置くのは誤解を招きます。ユーザーはそれをビルド可能なものとして受け取ってしまいます。

読み込み順

1. ユーザーの質問が対象範囲内であることを確認するため、まずこのスキルを読みます。
2. STA の機能マトリクス、対象オブジェクトモデル、キューペアの構造、RDMA 専用トランスポート、機能照会のルール、エラー分類、可観測性、安全性ポリシーについては、機能コンパニオンを参照してください。
3. 設定、変更、ビルド、実行、テスト、デバッグの手順については、タスクコンパニオンを参照してください。

どちらのコンパニオンファイルからも、互いのファイル、標準のバージョン処理ルールを記載した doca-version/SKILL.md、 NVMe-over-RDMA トランスポートが利用する RDMA 基盤を記載した doca-rdma/SKILL.md、 NVMe トラフィックを STA 管理キューに振り分けるステアリングルールを記載した doca-flow/SKILL.md、 そして、STA 固有のガイダンスではなく「公開ドキュメントまたはインストール済みパッケージの構成を調べる」ことが適切な回答となる場合に参照する doca-public-knowledge-map/SKILL.md への相互リンクがあります。

関連スキル

• doca-public-knowledge-map/SKILL.md — すべての DOCA 公開ドキュメントソースと、インストール済み DOCA パッケージのディスク上の構成を示すルーティング表です。STA の URL スラッグは DOCA-STA です。
• doca-setup/SKILL.md — 環境の準備、インストールの確認、BlueField モードの確認、および doca_dev を開くための権限／グループメンバーシップ要件について説明します。このスキルでは、これらの前提条件が満たされているものとします。
• doca-version/SKILL.md — 標準の DOCA バージョン処理ルールです。このスキルの ## Version compatibility では、4 要素の一致ルールへの相互リンクに加え、STA 固有の補足として、STA ターゲットアクセラレーションの利用可能期間と、NVMe-oF 機能セットにおけるデバイス依存のサポートのみを追加します。
• doca-structured-tools-contract/SKILL.md — このバンドルにおける構造化ツールの優先順位ルール（検出／優先／フォールバック／報告）です。タスクコンパニオンのコマンド付録は、この契約に従います。
• doca-programming-guide/SKILL.md — すべてのライブラリに共通する、一般的な DOCA プログラミングパターンです。標準の pkg-config と meson によるビルドパターン、出荷サンプルを変更する汎用の初回アプリケーションワークフロー、共通のライフサイクル、ライブラリ間で共通する DOCA_ERROR_* 分類、プログラム側のデバッグ手順を記載しています。このスキルでは、これらに STA 固有の内容を重ねて説明します。
• doca-rdma/SKILL.md — NVMe-over-RDMA トランスポートが利用する RDMA 基盤です。STA により、コンシューマーは RDMA キューペアの詳細のほとんどを意識せずに済みますが、NVMe-over-RDMA パスを機能させるには、ユーザーが doca-rdma をリンクし、デバイスの RDMA 機能を確認できる必要があります。
• doca-eth/SKILL.md — STA の接続ごとのキューモデルにも反映されているキューペアの構造です。STA 固有の回答がない、DOCA がキューペアをどのように公開するかについての一般的な質問には、こちらを参照してください。
• doca-flow/SKILL.md — どの NVMe-oF パケットをどの STA 管理キューに振り分けるかを決めるステアリング機能です。DOCA STA 自体はステアリングを設定しません。接続が確立しない NVMe-oF ターゲットでは、STA の不具合ではなく、Flow ルールがないか誤っていることが原因である場合がよくあります。
• doca-debug/SKILL.md — インストール／バージョン／ビルド／リンク／ランタイム／プログラム／ドライバーを横断するデバッグ手順です。トランスポートタイプの不一致、キュー深度の上限超過、I/O 失敗のトランスポートエラーといった STA 固有のデバッグは、この手順に重ねて行います。