ExInitializeNPagedLookasideList - NtDoc

Native API online documentation, based on the System Informer (formerly Process Hacker) phnt headers
// wdm.h

VOID ExInitializeNPagedLookasideList(
  [out]          PNPAGED_LOOKASIDE_LIST Lookaside,
  [in, optional] PALLOCATE_FUNCTION     Allocate,
  [in, optional] PFREE_FUNCTION         Free,
  [in]           ULONG                  Flags,
  [in]           SIZE_T                 Size,
  [in]           ULONG                  Tag,
  [in]           USHORT                 Depth
);

View the official Windows Driver Kit DDI reference

NtDoc

No description available.

Windows Driver Kit DDI reference (nf-wdm-exinitializenpagedlookasidelist)

Description

The ExInitializeNPagedLookasideList routine initializes a lookaside list for nonpaged entries of the specified size.

Parameters

Lookaside [out]

A pointer to the NPAGED_LOOKASIDE_LIST structure to initialize. The caller must use nonpaged system space for the structure. On 64-bit platforms, this structure must be 16-byte aligned.

Allocate [in, optional]

A pointer to either a caller-supplied function for allocating an entry when the lookaside list is empty, or to NULL. If non-NULL, the pointer is to a function with the prototype:

PVOID XxxAllocate(
  __in POOL_TYPE  PoolType,           // NonPagedPool
  __in SIZE_T  NumberOfBytes,         // value of Size
  __in ULONG  Tag                     // value of Tag
);

If the Allocate parameter is NULL, subsequent calls to ExAllocateFromNPagedLookasideList automatically allocate entries whenever the lookaside list is empty.

Free [in, optional]

A pointer to either a caller-supplied function for freeing an entry whenever the lookaside list is full, or to NULL. If non-NULL, the pointer is to a function with the prototype:

VOID XxxFree(
  __in PVOID  Buffer
);

If the Free parameter is NULL, subsequent calls to ExFreeToNPagedLookasideList automatically release the given entry back to nonpaged pool whenever the list is full, that is, currently holding the system-determined maximum number of entries.

Flags [in]

Starting in Windows 8, this parameter specifies an optional flag value to modify the default behavior of the ExInitializeNPagedLookasideList routine. Compatible flag bits include the following.

Flag bit Meaning Value
POOL_RAISE_IF_ALLOCATION_FAILURE If the allocation fails, raise an exception. 16
POOL_NX_ALLOCATION Allocate non-executable memory. 512

Before Windows 8, this parameter is not used and must be zero.

Size [in]

Specifies the size, in bytes, for each nonpaged entry to be allocated subsequently. This parameter must not be less than the required minimum size, LOOKASIDE_MINIMUM_BLOCK_SIZE, which is defined in the Wdm.h header file.

Tag [in]

Specifies the pool tag to use when allocating lookaside list entries. For more information about pool tags, see the Tag parameter of ExAllocatePoolWithTag.

Depth [in]

Reserved. Must be zero.

Remarks

After calling ExInitializeNPagedLookasideList, memory blocks of the caller-specified Size can be allocated from and freed to the lookaside list with calls to ExAllocateFromNPagedLookasideList and ExFreeToNPagedLookasideList, respectively. Such dynamically allocated and freed entries can be any data structure or fixed-size buffer that the caller uses while the system is running, particularly if the caller cannot predetermine how many such entries will be in use at any given moment. The layout and contents of each fixed-size entry are caller-determined.

ExInitializeNPagedLookasideList initializes the system state to track usage of the given lookaside list, as follows:

The system maintains a set of all lookaside lists currently in use. As demand for lookaside list entries and on available nonpaged memory varies while the system runs, the system adjusts its limits for the number of entries to be held in each nonpaged lookaside list dynamically.

Drivers must always explicitly free any lookaside lists they create before unloading. To do otherwise is a serious programming error. Use ExDeleteNPagedLookasideList to free the list.

ExInitializeNPagedLookasideList sets up the opaque list head at the caller-supplied location but preallocates no memory for list entries. Subsequently, the initial entries are allocated dynamically as calls to ExAllocateFromNPagedLookasideList occur, and these initial entries are held in the lookaside list as reciprocal calls to ExFreeToNPagedLookasideList occur. Entries collect in the given lookaside list until the system-determined maximum is reached, whereupon any additional entries are returned to nonpaged pool as they are freed. If the list becomes empty, allocate requests are satisfied by the XxxAllocate function specified at list initialization or by ExAllocatePoolWithTag.

It is more efficient to pass NULL pointers for the Allocate and Free parameters of ExInitializeNPagedLookasideList whenever the user of a lookaside list does nothing more than allocate and release fixed-size entries. However, any component that uses a lookaside list might supply these functions to do additional caller-determined processing, such as tracking its own dynamic memory usage by maintaining state about the number of entries it allocates and frees.

If the caller of ExInitializeNPagedLookasideList supplies an XxxAllocate function, that routine must allocate entries for the lookaside list using the given input parameters when it calls ExAllocatePoolWithTag.

Starting with Windows Vista, a similar routine, ExInitializeLookasideListEx, initializes a lookaside list that is described by a LOOKASIDE_LIST_EX structure. Unlike the XxxAllocate and XxxFree routines for a lookaside list that uses an NPAGED_LOOKASIDE_LIST structure, the allocation and deallocation routines for a lookaside list that uses the LOOKASIDE_LIST_EX structure receive a context pointer as an input parameter. These routines can use this context to store private data for the lookaside list. If your driver is intended to run only in Windows Vista and later versions of Windows, consider using ExInitializeLookasideListEx instead of ExInitializeNPagedLookasideList. For more information, see Using Lookaside Lists.

Callers of ExInitializeNPagedLookasideList can be running at IRQL <= DISPATCH_LEVEL, but are typically running at IRQL = PASSIVE_LEVEL.

See also

ExAllocateFromNPagedLookasideList

ExAllocatePoolWithTag

ExDeleteNPagedLookasideList

ExFreePool

ExFreeToNPagedLookasideList

ExInitializeLookasideListEx

ExInitializePagedLookasideList

LOOKASIDE_LIST_EX

NPAGED_LOOKASIDE_LIST