This topic has not yet been rated - Rate this topic

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 routine that is named MyCustomDpc, you must first provide a function declaration that Static Driver Verifier (SDV) and other verification tools require, as shown in the following code example:


KDEFERRED_ROUTINE MyCustomDpc;

Then, implement your DPC routine as follows:


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

The KDEFERRED_ROUTINE function type is defined in the Wdm.h header file. For more information about SDV requirements for function declarations, see Declaring Functions Using Function Role Types for WDM Drivers.

Requirements

Header	Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)
IRQL	Called at DISPATCH_LEVEL.