ExInitializePagedLookasideList 函数 (wdm.h)

项目
03/08/2023

ExInitializePagedLookasideList 例程初始化指定大小的可分页条目的 lookaside 列表。

语法

void ExInitializePagedLookasideList(
  [out]          PPAGED_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

指向要初始化 PAGED_LOOKASIDE_LIST 结构的指针。调用方必须为结构使用非分页系统空间，即使此查找列表中的条目将从可分页内存中分配。在 64 位平台上，此结构必须对齐 16 字节。

[in, optional] Allocate

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

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

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

[in, optional] Free

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

VOID XxxFree(
  __in PVOID  Buffer
);

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

[in] Flags

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

标记位	含义
POOL_RAISE_IF_ALLOCATION_FAILURE	如果分配失败，则引发异常。

指定POOL_NX_ALLOCATION标志不起作用。所有可分页内存都分配为 NX。

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

[in] Size

指定 lookaside 列表中每个条目的大小（以字节为单位）。

[in] Tag

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

[in] Depth

保留。必须为零。

返回值

无

备注

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

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

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

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

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

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

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

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

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

要求

要求	值
目标平台	通用
标头	wdm.h（包括 Wdm.h、Ntddk.h、Ntifs.h）
Library	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL
DDI 符合性规则	HwStorPortProhibitedDDI (storport) ， IrqlExApcLte2 (wdm)