Cara menulis driver klien USB pertama Anda (UMDF)

  • Artikel

Dalam artikel ini, Anda akan menggunakan templat Driver Mode Pengguna, USB (UMDF V2) yang disediakan dengan Microsoft Visual Studio 2022 untuk menulis driver driver framework berbasis mode pengguna (UMDF). Setelah membangun dan menginstal driver klien, Anda akan melihat driver klien di Device Manager dan melihat output driver dalam debugger.

UMDF (disebut sebagai kerangka kerja dalam artikel ini) didasarkan pada model objek komponen (COM). Setiap objek kerangka kerja harus mengimplementasikan IUnknown dan metodenya, QueryInterface, AddRef, dan Release, secara default. Metode AddRef dan Release mengelola masa pakai objek, sehingga driver klien tidak perlu mempertahankan jumlah referensi. Metode QueryInterface memungkinkan driver klien untuk mendapatkan penunjuk antarmuka ke objek kerangka kerja lain dalam model objek Windows Driver Frameworks (WDF). Objek kerangka kerja melakukan tugas driver yang rumit dan berinteraksi dengan Windows. Objek kerangka kerja tertentu mengekspos antarmuka yang memungkinkan driver klien berinteraksi dengan kerangka kerja.

Driver klien berbasis UMDF diimplementasikan sebagai server COM dalam proses (DLL), dan C++ adalah bahasa pilihan untuk menulis driver klien untuk perangkat USB. Biasanya, driver klien mengimplementasikan beberapa antarmuka yang diekspos oleh kerangka kerja. Artikel ini mengacu pada kelas yang ditentukan driver klien yang mengimplementasikan antarmuka kerangka kerja sebagai kelas panggilan balik. Setelah kelas-kelas ini dibuat, objek panggilan balik yang dihasilkan bermitra dengan objek kerangka kerja tertentu. Kemitraan ini memberi driver klien kesempatan untuk menanggapi peristiwa terkait perangkat atau sistem yang dilaporkan oleh kerangka kerja. Setiap kali Windows memberi tahu kerangka kerja tentang peristiwa tertentu, kerangka kerja memanggil panggilan balik driver klien, jika tersedia. Jika tidak, kerangka kerja dilanjutkan dengan pemrosesan default peristiwa. Kode templat menentukan kelas panggilan balik driver, perangkat, dan antrean.

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

Sebelum memulai

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

  • Komputer host yang menjalankan Windows 10 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 versi sistem operasi yang ingin Anda uji drivernya, misalnya, Windows 11, versi 22H2. Komputer target memiliki driver mode pengguna yang ingin Anda debug dan salah satu debugger.

Dalam beberapa kasus, di mana host dan komputer target menjalankan versi Windows yang sama, Anda hanya dapat memiliki satu komputer yang berjalan Windows 10 atau versi Windows yang lebih baru. Artikel ini mengasumsikan bahwa Anda menggunakan dua komputer untuk mengembangkan, men-debug, dan menginstal driver mode pengguna Anda.

Sebelum memulai, pastikan Anda memenuhi persyaratan berikut:

Persyaratan perangkat lunak

  • Komputer host Anda memiliki Visual Studio 2022.

  • Komputer host Anda memiliki Windows Driver Kit (WDK) terbaru untuk Windows 11, versi 22H2.

    Kit ini mencakup header, pustaka, alat, dokumentasi, dan alat penelusuran kesalahan yang diperlukan untuk mengembangkan, membangun, dan men-debug driver klien USB. Anda bisa mendapatkan WDK versi terbaru dari Cara Mendapatkan 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.

  • Jika Anda menggunakan dua komputer, Anda harus mengonfigurasi komputer host dan target untuk penelusuran kesalahan mode pengguna. Untuk informasi selengkapnya, lihat Menyiapkan User-Mode Debugging di Visual Studio.

Persyaratan perangkat keras

Dapatkan perangkat USB yang akan Anda tulis driver kliennya. Dalam kebanyakan kasus, Anda dilengkapi 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. Ini berisi perangkat USB FX2 dan semua spesifikasi perangkat keras yang diperlukan untuk mengimplementasikan driver klien.

