WdfDmaTransactionDmaCompleted 関数 (wdfdmatransaction.h)

[アーティクル]
02/27/2024

[KMDF にのみ適用]

WdfDmaTransactionDmaCompleted メソッドは、デバイスの DMA 転送操作が完了したことをフレームワークに通知します。

構文

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

パラメーター

[in] DmaTransaction

ドライバーが WdfDmaTransactionCreate の以前の呼び出しから取得した DMA トランザクションオブジェクトへのハンドル。

[out] Status

DMA 転送の状態を受け取る場所へのポインター。詳細については、「解説」を参照してください。

戻り値

WdfDmaTransactionDmaCompleted は FALSE を 返し、DMA トランザクションを完了するために追加の転送が必要な場合、 Status はSTATUS_MORE_PROCESSING_REQUIREDを受け取ります。メソッドは、追加の転送が必要ない場合に TRUE を 返します。

ドライバーが無効なオブジェクトハンドルを提供すると、バグチェックが発生します。

注釈

フレームワークベースのドライバーは、 DMA 転送が完了するたびに、次のいずれかのメソッドを呼び出す必要があります。

通常、ドライバーは、デバイスの割り込みが DMA 転送操作の完了を示した後、 EvtInterruptDpc イベントコールバック関数内からこれらのメソッドを呼び出します。システムモード DMA デバイスのドライバーは、 EvtDmaTransactionDmaTransferComplete イベントコールバック関数内からこれらのメソッドを呼び出す場合があります。

フレームワークでは、 DMA トランザクションを複数の DMA 転送操作に分割する場合があります。そのため、ドライバーはメソッドの戻り値を調べて、追加の転送が必要かどうかを判断する必要があります。

メソッドが FALSE を返す場合、状態の場所はSTATUS_MORE_PROCESSING_REQUIREDを受け取り、トランザクションを完了するには追加の DMA 操作が必要です。通常、 EvtInterruptDpc イベントコールバック関数は、この時点で他に何も行いません。代わりに、フレームワークはドライバーの EvtProgramDma イベントコールバック関数を呼び出して、コールバック関数が次の転送を開始できるようにします。

メソッドが TRUE を返した場合、指定したトランザクションに対してこれ以上の転送は行われません。この場合、 Status 値STATUS_SUCCESSは、フレームワークでエラーが発生せず、DMA トランザクションが完了したことを意味します。

WdfDmaTransactionDmaCompleted を呼び出す前にドライバーが WdfDmaTransactionStopSystemTransfer を呼び出した場合、WdfDmaTransactionDmaCompleted は TRUE を返し、Status 値は STATUS_CANCELLED。

単一転送に設定されたトランザクションの場合、WdfDmaTransactionDmaCompleted は TRUE を返し、ハードウェアが 1 回の転送でトランザクションを完了できなかった場合は、STATUS_WDF_TOO_MANY_TRANSFERSの Status 値を返します。ただし、初期化は成功しました。これは、DMA 操作ごとに残存転送を報告するハードウェアで発生する可能性があります。たとえば、ドライバーは 64 KB を書き込むデバイスをプログラムしますが、デバイスは 60 KB のみを書き込みます。この場合、ドライバーは DMA 操作を繰り返すか、デバイスをリセットする可能性があります。

Status のその他の値は、フレームワークがエラーを検出し、DMA トランザクションが完了していない可能性があることを意味します。

WdfDmaTransactionDmaCompleted がTRUE を返すと、ドライバーは通常、次の処理を行います。

WdfObjectDelete または WdfDmaTransactionRelease を呼び出して、トランザクションオブジェクトをそれぞれ削除または再利用します。
DMA トランザクションが I/O 要求に関連付けられている場合は、I/O 要求を完了します。 (ドライバーは、WdfRequestComplete または WdfRequestCompleteWithInformation を呼び出して要求を完了します)。

DMA 転送の完了の詳細については、「DMA 転送の完了」を参照してください。

例

次のコード例は、 AMCC5933 サンプルドライバーのコード例です。この例では、 EvtInterruptDpc コールバック関数を示します。この例では、DMA 転送が完了したことをフレームワークに通知します。この転送が DMA トランザクションの最後の転送であることをフレームワークが示す場合、コードは DMA トランザクションオブジェクトを削除し、関連付けられている I/O 要求を完了します。

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
                                          );
    }
}

要件

要件	値
対象プラットフォーム	ユニバーサル
最小 KMDF バージョン	1.0
Header	wdfdmatransaction.h (Wdf.h を含む)
Library	Wdf01000.sys (「Framework ライブラリのバージョン管理」を参照)。
IRQL	<=DISPATCH_LEVEL
DDI コンプライアンス規則	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)