Fungsi WdfDmaTransactionExecute (wdfdmatransaction.h)

Artikel
08/08/2023

[Hanya berlaku untuk KMDF]

Metode WdfDmaTransactionExecute memulai eksekusi transaksi DMA tertentu.

Sintaks

NTSTATUS WdfDmaTransactionExecute(
  [in]           WDFDMATRANSACTION DmaTransaction,
  [in, optional] WDFCONTEXT        Context
);

Parameter

[in] DmaTransaction

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

[in, optional] Context

Informasi konteks yang ditentukan driver. Kerangka kerja meneruskan nilai yang ditentukan untuk Konteks, yang dapat menjadi penunjuk, ke fungsi panggilan balik peristiwa EvtProgramDma driver. Parameter ini bersifat opsional dan dapat berupa NULL.

Nilai kembali

WdfDmaTransactionExecute mengembalikan STATUS_SUCCESS jika operasi berhasil. Jika tidak, metode mungkin mengembalikan salah satu nilai berikut.

Menampilkan kode	Deskripsi
STATUS_INSUFFICIENT_RESOURCES	Driver yang sebelumnya disebut WdfDmaTransactionSetImmediateExecution dan sumber daya yang diperlukan untuk permintaan tidak tersedia.
STATUS_INVALID_DEVICE_REQUEST	Panggilan ke WdfDmaTransactionExecute tidak didahului oleh panggilan ke WdfDmaTransactionInitialize atau WdfDmaTransactionInitializeUsingRequest.
STATUS_WDF_BUSY	Perangkat melakukan transfer paket tunggal, dan driver yang disebut WdfDmaTransactionExecute saat transaksi lain sedang dijalankan.
STATUS_WDF_TOO_FRAGMENTED	Jumlah elemen sebar/kumpulkan yang diperlukan sistem operasi untuk menangani ukuran transfer yang ditentukan lebih besar dari nilai yang ditentukan oleh panggilan driver ke WdfDmaEnablerSetMaximumScatterGatherElements . Untuk informasi selengkapnya, lihat bagian Keterangan berikut ini.

Metode ini juga dapat mengembalikan nilai NTSTATUS lainnya.

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

Keterangan

Metode WdfDmaTransactionExecute menginisialisasi daftar sebar/kumpulkan transaksi untuk transfer DMA pertama yang terkait dengan transaksi DMA yang ditentukan. (Untuk transfer paket tunggal, daftar sebar/kumpulkan berisi satu elemen.) Kemudian, metode memanggil fungsi panggilan balik peristiwa EvtProgramDma driver, dan fungsi panggilan balik dapat memprogram perangkat untuk memulai transfer.

Driver berbasis kerangka kerja biasanya memanggil WdfDmaTransactionExecute dari dalam fungsi panggilan balik peristiwa antrean I/O.

Setelah driver memanggil WdfDmaTransactionInitialize atau WdfDmaTransactionInitializeUsingRequest untuk menginisialisasi transaksi DMA, driver harus memanggil WdfDmaTransactionExecute hanya sekali sebelum menyelesaikan transaksi DMA.

Jika WdfDmaTransactionInitializeXxx mengembalikan keberhasilan tetapi WdfDmaTransactionExecute mengembalikan nilai kesalahan, driver Anda harus memanggil WdfDmaTransactionRelease.

Dalam versi kerangka kerja sebelum 1.11, jika perangkat melakukan transfer paket tunggal, sistem operasi hanya dapat menjalankan satu transaksi DMA pada satu waktu. Dalam hal ini, WdfDmaTransactionExecute mengembalikan STATUS_WDF_BUSY jika transaksi lain dijalankan.

Dalam kerangka kerja versi 1.11 dan yang lebih baru, jika driver menggunakan DMA versi 3 untuk melakukan transfer paket tunggal, sistem operasi dapat menyimpan beberapa transaksi DMA dalam antrean internal. Dalam hal ini, driver dapat memanggil WdfDmaTransactionExecute saat transaksi lain sedang dijalankan. Untuk memilih DMA versi 3, atur anggota WdmDmaVersionOverridedari WDF_DMA_ENABLER_CONFIG ke 3.

