função _RxAllocatePoolWithTag

Artigo
02/02/2024

_RxAllocatePoolWithTag aloca memória de um pool com uma marca de quatro bytes no início do bloco que pode ser usado para ajudar a capturar instâncias de lixo de memória.

Sintaxe

VOID* _RxAllocatePoolWithTag(
   ULONG Type,
   ULONG Size,
   ULONG Tag,
   PSZ   FileName,
   ULONG LineNumber
);

Parâmetros

Tipo
O tipo do pool a ser alocado. Esse parâmetro pode ser um dos seguintes valores de enumeração para POOL_TYPE:

NonPagedPool
Memória do sistema não pageable que pode ser acessada de qualquer IRQL. A memória nonPagedPool é um recurso escasso e os drivers devem alocá-la somente quando necessário. O sistema só pode alocar buffers maiores que PAGE_SIZE de NonPagedPool em múltiplos de PAGE_SIZE. Solicitações de buffers maiores que PAGE_SIZE, mas não uma PAGE_SIZE várias, desperdiçam memória não pageable.

PagedPool
Memória do sistema paginável que só pode ser alocada e acessada no IRQL < DISPATCH_LEVEL.

Tamanho
O tamanho do bloco de memória, em bytes, a ser alocado.

Tag
A marca de quatro bytes a ser usada para marcar o buffer alocado. Para obter uma descrição de como usar marcas, consulte ExAllocatePoolWithTag. O valor ASCII de cada caractere na marca deve estar entre 0 e 127.

FileName
Um ponteiro para o nome do arquivo de origem em que a alocação de memória ocorreu. Esse parâmetro não é usado no momento.

LineNumber
O número de linha no arquivo de origem em que a alocação de memória ocorreu. Esse parâmetro não é usado no momento.

Retornar valor

RxAllocatePoolWithTag 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.

Comentários

É recomendável que a macro RxAllocatePoolWithTag seja chamada em vez de usar essa rotina diretamente. Em builds de varejo, essa macro é definida para chamar ExAllocatePoolWithTag. Em builds verificados, essa macro é definida para chamar _RxAllocatePoolWithTag.

A rotina _RxAllocatePoolWithTag chama ExAllocatePoolWithTagPriority com a prioridade (importância da solicitação) definida como LowPoolPriority. O sistema pode falhar na solicitação de LowPoolPriority quando ele é executado com poucos recursos. Um driver deve estar preparado para se recuperar de uma falha de alocação ao usar essa rotina.

Quando o sistema aloca um buffer da memória do pool de PAGE_SIZE ou superior, ele alinha o buffer em um limite de página. Solicitações de memória menores que PAGE_SIZE não são necessariamente alinhadas nos limites da página, mas sempre se encaixam em uma única página e são alinhadas em um limite de 8 bytes. Qualquer alocação bem-sucedida que solicite um bloco maior que PAGE_SIZE que não seja um múltiplo de PAGE_SIZE desperdiça todos os bytes não utilizados na última página alocada.

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 valor de Tag normalmente é exibido em ordem inversa. Por exemplo, se um chamador passar 'Fred' como uma Marca, ele aparecerá como 'derF' se a memória for despejada ou ao rastrear o uso de memória no depurador.

A memória alocada com _RxAllocatePoolWithTag deve ser liberada chamando _RxFreePool.

Os chamadores de _RxAllocatePoolWithTag devem estar em execução em IRQL <= DISPATCH_LEVEL. Um chamador em execução em DISPATCH_LEVEL deve especificar um valor NonPagedPool para o parâmetro Type . Um chamador em execução em IRQL <= APC_LEVEL pode especificar qualquer valor POOL_TYPE para o parâmetro Type .