Função WdfDmaEnablerCreate (wdfdmaenabler.h)

[Aplica-se somente ao KMDF]

O método WdfDmaEnablerCreate cria um objeto de habilitador de DMA.

Sintaxe

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

Parâmetros

[in] Device

Um identificador para um objeto de dispositivo de estrutura.

[in] Config

Um ponteiro para uma estrutura WDF_DMA_ENABLER_CONFIG . Os drivers devem inicializar essa estrutura chamando WDF_DMA_ENABLER_CONFIG_INIT.

[in, optional] Attributes

Um ponteiro para uma estrutura WDF_OBJECT_ATTRIBUTES que especifica atributos de objeto para o novo objeto habilitador de DMA. Esse parâmetro é opcional e pode ser WDF_NO_OBJECT_ATTRIBUTES.

[out] DmaEnablerHandle

Um identificador para um novo objeto de habilitador de DMA.

Retornar valor

WdfDmaEnablerCreate retornará STATUS_SUCCESS se a operação for bem-sucedida. Caso contrário, o método poderá retornar um dos valores a seguir.

Para obter uma lista de outros valores retornados que o método WdfDmaEnablerCreate pode retornar, consulte Erros de criação de objeto da estrutura.

Esse método também pode retornar outros valores NTSTATUS.

Um bug marcar ocorrerá se o driver fornecer um identificador de objeto inválido.

Comentários

Os drivers baseados em estrutura devem chamar WdfDmaEnablerCreate antes de criar transações de DMA para um dispositivo.

Antes que um driver chame WdfDmaEnablerCreate, ele deve chamar WdfDeviceSetAlignmentRequirement.

O objeto de dispositivo de estrutura que o parâmetro Device de WdfDmaEnablerCreate especifica sempre se torna o objeto pai do novo objeto habilitador de DMA. Se o driver especificar um pai diferente no membro ParentObject da estrutura WDF_OBJECT_ATTRIBUTES , a estrutura ignorará esse valor. A estrutura exclui o objeto do habilitador de DMA quando exclui o objeto pai.

Quando chamado com um parâmetro Config que solicita um perfil de DMA no modo de sistema, WdfDmaEnablerCreate cria um habilitador de DMA parcialmente inicializado. Posteriormente, o driver deve chamar WdfDmaEnablerConfigureSystemProfile para definir as configurações de DMA para os canais subjacentes.

Para obter mais informações sobre objetos habilitadores de DMA e WdfDmaEnablerCreate, consulte Habilitando transações de DMA.

Exemplos

O exemplo de código a seguir é do driver de exemplo PLX9x5x . Este exemplo define o requisito de alinhamento do buffer de um dispositivo, inicializa uma estrutura WDF_DMA_ENABLER_CONFIG e chama 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

Confira também

WDF_DMA_ENABLER_CONFIG

WDF_DMA_ENABLER_CONFIG_INIT

WDF_OBJECT_ATTRIBUTES

WdfDeviceSetAlignmentRequirement