IRP_MN_QUERY_DEVICE_RELATIONS

Статья
06/15/2023

Диспетчер PnP отправляет этот запрос для определения определенных связей между устройствами. Следующие типы драйверов обрабатывают этот запрос:

Водители шины должны обрабатывать запросы BusRelations для адаптера или контроллера (FDO шины). Драйверы фильтров могут обрабатывать запросы BusRelations .
Водители автобусов должны обрабатывать запросы TargetDeviceRelation для своих дочерних устройств (дочерних PDO).
Драйверы функций и фильтров могут обрабатывать запросы на удалениеRelations и PowerRelations .
Водители автобусов могут обрабатывать запросы EjectionRelations для своих дочерних устройств (дочерних PDO).

Значение

0x07

Основной код

IRP_MJ_PNP

При отправке

Диспетчер PnP отправляет этот IRP для сбора сведений об устройствах, имеющих отношение к указанному устройству.

Диспетчер PnP запрашивает busRelations устройства (дочерние устройства) при перечислении устройства и в другое время, когда устройство активно, например когда драйвер вызывает подпрограмму IoInvalidateDeviceRelations , чтобы указать, что дочернее устройство прибыло или покинуло его.

Диспетчер PnP запрашивает метод RemoveRelations устройства перед удалением драйверов устройства. Диспетчер PnP запрашивает RemovalRelations и EjectionRelations перед извлечением устройства.

Диспетчер PnP запрашивает TargetDeviceRelation устройства, когда драйвер или приложение в пользовательском режиме регистрирует уведомление PnP о EventCategoryTargetDeviceChange на устройстве. Диспетчер PnP запрашивает устройство, связанное с определенным объектом файла. IRP_MN_QUERY_DEVICE_RELATIONS является единственным параметром PnP IRP, который имеет допустимый параметр объекта файла. Драйвер может запрашивать стек устройств для TargetDeviceRelation. Драйверу не нужно предоставлять объект файла при отправке запроса TargetDeviceRelation .

Диспетчер PnP запрашивает powerRelations устройства, когда драйвер для устройства вызывает IoInvalidateDeviceRelations , чтобы указать, что набор устройств, с которым это устройство имеет неявное отношение управления питанием, изменился. Запросы PowerRelations поддерживаются, начиная с Windows 7.

Для запросов BusRelations, RemovalRelations, EjectionRelations и PowerRelations диспетчер PnP отправляет IRP_MN_QUERY_DEVICE_RELATIONS в IRQL = PASSIVE_LEVEL в контексте системного потока.

Для запросов TargetDeviceRelation диспетчер PnP отправляет этот IRP по адресу IRQL = PASSIVE_LEVEL в произвольном контексте потока.

Входные параметры

Элемент Parameters.QueryDeviceRelations.Type структуры IO_STACK_LOCATION указывает тип связей, которые запрашиваются. Возможные значения: BusRelations, EjectionRelations, RemovalRelations, TargetDeviceRelation и PowerRelations.

Элемент FileObject текущей структуры IO_STACK_LOCATION указывает на допустимый объект файла, только если Parameters.QueryDeviceRelations.Type имеет значение TargetDeviceRelation.

Выходные параметры

Возвращается в блоке состояния ввода-вывода.

Блок состояния ввода-вывода

Драйвер присваивает Irp-IoStatus.Status> значение STATUS_SUCCESS или состояние сбоя, например STATUS_INSUFFICIENT_RESOURCES.

При успешном выполнении драйвер задает Irp-IoStatus.Information> PDEVICE_RELATIONS указатель, указывающий на запрошенные сведения о связях. Структура DEVICE_RELATIONS определяется следующим образом:

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

Операция

Если драйвер возвращает связи в ответ на это IRP_MN_QUERY_DEVICE_RELATIONS, драйвер выделяет структуру DEVICE_RELATIONS из подкачки памяти, которая содержит количество и соответствующее количество указателей объектов устройства. Диспетчер PnP освобождает структуру, когда она больше не нужна. Если драйвер заменяет DEVICE_RELATIONS структуру, выделенную другим драйвером, драйвер должен освободить предыдущую структуру.

Драйвер должен ссылаться на PDO любого устройства, о чем он сообщает в этом IRP (ObReferenceObject). При необходимости диспетчер PnP удаляет ссылку.

Драйвер функции или фильтра должен быть подготовлен к обработке этого IRP для устройства в любое время после завершения процедуры AddDevice для устройства. Драйверы шины должны быть готовы к обработке запроса BusRelations сразу после перечисления устройства.

Общие правила обработки Plug and Play дополнительных irP см. в разделе Plug and Play.

В следующих подразделах описываются конкретные действия по обработке различных запросов.

Запрос BusRelations

Когда диспетчер PnP запрашивает связи шины (дочерние устройства) адаптера или контроллера, водитель шины должен вернуть список указателей на PDO всех устройств, физически присутствующих в шине. Водитель автобуса сообщает обо всех устройствах, независимо от того, были ли они запущены. Водителю автобуса может потребоваться включить свое устройство шины, чтобы определить, какие дети присутствуют.

Предупреждение Объект устройства не может быть передан ни одной подпрограмме, которая принимает PDO в качестве аргумента, пока диспетчер PnP не создаст узел устройства (devnode) для этого объекта. (Если драйвер передает объект устройства, система проверка ошибок с 0xCA проверки ошибок: PNP_DETECTED_FATAL_ERROR.) Диспетчер PnP создает devnode в ответ на запрос IRP_MN_QUERY_DEVICE_RELATIONS. Драйвер может с уверенностью предположить, что devnode PDO был создан при получении запроса IRP_MN_QUERY_RESOURCE_REQUIREMENTS .

Драйвер шины, реагирующий на это IRP, является драйвером функции для адаптера шины или контроллера, а не родительским драйвером шины для шины, к которому подключен адаптер или контроллер. Драйверы функций для устройств, не являющихся шинами, не обрабатывают этот запрос. Такие водители просто передают IRP следующему более низкому водителю. (См. следующий рисунок.) Драйверы фильтров обычно не обрабатывают этот запрос.

В Windows Vista и более поздних операционных системах рекомендуется, чтобы драйверы всегда выполняли IRP_MN_QUERY_DEVICE_RELATIONS IRP и завершайте его обработку позже. Этот порядок позволяет системе асинхронно обрабатывать запросы связи шины. (В операционных системах, предшествующих Windows Vista, драйверы могут безопасно возвращать STATUS_PENDING из своих подпрограмм диспетчера, но диспетчер PnP не перекрывает запрос связи шины с любой другой операцией.)

На следующей схеме показано, как водители обрабатывают запрос на связи между шинами.

схема, иллюстрирующая водителей, обрабатывающих запрос на связи между шинами.

В примере, показанном на рисунке, диспетчер PnP отправляет IRP_MN_QUERY_DEVICE_RELATIONS для BusRelations драйверам usb-концентратора. Диспетчер PnP запрашивает список дочерних элементов центрального устройства.

Как и в случае со всеми PnP IRP, диспетчер PnP отправляет IRP в верхний драйвер в стеке устройств для устройства.
Дополнительный драйвер фильтра может быть верхним драйвером в стеке. Драйвер фильтра обычно не обрабатывает этот IRP; он передает IRP вниз по стеку. Драйвер фильтра может обрабатывать этот IRP, например, если драйвер предоставляет неунижаемое устройство в шине.
Драйвер шины концентратора USB обрабатывает IRP.

