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

Статья
03/08/2023

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

Синтаксис

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

Параметры

[out] Lookaside

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

[in, optional] Allocate

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

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

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

[in, optional] Free

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

VOID XxxFree(
  __in PVOID  Buffer
);

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

[in] Flags

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

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

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

[in] Size

Указывает размер (в байтах) для каждой непагрегированных записей, которые будут выделены впоследствии. Этот параметр не должен быть меньше требуемого минимального размера, LOOKASIDE_MINIMUM_BLOCK_SIZE, который определен в файле заголовка Wdm.h.

[in] Tag

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

[in] Depth

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

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

None

Remarks

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

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

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

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

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

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

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

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

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

Вызывающие функции ExInitializeNPagedLookasideList могут выполняться в IRQL <= DISPATCH_LEVEL, но обычно выполняются в IRQL = PASSIVE_LEVEL.

Требования

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