Bagikan melalui

Mengakses Buffer Data di Driver UMDF 1.x

  • Artikel

Peringatan

UMDF 2 adalah versi terbaru UMDF dan pengganti UMDF 1. Semua driver UMDF baru harus ditulis menggunakan UMDF 2. Tidak ada fitur baru yang ditambahkan ke UMDF 1 dan ada dukungan terbatas untuk UMDF 1 pada versi Windows 10 yang lebih baru. Driver Universal Windows harus menggunakan UMDF 2.

Untuk informasi selengkapnya, lihat Memulai UMDF.

Untuk informasi tentang mengakses buffer data untuk UMDF 2, lihat Mengakses Buffer Data di Driver WDF.

Ketika driver menerima permintaan kontrol I/O baca, tulis, atau perangkat, objek permintaan berisi buffer input atau buffer output, atau keduanya. (Beberapa permintaan kontrol I/O perangkat menyediakan dua buffer input, dua output, atau dua buffer input/output.)

Buffer input berisi informasi yang dibutuhkan driver. Untuk permintaan tulis, biasanya informasi ini adalah data yang harus dikirim driver fungsi ke perangkat. Untuk permintaan kontrol I/O perangkat, buffer input mungkin berisi informasi yang menunjukkan jenis operasi yang harus dilakukan driver.

Buffer output menerima informasi dari driver. Untuk permintaan baca, biasanya informasi ini adalah data yang diterima driver fungsi dari perangkat. Untuk permintaan kontrol I/O perangkat, buffer output mungkin menerima status atau informasi lain bahwa kode kontrol I/O dari permintaan yang ditentukan.

Teknik yang digunakan driver Anda untuk mengakses buffer data permintaan dapat bergantung pada metode driver untuk mengakses buffer data untuk perangkat. UMDF mendukung metode akses buffer berikut:

Metode akses ketiga, yang disebut tidak di-buffer atau I/O langsung, tidak tersedia untuk driver berbasis UMDF, tetapi UMDF dapat mengonversi beberapa permintaan I/O dari metode "tidak keduanya" ke metode yang didukung versi UMDF.

Dalam kebanyakan kasus, driver berbasis UMDF memanggil metode objek UMDF yang sama untuk mengakses buffer data, baik UMDF dan driver menggunakan I/O buffer atau I/O langsung. I/O langsung sering memberikan performa yang lebih baik daripada yang disediakan buffer I/O.

Bagian berikut dari topik ini menjelaskan:

Menentukan Metode Akses Buffer Pilihan

UMDF versi 1.9 dan yang lebih baru mendukung metode akses I/O yang di-buffer dan langsung. Driver dapat menentukan metode akses yang lebih Anda sukai untuk semua permintaan kontrol I/O baca, tulis, dan perangkat perangkat dengan memanggil IWDFDeviceInitialize2::SetIoTypePreference sebelum memanggil IWDFDriver::CreateDevice untuk membuat objek perangkat. Misalnya, jika driver menentukan preferensi hanya untuk metode I/O yang di-buffer untuk permintaan baca dan tulis untuk salah satu perangkatnya, proses host driver UMDF menggunakan metode I/O yang di-buffer saat mengirimkan permintaan baca dan tulis ke driver untuk perangkat tersebut. Jika driver menentukan preferensi untuk I/O langsung, UMDF dapat (tetapi mungkin tidak) menggunakan I/O langsung. Untuk informasi selengkapnya tentang kapan UMDF menggunakan I/O langsung, lihat Bagaimana UMDF Memilih Metode Akses Buffer untuk Permintaan I/O.

Untuk setiap perangkat yang didukung driver, driver dapat menentukan preferensi untuk I/O buffer, untuk I/O langsung, atau untuk I/O buffer atau langsung untuk perangkat. Driver dapat menentukan satu jenis metode akses untuk permintaan baca dan tulis dan jenis metode akses lain untuk permintaan kontrol I/O perangkat. Jika driver tidak menentukan preferensi metode akses, UMDF menggunakan metode buffer.

Untuk permintaan kontrol I/O perangkat, kode kontrol I/O (IOCTL) menentukan metode akses buffer. (Untuk informasi selengkapnya tentang bagaimana IOCTL menentukan metode akses, lihat Menentukan Kode Kontrol I/O.) Namun, metode akses yang digunakan UMDF mungkin tidak cocok dengan metode akses yang ditentukan IOCTL.

