IoInitializeRemoveLock macro (wdm.h)

Article
02/25/2022

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

Syntax

void IoInitializeRemoveLock(
  [in]  Lock,
  [in]  Tag,
  [in]  Maxmin,
  [in]  HighWater
);

Parameters

[in] Lock

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.

[in] Tag

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. The caller should always supply a nonzero tag value for this parameter.

[in] Maxmin

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.

[in] HighWater

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.

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

Requirement	Value
Minimum supported client	Available starting with Windows 2000.
Target Platform	Desktop
Header	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	PASSIVE_LEVEL