Função ExAllocatePoolWithTag (wdm.h)
A rotina ExAllocatePoolWithTag aloca memória do pool do tipo especificado e retorna um ponteiro para o bloco alocado.
Aviso
ExAllocatePoolWithTag foi preterido em Windows 10, versão 2004 e foi substituído por ExAllocatePool2. Para obter mais informações, consulte Atualizando chamadas de ExAllocatePool preteridas para ExAllocatePool2 e ExAllocatePool3.
Sintaxe
PVOID ExAllocatePoolWithTag(
[in] __drv_strictTypeMatch(__drv_typeExpr)POOL_TYPE PoolType,
[in] SIZE_T NumberOfBytes,
[in] ULONG Tag
);
Parâmetros
[in] PoolType
O tipo de memória do pool a ser alocada. Para obter uma descrição dos tipos de memória do pool disponíveis, consulte POOL_TYPE.
Você pode modificar o valor PoolType por ORing bit a bit com o sinalizador POOL_RAISE_IF_ALLOCATION_FAILURE. Esse sinalizador fará com que uma exceção seja gerada se a solicitação não puder ser atendida. O uso do sinalizador POOL_RAISE_IF_ALLOCATION_FAILURE não é recomendado porque ele é caro.
Da mesma forma, você pode modificar o valor poolType por bit a bit ORing esse valor com o sinalizador POOL_COLD_ALLOCATION como uma dica para o kernel para alocar a memória de páginas que provavelmente serão paginada rapidamente. Para reduzir a quantidade de memória do pool residente o máximo possível, você não deve referenciar essas alocações com frequência. O sinalizador POOL_COLD_ALLOCATION é apenas aviso.
[in] NumberOfBytes
O número de bytes a serem alocados.
[in] 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
ExAllocatePoolWithTag retornará NULL se não houver memória suficiente no pool livre para atender à solicitação. Caso contrário, a rotina retornará um ponteiro para a memória alocada.
Comentários
Essa rotina é usada para a alocação geral de memória do pool.
Se NumberOfBytes for PAGE_SIZE ou superior, um buffer alinhado à página será alocado. Alocações de memória de PAGE_SIZE ou menos são alocadas em uma página e não cruzam limites de página. As alocações de memória de menos de 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.
Uma alocação bem-sucedida que solicita NumberOfBytes< PAGE_SIZE de pool nãopagado fornece ao chamador exatamente o número de bytes de memória solicitados. Se uma solicitação de alocação para NumberOfBytes> PAGE_SIZE for bem-sucedida e NumberOfBytes não for um múltiplo exato de PAGE_SIZE, a última página na alocação conterá bytes que não fazem parte da alocação do chamador. Se possível, o alocador de pool usa esses bytes. Para evitar corromper dados que pertencem a outros componentes do modo kernel, os drivers devem acessar apenas os endereços de armazenamento que eles alocaram explicitamente.
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.
O sistema define automaticamente determinados objetos de evento padrão quando a quantidade de pool (paginada ou não paga) é alta ou baixa. Os drivers podem aguardar esses eventos ajustarem o uso do pool. Para obter mais informações, consulte Objetos de evento padrão.
Os chamadores de ExAllocatePoolWithTag devem estar em execução em IRQL <= DISPATCH_LEVEL. Um chamador em execução no DISPATCH_LEVEL deve especificar um valor XxxNãoPaged para PoolType. Um chamador em execução em IRQL <= APC_LEVEL pode especificar qualquer valor de POOL_TYPE , mas o IRQL e o ambiente também devem ser considerados para determinar o tipo de página.
Não defina NumberOfBytes = 0. Evite alocações de comprimento zero porque elas desperdiçam espaço de cabeçalho do pool e, em muitos casos, indicam um possível problema de validação no código de chamada. Por esse motivo, o Verificador de Driver sinaliza essas alocações como possíveis erros.
Em uma arquitetura de multiprocessador NUMA (acesso à memória não uniforme), ExAllocatePoolWithTag tenta alocar memória local para o processador que está chamando ExAllocatePoolWithTag. Se nenhuma memória local estiver disponível, ExAllocatePoolWithTag alocará a memória disponível mais próxima.
A memória alocada por ExAllocatePoolWithTag não é inicializada. Um driver de modo kernel deve primeiro zero essa memória se ele vai torná-lo visível para o software no modo de usuário (para evitar o vazamento de conteúdo potencialmente privilegiado).
Requisitos
| Requisito | Valor |
|---|---|
| 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 | CheckDeviceObjectFlags(wdm), HwStorPortProhibitedDIs(storport), IrqlExAllocatePool(wdm), IrqlExFree1(wdm), PowerDownAllocate(wdm), PowerUpFail(wdm), SpNoWait(storport), StorPortStartIo(storport), UnsafeAllocatePool(kmdf), UnsafeAllocatePool(wdm) |