Функция WdfMemoryCreate (wdfmemory.h)

Статья
08/08/2023

[Применимо к KMDF и UMDF]

Метод WdfMemoryCreate создает объект памяти платформы и выделяет буфер памяти указанного размера.

Синтаксис

NTSTATUS WdfMemoryCreate(
  [in, optional]  PWDF_OBJECT_ATTRIBUTES Attributes,
  [in]            POOL_TYPE              PoolType,
  [in, optional]  ULONG                  PoolTag,
  [in]            size_t                 BufferSize,
  [out]           WDFMEMORY              *Memory,
  [out, optional] PVOID                  *Buffer
);

Параметры

[in, optional] Attributes

Указатель на структуру WDF_OBJECT_ATTRIBUTES , содержащую атрибуты объекта для нового объекта памяти. Этот параметр является необязательным и может быть WDF_NO_OBJECT_ATTRIBUTES.

[in] PoolType

POOL_TYPE типизированное значение, указывающее тип выделенной памяти.

[in, optional] PoolTag

Определенный драйвером тег пула для выделенной памяти. Отладчики отображают этот тег. Драйверы обычно указывают строку символов длиной до четырех символов, разделенную одними кавычками, в обратном порядке (например, dcba). Значение ASCII каждого символа в теге должно находиться в диапазоне от 0 до 127. Отладка драйвера упрощается, если каждый тег пула уникален.

Если значение PoolTag равно нулю, платформа предоставляет тег пула по умолчанию, который использует первые четыре символа имени службы драйвера в режиме ядра. Если имя службы начинается с "WDF" (имя не учитывает регистр и не содержит кавычки), используются следующие четыре символа. Если доступно менее четырех символов, используется FxDr.

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

[in] BufferSize

Ненулевой указанный размер буфера в байтах.

[out] Memory

Указатель на расположение, которое получает дескриптор нового объекта памяти.

[out, optional] Buffer

Указатель на расположение, которое получает указатель на буфер, связанный с новым объектом памяти. Этот параметр является необязательным и может иметь значение NULL.

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

WdfMemoryCreate возвращает STATUS_SUCCESS, если операция выполнена успешно. В противном случае этот метод может возвращать одно из следующих значений:

Код возврата	Описание
STATUS_INVALID_PARAMETER	Обнаружен недопустимый параметр.
STATUS_INSUFFICIENT_RESOURCES	Недостаточно памяти.

Список других возвращаемых значений, которые может возвращать метод WdfMemoryCreate , см. в разделе Ошибки создания объекта платформы.

Этот метод также может возвращать другие значения NTSTATUS.

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

В зависимости от модели использования выделенной памяти драйвером рекомендуется учесть следующее:

RtlZeroMemory сразу после вызова WdfMemoryCreate
Или используйте API с нулевым выделением (ExAllocatePool2, ExAllocatePoolZero для режима ядра; HeapAlloc с флагом HEAP_ZERO_MEMORY для пользовательского режима), за которым следует WdfMemoryCreatePreallocated. Так как предварительно выделенный буфер не удаляется автоматически в рамках WDFMEMORY или его родительского удаления, это не лучший подход.

Родительским объектом по умолчанию для каждого объекта памяти является объект драйвера платформы, представляющий драйвер, который называется WdfMemoryCreate. Если драйвер создает объект памяти, который он использует с определенным объектом устройства, объектом запроса или другим объектом платформы, он должен правильно задать родительский объект памяти. Объект памяти и его буфер будут удалены при удалении родительского объекта. Если не изменить родительский объект по умолчанию, объект памяти и его буфер останутся до тех пор, пока диспетчер ввода-вывода не выгрузит драйвер.

Драйвер также может удалить объект памяти и его буфер, вызвав WdfObjectDelete.

Если значение BufferSize меньше PAGE_SIZE, операционная система предоставляет вызывающей объекту точное количество запрошенных байтов памяти. Буфер не обязательно выравнивается по страницам, но он выравнивается по количеству байтов, заданному константой MEMORY_ALLOCATION_ALIGNMENT в ntdef.h.

Если параметр BufferSize PAGE_SIZE или больше, для KMDF только система выделяет буфер, выровняемый по страницам. Если параметр PoolType имеет значение NonPagedPool, система выделяет количество страниц, необходимых для хранения всех байтов. Все неиспользуемые байты на последней выделенной странице по сути тратятся впустую.

Дополнительные сведения об объектах памяти платформы см. в разделе Использование буферов памяти.

Если драйвер указывает PagedPool для poolType, метод WdfMemoryCreate должен вызываться в irQL <= APC_LEVEL. В противном случае метод можно вызвать в IRQL <= DISPATCH_LEVEL.

Примеры

В следующем примере кода создается объект памяти платформы и выделяется буфер, размер которого составляет WRITE_BUFFER_SIZE. Родительский объект памяти является объектом запроса.

NTSTATUS  status;
WDF_OBJECT_ATTRIBUTES  attributes;
WDFMEMORY  writeBufferMemHandle;
PVOID  writeBufferPointer;

WDF_OBJECT_ATTRIBUTES_INIT(&attributes);
attributes.ParentObject = requestHandle;
status = WdfMemoryCreate(
                         &attributes,
                         NonPagedPool,
                         0,
                         WRITE_BUFFER_SIZE,
                         &writeBufferMemHandle,
                         &writeBufferPointer
                         );

Требования

Требование	Значение
Целевая платформа	Универсальное
Минимальная версия KMDF	1,0
Минимальная версия UMDF	2,0
Верхняя часть	wdfmemory.h (включая Wdf.h)
Библиотека	Wdf01000.sys (KMDF); WUDFx02000.dll (UMDF)
IRQL	См. раздел "Примечания".
Правила соответствия DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf), ParentObjectCheck(kmdf)