Portage d’un pilote d’UMDF 1 vers UMDF 2
Cette rubrique explique comment porter un pilote User-Mode Driver Framework (UMDF) 1 vers UMDF 2. Vous pouvez commencer avec un pilote UMDF 1 qui utilise des fichiers Sources/Dirs (pas un projet Visual Studio), ou vous pouvez convertir un pilote UMDF 1 contenu dans un projet Visual Studio. Le résultat sera un projet de pilote UMDF 2 dans Visual Studio. Les pilotes UMDF 2 s’exécutent à la fois sur Windows 10 pour les éditions de bureau (Famille, Professionnel, Entreprise et Éducation) et Windows 10 Mobile.
L’exemple de pilote Echo est un exemple de pilote qui a été porté d’UMDF 1 vers UMDF 2.
Mise en route
Pour commencer, ouvrez un nouveau projet de pilote dans Visual Studio. Sélectionnez le modèle Visual C++->Windows Driver-WDF-User>> Mode Driver (UMDF 2). Visual Studio ouvre un modèle partiellement rempli qui inclut des stubs pour les fonctions de rappel que votre pilote doit implémenter. Ce nouveau projet de pilote sera la base de votre pilote UMDF 2. Utilisez l’exemple Echo UMDF 2 comme guide du type de code que vous devez introduire.
Ensuite, passez en revue votre code de pilote UMDF 1 existant et déterminez les mappages d’objets. Chaque objet COM dans UMDF 1 a un objet WDF correspondant dans UMDF 2. Par exemple, l’interface IWDFDevice est mappée à l’objet d’appareil WDF, qui est représenté par un handle WDFDEVICE. Presque toutes les méthodes d’interface fournies par l’infrastructure dans UMDF 1 ont des méthodes correspondantes dans UMDF 2. Par exemple, IWDFDevice::GetDefaultIoQueue est mappé à WdfDeviceGetDefaultQueue.
De même, les fonctions de rappel fournies par le pilote ont des équivalents dans les deux versions. Dans UMDF 1, la convention de nommage des interfaces fournies par le pilote (à l’exception d’IDriverEntry) est IObjectCallbackXxx, tandis que dans UMDF 2, la convention de nommage pour les routines fournies par le pilote est EvtObjectXxx. Par exemple, la méthode de rappel IDriverEntry::OnDeviceAdd est mappée à EvtDriverDeviceAdd.
Votre pilote implémente des fonctions de rappel dans UMDF 1 et 2, mais la façon dont le pilote fournit des pointeurs vers ses rappels diffère. Dans UMDF 1, le pilote implémente des méthodes de rappel en tant que membres des interfaces fournies par le pilote. Le pilote inscrit ces interfaces auprès de l’infrastructure lorsqu’il crée des objets d’infrastructure, par exemple en appelant IWDFDriver::CreateDevice.
Dans UMDF 2, le pilote fournit des pointeurs vers les fonctions de rappel fournies par le pilote dans des structures de configuration telles que WDF_DRIVER_CONFIG et WDF_IO_QUEUE_CONFIG.
Gestion de la durée de vie des objets
Les pilotes qui utilisent UMDF 1 doivent implémenter le comptage des références afin de déterminer quand il est sûr de supprimer des objets. Étant donné que l’infrastructure effectue le suivi des références d’objets pour le compte du pilote, un pilote UMDF 2 n’a pas besoin de compter les références.
Dans UMDF 2, chaque objet framework a un objet parent par défaut. Lorsqu’un objet parent est supprimé, l’infrastructure supprime les objets enfants associés. Lorsque votre pilote appelle une méthode de création d’objet telle que WdfDeviceCreate, il peut accepter le parent par défaut ou spécifier un parent personnalisé dans une structure WDF_OBJECT_ATTRIBUTES . Pour obtenir la liste des objets framework et de leurs objets parent par défaut, consultez Résumé des objets framework.
Initialisation du pilote
Un pilote UMDF 1 implémente l’interface IDriverEntry . Dans sa méthode de rappel IDriverEntry::OnDeviceAdd , le pilote :
- Crée et initialise un instance de l’objet de rappel d’appareil.
- Crée le nouvel objet d’appareil framework en appelant IWDFDriver::CreateDevice.
- Configure les files d’attente de l’appareil et leurs objets de rappel correspondants.
- Crée une instance d’une classe d’interface d’appareil en appelant IWDFDevice::CreateDeviceInterface.
Un pilote UMDF 2 implémente DriverEntry et EvtDriverDeviceAdd. Dans sa routine DriverEntry , un pilote UMDF 2 appelle généralement WDF_DRIVER_CONFIG_INIT pour initialiser la structure de WDF_DRIVER_CONFIG du pilote. Ensuite, il transmet cette structure à WdfDriverCreate.
Dans sa fonction EvtDriverDeviceAdd , le pilote peut effectuer certaines des opérations suivantes :
- Renseignez la structure WDFDEVICE_INIT , qui fournit les informations utilisées pour créer l’objet d’appareil. Pour plus d’informations sur l’utilisation de WDFDEVICE_INIT, consultez Création d’un objet d’appareil Framework.
- Configurez la zone de contexte de l’objet d’appareil. Pour plus d’informations sur l’allocation et l’accès à l’espace de contexte pour les objets framework, consultez Framework Object Context Space.
- Créez l’objet d’appareil.
- Spécifiez les gestionnaires de requêtes pour l’objet d’appareil.
- Créer des files d’attente d’E/S.
- Créez des interfaces d’appareil.
- Définissez la stratégie d’inactivité et les paramètres de veille de l’appareil, si l’objet d’appareil est propriétaire de la stratégie d’alimentation.
- Créez des objets d’interruption, si le matériel prend en charge les interruptions.
Installation de votre pilote
Lorsque vous créez un projet de pilote dans Visual Studio, le nouveau projet contient un fichier .inx. Lorsque vous générez votre pilote, Visual Studio compile votre fichier .inx dans un fichier INF qui peut être utilisé dans le cadre d’un package de pilotes.
Alors qu’un fichier INF pour un pilote UMDF 1 doit inclure un ID de classe de pilote, un DriverCLSID n’est pas requis dans un fichier INF pour un pilote UMDF 2.
En outre, bien qu’un pilote UMDF 1 doit référencer le co-programme d’installation dans son fichier INF, aucune référence de constaller n’est requise dans un fichier INF UMDF 2. Bien qu’une référence de coinstaller puisse apparaître dans un fichier INF pour un pilote UMDF 2, une référence n’est pas obligatoire.
Stockage du contexte d’appareil
Dans UMDF 1, le pilote stocke généralement le contexte de périphérique dans un objet de rappel créé par le pilote, par exemple en spécifiant des membres privés de la classe d’objet de rappel d’appareil. Un pilote UMDF 1 peut également appeler la méthode IWDFObject::AssignContext pour inscrire le contexte sur un objet framework.
Dans UMDF 2, l’infrastructure alloue de l’espace de contexte en fonction de la structure WDF_OBJECT_ATTRIBUTES facultative que le pilote fournit lorsqu’il appelle une méthode de création d’objet. Après avoir appelé la méthode create d’un objet, un pilote peut appeler WdfObjectAllocateContext une ou plusieurs fois pour allouer de l’espace de contexte supplémentaire à un objet spécifique. Pour connaître les étapes qu’un pilote UMDF 2 doit utiliser pour définir une structure de contexte et une méthode d’accesseur, consultez Framework Object Context Space.
Débogage de votre pilote
Pour déboguer un pilote UMDF 2, vous allez utiliser des extensions dans Wdfkd.dll au lieu de Wudfext.dll. Pour plus d’informations sur les extensions dans Wudfext.dll, consultez Résumé des extensions de débogueur dans Wdfkd.dll.
Dans UMDF 2, vous pouvez également obtenir des informations de débogage de pilote supplémentaires via l’enregistreur de traces en vol (IFR), comme décrit dans Utilisation de l’enregistreur de traces en vol dans les pilotes KMDF et UMDF 2. Vous pouvez également utiliser le propre enregistreur en vol (IFR) de l’infrastructure. Consultez Utilisation de l’enregistreur d’événements de l’infrastructure.