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

Artigo
03/08/2023

A rotina LookasideListFreeEx libera o armazenamento para uma entrada lookaside-list quando um cliente tenta inserir a entrada em uma lista lookaside que está cheia.

Sintaxe

FREE_FUNCTION_EX FreeFunctionEx;

void FreeFunctionEx(
  [in]      PVOID Buffer,
  [in, out] PLOOKASIDE_LIST_EX Lookaside
)
{...}

Parâmetros

[in] Buffer

Um ponteiro para a entrada lookaside-list que deve ser liberada.

[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

Nenhum

Comentários

Um driver que cria uma lista lookaside pode implementar uma rotina LookasideListFreeEx para liberar buffers alocados anteriormente quando a lista ficar cheia e não puder conter mais buffers. 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 LookasideListFreeEx personalizada 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 desalocação padrão.

Um driver chama a rotina ExFreeToLookasideListEx para inserir uma entrada alocada anteriormente em uma lista lookaside. Se a lista estiver cheia (ou seja, se a lista já contiver o número máximo de entradas determinado pelo sistema), ExFreeToLookasideListExchamará LookasideListFreeEx para liberar o armazenamento para a entrada.

A rotina LookasideListFreeEx 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 LookasideListFreeEx é chamada no mesmo IRQL que a chamada para ExFreeToLookasideListEx que libera a entrada. Para uma chamada para liberar uma entrada que reside na memória paginada, o chamador deve estar executando IRQL <= APC_LEVEL. Para uma chamada para liberar 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 LookasideListFreeEx , 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 escrever drivers para o sistema operacional Windows.

Por exemplo, para definir uma rotina de retorno de chamada LookasideListFreeEx chamada MyLookasideListFreeEx, 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.