doca-debug

DOCA のデバッグ

例

• 「DOCA のビルド／リンク／実行時に失敗しました。どのレイヤーの問題ですか？」 — このスキルの対象です。レイヤー別の手順に沿って確認し、最初からライブラリ内部のデバッグに進まないでください。
• 「DOCA のライブラリやツールの詳細度を上げるにはどうすればよいですか？」 — ログレベル／トレースの種類を設定し、その後、フォーラムへの投稿用に状態を収集してください。

手順

undefined reference はリンクレイヤーの症状であり、ライブラリの欠落やアプリケーションコードの不具合を示す証拠ではありません。修正を提案する前に、ビルドに失敗したときと同じホスト／コンテナおよびシェルで、次の情報を取得してください。

• pkg-config --modversion doca-common と、選択したライブラリのバージョン。Flow の場合は、pkg-config --modversion doca-flow。
• pkg-config --libs doca-<library>。Flow の場合は、pkg-config --libs doca-flow。
• ビルドログに記録された、実際に失敗したコンパイラー／リンカーの呼び出しと、エラー出力の全文。pkg-config が報告するのはフラグであり、失敗したコマンドではありません。

これらの出力がない場合は、取得を依頼してから、修正を指示せずに待ってください。 確認項目を挙げただけでは、その確認に合格した証拠にはなりません。情報の取得を依頼する際に、推測による修正、推測した -L／-l フラグ、予測したライブラリのファイル名、置き換え用のコンパイラーコマンドを追加しないでください。証拠が揃ったら、既存のビルドシステムを通じて、元の呼び出しと確認できた pkg-config の出力全体を比較してください。DOCA のバージョンによって異なる分割ライブラリを手作業で組み立てないでください。ldd を使うのは、関連するバイナリが実際に生成された場合に限ります。ヘッダー内の宣言は、リンクされた共有オブジェクトがそのシンボルをエクスポートしている証拠にはなりません。

バージョンの整合性については doca-version/TASKS.md#configure に従い、環境をプログラムより先に調査する手順については doca-programming-guide/TASKS.md#debug に従い、検証済みのインストール場所と公開ドキュメントについては doca-public-knowledge-map/SKILL.md を参照してください。バンドルスキル名は SDK ページのスラッグではありません。そこからドキュメントの URL を作らないでください。一致するガイドが検証されていない場合は、DOCA SDK のインデックスを使用し、該当するページがまだ確認できていないことを伝えてください。 その後、段階的な調査については TASKS.md に従ってください。後続のフェーズは、推測で修正を指示するものではなく、観察された結果に応じて進めるものです。

リンカーエラーしかない場合の最初の返信（Flow の例）。 実際の質問に合わせてライブラリ名を変更し、情報の取得のみを求める次の形式を使用してください。

これはリンク時の失敗です。未定義シンボルのメッセージだけでは、インストールされているバージョンや、どのビルド設定に問題があるかは分かりません。ビルドに失敗したときと同じホスト／コンテナおよびシェルで、次の出力を貼り付けてください。

pkg-config --modversion doca-common
pkg-config --modversion doca-flow
pkg-config --libs doca-flow

また、実際に失敗したリンカーの呼び出し、エラー出力の全文、ビルドがホストとコンテナのどちらで実行されたかも含めてください。まだフラグ、パッケージ、ソースを変更しないでください。フェーズ 3～5 は、これらの証拠が揃うまで保留です。修正はまだ選択されていません。情報が揃ったら、それらを比較し、根拠のある修正を 1 つ選んで、元のビルドを再実行できます。リンクの確認が成功したと判断できるのは、そのビルドが不足しているシンボルなしで正常終了した場合のみです。それによって実行時やハードウェアの正常性が確認されるわけではありません。

最初の返信は、証拠の提示依頼と判断保留の説明で終えてください。後で検証すると断っていても、その後に修正コマンドの例を追加しないでください。

調査の開始点： このスキルは、doca-setup/SKILL.md と doca-programming-guide/SKILL.md が参照する、標準的なレイヤー別手順のリファレンスです。症状が env-class と program-class のどちらにも明確に当てはまらない場合は、タスクの補助資料から調査を開始してください。レイヤー別手順の全体は、そちらに記載されています。

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

このスキルが回答できるデバッグ質問の種類と、それぞれの具体例です。

