Uso di IfR (Inflight Trace Recorder) nei driver KMDF e UMDF 2

Articolo
07/08/2024

A partire da Windows 10, puoi compilare il driver KMDF o UMDF in modo che ottenga informazioni aggiuntive sul debug dei driver tramite la pre-elaborazione della traccia software Windows. Questa funzionalità, denominata IfR (Inflight Trace Recorder), è 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 impaginabile, quindi sono recuperabili dopo un arresto anomalo del sistema. Inoltre, i log di Registrazione traccia in volo sono inclusi nei file minidump tranne quando il driver responsabile non è deterministico o se l'arresto anomalo è un timeout dell'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 scegliere 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 Options (Opzioni macro) e scegliere Enable WPP Recorder (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 <driver-source-file-name.tmh>.

Ad esempio, se il driver è costituito da due file di origine, denominati 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 .file tmh .

Definire una macro WPP_CONTROL_GUIDS in un file di intestazione. Questa macro definisce un GUID e i 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 */ \
)

In questo esempio:

OsrUsbFxTraceGuid è il nome descrittivo del GUID {d23a0c5a-d307-4f0e-ae8e-E2A355AD5DAB}.
I flag di traccia vengono usati per distinguere tra i messaggi di traccia generati mentre il driver gestisce diversi tipi di richieste di I/O.

Il driver (KMDF e UMDF 2) deve chiamare WPP_INIT_TRACING per i driver in modalità kernel con l'oggetto driver e un percorso del Registro di sistema, in genere da DriverEntry:
```
WPP_INIT_TRACING( DriverObject, RegistryPath );
```
Per disattivare la traccia, i driver KMDF e UMDF 2 chiamano WPP_CLEANUP per i driver in modalità kernel da EvtCleanupCallback o EvtDriverUnload:
```
WPP_CLEANUP( WdfDriverWdmGetDriverObject( Driver ));
```
La macro WPP_CLEANUP accetta un parametro di tipo PDRIVER_OBJECT, quindi se driverEntry 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 hanno un aspetto identico per KMDF e UMDF.
Utilizzare la macro DoTraceMessage o una versione personalizzata della macro nel driver per creare messaggi di traccia.

L'esempio seguente mostra 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:

Per UMDF:

SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF\Services\<YourDriver>\Parameters\Wdf

Per KMDF:

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 di framework e driver uniti
- 0x2 : log del 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 di cui si vuole eseguire il debug.
Digitare !wdfkd.wdfcrashdump <YourDriverName.dll><ID processo dell'opzione> host<>driver, dove <Option> è:
- 0x1 : log di framework e driver uniti
- 0x2 : log del driver
- 0x3 - Log del framework
Se non si specifica un driver, !wdfcrashdump visualizza informazioni per tutti i driver. Se non si specifica un processo host e ne esiste solo uno, l'estensione usa il singolo processo host. Se non si specifica un processo host e ne sono presenti più, 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.

Come abilitare il debug di un driver UMDF

Estensioni RCDRKD

Uso del logger di eventi del framework

Uso della traccia software WPP nei driver UMDF

Condividi tramite

Uso di IfR (Inflight Trace Recorder) nei driver KMDF e UMDF 2

Commenti e suggerimenti

Risorse aggiuntive

Condividi tramite

Uso di IfR (Inflight Trace Recorder) nei driver KMDF e UMDF 2

Articoli correlati

Commenti e suggerimenti

Risorse aggiuntive