NdisAcquireRWLockRead-Funktion (ndis.h)

Artikel
02/29/2024

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 von 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, zu denen der Aufrufer die Sperre abruft und freigibt. 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 vornimmt.

[in] Flags

Ein ULONG-Wert , der Sperrflags enthält. Legen Sie diesen Parameter auf NDIS_RWL_AT_DISPATCH_LEVEL fest, wenn die aktuelle IRQL des Aufrufers DISPATCH_LEVEL ist. Legen Sie andernfalls diesen Parameter auf 0 (null) fest. Weitere Informationen zur IRQL-Nachverfolgung für den Versand finden Sie unter Dispatch IRQL Tracking.

Hinweis Wenn der Aufrufer weiß, dass die aktuelle IRQL DISPATCH_LEVEL ist, legen Sie diesen Parameter auf NDIS_RWL_AT_DISPATCH_LEVEL fest. Dieses Flag macht die Sperre noch effizienter, da sie eine Überprüfung für die aktuelle IRQL auslässt. Wenn die aktuelle IRQL unbekannt ist, testen Sie den aktuellen IRQL nicht mit KeGetCurrentIrql , nur um zu bestimmen, ob dieses Flag festgelegt werden soll, da es effizienter ist, die NdisAcquireRWLockRead-Funktion zum Testen des IRQL selbst zuzulassen.

Rückgabewert

Keine

Bemerkungen

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

Der Treiber muss eine Variable vom Typ NDIS_RW_LOCK_EX mit der NdisAllocateRWLock-Funktion zuordnen, 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 zu erhalten. Nur jeweils ein Nicht-ISR-Treiberthread kann Schreibzugriff auf die Ressource erhalten. Wenn ein Nicht-ISR-Thread über Schreibzugriff verfügt, müssen alle Lese- und Schreibzugriffe anderer Nicht-ISR-Threads warten, bis der Schreibzugriffsinhaber die Sperre freigibt. Wenn jedoch ein Nicht-ISR-Thread Über Lesezugriff verfügt, können andere Nicht-ISR-Threads gleichzeitig Lesezugriff erhalten.

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

Eine NDIS_RW_LOCK_EX Lesesperre kann rekursiv auf demselben Prozessor abgerufen werden. Für jeden Aufruf von NdisAcquireRWLockRead muss ein entsprechender Aufruf von NdisReleaseRWLock vorhanden sein. Die Sperre wird erst nach dem letzten Aufruf von NdisReleaseRWLock aufgehoben.

Der Treiber kann keine Sperre verwenden, um Ressourcen vor Lese- oder Schreibzugriff zu schützen, die seine anderen Funktionen mit dem MiniportInterrupt oder teilen. MiniportDisableInterruptEx-Funktion oder beides. Stattdessen muss der Treiber aufrufen. NdisMSynchronizeWithInterruptEx , damit Die MiniportSynchronizeInterrupt-Funktion greift auf diese freigegebenen Ressourcen auf dieselbe DIRQL zu, die ihr MiniportInterrupt oder MiniportDisableInterruptEx-Funktionen oder beides.

NdisAcquireRWLockRead hebt die IRQL immer auf IRQL = DISPATCH_LEVEL.

Anforderungen

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