Função KeQueryLogicalProcessorRelationship (wdm.h)

A rotina KeQueryLogicalProcessorRelationship obtém informações sobre as relações de um ou mais processadores com os outros processadores em um sistema multiprocessador.

Sintaxe

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

Parâmetros

[in, optional] ProcessorNumber

Um ponteiro para uma estrutura PROCESSOR_NUMBER que identifica o processador lógico para o qual o chamador solicita informações de relação. Para solicitar informações sobre todos os processadores lógicos no sistema, defina esse parâmetro como NULL.

[in] RelationshipType

Especifica o tipo de informações de relação solicitadas pelo chamador. Defina esse parâmetro como um dos seguintes valores de enumeração LOGICAL_PROCESSOR_RELATIONSHIP :

• RelationProcessorCore

• RelationNumaNode

  A partir do Windows Server 2022, cada nó NUMA recebe um grupo primário. As solicitações para RelationNumaNode retornarão estruturas RelationNumaNode que contêm apenas uma afinidade de grupo única, a do grupo primário do nó se um número de processador não for especificado, o do grupo que contém o processador determinado se um número de processador for especificado (GroupCount == 1, o tamanho da estrutura não será alterado). Para obter mais informações, consulte KeQueryNodeActiveAffinity e Suporte NUMA.

• RelationCache

• RelationProcessorPackage

• RelationGroup

• RelationProcessorDie

• RelationNumaNodeEx

• RelationAll

  A partir do Windows Server 2022, as solicitações para RelationNumaNodeEx ou RelationAll retornarão estruturas RelationNumaNode que contêm uma matriz de afinidades para o nó em todos os grupos (GroupCount relata o número de afinidades, o tamanho da estrutura é variável). Para obter mais informações, consulte Suporte a NUMA.

[out, optional] Information

Um ponteiro para um buffer alocado pelo chamador no qual a rotina grava uma matriz de uma ou mais estruturas SYSTEM_LOGICAL_PROCESSOR_INFORMATION_EX que contêm as informações solicitadas pelo chamador. Se a função falhar, o conteúdo desse buffer será indefinido. Defina Informações = NULL para obter o comprimento do buffer necessário antes de alocar o buffer. Para obter mais informações, consulte a seção Comentários a seguir.

[in, out] Length

Um ponteiro para um local que contém o tamanho, em bytes, do buffer apontado por Informações. Na entrada, *Length contém o tamanho do buffer alocado pelo chamador apontado por Informações. Durante a chamada, a rotina substitui o valor apontado por Length pelo tamanho do buffer necessário para conter as informações de relação solicitadas.

Retornar valor

KeQueryLogicalProcessorRelationship retornará STATUS_SUCCESS se a chamada for bem-sucedida. Os possíveis valores retornados por erro incluem o seguinte:

Código de retorno	Descrição
STATUS_INVALID_PARAMETER	O parâmetro ProcessorNumber aponta para uma estrutura PROCESSOR_NUMBER que contém informações inválidas.
STATUS_INFO_LENGTH_MISMATCH	O buffer alocado pelo chamador apontado pelo parâmetro Information não é grande o suficiente para conter as informações de relação solicitadas.

Comentários

Para determinar o tamanho do buffer a ser alocado, inicialmente chame KeQueryLogicalProcessorRelationship com Information = NULL e Length = 0. Em resposta, a rotina grava o tamanho do buffer necessário em**Comprimento e retorna STATUS_INFO_LENGTH_MISMATCH. Em seguida, aloque um buffer do tamanho necessário e chame KeQueryLogicalProcessorRelationship uma segunda vez. Nesta segunda chamada, defina Informações como o endereço do buffer e *Comprimento para o tamanho do buffer. Se a segunda chamada for bem-sucedida, a rotina gravará as informações de relação solicitadas no buffer e retornará STATUS_SUCCESS.

Exemplos

O exemplo de código a seguir obtém informações de relação do processador para todos os processadores lógicos em um sistema multiprocessador:

//
// 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);
}

A macro NT_ASSERT é definida no arquivo de cabeçalho Wdm.h. A macro NT_SUCCESS é definida no arquivo de cabeçalho Ntdef.h.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Disponível no Windows 7 e versões posteriores do Windows.
Plataforma de Destino	Universal
Cabeçalho	wdm.h (inclua Ntddk.h, Wdm.h, Ntddk.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL

Confira também

LOGICAL_PROCESSOR_RELATIONSHIP

PROCESSOR_NUMBER

SYSTEM_LOGICAL_PROCESSOR_INFORMATION_EX