Função ExAllocatePoolWithTagPriority (wdm.h)
A rotina ExAllocatePoolWithTagPriority aloca a memória do pool do tipo especificado.
Aviso
ExAllocatePoolWithTagPriority foi preterido no Windows 10, versão 2004 e foi substituído por ExAllocatePool3. Para obter mais informações, consulte Atualizando chamadas preteridas do ExAllocatePool 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 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.
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 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 com muito poucos 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 seja bem-sucedida. |
A enumeração EX_POOL_PRIORITY define SpecialPoolOverrun e SpecialPoolUnderrun variantes para especificar como a memória deve ser alocada quando do Verificador de Driver (ou pool especial) estiver habilitado. Se o driver especificar SpecialPoolUnderrunxxx, quando o gerenciador de memória alocar memória de de pool especial, ele a alocará no início de uma página física. Se o driver especificar SpecialPoolOverrun, o gerenciador de memória o alocará no final de uma página física.
Valor de retorno
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.
Observações
Os chamadores de ExAllocatePoolWithTagPriority 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.
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.
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.
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.
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 que exAllocatePoolWithTagPriority aloca não é 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 | HwStorPortProhibitedDIs(storport), IrqlExAllocatePool(wdm), IrqlExFree2(wdm), SpNoWait(storport), StorPortStartIo(storport), UnsafeAllocatePool(kmdf), UnsafeAllocatePool(wdm) |