Windows Diagnostics Infrastructure

The Windows Diagnostics Infrastructure (WDI) is new to Windows Vista. Though it is called an infrastructure, it is actually built over another feature, Event Tracing for Windows (ETW). In its use of interfaces, formally defined even if undocumented, it does nothing that could not be coded by non-Microsoft programmers using the kernel-mode ETW functions or the corresponding user-mode functions in ADVAPI32 or NTDLL. Yet much WDI functionality is coded in the kernel itself, which is not something that non-Microsoft programmers could arrange for an alternative package of diagnostics tools.

The WDI is almost entirely undocumented. An MSDN Library CD dated January 2007 (and thus contemporaneous with the WDI’s appearance in Windows Vista) has just three mentions of the thing. Two are nothing but talk of other features that are said to be “extensions” of the WDI. The third talks of WDI “context events” and “diagnostic events” and again has the feel of expecting the reader to know about the WDI from elsewhere. I have written before that much of the programming details that Microsoft eventually publishes in the MSDN Library and in various development kits is written primarily for Microsoft’s own programmers but that some information that Microsoft never really intended to disclose slips through the editing when the material is published for others. The WDI may be one of those features. Its existence is documented in public resources, albeit scarcely, but details, whether for programming or usage, are non-existent.

Though the kernel exports no functions specifically concerned with WDI, the undocumented ETW functions EtwWriteStartScenario and EtwWriteEndScenario are variations of the documented EtwWrite to support WDI and one case of the undocumented NtTraceControl function certainly is specific to WDI. Moreover, thirty functions that are very specific to WDI are exported by the user-mode DLL, named WDI.DLL, that implements the “Diagnostic Service Host” and “Diagnostic System Host” services. None of these are even declared in any header from the Windows SDK or Windows Driver Kit (WDK). This would not matter if WDI.DLL is just the core module in a suite of diagnostic tools that Microsoft supplies with Windows but which doesn’t have any system interactions that aren’t available to clever non-Microsoft programmers writing alternative diagnostic software. Those WDI.DLL functions would then just be internal to those tools. If some enterprising programmers wanted to write their own tools and try selling them in what is surely by now a thin market for low-level utility software, then they too would likely have DLLs and exported functions, and nobody would think that the interfaces between their components must be published. But WDI is not just one of potentially any number of diagnostic suites: it has that special support from the kernel. Either those WDI functions should be documented so that non-Microsoft programmers can write WDI extensions or the kernel facilities that WDI depends on should all be documented so that non-Microsoft programmers can write whole diagnostic suites that are equally capable (and might even be superior).

Neither are things any better for users, whether of ordinary facility with Windows or advanced. The WDI is highly configurable, but the relevant registry settings seem also to be completely undocumented, as if Microsoft means that configuration should not be in the hands of customers. Fine perhaps, but since the point to WDI is to collect, store and even transmit information about what the computer has been doing, at least as seen by Windows, some might think that the process would better be transparent. Though I don’t mean to suggest that WDI collects information that anyone should worry about for their privacy, I do note that governments have established pretty well by now that their only means for verifying what software collects is to trust the manufacturer’s lawyers. This article (including its attendant pages, presently in preparation) exists in part to demonstrate what detail is obtainable from sufficiently expert examination of what software actually does when collecting data.

ACCOMPANYING PAGES ON HOLD

Architecture

Central to the WDI is the notion of scenarios for logging events. A Scenario Event Mapper (SEM) in the kernel loads the defined scenarios from the registry fairly early during the system’s initialisation. To the SEM, a scenario comprises:

To get a scenario started, an event provider, which need not be one of the context providers, writes the start event using the special function EtwWriteStartScenario in kernel mode or EventWriteStartScenario in user mode. The SEM then enables the context providers so that all their events are written to a special WDI logger (see below). This logging continues until one of two things happens. An event provider, again not necessarily one of the context providers, may write one of the end events using the special function EtwWriteEndScenario or EventWriteEndScenario, again in kernel mode and user mode respectively. Alternatively, the scenario can be stopped by the SEM on a timeout.

The SEM has two dedicated autologger sessions, named DiagLog and WdiContextLog. The main difference between the two, as loggers, is that DiagLog delivers events direct to consumers (as a so-called real-time logger) but WdiContextLog writes through a file.

Events written to WdiContextLog are much more readily accessible for inspection by the curious. Events written to DiagLog are consumed by the Diagnostic Policy Service. This is implemented in DPS.DLL, running in a SVCHOST process using the SYSTEM account. It creates an ALPC port which WDI.DLL, executing in other processes, can read from to learn of diagnostic messages.