Funzione KeQueryLogicalProcessorRelationship (wdm.h)
La routine KeQueryLogicalProcessorRelationship ottiene informazioni sulle relazioni tra 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 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 sulle relazioni richieste dal chiamante. Impostare questo parametro su uno dei valori di enumerazione LOGICAL_PROCESSOR_RELATIONSHIP seguenti:
RelationProcessorCore
RelationNumaNode
A partire da Windows Server 2022, a ogni nodo NUMA viene assegnato un gruppo primario. Le richieste di RelationNumaNode restituiranno strutture RelationNumaNode che contengono solo una singola affinità di gruppo, quella del gruppo primario del nodo se non è specificato un numero di processore, quella del gruppo contenente il processore specificato se è specificato un numero di processore (GroupCount == 1, la dimensione della struttura è invariata). Per altre informazioni, vedere KeQueryNodeActiveAffinity e NUMA Support.
RelationCache
RelationProcessorPackage
RelationGroup
RelationProcessorDie
RelationNumaNodeEx
RelationAll
A partire da Windows Server 2022, le richieste di RelationNumaNodeEx o RelationAll restituiranno strutture RelationNumaNode che contengono una matrice di affinità per il nodo su tutti i gruppi (GroupCount segnala il numero di affinità, la dimensione della struttura è variabile). Per altre informazioni, vedere NUMA Support.
[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 del buffer non è definito. Impostare Informazioni = NULL per ottenere la lunghezza del buffer necessaria prima di allocare il buffer. Per altre informazioni, vedere la sezione Osservazioni seguente.
[in, out] Length
Puntatore a una posizione contenente le dimensioni, in byte, del buffer a cui punta Informazioni. Nella voce *Lunghezza 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 sulle relazioni richieste.
Valore restituito
KeQueryLogicalProcessorRelationship restituisce STATUS_SUCCESS se la chiamata ha esito positivo. I possibili valori restituiti dall'errore includono quanto segue:
| Codice restituito | Descrizione |
|---|---|
| STATUS_INVALID_PARAMETER | Il parametro ProcessorNumber punta a una struttura PROCESSOR_NUMBER contenente informazioni non valide. |
| STATUS_INFO_LENGTH_MISMATCH | Il buffer allocato dal chiamante a cui punta il parametro Information non è sufficiente per contenere le informazioni sulle relazioni richieste. |
Osservazioni
Per determinare le dimensioni del buffer da allocare, chiamare inizialmente KeQueryLogicalProcessorRelationship con informazioni informazioni = NULL e Lunghezza = 0. In risposta, la routine scrive le dimensioni del buffer necessarie in**Lunghezza e restituisce STATUS_INFO_LENGTH_MISMATCH. Allocare quindi un buffer delle dimensioni necessarie e chiamare KeQueryLogicalProcessorRelationship una seconda volta. In questa seconda chiamata impostare Information sull'indirizzo del buffer e *Length sulla dimensione del buffer. Se la seconda chiamata ha esito positivo, la routine scrive le informazioni sulla relazione richieste nel buffer e restituisce STATUS_SUCCESS.
Esempi
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 viene definita nel file di intestazione Wdm.h. La macro NT_SUCCESS è definita nel file di intestazione Ntdef.h.
Fabbisogno
| 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 |