Dari Kode Sampel ke Driver Produksi - Apa yang Harus Diubah dalam Sampel

Artikel
06/15/2023

Topik ini menjelaskan perubahan penting yang perlu dilakukan pada driver sampel WDK sebelum merilis driver perangkat berdasarkan kode sampel.

Selain perubahan yang dijelaskan di sini, semua driver harus menggunakan praktik terbaik yang dijelaskan dalam Membuat Driver reliable Kernel-Mode dan dalam Praktik Terbaik Pengembangan Driver Tim Surface. Semua pengemudi juga harus mematuhi pedoman yang disediakan dalam Panduan Keamanan Pengemudi.

Sampel Driver WDK - Pengidentifikasi Unik

Windows Driver Kit (WDK) berisi berbagai driver sampel yang menunjukkan teknik yang berguna untuk pengembangan driver. Anda dapat menggunakan sampel ini sebagai dasar untuk driver Anda sendiri, tetapi sebelum merilis driver, Anda harus mengubah aspek spesifik perangkat tertentu dari sampel - di luar kode operasional yang jelas - untuk diterapkan secara unik ke perangkat dan driver Anda sendiri. Penulis driver terkadang mengabaikan detail ini.

Item yang tepat yang harus Anda ubah bervariasi dari satu sampel ke sampel berikutnya, tetapi secara umum, item tersebut mengidentifikasi perangkat, antarmuka, atau driver tertentu. Misalnya, jika driver sampel berisi salah satu item berikut, Anda harus mengubahnya untuk diterapkan ke driver dan perangkat Anda:

Pengidentifikasi unik global (GUID)
Nama tautan simbolis
Nama objek perangkat
Tag kumpulan
Definisi kode kontrol I/O (IOCTL)
Nama file apa pun yang disalin ke folder sistem
Plug and Play ID perangkat, ID perangkat keras, dan ID yang kompatibel
Nama layanan driver
Deskripsi perangkat
File sumber daya

Lupa membuat perubahan ini dapat mengakibatkan penginstalan yang gagal, konflik dengan perangkat dan driver lain pada sistem, dan kesulitan dalam penelusuran kesalahan, bersama dengan kesalahan lainnya.

Misalnya jika Anda menerima kesalahan seperti ...\toastDrv\kmdf\toastmon\wdftoastmon.inx(18-18): error 1284: Class "Sample" is reserved for use by Microsoft. ini menunjukkan bahwa nama "Sampel" harus diubah menjadi nama unik untuk driver sampel Anda.

GUID

Driver menggunakan GUID untuk mengidentifikasi kelas penyiapan perangkat, kelas antarmuka perangkat, peristiwa PnP kustom, peristiwa Windows Management Instrumentation (WMI) kustom, dan penyedia pelacakan Windows PreProcessor (WPP). Beberapa GUID didefinisikan oleh Microsoft, dan yang lainnya didefinisikan oleh vendor perangkat dan driver.

GUID kelas penyiapan perangkat, GUID kelas antarmuka perangkat, dan GUID WMI untuk perangkat umum dan data WMI didefinisikan dalam WDK atau dalam file header publik untuk digunakan oleh driver apa pun. Anda tidak boleh mengubah GUID ini.

Misalnya, jika Anda menerapkan mouse, Anda akan terus menggunakan GUID_DEVINTERFACE_MOUSE, yang didefinisikan dalam file header WDK Ntddmou.h, sebagai kelas antarmuka perangkat. Namun, jika Anda menentukan kelas penyiapan perangkat baru, Anda harus membuat GUID kelas penyiapan perangkat baru dan menyiapkan nama kelas, dan mungkin GUID kelas antarmuka perangkat baru juga. GUID kelas penyiapan dan GUID kelas antarmuka perangkat harus berupa nilai unik; mereka tidak dapat berbagi GUID.

Untuk sebagian besar driver berbasis sampel, Anda hanya boleh mengubah GUID yang ditentukan dalam header lokal sampel atau file sumber dan dengan demikian khusus untuk sampel. GUID tersebut mungkin mencakup hal-hal berikut:

