Uso di Inflight Trace Recorder (IFR) nei driver KMDF e UMDF 2
A partire da Windows 10, è possibile compilare il driver KMDF o UMDF in modo da ottenere informazioni aggiuntive sul debug dei driver tramite la pre-elaborazione del software Windows. Questa funzionalità, denominata Inflight Trace Recorder (IFR), è disponibile a partire da KMDF versione 1.15 e UMDF versione 2.15.
Inflight Trace Recorder è un'estensione della traccia software WPP. A differenza della traccia WPP, Inflight Trace Recorder continua a funzionare senza un consumer di traccia collegato. Il framework scrive messaggi in un buffer circolare e il driver può anche aggiungere i propri messaggi. Ogni driver ha un proprio log, quindi più dispositivi associati a un driver condividono un singolo log.
Se si attiva l'IFR nel file binario del driver, l'IFR è presente e in esecuzione durante la durata del driver. Non è necessario avviare una sessione di raccolta di traccia esplicita.
I log vengono archiviati in memoria non paginabile, quindi sono ripristinabili dopo un arresto anomalo del sistema. Inoltre, i log di Inflight Trace Recorder sono inclusi nei file minidump tranne quando il driver responsabile non è indeterminato o se l'arresto anomalo è un timeout host.
Come abilitare Inflight Trace Recorder e inviare messaggi dal driver
In Microsoft Visual Studio seguire questa procedura:
Aprire le pagine delle proprietà per il progetto driver. Fare clic con il pulsante destro del mouse sul progetto driver in Esplora soluzioni e selezionare Proprietà. Nelle pagine delle proprietà per il driver selezionare Proprietà di configurazione e quindi Wpp Tracing. Nel menu Generale impostare Esegui traccia WPP su Sì.
Passare a Proprietà-Wpp> Tracing-Function e> macro opzioni e scegliere Abilita registrazione WPP.
Nello stesso menu impostare Analizza dati di configurazione sul file contenente le informazioni di traccia, ad esempio Trace.h.
In ogni file di origine che chiama una macro WPP, aggiungere una direttiva #include che identifica un file di intestazione del messaggio di traccia (TMH). Il nome del file deve avere un formato di <driver-source-file-name.tmh.>
Ad esempio, se il driver è costituito da due file di origine, denominato MyDriver1.c e MyDriver2.c, MyDriver1.c deve contenere:
#include "MyDriver1.tmh"
e MyDriver2.c devono contenere:
#include "MyDriver2.tmh"
Quando si compila il driver in Visual Studio, il preprocessore WPP genera l'oggetto . file tmh .
Definire una macro WPP_CONTROL_GUIDS in un file di intestazione. Questa macro definisce un GUID e flag di traccia per i messaggi di traccia del driver.
L'esempio di driver Osrusbfx2 definisce un singolo GUID di controllo e sette flag di traccia nel file di intestazione Trace.h, come illustrato nell'esempio seguente:
#define WPP_CONTROL_GUIDS \ WPP_DEFINE_CONTROL_GUID(OsrUsbFxTraceGuid, \ (d23a0c5a,d307,4f0e,ae8e,E2A355AD5DAB), \ WPP_DEFINE_BIT(DBG_INIT) /* bit 0 = 0x00000001 */ \ WPP_DEFINE_BIT(DBG_PNP) /* bit 1 = 0x00000002 */ \ WPP_DEFINE_BIT(DBG_POWER) /* bit 2 = 0x00000004 */ \ WPP_DEFINE_BIT(DBG_WMI) /* bit 3 = 0x00000008 */ \ WPP_DEFINE_BIT(DBG_CREATE_CLOSE) /* bit 4 = 0x00000010 */ \ WPP_DEFINE_BIT(DBG_IOCTL) /* bit 5 = 0x00000020 */ \ WPP_DEFINE_BIT(DBG_WRITE) /* bit 6 = 0x00000040 */ \ WPP_DEFINE_BIT(DBG_READ) /* bit 7 = 0x00000080 */ \ )Esempio:
- OsrUsbFxTraceGuid è il nome descrittivo per il GUID {d23a0c5a-d307-4f0e-ae8e-E2A355AD5DAB} .
- I flag di traccia vengono usati per distinguere tra i messaggi di traccia generati come driver gestisce diversi tipi di richieste di I/O.
Il driver (sia KMDF che UMDF 2) deve chiamare WPP_INIT_TRACING per i driver di Kernel-Mode con l'oggetto driver e un percorso del Registro di sistema, in genere da DriverEntry:
WPP_INIT_TRACING( DriverObject, RegistryPath );Per disattivare la traccia, sia KMDF che UMDF 2 driver chiamano WPP_CLEANUP per i driver di Kernel-Mode da EvtCleanupCallback o EvtDriverUnload:
WPP_CLEANUP( WdfDriverWdmGetDriverObject( Driver ));La macro WPP_CLEANUP accetta un parametro di tipo PDRIVER_OBJECT, quindi, se il driver del driver ha esito negativo, è possibile ignorare la chiamata a WdfDriverWdmGetDriverObject e chiamare invece WPP_CLEANUP con un puntatore all'oggetto driver WDM.
Poiché i driver UMDF usano le firme in modalità kernel di queste macro per inizializzare e pulire la traccia, le chiamate sembrano identiche per KMDF e UMDF.
Usare la macro DoTraceMessage o una versione personalizzata della macro nel driver per creare messaggi di traccia.
Nell'esempio seguente viene illustrato come il driver Osrusbfx2 usi la funzione TraceEvents in una parte del codice dedicato alla gestione delle richieste di lettura:
if (Length > TEST_BOARD_TRANSFER_BUFFER_SIZE) { TraceEvents(TRACE_LEVEL_ERROR, DBG_READ, "Transfer exceeds %d\n", TEST_BOARD_TRANSFER_BUFFER_SIZE); status = STATUS_INVALID_PARAMETER; }La chiamata a TraceEvents genera un messaggio di traccia se il controller di traccia abilita il livello di TRACE_LEVEL_ERROR e il flag di traccia DBG_READ . Il messaggio include il valore della costante definita dal driver TEST_BOARD_TRANSFER_BUFFER_SIZE.
Per modificare le dimensioni del buffer circolare usato dal log del driver, modificare il valore del Registro di sistema LogPages nel percorso del Registro di sistema seguente:
SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services<\YourDriver>\Parameters\Wdf
<HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\YourDriver>\Parameters\Wdf
Si tratta di un valore di tipo REG_DWORD che contiene le dimensioni del buffer di log allocato, nelle pagine. I valori validi sono compresi tra 0x1 e 0x10.
Per un driver KMDF
- Caricare i comandi RCDRKD digitando .load rcdrkd.dll nel debugger.
- Usare l'estensione !wdfkd.wdfldr per visualizzare informazioni sul driver attualmente associato dinamicamente a Windows Driver Framework (WDF).
- Usare !rcdrkd.rcdrlogdump e !rcdrkd.rcdrcrashdump per visualizzare i messaggi forniti dal driver.
- Usare !wdfkd.wdflogdump o !wdfkd.wdfcrashdump per visualizzare i messaggi forniti dal framework.
Debug in tempo reale di un driver UMDF
Usare l'estensione !wdfkd.wdfldr per visualizzare informazioni sui driver attualmente associati dinamicamente a WDF. Trovare il driver in modalità utente. Immettere il processo host associato.
Digitare !wdfkd.wdflogdump<YourDriverName.dll><Flag> , dove <Flag> è:
- 0x1 - Log del framework e del driver uniti
- 0x2 - Log driver
- 0x3 - Log del framework
Se non è presente alcun log driver per il driver specificato, l'estensione visualizza solo il log del framework.
Visualizzazione dei log di Registrazione traccia in volo dopo un arresto anomalo del driver UMDF
Da WinDbg selezionare File-Open> Crash Dump e specificare il file minidump da eseguire il debug.
Digitare !wdfkd.wdfcrashdump <YourDriverName.dll><ID processo dell'opzione> host><driver, dove <Option> è:
- 0x1 - Log del framework e del driver uniti
- 0x2 - Log driver
- 0x3 - Log del framework
Se non si specifica un driver, !wdfcrashdump visualizza le informazioni per tutti i driver. Se non si specifica un processo host e ne esiste solo uno, l'estensione usa il processo host singolo. Se non si specifica un processo host e sono presenti più di uno, l'estensione elenca i processi host attivi.
Se le informazioni di log archiviate nel minidump non corrispondono al nome immesso, il minidump non contiene i log del driver.
Se non si dispone di un debugger connesso, è comunque possibile accedere ai log del driver e del framework. Per informazioni su come, vedere Video: Accesso ai log IFR del driver senza un debugger.
Per altre informazioni sull'aggiunta di messaggi di traccia al driver, vedere Aggiunta di macro WPP a un driver.
Articoli correlati
Come abilitare il debug di un driver UMDF
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per