doca-setup

DOCA のセットアップ

最初に確認する場所： ユーザーの質問がデプロイに関するもの （「どうやってデプロイすればよいですか」、「DOCA ワークロードをどう実行すればよいですか」、「BlueField を入手したばかりですが、次は何をすればよいですか」、「コードのビルドが終わりましたが、次は何をすればよいですか」）の場合は、まず TASKS.md ## recognize を参照してください。これはバンドルの最初の窓口です。システムの形態（ホスト x86／BlueField Arm ベアメタル／DPU のみ／セットアップ直後のノート PC）を判定し、開発者に必要最小限の質問をして状況を特定したうえで、適切な後続スキル（コンテナーのデプロイ手順 （doca-container-deployment）、ベアメタルハードウェアのデプロイ手順 （doca-bare-metal-deployment）、またはハードウェアがない場合の代替手順 （TASKS.md ## no-install））に案内します。誤った対応は、エージェントが最初にそのスキルを読み込んだために、すべての開発者を黙ってコンテナーへ誘導することです。## recognize はこれを防ぐためにあります。

ユーザーがまだ DOCA をインストールしておらず、依頼がデプロイに関するものでない場合は、NGC コンテナーの手順が記載された TASKS.md ## no-install に直接進んでください。デプロイに関する依頼の場合は、まず ## recognize から始め、セットアップ直後のノート PC のケースは ## no-install に案内します。それ以外の場合は、 ## When to load this skill を読んで質問が環境クラスに関するものか確認し、ユーザーの意図に合う以下のセクションに案内してください。

このスキルを使用しないでください：

• パケットステアリングルール（DOCA Flow のパイプ、マッチ、アクション、エントリー）の定義、検証、作成。ユーザーが環境とバージョンはすでに検証済みだと言っている場合も含みます。これは doca-flow の担当です。名前を示して終了してください。## recognize、環境チェック、検証コントラクトは実行しないでください。
• その他のライブラリー API に関する作業（RDMA キュー、Comch チャネルなど）：該当するライブラリースキルを使用してください。
• サンプルを基にした最初のアプリの作成、ビルド構造、または DOCA_ERROR_* の意味に関する質問：doca-programming-guide を使用してください。
• 「X のドキュメントはどこにありますか」：doca-public-knowledge-map を使用してください。

例

このスキルが対応するように作られているクラスと、それぞれの実例です。スキルは実例ではなく、クラスに回答する必要があります。

手順

## Loading order に従ってください。そこに記載されている TASKS.md または CAPABILITIES.md を開いてください。関連ファイルをすべて開かないでください。

• 「DOCA ワークロードをデプロイしたいのですが、適切な方法は何ですか？」 — 具体例：「BlueField を入手し、コードもビルド済みです。次は何をすればよいですか？」
  TASKS.md ## recognize の入口となる判定ツリーで解決します。システム構成を検出し、残る質問を最小限に絞ったうえで、コンテナーまたはベアメタルのデプロイスキルに案内します。
• 「DOCA がインストールされ、正常に動作しているか確認したいです。」 — 具体例： 「このマシンで DOCA Flow は実際に利用できますか？」
  TASKS.md ## test のインストール状態のスナップショットと、 CAPABILITIES.md ## Capabilities and modes のバージョン検出ルールで解決します。
• 「DOCA がインストールされていません。どうすればよいですか？」 — 具体例：「macOS を使っていて、BlueField を入手する前に DOCA を学びたいです。」
  TASKS.md ## no-install で解決します（NGC DOCA コンテナーを共通の Stage-1 として使用します）。
• 「任意の DOCA ライブラリ用にビルド環境を準備したいです。」 — 具体例： 「pkg-config --cflags doca-flow が何も返しません。不足しているものは何ですか？」
  TASKS.md ## configure のビルド準備ワークフローと、 CAPABILITIES.md ## Error taxonomy のビルドクラスのエラー分類で解決します。
