NdisDprAcquireReadWriteLock, fonction (ndis.h)

Article
08/07/2023

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

Note L’interface de verrouillage en lecture-écriture est déconseillée pour les pilotes NDIS 6.20 et ultérieur, qui doivent utiliser NdisAcquireRWLockRead ou NdisAcquireRWLockWrite (paramètre NDIS_RWL_AT_DISPATCH_LEVEL dans le paramètre Flags ) au lieu de NdisDprAcquireReadWriteLock.

Syntaxe

void NdisDprAcquireReadWriteLock(
  [in, out] PNDIS_RW_LOCK Lock,
  [in]      BOOLEAN       fWrite,
  [out]     PLOCK_STATE   LockState
);

Paramètres

[in, out] Lock

Pointeur vers une variable opaque qui représente un verrou. L’appelant peut utiliser ce verrou pour accéder aux ressources partagées.

[in] fWrite

Valeur booléenne. Si la valeur est TRUE, cette fonction est fournie avec un accès en écriture aux ressources partagées ; si la valeur est FALSE, cette fonction est fournie avec un accès en lecture.

[out] LockState

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

Valeur de retour

None

Remarques

Le pilote doit initialiser une variable de type NDIS_RW_LOCK à l’aide du Fonction NdisInitializeReadWriteLock avant que le pilote appelle toute autre fonction NdisXxxReadWriteLock. Le pilote doit fournir un stockage résident pour les verrous qu’il utilise.

Après avoir acquis un verrou à l’aide de NdisDprAcquireReadWriteLock, l’appelant doit libérer ce verrou en appelant la fonction NdisDprReleaseReadWriteLock . Pour décrémenter le nombre de références du verrou, un pilote doit appeler
NdisDprReleaseReadWriteLock une fois pour chaque appel à NdisDprAcquireReadWriteLock.

Il est sûr d’utiliser NdisDprAcquireReadWriteLock et NdisDprAcquireReadWriteLock sur le même verrou. Toutefois, les appels doivent être équilibrés de sorte que si le verrou est acquis avec NdisDprAcquireReadWriteLock, il doit être libéré avec NdisDprReleaseReadWriteLock. De même, si le verrou est acquis avec NdisAcquireReadWriteLock, il doit être libéré avec NdisReleaseReadWriteLock.

Avec certaines architectures, NdisDprAcquireReadWriteLock fonctionne plus rapidement que NdisAcquireReadWriteLock. Les pilotes peuvent utiliser NdisDprAcquireReadWriteLock plutôt que NdisAcquireReadWriteLock lorsqu’il est certain que l’IRQL actuel est déjà DISPATCH_LEVEL. Toutefois, elle n’est pas obligatoire. La surcharge liée à l’appel de la fonction KeGetCurrentIrql est supérieure à l’avantage en matière de performances de l’appel de NdisDprAcquireReadWriteLock au lieu de NdisAcquireReadWriteLock.

Pour modifier les ressources partagées entre les threads de pilote, un thread de pilote doit acquérir un verrou d’écriture. Pour surveiller simplement ces ressources, un thread de pilote doit acquérir un verrou en lecture seule. L’accès en lecture ne nécessite pas d’opérations verrouillées ou de contention pour les verrous de rotation. L’utilisation de l’accès en lecture seule permet de maintenir de bonnes performances du système d’exploitation et des pilotes.

Un thread de pilote ne doit jamais contenir un verrou d’écriture pendant plus de 25 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 contre l’accès en lecture ou en écriture que ses autres fonctions partagent avec miniportInterrupt et/ou Fonctions MiniportDisableInterruptEx . Au lieu de cela, le pilote doit appeler NdisMSynchronizeWithInterruptEx pour que son La fonction MiniportSynchronizeInterrupt accède à ces ressources partagées au même niveau DIRQL auquel son
MiniportInterrupt et/ou Les fonctions MiniportDisableInterruptEx le font.

Pour plus d’informations sur l’acquisition et la publication de verrous de rotation NDIS, consultez Synchronisation et notification dans les pilotes réseau.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Déconseillé pour les pilotes NDIS 6.20 et ultérieur, qui doivent utiliser NdisAcquireRWLockRead ou NdisAcquireRWLockWrite au lieu de NdisDprAcquireReadWriteLock. Pris en charge dans NDIS 6.0 et 6.1.
Plateforme cible	Universal
En-tête	ndis.h (inclure Ndis.h)
Bibliothèque	Ndis.lib
IRQL	= DISPATCH_LEVEL