Función WdfDmaTransactionDmaCompleted (wdfdmatransaction.h)

Artículo
08/08/2023

[Solo se aplica a KMDF]

El método WdfDmaTransactionDmaCompleted notifica al marco que se ha completado la operación de transferencia DMA de un dispositivo.

Sintaxis

BOOLEAN WdfDmaTransactionDmaCompleted(
  [in]  WDFDMATRANSACTION DmaTransaction,
  [out] NTSTATUS          *Status
);

Parámetros

[in] DmaTransaction

Identificador de un objeto de transacción DMA que el controlador obtuvo de una llamada anterior a WdfDmaTransactionCreate.

[out] Status

Puntero a una ubicación que recibe el estado de la transferencia DMA. Para obtener más información, vea la sección Comentarios que se muestra más adelante.

Valor devuelto

WdfDmaTransactionDmaCompleted devuelve FALSE y Status recibe STATUS_MORE_PROCESSING_REQUIRED si se necesitan transferencias adicionales para completar la transacción DMA. El método devuelve TRUE si no se requieren transferencias adicionales.

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 uno de los métodos siguientes cada vez que se completa una transferencia de DMA :

Normalmente, los controladores llaman a estos métodos desde una función de devolución de llamada de evento EvtInterruptDpc , después de una interrupción del dispositivo indica la finalización de una operación de transferencia DMA. Un controlador para un dispositivo DMA en modo del sistema podría llamar a estos métodos desde una función de devolución de llamada de evento EvtDmaTransactionDmaTransferComplete .

El marco podría dividir una transacción DMA en varias operaciones de transferencia de DMA. Por lo tanto, el controlador debe examinar el valor devuelto del método para determinar si se requieren transferencias adicionales.

Si el método devuelve FALSE, la ubicación estado recibe STATUS_MORE_PROCESSING_REQUIRED y se requieren operaciones DMA adicionales para completar la transacción. Normalmente, la función de devolución de llamada de evento EvtInterruptDpc no hace nada más en este momento. En su lugar, el marco llama a la función de devolución de llamada de eventos EvtProgramDma del controlador, por lo que la función de devolución de llamada puede comenzar la transferencia siguiente.

Si el método devuelve TRUE, no se producirán más transferencias para la transacción especificada. En este caso, un valor status de STATUS_SUCCESS significa que el marco no encontró ningún error y la transacción DMA se ha completado.

Si el controlador llama a WdfDmaTransactionStopSystemTransfer antes de llamar a WdfDmaTransactionDmaCompleted, WdfDmaTransactionDmaCompleted devuelve TRUE y un valor status de STATUS_CANCELLED.

En el caso de las transacciones que se establecieron para la transferencia única, WdfDmaTransactionDmaCompleted devuelve TRUEy un valor status de STATUS_WDF_TOO_MANY_TRANSFERS si el hardware no puede completar la transacción en una sola transferencia, aunque la inicialización se realizó correctamente. Esto podría ocurrir para el hardware que informa de transferencias residuales para cada operación de DMA. Por ejemplo, el controlador programa el dispositivo para escribir 64 KB, pero el dispositivo escribe solo 60 KB. En este caso, el controlador puede repetir la operación DMA o restablecer el dispositivo.

Cualquier otro valor de Status significa que el marco detectó un error y es posible que la transacción DMA no se haya completado.

Cuando WdfDmaTransactionDmaCompleted devuelve TRUE, el controlador normalmente hace lo siguiente:

Llama a WdfObjectDelete o WdfDmaTransactionRelease para eliminar o reutilizar el objeto de transacción, respectivamente.
Completa la solicitud de E/S, si la transacción DMA está asociada a una solicitud de E/S. (Los controladores completan las solicitudes mediante una llamada a WdfRequestComplete o WdfRequestCompleteWithInformation).

Para obtener más información sobre cómo completar las transferencias de DMA, consulte Finalización de una transferencia de DMA.

Ejemplos

El siguiente ejemplo de código procede del controlador de ejemplo de AMCC5933 . En este ejemplo se muestra una función de devolución de llamada EvtInterruptDpc . En el ejemplo se notifica al marco que se ha completado una transferencia de DMA. Si el marco indica que esta transferencia es la última para la transacción DMA, el código elimina el objeto de transacción DMA y completa la solicitud de E/S asociada.

VOID
AmccPciEvtInterruptDpc(
    IN WDFINTERRUPT  WdfInterrupt,
    IN WDFOBJECT  WdfDevice
    )
{
    PAMCC_DEVICE_EXTENSION  devExt;
    WDFREQUEST  request;
    REQUEST_CONTEXT  *transfer;
    NTSTATUS  status;
    size_t  transferred;
    BOOLEAN  transactionComplete;

    UNREFERENCED_PARAMETER( WdfInterrupt );

    //
    // Retrieve request and transfer.
    //
    devExt = AmccPciGetDevExt(WdfDevice);
    request  = devExt->CurrentRequest;
    transfer = GetRequestContext(request);

    //
    // Check to see if the request has been canceled. 
    //
    if (WdfRequestIsCanceled(request)) {
        TraceEvents(
                    TRACE_LEVEL_ERROR,
                    AMCC_TRACE_IO,
                    "Aborted DMA transaction 0x%p",
                    request
                    );
        WdfObjectDelete( transfer->DmaTransaction );
        devExt->CurrentRequest = NULL;
        WdfRequestComplete(
                           request,
                           STATUS_CANCELLED
                           );
        return;
    }
 
    //
    // Notify the framework that a DMA transfer has completed.
    //
    transactionComplete = WdfDmaTransactionDmaCompleted(
                                                    transfer->DmaTransaction,
                                                    &status
                                                    );
    if (transactionComplete) {
        ASSERT(status != STATUS_MORE_PROCESSING_REQUIRED);

        //
        // No more data. The request is complete.
        //
        TraceEvents(
                    TRACE_LEVEL_INFORMATION,
                    AMCC_TRACE_IO,
                    "Request %p completed: status %X",  
                    request,
                    status
                    );

        //
        // Get the byte count.
        //
        transferred =
                WdfDmaTransactionGetBytesTransferred(transfer->DmaTransaction);

        TraceEvents(
                    TRACE_LEVEL_INFORMATION,
                    AMCC_TRACE_IO,
                    "Bytes transferred %d",
                    (int) transferred
                    );

        //
        // Delete this DmaTransaction object.
        //
        WdfObjectDelete(transfer->DmaTransaction);

        //
        // Clean up the device context for this request.
        //
        devExt->CurrentRequest = NULL;

        //
        // Complete this I/O request.
        //
        WdfRequestCompleteWithInformation(
                                          request, 
                                          status,
                                          (NT_SUCCESS(status)) ? transferred : 0
                                          );
    }
}

Requisitos

Requisito	Value
Plataforma de destino	Universal
Versión mínima de KMDF	1.0
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), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)