Chris Cant - Writing Windows WDM Device Drivers

The NT_SUCCESS macro is used to test whether the IoCreateDevice kernel call has completed. Do not forget to check that all calls to the kernel succeed. The NT_ERROR macro is not equivalent to !NT_SUCCESS. It is better to use !NT_SUCCESS, as it catches warning status values as well as errors.

Listing 5.2 Wdm1 Pnp.cpp Create and Delete device code

NTSTATUS Wdm1AddDevice(IN PDRIVER_OBJECT DriverObject, IN PDEVICE_OBJECT pdo) {

…

NTSTATUS status;

PDEVICE_OBJECT fdo;

// Create our Functional Device Object in fdo

status = IoCreateDevice(DriverObject, sizeof(WDM1_DEVICE_EXTENSION),

NULL, // No Name

FILE_DEVICE_UNKNOWN, 0,

FALSE, // Not exclusive

&fdo);

if (!NT_SUCCESS(status)) return status;

// Remember fdo in our device extension

PWDM1_DEVICE_EXTENSION dx = (PWDM1_DEVICE_EXTENSION)fdo->DeviceExtension;

dx->fdo = fdo;

…

// Attach to the driver stack below us

dx->NextStackDevice = IoAttachDeviceToDeviceStack{fdo,pdo);

// Set fdo flags appropriately

fdo->Flags &= ~DO_DEVICE_INITIALIZING;

fdo->Flags |= DO_BUFFERED_IO;

…

}

NTSTATUS Wdm1Pnp( IN PDEVICE_OBJECT fdo, IN PIRP Irp) {

…

// Device removed

if (MinorFunction==IRP_MN_REMOVE_DEVICE) {

// unattach from stack if (dx->NextStackDevice)

IoDetachDevice(dx->NextStackDevice);

// delete our fdo

IoDeleteDevice(fdo);

}

return status;

}

Wdm1AddDevice is called with two parameters, a pointer to the driver object and a pointer to a device object called the Physical Device Object (PDO).

Wdm1AddDevice calls IoCreateDevice to create the Wdm1 device using the parameters described in Table 5.2. The DeviceName parameter can be used to give a name to the device. However, as Wdm1 uses device interfaces, no name needs to be given, so NULL is passed here. Wdm1 devices do not correspond to any of the hardware device types, so FILE_DEVICE_UNKNOWN is given for DeviceType.

Table 5.1 IoCreateDevice function

Table 5.2 IoRegisterDeviceInterface function

If IoCreateDevice returns successfully, the DeviceObject parameter is set to point to the new device object. Wdm1 calls this its Functional Device Object (FDO). The Plug and Play chapter explains FDOs and PDOs in detail. Wdm1AddDevice returns an error if IoCreateDevice fails.

The Wdm1 device extension is now available through the FDO DeviceExtension field. Wdm1AddDevice stores a pointer to the FDO in its device extension.

Wdm1AddDevice now attaches the Wdm1 device to the device stack using IoAttachDeviceToDeviceStack, which must be called at PASSIVE_LEVEL [11] If you call IoAttachDeviceToDeviceStack at a higher IRQL, your driver may crash. . The FDO and the given PDO are passed to this function. It returns a pointer to yet another device object that is also stored in the Wdm1 device extension. All this shenanigans are explained in the Plug and Play chapters.

Finally, two bits in the FDO Flags field must be changed. AddDevice routines must clear the DO_DEVICE_INITIALIZING flag. You do not need to clear this flag if you call IoCreateDevice in your DriverEntry routine. The DO_BUFFERED_IO flag is set in the Flags field. Again, this is covered later.

The Wdm1 driver must delete its FDO if it receives a Remove Device request. This is an IRP_ MJ_PNP_IRP with an IRP_MN_REMOVE_DEVICE minor version code. The code in Wdm1Pnp first calls IoDetachDevice to detach the FDO from the device stack. Finally, IoDeleteDevice is called to delete the FDO and its device extension.

IoDetachDevice and IoDeleteDevice must be called at IRQL PASSIVE_LEVEL

The Wdm1 AddDevice code calls IoCreateDevice to create a Wdm1 device object. There are two ways to provide a name that is available to Win32 programs. The old way is to provide an explicit symbolic link name. The newfangled approach is to use a device interface to identify the devices that support a defined API.

The IoCreateDevice call has a DeviceName parameter that you can use to give your device a name. This name identifies the device to the kernel, not to Win32.

You must create a symbolic link to make the kernel device name available to Win32. To do this the old way, call IoCreateSymbolicLink at IRQL PASSIVE_LEVEL, passing the desired symbolic link name and the kernel device name as parameters.

Explicit device names created using this technique usually have a device number at the end. By convention, kernel device name numbers increment from zero, while symbolic link names increment from one.

The best way to illustrate device naming is using the WinObj tool, which only runs in NT and Windows 2000. WinObj is supplied in the Platform SDK, not the W2000 DDK. The standard serial ports have kernel device names \device\Serial0, \device\Serial1, etc. In WinObj, these names appear in the \device folder.

Windows provides symbolic links "C0M1", "COM2", etc., to make these serial ports available to Win32. Symbolic links appear in the \?? folder in WinObj. You can double-click on each symbolic link to find out to which kernel device it refers. The screenshot in Figure 5.2 shows that COM3, \??\com3, is a symbolic link to kernel device Serial0.

The \?? folder used to be called \DosDevices, which you might come across in some old documentation.