Share via

Customizing the KMDF log for your driver

  • Article

Yesterday
I talked about the KMDF log. The KMDF log is a great tool to debug why a DDI call has failed or diagnose the
cause of a bugcheck in your driver. You can customize different attributes of
the log so that you can better debug your driver. The customizations available to
you are:

  • The length of the log
  • The format of the output
  • Verbose output

When a customization requires you to add or modify a registry value, the value will
always be under HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\<your driver>\Parameters\WDF.
WHDC has a great KMDF tip
which describes all of these options as well.

Length of the log

Every KMDF driver has a log associated with it (you cannot turn it off). The
default size of the log is one page (as defined by PAGE_SIZE; 4K on x86 and x64 systems, 8K on IA64). Since
the log is measured by the size of a memory page it is not possible to say exactly how
many entries fit in the log, but one page usually holds around 100 entries. You
can increase the size of the log by specifying the number of pages it should be.
The limit is currently 10 pages. You should be conservative in the number of
pages you specify since these pages will not be available for general use by applications,
other drivers, or the OS.

You specify the number of pages with the following value:

 
    LogPages : REG_DWORD

Format of the log

You can modify the format of the log, just like you can with a WPP log. The
format specifiers are intentionally the same so that you can transition from one
to the other. The DDK has a good listing of the specifiers
here
(the article is titled "Trace Message Prefix"). You can
set the formatting in two ways. First, you can set the environment variable
TRACE_FORMAT_PREFIX. If you use a constant format this is the best way
to go since you just set it once and then leave it alone. Second, you can also use the
!wdfsettraceprefix comand in wdfkd.dll.

The default formatting changed in KMDF v1.5. The big difference between the
two is that for v1.5 the calling function is in the entry, while pre v1.5
the source file and line number are in the entry. The calling function is much more useful to
an external developer then the file and line number (which is only available internally)
which is why we made the change. (If you use the v1.5 wdfkd.ll with an earlier
version of KMDF, you will get the v1.5 formatting.)

 
KMDF v1.5:          "%7!u!: %!FUNC! - "
KMDF v1.0 and v1.1: "%7!u!: %2!-20.20s! -- "

Verbose output

What you see in the log is not everything that KMDF can potentially log, only
the most relevant entries are written to the log. Sometimes this is not enough
information though. You can tell KMDF to log everything by turning on
verbose logging, but this comes with a caveat. You will get a lot more information,
but you may lose the entries you really need since the log might overflow with the
verbose entries. I would recommend increasing the log size if you are going to enable
verbose logging. When you enable the KMDF verifier on your driver,
verbose logging is also enabled by default.

You specify verbose logging with the following registry value.
A value of 0x0 (the default) turns verbose logging off, while a non zero value
will enable verbose logging.

 
    VerboseOn : REG_DWORD