title | description | ms.date |
---|---|---|
Inflight Trace Recorder (IFR) for Logging Traces |
Inflight Trace Recorder (IFR) allows a trace provider, such as a kernel-mode driver, to record trace logs and store WPP log messages in buffers. |
03/30/2020 |
Inflight Trace Recorder (IFR) is a tracing feature that allows a trace provider, such as a kernel-mode driver or a UMDF driver, to create a set of in-memory circular buffers where the latest log messages are preserved. The log messages can be viewed using a debugger.
IFR is built on top of WPP software tracing. The primary benefit of IFR over WPP is that it is turned on automatically and you do not need to start trace sessions in advance.
Applies to:
- Minimum OS: Windows 8 for KMDF and WDM driver developers
- Minimum OS: Windows 10 for UMDF (2.15) driver developers
First, follow the steps in Adding WPP Software Tracing to a Windows Driver.
Next, in the Project property page, under Configuration Properties->WPP Tracing->Function and Macro Options->Enable Inflight Trace Recorder, select Yes.
Finally, for UMDF only, there is one additional step: under WPP Tracing->Function and Macro Options->Preprocessor Definitions, add WPP_MACRO_USE_KM_VERSION_FOR_UM=1
.
If you edit the .vcxproj file manually, set the following entries:
For a KMDF or WDM driver:
<ClCompile Include=...>
<WppEnabled>true</WppEnabled>
<WppKernelMode>true</WppKernelMode>
<WppRecorderEnabled>true</WppRecorderEnabled>
...
</ClCompile>
For a UMDF driver:
<ClCompile Include=...>
<WppEnabled>true</WppEnabled>
<WppRecorderEnabled>true</WppRecorderEnabled>
<WppPreprocessorDefinitions>WPP_MACRO_USE_KM_VERSION_FOR_UM=1</WppPreprocessorDefinitions>
...
</ClCompile>
You can configure the IFR by setting the following optional registry entries under the driver's Parameter key.
Use the following registry entries:
LogPages: REG_DWORD
Set to the number of pages to store the default log. The default is one.
VerboseOn: REG_DWORD
The default setting of zero causes the IFR to log errors, warnings, and informational events. Set to one to add verbose output to the log.
WppRecorder_UseTimeStamp: REG_DWORD (available starting in WDK build 22557)
Drivers set this entry to one to add timestamps to log entries that are then viewable using !rcdrkd.rcdrlogdump or !wdfkd.wdflogdump.
WppRecorder_PreciseTimeStamp: REG_DWORD (available starting in WDK build 22557)
If you would like more precise timestamps, in addition to WppRecorder_UseTimeStamp, add WppRecorder_PreciseTimeStamp using the same syntax shown above.
In the following examples, add the lines between the start and end comments to set the number of log pages to two and turn on timestamps.
For a kernel-mode driver:
[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
For a UMDF driver:
[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
Follow the instructions in Adding WPP Software Tracing to a Windows Driver. For example:
- In DriverEntry, call
WPP_INIT_TRACING(DriverObject, RegistryPath)
. - In EvtDriverUnload, call
WPP_CLEANUP(WdfDriverWdmGetDriverObject(Driver))
.
Now the driver is free to call the trace function as needed. For example: TraceEvents(TRACE_LEVEL_ERROR, DBG_INIT, "WdfDriverCreate failed, %!STATUS!", ntStatus);
For more info, see WPP_INIT_TRACING and WPP_CLEANUP.
This only applies to kernel-mode drivers (KMDF or WDM).
For the majority of drivers, the single default log is good enough. However, in some scenarios, it's helpful to have separate log buffers for distinct entities.
For example, when writing a bus driver, you might want each child device to have its own buffer. Then you can use the debugger to dump only the log for a specific child device.
To set up custom logs, the driver must include <WppRecorder.h>
. Then call the following APIs:
- WppRecorderLogCreate to create more than one log buffer
- WppRecorderLogDelete before calling WPP_CLEANUP.
- WppRecorderLogSetIdentifier to set a string identifier for a given recorder log (optional)
- WppRecorderConfigure to disable the default log (optional)
The driver also needs to define a new trace macro that takes the log handle as the first parameter. For an example, see the Toaster Sample Driver.
If your driver calls WppRecorderLogCreate to create additional log handles, it is possible to enable timestamps for some log handles but not others.
To do this you need to add a single line to the driver code for each log handle that should use timestamps. For a code example, see WppRecorderLogCreate.
Note
This functionality is available starting in WDK build 22557. For info on targeting a specific release, see Building Drivers for Different Versions of Windows.
For KMDF and UMDF drivers, use !wdfkd.wdflogdump as usual. It will print out both the framework IFR log and the driver IFR log.
For WDM drivers, use !rcdrkd.rcdrloglist and !rcdrkd.rcdrlogdump.