EvtDpcFunc function

[Applies to KMDF only]

A driver's EvtDpcFunc callback function performs driver-defined operations at IRQL = DISPATCH_LEVEL.

Syntax


EVT_WDF_DPC EvtDpcFunc;

VOID EvtDpcFunc(
  _In_ WDFDPC Dpc
)
{ ... }

Parameters

Dpc [in]

A handle to a framework DPC object.

Return value

None

Remarks

To register an EvtDpcFunc callback function, your driver must place the function's address in a WDF_DPC_CONFIG structure and call WdfDpcCreate.

Drivers typically complete I/O requests in their EvtDpcFunc callback functions.

The EvtDpcFunc callback function executes at DISPATCH_LEVEL and must not access pageable code. If an EvtDpcFunc callback function must perform operations at IRQL = PASSIVE_LEVEL, it can use framework work items.

Instead of providing EvtDpcFunc callback functions, many drivers provide a single EvtInterruptDpc callback function for each type of interrupt that its devices support. If your driver creates multiple framework queue objects for each device, you might consider using a separate DPC object and EvtDpcFunc callback function for each queue.

To schedule execution of an EvtDpcFunc callback function, the driver must call WdfDpcEnqueue. Drivers typically call WdfDpcEnqueue from an EvtInterruptIsr callback function.

When a driver calls WdfDpcEnqueue, the system adds the DPC object to the system's DPC queue. If the system is not executing higher-priority tasks, it removes the object from the queue and calls the object's EvtDpcFunc callback function.

The system does not add the DPC object to the DPC queue if the object is already queued. An EvtInterruptIsr callback function might be called several times before the system calls the EvtDpcFunc callback function. Therefore, the EvtDpcFunc callback function must be able to process information from several interrupts, and it must process all of the interrupts that have occurred since the last time it was called.

Typically, it is necessary to synchronize the execution of a driver's EvtDpcFunc callback function with the execution of other callback functions. For more information, see Synchronizing Interrupt Code.

To obtain a handle to a DPC object's parent object, the EvtDpcFunc callback function can call WdfDpcGetParentObject. To obtain a pointer to a DPC object's underlying KDPC structure, the EvtDpcFunc callback function can call WdfDpcWdmGetDpc.

For more information about using EvtDpcFunc callback functions, see Servicing an Interrupt.

Examples

To define an EvtDpcFunc callback function, you must first provide a function declaration that identifies the type of callback function you’re defining. Windows provides a set of callback function types for drivers. Declaring a function using the callback function types helps Code Analysis for Drivers, Static Driver Verifier (SDV), and other verification tools find errors, and it’s a requirement for writing drivers for the Windows operating system.

For example, to define an EvtDpcFunc callback function that is named MyDpcFunc, use the EVT_WDF_DPC type as shown in this code example:


EVT_WDF_DPC  MyDpcFunc;

Then, implement your callback function as follows:


_Use_decl_annotations_
VOID
 MyDpcFunc (
    WDFDPC  Dpc
    )
  {...}

The EVT_WDF_DPC function type is defined in the Wdfdpc.h header file. To more accurately identify errors when you run the code analysis tools, be sure to add the _Use_decl_annotations_ annotation to your function definition. The _Use_decl_annotations_ annotation ensures that the annotations that are applied to the EVT_WDF_DPC function type in the header file are used. For more information about the requirements for function declarations, see Declaring Functions by Using Function Role Types for KMDF Drivers. For information about _Use_decl_annotations_, see Annotating Function Behavior.

Requirements

Target platform

Universal

Minimum KMDF version

1.0

Header

Wdfdpc.h (include Wdf.h)

IRQL

DISPATCH_LEVEL

See also

WdfDpcCreate
WdfDpcEnqueue
WdfDpcGetParentObject
WdfDpcWdmGetDpc
WDF_DPC_CONFIG
EvtInterruptDpc
EvtInterruptIsr

 

 

Send comments about this topic to Microsoft

Show:
© 2015 Microsoft