NdisInitializeReadWriteLock (NDIS 5.1) function

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

NdisInitializeReadWriteLock initializes a variable of type NDIS_RW_LOCK. An NDIS_RW_LOCK variable is used to limit write access to shared resources to one non-ISR driver thread at a time. This NDIS_RW_LOCK can allow multiple non-ISR driver threads concurrent read access to those resources. Such read access is not permitted during a write access.

Syntax

VOID NdisInitializeReadWriteLock(
  _Out_ PNDIS_RW_LOCK Lock
);

Parameters

Lock [out]
Pointer to an opaque variable that represents a lock. The caller can use this lock to gain write or read access to resources that are shared among non-ISR driver threads.

Return value

None

Remarks

The Lock pointer that is passed to NdisInitializeReadWriteLock is a required parameter for all other Ndis..ReadWriteLock functions.

Before a driver calls NdisAcquireReadWriteLock to obtain write or read access to a resource, the driver must call NdisInitializeReadWriteLock to initialize the lock that is associated with that resource. The caller must provide nonpaged storage for the variable at Lock.

After calling NdisInitializeReadWriteLock, the driver can call NdisAcquireReadWriteLock 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 acquire read access.

Initialize and use this type of lock for resources that are frequently accessed for reading and infrequently accessed for writing.

Once resource access is complete, the driver calls NdisReleaseReadWriteLock.

Each lock that a driver initializes does one of the following:

protects a discrete set of shared resources from simultaneous write and read access by driver threads that run at IRQL <= DISPATCH_LEVEL.
exposes a discrete set of shared resources to simultaneous read access by driver threads that run at IRQL <= DISPATCH_LEVEL

Callers of NdisInitializeReadWriteLock can run at any IRQL. Usually a caller is running at IRQL = PASSIVE_LEVEL during initialization.

Requirements

Target platform	Universal
Version	See NdisInitializeReadWriteLock.
Header	Ndis.h (include Ndis.h)
Library	Ndis.lib
IRQL	Any level (see Remarks section)

Partager via