Peristiwa PnP kustom
Peristiwa WMI kustom
Kelas antarmuka perangkat untuk perangkat baru atau kustom
Penyedia pelacakan WPP

Menggunakan GUID yang telah ditentukan untuk driver lain dapat menyebabkan konflik jika kedua driver dimuat pada sistem yang sama. Misalnya, jika dua driver yang berbeda menggunakan GUID yang sama untuk mendaftarkan antarmuka perangkat, klien yang mencoba membuka antarmuka perangkat mungkin secara tidak sengaja membuka perangkat yang salah.

Kutipan berikut berasal dari file Driver.h yang disertakan dalam semua sampel driver Toaster. Ini mendefinisikan GUID antarmuka perangkat untuk perangkat Toaster:

DEFINE_GUID(GUID_TOASTER_INTERFACE_STANDARD, \
            0xe0b27630, 0x5434, 0x11d3, 0xb8, 0x90, 0x0, 0xc0, \
            0x4f, 0xad, 0x51, 0x71);
// {E0B27630-5434-11d3-B890-00C04FAD5171}

Jika Anda menggunakan file ini di driver Anda sendiri, pastikan Anda mengganti contoh GUID (ditunjukkan di atas sebagai teks tebal) dengan GUID antarmuka untuk perangkat Anda sendiri. Untuk membuat GUID, gunakan alat Buat GUID di Microsoft Visual Studio atau Guidgen.exe, yang keduanya disertakan dalam Microsoft Windows Software Development Kit (SDK). Anda kemudian dapat mengaitkan GUID dengan konstanta simbolis dalam file header driver, seperti yang ditunjukkan contoh.

Anda mungkin juga diharuskan untuk membuat GUID baru untuk peristiwa WMI driver. Sampel driver Toaster menentukan GUID berikut untuk pemberitahuan kedatangan perangkat pemangsa:


DEFINE_GUID (TOASTER_NOTIFY_DEVICE_ARRIVAL_EVENT, \
             0x1cdaff1, 0xc901, 0x45b4, 0xb3, 0x59, 0xb5, 0x54, \
             0x27, 0x25, 0xe2, 0x9c);
// {01CDAFF1-C901-45b4-B359-B5542725E29C}

Anda harus membuat GUID baru untuk setiap peristiwa WMI di driver Anda.

Jika driver sampel menggunakan pelacakan perangkat lunak WPP, buat GUID penyedia pelacakan baru untuk driver apa pun yang Anda dasarkan pada sampel. Misalnya, file header Trace.h sampel Osrusbfx2 di %WinDDK%\Src\Kmdf\Osrusbfx2\Final mendefinisikan GUID kontrol sebagai berikut:

#define WPP_CONTROL_GUIDS \
    WPP_DEFINE_CONTROL_GUID( \
           OsrUsbFxTraceGuid,(d23a0c5a,d307,4f0e,ae8e,E2A355AD5DAB), \
        WPP_DEFINE_BIT(DBG_INIT)          /* bit  0 = 0x00000001 */ \
        WPP_DEFINE_BIT(DBG_PNP)           /* bit  1 = 0x00000002 */ \
        WPP_DEFINE_BIT(DBG_POWER)         /* bit  2 = 0x00000004 */ \
        WPP_DEFINE_BIT(DBG_WMI)           /* bit  3 = 0x00000008 */ \
        WPP_DEFINE_BIT(DBG_CREATE_CLOSE)  /* bit  4 = 0x00000010 */ \
        WPP_DEFINE_BIT(DBG_IOCTL)         /* bit  5 = 0x00000020 */ \
        WPP_DEFINE_BIT(DBG_WRITE)         /* bit  6 = 0x00000040 */ \
        WPP_DEFINE_BIT(DBG_READ)          /* bit  7 = 0x00000080 */ \
       )

Di driver Anda sendiri, Anda akan mengganti teks yang di-boldfaced dengan nama khusus driver dan GUID yang Anda buat.

Nama Tautan Simbolis

Jika sampel menentukan nama tautan simbolis, ganti nama dalam sampel dengan nama yang berlaku untuk driver Anda sendiri. Namun, jangan ubah nama tautan terkenal seperti \DosDevices\COM1. Secara umum, jika nama tautan sangat mirip dengan nama sampel (seperti \DosDevices\CancelSamp)Anda harus mengubahnya.

