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

Статья
03/08/2023

Предупреждение

ExAllocatePool устарел и устарел в Windows 10 версии 2004. Он был заменен ExAllocatePool2. Дополнительные сведения см. в разделе Обновление устаревших вызовов ExAllocatePool для ExAllocatePool2 и ExAllocatePool3.

При разработке драйверов для версии Windows до Windows 10 версии 2004 используйте ExAllocatePoolZero.

ExAllocatePool выделяет память пула указанного типа и возвращает указатель на выделенный блок.

Синтаксис

PVOID ExAllocatePool(
  [in] __drv_strictTypeMatch(__drv_typeExpr)POOL_TYPE PoolType,
  [in] SIZE_T                                         NumberOfBytes
);

Параметры

[in] PoolType

Указывает тип памяти пула для выделения. Описание доступных типов памяти пула см. в разделе POOL_TYPE.

Вы можете изменить PoolType , используя побитовую или с флагом POOL_COLD_ALLOCATION в качестве указания для ядра, чтобы выделить память на страницах, которые, скорее всего, будут быстро выгручаться. Чтобы максимально уменьшить объем памяти постоянного пула, не следует часто ссылаться на эти выделения. Флаг POOL_COLD_ALLOCATION доступен только для Windows XP и более поздних версий операционной системы Windows.

[in] NumberOfBytes

Указывает число байтов для распределения.

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

ExAllocatePool возвращает значение NULL , если в свободном пуле недостаточно памяти для удовлетворения запроса. В противном случае подпрограмма возвращает указатель на выделенную память.

Если значение NumberOfBytes PAGE_SIZE или больше, выделяется буфер с выравниванием по страницам. Объем памяти PAGE_SIZE или менее не пересекает границы страницы. Выделение памяти меньше PAGE_SIZE не обязательно выравнивается по страницам, но выравнивается по 8-байтовой границе в 32-разрядных системах и к 16-байтовой границе в 64-разрядных системах.

При успешном выделении, запрашиваемом numberOfBytes< PAGE_SIZE непагрегированного пула, вызывающий объект точно определяет количество запрошенных байтов памяти. Если запрос на выделение numberOfBytes> PAGE_SIZE выполнен успешно и NumberOfBytes не является точным кратным PAGE_SIZE, последняя страница выделения содержит байты, которые не являются частью выделения вызывающего объекта. Если это возможно, распределителем пула используются эти байты. Чтобы избежать повреждения данных, принадлежащих другим компонентам режима ядра, драйверы должны обращаться только к адресам хранения, которые они явно выделили.

Если ExAllocatePool возвращает значение NULL, вызывающий объект должен вернуть значение NTSTATUS STATUS_INSUFFICIENT_RESOURCES или задержать обработку до другой точки во времени.

Вызывающие экземпляры ExAllocatePool должны выполняться по адресу IRQL <= DISPATCH_LEVEL. Вызывающий объект, выполняющийся в DISPATCH_LEVEL, должен указать значение непагрегированногоxxx для параметра PoolType. Вызывающий объект, выполняющий команду IRQL <= APC_LEVEL, может указать любое значение POOL_TYPE , но при определении типа страницы также необходимо учитывать irQL и среду.

Не устанавливайте numberOfBytes = 0. Избегайте выделения нулевой длины, так как они тратят пространство заголовков пула и, во многих случаях, указывают на потенциальную проблему проверки в вызывающем коде. По этой причине средство проверки драйверов помечает такие выделения как возможные ошибки.

Система автоматически задает определенные стандартные объекты событий, если объем пула (выгружаемого или несгружаемого) является высоким или низким. Драйверы могут ждать, пока эти события будут настроены для настройки использования пула. Дополнительные сведения см. в разделе Стандартные объекты событий.

Память, выделенная ExAllocatePool , не инициализирована. Драйвер режима ядра должен сначала обнулить эту память, если он собирается сделать ее видимой для программного обеспечения в пользовательском режиме (чтобы избежать утечки потенциально привилегированного содержимого).

Требования

Требование	Значение
Минимальная версия клиента	Является устаревшей. Эта подпрограмма экспортируется только для существующих двоичных файлов. Вместо этого используйте ExAllocatePoolWithTag.
Целевая платформа	Универсальное
Верхняя часть	wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h, Classpnp.h, Smcnt.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	IRQL <= DISPATCH_LEVEL (см. раздел "Примечания")
Правила соответствия DDI	CheckDeviceObjectFlags(wdm), HwStorPortProhibitedDIs(storport), IrqlExAllocatePool(wdm), PowerDownAllocate(wdm), PowerUpFail(wdm), SpNoWait(storport), StorPortStartIo(storport), UnsafeAllocatePool(kmdf), UnsafeAllocatePool(wdm)

См. также раздел

ExAllocatePoolWithTag

ExFreePool

POOL_TYPE