How to Use the KMDF Log

Viewing the KMDF Log While Debugging

To view the KMDF log during a debugging session:

1.	If you have not already done so, load the KMDF debugger extensions.
2.	Set the search path for the KMDF TMF file. The file is named WdfVersionNumber.tmf and is located at %wdk%\WDKVersionNumber\tools\tracing\Architecture. To set the search path, run the !wdftmffile debugger extension command followed by the path to the folder that contains the TMF files. The following example sets the search path for the TMF file for WDF version 1.5 from build 6000 of the WDK, for a computer running a 32-bit version of Windows:     !wdftmffile%wdk%\6000\tools\tracing\i386\wdf01005.tmf \ You can also set the search path by setting the TRACE_FORMAT_SEARCH_PATH environment variable. The !wdftmffile command takes precedence over the search path that is set by the environment variable.
3.	Display the contents of the log file in the Command window by running the !wdflogdump debugger extension command followed by the name of your driver. Do not include the .sys extension. For example, to dump the KMDF log for Osrusbfx2, run the following command:     !wdflogdump osrusbfx2 Figure 1 is a screenshot of a WinDbg Command window that shows a typical example of the output of !wdflogdump. Figure 1. KMDF log

You can save the contents of the KMDF log to a file by using the !wdflogsave command as follows:

    !wdflogsave [DriverName [FileName]]

Replace DriverName with the name of the driver. The name must not include the .sys extension. Replace FileName to specify a name for the log file. Do not include the .etl extension. If you omit FileName, the log is written to DriverName.etl.

Top of page

Getting Log Information After a Bug Check

After the system bug checks, you can sometimes use the !wdfcrashdump command to display KMDF log information. The log information is available only if KMDF can determine that your driver caused the bug check or if you have set the ForceLogsInMiniDump registry value for the driver. If a debugger is attached when the bug check occurs, you can use the !wdfcrashdump debugger extension to view the KMDF log information immediately. Otherwise, view the information by loading the memory dump file.

KMDF can determine whether a particular driver caused the following bug check codes:

To include KMDF log information in the system's small memory dump, use RegEdit to modify the driver settings, which are defined as values of the driver's Parameters\Wdf subkey. The driver's key is named for the driver, and the full path to the Wdf subkey is:

    HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services
    \DriverName\Parameters\Wdf

To cause the system to include the KMDF log information in the small memory dump, set the Wdf subkey's ForceLogsInMiniDump value to a nonzero value.

Controlling the Contents of the KMDF Log

You can control several aspects of the KMDF log:

Log Size

You can specify the number of memory pages that the framework assigns to the logger by setting the LogPages value of the driver's Parameters\Wdf registry subkey. You can set LogPages to a value ranging from 1 to 10, which indicates the number of pages of memory that are assigned to the logger. If no value is assigned to LogPages, KMDF uses a default value of one page.

Note: The LogPages value is a request, not a requirement. The size of a small crash dump file is limited, so the operating system might omit the KMDF log data if the log is too large.

Information Level

You can change the amount of information written to the KMDF log file by setting the VerboseOn value in the driver's Parameters\Wdf registry subkey. A nonzero value for VerboseOn causes the framework to record detailed, developer-level information in the log. You should set VerboseOn only while developing and debugging your driver because doing so can degrade performance.

Prefix String

Each line in the KMDF log is preceded by a string that is called the trace message prefix. The trace logger prepends this prefix to each message that is written to the log. By default, the prefix includes a standard set of data elements, but you can change the default elements to suit your particular requirements.

The contents of the prefix are specified by a format string that is somewhat similar to the format string that is used in printf statements. The format of the trace prefix string is defined by the Windows tracing tools and is described in "Trace Message Prefix" in the Driver Development Tools section of the Windows Driver Kit (WDK).

You can change the prefix string for a KMDF driver by setting the TRACE_FORMAT_PREFIX environment variable or by using the !wdfsettraceprefix debugger extension command. Setting TRACE_FORMAT_PREFIX allows you to control the format of the standard information captured by ETW, such as line, function name, module name, and so on. The contents of the prefix are specified by a format string that is similar to the one in printf statements. For details on how to construct a format string, see "Trace Message Prefix" in the WDK.

You can change the prefix string for a KMDF driver by setting the TRACE_FORMAT_PREFIX environment variable or by using the !wdfsettraceprefix debugger extension command.

To set the environment variable, use a command like the following:

Set TRACE_FORMAT_PREFIX=%2!s!: %!FUNC!: %8!04x!.%3!04x!: %4!s!:

This command sets the trace message prefix to the following:

SourceFile_LineNumber: FunctionName: ProcessID.ThreadID: SystemTime 

To set the format string during debugging, use the !wdfsettraceprefix debugger extension:

    !wdfkd.wdfsettraceprefix PrefixString

The following example sets the same string as the preceding environment variable:

    !wdfkd.wdfsettraceprefix %2!s!: %!FUNC!: %8!04x!.%3!04x!: %4!s!:

What should you do?

For more information:

Architecture of the Windows Driver Foundation

Debugging Tools for Windows

Kernel-Mode Driver Framework (KMDF)

In the KMDF Documentation, see:
Design Guide
    Debugging a Framework-based Driver

Windows Driver Kit
In the Driver Development Tools section, see:
    Trace Message Prefix

Top of page