Beispiel für DCH-Compliant-Treiberpaket

Artikel
06/08/2023

In diesem Artikel wird beschrieben, wie das DCHU-Treiberbeispiel DCH-Entwurfsprinzipien anwendet. Sie können es als Modell verwenden, um DCH-Entwurfsprinzipien auf Ihr eigenes Treiberpaket anzuwenden.

Wenn Sie eine lokale Kopie des Beispielrepositorys wünschen, klonen Sie aus Windows-driver-samples.

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

Voraussetzungen

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

Übersicht

Das Beispiel enthält Beispielszenarien, in denen die beiden Hardwarepartner Contoso (Systementwickler oder OEM) und Fabrikam (Gerätehersteller oder IHV) zusammenarbeiten, um einen Treiber zu erstellen, der DCH-konform für ein Gerät im bevorstehenden System von Contoso ist. Bei dem betreffenden Gerät handelt es sich um ein OSR USB FX2-Lernkit. In der Vergangenheit hat Fabrikam ein Legacytreiberpaket geschrieben, das an eine bestimmte Contoso-Produktlinie angepasst wurde, und es dann an den OEM übergeben, um die Wartung zu übernehmen. Dies führte zu einem erheblichen Wartungsaufwand, sodass Fabrikam beschlossen hat, den Code umzugestalten und stattdessen ein DCH-kompatibles Treiberpaket zu erstellen.

Verwenden deklarativer Abschnitte/Direktiven und ordnungsgemäßes Isolieren von INF

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

Der Treiber INF registriert ein Co-Installationsprogramm, das plattformabhängige Einstellungen und Dateien anwendet. Dies bedeutet, dass das Treiberpaket größer als es sein sollte, und es ist schwieriger, den Treiber zu bedienen, wenn ein Fehler nur eine Teilmenge der OEM-Systeme betrifft, die den Treiber liefern. Außerdem beziehen sich die meisten OEM-spezifischen Änderungen auf das Branding, sodass Fabrikam das Treiberpaket jedes Mal aktualisieren muss, wenn ein OEM hinzugefügt wird oder wenn ein kleineres Problem eine Teilmenge 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 der deklarativen INF-Anforderung entspricht.

Verwenden von Erweiterungs-INFs zum Komponentenisieren eines Treiberpakets

Als Nächstes trennt Fabrikam anpassungen, die spezifisch für OEM-Partner (z. B. Contoso) sind, vom Basistreiberpaket in eine Erweiterung INF.

Der folgende Codeausschnitt, aktualisiert von [osrfx2_DCHU_extension.inx], gibt die Extension -Klasse an und identifiziert Contoso als Anbieter, da er besitzer des Erweiterungstreiberpakets ist:

[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] gibt Fabrikam die folgenden Einträge an:

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

In [osrfx2_DCHU_extension.inx] überschreibt Contoso den von der Basis festgelegten OperatingParams-Registrierungswert und fügt OperatingExceptions hinzu:

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

Erweiterungen werden immer nach dem Basis-INF verarbeitet, aber in keiner bestimmten Reihenfolge. Wenn ein Basis-INF auf eine neuere Version aktualisiert wird, werden die Erweiterungen weiterhin erneut angewendet, nachdem das neue Basis-INF installiert wurde.

Installieren eines Diensts aus einer INF-Datei

Fabrikam verwendet einen Win32-Dienst, um die LEDs auf dem OSR-Board zu steuern. Sie betrachten diese Komponente als Teil der Kernfunktionalität des Geräts, sodass sie als Teil ihres Basis-INF ([osrfx2_DCHU_base.inx]) eingeschlossen wird. Dieser Benutzermodusdienst (usersvc) kann hinzugefügt und deklarativ gestartet werden, indem die AddService-Direktive in der INF-Datei angegeben wird:

