Chris Cant - Writing Windows WDM Device Drivers

NTTARGETFILE0=prebuiId

As described in Chapter 4, this invokes nmake on the makefile.inc makefile before the main compile. The prebuild step compiles the WMI MOF file and the event message definition file, as shown in Listing 13.3. The mc command is run, if necessary, using the –c option to set the "customer" bit and the –v option for verbose output.

Listing 13.3 New makefile.inc

prebuild: Wdm3Msg.h Wdm3.bmf

Wdm3.bmf: Wdm3.mof

mofcomp –B:Wdm3.bmf –WMI Wdm3.mof

Wdm3Msg.rc Wdm3Msg.h: Wdm3Msg.mc

mc –v –c Wdm3Msg.mc

PostBuildSteps: $(TARGET)

!if "$(DDKBUILDENV)"=="free"

rebase –B 0x10000 –X . $(TARGET)

!endif

copy $(TARGET) $(WINDIR)\system32\drivers

The final change to the build process is to make the main resource file, Wdm3.rc, include the message resource script, Wdm3Msg.rc. In Visual C++, select the View+Resource Includes… menu and add the following line to the "Read-only symbol directives" box.

#include "Wdm3Msg.rc"

In Windows 2000, I found that building the driver from a changed message definition file initially reported an error but then went on to compile successfully.

The final hurdle to overcome is registering your driver as an event source so that the event viewer knows where to find your message text resource. Two registry changes must be made.

First, the HKLM\System\CurrentControlSet\Services\EventLog\System key has an existing REG_MULTI_SZ value called Sources. Add the name of your driver's executable (without the extension) as a line in Sources.

In this same registry key, make a new subkey with this same driver name. In this subkey, add a REG_EXPAND_SZ value called EventMessageFile and set a REG_DWORD called TypesSupported with a value of 0x7. For Wdm3, set EventMessageFile to the following value.

%SystemRoot%\System32\IoLogMsg.dll;%SystemRoot%\System32\Drivers\Wdm3.sys

The Wdm3 installation INF file supposedly has the correct information to make these registry changes when a Wdm3 device is installed. Listing 13.4 shows the amendments made to the standard installation file. The AddService directive's last field specifies the name of the section containing the error logging registry values. There are optional fields to specify the log type (System, Security, or Application) and a log name.

The Wdm3.Service.EventLog section specifies the values for the EventMessageFile and TypesSupported values. The EventMessageFile entry is on one long line.

However, I found that this did not work completely in Windows 2000 Beta 3. "Wdm3" was correctly added to the Sources value and the HKLM\System\CurrentControlSet\Services\EventLog\System\Wdm3 key was correctly made, but no values were placed in the key.

It is simplest just to add these registry entries by hand. You will have to use RegEdt32 to use the required registry types.

Note: A revised version of installation file Wdm3\sys\Wdm3free.inf is available on the book's web site, www.phdcc.com/wdmbook. This updated version fixes the EventLog section problem.

For NT 3.51 and NT 4 drivers, you cannot use an INF installation file. Instead, you will have to amend your installation program to set up the registry entries. The example installation code, install.cpp (on the book's CD-ROM) shows how to do this job.

Listing 13.4 Wdm3free.inf installation file event logging sections

[Wdm3.Install.NT.Services]

AddService =

Wdm3, %SPSVCINST_ASSOCSERVICE%, Wdm3.Service, Wdm3.Service.EventLog

; …

[Wdm3.Service.EventLog]

HKR,,EventMessageFile,%FLG_ADDREG_TYPE_EXPAND_SZ%,

"%%SystemRoot%%\System32\IoLogMsg.dll;

%%SystemRoot%%\System32\drivers\Wdm3.sys"

HKR,,TypesSupported,%FLG_ADDREG_TYPE_DW0RD%,7

Listing 13.5 shows the routines that provide the event logging, InitializeEventLog , and LogEvent . Later, I shall describe the Wdm3EventMessage function that provides a simpler interface.

InitializeEventLog is simply used to store a pointer to the main DriverObject . It then calls LogEvent to send a WDM3_MSG_LOGGING_STARTED event. If all's well, this should be displayed in the Event Viewer with the corresponding description, "Event logging enabled for Wdm3 Driver".

LogEvent does the bulk of the work in logging an NT event. It may be called at DISPATCH_ LEVEL or lower. Its first task is to decide the size of the error log packet. It then calls IoAllocateErrorLogEntry to obtain a suitably sized packet. It then fills the packet and sends it off using IoWriteErrorLogEntry .

LogEvent has parameters for the message ID (from the list in Wdm3Msg.h) and optionally an IRP pointer. If the IRP pointer is given, various fields in the packet are filled in with details of the IRP. LogEvent can also accept DumpData and Strings as parameters, for insertion into the event packet.

The basic IO_ERR0R_L0G_PACKET structure contains one dump data ULONG, but no insertion strings. It is an extendible structure. Zero or more dump data ULONGs can be provided, followed immediately by any NULL terminated wide strings. This makes calculating and filling the packet size slightly involved. LogEvent saves each string length in a temporary array of integers called StringSizes. Note that the maximum packet size, ERROR_LOG_MAXIMUM_SIZE, is only 0x98 bytes, so do not try to pass large insertion strings.

Listing 13.5 InitializeEventLog and LogEvent routines

void InitializeEventLog(IN PDRIVER_OBJECT DriverObject) {

SavedDriverObject = DriverObject;

// Log a message saying that logging is started.

LogEvent(WDM3_MSG_LOGGING_STARTED, NULL, // IRP

NULL, 0, // dump data

NULL, 0); // strings

}

bool LogEvent(IN NTSTATUS ErrorCode, IN PIRP Irp, IN ULONG DumpData[], IN int DumpDataCount, IN PWSTR Strings[], IN int StringCount) {

if (SavedDriverObject==NULL) return false;

// Start working out size of complete event packet

int size = sizeof(IO_ERROR_LOG_PACKET);

// Add in dump data size.

// Less one as DumpData already has 1 ULONG in IO_ERROR_LOG_PACKET

if (DumpDataCount>0) size += sizeof(ULONG) * (DumpDataCount-1);

// Add in space needed for insertion strings (inc terminating NULLs)

int* StringSizes = NULL;

if (StringCount>0) {

StringSizes = (int*)ExAllocatePool(NonPagedPool, StringCount*sizeof(int));

if (StringSizes==NULL) return false;

// Remember each string size

for (int i=0; i

StringSizes[i] = (int)GetWideStringSize(Strings[i]);

size += StringSizes[i ];

}

}

if (size>ERROR_LOG_MAXIMUM_SIZE) // 0x98!

{

if (StringSizes!=NULL) ExFreePool(StringSizes);

return false;

}

// Try to allocate the packet

PIO_ERROR_LOG_PACKET Packet = (PIO_ERROR_LOG_PACKET)IoAllocateErrorLogEntry(SavedDriverObject, size);

if (Packet==NULL) {

if (StringSizes!=NULL) ExFreePool(StringSizes);