次の方法で共有

EXDI デバッガー トランスポートの構成

  • [アーティクル]

このトピックでは、EXDI を使用してカーネル モード デバッグを設定する方法について説明します。 拡張デバッグ インターフェイス (EXDI) は、ソフトウェア デバッガーとデバッグ ターゲットの間の適合レイヤーです。

  • Windows デバッグ ツールでは、Windows バージョン 22000 以降の EXDI を使用したカーネル デバッグがサポートされています。

  • EXDI を構成するためのユーザー インターフェイスは、バージョン 1.2410.11001.0 以降のデバッガーで使用できます。

EXDI を使用して、QEMU 仮想環境との接続を確立できます。 詳細については、「 EXDI を使用した QEMU カーネル モード デバッグの設定を参照してください。

Note

EXDI は、特定の環境向けの高度で特殊な形式のデバッグです。 標準の KDNET 接続を使用するほうが構成が容易であり、推奨されます。 ネットワーク デバッグを自動的に設定するには、「KDNET ネットワーク カーネル デバッグの自動設定」を参照してください。

EXDI COM サーバーの概要

EXDI は、ハードウェア デバッガー (JTAG ベース、GdbServer ベースなど) のサポートを追加することで WinDbg を拡張するインターフェイスです。 次の図は、EXDI-GdbServer の役割を示しています。

上に WinDbg-DbgEng がある EXDI-GdbServer ロール、EXDI インターフェイス、GDB サーバーと通信する EXDI COM サーバー示すスタック図。

COM サーバーは、COM インターフェイスを実装するバイナリ コンポーネントを指します。 この場合、windows デバッガー プロトコル クライアントのExdiGdbSrv.dllによって実装される exdi3.idl。

ExdiGdbsrv.dll自体は、GDB サーバー側 (または GDB サーバー スタブとも呼ばれます) が QEMU GDB サーバー (または Trace32/OpenOCD/UEFI GDB サーバー スタブなど) によって実装される GDB-RSP プロトコルのクライアント側を実装します。

EXDI 接続は、ターゲット PC に読み込まれている Windows または Windows デバッグ KDNET プロトコルに依存しないためです。 これらのソフトウェア デバッガー コンポーネントが不要なため、EXDI は、デバイス導入の初期段階や、OS の起動の問題のデバッグに役立ちます。

重要

EXDI は KDNET プロトコルを使用しないため、接続されたデバッガーでは、PC 上で実行されている内容に関する情報が大幅に少なく、多くのコマンドで動作が異なるか、まったく機能しない可能性があります。 デバッグ対象のコードのプライベート シンボルにアクセスすることで、デバッガーがターゲット システムのコード実行について、より詳細に把握するのに役立ちます。 詳細については、「パブリック シンボルとプライベート シンボル」を参照してください。

EXDI カーネル モード デバイスの要件

デバッガを実行するコンピューターは ホスト コンピューターと呼ばれ、デバッグ対象のコンピューターは ターゲット コンピューターと呼ばれます。

次が必要です。

  • ターゲット コンピューターとホスト コンピューターに、QEMU などの、目的の環境でサポートされているネットワーク カードが必要です。

  • ターゲットとホストの間の、TCP/IP を使用したネットワーク接続。

  • Windows 10 または Windows 11 のバージョン 22000 以降。

制限事項

前述のように、EXDI は KDNET プロトコルを使用しないため、接続されたデバッガーではターゲット システムに関する情報が少なく、デバッガーの使用方法が異なります。 ターゲット コードのプライベート シンボルにアクセスしないと、ターゲット システムの状態を把握するためにシンボルを使用する多くのコマンドが機能しません。 この場合、メモリを表示し、内容を登録して、コードを逆アセンブルすることができます。 コードの実行場所の特定や、他の一般的なデバッガー タスクの実行は、プライベート シンボルがないと非常に困難で時間がかかる場合があります。

EXDI と KDNET の同時デバッグ

デバイス導入の初期段階など、一部の複雑なシナリオでは、ターゲット デバイスに 2 つの接続があると便利です。 1 つは EXDI で、1 つは KDNET です。 ターゲットが Windows OS の場合、KDNET ソフトウェア のデバッグは、仮想マシンへの接続など、通常と同様に構成されます。 この設定では、2 つの同時デバッガーのいずれかにターゲット コンピューターの処理を一時停止させてコードをデバッグすることができます。

プロセス サーバー内の WinDbg

バイナリ EXDI コンポーネントは、Windbg プロセスから、または Windbg プロセス内で実行できます。 EXDI UI または Inproc=<EXDI COM server binary> を使用すると、COM の起動エラーを減らすことで、信頼性が大幅に向上します。 そのため、UI を使用する場合は常に有効になる Inproc パラメーターを使用して EXDI セッションを実行することをお勧めします。

