Declaring Functions Using Function Role Type Declarations
When you write driver code, you might notice that it is often the operating system that calls a function in a driver rather than the reverse. The driver functions that are called from the operating system must have their contract specified. A function can specify a contract by using function typedefs, where the type of the function is declared in the system headers. These function typedefs are also called role types because they define the role that the function plays in the operation of the driver.
When you declare a function using one of the predefined function role types for driver functions, the declared function implicitly gets the annotations that have been provided for that role type. You do not need to annotate the function beyond the function declaration. If your driver uses another driver model, or has functions that do not fall under the recognized role types, you can skip this step. But you will still need to place annotations on the function declaration and definition.
For example, the following declarations specify the function role types for some of the functions in a sample WDM driver. These annotations are used by PREfast for Drivers (PFD) and Static Driver Verifier (SDV).
DRIVER_INITIALIZE DriverEntry;
DRIVER_ADD_DEVICE DriverAddDevice;
DRIVER_UNLOAD DriverUnload;
__drv_dispatchType(IRP_MJ_PNP) DRIVER_DISPATCH DispatchPnp;
__drv_dispatchType(IRP_MJ_POWER) DRIVER_DISPATCH DispatchPower;
__drv_dispatchType(IRP_MJ_SYSTEM_CONTROL) DRIVER_DISPATCH DispatchSystemControl;
The following table lists the primary function role type for WDM drivers.
:
| Annotation (WDM function role type) | WDM routine |
|---|---|
DRIVER_INITIALIZE |
|
DRIVER_STARTIO |
|
DRIVER_UNLOAD |
|
DRIVER_ADD_DEVICE |
|
__drv_dispatchType(type) DRIVER_DISPATCH |
The dispatch routine(s) used by the driver. See Writing Dispatch Routines. The __drv_dispatchType(type) annotation must be combined with the DRIVER_DISPATCH role type annotation to specify the driver entry points. |
IO_COMPLETION_ROUTINE |
The IoCompletion routine is set by calling IoSetCompletionRoutine or IoSetCompletionRoutineEx and passing the function pointer to the IoCompletion routine as the second parameter. |
DRIVER_CANCEL |
The Cancel routine is set by calling IoSetCancelRoutine and passing the function pointer to the cancellation routine for the IRP as the second parameter to the function. |
IO_DPC_ROUTINE |
The DpcForIsr routine is registered by calling IoInitializeDpcRequest and passing the function pointer to the DpcForIsr routine as the second parameter. To queue the DPC, call IoQueueDpc from the ISR routine by using the same DPC object. |
KDEFERRED_ROUTINE |
The CustomDpc routine is set by calling KeInitializeDpc and passing the function pointer to the CustomDpc as the second parameter. To queue the CustomDpc for the driver, call KeInsertQueueDpc from the ISR routine by using the same DPC object. |
WORKER_THREAD_ROUTINE |
Routine Routine is the callback routine that is specified in the second parameter to the ExInitializeWorkItem function. The callback routine is responsible for freeing the specified work item when it is no longer needed. The Routine should only be declared this way if the driver calls ExQueueWorkItem to add the work item to a system queue. |
For a list of function role types for KMDF drivers, see Declaring Functions Using Function Role Types for KMDF Drivers.
If your driver is written in C++, see Using Function typedefs or Function Role Types in C++ Driver Code to Improve PREfast Results.
Example of KMDF Function Role Type Declarations
#include <NTDDK.h>
#include <wdf.h>
#include "fail_library1.h"
DRIVER_INITIALIZE DriverEntry;
EVT_WDF_DRIVER_DEVICE_ADD EvtDriverDeviceAdd;
EVT_WDF_IO_QUEUE_IO_READ EvtIoRead;
EVT_WDF_IO_QUEUE_IO_DEVICE_CONTROL EvtIoDeviceControl;
EVT_WDF_IO_QUEUE_IO_INTERNAL_DEVICE_CONTROL EvtIoInternalDeviceControl;
EVT_WDF_REQUEST_CANCEL EvtRequestCancel;
Send comments about this topic to Microsoft
Build date: 5/3/2011