Panduan untuk Porting Driver Filter Warisan
Pengembang didorong untuk memindahkan driver filter warisan ke model manajer filter untuk mendapatkan fungsionalitas yang lebih baik untuk driver filter mereka dan meningkatkan keandalan sistem. Pengembang berpengalaman harus merasa relatif mudah untuk memindahkan driver filter warisan ke driver minifilter. Filter pengembang driver di Microsoft merekomendasikan pendekatan berikut:
Mulailah dengan rangkaian pengujian regresi yang andal untuk memverifikasi perilaku antara driver filter lama dan driver minifilter port.
Buat shell driver minifilter dan pindahkan fungsionalitas secara sistematis dari driver filter warisan ke driver minifilter. Misalnya, buat lampiran berfungsi lalu port satu operasi sekaligus, pengujian setelah setiap operasi.
Ubah komunikasi mode pengguna/mode kernel terakhir, sehingga Anda dapat menggunakan alat yang ada untuk menguji driver minifilter.
Kompilasi dengan PREfast dan uji dengan opsi verifikasi Filter Verifier I/O di Driver Verifier diaktifkan.
Selama proses porting, Anda harus meninjau semua kode driver filter warisan untuk memanfaatkan sepenuhnya kemampuan manajer filter. Secara khusus, ingatlah hal-hal berikut:
I/O berbasis IRP dan operasi I/O cepat dapat melalui operasi yang sama jika sesuai, yang membantu mengurangi duplikasi kode.
Saat mendaftar untuk operasi, driver minifilter dapat secara eksplisit memilih untuk mengabaikan semua I/O halaman dan I/O yang di-cache, yang menghilangkan kebutuhan kode untuk memeriksanya.
Pemberitahuan instans sangat menyederhanakan logika lampirkan/lepaskan.
Daftar hanya untuk operasi yang harus ditangani driver minifilter Anda; Anda dapat mengabaikan segala sesuatu yang lain.
Manfaatkan konteks manajer filter dan dukungan manajemen nama.
Manfaatkan dukungan manajer filter untuk menerbitkan I/O non-rekursif.
Tidak seperti driver filter warisan, driver minifilter tidak dapat mengandalkan variabel lokal untuk mempertahankan konteks dari pemrosesan praoperasi hingga pemrosesan pascaoperasi. Pertimbangkan untuk mengalokasikan daftar lookaside untuk menyimpan status operasi.
Pastikan untuk merilis referensi setelah selesai dengan nama atau konteks.
Port penyelesaian dalam mode pengguna menambahkan teknik yang kuat untuk membangun antrean. Anda mungkin hanya akan membutuhkan satu koneksi ke satu port bernama.
Tabel berikut mencantumkan operasi umum dalam driver filter warisan dan bagaimana mereka memetakan ke model manajer filter.
| Model driver filter warisan | Model manajer filter |
|---|---|
Operasi pass-through tanpa rutinitas penyelesaian |
Jika driver minifilter Anda tidak pernah berfungsi untuk jenis operasi I/O ini, jangan mendaftarkan rutinitas panggilan balik praoperasi atau pascaoperasi untuk operasi ini. Jika tidak, kembalikan FLT_PREOP_SUCCESS_NO_CALLBACK dari rutinitas panggilan balik praoperasi yang terdaftar untuk operasi ini. |
Operasi pass-through dengan rutinitas penyelesaian |
Mengembalikan FLT_PREOP_SUCCESS_WITH_CALLBACK dari rutinitas panggilan balik praoperasi. |
Operasi tertunda dalam rutinitas panggilan balik praoperasi |
Panggil FltLockUserBuffer sesuai kebutuhan untuk memastikan bahwa setiap buffer pengguna dikunci dengan benar sehingga dapat diakses di utas pekerja. Antrekan pekerjaan ke utas pekerja dengan memanggil rutinitas dukungan seperti FltAllocateDeferredIoWorkItem dan FltQueueDeferredIoWorkItem. Mengembalikan FLT_PREOP_PENDING dari rutinitas panggilan balik praoperasi. Ketika siap untuk mengembalikan operasi I/O ke manajer filter, panggil FltCompletePendedPreOperation. Lihat Operasi I/O tertunda dalam Rutinitas Panggilan Balik Praoperasi. |
Operasi tertunda dalam rutinitas panggilan balik pascaoperasi |
Dalam rutinitas panggilan balik praoperasi, panggil FltLockUserBuffer untuk memastikan bahwa buffer pengguna dikunci dengan benar sehingga dapat diakses di utas pekerja. Antrekan pekerjaan ke utas pekerja dengan memanggil rutinitas dukungan seperti FltAllocateGenericWorkItem dan FltQueueGenericWorkItem. Mengembalikan FLT_POSTOP_MORE_PROCESSING_REQUIRED dari rutinitas panggilan balik pascaoperasi. Ketika siap untuk mengembalikan operasi I/O ke manajer filter, panggil FltCompletePendedPostOperation. Lihat Operasi I/O tertunda dalam Rutinitas Panggilan Balik Pascaoperasi. |
Menyinkronkan operasi |
Mengembalikan FLT_PREOP_SYNCHRONIZE dari rutinitas panggilan balik praoperasi. |
Selesaikan operasi dalam rutinitas panggilan balik praoperasi |
Atur status operasi akhir dan informasi di anggota IoStatus dari struktur FLT_CALLBACK_DATA untuk operasi. Mengembalikan FLT_PREOP_COMPLETE dari rutinitas panggilan balik praoperasi. Lihat Menyelesaikan Operasi I/O dalam Rutinitas Panggilan Balik Praoperasi. |
Selesaikan operasi setelah ditunda dalam rutinitas panggilan balik praoperasi |
Atur status operasi akhir dan informasi di anggota IoStatus dari struktur FLT_CALLBACK_DATA untuk operasi. Panggil FltCompletePendedPreOperation dari utas pekerja yang memproses operasi I/O, melewati FLT_PREOP_COMPLETE sebagai parameter CallbackStatus . Lihat Menyelesaikan Operasi I/O dalam Rutinitas Panggilan Balik Praoperasi. |
Lakukan semua pekerjaan penyelesaian dalam rutinitas penyelesaian |
Mengembalikan FLT_POSTOP_FINISHED_PROCESSING dari rutinitas panggilan balik pascaoperasi. |
Lakukan pekerjaan penyelesaian di IRQL yang aman |
Panggil FltDoCompletionProcessingWhenSafe dari rutinitas panggilan balik pascaoperasi. Lihat Memastikan bahwa Pemrosesan Penyelesaian Dilakukan di IRQL Aman. |
Memberi sinyal peristiwa dari rutinitas penyelesaian |
Kembalikan FLT_PREOP_SYNCHRONIZE dari rutinitas panggilan balik praoperasi untuk operasi ini. Manajer filter memanggil rutinitas panggilan balik pascaoperasi dalam konteks utas yang sama dengan rutinitas panggilan balik praoperasi, di IRQL <= APC_LEVEL. |
Gagal membuat operasi yang berhasil |
Panggil FltCancelFileOpen dari rutinitas panggilan balik pascaoperasi untuk operasi pembuatan. Tetapkan nilai kesalahan NTSTATUS yang sesuai di anggota IoStatus dari struktur FLT_CALLBACK_DATA untuk operasi. Mengembalikan FLT_POSTOP_FINISHED_PROCESSING. Lihat Gagal operasi I/O dalam Rutinitas Panggilan Balik Pascaoperasi. |
Melarang I/O melalui jalur I/O cepat untuk operasi I/O |
Mengembalikan FLT_STATUS_DISALLOW_FAST_IO dari rutinitas panggilan balik praoperasi untuk operasi. Lihat Melarang Operasi I/O Cepat dalam Rutinitas Panggilan Balik Praoperasi. |
Mengubah parameter untuk operasi I/O |
Atur nilai parameter yang dimodifikasi di anggota Iopb dari struktur FLT_CALLBACK_DATA untuk operasi. Tandai struktur FLT_CALLBACK_DATA sebagai kotor dengan memanggil FltSetCallbackDataDirty, kecuali ketika Anda telah memodifikasi konten anggota IoStatus dari struktur FLT_CALLBACK_DATA. |
Mengunci buffer pengguna untuk operasi |
Gunakan teknik dan panduan yang dijelaskan dalam Mengakses Buffer Pengguna untuk Operasi I/O. |