NdisAcquireRWLockRead, fonction (ndis.h)

Article
02/26/2024

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

Syntaxe

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

Paramètres

[in] Lock

Pointeur vers une variable opaque NDIS_RW_LOCK_EX 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 pilotes non ISR.

[out] LockState

Pointeur vers une variable opaque LOCK_STATE_EX qui suit 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 verrouillage. 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 répartition, 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 de permettre à la fonction NdisAcquireRWLockRead de tester l’IRQL elle-même.

Valeur de retour

None

Remarques

Les pilotes NDIS appellent la fonction NdisAcquireRWLockRead pour obtenir un accès en lecture seule aux 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 NdisAcquireRWLockRead .

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 titulaire de l’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 de lecture NDIS_RW_LOCK_EX peut être acquis de manière récursive sur le même processeur. Pour chaque appel à NdisAcquireRWLockRead, il doit y avoir un appel correspondant à NdisReleaseRWLock. Le verrou n’est libéré qu’après le dernier appel à NdisReleaseRWLock.

Le pilote ne peut pas utiliser de verrou pour protéger les ressources de l’accès en lecture ou en écriture que ses autres fonctions partagent avec le MiniportInterrupt ou Fonction 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 Fonctions MiniportDisableInterruptEx , ou les deux.

NdisAcquireRWLockRead élève toujours l’IRQL sur IRQL = DISPATCH_LEVEL.

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