KeSetTargetProcessorDpcEx function (wdm.h)

Article
02/25/2022

The KeSetTargetProcessorDpcEx routine specifies the processor that a DPC routine will run on.

Syntax

NTSTATUS KeSetTargetProcessorDpcEx(
  [in, out] PKDPC             Dpc,
  [in]      PPROCESSOR_NUMBER ProcNumber
);

Parameters

[in, out] Dpc

A pointer to the caller's DPC object. This parameter points to a KDPC structure, which is an opaque, system structure that represents the DPC object. This object must previously have been initialized by the KeInitializeDpc routine.

[in] ProcNumber

A pointer to a caller-allocated PROCESSOR_NUMBER structure that identifies the target processor on which the DPC will be queued and executed. This structure specifies a group and a processor within this group.

Return value

KeSetTargetProcessorDpcEx returns STATUS_SUCCESS if the call is successful. Otherwise, it returns the following:

Return code	Description
STATUS_INVALID_PARAMETER	The ProcNumber parameter points to an invalid processor number.

Remarks

Each processor in a multiprocessor system has its own DPC queue. KeSetTargetProcessorDpcEx specifies which processor's queue the system should use when the driver calls the KeInsertQueueDpc or IoRequestDpc routine to queue a DPC to be run later.

KeSetTargetProcessorDpcEx can specify the target processor for both ordinary DPCs and threaded DPCs. An ordinary DPC cannot be preempted by even a high-priority thread, but a threaded DPC can be preempted by time-critical threads that have sufficiently high priorities.

A related routine, KeSetTargetProcessorDpc, specifies a target processor for a DPC, but this routine, unlike KeSetTargetProcessorDpcEx, does not specify a group for the target processor. Starting with Windows 7, KeSetTargetProcessorDpc assumes that the target processor belongs to group 0. This behavior ensures that existing drivers that call KeSetTargetProcessorDpc and that use no group-oriented features will run correctly in multiprocessor systems that have two or more groups. However, drivers that use any group-oriented features in Windows 7 and later versions of the Windows operating system should call KeSetTargetProcessorDpcEx instead of KeSetTargetProcessorDpc.

A call to KeSetTargetProcessorDpcEx that occurs after a DPC object has been queued has no effect on the selection of a processor for the DPC routine to run on. To control the selection of the target processor, a KeSetTargetProcessorDpcEx call must occur before the call to KeInsertQueueDpc or IoRequestDpc that queues the DPC object.

For more information about DPC queues, see Organization of DPC Queues.

Requirements

Requirement	Value
Minimum supported client	Available starting with Windows 7.
Target Platform	Universal
Header	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	Any level