InitializeListHead

InitializeListHead

VOID
InitializeListHead(
IN PLIST_ENTRY ListHead
);

InitializeListHead initializes any doubly linked, driver-managed interlocked queue or driver-maintained doubly linked list.

Parameters

ListHead

Points to the driver-allocated storage for the head of the interlocked queue or list. For an interlocked queue, the storage must be resident and the driver also must provide storage for a spin lock.

Comments

InitializeListHead must be called from the DriverEntry routine if a driver sets up internal interlocked queues for IRPs or manages internal linked lists.

The ListHead of type LIST_ENTRY is doubly linked. Entries in an interlocked queue can be queued and dequeued by calling ExInterlockedInsert..List and ExInterlockedRemoveHeadList. Entries can be inserted into and removed from a driver-maintained list with Insert..List and Remove..List.

For an interlocked queue, a driver must provide resident storage: in the device extension of a driver-created device object, in the controller extension of a driver-created controller object, or in nonpaged pool allocated by the driver. The driver also must provide storage for a spin lock, which must be initialized with KeInitializeSpinLock before the driver's initial call to ExInterlockedXxx with the spin lock.

For a driver-maintained list, the driver must synchronize access to the list so that it is impossible for any two routines to be inserting and/or removing entries from the list simultaneously in SMP machines. Consequently, most drivers use the ExInterlockedXxx routines to manage the necessary synchronization, rather than setting up a driver-managed list, which is likely to require spin lock protection anyway.

Callers of InitializeListHead must be running at IRQL PASSIVE_LEVEL.