Función WdfDmaEnablerCreate (wdfdmaenabler.h)

[Solo se aplica a KMDF]

El método WdfDmaEnablerCreate crea un objeto enabler DMA.

Sintaxis

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

Parámetros

[in] Device

Identificador de un objeto de dispositivo de marco.

[in] Config

Puntero a una estructura de WDF_DMA_ENABLER_CONFIG. Los controladores deben inicializar esta estructura llamando a WDF_DMA_ENABLER_CONFIG_INIT.

[in, optional] Attributes

Puntero a una estructura de WDF_OBJECT_ATTRIBUTES que especifica atributos de objeto para el nuevo objeto habilitador DMA. Este parámetro es opcional y se puede WDF_NO_OBJECT_ATTRIBUTES.

[out] DmaEnablerHandle

Identificador de un nuevo objeto de habilitador DMA.

Valor devuelto

WdfDmaEnablerCreate devuelve STATUS_SUCCESS si la operación se realiza correctamente. De lo contrario, el método podría devolver uno de los valores siguientes.

Para obtener una lista de otros valores devueltos que el método WdfDmaEnablerCreate podría devolver, vea Errores de creación de objetos de marco.

Este método también puede devolver otros valores de NTSTATUS.

Se produce una comprobación de errores si el controlador proporciona un identificador de objeto no válido.

Observaciones

Los controladores basados en marcos deben llamar a WdfDmaEnablerCreate antes de crear transacciones DMA para un dispositivo.

Antes de que un controlador llame a WdfDmaEnablerCreate, debe llamar a WdfDeviceSetAlignmentRequirement.

El objeto de dispositivo de marco que el parámetro Device de WdfDmaEnablerCreate especifica siempre se convierte en el objeto primario para el nuevo objeto enabler DMA. Si el controlador especifica un elemento primario diferente en el miembro ParentObject de la estructura WDF_OBJECT_ATTRIBUTES, el marco omite este valor. El marco elimina el objeto del habilitador DMA cuando elimina el objeto primario.

Cuando se llama a con un parámetro Config que solicita un perfil DMA en modo del sistema, WdfDmaEnablerCreate crea un habilitador DMA inicializado parcialmente. El controlador debe llamar posteriormente a WdfDmaEnablerConfigureSystemProfile para configurar la configuración de DMA para los canales subyacentes.

Para obtener más información sobre los objetos del habilitador DMA y WdfDmaEnablerCreate, vea Habilitación de transacciones DMA.

Ejemplos

El ejemplo de código siguiente procede del controlador de ejemplo de PLX9x5x. En este ejemplo se establece el requisito de un dispositivo para la alineación del búfer, se inicializa una estructura de WDF_DMA_ENABLER_CONFIG y se llama a 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;
    }
}

Requisitos

Consulte también

WDF_DMA_ENABLER_CONFIG

WDF_DMA_ENABLER_CONFIG_INIT

WDF_OBJECT_ATTRIBUTES

WdfDeviceSetAlignmentRequirement