Micro-drivers, miniport drivers, and drivers for

MSDN Original: https://msdn.microsoft.com/zh-cn/library/windows/hardware/hh439643 (v=vs.85). aspx

A mini-driver or miniport driver can be used as a half-driver pair. Driver pairs such as (miniport, port) can simplify driver development. In driver pairs, one driver handles common tasks for the entire collection of devices, while another driver handles tasks specific to a single device. Drivers that handle device-specific tasks have multiple names, including miniport drivers, micro-class drivers, and micro-drivers.

Microsoft provides generic drivers, while independent hardware vendors typically provide specific drivers. Before you read this topic, you should understand the concepts described in Device node and device stacks and I/O request packets.

Each kernel-mode driver must implement a function named DriverEntry , which is called immediately after the driver has been loaded. The driverentry function Populates some members of the Driver_object structure with pointers to some other functions implemented by the driver. For example, thedriverentry function uses a pointer to the driver's Unload function to populate the Unload member of the Driver_object structure, as shown in.

The majorfunction member of the Driver_object structure is a large number of pointers to functions that process the I/O request packet (IRP) as shown in. Typically, the driver populates multiple members of the majorfunction array with pointers to functions (implemented by the driver) that handle various IRP types.

The IRP can be categorized according to the main function code of the IRP, which is identified by a constant, such as Irp_mj_read,irp_mj_write , or irp_mj_pnp. Constants that identify the main function code are used as indexes in the majorfunction array. For example, suppose the driver implements an allocation function to handle an IRP with the main function code irp_mj_write . In this case, the driver must populate the majorfunction[irp_mj_write] element of the array with a pointer to the allocation function.

Typically, the driver populates some elements of the majorfunction array and sets the remaining elements to the default values that the I/O Manager provides. The following example shows how to use the !drvobj debugger extension to check a function pointer for the Parport driver.

0:kd>!drvobj parport 2Driver Object (FFFFFA80048D9E70) is for: \driver\parportdriverentry:fffff880065ea070parport! gsdriverentrydriverstartio:00000000driverunload:fffff880065e131cparport! pptunloadadddevice:fffff880065d2008parport! P5adddevicedispatch routines:[00] Irp_mj_create fffff880065d49d0parport! PPTDISPATCHCREATEOPEN[01] Irp_mj_create_named_pipe fffff80001b6ecd4nt! IOPINVALIDDEVICEREQUEST[02] Irp_mj_close fffff880065d4a78parport! PPTDISPATCHCLOSE[03] Irp_mj_read fffff880065d4bacparport! PPTDISPATCHREAD[04] Irp_mj_write fffff880065d4bacparport! PPTDISPATCHREAD[05] Irp_mj_query_information fffff880065d4c40parport! PPTDISPATCHQUERYINFORMATION[06] Irp_mj_set_information fffff880065d4ce4parport! PPTDISPATCHSETINFORMATION[07] Irp_mj_query_ea fffff80001b6ecd4nt! IOPINVALIDDEVICEREQUEST[08] Irp_mj_set_ea fffff80001b6ecd4nt!IOPINVALIDDEVICEREQUEST[09] Irp_mj_flush_buffers fffff80001b6ecd4nt! IOPINVALIDDEVICEREQUEST[0A] Irp_mj_query_volume_information fffff80001b6ecd4nt! IOPINVALIDDEVICEREQUEST[0B] Irp_mj_set_volume_information fffff80001b6ecd4nt! IOPINVALIDDEVICEREQUEST[0C] Irp_mj_directory_control fffff80001b6ecd4nt! IOPINVALIDDEVICEREQUEST[0D] Irp_mj_file_system_control fffff80001b6ecd4nt! IOPINVALIDDEVICEREQUEST[0E] Irp_mj_device_control fffff880065d4be8parport! PPTDISPATCHDEVICECONTROL[0F] Irp_mj_internal_device_control fffff880065d4c24parport! PPTDISPATCHINTERNALDEVICECONTROL[10] Irp_mj_shutdown fffff80001b6ecd4nt! IOPINVALIDDEVICEREQUEST[11] Irp_mj_lock_control fffff80001b6ecd4nt! IOPINVALIDDEVICEREQUEST[12] Irp_mj_cleanup fffff880065d4af4parport! PPTDISPATCHCLEANUP[13] Irp_mj_create_mailslot fffff80001b6ecd4nt! IOPINVALIDDEVICEREQUEST[14] Irp_mj_query_security FFFFF80001B6ECD4nt! IOPINVALIDDEVICEREQUEST[15] Irp_mj_set_security fffff80001b6ecd4nt! IOPINVALIDDEVICEREQUEST[16] Irp_mj_power fffff880065d491cparport! PPTDISPATCHPOWER[17] Irp_mj_system_control fffff880065d4d4cparport! PPTDISPATCHSYSTEMCONTROL[18] Irp_mj_device_change fffff80001b6ecd4nt! IOPINVALIDDEVICEREQUEST[19] Irp_mj_query_quota fffff80001b6ecd4nt! IOPINVALIDDEVICEREQUEST[1A] Irp_mj_set_quota fffff80001b6ecd4nt! IOPINVALIDDEVICEREQUEST[1B] Irp_mj_pnp fffff880065d4840parport! Pptdispatchpnp

