Remarque
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de vous connecter ou de modifier des répertoires.
L’accès à cette page nécessite une autorisation. Vous pouvez essayer de modifier des répertoires.
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 disponibles uniquement sur certaines versions de Windows 10 et versions ultérieures. 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 exemples de scénarios où deux partenaires matériels, Contoso (générateur de système ou OEM) et Fabrikam (fabricant d’appareils ou IHV) travaillent ensemble pour créer un pilote conforme au DCH pour un appareil dans le système à venir 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. Ce processus a entraîné une surcharge de maintenance importante, donc Fabrikam a décidé de refactoriser le code et de créer un package de pilotes conforme 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 pilote INF enregistre un coinstallateur qui applique les paramètres et fichiers dépendant de la plateforme. Le package de pilotes est plus grand qu’il ne le doit, et il est plus difficile de traiter le pilote lorsqu’un bogue affecte uniquement un sous-ensemble des systèmes OEM qui fournissent le pilote. La plupart des modifications spécifiques à l’OEM sont liées à la personnalisation. Fabrikam doit donc mettre à jour le package de pilotes chaque fois qu’il ajoute un OEM 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 suit 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 de code suivant, mis à jour à partir de [osrfx2_DCHU_extension.inx], spécifie la Extension classe et identifie Contoso comme fournisseur, car il possède le package de pilotes 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"
Le système traite toujours les extensions après l’INF de base, mais dans aucun ordre défini. Si vous mettez à jour un INF de base vers une version plus récente, le système réapplique toujours les extensions après avoir installé le nouveau 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
Vous pouvez également installer un tel service dans un composant ou une extension INF, en fonction du scénario.
Utiliser un composant pour installer un logiciel classique à partir d’un package de pilote
Fabrikam dispose d’un fichier osrfx2_DCHU_componentsoftware.exe exécutable qu’il a installé précédemment à l’aide d’un coinstallateur. Ce logiciel hérité affiche les clés de Registre définies par la carte et requises par l’OEM. Cet exécutable est une application basée sur l’interface graphique utilisateur 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 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 pilotes 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, 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 complémentaires Basées sur Win32 ne peuvent pas faire partie d’un package pilote Windows, Fabrikam ports leur application Win32 vers la plateforme Windows universelle (UWP) et associe l’application à l’appareil.
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 vous pouvez la mettre à jour facilement dans le Microsoft Store. Avec l’application UWP prête, Contoso utilise DISM - Deployment Image Servicing and Management pour préinstaller l’application sur les versions de Windows Desktop.
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_tight
Lorsque l’extension et le composant se trouvent dans le même package de pilote (« étroitement couplé »), le fichier INF de l'extension spécifie la directive CopyINF afin que le système copie le fichier INF du composant dans le système cible. DCHU_Sample\osrfx2_DCHU_extension_tight\osrfx2_DCHU_extension\osrfx2_DCHU_extension.inx illustre cette technique :
[OsrFx2Extension_Install.NT]
CopyInf=osrfx2_DCHU_component.inf
Vous pouvez également utiliser cette directive pour coordonner l’installation des fichiers INF dans des appareils multifonction. 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 de livraison), vous ne pouvez pas publier une extension groupée avec un autre pilote vers 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é du 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 l’article Exécuter à partir du magasin de pilotes .
Résumé
Le diagramme suivant montre les packages de pilotes créés par Fabrikam et Contoso 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.
Le composant INF correspond à l’ID matériel du composant, tandis que la base et les extensions correspondent à l’ID matériel de la carte.