Beispiel für ein DCH-kompatibles Treiberpaket

Artikel
09/24/2024

Dieser Artikel beschreibt, wie das DCHU-Treiberbeispiel die DCH-Designprinzipien anwendet. Sie können ihn als Modell verwenden, um die DCH-Designprinzipien auf Ihr eigenes Treiberpaket anzuwenden.

Wenn Sie eine lokale Kopie des Beispiels aus dem Repo haben möchten, klonen Sie es von Windows-driver-samples.

Einige Teile des Beispiels können Direktiven und APIs verwenden, die nur auf bestimmten Versionen von Windows 10 und höher verfügbar sind. Lesen Sie Geräte- und Treiberinstallation, um zu erfahren, für welche Betriebssystemversion eine bestimmte Direktive unterstützt wird.

Voraussetzungen

Bevor Sie diesen Abschnitt lesen, sollten Sie sich mit den DCH-Design-Prinzipien vertraut machen.

Übersicht

Das Beispiel zeigt ein Szenario, in dem zwei Hardwarepartner, Contoso (ein Systemhersteller oder OEM) und Fabrikam (ein Gerätehersteller oder IHV), zusammenarbeiten, um einen DCH-kompatiblen Treiber für ein Gerät im kommenden System von Contoso zu erstellen. Bei dem fraglichen Gerät handelt es sich um ein OSR USB FX2 Learning Kit. In der Vergangenheit hat Fabrikam ein veraltetes Paket von Treibern geschrieben, das an eine bestimmte Contoso-Produktlinie angepasst war, und es dann dem OEM für die Wartung überlassen. Dies führte zu einem erheblichen Wartungsaufwand, so dass Fabrikam beschloss, den Code zu refaktorisieren und stattdessen ein DCH-konformes Treiberpaket zu erstellen.

Verwendung deklarativer Abschnitte/Direktiven und korrekte Isolierung von INF

Zunächst überprüft Fabrikam die Liste der INF-Abschnitte und Direktiven, die in DCH-konformen Treiberpaketen ungültig sind. Bei dieser Übung stellt Fabrikam fest, dass sie viele dieser Abschnitte und Direktiven in ihrem Treiberpaket verwenden.

Ihre Treiber-INF registriert einen Co-Installer, der plattformabhängige Einstellungen und Dateien anwendet. Das bedeutet, dass das Treiberpaket größer ist, als es sein sollte, und es ist schwieriger, den Treiber zu warten, wenn ein Fehler nur eine Untermenge der OEM-Systeme betrifft, die den Treiber ausliefern. Außerdem sind die meisten OEM-spezifischen Änderungen mit der Marke verbunden, so dass Fabrikam das Treiberpaket jedes Mal aktualisieren muss, wenn ein OEM hinzukommt oder wenn ein kleineres Problem eine Untermenge von OEM-Systemen betrifft.

Fabrikam entfernt die nicht deklarativen Abschnitte und Direktiven und verwendet das InfVerif-Tool, um zu überprüfen, ob die INF-Datei des neuen Treiberpakets den deklarativen INF-Anforderungen entspricht.

Verwenden Sie Erweiterungs-INFs, um ein Treiberpaket zu komponieren

Als Nächstes trennt Fabrikam Anpassungen, die für OEM-Partner (wie Contoso) spezifisch sind, vom Basistreiberpaket in einer Erweiterungs-INF.

Der folgende Ausschnitt, der von [osrfx2_DCHU_extension.inx] aktualisiert wurde, gibt die Klasse Extension an und identifiziert Contoso als Anbieter, da sie das Paket für die Erweiterung des Treibers besitzen werden:

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

In [osrfx2_DCHU_base.inx] spezifiziert Fabrikam die folgenden Einträge:

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

In [osrfx2_DCHU_extension.inx] setzt Contoso den von der Basis festgelegten Registrierungswert OperatingParams außer Kraft und fügt OperatingExceptions hinzu:

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

Erweiterungen werden immer nach der Basis-INF verarbeitet, aber in keiner bestimmten Reihenfolge. Wenn eine Basis-INF auf eine neuere Version aktualisiert wird, werden die Erweiterungen auch nach der Installation der neuen Basis-INF erneut angewandt.

Installieren eines Dienstes aus einer INF-Datei

Fabrikam verwendet einen Win32-Dienst, um die LEDs auf der OSR-Platine zu steuern. Sie betrachten diese Komponente als Element der Core-Funktionalität des Geräts und fügen sie daher als Element ihrer Basis-INF ([osrfx2_DCHU_base.inx]) ein. Dieser Dienst im Benutzermodus (usersvc) kann deklarativ hinzugefügt und gestartet werden, indem Sie die Direktive AddService in der INF-Datei angeben:

