ExInitializeNPagedLookasideList 函数 (wdm.h)

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

语法

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

指定在分配外观列表条目时要使用的池标记。 有关池标记的详细信息,请参阅 ExAllocatePoolWithTagTag 参数。

[in] Depth

保留。 必须为零。

返回值

没有

言论

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

ExInitializeNPagedLookasideList 初始化系统状态以跟踪给定外观列表的使用情况,如下所示:

  • 零初始化要为条目维护的计数器。

  • 存储调用方提供的 Xxx分配XxxFree 例程的入口点(如果有)或将这些入口点分别设置为 exAllocatePoolWithTagExFreePool

  • 初始化系统旋转锁,以在必要时以多处理器安全的方式控制从外观列表释放和释放分配。

  • 存储调用方提供的条目 大小,并列出 标记

  • 设置系统确定的条目数(最小值和最大值)在望边列表中,如果系统范围的条目需求高于或低于预期,则随后可以调整这些限制。

  • 设置系统确定的标志,用于控制随后将分配条目的内存类型。

系统维护当前正在使用的所有外观列表集。 随着对查找列表条目和可用非分页内存的需求在系统运行时变化,系统会动态调整每个非分页查找列表中要保留的条目数的限制。

驱动程序在卸载之前必须始终显式释放他们创建的任何外观列表。 否则,这是一个严重的编程错误。 使用 ExDeleteNPagedLookasideList 释放列表。

ExInitializeNPagedLookasideList 在调用方提供的位置设置不透明的列表头,但预分配列表条目没有内存。 随后,初始条目将动态分配为对 ExAllocateFromNPagedLookasideList 的调用,并且这些初始条目将作为对 ExFreeToNPagedLookasideList 的相互调用保存在 lookaside 列表中。 条目收集在给定的望边列表中,直到达到系统确定的最大值,在释放时,任何其他条目将返回到非分页池。 如果列表变为空,则 Xxx在列表初始化中指定的分配 函数或 ExAllocatePoolWithTag满足分配请求。

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

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

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

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

要求

要求 价值
目标平台 普遍
标头 wdm.h (包括 Wdm.h、Ntddk.h、Ntifs.h)
NtosKrnl.lib
DLL NtosKrnl.exe
IRQL IRQL <= DISPATCH_LEVEL (请参阅“备注”部分)

另请参阅

ExAllocateFromNPagedLookasideList

ExAllocatePoolWithTag

ExDeleteNPagedLookasideList

ExFreePool

ExFreeToNPagedLookasideList

ExInitializeLookasideListEx

ExInitializePagedLookasideList

LOOKASIDE_LIST_EX

NPAGED_LOOKASIDE_LIST