Función ExInitializePagedLookasideList (wdm.h)

Artículo
02/29/2024

La rutina ExInitializePagedLookasideList inicializa una lista de lookaside para las entradas paginables del tamaño especificado.

Sintaxis

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

Puntero a la estructura PAGED_LOOKASIDE_LIST que se va a inicializar. El autor de la llamada debe usar espacio del sistema no paginado para la estructura, aunque las entradas de esta lista de aspecto se asignarán desde la memoria paginable. En las plataformas de 64 bits, esta estructura debe estar alineada con 16 bytes.

[in, optional] Allocate

Puntero a una función proporcionada por el autor de la llamada para asignar una entrada cuando la lista de lookaside está vacía o a NULL. Si no es NULL, el puntero es a una función con el prototipo:

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

Si el parámetro Allocate es NULL, las llamadas posteriores a ExAllocateFromPagedLookasideList asignan automáticamente entradas cada vez que la lista de lookaside está vacía.

[in, optional] Free

Puntero a una función proporcionada por el autor de la llamada para liberar una entrada cada vez que la lista de lookaside está llena o en NULL. Si no es NULL, el puntero es a una función con el prototipo:

VOID XxxFree(
  __in PVOID  Buffer
);

Si el parámetro Free es NULL, las llamadas posteriores a ExFreeToPagedLookasideList liberan automáticamente la entrada especificada al grupo paginado cada vez que la lista está llena, es decir, que contiene actualmente el número máximo de entradas determinado por el sistema.

[in] Flags

A partir de Windows 8, este parámetro especifica un valor de marca opcional para modificar el comportamiento predeterminado de la rutina ExInitializePagedLookasideList. Los bits de marca compatibles incluyen lo siguiente.

Bit de marca	Significado
POOL_RAISE_IF_ALLOCATION_FAILURE	Si se produce un error en la asignación, genere una excepción.

Especificar la marca POOL_NX_ALLOCATION no tiene ningún efecto. Toda la memoria paginable se asigna como NX.

Antes de Windows 8, este parámetro no se usa y debe ser cero.

[in] Size

Especifica el tamaño en bytes de cada entrada de la lista de lookaside.

[in] Tag

Especifica la etiqueta de grupo que se va a usar al asignar entradas de lista de lookaside. Para obtener más información sobre las etiquetas de grupo, consulte el parámetro Tag de ExAllocatePoolWithTag.

[in] Depth

Reservado. Debe ser cero.

Valor devuelto

None

Observaciones

Después de llamar a ExInitializePagedLookasideList, los bloques del tamaño especificado por el autor de la llamada se pueden asignar y liberar a la lista de lookaside con llamadas a ExAllocateFromPagedLookasideList y ExFreeToPagedLookasideList, respectivamente. Estas entradas asignadas y liberados dinámicamente pueden ser cualquier estructura de datos o búfer de tamaño fijo que el autor de la llamada use mientras se ejecuta el sistema, especialmente si el autor de la llamada no puede predeterminar cuántas entradas de este tipo se usarán en un momento dado. El diseño y el contenido de cada entrada de tamaño fijo están determinados por el autor de la llamada.

ExInitializePagedLookasideList inicializa el estado del sistema para realizar un seguimiento del uso de la lista de lookaside especificada, como se indica a continuación:

Inicializa cero los contadores que se van a mantener para las entradas.
Almacena los puntos de entrada de las rutinas XxxAllocate y XxxFree proporcionadas por el autor de la llamada, si las hay, o establece estos puntos de entrada en ExAllocatePoolWithTag y ExFreePool, respectivamente.
Inicializa un bloqueo de número del sistema para controlar las asignaciones de y libera a la lista de aspecto de forma segura para varios procesadores si es necesario.
Almacena el tamaño y la etiqueta de lista proporcionados por el autor de la llamada.
Configura los límites definidos por el sistema (mínimo y máximo) en el número de entradas que se van a mantener en la lista de lookaside, que se pueden ajustar posteriormente si la demanda de entradas para todo el sistema es superior o inferior a la prevista.
Configura las marcas determinadas por el sistema, que controlan el tipo de memoria desde la que se asignarán las entradas posteriormente.

El sistema mantiene un conjunto de todas las listas de aspecto en uso. A medida que la demanda de entradas de lista de búsqueda y en la memoria paginada disponible varía mientras se ejecuta el sistema, el sistema ajusta sus límites para el número de entradas que se deben mantener en cada lista de búsqueda paginada dinámicamente.

Los controladores siempre deben usar explícitamente las listas de lookaside que creen antes de descargarse. De lo contrario, es un error de programación grave. Use ExDeletePagedLookasideList para liberar la lista.

ExInitializePagedLookasideList configura el encabezado de lista opaco en la ubicación proporcionada por el autor de la llamada, pero no asigna previamente memoria para las entradas de lista. Posteriormente, las entradas iniciales se asignan dinámicamente a medida que se producen llamadas a ExAllocateFromPagedLookasideList y estas entradas iniciales se mantienen en la lista lookaside como llamadas recíprocas a ExFreeToPagedLookasideList . Las entradas se recopilan en la lista de lookaside dada hasta que se alcanza el máximo determinado por el sistema, donde se devuelven todas las entradas adicionales al grupo paginado a medida que se liberan. Si la lista está vacía, la función XxxAllocate especificada en la inicialización de lista o exAllocatePoolWithTag satisface las solicitudes de asignación.

Es más eficaz pasar punteros NULL para los parámetros Allocate y Free de ExInitializePagedLookasideList siempre que el usuario de una lista de lookaside no haga nada más que asignar y liberar entradas de tamaño fijo. Sin embargo, cualquier componente que use una lista de lookaside puede proporcionar estas funciones para realizar un procesamiento adicional determinado por el autor de la llamada, como el seguimiento de su propio uso de memoria dinámica manteniendo el estado sobre el número de entradas que asigna y libera.

Si el autor de la llamada de ExInitializePagedLookasideList proporciona una función XxxAllocate , esa función debe asignar entradas para la lista de lookaside mediante los parámetros de entrada especificados cuando llama a ExAllocatePoolWithTag.

A partir de Windows Vista, una rutina similar, ExInitializeLookasideListEx, inicializa una lista de aspecto descrita por una estructura de LOOKASIDE_LIST_EX . A diferencia de las rutinas XxxAllocate y XxxFree para una lista de aspecto que usa una estructura de PAGED_LOOKASIDE_LIST , las rutinas de asignación y desasignación de una lista de aspecto que usa la estructura LOOKASIDE_LIST_EX reciben un puntero de contexto como parámetro de entrada. Estas rutinas pueden usar este contexto para almacenar datos privados para la lista de lookaside. Si el controlador está pensado para ejecutarse solo en Windows Vista y versiones posteriores de Windows, considere la posibilidad de usar ExInitializeLookasideListEx en lugar de ExInitializePagedLookasideList. Para obtener más información, consulte Uso de lookaside Listas.

Requisitos

Requisito	Value
Plataforma de destino	Universal
Encabezado	wdm.h (incluya Wdm.h, Ntddk.h, Ntifs.h)
Library	NtosKrnl.lib
Archivo DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL
Reglas de cumplimiento de DDI	HwStorPortProhibitedDIs(storport), IrqlExApcLte2(wdm)