NdisAllocateSpinLock, fonction (ndis.h)

Article
02/07/2025

La fonction NdisAllocateSpinLock initialise une variable de type NDIS_SPIN_LOCK, utilisée pour synchroniser l’accès aux ressources partagées entre les fonctions de pilote non-ISR.

Syntaxe

void NdisAllocateSpinLock(
  [out] PNDIS_SPIN_LOCK SpinLock
);

Paramètres

[out] SpinLock

Pointeur vers une variable opaque qui représente un verrou de rotation.

Valeur de retour

Aucun

Remarques

Avant qu’un pilote appelle NdisAcquireSpinLock, NdisDprAcquireSpinLock, ou l’une des fonctions NdisInterlockedXxx, elle doit appeler NdisAllocateSpinLock pour initialiser le verrou de rotation passé en tant que paramètre requis à ces fonctions NdisXxx. L’appelant doit fournir un stockage non paginé pour la variable à SpinLock .

Après avoir appelé NdisAllocateSpinLock, le pilote peut appeler NdisAcquireSpinLock pour obtenir une utilisation exclusive des ressources protégées par le verrou de rotation. Une fois l’accès aux ressources terminé, le pilote appelle NdisReleaseSpinLock afin que d’autres fonctions de pilote puissent accéder aux ressources protégées par ce verrou de rotation.

En règle générale, pour améliorer les performances, un pilote doit utiliser différents verrous pour protéger différentes sections critiques. Par conséquent, un pilote peut initialiser plusieurs verrous spin avec NdisAllocateSpinLock.

Chaque verrou de rotation qu’un pilote alloue protège un ensemble discret de ressources partagées contre l’accès simultané par les fonctions de pilote qui s’exécutent à IRQL <= DISPATCH_LEVEL. Par exemple, un pilote qui gère une file d’attente interne de paquets peut initialiser un verrou de rotation pour protéger sa file d’attente et un autre pour protéger un ensemble de variables d’état que plusieurs fonctions de pilote, sans inclure la MiniportInterrupt ou MiniportDisableInterruptEx fonction, l’accès pendant le traitement des paquets par le pilote.

NdisAcquireSpinLock déclenche l’IRQL à DISPATCH_LEVEL et stocke l’ancien IRQL dans le verrou de rotation. La libération du verrou de rotation définit l’IRQL sur la valeur stockée dans le verrou de rotation. Étant donné que NDIS entre parfois des pilotes à PASSIVE_LEVEL, les problèmes peuvent survenir avec le code suivant :

NdisAcquireSpinLock(A);
NdisAcquireSpinLock(B);
NdisReleaseSpinLock(A);
NdisReleaseSpinLock(B);

Un pilote ne doit pas accéder aux verrous de rotation dans cette séquence pour les raisons suivantes :

Entre NdisReleaseSpinLock(A) et NdisReleaseSpinLock(B) le code s’exécute à PASSIVE_LEVEL au lieu de DISPATCH_LEVEL et est soumis à une interruption inappropriée.
Après NdisReleaseSpinLock(B) le code est en cours d’exécution à DISPATCH_LEVEL ce qui peut provoquer l’erreur de l’appelant à un moment donné avec une erreur d’arrêt IRQL_NOT_LESS_OR_EQUAL.

Un pilote ne doit jamais utiliser deux verrous de rotation pour protéger le même (sous-ensemble de ressources), car les acquisitions de verrous de rotation imbriquées provoquent fréquemment des interblocages. Même si un pilote peut être conçu pour empêcher les interblocages, les acquisitions de verrous de rotation imbriquées ont un effet négatif sur les performances du pilote et le débit d’E/S.

Un pilote miniport ne peut pas utiliser un verrou de rotation pour protéger les ressources que ses fonctions non ISR partagent avec son MiniportInterrupt ou fonction MiniportDisableInterruptEx. Pour accéder aux ressources partagées avec une fonction MiniportInterrupt ou MiniportDisableInterruptEx, un pilote miniport doit appeler NdisMSynchronizeWithInterruptEx d’avoir MiniportSynchronizeInterrupt fonction accèdent à ces ressources dans DIRQL.

Lorsqu’un pilote ne nécessite plus de protection des ressources, par exemple lorsqu’une carte réseau est supprimée et que le pilote libère les ressources qu’il a allouées pour cette carte réseau, le pilote appelle NdisFreeSpinLock.

La libération d’un verrou de rotation et la libération d’un verrou de rotation sont potentiellement déroutantes. NdisFreeSpinLock efface la mémoire à SpinLock afin qu’elle ne représente plus un verrou de rotation. La libération d’un verrou de rotation acquis avec NdisReleaseSpinLock permet simplement à un autre thread d’exécution d’acquérir ce verrou de rotation.

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

Les appelants de NdisAllocateSpinLock peuvent s’exécuter à n’importe quel irQL. En règle générale, un appelant s’exécute à IRQL = PASSIVE_LEVEL lors de l’initialisation.

Exigences

Exigence	Valeur
client minimum pris en charge	Pris en charge pour les pilotes NDIS 6.0 et NDIS 5.1 (voir NdisAllocateSpinLock (NDIS 5.1)) dans Windows Vista. Pris en charge pour les pilotes NDIS 5.1 (voir NdisAllocateSpinLock (NDIS 5.1)) dans Windows XP.
plateforme cible	Universel
d’en-tête	ndis.h (include Ndis.h)
bibliothèque	Ndis.lib
IRQL	N’importe quel niveau (voir section Remarques)
règles de conformité DDI	SpinLockDpr(ndis), SpinLockDprRelease(ndis), SpinlockRelease(ndis)