exAllocatePoolWithTag 函数 (wdm.h)

  • 项目

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

警告

exAllocatePoolWithTag 在 Windows 10 版本 2004 中已弃用，并由 ExAllocatePool2 取代。 有关详细信息，请参阅 将已弃用的 ExAllocatePool 调用更新到 ExAllocatePool2 和 ExAllocatePool3。

语法

PVOID ExAllocatePoolWithTag(
  [in] __drv_strictTypeMatch(__drv_typeExpr)POOL_TYPE PoolType,
  [in] SIZE_T                                         NumberOfBytes,
  [in] ULONG                                          Tag
);

参数

[in] PoolType

要分配的池内存的类型。 有关可用池内存类型的说明，请参阅 POOL_TYPE。

可以通过使用 POOL_RAISE_IF_ALLOCATION_FAILURE 标志对此值进行按位操作来修改 PoolType 值。 如果无法满足请求，此标志会导致引发异常。 不建议使用 POOL_RAISE_IF_ALLOCATION_FAILURE 标志，因为它成本高昂。

同样，可以修改 PoolType 值，方法是使用POOL_COLD_ALLOCATION标志对此值进行按位操作，作为内核的提示，以便从可能快速分页的页中分配内存。 若要尽可能减少驻留池内存量，不应频繁引用这些分配。 POOL_COLD_ALLOCATION标志只是公告。

[in] NumberOfBytes

要分配的字节数。

[in] Tag

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

返回值

如果可用池中没有足够的内存来满足请求，ExAllocatePoolWithTag 将返回 NULL。 否则，例程返回指向已分配内存的指针。

注解

此例程用于内存的常规池分配。

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

请求 numberOfBytes< PAGE_SIZE非分页池的成功分配会向调用方提供确切的内存请求字节数。 如果 NumberOfBytes> PAGE_SIZE分配请求成功，并且 NumberOfBytes 不是PAGE_SIZE的确切倍数，则分配中的最后一页包含不属于调用方分配的字节。 如果可能，池分配器将使用这些字节。 为了避免损坏属于其他内核模式组件的数据，驱动程序必须仅访问显式分配的存储地址。

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

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

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

当池 (分页或非分页) 的数量高或低时，系统会自动设置某些标准事件对象。 驱动程序可以等待这些事件来优化其池使用情况。 有关详细信息，请参阅 标准事件对象。

ExAllocatePoolWithTag 的调用方必须在 IRQL <= DISPATCH_LEVEL 执行。 在 DISPATCH_LEVEL 处执行的调用方必须为 PoolType 指定 NonPagedXxx 值。 在 IRQL <= APC_LEVEL 处执行的调用方可以指定任何 POOL_TYPE 值，但还必须考虑 IRQL 和环境来确定页面类型。

请勿设置 NumberOfBytes = 0。 避免零长度分配，因为它们会浪费池标头空间，并且在许多情况下，指示调用代码中存在潜在的验证问题。 因此， 驱动程序验证程序 将此类分配标记为可能的错误。

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

ExAllocatePoolWithTag 分配的内存未初始化。 如果内核模式驱动程序要使其对 (的用户模式软件可见，则必须先将其归零，以避免泄露) 潜在的特权内容。

要求

要求 值
目标平台 通用
标头 wdm.h（包括 Wdm.h、Ntddk.h、Ntifs.h）
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL IRQL <= DISPATCH_LEVEL (请参阅备注部分)
DDI 符合性规则 CheckDeviceObjectFlags (wdm) 、 HwStorPortProhibitedDDI (storport) 、 IrqlExAllocatePool (wdm) 、 IrqlExFree1 (wdm) 、 PowerDownAllocate (wdm) 、 PowerUpFail (wdm) 、 SpNoWait (storport) 、 StorPortStartIo (storport) 、 UnsafeAllocatePool (kmdf) 、 UnsafeAllocatePool (wdm)

另请参阅

ExAllocatePoolWithQuotaTag

ExAllocatePoolWithTagPriority

ExFreePool

ExFreePoolWithTag

POOL_TYPE