Función WdfDmaTransactionAllocateResources (wdfdmatransaction.h)

Artículo
08/08/2023

[Solo se aplica a KMDF]

El método WdfDmaTransactionAllocateResources reserva un habilitador DMA de un solo paquete o modo del sistema para uso exclusivo (y repetido) con el objeto de transacción especificado. El controlador puede inicializar e iniciar la transacción varias veces mientras mantiene recursos reservados.

Sintaxis

NTSTATUS WdfDmaTransactionAllocateResources(
  [in] WDFDMATRANSACTION   DmaTransaction,
  [in] WDF_DMA_DIRECTION   DmaDirection,
  [in] ULONG               RequiredMapRegisters,
  [in] PFN_WDF_RESERVE_DMA EvtReserveDmaFunction,
  [in] PVOID               EvtReserveDmaContext
);

Parámetros

[in] DmaTransaction

Identificador del objeto de transacción DMA para el que se deben reservar recursos DMA.

[in] DmaDirection

Valor con tipo WDF_DMA_DIRECTION que especifica la dirección de transferencia de DMA para la que se reservan los recursos. Si el controlador no especificó un perfil dúplex, el marco omite este valor.

[in] RequiredMapRegisters

El número de mapas registra el controlador que desea reservar. Si es cero, el marco deriva el número necesario de registros de mapa de la transacción inicializada.

[in] EvtReserveDmaFunction

Puntero a la función de devolución de llamada de eventos EvtReserveDma del controlador.

[in] EvtReserveDmaContext

Puntero a un búfer que contiene el contexto que se va a proporcionar a la función de devolución de llamada de eventos EvtReserveDma del controlador.

Valor devuelto

WdfDmaTransactionAllocateResources devuelve STATUS_SUCCESS si la operación se realiza correctamente. De lo contrario, este método devuelve uno de los valores siguientes.

Código devuelto	Descripción
STATUS_INVALID_PARAMETER	El parámetro DmaDirection contiene un valor no válido.
STATUS_INSUFFICIENT_RESOURCES	El número de solicitudes de registro de mapa supera el número asignado al habilitador o el controlador anteriormente llamado WdfDmaTransactionSetImmediateExecution y los recursos necesarios para la solicitud no están disponibles.
STATUS_INVALID_DEVICE_REQUEST	La versión 3 o posterior de DMA no está habilitada o el controlador llamado este método para un habilitador DMA de recopilación de dispersión.

Comentarios

WdfDmaTransactionAllocateResources envía una solicitud para los registros de asignación al motor DMA del sistema. Cuando se ha cumplido la solicitud, el marco llama a la función de devolución de llamada de eventos EvtReserveDma del controlador. Para obtener más información sobre cómo reservar recursos, vea Reservar recursos de DMA.

Normalmente, los controladores basados en marcos llaman a WdfDmaTransactionAllocateResources desde un controlador de solicitudes de E/S. Un controlador también puede llamar a WdfDmaTransactionAllocateResources desde su función de devolución de llamada EvtDriverDeviceAdd , después de crear un objeto enabler DMA.

Cuando se llama con un habilitador DMA de dispersión o recopilación, WdfDmaTransactionAllocateResources provoca una comprobación de errores del comprobador.

El controlador debe crear la transacción especificada por DmaTransaction antes de llamar a WdfDmaTransactionAllocateResources. Después de llamar a WdfDmaTransactionAllocateResources, el controlador inicializa e inicia la transacción. El controlador puede reinicializar y volver a iniciar el mismo objeto de transacción varias veces, evitando el retraso que, de lo contrario, se produciría entre las transacciones, ya que los registros de mapa se liberaron de nuevo a HAL y, a continuación, se reasignaron.

Un controlador podría llamar a WdfDmaTransactionAllocateResources en las situaciones siguientes:

El controlador recibe un conjunto de canales DMA en su función de devolución de llamada EvtDevicePrepareHardware . En EvtDevicePrepareHardware, el controlador inicializa una transacción DMA y llama a WdfDmaTransactionAllocateResources para reservar el habilitador para uso exclusivo con esta transacción. Como alternativa, el controlador puede llamar a WdfDmaTransactionAllocateResources desde un controlador de solicitudes y, a continuación, iniciar la transacción varias veces.
El controlador debe realizar una serie de transacciones en el habilitador. El controlador reserva el habilitador, inicializa e inicia varias transacciones con el mismo objeto de transacción y, a continuación, libera el habilitador.

Antes de llamar a WdfDmaTransactionAllocateResources, el controlador debe determinar el número de registros de mapa necesarios para cualquier transacción que inicie con esta reserva. Para ello, el controlador puede llamar a [ADDRESS_AND_SIZE_TO_SPAN_PAGES](.. Macro /wdm/nf-wdm-address_and_size_to_span_pages.md) o WdfDmaTransactionGetTransferInfo.

Al llamar a WdfDmaTransactionAllocateResources, el controlador no debe solicitar más registros de mapa de los que solicitó cuando creó el habilitador.

Para llamar a WdfDmaTransactionAllocateResources de forma no bloqueada, el controlador debe llamar primero a WdfDmaTransactionSetImmediateExecution.

WdfDmaTransactionAllocateResources requiere la versión 3 de DMA. Para seleccionar DMA versión 3, establezca el miembro WdmDmaVersionOverride de WDF_DMA_ENABLER_CONFIG en 3.

Requisitos

Requisito	Value
Plataforma de destino	Universal
Versión mínima de KMDF	1.11
Encabezado	wdfdmatransaction.h (incluya Wdf.h)
Library	Wdf01000.sys (consulte Control de versiones de la biblioteca de marcos).
IRQL	<=DISPATCH_LEVEL
Reglas de cumplimiento de DDI	DriverCreate(kmdf)