Exemple de package de pilote conforme à la norme DCH

Article
10/16/2024

Cet article décrit comment l’exemple de pilote DCHU applique les principes de conception DCH. Vous pouvez l’utiliser comme modèle pour appliquer les principes de conception DCH à votre propre package de pilote.

Si vous souhaitez une copie locale du référentiel d’exemples, clonez à partir de Windows-driver-samples.

Certaines parties de l’exemple peuvent utiliser des directives et des API qui ne sont disponibles que sur certaines versions de Windows 10 et au-delà. Veuillez consulter la section Installation de périphériques et de pilotes pour savoir sur quelle version du système d’exploitation une directive donnée est prise en charge.

Prérequis

Avant de lire cette section, vous devez vous familiariser avec les Principes de conception DCH.

Vue d’ensemble

L’exemple fournit des scénarios où deux partenaires matériels, Contoso (un constructeur de systèmes, ou OEM) et Fabrikam (un fabricant de périphériques, ou IHV), travaillent ensemble pour créer un pilote conforme aux normes DCH pour un périphérique dans le prochain système de Contoso. Le périphérique en question est un kit d’apprentissage OSR USB FX2. Dans le passé, Fabrikam rédigeait un package de pilote classique qui était personnalisé pour une ligne de produits Contoso spécifique, puis le transmettait à l’OEM pour la maintenance. Cela entraînait une surcharge de maintenance importante, c’est pourquoi Fabrikam a décidé de remanier le code et de créer un package de pilote conforme aux normes DCH à la place.

Utilisez des sections/directives déclaratives et isolez correctement l’INF

Tout d’abord, Fabrikam examine la liste des sections et directives INF qui sont invalides dans les packages de pilotes conformes aux normes DCH. Lors de cet exercice, Fabrikam remarque qu’ils utilisent beaucoup de ces sections et directives dans leur package de pilote.

Leur INF de pilote enregistre un co-installateur qui applique des paramètres et fichiers dépendants de la plate-forme. Cela signifie que le package de pilote est plus volumineux qu’il ne le devrait et qu’il est plus difficile d’entretenir le pilote lorsqu’un bogue affecte seulement un sous-ensemble des systèmes OEM livrant le pilote. De plus, la plupart des modifications spécifiques à l’OEM sont liées à l’image de marque, de sorte que Fabrikam doit mettre à jour le package de pilote chaque fois qu’un OEM est ajouté ou lorsqu’un problème mineur affecte un sous-ensemble des systèmes OEM.

Fabrikam supprime les sections et directives non déclaratives et utilise l’outil InfVerif pour vérifier que le fichier INF du nouveau package de pilote respecte l’exigence INF déclarative.

Utilisez des INF d’extension pour modulariser un package de pilote

Ensuite, Fabrikam sépare les personnalisations spécifiques aux partenaires OEM (comme Contoso) du package de pilote de base dans un INF d’extension.

L’extrait suivant, mis à jour à partir de [osrfx2_DCHU_extension.inx], spécifie la classe Extension et identifie Contoso comme le fournisseur car ils posséderont le package de pilote d’extension :

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

Dans [osrfx2_DCHU_base.inx], Fabrikam spécifie les entrées suivantes :

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

Dans [osrfx2_DCHU_extension.inx], Contoso remplace la valeur de registre OperatingParams définie par le package de base et ajoute OperatingExceptions :

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

Les extensions sont toujours traitées après l’INF de base, mais sans ordre défini. Si un INF de base est mis à jour vers une nouvelle version, les extensions seront toujours réappliquées après l’installation du nouvel INF de base.

Installer un service à partir d’un fichier INF

Fabrikam utilise un service Win32 pour contrôler les LED sur la carte OSR. Ils considèrent ce composant comme faisant partie de la fonctionnalité principale du périphérique, ils l’incluent donc dans leur INF de base ([osrfx2_DCHU_base.inx]). Ce service en mode utilisateur (usersvc) peut être ajouté et démarré de manière déclarative en spécifiant la directive AddService dans le fichier 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

Un tel service pourrait également être installé dans un INF de composant ou d’extension, selon le scénario.

Utiliser un composant pour installer un logiciel classique à partir d’un package de pilote

Fabrikam dispose d’un fichier exécutable osrfx2_DCHU_componentsoftware.exe qu’ils ont précédemment installé à l’aide d’un co-installateur. Ce logiciel classique affiche les clés de registre définies par la carte et est requis par l’OEM. Il s’agit d’un exécutable basé sur une interface graphique qui ne fonctionne que sur les éditions de bureau de Windows. Pour l’installer, Fabrikam crée un package de pilote de composant distinct et l’ajoute dans leur INF d’extension.

