De l’exemple de code au pilote de production - Éléments à modifier dans les exemples
Cette rubrique décrit les modifications importantes qui doivent être apportées aux exemples de pilotes WDK avant de libérer des pilotes de périphérique en fonction de l’exemple de code.
En plus des modifications décrites ici, tous les pilotes doivent utiliser les meilleures pratiques décrites dans Création de pilotes fiables Kernel-Mode et bonnes pratiques de développement de pilotes d’équipe Surface. Tous les pilotes doivent également respecter les instructions fournies dans les Instructions sur la sécurité des pilotes.
Exemples de pilotes WDK - Identificateurs uniques
Le Kit de pilotes Windows (WDK) contient un large éventail d’exemples de pilotes qui illustrent des techniques utiles pour le développement de pilotes. Vous pouvez utiliser ces exemples comme base pour vos propres pilotes, mais avant de libérer le pilote, vous devez modifier certains aspects spécifiques de l’appareil de l’exemple , au-delà du code opérationnel évident, pour qu’ils s’appliquent de manière unique à votre propre appareil et à votre propre pilote. Les enregistreurs de pilotes négligent parfois ces détails.
Les éléments exacts que vous devez modifier varient d’un exemple à l’autre, mais en général, ils identifient un appareil, une interface ou un pilote spécifique. Par exemple, si l’exemple de pilote contient l’un des éléments suivants, vous devez les modifier pour les appliquer à votre pilote et à votre appareil :
Identificateurs uniques globaux (GUID)
Noms de liens symboliques
Nom de l’objet de l’appareil
Étiquettes de pool
Définitions de code de contrôle d’E/S (IOCTL)
Noms des fichiers copiés dans le dossier système
PLUG-AND-PLAY ID d’appareil, ID matériel et ID compatibles
Nom du service de pilote
Description de l’appareil
Fichier de ressources
L’omission d’apporter ces modifications peut entraîner l’échec de l’installation, des conflits avec d’autres périphériques et pilotes sur le système et des difficultés de débogage, ainsi que d’autres erreurs.
Par exemple, si vous recevez une erreur telle ...\toastDrv\kmdf\toastmon\wdftoastmon.inx(18-18): error 1284: Class "Sample" is reserved for use by Microsoft. que celle-ci indique que le nom « Exemple » doit être remplacé par un nom unique pour votre exemple de pilote.
GUID
Les pilotes utilisent des GUID pour identifier les classes d’installation d’appareil, les classes d’interface d’appareil, les événements PnP personnalisés, les événements WMI (Windows Management Instrumentation) personnalisés et les fournisseurs de traces de préprocesseur Windows (WPP). Certains GUID sont définis par Microsoft, tandis que d’autres sont définis par les fournisseurs d’appareils et de pilotes.
Les GUID de classe de configuration de l’appareil, les GUID de classe d’interface d’appareil et les GUID WMI pour les appareils courants et les données WMI sont définis dans le WDK ou dans les fichiers d’en-tête publics à utiliser par n’importe quel pilote. Vous ne devez pas modifier ces GUID.
Par exemple, si vous implémentez une souris, vous continuerez à utiliser GUID_DEVINTERFACE_MOUSE, qui est défini dans le fichier d’en-tête WDK Ntddmou.h, comme classe d’interface d’appareil. Toutefois, si vous définissez une nouvelle classe d’installation d’appareil, vous devez générer un nouveau GUID de classe d’installation d’appareil et un nom de classe d’installation, et éventuellement un nouveau GUID de classe d’interface d’appareil. Le GUID de classe d’installation et le GUID de classe d’interface d’appareil doivent être des valeurs uniques ; ils ne peuvent pas partager un GUID.
Pour la plupart des pilotes basés sur des exemples, vous devez modifier uniquement les GUID définis dans l’en-tête local ou le fichier source d’un exemple et qui sont donc spécifiques à l’exemple. Ces GUID peuvent inclure les éléments suivants :
Événements PnP personnalisés
Événements WMI personnalisés
Classes d’interface d’appareil pour les appareils nouveaux ou personnalisés
Fournisseurs de trace WPP
L’utilisation d’un GUID qui a été défini pour un autre pilote peut entraîner des conflits si les deux pilotes sont chargés sur le même système. Par exemple, si deux pilotes différents utilisent le même GUID pour inscrire une interface d’appareil, les clients qui tentent d’ouvrir l’interface de périphérique peuvent ouvrir par inadvertance le mauvais appareil.
L’extrait suivant provient du fichier Driver.h inclus dans tous les exemples de pilotes Grille-pain. Il définit le GUID d’interface d’appareil pour les appareils Grille-pain :
DEFINE_GUID(GUID_TOASTER_INTERFACE_STANDARD, \
0xe0b27630, 0x5434, 0x11d3, 0xb8, 0x90, 0x0, 0xc0, \
0x4f, 0xad, 0x51, 0x71);
// {E0B27630-5434-11d3-B890-00C04FAD5171}
Si vous utilisez ce fichier dans votre propre pilote, veillez à remplacer l’exemple DE GUID (ci-dessus sous forme de texte en gras) par le GUID d’interface de votre propre appareil. Pour créer un GUID, utilisez l’outil Créer un GUID dans Microsoft Visual Studio ou Guidgen.exe, tous deux inclus dans le Kit de développement logiciel (SDK) Microsoft Windows. Vous pouvez ensuite associer le GUID à une constante symbolique dans le fichier d’en-tête du pilote, comme le montre l’exemple.
Vous devrez peut-être également créer des GUID pour les événements WMI du pilote. Les exemples de pilotes Grille-pain définissent le GUID suivant pour la notification de l’arrivée de l’appareil grille-pain :
DEFINE_GUID (TOASTER_NOTIFY_DEVICE_ARRIVAL_EVENT, \
0x1cdaff1, 0xc901, 0x45b4, 0xb3, 0x59, 0xb5, 0x54, \
0x27, 0x25, 0xe2, 0x9c);
// {01CDAFF1-C901-45b4-B359-B5542725E29C}
Vous devez créer un GUID pour chaque événement WMI dans votre pilote.
Si l’exemple de pilote utilise le suivi logiciel WPP, générez un nouveau GUID de fournisseur de trace pour tous les pilotes que vous basez sur l’exemple. Par exemple, le fichier d’en-tête Trace.h de l’exemple Osrusbfx2 dans %WinDDK%\Src\Kmdf\Osrusbfx2\Final définit un GUID de contrôle comme suit :
#define WPP_CONTROL_GUIDS \
WPP_DEFINE_CONTROL_GUID( \
OsrUsbFxTraceGuid,(d23a0c5a,d307,4f0e,ae8e,E2A355AD5DAB), \
WPP_DEFINE_BIT(DBG_INIT) /* bit 0 = 0x00000001 */ \
WPP_DEFINE_BIT(DBG_PNP) /* bit 1 = 0x00000002 */ \
WPP_DEFINE_BIT(DBG_POWER) /* bit 2 = 0x00000004 */ \
WPP_DEFINE_BIT(DBG_WMI) /* bit 3 = 0x00000008 */ \
WPP_DEFINE_BIT(DBG_CREATE_CLOSE) /* bit 4 = 0x00000010 */ \
WPP_DEFINE_BIT(DBG_IOCTL) /* bit 5 = 0x00000020 */ \
WPP_DEFINE_BIT(DBG_WRITE) /* bit 6 = 0x00000040 */ \
WPP_DEFINE_BIT(DBG_READ) /* bit 7 = 0x00000080 */ \
)
Dans votre propre pilote, vous remplacez le texte en gras par un nom spécifique au pilote et le GUID que vous avez créé.
Noms de liens symboliques
Si l’exemple définit un nom de lien symbolique, remplacez le nom dans l’exemple par un nom qui s’applique à votre propre pilote. Toutefois, ne modifiez pas les noms de liens connus tels que \DosDevices\COM1. En général, si le nom du lien est assez similaire à l’exemple de nom (tel que \DosDevices\CancelSamp), vous devez le modifier.
L’utilisation du même lien symbolique qu’un autre pilote a le même effet que l’utilisation d’un GUID d’interface d’appareil incorrect, car les interfaces d’appareil sont essentiellement des liens symboliques.
Le pilote de filtre de grille-pain KMDF dans %WinDDK\Src\Kmdf\Toaster\Filter crée un nom de lien symbolique qui utilise une chaîne définie comme suit dans le fichier d’en-tête Filter.h :
#define SYMBOLIC_NAME_STRING L"\\DosDevices\\ToasterFilter"
Modifiez la chaîne en gras pour décrire plus précisément votre propre pilote.
Nom de l’objet de l’appareil
Si l’exemple crée un nom pour l’objet d’appareil, vous devez modifier le nom lorsque vous adaptez l’exemple de code.
Le pilote de filtre de grille-pain KMDF nomme son objet d’appareil dans le fichier d’en-tête Filter.h comme suit :
#define NTDEVICE_NAME_STRING L\\Device\\ToasterFilter
Comme pour le nom du lien symbolique, vous devez modifier la chaîne pour décrire votre pilote.
N’oubliez pas que les objets d’appareil nommés peuvent représenter un risque de sécurité. Les objets d’appareil physique (PDO) doivent avoir des noms, et la plupart de ces noms sont générés par le système au lieu d’être attribués explicitement par un pilote. Les autres objets d’appareil doivent être nommés uniquement s’ils représentent des objets d’appareil de contrôle, qui sont utilisés pour la communication à bande latérale entre une application et un pilote. L’infrastructure de pilote en mode noyau (KMDF) et le modèle de pilote Windows (WDM) vous permettent de laisser Windows générer le nom. Cette approche garantit que le nom de l’objet d’appareil est unique et que les utilisateurs non privilégiés ne peuvent pas y accéder. Pour plus d’informations, consultez Contrôle de l’accès à l’espace de nomsd’appareil et Contrôle de l’accès aux appareils dans les pilotes KMDF.
Balises de pool
Une balise de pool est un littéral de un à quatre caractères qui identifie une allocation de mémoire spécifique et peut faciliter le débogage.
La plupart des exemples de pilotes définissent une balise de pool dans le fichier d’en-tête du pilote, comme dans la ligne suivante de Grille-pain.h :
#define TOASTER_POOL_TAG (ULONG) 'saoT'
Le pilote définit la balise vers l’arrière, car le débogueur l’affiche dans l’ordre inverse. Par conséquent, cette balise apparaît en tant que Toas dans la sortie du débogueur. Au lieu d’utiliser la balise définie par l’exemple, modifiez la chaîne pour identifier de manière unique votre propre code.
Le fichier Pooltag.txt répertorie les balises de pool utilisées par les composants et pilotes en mode noyau fournis avec Windows. Pooltag.txt est installé avec le WDK dans %winddk%\Tools\Other<i>platform\Poolmon, où la plateforme est amd64, i386 ou ia64. N’utilisez aucune des balises qui apparaissent dans cette liste.
Définitions IOCTL
Modifiez les codes de contrôle d’E/S définis par l’exemple pour utiliser un nom, un type d’appareil, un code de fonction, un type de transfert et un type d’accès appropriés pour votre appareil et votre pilote.
Par exemple, l’exemple Osrusbfx2 inclut la définition suivante pour IOCTL_OSRUSBFX2_READ_SWITCHES :
#define IOCTL_OSRUSBFX2_READ_SWITCHES
CTL_CODE(FILE_DEVICE_OSRUSBFX2, \
IOCTL_INDEX + 6, \
METHOD_BUFFERED, \
FILE_READ_ACCESS)
Un pilote basé sur un exemple pour un autre appareil nécessite des modifications à cette définition.
Noms de fichiers
Dans INF ou INX, modifiez les noms du pilote, du co-programme d’installation fourni par le fournisseur et de tous les autres fichiers que la procédure d’installation copie dans le dossier système. Ces noms de fichiers apparaissent généralement dans les sections [SourceDisksFiles] et [ClassInstall32] de l’INF et dans les entrées CopyFiles .
L’exemple suivant provient du fichier INX de l’exemple De grille-pain proposé KMDF, qui est disponible dans %WinDDK%\src\kmdf\Toaster\Func\Featured. Les noms de fichiers qui doivent être modifiés sont affichés en gras :
[ClassInstall32] Addreg=ToasterClassReg CopyFiles=ToasterClassInstallerCopyFileshighlight [ToasterClassReg] ... HKR,,Installer32,,"tostrcls.dll,ToasterClassInstaller" ... [ToasterClassInstallerCopyFiles] tostrcls.dll ...
Pour adapter cette partie du fichier à un autre pilote, vous devez remplacer « tostrcls.dll » par le nom de fichier de votre programme d’installation de classe et modifier la chaîne « ToasterClassInstaller » pour décrire votre propre programme d’installation. Ces modifications garantissent que la procédure d’installation copie le fichier de co-programme d’installation correct et que la clé de Registre enregistre le nom de fichier correct.
Ne modifiez pas le nom des co-programmes d’installation fournis dans le WDK ou avec Windows, tels que les co-programmes d’installation KMDF, UMDF et WinUSB.
Des modifications supplémentaires sont requises plus loin dans la section Installation de l’appareil du fichier, comme illustré dans cet exemple :
[Toaster_Device.NT] CopyFiles=Toaster_Device.NT.Copy [Toaster_Device.NT.Copy] wdffeatured.sys
Dans cet exemple, vous devez remplacer le nom du fichier en gras par le nom de votre fichier de pilote généré.
Lorsque le programme d’installation copie les fichiers INF et de catalogue de pilotes, il les renomme, de sorte que vous n’êtes pas strictement obligé de modifier leurs noms dans votre package de pilotes. Toutefois, il est généralement judicieux de s’assurer que les noms de fichiers INF et catalogue sont similaires au nom du fichier de pilote.
ID d’appareil PnP, ID matériel et ID compatibles
Le programme d’installation utilise l’ID de l’appareil ainsi que les ID matériels et les ID compatibles pour sélectionner l’INF à utiliser pour l’installation de l’appareil.
L’ID d’appareil est une chaîne définie par le fournisseur qui identifie de manière unique un appareil spécifique. Chaque appareil a exactement un ID d’appareil. Le pilote de bus signale l’ID de périphérique pendant l’énumération et le programme d’installation l’utilise pour faire correspondre l’appareil avec le fichier INF correct. L’ID d’appareil est défini dans la section [Fabricant] de l’INF.
L’exemple suivant montre l’ID d’appareil pour l’appareil OSR USB Fx2, comme spécifié dans le fichier Osrusbfx2.inx :
[Manufacturer]
%MfgName%=Microsoft,NT$ARCH$
; For Win2K
[Microsoft]
%USB\VID_045E&PID_930A.DeviceDesc%=osrusbfx2.Dev,
USB\VID_0547&PID_1002
...
; For XP and later
[Microsoft.NT$ARCH$]
%USB\VID_045E&PID_930A.DeviceDesc%=osrusbfx2.Dev,
USB\VID_0547&PID_1002
Pour adapter cette directive INF à votre propre pilote, remplacez l’ID d’appareil affiché en gras par l’ID de l’appareil de votre propre appareil. Vous devez également remplacer le nom du fabricant par le nom de votre entreprise.
L’ID matériel et l’ID compatible sont des ID moins spécifiques que le programme d’installation utilise s’il ne peut pas faire correspondre l’ID de l’appareil à un INF. Si votre INF peut prendre en charge d’autres appareils, vous devez modifier ces valeurs en plus de l’ID de l’appareil. L’exemple suivant du pilote Grille-pain en vedette KMDF montre un ID matériel :
[Manufacturer]
%StdMfg%=Standard,NT$ARCH$
; For Win2K
[Standard]
; DisplayName Section DeviceId
; ----------- ------- --------
%ToasterDevice.DeviceDesc%=Toaster_Device,
{b85b7c50-6a01-11d2-b841-00c04fad5171}\MsToaster
; For XP and later
[Standard.NT$ARCH$]
%ToasterDevice.DeviceDesc%=Toaster_Device,
{b85b7c50-6a01-11d2-b841-00c04fad5171}\MsToaster
Pour adapter cette directive INF à votre propre pilote, remplacez l’ID matériel par l’ID de périphérique de votre pilote et remplacez « MsToaster » par une chaîne plus descriptive.
Nom du service de pilote
Mettez à jour le nom du service dans la directive AddService dans inf vers une valeur appropriée pour votre pilote. Si le nom du service de pilote est en conflit avec celui d’un autre pilote sur le système, le pilote n’est pas installé ni chargé.
Le pilote De grille-pain en vedette KMDF nomme son service comme suit :
[Toaster_Device.NT.Services]
AddService = wdffeatured, %SPSVCINST_ASSOCSERVICE%,
wdffeatured_Service_Inst
Le nom du service est la première entrée de la directive AddService . Pour adapter l’INF du grille-pain proposé, vous devez remplacer la chaîne en gras par une chaîne plus adaptée à votre pilote. Dans l’exemple, l’entrée wdffeatured_Service_Inst fait simplement référence à une section définie par INF. Sa modification n’est donc pas critique.
Description de l’appareil
La description de l’appareil se compose de plusieurs chaînes qui sont généralement définies dans la section [Chaînes] de l’INF et sont utilisées à différents endroits dans l’inf. Par exemple, l’exemple KmDF Featured Toaster définit les chaînes suivantes dans le fichier WdfFeatured.inx :
[Strings] SPSVCINST_ASSOCSERVICE = 0x00000002 MSFT = "Microsoft" StdMfg = "(Standard system devices)" ClassName = "Toaster" DiskId1 = "Toaster Device Installation Disk #1" ToasterDevice.DeviceDesc = "Microsoft WDF Featured Toaster" Toaster.SVCDESC = "Microsoft WDF Toaster Featured Device Driver"
Pour modifier ce fichier afin d’installer votre propre pilote, vous devez modifier les chaînes en gras pour refléter des informations sur votre entreprise, votre appareil et votre pilote.
Si le nom de l’entreprise apparaît également dans une section [Fabricant] dans l’INF, vous devez également modifier le nom.
Fichier de ressources
Les pilotes et d’autres composants, tels que les co-programmes d’installation spécifiques aux exemples, ont également des fichiers de ressources (.rc), qui définissent des chaînes spécifiques au pilote, notamment le nom du produit, la version du fichier et le nom de l’entreprise. Modifiez ces chaînes pour les valeurs appropriées pour votre package de pilotes.
Résumé - Que devez-vous faire ?
Avant de publier un pilote basé sur un exemple WDK, remplacez toutes les informations spécifiques à l’exemple dans les fichiers sources, l’INF et toutes les autres ressources que vous avez utilisées pour créer votre propre pilote. Les modifications requises varient d’un exemple à l’autre, mais incluent généralement toutes les informations qui identifient de manière unique l’exemple de pilote ou son appareil. Les éléments suivants sont typiques des modifications que vous devez apporter :
Générez et utilisez des GUID spécifiques à votre pilote, le cas échéant.
Mettez à jour le nom du lien symbolique.
Mettez à jour le nom de l’objet d’appareil ou utilisez un nom généré automatiquement.
Utilisez des balises de pool qui identifient votre pilote et ne sont pas en conflit avec les balises connues.
Définissez les codes IOCTL appropriés pour votre pilote et votre appareil.
Mettez à jour les noms de tous les fichiers copiés dans le dossier système.
Insérez l’ID d’appareil Plug-and-Play, les ID matériels et les ID compatibles appropriés dans l’INF.
Mettez à jour le nom du service du pilote dans le fichier INF.
Modifier la description de l’appareil.
Modifiez toutes les chaînes spécifiques au pilote dans le fichier de ressources.
Respecter les meilleures pratiques en matière de sécurité et de fiabilité
Informations supplémentaires
Livres
Développement de pilotes avec Windows Driver Foundation, par Penny Orwick et Guy Smith
Rubriques WDK
Définition et exportation de nouveaux GUID
Contrôle de l’accès des appareils dans les pilotes KMDF
Développement, test et déploiement de pilotes
Création de pilotes Kernel-Mode fiables
Meilleures pratiques en matière de développement de pilotes d’équipe Surface
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour