Configurazione del trasporto del debugger EXDI

Articolo
11/01/2024

Questo argomento descrive come configurare il debug in modalità kernel usando EXDI. L'interfaccia di debug esteso (EXDI) è un livello di adattamento tra un debugger software e una destinazione di debug.

Gli strumenti di debug per Windows supportano il debug del kernel usando EXDI a partire da Windows versione 22000.
L'interfaccia utente per configurare EXDI è disponibile nel debugger a partire dalla versione 1.2410.11001.0.

È possibile usare EXDI per stabilire una connessione con l'ambiente virtuale QEMU. Per altre informazioni, vedere Configurazione del debug in modalità kernel QEMU con EXDI.

Nota

EXDI è una forma avanzata e specializzata di debug per ambienti specifici. L'uso di una connessione KDNET standard è più semplice da configurare ed è consigliabile. Per configurare automaticamente il debug di rete, vedere Configurazione automatica del debug del kernel di rete KDNET.

Panoramica del server COM EXDI

EXDI è un'interfaccia che estende WinDbg aggiungendo il supporto per i debugger hardware(ad esempio basato su JTAG o basato su GdbServer). Il diagramma seguente illustra il ruolo di EXDI-GdbServer.

Diagramma dello stack che mostra il ruolo di EXDI-GdbServer con WinDbg-DbgEng sopra, un'interfaccia EXDI e un server COM EXDI che comunica con un server GDB.

Un server COM fa riferimento a un componente binario che implementa un'interfaccia COM. In questo caso exdi3.idl implementato da ExdiGdbSrv.dll per il client del protocollo del debugger windows.

Il ExdiGdbsrv.dll stesso implementa il lato client del protocollo GDB-RSP sul lato server GDB (o qualche volta denominato stub del server GDB) viene implementato dal server GDB QEMU (o dallo stub del server GDB Trace32/OpenOCD/UEFI GDB e così via).

Poiché la connessione EXDI non ha alcuna dipendenza da Windows o dal protocollo KDNET di debug di Windows caricato nel PC di destinazione. Poiché questi componenti del debugger software non sono necessari, EXDI può essere utile nelle prime fasi del dispositivo e nel debug dei problemi di avvio del sistema operativo.

Importante

Poiché EXDI non usa il protocollo KDNET, il debugger connesso dispone di informazioni significativamente meno su ciò che è in esecuzione nel PC e molti comandi funzioneranno in modo diverso o potrebbero non funzionare affatto. L'accesso ai simboli privati per il codice sottoposto a debug può aiutare il debugger a comprendere meglio l'esecuzione del codice dei sistemi di destinazione. Per altre informazioni, vedere Simboli pubblici e privati.

Requisiti dei dispositivi in modalità kernel EXDI

Il computer che esegue il debugger viene chiamato computer host e il computer sottoposto a debug viene chiamato computer di destinazione.

È necessario quanto segue:

Nel computer di destinazione e host, una scheda di rete supportata supportata dall'ambiente desiderato, ad esempio QEMU.
Connessione di rete tra la destinazione e l'host tramite TCP/IP.
Windows 10 o Windows 11 versione 22000 o successiva.

Limiti

Come descritto in precedenza, poiché EXDI non usa il protocollo KDNET, il debugger connesso ha meno informazioni sul sistema di destinazione e l'uso del debugger è diverso. Senza l'accesso ai simboli privati per il codice di destinazione, molti comandi che usano simboli per comprendere lo stato del sistema di destinazione non funzioneranno. In questo caso, è possibile visualizzare la memoria e registrare il contenuto e disassemblare il codice. Determinare la posizione del codice in esecuzione o eseguire altre attività comuni del debugger può essere molto difficile e dispendioso in termini di tempo senza simboli privati.

Debug SIMultaneo di EXDI e KDNET

In alcuni scenari complessi, ad esempio nelle prime fasi del dispositivo, può essere utile avere due connessioni al dispositivo di destinazione. Un EXDI e un KDNET. Se la destinazione è un sistema operativo Windows, il debug del software KDNET viene configurato come normalmente, ad esempio per connettersi a una macchina virtuale. In questa configurazione, uno dei due debugger simultanei può interrompere il debug del codice nel computer di destinazione.

WinDbg nel server di elaborazione

Il componente EXDI binario può essere eseguito fuori dal processo Windbg o all'interno del processo Windbg. L'uso dell'interfaccia utente DI EXDI o migliora notevolmente l'affidabilità Inproc=<EXDI COM server binary> , riducendo gli errori di avvio COM. Pertanto, è sempre consigliabile eseguire la sessione EXDI con il parametro Inproc, che è sempre abilitato quando si usa l'interfaccia utente.

Per l'avvio della riga di comando, l'opzione predefinita non è elaborata, ma inprocess deve essere abilitata usando il InProc=ExdiGdbDrv.dll parametro .

Client del server GDB COM

In questo argomento viene descritto l'uso del client server GDB COM EXDI (ExdiGdbSrv.dll) che implementa l'interfaccia del debugger COM EXDI. È possibile usare la stessa interfaccia COM per implementare altre interfacce, ad esempio un server COM EXDI per JTAG-DCI.

Riepilogo del processo per l'uso di una connessione EXDI

Usare questo processo per usare una connessione EXDI con WinDbg.

Scaricare e installare gli strumenti di debug di Windows nel sistema host.
Avviare WinDbg usando l'interfaccia utente o l'opzione -kx per connettersi al server EXDI.
Usare WinDbg per eseguire il debug del sistema di destinazione usando un sub set di comandi del debugger disponibili.

Per un esempio di scenario di utilizzo di EXDI, vedere Configurazione del debug in modalità kernel QEMU tramite EXDI.

Scaricare e installare gli strumenti di debug di Windows

Installare gli strumenti di debug di Windows nel sistema host. Per informazioni sul download e l'installazione degli strumenti del debugger, vedere Strumenti di debug per Windows.

Avviare WinDbg e connettersi al server EXDI

Nell'interfaccia utente della connessione kernel EXDI è possibile configurare le opzioni seguenti.

Interfaccia utente della connessione kernel EXDI windbg, con opzioni di connessione visualizzate, tra cui INDIRIZZO IP e porta.

Tipo di [Trace32|BMC-OpenOCD|QEMU|VMWare|UEFI] destinazione Selezionare in base al tipo di destinazione di cui si vuole eseguire il debug. Sono disponibili i tipi di destinazione seguenti.
- Trace32 : Configurazione del server GDB del debugger Trace32 Trace32 HW
- BMC-OpenOCD : configurazione del server GDB del debugger BMC-OpenOCD HW
- QEMU: configurazione del server GDB del simulatore SW QEMU
- VMWare: configurazione del server GDB VMWare
- UEFI: debug del firmware UEFI
Architettura [x86 | ARM64 | x64] di destinazione: architettura del processore di destinazione. Si noti che tutti i tipi di destinazione potrebbero non supportare tutte le architetture di destinazione.
Sistema operativo [Windows|Linux] di destinazione: selezionare in base al sistema operativo di destinazione di cui si vuole eseguire il debug.
Dimensioni [None | 0xFE - PreNT |0xFFE - NT] euristiche dell'analisi delle immagini: selezionare una delle tre opzioni per determinare le dimensioni euristiche per l'analisi delle immagini. Questo valore consente di configurare il modo in cui il motore del debugger analizza la memoria alla ricerca della firma PE DOS, usata per raccogliere lo stato di execuition del codice. Se il valore dell'attributo non è specificato (o "0"), il motore del debugger non userà l'euristica veloce ed eseguirà il fallback all'euristica legacy che analizza l'intera memoria cercando la firma PE DOS. Il valore predefinito è selezionato per ogni tipo di destinazione ed è consigliato.
Server e porta TargetIPAddress:TargetPortAddress Gdb: impostare su una stringa che contiene, IPTargetAddress, due punti e PortAddress di destinazione. Ad esempio, LocalHost:1234 o 168.82.1.5:5555.
Interruzione nelle connessioni [on|off] Selezionare la casella di controllo per suddividersi nella destinazione dopo che è stata stabilita la connessione.
Opzioni avanzate

Mostra log pacchetti [on|off] di comunicazione: selezionare la casella di controllo per visualizzare i valori esadecimali del log dei pacchetti di comunicazione GDBServer non elaborati per il debug e la risoluzione dei problemi.

Dopo aver selezionato le opzioni desiderate, selezionare OK per connettersi.

Configurare le opzioni avanzate usando i file XML di configurazione EXDI

Le opzioni più necessarie sono disponibili nell'interfaccia utente descritta in questo argomento. Per informazioni sulla configurazione di opzioni avanzate tramite i file XML di configurazione EXDI, vedere File di configurazione XML DI EXDI.

