NdisAcquireRWLockRead-Funktion (ndis.h)

Artikel
02/07/2025

Die NdisAcquireRWLockRead--Funktion ruft eine Lesesperre ab, die der Aufrufer für den Lesezugriff auf Ressourcen verwendet, die von Treiberthreads gemeinsam genutzt werden.

Syntax

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

Parameter

[in] Lock

Ein Zeiger auf eine undurchsichtige NDIS_RW_LOCK_EX Variable, die eine Sperre darstellt. Der Aufrufer kann diese Sperre verwenden, um Schreib- oder Lesezugriff auf Ressourcen zu erhalten, die zwischen Nicht-ISR-Treiberthreads gemeinsam genutzt werden.

[out] LockState

Ein Zeiger auf eine undurchsichtige LOCK_STATE_EX Variable, die den Zustand der Sperre nachverfolgt. Diese Variable ist im Intervall zwischen den Zeiten vorhanden, die der Aufrufer abruft und die Sperre loslässt. Der Aufrufer muss eine andere Variable vom Typ LOCK_STATE_EX für jeden Versuch verwenden, den er zum Abrufen der Sperre aus demselben Nicht-ISR-Treiberthread vorgibt.

[in] Flags

Ein ULONG- Wert, der Sperrkennzeichnungen enthält. Legen Sie diesen Parameter auf NDIS_RWL_AT_DISPATCH_LEVEL fest, wenn der aktuelle IRQL-Wert des Aufrufers DISPATCH_LEVEList. Legen Sie andernfalls diesen Parameter auf Null fest. Weitere Informationen zur IRQL-Verteilerverfolgung finden Sie unter IRQL Tracking.

Hinweis Wenn der Aufrufer weiß, dass der aktuelle IRQL DISPATCH_LEVEList, legen Sie diesen Parameter auf NDIS_RWL_AT_DISPATCH_LEVELfest. Mit diesem Kennzeichen wird die Sperre noch effizienter, da dadurch eine Überprüfung auf die aktuelle IRQL weggelassen wird. Wenn die aktuelle IRQL unbekannt ist, testen Sie den aktuellen IRQL nicht mit KeGetCurrentIrql ausschließlich, um festzustellen, ob dieses Flag festgelegt werden soll, da es effizienter ist, die NdisAcquireRWLockRead--Funktion zum Testen des IRQL selbst zuzulassen.

Rückgabewert

Nichts

Bemerkungen

NDIS-Treiber rufen die NdisAcquireRWLockRead--Funktion auf, um schreibgeschützten Zugriff auf Ressourcen abzurufen, die zwischen Treiberthreads gemeinsam genutzt werden.

Der Treiber muss eine Variable vom Typ NDIS_RW_LOCK_EX mit der NdisAllocateRWLock-Funktion zuweisen, bevor der Treiber die NdisAcquireRWLockRead--Funktion aufruft.

Nachdem der Treiber NdisAllocateRWLock-aufgerufen hat, kann er NdisAcquireRWLockWrite oder NdisAcquireRWLockRead- aufrufen, um schreib- oder lesezugriff auf die Ressource abzurufen. Nur jeweils ein Nicht-ISR-Treiberthread kann Schreibzugriff auf die Ressource erhalten. Wenn ein Nicht-ISR-Thread Schreibzugriff hat, müssen alle Lese- und Schreibzugriffe von anderen Nicht-ISR-Threads warten, bis der Schreibzugriffshalter die Sperre loslässt. Wenn jedoch ein Nicht-ISR-Thread Lesezugriff hat, können andere Nicht-ISR-Threads gleichzeitig Lesezugriff erhalten.

Die NDIS_RW_LOCK_EX-Sperre unterstützt keine Heraufsteufung von Lese-zu-Schreibzugriff. Nachdem ein Prozessor eine NDIS_RW_LOCK_EX für den Lesezugriff erworben hat (durch Aufrufen von NdisAcquireRWLockRead), darf derselbe Prozessor nicht versuchen, Schreibzugriff (durch Aufrufen von NdisAcquireRWLockWrite) zu erhalten, bis der vorherige Lesezugriff freigegeben wird.

Eine NDIS_RW_LOCK_EX Lesesperre kann rekursiv auf demselben Prozessor abgerufen werden. Für jeden Aufruf von NdisAcquireRWLockReadmuss ein entsprechender Aufruf an NdisReleaseRWLockvorhanden sein. Die Sperre wird erst nach dem letzten Aufruf von NdisReleaseRWLockfreigegeben.

Der Treiber kann keine Sperre verwenden, um Ressourcen vor Lese- oder Schreibzugriff zu schützen, die seine anderen Funktionen für die MiniportInterrupt- oder MiniportDisableInterruptEx Funktion oder beides. Stattdessen muss der Treiber anrufen NdisMSynchronizeWithInterruptEx so, dass sie MiniportSynchronizeInterrupt-Funktion greift auf solche freigegebenen Ressourcen in derselben DIRQL zu, die MiniportInterrupt oder MiniportDisableInterruptEx Funktionen oder beides.

NdisAcquireRWLockRead löst immer den IRQL auf IRQL = DISPATCH_LEVELaus.

Anforderungen

Anforderung	Wert
mindestens unterstützte Client-	Unterstützt in NDIS 6.20 und höher.
Zielplattform-	Universal
Header-	ndis.h (include Ndis.h)
Library	Ndis.lib
IRQL-	<= DISPATCH_LEVEL