Función WdfDmaEnablerCreate (wdfdmaenabler.h)
[Solo se aplica a KMDF]
El método WdfDmaEnablerCreate crea un objeto enabler de 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 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 de DMA. Este parámetro es opcional y puede ser 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.
| Código devuelto | Descripción |
|---|---|
|
Se ha detectado un parámetro no válido. |
|
No había memoria suficiente para construir un nuevo objeto de habilitador de DMA. |
|
El tamaño de la estructura WDF_DMA_ENABLER_CONFIG es incorrecto. |
|
El controlador solicitó la versión 3 de DMA en un sistema operativo anterior a Windows 8. |
Para obtener una lista de otros valores devueltos que puede devolver el método WdfDmaEnablerCreate , vea Errores de creación de objetos de marco.
Este método también podría devolver otros valores NTSTATUS.
Se produce una comprobación de errores si el controlador proporciona un identificador de objeto no válido.
Comentarios
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 del nuevo objeto enabler de 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 con un parámetro Config que solicita un perfil de DMA en modo sistema, WdfDmaEnablerCreate crea un habilitador DMA inicializado parcialmente. Posteriormente, el controlador debe llamar 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 es del controlador de ejemplo 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
| Requisito | Value |
|---|---|
| Plataforma de destino | Universal |
| Versión mínima de KMDF | 1.0 |
| Encabezado | wdfdmaenabler.h (include Wdf.h) |
| Library | Wdf01000.sys (consulte Control de versiones de la biblioteca de marcos). |
| IRQL | PASSIVE_LEVEL |
| Reglas de cumplimiento de DDI | DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf) |