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

Статья
03/08/2023

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

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

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

Синтаксис

PVOID ExAllocatePoolWithTag(
  [in] __drv_strictTypeMatch(__drv_typeExpr)POOL_TYPE PoolType,
  [in] SIZE_T                                         NumberOfBytes,
  [in] ULONG                                          Tag
);

Параметры

[in] PoolType

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

Вы можете изменить значение PoolType , побитово объединяя это значение с флагом POOL_RAISE_IF_ALLOCATION_FAILURE. Этот флаг вызывает исключение, если запрос не может быть удовлетворен. Не рекомендуется использовать флаг POOL_RAISE_IF_ALLOCATION_FAILURE, так как он является дорогостоящим.

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

[in] NumberOfBytes

Количество байтов, которые необходимо выделить.

[in] Tag

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

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

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

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

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

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

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

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

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

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

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

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

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

Требования

Требование	Значение
Целевая платформа	Универсальное
Верхняя часть	wdm.h (включая Wdm.h, Ntddk.h, Ntifs.h)
Библиотека	NtosKrnl.lib
DLL	NtosKrnl.exe
IRQL	IRQL <= DISPATCH_LEVEL (см. раздел "Примечания")
Правила соответствия DDI	CheckDeviceObjectFlags(wdm), HwStorPortProhibitedDDIs(storport), IrqlExAllocatePool(wdm), IrqlExFree1(wdm), PowerDownAllocate(wdm), PowerUpFail(wdm), SpNoWait(storport), StorPortStartIo(storport), UnsafeAllocatePool(kmdf), UnsafeAllocatePool(wdm)

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

ExAllocatePoolWithQuotaTag

ExAllocatePoolWithTagPriority

ExFreePool

ExFreePoolWithTag

POOL_TYPE