Драйвер шины USB-концентратора:
- Создает PDO для любого дочернего устройства, у которых его еще нет.
- Помечает PDO неактивным для любого устройства, которое больше не присутствует в шине. Водитель автобуса не удаляет такие PDO. Дополнительные сведения о том, когда следует удалять PDO, см. в разделе Удаление устройства.
- Сообщает о всех дочерних устройствах, которые присутствуют в шине.
  
  Для каждого дочернего устройства драйвер шины ссылается на PDO и помещает указатель на PDO в DEVICE_RELATIONS структуре.
  
  В этом примере есть два PDO: один для джойстика и один для устройства с клавиатурой.
  
  Водитель автобуса должен проверка, создал ли другой водитель DEVICE_RELATIONS структуру для этого IRP. Если это так, водитель автобуса должен добавить к существующей информации.
  
  Если в шине нет дочернего устройства, водитель устанавливает в структуре DEVICE_RELATIONS число равным нулю и возвращает успешное выполнение.
- Задает соответствующие значения в блоке состояния ввода-вывода и передает IRP следующему более низкому драйверу. Драйвер шины для адаптера или контроллера не завершает IRP.
Необязательный нижний фильтр, если он имеется, обычно не обрабатывает этот IRP. Такой драйвер фильтра передает IRP вниз по стеку. Если драйвер нижнего фильтра обрабатывает это IRP, он может добавить PDO в список дочерних устройств, но не должен удалять все PDO, созданные другими драйверами.
Драйвер родительской шины не обрабатывает этот IRP, если он не является единственным драйвером в стеке устройств (устройство находится в режиме необработанных данных). Как и в случае со всеми PnP IRP, драйвер родительского автобуса завершает IRP с помощью IoCompleteRequest.

Если в стеке устройств есть один или несколько драйверов фильтров шины, такие драйверы могут обрабатывать IRP на пути к водителю автобуса и (или) на пути IRP резервное копирование стека устройств (если есть процедуры IoCompletion ). В соответствии с правилами PnP IRP такой драйвер может добавлять PDO в IRP на пути вниз по стеку и /или изменять список связей на пути пути IRP вверх по стеку (в подпрограммах IoCompletion ).

Запрос EjectionRelations

Драйвер возвращает указатели на PDO любых устройств, которые могут быть физически удалены из системы при извлечении указанного устройства. Не сообщайте ОПК дочерних элементов устройства; диспетчер PnP всегда запрашивает удаление дочерних устройств до их родительского устройства.

Диспетчер PnP отправляет IRP_MN_EJECT IRP на извлекаемое устройство. Драйвер для такого устройства также получает удаление IRP. Отношения извлечения устройства получают IRP_MN_REMOVE_DEVICE IRP (не IRP_MN_EJECT IRP).

Только драйвер родительского автобуса может отвечать на запрос EjectionRelations для одного из своих дочерних устройств. Драйверы функций и фильтров должны передавать их следующему более низкому драйверу в стеке устройств. Если водитель автобуса получает этот IRP в качестве драйвера функции для своего адаптера или контроллера, водитель автобуса выполняет задачи драйвера функции и должен передать IRP следующему драйверу ниже.

Запрос PowerRelations

Начиная с Windows 7, запрос PowerRelations позволяет драйверу указать связь управления питанием вне обычного отношения между родительской шиной, поддерживающей перечисление PnP, и перечислимым дочерним устройством в шине. Например, если водитель автобуса не может перечислить дочернее устройство в шине или устройство является дочерним для нескольких автобусов, запрос PowerRelations может описать отношения власти дочернего устройства с автобусом или автобусами.

Диспетчер PnP отправляет запрос PowerRelations для устройства, когда драйвер для устройства вызывает подпрограмму IoInvalidateDeviceRelations и задает значение параметра Typeдля PowerRelations.

В ответ на этот запрос драйвер для целевого устройства (т. е. устройства, которое является целевым объектом для запроса) предоставляет структуру DEVICE_RELATIONS , содержащую указатели на PDO любых других устройств, которые должны быть включено диспетчером питания перед включением целевого устройства. И наоборот, эти другие устройства должны быть отключены только после отключения целевого устройства. Диспетчер питания использует сведения из запроса, чтобы гарантировать, что эти устройства включены и отключены в правильном порядке.

