Chris Cant - Writing Windows WDM Device Drivers

boolean Active;

[WmiDataId(1), read, write]

boolean Enable;

};

A WDM driver can use WMI mechanisms to publish information, permit configuration of its device, and supply notifications of events. It should continue to report standard Windows 2000 events, as many system administrators will still be looking for this event information. However, WMI is the way forward, as it allows information to be made available on non-W2000 systems, and it allows remote inspection and control of the device.

WDM drivers, NT style drivers, and miniport drivers/minidriver can support WMI. In the latter case, you must fit in with the WMI reporting mechanism supported by the class driver. For example, a SCSI miniport must set the WmiDataProvider BOOLEAN in the PORT_CONFIGURATION_INFORMATION structure and handle SRB_FUNCTION_WMI requests.

The Wdm3 driver defines two custom WMI blocks. Listing 12.2 shows how the Wdm3Information data block and the Wdm3Event event block are defined in Wdm3.mof. The identifying GUID for each block is defined in the GUIDs.h header: WDM3_WMI_GUID and WDM3_WMI_EVENT_GUID.

The Wdm3Information data block contains two 32-bit unsigned properties followed by a counted wide string property. The first real property, BufferLen, is the length of the shared memory buffer. BufferFirstWord is the first 32 bits of the shared memory buffer, or zero if the buffer is not long enough. Finally, SymbolicLinkName is the symbolic link name of the Wdm3 device interface.

The Wdm3Inforination data block has a definition for a PowerDown function. I found that this did not compile, so I commented it out.

The Wdm3Event WMI event block must be derived from the standard WMI Event class. It simply defines a Message property.

Listing 12.2 Wdm3Iinformation and Wdm3Event block

/* WMI data block: Information about Wdm3 device Wdm3Information, identified by WDM3_WMI_GUID */

[WMI, Dynamic, Provider("WMIProv"), Description("Wdm3 information"), guid("{C0CF0643-5F6E-11d2-B677-0OC0DFE4C1F3}"), locale("MS\\0x409")]

class Wdm3Information {

[key, read]

string InstanceName;

[read]

boolean Active;

[WmiDataId(1), read, Description("Shared memory buffer length") ]

uint32 BufferLen;

[WmiDataId(2), read, Description("First ULONG of shared memory buffer") ]

uint32 BufferFirstWord;

[WmiDataId(3), read, Description("Symbolic link name") ]

string SymbolicLinkName;

/* Doesn't compile

[Implemented]

void PowerDown(); */

};

/* WMI event block: Wdm3 device event Wdm3Event, identified by WDM3_WMI_EVENT_GUID */

[WMI, Dynamic, Provider("WMIProv"), guid("{C0CF0644-5F6E-11d2-B677-00C0DFE4C1F3}"), locale("MS\\0x409"), Description("Wdm3 event message")]

class Wdm3Event : WMIEvent {

[key, read]

string InstanceName;

[read]

boolean Active;

[WmiDataId(1), read, Description("Message")]

string Message;

};

This example MOF file shows how a driver defines static instance names when it registers a WMI block. Alternatively, if necessary, the driver can define dynamic instance names if the instances change frequently at run time. Handling dynamic instance names is harder and is not a common requirement, so it is not discussed here.

Quite a few changes must be made to a project to support WMI.

1. All the WMI functions, including support for the Wdm3SystemControl WMI IRP, are in Wmi.cpp. Include this file in the SOURCES list of files to compile in the SOURCES file.

2. I found that this line had to be included in SOURCES to ensure that the WMI library file was found.

TARGETLIBS=C:\NTDDK\LIBFRE\I386\WmiLib.Lib

3. The prebuild steps had to be altered to persuade build to run the mofcomp tool to compile Wdm3.mof. The SOURCES file NTTARGETFILE0 macro is changed to ensure that makefile.inc runs the following command. The complete makefile.inc is given in the next chapter.

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

This command line compiles MOF source file Wdm3.mof into the binary MOF Wdm3.bmf file. The options to mofcomp ensure that the source code is checked for WMI compatibility and that the output goes in the correct file.

4. The main resource file Wdm3.rc must now include the binary MOF file Wdm3.bmf. The following line in the resource script identifies the data using the name MofResource.

MOFRESOURCE MOFDATA MOVEABLE PURE "Wdm3.bmf"

5. The main header in Wdm3.h had to use standard headers wmilib.h and wmistr.h. It also included wdmguid.h to get the definition of the standard GUID, GUID_POWER_DEVICE_ENABLE.

6. The device extension has these extra fields added.

WMILIB_CONTEXT WmiLibInfo; // WMI Context

BOOLEAN IdlePowerDownEnable; // Enable power down option

BOOLEAN WMIEventEnabled; // Enable WMI events

WmiLibInfo is used to pass the Wdm3 WMI GUIDs and various callbacks, as described later.

IdlePowerDownEnable implements the MSPower_DeviceEnable WMI data block. If IdlePowerDownEnable is TRUE, the driver can power down when it is idle.

Finally, WMIEventEnabled is used to enable WMI event reporting.

7. The main WMI code needs to refer to the driver registry path that was passed to DriverEntry . Therefore, DriverEntry saves a copy in its Wdm3RegistryPath global variable.

// Save a copy of our RegistryPath for WMI

Wdm3RegistryPath.MaximumLength = RegistryPath->MaximumLength;

Wdm3RegistryPath.Length = 0;

Wdm3RegistryPath.Buffer = (PWSTR)ExAllocatePool(PagedPool, Wdm3RegistryPath.MaximumLength);

if (Wdm3RegistryPath.Buffer == NULL) return STATUS_INSUFFICIENT_RESOURCES;

RtlCopyUnicodeString(&Wdm3RegistryPath, RegistryPath);

The driver unload routine Wdm3Unload deletes the Wdm3RegistryPath buffer.

You must register as a WMI provider by calling IoWmiRegistrationControl with a WMIREG_ACTION_REGISTER command for each device when it is ready to handle WMI IRPs. The Wdm3 driver makes this call in its RegisterWmi routine. RegisterWmi is called at the end of Wdm3AddDevice . The corresponding DeregisterWmi routine deregisters the WMI support by calling IoWmiRegistrationControl with the WMIREG_ACTION_DEREGISTER command. DeregisterWmi is called when the device is removed.

Listing 12.3 shows the RegisterWmi and DeregisterWMI routines. RegisterWmi also sets up the WmiLibInfo structure in the device extension, ready for processing by the System Control WMI IRP. Table 12.1 shows the WmiLibInfo WMILIB_CONTEXT structure fields.

WmiLibInfo first contains the list of WMI block GUIDs that are handled by this driver. Wdm3GuidList is an array of these WMIGUIDREGINFO structures. Each specifies the GUID pointer, a count of instances, and optionally some flags. There is only one instance of each WMI block for this device. No flags are specified, as the appropriate flags are used later in the call to QueryWmiRegInfo .