ALLOCATE_FUNCTION_EX función de devolución de llamada (wdm.h)

Artículo
03/08/2023

La rutina LookasideListAllocateEx asigna el almacenamiento para una nueva entrada lookaside-list cuando un cliente solicita una entrada de una lista de búsqueda vacía.

Sintaxis

ALLOCATE_FUNCTION_EX AllocateFunctionEx;

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

Parámetros

[in] PoolType

Especifica el tipo de almacenamiento que se va a asignar para la nueva entrada lookaside-list. El autor de la llamada establece este parámetro en un valor de enumeración de POOL_TYPE válido y, posiblemente, las operaciones organizativas bit a bit con uno de los siguientes bits de marca:

POOL_RAISE_IF_ALLOCATION_FAILURE
POOL_QUOTA_FAIL_INSTEAD_OF_RAISE

Para obtener más información sobre la marca de POOL_RAISE_IF_ALLOCATION_FAILURE, vea ExAllocatePoolWithTag. Para obtener más información sobre la marca de POOL_QUOTA_FAIL_INSTEAD_OF_RAISE, vea ExAllocatePoolWithQuotaTag.

Si, en la llamada ExInitializeLookasideListEx que inicializó la lista de lookaside, el parámetro Flags es cero, el parámetro PoolType que recibe la rutina LookasideListAllocateEx es el mismo valor de parámetro PoolType que se pasó a ExInitializeLookasideListEx.

Si, en la llamada ExInitializeLookasideListEx , Flags = EX_LOOKASIDE_LIST_EX_FLAGS_RAISE_ON_FAIL, el parámetro PoolType que recibe la rutina LookasideListAllocateEx es el OR bit a bit de POOL_RAISE_IF_ALLOCATION_FAILURE y el valor del parámetro PoolType que se pasó a ExInitializeLookasideListEx. La rutina LookasideListAllocateEx puede pasar su valor de parámetro PoolType , sin modificaciones, a la rutina ExAllocatePoolWithTag .

Si, en la llamada ExInitializeLookasideListEx , Flags = EX_LOOKASIDE_LIST_EX_FLAGS_FAIL_NO_RAISE, el parámetro PoolType que recibe la rutina LookasideListAllocateEx es el OR bit a bit de POOL_QUOTA_FAIL_INSTEAD_OF_RAISE y el valor PoolType que se pasó a ExInitializeLookasideListEx. La rutina LookasideListAllocateEx puede pasar su valor de parámetro PoolType , sin modificaciones, a la rutina ExAllocatePoolWithQuotaTag .

[in] NumberOfBytes

Especifica el tamaño, en bytes, de la entrada lookaside-list que se va a asignar.

[in] Tag

Especifica la etiqueta de grupo de cuatro bytes que se va a usar para marcar el almacenamiento asignado para la nueva entrada lookaside-list. Para obtener más información sobre las etiquetas de grupo, consulte la descripción del parámetro Tag en ExAllocatePoolWithTag.

[in, out] Lookaside

Puntero a una estructura de LOOKASIDE_LIST_EX que describe la lista de aspecto. Esta estructura se inicializó anteriormente mediante la rutina ExInitializeLookasideListEx .

Valor devuelto

LookasideListAllocateEx devuelve un puntero a la entrada de lookaside-list asignada. Si la rutina no puede asignar una entrada, devuelve NULL.

Comentarios

Un controlador que crea una lista de búsqueda puede implementar una rutina LookasideListAllocateEx para asignar dinámicamente búferes para la lista. Un búfer que no está en uso se almacena como entrada en la lista. Todas las entradas de una lista de búsqueda son búferes de un tamaño uniforme, que el controlador especifica cuándo se inicializa la lista.

El controlador proporciona un puntero a una rutina LookasideListAllocateEx personalizada como parámetro de entrada en la llamada ExInitializeLookasideListEx que inicializa la lista de lookaside. Si el controlador establece este parámetro en NULL, la lista de búsqueda usa una rutina de asignación predeterminada en su lugar.

Un controlador llama a la rutina ExAllocateFromLookasideListEx para asignar una entrada de una lista de aspecto. Si la lista está vacía (no contiene entradas), ExAllocateFromLookasideListEx llama a LookasideListAllocateEx para asignar dinámicamente el almacenamiento para una nueva entrada. LookasideListAllocateEx devuelve un puntero a la entrada recién asignada si la asignación se realiza correctamente. De lo contrario, devuelve NULL.

Los parámetros PoolType, NumberOfBytes, Tag y Lookaside contienen los mismos valores que se pasaron como parámetros de entrada en la llamada ExInitializeLookasideListEx que inicializó la lista de lookaside.

La rutina LookasideListAllocateEx puede usar el parámetro Lookaside para obtener acceso a los datos de contexto privados que el controlador ha asociado a la lista de búsqueda. Para obtener más información, vea el ejemplo de código en ExInitializeLookasideListEx.

Para obtener más información sobre las listas de búsqueda, consulte Uso de lookaside Listas.

Se llama a la rutina LookasideListAllocateEx en el mismo IRQL que la llamada a ExAllocateFromLookasideListEx que solicita la entrada. Para una llamada que solicita una entrada que reside en memoria paginada, el autor de la llamada debe ejecutar IRQL <= APC_LEVEL. Para una llamada que solicita una entrada que reside en memoria no paginada, el autor de la llamada debe ejecutar IRQL <= DISPATCH_LEVEL.

Ejemplos

Para definir una rutina de devolución de llamada LookasideListAllocateEx , primero debe proporcionar una declaración de función que identifique el tipo de rutina de devolución de llamada que está definiendo. Windows proporciona un conjunto de tipos de función de devolución de llamada para controladores. Declarar una función mediante los tipos de función de devolución de llamada ayuda a Code Analysis for Drivers, Static Driver Verifier (SDV) y otras herramientas de comprobación encuentran errores y es un requisito para escribir controladores para el sistema operativo Windows.

Por ejemplo, para definir una rutina de devolución de llamada LookasideListAllocateEx denominada MyLookasideListAllocateEx, use el tipo de FREE_FUNCTION_EX como se muestra en este ejemplo de código:

FREE_FUNCTION_EX MyLookasideListFreeEx;

A continuación, implemente la rutina de devolución de llamada de la siguiente manera:

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

El tipo de función FREE_FUNCTION_EX se define en el archivo de encabezado Wdm.h. Para identificar con más precisión los errores al ejecutar las herramientas de análisis de código, asegúrese de agregar la anotación a la _Use_decl_annotations_ definición de la función. La _Use_decl_annotations_ anotación garantiza que se usen las anotaciones que se aplican al tipo de función FREE_FUNCTION_EX en el archivo de encabezado. Para obtener más información sobre los requisitos de las declaraciones de función, vea Declarar funciones mediante tipos de roles de función para controladores WDM. Para obtener información sobre _Use_decl_annotations_, consulte Anotación del comportamiento de la función.