Menentukan Mode Pengambilan Buffer

Dalam versi UMDF sebelum versi 1.9, UMDF selalu membuat buffer permintaan I/O tersedia untuk driver (dengan menyalin buffer ke dalam proses host driver UMDF) segera setelah UMDF menerima permintaan I/O. Mode pengambilan buffer ini disebut pengambilan segera. Jika kegagalan terjadi, UMDF menyelesaikan permintaan I/O dengan nilai status kegagalan dan tidak mengirimkan permintaan I/O ke driver.

UMDF versi 1.9 dan yang lebih baru mendukung mode pengambilan segera dan pengambilan yang ditangguhkan . Mode pengambilan yang ditangguhkan menunda penyalinan buffer permintaan I/O ke dalam proses host driver hingga driver mencoba mengakses buffer. Jika kegagalan terjadi, fungsi akses buffer mengembalikan nilai status kesalahan ke driver.

Driver Anda dapat menentukan mode pengambilan buffer saat memanggil IWDFDeviceInitialize2::SetIoTypePreference untuk setiap perangkat. Gunakan aturan berikut:

  • Jika driver Anda menentukan metode akses I/O langsung, driver juga harus menentukan mode pengambilan yang ditangguhkan. I/O langsung hanya berfungsi dengan pengambilan yang ditangguhkan.

  • Semua driver yang ditulis untuk dijalankan dengan UMDF versi 1.9 dan yang lebih baru harus menentukan mode pengambilan yang ditangguhkan untuk semua permintaan I/O, apakah driver memilih metode akses I/O yang di-buffer atau langsung. Pengambilan yang ditangguhkan memberikan performa yang lebih baik karena tidak mengakses buffer yang tidak digunakan driver.

Jika driver Anda tidak menentukan mode pengambilan buffer, UMDF menggunakan pengambilan segera.

Semua driver berbasis UMDF dalam tumpukan driver harus menggunakan mode pengambilan yang sama. Jika beberapa driver menentukan pengambilan segera dan beberapa menentukan pengambilan yang ditangguhkan, UMDF menggunakan pengambilan segera.

Bagaimana UMDF Memilih Metode Akses Buffer untuk Permintaan I/O

