NdisAcquireReadWriteLock (NDIS 5.1) function

项目
06/19/2017

Note NDIS 5. x has been deprecated and is superseded by NDIS 6. x. For new NDIS driver development, see Network Drivers Starting with Windows Vista. For information about porting NDIS 5. x drivers to NDIS 6. x, see Porting NDIS 5.x Drivers to NDIS 6.0.

NdisAcquireReadWriteLock acquires a lock that the caller uses for either write or read access to the resources that are shared among driver threads.

Syntax

VOID NdisAcquireReadWriteLock(
  _Inout_ PNDIS_RW_LOCK Lock,
  _In_    BOOLEAN       fWrite,
  _Out_   PLOCK_STATE   LockState
);

Parameters

Lock [in, out]
Pointer to an opaque variable that represents a lock. The caller can use this lock to access shared resources.
fWrite [in]
Specifies a Boolean value. If the value is TRUE, this function is provided with write access to shared resources; if the value is FALSE, this function is provided with read access.
LockState [out]
Pointer to an opaque variable that tracks the state of the lock. This variable exists in the interval between the time the caller acquires and releases the lock. The caller must use a different variable of type LOCK_STATE for each attempt it makes to acquire the lock from the same non-ISR driver thread.

Return value

None

Remarks

The driver must initialize a variable of type NDIS_RW_LOCK using NdisInitializeReadWriteLock before the driver calls any other NdisXxxReadWriteLock function. The driver must provide resident storage for the locks it uses.

After acquiring a lock by using NdisAcquireReadWriteLock, the caller must release that lock by calling NdisReleaseReadWriteLock. To decrement the reference count of the lock, a driver must call NdisReleaseReadWriteLock once for each call to NdisAcquireReadWriteLock.

To modify resources shared among driver threads, a driver thread must acquire a write lock. To simply monitor those resources, a driver thread must acquire a read-only lock. Read access does not require interlocked operations or contention for spin locks. Using read-only access helps to maintain good operating system and driver performance.

A driver thread should never hold a write lock for more than 25 microseconds. Holding a write lock for a prolonged period degrades both operating system and driver performance.

The driver cannot use a lock to protect resources from read or write access that its other functions share with the MiniportISR and/or MiniportDisableInterrupt functions. Instead, the driver must call NdisMSynchronizeWithInterrupt so that its MiniportSynchronizeISR function accesses such shared resources at the same DIRQL at which its MiniportISR and/or MiniportDisableInterrupt functions do.

NdisAcquireReadWriteLock always raises the IRQL. For a write operation, NdisAcquireReadWriteLock raises the IRQL by acquiring a spin lock. For a read operation, NdisAcquireReadWriteLock explicitly raises the IRQL to IRQL = DISPATCH_LEVEL.

For more information about acquiring and releasing NDIS spin locks, see Synchronization and Notification in Network Drivers.

Requirements

Target platform	Universal
Version	See NdisAcquireReadWriteLock.
Header	Ndis.h (include Ndis.h)
Library	Ndis.lib
IRQL	<= DISPATCH_LEVEL

通过