KeQueryLogicalProcessorRelationship, fonction (wdm.h)

  • Article

La routine KeQueryLogicalProcessorRelationship obtient des informations sur les relations d’un ou de plusieurs processeurs avec les autres processeurs dans un système multiprocesseur.

Syntaxe

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

Paramètres

[in, optional] ProcessorNumber

Pointeur vers une structure PROCESSOR_NUMBER qui identifie le processeur logique pour lequel l’appelant demande des informations de relation. Pour demander des informations sur tous les processeurs logiques du système, définissez ce paramètre sur NULL.

[in] RelationshipType

Spécifie le type d’informations de relation demandées par l’appelant. Définissez ce paramètre sur l’une des valeurs d’énumération LOGICAL_PROCESSOR_RELATIONSHIP suivantes :

  • RelationProcessorCore

  • RelationNumaNode

    À compter de Windows Server 2022, un groupe principal est affecté à chaque nœud NUMA. Les demandes de RelationNumaNode renvoient les structures RelationNumaNode qui contiennent une seule affinité de groupe, celle du groupe principal du nœud si aucun numéro de processeur n’est spécifié, celle du groupe contenant le processeur donné si un numéro de processeur est spécifié (GroupCount == 1, la taille de la structure est inchangée). Pour plus d’informations, consultez Prise en charge de KeQueryNodeActiveAffinity et NUMA.

  • RelationCache

  • RelationProcessorPackage

  • RelationGroup

  • RelationProcessorDie

  • RelationNumaNodeEx

  • RelationTous

    À compter de Windows Server 2022, les demandes de RelationNumaNodeEx ou RelationAll retournent les structures RelationNumaNode qui contiennent un tableau d’affinités pour le nœud sur tous les groupes (GroupCount indique le nombre d’affinités, la taille de la structure est variable). Pour plus d’informations, consultez Support NUMA.

[out, optional] Information

Pointeur vers une mémoire tampon allouée par l’appelant dans laquelle la routine écrit un tableau d’une ou plusieurs structures SYSTEM_LOGICAL_PROCESSOR_INFORMATION_EX qui contiennent les informations demandées par l’appelant. Si la fonction échoue, le contenu de cette mémoire tampon n’est pas défini. Définissez Information = NULL pour obtenir la longueur de mémoire tampon requise avant d’allouer la mémoire tampon. Pour plus d'informations, consultez la section Notes qui suit.

[in, out] Length

Pointeur vers un emplacement qui contient la taille, en octets, de la mémoire tampon pointée par Information. Lors de l’entrée, *Length contient la taille de la mémoire tampon allouée à l’appelant qui est pointée par Information. Pendant l’appel, la routine remplace la valeur pointée par Length par la taille de mémoire tampon requise pour contenir les informations de relation demandées.

Valeur retournée

KeQueryLogicalProcessorRelationship retourne STATUS_SUCCESS si l’appel réussit. Les valeurs de retour d’erreur possibles sont les suivantes :

Code de retour Description
STATUS_INVALID_PARAMETER Le paramètre ProcessorNumber pointe vers une structure PROCESSOR_NUMBER qui contient des informations non valides.
STATUS_INFO_LENGTH_MISMATCH La mémoire tampon allouée à l’appelant pointée par le paramètre Information n’est pas suffisamment grande pour contenir les informations de relation demandées.

Remarques

Pour déterminer la taille de mémoire tampon à allouer, appelez d’abord KeQueryLogicalProcessorRelationship avec Information = NULL et Length = 0. En réponse, la routine écrit la taille de mémoire tampon requise dans**Length et retourne STATUS_INFO_LENGTH_MISMATCH. Ensuite, allouez une mémoire tampon de la taille requise et appelez KeQueryLogicalProcessorRelationship une deuxième fois. Dans ce deuxième appel, définissez Information sur l’adresse de la mémoire tampon et *Longueur sur la taille de la mémoire tampon. Si le deuxième appel réussit, la routine écrit les informations de relation demandées dans la mémoire tampon et retourne STATUS_SUCCESS.

Exemples

L’exemple de code suivant obtient des informations de relation de processeur pour tous les processeurs logiques d’un système multiprocesseur :

//
// 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 est définie dans le fichier d’en-tête Wdm.h. La macro NT_SUCCESS est définie dans le fichier d’en-tête Ntdef.h.

Configuration requise

Condition requise Valeur
Client minimal pris en charge Disponible dans Windows 7 et versions ultérieures de Windows.
Plateforme cible Universal
En-tête wdm.h (inclure Ntddk.h, Wdm.h, Ntddk.h)
Bibliothèque NtosKrnl.lib
DLL NtosKrnl.exe
IRQL <= DISPATCH_LEVEL

Voir aussi

LOGICAL_PROCESSOR_RELATIONSHIP

PROCESSOR_NUMBER

SYSTEM_LOGICAL_PROCESSOR_INFORMATION_EX