Menggunakan tautan simbolis yang sama dengan driver lain memiliki efek yang sama seperti menggunakan GUID antarmuka perangkat yang salah, karena antarmuka perangkat pada dasarnya adalah tautan simbolis.

Driver KmDF Toaster Filter di %WinDDK\Src\Kmdf\Toaster\Filter membuat nama tautan simbolis yang menggunakan string yang didefinisikan sebagai berikut dalam file header Filter.h:

#define SYMBOLIC_NAME_STRING     L"\\DosDevices\\ToasterFilter"

Ubah string yang dicetak tebal menjadi lebih akurat menggambarkan driver Anda sendiri.

Nama Objek Perangkat

Jika sampel membuat nama untuk objek perangkat, Anda harus mengubah nama saat menyesuaikan kode sampel.

Driver KmDF Toaster Filter menamai objek perangkatnya dalam file header Filter.h sebagai berikut:

#define NTDEVICE_NAME_STRING      L\\Device\\ToasterFilter

Seperti nama tautan simbolis, Anda harus mengubah string untuk menggambarkan driver Anda.

Ingat bahwa objek perangkat bernama dapat mewakili risiko keamanan. Objek perangkat fisik (PDO) harus memiliki nama, dan sebagian besar nama tersebut adalah sistem yang dihasilkan alih-alih ditetapkan secara eksplisit oleh driver. Objek perangkat lain harus diberi nama hanya jika mewakili objek perangkat kontrol, yang digunakan untuk komunikasi sideband antara aplikasi dan driver. Kerangka kerja driver mode kernel (KMDF) dan Windows Driver Model (WDM) memungkinkan Anda membiarkan Windows menghasilkan nama. Pendekatan ini memastikan bahwa nama objek perangkat unik dan pengguna yang tidak istimewa tidak dapat mengaksesnya. Untuk detailnya, lihat Mengontrol Akses Namespace Perangkat dan Mengontrol Akses Perangkat di Driver KMDF.

Tag Kumpulan

Tag kumpulan adalah harfiah satu hingga empat karakter yang mengidentifikasi alokasi memori tertentu dan dapat membantu dalam penelusuran kesalahan.

Banyak driver sampel menentukan tag kumpulan dalam file header driver, seperti pada baris berikut dari Toaster.h:

#define TOASTER_POOL_TAG (ULONG) 'saoT'

Driver menentukan tag mundur karena debugger menampilkannya dalam urutan terbalik. Dengan demikian, tag ini muncul sebagai Toas dalam output debugger. Alih-alih menggunakan tag yang ditentukan sampel, ubah string untuk mengidentifikasi kode Anda sendiri secara unik.

File Pooltag.txt mencantumkan tag kumpulan yang digunakan oleh komponen dan driver mode kernel yang disediakan dengan Windows. Pooltag.txt diinstal dengan WDK di %winddk%\Tools\Other<i>platform\Poolmon, dengan platform amd64, i386, atau ia64. Jangan gunakan tag apa pun yang muncul dalam daftar ini.

Definisi IOCTL

Ubah kode kontrol I/O yang ditentukan sampel untuk menggunakan nama, jenis perangkat, kode fungsi, jenis transfer, dan jenis akses yang sesuai untuk perangkat dan driver Anda.

Misalnya, sampel Osrusbfx2 menyertakan definisi berikut untuk IOCTL_OSRUSBFX2_READ_SWITCHES:

#define IOCTL_OSRUSBFX2_READ_SWITCHES   
                    CTL_CODE(FILE_DEVICE_OSRUSBFX2, \
                             IOCTL_INDEX + 6, \
                             METHOD_BUFFERED, \
                             FILE_READ_ACCESS)

Driver berbasis sampel untuk perangkat yang berbeda akan memerlukan modifikasi pada definisi ini.

Nama File

Di INF atau INX, ubah nama driver, penginstal bersama yang disediakan vendor, dan file lain yang disalin prosedur penginstalan ke folder sistem. Nama file ini biasanya muncul di bagian [SourceDisksFiles] dan [ClassInstall32] dari INF dan dalam entri CopyFiles .

