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

Статья
08/08/2023

[Относится только к 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 , которая задает атрибуты объекта для общего объекта буфера. (Элемент ParentObject структуры должен иметь значение NULL.) Этот параметр является необязательным и может быть WDF_NO_OBJECT_ATTRIBUTES.

[out] CommonBuffer

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

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

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

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

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

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

После вызова 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 (включая WdfCommonBuffer.h)
Библиотека	Wdf01000.sys (см. раздел Управление версиями библиотеки Платформы).
IRQL	PASSIVE_LEVEL
Правила соответствия DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)