Función ExAllocatePoolWithTag (wdm.h)

  • Artículo

La rutina ExAllocatePoolWithTag asigna memoria del grupo del tipo especificado y devuelve un puntero al bloque asignado.

Advertencia

ExAllocatePoolWithTag ha quedado en desuso en Windows 10, versión 2004 y se ha reemplazado por ExAllocatePool2. Para obtener más información, vea Actualización de llamadas exAllocatePool en desuso a ExAllocatePool2 y ExAllocatePool3.

Sintaxis

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

Parámetros

[in] PoolType

Tipo de memoria del grupo que se va a asignar. Para obtener una descripción de los tipos de memoria del grupo disponibles, consulte POOL_TYPE.

Puede modificar el valor PoolType bit a bit-ORing con la marca POOL_RAISE_IF_ALLOCATION_FAILURE. Esta marca hace que se genere una excepción si no se puede satisfacer la solicitud. No se recomienda el uso de la marca POOL_RAISE_IF_ALLOCATION_FAILURE porque es costoso.

Del mismo modo, puede modificar el valor PoolType mediante ORing bit a bit con la marca POOL_COLD_ALLOCATION como sugerencia al kernel para asignar la memoria de las páginas que probablemente se paginan rápidamente. Para reducir la cantidad de memoria del grupo residente tanto como sea posible, no debe hacer referencia a estas asignaciones con frecuencia. La marca de POOL_COLD_ALLOCATION solo es de aviso.

[in] NumberOfBytes

Número de bytes que se van a asignar.

[in] Tag

Etiqueta de grupo que se va a usar para la memoria asignada. Especifique la etiqueta de grupo como un literal de carácter distinto de cero de uno a cuatro caracteres delimitados por comillas simples (por ejemplo, "Tag1"). Normalmente, la cadena se especifica en orden inverso (por ejemplo, "1gaT"). Cada carácter ASCII de la etiqueta debe ser un valor del intervalo 0x20 (espacio) para 0x7E (tilde). Cada ruta de acceso de código de asignación debe usar una etiqueta de grupo única para ayudar a los depuradores y comprobadores a identificar la ruta de acceso del código.

Valor devuelto

ExAllocatePoolWithTag devuelve NULL si no hay memoria suficiente en el grupo libre para satisfacer la solicitud. De lo contrario, la rutina devuelve un puntero a la memoria asignada.

Comentarios

Esta rutina se usa para la asignación de memoria del grupo general.

Si NumberOfBytes es PAGE_SIZE o superior, se asigna un búfer alineado con páginas. Las asignaciones de memoria de PAGE_SIZE o menos se asignan dentro de una página y no cruzan los límites de la página. Las asignaciones de memoria de menos de PAGE_SIZE no están necesariamente alineadas con páginas, pero están alineadas con límites de 8 bytes en sistemas de 32 bits y límites de 16 bytes en sistemas de 64 bits.

Una asignación correcta que solicita NumberOfBytes PAGE_SIZE del grupo no paginado proporciona al autor de la llamada exactamente el número de bytes solicitados < de memoria. Si una solicitud de asignación para NumberOfBytes> PAGE_SIZE se realiza correctamente y NumberOfBytes no es un múltiplo exacto de PAGE_SIZE, la última página de la asignación contiene bytes que no forman parte de la asignación del autor de la llamada. Si es posible, el asignador del grupo usa estos bytes. Para evitar daños en los datos que pertenecen a otros componentes del modo kernel, los controladores solo deben tener acceso a las direcciones de almacenamiento que hayan asignado explícitamente.

El sistema asocia la etiqueta de grupo a la memoria asignada. Las herramientas de programación, como WinDbg, pueden mostrar la etiqueta de grupo asociada a cada búfer asignado. Gflags, una herramienta incluida en Herramientas de depuración para Windows, activa una característica del sistema que solicita la asignación de un grupo especial para una etiqueta de grupo determinada. Poolmon, que se incluye en el WDK, realiza un seguimiento de la memoria por etiqueta de grupo.

El valor de Tag se almacena y, a veces, se muestra, en orden inverso (little-endian). Por ejemplo, si un autor de la llamada pasa "Fred" como etiqueta, aparece como "derF" en un volcado de memoria del grupo y en el seguimiento del uso del grupo en el depurador, y como 0x64657246 en el Registro y en la herramienta se muestra.

El búfer asignado se puede liberar con ExFreePool o ExFreePoolWithTag.

El sistema establece automáticamente determinados objetos de evento estándar cuando la cantidad de grupo (paginada o no paginada) es alta o baja. Los controladores pueden esperar a que estos eventos ajusten su uso del grupo. Para obtener más información, vea Objetos de eventos estándar.

Los autores de llamadas de ExAllocatePoolWithTag deben ejecutarse en IRQL <= DISPATCH_LEVEL. Un llamador que se ejecuta en DISPATCH_LEVEL debe especificar un valor NonPagedXxx para PoolType. Un llamador que se ejecuta en IRQL <= APC_LEVEL puede especificar cualquier valor de POOL_TYPE , pero también se debe tener en cuenta el irQL y el entorno para determinar el tipo de página.

No establezca NumberOfBytes = 0. Evite las asignaciones de longitud cero porque desperdician el espacio de encabezado del grupo y, en muchos casos, indican un posible problema de validación en el código de llamada. Por este motivo, el Comprobador de controladores marca tales asignaciones como posibles errores.

En una arquitectura de varios procesadores de acceso a memoria no uniforme (NUMA), ExAllocatePoolWithTag intenta asignar memoria local al procesador que llama a ExAllocatePoolWithTag. Si no hay memoria local disponible, ExAllocatePoolWithTag asigna la memoria disponible más cercana.

La memoria que ExAllocatePoolWithTag asigna no está inicializada. Un controlador en modo kernel debe cero primero esta memoria si va a hacer que sea visible para el software en modo de usuario (para evitar la pérdida de contenido potencialmente con privilegios).

Requisitos

Requisito Value
Plataforma de destino Universal
Encabezado wdm.h (incluya Wdm.h, Ntddk.h, Ntifs.h)
Library NtosKrnl.lib
Archivo DLL NtosKrnl.exe
IRQL IRQL <= DISPATCH_LEVEL (consulte la sección Comentarios)
Reglas de cumplimiento de DDI CheckDeviceObjectFlags(wdm), HwStorPortProhibitedDIs(storport), IrqlExAllocatePool(wdm), IrqlExFree1(wdm), PowerDownAllocate(wdm), PowerUpFail(wdm), SpNoWait(storport), StorPortStartIo(storport), UnsafeAllocatePool(kmdf), UnsafeAllocatePool(wdm)

Consulte también

ExAllocatePoolWithQuotaTag

ExAllocatePoolWithTagPriority

ExFreePool

ExFreePoolWithTag

POOL_TYPE