Contoh berikut berasal dari file INX untuk sampel PemanggiH Unggulan KMDF, yang tersedia di %WinDDK%\src\kmdf\Toaster\Func\Featured. Nama file yang harus diubah ditampilkan dalam huruf tebal:

[ClassInstall32]
Addreg=ToasterClassReg
CopyFiles=ToasterClassInstallerCopyFileshighlight

[ToasterClassReg]
...
HKR,,Installer32,,"tostrcls.dll,ToasterClassInstaller"
...

[ToasterClassInstallerCopyFiles]
tostrcls.dll									    
...

Untuk menyesuaikan bagian file ini untuk driver yang berbeda, Anda akan mengubah "tostrcls.dll" ke nama file alat penginstal kelas Anda dan mengubah string "ToasterClassInstaller" untuk menjelaskan alat penginstal Anda sendiri. Perubahan ini memastikan bahwa prosedur penginstalan menyalin file penginstal bersama yang benar dan bahwa kunci registri merekam nama file yang benar.

Jangan mengubah nama penginstal bersama yang disediakan di WDK atau dengan Windows, seperti penginstal bersama KMDF, UMDF, dan WinUSB.

Perubahan tambahan diperlukan nanti di bagian Penginstalan Perangkat file, seperti yang ditunjukkan dalam contoh ini:

[Toaster_Device.NT]
CopyFiles=Toaster_Device.NT.Copy

[Toaster_Device.NT.Copy]
wdffeatured.sys

Dalam contoh ini, Anda akan mengubah nama file yang dicetak tebal menjadi nama file driver yang Anda buat.

Ketika Penyiapan menyalin file katalog INF dan driver, itu mengganti namanya, sehingga Anda tidak diharuskan untuk mengubah nama mereka dalam paket driver Anda. Namun, umumnya merupakan ide yang baik untuk memastikan bahwa nama file INF dan katalog mirip dengan nama file driver.

ID Perangkat PnP, ID Perangkat Keras, dan ID yang Kompatibel

Penyiapan menggunakan ID perangkat bersama dengan ID perangkat keras dan ID yang kompatibel untuk memilih INF yang akan digunakan untuk penginstalan perangkat.

ID perangkat adalah string yang ditentukan vendor yang secara unik mengidentifikasi perangkat tertentu. Setiap perangkat memiliki tepat satu ID perangkat. Driver bus melaporkan ID perangkat selama enumerasi, dan Penyiapan menggunakannya untuk mencocokkan perangkat dengan file INF yang benar. ID perangkat didefinisikan di bagian [Produsen] dari INF.

Contoh berikut menunjukkan ID perangkat untuk perangkat OSR USB Fx2, seperti yang ditentukan dalam file Osrusbfx2.inx:

[Manufacturer]
%MfgName%=Microsoft,NT$ARCH$

; For Win2K
[Microsoft]
%USB\VID_045E&PID_930A.DeviceDesc%=osrusbfx2.Dev, 
        USB\VID_0547&PID_1002
...

; For XP and later
[Microsoft.NT$ARCH$]
%USB\VID_045E&PID_930A.DeviceDesc%=osrusbfx2.Dev, 
        USB\VID_0547&PID_1002

Untuk menyesuaikan direktif INF ini untuk driver Anda sendiri, ganti ID perangkat yang ditampilkan dalam huruf tebal dengan ID perangkat untuk perangkat Anda sendiri. Anda juga harus mengubah nama produsen menjadi nama perusahaan Anda.

ID perangkat keras dan ID yang kompatibel adalah ID yang kurang spesifik yang digunakan Penyetelan jika tidak dapat mencocokkan ID perangkat dengan INF. Jika INF Anda dapat mendukung perangkat lain, Anda harus mengubah nilai-nilai ini selain ID perangkat. Contoh berikut dari driver Pemanggang Toaster Unggulan KMDF menunjukkan ID perangkat keras:


[Manufacturer]
%StdMfg%=Standard,NT$ARCH$

