Funzione KeQueryLogicalProcessorRelationship (wdm.h)
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 |