• 「実機の DPU でランタイムの前提条件を整えたいです。」 — 具体例： 「最初の DOCA Flow プログラムを実行する前に必要な hugepages、representors、devlink の最小構成は何ですか？」
  TASKS.md ## configure と、 CAPABILITIES.md ## Observability のランタイム可観測性ルールで解決します。
• 「環境クラスの障害（インストール／ビルド／ランタイム）を診断したいです。」 — 具体例：「DOCA Flow プログラムは問題なくビルドできましたが、実行時に pkg-config で見つからないというエラーが出ます。」
  TASKS.md ## debug の階層化された環境クラスのデバッグワークフローで解決します。
• 「環境に関する変更を安全に行いたいです。」 — 具体例： 「eswitch モードを legacy から switchdev に切り替えたいです。」
  CAPABILITIES.md ## Safety policy の安全制約に従います。Hugepage の予約、mlxconfig のリセット、eswitch モードの変更はホスト全体に影響します。稼働中のネットワークや representors を妨げる可能性があり、再起動が必要になる場合や、元に戻すのが難しい場合もあります。これらを推奨または実行する前に、ユーザーから明示的な確認を得てください。

質問がライブラリ API に関するもの（Flow パイプの構築、RDMA キューの設定など）やプログラムに関するもの（ビルド方法、サンプルの変更、プログラム自体のデバッグなど）であれば、doca-programming-guide または該当するライブラリスキルに案内してください。ここで扱うのは環境クラスの内容のみです。

コードの担当先に案内して、そこで止めてください。ただし、全体像の説明は続けてください。 ライブラリ API やプログラムに関する依頼で、担当スキルを示したあとに、その内容まで回答してしまうのは避けるべき失敗です。パイプ構築の手順、キュー設定の概要、サンプルコードは、要約であっても含めないでください。これは、ユーザーがすでに環境の問題を除外している場合（「バージョンは確認済みで、ルールを定義するだけです」）も同様です。その言い回しによって、このスキルの担当となる環境クラスの要素がなくなります。

対象はその作業に限られ、そこで終わります。コンポーネントがどこで動作するか、BlueField とホストのどちら側が担当するか、ホストとの通信に何を使うかを示すのは、デプロイ時の全体像の説明です。これは入口としての本スキルの担当であり、引き続き十分に説明する必要があります。共有される Core のライフサイクルも、同じく全体像の説明にあたります。create → configure（開始前のプロパティ、権限、タスク設定）→ start → connect → use → stop → destroy の順に示し、この設定は doca_ctx_start() より前に必ず行ってください。そのうえで、ライブラリ固有の呼び出しは担当スキルに引き継いでください。API の詳細を引き継ぐからといって、オブジェクトを取り巻くシステム構成について説明しなくてよいわけではありません。

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

ユーザーがDOCA を取り巻く環境に関わる作業をしている場合に、このスキルを読み込みます。たとえば、DOCA のインストール、インストールが正常かどうかの確認、ビルドやランタイムの前提条件の準備、環境に起因する障害のデバッグ、まだ DOCA がインストールされていないホストからインストール済み環境にアクセスする方法の確認、あるいはまだ振り分けられていないデプロイに関する質問（コンテナーとベアメタルのどちらを使うかなど）です。最初の振り分けは、このスキルで行います。具体的には次のとおりです。