Эта гарантия упорядочения применяется только к глобальным системным переходам состояния спящего режима, которые включают переходы на S1, S2, S3 (спящий режим), S4 (гибернации) и S5 (выключение) и S5 (выключение). Гарантия упорядочения PowerRelations не применяется к переходу состояния питания устройства Dx, пока система остается в системном состоянии S0 (выполняется), за исключением случаев переходов управления питанием в среде direct Runtime (DFx ).

Если целевое устройство находится в пути к устройству для специального файла (например, файла подкачки, файла гибернации или файла аварийного дампа), драйвер для целевого устройства должен выполнить дополнительный шаг при обработке IRP_MN_DEVICE_USAGE_NOTIFICATION IRP, в котором InPath имеет значение TRUE. Этот драйвер должен гарантировать, что устройства, PDO которых предоставляются для запроса PowerRelations , также могут поддерживать путь к устройству для специального файла. Чтобы подтвердить эту поддержку, драйвер для целевого устройства должен сначала отправить IRP_MN_DEVICE_USAGE_NOTIFICATION IRP на каждое из этих устройств, и этот IRP должен указать тот же UsageNotification.Type , что и целевое устройство. Драйвер для целевого устройства может успешно завершить IRP_MN_DEVICE_USAGE_NOTIFICATION IRP только в том случае, если все устройства, получающие этот IRP, завершают его с кодом состояния успешного выполнения. В противном случае этот драйвер должен завершить этот IRP с кодом состояния сбоя.

Если этот же драйвер обрабатывает IRP_MN_DEVICE_USAGE_NOTIFICATION IRP, для которого InPath имеет значение FALSE, драйвер должен отправить IRP_MN_DEVICE_USAGE_NOTIFICATION IRP на тот же набор зависимых устройств, что и в случае, когда InPath имеет значение TRUE. Однако драйвер никогда не должен завершать этот IRP с кодом состояния сбоя, если InPath имеет значение FALSE.

Драйвер, отвечающий на запрос PowerRelations , должен зарегистрироваться для получения уведомлений об изменении целевых устройств на всех устройствах, PDO которых предоставляются для запроса PowerRelations . Чтобы зарегистрироваться для получения этих уведомлений, драйвер может вызвать подпрограмму IoRegisterPlugPlayNotification и указать значение параметра EventCategoryTargetDeviceChange.

Запрос на удалениеRelations

Драйвер возвращает указатели на PDO всех устройств, драйверы которых должны быть удалены при удалении драйверов для указанного устройства. Не сообщайте ОПК дочерних элементов устройства; Диспетчер PnP уже запрашивает удаление дочерних устройств перед удалением устройства.

Порядок удаления отношений удаления не определен.

Любой драйвер в стеке устройств может обрабатывать запросы такого типа связей. Драйвер функции или фильтра обрабатывает IRP перед передачей его следующему драйверу более низкого уровня. Водитель автобуса обрабатывает IRP, а затем завершает его.

Запрос TargetDeviceRelation

Запрос TargetDeviceRelation позволяет диспетчеру PnP запрашивать стек устройств, отличный от PnP, для PDO в стеке устройств PnP, который управляет оборудованием.

Как правило, драйверы перенаправят IRP_MN_QUERY_DEVICE_RELATIONS IRP вниз по стеку, пока IRP не достигнет нижней части определенного стека устройств. Драйвер в нижней части стека, отличного от PnP, затем перенаправит или повторно выдает IRP в соответствующий стек PnP. Например, диспетчер PnP может отправить запрос TargetDeviceRelation объекту устройства в верхней части стека файловой системы, который не является стеком PnP. Каждый объект устройства в стеке файловой системы будет передавать запрос объекту устройства под ним до тех пор, пока запрос не достигнет объекта устройства в нижней части стека. Самый низкий объект устройства в стеке перенаправит или повторно передаст запрос TargetDeviceRelation объекту устройства в верхней части стека томов хранилища PnP, а затем запрос будет передан в PDO в нижней части стека томов хранилища.

