IRP_MN_DEVICE_USAGE_NOTIFICATION

Article
06/15/2023

Les composants système envoient cette IRP pour demander aux pilotes d’un appareil si l’appareil peut prendre en charge un fichier spécial. Les fichiers spéciaux incluent les fichiers de pagination, les fichiers de vidage et les fichiers de mise en veille prolongée. Si tous les pilotes de l’appareil réussissent l’IRP, le système crée le fichier spécial. Le système envoie également cette IRP pour informer les pilotes qu’un fichier spécial a été supprimé de l’appareil.

Les pilotes de fonction doivent gérer cette IRP si leur appareil peut contenir un fichier de pagination, un fichier de vidage ou un fichier de mise en veille prolongée. Les pilotes de filtre doivent gérer cette IRP si le pilote de fonction qu’ils filtrent gère l’IRP. Les pilotes de bus doivent gérer cette IRP pour leur adaptateur ou contrôleur (bus FDO) et pour leurs appareils enfants (PDO enfants).

Valeur

0x16

Code majeur

IRP_MJ_PNP

Date d’envoi

Le système envoie cette IRP lorsqu’il crée ou supprime un fichier de pagination, un fichier de vidage ou un fichier de mise en veille prolongée. Si un appareil a une relation de gestion de l’alimentation qui ne relève pas de la relation parent-enfant conventionnelle, le pilote peut envoyer cette IRP pour propager les informations d’utilisation des appareils à une autre pile d’appareils. Pour plus d’informations, consultez la description de la demande PowerRelations dans IRP_MN_QUERY_DEVICE_RELATIONS.

Les composants système et les pilotes envoient cette IRP au PASSIVE_LEVEL IRQL dans un contexte de thread arbitraire.

Paramètres d’entrée

Le membre Parameters.UsageNotification.InPath de la structure IO_STACK_LOCATION est booléen. Lorsque ce paramètre a la valeur TRUE, le système crée un fichier de pagination, de vidage sur incident ou de mise en veille prolongée sur l’appareil. Lorsque InPath a la valeur FALSE, un tel fichier a été supprimé de l’appareil.

Parameters.UsageNotification.Type est une énumération indiquant le type de fichier. Ce paramètre a l’une des valeurs suivantes : DeviceUsageTypePaging, DeviceUsageTypeDumpFile ou DeviceUsageTypeHibernation.

Paramètres de sortie

None

Bloc d’état E/S

Les pilotes définissent Irp-IoStatus.Status> sur STATUS_SUCCESS ou sur un status d’erreur approprié.

Les pilotes ne modifient pas le champ Irp-IoStatus.Information> ; il reste à zéro, tel que défini par le composant qui envoie l’IRP.

Opération

Un pilote gère cette IRP sur le chemin de l’IRP vers le bas de la pile des appareils et sur le chemin de l’IRP de remonter la pile.

Un pilote répond à cette IRP avec une procédure semblable à la suivante :

Si Parameters.UsageNotification.InPath a la valeur TRUE, déterminez si l’appareil prend en charge le fichier spécial.

Un pilote doit tester le ou les types Parameters.UsageNotification.Type spécifiques qu’il peut prendre en charge. D’autres types de notification peuvent être ajoutés à l’avenir.

Consultez plus d’informations ci-dessous décrivant les actions requises pour prendre en charge chaque type de notification.

Si Parameters.UsageNotification.InPath a la valeur TRUE et que le pilote ne peut pas prendre en charge le fichier spécial sur le périphérique, le pilote doit effectuer l’IRP avec un échec status.
Si l’appareil prend en charge le fichier spécial :
1. Prenez les mesures appropriées pour refléter que l’appareil contient désormais, ou ne contient plus, un fichier spécial.
  
  Un pilote incrémente ou décrémente généralement un compteur. Par exemple, si Parameters.UsageNotification.Type a la valeur DeviceUsageTypePaging et Parameters.UsageNotification.InPath a la valeur TRUE, incrémentez le nombre de fichiers de pagination sur l’appareil. Certaines routines de répartition des pilotes doivent case activée le ou les compteurs.
  
  Un appareil qui contient un fichier spécial ne doit pas être désactivé. Un pilote peut appeler IoInvalidateDeviceState, en demandant au gestionnaire PnP d’interroger à nouveau les informations d’état du périphérique PnP de l’appareil. En réponse à la IRP_MN_QUERY_PNP_DEVICE_STATE IRP résultante, le pilote doit définir l’indicateur PNP_DEVICE_NOT_DISABLEABLE.
  
  Si InPath a la valeur FALSE, un pilote définit le bit DO_POWER_PAGABLE dans son objet de périphérique pour l’appareil.
2. Propagez les informations d’utilisation de l’appareil à tous les appareils associés qui nécessitent les informations.
  
  Dans le cadre de sa gestion d’un IRP_MN_DEVICE_USAGE_NOTIFICATION IRP, un pilote peut être amené à transmettre les informations à une ou plusieurs autres piles d’appareils. Un tel pilote crée un IRP_MN_DEVICE_USAGE_NOTIFICATION IRP (ou IRPs) et les envoie à la pile de périphériques (ou piles) appropriée. Le pilote doit attendre l’achèvement des IRP de notification d’utilisation des appareils qu’il envoie avant que le pilote termine le traitement de l’IRP d’utilisation du périphérique qu’il a reçu.
  
  L’identification des appareils associés est propre au périphérique et au pilote. En règle générale, un pilote envoie l’IRP à d’autres pilotes auxquels il envoie des demandes d’E/S pour le fichier. Lorsqu’un pilote de bus gère cette demande pour un appareil enfant, il doit envoyer un IRP de notification d’utilisation à la pile de périphériques pour le parent de l’appareil.
  
  Par exemple, lorsque ftdisk exécute un jeu de bandes à cinq disques, il propage des notifications de pagination à chacun de ces cinq disques, car chacun de ces appareils peut être requis pour gérer les opérations de pagination des fichiers.
