Contoh Paket Driver DCH-Compliant

Artikel
06/08/2023

Artikel ini menjelaskan bagaimana sampel driver DCHU menerapkan prinsip desain DCH. Anda dapat menggunakannya sebagai model untuk menerapkan prinsip desain DCH ke paket driver Anda sendiri.

Jika Anda ingin salinan lokal repositori sampel, kloning dari Windows-driver-samples.

Beberapa bagian sampel dapat menggunakan direktif dan API yang hanya tersedia pada versi Windows 10 dan di atasnya. Lihat Penginstalan Perangkat dan Driver untuk melihat versi OS apa yang didukung oleh direktif tertentu.

Prasyarat

Sebelum Anda membaca bagian ini, Anda harus terbiasa dengan Prinsip Desain DCH.

Gambaran Umum

Sampel ini menyediakan contoh skenario di mana dua mitra perangkat keras, Contoso (pembuat sistem, atau OEM) dan Fabrikam (produsen perangkat, atau IHV) bekerja sama untuk membuat driver yang sesuai dengan DCH untuk perangkat di sistem Contoso yang akan datang. Perangkat yang dimaksud adalah kit pembelajaran OSR USB FX2. Di masa lalu, Fabrikam akan menulis paket driver warisan yang disesuaikan dengan lini produk Contoso tertentu, dan kemudian menyerahkannya ke OEM untuk menangani layanan. Ini menghasilkan overhead pemeliharaan yang signifikan, sehingga Fabrikam memutuskan untuk merefaktor kode dan membuat paket driver yang mematuhi DCH sebagai gantinya.

Gunakan bagian/arahan deklaratif dan isolasi INF dengan benar

Pertama, Fabrikam meninjau daftar bagian dan arahan INF yang tidak valid dalam paket driver yang mematuhi DCH. Selama latihan ini, Fabrikam memperhatikan bahwa mereka menggunakan banyak bagian dan arahan ini dalam paket driver mereka.

DRIVER INF mereka mendaftarkan penginstal bersama yang menerapkan pengaturan dan file yang bergantung pada platform. Ini berarti bahwa paket driver lebih besar dari yang seharusnya, dan lebih sulit untuk melayani driver ketika bug hanya memengaruhi subset sistem OEM yang mengirim driver. Selain itu, sebagian besar modifikasi khusus OEM terkait dengan branding, sehingga Fabrikam perlu memperbarui paket driver setiap kali OEM ditambahkan atau ketika masalah kecil memengaruhi subset sistem OEM.

Fabrikam menghapus bagian dan arahan non-deklaratif dan menggunakan alat InfVerif untuk memverifikasi bahwa file INF paket driver baru mengikuti persyaratan INF deklaratif.

Menggunakan INF ekstensi untuk menginisialisasi paket driver

Selanjutnya, Fabrikam memisahkan kustomisasi yang khusus untuk mitra OEM (seperti Contoso) dari paket driver dasar menjadi INF ekstensi.

Cuplikan berikut, yang diperbarui dari [osrfx2_DCHU_extension.inx], menentukan Extension kelas dan mengidentifikasi Contoso sebagai penyedia karena mereka akan memiliki paket driver ekstensi:

[Version]
...
Class       = Extension
ClassGuid   = {e2f84ce7-8efa-411c-aa69-97454ca4cb57}
Provider    = Contoso
ExtensionId = {zzzzzzzz-zzzz-zzzz-zzzz-zzzzzzzzzzzz} ; replace with your own GUID
...

Dalam [osrfx2_DCHU_base.inx], Fabrikam menentukan entri berikut:

[OsrFx2_AddReg]
HKR, OSR, "OperatingMode",, "Default" ; FLG_ADDREG_TYPE_SZ
HKR, OSR, "OperatingParams",, "None" ; FLG_ADDREG_TYPE_SZ

Di [osrfx2_DCHU_extension.inx], Contoso mengambil alih nilai registri OperatingParams yang ditetapkan oleh basis dan menambahkan OperatingExceptions:

[OsrFx2Extension_AddReg]
HKR, OSR, "OperatingParams",, "-Extended"
HKR, OSR, "OperatingExceptions",, "x86"

Ekstensi selalu diproses setelah INF dasar tetapi tidak dalam urutan yang pasti. Jika INF dasar diperbarui ke versi yang lebih baru, ekstensi masih akan diterapkan kembali setelah INF dasar baru diinstal.

