NdisAllocateSpinLock (Windows Embedded CE 6.0)

1/6/2010

This function initializes a variable of type NDIS_SPIN_LOCK, used to synchronize access to resources shared among driver functions not related to interrupts.

Syntax

VOID NdisAllocateSpinLock(
  PNDIS_SPIN_LOCK SpinLock
);

Parameters

• SpinLock
  [in] Pointer to an opaque variable that represents a spin lock.

Return Value

None.

Remarks

Before a driver calls NdisAcquireSpinLock, NdisDprAcquireSpinLock, or any of the NdisInterlockedXXX functions, it must call this function to initialize the spin lock passed as a required parameter to these NdisXXX functions. The caller must provide storage for the variable at SpinLock.

After calling this function, the driver can call NdisAcquireSpinLock to obtain exclusive use of the resources that the spin lock protects. When resource access is complete, the driver calls NdisReleaseSpinLock so that other driver functions can access the resources protected by that spin lock.

In general, a driver should not pass the same spin lock to every NdisXXXSpinLock and NdisInterlockedXXX that it calls subsequently. In this way, any driver might initialize more than one spin lock with this function.

Each spin lock that a driver allocates protects a discrete set of shared resources from simultaneous access. For example, a driver that maintains an internal queue of packets might initialize one spin lock to protect its queue and another to protect a set of state variables that several driver functions, not including the MiniportISR or MiniportDisableInterrupt function, access while the driver is processing packets.

A driver should never use two spin locks to protect the same resources because nested spin-lock acquisitions frequently cause deadlocks. Even if a driver could be designed to prevent deadlocks, nested spin-lock acquisitions have an adverse effect on driver performance and I/O throughput.

A miniport driver cannot use a spin lock to protect resources that its non-ISR functions share with its MiniportISR or the MiniportDisableInterrupt function. To access resources shared with a MiniportISR or MiniportDisableInterrupt function, a miniport must call NdisMSynchronizeWithInterrupt to have its MiniportSynchronizeISR function access those resources.

When a driver no longer requires resource protection, for example, when an NIC is being removed and the driver is releasing the resources that it allocated for that NIC, the driver calls NdisFreeSpinLock.

Freeing a spin lock and releasing a spin lock must be distinguished. NdisFreeSpinLock clears the memory at SpinLock so it no longer represents a spin lock. Releasing an acquired spin lock with NdisReleaseSpinLock allows another thread of execution to acquire that spin lock.

Requirements

See Also

Reference

NDIS Library Functions
MiniportDisableInterrupt
MiniportISR
MiniportSynchronizeISR
NdisAcquireSpinLock
NdisDprAcquireSpinLock
NdisDprReleaseSpinLock
NdisFreeSpinLock
NdisMSynchronizeWithInterrupt
NdisReleaseSpinLock