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)

Confira também

ExAllocatePoolWithTag

ExFreePool

POOL_TYPE