Bagikan melalui

Menulis driver Universal Windows (KMDF) berdasarkan templat

  • Artikel

Topik ini menjelaskan cara menulis driver Universal Windows menggunakan Kernel-Mode Driver Framework (KMDF). Anda akan mulai dengan templat Microsoft Visual Studio lalu menyebarkan dan menginstal driver Anda di komputer terpisah.

Sebelum melanjutkan, Anda harus mengikuti langkah-langkah penginstalan yang tercantum dalam Unduh Windows Driver Kit (WDK).

Alat Penelusuran Kesalahan untuk Windows disertakan saat Anda menginstal WDK.

Membuat dan membangun driver

  1. Buka Microsoft Visual Studio. Pada menu File, pilih Proyek Baru>.

  2. Dalam kotak dialog Buat proyek baru , pilih C++ di menu dropdown kiri, pilih Windows di dropdown tengah, dan pilih Driver di menu dropdown kanan.

  3. Pilih Driver Mode Kernel (KMDF) dari daftar jenis proyek. Pilih Selanjutnya.

    Cuplikan layar kotak dialog proyek baru, memperlihatkan driver mode kernel dipilih.

  4. Dalam kotak dialog Konfigurasikan proyek baru Anda , masukkan "KmdfDriver" di bidang Nama proyek .

    Catatan

    Saat membuat driver KMDF atau UMDF baru, Anda harus memilih nama driver yang memiliki 32 karakter atau kurang. Batas panjang ini didefinisikan dalam wdfglobals.h.  

  5. Di bidang Lokasi , masukkan direktori tempat Anda ingin membuat proyek baru.

  6. Centang Tempatkan solusi dan proyek di direktori yang sama dan pilih Buat.

    Cuplikan layar kotak dialog konfigurasi proyek.

    Visual Studio membuat satu proyek dan solusi. Anda dapat melihatnya di jendela Penjelajah Solusi. (Jika jendela Penjelajah Solusi tidak terlihat, pilih Penjelajah Solusi dari menu Tampilan.) Solusinya memiliki proyek driver bernama KmdfDriver. Untuk melihat kode sumber driver, buka salah satu file di bawah File Sumber. Driver.c dan Device.c adalah tempat yang baik untuk memulai.

    Cuplikan layar penjelajah solusi memperlihatkan file dalam proyek driver.

  7. Di jendela Penjelajah Solusi, pilih dan tahan (atau klik kanan) KmdfDriver, dan pilih Properti. Navigasi ke Pengaturan > Driver Properti > Konfigurasi Umum, dan perhatikan bahwa Platform Target default ke Universal.

  8. Untuk membangun driver Anda, pilih Build Solution dari menu Build . Microsoft Visual Studio menampilkan kemajuan build di jendela Output . (Jika jendela Output tidak terlihat, pilih Output dari menu Tampilan .)

    Verifikasi bahwa output build mencakup:

    >    Driver is 'Universal'.

    Setelah memverifikasi bahwa solusi berhasil dibangun, Anda dapat menutup Visual Studio.

  9. Untuk melihat driver bawaan, di File Explorer, buka folder KmdfDriver Anda, lalu ke x64\Debug\KmdfDriver. Direktori mencakup file berikut:

    • KmdfDriver.sys -- file driver mode kernel
    • KmdfDriver.inf -- file informasi yang digunakan Windows saat Anda menginstal driver

Menyebarkan driver

Biasanya ketika Anda menguji dan men-debug driver, debugger dan driver berjalan pada komputer terpisah. Komputer yang menjalankan debugger disebut komputer host, dan komputer yang menjalankan driver disebut komputer target. Komputer target juga disebut komputer uji. Untuk informasi selengkapnya tentang driver penelusuran kesalahan, lihat Alat Debugging untuk Windows.

