Função ExAllocatePool2 (wdm.h)
A rotina ExAllocatePool2 aloca a memória do 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 tipo ULONG64 especificando o tipo de memória do pool juntamente com atributos obrigatórios e opcionais. Vários valores de sinalizador podem ser combinados usando OR em termos de bits. Consulte 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 (bloco). 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.
Valor de retorno
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
- de marca é definido como 0 ou POOL_FLAGS inválido são especificados
Observações
Se você estiver criando um driver destinado a versões do Windows antes do Windows 10, versão 2004, use ExAllocatePoolZero, ExAllocatePoolUninitialized, ExAllocatePoolQuotaZeroou ExAllocatePoolQuotaUninitialized .
Essa rotina tem as seguintes diferenças em relação às rotinas de alocação anteriores (ExAllocatePoolWithTag, ExAllocatePoolWithQuotaTag, ExAllocatePoolWithTagPriority):
A memória é zero inicializada, a menos que POOL_FLAG_UNINITIALIZED seja especificado.
Retornar comportamento em caso de alocação malsucedida. ExAllocatePoolWithQuotaTag gera uma exceção por padrão.
Marcas com um valor de 0 são inválidas.
Ao substituir ExAllocatePoolWithQuotaTag por ExAllocatePool2, especifique 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 ultrapassam limites de página. Alocações de memória inferiores a 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 a limites de 16 bytes em sistemas de 64 bits.
Os drivers só podem usar até o NumberOfBytes eles alocaram explicitamente. Acessar a memória fora desse intervalo pode corromper o pool e causar uma falha no sistema.
O sistema associa a marca de pool à memória alocada. Ferramentas de programação, como o 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 no 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 de . Um chamador em execução no 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 que aloca ExAllocatePool2 é zero inicializada. 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 |
|---|---|
| de cliente com suporte mínimo | Windows 10, versão 2004 |
| da Plataforma de Destino | Universal |
| cabeçalho | wdm.h (include Wdm.h, Ntddk.h, Ntifs.h) |
| biblioteca | NtosKrnl.lib |
| de DLL | NtosKrnl.exe |
| IRQL | IRQL <= DISPATCH_LEVEL (consulte a seção Comentários) |
| regras de conformidade de DDI | HwStorPortProhibitedDIs, SpNoWait, StorPortStartIo |