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