Tests PnP (Device Fundamentals)

Les tests fondamentaux PnP des appareils forcent un pilote à gérer presque tous les IRP PnP ; toutefois, il existe trois domaines qui sont mis en avant spécifiquement : la suppression, le rééquilibrage et la suppression surprise. Le test PnP fournit un mécanisme permettant de tester chacun de ces éléments séparément, ou de les tester ensemble (autrement dit, en tant que test de contrainte). Ce test PnP s’effectue à l’aide d’une combinaison d’appels d’API en mode utilisateur (via l’application de test) et d’appels d’API en mode noyau (via un pilote de filtre supérieur).

Tests PNP

Les tests Plug-and-Play (PnP) exécutent différents chemins de code liés à PnP dans les composants du pilote et du mode utilisateur. Les tests PnP doivent être exécutés avec driver Verifier activé sur l’ordinateur de test. Pour plus d’informations sur l’activation du vérificateur de pilotes, consultez les propriétés du vérificateur de pilotes pour les projets de pilotes.

À propos des tests de suppression d’appareil

• Test de suppression du périphérique PNP
• Test de suppression d’appareil PNP Cancel

Le test de suppression d’appareil englobe IRP_MN_QUERY_REMOVE_DEVICE, IRP_MN_CANCEL_REMOVE_DEVICE et IRP_MN_REMOVE_DEVICE.

Le test tente d’installer son pilote de filtre supérieur sur la pile de périphériques cibles. Cette tentative entraîne une IRP de suppression de requête.

Si cette requête IRP de suppression échoue, le test redémarre l’ordinateur pour placer le pilote de filtre dans la pile de périphériques. Si la demande de suppression n’est pas bloquée, la pile de périphériques est supprimée et redémarrée avec le pilote de filtre sur la pile de périphériques.

Le test, à l’aide des API d’installation, entraîne l’envoi d’un IRP de suppression de requête à la pile d’appareils. Le pilote de filtre échoue à traiter cette demande de suppression. Par conséquent, un IRP d’annulation est envoyé. Le pilote de filtre va confirmer que l'annulation de la suppression a été effectuée avec succès.

Ensuite, l’application de test appelle le programme d’installation de classe approprié et tous les co-programmes d’installation inscrits pour désactiver ou activer et supprimer ou réenumer l’appareil (cela teste la gestion des classes et des co-programmes d’installation de DIF_PROPERTYCHANGE avec DICS_DISABLE, DICS_ENABLE et DICS_PROPCHANGE). Lors de la réception de IRP_MN_REMOVE_DEVICE, le pilote de filtre affirme que les pilotes inférieurs l’ont terminé correctement.

Chacune de ces étapes implique une demande de suppression préliminaire. Si cette demande est bloquée, l’appareil ne sera pas supprimé. Vous pouvez choisir de refuser une demande de suppression le cas échéant, par exemple lors de la diffusion de vidéos sur une caméra USB ou si l’appareil cible se trouve dans le chemin de démarrage ou de pagination. N’oubliez pas que l’échec de toutes les demandes de suppression n’est généralement pas une bonne pratique. L’échec de toutes les demandes de suppression ne garantit pas que le pilote ne recevra jamais de suppression, car un IRP de suppression sera toujours émis après une suppression surprise, ou si quelqu’un dans la pile d’appareils échoue à un IRP de démarrage.

À propos du test de suppression surprise

• Test de retrait surprise du périphérique (PNP)

Le test De suppression surprise englobe IRP_MN_SURPRISE_REMOVAL suivi de IRP_MN_REMOVE_DEVICE.

Comme pour les tests précédents, l’application de test tente d’ajouter un filtre supérieur à la pile d’appareils cible, puis redémarre la pile. Si cette tentative ne réussit pas, le test redémarre l’ordinateur.

Lorsqu’il est déclenché par l’application de test, le pilote de filtre entraîne l’envoi d’un IRP_MN_SURPRISE_REMOVAL à la pile de périphériques, suivi d’un IRP_MN_REMOVE_DEVICE. Le pilote de filtre assurera que ces deux IRP (paquets de requêtes I/O) sont terminés avec succès par les pilotes de niveau inférieur.

