exemple de package de pilotes DCH-Compliant

Article
06/08/2023

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 pilotes.

Si vous souhaitez obtenir une copie locale de l’exemple de référentiel, 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 versions ultérieures. Reportez-vous à Installation des périphériques et des pilotes pour voir sur quelle version de 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 exemples de scénarios dans lesquels deux partenaires matériels, Contoso (un générateur de système ou OEM) et Fabrikam (un fabricant d’appareils, ou IHV) travaillent ensemble pour créer un pilote compatible DCH pour un appareil dans le système à venir de Contoso. L’appareil en question est un kit d’apprentissage OSR USB FX2. Dans le passé, Fabrikam écrivait un package de pilotes hérité qui était personnalisé pour une ligne de produits Contoso spécifique, puis le remettait au fabricant OEM pour gérer la maintenance. Cela a entraîné une surcharge de maintenance importante. Fabrikam a donc décidé de refactoriser le code et de créer un package de pilotes compatible DCH à la place.

Utiliser des sections/directives déclaratives et isoler correctement INF

Tout d’abord, Fabrikam passe en revue la liste des sections et directives INF qui ne sont pas valides dans les packages de pilotes compatibles DCH. Au cours de cet exercice, Fabrikam remarque qu’il utilise bon nombre de ces sections et directives dans son package de pilotes.

Son pilote INF inscrit un co-programme d’installation qui applique des paramètres et des fichiers dépendant de la plateforme. Cela signifie que le package de pilotes est plus volumineux qu’il ne devrait l’être et qu’il est plus difficile de le traiter lorsqu’un bogue affecte uniquement un sous-ensemble des systèmes OEM qui expédient le pilote. En outre, la plupart des modifications spécifiques aux OEM sont liées à la personnalisation. Fabrikam doit donc mettre à jour le package de pilotes chaque fois qu’un OEM est ajouté ou lorsqu’un problème mineur affecte un sous-ensemble de 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 pilotes respecte l’exigence INF déclarative.

Utiliser l’extension INFs pour composant un package de pilotes

Ensuite, Fabrikam sépare les personnalisations spécifiques aux partenaires OEM (tels que Contoso) du package de pilotes de base en une extension INF.

L’extrait de code suivant, mis à jour à partir de [osrfx2_DCHU_extension.inx], spécifie la Extension classe et identifie Contoso comme fournisseur, car il sera propriétaire du 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 la 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 dans aucun ordre défini. Si un INF de base est mis à jour vers une version plus récente, les extensions seront toujours appliquées à nouveau 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 des fonctionnalités principales de l’appareil, de sorte qu’ils l’incluent 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 peut également être installé dans un composant ou une extension INF, selon le scénario.

Utiliser un composant pour installer des logiciels hérités à partir d’un package de pilotes

Fabrikam a un fichier osrfx2_DCHU_componentsoftware.exe exécutable qu’il a installé précédemment à l’aide d’un co-programme d’installation. Ce logiciel hérité 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 l’interface graphique graphique qui s’exécute uniquement sur Windows pour les éditions de bureau. Pour l’installer, Fabrikam crée un package de pilote de composant distinct et l’ajoute dans son extension INF.

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

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


[OsrFx2Extension_ComponentInstall]
ComponentIds=VID_045e&PID_94ab

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

[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 distribué uniquement sur les références SKU de bureau en raison du ciblage défini dans le tableau de bord du Centre de développement matériel Windows. Pour plus d’informations, consultez Publier un pilote sur Windows Update.

Autoriser la communication avec une application de prise en charge matérielle

Fabrikam souhaite fournir une application complémentaire basée sur l’interface graphique graphique dans le cadre du package Windows Driver. Étant donné que les applications complémentaires basées sur Win32 ne peuvent pas faire partie d’un package Windows Driver, elles portent leur application Win32 vers le plateforme Windows universelle (UWP) et associent l’application à l’appareil.

L’extrait de code suivant montre comment le package de pilotes de osrfx2_DCHU_base/device.c base ajoute une fonctionnalité personnalisée à l’interface de l’appareil instance :

    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 mise à jour facilement dans le Microsoft Store. Une fois l’application UWP prête, Contoso utilise DISM - Deployment Image Servicing and Management pour précharger l’application sur les images windows Desktop Edition.

Couplage étroit de plusieurs fichiers INF

Dans l’idéal, il doit y avoir des contrats de contrôle de version forts entre la base, les extensions et les composants. Il existe des avantages de maintenance à avoir ces trois packages gérés indépendamment (le scénario « faiblement couplé »), mais il existe des scénarios où ils doivent être regroupés dans un seul package de pilotes (« étroitement couplé ») en raison de contrats de gestion de version médiocres. 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 se trouvent dans le même package de pilotes (« étroitement couplé »), l’extension INF spécifie la directive CopyINF pour que le composant INF soit copié sur le système cible. Cela est illustré 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 appareils multifonctions. Pour plus d’informations, consultez Copie de fichiers INF.

Notes

Bien qu’un pilote de base puisse charge utile 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 dans l’ID 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 à l’aide de dirid 13 dans la mesure du possible. L’utilisation d’une valeur de répertoire de destination de 13 peut améliorer la stabilité pendant le processus de mise à jour du pilote. Voici un exemple de [osrfx2_DCHU_base.inx] :

[DestinationDirs]
OsrFx2_CopyFiles = 13 ; copy to Driver Store

Pour plus d’informations sur la façon de rechercher et de charger dynamiquement des fichiers à partir du magasin de pilotes, consultez la page Exécuter à partir du Magasin de pilotes.

Récapitulatif

Le diagramme suivant montre les packages de pilotes que Fabrikam et Contoso ont créés pour leur pilote compatible DCH. Dans l’exemple faiblement couplé, ils effectuent trois soumissions distinctes sur le tableau de bord du Centre de développement matériel Windows : une pour la base, une pour l’extension et une pour le composant. Dans l’exemple étroitement couplé, ils effectuent deux soumissions : base et extension/composant.

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