In the debugger output, you can see the Parport.sys implementation Gsdriverentry, the entry point of the driver. gsdriverentry(generated automatically when building the driver) performs some initialization and then calls DriverEntry(implemented by the driver developer).

You can also see that the Parport driver (in its driverentry function) provides the following main function code for pointers to allocation functions:

• Irp_mj_create
• Irp_mj_close
• Irp_mj_read
• Irp_mj_write
• Irp_mj_query_information
• Irp_mj_set_information
• Irp_mj_device_control
• Irp_mj_internal_device_control
• Irp_mj_cleanup
• Irp_mj_power
• Irp_mj_system_control
• Irp_mj_pnp

The remaining elements of the majorfunction array contain points to the default allocation function nt! A pointer to the iopinvaliddevicerequest.

In the debugger output, you can see that the Parport driver provides a function pointer for Unload and AddDevice , but does not provide a function pointer for startio . The AddDevice function is unique because its function pointers are not stored in the driver_object structure. Instead, it is stored in the AddDevice member of the driver_object structure extension. Describes the function pointers that the Parport driver provides in its driverentry function. The function pointers provided by Parport are shaded by shadows.

Use a driver to make it easier

Over time, when driver developers are inside and outside the Windows Driver Model (WDM) experience that Microsoft obtains, they are aware of some things about allocating functions:

• The dispatch function is largely a sample. For example, many of the code in a dispatch function for IRP_MJ_PNP is the same for all drivers. It is only a small part of Plug and Play (PnP) code that is specific to a single driver that controls a single part of the hardware.
• Scheduling functions are complex and difficult to use. Implementing features such as thread synchronization, IRP queuing, and IRP cancellation are challenging and require a deeper understanding of how the operating system works.

To make it easier for driver developers, Microsoft has created several technology-specific driver models. At first glance, technology-specific models seem to be far apart from each other, but a closer look will show that multiple models are based on this paradigm:

• The driver is split into two parts: part handles generic processing, and the other part handles special device-specific processing.
• The common part is written by Microsoft.
• Specific sections are written by Microsoft or by independent hardware vendors.

Suppose Proseware and Contoso's robot toys all need to use WDM drivers. Also assume that Microsoft provides a generic robot driver named Generalrobot.sys. Each of Proseware and Contoso can write small drivers to handle the needs of their specific robots. For example, Proseware can write Prosewarerobot.sys, and driver pairs (Prosewarerobot.sys, Generalrobot.sys) can be combined to form a single WDM driver. Similarly, driver pairs (Contosorobot.sys, Generalrobot.sys) can be combined to form a single WDM driver. In most common forms, the idea is that you can use (Specific.sys, general.sys) pairs to create drivers.

function pointers in driver pairs

In the (Specific.sys, General.sys) pair, Windows loads the Specific.sys and calls its driverentry function. Specific.sys's driverentry function receives a pointer to the DRIVER_OBJECT structure. Under normal circumstances, you expect DriverEntry to populate multiple elements of the majorfunction array with pointers to the dispatch function. You also expect DriverEntry to populate the Unload members (and possible Startio members) of the Driver_object structure and the driver object extensions AddDevice members. However, in a driver-to-model,DriverEntry does not need to do so. Instead, the Specific.sys driverentry function passes the driver_object structure to the General.sys-implemented initialization function. The following code example shows how to call the initialization function in the (Prosewarerobot.sys, Generalrobot.sys) pair.

C++

PVOID G_prosewarerobottcallbacks[3] = {devicecontrolcallback, pnpcallback, powercallback};//DriverEntry function in Prosewarerobot.sysntstatus DriverEntry (Driver_object *driverobject, punicode_string RegistryPath) {   //Call the Initialization function implemented by Generalrobot.sys.   Return Generalrobotinit (DriverObject, Registrypath, g_prosewarerobottcallbacks);}

The initialization function in Generalrobot.sys writes a function pointer to the corresponding member of the Driver_object structure (and its extension) and to the corresponding element of the majorfunction array. The idea is that when the I/O Manager sends an IRP to a driver pair, the IRP first goes to the dispatch function implemented by Generalrobot.sys. If the Generalrobot.sys can handle the IRP on its own, there is no need to involve a specific driver prosewarerobot.sys. If Generalrobot.sys can handle some but not all IRP processing, it will get help from one of the callback functions implemented by Prosewarerobot.sys. Generalrobot.sys receives a pointer to the Prosewarerobot callback in the Generalrobotinit call.

At a point returned by DriverEntry , a device stack is constructed for Proseware Robot device nodes. The device stack may resemble the following.

As shown, the Proseware Robot device stack has three device objects. The top device object is the filter device object (filter do) that is associated with the filter driver Afterthought.sys. The intermediary device object is a functional device object (FDO) associated with the driver pair (Prosewarerobot.sys, Generalrobot.sys). The driver pairs the function driver that is used as the device stack. The bottom device object is the physical device object (PDO) associated with the Pci.sys.

