IoInitializeRemoveLock routine

The IoInitializeRemoveLock routine initializes a remove lock for a device object.

Syntax


VOID IoInitializeRemoveLock(
  _In_ PIO_REMOVE_LOCK Lock,
  _In_ ULONG           AllocateTag,
  _In_ ULONG           MaxLockedMinutes,
  _In_ ULONG           HighWatermark
);

Parameters

Lock [in]

Pointer to a caller-supplied IO_REMOVE_LOCK structure that this routine initializes with information about the lock, including a counter and a synchronization event. A driver writer must allocate this structure as part of the device object's device extension.

AllocateTag [in]

Specifies a tag to identify the creator of the lock. Driver writers typically use a 4-character string, specified in reverse order, like the tags used for ExAllocatePoolWithTag.

The I/O system uses this parameter if Driver Verifier is enabled, and on checked builds regardless of whether Driver Verifier is enabled. The caller should always supply a nonzero tag value for this parameter, for both free and checked builds.

MaxLockedMinutes [in]

Specifies the maximum number of minutes that this lock should be held. A value of zero means there is no limit. This value is typically used during debugging to identify a driver routine that holds the lock longer than expected.

The I/O system uses this parameter if Driver Verifier is enabled, and on checked builds regardless of whether Driver Verifier is enabled. If the lock is held for more than MaxLockedMinutes on a checked build, the operating system asserts.

HighWatermark [in]

Specifies the maximum number of outstanding acquisitions allowed on the lock. Use 0 to specify no maximum. HighWatermark must be <= 0x7FFFFFFF.

The I/O system uses this parameter if Driver Verifier is enabled, and on checked builds regardless of whether Driver Verifier is enabled. If the lock is acquired HighWatermark times on a checked build, the operating system asserts.

Return value

None

Remarks

A driver can use a remove lock to track outstanding I/O operations on a device and to determine when the driver can delete its device object in response to an IRP_MN_REMOVE_DEVICE request.

Before calling IoInitializeRemoveLock, a driver should allocate an IO_REMOVE_LOCK structure in its device extension. A driver typically calls IoInitializeRemoveLock in its AddDevice routine, when the driver initializes the rest of the device extension for a device object.

After the IoReleaseRemoveLockAndWait routine returns, the driver should consider the device to be in a state in which it is ready to be removed and cannot perform I/O operations. Therefore, the driver must not call IoInitializeRemoveLock to re-initialize the remove lock. Violation of this rule while the driver is being verified by Driver Verifier will result in a bug check.

Because the driver stores the IO_REMOVE_LOCK structure in the device extension of a device object, the remove lock is deleted when the driver deletes the device extension as part of processing an IRP_MN_REMOVE_DEVICE request.

For more information, see Using Remove Locks.

Requirements

Target platform

Desktop

Version

Available starting with Windows 2000.

Header

Wdm.h (include Wdm.h, Ntddk.h, or Ntifs.h)

Library

NtosKrnl.lib

DLL

NtosKrnl.exe

IRQL

PASSIVE_LEVEL

See also

IoAcquireRemoveLock
IoInitializeRemoveLock
IoReleaseRemoveLock
IoReleaseRemoveLockAndWait

 

 

Send comments about this topic to Microsoft

Show: