CustomDpc routine

The CustomDpc routine finishes the servicing of an I/O operation, after an InterruptService routine returns.

Syntax


KDEFERRED_ROUTINE CustomDpc;

VOID CustomDpc(
  _In_      struct _KDPC *Dpc,
  _In_opt_  PVOID DeferredContext,
  _In_opt_  PVOID SystemArgument1,
  _In_opt_  PVOID SystemArgument2
)
{ ... }

Parameters

Dpc [in]

Caller-supplied pointer to a KDPC structure, which represents the DPC object that is associated with this CustomDpc routine.

DeferredContext [in, optional]

Caller-supplied pointer to driver-defined context information that was specified in a previous call to KeInitializeDpc.

SystemArgument1 [in, optional]

Caller-supplied pointer to driver-supplied information that was specified in a previous call to KeInsertQueueDpc.

SystemArgument2 [in, optional]

Caller-supplied pointer to driver-supplied information that was specified in a previous call to KeInsertQueueDpc.

Return value

None

Remarks

To create a DPC object and register a CustomDpc routine for that object, a driver must call KeInitializeDpc. (If you need only one DPC routine, you can use a DpcForIsr routine and the system-allocated DPC object.)

To queue a CustomDpc routine for execution, a driver's InterruptService routine must call KeInsertQueueDpc.

One or more CustomDpc routines can be used instead of, or in conjunction with, a DpcForIsr routine. A driver that maintains several internal IRP queues typically supplies a CustomDpc routine for each queue. Each CustomDpc routine is typically responsible for at least the following tasks:

  • Completing the I/O operation that is described by the current IRP.

  • Dequeuing the next IRP from one of the driver's IRP queues. (Drivers that use the system-supplied IRP queue together with a StartIo routine call IoStartNextPacket.)

  • Setting the I/O status block in the current IRP and calling IoCompleteRequest for the completed request.

A CustomDpc routine might also retry a failed operation or set up the next transfer for a large I/O request that has been broken into smaller pieces.

For more information about CustomDpc routines, see DPC Objects and DPCs.

Examples

To define a CustomDpc callback routine, you must first provide a function declaration that identifies the type of callback routine 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 a CustomDpc callback routine that is named MyCustomDpc, use the KDEFERRED_ROUTINE type as shown in this code example:


KDEFERRED_ROUTINE MyCustomDpc;

Then, implement your callback routine as follows:


_Use_decl_annotations_
VOID
  MyCustomDpc(
    struct _KDPC  *Dpc,
    PVOID  DeferredContext,
    PVOID  SystemArgument1,
    PVOID  SystemArgument2
    )
  {
      // Function body
  }

The KDEFERRED_ROUTINE function type is defined in the Wdm.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 KDEFERRED_ROUTINE 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 WDM Drivers. For information about _Use_decl_annotations_, see Annotating Function Behavior.

Requirements

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)

IRQL

Called at DISPATCH_LEVEL.

See also

KeInitializeDpc
KeInsertQueueDpc

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft