NdisAcquireRWLockRead function (ndis.h)

Article
10/21/2021

The NdisAcquireRWLockRead function obtains a read lock that the caller uses for read access to resources that are shared among driver threads.

Syntax

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

Parameters

[in] Lock

A pointer to an opaque NDIS_RW_LOCK_EX variable that represents a lock. The caller can use this lock to gain write or read access to resources that are shared between non-ISR driver threads.

[out] LockState

A pointer to an opaque LOCK_STATE_EX variable that tracks the state of the lock. This variable exists in the interval between the times that the caller obtains and releases the lock. The caller must use a different variable of type LOCK_STATE_EX for each attempt that it makes to obtain the lock from the same non-ISR driver thread.

[in] Flags

A ULONG value that contains lock flags. Set this parameter to NDIS_RWL_AT_DISPATCH_LEVEL if the caller's current IRQL is DISPATCH_LEVEL. Otherwise, set this parameter to zero. For more information about dispatch IRQL tracking, see Dispatch IRQL Tracking.

Note If the caller knows the current IRQL is DISPATCH_LEVEL, set this parameter to NDIS_RWL_AT_DISPATCH_LEVEL. This flag makes the lock even more efficient by causing it to omit a check for the current IRQL. If the current IRQL is unknown, do not test the current IRQL with KeGetCurrentIrql solely to determine whether to set this flag, as it is more efficient to allow the NdisAcquireRWLockRead function to test the IRQL itself.

Return value

None

Remarks

NDIS drivers call the NdisAcquireRWLockRead function to obtain read-only access to resources that are shared between driver threads.

The driver must allocate a variable of type NDIS_RW_LOCK_EX with the NdisAllocateRWLock function before the driver calls the NdisAcquireRWLockRead function.

After the driver calls NdisAllocateRWLock, it can call NdisAcquireRWLockWrite or NdisAcquireRWLockRead to obtain either write or read access to the resource. Only one non-ISR driver thread at a time can obtain write access to the resource. When one non-ISR thread has write access, all read and write accesses by other non-ISR threads must wait until the write-access holder releases the lock. However, if a non-ISR thread has read access, other non-ISR threads can concurrently obtain read access.

The NDIS_RW_LOCK_EX lock does not support promotion from read to write. Once a processor has acquired an NDIS_RW_LOCK_EX for read access (by calling NdisAcquireRWLockRead), the same processor must not attempt to acquire write access (by calling NdisAcquireRWLockWrite) until the previous read access is released.

An NDIS_RW_LOCK_EX read lock can be acquired recursively on the same processor. For each call to NdisAcquireRWLockRead, there must be a corresponding call to NdisReleaseRWLock. The lock is only released after the last call to NdisReleaseRWLock.

The driver cannot use a lock to protect resources from read or write access that its other functions share with the MiniportInterrupt or MiniportDisableInterruptEx function, or both. Instead, the driver must call NdisMSynchronizeWithInterruptEx so that its MiniportSynchronizeInterrupt function accesses such shared resources at the same DIRQL that its MiniportInterrupt or MiniportDisableInterruptEx functions, or both do.

NdisAcquireRWLockRead always raises the IRQL to IRQL = DISPATCH_LEVEL.

Requirements

Requirement	Value
Minimum supported client	Supported in NDIS 6.20 and later.
Target Platform	Universal
Header	ndis.h (include Ndis.h)
Library	Ndis.lib
IRQL	<= DISPATCH_LEVEL