Cara menulis driver klien USB pertama Anda (KMDF)

  • Artikel

Dalam artikel ini Anda akan menggunakan templat USB Kernel-Mode Driver yang disediakan dengan Microsoft Visual Studio untuk menulis driver driver framework mode kernel sederhana (KMDF) berbasis driver klien. Setelah membangun dan menginstal driver klien, Anda akan melihat driver klien di Device Manager dan melihat output driver dalam debugger.

Untuk penjelasan tentang kode sumber yang dihasilkan oleh templat, lihat Memahami kode templat KMDF untuk driver klien USB.

Prasyarat

Untuk mengembangkan, men-debug, dan menginstal driver mode kernel, Anda memerlukan dua komputer:

  • Komputer host yang menjalankan Windows 7 atau versi sistem operasi Windows yang lebih baru. Komputer host adalah lingkungan pengembangan Anda, tempat Anda menulis dan men-debug driver Anda.
  • Komputer target yang menjalankan Windows Vista atau versi Windows yang lebih baru. Komputer target memiliki driver mode kernel yang ingin Anda debug.

Sebelum memulai, pastikan Anda memenuhi persyaratan berikut:

Persyaratan perangkat lunak

  • Komputer host Anda menghosting lingkungan pengembangan Anda dan memiliki Visual Studio.
  • Komputer host Anda memiliki Windows Driver Kit (WDK) terbaru. Kit ini mencakup header, pustaka, alat, dokumentasi, dan alat penelusuran kesalahan yang diperlukan untuk mengembangkan, membangun, dan men-debug driver KMDF. Untuk mendapatkan WDK versi terbaru, lihat Mengunduh Windows Driver Kit (WDK).
  • Komputer host Anda memiliki versi terbaru alat penelusuran kesalahan untuk Windows. Anda bisa mendapatkan versi terbaru dari WDK atau Anda dapat Mengunduh dan Menginstal Alat Debugging untuk Windows.
  • Komputer target Anda menjalankan Windows Vista atau versi Windows yang lebih baru.
  • Komputer host dan target Anda dikonfigurasi untuk penelusuran kesalahan kernel. Untuk informasi selengkapnya, lihat Menyiapkan Koneksi Jaringan di Visual Studio.

Persyaratan perangkat keras

Dapatkan perangkat USB yang akan Anda tulis driver kliennya. Dalam kebanyakan kasus, Anda disediakan dengan perangkat USB dan spesifikasi perangkat kerasnya. Spesifikasi menjelaskan kemampuan perangkat dan perintah vendor yang didukung. Gunakan spesifikasi untuk menentukan fungsionalitas driver USB dan keputusan desain terkait.

Jika Anda baru menggunakan pengembangan driver USB, gunakan kit pembelajaran OSR USB FX2 untuk mempelajari sampel USB yang disertakan dengan WDK. Anda bisa mendapatkan kit pembelajaran dari OSR Online. Ini berisi perangkat USB FX2 dan semua spesifikasi perangkat keras yang diperlukan untuk mengimplementasikan driver klien.

Anda juga bisa mendapatkan perangkat Microsoft USB Test Tool (MUTT). Perangkat keras MUTT dapat dibeli dari Teknologi JJG. Perangkat belum menginstal firmware yang terinstal. Untuk menginstal firmware, unduh paket perangkat lunak MUTT dari situs Web ini dan jalankan MUTTUtil.exe. Untuk informasi selengkapnya, lihat dokumentasi yang disertakan dengan paket.

Langkah 1: Buat kode driver KMDF dengan menggunakan templat driver USB Visual Studio

Untuk instruksi tentang membuat kode driver KMDF, lihat langkah-langkah dalam Menulis driver KMDF berdasarkan templat.

Untuk kode khusus USB, pilih opsi berikut di Visual Studio:

  1. Dalam kotak dialog Proyek Baru , di kotak pencarian di bagian atas, ketik USB.
  2. Di panel tengah, pilih Driver Mode Kernel, USB (KMDF).
  3. Pilih Selanjutnya.
  4. Masukkan nama proyek, pilih lokasi penyimpanan, dan pilih Buat.

Cuplikan layar berikut ini memperlihatkan kotak dialog Proyek Baru untuk templat USB Kernel-Mode Driver .

opsi proyek baru visual studio.

opsi proyek baru visual studio layar kedua.

Artikel ini mengasumsikan bahwa nama proyek Visual Studio adalah "MyUSBDriver_". Template ini berisi file-file berikut:

