ExInitializeNPagedLookasideList

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

VOID 
  ExInitializeNPagedLookasideList(
    IN PNPAGED_LOOKASIDE_LIST  Lookaside,
    IN PALLOCATE_FUNCTION  Allocate  OPTIONAL,
    IN PFREE_FUNCTION  Free  OPTIONAL,
    IN ULONG  Flags,
    IN SIZE_T  Size,
    IN ULONG  Tag,
    IN USHORT  Depth
    );

Parameters

Lookaside

Pointer to the caller-supplied memory for the lookaside list head to be initialized. The caller must provide at least sizeof(NPAGED_LOOKASIDE_LIST) in nonpaged system space for this opaque list head.

Allocate

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

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 (
    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

Reserved. Must be zero.

Size

Specifies the size in bytes for each nonpaged entry to be allocated subsequently.

Tag

Specifies the pool tag for lookaside list entries. The Tag is a string of four characters delimited by single quote marks (for example, ‘derF’). The characters are usually specified in reverse order so they are easier to read when dumping pool or tracking pool usage with the PoolHitTag variable in the debugger.

Depth

Reserved. Must be zero.

Return Value

None

Headers

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

Comments

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:

• Zero-initializes the counters to be maintained for entries
• Stores the entry points of the caller-supplied XxxAllocate and XxxFree functions, if any, or sets these entry points to ExAllocatePoolWithTag and ExFreePool, respectively
• Initializes a system spin lock to control allocations from and frees to the lookaside list in a multiprocessor-safe manner if necessary
• Stores the caller-supplied entry Size and list Tag
• Sets up the system-determined limits (minimum and maximum) on the number of entries to be held in the lookaside list, which can be adjusted subsequently if system-wide demand for entries is higher or lower than anticipated
• Sets up the system-determined flags, which control the type of memory from which entries will be allocated subsequently

The OS 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 OS adjusts its limits for the number of entries to be held in each nonpaged lookaside list dynamically.

Drivers must always use explicitly free any lookaside lists they create before unloading. It is a serious programming error to do otherwise. Use ExDeletePagedLookasideList 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.

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

See Also

ExAllocateFromNPagedLookasideList, ExAllocatePoolWithTag, ExDeleteNPagedLookasideList, ExFreeToNPagedLookasideList, ExFreePool, ExInitializePagedLookasideList