Функция ExInitializeNPagedLookasideList (wdm.h)
Подпрограмма 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 (см. раздел "Примечания") |
См. также раздел
ExAllocateFromNPagedLookasideList