doca-mgmt

DOCA Management

例

• 「VF で data-direct を切り替える。」 — これは対象範囲内です。 管理／リプリゼンターのコンテキストを使用し、低レベルの mlxconfig に移行しないでください。
• 「raw_cmd から DOCA_ERROR_IO_FAILED が返される。」 — ファームウェアが コマンドを拒否しています。4 つのバージョンの一致、オペコード、最も限定的で 正しいスコープ（CONFIGURATION、DEBUG_READ_ONLY、DEBUG_WRITE、 DEBUG_WRITE_FULL）を再確認してください。fwctl または権限のエラーは、 代わりに DOCA_ERROR_OPERATING_SYSTEM として通知されます。

手順

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

最初に確認すること： このスキルは、DOCA がすでにインストールされており、 ユーザーが BlueField／ConnectX デバイスに対する管理プレーンの実作業を 行っていることを前提としています。通常は、デバイスレベルの状態をプログラムから 照会または変更する必要がある、フリート管理ツールやオーケストレーションツールが該当します。 ユーザーが何かを実行（インストール／設定／ビルド／変更／実行／テスト／デバッグ／使用） したい場合は、タスク用コンパニオンを開いてください。質問が「このバージョンでは doca-mgmt で何を表現できるか」についての場合は、機能用コンパニオンを開いてください。 対象には、管理コンテキストモデル、raw コマンドのスコープ階層、 サブドメインのインターフェース（caps-general、cc-global-status、diagnostics- data、icm-quota）、バージョン互換性、安全性オーバーレイが含まれます。 ユーザーがまだ DOCA をインストールしていない場合は、最初に doca-setup/SKILL.md に案内してください。

このスキルの使い方。 このファイルを読み、質問に必要な ## <name> 見出しを コンパニオンファイル内で検索し、そのセクション全体を読んでください。 その内容だけに基づいて回答し、記載されているシンボルとコマンドのみを引用してください。 ドキュメントを閲覧しないでください。doca-public-knowledge-map のエントリーポイントを 使用してください。環境確認には、ユーザーの DOCA ホストで実行するコマンドを示してください。 デバイスの状態を変更する場合は、必ず doca-hardware-safety にも従い、その旨を伝えて 参照先を示してください。対象範囲外の依頼については、該当するスキル名を示して終了してください。

このスキルが得意とする質問の例

このスキルが回答できるよう設計されている管理プレーン関連の質問のクラスと、それぞれの具体例です。エージェントは、重要なのはクラスであり、具体例はその一例にすぎないと捉えてください。

• 「doca-mgmt が適切なインターフェースなのか、それともテレメトリー／ベンチマーク／caps を使うべきなのか？」 — 具体例：「フリートインベントリーツールを作っています。各 BlueField のデータダイレクト機能を照会するには、doca-mgmt、doca-telemetry、doca_caps のどれを使えばよいですか？」。## Capabilities and modes のインターフェース選択テーブルにある、管理プレーンと可観測性プレーンと読み取り専用 CLI の選択ルールで回答します。
• 「デバイス（および representor）で管理コンテキストをどのように確立しますか？」 — 具体例：「デバイス上で doca_mgmt_dev_ctx を開き、次に caps-general の設定用に特定の VF representor 上で doca_mgmt_dev_rep_ctx を開く」。## Capabilities and modes の管理コンテキストのライフサイクルと、## configure の設定手順で回答します。
• 「データダイレクトに対応しているかどうかなど、デバイスの機能をどのように照会しますか？」 — 具体例：「caps-general ハンドルを作成し、representor コンテキストで doca_mgmt_device_caps_general_get を呼び出して、データダイレクトのフラグを読み取る」。## Capabilities and modes の機能照会パターンと、## test のテスト手順で回答します。
• 「デバイスレベルの機能フラグを安全に変更するにはどうすればよいですか？」 — 具体例：「representor 上で data_direct を切り替え、変更前の状態を記録し、書き込み、検証して、ロールバックに備える」。## Safety policy で参照されている、バンドル全体に適用されるハードウェア安全性メタポリシーを踏まえた、## modify の適用とロールバックのワークフローで回答します。
• 「doca_mgmt_raw_cmd のスコープとは何を意味し、どのスコープを使うべきですか？」 — 具体例：「DEBUG_READ_ONLY クエリー用にベンダーのドキュメントに記載されたオペコードがあります。どのスコープが必要で、影響範囲はどれくらいですか？」。## Capabilities and modes のコマンドスコープの段階と、## use の raw コマンドの動詞で回答します。
• 「doca_mgmt_* の呼び出しで発生したこの DOCA_ERROR_* は何を意味し、どのレイヤーが原因ですか？」 — 具体例：「doca_mgmt_raw_cmd で DOCA_ERROR_IO_FAILED が発生した」。## Error taxonomy のライブラリー横断的な分類に mgmt のオーバーレイを加えた内容と、## debug の段階的な手順で回答します。原因がデバイス状態の変更である場合は、doca-debug/SKILL.md と doca-hardware-safety/SKILL.md にエスカレーションします。

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

