StorPortAcquireSpinLockEx function (storport.h)
The StorPortAcquireSpinLockEx routine acquires the specified spin lock.
Syntax
ULONG StorPortAcquireSpinLockEx(
PVOID HwDeviceExtension,
STOR_SPINLOCK SpinLock,
PVOID LockContext,
PSTOR_LOCK_HANDLE LockHandle
);
Parameters
HwDeviceExtension
[in] Pointer to the miniport driver per-adapter device extension.
SpinLock
[in] Specifies an enumerator value of type STOR_SPINLOCK that specifies the spin lock to acquire.
LockContext
[in] A pointer to the DPC object for which the lock is held if SpinLock is set to DpcLock. This member should be NULL if SpinLock indicates a type of either InterruptLock or StartIoLock.
LockHandle
[in/out] A pointer to a buffer that, on return, will contain a lock handle. To release the lock, the caller must pass this handle to the StorPortReleaseSpinLock routine.
Return value
StorPortAcquireSpinLockEx returns STOR_STATUS_SUCCESS if the spin lock is acquired successfully. Otherwise, it returns a status code such as one of the following:
| Status code | Description |
|---|---|
| STOR_STATUS_INVALID_PARAMETER | A parameter is invalid. |
| STOR_STATUS_INVALID_IRQL | The caller is at an invalid IRQL for the type of SpinLock that it is trying to acquire. |
Remarks
Miniport drivers must ensure that they do not attempt to acquire a lock that is already held or acquire locks in an incorrect order. Either of these mistakes will result in system deadlock.
Certain locks are held automatically by the port driver before it calls the miniport driver callback routines. For each miniport driver callback routine, the following table indicates which locks the port driver acquires automatically before calling the callback routine.
| Miniport driver routine | Spin lock held by port driver |
|---|---|
| HwStorFindAdapter | None |
| HwStorInitialize | Interrupt (physical miniports), None (virtual miniports) |
| HwStorInterrupt | Interrupt |
| HwMSIInterruptRoutine | Interrupt |
| HwStorStartIo | StartIo (physical miniports only when requested concurrent channels <= 1) |
| HwStorBuildIo | None |
| HwStorTimer | Startio, Interrupt (when SynchronizationModel member of PORT_CONFIGURATION_INFORMATION is set to StorSynchronizeHalfDuplex) |
| HwStorResetBus | Startio, Interrupt (when SynchronizationModel member of PORT_CONFIGURATION_INFORMATION is set to StorSynchronizeHalfDuplex) |
| HwStorAdapterControl | None. (In Windows Server 2003, the StartIo spin lock was held when control type is ScsiStopAdapter.) |
| HwStorUnitControl | None |
| HwStorTracingEnabled | None |
| HwStorPassiveInitializeRoutine | None |
| HwStorDpcRoutine | None |
| HwStorStateChange | Startio, Interrupt (when SynchronizationModel member of PORT_CONFIGURATION_INFORMATION is set to StorSynchronizeHalfDuplex) |
The locks held by the port driver influence which locks the callback routines are allowed to acquire, because spin locks must be acquired in the following order:
- DPC or StartIo
- Interrupt
For instance, if the port driver acquires the Interrupt spin lock before calling a callback routine, that callback routine can no longer acquire the DPC or StartIo spin lock because the DPC and StartIo spin locks are of a lower order than the Interrupt spin lock. On the other hand, if the port driver acquires the StartIo spin lock before calling a callback routine, that callback routine, when executed, could still acquire an Interrupt or a DPC spin lock.
The following table indicates which spin locks each miniport driver routine can acquire. In those cases where the miniport driver routine must obtain both the StartIo spin lock and the Interrupt spin lock, the routine must always acquire the StartIo spin lock first.
| Miniport driver routine | Allowed spin locks |
|---|---|
| HwStorFindAdapter | None |
| HwStorInitialize | None |
| HwStorInterrupt | None |
| HwMSIInterruptRoutine | None |
| HwStorStartIo | DPC, Interrupt. Note that StartIo can be acquired in a virtual miniport driver or from a physical miniport driver that uses multiple concurrent channels. |
| HwStorBuildIo | DPC, StartIo, Interrupt |
| HwStorTimer | Interrupt (when SynchronizationModel member of PORT_CONFIGURATION_INFORMATION is not set to StorSynchronizeHalfDuplex) |
| HwStorResetBus | Interrupt (when SynchronizationModel member of PORT_CONFIGURATION_INFORMATION is not set to StorSynchronizeHalfDuplex) |
| HwStorAdapterControl | DPC, StartIo, Interrupt. (In Windows Server 2003, the no spin lock is allowed when control type is ScsiStopAdapter.) |
| HwStorUnitControl | DPC, StartIo, Interrupt |
| HwStorTracingEnabled | DPC, StartIo, Interrupt |
| HwStorPassiveInitializeRoutine | None |
| HwStorDpcRoutine | DPC, StartIo, Interrupt |
| HwStorStateChange | Interrupt (when SynchronizationModel member of PORT_CONFIGURATION_INFORMATION is not set to StorSynchronizeHalfDuplex) |
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows 10, version 1809 |
| Header | storport.h |