Konfigurieren des EXDI-Debuggertransports
In diesem Thema wird beschrieben, wie Sie das Kernelmodusdebugging mit EXDI einrichten. Die Extended Debugging Interface (EXDI) ist eine Anpassungsebene zwischen einem Softwaredebugger und einem Debuggingziel. Die Debuggingtools für Windows unterstützen das Kerneldebugging mit EXDI ab Windows Version 22000.
EXDI kann verwendet werden, um eine Verbindung mit der virtuellen QEMU-Umgebung herzustellen. Weitere Informationen finden Sie unter Einrichten des QEMU-Kernelmodus-Debuggings mit EXDI.
Hinweis
EXDI ist eine fortschrittliche, spezielle Form des Debuggings für bestimmte Umgebungen. Die Verwendung einer Standard-KDNET-Verbindung ist einfacher zu konfigurieren und wird empfohlen. Informationen zum automatischen Einrichten des Netzwerk-Debuggings finden Sie unter Automatisches Einrichten des KDNET-Netzwerk-Kernel-Debuggings.
EXDI COM-Serverübersicht
EXDI ist eine Schnittstelle, die das Erweitern von WinDbg ermöglicht, indem Unterstützung für Hardwaredebugger hinzugefügt wird (z. B. JTAG-basiert oder GdbServer-basiert). Das folgende Diagramm veranschaulicht die Rolle von EXDI-GdbServer.
Da die EXDI-Verbindung keine Abhängigkeit von Windows oder dem KDNET-Protokoll hat, das auf dem Ziel-PC geladen wird. Da diese Softwaredebuggerkomponenten nicht erforderlich sind, kann EXDI bei einem frühen Gerätestart und beim Debuggen von Betriebssystemstartproblemen hilfreich sein.
Wichtig
Da EXDI nicht das KDNET-Protokoll verwendet, verfügt der angeschlossene Debugger über deutlich weniger Informationen über das, was auf dem PC ausgeführt wird, und viele Befehle funktionieren anders oder möglicherweise gar nicht. Der Zugriff auf private Symbole für den zu debuggenden Code kann dem Debugger helfen, die Code-Ausführung des Zielsystems besser zu verstehen. Weitere Informationen finden Sie im Artikel zu öffentlichen und privaten Symbolen.
EXDI Kernel-Mode-Geräteanforderungen
Der Computer, auf dem der Debugger ausgeführt wird, wird als Hostcomputer bezeichnet, und der Computer, der debugged wird, wird als Zielcomputer bezeichnet.
Das Folgende ist erforderlich:
Auf dem Ziel- und Hostcomputer eine unterstützte Netzwerkkarte, die von der gewünschten Umgebung unterstützt wird, beispielsweise QEMU.
Eine Netzwerkverbindung zwischen Ziel und Host mit Verwendung von TCP/IP.
Windows 10 oder Windows 11, Version 22000 oder höher.
Begrenzungen
DAS EXDI-Hardwaredebugging muss manuell mithilfe von XML-Dateien konfiguriert werden, und es gibt keine zugehörige Benutzeroberfläche in den Windows-Debuggern.
Wie oben beschrieben, da EXDI das KDNET-Protokoll nicht verwendet, weist der verbundene Debugger weniger Informationen zum Zielsystem auf und die Verwendung des Debuggers unterscheidet sich. Ohne Zugriff auf private Symbole für den Zielcode funktionieren viele Befehle nicht, die Symbole verwenden, um den Status des Zielsystems zu verstehen. In diesem Fall ist es möglich, Speicher anzuzeigen und Inhalte zu registrieren und Code zu zerlegen. Die Bestimmung des Speicherorts der Ausführung von Code oder das Ausführen anderer gängiger Debuggeraufgaben kann sehr schwierig und zeitaufwändig sein, ohne private Symbole.
COM GDB Server-Client
In diesem Thema wird die Verwendung des EXDI COM GDB Server-Clients (ExdiGdbSrv.dll) behandelt, der die EXDI COM-Debuggerschnittstelle implementiert. Es ist möglich, dieselbe COM-Schnittstelle zu verwenden, um andere Schnittstellen zu implementieren, z. B. einen EXDI COM-Server für JTAG-DCI.
Gleichzeitiges EXDI- und KDNET-Debugging
In einigen komplexen Szenarien, z. B. bei einer frühen Geräteaufnahme, kann es hilfreich sein, zwei Verbindungen mit dem Zielgerät herzustellen. Ein EXDI und ein KDNET. Wenn es sich bei dem Ziel um ein Windows-Betriebssystem handelt, wird das Debuggen von KDNET-Software wie normalerweise konfiguriert, z. B. um eine Verbindung mit einem virtuellen Computer herzustellen. In dieser Konfiguration kann jeder der beiden gleichzeitig laufenden Debugger eingreifen, um Code auf der Zielmaschine zu debuggen.
Zusammenfassung des Prozesses zum Konfigurieren einer EXDI-Verbindung
In diesem Thema beschreiben wir den Prozess zum Konfigurieren einer EXDI-Verbindung. Ein Beispiel für ein EXDI-Verwendungsszenario finden Sie unter Einrichten des QEMU-Kernelmodusdebuggings mit EXDI.
- Laden Sie die Windows-Debugging-Tools herunter und installieren Sie sie auf dem Hostsystem.
- Laden Sie die EXDI-Server-DLL herunter, erstellen und registrieren Sie sie.
- Konfigurieren Sie die Verbindung, indem Sie die XML-Konfigurationsdateien von EXDI bearbeiten.
- Starten Sie WinDbg mit der Option -kx, um eine Verbindung mit dem EXDI-Server herzustellen.
- Verwenden Sie WinDbg, um das Zielsystem zu debuggen.
Herunterladen und Installieren des Windows-Debugging-Tools
Installieren Sie die Windows-Debugging-Tools auf dem Hostsystem. Informationen zum Herunterladen und Installieren der Debugging-Tools finden Sie unter Debugging-Tools für Windows.
Laden Sie die EXDI-Server-DLL herunter, erstellen und registrieren Sie sie.
Herunterladen des entsprechenden binären ExdiGdbSrv.dll-Quellcodes (EXDI-COM-Server-Client) aus den microsoft/WinDbg-Samples, GitHub https://github.com/microsoft/WinDbg-Samples)
git clone https://github.com/microsoft/WinDbg-Samples
Erstellen Sie die VS-Lösung (ExdiGdbSrv.sln) entsprechend der Architektur Ihrer Host-Debugger-Installation, die sich in Exdi/exdigdbsrv befindet.
Sichern Sie die ExdiGdbSrv.dll, die durch den Build erzeugt wurde.
Kopieren Sie den EXDI-COM-Server (ExdiGdbSrv.dll) auf den Host-Computer, in das Verzeichnis, das Ihren Debugger enthält, z. B. C:\Program Files (x86)\Windows Kits\10\Debuggers\x64 oder C:\Debuggers)
Verwenden Sie regsvr32, um die DLL in einer administrativen Eingabeaufforderung zu registrieren.
C:\Program Files (x86)\Windows Kits\10\Debuggers\x64>regsvr32 ExdiGdbSrv.dll
RegSvr32 sollte eine Nachricht zurückgeben, die besagt, das die DLLRegisterServer in ExdiGdbSrv.dll succeeded.
Dieser Schritt muss nur einmal ausgeführt werden, aber wenn Sie den Speicherort der ExdiGdbSrv.dll ändern, müssen Sie den COM-Server erneut registrieren.
Eine andere Möglichkeit besteht darin, das PowerShell-Beispielskript zu verwenden, um die EXDI-DLL zu installieren und den Debugger beim ersten Mal zu starten. Weitere Informationen finden Sie unter Beispiel eines EXDI PowerShell-Skripts.
Konfigurieren von WinDbg mithilfe der EXDI-Konfigurations-XML-Dateien
Suchen Sie die beiden benötigten Konfigurationsdateien in WinDbg-Samples/Exdi/exdigdbsrv/, und kopieren Sie sie lokal auf den Computer, auf dem der Debugger-Host installiert ist.
exdiConfigData.xmlsystemregisters.xml
EXDI_GDBSRV_XML_CONFIG_FILE – Beschreibt den vollständigen Pfad zur Exdi-XML-Konfigurationsdatei.
EXDI_SYSTEM_REGISTERS_MAP_XML_FILE – Beschreibt den vollständigen Pfad zur Exdi XML-Systemregisterzuordnungsdatei.
Weitere Informationen zu den Tags und Attributen von exdiConfigData.xml finden Sie weiter unten in den EXDI XML-Konfigurationsdateien .
In unserem Szenario legen wir den folgenden Wert auf Null fest, um den Debugger vom Versuch zu deaktivieren, den nt!kdVersionBlock zu finden.
heuristicScanSize = "0"
Legen Sie die EXDI-Pfadwerte fest, um auf den Speicherort der XML-Konfigurationsdateien zu verweisen.
Legen Sie die Umgebungsvariable EXDI_GDBSRV_XML_CONFIG_FILE und EXDI_SYSTEM_REGISTERS_MAP_XML_FILE fest, um den vollständigen Pfad zur Exdi-XML-Konfigurationsdatei zu beschreiben. Stellen Sie sicher, dass der angegebene Pfadumgebungswert vom Speicherort der ExdiGdbSrv.dll verfügbar ist.
Eingabeaufforderung
Öffnen Sie eine Eingabeaufforderung, und legen Sie die folgenden Umgebungsvariablen fest.
set EXDI_GDBSRV_XML_CONFIG_FILE="C:\Program Files (x86)\Windows Kits\10\Debuggers\x64\exdiConfigData.xml"
set EXDI_SYSTEM_REGISTERS_MAP_XML_FILE="C:\Program Files (x86)\Windows Kits\10\Debuggers\x64\systemregisters.xml"
Geben Sie SET ein, um zu bestätigen, dass der angegebene Pfad am Speicherort der ExdiGdbSrvSample.dll verfügbar ist
PowerShell
Öffnen Sie eine PowerShell-Eingabeaufforderung, und legen Sie die folgenden Umgebungsvariablen fest:
$env:EXDI_GDBSRV_XML_CONFIG_FILE = 'C:\Program Files (x86)\Windows Kits\10\Debuggers\x64\exdiConfigData.xml'
$env:EXDI_SYSTEM_REGISTERS_MAP_XML_FILE = 'C:\Program Files (x86)\Windows Kits\10\Debuggers\x64\systemregisters.xml'
Geben Sie dir env: den Typ ein, um zu bestätigen, dass der angegebene Pfad vom Speicherort der ExdiGdbSrvSample.dll
Starten Sie WinDbg, und stellen Sie eine Verbindung mit dem EXDI-Server her.
Starten Sie die Windbg-Sitzung über die Exdi-Schnittstelle in derselben Eingabeaufforderung, in der Sie die Umgebungsvariablen (EXDI_GDBSRV_XML_CONFIG_FILE und EXDI_SYSTEM_REGISTERS_MAP_XML_FILE) festlegen.
c:\Debuggers> windbg.exe -v -kx exdi:CLSID={29f9906e-9dbe-4d4b-b0fb-6acf7fb6d014},Kd=NtBaseAddr,DataBreaks=Exdi
Um zusätzliche Ausgabe für Diagnosezwecke anzuzeigen, kann die -v: ausführliche Sitzung verwendet werden. Allgemeine Informationen zu den WinDbg-Optionen finden Sie unter WinDbg-Befehlszeilenoptionen. Weitere Informationen finden Sie weiter unten unter EXDI WinDbg-Ladeparameter .
Der Debugger zeigt die erfolgreiche EXDI-Transportinitialisierung an.
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
Das Konsolenfenster EXDIGdbServer kann auch Informationen zum Status der EXDI-Verbindung anzeigen. Weitere Informationen über die Konsole finden Sie unter Problembehandlung.
EXDI WinDbg-Ladeparameter
Die folgenden Parameter werden mit WinDbg verwendet, um eine EXDI-Kernelsitzung zu starten.
-kx: EXDI:Optionen
Die folgenden EXDI-Optionen sind mit der Option -kx verfügbar.
| Parameter | Beschreibung |
|---|---|
| CLSID | Klassen-ID, die dem LiveExdiGdbSrvServer zugewiesen ist (wie in der Datei "ExdiGdbSrv.idl" definiert). |
| Kd=NtBaseAddr | Das Debuggermodul sucht nach der NT-Basisadresse. |
| ForceX86 | Erzwingt das Debuggermodul, die IeXdiX86Context3-Schnittstelle zum Abrufen/Festlegen des CPU-Kontexts zu verwenden. |
| DataBreaks=Exdi | Verwendung von Datenhaltepunkten zulassen. |
| Inproc | Verwendung eines inproc Exdi-Servers zulassen. |
Verwenden Sie WinDbg, um das Zielsystem zu debuggen.
Die dbgeng.dll verwendet einen heuristischen Algorithmus, um die Position der NT-Basisladeadresse zum Zeitpunkt des Auftretens des Unterbrechungsbefehls zu ermitteln. Wenn keine privaten Symbole verfügbar sind, schlägt dieser Prozess fehl.
Das bedeutet, dass die Unterbrechung bei vielen Sequenzen von Verbindungen nicht wie erwartet funktionieren wird. Wenn Sie manuell in den Code eingreifen, wird es sich um eine zufällige Stelle handeln, die Windows zufällig in diesem Moment ausgeführt hat. Da Symbole für den Ziel-Code möglicherweise nicht verfügbar sind, kann es schwierig sein, Haltepunkte mit Hilfe von Symbolen festzulegen.
Befehle wie die folgenden, die direkt auf den Speicher zugreifen, funktionieren.
k, kb, kc, kd, kp, kP, kv (Stack Backtrace anzeigen)
d, da, db, dc, dd, dD, df, dp, dq, du, dw (Display-Speicher)
Und Sie können Code mithilfe von p (Step) schrittweise durchlaufen.
Es gibt auch Befehle, die verwendet werden können, um Code zu finden, den Sie debuggen möchten.
.imgscan (Bildkopfzeilen suchen)
Imgscan kann beim Debuggen von EDXI hilfreich sein, da das Festlegen von Haltepunkten auf der Basis von Symbolen im Gegensatz zum traditionellen KDNET-basierten Debuggen des Kernels nicht möglich ist. Das Auffinden eines gewünschten Ziel-Images kann das Festlegen eines Haltepunkts für den Zugriff auf den Speicher erleichtern.
.exdicmd (EXDI-Befehl)
.exdicmd sendet einen EXDI-Befehl über die aktive EXDI-Debugging-Verbindung an das Zielsystem. Weitere Informationen finden Sie unter .exdicmd (EXDI Command).
Problembehandlung
Verwenden Sie die Ausgabe aus dem ExdiGdbServer-Fenster, um die Verbindungssequenz zu überwachen.
Problem: Fehler: Es kann keine Verbindung mit dem GbDServer hergestellt werden. Bitte überprüfen der Verbindungszeichenfolge<hostname/ip>:portnumber
Dieses Problem kann folgende Ursachen haben:
- Die ExdiGdbSrv.dll kann keine Verbindung mit dem Ziel-GDB-Server herstellen.
- Der GDB-Server wird noch nicht am Ziel ausgeführt.
- Firewallprobleme, stellen Sie sicher, dass beide IP-Adressen erreichbar sind, indem Sie Ping, Tracert oder ein anderes Tool verwenden, um zu überprüfen, ob der GDB-Datenverkehr die Firewall durchlaufen kann.
Problem: Das Kerneldebugging mit EXDI konnte nicht gestartet werden.
Dieses Problem kann folgende Ursachen haben:
- Es gibt eine weitere Instanz des ExdiGdbSrv.dll (gehostet von dllhost.exe) auf dem Hostdebuggercomputer.
- Beenden Sie die zusätzliche Instanz des COM-Diensts, der die ExdiGdbSrv.dll hostet.
- Führen Sie zunächst die Prozesse unter Verwendung des Dienstprogramms TList auf dem Host-PC auf. Der DLLHost, der die ExdiGdbSrv.dll hostet, zeigt ExdiGdbServer an.
tlist 261928 dllhost.exe ExdiGdbServer
- Verwenden Sie
kill -f XXXXXan der Debugger-Eingabeaufforderung, um den Prozess mithilfe der Prozessnummer zu beenden.
- Führen Sie zunächst die Prozesse unter Verwendung des Dienstprogramms TList auf dem Host-PC auf. Der DLLHost, der die ExdiGdbSrv.dll hostet, zeigt ExdiGdbServer an.
Problem: Fehler: GdbServer-Sitzung kann nicht konfiguriert werden.
Dieses Problem kann folgende Ursachen haben:
- Fehler beim Auffinden der Sitzungsinformationen, z. B. des Pfads zu den XML-Konfigurationsdateien.
Problem: Fehler: EXDI_GDBSRV_XML_CONFIG_FILE Umgebungsvariable ist nicht definiert.
Dieses Problem kann folgende Ursachen haben:
- ExdiGdbSrv.dll Umgebungsvariablen sind in der Umgebung nicht festgelegt oder anderweitig nicht verfügbar.
Problem: Fehler: EXDI_GDBSRV_XML_CONFIG_FILE Umgebungsvariable ist nicht definiert. Das Beispiel "Exdi-GdbServer" wird zu diesem Zeitpunkt nicht fortgesetzt. Legen Sie den vollständigen Pfad zur Exdi-XML-Konfigurationsdatei fest.
Dieses Problem kann folgende Ursachen haben:
- Die EXDI_GDBSRV_XML_CONFIG_FILE Umgebungsvariable ist nicht festgelegt. In manchen Situationen funktioniert ExdiGDbSrv.dll weiterhin, wenn Sie auf die Schaltfläche „OK“ klicken, aber die Abfrage der Systemregister durch windbg.exe (z. B. über die Funktionen rdmsr/wrmsr) schlägt fehl.
Problem: Fehlerszenario mit dem Zielsystem ist nicht verfügbar - DbgCoInitialize gibt 0x00000001 zurück
Die folgende Ausgabe kann zurückgegeben werden, wenn das Zielsystem nicht geladen oder anderweitig nicht verfügbar ist.
Microsoft (R) Windows Debugger Version 10.0.20317.1 AMD64
Copyright (c) Microsoft Corporation. All rights reserved.
EXDI: DbgCoInitialize returned 0x00000001
Dies ist ein häufiger Fehler, wenn der ExdiGdbSrv.dll COM-Server keine Verbindung mit dem QEMU GDServer herstellen konnte, sodass dies zu einem Fehler führen kann:
Fehler beim Starten des EXDI-COM-Servers (ExdiGDbSrv.dll) über den dllhost.exe-Prozess (COM-bezogen). Um dies zu beheben, starten Sie den Hostdebugger-PC neu oder melden Sie sich erneut bei Windows ab, und melden Sie sich erneut an. Wenn dies nicht funktioniert, registrieren Sie den EXDI COM-Server nach dem Neustart/erneuten Anmelden erneut.
regsvr32.exe <full path to the ExdiGdbSrv.dll)
Die vorherige Sitzung des ExdiGdbSrv.dll wird weiterhin von einem dllhost.exe Prozess gehostet, sodass Sie den dllhost.exe Prozess beenden müssen. Suchen Sie in tlist nach der PID von dllhost.exe, das die ExdiGdbSrv.dll hostet, und löschen Sie die zugehörige PID.
Der QEMU gdbserver wurde noch nicht gestartet, oder die Datei exdiconfigdata.xml enthält ungültige IP:Port-Werte. Wenn die WinDbg-Sitzung auf demselben Host-PC wie die Windows-VM QEMU gestartet wird, dann die IP=LocalHost.
Problem: Die Debugsitzung konnte nicht gestartet werden: FAILURE HR=0x80004005:Failed to AttachKernel.
Dieses Problem kann folgende Ursachen haben:
- Wie oben beschrieben, ist es möglich, dass die vorherige Sitzung der ExdiGdbSrv.dll noch aktiv ist. Suchen und beenden Sie den zugeordneten DLL-Host wie oben beschrieben.
EXDI XML Konfigurationsdateien
Es gibt zwei erforderliche xml-Dateien, die vom EXDI GDB COM-Server (ExdiGdbSrv.dll) genutzt werden.
exdiConfigData.xml – Diese Datei enthält die wichtigsten Konfigurationsdaten, die der GDB-Server-Client benötigt, um eine erfolgreiche GDB-Sitzung mit dem HW-Debugger GDB-Server-Ziel aufzubauen. Der GDB-Server-Client wird also nicht ausgeführt, wenn der Ort der Datei nicht durch die Umgebungsvariable EXDI_GDBSRV_XML_CONFIG_FILE festgelegt ist. Jedes XML-Tag bietet die Möglichkeit, bestimmte Funktionen des GDB-Servers festzulegen. Im Folgenden finden Sie eine Liste der Attribute, die Sie in der XML-Datei ändern können, sowie ein XML-Beispiel.
Systemregister.xml – Diese Datei enthält eine Zuordnung zwischen Systemregistern und ihrem Code für den Zugriff. Dies ist erforderlich, da der Zugriffscode nicht vom GDB-Server in der XML-Datei bereitgestellt wird und der Debugger über den Zugriffscode auf jedes Systemregister zugreift. Wenn die Datei nicht über die Umgebungsvariable
EXDI_SYSTEM_REGISTERS_MAP_XML_FILEfestgelegt wird, funktioniert die ExdiGdbSrv.dll weiterhin, der Debugger kann jedoch nicht über rdmsr- oder wrmsr-Befehle auf ein Systemregister zugreifen. Die Liste dieser Register sollte vom GDB-Serverhardwaredebugger unterstützt werden (der spezifische Systemregistername sollte in der Liste der Register vorhanden sein, die in der XML-Datei des Systems gesendet werden).
GDBServer-Tags und -Attribute
In der folgenden Tabelle werden die in der exdiConfigData.xml Datei definierten GDBServer-Tags und -Attribute beschrieben.
| Parameter | Beschreibung |
|---|---|
| ExdiTargets | Gibt an, welche spezifische GDB-Serverzielkonfiguration von ExdiGgbSrv.dll verwendet wird, um die GDB-Verbindung mit dem GDB-Serverziel herzustellen, da die Datei exdiConfigData.xml alle GDB-Server enthält, die derzeit von ExdiGdbSrv.dll unterstützt werden (diese Datei MUSS ausgefüllt werden, bevor ExdiGdbSrv.dll mit einem bestimmten GDB-Server verwendet wird). |
| CurrentTarget | Gibt den Namen des GDB-Serverziels an (z. B. dieser Attributwert sollte mit dem Namenswert eines der <ExdiTarget Name= Tags übereinstimmen, die in der Datei exdiConfigData.xml enthalten sind. |
| ExdiTarget | Dies ist das Starttag für alle Konfigurationsdaten, die von jeder GDB-Serverzielkomponente enthalten sind. |
| Name | Gibt den Namen des GDB-Servers an (z. B. QEMU, BMC-OpenOCD, Trace32, VMWare). |
| agentNamePacket | Dies ist der Name des GDB-Clients, wie er vom GDB-Server-HW-Debugger erkannt wird. Dies kann vom HW-Debugger des GDB-Servers verwendet werden, um sich selbst für bestimmte GDB-Clients zu konfigurieren (z. B. erfordert der Trace32-GDB-Server, dass ExdiGdbSrv.dll den Namen „QMS.windbg“ sendet, um den windbg-GDB-Client zu identifizieren und dann benutzerdefinierte GDB-Speicherpakete zu aktivieren, die nur für den MS GDB-Server-Client (exdiGdbSrv.dll) unterstützt werden). |
| ExdiGdbServerConfigData | Gibt die ExdiGdbSrv.dll komponentenbezogenen Konfigurationsparameter an. |
| uuid | Gibt die UUI der ExdiGdbSrv.dll Komponente an. |
| displayCommPackets | Wenn die Markierung „Ja“ ist, werden die Kommunikationszeichen des RSP-Protokolls im Befehlsprotokollfenster angezeigt. Wenn "Nein" angezeigt wird, wird nur der Text des Anforderungsantwortpaars angezeigt. |
| enableThrowExceptionOnMemoryErrors | Dieses Attribut wird vom GDB-Serverclient überprüft, wenn ein GDB-Fehlerantwortpaket (E0x) vorhanden ist, um festzustellen, ob der Client eine Ausnahme auslösen und den Lesespeicher beenden soll. |
| qSupportedPacket | Dies ermöglicht das Konfigurieren des GDB-Clients, um anzufordern, welche XML-Registerarchitekturdatei vom GDB-Server-HW-Debugger nach der XML-Zielbeschreibungsdatei gesendet werden soll (im Grunde informiert der Client den GDB-Server, welche Architekturen vom Client unterstützt werden, derzeit unterstützt der Client die x64-Architektur). |
| ExdiGdbServerTargetData | Gibt die Parameter im Zusammenhang mit dem Hardwareziel an, das von der GdbServer-Sitzung gedebuggt wird. |
| targetArchitecture | Zeichenfolge, die die Zielhardwarearchitektur enthält. Mögliche Werte: X86, X64, ARM, ARM64. Derzeit unterstützt die exdiGdbSrv.dll nur X86 und ARM. |
| targetFamily | Zeichenfolge, die die Zielhardwarefamilie enthält. Mögliche Werte: ProcessorFamilyX86, ProcessorFamilyX64, ProcessorFamilyARM, ProcessorFamilyARM64. |
| numberOfCores | Die Anzahl der Prozessorkerne, die vom Ziel unterstützt werden. Dieser Parameter wird überprüft, wenn wir eine Multi-Gdbserver-Sitzung (T32-GdbServer-Sitzung) verwenden. Das folgende Attribut "MultiCoreGdbServerSessions" sollte auf "Ja" festgelegt werden. |
| EnableSseContext | Wenn die Markierung „Ja“ ist, enthält das RSP-Paket im Kontext „g“ Gleitkommaregisterwerte. Dieser Parameter ist nur für Intel Family-Ziele sinnvoll. |
| heuristicScanSize | Dies konfiguriert den schnellen heuristischen Algorithmus der Debugger-Engine so, dass die gescannte Speicherprobe um die angegebene Größe verringert wird. Wenn der Attributwertnicht angegeben ist (oder „0“), verwendet die Debugger-Engine die schnelle Heuristik nicht und greift auf die alte Heuristik zurück, die den gesamten Speicher nach der PE-DOS-Signatur durchsucht. |
| targetDescriptionFile | Gibt an, ob der GDB-Server eine Zielbeschreibungsheaderdatei sendet, bevor jede separate XML-Datei gesendet wird. Dieses Feld ist leer, dann fordert der GDB-Serverclient das XML-Architektursystemregister nicht an (z. B. Trace32 GDBs-Server, der das Senden von Architekturregistern in einer separaten XML-Datei nicht unterstützt). |
| GdbServerConnectionParameters | Gibt GdbServer-Sitzungsparameter an. Diese Parameter werden verwendet, um die RSP GdbServer-Sitzung zwischen der ExdiGdbSrv.dll Komponente und GdbServer zu steuern. |
| MultiCoreGdbServerSessions | Markieren: Wenn „Ja“, dann verfügen wir über eine Multi-Core-GdbServer-Sitzung (die vom T32-GdbServer-Back-End verwendet wird). Wenn "Nein", kommunizieren wir nur mit einer Instanz des GdbServer. |
| MaximumGdbServerPacketLength | Dies ist die maximale GdbServer-unterstützte Länge für ein Paket. |
| MaximumConnectAttempts | Dies ist die maximale Verbindungsversuche. Sie wird vom ExdiGdbSrv.dll verwendet, wenn versucht wird, die RSP-Verbindung mit dem GdbServer herzustellen. |
| SendPacketTimeout | Dies ist das RSP-Sendetimeout. |
| ReceivePacketTimeout | Dies ist das RSP-Empfangstimeout. |
| HostNameAndPort | Dies ist der Verbindungsstring im Format <hostname/ip address:Port number>. Es kann mehrere GdbServer-Verbindungszeichenfolge (z. B. T32 Multi-Core GdbServer-Sitzung) geben. Die Anzahl der Verbindungszeichenfolge sollte mit der Anzahl der Kerne übereinstimmen. |
| ExdiGdbServerMemoryCommands | Gibt verschiedene Möglichkeiten zum Ausgeben der GDB-Speicherbefehle an, um Systemwerte zu registrieren oder Lese-/Schreibzugriffsspeicher auf unterschiedlichen Ausnahme-CPU-Ebenen zu erhalten (z. B. BMC-OpenOCD bietet Zugriff auf CP15-Register über "aarch64 mrs nsec/sec <access code>" angepassten Befehl). |
| GdbSpecialMemoryCommand | wenn "Ja", unterstützt der GDB-Server angepasste Speicherbefehle (z. B. Systemregister, dies sollte für den Trace32 GDB-Server festgelegt werden). |
| PhysicalMemory | wenn "ja", unterstützt der GDB-Server angepasste Befehle zum Lesen des physischen Arbeitsspeichers (er ist für Trace32 GDB-Server festgelegt). |
| SupervisorMemory | wenn "ja", dann unterstützt der GDB-Server benutzerdefinierte Befehle zum Lesen des Supervisor-Speichers (es ist für den Trace32-GDB-Server eingestellt). |
| SpecialMemoryRegister | wenn "ja", dann unterstützt der GDB-Server benutzerdefinierte Befehle zum Lesen von Systemregistern (ist für den Trace32-GDB-Server eingestellt) |
| SystemRegistersGdbMonitor | wenn "ja", unterstützt der GDB-Server angepasste Befehle über den GDB-Monitorbefehl (er ist für BMC Open-OCD festgelegt). |
| SystemRegisterDecoding | wenn "ja", akzeptiert der GDB-Client die Decodierung des Zugriffscodes, bevor der GDB-Monitorbefehl gesendet wird. |
| ExdiGdbServerRegisters | Gibt den spezifischen Architekturregisterkernsatz an. |
| Aufbau | CPU-Architektur der definierten Registersätze. |
| FeatureNameSupported | Dies ist der Name der Systemregistergruppe, wie sie von der XML-Systemregisterbeschreibungsdatei bereitgestellt wird. Es ist erforderlich, die XML-Registergruppe des Systems zu identifizieren, die Teil der XML-Datei ist, wie sie vom GDB-Server gesendet wird. |
| SystemRegistersStart | Dies dient der Identifizierung des ersten Systemregisters (niedrigste Registernummer/-reihenfolge), das als Teil des Kernregistersatzes gemeldet wird (beispielsweise meldet QEMU unter X64 den x64-Systemregistersatz nicht als separate XML-Zielbeschreibungsdatei, sodass Systemregister Teil der Kernregister sind). |
| SystemRegistersEnd | Dies ist die Identifizierung des letzten Systemregisters (hohe Registernummer/Reihenfolge), das als Teil des Kernregistersatzes gemeldet wird. |
| Name | Name des Registers. |
| Auftrag | Dies ist eine Zahl, die den Index im Array von Registern identifiziert. Diese Nummer wird vom GDB-Client und vom Server zum Setzen/Abfragen (p<number>”/”q<number>) von Registerpaketen verwendet. |
| Size | Dies ist die Registergröße in Byte. |
Beispieldatei für exdiConfigData.xml
<ExdiTargets CurrentTarget = "QEMU">
<!-- QEMU SW simulator GDB server configuration -->
<ExdiTargets CurrentTarget="QEMU">
<!-- QEMU SW simulator GDB server configuration -->
<ExdiTarget Name="QEMU">
<ExdiGdbServerConfigData agentNamePacket="" uuid="72d4aeda-9723-4972-b89a-679ac79810ef" displayCommPackets="yes" debuggerSessionByCore="no" enableThrowExceptionOnMemoryErrors="yes" qSupportedPacket="qSupported:xmlRegisters=aarch64,i386">
<ExdiGdbServerTargetData targetArchitecture="ARM64" targetFamily="ProcessorFamilyARM64" numberOfCores="1" EnableSseContext="no" heuristicScanSize="0xfffe" targetDescriptionFile="target.xml"/>
<GdbServerConnectionParameters MultiCoreGdbServerSessions="no" MaximumGdbServerPacketLength="1024" MaximumConnectAttempts="3" SendPacketTimeout="100" ReceivePacketTimeout="3000">
<Value HostNameAndPort="LocalHost:1234"/>
</GdbServerConnectionParameters>
<ExdiGdbServerMemoryCommands GdbSpecialMemoryCommand="no" PhysicalMemory="no" SupervisorMemory="no" HypervisorMemory="no" SpecialMemoryRegister="no" SystemRegistersGdbMonitor="no" SystemRegisterDecoding="no"> </ExdiGdbServerMemoryCommands>
<ExdiGdbServerRegisters Architecture = "ARM64" FeatureNameSupported = "sys">
<Entry Name ="X0" Order = "0" Size = "8" />
<Entry Name ="X1" Order = "1" Size = "8" />
<Entry Name ="X2" Order = "2" Size = "8" />
<Entry Name ="X3" Order = "3" Size = "8" />
<Entry Name ="X4" Order = "4" Size = "8" />
<Entry Name ="X5" Order = "5" Size = "8" />
<Entry Name ="X6" Order = "6" Size = "8" />
<Entry Name ="X7" Order = "7" Size = "8" />
<Entry Name ="X8" Order = "8" Size = "8" />
<Entry Name ="X9" Order = "9" Size = "8" />
<Entry Name ="X10" Order = "a" Size = "8" />
<Entry Name ="X11" Order = "b" Size = "8" />
<Entry Name ="X12" Order = "c" Size = "8" />
<Entry Name ="X13" Order = "d" Size = "8" />
<Entry Name ="X14" Order = "e" Size = "8" />
<Entry Name ="X15" Order = "f" Size = "8" />
<Entry Name ="X16" Order = "10" Size = "8" />
<Entry Name ="X17" Order = "11" Size = "8" />
<Entry Name ="X18" Order = "12" Size = "8" />
<Entry Name ="X19" Order = "13" Size = "8" />
<Entry Name ="X20" Order = "14" Size = "8" />
<Entry Name ="X21" Order = "15" Size = "8" />
<Entry Name ="X22" Order = "16" Size = "8" />
<Entry Name ="X23" Order = "17" Size = "8" />
<Entry Name ="X24" Order = "18" Size = "8" />
<Entry Name ="X25" Order = "19" Size = "8" />
<Entry Name ="X26" Order = "1a" Size = "8" />
<Entry Name ="X27" Order = "1b" Size = "8" />
<Entry Name ="X28" Order = "1c" Size = "8" />
<Entry Name ="fp" Order = "1d" Size = "8" />
<Entry Name ="lr" Order = "1e" Size = "8" />
<Entry Name ="sp" Order = "1f" Size = "8" />
<Entry Name ="pc" Order = "20" Size = "8" />
<Entry Name ="cpsr" Order = "21" Size = "8" />
<Entry Name ="V0" Order = "22" Size = "16" />
<Entry Name ="V1" Order = "23" Size = "16" />
<Entry Name ="V2" Order = "24" Size = "16" />
<Entry Name ="V3" Order = "25" Size = "16" />
<Entry Name ="V4" Order = "26" Size = "16" />
<Entry Name ="V5" Order = "27" Size = "16" />
<Entry Name ="V6" Order = "28" Size = "16" />
<Entry Name ="V7" Order = "29" Size = "16" />
<Entry Name ="V8" Order = "2a" Size = "16" />
<Entry Name ="V9" Order = "2b" Size = "16" />
<Entry Name ="V10" Order = "2c" Size = "16" />
<Entry Name ="V11" Order = "2d" Size = "16" />
<Entry Name ="V12" Order = "2e" Size = "16" />
<Entry Name ="V13" Order = "2f" Size = "16" />
<Entry Name ="V14" Order = "30" Size = "16" />
<Entry Name ="V15" Order = "31" Size = "16" />
<Entry Name ="V16" Order = "32" Size = "16" />
<Entry Name ="V17" Order = "33" Size = "16" />
<Entry Name ="V18" Order = "34" Size = "16" />
<Entry Name ="V19" Order = "35" Size = "16" />
<Entry Name ="V20" Order = "36" Size = "16" />
<Entry Name ="V21" Order = "37" Size = "16" />
<Entry Name ="V22" Order = "38" Size = "16" />
<Entry Name ="V23" Order = "39" Size = "16" />
<Entry Name ="V24" Order = "3a" Size = "16" />
<Entry Name ="V25" Order = "3b" Size = "16" />
<Entry Name ="V26" Order = "3c" Size = "16" />
<Entry Name ="V27" Order = "3d" Size = "16" />
<Entry Name ="V28" Order = "3e" Size = "16" />
<Entry Name ="V29" Order = "3f" Size = "16" />
<Entry Name ="V30" Order = "3f" Size = "16" />
<Entry Name ="V31" Order = "3f" Size = "16" />
<Entry Name ="fpsr" Order = "40" Size = "4" />
<Entry Name ="fpcr" Order = "41" Size = "4" />
</ExdiGdbServerRegisters>
<!-- x64 GDB server core resgisters -->
<ExdiGdbServerRegisters Architecture = "X64" FeatureNameSupported = "sys" SystemRegistersStart = "18" SystemRegistersEnd = "20" >
<Entry Name ="rax" Order = "0" Size ="8" />
<Entry Name ="rbx" Order = "1" Size ="8" />
<Entry Name ="rcx" Order = "2" Size ="8" />
<Entry Name ="rdx" Order = "3" Size ="8" />
<Entry Name ="rsi" Order = "4" Size ="8" />
<Entry Name ="rdi" Order = "5" Size ="8" />
<Entry Name ="rbp" Order = "6" Size ="8" />
<Entry Name ="rsp" Order = "7" Size ="8" />
<Entry Name ="r8" Order = "8" Size ="8" />
<Entry Name ="r9" Order = "9" Size ="8" />
<Entry Name ="r10" Order = "a" Size ="8" />
<Entry Name ="r11" Order = "b" Size ="8" />
<Entry Name ="r12" Order = "c" Size ="8" />
<Entry Name ="r13" Order = "d" Size ="8" />
<Entry Name ="r14" Order = "e" Size ="8" />
<Entry Name ="r15" Order = "f" Size ="8" />
<Entry Name ="rip" Order = "10" Size ="8" />
<!-- <flags id="x64_eflags" size="4">
<field name="" start="22" end="31"/>
<field name="ID" start="21" end="21"/>
<field name="VIP" start="20" end="20"/>
<field name="VIF" start="19" end="19"/>
<field name="AC" start="18" end="18"/>
<field name="VM" start="17" end="17"/>
<field name="RF" start="16" end="16"/>
<field name="" start="15" end="15"/>
<field name="NT" start="14" end="14"/>
<field name="IOPL" start="12" end="13"/>
<field name="OF" start="11" end="11"/>
<field name="DF" start="10" end="10"/>
<field name="IF" start="9" end="9"/>
<field name="TF" start="8" end="8"/>
<field name="SF" start="7" end="7"/>
<field name="ZF" start="6" end="6"/>
<field name="" start="5" end="5"/>
<field name="AF" start="4" end="4"/>
<field name="" start="3" end="3"/>
<field name="PF" start="2" end="2"/>
<field name="" start="1" end="1"/>
<field name="CF" start="0" end="0"/>
</flags> -->
<Entry Name ="eflags" Order = "11" Size ="4" />
<!-- Segment registers -->
<Entry Name ="cs" Order = "12" Size ="4" />
<Entry Name ="ss" Order = "13" Size ="4" />
<Entry Name ="ds" Order = "14" Size ="4" />
<Entry Name ="es" Order = "15" Size ="4" />
<Entry Name ="fs" Order = "16" Size ="4" />
<Entry Name ="gs" Order = "17" Size ="4" />
<!-- Segment descriptor caches and TLS base MSRs -->
<!--Entry Name ="cs_base" Order = "18" Size="8"/
<Entry Name ="ss_base" Order = "18" Size ="8" />
<Entry Name ="ds_base" Order = "19" Size ="8" />
<Entry Name ="es_base" Order = "1a" Size ="8" /> -->
<Entry Name ="fs_base" Order = "18" Size ="8" />
<Entry Name ="gs_base" Order = "19" Size ="8" />
<Entry Name ="k_gs_base" Order = "1a" Size ="8" />
<!-- Control registers -->
<!-- the cr0 register format fields:
<flags id="x64_cr0" size="8">
<field name="PG" start="31" end="31"/>
<field name="CD" start="30" end="30"/>
<field name="NW" start="29" end="29"/>
<field name="AM" start="18" end="18"/>
<field name="WP" start="16" end="16"/>
<field name="NE" start="5" end="5"/>
<field name="ET" start="4" end="4"/>
<field name="TS" start="3" end="3"/>
<field name="EM" start="2" end="2"/>
<field name="MP" start="1" end="1"/>
<field name="PE" start="0" end="0"/>
</flags> -->
<Entry Name ="cr0" Order = "1b" Size ="8" />
<Entry Name ="cr2" Order = "1c" Size ="8" />
<!-- the cr3 register format fields:
<flags id="x64_cr3" size="8">
<field name="PDBR" start="12" end="63"/>
<field name="PCID" start="0" end="11"/>
</flags> -->
<Entry Name ="cr3" Order = "1d" Size ="8" />
<!-- the cr4 register format fields:
<flags id="x64_cr4" size="8">
<field name="PKE" start="22" end="22"/>
<field name="SMAP" start="21" end="21"/>
<field name="SMEP" start="20" end="20"/>
<field name="OSXSAVE" start="18" end="18"/>
<field name="PCIDE" start="17" end="17"/>
<field name="FSGSBASE" start="16" end="16"/>
<field name="SMXE" start="14" end="14"/>
<field name="VMXE" start="13" end="13"/>
<field name="LA57" start="12" end="12"/>
<field name="UMIP" start="11" end="11"/>
<field name="OSXMMEXCPT" start="10" end="10"/>
<field name="OSFXSR" start="9" end="9"/>
<field name="PCE" start="8" end="8"/>
<field name="PGE" start="7" end="7"/>
<field name="MCE" start="6" end="6"/>
<field name="PAE" start="5" end="5"/>
<field name="PSE" start="4" end="4"/>
<field name="DE" start="3" end="3"/>
<field name="TSD" start="2" end="2"/>
<field name="PVI" start="1" end="1"/>
<field name="VME" start="0" end="0"/>
</flags> -->
<Entry Name ="cr4" Order = "1e" Size ="8" />
<Entry Name ="cr8" Order = "1f" Size ="8" />
<!-- the efer register format fields:
<flags id="x64_efer" size="8">
<field name="TCE" start="15" end="15"/>
<field name="FFXSR" start="14" end="14"/>
<field name="LMSLE" start="13" end="13"/>
<field name="SVME" start="12" end="12"/>
<field name="NXE" start="11" end="11"/>
<field name="LMA" start="10" end="10"/>
<field name="LME" start="8" end="8"/>
<field name="SCE" start="0" end="0"/>
</flags> -->
<Entry Name ="efer" Order = "20" Size ="8"/>
<!-- x87 FPU -->
<Entry Name ="st0" Order = "21" Size ="10" />
<Entry Name ="st1" Order = "22" Size ="10" />
<Entry Name ="st2" Order = "23" Size ="10" />
<Entry Name ="st3" Order = "24" Size ="10" />
<Entry Name ="st4" Order = "25" Size ="10" />
<Entry Name ="st5" Order = "26" Size ="10" />
<Entry Name ="st6" Order = "27" Size ="10" />
<Entry Name ="st7" Order = "28" Size ="10" />
<Entry Name ="fctrl" Order = "29" Size ="4" />
<Entry Name ="fstat" Order = "2a" Size ="4" />
<Entry Name ="ftag" Order = "2b" Size ="4" />
<Entry Name ="fiseg" Order = "2c" Size ="4" />
<Entry Name ="fioff" Order = "2d" Size ="4" />
<Entry Name ="foseg" Order = "2e" Size ="4" />
<Entry Name ="fooff" Order = "2f" Size ="4" />
<Entry Name ="fop" Order = "30" Size ="4" />
<Entry Name ="xmm0" Order = "31" Size ="16" />
<Entry Name ="xmm1" Order = "32" Size ="16" />
<Entry Name ="xmm2" Order = "33" Size ="16" />
<Entry Name ="xmm3" Order = "34" Size ="16" />
<Entry Name ="xmm4" Order = "35" Size ="16" />
<Entry Name ="xmm5" Order = "36" Size ="16" />
<Entry Name ="xmm6" Order = "37" Size ="16" />
<Entry Name ="xmm7" Order = "38" Size ="16" />
<Entry Name ="xmm8" Order = "39" Size ="16" />
<Entry Name ="xmm9" Order = "3a" Size ="16" />
<Entry Name ="xmm10" Order = "3b" Size ="16" />
<Entry Name ="xmm11" Order = "3c" Size ="16" />
<Entry Name ="xmm12" Order = "3d" Size ="16" />
<Entry Name ="xmm13" Order = "3e" Size ="16" />
<Entry Name ="xmm14" Order = "3f" Size ="16" />
<Entry Name ="xmm15" Order = "40" Size ="16" />
<!-- the mxcsr register format fields:
<flags id="x64_mxcsr" size="4">
<field name="IE" start="0" end="0"/>
<field name="DE" start="1" end="1"/>
<field name="ZE" start="2" end="2"/>
<field name="OE" start="3" end="3"/>
<field name="UE" start="4" end="4"/>
<field name="PE" start="5" end="5"/>
<field name="DAZ" start="6" end="6"/>
<field name="IM" start="7" end="7"/>
<field name="DM" start="8" end="8"/>
<field name="ZM" start="9" end="9"/>
<field name="OM" start="10" end="10"/>
<field name="UM" start="11" end="11"/>
<field name="PM" start="12" end="12"/>
<field name="FZ" start="15" end="15"/>
</flags> -->
<Entry Name ="mxcsr" Order = "41" Size ="4" />
</ExdiGdbServerRegisters>
</ExdiGdbServerConfigData>
</ExdiTarget>
</ExdiTargets>
</ExdiTargets>
EXDI PowerShell-Beispielskript:
Dieses PowerShell-Beispielskript installiert EXDI und startet dann den Debugger. Das Skript Start-ExdiDebugger.ps1 installiert bei Bedarf ExdiGdbSrv.dll, konfiguriert die XML-Einstellungsdateien, sucht nach laufenden dllhost.exe-Prozessen und startet den Debugger, um eine Verbindung mit einem bereits laufenden Hardware-Debuggingziel des GDB-Servers herzustellen.
Dies ist ein Beispiel für das Aufrufen des Startskripts.
PS>.\Start-ExdiDebugger.ps1 -ExdiTarget "QEMU" -GdbPort 1234 -Architecture x64
Sie können die integrierten Dateien auch bei Bedarf angeben.
PS>.\Start-ExdiDebugger.ps1 -ExdiTarget "QEMU" -GdbPort 1234 -Architecture x64 -ExdiDropPath "C:\path\to\built\exdi\files"
Die Start-ExdiDebugger.ps1 verfügt über die folgenden Einstellungsoptionen.
| Parameter | Beschreibung |
|---|---|
| ExdiTarget | Der Typ des Ziels, mit dem eine Verbindung hergestellt werden soll. Dies entspricht einem bestimmten Abschnitt in der XML-Datei "Einstellungen" |
| HostName | Die IP-Adresse oder der Hostname des Computers, auf dem die gdb-Serversitzung gehostet wird (standardmäßig "LocalHost") |
| GdbPort | Der Port, auf dem der gdb-Server lauscht. |
| Aufbau | Architektur des Hardwaredebuggingziels (dieser Parameter impliziert auch den ArchitectureFamily-Parameter in der XML-Einstellungsdatei) |
| ExdiDropPath | Speicherort der Dateien ExdiGdbSrv.dll, exdiConfigData.xml und systemregisters.xml. Diese werden nur kopiert, wenn ExdiGdbSrv.dll nicht installiert oder falsch installiert ist. |
| ExtraDebuggerArgs | Zusätzliche Argumente, die an die Befehlszeile des Debuggers übergeben werden sollen |
| PreNTAppDebugging | Ändert den Wert des heuristicScanSize von 0xfffe (am besten für NT) in 0xffe (für Pre-NT-Apps) |
| DontTryDllHostCleanup | Für die Überprüfung auf vorhandene ausgeführte Instanzen von ExdiGdbSrv.dll in dllhost.exe ist eine Erhöhung erforderlich. Wenn Sie diese Option angeben, kann das Skript ohne Erhöhung ausgeführt werden (obwohl der Debugger möglicherweise nicht ordnungsgemäß funktioniert). |
Um die Anzeige von Paketen zu ermöglichen, legen Sie den Wert von displayCommPackets auf "Ja" fest.
[pscustomobject]@{ Path = 'displayCommPackets' ; value = "yes" }
.\Start-ExdiDebugger.ps1 -ExdiTarget "QEMU" -GdbPort 1234 -Architecture x64 -ExdiDropPath "C:\path\to\built\exdi\files"
Weitere Einstellungsoptionen finden Sie in den Codekommentaren.
<#
.Synopsis
Installs and launches exdi debugger (automating xml file editing)
.Description
This script will install ExdiGdbSrv.dll if required, configure the xml settings
files, check for running dllhost.exe processes, and launch the debugger to connect to
an already running gdb server hardware debugging target.
.Parameter ExdiTarget
Type of target to connect to. This corresponds to a specific section in the settings xml file
.Parameter HostName
IP address or hostname of the computer hosting the gdb server session (defaults to "LocalHost")
.Parameter GdbPort
Port that the gdb server is listening on.
.Parameter Architecture
Architecture of the hardware debugging target (this parameter also implies the ArchitectureFamily
parameter in the xml settings file)
.Parameter ExdiDropPath
Location of the ExdiGdbSrv.dll, exdiConfigData.xml, and systemregisters.xml files. These will
only be copied if ExdiGdbSrv.dll is not installed or is installed incorrectly.
.Parameter ExtraDebuggerArgs
Extra arguments to pass on the debugger command line
.Parameter PreNTAppDebugging
Changes the value of the heuristicScanSize from 0xfffe (best for NT) to 0xffe (for pre-NT Apps)
.Parameter DontTryDllHostCleanup
Checking for existing running instances of ExdiGdbSrv.dll in dllhost.exe requires elevation.
Providing this switch will allow the script to run without elevation (although the debugger may not
function correctly).
.Example
>---------------- (first run) ------------<
.\Start-ExdiDebugger.ps1 -ExdiTarget "QEMU" -GdbPort 1234 -Architecture x64 -ExdiDropPath "C:\path\to\built\exdi\files"
.Example
PS>.\Start-ExdiDebugger.ps1 -ExdiTarget "QEMU" -GdbPort 1234 -Architecture x64
#>
[CmdletBinding()]
param
(
[ValidateSet("QEMU")]
[string]
$ExdiTarget = "QEMU",
[string]
$HostName = "LocalHost",
[Parameter(Mandatory=$true)]
[Int]
$GdbPort,
[Parameter(Mandatory=$true)]
[string]
[ValidateSet("x86", "x64", "arm64")]
$Architecture,
[string]
$ExdiDropPath,
[string]
$DebuggerPath,
[string[]]
$ExtraDebuggerArgs = @(),
[switch]
$PreNTAppDebugging,
[switch]
$DontTryDllHostCleanup
)
$ErrorActionPreference = "Stop"
#region Functions
Function Test-Admin
{
([Security.Principal.WindowsPrincipal] [Security.Principal.WindowsIdentity]::GetCurrent()).IsInRole([Security.Principal.WindowsBuiltInRole]"Administrator")
}
Function Find-PathToWindbgX
{
$InternalWindbgXPath = "$env:LOCALAPPDATA\DBG\UI\WindbgX.exe"
$ExternalWindbgXPath = "$env:LOCALAPPDATA\Microsoft\WindowsApps\WinDbgX.exe"
if (Test-Path $InternalWindbgXPath -PathType Leaf)
{
return $InternalWindbgXPath
}
elseif (Test-Path $ExternalWindbgXPath -PathType Leaf)
{
return $ExternalWindbgXPath
}
}
Function Test-ParameterValidation
{
$CommandName = $PSCmdlet.MyInvocation.InvocationName
$ParameterList = (Get-Command -Name $CommandName).Parameters
foreach ($Parameter in $ParameterList) {
Get-Variable -Name $Parameter.Values.Name -ErrorAction SilentlyContinue | Out-String | Write-Verbose
}
if (-not $DebuggerPath)
{
throw "WindbgX is not installed"
}
elseif (-not (Test-Path $DebuggerPath -PathType Leaf))
{
throw "DebuggerPath param ($DebuggerPath) does not point to a debugger."
}
# Searching for loaded instances of ExdiGdbSrv.dll in dllhost.exe requires elevation
if (-not $DontTryDllHostCleanup -and
-not $(Test-Admin))
{
throw "Searching for loaded instances of ExdiGdbSrv.dll in dllhost.exe requires elevation. Run with the -DontTryDllHostCleanup parameter to skip this check (debugger session init may fail)."
}
}
Function Get-ExdiInstallPath
{
Get-ItemPropertyValue -Path "Registry::HKEY_CLASSES_ROOT\CLSID\{29f9906e-9dbe-4d4b-b0fb-6acf7fb6d014}\InProcServer32" -Name "(default)" -ErrorAction SilentlyContinue
}
Function Test-ExdiServerInstalled
{
# Check registration of exdi server class
if ($(Get-ExdiInstallPath) -ne $null -and $(Test-Path "$(Get-ExdiInstallPath)"))
{
Write-Verbose "Exdi server is installed. Checking installation..."
$ExdiInstallDir = [System.IO.Path]::GetDirectoryName($(Get-ExdiInstallPath))
if (-not (Test-Path $ExdiInstallDir))
{
Write-Host "Currently Registered exdi server does not exist. Reinstalling..."
return $false
}
elseif (-not ((Test-Path "$ExdiInstallDir\exdiConfigData.xml") -and (Test-Path "$ExdiInstallDir\systemregisters.xml")))
{
Write-Host "Currently Registered exdi server does not have required xml settings files. Reinstalling..."
return $false
}
else
{
Write-Verbose "Exdi server is insalled correctly. Skipping installation..."
return $true
}
}
else
{
Write-Host "Exdi server is not installed. Installing..."
return $false
}
}
Function Install-ExdiServer
{
[CmdletBinding()]
param
(
[string] $InstallFrom,
[string] $InstallTo
)
if (-not $(Test-Admin))
{
throw "Script needs to be run as an Admin to install exdi software."
}
New-Item -ItemType Directory $InstallTo -ErrorAction SilentlyContinue | Write-Verbose
Copy-Item -Path "$InstallFrom\ExdiGdbSrv.dll" -Destination $InstallTo -ErrorAction stop | Write-Verbose
Copy-Item -Path "$InstallFrom\exdiConfigData.xml" -Destination $InstallTo -ErrorAction stop | Write-Verbose
Copy-Item -Path "$InstallFrom\systemregisters.xml" -Destination $InstallTo -ErrorAction stop | Write-Verbose
regsvr32 /s "$InstallTo\ExdiGdbSrv.dll"
if ($(Get-ExdiInstallPath) -eq $null)
{
throw "Unable to install exdi server"
}
}
Function Edit-ExdiConfigFile
{
[CmdletBinding()]
param
(
[string] $ExdiFilePath,
[string] $ExdiTargetType,
[PSCustomObject[]] $XmlSettingPathValueList
)
# Edit exdiConfigData.xml
[xml]$exdiConfigXml = Get-Content "$ExdiFilePath"
# Set current target
$exdiConfigXml.ExdiTargets.CurrentTarget = $ExdiTarget
# set HostNameAndPort
$ExdiTargetXmlNode = $exdiConfigXml.SelectSingleNode("//ExdiTargets/ExdiTarget[@Name='$ExdiTarget']/ExdiGdbServerConfigData")
foreach ($XmlSettingPathValue in $XmlSettingPathValueList)
{
Write-Verbose "Processing $XmlSettingPathValue"
if ($XmlSettingPathValue.Value -eq $null)
{
continue
}
$PathParts = $XmlSettingPathValue.Path.Split(".")
$curNode = $ExdiTargetXmlNode
if ($PathParts.Count -gt 1)
{
foreach ($PathPart in $PathParts[0..($PathParts.Count-2)])
{
Write-Verbose $PathPart
$curNode = $curNode.($PathPart)
}
}
$curNode.($PathParts[-1]) = $XmlSettingPathValue.Value
}
$exdiConfigXml.Save("$ExdiFilePath")
}
Function Stop-ExdiContainingDllHosts
{
$DllHostPids = Get-Process dllhost | ForEach-Object { $_.Id }
foreach ($DllHostPid in $DllHostPids)
{
$DllHostExdiDlls = Get-Process -Id $DllHostPid -Module | Where-Object { $_.FileName -like "*ExdiGdbSrv.dll" }
if ($DllHostExdiDlls.Count -ne 0)
{
Write-Verbose "Killing dllhost.exe with pid $DllHostPid (Contained instance of ExdiGdbSrv.dll)"
Stop-Process -Id $DllHostPid -Force
}
}
}
#endregion
#region Script
# Apply defaults for $DebuggerPath before Parameter validation
if (-not $DebuggerPath)
{
$DebuggerPath = Find-PathToWindbgX
}
Test-ParameterValidation
# look clean up dllhost.exe early since it can hold a lock on files which
# need to be overwritten
if (-not $DontTryDllHostCleanup)
{
Stop-ExdiContainingDllHosts
}
if (-not $(Test-ExdiServerInstalled))
{
if (-not $ExdiDropPath)
{
throw "ExdiServer is not installed and -ExdiDropPath is not valid"
}
$ExdiInstallDir = Join-Path -Path "$([System.IO.Path]::GetDirectoryName($DebuggerPath))" -ChildPath "exdi"
Install-ExdiServer -InstallFrom "$ExdiDropPath" -InstallTo "$ExdiInstallDir"
}
$SystemRegistersFilepath = Join-Path -Path "$([System.IO.Path]::GetDirectoryName($(Get-ExdiInstallPath)))" -ChildPath "systemregisters.xml"
$ExdiConfigFilepath = Join-Path -Path "$([System.IO.Path]::GetDirectoryName($(Get-ExdiInstallPath)))" -ChildPath "exdiConfigData.xml"
# Calculate implied parameters
$HeuristicScanSize = if ($PreNTAppDebugging) { "0xffe" } else { "0xfffe" }
$ArchitectureFamily = switch($Architecture)
{
x64 { "ProcessorFamilyx64" }
x86 { "ProcessorFamilyx86" }
arm64 { "ProcessorFamilyARM64" }
}
# Path is evaluated relative to the relevant ExdiTarget's ExdiGdbServerConfigData node in the xml schema
$SettingsToChange = @(
[pscustomobject]@{ Path = 'GdbServerConnectionParameters.Value.HostNameAndPort' ; Value = "${HostName}:$GdbPort" },
[pscustomobject]@{ Path = 'ExdiGdbServerTargetData.targetArchitecture' ; Value = "$Architecture" },
[pscustomobject]@{ Path = 'ExdiGdbServerTargetData.targetFamily' ; Value = "$ArchitectureFamily" },
[pscustomobject]@{ Path = 'ExdiGdbServerTargetData.heuristicScanSize' ; Value = "$HeuristicScanSize" },
[pscustomobject]@{ Path = 'displayCommPackets' ; value = "no" }
)
Edit-ExdiConfigFile -ExdiFilePath "$ExdiConfigFilepath" -ExdiTargetType "$ExdiTarget" -XmlSettingPathValueList $SettingsToChange
# Set env vars for debugger
[System.Environment]::SetEnvironmentVariable('EXDI_GDBSRV_XML_CONFIG_FILE',"$ExdiConfigFilepath")
[System.Environment]::SetEnvironmentVariable('EXDI_SYSTEM_REGISTERS_MAP_XML_FILE',"$SystemRegistersFilepath")
$DebuggerArgs = @("-v", "-kx exdi:CLSID={29f9906e-9dbe-4d4b-b0fb-6acf7fb6d014},Kd=Guess,DataBreaks=Exdi")
Write-Verbose "DebuggerPath = $DebuggerPath"
Start-Process -FilePath "$DebuggerPath" -ArgumentList ($DebuggerArgs + $ExtraDebuggerArgs)
#endregion
Weitere Informationen
Einrichten des QEMU-Kernelmodus-Debuggings mit EXDI
Automatisches Einrichten des KDNET-Netzwerkkernel-Debuggings
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Issues stufenweise als Feedbackmechanismus für Inhalte abbauen und durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter https://aka.ms/ContentUserFeedback.
Feedback senden und anzeigen für