ユーザーが、1 台以上の BlueField／ConnectX デバイスを搭載したホストで、DOCA Management を実際に操作する作業を行う場合に、このスキルを読み込みます。 具体的には、以下のような作業が該当します。

• doca_dev 上に doca_mgmt_dev_ctx を作成し、デバイスレベルの状態を確認または変更する。
• doca_dev_rep 上に doca_mgmt_dev_rep_ctx を作成する（representor を利用できない場合は doca_mgmt_dev_rep_ctx_create_by_pci_addr を使用する）ことで、VF／機能レベルの設定を確認または変更する。
• doca_mgmt_device_caps_general_* を使用して、デバイスの一般的な機能（data-direct のサポートなど、デバイス全体に関する属性）を問い合わせる。
• 同じ set 経路を使用して、representor の一般的な機能を設定する。
• doca_mgmt_cc_global_status_* を使用して、輻輳制御のグローバルステータス（RP／NP プロトコルタイプ、優先度、有効／無効）を問い合わせまたは変更する。
• 特定のデバイスに対して doca_mgmt_diagnostics_data_* を使用し、複数ドメインの診断データを変更または問い合わせる。
• doca_mgmt_icm_quota_* を使用して、デバイスまたは representor ごとの ICM クォータ制限を設定し、現在の割り当て／上限到達状態を読み取る。
• デバイスのファームウェア制御エンドポイントに対して doca_mgmt_raw_cmd を発行し、操作の影響範囲に適した enum doca_mgmt_cmd_scope を選択する。
• doca_mgmt_* 呼び出しが返した DOCA_ERROR_* をデバッグし、原因が設定ミス、ライフサイクルの順序に関するバグ、デバイスの機能不足、fwctl の ioctl 失敗、またはファームウェア側での拒否のいずれかを判断する。

DOCA 全般の概要、DOCA 自体のインストール、実環境でのパフォーマンスベンチマーク、またはストリームベースのテレメトリには、このスキルを読み込まないでください。これらには、それぞれ doca-public-knowledge-map/SKILL.md、 doca-setup/SKILL.md、 doca-bench/SKILL.md、および doca-telemetry/SKILL.md を使用してください。

このスキルの内容

これは薄いローダーです。本体には、次に読むファイルを選ぶために必要な概要だけを残しています。Management 固有の実質的な内容は、2 つの関連ファイルに記載されています。

• 機能に関する関連ファイル — このバージョンで doca-mgmt が表現できる内容：Management コンテキストのオブジェクトモデル（doca_mgmt_dev_ctx + doca_mgmt_dev_rep_ctx）、raw コマンドのスコープ階層（DOCA_MGMT_CMD_SCOPE_CONFIGURATION、DOCA_MGMT_CMD_SCOPE_DEBUG_READ_ONLY、DOCA_MGMT_CMD_SCOPE_DEBUG_WRITE、DOCA_MGMT_CMD_SCOPE_DEBUG_WRITE_FULL）、サブドメインのインターフェイス（caps-general、cc-global-status、diagnostics-data、icm-quota）とその機能問い合わせゲート、EXPERIMENTAL シンボルセットのポリシー（すべての公開 doca_mgmt_* シンボルに EXPERIMENTAL のタグが付いています）、ライブラリ横断の DOCA_ERROR_* 分類体系に対する mgmt の補足情報、可観測性のインターフェイス（状態変更前の記録 + 書き込み後の再問い合わせ）、およびバンドル全体のハードウェア安全性メタポリシーに対するアーティファクトごとの安全性補足。
• タスクに関する関連ファイル — 対象となる 8 つの動詞（install、configure、build、modify、run、test、debug、use）について、手順を追ったワークフローを記載しています。さらに、対象外の質問を適切な次のスキルに案内する Deferred task verbs ブロックもあります。

このスキルは、DOCA が標準の場所にすでにインストールされ、ユーザーが公開されているインストールプロファイルで想定される権限を持つホストまたは BlueField を前提としています（Management プレーンの操作には、通常、root または同等のデバイス管理権限が必要です）。DOCA のインストール方法は対象外です。インストールについては doca-setup/SKILL.md を参照してください。

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

このスキルはエージェント向けのガイダンスであり、サンプルやテンプレートの一式ではありません。明確な境界を保つため、意図的に以下を含めておらず、プルリクエストで追加すべきでもありません。