Sejauh ini Anda telah menggunakan Visual Studio untuk membangun driver di komputer host. Sekarang Anda perlu mengonfigurasi komputer target.

  1. Ikuti instruksi di Menyediakan komputer untuk penyebaran dan pengujian driver (WDK 10).

    Tip

    Ketika Anda mengikuti langkah-langkah untuk memprovisikan komputer target secara otomatis menggunakan kabel jaringan, perhatikan port dan kunci. Anda akan menggunakannya nanti di langkah penelusuran kesalahan. Dalam contoh ini, kita akan menggunakan 50000 sebagai port dan 1.2.3.4 sebagai kunci.

    Dalam skenario penelusuran kesalahan driver nyata, sebaiknya gunakan kunci yang dihasilkan KDNET. Untuk informasi selengkapnya tentang cara menggunakan KDNET untuk menghasilkan kunci acak, lihat topik Driver Debug - Step by Step Lab (Mode Kernel Sysvad).

  2. Di komputer host, buka solusi Anda di Visual Studio. Anda bisa mengklik dua kali file solusi, KmdfDriver.sln, di folder KmdfDriver Anda.

  3. Di jendela Penjelajah Solusi, pilih dan tahan (atau klik kanan) proyek KmdfDriver, dan pilih Properti.

  4. Di jendela Halaman Properti Paket KmdfDriver, di panel kiri, buka Penyebaran Penginstalan > Driver Properti > Konfigurasi.

  5. Centang Hapus versi driver sebelumnya sebelum penyebaran.

  6. Untuk Nama Komputer Jarak Jauh, pilih nama komputer yang Anda konfigurasi untuk pengujian dan penelusuran kesalahan. Dalam latihan ini, kita menggunakan komputer bernama MyTestComputer.

  7. Pilih Pembaruan Driver ID Perangkat Keras, dan masukkan ID perangkat keras untuk driver Anda. Dalam latihan ini, ID perangkat keras adalah Root\KmdfDriver. PilihOK.

    cuplikan layar jendela halaman properti paket kmdfdriver, memperlihatkan penginstalan driver penyebaran dipilih

    Catatan

    Dalam latihan ini, ID perangkat keras tidak mengidentifikasi perangkat keras yang sebenarnya. Ini mengidentifikasi perangkat imajiner yang akan diberikan tempat di pohon perangkat sebagai anak dari simpul akar. Untuk perangkat keras nyata, jangan pilih Pembaruan Driver ID Perangkat Keras; sebagai gantinya, pilih Instal dan Verifikasi. Anda akan melihat ID perangkat keras dalam file informasi driver (INF) Anda. Di jendela Penjelajah Solusi, buka File Driver KmdfDriver > dan klik dua kali KmdfDriver.inf. ID perangkat keras terletak di bawah [Standard.NT$ARCH$].

    [Standard.NT$ARCH$]
%KmdfDriver.DeviceDesc%=KmdfDriver_Device, Root\KmdfDriver

  8. Pada menu Build , pilih Sebarkan Solusi. Visual Studio secara otomatis menyalin file yang diperlukan untuk menginstal dan menjalankan driver ke komputer target. Ini mungkin memakan waktu satu atau dua menit.

    Ketika Anda menyebarkan driver, file driver disalin ke folder %Systemdrive%\drivertest\drivers pada komputer uji. Jika terjadi kesalahan selama penyebaran, Anda dapat memeriksa untuk melihat apakah file disalin ke komputer pengujian. Verifikasi bahwa file .inf, .cat, test cert, dan .sys, dan file lain yang diperlukan, ada di folder %systemdrive%\drivertest\drivers.

    Untuk informasi selengkapnya tentang menyebarkan driver, lihat Menyebarkan Driver ke Komputer Uji.

Menginstal driver

Dengan driver KMDF yang disebarkan ke komputer target, sekarang Anda akan menginstal driver. Ketika sebelumnya Anda memprovisikan komputer target dengan Visual Studio menggunakan opsi otomatis , Visual Studio menyiapkan komputer target untuk menjalankan driver yang ditandatangani pengujian sebagai bagian dari proses provisi. Sekarang Anda hanya perlu menginstal driver menggunakan alat DevCon.

  1. Di komputer host, navigasikan ke folder Alat di penginstalan WDK Anda dan temukan alat DevCon. Misalnya, lihat di folder berikut:

    C:\Program Files (x86)\Windows Kits\10\Tools\x64\devcon.exe

    Salin alat DevCon ke komputer jarak jauh Anda.

  2. Pada komputer target, instal driver dengan menavigasi ke folder yang berisi file driver, lalu jalankan alat DevCon.

    1. Berikut adalah sintaks umum untuk alat devcon yang akan Anda gunakan untuk menginstal driver:

      devcon menginstal <ID perangkat keras file><INF>

      File INF yang diperlukan untuk menginstal driver ini adalah KmdfDriver.inf. File INF berisi ID perangkat keras untuk menginstal biner driver, KmdfDriver.sys. Ingat bahwa ID perangkat keras, yang terletak di file INF, adalah Root\KmdfDriver.

    2. Buka jendela Wantian Perintah sebagai Administrator. Navigasi ke folder paket driver Anda, lalu masukkan perintah ini:

      devcon install kmdfdriver.inf root\kmdfdriver

      Jika Anda mendapatkan pesan kesalahan tentang devcon yang tidak dikenali, coba tambahkan jalur ke alat devcon . Misalnya, jika Anda menyalinnya ke folder di komputer target yang disebut C:\Tools, coba gunakan perintah berikut:

      c:\tools\devcon install kmdfdriver.inf root\kmdfdriver

      Kotak dialog akan muncul yang menunjukkan bahwa driver uji adalah driver yang tidak ditandatangani. Pilih Tetap instal driver ini untuk melanjutkan.

      cuplikan layar peringatan penginstalan driver.