[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 kann je nach Szenario auch in einer Komponente oder Erweiterung in INF installiert werden.

Verwenden einer Komponente zum Installieren von Legacysoftware aus einem Treiberpaket

Fabrikam verfügt über eine ausführbare Datei osrfx2_DCHU_componentsoftware.exe , die zuvor mithilfe eines Co-Installers installiert wurde. Diese Legacysoftware zeigt die vom Board festgelegten Registrierungsschlüssel an und wird vom OEM benötigt. Dies ist eine GUI-basierte ausführbare Datei, die nur unter Windows für Desktopeditionen ausgeführt wird. Um es zu installieren, erstellt Fabrikam ein separates Komponententreiberpaket und fügt es der Erweiterung INF hinzu.

Der folgende Codeausschnitt aus [osrfx2_DCHU_extension.inx] verwendet die AddComponent-Direktive , 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

Anschließend gibt Fabrikam in der Komponente INF [osrfx2_DCHU_component.inx] die AddSoftware-Direktive 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 im Beispiel enthalten.

Das Komponententreiberpaket wird aufgrund der im Windows Hardware Dev Center-Dashboard festgelegten Zielgruppen nur auf Desktop-SKUs verteilt. Weitere Informationen finden Sie unter Veröffentlichen eines Treibers in Windows Update.

Zulassen der Kommunikation mit einer Hardwareunterstützungs-App

Fabrikam möchte eine GUI-basierte Begleit-App als Teil des Windows-Treiberpakets bereitstellen. Da Win32-basierte Begleitanwendungen nicht Teil eines Windows-Treiberpakets sein können, portieren sie ihre Win32-App auf die Universelle Windows-Plattform (UWP) und koppeln die App mit dem Gerät.

Der folgende Codeausschnitt aus osrfx2_DCHU_base/device.c zeigt, wie das Basistreiberpaket der Geräteschnittstelle instance eine benutzerdefinierte Funktion 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 problemlos im Microsoft Store aktualisiert werden. Da die UWP-Anwendung bereit ist, verwendet Contoso DISM - Deployment Image Servicing and Management , um die Anwendung in Windows Desktop Edition-Images vorab zu laden.

Enge Kopplung mehrerer INF-Dateien

Im Idealfall sollten starke Versionsverwaltungsverträge zwischen Basis, Erweiterungen und Komponenten vorhanden sein. Es gibt Wartungsvorteile, wenn diese drei Pakete unabhängig (das "lose gekoppelte" Szenario) gewartet werden, aber es gibt Szenarien, in denen sie aufgrund schlechter Versionsverwaltungsverträge in einem einzelnen Treiberpaket ("eng gekoppelt") gebündelt werden müssen. 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 gleichen Treiberpaket befinden ("eng gekoppelt"), gibt die Erweiterung INF die CopyINF-Direktive an, die bewirkt, dass die Komponente INF auf das Zielsystem kopiert wird. Dies wird in DCHU_Sample\osrfx2_DCHU_extension_tight\osrfx2_DCHU_extension\osrfx2_DCHU_extension.inx veranschaulicht:

[OsrFx2Extension_Install.NT]
CopyInf=osrfx2_DCHU_component.inf

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

Hinweis

Ein Basistreiber kann zwar eine Erweiterung nutzen (und den Basistreiber im Versandetikett als Ziel verwenden), aber eine Erweiterung, die mit einem anderen Treiber gebündelt ist, kann nicht in der Erweiterungshardware-ID veröffentlicht werden.

Ausführen aus dem Treiberspeicher

Um das Aktualisieren des Treibers zu vereinfachen, gibt Fabrikam den Treiberspeicher als Ziel an, um die Treiberdateien nach Möglichkeit mithilfe von dirid 13 zu kopieren. Die Verwendung eines Zielverzeichniswerts von 13 kann zu einer verbesserten Stabilität während des Treiberupdateprozesses führen. Hier ist ein Beispiel aus [osrfx2_DCHU_base.inx]:

[DestinationDirs]
OsrFx2_CopyFiles = 13 ; copy to Driver Store

Weitere Informationen zum dynamischen Suchen und Laden von Dateien aus dem Treiberspeicher finden Sie auf der Seite "Ausführen im Treiberspeicher ".

Zusammenfassung

Das folgende Diagramm zeigt die Treiberpakete, die Fabrikam und Contoso für ihren DCH-kompatiblen Treiber erstellt haben. Im lose gekoppelten Beispiel werden drei separate Übermittlungen für die Windows Hardware Dev Center-Dashboard vorgenommen: eine für die Basis, eine für die Erweiterung und eine für die Komponente. Im eng gekoppelten Beispiel werden zwei Übermittlungen vorgenommen: Basis und Erweiterung/Komponente.

Erweiterungs-, Basis- und Komponententreiberpakete.

Die Komponenten-INF stimmt mit der Hardware-ID der Komponente überein, während die Basis und die Erweiterungen mit der Hardware-ID des Boards übereinstimmen.