Note that the driver pair consumes only one layer in the device stack and is associated with only one device object: FDO. When Generalrobot.sys processes an IRP, it may call Prosewarerobot.sys for help, but this differs from passing requests down the device stack. The driver pairs form a single WDM driver that is located at the level of the device stack. The driver passes the IRP to the completion IRP or down the device stack down to the PDO associated with the Pci.sys.

Driver for example

Suppose you have a wireless card in your laptop, and you are sure that Netwlv64.sys is the NIC driver by looking in Device Manager. You can use the !drvobj debugger extension to check the function pointers used for Netwlv64.sys.

1:kd>!drvobj netwlv64 2Driver Object (fffffa8002e5f420) is for: \driver\netwlv64driverentry:fffff8800482f064 NETWL v64! gsdriverentrydriverstartio:00000000 driverunload:fffff8800195c5f4 ndis!ndismunloadexadddevice:fffff88001940d30th Is!ndispnpadddevicedispatch routines:[00] Irp_mj_create fffff880018b5530 ndis!ndiscreateirphandler[01 ] Irp_mj_create_named_pipe fffff88001936f00 ndis!ndisdummyirphandler[02] Irp_mj_close FFFF  f880018b5870 ndis!ndiscloseirphandler[03] Irp_mj_read fffff88001936f00 ndis!ndisdummyirphandler[04] Irp_mj_write fffff88001936f00 ndis!ndisdummyirphandler[05] irp_mj_query_information fffff 88001936F00 ndis!ndisdummyirphandler[06] irp_mj_set_information fffff88001936f00 ndis!ndisDummyIrpHandler[07] Irp_mj_query_ea fffff88001936f00 ndis!ndisdummyirphandler[08] Irp_mj_set_ea fffff8 8001936F00 NDIS!NDISDUMMYIRPHANDLER[09] irp_mj_flush_buffers fffff88001936f00 ndis!ndisdummyirphandler[0a] IRP_MJ_QUERY_VOLUME_IN Formation fffff88001936f00 ndis!ndisdummyirphandler[0b] irp_mj_set_volume_information fffff88001936f00 ndis!ndisDu MMYIRPHANDLER[0C] Irp_mj_directory_control fffff88001936f00 ndis!ndisdummyirphandler[0d] IRP_MJ_FILE_SYSTEM_CONT ROL fffff88001936f00 ndis!ndisdummyirphandler[0e] Irp_mj_device_control fffff8800193696c Ndis!ndisDev ICECONTROLIRPHANDLER[0F] Irp_mj_internal_device_control fffff880018f9114 ndis!ndisdeviceinternalirpdispatch[10] Irp_mj_shutdown fffff88001936f00 ndis!ndisdummyirphandler[11] Irp_mj_lock_control fffff8 8001936F00 ndis!ndisdummyirphandler[12] irp_mj_cleanup fffff88001936f00 ndis!ndisdummyirphandler[13] I Rp_mj_create_mailslot fffff88001936f00 ndis!ndisdummyirphandler[14] irp_mj_query_security fffff88 001936F00 Ndis!ndisdummyirphanDLER[15] irp_mj_set_security fffff88001936f00 ndis!ndisdummyirphandler[16] Irp_mj_power Fffff880018c35e8 ndis!ndispowerdispatch[17] Irp_mj_system_control fffff880019392c8 ndis!ndisWMIDispatch[18 ] Irp_mj_device_change fffff88001936f00 ndis!ndisdummyirphandler[19] Irp_mj_query_quota FFFF  F88001936F00 ndis!ndisdummyirphandler[1a] Irp_mj_set_quota fffff88001936f00 ndis!ndisdummyirphandler[1b] Irp_mj_pnp fffff8800193e518 Ndis!ndispnpdispatch

In the debugger output, you can see the Netwlv64.sys implementation Gsdriverentry, the entry point of the driver. gsdriverentry(generated automatically when building the driver) performs some initialization and then calls DriverEntry(written by the driver developer).

In this example, Netwlv64.sys implements DriverEntry, but Ndis.sys implements AddDevice,Unload , and multiple dispatch functions. Netwlv64.sys is called the NDIS miniport driver, Ndis.sys is called the NDIS library. Two modules are formed together (NDIS miniport, NDIS library) pairs.

This figure represents the device stack for the wireless card. Note that the driver pair (Netwlv64.sys, Ndis.sys) occupies only one layer in the device stack and is associated with only one device object: FDO.

Available drivers for

Different technology-specific driver models use a large number of names for specific parts and common parts of driver pairs. In many cases, the specific part of the pair has the prefix "Mini". The following are some (specific, generic) pairs that are available:

• (Screen miniport driver, screen port driver)
• (Audio miniport driver, audio port driver)
• (Storage miniport driver, storage port driver)
• (Battery mini-class driver, battery class driver)
• (HID micro driver, HID class driver)
• (Converter mini-class driver, converter port driver)
• (NDIS miniport driver, NDIS library)

NoteAs you can see in the list, multiple models use the term "class driver" as the generic part of the driver pair. This kind of driver differs from a standalone class driver and also differs from a class filter driver.

Micro-drivers, miniport drivers, and drivers for