Langkah 1: Hasilkan kode driver

Untuk detail tentang menulis kode driver UMDF, lihat Menulis driver UMDF berdasarkan templat.

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

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

Cuplikan layar berikut menunjukkan kotak dialog Proyek Baru untuk templat USB User-Mode Driver .

Cuplikan layar opsi proyek pembuatan Visual Studio.

Cuplikan layar konfigurasi proyek buat Visual Studio.

Artikel ini mengasumsikan bahwa nama proyek MyUSBDriver_UMDF_. Template ini berisi file-file berikut:

File Deskripsi
Driver.h; Driver.c Berisi implementasi titik masuk modul driver. Fungsionalitas dan panggilan balik terkait DriverEntry dan WDFDRIVER.
Device.h; Device.c Fungsionalitas dan panggilan balik terkait WDFDEVICE dan WDFUSBDEVICE.
Queue.h; Queue.c Fungsionalitas dan panggilan balik terkait WDFQUEUE.
Trace.h Menentukan GUID antarmuka perangkat. Ini juga menyatakan fungsi pelacakan dan makro.
<Nama proyek.inf> File INF yang diperlukan untuk menginstal driver klien pada komputer target.

Langkah 2: Menambahkan informasi tentang perangkat Anda

Sebelum membuat driver, Anda harus menambahkan informasi tentang perangkat Anda, khususnya ID perangkat keras. Untuk memberikan ID perangkat keras:

  1. Di jendela Penjelajah Solusi, klik kanan MyUSBDriver_UMDF_, dan pilih Properti.
  2. Di jendela Halaman Properti MyUSBDriver_UMDF_, buka Penyebaran Penginstalan > Driver Properti > Konfigurasi, seperti yang diperlihatkan di sini. Cuplikan layar jendela halaman properti Visual Studio 2022.
  3. Centang Hapus versi driver sebelumnya sebelum penyebaran.
  4. Untuk Nama Perangkat Target, pilih nama komputer yang Anda konfigurasi untuk pengujian dan penelusuran kesalahan.
  5. Pilih Pembaruan Driver ID Perangkat Keras, dan masukkan ID perangkat keras untuk driver Anda. Dalam latihan ini, ID perangkat keras adalah Root\MyUSBDriver_UMDF_. PilihOK.

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 dapat melihat ID perangkat keras dalam file informasi driver (INF). Di jendela Penjelajah Solusi, buka MyUSBDriver_UMDF_ > File Driver, dan klik dua kali MyUSBDriver_UMDF_.inf. ID perangkat keras berada di bawah [Standard.NT$ARCH$].

Semua driver klien USB berbasis UMDF memerlukan dua driver yang disediakan Microsoft, reflektor dan WinUSB.

  • Reflektor: Jika driver Anda berhasil dimuat, reflektor dimuat sebagai driver paling atas dalam tumpukan mode kernel. Reflektor harus menjadi driver teratas dalam tumpukan mode kernel. Untuk memenuhi persyaratan ini, file INF templat menentukan reflektor sebagai layanan dan WinUSB sebagai driver filter bawah di INF:

    [MyDevice_Install.NT.Services]
AddService=WUDFRd,0x000001fa,WUDFRD_ServiceInstall  ; flag 0x2 sets this as the service for the device
AddService=WinUsb,0x000001f8,WinUsb_ServiceInstall  ; this service is installed because its a filter.

  • WinUSB: Paket penginstalan harus berisi coinstallers untuk Winusb.sys karena untuk driver klien, WinUSB adalah gateway ke tumpukan driver USB mode kernel. Komponen lain yang dimuat adalah DLL mode pengguna, bernama WinUsb.dll, dalam proses host driver klien (Wudfhost.exe). Winusb.dll mengekspos Fungsi WinUSB yang menyederhanakan proses komunikasi antara driver klien dan WinUSB.

Langkah 3: Buat kode driver klien USB

