Mendukung klien Kernel-Mode di Driver UMDF 1.x

Artikel
03/08/2023

Peringatan

UMDF 2 adalah versi terbaru UMDF dan supersedes 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.

Sampel UMDF 1 yang diarsipkan dapat ditemukan di Windows 11, versi 22H2 - Pembaruan Sampel Driver Mei 2022.

Untuk informasi selengkapnya, lihat Mulai menggunakan UMDF.

Peringatan

Lihat juga Mendukung klien Kernel-Mode di UMDF 2.x.

UMDF versi 1.9 dan yang lebih baru memungkinkan driver UMDF untuk mendukung klien mode kernel. Klien mode kernel dapat berupa salah satu hal berikut ini:

Driver mode kernel yang ada di atas driver UMDF dalam tumpukan driver perangkat.
Driver mode-kernel untuk satu tumpukan perangkat, yang mendukung satu perangkat, membuka handel ke perangkat lain, dan tumpukan driver perangkat yang terakhir berisi driver UMDF.

Dengan kata lain, driver UMDF yang mendukung klien mode kernel dapat menerima permintaan I/O dari driver mode kernel. Driver mode kernel dapat meneruskan permintaan I/O yang telah diterimanya dari aplikasi mode pengguna, atau dapat membuat permintaan I/O baru dan mengirimkannya ke driver mode pengguna.

Untuk menentukan apakah driver UMDF Anda harus mendukung klien mode kernel, Anda harus memahami tumpukan driver tempat driver Anda akan ditambahkan, dan di mana dalam tumpukan itu driver Anda akan berada. Anda juga harus menentukan apakah driver dari tumpukan lain mungkin mengirim permintaan I/O ke perangkat driver Anda.

Driver Anda harus mendukung klien mode kernel jika:

Driver mode kernel dapat terletak tepat di atas driver UMDF Anda di tumpukan driver. Misalnya, driver filter mode kernel mungkin berada tepat di atas driver fungsi berbasis UMDF.
Driver mode kernel dari tumpukan lain dapat mengirim permintaan I/O ke perangkat driver Anda. Misalnya, driver Anda mungkin membuat tautan simbolis yang dapat digunakan driver mode kernel di tumpukan lain untuk membuka handel ke perangkat driver Anda. Driver mode kernel kemudian dapat mengirim permintaan I/O ke perangkat.

Cara mendukung klien mode kernel dalam driver UMDF

Driver UMDF dapat menerima permintaan I/O dari driver mode kernel hanya jika driver UMDF telah mengaktifkan dukungan untuk klien mode kernel. Selain itu, jika penginstalan perangkat mencoba memuat driver mode kernel di atas driver UMDF di tumpukan driver perangkat, kerangka kerja memungkinkan driver untuk memuat hanya jika driver UMDF telah mengaktifkan dukungan untuk klien mode kernel.

Untuk mengaktifkan dukungan driver UMDF untuk klien mode kernel, file INF driver UMDF harus menyertakan arahan UmdfKernelModeClientPolicy dalam INF DDInstall-nya. Bagian WDF . Jika file INF driver UMDF tidak menyertakan direktif ini, UMDF tidak mengizinkan driver mode kernel yang diinstal di atas driver UMDF untuk berjalan.

Kerangka kerja ini menyediakan dua metode yang berguna untuk driver yang mendukung klien mode kernel. Driver dapat memanggil metode IWDFIoRequest2::GetRequestorMode untuk menentukan apakah permintaan I/O berasal dari mode kernel atau mode pengguna. Jika permintaan I/O berasal dari mode pengguna, driver dapat memanggil IWDFIoRequest2::IsFromUserModeDriver untuk menentukan apakah permintaan berasal dari aplikasi atau driver mode pengguna lainnya.

Pembatasan driver mode kernel

Driver UMDF dapat memproses permintaan I/O dari driver mode kernel hanya jika driver mode kernel memenuhi persyaratan berikut:

Driver mode kernel harus berjalan di IRQL = PASSIVE_LEVEL saat mengirim permintaan I/O.
Kecuali driver telah mengatur direktif INF UmdfFileObjectPolicy ke AllowNullAndUnknownFileObjects, setiap permintaan I/O yang dikirim driver mode kernel ke driver mode pengguna harus memiliki objek file terkait. Kerangka kerja sebelumnya harus diberi tahu bahwa manajer I/O membuat objek file. (Pemberitahuan tersebut menyebabkan kerangka kerja memanggil fungsi panggilan balik IQueueCallbackCreate::OnCreateFile driver pengguna, tetapi fungsi panggilan balik tersebut bersifat opsional.)
Permintaan I/O tidak boleh berisi kode fungsi IRP_MJ_INTERNAL_DEVICE_CONTROL .
Buffer permintaan I/O tidak boleh berisi pointer ke informasi tambahan, karena driver mode pengguna tidak dapat mendereferensikan pointer.
Jika permintaan I/O berisi kode kontrol I/O yang menentukan metode akses buffer "tidak keduanya", driver mode kernel harus mengirim permintaan I/O dalam konteks proses aplikasi yang membuat permintaan I/O. Untuk informasi selengkapnya tentang cara mendukung metode "tidak keduanya" dalam driver berbasis UMDF, lihat Menggunakan I/O Buffered maupun I/O Langsung di Driver UMDF.
Driver UMDF mungkin mengubah data output permintaan I/O, dalam mode pengguna. Oleh karena itu, driver mode kernel harus memvalidasi data output apa pun yang diterimanya dari driver mode pengguna.
Klien mode kernel biasanya harus memvalidasi nilai Informasi yang diteruskan driver UMDF ke IWDFIoRequest::CompleteWithInformation. Jika klien adalah driver KMDF, klien dapat memanggil WdfRequestGetCompletionParams untuk mendapatkan informasi ini dalam struktur IO_STATUS_BLOCK.

