KeQueryActiveProcessors routine

The KeQueryActiveProcessors routine returns a bitmask of the currently active processors.

Syntax


KAFFINITY KeQueryActiveProcessors(void);

Parameters

This routine has no parameters.

Return value

KeQueryActiveProcessors returns a KAFFINITY value that represents the set of currently active processors.

Remarks

Callers cannot assume that KeQueryActiveProcessors maps processors to bits consecutively, or that the routine consistently uses the same mapping each time it is called. The only valid use for the return value is to determine the number of active processors by counting the number of bits that are set.

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

Windows 7 and later versions of Windows support processor groups. Drivers that are designed to handle information about processor groups should use the KeQueryGroupAffinity routine, which specifies a processor group, instead of KeQueryActiveProcessors, which does not. However, the implementation of KeQueryActiveProcessors 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, KeQueryActiveProcessors returns an affinity mask that specifies the set of active logical processors in group 0.

In Windows Vista and later versions of Windows, this routine can be called at any IRQL. However, in Windows Server 2003 and earlier versions of Windows, this routine must be called at IRQL <= APC_LEVEL.

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.

The KeNumberProcessors kernel variable is obsolete in Windows Vista with Service Pack 1 (SP1), Windows Server 2008, and later versions of Windows. KeNumberProcessors does not appear in WDK headers for WDK releases starting with Windows Vista SP1; however, the variable is still exported from the kernel, so drivers built for earlier platforms will not break

Windows Server 2008 includes support for Dynamic Hardware Partitioning (DHP) in the Windows Datacenter and Enterprise Edition SKUs. As part of DHP, Windows Server 2008 supports hot adding CPUs at runtime. In a hot-add CPU environment, the number of processors may not remain constant during runtime.

Accordingly, in Windows Server 2008, code that can determine the number of processors must use KeQueryActiveProcessors instead of direct references to the kernel variable, KeNumberProcessors.

Review any code that currently references KeNumberProcessors to make sure that it accommodates changes to CPU count in hot-add CPU environments.

You can use the PNPCPU tool to simulate hot adding a CPU for testing purposes.


#if (NTDDI_VERSION >= NTDDI_VISTA)
extern NTSYSAPI volatile CCHAR KeNumberProcessors;
#else
#if (NTDDI_VERSION >= NTDDI_WINXP)
extern NTSYSAPI CCHAR KeNumberProcessors;
#else
extern PCCHAR KeNumberProcessors;
#endif
#endif

Starting with Windows XP, KeNumberProcessors is an 8-bit integer value that indicates the number of processors in the platform. In earlier versions of Windows, KeNumberProcessors is a pointer to an 8-bit integer value that indicates the number of processors in the platform.

Requirements

Target platform

Universal

Version

Available starting with Windows 2000.

Header

Ntddk.h (include Ntddk.h)

Library

NtosKrnl.lib

DLL

NtosKrnl.exe

IRQL

See Remarks section.

DDI compliance rules

IrqlKeApcLte1, HwStorPortProhibitedDDIs

See also

KeQueryActiveProcessorCount
KeQueryGroupAffinity

 

 

Send comments about this topic to Microsoft

Show: