Funzione NdisAllocateRWLock (ndis.h)

Articolo
08/07/2023

La funzione NdisAllocateRWLock alloca una variabile di blocco di lettura/scrittura di tipo NDIS_RW_LOCK_EX.

Sintassi

PNDIS_RW_LOCK_EX NdisAllocateRWLock(
  NDIS_HANDLE NdisHandle
);

Parametri

NdisHandle

Handle restituito da una delle funzioni seguenti:

NdisMRegisterMiniportDriver
MiniportInitializeEx
NdisRegisterProtocolDriver
NdisOpenAdapterEx
NdisFRegisterFilterDriver
FilterAttach
Windows 8 e Windows Server 2012 e versioni successive: se il blocco di lettura/scrittura viene allocato in DriverEntry prima che sia disponibile un handle NDIS, il chiamante può passare un valore NULL per questo parametro.

Valore restituito

NdisAllocateRWLock restituisce un puntatore a una struttura NDIS_RW_LOCK_EX , se possibile; in caso contrario restituisce NULL.

Commenti

I driver NDIS chiamano la funzione NdisAllocateRWLock per allocare una struttura NDIS_RW_LOCK_EX che controlla l'accesso in lettura/scrittura alle risorse condivise tra i thread driver. I driver usano un blocco di lettura/scrittura per le risorse a cui si accede di frequente per la lettura e l'accesso raramente per la scrittura.

Ogni blocco allocato da un driver può eseguire una delle operazioni seguenti:

Proteggere un set discreto di risorse condivise da accessi in lettura e scrittura simultanei da thread driver eseguiti in IRQL <= DISPATCH_LEVEL.
Esporre un set discreto di risorse condivise all'accesso in lettura simultaneo dai thread driver eseguiti in IRQL <= DISPATCH_LEVEL.

Il puntatore NDIS_RW_LOCK_EX restituito da NdisAllocateRWLock è un parametro obbligatorio per tutte le altre funzioni di blocco di lettura/scrittura.

Un NDIS_RW_LOCK_EX non è giusto. Ovvero, un processore in attesa di acquisire il blocco per l'accesso esclusivo può essere risolto dai processori che mantengono il blocco per l'accesso in lettura. Pertanto, non usare un NDIS_RW_LOCK_EX in situazioni in cui la maggior parte degli accessi sarà per l'accesso in scrittura. Se la maggior parte degli accessi richiederà l'accesso in scrittura, è più efficiente usare semplicemente un blocco spin del kernel. Per altre informazioni sui blocchi di rotazione, vedere Introduzione ai blocchi di rotazione.

In situazioni in cui sono presenti molte acquisizioni per l'accesso in lettura su più processori, il NDIS_RW_LOCK_EX in genere offre prestazioni migliori rispetto a un blocco di rotazione del kernel. Usare NDIS_RW_LOCK_EX quando si prevedono molti accessi in lettura al secondo distribuiti in più processori.

Una struttura NDIS_RW_LOCK_EX definisce gli attributi che limitano l'accesso in scrittura alle risorse condivise a un thread del driver non ISR alla volta. La struttura NDIS_RW_LOCK_EX può consentire a più thread driver non ISR di avere accesso in lettura simultaneo alle risorse associate. Tale accesso in lettura non è consentito durante un accesso in scrittura.

Per modificare le risorse protette, un thread driver deve ottenere un blocco di scrittura con la funzione NdisAcquireRWLockWrite . Per leggere semplicemente queste risorse, un thread del driver deve ottenere un blocco di sola lettura con la funzione NdisAcquireRWLockRead . L'accesso in lettura non richiede operazioni interlock o conflitti per i blocchi di rotazione. L'accesso in sola lettura consente di mantenere buone prestazioni del sistema operativo e del driver.

Al termine dell'accesso alle risorse, il driver chiama la funzione NdisReleaseRWLock .

Un driver deve chiamare la funzione NdisFreeRWLock per liberare la struttura NDIS_RW_LOCK_EX allocata con la funzione NdisAllocateRWLock .

È possibile usare l'estensione del debugger !ndiskd.ndisrwlock per esaminare un NDIS_RW_LOCK_EX, verificare il numero di lettori presenti e vedere chi è il writer corrente. Per altre informazioni, vedere Estensioni NDIS (Ndiskd.dll).For more information, see NDIS Extensions (Ndiskd.dll).

Requisiti

Requisito	Valore
Client minimo supportato	Supportato in NDIS 6.20 e versioni successive.
Piattaforma di destinazione	Universale
Intestazione	ndis.h (include Ndis.h)
Libreria	Ndis.lib
IRQL	<=DISPATCH_LEVEL