Função ExAllocatePoolWithTag (wdm.h)
A rotina ExAllocatePoolWithTag aloca a memória do pool do tipo especificado e retorna um ponteiro para o bloco alocado.
Aviso
ExAllocatePoolWithTag foi preterido no Windows 10, versão 2004 e foi substituído por ExAllocatePool2. Para obter mais informações, consulte Atualizando chamadas preteridas do ExAllocatePool 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 meio de ORing bit a bit desse valor com o sinalizador POOL_RAISE_IF_ALLOCATION_FAILURE. Esse sinalizador fará com que uma exceção seja acionada se a solicitação não puder ser atendida. O uso do sinalizador de POOL_RAISE_IF_ALLOCATION_FAILURE não é recomendado porque ele é caro.
Da mesma forma, você pode modificar o valor PoolType por meio de ORing bit a bit com o sinalizador POOL_COLD_ALLOCATION como uma dica para o kernel para alocar a memória de páginas que provavelmente serão excluídas rapidamente. Para reduzir a quantidade de memória do pool de residentes o máximo possível, você não deve referenciar essas alocações com frequência. O sinalizador POOL_COLD_ALLOCATION é apenas um 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 (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
ExAllocatePoolWithTag retornará NULL se não houver memória suficiente no pool gratuito para atender à solicitação. Caso contrário, a rotina retornará um ponteiro para a memória alocada.
Observações
Essa rotina é usada para a alocação geral de memória do pool.
Se NumberOfBytes for PAGE_SIZE ou maior, um buffer alinhado à página será alocado. As 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.
Uma alocação bem-sucedida solicitando NumberOfBytes< PAGE_SIZE de pool nãopagado fornece ao chamador exatamente o número de bytes solicitados de memória. 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 o WinDbg, podem exibir a marca de pool associada a cada buffer alocado. O Gflags, uma ferramenta incluída no Ferramentas de Depuração para Windows, ativa um recurso do sistema que solicita alocação de de pool especial para uma marca de pool específica. poolmon, que está incluído no WDK, rastreia a memória por marca de pool.
O valor de de Marca é armazenado e, às vezes, exibido, na ordem inversa (little-endian). Por exemplo, se um chamador passar 'Fred' como um 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 esperar que esses eventos ajustem o uso do pool. Para obter mais informações, consulte de objetos de evento padrão.
Os chamadores de ExAllocatePoolWithTag devem estar em execução no <DO IRQL = DISPATCH_LEVEL. Um chamador em execução em DISPATCH_LEVEL deve especificar um valor Xxx nãopagado para poolType. Um chamador em execução no IRQL <= APC_LEVEL pode especificar qualquer valor 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, Verificador de Driver sinalizadores como alocações possíveis.
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 mais próxima disponível.
A memória que aloca ExAllocatePoolWithTag não está inicializada. Um driver de modo kernel deve primeiro zero essa memória se ele for torná-la visível para o software no modo de usuário (para evitar o vazamento de conteúdo potencialmente privilegiado).
Requisitos
| Requisito | Valor |
|---|---|
| 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 | CheckDeviceObjectFlags(wdm), HwStorPortProhibitedDIs(storport), IrqlExAllocatePool(wdm), IrqlExFree1(wdm), PowerDownAllocate (wdm), PowerUpFail(wdm), SpNoWait(storport), StorPortStartIo(storport), UnsafeAllocatePool(kmdf), UnsafeAllocatePool(wdm) |