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 |