StorPortSetSystemGroupAffinityThread, fonction (storport.h)

Article
02/26/2024

StorPortSetSystemGroupAffinityThread modifie le numéro de groupe et le masque d’affinité du thread appelant.

Syntaxe

ULONG StorPortSetSystemGroupAffinityThread(
  [in]           PVOID                HwDeviceExtension,
  [in/optional]  PVOID                ThreadContext,
  [in]           PSTOR_GROUP_AFFINITY Affinity,
  [out/optional] PSTOR_GROUP_AFFINITY PreviousAffinity
);

Paramètres

[in] HwDeviceExtension

Pointeur vers l’extension de périphérique matériel du miniport.

[in/optional] ThreadContext

Pointeur vers le contexte de thread reçu lors d’un appel antérieur à StorPortCreateSystemThread.

[in] Affinity

Pointeur vers une structure de STOR_GROUP_AFFINITY allouée à l’appelant qui spécifie le nouveau numéro de groupe et le masque d’affinité relative au groupe pour le thread appelant.

[out/optional] PreviousAffinity

Pointeur vers une structure STOR_GROUP_AFFINITY dans laquelle cette routine écrit le numéro de groupe et le masque d’affinité pour le thread appelant avant l’appel. Ce paramètre est facultatif et peut être NULL.

Valeur retournée

StorPortSetSystemGroupAffinityThread retourne l’une des valeurs suivantes :

Code de retour	Description
STOR_STATUS_SUCCESS	L’affinité de groupe spécifiée a été définie avec succès.
STOR_STATUS_INVALID_PARAMETER	Un ou plusieurs des paramètres fournis ne sont pas valides.
STOR_STATUS_UNSUCCESSFUL	Retourné pour d’autres raisons système internes.

Remarques

Un miniport peut appeler StorPortSetSystemGroupAffinityThread pour modifier le numéro de groupe et le masque d’affinité au niveau du groupe du thread appelant.

Le numéro de groupe et le masque d’affinité dans la structure STOR_GROUP_AFFINITY pointée par Affinity identifient un ensemble de processeurs sur lesquels le thread peut s’exécuter. En cas de réussite, StorPortSetSystemGroupAffinityThread planifie l’exécution du thread sur un processeur de cet ensemble.

Si le paramètre PreviousAffinity n’a pas la valeur NULL, StorPortSetSystemGroupAffinityThread enregistre des informations sur l’affinité de groupe précédente, qui était en vigueur au début de l’appel, dans la structure STOR_GROUP_AFFINITY vers laquelle previousAffinity pointe. Pour restaurer l’affinité de thread précédente, l’appelant peut fournir le pointeur vers cette structure en tant que paramètre d’entrée pour la routine StorPortRevertToUserGroupAffinityThread .

Si un miniport appelle cette fonction pour modifier temporairement l’affinité de groupe du thread, elle doit appeler StorPortRevertToUserGroupAffinityThread pour rétablir l’affinité de thread à sa valeur d’origine avant la fermeture du thread.

Un thread ne peut être affecté qu’à une seule affinité de groupe à tout moment. Ce groupe est toujours dans l’affinité du processus du thread. Un thread peut modifier le groupe auquel il est affecté en appelant cette routine.

StorPortSetSystemGroupAffinityThread modifie le numéro de groupe et le masque d’affinité en valeurs spécifiées dans Affinity uniquement si les conditions suivantes sont remplies :

Le numéro de groupe est valide.
Le masque d’affinité est valide (autrement dit, seuls les bits de masque qui correspondent aux processeurs logiques du groupe sont définis).
Au moins un des processeurs spécifiés dans le masque d’affinité est actif.

Si l’une de ces conditions n’est pas remplie, le numéro de groupe et le masque d’affinité du thread restent inchangés. Si PreviousAffinity n’a pas la valeur NULL, la routine écrit zéro dans le numéro de groupe et le masque d’affinité dans PreviousAffinity.

Avant que le nouveau masque d’affinité dans Affinity ne prenne effet, StorPortSetSystemGroupAffinityThread supprime (définit sur zéro) tous les bits de masque d’affinité qui correspondent aux processeurs qui ne sont pas actifs actuellement. Dans un appel StorPortSetSystemGroupAffinityThread suivant, la valeur que la routine écrit dans PreviousAffinity peut contenir un masque d’affinité qui a été modifié de cette façon.

Si StorPortSetSystemGroupAffinityThread est appelé à IRQL <= APC_LEVEL et que l’appel réussit, la nouvelle affinité de groupe 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 la nouvelle affinité de groupe. Si StorPortSetSystemGroupAffinityThread est appelé à IRQL = DISPATCH_LEVEL et que l’appel réussit, la modification du processeur en attente est différée jusqu’à ce que l’appelant abaisse l’IRQL sous DISPATCH_LEVEL.