IfR (Inflight Trace Recorder) per la registrazione delle tracce

Articolo
02/07/2024

Inflight Trace Recorder (IFR) è una funzionalità di traccia che consente a un provider di traccia, ad esempio un driver in modalità kernel o un driver UMDF, di creare un set di buffer circolari in memoria in cui vengono mantenuti i messaggi di log più recenti. I messaggi di log possono essere visualizzati usando un debugger.

IFR è basato sulla traccia software WPP. Il vantaggio principale di IFR su WPP è che è attivato automaticamente e non è necessario avviare le sessioni di traccia in anticipo.

Si applica a:

Sistema operativo minimo: Windows 8 per sviluppatori di driver KMDF e WDM
Sistema operativo minimo: Windows 10 per sviluppatori di driver UMDF (2.15)

Come abilitare Inflight Trace Recorder in Visual Studio

Per prima cosa, seguire la procedura descritta in Aggiunta di traccia software WPP a un driver Windows.

Nella pagina delle proprietà Project, in Proprietà di configurazione-WPP> Tracing-Function> e Macro Options-Enable> Inflight Trace Recorder selezionare Sì.

Infine, solo per UMDF, è presente un passaggio aggiuntivo: in WPP Tracing-Function> e Macro Options-Preprocessor Definitions (Definizioni del preprocessore> WPP) aggiungere WPP_MACRO_USE_KM_VERSION_FOR_UM=1.

Come abilitare Inflight Trace Recorder dalla riga di comando

Se si modifica manualmente il file di .vcxproj, impostare le voci seguenti:

Per un driver KMDF o WDM:

    <ClCompile Include=...>
        <WppEnabled>true</WppEnabled>
        <WppKernelMode>true</WppKernelMode>
        <WppRecorderEnabled>true</WppRecorderEnabled>
        ...
    </ClCompile>

Per un driver UMDF:

    <ClCompile Include=...>
        <WppEnabled>true</WppEnabled>
        <WppRecorderEnabled>true</WppRecorderEnabled>
        <WppPreprocessorDefinitions>WPP_MACRO_USE_KM_VERSION_FOR_UM=1</WppPreprocessorDefinitions>
        ...
    </ClCompile>

Come configurare i parametri di Inflight Trace Recorder

È possibile configurare l'IFR impostando le voci facoltative del Registro di sistema seguenti nella chiave del parametro del driver.

Usare le voci del Registro di sistema seguenti:

LogPages: REG_DWORD

Impostare sul numero di pagine in cui archiviare il log predefinito. Il valore predefinito è uno.

VerboseOn: REG_DWORD

L'impostazione predefinita di zero causa la registrazione degli errori, degli avvisi e degli eventi informativi dell'IFR. Impostare su uno per aggiungere l'output dettagliato al log.

WppRecorder_UseTimeStamp: REG_DWORD (disponibile a partire da WDK build 22557)

I driver impostano questa voce su uno per aggiungere timestamp alle voci di log che sono quindi visualizzabili usando !rcdrkd.rcdrlogdump o !wdfkd.wdflogdump.

WppRecorder_PreciseTimeStamp: REG_DWORD (disponibile a partire da WDK build 22557)

Se si desiderano timestamp più precisi, oltre a WppRecorder_UseTimeStamp, aggiungere WppRecorder_PreciseTimeStamp usando la stessa sintassi illustrata in precedenza.

Esempio

Negli esempi seguenti aggiungere le righe tra i commenti iniziale e finale per impostare il numero di pagine di log su due e attivare i timestamp.

Per un driver in modalità kernel:

[IfrSample_Service_Inst] 
DisplayName    = %IfrSample.SvcDesc%
ServiceType    = 1               ; SERVICE_KERNEL_DRIVER
StartType      = 3               ; SERVICE_DEMAND_START
ErrorControl   = 1               ; SERVICE_ERROR_NORMAL
ServiceBinary  = %12%\IfrSample.sys
; =============== START
AddReg = IfrSample_Service_Inst.AddReg
 
[IfrSample_Service_Inst.AddReg]
HKR, "Parameters", "LogPages", %REG_DWORD%, 2
HKR, "Parameters", "WppRecorder_UseTimeStamp", %REG_DWORD%, 1
; =============== END

[Strings]
REG_DWORD = 0x00010001

Per un driver UMDF:

[IfrSampleUm_Install] 
UmdfLibraryVersion=$UMDFVERSION$
ServiceBinary=%13%\IfrSampleUm.dll
; =============== START
AddReg=IfrSampleUm_Install.AddReg
 
[IfrSampleUm_Install.AddReg]
HKR, "Parameters", "LogPages", %REG_DWORD%, 2
HKR, "Parameters", "WppRecorder_UseTimeStamp", %REG_DWORD%, 1
; =============== END

Come inviare messaggi di traccia al log predefinito

Seguire le istruzioni riportate in Aggiunta di traccia software WPP a un driver Windows. Ad esempio:

In DriverEntry chiamare WPP_INIT_TRACING(DriverObject, RegistryPath).
In EvtDriverUnload chiamare WPP_CLEANUP(WdfDriverWdmGetDriverObject(Driver)).

Ora il driver è libero di chiamare la funzione di traccia in base alle esigenze. ad esempio TraceEvents(TRACE_LEVEL_ERROR, DBG_INIT, "WdfDriverCreate failed, %!STATUS!", ntStatus);

Per altre info, vedi WPP_INIT_TRACING e WPP_CLEANUP.

Come inviare messaggi di traccia a un log personalizzato

Questo vale solo per i driver in modalità kernel (KMDF o WDM).

Per la maggior parte dei driver, il singolo log predefinito è sufficiente. In alcuni scenari, tuttavia, è utile disporre di buffer di log separati per entità distinte.

Ad esempio, quando si scrive un driver del bus, è possibile che ogni dispositivo figlio abbia il proprio buffer. È quindi possibile usare il debugger per eseguire il dump solo del log per un dispositivo figlio specifico.

Per configurare i log personalizzati, il driver deve includere <WppRecorder.h>. Chiamare quindi le API seguenti:

WppRecorderLogCreate per creare più buffer di log
WppRecorderLogDelete prima di chiamare WPP_CLEANUP.
WppRecorderLogSetIdentifier per impostare un identificatore di stringa per un determinato log di registrazione (facoltativo)
WppRecorderConfigure per disabilitare il log predefinito (facoltativo)

Il driver deve anche definire una nuova macro di traccia che accetta l'handle di log come primo parametro. Per un esempio, vedere il driver di esempio tostapane.

Come aggiungere informazioni sul timestamp a un log personalizzato

Se il driver chiama WppRecorderLogCreate per creare handle di log aggiuntivi, è possibile abilitare timestamp per alcuni handle di log, ma non per altri.

A tale scopo, è necessario aggiungere una singola riga al codice driver per ogni handle di log che deve usare timestamp. Per un esempio di codice, vedere WppRecorderLogCreate.

Nota

Questa funzionalità è disponibile a partire da WDK build 22557. Per informazioni sulla destinazione di una versione specifica, vedi Compilazione di driver per versioni diverse di Windows.

Come visualizzare i messaggi di traccia nel debugger

Per i driver KMDF e UMDF, usare !wdfkd.wdflogdump come di consueto. Verrà stampato sia il log IFR del framework che il log IFR del driver.

Per i driver WDM, usare !rcdrkd.rcdrloglist e !rcdrkd.rcdrlogdump.

Condividi tramite