ExInitializeNPagedLookasideList 函数 (wdm.h)

项目
03/08/2023

ExInitializeNPagedLookasideList 例程初始化指定大小的非分页条目的查找列表。

语法

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
);

参数

[out] Lookaside

指向要初始化的NPAGED_LOOKASIDE_LIST 结构的指针。调用方必须为结构使用非分页系统空间。在 64 位平台上，此结构必须是 16 字节对齐的。

[in, optional] Allocate

指向调用方提供的函数的指针，用于在旁观列表为空时分配条目，或指向 NULL。如果不是 NULL，则指针指向具有原型的函数：

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

如果 Allocate 参数为 NULL，则每当 lookaside 列表为空时，对 ExAllocateFromNPagedLookasideList 的后续调用都会自动分配条目。

[in, optional] Free

指向调用方提供的函数的指针，用于在旁视列表已满时释放条目，或指向 NULL。如果不是 NULL，则指针指向具有原型的函数：

VOID XxxFree(
  __in PVOID  Buffer
);

如果 Free 参数为 NULL，则每当列表已满（即当前保留系统确定的最大条目数）时，对 ExFreeToNPagedLookasideList 的后续调用会自动将给定条目释放回非分页池。

[in] Flags

从 Windows 8 开始，此参数指定一个可选标志值来修改 ExInitializeNPagedLookasideList 例程的默认行为。兼容的标志位包括以下内容。

标志位	含义	“值”
POOL_RAISE_IF_ALLOCATION_FAILURE	如果分配失败，则引发异常。	16
POOL_NX_ALLOCATION	分配非可执行内存。	512

在Windows 8之前，不使用此参数，必须为零。

[in] Size

指定要随后分配的每个非分页条目的大小（以字节为单位）。此参数不得小于 Wdm.h 头文件中定义的所需最小大小（LOOKASIDE_MINIMUM_BLOCK_SIZE）。

[in] Tag

指定分配旁视列表条目时要使用的池标记。有关池标记的详细信息，请参阅 ExAllocatePoolWithTag 的 Tag 参数。

[in] Depth

保留。必须为零。

返回值

无

备注

调用 ExInitializeNPagedLookasideList 后，可以通过调用 ExAllocateFromNPagedLookasideList 和 ExFreeToNPagedLookasideList 分别从调用调用方指定 Size 的内存块并释放到 lookaside 列表。这种动态分配和释放的条目可以是调用方在系统运行时使用的任何数据结构或固定大小的缓冲区，特别是当调用方无法预先确定在任何给定时刻将使用多少个此类条目时。每个固定大小条目的布局和内容由调用方确定。

ExInitializeNPagedLookasideList 初始化系统状态以跟踪给定 lookaside 列表的使用情况，如下所示：

零初始化要为条目维护的计数器。
存储调用方提供的 XxxAllocate 和 XxxFree 例程的入口点（如果有），或将这些入口点分别设置为 ExAllocatePoolWithTag 和 ExFreePool。
如有必要，初始化系统自旋锁以控制从旁视列表的分配，并以多处理器安全的方式释放到旁视列表。
存储调用方提供的条目 Size 和 list Tag。
设置系统确定的限制 (最小和最大) 要保留在旁视列表中的条目数，如果系统范围的条目需求高于或低于预期，则可以随后进行调整。
设置系统确定的标志，这些标志控制随后将从中分配条目的内存类型。

系统维护一组当前正在使用的所有旁视列表。由于在系统运行时，对查看列表条目和可用非分页内存的需求会发生变化，因此系统会动态调整每个非分页旁视列表中要保留的条目数的限制。

在卸载之前，驱动程序必须始终显式释放它们创建的任何旁视列表。否则是严重的编程错误。使用 ExDeleteNPagedLookasideList 释放列表。

ExInitializeNPagedLookasideList 在调用方提供的位置设置不透明列表头，但不会为列表条目预分配内存。随后，初始条目在调用 ExAllocateFromNPagedLookasideList 时动态分配，这些初始条目在对 ExFreeToNPagedLookasideList 的倒数调用发生时保存在 lookaside 列表中。条目收集在给定的旁视列表中，直到达到系统确定的最大值，然后，任何其他条目在释放时将返回到非分页池。如果列表变为空，则分配请求由列表初始化时指定的 XxxAllocate 函数或 ExAllocatePoolWithTag 满足。

每当查找列表的用户只分配和释放固定大小的条目时，为 ExInitializeNPagedLookasideList 的 Allocate 和 Free 参数传递 NULL 指针会更有效。但是，任何使用旁视列表的组件都可能提供这些函数来执行调用方确定的其他处理，例如，通过维护其分配和释放的条目数的状态来跟踪其自己的动态内存使用情况。

如果 ExInitializeNPagedLookasideList 的调用方提供 XxxAllocate 函数，则该例程在调用 ExAllocatePoolWithTag 时必须使用给定的输入参数为 lookaside 列表分配条目。

从 Windows Vista 开始，类似的例程 ExInitializeLookasideListEx 初始化由 LOOKASIDE_LIST_EX 结构描述的旁观列表。与使用 NPAGED_LOOKASIDE_LIST 结构的 lookaside 列表的 Xxx Allocate 和 XxxFree 例程不同，使用 LOOKASIDE_LIST_EX 结构的 lookaside 列表的分配和解除分配例程接收上下文指针作为输入参数。这些例程可以使用此上下文来存储旁观列表的私有数据。如果驱动程序只打算在 Windows Vista 和更高版本的 Windows 中运行，请考虑使用 ExInitializeLookasideListEx 而不是 ExInitializeNPagedLookasideList。有关详细信息，请参阅使用 Lookaside Lists。

ExInitializeNPagedLookasideList 的调用方可以在 IRQL <= DISPATCH_LEVEL 运行，但通常在 IRQL = PASSIVE_LEVEL 运行。

要求

要求	值
目标平台	通用
标头	wdm.h（包括 Wdm.h、Ntddk.h、Ntifs.h）
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	IRQL <= DISPATCH_LEVEL (请参阅备注部分)