Функция WdfDmaEnablerCreate (wdfdmaenabler.h)

  • Статья

[Относится только к KMDF]

Метод WdfDmaEnablerCreate создает объект enabler DMA.

Синтаксис

NTSTATUS WdfDmaEnablerCreate(
  [in]           WDFDEVICE               Device,
  [in]           PWDF_DMA_ENABLER_CONFIG Config,
  [in, optional] PWDF_OBJECT_ATTRIBUTES  Attributes,
  [out]          WDFDMAENABLER           *DmaEnablerHandle
);

Параметры

[in] Device

Дескриптор объекта устройства платформы.

[in] Config

Указатель на структуру WDF_DMA_ENABLER_CONFIG . Драйверы должны инициализировать эту структуру, вызвав WDF_DMA_ENABLER_CONFIG_INIT.

[in, optional] Attributes

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

[out] DmaEnablerHandle

Дескриптор нового объекта включения DMA.

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

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

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

Недостаточно памяти для создания нового объекта включения DMA.
STATUS_INFO_LENGTH_MISMATCH
 Неправильный размер структуры WDF_DMA_ENABLER_CONFIG .
STATUS_NOT_SUPPORTED
 Драйвер запросил DMA версии 3 в операционной системе раньше, чем Windows 8.
 

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

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

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

Комментарии

Драйверы на основе платформы должны вызывать WdfDmaEnablerCreate перед созданием транзакций DMA для устройства.

Прежде чем драйвер вызывает WdfDmaEnablerCreate, он должен вызвать WdfDeviceSetAlignmentRequirement.

Объект устройства платформы, который задается параметром Deviceобъекта WdfDmaEnablerCreate , всегда становится родительским объектом для нового объекта включения DMA. Если драйвер указывает другой родительский элемент в элементе ParentObjectструктуры WDF_OBJECT_ATTRIBUTES , платформа игнорирует это значение. Платформа удаляет объект включения DMA при удалении родительского объекта.

При вызове с параметром Config , который запрашивает профиль DMA в системном режиме, WdfDmaEnablerCreate создает частично инициализированный активатор DMA. Драйвер должен впоследствии вызвать WdfDmaEnablerConfigureSystemProfile , чтобы настроить параметры DMA для базовых каналов.

Дополнительные сведения об объектах включения DMA и WdfDmaEnablerCreate см. в разделе Включение транзакций DMA.

Примеры

Следующий пример кода получен из примера драйвера PLX9x5x . В этом примере устанавливается требование устройства к выравниванию буфера, инициализируется структура WDF_DMA_ENABLER_CONFIG и вызывается WdfDmaEnablerCreate.

//
// PLx PCI9656 DMA_TRANSFER_ELEMENTS must be 16-byte aligned.
//
WdfDeviceSetAlignmentRequirement(
                                 DevExt->WdfDevice,
                                 PCI9656_DTE_ALIGNMENT_16
                                 );

//
// Create a new DMA enabler object instance. 
// Use scatter/gather, 64-bit addresses, and duplex-type profile.
//
{
    WDF_DMA_ENABLER_CONFIG   dmaConfig;
    WDF_DMA_ENABLER_CONFIG_INIT(
                                &dmaConfig,
                                WdfDmaProfileScatterGather64Duplex,
                                DevExt->MaximumTransferLength
                                );
    status = WdfDmaEnablerCreate(
                                 DevExt->WdfDevice,
                                 &dmaConfig,
                                 WDF_NO_OBJECT_ATTRIBUTES,
                                 &DevExt->DmaEnabler
                                 );
    if (!NT_SUCCESS (status)) {
        // Cannot continue, so release device resources.
        return status;
    }
}

Требования

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

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

WDF_DMA_ENABLER_CONFIG

WDF_DMA_ENABLER_CONFIG_INIT

WDF_OBJECT_ATTRIBUTES

WdfDeviceSetAlignmentRequirement