ALLOCATE_FUNCTION_EX回调函数 (wdm.h)

项目
02/27/2024

当客户端从空的 lookaside 列表中请求某个条目时， LookasideListAllocateEx 例程为新的 lookaside-list 条目分配存储。

语法

ALLOCATE_FUNCTION_EX AllocateFunctionEx;

PVOID AllocateFunctionEx(
  [in]      POOL_TYPE PoolType,
  [in]      SIZE_T NumberOfBytes,
  [in]      ULONG Tag,
  [in, out] PLOOKASIDE_LIST_EX Lookaside
)
{...}

参数

[in] PoolType

指定要为新的 lookaside-list 条目分配的存储类型。调用方将此参数设置为有效的 POOL_TYPE 枚举值，并可能按位将此值设置为以下标志位之一：

POOL_RAISE_IF_ALLOCATION_FAILURE
POOL_QUOTA_FAIL_INSTEAD_OF_RAISE

有关POOL_RAISE_IF_ALLOCATION_FAILURE标志的详细信息，请参阅 ExAllocatePoolWithTag。有关 POOL_QUOTA_FAIL_INSTEAD_OF_RAISE 标志的详细信息，请参阅 ExAllocatePoolWithQuotaTag。

如果在初始化 lookaside 列表的 ExInitializeLookasideListEx 调用中，Flags 参数为零，则 LookasideListAllocateEx 例程接收的 PoolType 参数与传递给 ExInitializeLookasideListEx 的 PoolType 参数值相同。

如果在 ExInitializeLookasideListEx 调用中，Flags = EX_LOOKASIDE_LIST_EX_FLAGS_RAISE_ON_FAIL，则 LookasideListAllocateEx 例程接收的 PoolType 参数是POOL_RAISE_IF_ALLOCATION_FAILURE的按位 OR 和传递给 ExInitializeLookasideListEx 的 PoolType 参数值。 LookasideListAllocateEx 例程可以将其 PoolType 参数值传递给 ExAllocatePoolWithTag 例程，而无需修改。

如果在 ExInitializeLookasideListEx 调用中，Flags = EX_LOOKASIDE_LIST_EX_FLAGS_FAIL_NO_RAISE，则 LookasideListAllocateEx 例程接收的 PoolType 参数是POOL_QUOTA_FAIL_INSTEAD_OF_RAISE的按位 OR 和传递给 ExInitializeLookasideListEx 的 PoolType 值。 LookasideListAllocateEx 例程可以将其 PoolType 参数值（无需修改）传递到 ExAllocatePoolWithQuotaTag 例程。

[in] NumberOfBytes

指定要分配的 lookaside-list 条目的大小（以字节为单位）。

[in] Tag

指定要用于标记新 lookaside-list 条目的已分配存储的四字节池标记。有关池标记的详细信息，请参阅 ExAllocatePoolWithTag 中 Tag 参数的说明。

[in, out] Lookaside

指向描述旁观列表的LOOKASIDE_LIST_EX 结构的指针。此结构以前由 ExInitializeLookasideListEx 例程初始化。

返回值

LookasideListAllocateEx 返回指向分配的 lookaside-list 条目的指针。如果例程无法分配条目，则返回 NULL。

注解

创建 lookaside 列表的驱动程序可以实现 LookasideListAllocateEx 例程，以动态分配列表的缓冲区。未使用的缓冲区作为条目存储在列表中。旁观列表中的所有条目都是统一大小的缓冲区，驱动程序在初始化列表时会指定该缓冲区。

驱动程序提供指向自定义 LookasideListAllocateEx 例程的指针，作为初始化 lookaside 列表的 ExInitializeLookasideListEx 调用中的输入参数。如果驱动程序将此参数设置为 NULL，则查找列表将改用默认分配例程。

驱动程序调用 ExAllocateFromLookasideListEx 例程来分配 lookaside 列表中的条目。如果列表为空 (不包含) 条目， ExAllocateFromLookasideListEx 将调用 LookasideListAllocateEx 来动态分配新条目的存储。如果分配成功，LookasideListAllocateEx 将返回指向新分配条目的指针。否则，它将返回 NULL。

PoolType、NumberOfBytes、Tag 和 Lookaside 参数包含在初始化 lookaside 列表的 ExInitializeLookasideListEx 调用中作为输入参数传递的相同值。

LookasideListAllocateEx 例程可以使用 Lookaside 参数访问驱动程序与 lookaside 列表关联的专用上下文数据。有关详细信息，请参阅 ExInitializeLookasideListEx 中的代码示例。

有关 lookaside 列表的详细信息，请参阅 Using Lookaside Lists。

LookasideListAllocateEx 例程与调用请求该条目的 ExAllocateFromLookasideListEx 在同一 IRQL 中调用。对于请求位于分页内存中的条目的调用，调用方必须运行 IRQL <= APC_LEVEL。对于请求驻留在非分页内存中的条目的调用，调用方必须运行 IRQL <= DISPATCH_LEVEL。

示例

若要定义 LookasideListAllocateEx 回调例程，必须首先提供一个函数声明来标识要定义的回调例程的类型。 Windows 为驱动程序提供了一组回调函数类型。使用回调函数类型声明函数可帮助驱动程序的代码分析、静态驱动程序验证程序 (SDV) 和其他验证工具查找错误，这是为 Windows 操作系统编写驱动程序的要求。

例如，若要定义名为 MyLookasideListAllocateEx的 LookasideListAllocateEx 回调例程，请使用 FREE_FUNCTION_EX 类型，如以下代码示例所示：

FREE_FUNCTION_EX MyLookasideListFreeEx;

然后，按如下所示实现回调例程：

_Use_decl_annotations_
VOID
  MyLookasideListFreeEx(
    PVOID  Buffer,
    PLOOKASIDE_LIST_EX  Lookaside
    )
  {
      // Function body
  }

FREE_FUNCTION_EX函数类型在 Wdm.h 头文件中定义。若要在运行代码分析工具时更准确地识别错误，请务必将 _Use_decl_annotations_ 注释添加到函数定义。注释 _Use_decl_annotations_ 可确保使用应用于头文件中FREE_FUNCTION_EX函数类型的注释。有关函数声明要求的详细信息，请参阅使用 WDM 驱动程序的函数角色类型声明函数。有关的信息 _Use_decl_annotations_，请参阅批注函数行为。