KeQueryNodeActiveAffinity function (wdm.h)

Article
01/06/2023

The KeQueryNodeActiveAffinity routine gets the current processor affinity of a specified node in a multiprocessor system that has a non-uniform memory access (NUMA) architecture.

Syntax

void KeQueryNodeActiveAffinity(
  [in]            USHORT          NodeNumber,
  [out, optional] PGROUP_AFFINITY Affinity,
  [out, optional] PUSHORT         Count
);

Parameters

[in] NodeNumber

The node number. If a multiprocessor system contains n nodes, the nodes are numbered from 0 to n-1. To obtain the highest node number (n-1) in the system, call the KeQueryHighestNodeNumber routine.

[out, optional] Affinity

A pointer to a caller-allocated buffer into which the routine writes a GROUP_AFFINITY structure. This structure contains the group number of the group that contains the node that is identified by NodeNumber, and an affinity mask that indicates which logical processors in the node are active. You can set this parameter to NULL if you do not need this information.

Starting in Windows Server 2022, a node can span more than one group. This happens when a node contains more than 64 processors. In this case, the OS assigns a primary group for each NUMA node. The primary group is always the one containing the most processors. In this case, the group affinity structure returned is for the node's primary group. For more info about this change in behavior, see NUMA Support. If your code runs on systems with more than 64 processors per NUMA node, consider instead using KeQueryNodeActiveAffinity2.

[out, optional] Count

A pointer to a location into which the routine writes the number of active processors that are represented in the node affinity mask that is pointed to by Affinity. You can set this parameter to NULL if you do not need this information.

Starting in Windows Server 2022, count returned is for the node's primary group. See more info about primary groups above.

Return value

None

Remarks

The caller-allocated buffer that is pointed to by the Affinity parameter must be large enough to contain a GROUP_AFFINITY structure. The Mask member of this structure contains an affinity mask that indicates which processors are active. If a processor is active, the corresponding bit in the mask is one. All other bits are zero.

In a NUMA multiprocessor architecture, a node is a collection of processors that share fast access to a region of memory. Memory access is non-uniform because a processor can access the memory in its node faster than it can access the memory in other nodes.

The number of processors in a node cannot exceed the number of bits in the affinity mask in the structure that is pointed to by Affinity. The affinity mask also determines the maximum number of processors in a group.

In Windows 10, version 2004 and earlier versions, if during system initialization, Windows encounters a NUMA hardware node that contains more logical processors than will fit into a group, Windows splits the node into smaller, logical nodes. Each of these nodes does not exceed the maximum group size. The NodeNumber parameter identifies a logical node. To obtain the maximum number of processors per group, call the KeQueryMaximumProcessorCountEx routine.

Requirements

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