ExAllocatePoolWithTag 函数 (wdm.h)

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

重要

ExAllocatePoolWithTag 已在 Windows 10 版本 2004 中弃用,并且已替换为 ExAllocatePool2。 有关详细信息,请参阅更新对 ExAllocatePool2 和 ExAllocatePool3 的已弃用 ExAllocatePool 调用

语法

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标志按位 ORing 此值来修改 PoolType 值。 如果无法满足请求,则此标志会导致引发异常。 不建议使用POOL_RAISE_IF_ALLOCATION_FAILURE标志,因为它成本高昂。

同样,可以通过按位 ORing 此值来修改 PoolType 值,并将POOL_COLD_ALLOCATION标志作为提示,提示内核从可能快速分页的页面分配内存。 若要尽可能减少驻留池内存量,不应经常引用这些分配。 POOL_COLD_ALLOCATION标志只是公告,从 Windows XP 开始受支持。

[in] NumberOfBytes

要分配的字节数。

[in] Tag

要用于已分配内存的池标记。 将池标记指定为一到四个字符的非零字符文本,用单引号分隔 (例如“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 按池标记跟踪内存。

标记的值以反向 (小端) 顺序存储,有时显示。 例如,如果调用方将“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 分配的内存未初始化。 如果内核模式驱动程序要使用户模式软件 (可见,则必须先将此内存设置为零,以避免) 泄露潜在的特权内容。
 

要求

   
最低受支持的客户端 从 Windows 2000 开始可用。
目标平台 通用
标头 wdm.h(包括 Wdm.h、Ntddk.h、Ntifs.h)
Library NtosKrnl.lib
DLL NtosKrnl.exe
IRQL <= DISPATCH_LEVEL (请参阅“备注”部分)
DDI 符合性规则 CheckDeviceObjectFlags (wdm) HwStorPortProhibitedDDIs (storport ) 、 IrqlExAllocatePool (wdm ) 、 IrqlExFree1 (wdm) PowerDownAllocate (wdm) PowerUpFail (wdm) SpNoWait (storport ) 、 StorPortStartIo (storport ) 、 UnsafeAllocatePool (kmdf) UnsafeAllocatePool (wdm)

请参阅

ExAllocatePoolWithQuotaTag

ExAllocatePoolWithTagPriority

ExFreePool

ExFreePoolWithTag

POOL_TYPE