; For Win2K
[Standard]
; DisplayName                   Section           DeviceId
; -----------                   -------           --------
%ToasterDevice.DeviceDesc%=Toaster_Device, 
         {b85b7c50-6a01-11d2-b841-00c04fad5171}\MsToaster

; For XP and later
[Standard.NT$ARCH$]
%ToasterDevice.DeviceDesc%=Toaster_Device, 
         {b85b7c50-6a01-11d2-b841-00c04fad5171}\MsToaster

Untuk menyesuaikan arahan INF ini untuk driver Anda sendiri, ganti ID perangkat keras dengan ID perangkat driver Anda dan ubah "MsToaster" ke string yang lebih deskriptif.

Nama Layanan Driver

Perbarui nama layanan dalam direktif AddService di INF ke nilai yang sesuai untuk driver Anda. Jika nama layanan driver bertentangan dengan driver lain pada sistem, driver tidak akan menginstal atau memuat.

Driver KmDF Featured Toaster menamai layanannya sebagai berikut:


[Toaster_Device.NT.Services]
AddService = wdffeatured, %SPSVCINST_ASSOCSERVICE%,
     wdffeatured_Service_Inst

Nama layanan adalah entri pertama dalam direktif AddService . Untuk mengadaptasi INF Toaster Unggulan, Anda akan mengubah string tebal menjadi string yang lebih cocok untuk driver Anda. Dalam contoh, entri wdffeatured_Service_Inst hanya mereferensikan bagian yang ditentukan INF, sehingga mengubahnya tidak penting.

Deskripsi Perangkat

Deskripsi perangkat terdiri dari beberapa string yang biasanya didefinisikan di bagian [String] INF dan digunakan di berbagai tempat di seluruh INF. Misalnya, sampel KmDF Featured Toaster menentukan string berikut dalam file WdfFeatured.inx:

[Strings]
SPSVCINST_ASSOCSERVICE   = 0x00000002
MSFT                     = "Microsoft"
StdMfg                   = "(Standard system devices)"
ClassName                = "Toaster"
DiskId1                  = "Toaster Device Installation Disk #1"
ToasterDevice.DeviceDesc = "Microsoft WDF Featured Toaster"
Toaster.SVCDESC          = "Microsoft WDF Toaster Featured Device Driver"

Untuk memodifikasi file ini untuk menginstal driver Anda sendiri, Anda harus mengubah string tebal untuk mencerminkan informasi tentang perusahaan, perangkat, dan driver Anda.

Jika nama perusahaan juga muncul di bagian [Produsen] di INF, Anda juga harus mengubah nama di sana.

File Sumber Daya

Driver dan komponen lain seperti rekan penginstal khusus sampel juga memiliki file sumber daya (.rc), yang menentukan string khusus driver, termasuk nama produk, versi file, dan nama perusahaan. Ubah string ini menjadi nilai yang sesuai untuk paket driver Anda.

Ringkasan - Apa yang harus Anda lakukan?

Sebelum Anda merilis driver yang didasarkan pada sampel WDK, ganti informasi khusus sampel apa pun dalam file sumber, INF, dan sumber daya lain yang Anda gunakan untuk membuat driver Anda sendiri. Perubahan yang diperlukan bervariasi dari satu sampel ke sampel lainnya, tetapi umumnya menyertakan informasi apa pun yang secara unik mengidentifikasi driver sampel atau perangkatnya. Berikut ini adalah tipikal perubahan yang harus Anda buat:

Buat dan gunakan GUID yang khusus untuk driver Anda jika sesuai.
Perbarui nama tautan simbolis.
Perbarui nama objek perangkat atau gunakan nama yang dibuat secara otomatis.
Gunakan tag kumpulan yang mengidentifikasi driver Anda dan tidak berkonflik dengan tag yang diketahui.
Tentukan kode IOCTL yang sesuai untuk driver dan perangkat Anda.
Perbarui nama file apa pun yang disalin ke folder sistem.
Masukkan ID perangkat Plug and Play yang benar, ID perangkat keras, dan ID yang kompatibel di INF.
Perbarui nama layanan driver di INF.
Ubah deskripsi perangkat.
Ubah string khusus driver apa pun dalam file sumber daya.
Mematuhi praktik terbaik untuk keamanan dan keandalan