[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

Ein solcher Dienst könnte auch in einer Komponenten- oder Erweiterungs-INF installiert werden, je nach Szenario.

Verwenden Sie eine Komponente zur Installation von veralteter Software aus einem Treiber-Paket

Fabrikam hat eine ausführbare Datei osrfx2_DCHU_componentsoftware.exe, die sie zuvor mit einem Co-Installer installiert haben. Diese veraltete Software zeigt die vom Board festgelegten Registrierungsschlüssel an und wird vom OEM benötigt. Es handelt sich um eine GUI-basierte ausführbare Datei, die nur unter Windows für Desktop Versionen ausgeführt werden kann. Um es zu installieren, erstellt Fabrikam ein separates Treiberpaket und fügt es in seine Erweiterungs-INF ein.

Der folgende Ausschnitt aus [osrfx2_DCHU_extension.inx] verwendet die Direktive AddComponent, um ein virtuelles untergeordnetes Gerät zu erstellen:

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


[OsrFx2Extension_ComponentInstall]
ComponentIds=VID_045e&PID_94ab

In der Komponenten-INF [osrfx2_DCHU_component.inx] gibt Fabrikam dann die Direktive AddSoftware an, um die optionale ausführbare Datei zu installieren:

[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

Der Quellcode für die Win32 App ist in dem Beispiel enthalten.

Das Treiberpaket der Komponente wird aufgrund der im Windows Hardware Dev Center Dashboard festgelegten Ziele nur auf Desktop-SKUs verteilt. Weitere Informationen finden Sie unter Veröffentlichen eines Treibers für Windows Update.

Kommunikation mit einer Hardware Support App zulassen

Fabrikam möchte eine GUI-basierte Companion App als Element des Windows Driver Pakets bereitstellen. Da Win32-basierte Begleitanwendungen nicht Teil eines Windows Driver-Pakets sein können, portieren sie ihre Win32-App auf die Universal Windows Platform (UWP) und koppeln die App mit dem Gerät.

Der folgende Ausschnitt aus osrfx2_DCHU_base/device.c zeigt, wie das Basistreiberpaket der Instanz der Geräteschnittstelle eine angepasste Funktionalität hinzufügt:

    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);

Die neue App (nicht im Beispiel enthalten) ist sicher und kann im Microsoft Store einfach aktualisiert werden. Nachdem die UWP-Anwendung fertig ist, verwendet Contoso DISM – Deployment Image Servicing and Management, um die Anwendung auf Images der Windows Desktop Edition bereitzustellen.

Enge Kopplung mehrerer INF-Dateien

Idealerweise gibt es starke Versionsverwaltungsverträge zwischen Basis, Erweiterungen und Komponenten. Es hat Vorteile, wenn diese drei Pakete unabhängig voneinander gewartet werden (das „lose gekoppelte“ Szenario), aber es gibt auch Szenarien, in denen sie aufgrund unzureichender Versionsverwaltungsverträge in einem einzigen Paket gebündelt werden müssen („eng gekoppelt“). Das Beispiel enthält Beispiele für beide Szenarien:

DCHU_Sample\osrfx2_DCHU_extension_loose
DCHU_Sample\osrfx2_DCHU_extension_tight

Wenn sich die Erweiterung und die Komponente im selben Treiberpaket befinden („eng gekoppelt“), gibt die Erweiterungs-INF die Direktive CopyINF an, damit die INF der Komponente auf das Zielsystem kopiert wird. Dies wird in DCHU_Sample\osrfx2_DCHU_extension_tight\osrfx2_DCHU_extension\osrfx2_DCHU_extension.inx demonstriert:

[OsrFx2Extension_Install.NT]
CopyInf=osrfx2_DCHU_component.inf

Diese Direktive kann auch verwendet werden, um die Installation von INF-Dateien in Multifunktionsgeräten zu koordinieren. Weitere Informationen finden Sie unter Kopieren von INF-Dateien.

Hinweis

Während ein Basistreiber eine Erweiterung mit Payload versehen kann (und den Basistreiber im Label als Ziel angibt), kann eine Erweiterung, die mit einem anderen Treiber gebündelt ist, nicht für die Hardware-ID der Erweiterung veröffentlicht werden.

Ausführen aus dem Driver Store

Um die Aktualisierung des Treibers zu erleichtern, gibt Fabrikam den Driver Store als Ziel für das Kopieren der Treiberdateien an, indem es dirid 13 verwendet, wo dies möglich ist. Die Verwendung eines Zielverzeichniswerts von 13 kann zu einer verbesserten Stabilität während des Treiberaktualisierungsprozesses führen. Hier ist ein Beispiel aus [osrfx2_DCHU_base.inx]:

[DestinationDirs]
OsrFx2_CopyFiles = 13 ; copy to Driver Store

Auf der Seite Aus dem Driver Store ausführen finden Sie weitere Informationen darüber, wie Sie Dateien dynamisch aus dem Driver Store suchen und laden können.

Zusammenfassung

Das folgende Diagramm zeigt die Pakete, die Fabrikam und Contoso für ihren DCH-kompatiblen Treiber erstellt haben. In dem lose gekoppelten Beispiel werden sie drei separate Übermittlungen auf dem Windows Hardware Dev Center Dashboard vornehmen: eine für die Basis, eine für die Erweiterung und eine für die Komponente. In dem eng gekoppelten Beispiel machen Sie zwei Übermittlungen: Basis und Erweiterung/Komponente.

Erweiterungs-, Basis- und Komponententreiberpakete.

Die INF der Komponente wird mit der Hardware-ID der Komponente übereinstimmen, während die Basis und die Erweiterungen mit der Hardware-ID der Karte übereinstimmen.