Fonction KeSetSystemAffinityThreadEx (wdm.h)

La routine KeSetSystemAffinityThreadEx définit l’affinité système du thread actuel.

Syntaxe

KAFFINITY KeSetSystemAffinityThreadEx(
  [in] KAFFINITY Affinity
);

Paramètres

[in] Affinity

Variable de type KAFFINITY qui spécifie la nouvelle affinité système du thread actuel.

Valeur retournée

KeSetSystemAffinityThreadEx retourne soit l’affinité système précédente du thread actuel, soit zéro pour indiquer qu’il n’y avait aucune affinité système précédente.

Remarques

KeSetSystemAffinityThreadEx modifie le masque d’affinité du thread actif. Le masque d’affinité identifie un ensemble de processeurs sur lesquels le thread peut s’exécuter. En cas de réussite, la routine planifie l’exécution du thread sur un processeur de cet ensemble.

Les appelants de KeSetSystemAffinityThreadEx doivent enregistrer la valeur de retour et passer ultérieurement cette valeur à la routine KeRevertToUserAffinityThreadEx pour restaurer le masque d’affinité précédent.

Dans un système multiprocesseur, une routine de pilote en mode noyau qui s’exécute dans le contexte d’un thread en mode utilisateur peut avoir besoin d’appeler KeSetSystemAffinityThreadEx pour modifier temporairement le masque d’affinité du thread. Avant la sortie de la routine, elle doit appeler KeRevertToUserAffinityThreadEx pour restaurer le masque d’affinité du thread à sa valeur d’origine.

Le terme affinité utilisateur fait référence à l’affinité d’origine du thread en mode utilisateur. L’affinité définie par le pilote en mode noyau est appelée affinité système. Si un appel à KeSetSystemAffinityThreadEx remplace l’affinité utilisateur d’un thread par une affinité système, l’appel retourne zéro. Plus tard, le pilote restaure l’affinité utilisateur en appelant KeRevertToUserAffinityThreadEx et en passant cette valeur de retour (zéro) comme valeur Affinity .

En outre, une routine de pilote en mode noyau qui nécessite un masque d’affinité particulier peut appeler une autre routine en mode noyau qui nécessite un autre masque d’affinité. Chaque routine peut appeler KeSetSystemAffinityThreadEx pour définir un nouveau masque d’affinité, puis appeler KeRevertToUserAffinityThreadEx pour restaurer le masque d’affinité précédent avant de retourner.

La routine KeSetSystemAffinityThreadEx modifie le masque d’affinité du thread actif en valeur Affinity uniquement si les deux éléments suivants sont vrais :

• La valeur Affinity est valide (autrement dit, seuls les bits de masque correspondant aux processeurs logiques sont définis).
• Au moins un des processeurs spécifiés dans la valeur Affinity est actif.

Si l’une de ces conditions n’est pas remplie, l’appel à KeSetSystemAffinityThreadEx n’a aucun effet.

Windows 7 et versions ultérieures de Windows prennent en charge les groupes de processeurs. Les pilotes conçus pour gérer des informations sur les groupes de processeurs doivent utiliser la routine KeSetSystemGroupAffinityThread , qui spécifie un groupe de processeurs, au lieu de KeSetSystemAffinityThreadEx, ce qui n’est pas le cas. Toutefois, l’implémentation de KeSetSystemAffinityThreadEx dans Windows 7 et les versions ultérieures de Windows fournit la compatibilité pour les pilotes qui ont été écrits pour les versions antérieures de Windows, qui ne prennent pas en charge les groupes de processeurs. Dans cette implémentation, KeSetSystemAffinityThreadEx affecte le thread au groupe 0 et utilise le masque d’affinité pour spécifier un ensemble de processeurs logiques dans ce groupe sur lesquels le thread peut s’exécuter. La routine retourne le masque d’affinité relatif au groupe précédent, mais pas le groupe précédent.

Si KeSetSystemAffinityThreadEx est appelé à IRQL <= APC_LEVEL et que l’appel réussit, le nouveau masque d’affinité prend effet immédiatement. Lorsque l’appel est retourné, le thread appelant est déjà en cours d’exécution sur un processeur spécifié dans le nouveau masque d’affinité. Si KeSetSystemAffinityThreadEx est appelé au niveau IRQL = DISPATCH_LEVEL et que l’appel réussit, le changement de processeur en attente est différé jusqu’à ce que l’appelant réduise l’IRQL sous DISPATCH_LEVEL.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible dans Windows Vista et les versions plus récentes de Windows.
Plateforme cible	Universal
En-tête	wdm.h (inclure Wdm.h, Ntddk.h, Ntifs.h)
Bibliothèque	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= DISPATCH_LEVEL (voir la section Remarques).

Voir aussi

KAFFINITY

KeRevertToUserAffinityThreadEx

KeSetSystemAffinityThread

KeSetSystemGroupAffinityThread