Função ExInitializePagedLookasideList (wdm.h)

Artigo
03/08/2023

A rotina ExInitializePagedLookasideList inicializa uma lista lookaside para entradas pagináveis do tamanho especificado.

Sintaxe

void ExInitializePagedLookasideList(
  [out]          PPAGED_LOOKASIDE_LIST Lookaside,
  [in, optional] PALLOCATE_FUNCTION    Allocate,
  [in, optional] PFREE_FUNCTION        Free,
  [in]           ULONG                 Flags,
  [in]           SIZE_T                Size,
  [in]           ULONG                 Tag,
  [in]           USHORT                Depth
);

Parâmetros

[out] Lookaside

Um ponteiro para a estrutura PAGED_LOOKASIDE_LIST a ser inicializada. O chamador deve usar espaço do sistema não paginado para a estrutura, mesmo que as entradas nesta lista lookaside sejam alocadas da memória paginável. Em plataformas de 64 bits, essa estrutura deve estar alinhada a 16 bytes.

[in, optional] Allocate

Um ponteiro para uma função fornecida pelo chamador para alocar uma entrada quando a lista lookaside estiver vazia ou para NULL. Se não for NULL, o ponteiro será para uma função com o protótipo:

PVOID XxxAllocate(
  __in POOL_TYPE  PoolType,           // PagedPool 
  __in SIZE_T  NumberOfBytes,         // value of Size
  __in ULONG  Tag                     // value of Tag
);

Se o parâmetro Allocate for NULL, as chamadas subsequentes para ExAllocateFromPagedLookasideList alocarão automaticamente entradas sempre que a lista lookaside estiver vazia.

[in, optional] Free

Um ponteiro para uma função fornecida pelo chamador para liberar uma entrada sempre que a lista lookaside estiver cheia ou para NULL. Se não for NULL, o ponteiro será para uma função com o protótipo:

VOID XxxFree(
  __in PVOID  Buffer
);

Se o parâmetro Free for NULL, as chamadas subsequentes para ExFreeToPagedLookasideList liberarão automaticamente a entrada fornecida de volta para o pool paginado sempre que a lista estiver cheia, ou seja, mantendo atualmente o número máximo de entradas determinado pelo sistema.

[in] Flags

Começando no Windows 8, esse parâmetro especifica um valor de sinalizador opcional para modificar o comportamento padrão da rotina ExInitializePagedLookasideList. Os bits de sinalizador compatíveis incluem o seguinte.

Bit de sinalizador	Significado
POOL_RAISE_IF_ALLOCATION_FAILURE	Se a alocação falhar, gere uma exceção.

Especificar o sinalizador POOL_NX_ALLOCATION não tem efeito. Toda a memória paginável é alocada como NX.

Antes de Windows 8, esse parâmetro não é usado e deve ser zero.

[in] Size

Especifica o tamanho em bytes de cada entrada na lista lookaside.

[in] Tag

Especifica a marca de pool a ser usada ao alocar entradas de lista lookaside. Para obter mais informações sobre marcas de pool, consulte o parâmetro Tag de ExAllocatePoolWithTag.

[in] Depth

Reservado. Deve ser zero.

Retornar valor

Nenhum

Comentários

Depois de chamar ExInitializePagedLookasideList, os blocos do Tamanho especificado pelo chamador podem ser alocados e liberados para a lista lookaside com chamadas para ExAllocateFromPagedLookasideList e ExFreeToPagedLookasideList, respectivamente. Essas entradas alocadas e liberadas dinamicamente podem ser qualquer estrutura de dados ou buffer de tamanho fixo que o chamador usa enquanto o sistema está em execução, especialmente se o chamador não puder predeterminar quantas dessas entradas estarão em uso em um determinado momento. O layout e o conteúdo de cada entrada de tamanho fixo são determinados pelo chamador.

ExInitializePagedLookasideList inicializa o estado do sistema para acompanhar o uso da lista lookaside fornecida, da seguinte maneira:

