InitializeListHead

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

VOID 
  InitializeListHead(
    IN PLIST_ENTRY  ListHead
    );

Parameters

ListHead

Pointer 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.

Return Value

None

Headers

Declared in wdm.h and ntddk.h. Include wdm.h or ntddk.h.

Comments

A driver that sets up internal interlocked queues for IRPs or manages internal linked lists must call InitializeListHead. A PnP driver should make the call from its AddDevice routine after creating the relevant device object; other drivers can call from the DriverEntry routine.

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 can be running at IRQL >= DISPATCH_LEVEL only if the caller-allocated storage for ListHead is resident.

See Also

ExInterlockedInsertHeadList, ExInterlockedInsertTailList, ExInterlockedRemoveHeadList, ExInterlockedPopEntryList, ExInterlockedPushEntryList, InsertHeadList, InsertTailList, IsListEmpty, KeInitializeSpinLock, PopEntryList, PushEntryList, RemoveEntryList, RemoveHeadList, RemoveTailList