NdisAcquireRWLockWrite-Funktion (ndis.h)

Artikel
03/01/2024

Die NdisAcquireRWLockWrite-Funktion ruft eine Schreibsperre ab, die der Aufrufer für den Schreibzugriff auf Ressourcen verwendet, die von Treiberthreads gemeinsam genutzt werden.

Syntax

void NdisAcquireRWLockWrite(
  [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 , um zu bestimmen, ob dieses Flag festgelegt werden soll, da es effizienter ist, der NdisAcquireRWLockWrite-Funktion das Testen des IRQL selbst zu ermöglichen.

Rückgabewert

Keine

Bemerkungen

NDIS-Treiber rufen die NdisAcquireRWLockWrite-Funktion auf, um Ressourcen zu ändern, 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 NdisAcquireRWLockWrite-Funktion aufruft . Der Treiber muss ein Handle für NdisAllocateRWLock für den residenten Speicher für die von ihnen verwendeten Sperren bereitstellen.

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 Schreibsperre kann rekursiv auf demselben Prozessor abgerufen werden. Für jeden Aufruf von NdisAcquireRWLockWrite muss ein entsprechender Aufruf von NdisReleaseRWLock vorhanden sein. Die Sperre wird erst nach dem letzten Aufruf von NdisReleaseRWLock aufgehoben.

Ein Treiberthread sollte niemals länger als ein paar Mikrosekunden eine Schreibsperre enthalten. Wenn Sie über einen längeren Zeitraum eine Schreibsperre halten, wird die Leistung des Betriebssystems und des Treibers beeinträchtigt.

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-Funktionen 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.

NdisAcquireRWLockWrite hebt die IRQL auf DISPATCH_LEVEL , indem eine Drehsperre abgerufen wird.

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