• 「DOCA のビルド／リンク／実行時／プログラムで失敗しました。どのレイヤーの問題ですか？」 — 具体例：「ld で undefined reference to doca_flow_init と表示されます。どのレイヤーの問題ですか？」 tasks コンパニオンにある標準のレイヤー別手順で回答します（レイヤー 4 = リンク）。
• 「DOCA のライブラリやツールで、詳細ログを出すにはどうすればよいですか？」 — 具体例：「DOCA Flow プログラムから何も出力されません。ログを増やすにはどこを見ればよいですか？」 capabilities コンパニオンにあるトレースの種類／ログレベルの一覧と、tasks コンパニオンにある詳細ログ付きで実行するワークフローで回答します。
• 「フォーラムへの質問やバグ報告のために、状態を記録するにはどうすればよいですか？」 — 具体例：「再現可能な情報を添えてフォーラムに質問を投稿したいのですが、何を含めればよいですか？」 tasks コンパニオンにある再現可能な状態を記録するワークフローで回答します。
• 「この DOCA ツールの出力は何を意味しますか／どのツールで確認できますか？」 — 具体例：「doca_caps を実行しても RDMA の結果が何も返りません。サポートされていないという意味ですか？」 capabilities コンパニオンにあるツールと機能の判断ツリー、および doca-caps/SKILL.md への相互リンクで回答します。
• 「NGC コンテナー内でデバッグしています。何を確認できますか？」 — 具体例：「コンテナー内で hugepages が空です。実際の問題ですか、それともコンテナー固有の問題ですか？」 capabilities コンパニオンにあるコンテナー固有のデバッグ制約と、tasks コンパニオンのレイヤー 5（実行時）で回答します。
• 「どこに問い合わせればよいですか？」 — 具体例：「お客様向けの DOCA フォーラムはどこにありますか。また、投稿には何を含めればよいですか？」 tasks コンパニオンにある Developer-Forum への案内ルールと、doca-public-knowledge-map/SKILL.md で回答します。

症状が環境クラスだけに該当する場合は doca-setup/SKILL.md に案内し、プログラムクラスだけに該当する場合は doca-programming-guide/SKILL.md に案内してください。このスキルは、両方から参照される横断的なレイヤーです。

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

ユーザーが DOCA 関連の問題をデバッグしている場合は、このスキルを読み込みます。たとえば、コンパイルできないビルド、doca_* シンボルを解決できないリンク処理、DOCA_ERROR_* を返す実行時の呼び出し、ワイヤー上に現れないパケット、起動しないサービス、または有用な出力を返さないツールなどが該当します。具体的には、次のような場合です。

• ユーザーが症状を報告し、原因となったレイヤー（インストール／バージョン／ビルド／リンク／実行時／プログラム）を特定する必要がある場合。
• ユーザーが DOCA のライブラリやツールについて、「ログを増やすにはどうすればよいですか？」や「詳細ログを出すにはどうすればよいですか？」と尋ねた場合。
• ユーザーがフォーラムへの質問や内部バグ報告のために状態を記録したい場合（このバンドルは内部バグ報告の窓口を扱いません。公開 DOCA Developer Forum へ案内します）。
• ユーザーが DOCA プログラムのスタックトレース、valgrind の出力、またはコアダンプを確認していて、最初に調べる場所を知りたい場合。
• ユーザーが NGC DOCA コンテナー内でデバッグしており、コンテナー内から何を確認できるか、また何を確認できないかを知る必要がある場合。

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

• 「DOCA_ERROR_BAD_STATE とは何ですか？」「DOCA が返すエラーコードには何がありますか？」 — これはライブラリ横断のエラー分類であり、doca-programming-guide/SKILL.md が担当します。このスキルはその分類を利用しますが、再定義はしません。
• 「pkg-config が doca-flow を見つけられません」「hugepages がマウントされていません」「representor が表示されません」 — これらは環境クラスの症状であり、doca-setup/SKILL.md が担当します。このスキルは、症状がインストール／バージョン／ビルドの前提条件を超えて悪化したときに、環境クラスのデバッグ手順から案内するための標準的な参照先です。
• ライブラリ固有のデバッグ（Flow のパイプレース、RDMA のキューペア状態、Comch のチャネル統計など） — これらは対応するライブラリのスキル（例：doca-flow/SKILL.md）で扱います。このスキルは横断的なデバッグ手順を提供し、ライブラリのスキルはその上にライブラリ固有のデバッグ情報を加えます。

このスキルでできること

