Edit

StorPortAcquireSpinLock function (storport.h)

  • Article

The StorPortAcquireSpinLock routine acquires the specified spin lock.

Syntax

void StorPortAcquireSpinLock(
  [in]     PVOID             DeviceExtension,
  [in]     STOR_SPINLOCK     SpinLock,
  [in]     PVOID             LockContext,
  [in/out] PSTOR_LOCK_HANDLE LockHandle
);

Parameters

[in] DeviceExtension

A pointer to the miniport driver per-adapter device extension.

[in] SpinLock

Specifies an enumerator value of type STOR_SPINLOCK that specifies the spin lock to acquire. For this function, SpinLock must be one of: DpcLock, StartIoLock, or InterruptLock. Call StorportAcquireSpinLockEx to acquire other types of spin locks.

[in] LockContext

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.

[in/out] LockHandle

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

None

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
Target Platform Universal
Header storport.h (include Storport.h)
DDI compliance rules StorPortSpinLock(storport), StorPortSpinLock3(storport), StorPortSpinLock4(storport)

See also

STOR_SPINLOCK

StorPortReleaseSpinLock