44. Windows Driver Model notes (2)

FigureDisplaySource image2-13Driver_object Data Structure

I/O manager driverProgramEach device driver, as shown in Figure 2-13. Like many data structures we will discuss, driver objects are partially opaque. This means that although the entire structure is exposed in the DDK header, we can only directly access or modify some fields in the structure. In the figure, I use a gray background to represent the opaque domain of the driver object. These opaque domains are similar to private or protected members in the C ++ class, while transparent domains are similar to public members.

1. driver_object Data Structure

Deviceobject (pdevice_object) points to a device object linked list. Each device object represents a device. The I/O manager connects multiple device objects and maintains the domain. The driverunload function of a non-WDM driver uses this field to traverse the list of Device objects to delete the device objects. The WDM driver does not need to use this domain.

Driverextension (pdriver_extension) points to a small sub-structure. Only the adddevice (pdriver_add_device) member can directly access it, as shown in Figure 2-14. Adddevice is a pointer that points to the function used to create a device object in the driver.

Figure 2-14. driver_extension Data Structure

Fastiodispatch (pfast_io_dispatch) points to a function pointer table, which is output by the file system and network driver.

Driverstartio (pdriver_startio) points to the function that processes serial I/O requests in the driver, and the I/O manager automatically serializes multiple I/O requests for the driver.

Driverunload (pdriver_unload) points to the purge function in the driver. I will discuss this function later in the DriverEntry function. In fact, the WDM driver has no important work to do at all.

Majorfunction (array of pdriver_dispatch) is a function pointing to more than 20 types of IRP processing functions in the driver.

2. device_object Structure

The WDM driver can call the iocreatedevice function to create a device object. However, the I/O manager is responsible for managing the device object.

Figure 2-15 device_object Structure

Driverobject (pdriver_object) points to the driver object related to the device object, which is usually the driver object that calls the iocreatedevice function to create the device object. The filter driver sometimes needs this pointer to find the driver object of the filtered device, and then view its majorfunction table items.

Nextdevice (pdevice_object) points to the next device object belonging to the same driver. This domain connects multiple device objects. The starting point is the deviceobject member in the driver object. The WDM driver does not need to use this domain.

Currentirp (pirp) points to the I/O Request package recently sent to the driver startio function.

Characteristics (ulong) is another set of flag that describes the optional features of the device.

Deviceextension (pvoid) points to a user-defined data structure that can be used to save information about each device instance. The I/O manager allocates space for the structure, but the name and content of the structure are completely determined by the user. A common practice is to name the structure device_extension. Use the given device object pointer fdo to access this user structure,CodeAs follows:

Pdevice_extension PDX = (pdevice_extension) fdo-> deviceextension;

Stacksize (cchar) is used to count the number of Device objects from the start of the device object to the end of the PDO. The purpose of this domain is to tell other code. If the driver of the device object is used as the first sending object of its IRP, the number of stack locations that should be created in this IRP ). You do not need to modify the value of the WDM driver because the supported functions for creating the device stack automatically complete this task.

In the above discussion of device_object, all the device objects that belong to a specific driver are connected horizontally through a nextdevice domain, but there is no description of how to vertically connect multiple device objects into a device stack, that is, from the upper layer Fido to fdo, then to the lower layer Fido, and finally to PDO. The opaque domain attacheddevice is used for this purpose. From PDO, each device object has a pointer to a device object. Because there are no exposed downward pointers, the driver must remember who the underlying device object is. (In fact, ioattachdevicetodevicestack indeed creates a downward pointer in a structure, but the structure is not fully declared in the DDK. Do not try to find this structure, it may be modified at any time)

The attacheddevice domain is intentionally not made public, because correct use of this domain must be synchronized with the code for deleting the device object. However, we can call the iogetattacheddevicereference function, which searches for the top-level device object in the given stack and adds the reference count. This prevents the device object from being prematurely deleted from the memory. If you want to go to the PDO, you can send an irp_mj_pnp request to the device. The sub-function code is irp_mn_query_device_relations, And the type parameter is targetdevicerelation. The PDO Driver returns the address of the PDO. However, I guess this IRP is reserved for the system, so you 'd better not use it. We can remember the PDO address when setting up a device object for the first time.

3. DriverEntry

DriverEntry is a common name for the main entry point of the kernel-mode driver.

Extern "C" ntstatus DriverEntry (in pdriver_object driverobject, in punicode_string registrypath)

{

...

}

The first parameter of DriverEntry is a pointer pointing to a newly initialized driver object, which represents your driver. The DriverEntry routine of the WDM driver should initialize the object and return it. Non-WDM drivers require a lot of extra work. They must detect their own hardware, create Device objects for the hardware (used to represent the hardware), configure and initialize the hardware to make it work normally. For WDM drivers, hardware probe and configuration work is automatically completed by the PNP manager. I will discuss the PNP in chapter 6. If you want to know how a non-WDM driver initializes itself, see the Windows NT Device Driver book (Prentice Hall, 1997) of art Baker) viscarola and Mason's Windows NT device driver development (Macmillan, 1998).

The second parameter of DriverEntry is the key name of the device service key. This string does not exist for a long time (it may disappear after the function returns). If you want to use this string later, you must copy it to a safe place.

Servkey. Buffer = (pwstr) exallocatepool (pagedpool, registrypath-> Length + sizeof (wchar ));

If (! Servkey. buffer)

Return status_insufficient_resources;

Servkey. maximumlength = registrypath-> Length + sizeof (wchar );

Rtlcopyunicodestring (& servkey, registrypath );

For the driver DriverEntry routine of WDM, the main task is to fill various function pointers into the driver object. These pointers indicate the locations of various subroutines in the driver container for the operating system. Driverextension-> adddevice points to the adddevice function of the driver. The PNP manager calls the adddevice routine once for each hardware instance.

Driverstartio if the driver uses the standard IRP queuing method, set this member to point it to the startio routine of the driver.

Majorfunction is a pointer array. Each WDM driver must be able to process the PNP, power, and system_control requests.