Uso della traccia software WPP nei driver UMDF

Articolo
03/08/2023

La traccia software WPP consente di aggiungere messaggi di traccia che consentono di eseguire il debug del driver. Inoltre, il logger di eventi del framework fornisce centinaia di messaggi di traccia che è possibile visualizzare.

È possibile visualizzare i messaggi di traccia tramite TraceView o Tracelog. È anche possibile inviare messaggi di traccia a un debugger del kernel.

Aggiunta di messaggi di traccia al driver

Per aggiungere messaggi di traccia al driver basato sul framework, è necessario:

Aggiungere una direttiva #include a ognuno dei file di origine del driver che contiene una delle macro WPP. Questa direttiva deve identificare 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 Microsoft Visual Studio, il preprocessore WPP genera i 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. Per ognuno dei driver di esempio basati su UMDF di WDK, il file di intestazione Internal.h include questa macro.
Includere una macro WPP_INIT_TRACING nella routine DllMain del driver. Questa macro attiva la traccia software nel driver. Per ognuno dei driver di esempio basati su UMDF di WDK, il file di intestazione DllSup.h include questa macro.
Includere una macro WPP_CLEANUP nella routine DllMain del driver. Questa macro disattiva la traccia software nel driver. Per ognuno dei driver di esempio basati su UMDF di WDK, il file di intestazione DllSup.h include questa macro.
Utilizzare la macro DoTraceMessage o una versione personalizzata della macro nel driver per creare messaggi di traccia. Per ognuno dei driver di esempio basati su UMDF di WDK, il file di intestazione Internal.h include una macro personalizzata.
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à. In Pagine delle proprietà per il driver selezionare Proprietà di configurazione e quindi Wpp. Nel menu Generale impostare Esegui traccia WPP su Sì. Nel menu Opzioni file è necessario specificare anche il file modello WPP del framework, ad esempio:
```
{km-WdfDefault.tpl}*.tmh
```

Per altre informazioni sull'aggiunta di messaggi di traccia al driver, vedere Aggiunta di macro WPP a un driver.

Driver di esempio che usano la traccia software WPP

Tutti i driver di esempio basati su UMDF in WDK forniscono file DllSup.h, Internal.h e Sources che abilitano la traccia software WPP. La maggior parte di questi driver di esempio usa anche una macro personalizzata per creare messaggi di traccia.

Visualizzazione dei messaggi di traccia del driver

Se sono stati aggiunti messaggi di traccia al driver, il driver è un provider di traccia. È possibile usare un controller di traccia, ad esempio Tracelog, per controllare una sessione di traccia e creare un log di traccia. È possibile usare un consumer di traccia, ad esempio Tracefmt, per visualizzare i messaggi.

Per altre informazioni sull'uso degli strumenti di traccia software, vedere Survey of Software Tracing Tools.For more information about how to use the software tracing tools, see Survey of Software Tracing Tools.

Visualizzazione del log di traccia UMDF

Il file di log UMDF si trova in %ProgramData%*\\Microsoft\\WDF.

È possibile visualizzare il file di log UMDF usando TraceView o Tracelog. Entrambi gli strumenti richiedono file TMF (Trace Message Format) che formattano i messaggi del log di traccia. I file TMF sono disponibili in WDK, nella sottodirectory \tools\tracing. In TraceView, UMDF viene visualizzato come provider denominato con il nome "Traccia UMDF-Framework" o "Traccia framework", a seconda della versione di UMDF.

WDF Verifier consente di inviare messaggi di traccia sia al log di traccia UMDF che al debugger del kernel. Non è consigliabile inviare messaggi di traccia al debugger del kernel usando l'opzione -kd in Tracelog, perché Tracelog può interrompere la registrazione delle tracce all'interno di UMDF.

È anche possibile usare l'estensione del debugger !wmitrace per visualizzare i messaggi di traccia nel debugger:

In WinDbg collegarsi all'istanza di WUDFHost che ospita il driver. Per altre informazioni, vedere How to Enable Debugging of a UMDF Driver.For more information, see How to Enable Debugging of a UMDF Driver.
Se il driver usa la versione 1.11 o successiva e si usa il debugger del kernel da Windows 8 o versione successiva, è possibile ignorare questo passaggio. Se il driver usa una versione di UMDF precedente alla 1.11, usare !wmitrace.tmffile o !wmitrace.searchpath per specificare un file di messaggio di traccia specifico della piattaforma (con estensione tmf) o un percorso di un file con estensione tmf. I file con estensione tmf si trovano nelle sottodirectory specifiche della piattaforma in WDK.
Usare il comando !wmitrace.logdump per visualizzare il contenuto dei buffer di traccia:
```
!wmitrace.logdump WudfTrace
```

Controllo dei messaggi di traccia

È possibile controllare i messaggi di traccia UMDF con l'interfaccia utente fornita da WDF Verifier o modificando i valori del Registro di sistema. È consigliabile usare l'interfaccia WDF Verifier , se possibile, perché i valori del Registro di sistema potrebbero cambiare nelle versioni future di UMDF. Inoltre, non è consigliabile accedere a questi valori all'interno dei file INF o del codice del driver.

Attualmente, è possibile modificare i valori del Registro di sistema seguenti, che si trovano nella chiave del Registro di sistema HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF :

Il valore LogEnable controlla se UMDF crea un log di traccia per il driver. Se questo valore è impostato su 1, UMDF crea un log di traccia.
Il valore LogLevel controlla la quantità di informazioni contenute nei messaggi di traccia UMDF. Il valore predefinito per LogLevel è 3, che causa la visualizzazione dei messaggi di traccia UMDF con messaggi di errore e di avviso. Impostare questo valore su 7 per includere messaggi di errore e di avviso, oltre a messaggi informativi non di errore. Impostarlo su 15 per includere tutte le informazioni di traccia che UMDF è in grado di fornire.
Il valore LogKd controlla se UMDF invia messaggi di traccia al debugger del kernel. Se LogKd è impostato su 1, UMDF invia i messaggi di traccia al debugger del kernel.
Il valore LogFlushPeriodSeconds specifica la frequenza, in secondi, dei messaggi di traccia scritti nel log di traccia.
Il valore LogMinidumpType contiene flag che specificano il tipo di informazioni che un file mini-dump, se prodotto, conterrà. Per altre informazioni su questi flag, vedere l'enumerazione MINIDUMP_TYPE .

È possibile trovare altri valori del Registro di sistema nella chiave del Registro di sistema HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\WUDF . Non è consigliabile modificare tali valori.

Condividi tramite