Función ExAllocatePool2 (wdm.h)

  • Artículo

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

Sintaxis

DECLSPEC_RESTRICT PVOID ExAllocatePool2(
  POOL_FLAGS Flags,
  SIZE_T     NumberOfBytes,
  ULONG      Tag
);

Parámetros

Flags

Valor de tipo ULONG64 que especifica el tipo de memoria del grupo junto con los atributos obligatorios y opcionales. Se pueden combinar varios valores de marca mediante OR bit a bit. Consulte POOL_FLAGS para conocer los valores posibles.

NumberOfBytes

Especifica un número distinto de cero de bytes que se van a asignar.

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 delimitado 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

ExAllocatePool2 devuelve un puntero a la memoria asignada.

Las condiciones siguientes hacen que la función devuelva NULL de forma predeterminada. Si se especifica POOL_FLAG_RAISE_ON_FAILURE , la función genera una excepción.

  • Memoria suficiente
  • La etiqueta se establece en 0 o se especifican POOL_FLAGS no válidos.

Comentarios

Si va a compilar un controlador destinado a versiones de Windows anteriores a Windows 10, versión 2004, use ExAllocatePoolZero, ExAllocatePoolUninitialized, ExAllocatePoolQuotaZero o ExAllocatePoolQuotaUninitialized.

Esta rutina tiene las siguientes diferencias con respecto a las rutinas de asignación anteriores (ExAllocatePoolWithTag, ExAllocatePoolWithQuotaTag, ExAllocatePoolWithTagPriority):

  1. La memoria es cero inicializada a menos que se especifique POOL_FLAG_UNINITIALIZED .

  2. Devuelve el comportamiento en caso de asignación incorrecta. ExAllocatePoolWithQuotaTag genera una excepción de forma predeterminada.

  3. Las etiquetas con un valor de 0 no son válidas.

Al reemplazar ExAllocatePoolWithQuotaTag por ExAllocatePool2, debe especificar la marca POOL_FLAG_USE_QUOTA . Para obtener más información sobre las marcas de grupo, consulte POOL_FLAGS.

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

Los controladores solo pueden usar hasta numberOfBytes que hayan asignado explícitamente. El acceso a la memoria fuera de este intervalo puede dañar el grupo y provocar que el sistema se bloquee.

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 una 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.

Los autores de llamadas de ExAllocatePool2 deben ejecutarse en IRQL <= DISPATCH_LEVEL. Un llamador que se ejecuta en DISPATCH_LEVEL debe especificar POOL_FLAG_NON_PAGED o POOL_FLAG_NON_PAGED_EXECUTABLE para Marcas. Un llamador que se ejecuta en IRQL <= APC_LEVEL puede especificar POOL_FLAG_PAGED, pero si se tendrá acceso a la memoria desde el código que se ejecuta en DISPATCH_LEVEL, todavía debe asignar memoria no paginada.

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

La memoria que asigna ExAllocatePool2 es cero inicializada. Los controladores en modo kernel no deben dejar de participar en ceros para las asignaciones que se copiarán en una ubicación que no es de confianza (modo de usuario, a través de la red, etc.) para evitar la divulgación de información confidencial.

Requisitos

Requisito Value
Cliente mínimo compatible Windows 10, versión 2004
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 HwStorPortProhibitedDIs, SpNoWait, StorPortStartIo

Consulte también

ExAllocatePool3