Edit

StorPortAcquireSpinLockEx function (storport.h)

  • Article

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

See also

STOR_SPINLOCK

StorPortReleaseSpinLock