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