Membangun driver WDF untuk beberapa versi Windows

WDF selalu memungkinkan Anda untuk membangun driver sekali dan menggunakan biner yang dihasilkan pada beberapa versi Windows, tetapi sebelum Windows 10 versi 1803 (Redstone 4), ini terbatas pada "build pada yang lebih lama, berjalan pada yang lebih baru." Mulai dari Windows 10 versi 1803, WDF menambahkan "build on newer, run on older," dengan manfaat tambahan dari eksekusi kondisional. Untuk meringkas:

• Yang sudah ada: Biner yang dibangun dengan versi kerangka kerja yang lebih lama berjalan pada versi Windows yang menyertakan versi kerangka kerja yang lebih baru, menyediakan versi utama yang cocok. Misalnya, driver yang dibangun dengan KMDF 1.9 (Windows 7) berjalan pada sistem Windows 8 (KMDF 1.11). Dalam contoh, driver terbatas pada fungsionalitas KMDF 1.9.
• Ditambahkan: Mulai dari KMDF versi 1.25 dan UMDF versi 2.25 pada Windows 10 versi 1803, Anda dapat membangun driver dengan versi kerangka kerja yang lebih baru dan biner driver yang dihasilkan berjalan pada versi Windows yang lebih lama (minimal Windows 10 versi 1803). Selain itu, driver dapat menggunakan fungsionalitas secara kondisional yang hanya tersedia dalam versi kerangka kerja yang lebih baru.

Ini berarti bahwa driver Anda tidak hanya berjalan pada versi Windows yang akan datang, seperti yang selalu ada, tetapi juga berjalan pada versi sebelumnya, kembali ke versi Windows 10 1803.

Ada dua langkah untuk melakukan ini: menentukan pengaturan build di Visual Studio, dan melakukan pemeriksaan runtime sebelum memanggil API atau mengakses struktur atau bidang yang mungkin atau mungkin tidak ada.

Catatan: Fitur ini bersifat opsional dan driver hanya boleh mengaktifkannya untuk membangun driver yang menggunakan fungsionalitas WDF terbaru sambil tetap dapat dimuat pada versi Windows sebelumnya yang tidak memiliki fungsionalitas WDF terbaru.

Jika Anda tidak mengatur Versi Minor (Versi Target) atau Versi Minor (Minimum Diperlukan), penerapan versi tetap sama seperti sebelumnya.

Menentukan Minimum diperlukan

Pengaturan konfigurasi baru di Visual Studio adalah:

• KMDF Versi Minor (Minimum Diperlukan)
• UMDF Versi Minor (Minimum Diperlukan)

Sesuai dengan perubahan ini, nama dua pengaturan yang ada diperbarui:

• Versi KMDF Minor ->KMDF Versi Minor (Versi Target)
• UMDF Versi Minor ->UMDF Versi Minor (Versi Target)

Jika Anda tidak mengatur Minimum Diperlukan, Visual Studio akan dibuat untuk Versi Target dan yang lebih baru, dan tidak memberikan dukungan downlevel. Ini cocok dengan perilaku properti Minor Versi lama.

Jika Anda menetapkan Minimum Diperlukan, persyaratan berikut berlaku:

• 25 <= Minimum Diperlukan <= Versi Target
• Di Properti Konfigurasi-Pengaturan> Driver-Umum>, atur _NT_TARGET_VERSION ke 0x0A000005 (RS4) atau yang lebih baru.

Memeriksa apakah fungsionalitas ada

Sebelum setiap penggunaan API, struktur, atau anggota yang mungkin atau mungkin tidak ada, Anda harus memanggil salah satu makro berikut, yang didefinisikan dalam WdfFuncEnum.h:

BOOLEAN
WDF_IS_FUNCTION_AVAILABLE (
    FunctionName
    );

BOOLEAN
WDF_IS_STRUCTURE_AVAILABLE (
    StructName
    );

BOOLEAN
WDF_IS_FIELD_AVAILABLE (
    StructName,
    FieldName
    );

Pertimbangkan contoh berikut. Ketika WDF v29 dirilis, WdfSomeNewFeature menambahkan API baru: WdfSomeNewFeature. Jika Anda mengatur Versi Target ke 29 dan Minimum Diperlukan ke 25, driver yang dihasilkan dimuat pada versi kerangka kerja apa pun dari 25 hingga 29 (dan seterusnya, selama versi utama tidak berubah), memanggil API versi 25 seperti sebelumnya, dan melakukan pemeriksaan berikut sebelum setiap panggilan API v29 apa pun:

if (WDF_IS_FUNCTION_AVAILABLE(WdfSomeNewFeature)) {
    WdfSomeNewFeature();
}

Jika Anda tidak melakukan pemeriksaan kondisi, Anda mungkin melihat hal berikut:

• Jika API mengembalikan NTSTATUS, panggilan mengembalikan kode kegagalan.
• Jika API mengembalikan apa pun selain NTSTATUS:
  • KMDF: Pemeriksaan bug mesin.
  • UMDF: Proses WudfHost mengalami crash dengan kesalahan DriverStop.
• Jika Driver Verifier diaktifkan, driver juga mengalami crash. Ini membantu mengidentifikasi masalah di lingkungan pengujian.
• Kerusakan memori senyap (saat mengakses struktur atau bidang).

Crash driver berisi nama driver yang gagal, nama kerangka kerja, dan indeks API yang gagal. Anda dapat mengambil nama API dengan mencari nilai WDFFUNCENUM di WdfFuncEnum.h.

Untuk informasi selengkapnya tentang properti Visual Studio untuk WDF, lihat Properti Pengaturan Model Driver untuk Proyek Driver.