В следующем списке перечислены ситуации, в которых можно безопасно получить указатель на PDO в нижней части стека устройств PnP.

Объект устройства в PnP

Объект устройства, который находится в стеке устройств PnP, узнает о PDO стека при вызове процедуры AddDevice для устройства. Драйвер может безопасно кэшировать указатель на PDO, если использование указателя правильно синхронизировано с входящими IRP_MN_REMOVE_DEVICE сообщениями с помощью процедур удаления блокировки.
Объект устройства в стеке, отличном от PnP, а не в нижней части стека

Для объекта устройства, который не находится в нижней части стека, отличного от PnP, драйвер может отправить запрос TargetDeviceRelation , чтобы получить указатель на PDO в нижней части соответствующего стека устройств PnP.
Объект file для устройства

При выборе объекта файла для устройства драйвер может вызвать IoGetRelatedDeviceObject , чтобы получить объект устройства, а затем следовать инструкциям в предыдущем элементе списка.
Дескриптор объекта устройства

С помощью дескриптора объекта устройства драйвер может вызвать ObReferenceObjectByHandle , чтобы получить объект файла для устройства, а затем следовать инструкциям в предыдущем элементе списка.

Драйвер родительской шины должен обрабатывать запрос отношений TargetDeviceRelation для своих дочерних устройств. Драйвер шины ссылается на PDO дочернего устройства с помощью ObReferenceObject и возвращает указатель на PDO в структуре DEVICE_RELATIONS . В структуре для этого типа отношения есть только один указатель PDO. Диспетчер PnP удаляет ссылку на PDO, когда драйвер или приложение отменяет регистрацию для уведомления на устройстве.

Только драйвер родительского автобуса отвечает на запрос TargetDeviceRelation . Драйверы функций и фильтров должны передавать их следующему более низкому драйверу в стеке устройств. Если водитель автобуса получает этот IRP в качестве драйвера функции для своего адаптера или контроллера, водитель автобуса выполняет задачи драйвера функции и должен передать IRP следующему драйверу ниже.

Если драйвер не находится в стеке на основе PDO, драйвер отправляет новый IRP запроса отношения целевого устройства объекту устройства, связанному с дескриптором файла, на котором драйвер выполняет операции ввода-вывода.

Отправка этого IRP

Драйверы не должны отправлять IRP_MN_QUERY_DEVICE_RELATIONS для запроса BusRelations. Драйверы не ограничены в отправке этого IRP для RemovalRelations или EjectionRelations, но маловероятно, что драйвер сделает это.

Драйверы могут запрашивать стек устройств для TargetDeviceRelation. Сведения об отправке IRP см. в разделе Обработка irPs . Следующие действия применяются специально к этому IRP:

Задайте значения в следующем расположении стека ввода-вывода IRP: задайте для параметра MajorFunctionзначение IRP_MJ_PNP, для параметра MinorFunction — значение IRP_MN_QUERY_DEVICE_RELATIONS, задайте для параметра Parameters.QueryDeviceRelations.Type значение TargetDeviceRelation, а для Irp-FileObject> — допустимый объект файла.
Инициализируйте IoStatus.Status для STATUS_NOT_SUPPORTED.

Если драйвер отправил этот IRP, чтобы получить PDO для отчета в ответ на IRP_MN_QUERY_DEVICE_RELATIONSдля TargetDeviceRelation , который получил драйвер, то драйвер сообщает PDO и освобождает возвращаемую структуру связей по завершении IRP. Если драйвер инициировал это IRP по другой причине, драйвер освобождает структуру связей после завершения IRP и разыменовывает PDO, когда она больше не нужна.