NdisInterlockedInsertHeadList function

The NdisInterlockedInsertHeadList function inserts an entry, usually a packet, at the head of a doubly linked list so that access to the list is synchronized in a multiprocessor-safe way.

Syntax


PLIST_ENTRY NdisInterlockedInsertHeadList(
  _In_  PLIST_ENTRY ListHead,
  _In_  PLIST_ENTRY ListEntry,
  _In_  PNDIS_SPIN_LOCK SpinLock
);

Parameters

ListHead [in]

A pointer to the head of the doubly linked list into which an entry is to be inserted.

ListEntry [in]

A pointer to the entry to be inserted at the head of the list.

SpinLock [in]

A pointer to a caller-supplied spin lock, used to synchronize access to the list.

Return value

NdisInterlockedInsertHeadList returns a pointer to the entry that was at the head of the queue before the given entry was inserted. If the queue was empty, it returns NULL.

Remarks

Before calling NdisInterlockedInsertHeadList, a driver must initialize the variable at ListHead with the NdisInitializeListHead function and the variable at SpinLock with the NdisAllocateSpinLock function. The driver also must provide resident storage for these variables and for its internal queue.

The caller-supplied spin lock prevents any other function from accessing the driver's internal queue while NdisInterlockedInsertHeadList is inserting the given entry, even when the driver is running on a multiprocessor computer.

NdisInterlockedInsertHeadList raises IRQL to DISPATCH_LEVEL when it acquires the given spin lock and restores the original IRQL before it returns control. Consequently, any driver function that calls NdisInterlockedInsertHeadList cannot be pageable code.

Most NDIS drivers process packets in FIFO order, so any driver that uses an interlocked queue tends to cal thel NdisInterlockedInsertTailList function far more frequently than NdisInterlockedInsertHeadList. Such a driver usually calls NdisInterlockedInsertHeadList only to requeue a packet for a retry operation.

To convert a returned value back to the address of the inserted entry, a driver can use the CONTAINING_RECORD macro.

If NdisInterlockedInsertHeadList is called at IRQL >= DISPATCH_LEVEL, the storage for the ListHead parameter and the list entries must be resident.

Requirements

Version

Supported for NDIS 6.0 and NDIS 5.1 drivers (see NdisInterlockedInsertHeadList (NDIS 5.1)) in Windows Vista. Supported for NDIS 5.1 drivers (see NdisInterlockedInsertHeadList (NDIS 5.1)) in Windows XP.

Header

Ndis.h (include Ndis.h)

IRQL

Any level

See also

CONTAINING_RECORD
NdisAllocateSpinLock
NdisInitializeListHead
NdisInterlockedInsertTailList
NdisInterlockedRemoveHeadList

 

 

Send comments about this topic to Microsoft

Show:
© 2014 Microsoft