KeQueryLogicalProcessorRelationship-Funktion (wdm.h)
Die KeQueryLogicalProcessorRelationship-Routine ruft Informationen über die Beziehungen eines oder mehrerer Prozessoren zu den anderen Prozessoren in einem Multiprozessorsystem ab.
Syntax
NTSTATUS KeQueryLogicalProcessorRelationship(
[in, optional] PPROCESSOR_NUMBER ProcessorNumber,
[in] LOGICAL_PROCESSOR_RELATIONSHIP RelationshipType,
[out, optional] PSYSTEM_LOGICAL_PROCESSOR_INFORMATION_EX Information,
[in, out] PULONG Length
);
Parameter
[in, optional] ProcessorNumber
Ein Zeiger auf eine PROCESSOR_NUMBER Struktur, die den logischen Prozessor identifiziert, für den der Aufrufer Beziehungsinformationen anfordert. Um Informationen zu allen logischen Prozessoren im System anzufordern, legen Sie diesen Parameter auf NULL fest.
[in] RelationshipType
Gibt den Typ der Beziehungsinformationen an, die vom Aufrufer angefordert werden. Legen Sie diesen Parameter auf einen der folgenden LOGICAL_PROCESSOR_RELATIONSHIP Enumerationswerte fest:
RelationProcessorCore
RelationNumaNode
Ab Windows Server 2022 wird jedem NUMA-Knoten eine primäre Gruppe zugewiesen. Anforderungen für RelationNumaNode geben RelationNumaNode-Strukturen zurück, die nur eine einzelne Gruppenaffinität enthalten, die der primären Gruppe des Knotens, wenn keine Prozessornummer angegeben wird, die der Gruppe, die den angegebenen Prozessor enthält, wenn eine Prozessornummer angegeben ist (GroupCount == 1, Größe der Struktur ist unverändert). Weitere Informationen finden Sie unter KeQueryNodeActiveAffinity und NUMA-Unterstützung.
RelationCache
RelationProcessorPackage
RelationGroup
RelationProcessorDie
RelationNumaNodeEx
RelationAll
Ab Windows Server 2022 geben Anforderungen für RelationNumaNodeEx oder RelationAllRelationNumaNode-Strukturen zurück, die ein Array von Affinitäten für den Knoten über alle Gruppen enthalten (GroupCount meldet die Anzahl von Affinitäten, die Größe der Struktur ist variabel). Weitere Informationen finden Sie unter NUMA-Support.
[out, optional] Information
Ein Zeiger auf einen vom Aufrufer zugewiesenen Puffer, in den die Routine ein Array aus einer oder mehreren SYSTEM_LOGICAL_PROCESSOR_INFORMATION_EX Strukturen schreibt, die die vom Aufrufer angeforderten Informationen enthalten. Wenn die Funktion fehlschlägt, ist der Inhalt dieses Puffers undefiniert. Legen Sie Information = NULL fest, um die erforderliche Pufferlänge abzurufen, bevor Sie den Puffer zuweisen. Weitere Informationen finden Sie im folgenden Abschnitt "Hinweise".
[in, out] Length
Ein Zeiger auf einen Speicherort, der die Größe des Puffers in Bytes enthält, auf den von Information verwiesen wird. Beim Eintrag enthält *Length die Größe des vom Aufrufer zugewiesenen Puffers, auf den durch Information verwiesen wird. Während des Aufrufs überschreibt die Routine den Wert, auf den von Length mit der Puffergröße verwiesen wird, die erforderlich ist, um die angeforderten Beziehungsinformationen zu enthalten.
Rückgabewert
KeQueryLogicalProcessorRelationship gibt STATUS_SUCCESS zurück, wenn der Aufruf erfolgreich ist. Mögliche Fehlerrückgabewerte sind:
| Rückgabecode | Beschreibung |
|---|---|
| STATUS_INVALID_PARAMETER | Der ProcessorNumber-Parameter verweist auf eine PROCESSOR_NUMBER Struktur, die ungültige Informationen enthält. |
| STATUS_INFO_LENGTH_MISMATCH | Der vom Aufrufer zugewiesene Puffer, auf den der Parameter Information verweist, ist nicht groß genug, um die angeforderten Beziehungsinformationen zu enthalten. |
Hinweise
Um die zuzuordnende Puffergröße zu bestimmen, rufen Sie zunächst KeQueryLogicalProcessorRelationship mit Information = NULL und Length = 0 auf. Als Antwort schreibt die Routine die erforderliche Puffergröße in**Length und gibt STATUS_INFO_LENGTH_MISMATCH zurück. Ordnen Sie als Nächstes einen Puffer der erforderlichen Größe zu, und rufen Sie KeQueryLogicalProcessorRelationship ein zweites Mal auf. Legen Sie in diesem zweiten Aufruf Information auf die Pufferadresse und *Length auf die Puffergröße fest. Wenn der zweite Aufruf erfolgreich ist, schreibt die Routine die angeforderten Beziehungsinformationen in den Puffer und gibt STATUS_SUCCESS zurück.
Beispiele
Im folgenden Codebeispiel werden Prozessorbeziehungsinformationen für alle logischen Prozessoren in einem Multiprozessorsystem abgerufen:
//
// 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);
}
Das NT_ASSERT Makros ist in der Headerdatei Wdm.h definiert. Das NT_SUCCESS Makros ist in der Headerdatei Ntdef.h definiert.
Anforderungen
| Anforderung | Wert |
|---|---|
| Unterstützte Mindestversion (Client) | Verfügbar in Windows 7 und späteren Windows-Versionen. |
| Zielplattform | Universell |
| Header | wdm.h (include Ntddk.h, Wdm.h, Ntddk.h) |
| Bibliothek | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | <= DISPATCH_LEVEL |