KeQueryLogicalProcessorRelationship-Funktion (wdm.h)

  • Artikel

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

Weitere Informationen

LOGICAL_PROCESSOR_RELATIONSHIP

PROCESSOR_NUMBER

SYSTEM_LOGICAL_PROCESSOR_INFORMATION_EX