コマンド ラインのスタートアップの場合、既定のオプションはプロセス外ですが、 InProc=ExdiGdbDrv.dll パラメーターを使用して inprocess を有効にする必要があります。

COM GDB サーバー クライアント

このトピックでは、EXDI COM デバッガー インターフェイスを実装する EXDI COM GDB サーバー クライアント (ExdiGdbSrv.dll) の使用方法について説明します。 同じ COM インターフェイスを使用して、JTAG-DCI 用 EXDI COM サーバーなど、他のインターフェイスを実装できます。

EXDI 接続を使用するプロセスの概要

WinDbg との EXDI 接続を使用するには、このプロセスを使用します。

  1. Windows デバッグ ツールをホスト システムにダウンロードしてインストールします。
  2. UI または -kx オプションを使用して WinDbg を起動し、EXDI サーバーに接続します。
  3. WinDbg を使用して、使用可能なデバッガー コマンドのサブ セットを使用してターゲット システムをデバッグします。

EXDI 使用シナリオの例については、「 EXDI を使用した QEMU カーネル モード デバッグの設定を参照してください。

Windows デバッグ ツールをダウンロードしてインストールする

Windows デバッグ ツールをホスト システムにインストールします。 デバッガー ツールのダウンロードとインストールについては、「Windows 用デバッグ ツール」を参照してください。

WinDbg を起動して EXDI サーバーに接続する

EXDI カーネル接続 UI では、次のオプションを構成できます。

Windbg EXDI カーネル接続 UI。IP アドレスとポート アドレスを含む接続オプションが表示されます。

  • ターゲットの種類 [Trace32|BMC-OpenOCD|QEMU|VMWare|UEFI] デバッグするターゲットの種類に応じて選択します。 次のターゲットの種類を使用できます。

    • Trace32: Lauterbach Trace32 HW デバッガー GDB サーバーの構成
    • BMC-OpenOCD: BMC-OpenOCD HW デバッガー GDB サーバーの構成
    • QEMU : QEMU SW シミュレーター GDB サーバーの構成
    • VMWare: VMWare GDB サーバーの構成
    • UEFI : UEFI ファームウェアのデバッグ

  • ターゲット アーキテクチャ [x86 | ARM64 | x64] - ターゲット プロセッサ アーキテクチャ。 すべてのターゲットの種類が、すべてのターゲット アーキテクチャをサポートしているわけではないことに注意してください。

  • ターゲット OS [Windows|Linux] - デバッグするターゲット OS に従って選択します。

  • 画像スキャンヒューリスティック サイズ [None | 0xFE - PreNT |0xFFE - NT] - 画像スキャンのヒューリスティック サイズを決定する 3 つのオプションのいずれかを選択します。 この値は、コードの実行状態を収集するために使用される PE DOS 署名を探してデバッガー エンジンがメモリをスキャンする方法を構成します。 属性値が指定されていない (または "0") 場合、デバッガー エンジンは高速ヒューリスティックを使用せず、PE DOS 署名を探してメモリ全体をスキャンする従来のヒューリスティックにフォールバックします。 既定値はターゲットの種類ごとに選択され、推奨されます。

  • Gdb サーバーとポート TargetIPAddress:TargetPortAddress - IPTargetAddress、コロン、およびターゲット PortAddress を含む文字列に設定します。 たとえば、LocalHost:1234 や 168.82.1.5:5555 などです。

  • 接続の中断 [on|off] 接続が確立された後にターゲットに分割するチェック ボックスをオンにします。

  • 詳細オプション

    通信パケット ログの表示 [on|off] - デバッグとトラブルシューティングのために生の GDBServer 通信パケット ログを 16 進値で表示する場合は、チェック ボックスをオンにします。

目的のオプションが選択されたら、 Ok を選択して接続します。

EXDI 構成 XML ファイルを使用して詳細オプションを構成する

ほとんどの必要なオプションは、このトピックで説明するユーザー インターフェイスで使用できます。 EXDI 構成 XML ファイルを使用して詳細オプションを構成する方法については、「 EXDI XML 構成ファイルを参照してください。

WinDbg コマンド ライン EXDI の例

コマンド プロンプトで EXDI インターフェイスを使用する windbg セッションを起動するには、次のオプションを使用します。

c:\Debuggers> windbg.exe -v -kx exdi:CLSID={29f9906e-9dbe-4d4b-b0fb-6acf7fb6d014},Kd=Guess,InProc=ExdiGdbDrv.dll,DataBreaks=Exdi

診断に役立つ追加の出力を表示するには、 -v: 詳細セッションを使用できます。 WinDbg オプションの一般的な情報については、「WinDbg コマンド ライン オプション」を参照してください。 詳細については、後述の「EXDI WinDbg 読み込みパラメーター」を参照してください。