File Deskripsi
Public.h Menyediakan deklarasi umum yang dibagikan oleh driver klien dan aplikasi pengguna yang berkomunikasi dengan perangkat USB.
<Nama proyek.inf> Berisi informasi yang diperlukan untuk menginstal driver klien pada komputer target.
Trace.h Menyatakan fungsi pelacakan dan makro.
Driver.h; Driver.c Mendeklarasikan dan mendefinisikan titik masuk driver dan rutinitas panggilan balik peristiwa.
Device.h; Device.c Mendeklarasikan dan mendefinisikan rutinitas panggilan balik peristiwa untuk peristiwa persiapan perangkat keras.
Queue.h; Queue.c Mendeklarasikan dan mendefinisikan rutinitas panggilan balik peristiwa untuk peristiwa yang dinaikkan oleh objek antrean kerangka kerja.

Langkah 2: Ubah file INF untuk menambahkan informasi tentang perangkat Anda

Sebelum membuat driver, Anda harus memodifikasi file INF templat dengan informasi tentang perangkat Anda, khususnya string ID perangkat keras.

Di Penjelajah Solusi, di bawah File Driver, klik dua kali file INF.

Dalam file INF, Anda dapat memberikan informasi seperti nama produsen dan penyedia, kelas penyiapan perangkat, dan sebagainya. Salah satu informasi yang harus Anda berikan adalah pengidentifikasi perangkat keras perangkat Anda.

Untuk menyediakan string ID perangkat keras:

  1. Pasang perangkat USB Anda ke komputer host Anda dan biarkan Windows menghitung perangkat.

  2. Buka Manajer Perangkat dan buka properti untuk perangkat Anda.

  3. Pada tab Detail , pilih Id Hardward di bawah Properti.

    ID perangkat keras untuk perangkat ditampilkan dalam kotak daftar. Pilih dan tahan (atau klik kanan) dan salin string ID perangkat keras.

  4. Ganti USB\VID_vvvv&PID_pppp di baris berikut dengan string ID perangkat keras Anda.

    [Standard.NT$ARCH$] %MyUSBDriver_.DeviceDesc%=MyUSBDriver__Device, USB\VID_vvvv&PID_pppp

Langkah 3: Membangun kode driver klien USB

Untuk membangun driver Anda:

  1. Buka proyek atau solusi driver di Visual Studio
  2. Pilih dan tahan (atau klik kanan) solusi di Penjelajah Solusi dan pilih Configuration Manager.
  3. Dari Configuration Manager, pilih Konfigurasi Solusi Aktif (misalnya, Debug atau Rilis) dan Platform Solusi Aktif (misalnya, Win32) yang sesuai dengan jenis build yang Anda minati.
  4. Dari menu Buat, pilih Buat Solusi.

Untuk informasi selengkapnya, lihat Membangun Driver.

Langkah 4: Mengonfigurasi komputer untuk pengujian dan penelusuran kesalahan

Untuk menguji dan men-debug driver, Anda menjalankan debugger pada komputer host dan driver di komputer target. Sejauh ini, Anda telah menggunakan Visual Studio di komputer host untuk membangun driver. Selanjutnya Anda perlu mengonfigurasi komputer target. Untuk mengonfigurasi komputer target, ikuti instruksi di Memprovisikan komputer untuk penyebaran dan pengujian driver.

Langkah 5: Aktifkan pelacakan untuk penelusuran kesalahan kernel

Kode templat berisi beberapa pesan jejak (TraceEvents) yang dapat membantu Anda melacak panggilan fungsi. Semua fungsi dalam kode sumber berisi pesan pelacakan yang menandai entri dan keluar dari rutinitas. Untuk kesalahan, pesan pelacakan berisi kode kesalahan dan string yang bermakna. Karena pelacakan WPP diaktifkan untuk proyek driver Anda, file simbol PDB yang dibuat selama proses build berisi petunjuk pemformatan pesan pelacakan. Jika Anda mengonfigurasi host dan komputer target untuk pelacakan WPP, driver Anda dapat mengirim pesan pelacakan ke file atau debugger.

Untuk mengonfigurasi komputer host Anda untuk pelacakan WPP:

  1. Buat file format pesan pelacakan (TMF) dengan mengekstrak petunjuk pemformatan pesan pelacakan dari file simbol PDB.

    Anda dapat menggunakan Tracepdb.exe untuk membuat file TMF. Alat ini terletak di <folder> penginstalanFolder Windows Kits\10.0\bin\<architecture> WDK. Perintah berikut membuat file TMF untuk proyek driver.

    tracepdb -f <PDBFiles> -p <TMFDirectory>

    Opsi -f menentukan lokasi dan nama file simbol PDB. Opsi -p menentukan lokasi untuk file TMF yang dibuat oleh Tracepdb. Untuk informasi selengkapnya, lihat Perintah Tracepdb.

    Di lokasi yang ditentukan, Anda akan melihat tiga file (satu per file .c dalam proyek). Mereka diberi nama file GUID.

  2. Di debugger, ketik perintah berikut:

    1. .load Wmitrace

      Memuat ekstensi Wmitrace.dll.

    2. .Jaringan

      Verifikasi bahwa ekstensi debugger dimuat.

    3. !wmitrace.searchpath +<lokasi> file TMF

      Tambahkan lokasi file TMF ke jalur pencarian ekstensi debugger.

      Outputnya menyerupai ini:

      Trace Format search path is: 'C:\Program Files (x86)\Microsoft Visual Studio 14.0\Common7\IDE;c:\drivers\tmf'

