KeQueryLogicalProcessorRelationship, fonction (wdm.h)
La routine KeQueryLogicalProcessorRelationship obtient des informations sur les relations d’un ou 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, chaque nœud NUMA est affecté à un groupe principal. Les demandes d'RelationNumaNode retournent 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é, celui du groupe contenant le processeur donné si un nombre de processeurs est spécifié (GroupCount == 1, la taille de la structure n’est pas modifiée). Pour plus d’informations, consultez KeQueryNodeActiveAffinity et support NUMA.
relationCache
RelationProcessorPackage
RelationGroup
RelationProcessorDie
RelationNumaNodeEx
RelationAll
À compter de Windows Server 2022, les demandes de RelationNumaNodeEx ou RelationAll retournent structures RelationNumaNode qui contiennent un tableau d’affinités pour le nœud sur tous les groupes (GroupCount signale le nombre d’affinités, la taille de la structure est variable). Pour plus d’informations, consultez prise en charge de 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 Informations = NULL pour obtenir la longueur de mémoire tampon requise avant d’allouer la mémoire tampon. Pour plus d’informations, consultez la section Remarques suivante.
[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 par l’appelant pointé par Information. Pendant l’appel, la routine remplace la valeur pointée par Longueur avec la taille de mémoire tampon requise pour contenir les informations de relation demandées.
Valeur de retour
KeQueryLogicalProcessorRelationship retourne STATUS_SUCCESS si l’appel réussit. Les valeurs de retour d’erreur possibles sont les suivantes :
| Retourner le code | 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 par l’appelant qui est 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 la mémoire tampon à allouer, appelez initialement 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 Informations 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 dans 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.
Exigences
| Exigence | Valeur |
|---|---|
| client minimum pris en charge | Disponible dans Windows 7 et versions ultérieures de Windows. |
| plateforme cible | Universel |
| d’en-tête | wdm.h (include Ntddk.h, Wdm.h, Ntddk.h) |
| bibliothèque | NtosKrnl.lib |
| DLL | NtosKrnl.exe |
| IRQL | <= DISPATCH_LEVEL |