L’extrait suivant de [osrfx2_DCHU_extension.inx] utilise la directive AddComponent pour créer un périphérique enfant virtuel :

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


[OsrFx2Extension_ComponentInstall]
ComponentIds=VID_045e&PID_94ab

Ensuite, dans l’INF de composant [osrfx2_DCHU_component.inx], Fabrikam spécifie la directive AddSoftware pour installer l’exécutable optionnel :

[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

Le code source de l’application Win32 est inclus dans l’exemple.

Le package de pilote de composant est uniquement distribué sur les SKU Desktop en raison de la configuration ciblée dans le tableau de bord Windows Hardware Dev Center. Pour plus d’informations, veuillez consulter la section Publier un pilote sur Windows Update.

Permettre la communication avec une application de support matériel

Fabrikam souhaite fournir une application compagnon avec interface graphique dans le cadre du package Windows Driver. Étant donné que les applications compagnons basées sur Win32 ne peuvent pas faire partie d’un package Windows Driver, ils adaptent leur application Win32 à la plate-forme Windows universelle (UWP) et associent l’application avec le périphérique.

L’extrait suivant de osrfx2_DCHU_base/device.c montre comment le package de pilote de base ajoute une capacité personnalisée à l’instance d’interface de périphérique :

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

La nouvelle application (non incluse dans l’exemple) est sécurisée et peut être facilement mise à jour dans le Microsoft Store. Avec l’application UWP prête, Contoso utilise DISM : Deployment Image Servicing and Management pour précharger l’application sur les images de l’édition Desktop de Windows.

Coupler étroitement plusieurs fichiers INF

Idéalement, il devrait y avoir des contrats de versionnage solides entre la base, les extensions et les composants. Il y a des avantages à maintenir ces trois packages indépendamment (le scénario « faiblement couplé »), mais il existe des scénarios où ils doivent être regroupés dans un seul package de pilote (« étroitement couplé ») en raison de mauvais contrats de versionnage. L’exemple inclut des exemples des deux scénarios :

DCHU_Sample\osrfx2_DCHU_extension_loose
DCHU_Sample\osrfx2_DCHU_extension_tight

Lorsque l’extension et le composant sont dans le même package de pilote (« étroitement couplés »), l’INF d’extension spécifie la directive CopyINF pour que l’INF du composant soit copié sur le système cible. Cela est démontré dans DCHU_Sample\osrfx2_DCHU_extension_tight\osrfx2_DCHU_extension\osrfx2_DCHU_extension.inx :

[OsrFx2Extension_Install.NT]
CopyInf=osrfx2_DCHU_component.inf

Cette directive peut également être utilisée pour coordonner l’installation de fichiers INF dans des périphériques multifonctions. Pour plus d’informations, consultez la section Copier des fichiers INF.

Remarque

Bien qu’un pilote de base puisse charger une extension (et cibler le pilote de base dans l’étiquette d’expédition), une extension groupée avec un autre pilote ne peut pas être publiée sur l’identifiant matériel de l’extension.

Exécuter à partir du magasin de pilotes

Pour faciliter la mise à jour du pilote, Fabrikam spécifie le Magasin de pilotes comme destination pour copier les fichiers du pilote en utilisant dirid 13 lorsque cela est possible. L’utilisation d’une valeur de répertoire de destination de 13 peut améliorer la stabilité du processus de mise à jour du pilote. Voici un exemple de [osrfx2_DCHU_base.inx] :

[DestinationDirs]
OsrFx2_CopyFiles = 13 ; copy to Driver Store

Consultez la section Exécuter à partir du magasin de pilotes pour plus de détails sur la manière de trouver et de charger dynamiquement des fichiers à partir du magasin de pilotes.

Résumé

Le diagramme suivant montre les packages de pilotes que Fabrikam et Contoso ont créés pour leur pilote conforme aux normes DCH. Dans l’exemple faiblement couplé, ils feront trois soumissions distinctes sur le tableau de bord Windows Hardware Dev Center : une pour la base, une pour l’extension et une pour le composant. Dans l’exemple étroitement couplé, ils feront deux soumissions : base et extension/composant.

Packages de pilotes d’extension, de base et de composant.

L’INF du composant correspondra à l’identifiant matériel du composant, tandis que les packages de base et d’extension correspondront à l’identifiant matériel de la carte.