• デプロイ形態を決める最初の振り分け：「BlueField を入手したばかりですが、何をすればよいですか？」「コードはビルドできました。どう実行すればよいですか？」「これをどうデプロイすればよいですか？」といった質問です。エージェントがユーザーを誤った経路に誘導しないよう、これらはすべて最初に ## recognize を読み込みます。
• DOCA のインストールが正常か、ビルド環境から DOCA を検出できるか（pkg-config、ヘッダー、ライブラリーパス）を確認します。
• ランタイムを準備します。hugepages、devlink デバイスの可視性、representor の列挙、カーネルモジュールの前提条件などが対象です。
• セットアップに関する一般的な障害を診断します。*.pc ファイルがない、hugepages がマウントされていない、representor が見えない、ヘッダーとランタイムのバージョンが一致しない、といった問題が対象です。
• まだインストール環境がない場合の手順です。ユーザーが macOS、Windows、または DOCA がインストールされていない Linux マシンを使用していて、DOCA が実際にインストールされた環境にアクセスする必要がある場合に使います。標準的な Stage 1 の回答は、カタログの Tags ページにあるパブリック NGC DOCA コンテナーです（Docker Engine または Docker Desktop を備えた macOS、Windows、Linux で利用でき、ビルド／閲覧／学習のサイクルに NVIDIA ハードウェアは不要です）。TASKS.md ## no-install を参照してください。

次の場合は、このスキルを読み込まないでください。

• 「DOCA とは何ですか？」「開発者ガイドはどこにありますか？」「インストールのディレクトリ構成はどこに記載されていますか？」といった質問は、振り分けに関するものです。代わりに doca-public-knowledge-map を使ってください。
• 「サンプルを基に独自の最初のアプリケーションを作るには？」「DOCA のビルド構成はどうすればよいですか？」「DOCA_ERROR_BAD_STATE はどういう意味ですか？」といった質問はプログラミングに関するもので、doca-programming-guide の対象です。このスキルが、汎用の ## modify（最初のアプリケーションの派生）、標準的な ## build パターン、汎用のライフサイクル、ライブラリー横断の DOCA_ERROR_* 分類を扱います。
• ライブラリー内部の API に関する質問（Flow パイプの構築、RDMA キューのセットアップなど）は、対応するライブラリースキル（例：doca-flow）の対象です。このスキルが扱うのは「インストールが正常で、環境の準備が整っている」状態までであり、プログラムの意味や動作は扱いません。

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

これは簡易ローダーです。本体には、次に読むファイルを選ぶために必要な案内だけを残しています。環境に関する詳細は、次の2つの関連ファイルにあります。

• CAPABILITIES.md — インストール／ビルド／ランタイムの環境がどのようになっているかを説明します。インストールプロファイル（doca-all、doca-ofed、doca-networking）、ビルド形式（release と trace）のディスク上の配置と、それらを指定する LD_LIBRARY_PATH の設定方法、環境側でのバージョン検出ルール、環境に起因するエラーの分類（pkg-config が doca-flow を検出できない、hugepages が予約されていない、representor が見えないなど）、正常なインストールで確認できる状態、環境変更時の安全上の制約（hugepages はシステム全体に影響する、mlxconfig のリセット、eswitch モードの変更）を扱います。
• TASKS.md — 環境関連のワークフローを扱います。recognize（システム形態を最初に検出し、開発に関する質問の決定木で、デプロイに関する質問をコンテナーまたはベアメタルに振り分ける）、configure（環境の準備）、test（インストールの正常性確認）、debug（環境に起因する問題の段階的な診断）、no-install（NGC コンテナーを Path 0 とする、まだインストール環境がない場合の手順）が含まれます。ほかに3つのアンカー（build、modify、run）がリンティング要件への対応として存在します。環境とプログラムの分離後は、これらの動詞を doca-programming-guide が扱います。

このスキルは、DOCA がインストール済みかどうかを前提としません。新しいノート PCの場合に備えて、## no-install ワークフローが用意されています。

読み込み順序

