NdisAllocateRWLock-Funktion (ndis.h)

Artikel
02/29/2024

Die NdisAllocateRWLock-Funktion weist eine Lese-/Schreibsperrevariable vom Typ NDIS_RW_LOCK_EX zu.

Syntax

PNDIS_RW_LOCK_EX NdisAllocateRWLock(
  NDIS_HANDLE NdisHandle
);

Parameter

NdisHandle

Ein Handle, das von einer der folgenden Funktionen zurückgegeben wird:

NdisMRegisterMiniportDriver
MiniportInitializeEx
NdisRegisterProtocolDriver
NdisOpenAdapterEx
NdisFRegisterFilterDriver
FilterAttach
Windows 8 und Windows Server 2012 und höher: Wenn die Lese-/Schreibsperre in DriverEntry zugewiesen wird, bevor ein NDIS-Handle verfügbar ist, kann der Aufrufer einen NULL-Wert für diesen Parameter übergeben.

Rückgabewert

NdisAllocateRWLock gibt einen Zeiger auf eine NDIS_RW_LOCK_EX-Struktur zurück, sofern eine zuordnung möglich ist. Andernfalls wird NULL zurückgegeben.

Hinweise

NDIS-Treiber rufen die NdisAllocateRWLock-Funktion auf, um eine NDIS_RW_LOCK_EX Struktur zuzuweisen, die den Lese-/Schreibzugriff auf Ressourcen steuert, die von Treiberthreads gemeinsam genutzt werden. Treiber verwenden eine Lese-/Schreibsperre für Ressourcen, auf die häufig zum Lesen zugegriffen wird und auf die selten zum Schreiben zugegriffen wird.

Jede Sperre, die ein Treiber ordnet, kann eine der folgenden Aktionen ausführen:

Schützen Sie eine diskrete Gruppe freigegebener Ressourcen vor dem gleichzeitigen Schreib- und Lesezugriff durch Treiberthreads, die bei IRQL <= DISPATCH_LEVEL ausgeführt werden.
Machen Sie einen diskreten Satz freigegebener Ressourcen für den gleichzeitigen Lesezugriff durch Treiberthreads verfügbar, die unter IRQL <= DISPATCH_LEVEL ausgeführt werden.

Der NDIS_RW_LOCK_EX Zeiger, den NdisAllocateRWLock zurückgibt, ist ein erforderlicher Parameter für alle anderen Funktionen der Lese-/Schreibsperre.

Eine NDIS_RW_LOCK_EX ist nicht fair. Das heißt, ein Prozessor, der auf den Erwerb der Sperre für den exklusiven Zugriff wartet, kann von Prozessoren ausgehungert werden, die die Sperre für den Lesezugriff halten. Verwenden Sie daher keine NDIS_RW_LOCK_EX in Situationen, in denen die meisten Zugriffe für den Schreibzugriff verwendet werden. Wenn die Mehrheit der Zugriffe Schreibzugriff benötigt, ist es effizienter, einfach eine Kernel-Spinsperre zu verwenden. Weitere Informationen zu Drehsperren finden Sie unter Einführung in Spin Locks.

In Situationen, in denen es viele Käufe für den Lesezugriff auf mehr als einem Prozessor gibt, ist die NDIS_RW_LOCK_EX in der Regel besser als eine Kernel-Spinsperre. Verwenden Sie NDIS_RW_LOCK_EX , wenn Sie viele Lesezugriffe pro Sekunde erwarten, die auf mehrere Prozessoren verteilt sind.

Eine NDIS_RW_LOCK_EX-Struktur definiert Attribute, die den Schreibzugriff auf freigegebene Ressourcen auf jeweils einen Nicht-ISR-Treiberthread beschränken. Die NDIS_RW_LOCK_EX-Struktur kann mehreren Nicht-ISR-Treiberthreads gleichzeitigen Lesezugriff auf die zugeordneten Ressourcen ermöglichen. Ein solcher Lesezugriff ist während eines Schreibzugriffs nicht zulässig.

Um die geschützten Ressourcen zu ändern, muss ein Treiberthread eine Schreibsperre mit der Funktion NdisAcquireRWLockWrite erhalten. Um diese Ressourcen einfach zu lesen, muss ein Treiberthread eine schreibgeschützte Sperre mit der NdisAcquireRWLockRead-Funktion erhalten. Für den Lesezugriff sind keine verriegelten Vorgänge oder Konflikte für Drehsperren erforderlich. Schreibgeschützter Zugriff trägt dazu bei, eine gute Betriebssystem- und Treiberleistung aufrechtzuerhalten.

Nachdem der Ressourcenzugriff abgeschlossen ist, ruft der Treiber die NdisReleaseRWLock-Funktion auf.

Ein Treiber muss die NdisFreeRWLock-Funktion aufrufen, um die NDIS_RW_LOCK_EX-Struktur freizusetzen, die er der NdisAllocateRWLock-Funktion zugeordnet hat.

Sie können die Debuggererweiterung "!ndiskd.ndisrwlock " verwenden, um einen NDIS_RW_LOCK_EX zu überprüfen, die Anzahl der Leser zu überprüfen und zu ermitteln, wer der aktuelle Writer ist. Weitere Informationen finden Sie unter NDIS-Erweiterungen (Ndiskd.dll).

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Unterstützt in NDIS 6.20 und höher.
Zielplattform	Universell
Header	ndis.h (einschließlich Ndis.h)
Bibliothek	Ndis.lib
IRQL	<=DISPATCH_LEVEL