How to Annotate KMDF Driver Source Code for SDV

You can annotate your driver source code with KMDF callback function role types for SDV to significantly enhance the ability of SDV to analyze and detect potential problems with your code. Role types provide SDV with information about the intended use of a function, which allows SDV to better determine whether a particular bug exists.

Function role types for SDV reveal the distinct roles defined for callback functions in the underlying WDF driver model or for dispatch functions in the underlying WDM driver model. These role types either substitute for or augment traditional declarations for these functions.

To enable SDV for a KMDF driver, you must add role type declarations to your driver source code as explained in this section. These role type declarations allow SDV to scan the driver as described in "How to Scan Driver Source Code to Create an Sdv-map.h File" later in this chapter.

 Tip  See "Static Driver Verifier" in the WDK for details about annotating a KMDF or WDM driver with role type declarations.

Function Role Type Declarations for KMDF Drivers

The Wdf.h header file includes other header files that define several driver callback function role types such as EVT_WDF_DRIVER_DEVICE_ADD, EVT_WDF_DRIVER_UNLOAD, and EVT_WDF_DEVICE_FILE_CREATE. See "KMDF Callback Function Role Types for SDV" later in this chapter for a complete list of these role types.

To enhance SDV capabilities, each driver callback function in a KMDF driver must be declared in one of the driver's header files by specifying the corresponding role type. For example, the following declaration shows the role type for the driver's MyFileCreate callback function:

 EVT_WDF_DEVICE_FILE_CREATE MyFileCreate; 

This declaration, which is pure C, is all that the C compiler requires to compile the driver source code; neither the C compiler nor SDV requires the traditional verbose declaration of a callback function.

If you prefer to use traditional verbose declarations in your code, place the SDV role type declaration immediately before the traditional verbose declaration, as in the following example:

 EVT_WDF_DEVICE_FILE_CREATE MyFileCreate; VOID  MyFileCreate (         IN WDFDEVICE Device,         IN WDFREQUEST Request,         IN WDFFILEOBJECT FileObject         ); 

Example: Function Role Types in Sample Drivers

Inside Out 

Listing 24-1 shows the function role types for the callback functions for the KMDF Fail_driver6 sample, which can be found at %wdk%\tools\sdv\samples\ fail_drivers\kmdf\fail_driver6\driver. The related functions are declared in FailDriver6.c.

Listing 24-1: SDV role types for Fail_driver6 callback functions

 #include <NTDDK.h> #include <wdf.h> #include "fail_library6.h" NTSTATUS DriverEntry(             IN PDRIVER_OBJECT   DriverObject,             IN PUNICODE_STRING  RegistryPath             ); EVT_WDF_DRIVER_DEVICE_ADD EvtDriverDeviceAdd; EVT_WDF_IO_QUEUE_IO_READ EvtIoRead; EVT_WDF_IO_QUEUE_IO_WRITE EvtIoWrite; EVT_WDF_IO_QUEUE_IO_DEVICE_CONTROL EvtIoDeviceControl; 

The EVT_WDF_DRIVER_DEVICE_ADD function role type is associated with the driver's EvtDriverDeviceAdd callback function. Because the role types appear in the Fail_Driver6.h header file, adding role type declarations in the Fail_Driver6.c implementation file is unnecessary.

Inside Out 

The example in Listing 24-2 shows the function role type declarations in the header file for the Osrusbfx2 sample, which can be found at %wdk%\src\kmdf\osrusbfx2.

Listing 24-2: SDV function role types for Osrusbfx2 callback functions

 #include <wdf.h> #include <wdfusb.h> . . . // Code omitted for brevity typedef struct _DEVICE_CONTEXT {     WDFUSBDEVICE                    UsbDevice;     WDFUSBINTERFACE                 UsbInterface;     WDFUSBPIPE                      BulkReadPipe;     WDFUSBPIPE                      BulkWritePipe;     WDFUSBPIPE                      InterruptPipe;     UCHAR                           CurrentSwitchState;     WDFQUEUE                        InterruptMsgQueue; } DEVICE_CONTEXT, *PDEVICE_CONTEXT; WDF_DECLARE_CONTEXT_TYPE_WITH_NAME(DEVICE_CONTEXT, GetDeviceContext) extern ULONG DebugLevel; DRIVER_INITIALIZE DriverEntry; EVT_WDF_OBJECT_CONTEXT_CLEANUP OsrFxEvtDriverContextCleanup; EVT_WDF_DRIVER_DEVICE_ADD OsrFxEvtDeviceAdd; EVT_WDF_DEVICE_PREPARE_HARDWARE OsrFxEvtDevicePrepareHardware; EVT_WDF_IO_QUEUE_IO_READ OsrFxEvtIoRead; EVT_WDF_IO_QUEUE_IO_WRITE OsrFxEvtIoWrite; EVT_WDF_IO_QUEUE_IO_DEVICE_CONTROL OsrFxEvtIoDeviceControl; EVT_WDF_REQUEST_COMPLETION_ROUTINE EvtRequestReadCompletionRoutine; EVT_WDF_REQUEST_COMPLETION_ROUTINE EvtRequestWriteCompletionRoutine; . . . 

Chapter 23, "PREfast for Drivers," provides the complete annotated Osrusbfx2 sample.