Une fois le test de suppression surprise terminé, l’appareil sera désinstallé et réenumeré, ce qui supprimera également le pilote de filtre de la pile.

À propos des tests de rééquilibrage

• Test de l'appareil PNP Stop (Rééquilibrage)
• Test du rééquilibrage PNP Demande de nouvelles ressources pour le périphérique
• Test d’échec de rééquilibrage et redémarrage de l’appareil PNP
• Test du dispositif d'arrêt PNP

Comme pour le test de suppression, l’application de test tente d’ajouter un filtre supérieur à la pile d’appareils cible, puis redémarre la pile en utilisant SetupDiCallClassInstaller avec DIF_PROPERTYCHANGE. Si cette tentative n’a pas réussi (autrement dit, si un élément sur la pile de périphériques cibles a échoué dans la suppression de la requête IRP), le test redémarre l’ordinateur afin de tester le rééquilibrage.

Selon le test de rééquilibrage que vous choisissez, les événements suivants se produisent :

1. Test d’appareil PNP Stop (Rééquilibrage) Ce test lance une procédure de rééquilibrage qui entraîne un IRP_MN_QUERY_STOP_DEVICE PnP IRP auprès du pilote de périphérique.

   Si un pilote au sein de la pile échoue cet IRP, la procédure de rééquilibrage est abandonnée. Notez que dans Windows Vista, il existe une prise en charge du rééquilibrage multiniveaux. Si un rééquilibrage est démarré sur un nœud d'appareil non-feuille, toutes les piles de dispositifs présentes dans l’arborescence des appareils avec ce nœud d'appareil en tant que racine passent également par un rééquilibrage. Et si l’une des piles des dispositifs enfants échoue lors de la requête d'arrêt, la procédure de rééquilibrage complète est abandonnée. Les pilotes ne doivent donc pas échouer à l’arrêt de la requête sans une véritable raison de le faire. Si cette défaillance se produit, le gestionnaire PnP envoie une annulation d'arrêt (IRP_MN_CANCEL_STOP) à toutes les piles d'appareils pour lesquelles la requête d'arrêt avait été envoyée.

   Si toutes les piles d’appareils impliquées ont réussi l’arrêt de la requête, le test continue avec le rééquilibrage et envoie les IRP_MN_QUERY_RESOURCE_REQUIREMENTS et IRP_MN_FILTER_RESOURCE_REQUIREMENTS IRPS pour trouver les besoins en ressources des appareils.

   Après ce point, deux chemins différents sont possibles selon que l’appareil cible consomme des ressources ou non :

   • Si l’appareil ne consomme aucune ressource, le gestionnaire PnP lui-même envoie une annulation d’arrêt (IRP_MN_CANCEL_STOP_DEVICE) pour optimiser le fonctionnement.

     Si l’appareil consomme réellement des ressources, la procédure de rééquilibrage est effectuée avec les IRP_MN_STOP_DEVICE et les IRP_MN_START_DEVICE IRPs.

   Avec cette option, les ressources de l’appareil ne changent pas.

2. Test PNP Cancel Stop Device : ce test lance une procédure de rééquilibrage, mais le pilote de filtre échoue délibérément à l’arrêt de requête IRP. L'ordre des IRPs ressemble à IRP_MN_QUERY_STOP_DEVICE (qui échoue par le pilote de filtre au démarrage, provoquant une annulation de rééquilibrage) et IRP_MN_CANCEL_STOP_DEVICE.

   Avec cette option, les ressources de l’appareil ne changent pas

