Функция ExInitializePagedLookasideList (wdm.h)

Статья
02/29/2024

Подпрограмма ExInitializePagedLookasideList инициализирует список lookaside для записей с возможностью страницы указанного размера.

Синтаксис

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
);

Параметры

[out] Lookaside

Указатель на инициализируемую структуру PAGED_LOOKASIDE_LIST . Вызывающий объект должен использовать нестраничное системное пространство для структуры, несмотря на то, что записи в этом списке просмотра будут выделены из страничной памяти. На 64-разрядных платформах эта структура должна быть выровнена по 16 байтам.

[in, optional] Allocate

Указатель на функцию, предоставляемую вызывающей стороной, для выделения записи, когда список lookaside пуст, или на значение NULL. Если значение не равно NULL, указателем является функция с прототипом:

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

Если параметр Allocate имеет значение NULL, последующие вызовы ExAllocateFromPagedLookasideList автоматически выделяют записи, когда список lookaside пуст.

[in, optional] Free

Указатель на функцию, предоставляемую вызывающей стороной, для освобождения записи при заполнении списка lookaside или на значение NULL. Если значение не равно NULL, указателем является функция с прототипом:

VOID XxxFree(
  __in PVOID  Buffer
);

Если параметр Free имеет значение NULL, последующие вызовы ExFreeToPagedLookasideList автоматически освобождают указанную запись обратно в выгружаемый пул при заполнении списка, то есть в настоящее время содержит заданное системой максимальное количество записей.

[in] Flags

Начиная с Windows 8, этот параметр задает необязательное значение флага для изменения поведения по умолчанию подпрограммы ExInitializePagedLookasideList. Совместимые биты флага включают следующее.

Бит флага	Значение
POOL_RAISE_IF_ALLOCATION_FAILURE	Если выделение не удается, создайте исключение.

Указание флага POOL_NX_ALLOCATION не оказывает никакого влияния. Вся страничной памяти выделяется как NX.

До Windows 8 этот параметр не используется и должен иметь нулевое значение.

[in] Size

Задает размер в байтах каждой записи в списке lookaside.

[in] Tag

Указывает тег пула, используемый при выделении записей списка lookaside. Дополнительные сведения о тегах пула см. в разделе Параметр Tagобъекта ExAllocatePoolWithTag.

[in] Depth

Зарезервировано. Должен равняться нулю.

Возвращаемое значение

None

Remarks

После вызова ExInitializePagedLookasideList блоки размера, указанного вызывающим объектом, можно выделить из списка lookaside и освободить их с помощью вызовов ExAllocateFromPagedLookasideList и ExFreeToPagedLookasideList соответственно. Такие динамически выделенные и освобожденные записи могут быть любой структурой данных или буфером фиксированного размера, используемым вызывающим объектом во время работы системы, особенно если вызывающий объект не может заранее определить, сколько таких записей будет использоваться в данный момент. Макет и содержимое каждой записи фиксированного размера определяются вызывающим элементом.

ExInitializePagedLookasideList инициализирует состояние системы для отслеживания использования заданного списка lookaside следующим образом:

Нулевой инициализирует счетчики, которые будут поддерживаться для записей.
Хранит точки входа подпрограмм XxxAllocate и XxxFree , предоставляемых вызывающим абонентом, если таковые есть, или устанавливает для этих точек входа ExAllocatePoolWithTag и ExFreePool соответственно.
Инициализирует системную блокировку спина для управления выделениями из и освобождает список lookaside в многопроцессорном режиме, если это необходимо.
Сохраняет предоставленные вызывающим элементом размер и тег списка.
Устанавливает системные ограничения (минимальные и максимальные) на количество записей, которые будут храниться в списке просмотров, которые могут быть впоследствии скорректированы, если общесистемный спрос на записи будет выше или ниже, чем ожидалось.
Устанавливает системные флаги, которые управляют типом памяти, из которой впоследствии будут выделены записи.

Система поддерживает набор всех используемых списков lookaside. Так как потребность в записях списка lookaside и доступной выстраиваемой памяти меняется во время работы системы, система корректирует свои ограничения на количество записей, которые будут динамически храниться в каждом страничном списке просмотра.

Драйверы всегда должны использовать явным образом свободные списки lookaside, которые они создают перед выгрузками. В противном случае это серьезная ошибка программирования. Используйте ExDeletePagedLookasideList , чтобы освободить список.

ExInitializePagedLookasideList настраивает непрозрачный заголовок списка в расположении, предоставленном вызывающей стороной, но предварительно не выделяет память для записей списка. Впоследствии начальные записи выделяются динамически по мере выполнения вызовов ExAllocateFromPagedLookasideList , и эти начальные записи хранятся в списке lookaside по мере выполнения обратных вызовов ExFreeToPagedLookasideList . Записи собираются в заданном списке lookaside до достижения установленного системой максимального значения, после чего все дополнительные записи возвращаются в выстраиваемый пул по мере их освобождения. Если список становится пустым, запросы на выделение удовлетворяются функцией XxxAllocate , указанной при инициализации списка, или ExAllocatePoolWithTag.

Более эффективно передавать указатели NULL для параметров Allocate и Freeобъекта ExInitializePagedLookasideList всякий раз, когда пользователь списка lookaside делает только выделение и освобождение записей фиксированного размера. Однако любой компонент, использующий список lookaside, может предоставлять эти функции для выполнения дополнительной обработки, определяемой вызывающим объектом, например для отслеживания собственного динамического использования памяти путем поддержания состояния о количестве записей, которые он выделяет и освобождает.

Если вызывающий объект ExInitializePagedLookasideList предоставляет функцию XxxAllocate , эта функция должна выделять записи для списка lookaside с помощью заданных входных параметров при вызове ExAllocatePoolWithTag.

Начиная с Windows Vista, аналогичная подпрограмма ExInitializeLookasideListEx инициализирует список внешних элементов, который описывается структурой LOOKASIDE_LIST_EX . В отличие от подпрограмм XxxAllocate и XxxFree для списка lookaside, использующего структуру PAGED_LOOKASIDE_LIST , подпрограммы выделения и освобождения для списка lookaside, использующего структуру LOOKASIDE_LIST_EX , получают указатель контекста в качестве входного параметра. Эти подпрограммы могут использовать этот контекст для хранения личных данных для списка lookaside. Если драйвер предназначен для работы только в Windows Vista и более поздних версиях Windows, рассмотрите возможность использования ExInitializeLookasideListEx вместо ExInitializePagedLookasideList. Дополнительные сведения см. в статье Использование lookaside Списки.

Требования

Требование	Значение
Целевая платформа	Универсальное
Верхняя часть	wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	<= APC_LEVEL
Правила соответствия DDI	HwStorPortProhibitedDIs(storport), IrqlExApcLte2(wdm)