Поделиться через

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

  • Статья

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

Синтаксис

DECLSPEC_RESTRICT PVOID ExAllocatePool2(
  POOL_FLAGS Flags,
  SIZE_T     NumberOfBytes,
  ULONG      Tag
);

Параметры

Flags

ULONG64 типизированное значение, указывающее тип памяти пула, а также обязательные и необязательные атрибуты. Несколько значений флагов можно объединить с помощью битового ИЛИ. Возможные значения см. в POOL_FLAGS .

NumberOfBytes

Указывает ненулевое количество выделенных байтов.

Tag

Тег пула, используемый для выделенной памяти. Укажите тег пула как ненулевой символьный литерал от одного до четырех символов, разделенных одними кавычками (например, Tag1). Строка обычно указывается в обратном порядке (например, 1gaT). Каждый символ ASCII в теге должен быть значением в диапазоне 0x20 (пробел) до 0x7E (тильда). Каждый путь к коду выделения должен использовать уникальный тег пула, чтобы помочь отладчикам и проверятелям определить путь к коду.

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

ExAllocatePool2 возвращает указатель на выделенную память.

Следующие условия приводят к тому, что функция возвращает значение NULL по умолчанию. Если указан POOL_FLAG_RAISE_ON_FAILURE , функция создает исключение.

  • Недостаточно памяти
  • Тег имеет значение 0 или указаны недопустимые POOL_FLAGS

Комментарии

При создании драйвера, предназначенного для версий Windows до Windows 10 версии 2004, используйте ExAllocatePoolZero, ExAllocatePoolUninitialized, ExAllocatePoolQuotaZero или ExAllocatePoolQuotaUninitialized.

Эта подпрограмма имеет следующие отличия от предыдущих процедур выделения (ExAllocatePoolWithTag, ExAllocatePoolWithQuotaTag, ExAllocatePoolWithTagPriority):

  1. Память инициализируется нулевым значением, если не указано POOL_FLAG_UNINITIALIZED .

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

  3. Недопустимые теги со значением 0.

При замене ExAllocatePoolWithQuotaTag на ExAllocatePool2 необходимо указать флаг POOL_FLAG_USE_QUOTA . Дополнительные сведения о флагах пула см. в разделе POOL_FLAGS.

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

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

Система связывает тег пула с выделенной памятью. Средства программирования, такие как WinDbg, могут отображать тег пула, связанный с каждым выделенным буфером. Средство Gflags, входящее в состав средств отладки для Windows, включает системную функцию, которая запрашивает выделение из специального пула для определенного тега пула. Poolmon, который входит в состав WDK, отслеживает память по тегу пула.

Значение тега сохраняется и иногда отображается в обратном порядке (с небольшим порядком байтов). Например, если вызывающий объект передает Fred как тег, он отображается как derF в дампе пула и в отслеживании использования пула в отладчике, а также как 0x64657246 в реестре и в отображается средство.

Выделенный буфер можно освободить с помощью ExFreePool или ExFreePoolWithTag.

Вызывающие экземпляры ExAllocatePool2 должны выполняться по адресу IRQL <= DISPATCH_LEVEL. Вызывающий объект, выполняющийся на DISPATCH_LEVEL, должен указать POOL_FLAG_NON_PAGED или POOL_FLAG_NON_PAGED_EXECUTABLE для флагов. Вызывающий объект, выполняющий команду IRQL <= APC_LEVEL, может указать POOL_FLAG_PAGED, но если доступ к памяти будет осуществляться из кода, выполняемого в DISPATCH_LEVEL, необходимо по-прежнему выделять нестраничную память.

В многопроцессорной архитектуре с неоднородным доступом к памяти (NUMA) ExAllocatePool2 пытается выделить локальную память для процессора, который вызывает ExAllocatePool2. Если локальная память недоступна, ExAllocatePool2 выделяет ближайшую доступную память.

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

Требования

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

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

ExAllocatePool3