Biasanya, kerangka kerja tidak memvalidasi nilai informasi yang diteruskan driver UMDF ke IWDFIoRequest::CompleteWithInformation. (Parameter ini biasanya menentukan jumlah byte yang ditransfer.) Kerangka kerja memvalidasi nilai informasi hanya untuk buffer output, dan hanya untuk metode akses data I/O yang di-buffer . (Misalnya, kerangka kerja memverifikasi bahwa jumlah byte yang ditransfer tidak melebihi ukuran buffer output operasi baca, jika metode akses di-buffer I/O.)

Menangani nilai status pengembalian dalam driver UMDF 1.x

Meneruskan nilai status pengembalian dari mode pengguna ke mode kernel memerlukan perhatian khusus, sebagai berikut:

Driver UMDF versi 1 biasanya menerima nilai pengembalian berjenis HRESULT, sementara driver mode kernel berbasis KMDF dan WDM biasanya menerima nilai berjenis NTSTATUS. Jika UMDF 1. driver x menyelesaikan permintaan I/O, dan jika driver memiliki klien mode kernel, panggilan driver ke IWDFIoRequest::Complete atau IWDFIoRequest::CompleteWithInformation harus menentukan nilai HRESULT yang dihasilkan driver dari nilai NTSTATUS. Secara umum, UMDF 1. Driver x harus menggunakan makro HRESULT_FROM_NT (ditentukan dalam Winerror.h) untuk mengembalikan status ke klien mode kernel. Contoh berikut menunjukkan cara menggunakan makro ini saat menyelesaikan permintaan.
```
hr = HRESULT_FROM_NT(STATUS_BUFFER_OVERFLOW)
request->Complete(HRESULT_FROM_NT(STATUS_BUFFER_OVERFLOW);
return hr;
```
Untuk mengembalikan nilai HRESULT tertentu ke klien mode kernel, panggilan balik berikut harus menggunakan makro HRESULT_FROM_NT:
Untuk menggunakan nilai NTSTATUS yang ditentukan dalam ntstatus.h, UMDF 1. driver x harus menyertakan kedua baris ini sebelum menyertakan header tambahan.
```
#define UMDF_USING_NTSTATUS
#include <ntstatus.h>
```
Jangan gunakan makro HRESULT_FROM_NT untuk mengonversi STATUS_SUCCESS dari nilai NTSTATUS ke nilai HRESULT. Cukup kembalikan S_OK, seperti yang ditunjukkan dalam contoh berikut.
```
request->Complete(S_OK);
```
Kerangka kerja menyelesaikan beberapa permintaan I/O atas nama driver UMDF. Terkadang kerangka kerja tidak mengonversi nilai pengembalian yang ditik HRESULT menjadi nilai NTSTATUS yang setara, sehingga kerangka kerja mungkin meneruskan status penyelesaian jenis HRESULT ke klien mode kernel.

Karena situasi ini, klien mode kernel tidak boleh menggunakan makro NT_ERROR saat menguji status penyelesaian permintaan I/O, karena makro NT_ERROR tidak mengembalikan TRUE untuk nilai kesalahan HRESULT. Driver mode kernel harus menggunakan makro NT_SUCCESS saat menguji status penyelesaian permintaan I/O.

Dukungan klien mode kernel di versi UMDF sebelumnya

Untuk versi UMDF yang lebih lama dari versi 1.9, file INF driver dapat menyertakan direktif INF AddReg untuk membuat nilai registri UpperDriverOk berukuran REG_DWORD di bawah subkunci WUDFkunci perangkat keras perangkat keras perangkat.

Jika nilai registri UpperDriverOk diatur ke angka bukan nol, kerangka kerja memungkinkan driver mode kernel memuat di atas driver mode pengguna. Driver mode kernel dapat meneruskan permintaan I/O dari aplikasi mode pengguna ke driver UMDF, tetapi driver mode kernel tidak dapat mengirim permintaan I/O yang dibuat dalam mode kernel ke driver UMDF.

Untuk UMDF versi 1.9 dan yang lebih baru, nilai registri UpperDriverOk sudah usang dan hanya didukung untuk driver yang ada. Driver baru harus menggunakan direktif UmdfKernelModeClientPolicy .

Bagikan melalui