KDEFERRED_ROUTINE callback function (wdm.h)

Article
02/28/2023

The callback routine performs actions, after an InterruptService returns, of a threaded DPC,

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

The CustomThreadedDpc routine performs the action of a threaded DPC. The system executes this routine when the threaded DPC runs.

The CustomTimerDpc routine executes after a timer object's time interval expires.

Syntax

KDEFERRED_ROUTINE KdeferredRoutine;

void KdeferredRoutine(
  [in]           _KDPC *Dpc,
  [in, optional] PVOID DeferredContext,
  [in, optional] PVOID SystemArgument1,
  [in, optional] PVOID SystemArgument2
)
{...}

Parameters

[in] Dpc

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

[in, optional] DeferredContext

For CustomDpc, a caller-supplied pointer to driver-defined context information that was specified in a previous call to KeInitializeDpc.

For CustomThreadedDpc, specifies driver-defined context information. When it initialized the DPC object, the driver supplied this value as the DeferredContext parameter to KeInitializeThreadedDpc.

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

[in, optional] SystemArgument1

Caller-supplied pointer to driver-supplied information that was specified in a previous call to KeInsertQueueDpc. When it added the DPC to the DPC queue, the driver supplied this value as the SystemArgument1 parameter to KeInsertQueueDpc.

For CustomTimerDpc, this value is not used.

[in, optional] SystemArgument2

Specifies driver-defined context information. When it added the DPC to the DPC queue, the driver supplied this value as the SystemArgument2 parameter to KeInsertQueueDpc.

For CustomTimerDpc, this value is not used.

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.

A driver registers a CustomThreadedDpc for a DPC object by calling KeInitializeThreadedDpc. To actually add the DPC to the DPC queue so that the CustomThreadedDpc routine will be executed, call KeInsertQueueDpc.

For more information about using CustomThreadedDpc routines, see Introduction to Threaded DPCs.

A CustomThreadedDpc routine can run at IRQL = DISPATCH_LEVEL, or it can run at IRQL = PASSIVE_LEVEL in a real-time thread.

To create a DPC object and register a CustomTimerDpc routine for that object, a driver must call KeInitializeDpc.

To queue a CustomTimerDpc routine for execution, a driver routine must call KeSetTimer or KeSetTimerEx, supplying a DPC object pointer returned by KeInitializeDpc. The system calls the CustomTimerDpc routine when the timer interval expires.

For more information about CustomTimerDpc routines, see Timer Objects and DPCs.

Examples

To define a 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
  }

Requirements

Requirement	Value
Target Platform	Desktop
Header	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
IRQL	Called at DISPATCH_LEVEL.

Share via