Função ExInitializeNPagedLookasideList (wdm.h)

Artigo
03/08/2023

A rotina ExInitializeNPagedLookasideList inicializa uma lista lookaside para entradas nãopagadas do tamanho especificado.

Sintaxe

void ExInitializeNPagedLookasideList(
  [out]          PNPAGED_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 NPAGED_LOOKASIDE_LIST a ser inicializada. O chamador deve usar espaço do sistema nãopagado para a estrutura. 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,           // NonPagedPool 
  __in SIZE_T  NumberOfBytes,         // value of Size
  __in ULONG  Tag                     // value of Tag
);

Se o parâmetro Allocate for NULL, as chamadas subsequentes para ExAllocateFromNPagedLookasideList 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 ExFreeToNPagedLookasideList liberarão automaticamente a entrada fornecida de volta para o pool nãopagado 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 ExInitializeNPagedLookasideList. Os bits de sinalizador compatíveis incluem o seguinte.

Bit de sinalizador	Significado	Valor
POOL_RAISE_IF_ALLOCATION_FAILURE	Se a alocação falhar, gere uma exceção.	16
POOL_NX_ALLOCATION	Alocar memória não executável.	512

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

[in] Size

Especifica o tamanho, em bytes, para cada entrada nãopagada a ser alocada posteriormente. Esse parâmetro não deve ser menor que o tamanho mínimo necessário, LOOKASIDE_MINIMUM_BLOCK_SIZE, que é definido no arquivo de cabeçalho Wdm.h.

[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 ExInitializeNPagedLookasideList, os blocos de memória do Tamanho especificado pelo chamador podem ser alocados e liberados para a lista lookaside com chamadas para ExAllocateFromNPagedLookasideList e ExFreeToNPagedLookasideList, 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.

ExInitializeNPagedLookasideList 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 atualmente em uso. À medida que a demanda por entradas de lista lookaside e na memória nãopagada 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 nãopagada dinamicamente.

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

ExInitializeNPagedLookasideList 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 ExAllocateFromNPagedLookasideList e essas entradas iniciais são mantidas na lista lookaside à medida que ocorrem chamadas recíprocas para ExFreeToNPagedLookasideList . As entradas são coletadas na lista lookaside fornecida até que o máximo determinado pelo sistema seja atingido, em que todas as entradas adicionais são retornadas ao pool nãopagado à medida que 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 ExInitializeNPagedLookasideList 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 ExInitializeNPagedLookasideList fornecer uma função XxxAllocate , essa rotina 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 NPAGED_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 ExInitializeNPagedLookasideList. Para obter mais informações, consulte Usando Listas Lookaside.

Os chamadores de ExInitializeNPagedLookasideList podem estar em execução em IRQL <= DISPATCH_LEVEL, mas normalmente são executados em IRQL = PASSIVE_LEVEL.

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	IRQL <= DISPATCH_LEVEL (consulte a seção Comentários)