Jika perangkat melakukan transfer sebar/kumpulkan, sistem operasi dapat menjalankan beberapa transaksi DMA secara bersamaan. Dalam hal ini, driver dapat memanggil WdfDmaTransactionExecute saat transaksi lain sedang dijalankan.

Jika driver memanggil WdfDmaTransactionDmaCompletedWithLength untuk melaporkan transfer parsial, dan jika driver telah menentukan buffer data transaksi DMA dengan menggunakan MDL yang dirangkai bersama (menggunakan anggota berikutnya dari struktur MDL ), WdfDmaTransactionExecute dapat mengembalikan STATUS_WDF_TOO_FRAGMENTED karena kerangka kerja mungkin menghitung ulang jumlah dan ukuran fragmen dan mungkin melebihi jumlah fragmen yang diizinkan.

WdfDmaTransactionExecute mengembalikan STATUS_SUCCESS jika transaksi berhasil dimulai. Untuk menentukan apakah kerangka kerja berhasil mengirim semua transfer transaksi ke fungsi panggilan balik EvtProgramDma driver, driver harus memanggil WdfDmaTransactionDmaCompleted, WdfDmaTransactionDmaCompletedWithLength, atau WdfDmaTransactionDmaCompletedFinal.

Jika nilai yang disediakan parameter Konteks adalah pointer atau handel, memori yang dirujuknya harus dapat diakses dalam fungsi panggilan balik peristiwa EvtProgramDma driver di IRQL = DISPATCH_LEVEL. Anda dapat menggunakan konteks objek kerangka kerja untuk memenuhi persyaratan ini.

Driver dapat memanggil WdfDmaTransactionExecute dengan cara yang tidak memblokir jika sebelumnya disebut WdfDmaTransactionSetImmediateExecution.

Untuk informasi selengkapnya tentang transaksi DMA, lihat Memulai Transaksi DMA.

Contoh

Contoh kode berikut berasal dari driver sampel PCIDRV . Contoh ini membuat dan menginisialisasi transfer DMA dan memulai eksekusinya.

NTSTATUS
NICInitiateDmaTransfer(
    IN PFDO_DATA  FdoData,
    IN WDFREQUEST  Request
    )
{
    WDFDMATRANSACTION  dmaTransaction;
    NTSTATUS  status;
    BOOLEAN  bCreated = FALSE;
 
    do {
        status = WdfDmaTransactionCreate(
                                         FdoData->WdfDmaEnabler,
                                         WDF_NO_OBJECT_ATTRIBUTES,
                                         &dmaTransaction
                                         );
        if(!NT_SUCCESS(status)) {
            TraceEvents(TRACE_LEVEL_ERROR, DBG_WRITE, 
                        "WdfDmaTransactionCreate failed %X\n", status);
            break;
        }

        bCreated = TRUE;

        status = WdfDmaTransactionInitializeUsingRequest( 
                                     dmaTransaction,
                                     Request,
                                     NICEvtProgramDmaFunction,
                                     WdfDmaDirectionWriteToDevice
                                     );
        if(!NT_SUCCESS(status)) {
            TraceEvents(
                        TRACE_LEVEL_ERROR,
                        DBG_WRITE, 
                        "WdfDmaTransactionInitalizeUsingRequest failed %X\n", 
                        status
                        );
            break;
        }

        status = WdfDmaTransactionExecute(
                                          dmaTransaction,
                                          dmaTransaction
                                          );

        if(!NT_SUCCESS(status)) {
            TraceEvents(
                        TRACE_LEVEL_ERROR,
                        DBG_WRITE, 
                        "WdfDmaTransactionExecute failed %X\n",
                        status
                        );
            break;
        }
    } while (FALSE);

    if(!NT_SUCCESS(status)){
 
        if(bCreated) {
            WdfObjectDelete(dmaTransaction);
        }
    }
    return status;
}

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)