3. Dans un pilote de fonction ou de filtre, définissez une routine IoCompletion .
4. Dans un pilote de fonction ou de filtre, définissez Irp-IoStatus.Status> sur STATUS_SUCCESS, configurez l’emplacement de pile suivant et transmettez l’IRP au pilote inférieur suivant avec IoCallDriver. Ne terminez pas le IRP.
  
  Dans un pilote de bus qui gère l’IRP pour un PDO enfant : définissez Irp-IoStatus.Status> et terminez l’IRP (IoCompleteRequest).
5. Pendant le traitement de la fin de l’IRP :
  
  Si une routine IoCompletion détecte qu’un pilote inférieur a échoué à l’IRP, la fonction ou le pilote de filtre doit annuler toutes les opérations qu’elle a effectuées en réponse à l’IRP et propager l’erreur. Si la fonction ou le pilote de filtre a propagé les informations d’utilisation à d’autres piles de périphériques, le pilote doit envoyer une autre IRP d’utilisation à ces piles pour les informer de la défaillance.
  
  Si status est STATUS_SUCCESS et Qu’InPath a la valeur TRUE, effacez le bit DO_POWER_PAGABLE.

Consultez Plug-and-Play pour connaître les règles générales de gestion Plug-and-Play irps mineurs.

Prise en charge de la pagination, du vidage sur incident et des fichiers de mise en veille prolongée sur un appareil

Lorsque l’un des nombres de fichiers spéciaux d’un pilote est différent de zéro, le pilote doit prendre en charge la présence du ou des fichiers spéciaux sur son appareil (ou un périphérique descendant).

Pour un fichier DeviceUsageTypePaging créé sur son appareil, un pilote doit effectuer les opérations suivantes :

Verrouillez le code en mémoire pour ses routines DispatchRead, DispatchWrite, DispatchDeviceControl et DispatchPower .
Effacez le bit DO_POWER_PAGABLE dans son objet d’appareil pour l’appareil (sur le chemin de l’IRP vers le haut de la pile de l’appareil).
Échec IRP_MN_QUERY_STOP_DEVICE et IRP_MN_QUERY_REMOVE_DEVICE demandes pour l’appareil.

Pour un fichier DeviceUsageTypeDumpFile sur son appareil, un pilote doit effectuer les opérations suivantes :

Verrouillez le code en mémoire pour ses routines DispatchRead, DispatchWrite, DispatchDeviceControl et DispatchPower .
Ne sortez pas l’appareil de l’état D0.

N’inscrivez pas l’appareil pour la détection d’inactivité (PoRegisterDeviceForIdleDetection). Si l’appareil est déjà inscrit, annulez l’inscription. Si le pilote effectue sa propre détection d’inactivité pour l’appareil, suspendez cette détection.
Effacez le bit DO_POWER_PAGABLE dans son objet d’appareil pour l’appareil (sur le chemin de l’IRP vers le haut de la pile de l’appareil).
Échec IRP_MN_QUERY_STOP_DEVICE et IRP_MN_QUERY_REMOVE_DEVICE demandes pour l’appareil.

Pour un fichier DeviceUsageTypeHibernation sur son appareil, un pilote doit effectuer les opérations suivantes :

Verrouillez le code en mémoire pour ses routines DispatchRead, DispatchWrite, DispatchDeviceControl et DispatchPower .
Vérifiez que l’appareil est à l’état D0 lorsque le pilote reçoit un IRP d’alimentation du système S4 indiquant que le système est sur le point de mettre en veille prolongée.
Ne mettez pas l’appareil hors tension en réponse à un IRP de puissance définie D3 qui fait partie d’une action de mise en veille prolongée S4. Pour plus d’informations, consultez Actions d’alimentation système .

À la réception d’un IRP d’alimentation D3 de ce type, effectuez toutes les tâches requises pour placer l’appareil dans l’état D3, à l’exception de la mise hors tension de l’appareil et de la notification du gestionnaire d’alimentation (PoSetPowerState). L’appareil doit conserver l’alimentation jusqu’à ce que le fichier de mise en veille prolongée ait été écrit.
Effacez le bit DO_POWER_PAGABLE dans son objet d’appareil pour l’appareil (sur le chemin de l’IRP vers le haut de la pile de l’appareil).
Échec IRP_MN_QUERY_STOP_DEVICE et IRP_MN_QUERY_REMOVE_DEVICE demandes pour l’appareil.

Consultez Gestion de l’alimentation pour plus d’informations sur les états d’alimentation des appareils, les irps d’alimentation et la prise en charge de la gestion de l’alimentation dans les pilotes.

Envoi de cette IRP

Un pilote peut envoyer un IRP IRP_MN_DEVICE_USAGE_INFORMATION , mais uniquement pour propager les informations d’utilisation des appareils à une autre pile d’appareils. Un pilote n’est jamais la source initiale d’informations sur l’utilisation des appareils.