Fungsi WdfDmaTransactionDmaCompleted (wdfdmatransaction.h)

Artikel
08/08/2023

[Berlaku untuk KMDF saja]

Metode WdfDmaTransactionDmaCompleted memberi tahu kerangka kerja bahwa operasi transfer DMA perangkat selesai.

Sintaks

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

Parameter

[in] DmaTransaction

Handel ke objek transaksi DMA yang diperoleh driver dari panggilan sebelumnya ke WdfDmaTransactionCreate.

[out] Status

Penunjuk ke lokasi yang menerima status transfer DMA. Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.

Nilai kembali

WdfDmaTransactionDmaCompleted mengembalikan FALSE dan Status menerima STATUS_MORE_PROCESSING_REQUIRED jika transfer tambahan diperlukan untuk menyelesaikan transaksi DMA. Metode mengembalikan TRUE jika tidak ada transfer tambahan yang diperlukan.

Pemeriksaan bug terjadi jika driver menyediakan handel objek yang tidak valid.

Keterangan

Driver berbasis kerangka kerja harus memanggil salah satu metode berikut setiap kali transfer DMA selesai:

Biasanya, driver memanggil metode ini dari dalam fungsi panggilan balik peristiwa EvtInterruptDpc , setelah gangguan perangkat menunjukkan penyelesaian operasi transfer DMA. Driver untuk perangkat DMA mode sistem mungkin memanggil metode ini dari dalam fungsi panggilan balik peristiwa EvtDmaTransactionDmaTransferComplete .

Kerangka kerja mungkin membagi transaksi DMA menjadi beberapa operasi transfer DMA. Oleh karena itu, driver harus memeriksa nilai pengembalian metode untuk menentukan apakah transfer tambahan diperlukan.

Jika metode mengembalikan FALSE, lokasi Status menerima STATUS_MORE_PROCESSING_REQUIRED dan operasi DMA tambahan diperlukan untuk menyelesaikan transaksi. Biasanya, fungsi panggilan balik peristiwa EvtInterruptDpc tidak melakukan hal lain pada saat ini. Sebaliknya, kerangka kerja memanggil fungsi panggilan balik peristiwa EvtProgramDma driver, sehingga fungsi panggilan balik dapat memulai transfer berikutnya.

Jika metode mengembalikan TRUE, tidak ada lagi transfer yang akan terjadi untuk transaksi yang ditentukan. Dalam hal ini, nilai Status STATUS_SUCCESS berarti bahwa kerangka kerja tidak mengalami kesalahan dan transaksi DMA selesai.

Jika driver memanggil WdfDmaTransactionStopSystemTransfer sebelum memanggil WdfDmaTransactionDmaCompleted, WdfDmaTransactionDmaCompleted mengembalikan TRUE dan nilai StatusSTATUS_CANCELLED.

Untuk transaksi yang ditetapkan untuk transfer tunggal, WdfDmaTransactionDmaCompleted mengembalikan TRUE dan nilai StatusSTATUS_WDF_TOO_MANY_TRANSFERS jika perangkat keras gagal menyelesaikan transaksi dalam satu transfer, meskipun inisialisasi berhasil. Ini dapat terjadi untuk perangkat keras yang melaporkan transfer sisa untuk setiap operasi DMA. Misalnya, driver memprogram perangkat untuk menulis 64KB, tetapi perangkat hanya menulis 60KB. Dalam hal ini, driver mungkin mengulangi operasi DMA atau mengatur ulang perangkat.

Nilai lain untuk Status berarti bahwa kerangka kerja mendeteksi kesalahan dan transaksi DMA mungkin belum selesai.

Ketika WdfDmaTransactionDmaCompleted mengembalikan TRUE, driver biasanya melakukan hal berikut:

Memanggil WdfObjectDelete atau WdfDmaTransactionRelease untuk menghapus atau menggunakan kembali objek transaksi.
Menyelesaikan permintaan I/O, jika transaksi DMA dikaitkan dengan permintaan I/O. (Driver menyelesaikan permintaan dengan memanggil WdfRequestComplete atau WdfRequestCompleteWithInformation.)

Untuk informasi selengkapnya tentang menyelesaikan transfer DMA, lihat Menyelesaikan Transfer DMA.

Contoh

Contoh kode berikut berasal dari driver sampel AMCC5933 . Contoh ini menunjukkan fungsi panggilan balik EvtInterruptDpc . Contoh memberi tahu kerangka kerja bahwa transfer DMA telah selesai. Jika kerangka kerja menunjukkan bahwa transfer ini adalah yang terakhir untuk transaksi DMA, kode akan menghapus objek transaksi DMA dan menyelesaikan permintaan I/O terkait.

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

Persyaratan

Persyaratan	Nilai
Target Platform	Universal
Versi KMDF minimum	1,0
Header	wdfdmatransaction.h (termasuk Wdf.h)
Pustaka	Wdf01000.sys (lihat Penerapan Versi Pustaka Kerangka Kerja.)
IRQL	<=DISPATCH_LEVEL
Aturan kepatuhan DDI	DriverCreate(kmdf), KmdfIrql(kmdf), KmdfIrql2(kmdf), KmdfIrqlExplicit(kmdf)