KeQueryLogicalProcessorRelationship function (wdm.h)

The KeQueryLogicalProcessorRelationship routine gets information about the relationships of one or more processors to the other processors in a multiprocessor system.

Syntax

NTSTATUS KeQueryLogicalProcessorRelationship(
  [in, optional]  PPROCESSOR_NUMBER                        ProcessorNumber,
  [in]            LOGICAL_PROCESSOR_RELATIONSHIP           RelationshipType,
  [out, optional] PSYSTEM_LOGICAL_PROCESSOR_INFORMATION_EX Information,
  [in, out]       PULONG                                   Length
);

Parameters

[in, optional] ProcessorNumber

A pointer to a PROCESSOR_NUMBER structure that identifies the logical processor for which the caller requests relationship information. To request information about all logical processors in the system, set this parameter to NULL.

[in] RelationshipType

Specifies the type of relationship information that is requested by the caller. Set this parameter to one of the following LOGICAL_PROCESSOR_RELATIONSHIP enumeration values:

• RelationProcessorCore

• RelationNumaNode

  Starting in Windows Server 2022, each NUMA node is assigned a primary group. Requests for RelationNumaNode will return RelationNumaNode structures that contain only a single group affinity, that of the node's primary group if a processor number is not specified, that of the group containing the given processor if a processor number is specified (GroupCount == 1, size of structure is unchanged). For more info, see KeQueryNodeActiveAffinity and NUMA Support.

• RelationCache

• RelationProcessorPackage

• RelationGroup

• RelationProcessorDie

• RelationNumaNodeEx

• RelationAll

  Starting in Windows Server 2022, requests for RelationNumaNodeEx or RelationAll will return RelationNumaNode structures that contain an array of affinities for the node over all groups (GroupCount reports number of affinities, size of structure is variable). For more info, see NUMA Support.

[out, optional] Information

A pointer to a caller-allocated buffer into which the routine writes an array of one or more SYSTEM_LOGICAL_PROCESSOR_INFORMATION_EX structures that contain the information requested by the caller. If the function fails, the contents of this buffer are undefined. Set Information = NULL to obtain the required buffer length before you allocate the buffer. For more information, see the following Remarks section.

[in, out] Length

A pointer to a location that contains the size, in bytes, of the buffer that is pointed to by Information. On entry, *Length contains the size of the caller-allocated buffer that is pointed to by Information. During the call, the routine overwrites the value that is pointed to by Length with the buffer size that is required to contain the requested relationship information.

Return value

KeQueryLogicalProcessorRelationship returns STATUS_SUCCESS if the call is successful. Possible error return values include the following:

Remarks

To determine the buffer size to allocate, initially call KeQueryLogicalProcessorRelationship with Information = NULL and Length = 0. In response, the routine writes the required buffer size to**Length and returns STATUS_INFO_LENGTH_MISMATCH. Next, allocate a buffer of the required size and call KeQueryLogicalProcessorRelationship a second time. In this second call, set Information to the buffer address and *Length to the buffer size. If the second call succeeds, the routine writes the requested relationship information to the buffer and returns STATUS_SUCCESS.

Examples

The following code example gets processor relationship information for all the logical processors in a multiprocessor system:

//
// Get required buffer size.
//
NTSTATUS Status;
PSYSTEM_LOGICAL_PROCESSOR_INFORMATION_EX Info = NULL;
ULONG BufferSize = 0;
Status = KeQueryLogicalProcessorRelationship(NULL, RelationAll, NULL, &BufferSize);

NT_ASSERT(Status == STATUS_INFO_LENGTH_MISMATCH && BufferSize > 0);

//
// Allocate buffer (assume IRQL <= APC_LEVEL).
//
Info = ExAllocatePoolWithTag(PagedPool, BufferSize, ' gaT');
if (Info == NULL)
{
    Status = STATUS_INSUFFICIENT_RESOURCES;
}

//
// Get processor relationship information.
//
if (NT_SUCCESS(Status))
{
    Status = KeQueryLogicalProcessorRelationship(NULL, RelationAll, Info, &BufferSize);
}

The NT_ASSERT macro is defined in the Wdm.h header file. The NT_SUCCESS macro is defined in the Ntdef.h header file.

Requirements

See also

LOGICAL_PROCESSOR_RELATIONSHIP

PROCESSOR_NUMBER

SYSTEM_LOGICAL_PROCESSOR_INFORMATION_EX