Esempio di EXDI della riga di comando di WinDbg

Per avviare la sessione windbg che usa l'interfaccia EXDI al prompt dei comandi, usare queste opzioni.

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

Per visualizzare un output aggiuntivo utile per scopi di diagnostica, è possibile usare la sessione -v: dettagliata. Per informazioni generali sulle opzioni winDbg, vedere Opzioni della riga di comando di WinDbg. Per altre informazioni, vedere Parametri di caricamento winDbg EXDI di seguito.

La console del debugger visualizzerà l'inizializzazione del trasporto 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

Sessione WinDbg principale che visualizza CLSID EXDI nel titolo della finestra.

La finestra della console EXDIGdbServer può anche visualizzare informazioni sullo stato della connessione EXDI. Per altre informazioni sulla console, vedere Risoluzione dei problemi.

Parametri di caricamento winDbg EXDI

I parametri seguenti vengono usati con WinDbg per avviare una sessione del kernel EXDI.

-kx EXDI:Options

Le opzioni EXDI seguenti sono disponibili con l'opzione -kx. Ogni opzione deve essere separata usando una virgola.

Parametro	Descrizione
CLSID	ID classe assegnato al LiveExdiGdbSrvServer (come definito nel fileExdiGdbSrv.idl).
Kd=Guess -or- NtBaseAddr	Il motore del debugger userà un meccanismo euristico generale oppure cercare l'indirizzo di base NT.
ForceX86	Forza il motore del debugger a usare l'interfaccia IeXdiX86Context3 per ottenere/impostare Il contesto della CPU.
DataBreaks=Exdi	Consentire l'uso dei punti di interruzione dei dati.
Inproc	Consentire l'uso di un exdi-server inproc. Questa opzione è consigliata : InProc=ExdiGdbDrv.dll
PathToSrvCfgFiles	Percorso dei file di configurazione XML per EXDI.

Controllo della ricerca euristica e delle dimensioni euristiche

Come descritto in precedenza, il debugger usa un algoritmo euristico per individuare l'indirizzo di base NT. Per annullare la ricerca euristica, quando si avvia WinDbg tramite la riga di comando, completare i passaggi seguenti.

Impostare euristicScanSize su 0 nel file di exdiconfigdata.xml per il server di destinazione a cui verrà collegato.
Usare il kd=NtBaseAddr tipo euristico nella riga di comando windbg.

Per altre informazioni sull'uso dei file di configurazione XML, vedere File di configurazione XML DI EXDI.

Usare WinDbg per eseguire il debug del sistema di destinazione- punti di interruzione

Il dbgeng.dll usa un algoritmo euristico per trovare la posizione dell'indirizzo di caricamento di base NT al momento in cui si è verificato il comando di interruzione. Se i simboli privati non sono disponibili, questo processo avrà esito negativo.

Ciò significa che in molte sequenze di connessione l'interruzione non funzionerà come previsto. se si suddivide manualmente nel codice, si tratta di una posizione casuale in cui Windows è stato eseguito in quel momento. Poiché i simboli per il codice di destinazione potrebbero non essere disponibili, può essere difficile impostare punti di interruzione usando i simboli.

Comandi del debugger

I comandi, ad esempio i seguenti, che accedono direttamente alla memoria funzioneranno.

k, kb, kc, kd, kp, kP, kv (Display Stack Backtrace)

r (registri)

d, da, db, dc, dd, dD, df, dp, dq, du, dw (Display Memory)

u (unassemble)

È anche possibile scorrere il codice usando p (passaggio).

Sono inoltre disponibili comandi che possono essere usati per tentare di individuare il codice di cui si vuole eseguire il debug.

s (memoria di ricerca)

.imgscan (Trova intestazioni immagine)

Imgscan può essere utile con il debug EDXI, come a differenza del debug del kernel basato su KDNET tradizionale, l'impostazione di punti di interruzione in base ai simboli potrebbe non essere disponibile. L'individuazione di un'immagine di destinazione desiderata può semplificare l'uso della posizione per impostare un punto di interruzione di accesso alla memoria.

.exdicmd (comando EXDI)

.exdicmd invia un comando EXDI al sistema di destinazione usando la connessione di debug EXDI attiva. Per altre informazioni, vedere .exdicmd (comando EXDI).

Risoluzione dei problemi

Usare l'output della finestra ExdiGdbServer per monitorare la sequenza di connessione.

Finestra di testo ExdiGdbServer con numeri esadecimali lunghi.

Problema: Errore: impossibile stabilire una connessione con GbDServer. Verificare il stringa di connessione <hostname/ip>:portnumber

Questo problema potrebbe essere causato da:

Il ExdiGdbSrv.dll non può connettersi al server GDB di destinazione.
Il server GDB non è ancora in esecuzione nella destinazione.
Problemi del firewall, assicurarsi che entrambi gli indirizzi IP siano raggiungibili usando ping, tracert o altri strumenti per verificare che il traffico GDB possa attraversare il firewall.

Problema: lo scenario di errore con il sistema di destinazione non è disponibile - DbgCoInitialize restituito 0x00000001

L'output seguente può essere restituito se il sistema di destinazione non è caricato o non è disponibile.

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

EXDI: DbgCoInitialize returned 0x00000001

Si tratta di un errore comune quando il server COM ExdiGdbSrv.dll non è riuscito a connettersi al GDServer QEMU, quindi potrebbe non riuscire a causa di:

La sessione precedente del ExdiGdbSrv.dll è ancora ospitata da un processo di dllhost.exe, quindi è necessario terminare il processo di dllhost.exe. Usare TaskList al prompt dei comandi per individuare il PID di dllhost.exe che ospita il ExdiGdbSrv.dll. Usare TaskKill /PID <PID ID> /f e terminare il PID associato. Per altre informazioni sull'uso dei PID, vedere Ricerca dell'ID processo.
QEMU gdbserver non è ancora stato avviato o il file exdiconfigdata.xml contiene valori IP:Port non validi. Se la sessione WinDbg viene avviata nello stesso pc host della macchina virtuale Windows QEMU, ip=LocalHost.
Errore durante l'avvio del server COM EXDI (ExdiGDbSrv.dll) tramite il processo di dllhost.exe (correlato a COM). Per risolvere questo problema, riavviare il PC del debugger host o disconnettersi di nuovo da Windows e accedere. In caso contrario, registrare nuovamente il server COM EXDI dopo il riavvio o l'accesso.
- regsvr32.exe <full path to the ExdiGdbSrv.dll)

Problema: impossibile avviare la sessione di debug: FAILURE HR=0x80004005:Failed to AttachKernel.

Questo problema potrebbe essere causato da:

Come descritto in precedenza, è possibile che la sessione precedente del ExdiGdbSrv.dll sia ancora attiva. Individuare e terminare l'host DLL associato come descritto in precedenza.

Finestra di dialogo WinDbg che visualizza un errore con 0x80004005 HR.

Problema: non è stato possibile avviare il debug del kernel con EXDI.

Questo problema potrebbe essere causato da:

Esiste un'altra istanza del ExdiGdbSrv.dll (ospitata da dllhost.exe) in esecuzione nel computer del debugger host.
Terminare l'istanza aggiuntiva del servizio COM che ospita il ExdiGdbSrv.dll.
- Per prima cosa elencare i processi, usando utilità come TList nel PC host. DLLHost che ospita il ExdiGdbSrv.dll mostrerà ExdiGdbServer.
  
  tlist 261928 dllhost.exe ExdiGdbServer
- Usare kill -f XXXXX al prompt dei comandi del debugger per terminare il processo usando il numero di processo.

Problema: Errore: non è possibile configurare la sessione GdbServer.

Questo problema potrebbe essere causato da:

Errore durante l'individuazione delle informazioni sulla sessione, ad esempio il percorso dei file di configurazione XML.

Problema: Errore: la variabile di ambiente EXDI_GDBSRV_XML_CONFIG_FILE non è definita.

Questo problema potrebbe essere causato da:

ExdiGdbSrv.dll variabili di ambiente non sono impostate o non sono altrimenti disponibili nell'ambiente.

Problema: Errore: la variabile di ambiente EXDI_GDBSRV_XML_CONFIG_FILE non è definita. L'esempio Exdi-GdbServer non continuerà a questo punto. Impostare il percorso completo sul file di configurazione XML di Exdi.

Questo problema potrebbe essere causato da:

La variabile di ambiente EXDI_GDBSRV_XML_CONFIG_FILE non è impostata. In alcune situazioni, ExdiGDbSrv.dll continuerà a funzionare se si preme il pulsante "OK", ma windbg.exe non riuscirà a eseguire query sui registri di sistema (ad esempio tramite funzioni rdmsr/wrmsr).