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

  • Статья

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

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

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

Синтаксис

PVOID ExAllocatePoolWithTagPriority(
  [in] __drv_strictTypeMatch(__drv_typeCond)POOL_TYPE        PoolType,
  [in] SIZE_T                                                NumberOfBytes,
  [in] ULONG                                                 Tag,
  [in] __drv_strictTypeMatch(__drv_typeExpr)EX_POOL_PRIORITY Priority
);

Параметры

[in] PoolType

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

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

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

[in] NumberOfBytes

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

[in] Tag

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

[in] Priority

Приоритет этого запроса. Задайте для этого параметра одно из следующих значений перечисления EX_POOL_PRIORITY .

Значение приоритета Описание
LowPoolPriority Указывает, что система может завершить запрос сбоем при нехватке ресурсов. Этот приоритет используется для распределений драйверов, которые могут быть восстановлены после сбоя выделения.
NormalPoolPriority Указывает, что система может завершить запрос сбоем при очень низком уровне ресурсов. Большинство драйверов должны использовать это значение.
HighPoolPriority Указывает, что система не должна завершить запрос сбоем, если не будет полностью недостаточно ресурсов. Драйверы используют это значение только в том случае, если это критически важно для успешного выполнения запроса.

Перечисление EX_POOL_PRIORITY определяет варианты XxxSpecialPoolOverrun и XxxSpecialPoolUnderrun , чтобы указать способ выделения памяти при включении средства проверки драйверов (или специального пула). Если драйвер указывает XxxSpecialPoolUnderrun, когда диспетчер памяти выделяет память из специального пула, он выделяет ее в начале физической страницы. Если драйвер указывает XxxSpecialPoolOverrun, диспетчер памяти выделяет его в конце физической страницы.

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

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

Комментарии

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

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

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

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

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

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

Требования

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

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

ExAllocatePoolWithTag

ExFreePool

POOL_TYPE