Condividi tramite

IfR (Inflight Trace Recorder) per la registrazione delle tracce

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 registrazione 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

Prima di tutto, seguire i passaggi in Aggiunta della tracciatura software WPP a un driver Windows.

Quindi, nella pagina delle proprietà del Progetto, in Proprietà di configurazione-Traccia WPP-Funzione e Opzioni macro-Abilita> registratore traccia di volo selezionare Sì.

Infine, solo per UMDF, è presente un passaggio aggiuntivo: in WPP Tracing-Function> and Macro Options-Preprocessor> Definitions (Opzioni di traccia WPP) aggiungereWPP_MACRO_USE_KM_VERSION_FOR_UM=1 .

Come abilitare Inflight Trace Recorder dalla riga di comando

Se si modifica il file .vcxproj manualmente, 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 del Registratore di tracce in volo

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

Utilizzare le seguenti voci del Registro di sistema:

LogPages: REG_DWORD

Impostare il numero di pagine per archiviare il log predefinito. Il valore predefinito è uno.

VerboseOn: REG_DWORD

L'impostazione predefinita di zero fa sì che ifR registri errori, avvisi ed eventi informativi. Impostare su uno per aggiungere un 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 possono quindi essere visualizzate 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.

Esempi

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 in Aggiunta di Traccia software WPP a un driver Windows. Per 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 un proprio buffer. È possibile quindi utilizzare il debugger per eseguire il dump solo del log relativo a un dispositivo figlio specifico.

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

Il driver deve inoltre definire una nuova macro di tracciamento che utilizza l'handle di log come primo parametro. Per un esempio, vedere il Toaster Sample Driver.

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 del driver per ogni handle di log che deve usare timestamp. Per un esempio di codice, vedere WppRecorderLogCreate.

Annotazioni

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.

  • Last updated on