KeQueryActiveProcessorCount routine

The KeQueryActiveProcessorCount routine returns the number of currently active processors.

Syntax


ULONG KeQueryActiveProcessorCount(
  _Out_opt_ PKAFFINITY ActiveProcessors
);

Parameters

ActiveProcessors [out, optional]

A pointer to a KAFFINITY-typed variable into which the routine writes a bitmask that represents the set of currently active processors. In a hot-add environment, this mask may change during runtime. This parameter is optional and can be specified as NULL if the caller does not require the mask of active processors.

Return value

KeQueryActiveProcessorCount returns the number of currently active processors.

Remarks

A device driver calls the KeQueryActiveProcessorCount routine to retrieve the number of currently active processors. Device drivers that are built for Windows Vista and later versions of the Windows operating system should not use the KeNumberProcessors kernel variable for this purpose.

Callers cannot assume that the KeQueryActiveProcessorCount routine maps processors to bits in the returned KAFFINITY value consecutively, or that the routine will return the same bitmask each time it is called.

Callers must also be aware that the value returned by KeQueryActiveProcessorCount can change at runtime on versions of Windows that support hot-add CPU functionality.

If necessary, register for notification of changes to the number of processors by calling the KeRegisterProcessorChangeCallback routine.

To query just the affinity mask without getting the number of active processors, use KeQueryActiveProcessors.

Windows 7 and later versions of Windows support processor groups. Drivers that are designed to handle information about processor groups should use the KeQueryActiveProcessorCountEx routine, which specifies a processor group, instead of KeQueryActiveProcessorCount, which does not. However, the implementation of KeQueryActiveProcessorCount in Windows 7 and later versions of Windows provides compatibility for drivers that were written for earlier versions of Windows, which do not support processor groups. In this implementation, KeQueryActiveProcessorCount returns the number of active logical processors in group 0, and writes an affinity mask to *ActiveProcessors that specifies the set of active logical processors in group 0.

The KAFFINITY type is an affinity mask that represents a set of logical processors in a group. The KAFFINITY type is 32 bits on a 32-bit version of Windows and is 64 bits on a 64-bit version of Windows.

If a group contains n logical processors, the processors are numbered from 0 to n-1. Processor number i in the group is represented by bit i in the affinity mask, where i is in the range 0 to n-1. Affinity mask bits that do not correspond to logical processors are always zero.

For example, if a KAFFINITY value identifies the active processors in a group, the mask bit for a processor is one if the processor is active, and is zero if the processor is not active.

The number of bits in the affinity mask determines the maximum number of logical processors in a group. For a 64-bit version of Windows, the maximum number of processors per group is 64. For a 32-bit version of Windows, the maximum number of processors per group is 32. Call the KeQueryMaximumProcessorCountEx routine to obtain the maximum number of processors per group. This number depends on the hardware configuration of the multiprocessor system, but can never exceed the fixed 64-processor and 32-processor limits that are set by the 64-bit and 32-bit versions of Windows, respectively.

The GROUP_AFFINITY structure contains an affinity mask and a group number. The group number identifies the group to which the affinity mask applies.

Kernel routines that use the KAFFINITY type include IoConnectInterrupt, KeQueryActiveProcessorCount, and KeQueryActiveProcessors.

Requirements

Target platform

Universal

Version

Available in Windows Vista and later versions of Windows.

Header

Ntddk.h (include Ntddk.h)

Library

NtosKrnl.lib

DLL

NtosKrnl.exe

IRQL

Any level

See also

KeQueryActiveProcessorCountEx
KeQueryActiveProcessors
KeRegisterProcessorChangeCallback

 

 

Send comments about this topic to Microsoft

Show: