NdisAcquireRWLockWrite, fonction (ndis.h)

Article
02/29/2024

La fonction NdisAcquireRWLockWrite obtient un verrou d’écriture que l’appelant utilise pour l’accès en écriture aux ressources partagées entre les threads de pilote.

Syntaxe

void NdisAcquireRWLockWrite(
  [in]  PNDIS_RW_LOCK_EX Lock,
  [out] PLOCK_STATE_EX   LockState,
  [in]  UCHAR            Flags
);

Paramètres

[in] Lock

Pointeur vers une variable NDIS_RW_LOCK_EX opaque qui représente un verrou. L’appelant peut utiliser ce verrou pour obtenir un accès en écriture ou en lecture aux ressources partagées entre des threads de pilote non-ISR.

[out] LockState

Pointeur vers une variable opaque LOCK_STATE_EX qui effectue le suivi de l’état du verrou. Cette variable existe dans l’intervalle entre le moment où l’appelant obtient et libère le verrou. L’appelant doit utiliser une variable différente de type LOCK_STATE_EX pour chaque tentative d’obtention du verrou à partir du même thread de pilote non-ISR.

[in] Flags

Valeur ULONG qui contient des indicateurs de verrou. Définissez ce paramètre sur NDIS_RWL_AT_DISPATCH_LEVEL si l’IRQL actuel de l’appelant est DISPATCH_LEVEL. Sinon, définissez ce paramètre sur zéro. Pour plus d’informations sur le suivi IRQL de dispatch, consultez Dispatch IRQL Tracking.

Note Si l’appelant sait que l’IRQL actuel est DISPATCH_LEVEL, définissez ce paramètre sur NDIS_RWL_AT_DISPATCH_LEVEL. Cet indicateur rend le verrou encore plus efficace en l’obligeant à omettre un case activée pour l’IRQL actuel. Si l’IRQL actuel est inconnu, ne testez pas l’IRQL actuel avec KeGetCurrentIrql uniquement pour déterminer s’il faut définir cet indicateur, car il est plus efficace d’autoriser la fonction NdisAcquireRWLockWrite à tester l’IRQL elle-même.

Valeur de retour

None

Remarques

Les pilotes NDIS appellent la fonction NdisAcquireRWLockWrite pour modifier les ressources partagées entre les threads de pilotes.

Le pilote doit allouer une variable de type NDIS_RW_LOCK_EX avec la fonction NdisAllocateRWLock avant que le pilote appelle la fonction NdisAcquireRWLockWrite . Le pilote doit fournir un handle à NdisAllocateRWLock pour le stockage résident des verrous qu’il utilise.

Une fois que le pilote a appelé NdisAllocateRWLock, il peut appeler NdisAcquireRWLockWrite ou NdisAcquireRWLockRead pour obtenir un accès en écriture ou en lecture à la ressource. Un seul thread de pilote non ISR à la fois peut obtenir un accès en écriture à la ressource. Lorsqu’un thread non-ISR dispose d’un accès en écriture, tous les accès en lecture et en écriture par d’autres threads non-ISR doivent attendre que le détenteur d’accès en écriture libère le verrou. Toutefois, si un thread non-ISR dispose d’un accès en lecture, d’autres threads non-ISR peuvent obtenir simultanément un accès en lecture.

Le verrou NDIS_RW_LOCK_EX ne prend pas en charge la promotion de la lecture à l’écriture. Une fois qu’un processeur a acquis un NDIS_RW_LOCK_EX pour l’accès en lecture (en appelant NdisAcquireRWLockRead), le même processeur ne doit pas tenter d’acquérir l’accès en écriture (en appelant NdisAcquireRWLockWrite) tant que l’accès en lecture précédent n’est pas libéré.

Un verrou d’écriture NDIS_RW_LOCK_EX peut être acquis de manière récursive sur le même processeur. Pour chaque appel à NdisAcquireRWLockWrite, il doit y avoir un appel correspondant à NdisReleaseRWLock. Le verrou est libéré uniquement après le dernier appel à NdisReleaseRWLock.

Un thread de pilote ne doit jamais contenir un verrou d’écriture pendant plus de quelques microsecondes. La conservation d’un verrou d’écriture pendant une période prolongée dégrade les performances du système d’exploitation et du pilote.

Le pilote ne peut pas utiliser un verrou pour protéger les ressources de l’accès en lecture ou en écriture que ses autres fonctions partagent avec miniportInterrupt ou Fonctions MiniportDisableInterruptEx , ou les deux. Au lieu de cela, le pilote doit appeler NdisMSynchronizeWithInterruptEx afin que son La fonction MiniportSynchronizeInterrupt accède à ces ressources partagées au même niveau DIRQL que son MiniportInterrupt ou Les fonctions MiniportDisableInterruptEx , ou les deux, font.

NdisAcquireRWLockWrite déclenche l’IRQL pour DISPATCH_LEVEL en obtenant un verrou de rotation.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Pris en charge dans NDIS 6.20 et versions ultérieures.
Plateforme cible	Universal
En-tête	ndis.h (inclure Ndis.h)
Bibliothèque	Ndis.lib
IRQL	<= DISPATCH_LEVEL