• あらゆる言語で記述された、事前作成済みの DOCA Management アプリケーションのソースコード。 管理プレーンのコードはデバイスの状態を操作し、誤った書き込みによってデバイスがオフラインになる可能性があります。ドキュメントの文章からコードを作成することは、特にリリース間で形状が変わる可能性のある EXPERIMENTAL なシンボルセットを対象とする場合、このスキルで禁止されています。エージェントの役割は、検証済みのリファレンスコード（インストール済みパッケージセットに同梱されている DOCA サンプルが、正式な実例です）へユーザーを案内し、doca-programming-guide/SKILL.md にある汎用のサンプル変更ワークフローに従って、差分を最小限に抑えた変更を指示することです。
• スキル内に置かれた単独のビルドマニフェスト。 エージェントは、pkg-config --modversion doca-mgmt を信頼できる情報源として、ユーザーのインストール済み DOCA に合わせて、ユーザーのプロジェクトディレクトリ内でビルドマニフェストを作成します。
• raw-command のオペコードカタログ。 doca_mgmt_raw_cmd の入力ペイロードと出力ペイロードはデバイス／ファームウェアに固有です。このスキルでは、コマンドクラスの対象範囲と、エージェントが適用する手順（事前状態の取得、対象範囲の段階的な拡大、ロールバック手順）を示しますが、オペコードは列挙しません。オペコードはベンダー／デバイスのドキュメントに記載されており、doca-public-knowledge-map/SKILL.md を通じて確認します。
• samples/、bindings/、reference/ サブツリー。 このスキルのツリー内にあるモックや未完成の成果物は、「reference」と表示されていても誤解を招きます。ユーザーがビルド可能なものとして受け取ってしまうためです。

読み込み順序

1. ユーザーの質問が対象範囲内であることを確認するため、まずこのスキルを読みます。
2. 管理コンテキストのオブジェクトモデル、raw-command の対象範囲を段階的に示すガイド、サブドメインの各機能、バージョン互換性、エラー分類、可観測性、および成果物ごとの安全性に関する補足については、機能コンパニオンを参照してください。
3. インストール、設定、ビルド、変更、実行、テスト、デバッグ、使用の手順を追ったワークフローについては、タスクコンパニオンを参照してください。

どちらのコンパニオンファイルも相互にリンクしており、「管理機能固有のガイダンス」ではなく「公開ドキュメントまたはインストール済みパッケージの構成を調べる」が適切な回答となる場合は、doca-public-knowledge-map/SKILL.md にもリンクしています。

関連スキル

• doca-hardware-safety/SKILL.md — バンドル全体に適用されるハードウェア安全性メタポリシーです。 doca-mgmt は、エージェントがプログラムからデバイスの状態を 変更する際に最もよく使うインターフェースであるため、 capabilities コンパニオンの安全性オーバーレイでは、メタポリシーを 重要な形で相互参照しており、書き込みを推奨する際には常に、 エージェントがハードウェア安全性の手順に従います。
• doca-telemetry/SKILL.md および doca-telemetry-exporter/SKILL.md — デバイスからのテレメトリーをストリーミングするための可観測性 インターフェースです。ユーザーがリアルタイムのメトリクスを求める場合は これらを使い、特定時点のプログラムによるクエリや変更を求める場合は doca-mgmt を使います。
• doca-caps/SKILL.md — デバイスの機能を調査するための読み取り専用 CLI です。ユーザーが 対話形式でのスナップショットを求める場合はこのツールを使い、 フリートツールで同じ情報を C API 経由で取得したい場合は doca-mgmt を使います。
• doca-bench/SKILL.md — リアルタイムの性能ベンチマークツールです。doca-mgmt の対象範囲外であり、 このスキルではその境界を示しています。
• doca-pcc/SKILL.md および doca-pcc-counters/SKILL.md — プログラム可能な輻輳制御です。doca-mgmt の doca_mgmt_cc_global_status_* インターフェースは、 doca-pcc が担う、より詳細なプログラム可能な CC インターフェースの上位に 重なる、グローバルな有効化／無効化とプロトコル選択を行う コントロールプレーンです。
• doca-public-knowledge-map/SKILL.md — 公開されている DOCA ドキュメントソースすべてへのルーティングテーブルと、 インストール済み DOCA パッケージのディスク上のレイアウトです。
• doca-setup/SKILL.md — 環境の準備、インストールの検証、および公開 NGC DOCA コンテナを使った まだインストールしていない場合の手順です。
• doca-programming-guide/SKILL.md — すべてのライブラリで共通する DOCA の一般的なプログラミングパターンです。 標準の pkg-config と meson によるビルドパターン、提供済みサンプルを 変更して最初のアプリケーションを作成する共通ワークフロー、 ライブラリ間で共通する DOCA_ERROR_* の分類体系を説明しています。 このスキルでは、その上に管理プレーン固有の情報を重ねています。
• doca-debug/SKILL.md — 分野横断的なデバッグ手順です。その上に管理固有のデバッグオーバーレイを 重ねています。
• doca-version/SKILL.md — 各アーティファクトの ## Version compatibility アンカーが基盤とする、 バージョン検出と四者一致のルールです。このスキルでは、管理固有の オーバーレイのみを引用しています。
• doca-structured-tools-contract/SKILL.md — エージェントが優先する構造化ヘルパーの JSON スキーマ契約です。 タスク用コンパニオンの ## Command appendix では、手動の手順に フォールバックする前に、これらを参照します。