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

[Относится только к 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, если операция выполнена успешно. В противном случае этот метод может возвращать одно из следующих значений:

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

Комментарии

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

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

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

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

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

На компьютерах с процессорами 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;
}

Требования

См. также раздел

EvtDriverDeviceAdd

WDF_COMMON_BUFFER_CONFIG

WDF_OBJECT_ATTRIBUTES

WdfCommonBufferCreate

WdfCommonBufferGetAlignedLogicalAddress

WdfCommonBufferGetAlignedVirtualAddress

WdfDeviceSetAlignmentRequirement

WdfDmaEnablerCreate