NdisAllocateSpinLock-Funktion (ndis.h)

Artikel
02/07/2025

Die NdisAllocateSpinLock-Funktion initialisiert eine Variable vom Typ NDIS_SPIN_LOCK, die verwendet wird, um den Zugriff auf Ressourcen zu synchronisieren, die von nicht-ISR-Treiberfunktionen gemeinsam genutzt werden.

Syntax

void NdisAllocateSpinLock(
  [out] PNDIS_SPIN_LOCK SpinLock
);

Parameter

[out] SpinLock

Zeiger auf eine undurchsichtige Variable, die eine Drehsperre darstellt.

Rückgabewert

Nichts

Bemerkungen

Before a driver calls NdisAcquireSpinLock, NdisDprAcquireSpinLock, or any of the NdisInterlockedXxx functions, sie muss NdisAllocateSpinLock- aufrufen, um die spin lock zu initialisieren, die als erforderlicher Parameter an diese NdisXxx--Funktionen übergeben wird. Der Aufrufer muss nicht ausgelagerten Speicher für die Variable bei SpinLock bereitstellen.

Nach dem Aufrufen NdisAllocateSpinLock-kann der Treiber NdisAcquireSpinLock aufrufen, um die ausschließliche Verwendung der Ressource(n) zu erhalten, die die Drehsperre schützt. Wenn der Ressourcenzugriff abgeschlossen ist, ruft der Treiber NdisReleaseSpinLock auf, sodass andere Treiberfunktionen auf die durch diese Drehsperre geschützten Ressourcen zugreifen können.

In der Regel sollten zum Verbessern der Leistung eines Treibers unterschiedliche Sperren verwendet werden, um unterschiedliche kritische Abschnitte zu schützen. Daher kann ein Treiber mehrere Drehsperren mit NdisAllocateSpinLockinitialisieren.

Jede Drehsperre, die ein Treiber zuweist, schützt einen separaten Satz freigegebener Ressourcen vor gleichzeitigem Zugriff durch Treiberfunktionen, die bei IRQL-<= DISPATCH_LEVEL ausgeführt werden. Beispielsweise kann ein Treiber, der eine interne Warteschlange mit Paketen verwaltet, eine Drehsperre initialisieren, um die Warteschlange und eine andere zu schützen, um eine Reihe von Zustandsvariablen zu schützen, die mehrere Treiberfunktionen nicht enthalten, einschließlich der MiniportInterrupt oder MiniportDisableInterruptEx--Funktion zugreifen, während der Treiber Pakete verarbeitet.

NdisAcquireSpinLock löst die IRQL auf DISPATCH_LEVEL aus und speichert die alte IRQL in der Drehsperre. Durch Loslassen der Drehsperre wird der IRQL auf den wert festgelegt, der in der Drehsperre gespeichert ist. Da NDIS manchmal Treiber bei PASSIVE_LEVEL eingibt, können Probleme mit dem folgenden Code auftreten:

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

Ein Treiber sollte aus folgenden Gründen nicht auf Drehsperren in dieser Sequenz zugreifen:

Zwischen NdisReleaseSpinLock(A) und NdisReleaseSpinLock(B) wird der Code bei PASSIVE_LEVEL anstelle von DISPATCH_LEVEL ausgeführt und unterliegt unangemessenen Unterbrechungen.
Nach NdisReleaseSpinLock(B) wird der Code bei DISPATCH_LEVEL ausgeführt, wodurch der Aufrufer zu einem späteren Zeitpunkt mit einem IRQL_NOT_LESS_OR_EQUAL Stoppfehler fehler verursachen kann.

Ein Treiber sollte niemals zwei Drehsperren verwenden, um den gleichen (Unter)Satz von Ressourcen zu schützen, da geschachtelte Spin-Lock-Käufe so häufig zu Deadlocks führen. Selbst wenn ein Treiber entwickelt werden könnte, um Deadlocks zu verhindern, wirken sich geschachtelte Spin-Lock-Käufe negativ auf die Treiberleistung und den E/A-Durchsatz aus.

Ein Miniporttreiber kann keine Drehsperre verwenden, um Ressourcen zu schützen, die seine Nicht-ISR-Funktionen mit seinen MiniportInterrupt- oder MiniportDisableInterruptEx Funktion. Um auf Ressourcen zuzugreifen, die mit einer MiniportInterrupt oder MiniportDisableInterruptEx--Funktion gemeinsam genutzt werden, muss ein Miniporttreiber aufrufen NdisMSynchronizeWithInterruptEx MiniportSynchronizeInterrupt Funktion greifen auf diese Ressourcen bei DIRQL zu.

Wenn ein Treiber beispielsweise keinen Ressourcenschutz mehr erfordert, wenn eine NIC entfernt wird und der Treiber die für diese NIC zugewiesenen Ressourcen freigibt, ruft der Treiber NdisFreeSpinLockauf.

Das Freigeben einer Spin-Sperre und das Freigeben einer Drehsperre sind möglicherweise verwirrend. NdisFreeSpinLock den Speicher bei SpinLock- löscht, sodass es keine Drehsperre mehr darstellt. Durch das Freigeben einer erworbenen Drehsperre mit NdisReleaseSpinLock können Sie einfach einen anderen Ausführungsthread abrufen.

Weitere Informationen zum Abrufen und Freigeben von NDIS-Drehsperren finden Sie unter Synchronisierung und Benachrichtigung in Netzwerktreibern.

Aufrufer von NdisAllocateSpinLock- können bei jedem IRQL ausgeführt werden. Normalerweise wird ein Aufrufer bei IRQL = PASSIVE_LEVEL während der Initialisierung ausgeführt.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Unterstützt für NDIS 6.0- und NDIS 5.1-Treiber (siehe NdisAllocateSpinLock (NDIS 5.1)) in Windows Vista. Unterstützt für NDIS 5.1-Treiber (siehe NdisAllocateSpinLock (NDIS 5.1)) in Windows XP.
Zielplattform-	Universal
Header-	ndis.h (include Ndis.h)
Library	Ndis.lib
IRQL-	Beliebige Ebene (siehe Abschnitt "Hinweise")
DDI-Complianceregeln	SpinLockDpr(ndis), SpinLockDprRelease(ndis), SpinlockRelease(ndis)