exAllocatePool2 函数 (wdm.h)

  • 项目

ExAllocatePool2 例程分配指定类型的池内存，并返回指向已分配块的指针。

语法

DECLSPEC_RESTRICT PVOID ExAllocatePool2(
  POOL_FLAGS Flags,
  SIZE_T     NumberOfBytes,
  ULONG      Tag
);

参数

Flags

一个ULONG64类型的值，用于指定池内存的类型以及必需属性和可选属性。 可以使用按位 OR 组合多个标志值。 有关可能的值 ，请参阅POOL_FLAGS 。

NumberOfBytes

指定要分配的非零字节数。

Tag

要用于已分配内存的池标记。 将池标记指定为由单引号分隔的 1 到 4 个字符的非零字符文本 (例如 Tag1 ，) 。 通常以相反的顺序指定字符串， (例如 1gaT ，) 。 标记中的每个 ASCII 字符必须是0x20 () 0x7E (波形符) 范围内的值。 每个分配代码路径应使用唯一的池标记来帮助调试器和验证程序识别代码路径。

返回值

ExAllocatePool2 返回指向已分配内存的指针。

以下条件导致函数默认返回 NULL。 如果指定 了POOL_FLAG_RAISE_ON_FAILURE ，该函数将引发异常。

  • 内存不足
  • 标记 设置为 0 或指定POOL_FLAGS无效

注解

如果要生成面向 Windows 10 版本 2004 之前的 Windows 版本的驱动程序，请使用 ExAllocatePoolZero、ExAllocatePoolUninitialized、ExAllocatePoolQuotaZero 或 ExAllocatePoolQuotaUninitialized。

此例程与以前的分配例程 (ExAllocatePoolWithTag、 ExAllocatePoolWithQuotaTag、 ExAllocatePoolWithTagPriority) 存在以下差异：

  1. 除非指定 POOL_FLAG_UNINITIALIZED ，否则初始化内存为零。

  2. 返回分配失败时的行为。 默认情况下，ExAllocatePoolWithQuotaTag 引发异常。

  3. 值为 0 的标记无效。

将 ExAllocatePoolWithQuotaTag 替换为 ExAllocatePool2 时，必须指定 POOL_FLAG_USE_QUOTA 标志。 有关池标志的详细信息，请参阅 POOL_FLAGS。

如果 NumberOfBytes 为 PAGE_SIZE 或更大，则分配页对齐缓冲区。 或更少的内存分配 PAGE_SIZE 在页中分配，不会跨越页边界。 小于 PAGE_SIZE 的内存分配不一定与页对齐，但在 32 位系统中与 8 字节边界对齐，在 64 位系统中与 16 字节边界对齐。

驱动程序最多只能使用显式分配的 NumberOfBytes 。 访问此范围之外的内存可能会损坏池并导致系统崩溃。

系统将池标记与分配的内存相关联。 WinDbg 等编程工具可以显示与每个分配的缓冲区关联的池标记。 Gflags 是 Windows 调试工具中包含的一种工具，它将打开一项系统功能，该功能请求从特定池标记的特殊池进行分配。 WDK 中包含的 Poolmon 按池标记跟踪内存。

Tag 的值以 (little-endian) 顺序进行反向存储，有时也会显示。 例如，如果调用方作为标记传递 Fred ，则它在调试器中的池转储和池使用情况跟踪中显示为 derF ，在 0x64657246 注册表和工具中显示。

可以使用 ExFreePool 或 ExFreePoolWithTag 释放分配的缓冲区。

ExAllocatePool2 的调用方必须在 IRQL <= DISPATCH_LEVEL 运行。 在 DISPATCH_LEVEL 处执行的调用方必须为 Flags 指定POOL_FLAG_NON_PAGED或POOL_FLAG_NON_PAGED_EXECUTABLE。 在 IRQL <= APC_LEVEL 处执行的调用方可以指定 POOL_FLAG_PAGED，但如果将从DISPATCH_LEVEL运行的代码访问内存，则仍必须分配非分页内存。

在非统一内存访问 (NUMA) 多处理器体系结构中， ExAllocatePool2 尝试为调用 ExAllocatePool2 的处理器分配本地内存。 如果没有可用的本地内存， ExAllocatePool2 将分配最近的可用内存。

ExAllocatePool2 分配的内存初始化为零。 内核模式驱动程序不应选择不对将复制到不受信任位置的分配 (用户模式、通过网络等进行归零，) 以避免泄露敏感信息。

要求

要求 值
最低受支持的客户端 Windows 10 版本 2004
目标平台 通用
标头 wdm.h（包括 Wdm.h、Ntddk.h、Ntifs.h）
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL IRQL <= DISPATCH_LEVEL (请参阅备注部分)
DDI 符合性规则 HwStorPortProhibitedDDI、SpNoWait、StorPortStartIo

另请参阅

ExAllocatePool3