IRP_MN_QUERY_DEVICE_RELATIONS

Article
06/15/2023

Le gestionnaire PnP envoie cette requête pour déterminer certaines relations entre les appareils. Les types de pilotes suivants gèrent cette demande :

Les pilotes de bus doivent gérer les demandes BusRelations pour leur adaptateur ou contrôleur (bus FDO). Les pilotes de filtre peuvent gérer les requêtes BusRelations .
Les pilotes de bus doivent gérer les demandes TargetDeviceRelation pour leurs appareils enfants (PDO enfants).
Les pilotes de fonction et de filtre peuvent gérer les demandes RemovalRelations et PowerRelations .
Les pilotes de bus peuvent gérer les demandes EjectionRelations pour leurs appareils enfants (PDO enfants).

Valeur

0x07

Code majeur

IRP_MJ_PNP

Date d’envoi

Le gestionnaire PnP envoie cette IRP pour collecter des informations sur les appareils ayant une relation avec l’appareil spécifié.

Le gestionnaire PnP interroge les BusRelations (appareils enfants) d’un appareil lorsque l’appareil est énuméré et à d’autres moments pendant que l’appareil est actif, par exemple lorsqu’un pilote appelle la routine IoInvalidateDeviceRelations pour indiquer qu’un appareil enfant est arrivé ou parti.

Le gestionnaire PnP interroge les éléments RemovalRelations d’un appareil avant de supprimer les pilotes d’un appareil. Le gestionnaire PnP interroge RemovalRelations et EjectionRelations avant d’éjecter un appareil.

Le gestionnaire PnP interroge le TargetDeviceRelation d’un appareil lorsqu’un pilote ou une application en mode utilisateur s’inscrit pour la notification PnP d’un EventCategoryTargetDeviceChange sur l’appareil. Le gestionnaire PnP interroge l’appareil associé à un objet de fichier particulier. IRP_MN_QUERY_DEVICE_RELATIONS est le seul IRP PnP qui a un paramètre d’objet de fichier valide. Un pilote peut interroger une pile d’appareils pour TargetDeviceRelation. Un pilote n’a pas besoin de fournir un objet fichier lors de l’envoi de sa requête TargetDeviceRelation .

Le gestionnaire PnP interroge les powerRelations d’un appareil lorsque le pilote de l’appareil appelle IoInvalidateDeviceRelations pour indiquer que l’ensemble d’appareils avec lesquels cet appareil a une relation implicite de gestion de l’alimentation a changé. Les demandes PowerRelations sont prises en charge à partir de Windows 7.

Pour les requêtes BusRelations, RemovalRelations, EjectionRelations et PowerRelations , le gestionnaire PnP envoie IRP_MN_QUERY_DEVICE_RELATIONS à IRQL = PASSIVE_LEVEL dans le contexte d’un thread système.

Pour les requêtes TargetDeviceRelation , le gestionnaire PnP envoie cette IRP à IRQL = PASSIVE_LEVEL dans un contexte de thread arbitraire.

Paramètres d’entrée

Le membre Parameters.QueryDeviceRelations.Type de la structure IO_STACK_LOCATION spécifie le type de relations interrogées. Les valeurs possibles incluent BusRelations, EjectionRelations, RemovalRelations, TargetDeviceRelation et PowerRelations.

Le membre FileObject de la structure IO_STACK_LOCATION actuelle pointe vers un objet de fichier valide uniquement si Parameters.QueryDeviceRelations.Type est TargetDeviceRelation.

Paramètres de sortie

Retourné dans le bloc d’E/S status.

Bloc d’état E/S

Un pilote définit Irp-IoStatus.Status> sur STATUS_SUCCESS ou sur un status d’échec tel que STATUS_INSUFFICIENT_RESOURCES.

En cas de réussite, un pilote définit Irp-IoStatus.Information> sur un pointeur PDEVICE_RELATIONS qui pointe vers les informations de relations demandées. La structure DEVICE_RELATIONS est définie comme suit :

typedef struct _DEVICE_RELATIONS {
  ULONG  Count;
  PDEVICE_OBJECT  Objects[1];  // variable length
} DEVICE_RELATIONS, *PDEVICE_RELATIONS;

Opération