Untuk membangun driver Anda:

  1. Buka proyek atau solusi driver di Visual Studio 2022.
  2. Klik kanan solusi di Penjelajah Solusi dan pilih Configuration Manager.
  3. Dari Configuration Manager, pilih Konfigurasi Solusi Aktif Anda (misalnya, Debug atau Rilis) dan Platform Solusi Aktif Anda (misalnya, x64) yang sesuai dengan jenis build yang Anda minati.
  4. Verifikasi bahwa GUID antarmuka perangkat Anda akurat di seluruh proyek.
    • GUID antarmuka perangkat didefinisikan dalam Trace.h dan dirujuk dari MyUSBDriverUMDFCreateDevice di Device.c. Saat Anda membuat proyek dengan nama MyUSBDriver_UMDF_, Visual Studio 2022 menentukan GUID antarmuka perangkat dengan nama GUID_DEVINTERFACE_MyUSBDriver_UMDF_ tetapi panggilan WdfDeviceCreateDeviceInterface dengan parameter &GUID_DEVINTERFACE_MyUSBDriverUMDFyang salah . Ganti parameter yang salah dengan nama yang ditentukan dalam Trace.h untuk memastikan bahwa driver dibangun dengan benar.
  5. 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 pada 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 Menyediakan komputer untuk penyebaran dan pengujian driver.

Langkah 5: Aktifkan pelacakan untuk penelusuran kesalahan kernel

Kode templat berisi beberapa pesan pelacakan (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> instalFolder Windows Kits\10\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.

    Ada tiga file di lokasi yang ditentukan, satu file kode per C dalam proyek. Mereka diberi nama file GUID.

  2. Di debugger, ketik perintah berikut:

    .load Wmitrace
.chain
!wmitrace.searchpath + <TMF file location>

Perintah-perintah ini:

  • Muat ekstensi Wmitrace.dll.
  • Memverifikasi bahwa ekstensi debugger dimuat.
  • Menambahkan 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 <folderinstall_folder Windows Kits\10\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 2022. 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, klik kanan nama proyek (MyUSBDriver_UMDF_), dan pilih Properti.
  2. Di panel kiri, navigasi ke Properti > Konfigurasi Penyebaran Penginstalan > Driver.
  3. Untuk Nama Perangkat Target, tentukan nama komputer target.
  4. Pilih Instal/Instal Ulang dan Verifikasi.
  5. Pilih Ok.
  6. 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).

Langkah 7: Lihat driver di Device Manager

  1. Masukkan perintah berikut untuk membuka Manajer Perangkat.

    devmgmt

  2. Verifikasi bahwa Manajer Perangkat menunjukkan simpul berikut.

    Perangkat USB

    MyUSBDriver_UMDF_Device

Langkah 8: Lihat output di debugger

Verifikasi bahwa pesan pelacakan muncul di Jendela Segera Debugger di komputer host.

Output harus sama dengan berikut ini.

[0]0744.05F0::00/00/0000-00:00:00.000 [MyUSBDriver_UMDF_]CMyDevice::OnPrepareHardware Entry
[0]0744.05F0::00/00/0000-00:00:00.000 [MyUSBDriver_UMDF_]CMyDevice::OnPrepareHardware Exit
[1]0744.05F0::00/00/0000-00:00:00.000 [MyUSBDriver_UMDF_]CMyDevice::CreateInstanceAndInitialize Entry
[1]0744.05F0::00/00/0000-00:00:00.000 [MyUSBDriver_UMDF_]CMyDevice::Initialize Entry
[1]0744.05F0::00/00/0000-00:00:00.000 [MyUSBDriver_UMDF_]CMyDevice::Initialize Exit
[1]0744.05F0::00/00/0000-00:00:00.000 [MyUSBDriver_UMDF_]CMyDevice::CreateInstanceAndInitialize Exit
[1]0744.05F0::00/00/0000-00:00:00.000 [MyUSBDriver_UMDF_]CMyDevice::Configure Entry
[1]0744.05F0::00/00/0000-00:00:00.000 [MyUSBDriver_UMDF_]CMyIoQueue::CreateInstanceAndInitialize Entry
[1]0744.05F0::00/00/0000-00:00:00.000 [MyUSBDriver_UMDF_]CMyIoQueue::Initialize Entry
[1]0744.05F0::00/00/0000-00:00:00.000 [MyUSBDriver_UMDF_]CMyIoQueue::Initialize Exit
[1]0744.05F0::00/00/0000-00:00:00.000 [MyUSBDriver_UMDF_]CMyIoQueue::CreateInstanceAndInitialize Exit
[1]0744.05F0::00/00/0000-00:00:00.000 [MyUSBDriver_UMDF_]CMyDevice::Configure Exit

