Fungsi WdfDmaTransactionAllocateResources (wdfdmatransaction.h)

Artikel
02/29/2024

[Berlaku untuk KMDF saja]

Metode WdfDmaTransactionAllocateResources mencadangkan pengaktif DMA paket tunggal atau mode sistem untuk penggunaan eksklusif (dan berulang) dengan objek transaksi yang ditentukan. Driver dapat menginisialisasi dan memulai transaksi beberapa kali sambil menyimpan sumber daya yang dipesan.

Sintaks

NTSTATUS WdfDmaTransactionAllocateResources(
  [in] WDFDMATRANSACTION   DmaTransaction,
  [in] WDF_DMA_DIRECTION   DmaDirection,
  [in] ULONG               RequiredMapRegisters,
  [in] PFN_WDF_RESERVE_DMA EvtReserveDmaFunction,
  [in] PVOID               EvtReserveDmaContext
);

Parameter

[in] DmaTransaction

Handel ke objek transaksi DMA tempat sumber daya DMA harus dicadangkan.

[in] DmaDirection

Nilai jenis WDF_DMA_DIRECTION yang menentukan arah transfer DMA tempat sumber daya dicadangkan. Jika driver tidak menentukan profil dupleks, kerangka kerja akan mengabaikan nilai ini.

[in] RequiredMapRegisters

Jumlah daftar peta yang ingin dipesan driver. Jika nol, kerangka kerja memperoleh jumlah register peta yang diperlukan dari transaksi yang diinisialisasi.

[in] EvtReserveDmaFunction

Penunjuk ke fungsi panggilan balik peristiwa EvtReserveDma driver.

[in] EvtReserveDmaContext

Penunjuk ke buffer yang berisi konteks yang akan diberikan ke fungsi panggilan balik peristiwa EvtReserveDma driver.

Nilai kembali

WdfDmaTransactionAllocateResources mengembalikan STATUS_SUCCESS jika operasi berhasil. Jika tidak, metode ini mengembalikan salah satu nilai berikut.

Menampilkan kode	Deskripsi
STATUS_INVALID_PARAMETER	Parameter DmaDirection berisi nilai yang tidak valid.
STATUS_INSUFFICIENT_RESOURCES	Jumlah permintaan register peta melebihi jumlah yang ditetapkan ke pengaktif, atau driver yang sebelumnya disebut WdfDmaTransactionSetImmediateExecution dan sumber daya yang diperlukan untuk permintaan tidak tersedia.
STATUS_INVALID_DEVICE_REQUEST	DMA versi 3 atau yang lebih baru tidak diaktifkan, atau driver memanggil metode ini untuk pengaktif DMA yang dikumpulkan sebar.

Keterangan

WdfDmaTransactionAllocateResources mengirimkan permintaan untuk register peta ke mesin DMA sistem. Ketika permintaan telah terpenuhi, kerangka kerja memanggil fungsi panggilan balik peristiwa EvtReserveDma driver. Untuk informasi selengkapnya tentang mempertahankan sumber daya, lihat Mencadangkan Sumber Daya DMA.

Driver berbasis kerangka kerja biasanya memanggil WdfDmaTransactionAllocateResources dari dalam handler permintaan I/O. Driver juga dapat memanggil WdfDmaTransactionAllocateResources dari fungsi panggilan balik EvtDriverDeviceAdd , setelah membuat objek pengaktif DMA.

Ketika dipanggil dengan pengaktif DMA sebar/kumpulkan, WdfDmaTransactionAllocateResources menyebabkan pemeriksaan bug pemverifikasi.

Driver harus membuat transaksi yang ditentukan oleh DmaTransaction sebelum memanggil WdfDmaTransactionAllocateResources. Setelah memanggil WdfDmaTransactionAllocateResources, driver menginisialisasi dan memulai transaksi. Driver dapat menginisialisasi ulang dan menginisialisasi ulang objek transaksi yang sama beberapa kali, menghindari keterlambatan yang akan terjadi antara transaksi karena register peta dibebaskan kembali ke HAL dan kemudian direalokasikan.

Driver dapat memanggil WdfDmaTransactionAllocateResources dalam situasi berikut:

Driver menerima satu set saluran DMA dalam fungsi panggilan balik EvtDevicePrepareHardware . Di EvtDevicePrepareHardware, driver menginisialisasi transaksi DMA dan memanggil WdfDmaTransactionAllocateResources untuk memesan enabler untuk penggunaan eksklusif dengan transaksi ini. Atau, driver dapat memanggil WdfDmaTransactionAllocateResources dari handler permintaan dan kemudian memulai transaksi beberapa kali.
Driver perlu melakukan serangkaian transaksi pada pengaktif. Driver mencadangkan pengaktif, menginisialisasi, dan memulai beberapa transaksi menggunakan objek transaksi yang sama, lalu melepaskan pengaktif.

Sebelum memanggil WdfDmaTransactionAllocateResources, driver harus menentukan jumlah register peta yang diperlukan untuk setiap transaksi yang akan dimulai menggunakan reservasi ini. Untuk melakukannya, driver dapat memanggil [ADDRESS_AND_SIZE_TO_SPAN_PAGES](.. Makro /wdm/nf-wdm-address_and_size_to_span_pages.md) atau WdfDmaTransactionGetTransferInfo.

Saat memanggil WdfDmaTransactionAllocateResources, driver tidak boleh meminta lebih banyak register peta daripada yang diminta saat membuat pengaktif.

Untuk memanggil WdfDmaTransactionAllocateResources dengan cara yang tidak memblokir, driver harus terlebih dahulu memanggil WdfDmaTransactionSetImmediateExecution.

WdfDmaTransactionAllocateResources memerlukan DMA versi 3. Untuk memilih DMA versi 3, atur anggota WdmDmaVersionOverridedari WDF_DMA_ENABLER_CONFIG ke 3.

Persyaratan

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