Untuk mengonfigurasi komputer target Anda untuk pelacakan WPP:

  1. Pastikan Anda memiliki alat Tracelog di komputer target Anda. Alat ini terletak di <folder install_folder>Windows Kits\8.0\Tools\<arch> WDK. Untuk informasi selengkapnya, lihat Sintaks Perintah Tracelog.

  2. Buka Jendela Perintah dan jalankan sebagai administrator.

  3. Ketik perintah berikut:

    tracelog -start MyTrace -guid #c918ee71-68c7-4140-8f7d-c907abbcb05d -flag 0xFFFF -level 7-rt -kd

    Perintah memulai sesi pelacakan bernama MyTrace.

    Argumen guid menentukan GUID penyedia pelacakan, yang merupakan driver klien. Anda bisa mendapatkan GUID dari Trace.h di proyek Visual Studio Professional 2019. Sebagai opsi lain, Anda dapat mengetik perintah berikut dan menentukan GUID dalam file .guid. File berisi GUID dalam format tanda hubung:

    tracelog -start MyTrace -guid c:\drivers\Provider.guid -flag 0xFFFF -level 7-rt -kd

    Anda dapat menghentikan sesi pelacakan dengan mengetik perintah berikut:

    tracelog -stop MyTrace

Langkah 6: Sebarkan driver pada komputer target

  1. Di jendela Penjelajah Solusi, pilih dan tahan (atau klik kanan) *<nama> proyek*Paket , dan pilih Properti.
  2. Di panel kiri, navigasi ke Properti > Konfigurasi Penyebaran Penginstalan > Driver.
  3. Centang Aktifkan penyebaran, dan centang Impor ke penyimpanan driver.
  4. Untuk Nama Komputer Jarak Jauh, tentukan nama komputer target.
  5. Pilih Instal dan Verifikasi.
  6. Pilih Ok.
  7. Pada menu Debug , pilih Mulai Penelusuran Kesalahan, atau tekan F5 pada keyboard.

Catatan

Jangan tentukan ID perangkat keras perangkat Anda di bawah Pembaruan Driver ID Perangkat Keras. ID piranti keras hanya boleh ditentukan dalam berkas informasi pengandar (INF).

Untuk informasi selengkapnya tentang menyebarkan driver ke sistem target di Visual Studio, lihat Menyebarkan Driver ke Komputer Uji.

Anda juga dapat menginstal driver secara manual pada komputer target dengan menggunakan Manajer Perangkat. Jika Anda ingin menginstal driver dari prompt perintah, utilitas ini tersedia:

  • PnPUtil

    Alat ini dilengkapi dengan Windows. Ini ada di Windows\System32. Anda dapat menggunakan utilitas ini untuk menambahkan driver ke penyimpanan driver.

    C:\>pnputil /a m:\MyDriver_.inf
Microsoft PnP Utility

Processing inf : MyDriver_.inf
Driver package added successfully.
Published name : oem22.inf

    Untuk informasi selengkapnya, lihat Contoh PnPUtil.

  • Pembaruan DevCon

    Alat ini dilengkapi dengan WDK. Anda dapat menggunakannya untuk menginstal dan memperbarui driver.

    devcon update c:\windows\inf\MyDriver_.inf USB\VID_0547&PID_1002\5&34B08D76&0&6

Langkah 7: Lihat driver di Device Manager

  1. Masukkan perintah berikut untuk membuka Manajer Perangkat:

    devmgmt

  2. Verifikasi bahwa Manajer Perangkat menampilkan simpul untuk simpul berikut:

    Sampel

    MyUSBDriver_Device

Langkah 8: Lihat output di debugger

Visual Studio pertama-tama menampilkan kemajuan di jendela Output . Kemudian membuka Jendela Langsung Debugger. Verifikasi bahwa pesan pelacakan muncul di debugger di komputer host. Output akan terlihat seperti ini, di mana "MyUSBDriver_" adalah nama modul driver:

[3]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]MyUSBDriver_EvtDriverContextCleanup Entry
[1]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]MyUSBDriver_EvtDriverDeviceAdd Entry
[1]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]MyUSBDriver_EvtDriverDeviceAdd Exit
[0]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]DriverEntry Entry
[0]0004.0054::00/00/0000-00:00:00.000 [MyUSBDriver_]DriverEntry Exit