Menginstal layanan dari file INF

Fabrikam menggunakan layanan Win32 untuk mengontrol LED pada papan OSR. Mereka melihat komponen ini sebagai bagian dari fungsionalitas inti perangkat, sehingga mereka menyertakannya sebagai bagian dari INF dasar mereka ([osrfx2_DCHU_base.inx]). Layanan mode pengguna (usersvc) ini dapat ditambahkan dan dimulai secara deklaratif dengan menentukan arahan AddService dalam file INF:

[OsrFx2_Install.NT]
CopyFiles = OsrFx2_CopyFiles

[OsrFx2_Install.NT.Services]
AddService = WUDFRd, 0x000001fa, WUDFRD_ServiceInstall    ; Flag 0x2 sets this as the service for the device
AddService = osrfx2_DCHU_usersvc,, UserSvc_ServiceInstall

[UserSvc_ServiceInstall]
DisplayName = %UserSvcDisplayName%
ServiceType = 0x10                                ; SERVICE_WIN32_OWN_PROCESS
StartType = 0x3                                   ; SERVICE_DEMAND_START
ErrorControl = 0x1                                ; SERVICE_ERROR_NORMAL
ServiceBinary = %13%\osrfx2_DCHU_usersvc.exe
AddTrigger = UserSvc_AddTrigger                   ; AddTrigger syntax is only available in Windows 10 Version 2004 and above

[UserSvc_AddTrigger]
TriggerType = 1                                   ; SERVICE_TRIGGER_TYPE_DEVICE_INTERFACE_ARRIVAL
Action = 1                                        ; SERVICE_TRIGGER_ACTION_SERVICE_START
SubType = %GUID_DEVINTERFACE_OSRFX2%              ; Interface GUID
DataItem = 2, "USB\VID_0547&PID_1002"             ; SERVICE_TRIGGER_DATA_TYPE_STRING

[OsrFx2_CopyFiles]
osrfx2_DCHU_base.dll
osrfx2_DCHU_filter.dll
osrfx2_DCHU_usersvc.exe

Layanan semacam itu juga dapat diinstal dalam INF komponen atau ekstensi, tergantung pada skenarionya.

Menggunakan komponen untuk menginstal perangkat lunak warisan dari paket driver

Fabrikam memiliki file osrfx2_DCHU_componentsoftware.exe yang dapat dieksekusi yang sebelumnya diinstal menggunakan penginstal bersama. Perangkat lunak warisan ini menampilkan kunci registri yang ditetapkan oleh papan dan diperlukan oleh OEM. Ini adalah executable berbasis GUI yang hanya berjalan pada Windows untuk edisi desktop. Untuk menginstalnya, Fabrikam membuat paket driver komponen terpisah dan menambahkannya di INF ekstensi mereka.

Cuplikan berikut dari [osrfx2_DCHU_extension.inx] menggunakan direktif AddComponent untuk membuat perangkat anak virtual:

[OsrFx2Extension_Install.NT.Components]
AddComponent = osrfx2_DCHU_component,,OsrFx2Extension_ComponentInstall


[OsrFx2Extension_ComponentInstall]
ComponentIds=VID_045e&PID_94ab

Kemudian, dalam komponen INF [osrfx2_DCHU_component.inx], Fabrikam menentukan direktif AddSoftware untuk menginstal executable opsional:

[OsrFx2Component_Install.NT.Software]
AddSoftware = osrfx2_DCHU_componentsoftware,, OsrFx2Component_SoftwareInstall

[OsrFx2Component_SoftwareInstall]
SoftwareType = 1
SoftwareBinary = osrfx2_DCHU_componentsoftware.exe
SoftwareArguments = <<DeviceInstanceId>>
SoftwareVersion = 1.0.0.0

[OsrFx2Component_CopyFiles]
osrfx2_DCHU_componentsoftware.exe

Kode sumber untuk aplikasi Win32 disertakan dalam sampel.

Paket driver komponen hanya didistribusikan pada SKU Desktop karena penargetan yang ditetapkan di dasbor Windows Hardware Dev Center. Untuk informasi selengkapnya, lihat Menerbitkan driver ke Windows Update.

Mengizinkan komunikasi dengan aplikasi dukungan perangkat keras

