Функция ExAllocatePoolWithTag (wdm.h)
Программа 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, побитово-ORing это значение с помощью флага POOL_RAISE_IF_ALLOCATION_FAILURE. Этот флаг вызывает исключение, если запрос не может быть удовлетворен. Использование флага POOL_RAISE_IF_ALLOCATION_FAILURE не рекомендуется, так как это затратно.
Аналогичным образом можно изменить значение PoolType, побитово-ORing это значение с флагом 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, должен указать значение NonPagedXxx для PoolType. Вызывающий объект, выполняющийся в IRQL <= APC_LEVEL, может указывать любое POOL_TYPE значение, но для определения типа страницы также следует учитывать irQL и среду.
Не устанавливайте NumberOfBytes = 0. Избегайте выделения нулевой длины, так как они занимают место заголовка пула отходов и, во многих случаях, указывают на потенциальную проблему проверки в вызывающем коде. По этой причине проверяющего драйвера флаги таких выделений, как возможные ошибки.
В многопроцессорной архитектуре доступа к памяти (NUMA) ExAllocatePoolWithTag пытается выделить память, которая является локальной для процессора, вызывающего ExAllocatePoolWithTag. Если локальная память недоступна, ExAllocatePoolWithTag выделяет ближайшую доступную память.
Память, которая exAllocatePoolWithTag выделяется неинициализируется. Драйвер в режиме ядра должен сначала ноль этой памяти, если он будет отображаться в программном обеспечении в пользовательском режиме (чтобы избежать утечки потенциально привилегированного содержимого).
Требования
| Требование | Ценность |
|---|---|
| целевая платформа | Всеобщий |
| заголовка | wdm.h (include 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) |