Función WdfDmaTransactionAllocateResources (wdfdmatransaction.h)

Artículo
03/22/2025

[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 contiene 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 de tipo WDF_DMA_DIRECTIONque 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 registros de mapa que el controlador 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 al EvtReserveDma del controlador función de devolución de llamada de eventos.

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 de retorno	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.

Observaciones

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

Normalmente, los controladores basados en marcos llaman a WdfDmaTransactionAllocateResources desde un controlador de solicitudes de E/S de . Un controlador también puede llamar a función de devolución de llamada WdfDmaTransactionAllocateResource s desde su EvtDriverDeviceAdd función de devolución de llamada, 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 EvtDevicePrepareHardware función de devolución de llamada. En EvtDevicePrepareHardware, el controlador inicializa una transacción DMA y llama a WdfDmaTransactionAllocateResources para reservar el habilitador para su uso exclusivo con esta transacción. Como alternativa, el controlador puede llamar a WdfDmaTransactionAllocateResources desde un controlador de solicitudes e 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 mediante 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 asignación de los que solicitó cuando creó el habilitador.

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

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

Requisitos

Requisito	Valor
de la plataforma de destino de	Universal
versión mínima de KMDF	1.11
encabezado	wdfdmatransaction.h (incluya Wdf.h)
Biblioteca	Wdf01000.sys (consulte Control de versiones de la biblioteca de marcos).
irQL	<=DISPATCH_LEVEL
reglas de cumplimiento de DDI	DriverCreate(kmdf)