Metode akses yang ditentukan driver saat memanggil IWDFDeviceInitialize2::SetIoTypePreference, mungkin bukan yang digunakan UMDF. UMDF menggunakan aturan berikut untuk menentukan metode akses mana yang akan digunakan:

  • Semua driver berbasis UMDF dalam tumpukan driver harus menggunakan metode yang sama untuk mengakses buffer perangkat. Jika UMDF menentukan bahwa beberapa driver lebih suka I/O buffer atau I/O langsung untuk perangkat sementara driver lain hanya lebih suka I/O buffer untuk perangkat, UMDF menggunakan I/O buffer untuk semua driver. Jika satu atau beberapa driver tumpukan lebih suka hanya I/O yang di-buffer sementara yang lain hanya lebih suka I/O langsung, UMDF mencatat peristiwa ke log peristiwa sistem dan tidak memulai tumpukan driver.

    Driver Anda dapat memanggil IWDFDevice2::GetDeviceStackIoTypePreference untuk menentukan metode akses buffer yang telah ditetapkan UMDF ke permintaan baca/tulis perangkat dan permintaan kontrol I/O.

  • Dalam beberapa kasus, driver menentukan preferensi untuk I/O langsung saat memanggil IWDFDeviceInitialize2::SetIoTypePreference, tetapi untuk performa terbaik, UMDF menggunakan I/O buffer untuk satu atau beberapa permintaan perangkat. Misalnya, UMDF menggunakan I/O buffer untuk buffer kecil jika dapat menyalin data ke buffer driver lebih cepat daripada yang dapat memetakan buffer untuk akses langsung.

    Secara opsional, Anda dapat mengatur nilai registri DirectTransferThreshold yang diketik REG_DWORD yang digunakan kerangka kerja untuk menentukan ukuran buffer terkecil yang kerangka kerjanya akan menggunakan I/O langsung. Biasanya, Anda tidak perlu memberikan nilai registri ini karena kerangka kerja menggunakan nilai yang memberikan performa terbaik. Nilai DirectTransferThreshold terletak di bawah subkunci Device Parameters\WUDF perangkat, yang berada di bawah kunci perangkat keras perangkat.

    Kerangka kerja menggunakan aturan berikut untuk menentukan ambang berdasarkan nilai yang Anda berikan di DirectTransferThreshold. Angka yang diberikan mengasumsikan PAGE_SIZE 4096, yang valid kecuali pada sistem berbasis Itanium.

    • Jika Anda mengatur DirectTransferThreshold ke nilai apa pun yang kurang dari atau sama dengan 8192 (atau 2 * PAGE_SIZE), kerangka kerja menetapkan ambang batas ke 8192. Kerangka kerja ini menggunakan I/O buffer untuk buffer yang lebih kecil dari 8192 byte, dan I/O langsung untuk buffer yang sama dengan atau lebih besar dari 8192 byte.

    • Jika Anda mengatur DirectTransferThreshold ke nilai apa pun yang lebih besar dari 8192, kerangka kerja dibulatkan ke kelipatan PAGE_SIZE yang tepat berikutnya. Sekali lagi, kerangka kerja menggunakan I/O buffer untuk buffer yang lebih kecil dari ambang batas, dan I/O langsung untuk buffer yang sama dengan atau lebih besar dari ambang batas.

  • UMDF menggunakan I/O langsung hanya untuk ruang buffer yang dimulai dan berakhir pada batas halaman memori. Jika awal atau akhir buffer tidak terletak pada batas halaman, UMDF menggunakan I/O buffer untuk bagian buffer tersebut. Dengan kata lain, UMDF mungkin menggunakan I/O yang di-buffer dan I/O langsung untuk transfer data besar yang terdiri dari beberapa permintaan I/O.

  • Untuk permintaan kontrol I/O perangkat, UMDF menggunakan I/O langsung hanya jika kode kontrol I/O (IOCTL) menentukan I/O langsung dan hanya jika semua driver berbasis UMDF perangkat telah memanggil IWDFDeviceInitialize2::SetIoTypePreference untuk menentukan metode akses langsung.

Driver menggunakan set metode objek permintaan yang sama untuk mengakses buffer data, terlepas dari metode akses buffer. Oleh karena itu, sebagian besar driver biasanya tidak perlu mengetahui apakah UMDF menggunakan I/O buffer atau I/O langsung untuk permintaan I/O.

Bagaimana Driver Dapat Memperoleh Metode Akses untuk Permintaan I/O

Dalam beberapa kasus, Anda dapat meningkatkan performa perangkat dan driver jika metode akses diketahui. Dalam kasus seperti itu, driver Anda dapat memanggil IWDFIoRequest2::GetEffectiveIoType untuk mendapatkan metode akses buffer permintaan I/O.

Misalnya, pertimbangkan perangkat throughput tinggi yang biasanya menggunakan I/O langsung. Karena menggunakan I/O langsung, driver harus menyalin parameter yang ditentukan aplikasi ke memori driver lokal sebelum memvalidasi parameter, untuk memastikan bahwa aplikasi tidak memodifikasi parameter setelah validasi.

Karena driver mungkin kadang-kadang menerima buffer yang menggunakan I/O buffer, dan karena buffer I/O buffer telah disalin, aplikasi tidak dapat memodifikasi data dan driver tidak harus menyalin parameter sebelum memvalidasinya. Oleh karena itu, driver harus memeriksa setiap metode akses buffer permintaan untuk menentukan apakah harus menyalin parameter sebelum memvalidasinya.

Menggunakan I/O Buffered di Driver UMDF

Jika driver Anda menggunakan I/O buffer, perilaku UMDF berbeda tergantung pada jenis permintaan. Untuk permintaan baca dan tulis, proses host driver membuat buffer perantara tunggal yang dapat diakses driver.

Untuk permintaan tulis, proses host driver mentransfer informasi input dari buffer input aplikasi panggilan sebelum memanggil tumpukan driver. Driver biasanya membaca informasi input dari buffer perantara dan menulisnya ke perangkat.

Untuk permintaan baca, driver biasanya membaca informasi dari perangkat dan menyimpannya di buffer perantara. Proses host driver menyalin data output dari buffer perantara ke buffer output aplikasi.