デバッガー コンソールに EXDI トランスポートの初期化が表示されます。

EXDI: DbgCoInitialize returned 0x00000001
EXDI: CoCreateInstance() returned 0x00000000
EXDI: QueryInterface(IExdiServer3) returned 0x00000000
EXDI: Server::GetTargetInfo() returned 0x00000000
EXDI: Server::SetKeepaliveInterface() returned 0x00000000
EXDI: Server::GetNbCodeBpAvail() returned 0x00000000
EXDI: ExdiNotifyRunChange::Initialize() returned 0x00000000
EXDI: LiveKernelTargetInfo::Initialize() returned 0x00000000
EXDI: Target initialization succeeded
Kernel Debugger connection established

ウィンドウ タイトルに EXDI CLSID が表示されているメインの WinDbg セッション。

EXDIGdbServer コンソール ウィンドウにも、EXDI 接続の状態に関する情報を表示できます。 コンソールの詳細については、「トラブルシューティング」を参照してください。

EXDI WinDbg 読み込みパラメーター

以下のパラメーターは、EXDI カーネル セッションを開始するために WinDbg と共に使用されます。

-kx EXDI:Options

以下の EXDI オプションは、-kx オプションで使用できます。 各オプションはコンマで区切る必要があります。

パラメーター 説明
CLSID LiveExdiGdbSrvServer に割り当てられたクラス ID (ExdiGdbSrv.idl ファイルで定義)。
Kd=Guess -or- NtBaseAddr デバッガー エンジンは、一般的なヒューリスティック メカニズムを使用するか、NT ベース アドレスを探します。
ForceX86 CPU コンテキストの取得/設定に IeXdiX86Context3 インターフェイスを使用するように、デバッガー エンジンに強制します。
DataBreaks=Exdi データ ブレークポイントの使用を許可します。
Inproc inproc Exdi-Server の使用を許可します。 このオプションをお勧めします - InProc=ExdiGdbDrv.dll
PathToSrvCfgFiles EXDI の XML 構成ファイルへのパス。

ヒューリスティック検索とヒューリスティック サイズの制御

前述のように、デバッガーはヒューリスティック アルゴリズムを使用して NT ベース アドレスを見つけます。 ヒューリスティック検索を取り消すには、コマンド ラインを使用して WinDbg を起動するときに、次の手順を実行します。

  • アタッチするターゲット サーバーのexdiconfigdata.xml ファイルで、ヒューリスティックScanSize を 0 に設定します。
  • Windbg コマンド ラインで kd=NtBaseAddr ヒューリスティック型を使用します。

XML 構成ファイルの操作の詳細については、EXDI XML 構成ファイルを参照してください。

WinDbg を使用してターゲット システムをデバッグする - ブレークポイント

dbgeng.dll では、ヒューリスティック アルゴリズムを使用して、break コマンドが発生した時点の NT ベースの読み込みアドレスの場所を検索します。 プライベート シンボルを使用できない場合、このプロセスは失敗します。

これは、多くの接続シーケンスでは、break が期待どおりに機能しないことを意味します。 手動でコードを一時停止すると、その時点で Windows が実行していたランダムな場所になります。 ターゲット コードのシンボルを使用できない可能性があるため、シンボルを使用してブレークポイントを設定することが困難な場合があります。

デバッガー コマンド

メモリに直接アクセスする次のようなコマンドは機能します。

k、kb、kc、kd、kp、kP、kv (スタック バックトレースの表示)

r (レジスタ)

d、da、db、dc、dd、dD、df、dp、dq、du、dw (メモリの表示)

u (逆アセンブル)

p (ステップ) を使用すると、コードをステップごとに実行できます。

デバッグ対象のコードの場所を特定するために使用できるコマンドもあります。

s (メモリの検索)

.imgscan (イメージ ヘッダーの検索)

従来の KDNET ベースのカーネル デバッグとは異なり、シンボルに基づいてブレークポイントを設定できない場合があるため、Imgscan は EDXI デバッグで役立ちます。 目的のターゲット イメージの場所を特定することで、その場所を使用してメモリ アクセス ブレークポイントを簡単に設定できるようになります。

.exdicmd (EXDI コマンド)

.exdicmd は、アクティブな EXDI デバッグ接続を使用して、EXDI コマンドをターゲット システムに送信します。 詳細については、「.exdicmd (EXDI コマンド)」を参照してください。

トラブルシューティング

ExdiGdbServer ウィンドウからの出力を使用して、接続シーケンスを監視します。

長い 16 進数を表示する ExdiGdbServer テキスト ウィンドウ。

問題: エラー: GbDServer との接続を確立できません。 接続文字列を確認する <hostname/ip>:portnumber

