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.
| Código de retorno | Descrição |
|---|---|
|
Um parâmetro inválido foi detectado. |
|
Não havia memória suficiente para construir um novo objeto de habilitador de DMA. |
|
O tamanho da estrutura de WDF_DMA_ENABLER_CONFIG está incorreto. |
|
O driver solicitou o DMA versão 3 em um sistema operacional anterior a Windows 8. |
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
| Requisito | Valor |
|---|---|
| Plataforma de Destino | Universal |
| Versão mínima do KMDF | 1.0 |
| Cabeçalho | wdfdmaenabler.h (inclua Wdf.h) |
| Biblioteca | Wdf01000.sys (consulte Controle de versão da biblioteca de estrutura.) |
| IRQL | PASSIVE_LEVEL |
| Regras de conformidade de DDI | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf) |