KeQueryLogicalProcessorRelationship - NtDoc

Native API online documentation, based on the System Informer (formerly Process Hacker) phnt headers
// wdm.h

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

View the official Windows Driver Kit DDI reference

NtDoc

No description available.

Windows Driver Kit DDI reference (nf-wdm-kequerylogicalprocessorrelationship)

Description

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

Parameters

ProcessorNumber [in, optional]

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.

RelationshipType [in]

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:

Information [out, optional]

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.

Length [in, out]

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:

Return code Description
STATUS_INVALID_PARAMETER The ProcessorNumber parameter points to a PROCESSOR_NUMBER structure that contains invalid information.
STATUS_INFO_LENGTH_MISMATCH The caller-allocated buffer that is pointed to by the Information parameter is not large enough to contain the requested relationship information.

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 toLength* 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.

See also

LOGICAL_PROCESSOR_RELATIONSHIP

PROCESSOR_NUMBER

SYSTEM_LOGICAL_PROCESSOR_INFORMATION_EX