3. Test de rééquilibrage PNP pour un nouvel appareil nécessitant des ressources Ce test initie un rééquilibrage et manipule également les exigences de ressources de l’appareil pour maximiser les chances que de nouvelles ressources soient effectivement allouées à celui-ci. Cette option permet également à un appareil sans ressources d’effectuer la procédure complète de rééquilibrage :

   1. Premièrement, le rééquilibrage simple est démarré, provoquant les IRPs suivants :

      • IRP_MN_QUERY_STOP_DEVICE (en supposant que cet IRP est traité par tous les pilotes. Le test a déjà couvert le cas où cet IRP a échoué.)
      • IRP_MN_QUERY_RESOURCE_REQUIREMENTS
      • IRP_MN_FILTER_RESOURCE_REQUIREMENTS. En réponse à cet IRP, tout en remontant, le pilote de filtre agit en fonction du fait que le périphérique consomme des ressources ou non :
        • Si l’appareil n’a aucune exigence de ressource, le filtre affecte une fausse ressource.
        • Si l’appareil a une exigence de ressource, il tente de restructurer la liste des besoins en ressources de telle sorte qu’il optimise la probabilité de modifier l’affectation actuelle. Par exemple, si un appareil a besoin de 2 octets de mémoire n’importe où entre 00 et FF et est actuellement affecté à 3A-3B, modifiez de sorte que la nouvelle exigence de ressource (par ordre de préférence) ressemble à 00-39 ou 3C-FF ou 3A-3B. De même, si la liste des conditions requises pour les ressources de l’appareil a des exigences alternatives, elle modifie leur ordre afin que l’autre exigence soit fournie plus haut dans la liste.

   2. À présent, l’appareil doit toujours effectuer la procédure de rééquilibrage.

      IRP_MN_STOP_DEVICE

      IRP_MN_START_DEVICE (les nouvelles ressources allouées. Si des exigences fausses ont été créées, masquez les nouvelles ressources des pilotes réels.)

4. Test de redémarrage de l'appareil suite à l'échec du rééquilibrage PNP Ce test initie un rééquilibrage, mais lorsque le pilote de filtre reçoit le signal de démarrage après le rééquilibrage, il échoue délibérément, ce qui provoque une requête IRP de retrait surprise suivie d'une requête IRP de retrait.

   Tout d’abord, il démarre la procédure de rééquilibrage et vérifie que le pilote obtient un arrêt et un démarrage en générant une exigence fictive de ressource pour un appareil qui ne consomme aucune ressource.

   • IRP_MN_QUERY_STOP_DEVICE (en supposant que cet IRP est traité par tous les pilotes. Le test a déjà couvert le cas où cet IRP a échoué.)
   • IRP_MN_QUERY_RESOURCE_REQUIREMENTS
   • IRP_MN_FILTER_RESOURCE_REQUIREMENTS (Si la nécessité réelle en ressources est nulle, le filtre attribue une nécessité en ressources factice, afin qu'il y ait un arrêt et un démarrage.)
   • IRP_MN_STOP_DEVICE
   • IRP_MN_START_DEVICE (le filtre échoue sur cette IRP lors de la montée. Cette action provoque la suppression de l’IRP surprise.)
   • IRP_MN_SURPRISE_REMOVAL
   • IRP_MN_REMOVE

   Une fois le test de rééquilibrage terminé, le périphérique sera désinstallé et réénuméré, supprimant également le pilote de filtre de la pile.

Codes d’erreur de l’appareil

Si le test fournit un message d’erreur indiquant que l’état de l’appareil n’est pas OK, vous pouvez en savoir plus sur l’état de l’appareil via device Manager. Pour obtenir un résumé des différents codes d’erreur de l’appareil, consultez Les messages d’erreur du Gestionnaire de périphériques.

Déboguer les échecs d'installation à l'aide des journaux de l'API d'installation

Les journaux de l’API d’installation (setupapi.app.log et setupapi.dev.log) peuvent contenir des informations utiles pour déboguer les échecs d’installation du pilote enregistrés par ce test. Les journaux de l’API d’installation se trouvent sous %windir%répertoire \inf\ sur le système de test.

Pour augmenter le niveau de détail et l’utilité potentielle de ces journaux, définissez la clé de Registre suivante sur 0x2000FFFF avant d’exécuter le test de réinstallation :

HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\CurrentVersion\Setup\LogLevel

Rubriques connexes

Comment tester un pilote au moment de l’exécution à l’aide de Visual Studio

Comment sélectionner et configurer les tests de base de l’appareil

Tests de base de l’appareil

Plug-ins WDTF simple d’E/S fournis

Guide pratique pour tester un pilote au moment de l’exécution à partir d’une invite de commandes