Функция WdfCommonBufferCreate (wdfcommonbuffer.h)

Статья
02/07/2025

[Применимо только к KMDF]

Метод WdfCommonBufferCreate создает буфер памяти, к которому одновременно может обращаться драйвер и устройство прямого доступа к памяти (DMA).

Синтаксис

NTSTATUS WdfCommonBufferCreate(
  [in]           WDFDMAENABLER          DmaEnabler,
  [in]           size_t                 Length,
  [in, optional] PWDF_OBJECT_ATTRIBUTES Attributes,
  [out]          WDFCOMMONBUFFER        *CommonBuffer
);

Параметры

[in] DmaEnabler

Дескриптор объекта включения DMA, полученный драйвером при предыдущем вызове WdfDmaEnablerCreate.

[in] Length

Требуемый размер в байтах нового буфера. Максимальный допустимый размер буфера — байт (MAXULONG — PAGE_SIZE).

[in, optional] Attributes

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

[out] CommonBuffer

Указатель на переменную типа WDFCOMMONBUFFER, которая получает дескриптор к общему объекту буфера.

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

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

Возвращаемый код	Описание
STATUS_INVALID_PARAMETER	Драйвер предоставил недопустимый параметр.
STATUS_INSUFFICIENT_RESOURCES	Платформа не могла выделить общий буферный объект или система не могла выделить буфер.

Ошибка возникает, если драйвер предоставляет недопустимый дескриптор объекта.

Замечания

Метод WdfCommonBufferCreate выделяет память и сопоставляет его таким образом, чтобы драйвер и устройство могли получить доступ к нему одновременно для операций DMA. После вызова драйвера WdfCommonBufferCreateдрайвер должен:

Вызовите WdfCommonBufferGetAlignedVirtualAddress, чтобы получить виртуальный адрес буфера, который может использовать драйвер.
Вызовите WdfCommonBufferGetAlignedLogicalAddress, чтобы получить логический адрес буфера, который устройство может использовать.

Драйвер обычно вызывает WdfCommonBufferCreate из функции обратного вызова EvtDriverDeviceAdd.

Прежде чем драйвер вызывает WdfDmaEnablerCreate, он может вызывать WdfDeviceSetAlignmentRequirement, чтобы задать требование выравнивания буфера. Если драйвер не вызывает WdfDeviceSetAlignmentRequirement, буферы выравниваются по границам слова. Если драйвер создает несколько включений DMA, каждый из которых имеет другое требование выравнивания буфера, драйвер может вызывать WdfDeviceSetAlignmentRequirement перед каждым вызовом WdfDmaEnablerCreate.

Чтобы создать общий буфер, имеющий требование выравнивания, отличное от требования выравнивания, указанного драйвером WdfDeviceSetAlignmentRequirement, драйвер может вызывать WdfCommonBufferCreateWithConfig вместо WdfCommonBufferCreate.

Операционная система определяет, следует ли включить кэшированную память в общем буфере, который должен быть выделен. Это решение основано на архитектуре процессора и шине устройства.

На компьютерах с процессорами на основе x86, x64 и Процессорами на основе Itanium кэшированные памяти включены. На компьютерах с процессорами на основе ARM или ARM 64 операционная система не включает кэшированную память для всех устройств. Система использует метод ACPI_CCA для каждого устройства, чтобы определить, является ли устройство кэшным.

Объект включения DMA, который параметр DmaEnablerWdfCommonBufferCreate становится родительским объектом для нового общего буферного объекта. Драйвер не может изменить этот родительский элемент, а элемент ParentObject структуры WDF_OBJECT_ATTRIBUTES должен быть null. Платформа удаляет каждый общий буферный объект при удалении родительского объекта включения DMA. Кроме того, можно явно удалить общий буферный объект, вызвав WdfObjectDelete.

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

Примеры

В следующем примере кода показано, как получить общий буфер. В примере хранятся сведения об общем буфере в пространстве контекста, определяемом драйвером, который определяется указателем DevExt.

DevExt->CommonBufferSize = sizeof(COMMON_BUFFER_STRUCT);  // Your structure size
status = WdfCommonBufferCreate(
                               DevExt->DmaEnabler,
                               DevExt->CommonBufferSize,
                               WDF_NO_OBJECT_ATTRIBUTES,
                               &DevExt->CommonBuffer
                               );
if (status == STATUS_SUCCESS) {
    DevExt->CommonBufferBaseVA = 
        WdfCommonBufferGetAlignedVirtualAddress(DevExt->CommonBuffer);
    DevExt->CommonBufferBaseLA =
        WdfCommonBufferGetAlignedLogicalAddress(DevExt->CommonBuffer); 
}

Требования

Требование	Ценность
целевая платформа	Всеобщий
минимальная версия KMDF	1.0
заголовка	wdfcommonbuffer.h (include WdfCommonBuffer.h)
библиотеки	Wdf01000.sys (см. управление версиями библиотеки Платформы).)
IRQL	PASSIVE_LEVEL
правил соответствия DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)