Si un pilote retourne des relations en réponse à cette IRP_MN_QUERY_DEVICE_RELATIONS, le pilote alloue une structure de DEVICE_RELATIONS à partir de la mémoire paginée qui contient un nombre et le nombre approprié de pointeurs d’objets d’appareil. Le gestionnaire PnP libère la structure quand elle n’est plus nécessaire. Si un pilote remplace une structure DEVICE_RELATIONS qu’un autre pilote a allouée, le pilote doit libérer la structure précédente.

Un pilote doit référencer l’AOP de tout appareil qu’il signale dans cet IRP (ObReferenceObject). Le gestionnaire PnP supprime la référence le cas échéant.

Un pilote de fonction ou de filtre doit être prêt à gérer cette IRP pour un appareil à tout moment une fois que sa routine AddDevice est terminée pour l’appareil. Les pilotes de bus doivent être prêts à gérer une requête pour BusRelations immédiatement après l’énumération d’un appareil.

Pour connaître les règles générales relatives à la gestion des Plug-and-Play les IIP mineurs, consultez Plug-and-Play.

Les sous-sections suivantes décrivent les actions spécifiques de gestion des différentes requêtes.

Demande BusRelations

Lorsque le gestionnaire PnP interroge les relations de bus (périphériques enfants) d’un adaptateur ou d’un contrôleur, le pilote de bus doit retourner une liste de pointeurs vers les PDO de tous les appareils physiquement présents sur le bus. Le pilote de bus signale tous les appareils, qu’ils aient été démarrés ou non. Le pilote de bus peut avoir besoin d’allumer son périphérique de bus pour déterminer quels enfants sont présents.

