WdfDmaTransactionStopSystemTransfer 関数 (wdfdmatransaction.h)

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

[KMDF にのみ適用]

WdfDmaTransactionStopSystemTransfer メソッドは、フレームワークが EvtProgramDma を呼び出した後、システムモード DMA 転送を停止しようとします。

構文

void WdfDmaTransactionStopSystemTransfer(
  [in] WDFDMATRANSACTION DmaTransaction
);

パラメーター

[in] DmaTransaction

初期化された DMA トランザクションオブジェクトへのハンドル。

戻り値

なし

解説

システムモード DMA を使用するドライバーのみが WdfDmaTransactionStopSystemTransfer を呼び出す必要があります。

バスマスタリング DMA を使用するドライバーは、独自の専用 DMA コントローラーのプログラミングを担当します。要求の取り消し、タイムアウト、またはデバイスエラーが発生した場合、ドライバーは DMA コントローラーをプログラムしてデータの転送を停止できます。

これに対し、システムモード DMA を使用するドライバーは、共有 DMA コントローラーをプログラムするためにハードウェア抽象化レイヤー (HAL) に依存する必要があります。ドライバーが WdfDmaTransactionStopSystemTransfer を呼び出すと、フレームワークは HAL に転送を停止する必要があることを通知し、直ちにを返します。

フレームワークは次に、ドライバーが提供している場合、ドライバーの EvtDmaTransactionDmaTransferComplete コールバック関数を呼び出します。そうでない場合、ドライバーが次に WdfDmaTransactionDmaCompleted を呼び出すと、フレームワークは FALSE を返します。

ドライバーがWindows 8より前のオペレーティングシステムでこのメソッドを呼び出すと、フレームワークの検証ツールによってエラーが報告されます。

システムモード DMA の詳細については、「 System-Mode DMA のサポート」を参照してください。

DMA トランザクションの取り消しの詳細については、「 DMA トランザクションの取り消し」を参照してください。

例

次のコード例は、ドライバーが、I/O 要求がタイムアウトした場合に呼び出されるように登録する EvtTimerFunc イベントコールバック関数から WdfDmaTransactionStopSystemTransfer を呼び出す方法を示しています。

VOID
MyTimerFunc(
    __in WDFTIMER Timer
    )
{
    WDFREQUEST request = (WDFREQUEST) WdfTimerGetParentObject(Timer);
    PREQUEST_CONTEXT requestContext = GetRequestContext(request);

    //
    // Begin the completion process.  If we're the first to get here 
    // then stop the DMA transfer.  The dma completion routine will
    // take care of running down cancellation.
    //
    if (BeginCompletion(requestContext, STATUS_IO_TIMEOUT, false)) {
        WdfDmaTransactionStopSystemTransfer(requestContext->DmaTransaction);
    }
    
    AttemptRequestCompletion(requestContext, false);
}

bool
BeginCompletion(
    __in PREQUEST_CONTEXT  RequestContext,
    __in NTSTATUS          CompletionStatus,
    __in bool              ForceStatusUpdate
    )
{
    bool completionStarted;

    //
    // Grab the object lock and mark the beginning of 
    // completion.
    //
    WdfSpinLockAcquire(RequestContext->Lock);

    completionStarted = RequestContext->CompletionStarted;
    RequestContext->CompletionStarted = true;

    if ((completionStarted == false) || 
        (ForceStatusUpdate == true)) {
        RequestContext->CompletionStatus = CompletionStatus;
    }

    WdfSpinLockRelease(RequestContext->Lock);

    return !completionStarted;
}

VOID
AttemptRequestCompletion(
    __in PREQUEST_CONTEXT RequestContext,
    __in bool TransferComplete
    )
{
    LONG refCount;

    NT_ASSERTMSG("No thread has begun completion", 
                 RequestContext->CompletionStarted == true);

    if (TransferComplete) {
        //
        // Unmark the request cancelable.  If that succeeds then drop the cancel reference
        //
        if (WdfRequestUnmarkCancelable(RequestContext->Request) == STATUS_SUCCESS) {
            refCount = InterlockedDecrement(&(RequestContext->CompletionRefCount));
            NT_ASSERTMSGW(L"Reference count should not have gone to zero yet",
                          refCount != 0);
        }
                
        //
        // Stop the timer if it's been started.
        //
        if (RequestContext->TimerStarted == true) {
            if (WdfTimerStop(RequestContext->Timer, FALSE) == TRUE) {
                //
                // The timer was queued but won't ever run.  Drop its 
                // reference count.
                //
                refCount = InterlockedDecrement(&RequestContext->CompletionRefCount);
                NT_ASSERTMSG("Completion reference count should not reach zero until "
                             L"this routine calls AttemptRequestCompletion",
                             refCount > 0);
            }
        }
    }

    //
    // Drop this caller's reference.  If that was the last one then 
    // complete the request.
    //
    refCount = InterlockedDecrement(&(RequestContext->CompletionRefCount));

    if (refCount == 0) {
        NT_ASSERTMSGW(L"Execution reference was released, but execution "
                      L"path did not set a completion status for the "
                      L"request",
                      RequestContext->CompletionStatus != STATUS_PENDING);
        
        
        //
        // Timers are disposed of at passive level.  If we leave it attached to 
        // the request then we can hit a verifier issue, since the request 
        // needs to be immediately disposable at dispatch-level.
        //
        // Delete the timer now so that we can complete the request safely.
        // At this point the timer has either expired or been successfully 
        // cancelled so there's no race with the timer routine.
        //
        if (RequestContext->Timer != NULL) {
            WdfObjectDelete(RequestContext->Timer);
            RequestContext->Timer = NULL;
        }

        WdfRequestComplete(RequestContext->Request, 
                           RequestContext->CompletionStatus);
    }
}

次のコード例は、ドライバーが EvtRequestCancel コールバック関数から WdfDmaTransactionStopSystemTransfer を呼び出す方法を示しています。以前に呼び出されたドライバーは、コールバックを登録するために、その I/O 要求ハンドラーから WdfRequestMarkCancelableEx を呼び出しました。

VOID
MyRequestCancel(
    __in WDFREQUEST Request
    )
{
    PREQUEST_CONTEXT requestContext = GetRequestContext(Request);
    LONG oldValue;

    //
    // Start completion
    //

    if (BeginCompletion(requestContext, STATUS_CANCELLED, false)) {
        
        //
        // Cancel the DMA transaction.
        //
        if (WdfDmaTransactionCancel(requestContext->DmaTransaction) == TRUE) {
            //
            // The transaction was stopped before EvtProgramDma could be 
            // called.  Drop the I/O reference.
            // 
            oldValue = InterlockedDecrement(&requestContext->CompletionRefCount);
            NT_ASSERTMSG("Completion reference count should not reach zero until "
                         L"this routine calls AttemptRequestCompletion",
                         oldValue > 0);
            NT_ASSERTMSG("Completion status should be cancelled", 
                         requestContext->CompletionStatus == STATUS_CANCELLED);
        }
        else {
            //
            // The transaction couldn't be stopped before EvtProgramDma.
            // Stop any running system DMA transfer.
            //
            WdfDmaTransactionStopSystemTransfer(requestContext->DmaTransaction);
        }
    }

    AttemptRequestCompletion(requestContext, false);
}

要件

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

こちらもご覧ください

WdfDmaTransactionCancel

WdfDmaTransactionCreate

WdfDmaTransactionStopSystemTransfer 関数 (wdfdmatransaction.h)

構文

パラメーター

戻り値

解説

例

要件

こちらもご覧ください

フィードバック

フィードバック

その他のリソース