これは薄いローダーです。本文には、次に読むべきファイルを選ぶために必要な概要だけを記載しています。具体的なデバッグ情報は、次の2つの関連ファイルにあります。

• capabilities 関連ファイル — DOCA が公開するデバッグ対象の種類：階層化されたデバッグモデル（インストール／バージョン／ビルド／リンク／ランタイム／プログラム）、読み取り専用を優先する方針、デバッグツールのバージョンごとの利用可否（例：doca_caps は DOCA 2.6.0 以降）、ライブラリ横断のエラー分類（相互リンクのみ — doca-programming-guide が管理）、DOCA が出力する可観測性のプリミティブ（stderr ログ、--sdk-log-level、doca-<lib>-trace ビルドフレーバー、ライブラリカウンター）、デバッグ操作に関する安全上の制約（まず読み取り専用で調査し、調査中にインストールツリーを変更しない）。
• tasks 関連ファイル — 実際のデバッグワークフロー：## configure（詳細なデバッグ用の環境を設定）、## test（再現可能な状態を取得）、## debug（標準的な階層化手順。すべてのライブラリの ## debug がリダイレクトする共通の入口）、および問い合わせ先の案内（NVIDIA DOCA Developer Forum）。その他の3つのアンカー（build、modify、run）は、lint に準拠するためのもので、doca-programming-guide/SKILL.md に案内します。環境／プログラムの切り分け後のこれらの動詞は、同ファイルが担当します。

読み込み順

1. まずこのスキルを読み、ユーザーの症状が横断的なデバッグの対象であることを確認します（環境クラスのみ、プログラムクラスのみ、ライブラリ内部のみの問題ではないこと）。
2. 階層化されたデバッグモデル、読み取り専用を優先する方針、デバッグツールのバージョンごとの利用可否、および DOCA が出力する可観測性の対象については、capabilities 関連ファイルを参照してください。
3. 標準的な階層化デバッグ手順と、状態の取得と報告のワークフローについては、tasks 関連ファイルを参照してください。 tasks 関連ファイルにある build、modify、run のアンカーは、doca-programming-guide/SKILL.md に案内するスタブです。詳細は同ファイルに記載されています。
4. ユーザーの症状が環境クラス（インストール／ビルドの前提条件）に該当する場合は、doca-setup/SKILL.md に引き継ぎます。プログラムクラスの場合は、doca-programming-guide/SKILL.md に引き継ぎます。ライブラリ内部の問題の場合は、該当するライブラリスキルの ## debug に引き継ぎます（例：doca-flow/SKILL.md）。

2つの関連ファイルは、適切な回答が*"デバッグ固有のガイダンス"ではなく、"公開ドキュメントまたはインストール済みパッケージの構成を調べること"*である場合に、互いに、また doca-public-knowledge-map/SKILL.md へのリンクを設けています。

関連スキル

• doca-public-knowledge-map/SKILL.md — 公開されている DOCA ドキュメントの案内と、インストール済み DOCA パッケージのディスク上の構成。このスキルでは、「X のドキュメントはどこにあるか」、「Y はディスク上のどこにあるか」、*「インストール済みのバージョンを確認するにはどうすればよいか」*という質問をすべてナレッジマップに委ねます。
• doca-setup/SKILL.md — 環境クラスのデバッグ（インストール／ビルドの前提条件）：pkg-config の失敗、hugepages の不足、representor が表示されない問題、ヘッダーとランタイムのバージョン不一致。doca-setup ## debug は環境クラスの階層化手順です。このスキルは、環境クラスとプログラムクラスの両方の手順がエスカレーションする、横断的なデバッグ手順です。
• doca-programming-guide/SKILL.md — プログラムクラスのデバッグ（ライフサイクルの順序、DOCA_ERROR_* の解釈、doca_error_get_descr() の使用、コミット前に検証するルール）。doca-programming-guide ## debug はプログラムクラスの階層化手順です。症状がライブラリ横断のツール（gdb、valgrind、コンテナーのイントロスペクション、コアダンプ）に関係する場合は、その続きとしてこのスキルが対応します。
• ライブラリスキル（例：doca-flow/SKILL.md、doca-dms/SKILL.md、doca-caps/SKILL.md）— ライブラリ固有のデバッグ用オーバーレイ。各ライブラリの ## debug は、ここで定義する横断的な手順を基盤として、独自のカウンター、トレース、インスペクターツールを追加します。