Namun, untuk permintaan kontrol I/O perangkat, proses host driver membuat dua buffer terpisah yang dapat diakses driver. Perhatikan bahwa ini berbeda dari perilaku driver WDM dan KMDF, yang permintaan kontrol I/O baca, tulis, dan perangkat yang dikirim menggunakan hasil I/O yang di-buffer pada driver yang mengakses buffer perantara tunggal. Dalam hal ini, buffer output awalnya tidak berisi apa-apa, dan driver tidak boleh membaca darinya. Selain itu, data apa pun yang ditulis driver ke buffer input dibuang dan tidak dikembalikan ke aplikasi panggilan.

Untuk panduan tentang kapan harus memilih I/O yang di-buffer, lihat WDF_DEVICE_IO_TYPE.

UMDF versi 1.9 dan yang lebih baru dapat mendukung pengambilan buffer permintaan segera atau ditangguhkan. Untuk informasi selengkapnya, lihat WDF_DEVICE_IO_BUFFER_RETRIEVAL.

Driver yang menggunakan mode pengambilan buffer langsung harus menggunakan IWDFIoRequest::GetInputMemory dan IWDFIoRequest::GetOutputMemory untuk mengakses buffer.

Driver yang menggunakan mode pengambilan buffer yang ditangguhkan dapat mengakses buffer dengan memanggil IWDFIoRequest2::RetrieveInputBuffer, IWDFIoRequest2::RetrieveInputMemory, IWDFIoRequest2::RetrieveOutputBuffer, atau IWDFIoRequest2::RetrieveOutputMemory.

Menggunakan I/O Langsung di Driver UMDF

Jika driver Anda menggunakan I/O langsung, proses host driver memverifikasi aksesibilitas ruang buffer yang ditentukan oleh pencitra permintaan I/O (biasanya aplikasi mode pengguna), mengunci ruang buffer ke dalam memori fisik, lalu memberi driver akses langsung ke ruang buffer.

Untuk panduan tentang kapan harus memilih I/O langsung, lihat WDF_DEVICE_IO_TYPE.

Driver Anda dapat mengakses buffer dengan memanggil IWDFIoRequest2::RetrieveInputBuffer, IWDFIoRequest2::RetrieveInputMemory, IWDFIoRequest2::RetrieveOutputBuffer, atau IWDFIoRequest2::RetrieveOutputMemory.

Tidak menggunakan Buffered I/O maupun Direct I/O di Driver UMDF

Metode akses buffer yang dikenal sebagai metode I/O atau I/O langsung yang di-buffer (atau, metode "tidak keduanya", singkatnya) memungkinkan driver untuk langsung mengakses penunjuk buffer permintaan aplikasi. Driver berbasis UMDF tidak dapat menggunakan metode akses ini.

Namun, definisi beberapa kode kontrol I/O perangkat (IOCTL) menentukan bahwa permintaan menggunakan metode "tidak keduanya". Secara opsional, UMDF dapat mengonversi metode akses buffer dari permintaan kontrol I/O perangkat tersebut menjadi I/O yang di-buffer atau I/O langsung. Gunakan langkah-langkah berikut:

  1. Sertakan direktif UmdfMethodNeitherAction di bagian INF DDInstall dari file INF driver Anda. Anda dapat mengatur nilai direktif untuk menunjukkan bahwa UMDF harus meneruskan permintaan kontrol I/O perangkat yang menggunakan metode akses "tidak ada" ke driver. (Jika tidak, UMDF menyelesaikan permintaan I/O ini dengan nilai status kesalahan.)

  2. Akses buffer permintaan I/O dengan menggunakan metode objek yang disediakan UMDF untuk I/O buffer atau I/O langsung.

Anda harus mengaktifkan dukungan permintaan IOCTL yang menggunakan metode "tidak keduanya" hanya jika Anda yakin bahwa UMDF dapat mengonversi metode akses menjadi I/O yang di-buffer atau I/O langsung. Misalnya, jika IOCTL menentukan permintaan yang disesuaikan yang tidak mengikuti aturan spesifikasi buffer yang dijelaskan di Deskripsi Buffer untuk Kode Kontrol I/O, UMDF tidak dapat mengonversi buffer.