16.8.4 Setting Up Driver-specific, User-visible Error Logging

Any NT driver that logs driver-defined I/O errors, as described in Section 16.6, can set itself up as an error-logging component of the system, which is also called an event-logging component within the Win32 subsystem programming environment.

Such a driver must create a new subkey in the registry under the key CurrentControlSet\Services\EventLog\System in order to have its driver-supplied message file made available to the Win32 event viewer or to any (subsystem-specific) application that reads the system error log file and displays Win32 events to users or system administrators. Note that a comparable application within another protected subsystem might use another, subsystem-specific term for Win32 "events."

Such a driver should name its new subkey with a unique DriverName that is identical to the name of the driver's executable. The driver-created subkey must include a value entry for the driver-supplied message file, which can have any unique name chosen by the driver writer. The value entry of a driver-supplied message file is a full pathname for the file.

Any NT device driver writer who sets up the value entries for a new DriverName subkey of the \EventLog\System key also should weigh the tradeoffs of supplying information that is truly useful to the customer who buys the device against the resources that setting up a Win32 event-logging component consumes.

An NT driver writer who sets up an event-logging driver should make its messages meaningful to the system administrator or end user who will use the Win32 event viewer (or some other application) to diagnose problems that have occurred while the system is running. The system error-logging mechanisms are not intended to be, nor should they be used for, debugging under-development NT drivers. Instead, they should provide useful information to an NT driver writer's retail customers.

For more information about the Windows NT event-logging mechanisms and how to set up Source, which corresponds to the NT DriverName, subkeys and message files, see the documentation provided with the Win32 SDK.