Inicializa zero os contadores a serem mantidos para entradas.
Armazena os pontos de entrada das rotinas XxxAllocate e XxxFree fornecidas pelo chamador, se houver, ou define esses pontos de entrada como ExAllocatePoolWithTag e ExFreePool, respectivamente.
Inicializa um bloqueio de rotação do sistema para controlar as alocações de e libera para a lista lookaside de maneira segura para vários processadores, se necessário.
Armazena a entrada fornecida pelo chamador Tamanhoe marca de lista.
Configura os limites determinados pelo sistema (mínimo e máximo) no número de entradas a serem mantidas na lista lookaside, que podem ser ajustadas posteriormente se a demanda por entradas em todo o sistema for maior ou menor do que o previsto.
Configura os sinalizadores determinados pelo sistema, que controlam o tipo de memória do qual as entradas serão alocadas posteriormente.

O sistema mantém um conjunto de todas as listas lookaside em uso. À medida que a demanda por entradas de lista lookaside e na memória paginada disponível varia enquanto o sistema é executado, o sistema ajusta seus limites para o número de entradas a serem mantidas em cada lista de lookaside paginada dinamicamente.

Os drivers devem sempre usar explicitamente as listas lookaside criadas antes de descarregar. Fazer o contrário é um erro grave de programação. Use ExDeletePagedLookasideList para liberar a lista.

ExInitializePagedLookasideList configura o cabeçalho de lista opaco no local fornecido pelo chamador, mas não aloca memória para entradas de lista. Posteriormente, as entradas iniciais são alocadas dinamicamente à medida que ocorrem chamadas para ExAllocateFromPagedLookasideList e essas entradas iniciais são mantidas na lista lookaside à medida que ocorrem chamadas recíprocas para ExFreeToPagedLookasideList . As entradas são coletadas na lista lookaside fornecida até que o máximo determinado pelo sistema seja atingido, em que quaisquer entradas adicionais são retornadas ao pool paginado conforme são liberadas. Se a lista ficar vazia, as solicitações de alocação serão atendidas pela função XxxAllocate especificada na inicialização da lista ou por ExAllocatePoolWithTag.

É mais eficiente passar ponteiros NULL para os parâmetros Allocate e Free de ExInitializePagedLookasideList sempre que o usuário de uma lista lookaside não faz nada mais do que alocar e liberar entradas de tamanho fixo. No entanto, qualquer componente que usa uma lista lookaside pode fornecer essas funções para fazer processamento adicional determinado pelo chamador, como acompanhar seu próprio uso de memória dinâmica mantendo o estado sobre o número de entradas que ele aloca e libera.

Se o chamador de ExInitializePagedLookasideList fornecer uma função XxxAllocate , essa função deverá alocar entradas para a lista lookaside usando os parâmetros de entrada fornecidos quando chamar ExAllocatePoolWithTag.

A partir do Windows Vista, uma rotina semelhante, ExInitializeLookasideListEx, inicializa uma lista lookaside descrita por uma estrutura LOOKASIDE_LIST_EX . Ao contrário das rotinas XxxAllocate e XxxFree para uma lista lookaside que usa uma estrutura PAGED_LOOKASIDE_LIST , as rotinas de alocação e desalocação para uma lista lookaside que usa a estrutura LOOKASIDE_LIST_EX recebem um ponteiro de contexto como um parâmetro de entrada. Essas rotinas podem usar esse contexto para armazenar dados privados para a lista lookaside. Se o driver se destina a ser executado somente no Windows Vista e em versões posteriores do Windows, considere usar ExInitializeLookasideListEx em vez de ExInitializePagedLookasideList. Para obter mais informações, consulte Usando Listas Lookaside.

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	<= APC_LEVEL
Regras de conformidade da DDI	HwStorPortProhibitedDDIs(storport), IrqlExApcLte2(wdm)