KDNET を使用した 2PF カーネルモード デバッグの設定
Windows 用デバッグ ツールでは、PCI 構成領域をパーティション分割することで、サポートされている NIC で複数の物理機能 (PF) を使用したネットワーク ケーブル経由のカーネル デバッグをサポートします。
2PF デバッグでは、各 PF を 1 つのネットワーク ポートに接続できるため、標準ネットワーク スタックが他の PF と通信中に、カーネル デバッグ機能を 1 つの PF に接続できます。 このため、KDNIC では KDNET 経由で Windows ネットワーク トラフィックをルーティングする必要はありません。KDNET はホスト カーネル デバッガー トラフィックのルーティングのみを行います。 これにより、パフォーマンスが大幅に向上します。
このトピックでは、kdnet.exe ユーティリティを使用して 2PF デバッグを設定する方法について説明します。
ネットワーク カード ベンダーは、この機能のサポートを有効にすることをお勧めします。 詳細については、「デバッガ― 2PF KDNET ミニポート ネットワーク ドライバーのサポート」を参照してください。
パーティション分割された PCI 構成領域で 2 つのドライバーが実行されます
Windows 受信トレイ ドライバーは、bus.dev.fun0.0 PCI ロケーションでプライマリ ネットワーク ポートから実行されます。
KDNET-Ext. モジュールは、bus.dev.fun0.1 で追加 PF から実行されます。この技法を活用して、KDNET と NIC を共有し、Windows 受信トレイ NIC ドライバーが影響を受けないようにします。
デバッガを実行するコンピューターはホスト コンピューターと呼ばれ、デバッグ対象のコンピューターはターゲット コンピューターと呼ばれます。
カーネルモード 2PF デバイスの要件
次が必要です。
ターゲット コンピューターでは、サポートされている 2PF ネットワーク カード。
ホスト コンピューターでは、ネットワーク カード。
ターゲットとホスト間のネットワーク接続。
Windows 10 ビルド 21313 以降。
サポートされている 2PF ネットワーク カード
NVIDIA Mellanox や Cisco などのベンダーは、2PF ネットワーク デバッグをサポートする NIC を提供しています。 サポートされているネットワーク カードのモデルを確認するには、ネットワーク カード ベンダーにお問い合わせください。 なお、ベンダーによっては、同じ PnP ID を共有するネットワーク カードのサブセットで 2PF をサポートしています。
kdnet.exe を使用してデバイスのサポートを確認し、busparams 値を表示する
KDNET 2PF トランスポート デバッグをサポートするコントローラーのパラメーター情報を表示するには、kdnet.exe ユーティリティーを使用します。
Windows 用デバッグ ツールがホスト システムにインストールされていることを確認します。 デバッガー ツールのダウンロードとインストールについては、「Windows 用デバッグ ツール」を参照してください。
kdnet.exe ファイルと VerifiedNICList.xml ファイルを見つけます。 既定では、これらのファイルは次の場所にあります。
C:\Program Files (x86)\Windows Kits\10\Debuggers\x64ホスト コンピューターで、2 つのファイルをネットワーク共有またはサム ドライブにコピーして、ターゲット コンピューターで使用できるようにします。
ターゲット コンピューターで
C:\KDNETディレクトリを作成し、kdnet.exe ファイルと VerifiedNICList.xml ファイルをそのディレクトリにコピーします。ターゲット コンピューターで、管理者として [コマンド プロンプト] ウィンドウを開きます。 サポートされているネットワーク アダプターがこのコンピューターにあることを確認したり、busparams 値を表示したりするには、次のコマンドを入力します。
C:\KDNET>kdnet.exe Network debugging is supported on the following NICs: busparams=141.0.0, Mellanox ConnectX-4 Lx Ethernet Adapter #2, Plugged in, Primary function, multiple physical functions are supported. Network debugging is supported on the following USB controllers: busparams=128.15.0, Standard USB 3.0 eXtensible Host Controller - 1.0 (Microsoft) busparams=0.15.0, Standard USB 3.0 eXtensible Host Controller - 1.0 (Microsoft) busparams=128.15.1, Standard USB 3.0 eXtensible Host Controller - 1.0 (Microsoft) busparams=0.15.1, Standard USB 3.0 eXtensible Host Controller - 1.0 (Microsoft)上記の出力には "KDNET is running on this NIC. (KDNET はこの NIC で実行中です)" が含まれていないため、これは、従来の KDNET デバッグがどのアダプターでも有効になっていないことを示しています。
NIC が複数の PF 機能をサポートしていない場合、"multiple physical functions are supported (複数の物理機能がサポートされています)" という PF 状態通知は、表示される情報から省かれます (空白になります)。
NIC が複数の PF をサポートしている場合、実際に表示される情報は、ネットワーク ポート (ルート ポート/PF 追加ポート) の組み合わせと、NIC 物理ポートとのケーブルの接続/切断状態によって異なります。
次のテーブルは、プライマリ NIC のさまざまな PF 通知をまとめたものです。
NIC アダプターの bus.dev.fun は次に対応 ケーブルの状態 PF の状態 original (プライマリ) PF ケーブルが接続されている プライマリ機能、複数の物理機能が有効になっている original (プライマリ) PF ケーブルが切断されている プライマリ機能、複数の物理機能がサポートされている 次のテーブルは、セカンダリ NIC のさまざまな PF 通知をまとめたものです。
NIC アダプターの bus.dev.fun は次に対応 ケーブルの状態 PF の状態 新しい (セカンダリ) PF ポート Kdnet が実行されている セカンダリ機能 新しい (セカンダリ) PF ポート ケーブルが切断されているか、不明な状態 プライマリ機能、複数の物理機能が有効になっているが、セカンダリ機能は使用されない kdnet.exe からの出力に、サポートされている NIC コントローラーが使用可能であることが示されている場合は、続行できます。
2PF のターゲット・コンピューターのセットアップ
次の手順に沿って、kdnet.exe ユーティリティを使用し、ターゲット PC で 2PF のデバッガー設定を構成します。
重要
BCDEdit を使用してブート情報を変更する前に、テスト PC で BitLocker やセキュア ブートなどの Windows セキュリティ機能を一時的に中断することが必要になる場合があります。 BCDEdit を使用してブート情報を更新したら、Bit Locker と Secure Boot を再度有効にできます。 セキュリティ機能が無効になっている場合は、テスト PC を適切に管理してください。
このプロセスにより、bus.device.function で指定された NIC に新しい物理機能 (PF) が追加されます。 Windows 受信トレイ ドライバーは追加されたセカンダリ PF で実行されないように設定されているため、新しい PF は KDNET でのみ使用できます。 次の手順に沿って、デバッグ デバイスで使用される新しい PF を追加します。
新しい物理機能を追加する前にデバッグが無効になっていることを確認します
- BCDEdit コマンドを使用し、NIC に新しい PF を追加する前に、ターゲットで KD が無効になっていることを確認します。 標準ベンダー NIC ドライバーが読み込まれており、それを使用して新しい PF を追加できることを確認するには、これを行う必要があります。
C:\> bcdedit /enum
...
debug No
別の方法として、パラメーターを指定しないで kdnet.exe を使用し、デバッグが有効になっているかどうかを確認します。 次の出力は、1 つの NIC でデバッグが有効になっているシステム上で KDNET が実行されていることを示します。 これは、低パフォーマンスのレガシ セットアップです。
c:\Debuggers>kdnet
Network debugging is supported on the following NICs:
busparams=141.0.0, Mellanox ConnectX-4 Lx Ethernet Adapter #2, KDNET is running on this NIC.
Network debugging is supported on the following USB controllers:
busparams=128.15.0, Standard USB 3.0 eXtensible Host Controller - 1.0 (Microsoft)
busparams=0.15.0, Standard USB 3.0 eXtensible Host Controller - 1.0 (Microsoft)
busparams=128.15.1, Standard USB 3.0 eXtensible Host Controller - 1.0 (Microsoft)
busparams=0.15.1, Standard USB 3.0 eXtensible Host Controller - 1.0 (Microsoft)
- デバッグ値が [はい] に設定されている場合は、set コマンドを使用してデバッグを無効にします。
C:\> bcdedit.exe /debug off
C:\> bcdedit.exe /set {default} bootdebug off
C:\> bcdedit.exe /set {bootmgr} bootdebug off
- 管理者のコマンド プロンプトから
shutdown -r -t 0コマンドを使用して再起動します。
ターゲット PC が再起動し、デバッグが無効になったら、新しい物理機能を追加できます。
新しい物理機能を追加する
- 管理者特権のコマンド プロンプトを開き、次のコマンドを実行して別の PF を追加します。 すべての値は、10 進値で指定されます。
C:\KDNET> kdnet -addpf 141.0.0 198.51.100.1 50001
Succeeded adding a Pci PF on :141.0.1. Please power off or reboot the machine.
Enabling network debugging on Mellanox ConnectX-4 Lx Ethernet Adapter #2.
Manage-bde.exe not present. Bitlocker presumed disabled.
To debug this machine, run the following command on your debugger host machine.
windbg -k net:port=50001,key=2steg4fzbj2sz.23418vzkd4ko3.1g34ou07z4pev.1sp3yo9yz874p
Then reboot this machine by running shutdown -r -t 0 from this command prompt.
bus.dev.fun は、複数の PF 機能をサポートする NIC アダプターの PCI ロケーション ポートであるため、新しい PF はこのネットワーク デバイスに追加またはアタッチされます。
-addpf オプションを使用すると、追加された PF ポートでは、カーネル デバッグが KDNET トランスポート経由で自動的に有効になります。
[host name/host ip address] は、ホスト コンピューターの TCP/IP アドレスです。 ホスト コンピューター上の ipconfig コマンドを使用して、このアドレスを確認します。
[port number] は、TCP/IP ポート番号です。 49152 から 65535 までの任意のポート番号を選択できます。 推奨範囲は 50000 から 50039 です。 選択したポートが開き、ホスト コンピューターで実行されているデバッガーが排他的にアクセスできるようになります。 50000 から 50039 の推奨範囲内で、使用するターゲット/ホスト ペアごとに一意のポート アドレスを選択します。 例では 50005 が示されています。
-addpf の場合、OS installation {default} loadoptions に NO_KDNIC 属性も追加されることにご注意ください。 これは、KDNET 上で KDNIC を実行する必要がなくなったためです。
新たに追加された PF (141.0.1) から実行されないようにするために、"loadoptions = NO_KDNIC" が {default} OS タグに追加されています。
bcdedit コマンドを使用して、NO_KDNIC が設定されていることを確認します。
C:\KDNET> bcdedit /enum {default}
Windows Boot Loader
-------------------
identifier {current}
device partition=C:
path \Windows\system32\winload.efi
description Windows Server
locale en-US
loadoptions NO_KDNIC
inherit {bootloadersettings}
recoverysequence {c23c4005d-12ae-11eb-9399-ac9840c152e7}
displaymessageoverride Recovery
recoveryenabled Yes
bootdebug No
testsigning Yes
isolatedcontext Yes
flightsigning Yes
allowedinmemorysettings 0x15000075
osdevice partition=C:
systemroot \Windows
resumeobject {c23c4005d-12ae-11eb-9399-ac9840c152e7}
nx OptOut
debug Yes
hypervisordebug No
2. Run the bcdedit /enum command to display the generated key.
```console
C:\KDNET> bcdedit /dbgsettings
busparams 141.0.1
key 2steg4fzbj2sz.23418vzkd4ko3.1g34ou07z4pev.1sp3yo9yz874p
debugtype NET
hostip 198.51.100.1
port 50001
dhcp Yes
The operation completed successfully.
返されたキーをメモ帳の .txt ファイルにコピーします。 次の例では、生成されたキーには次の値が設定されています。
2steg4fzbj2sz.23418vzkd4ko3.1g34ou07z4pev.1sp3yo9yz874p必要に応じて、kdnet.exe を使用して、複数の物理機能が有効になっていることを確認します。
C:\KDNET> kdnet.exe
Network debugging is supported on the following NICs:
busparams=141.0.0, Mellanox ConnectX-4 Lx Ethernet Adapter #2, Plugged in, Primary function, multiple physical functions are enabled.
busparams=141.0.1, Mellanox ConnectX-4 Lx Ethernet Adapter, KDNET is running on this NIC, Secondary function.
Network debugging is supported on the following USB controllers:
busparams=128.15.0, Standard USB 3.0 eXtensible Host Controller - 1.0 (Microsoft)
busparams=0.15.0, Standard USB 3.0 eXtensible Host Controller - 1.0 (Microsoft)
busparams=128.15.1, Standard USB 3.0 eXtensible Host Controller - 1.0 (Microsoft)
busparams=0.15.1, Standard USB 3.0 eXtensible Host Controller - 1.0 (Microsoft)
ホスト上のファイアウォールを無効にする
ホストで、デバッガー ポートのファイアウォールを無効にします。
カーネル デバッグ用ターゲットへの WinDbg の接続
ホスト コンピューターで WinDbg を開きます。 [ファイル] メニューの [カーネル デバッグ] を選択します。 [カーネル デバッグ] ダイアログ ボックスで、[Net] タブを開きます。先ほどメモ帳の .txt ファイルに保存したポート番号とキーを貼り付けます。 [OK] を選択します。
[コマンド プロンプト] ウィンドウを開き、次のコマンドを入力して、WinDbg セッションを開始することもできます。ここで、ポートは上記で選択したもの、キーは上記の kdnet.exe で返されたものになります。 先ほどメモ帳の .txt ファイルに保存したキーを貼り付けます。
windbg -k -d net:port=<YourDebugPort>,key=<YourKey>
ターゲット コンピューターを再起動する
デバッガーが接続されたら、ターゲット コンピューターを再起動します。 PC を再起動する方法の 1 つは、管理者のコマンド プロンプトから shutdown -r -t 0 コマンドを使用することです。
ターゲット PC を再起動したら、デバッガーは自動的に接続されます。
コンピューターが再起動したら、NIC ファームウェアは新たに追加された KDNET PF に新しい MAC アドレスを割り当て、dbgsettings::busparams は新たに追加された PF を指します。
2PF アダプターの MAC アドレスの検索
新たに追加された PF は PCI バスで構成されたポートであるため、NIC ファームウェアによって、新たに追加された PF に新しい MAC アドレス値が割り当てられます。 kdnet.exe ツールでは現在、追加された 2PF の MAC アドレスの表示はサポートされていません。
新しい MAC アドレスを見つけるには、次の 2 つの方法があります。
ローカル KD セッションで WinDbg/KD を使用する
ターゲットでローカル カーネル デバッガ― windbg.exe -kl を実行します。
.reload /f kdnet.dll を実行して、kdnet.pdb シンボル ファイルにアクセスできることを確認します
.kdtargetmac コマンドを実行して MAC アドレスを取得します。
kd> .kdtargetmac
Force unload of kdnet.dll
ModLoad: fffff800`18510000 fffff800`18557000 kdnet.dll
Loading symbols for fffff800`18510000 kdnet.dll -> kdnet.dll
The target machine MAC address in open-device format is: DC9840C151E8
ベンダー提供のファームウェア ツールを実行する
MAC アドレスを見つける方法の 1 つは、ベンダー提供のファームウェア ツールを実行することです。 ベンダーのツールのダウンロード、インストール、使用については、NIC ベンダーを参照してください。
...
Base MAC: 98039baa757c 4
MAC アドレス フィールドを見つけます。 KDNET 2PF MAC アドレスの値は、ルート MAC デバイスの最後の桁に順次 1 を加算して計算されます。 そのため、98039baa757c というアドレスを持つルート デバイスであれば、KDNET 2PF デバイスには 98039baa757d というアドレスが設定されます。
以前の構成状態の復元 - 別の PCI PF の削除
kdnet -removepf オプションと元の bus.device.function 値を使用して、以前追加した PF をデバイスから削除できます。 PF は NIC からデタッチされ、PF で割り当てられたリソースは NIC ファームウェアによって解放されます。
KDNET PF をデバイスから削除するには、管理者特権のコマンド プロンプトを開き、次のコマンドを実行します。
kdnet -removepf [bus.dev.fun] [host name/host ip address] [port number]
ここで、bus.dev.fun は PF が最初に接続されていた NIC アダプターの PCI ロケーション ポートです。 これは、最初に kdnet の -addpf に渡されたのと同じ PCI ロケーションです。
-removepf オプションを使用しても、元の bus.dev.fun で KDNET 経由のカーネル デバッグを再度有効にできます。
C:\KDNET> kdnet -removepf 141.0.0 198.51.100.1 50001
Succeeded removing a Pci PF on :141.0.0. Please power off or reboot the machine.
Enabling network debugging on Mellanox ConnectX-4 Lx Ethernet Adapter #2.
Manage-bde.exe not present. Bitlocker presumed disabled.
kdnet.exe の -removepf コマンドも、OS installation {default} loadoptions から NO_KDNIC 属性を削除します。KDNET が元の bus.dev.fun で有効になる、つまり dbgsettings::busparams が元のネットワーク ポートを指すことになるためです。 これにより KDNIC が再び使用され、KDNET 上でネットワーク接続が再び提供されます。
PF が削除されたら、BCD の変更を適用するためにコンピューターを再起動する必要があります。
shutdown -r -t 0
ホスト アダプター構成のトラブルシューティング
デバイス・マネージャーに 2PF アダプターがあることを確認する
KDNET PF が正常に追加されたことを確認するには、Windows デバイス マネージャーのアダプター一覧に、新しい NIC アダプターの新しい bus.dev.fun ポートが含まれていることを確認します。
この図は、3 つの異なるアダプターがあり、アダプター #2 はカーネル デバッガ―で使用するために予約済みであることを示しています。
一般的なエラー メッセージ - 新しい PF の追加
C:\KDNET> kdnet -addpf 28.0.0 192.168.137.1 50005
Device Name:\\.\Mlx5Util
Pci Bus:28.0.0
PCI PF はこのポートで既に構成されています: Error=(0x80004004) デバッグ デバイスでの PF 操作に失敗しました。デバッグ デバイスが KDNET 用に構成されていません。
- PF が既に PF として追加されているルート ポートで PF の追加や削除をしないでください。
一般的なエラー メッセージ - PF の削除
C:\KDNET> kdnet -removepf 28.0.1 192.168.137.1 50005
Adapter is not active: Error=(0x80070002)
Device Name:\\.\Mlx5Util
Pci Bus:28.0.1
アダプターがアクティブではありません: Error=(0x80070002) デバッグ デバイスでの PF 操作に失敗しました。デバッグ デバイスが KDNET 用に構成されていません
- 追加された PF ポートでの操作がすべてエラー (エラー: アダプターはポートでアクティブではありません) になるため、"-removepf/-addpf" コマンド ライン パラメーターと追加された PF ポートを併用しないでください。ベンダー NIC 受信トレイ ドライバーが、追加された PF で明示的に実行されないように設定されているためです。
- どちらのコマンド ライン オプション (-addpf/-removepf) も、ルート PCI デバイスでのみ使用する必要があります。
C:\KDNET> kdnet -removepf 28.0.0 192.168.137.1 50005
Device Name:\\.\Mlx5Util
Pci Bus:28.0.0
このポートで削除できる PCI PF はありません: Error=(0x80004005) デバッグ デバイスでの PF 操作に失敗しました。デバッグ デバイスが KDNET 用に構成されていません
- 新しい PF を追加した後で再起動を行わずにその PF を削除すると、エラーが発生します。ベンダー NIC ファームウェアでは、新たに追加された PF が認識される前に、NIC HW の再起動またはリセットをする必要があるためです。
一般的なエラー メッセージ - BCDEdit
NO_KDNIC は BCD OS {default} installation には存在しません。
- 新しい PF を追加した後でデバッグ デバイス (dbgsettings) を変更するために、bcdedit.exe 使用することはお勧めしません。 kdnet の -addpf または removepf のコマンド ライン オプションを使用すると、デバッグ デバイスを構成でき、
NO_KDNICトークンを{default}::loadoptionsに追加したりそこから削除したりといったことも行えます。