Função ExAllocatePool2 (wdm.h)

A rotina ExAllocatePool2 aloca memória de pool do tipo especificado e retorna um ponteiro para o bloco alocado.

Sintaxe

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

Parâmetros

Flags

Um valor de tipo ULONG64 especificando o tipo de memória do pool junto com atributos obrigatórios e opcionais. Vários valores de sinalizador podem ser combinados usando OR bit a bit. Confira POOL_FLAGS para obter valores possíveis.

NumberOfBytes

Especifica um número diferente de zero de bytes a serem alocados.

Tag

A marca de pool a ser usada para a memória alocada. Especifique a marca de pool como um literal de caractere diferente de zero de um a quatro caracteres delimitado por aspas simples (por exemplo, Tag1). A cadeia de caracteres geralmente é especificada em ordem inversa (por exemplo, 1gaT). Cada caractere ASCII na marca deve ser um valor no intervalo 0x20 (espaço) para 0x7E (til). Cada caminho de código de alocação deve usar uma marca de pool exclusiva para ajudar os depuradores e verificadores a identificar o caminho do código.

Retornar valor

ExAllocatePool2 retorna um ponteiro para a memória alocada.

As condições a seguir fazem com que a função retorne NULL por padrão. Se POOL_FLAG_RAISE_ON_FAILURE for especificado, a função gerará uma exceção.

• Memória insuficiente
• A marca é definida como 0 ou POOL_FLAGS inválidos são especificados

Comentários

Se você estiver criando um driver destinado a versões do Windows antes de Windows 10, versão 2004, use ExAllocatePoolZero, ExAllocatePoolUninitialized, ExAllocatePoolQuotaZero ou ExAllocatePoolQuotaUninitialized.

Essa rotina tem as seguintes diferenças em relação às rotinas de alocação anteriores (ExAllocatePoolWithTag, ExAllocatePoolWithQuotaTag, ExAllocatePoolWithTagPriority):

1. A memória é inicializada zero, a menos que POOL_FLAG_UNINITIALIZED seja especificado.

2. Retornar comportamento em caso de alocação malsucedida. ExAllocatePoolWithQuotaTag gera uma exceção por padrão.

3. Marcas com um valor de 0 são inválidas.

Ao substituir ExAllocatePoolWithQuotaTag por ExAllocatePool2, você deve especificar o sinalizador POOL_FLAG_USE_QUOTA . Para obter mais informações sobre sinalizadores de pool, consulte POOL_FLAGS.

Se NumberOfBytes for PAGE_SIZE ou maior, um buffer alinhado à página será alocado. Alocações de memória de PAGE_SIZE ou menos são alocadas dentro de uma página e não cruzam limites de página. As alocações de memória menores que PAGE_SIZE não são necessariamente alinhadas à página, mas estão alinhadas aos limites de 8 bytes em sistemas de 32 bits e aos limites de 16 bytes em sistemas de 64 bits.

Os drivers só podem usar até o NumberOfBytes que alocaram explicitamente. O acesso à memória fora desse intervalo pode corromper o pool e fazer com que o sistema falhe.

O sistema associa a marca de pool à memória alocada. Ferramentas de programação, como WinDbg, podem exibir a marca de pool associada a cada buffer alocado. O Gflags, uma ferramenta incluída nas Ferramentas de Depuração para Windows, ativa um recurso do sistema que solicita a alocação do pool especial para uma marca de pool específica. O Poolmon, que está incluído no WDK, rastreia a memória por marca de pool.

O valor de Tag é armazenado e, às vezes, exibido, na ordem inversa (little-endian). Por exemplo, se um chamador passar Fred como uma Marca, ele aparecerá como derF em um despejo de pool e no acompanhamento de uso do pool no depurador, e como 0x64657246 no registro e na ferramenta é exibido.

O buffer alocado pode ser liberado com ExFreePool ou ExFreePoolWithTag.

Os chamadores de ExAllocatePool2 devem estar em execução em IRQL <= DISPATCH_LEVEL. Um chamador em execução no DISPATCH_LEVEL deve especificar POOL_FLAG_NON_PAGED ou POOL_FLAG_NON_PAGED_EXECUTABLE para Sinalizadores. Um chamador em execução em IRQL <= APC_LEVEL pode especificar POOL_FLAG_PAGED, mas se a memória for acessada do código em execução em DISPATCH_LEVEL, você ainda deverá alocar memória não paginada.

Em uma arquitetura de multiprocessador NUMA (acesso à memória) não uniforme, ExAllocatePool2 tenta alocar memória local para o processador que está chamando ExAllocatePool2. Se nenhuma memória local estiver disponível, ExAllocatePool2 alocará a memória mais próxima disponível.

A memória alocada por ExAllocatePool2 é inicializada como zero. Os drivers no modo kernel não devem recusar a zero para alocações que serão copiadas para um local não confiável (modo de usuário, pela rede etc.) para evitar a divulgação de informações confidenciais.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 10, versão 2004
Plataforma de Destino	Universal
Cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
Biblioteca	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	IRQL <= DISPATCH_LEVEL (consulte a seção Comentários)
Regras de conformidade da DDI	HwStorPortProhibitedDDIs, SpNoWait, StorPortStartIo

Confira também

ExAllocatePool3