Funzione KeQueryLogicalProcessorRelationship (wdm.h)

Articolo
03/08/2023

La routine KeQueryLogicalProcessorRelationship ottiene informazioni sulle relazioni di uno o più processori con gli altri processori in un sistema multiprocessore.

Sintassi

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

Parametri

[in, optional] ProcessorNumber

Puntatore a una struttura di PROCESSOR_NUMBER che identifica il processore logico per cui il chiamante richiede informazioni sulla relazione. Per richiedere informazioni su tutti i processori logici nel sistema, impostare questo parametro su NULL.

[in] RelationshipType

Specifica il tipo di informazioni sulla relazione richieste dal chiamante. Impostare questo parametro su uno dei valori di enumerazione seguenti LOGICAL_PROCESSOR_RELATIONSHIP :

RelationProcessorCore
RelationNumaNode

A partire da Windows Server 2022, a ogni nodo NUMA viene assegnato un gruppo primario. Le richieste per RelationNumaNode restituiranno strutture RelationNumaNode che contengono solo un'affinità di gruppo singolo, quella del gruppo primario del nodo se non viene specificato un numero di processore, quella del gruppo contenente il processore specificato se viene specificato un numero di processore (GroupCount == 1, le dimensioni della struttura sono invariate). Per altre informazioni, vedi KeQueryNodeActiveAffinity e supporto NUMA.
RelationCache
RelationProcessorPackage
RelationGroup
RelationProcessorDie
RelationNumaNodeEx
RelationAll

A partire da Windows Server 2022, le richieste per RelationNumaNodeEx o RelationAll restituiranno le strutture RelationNumaNode che contengono una matrice di affinità per il nodo su tutti i gruppi (GroupCount segnala il numero di affinità, le dimensioni della struttura sono variabili). Per altre informazioni, vedi Supporto NUMA.

[out, optional] Information

Puntatore a un buffer allocato dal chiamante in cui la routine scrive una matrice di una o più strutture SYSTEM_LOGICAL_PROCESSOR_INFORMATION_EX che contengono le informazioni richieste dal chiamante. Se la funzione ha esito negativo, il contenuto di questo buffer non è definito. Impostare Information = NULL per ottenere la lunghezza del buffer necessaria prima di allocare il buffer. Per ulteriori informazioni, vedere la sezione Osservazioni successiva.

[in, out] Length

Puntatore a una posizione che contiene le dimensioni, in byte, del buffer a cui punta Informazioni. Nella voce *Length contiene le dimensioni del buffer allocato dal chiamante a cui punta Informazioni. Durante la chiamata, la routine sovrascrive il valore a cui punta Length con le dimensioni del buffer necessarie per contenere le informazioni sulla relazione richieste.

Valore restituito

KeQueryLogicalProcessorRelationship restituisce STATUS_SUCCESS se la chiamata ha esito positivo. I valori restituiti di errore possibili includono quanto segue:

Codice restituito	Descrizione
STATUS_INVALID_PARAMETER	Il parametro ProcessorNumber punta a una struttura PROCESSOR_NUMBER che contiene informazioni non valide.
STATUS_INFO_LENGTH_MISMATCH	Il buffer allocato dal chiamante a cui punta il parametro Information non è sufficiente per contenere le informazioni sulla relazione richieste.

Commenti

Per determinare le dimensioni del buffer da allocare, chiamare inizialmente KeQueryLogicalProcessorRelationship con Information = NULL e Length = 0. In risposta, la routine scrive le dimensioni del buffer necessarie in**Length e restituisce STATUS_INFO_LENGTH_MISMATCH. Allocare quindi un buffer delle dimensioni necessarie e chiamare KeQueryLogicalProcessorRelationship una seconda volta. In questa seconda chiamata impostare Informazioni sull'indirizzo del buffer e *Length sulle dimensioni del buffer. Se la seconda chiamata ha esito positivo, la routine scrive le informazioni sulla relazione richieste nel buffer e restituisce STATUS_SUCCESS.

Esempio

Nell'esempio di codice seguente vengono recuperate informazioni sulla relazione del processore per tutti i processori logici in un sistema multiprocessore:

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

La macro NT_ASSERT è definita nel file di intestazione Wdm.h. La macro NT_SUCCESS è definita nel file di intestazione Ntdef.h.

Requisiti

Requisito	Valore
Client minimo supportato	Disponibile in Windows 7 e versioni successive di Windows.
Piattaforma di destinazione	Universale
Intestazione	wdm.h (include Ntddk.h, Wdm.h, Ntddk.h)
Libreria	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL

Vedi anche

LOGICAL_PROCESSOR_RELATIONSHIP

PROCESSOR_NUMBER

SYSTEM_LOGICAL_PROCESSOR_INFORMATION_EX

Condividi tramite