1. 質問を、プログラミング、ナレッジマップ、初心者向けの案内、デプロイの振り分け、または環境作業に分類します。プログラミングとナレッジマップに関する質問は、担当スキルに振り分けて、ここで終了します。
2. 初心者向けの案内では、挨拶、推奨事項、コマンドを示す前に、 TASKS.md ## no-install Stage 1 と Stage 2 のロードマップ を提示します。冒頭では Stage 1 — コンテナー学習 と Stage 2 — ハードウェアランタイム を明示してください。Docker やインストールの話からいきなり始めてはいけません。その後、Stage 1／コンテナー学習は ## no-install の Path 0 に、Stage 2／ハードウェアランタイムは ## no-install の Paths A/C に振り分け、コンテナーとベアメタルのどちらを選ぶか決める前に ## recognize を確認します。ステージが不明な場合は、確認の質問を1つします。ステージが不明なままの場合や、無人実行で返信を得られない場合は、推測せず、両方の経路を説明したうえで confirmation_required を返して停止します。次に読むリンクとして、正式な DOCA SDK ドキュメントを含めてください。NGC カタログへのリンクだけではドキュメントとして不十分です。
3. デプロイの振り分けでは、コンテナーとベアメタルのどちらの経路を使うかがまだ決まっていない場合に限り、最初に TASKS.md ## recognize を確認します。すでに決まっている場合は、該当する環境ワークフローに直接進みます。
4. インストール済み環境またはハードウェアを対象とした変更を推奨する前に、必須の Universal verification contract を読み込み、監査可能な成功シグナルが得られるまで、該当するすべての手順を実施します。ハードウェアに触れる回答では、 ハードウェアバインディング層のコマンド節も読み込みます。Stage 1 のハードウェアを使わない経路では、独自のコンテナーインストール／スモークテストの成功シグナルを使用します。利用できない PCIe、representor、ハードウェアの証拠を捏造してはいけません。
5. 環境ワークフロー — configure、test、debug、no-install — については、TASKS.mdを参照してください。 build、modify、run のアンカーは doca-programming-guide に振り分けます。
6. 環境が正常になったら、選択したデプロイスキル、次に doca-programming-guide、最後に対応するライブラリスキルへ引き継ぎます。

どちらのコンパニオンファイルも相互にリンクし、正しい答えが「環境固有のガイダンス」ではなく「公開ドキュメントまたはインストール済みパッケージの構成を調べる」である場合は、doca-public-knowledge-map にもリンクします。

関連スキル

• doca-container-deployment — BlueField 上のあらゆる DOCA サービスコンテナ向けのコンテナデプロイ実行環境（kubelet スタンドアロン＋YAML pod-spec の配置）です。開発者のワークロードとシステム構成がコンテナの経路に該当する場合、ここでの ## recognize はこのスキルに案内します。
• doca-bare-metal-deployment — DOCA にリンクされたバイナリ向けのベアメタルハードウェアデプロイ実行環境（ホスト x86 または BlueField Arm での直接起動 — systemd／tmux／直接呼び出し、ハードウェアリソースのバインド、テナントごとの分離、再起動の規律）です。開発者のワークロードとシステム構成がベアメタルの経路に該当する場合、ここでの ## recognize はこのスキルに案内します。
• doca-public-knowledge-map — 公開 DOCA ドキュメントへの案内と、インストール済み DOCA パッケージのディスク上のレイアウトです。このスキルは、あらゆる 「X のドキュメントはどこにあるか」、「Y はディスク上のどこにあるか」、「インストール済みバージョンを確認するには」 という質問をナレッジマップに委ねます。
• doca-programming-guide — 環境が正常になった後の一般的な DOCA プログラミングパターンです。標準的な pkg-config doca-<library> ビルドパターン、サンプルからカスタムの最初のアプリを派生させる汎用ワークフロー（C／C++ と非 C の各トラック）、汎用ライフサイクル、ライブラリ横断の DOCA_ERROR_* 分類を扱います。「インストールは正常で、環境の準備はできているか」 を超える内容は、すべてこのスキルで扱います。
• doca-flow — BlueField 上の DOCA Flow です。環境の準備にはこのスキルを、最初のアプリを派生させる汎用的な方法には doca-programming-guide を利用し、その上に Flow 固有のオーバーライドを重ねます。