ALLOCATE_FUNCTION_EX função de retorno de chamada (wdm.h)

Artigo
03/08/2023

A rotina LookasideListAllocateEx aloca o armazenamento para uma nova entrada lookaside-list quando um cliente solicita uma entrada de uma lista lookaside vazia.

Sintaxe

ALLOCATE_FUNCTION_EX AllocateFunctionEx;

PVOID AllocateFunctionEx(
  [in]      POOL_TYPE PoolType,
  [in]      SIZE_T NumberOfBytes,
  [in]      ULONG Tag,
  [in, out] PLOOKASIDE_LIST_EX Lookaside
)
{...}

Parâmetros

[in] PoolType

Especifica o tipo de armazenamento a ser alocado para a nova entrada lookaside-list. O chamador define esse parâmetro como um valor de enumeração de POOL_TYPE válido e, possivelmente, ORs bit a bit desse valor com um dos seguintes bits de sinalizador:

POOL_RAISE_IF_ALLOCATION_FAILURE
POOL_QUOTA_FAIL_INSTEAD_OF_RAISE

Para obter mais informações sobre o sinalizador POOL_RAISE_IF_ALLOCATION_FAILURE, consulte ExAllocatePoolWithTag. Para obter mais informações sobre o sinalizador POOL_QUOTA_FAIL_INSTEAD_OF_RAISE, consulte ExAllocatePoolWithQuotaTag.

Se, na chamada ExInitializeLookasideListEx que inicializou a lista lookaside, o parâmetro Flags for zero, o parâmetro PoolType que a rotina LookasideListAllocateEx recebe será o mesmo valor de parâmetro PoolType que foi passado para ExInitializeLookasideListEx.

Se, na chamada ExInitializeLookasideListEx , Flags = EX_LOOKASIDE_LIST_EX_FLAGS_RAISE_ON_FAIL, o parâmetro PoolType que a rotina LookasideListAllocateEx recebe é o OR bit a bit de POOL_RAISE_IF_ALLOCATION_FAILURE e o valor do parâmetro PoolType que foi passado para ExInitializeLookasideListEx. A rotina LookasideListAllocateEx pode passar seu valor de parâmetro PoolType , sem modificação, para a rotina ExAllocatePoolWithTag .

Se, na chamada ExInitializeLookasideListEx , Flags = EX_LOOKASIDE_LIST_EX_FLAGS_FAIL_NO_RAISE, o parâmetro PoolType que a rotina LookasideListAllocateEx recebe é o OR bit a bit de POOL_QUOTA_FAIL_INSTEAD_OF_RAISE e o valor PoolType que foi passado para ExInitializeLookasideListEx. A rotina LookasideListAllocateEx pode passar seu valor de parâmetro PoolType , sem modificação, para a rotina ExAllocatePoolWithQuotaTag .

[in] NumberOfBytes

Especifica o tamanho, em bytes, da entrada lookaside-list a ser alocada.

[in] Tag

Especifica a marca de pool de quatro bytes a ser usada para marcar o armazenamento alocado para a nova entrada lookaside-list. Para obter mais informações sobre marcas de pool, consulte a descrição do parâmetro Tag em ExAllocatePoolWithTag.

[in, out] Lookaside

Um ponteiro para uma estrutura LOOKASIDE_LIST_EX que descreve a lista lookaside. Essa estrutura foi inicializada anteriormente pela rotina ExInitializeLookasideListEx .

Retornar valor

LookasideListAllocateEx retorna um ponteiro para a entrada de lista lookaside alocada. Se a rotina não puder alocar uma entrada, ela retornará NULL.

Comentários

Um driver que cria uma lista lookaside pode implementar uma rotina LookasideListAllocateEx para alocar dinamicamente buffers para a lista. Um buffer que não está em uso é armazenado como uma entrada na lista. Todas as entradas em uma lista lookaside são buffers de um tamanho uniforme, que o driver especifica quando a lista é inicializada.

O driver fornece um ponteiro para uma rotina Personalizada LookasideListAllocateEx como um parâmetro de entrada na chamada ExInitializeLookasideListEx que inicializa a lista lookaside. Se o driver definir esse parâmetro como NULL, a lista lookaside usará uma rotina de alocação padrão.

Um driver chama a rotina ExAllocateFromLookasideListEx para alocar uma entrada de uma lista lookaside. Se a lista estiver vazia (não contiver entradas), ExAllocateFromLookasideListExchamará LookasideListAllocateEx para alocar dinamicamente o armazenamento para uma nova entrada. LookasideListAllocateEx retornará um ponteiro para a entrada recém-alocada se a alocação for bem-sucedida. Caso contrário, ele retornará NULL.

Os parâmetros PoolType, NumberOfBytes, Tag e Lookaside contêm os mesmos valores que foram passados como parâmetros de entrada na chamada ExInitializeLookasideListEx que inicializou a lista lookaside.

A rotina LookasideListAllocateEx pode usar o parâmetro Lookaside para acessar dados de contexto privado que o driver associou à lista lookaside. Para obter mais informações, consulte o exemplo de código em ExInitializeLookasideListEx.

Para obter mais informações sobre listas lookaside, consulte Using Lookaside Listas.

A rotina LookasideListAllocateEx é chamada no mesmo IRQL que a chamada para ExAllocateFromLookasideListEx que solicita a entrada. Para uma chamada que solicita uma entrada que reside na memória paginada, o chamador deve estar executando IRQL <= APC_LEVEL. Para uma chamada que solicita uma entrada que reside na memória nãopagada, o chamador deve estar executando IRQL <= DISPATCH_LEVEL.

Exemplos

Para definir uma rotina de retorno de chamada LookasideListAllocateEx , primeiro você deve fornecer uma declaração de função que identifique o tipo de rotina de retorno de chamada que você está definindo. O Windows fornece um conjunto de tipos de função de retorno de chamada para drivers. Declarar uma função usando os tipos de função de retorno de chamada ajuda a Análise de Código para Drivers, SDV ( Verificador de Driver Estático ) e outras ferramentas de verificação a encontrar erros e é um requisito para gravar drivers para o sistema operacional Windows.

Por exemplo, para definir uma rotina de retorno de chamada LookasideListAllocateEx chamada MyLookasideListAllocateEx, use o tipo FREE_FUNCTION_EX conforme mostrado neste exemplo de código:

FREE_FUNCTION_EX MyLookasideListFreeEx;

Em seguida, implemente sua rotina de retorno de chamada da seguinte maneira:

_Use_decl_annotations_
VOID
  MyLookasideListFreeEx(
    PVOID  Buffer,
    PLOOKASIDE_LIST_EX  Lookaside
    )
  {
      // Function body
  }

O tipo de função FREE_FUNCTION_EX é definido no arquivo de cabeçalho Wdm.h. Para identificar erros com mais precisão ao executar as ferramentas de análise de código, adicione a _Use_decl_annotations_ anotação à sua definição de função. A _Use_decl_annotations_ anotação garante que as anotações aplicadas ao tipo de função FREE_FUNCTION_EX no arquivo de cabeçalho sejam usadas. Para obter mais informações sobre os requisitos para declarações de função, consulte Declarando funções usando tipos de função de função para drivers WDM. Para obter informações sobre _Use_decl_annotations_, consulte Anotando o comportamento da função.