Função ExAllocatePoolWithTagPriority (wdm.h)
A rotina ExAllocatePoolWithTagPriority aloca a memória do pool do tipo especificado.
Aviso
ExAllocatePoolWithTagPriority foi preterido em Windows 10, versão 2004 e foi substituído por ExAllocatePool3. Para obter mais informações, consulte Atualizando chamadas de ExAllocatePool preteridas para ExAllocatePool2 e ExAllocatePool3.
Sintaxe
PVOID ExAllocatePoolWithTagPriority(
[in] __drv_strictTypeMatch(__drv_typeCond)POOL_TYPE PoolType,
[in] SIZE_T NumberOfBytes,
[in] ULONG Tag,
[in] __drv_strictTypeMatch(__drv_typeExpr)EX_POOL_PRIORITY Priority
);
Parâmetros
[in] PoolType
O tipo de memória do pool a ser alocada. Para obter uma descrição dos tipos de memória de pool disponíveis, consulte POOL_TYPE.
Você pode modificar o valor PoolType bit a bit- ORing esse valor 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.
Da mesma forma, você pode modificar o valor poolType 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 de residentes o máximo possível, você não deve referenciar essas alocações com frequência. O sinalizador POOL_COLD_ALLOCATION é apenas aviso e está disponível a partir do Windows XP.
[in] NumberOfBytes
O número de bytes a serem alocados.
[in] Tag
A marca de pool a ser usada para a memória alocada. Para obter mais informações, consulte o parâmetro Tag de ExAllocatePoolWithTag.
[in] Priority
A prioridade dessa solicitação. Defina esse parâmetro como um dos seguintes valores de enumeração EX_POOL_PRIORITY .
| Valor de prioridade | Descrição |
|---|---|
| LowPoolPriority | Especifica que o sistema pode falhar na solicitação quando ele é executado com poucos recursos. As alocações de driver que podem se recuperar de uma falha de alocação usam essa prioridade. |
| NormalPoolPriority | Especifica que o sistema pode falhar na solicitação quando ele é executado muito baixo em recursos. A maioria dos drivers deve usar esse valor. |
| HighPoolPriority | Especifica que o sistema não deve falhar na solicitação, a menos que esteja completamente sem recursos. Os drivers só usam esse valor quando é extremamente importante que a solicitação tenha êxito. |
A enumeração EX_POOL_PRIORITY define as variantes XxxSpecialPoolOverrun e XxxSpecialPoolUnderrun para especificar como a memória deve ser alocada quando o Verificador de Driver (ou pool especial) está habilitado. Se o driver especificar XxxSpecialPoolUnderrun, quando o gerenciador de memória alocar memória do pool especial, ele a alocará no início de uma página física. Se o driver especificar XxxSpecialPoolOverrun, o gerenciador de memória o alocará no final de uma página física.
Retornar valor
ExAllocatePoolWithTagPriority retornará NULL se não houver memória suficiente no pool gratuito para atender à solicitação, a menos que POOL_RAISE_IF_ALLOCATION_FAILURE seja especificado. Caso contrário, a rotina retornará um ponteiro para a memória alocada.
Comentários
Os chamadores de ExAllocatePoolWithTagPriority devem estar sendo executados em IRQL <= DISPATCH_LEVEL. Um chamador em execução em DISPATCH_LEVEL deve especificar um valor XxxNãoPaged para PoolType. Um chamador em execução em 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.
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 aos limites de 16 bytes em sistemas de 64 bits.
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.
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 Objetos de Evento Padrão.
Em uma arquitetura multiprocessador numa (acesso à memória) não uniforme, ExAllocatePoolWithTagPriority tenta alocar memória local para o processador que está chamando ExAllocatePoolWithTagPriority. Se nenhuma memória local estiver disponível, ExAllocatePoolWithTagPriority alocará a memória mais próxima disponível.
A memória alocada por ExAllocatePoolWithTagPriority não é inicializada. Um driver de modo kernel deve primeiro zerar essa memória se ela for torná-la visível para o software no modo de usuário (para evitar 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 de DDI | HwStorPortProhibitedDIs(storport), IrqlExAllocatePool(wdm), IrqlExFree2(wdm), SpNoWait(storport), StorPortStartIo(storport), UnsafeAllocatePool(kmdf), UnsafeAllocatePool(wdm) |