|This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.|
This function initializes a variable of type NDIS_SPIN_LOCK, used to synchronize access to resources shared among driver functions not related to interrupts.
VOID NdisAllocateSpinLock ( IN PNDIS_SPIN_LOCK SpinLock );
Before a driver calls NdisAcquireSpinLock, NdisDprAcquireSpinLock, or any of the NdisInterlocked XXXfunctions, it must call this function to initialize the spin lock passed as a required parameter to these Ndis XXXfunctions. The caller must provide nonpaged storage for the variable at SpinLock.
After calling this function, the driver can call NdisAcquireSpinLockto obtain exclusive use of the resource(s) that the spin lock protects. When resource access is complete, the driver calls NdisReleaseSpinLockso that other driver functions can access the resource(s) protected by that spin lock.
As a general rule, a driver should not pass the same spin lock to every Ndis XXXSpinLockand NdisInterlocked XXXthat 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 simultanous access by driver functions that run at IRQL <= DISPATCH_LEVEL. 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 MiniportISRor MiniportDisableInterruptfunction, 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 MiniportISRor the MiniportDisableInterruptfunction. To access resources shared with a MiniportISRor MiniportDisableInterruptfunction, a miniport must call NdisMSynchronizeWithInterruptto have its MiniportSynchronizeISRfunction access those resources at DIRQL.
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. NdisFreeSpinLockclears the memory at SpinLockso it no longer represents a spin lock. Releasing an acquired spin lock with NdisReleaseSpinLockallows another thread of execution to acquire that spin lock.
A driver that calls this function can run at any IRQL. Usually a caller is running at IRQL PASSIVE_LEVEL during initialization.
|Runs on||Versions||Defined in||Include||Link to|
|Windows CE OS||2.0 and later||Ndis.h|
Note This API is part of the complete Windows CE OS package as provided by Microsoft. The functionality of a particular platform is determined by the original equipment manufacturer (OEM) and some devices may not support this API.
Last updated on Tuesday, July 13, 2004