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

Статья
02/07/2025

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

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

Синтаксис

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

Параметры

[in] DmaEnabler

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

[in] Length

Требуемый размер в байтах нового буфера.

[in] Config

Указатель на структуру WDF_COMMON_BUFFER_CONFIG, содержащую сведения о конфигурации буфера.

[in, optional] Attributes

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

[out] CommonBuffer

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

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

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

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

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

Замечания

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

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

После вызова драйвера WdfCommonBufferCreateWithConfigдрайвер должен:

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

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

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

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

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

Примеры

В следующем примере кода инициализируется структура WDF_COMMON_BUFFER_CONFIG, а затем создается 10-байтовый буфер, выровненный по границе 32-байтов.

WDF_COMMON_BUFFER_CONFIG  commonBufConfig;
WDFCOMMONBUFFER  commonBuffer;

WDF_COMMON_BUFFER_CONFIG_INIT(
                              &commonBufConfig,
                              FILE_32_BYTE_ALIGNMENT
                              );

status = WdfCommonBufferCreateWithConfig(
                                         DmaEnabler,
                                         10,
                                         &commonBufConfig,
                                         WDF_NO_OBJECT_ATTRIBUTES,
                                         &commonBuffer
                                         );
if (!NT_SUCCESS (status)) {
    return status;
}

Требования

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