Função ExInitializePagedLookasideList (wdm.h)

Artigo
02/07/2025

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 de 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ãoNULL, 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, chamadas subsequentes para ExAllocateFromPagedLookasideList alocar 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ãoNULL, o ponteiro será para uma função com o protótipo:

VOID XxxFree(
  __in PVOID  Buffer
);

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

[in] Flags

A partir do 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, crie uma exceção.

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

Antes do 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.

Valor de retorno

Nenhum

Observações

Depois de chamar ExInitializePagedLookasideList, blocos do tamanho do 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 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, se houver, ou define esses pontos de entrada como ExAllocatePoolWithTag e ExFreePool, respectivamente.
Inicializa um bloqueio de rotação do sistema para controlar 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 Tamanho e lista Marca.
Configura os limites determinados pelo sistema (mínimo e máximo) no número de entradas a serem mantidas na lista lookaside, que pode ser ajustada 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 memória de página disponível varia enquanto o sistema é executado, o sistema ajusta seus limites para o número de entradas a serem mantidas em cada lista lookaside paginada dinamicamente.

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

ExInitializePagedLookasideList configura a cabeça da lista opaca no local fornecido pelo chamador, mas não fornece 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 como 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 para o pool de páginas 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 de 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 use uma lista lookaside pode fornecer essas funções para fazer processamento adicional determinado pelo chamador, como acompanhar seu próprio uso dinâmico de memória mantendo o estado sobre o número de entradas que 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 ao 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 receber um ponteiro de contexto como 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 apenas 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
da Plataforma de Destino	Universal
cabeçalho	wdm.h (include Wdm.h, Ntddk.h, Ntifs.h)
biblioteca	NtosKrnl.lib
de DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL
regras de conformidade de DDI	HwStorPortProhibitedDIs(storport), IrqlExApcLte2(wdm)