Avertissement Un objet d’appareil ne peut pas être passé à une routine qui prend un PDO comme argument tant que le gestionnaire PnP n’a pas créé un nœud d’appareil (devnode) pour cet objet. (Si le pilote transmet un objet d’appareil, le système présente un bogue case activée avec l'0xCA de vérification des bogues : PNP_DETECTED_FATAL_ERROR.) Le gestionnaire PnP crée le devnode en réponse à la demande IRP_MN_QUERY_DEVICE_RELATIONS. Le pilote peut supposer en toute sécurité que le devnode du PDO a été créé lorsqu’il reçoit une demande de IRP_MN_QUERY_RESOURCE_REQUIREMENTS .

Le pilote de bus qui répond à cette IRP est le pilote de fonction de l’adaptateur de bus ou du contrôleur, et non le pilote de bus parent pour le bus auquel l’adaptateur ou le contrôleur est connecté. Les pilotes de fonction pour les appareils non bus ne gèrent pas cette requête. Ces pilotes passent simplement l’IRP au pilote inférieur suivant. (Voir la figure suivante.) Les pilotes de filtre ne gèrent généralement pas cette requête.

Sur Windows Vista et les systèmes d’exploitation ultérieurs, nous recommandons que les pilotes arrêtent toujours le IRP_MN_QUERY_DEVICE_RELATIONS IRP et terminent son traitement ultérieurement. Cet ordre permet au système de traiter les requêtes de relation de bus de manière asynchrone. (Sur les systèmes d’exploitation antérieurs à Windows Vista, les pilotes peuvent retourner en toute sécurité STATUS_PENDING à partir de leurs routines de répartition, mais le gestionnaire PnP ne chevauche pas la requête de relation de bus avec toute autre opération.)

Le diagramme suivant montre comment les pilotes gèrent une requête pour les relations de bus.

diagramme illustrant les pilotes gérant une requête pour les relations de bus.

Dans l’exemple illustré dans la figure, le gestionnaire PnP envoie un IRP_MN_QUERY_DEVICE_RELATIONS pour BusRelations aux pilotes du périphérique hub USB. Le gestionnaire PnP demande une liste des enfants de l’appareil hub.

Comme pour tous les fournisseurs d’intégration PnP, le gestionnaire PnP envoie l’IRP au pilote supérieur de la pile de périphériques pour l’appareil.
Un pilote de filtre facultatif peut être le pilote supérieur de la pile. Un pilote de filtre ne gère généralement pas cette IRP ; il passe l’IRP dans la pile. Un pilote de filtre peut gérer cette IRP, par exemple, si le pilote expose un appareil non énumérable sur le bus.
Le pilote de bus hub USB gère l’IRP.

Pilote de bus hub USB :
- Crée un PDO pour n’importe quel appareil enfant qui n’en a pas encore.
- Marque l’AOP inactif pour tout appareil qui n’est plus présent dans le bus. Le pilote de bus ne supprime pas ces PDO.Pour plus d’informations sur le moment où supprimer les PDO, consultez Suppression d’un appareil.
- Signale tous les appareils enfants présents sur le bus.
  
  Pour chaque périphérique enfant, le pilote de bus fait référence à l’AOP et place un pointeur vers l’AOP dans la structure DEVICE_RELATIONS.
  
  Cet exemple contient deux PDO : l’un pour le joystick et l’autre pour le clavier.
  
  Le pilote de bus doit case activée si un autre pilote a déjà créé une structure DEVICE_RELATIONS pour cette IRP. Si c’est le cas, le pilote de bus doit ajouter aux informations existantes.
  
  S’il n’y a pas d’appareil enfant présent sur le bus, le pilote définit le nombre sur zéro dans la structure DEVICE_RELATIONS et retourne la réussite.
- Définit les valeurs appropriées dans le bloc d’E/S status et transmet l’IRP au pilote inférieur suivant. Le pilote de bus de l’adaptateur ou du contrôleur ne termine pas le IRP.
Un filtre inférieur facultatif, s’il est présent, ne gère généralement pas cette IRP. Un tel pilote de filtre transmet l’IRP dans la pile. Si un pilote à filtre inférieur gère cette IRP, il peut ajouter des ADO à la liste des appareils enfants, mais il ne doit pas supprimer les PDO créés par d’autres pilotes.
Le pilote de bus parent ne gère pas cette IRP, sauf s’il s’agit du seul pilote de la pile d’appareils (l’appareil est en mode brut). Comme pour tous les IRP PnP, le pilote de bus parent termine l’IRP avec IoCompleteRequest.

S’il existe un ou plusieurs pilotes de filtre de bus dans la pile d’appareils, ces pilotes peuvent gérer l’IRP en descendant vers le pilote de bus et/ou sur le chemin de l’IRP de la pile d’appareils (s’il existe des routines IoCompletion ). Selon les règles pnP IRP, un tel pilote peut ajouter des PDO à l’IRP en descendant de la pile et/ou modifier la liste des relations sur la marche arrière de l’IRP (dans les routines IoCompletion ).

EjectionRelations Request

Un pilote retourne des pointeurs vers des PDO de tous les appareils qui peuvent être physiquement supprimés du système lorsque l’appareil spécifié est éjecté. Ne signalez pas les PDO des enfants de l’appareil ; le gestionnaire PnP demande toujours que les appareils enfants soient supprimés avant leur appareil parent.

Le gestionnaire PnP envoie une IRP_MN_EJECT IRP à un appareil en cours d’éjection. Le pilote d’un tel appareil reçoit également un IRP de suppression. Les relations d’éjection de l’appareil reçoivent un IRP IRP_MN_REMOVE_DEVICE (et non un IRP IRP_MN_EJECT ).

Seul un pilote de bus parent peut répondre à une requête EjectionRelations pour l’un de ses appareils enfants. Les pilotes de fonction et de filtre doivent les passer au pilote inférieur suivant dans la pile de périphériques. Si un pilote de bus reçoit cette IRP comme pilote de fonction pour son adaptateur ou son contrôleur, il effectue les tâches d’un pilote de fonction et doit passer l’IRP au pilote inférieur suivant.

Demande PowerRelations

À compter de Windows 7, la requête PowerRelations permet à un pilote de spécifier une relation de gestion de l’alimentation en dehors de la relation conventionnelle entre un bus parent qui prend en charge l’énumération PnP et un appareil enfant énuméré sur le bus. Par exemple, si un pilote de bus ne peut pas énumérer un appareil enfant sur le bus, ou si un appareil est un enfant de plusieurs bus, la requête PowerRelations peut décrire les relations d’alimentation de l’appareil enfant avec le bus ou les bus.

Le gestionnaire PnP émet une requête PowerRelations pour un appareil lorsque le pilote de l’appareil appelle la routine IoInvalidateDeviceRelations et spécifie une valeur de paramètre Type de PowerRelations.

En réponse à cette requête, le pilote de l’appareil cible (c’est-à-dire l’appareil qui est la cible de la requête) fournit une structure DEVICE_RELATIONS qui contient des pointeurs vers les PDO de tous les autres appareils qui doivent être activés par le gestionnaire d’alimentation avant que l’appareil cible soit activé. À l’inverse, ces autres appareils ne doivent être désactivés qu’une fois l’appareil cible désactivé. Le gestionnaire d’alimentation utilise les informations de la requête pour garantir que ces appareils sont activés et désactivés dans le bon ordre.

Cette garantie de classement s’applique uniquement aux transitions d’état de veille globale du système, qui incluent les transitions vers et depuis les états d’alimentation système S1, S2, S3 (veille), S4 (mise en veille prolongée) et S5 (arrêt). La garantie de classement PowerRelations ne s’applique pas aux transitions d’état d’alimentation des appareils Dx pendant que le système reste dans l’état système S0 (en cours d’exécution), sauf dans le cas des transitions de gestion de l’alimentation du runtime dirigé (DFx).

Si l’appareil cible se trouve sur le chemin d’accès d’un fichier spécial (tel que le fichier de pagination, le fichier de mise en veille prolongée ou le fichier de vidage sur incident), le pilote de l’appareil cible doit effectuer une étape supplémentaire lorsqu’il gère une IRP_MN_DEVICE_USAGE_NOTIFICATION IRP dans laquelle InPath a la valeur TRUE. Ce pilote doit s’assurer que les appareils dont les PDO sont fournis pour la requête PowerRelations peuvent également prendre en charge le chemin d’accès du périphérique pour le fichier spécial. Pour confirmer cette prise en charge, le pilote de l’appareil cible doit d’abord envoyer l’IRP IRP_MN_DEVICE_USAGE_NOTIFICATION à chacun de ces appareils, et cette IRP doit spécifier le même UsageNotification.Type que l’appareil cible. Ce n’est que si tous les appareils qui reçoivent cette IRP terminent l’IRP avec un code de status réussi que le pilote de l’appareil cible termine correctement son IRP_MN_DEVICE_USAGE_NOTIFICATION IRP. Sinon, ce pilote doit effectuer cette IRP avec un échec status code.

Lorsque ce même pilote gère un IRP IRP_MN_DEVICE_USAGE_NOTIFICATION pour lequel InPath a la valeur FALSE, le pilote doit envoyer l’IRP IRP_MN_DEVICE_USAGE_NOTIFICATION au même ensemble d’appareils dépendants que pour le cas où InPath a la valeur TRUE. Toutefois, le pilote ne doit jamais terminer cette IRP avec un échec status code lorsque InPath a la valeur FALSE.

Le pilote qui répond à la requête PowerRelations doit s’inscrire aux notifications de modification d’appareil cible sur tous les appareils dont les PDO sont fournis pour la requête PowerRelations . Pour s’inscrire à ces notifications, le pilote peut appeler la routine IoRegisterPlugPlayNotification et spécifier une valeur de paramètre EventCategory EventCategoryTargetDeviceChange.

Demande RemovalRelations

Un pilote retourne des pointeurs vers les PDO de tous les appareils dont les pilotes doivent être supprimés lorsque les pilotes de l’appareil spécifié sont supprimés. Ne signalez pas les PDO des enfants de l’appareil ; Le gestionnaire PnP demande déjà la suppression d’appareils enfants avant de supprimer un appareil.

L’ordre dans lequel les relations de suppression sont supprimées n’est pas défini.

N’importe quel pilote de la pile de périphériques peut gérer ce type de requête de relations. Un pilote de fonction ou de filtre gère l’IRP avant de le transmettre au pilote inférieur suivant. Un pilote de bus gère l’IRP, puis le termine.

Requête TargetDeviceRelation

La requête TargetDeviceRelation permet au gestionnaire PnP d’interroger une pile d’appareils non PnP pour l’AOP dans la pile d’appareils PnP qui contrôle le matériel.

En général, les pilotes avancent les IRP_MN_QUERY_DEVICE_RELATIONS IRP vers le bas de leur pile jusqu’à ce que l’IRP atteigne le bas d’une pile de périphériques particulière. Un pilote situé au bas d’une pile non PnP transfère ou réécrit l’IRP à la pile PnP appropriée. Par exemple, le gestionnaire PnP peut envoyer une requête TargetDeviceRelation à l’objet d’appareil situé en haut de la pile du système de fichiers, qui est une pile non PnP. Chaque objet d’appareil dans la pile du système de fichiers transmettait la requête à l’objet d’appareil situé en dessous jusqu’à ce que la requête atteigne l’objet d’appareil situé en bas de la pile. L’objet d’appareil le plus bas de la pile transfère ou réécrit la requête TargetDeviceRelation à l’objet d’appareil en haut de la pile de volumes de stockage PnP, puis la requête est transmise à l’AOP en bas de la pile de volumes de stockage.

La liste suivante récapitule les situations dans lesquelles vous pouvez acquérir en toute sécurité un pointeur vers l’AOP en bas d’une pile d’appareils PnP :

Objet Device dans un PnP

Un objet d’appareil qui se trouve dans une pile d’appareils PnP en apprend plus sur l’AOP de la pile lorsque la routine AddDevice pour l’appareil est appelée. Le pilote peut mettre en cache en toute sécurité le pointeur vers l’AOP si l’utilisation du pointeur est correctement synchronisée avec les messages IRP_MN_REMOVE_DEVICE entrants à l’aide des routines de suppression de verrou.
Objet d’appareil dans une pile non PnP, pas en bas de la pile

Pour un objet d’appareil qui ne se trouve pas au bas d’une pile non PnP, un pilote peut envoyer une requête TargetDeviceRelation pour obtenir un pointeur vers l’AOP en bas de la pile de périphériques PnP correspondante.
Objet File pour l’appareil

Étant donné un objet fichier pour l’appareil, un pilote peut appeler IoGetRelatedDeviceObject pour obtenir l’objet de l’appareil, puis suivre les instructions de l’élément de liste précédent.
Gérer l’objet de l’appareil

Avec un handle pour l’objet de périphérique, un pilote peut appeler ObReferenceObjectByHandle pour obtenir l’objet fichier de l’appareil, puis suivre les instructions de l’élément de liste précédent.

Un pilote de bus parent doit gérer une requête de relations TargetDeviceRelation pour ses appareils enfants. Le pilote de bus référence l’AOP de l’appareil enfant avec ObReferenceObject et retourne un pointeur vers l’AOP dans la structure DEVICE_RELATIONS . Il n’y a qu’un seul pointeur PDO dans la structure pour ce type de relation. Le gestionnaire PnP supprime la référence à l’AOP lorsque le pilote ou l’application se désinscrit pour la notification sur l’appareil.

Seul un pilote de bus parent répond à une requête TargetDeviceRelation . Les pilotes de fonction et de filtre doivent les passer au pilote inférieur suivant dans la pile de périphériques. Si un pilote de bus reçoit cette IRP en tant que pilote de fonction pour son adaptateur ou contrôleur, il effectue les tâches d’un pilote de fonction et doit passer l’IRP au pilote inférieur suivant.

Si un pilote ne se trouve pas dans une pile basée sur PDO, le pilote envoie un nouvel IRP de requête cible-appareil-relation à l’objet de périphérique associé au handle de fichier sur lequel le pilote effectue des E/S.

Envoi de cette IRP

Les pilotes ne doivent pas envoyer IRP_MN_QUERY_DEVICE_RELATIONS pour demander BusRelations. Les pilotes ne sont pas limités à l’envoi de cette IRP pour RemovalRelations ou EjectionRelations, mais il est peu probable qu’un pilote le fasse.

Les pilotes peuvent interroger une pile de périphériques pour TargetDeviceRelation. Pour plus d’informations sur l’envoi des IRP, consultez Gestion des irps . Les étapes suivantes s’appliquent spécifiquement à cette IRP :

Définissez les valeurs dans l’emplacement de pile d’E/S suivant de l’IRP : définissez MajorFunction sur IRP_MJ_PNP, définissez MinorFunctionsur IRP_MN_QUERY_DEVICE_RELATIONS, définissez Parameters.QueryDeviceRelations.Type sur TargetDeviceRelation et définissez Irp-FileObject> sur un objet de fichier valide.
Initialisez IoStatus.Status sur STATUS_NOT_SUPPORTED.

Si un pilote a envoyé cette IRP pour obtenir l’AOP à signaler en réponse à un IRP_MN_QUERY_DEVICE_RELATIONS pour TargetDeviceRelation reçu par le pilote, il signale l’AOP et libère la structure de relations retournée lorsque l’IRP se termine. Si un pilote a lancé cette IRP pour une autre raison, le pilote libère la structure de relations lorsque l’IRP se termine et déréférence l’AOP lorsqu’il n’est plus nécessaire.