Fabrikam ingin menyediakan aplikasi pendamping berbasis GUI sebagai bagian dari paket Driver Windows. Karena aplikasi pendamping berbasis Win32 tidak dapat menjadi bagian dari paket Driver Windows, mereka memindahkan aplikasi Win32 mereka ke Platform Windows Universal (UWP) dan memasangkan aplikasi dengan perangkat.

Cuplikan berikut dari osrfx2_DCHU_base/device.c menunjukkan bagaimana paket driver dasar menambahkan kemampuan kustom ke instans antarmuka perangkat:

    WDF_DEVICE_INTERFACE_PROPERTY_DATA PropertyData = { 0 };
    static const wchar_t customCapabilities[] = L"CompanyName.yourCustomCapabilityName_YourStorePubId\0";

    WDF_DEVICE_INTERFACE_PROPERTY_DATA_INIT(&PropertyData,
                                            &GUID_DEVINTERFACE_OSRUSBFX2,
                                            &DEVPKEY_DeviceInterface_UnrestrictedAppCapabilities);

    Status = WdfDeviceAssignInterfaceProperty(Device,
                                              &PropertyData,
                                              DEVPROP_TYPE_STRING_LIST,
                                              sizeof(customCapabilities),
                                              (PVOID)customCapabilities);

Aplikasi baru (tidak termasuk dalam sampel) aman dan dapat diperbarui dengan mudah di Microsoft Store. Dengan aplikasi UWP siap, Contoso menggunakan DISM - Deployment Image Servicing and Management untuk memuat aplikasi terlebih dahulu pada gambar edisi Windows Desktop.

Menghubungkan beberapa file INF dengan erat

Idealnya, harus ada kontrak penerapan versi yang kuat antara dasar, ekstensi, dan komponen. Ada keuntungan layanan dalam memiliki ketiga paket ini dilayankan secara independen (skenario "digabungkan secara longgar"), tetapi ada skenario di mana mereka perlu dibundel dalam satu paket driver ("digabungkan erat") karena kontrak penerapan versi yang buruk. Sampel mencakup contoh kedua skenario:

DCHU_Sample\osrfx2_DCHU_extension_loose
DCHU_Sample\osrfx2_DCHU_extension_tight

Ketika ekstensi dan komponen berada dalam paket driver yang sama ("digabungkan erat"), ekstensi INF menentukan arahan CopyINF untuk menyebabkan INF komponen disalin ke sistem target. Ini ditunjukkan dalam DCHU_Sample\osrfx2_DCHU_extension_tight\osrfx2_DCHU_extension\osrfx2_DCHU_extension.inx:

[OsrFx2Extension_Install.NT]
CopyInf=osrfx2_DCHU_component.inf

Arahan ini juga dapat digunakan untuk mengoordinasikan penginstalan file INF di perangkat multifungsi. Untuk informasi selengkapnya, lihat Menyalin file INF.

Catatan

Meskipun driver dasar dapat memuat ekstensi (dan menargetkan driver dasar di label pengiriman), ekstensi yang dibundel dengan driver lain tidak dapat diterbitkan ke ID perangkat keras ekstensi.

Jalankan dari Driver Store

Untuk mempermudah pembaruan driver, Fabrikam menentukan Driver Store sebagai tujuan untuk menyalin file driver dengan menggunakan dirid 13 jika memungkinkan. Menggunakan nilai direktori tujuan 13 dapat mengakibatkan peningkatan stabilitas selama proses pembaruan driver. Berikut adalah contoh dari [osrfx2_DCHU_base.inx]:

[DestinationDirs]
OsrFx2_CopyFiles = 13 ; copy to Driver Store

Lihat halaman jalankan dari Driver Store untuk detail selengkapnya mengenai cara menemukan dan memuat file secara dinamis dari Driver Store.

Ringkasan

Diagram berikut menunjukkan paket driver yang dibuat Fabrikam dan Contoso untuk driver yang mematuhi DCH mereka. Dalam contoh yang digabungkan secara longgar, mereka akan membuat tiga pengiriman terpisah di dasbor Windows Hardware Dev Center: satu untuk basis, satu untuk ekstensi, dan satu untuk komponen. Dalam contoh yang digabungkan dengan erat, mereka akan membuat dua pengiriman: dasar dan ekstensi/komponen.

Paket driver ekstensi, dasar, dan komponen.