この問題は、次の理由により発生する場合があります。

  • ExdiGdbSrv.dll がターゲット GDB サーバーに接続できない。
  • GDB サーバーがターゲットでまだ実行されていない。
  • ファイアウォールの問題については、ping、tracert、またはその他のツールを使用して両方の IP アドレスに到達できることを確認し、GDB トラフィックがファイアウォールを通過できることを確認します。

問題: ターゲット システムでのエラー シナリオが使用できない - DbgCoInitialize が 0x00000001 を返しました

ターゲット システムが読み込まれていない場合か使用できない場合は、次の出力が返される可能性があります。

Microsoft (R) Windows Debugger Version 10.0.20317.1 AMD64
Copyright (c) Microsoft Corporation. All rights reserved.

EXDI: DbgCoInitialize returned 0x00000001

これは、ExdiGdbSrv.dll COM サーバーが QEMU GDServer に接続できなかったときの一般的なエラーであり、原因には以下のようなものがあります。

  • ExdiGdbSrv.dll の前回のセッションが dllhost.exe プロセスによってホストされたままであるため、dllhost.exe プロセスを強制終了する必要があります。 コマンド プロンプトで TaskList を使用して、ExdiGdbSrv.dllをホストするdllhost.exeの PID を見つけます。 TaskKill /PID <PID ID> /fを使用し、関連付けられている PID を強制終了します。 PID の操作の詳細については、「 プロセス ID の検索を参照してください。

  • QEMU gdbserver がまだ起動されていないか、exdiconfigdata.xml ファイルに無効な IP:Port 値が含まれています。 WinDbg セッションが QEMU Windows VM と同じホスト PC で起動された場合は、IP=LocalHost です。

  • dllhost.exe プロセス (COM 関連) を介して EXDI COM サーバー (ExdiGDbSrv.dll) を起動する際のエラー。 これを解決するには、ホスト デバッガー PC を再起動するか、Windows からサインアウトしてもう一度サインインします。 それでも問題が解決しない場合は、再起動またはサインイン後に EXDI COM サーバーを登録し直します。

    • regsvr32.exe <full path to the ExdiGdbSrv.dll)

問題: デバッグ セッションを開始できませんでした: FAILURE HR=0x80004005:AttachKernel に失敗しました。

この問題は、次の理由により発生する場合があります。

  • 前述のように、ExdiGdbSrv.dll の前回のセッションがまだアクティブである可能性があります。 前述のように、関連付けられている DLL ホストを特定して終了します。

HR 0x80004005 のエラーが表示されている WinDbg ダイアログ ボックス。

問題: EXDI を使用したカーネル デバッグを開始できませんでした。

この問題は、次の理由により発生する場合があります。

  • ホスト デバッガー コンピューター上に、実行中の ExdiGdbSrv.dll (dllhost.exe によってホストされる) の別のインスタンスがあります。
  • ExdiGdbSrv.dll をホストしている COM サービスの追加インスタンスを終了します。
    • まず、ホスト PC 上で TList などのユーティリティを使用して、プロセスを一覧表示します。 ExdiGdbSrv.dll をホストしている DLLHost に、 ExdiGdbServerが表示されます。

      tlist 261928 dllhost.exe ExdiGdbServer

    • デバッガーのコマンド プロンプトで kill -f XXXXX を使用して、そのプロセス番号を使用しているプロセスを終了します。

問題: エラー: GdbServer セッションを構成できません。

この問題は、次の理由により発生する場合があります。

  • XML 構成ファイルへのパスなど、セッション情報の検索中にエラーが発生しました。

問題: エラー: EXDI_GDBSRV_XML_CONFIG_FILE 環境変数が定義されていません。

この問題は、次の理由により発生する場合があります。

  • ExdiGdbSrv.dll 環境変数が設定されていないか、環境で使用できません。

問題: エラー: EXDI_GDBSRV_XML_CONFIG_FILE環境変数が定義されていません。 Exdi-GdbServer サンプルは、この時点では続行されません。 Exdi XML 構成ファイルへの完全なパスを設定します。

この問題は、次の理由により発生する場合があります。

  • EXDI_GDBSRV_XML_CONFIG_FILE 環境変数が設定されて いません。 状況によっては、[OK] ボタンを押しても ExdiGDbSrv.dll は動作し続けますが、windbg.exe でシステム レジスタのクエリの実行が失敗します (例: rdmsr/wrmsr 関数を使用)。

関連項目

EXDI を使用した QEMU カーネル モード デバッグの設定

.exdicmd (EXDI コマンド)

EXDI XML 構成ファイル

KDNET ネットワーク カーネル デバッグの自動設定

KDNET ネットワーク カーネル デバッグの手動設定

カーネル モードのデバッグを手動でセットアップする