Keterangan

Mari kita lihat bagaimana kerangka kerja dan driver klien bekerja sama untuk berinteraksi dengan Windows dan menangani permintaan yang dikirim ke perangkat USB. Ilustrasi ini menunjukkan modul yang dimuat dalam sistem untuk driver klien USB berbasis UMDF.

Diagram arsitektur driver klien mode pengguna.

Tujuan setiap modul dijelaskan di sini:

  • Aplikasi — proses mode pengguna yang mengeluarkan permintaan I/O untuk berkomunikasi dengan perangkat USB.
  • Manajer I/O — komponen Windows yang membuat paket permintaan I/O (IRP) untuk mewakili permintaan aplikasi yang diterima, dan meneruskannya ke bagian atas tumpukan perangkat mode kernel untuk perangkat target.
  • Reflector — driver mode kernel yang disediakan Microsoft yang diinstal di bagian atas tumpukan perangkat mode kernel (WUDFRd.sys). Reflektor mengalihkan IRP yang diterima dari manajer I/O ke proses host driver klien. Setelah menerima permintaan, kerangka kerja dan driver klien menangani permintaan.
  • Proses host — proses di mana driver mode pengguna berjalan (Wudfhost.exe). Ini juga menghosting kerangka kerja dan dispatcher I/O.
  • Driver klien — driver fungsi mode pengguna untuk perangkat USB.
  • UMDF — modul kerangka kerja yang menangani sebagian besar interaksi dengan Windows atas nama driver klien. Ini mengekspos antarmuka driver perangkat mode pengguna (DDI) yang dapat digunakan driver klien untuk melakukan tugas driver umum.
  • Dispatcher—mekanisme yang berjalan dalam proses host; menentukan cara meneruskan permintaan ke mode kernel setelah diproses oleh driver mode pengguna dan telah mencapai bagian bawah tumpukan mode pengguna. Dalam ilustrasi, dispatcher meneruskan permintaan ke DLL mode pengguna, Winusb.dll.
  • Winusb.dll — DLL mode pengguna yang disediakan Microsoft yang mengekspos Fungsi WinUSB yang menyederhanakan proses komunikasi antara driver klien dan WinUSB (Winusb.sys, dimuat dalam mode kernel).
  • Winusb.sys — driver yang disediakan Microsoft yang diperlukan oleh semua driver klien UMDF untuk perangkat USB. Driver harus dipasang di bawah reflektor dan bertindak sebagai gateway ke tumpukan driver USB dalam mode kernel. Untuk informasi selengkapnya, lihat WinUSB.
  • Tumpukan driver USB — satu set driver, yang disediakan oleh Microsoft, yang menangani komunikasi tingkat protokol dengan perangkat USB. Untuk informasi selengkapnya, lihat Driver sisi host USB di Windows.

Setiap kali aplikasi membuat permintaan untuk tumpukan driver USB, manajer I/O Windows mengirimkan permintaan ke reflektor, yang mengarahkannya ke driver klien dalam mode pengguna. Driver klien menangani permintaan dengan memanggil metode UMDF tertentu, yang secara internal memanggil Fungsi WinUSB untuk mengirim permintaan ke WinUSB. Setelah menerima permintaan, WinUSB memproses permintaan atau meneruskannya ke tumpukan driver USB.