Men-debug driver

Setelah menginstal driver KMDF di komputer target, Anda akan melampirkan debugger dari jarak jauh dari komputer host.

  1. Di komputer host, buka jendela Wantian Perintah sebagai Administrator. Ubah ke direktori WinDbg.exe. Kami akan menggunakan x64version WinDbg.exe dari Windows Driver Kit (WDK) yang diinstal sebagai bagian dari penginstalan kit Windows. Berikut adalah jalur default ke WinDbg.exe:

    C:\Program Files (x86)\Windows Kits\10\Debuggers\x64

  2. Luncurkan WinDbg untuk menyambungkan ke sesi debug kernel pada komputer target dengan menggunakan perintah berikut. Nilai untuk port dan kunci harus sama dengan yang Anda gunakan untuk menyediakan komputer target. Kita akan menggunakan 50000 untuk port dan 1.2.3.4 untuk kunci, nilai yang kita gunakan selama langkah penyebaran. Bendera k menunjukkan bahwa ini adalah sesi debug kernel.

    WinDbg -k net:port=50000,key=1.2.3.4

  3. Pada menu Debug , pilih Putuskan. Debugger pada komputer host akan masuk ke komputer target. Di jendela Perintah Debugger , Anda dapat melihat perintah penelusuran kesalahan kernel: kd>.

  4. Pada titik ini, Anda dapat bereksperimen dengan debugger dengan memasukkan perintah di prompt kd> . Misalnya, Anda dapat mencoba perintah ini:

  5. Untuk membiarkan komputer target berjalan lagi, pilih Buka dari menu Debug atau tekan "g," lalu tekan "enter."

  6. Untuk menghentikan sesi penelusuran kesalahan, pilih Lepaskan Debuggee dari menu Debug .

    Penting

    Pastikan Anda menggunakan perintah "go" untuk membiarkan komputer target berjalan lagi sebelum keluar dari debugger, atau komputer target akan tetap tidak responsif terhadap input mouse dan keyboard Anda karena masih berbicara dengan debugger.

Untuk panduan langkah demi langkah terperinci dari proses penelusuran kesalahan driver, lihat Debug Driver Universal - Step by Step Lab (Echo Kernel-Mode).

Untuk informasi selengkapnya tentang penelusuran kesalahan jarak jauh, lihat Penelusuran Kesalahan Jarak Jauh Menggunakan WinDbg.

Menggunakan Driver Module Framework (DMF)

Driver Module Framework (DMF) adalah ekstensi untuk WDF yang memungkinkan fungsionalitas tambahan untuk pengembang driver WDF. Ini membantu pengembang menulis semua jenis driver WDF dengan lebih baik dan lebih cepat.

DMF sebagai kerangka kerja memungkinkan pembuatan objek WDF yang disebut Modul DMF. Kode untuk Modul DMF ini dapat dibagikan di antara driver yang berbeda. Selain itu, DMF menggabungkan pustaka Modul DMF yang telah kami kembangkan untuk driver kami dan merasa akan memberikan nilai bagi pengembang driver lainnya.

DMF tidak menggantikan WDF. DMF adalah kerangka kerja kedua yang digunakan dengan WDF. Pengembang yang memanfaatkan DMF masih menggunakan WDF dan semua primitifnya untuk menulis driver perangkat.

Untuk informasi selengkapnya, lihat Driver Module Framework (DMF).