IRP_MN_QUERY_DEVICE_RELATIONS

Artigo
06/15/2023

O gerenciador PnP envia essa solicitação para determinar determinadas relações entre dispositivos. Os seguintes tipos de drivers lidam com essa solicitação:

Os motoristas de ônibus devem lidar com solicitações busRelations para seu adaptador ou controlador (FDO de barramento). Os drivers de filtro podem lidar com solicitações de BusRelations .
Os motoristas de ônibus devem lidar com as solicitações TargetDeviceRelation para seus dispositivos filho (PDOs filho).
Drivers de função e filtro podem lidar com solicitações RemovalRelations e PowerRelations .
Os motoristas de ônibus podem lidar com solicitações de EjectionRelations para seus dispositivos filho (PDOs filho).

Valor

0x07

Código principal

IRP_MJ_PNP

Quando enviado

O gerenciador de PnP envia esse IRP para coletar informações sobre dispositivos com uma relação com o dispositivo especificado.

O gerenciador PnP consulta os BusRelations (dispositivos filho) de um dispositivo quando o dispositivo é enumerado e em outros momentos enquanto o dispositivo está ativo, como quando um driver chama a rotina IoInvalidateDeviceRelations para indicar que um dispositivo filho chegou ou partiu.

O gerenciador de PnP consulta as RemovalRelations de um dispositivo antes de remover os drivers de um dispositivo. O gerenciador PnP consulta RemovalRelations e EjectionRelations antes de ejetar um dispositivo.

O gerenciador PnP consulta TargetDeviceRelation de um dispositivo quando um aplicativo de modo de usuário ou driver se registra para notificação PnP de um EventCategoryTargetDeviceChange no dispositivo. O gerenciador PnP consulta o dispositivo associado a um objeto de arquivo específico. IRP_MN_QUERY_DEVICE_RELATIONS é o único IRP PnP que tem um parâmetro de objeto de arquivo válido. Um driver pode consultar uma pilha de dispositivos para TargetDeviceRelation. Um driver não precisa fornecer um objeto de arquivo ao enviar sua consulta TargetDeviceRelation .

O gerenciador de PnP consulta o PowerRelations de um dispositivo quando o driver do dispositivo chama IoInvalidateDeviceRelations para indicar que o conjunto de dispositivos com os quais esse dispositivo tem uma relação implícita de gerenciamento de energia foi alterado. Há suporte para solicitações do PowerRelations a partir do Windows 7.

Para solicitações BusRelations, RemovalRelations, EjectionRelations e PowerRelations , o gerenciador PnP envia IRP_MN_QUERY_DEVICE_RELATIONS em IRQL = PASSIVE_LEVEL no contexto de um thread do sistema.

Para solicitações TargetDeviceRelation , o gerenciador PnP envia esse IRP em IRQL = PASSIVE_LEVEL em um contexto de thread arbitrário.

Parâmetros de Entrada

O membro Parameters.QueryDeviceRelations.Type da estrutura IO_STACK_LOCATION especifica o tipo de relações que estão sendo consultadas. Os valores possíveis incluem BusRelations, EjectionRelations, RemovalRelations, TargetDeviceRelation e PowerRelations.

O membro FileObject da estrutura IO_STACK_LOCATION atual aponta para um objeto de arquivo válido somente se Parameters.QueryDeviceRelations.Type for TargetDeviceRelation.

Parâmetros de saída

Retornado no bloco status de E/S.

Bloco de Status de E/S

Um driver define Irp-IoStatus.Status> como STATUS_SUCCESS ou como uma falha status como STATUS_INSUFFICIENT_RESOURCES.

Em caso de êxito, um driver define Irp-IoStatus.Information> como um ponteiro PDEVICE_RELATIONS que aponta para as informações de relações solicitadas. A estrutura DEVICE_RELATIONS é definida da seguinte maneira:

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

Operação

Se um driver retornar relações em resposta a esse IRP_MN_QUERY_DEVICE_RELATIONS, o driver alocará uma estrutura DEVICE_RELATIONS da memória paginada que contém uma contagem e o número apropriado de ponteiros de objeto do dispositivo. O gerenciador PnP libera a estrutura quando ela não é mais necessária. Se um driver substituir um DEVICE_RELATIONS estrutura alocada por outro driver, o driver deverá liberar a estrutura anterior.

Um driver deve referenciar o PDO de qualquer dispositivo que ele relata neste IRP (ObReferenceObject). O gerenciador PnP remove a referência quando apropriado.

Um driver de função ou filtro deve estar preparado para manipular esse IRP para um dispositivo a qualquer momento após a conclusão de sua rotina AddDevice para o dispositivo. Os motoristas de ônibus devem estar preparados para lidar com uma consulta para BusRelations imediatamente após a enumeração de um dispositivo.

Para obter as regras gerais sobre como lidar com Plug and Play IRPs menores, consulte Plug and Play.

As subseções a seguir descrevem as ações específicas para lidar com as várias consultas.

Solicitação BusRelations

Quando o gerente PnP consulta as relações de barramento (dispositivos filho) de um adaptador ou controlador, o motorista do barramento deve retornar uma lista de ponteiros para os PDOs de todos os dispositivos fisicamente presentes no barramento. O motorista do ônibus relata todos os dispositivos, independentemente de terem sido iniciados. O motorista do ônibus pode precisar ligar seu dispositivo de ônibus para determinar quais crianças estão presentes.

Aviso Um objeto de dispositivo não pode ser passado para qualquer rotina que usa um PDO como argumento até que o gerenciador PnP crie um nó de dispositivo (devnode) para esse objeto. (Se o driver passar um objeto de dispositivo, o sistema bugará marcar com 0xCA de Verificação de Bugs: PNP_DETECTED_FATAL_ERROR.) O gerenciador PnP cria o devnode em resposta à solicitação de IRP_MN_QUERY_DEVICE_RELATIONS. O driver pode assumir com segurança que o devnode do PDO foi criado quando recebe uma solicitação IRP_MN_QUERY_RESOURCE_REQUIREMENTS .

O driver de ônibus que responde a esse IRP é o driver de função para o adaptador ou controlador do barramento, não o motorista do barramento pai para o ônibus ao qual o adaptador ou controlador está conectado. Os drivers de função para dispositivos que não são de barramento não lidam com essa consulta. Esses drivers passam o IRP para o próximo driver inferior. (Consulte a figura a seguir.) Normalmente, os drivers de filtro não lidam com essa consulta.

No Windows Vista e em sistemas operacionais posteriores, recomendamos que os drivers sempre pendam a IRP_MN_QUERY_DEVICE_RELATIONS IRP e conclua o processamento posteriormente. Essa ordem permite que o sistema processe consultas de relação de barramento de forma assíncrona. (Em sistemas operacionais antes do Windows Vista, os drivers podem retornar com segurança STATUS_PENDING de suas rotinas de expedição, mas o gerenciador PnP não sobrepõe a consulta de relação de barramento com nenhuma outra operação.)

O diagrama a seguir mostra como os motoristas lidam com uma consulta para relações de ônibus.

diagrama ilustrando os drivers que lidam com uma consulta para relações de ônibus.

No exemplo mostrado na figura, o gerenciador PnP envia um IRP_MN_QUERY_DEVICE_RELATIONS para BusRelations para os drivers do dispositivo de hub USB. O gerenciador PnP está solicitando uma lista dos filhos do dispositivo hub.

Assim como acontece com todos os IRPs PnP, o gerenciador PnP envia o IRP para o driver superior na pilha de dispositivos do dispositivo.
Um driver de filtro opcional pode ser o driver superior na pilha. Normalmente, um driver de filtro não manipula esse IRP; ele passa o IRP para baixo na pilha. Um driver de filtro poderá lidar com esse IRP, por exemplo, se o driver expor um dispositivo não enumerável no barramento.
O driver do barramento do hub USB manipula o IRP.

O driver do barramento do hub USB:
- Cria um PDO para qualquer dispositivo filho que ainda não tenha um.
- Marca o PDO inativo para qualquer dispositivo que não esteja mais presente no barramento. O driver de barramento não exclui esses PDOs.Para obter mais informações sobre quando excluir os PDOs, consulte Removendo um dispositivo.
- Relata todos os dispositivos filho que estão presentes no ônibus.
  
  Para cada dispositivo filho, o driver de barramento faz referência ao PDO e coloca um ponteiro para o PDO na estrutura DEVICE_RELATIONS.
  
  Há dois PDOs neste exemplo: um para o dispositivo joystick e outro para o dispositivo de teclado.
  
  O motorista do ônibus deve marcar se outro driver já criou uma estrutura DEVICE_RELATIONS para esse IRP. Nesse caso, o motorista do ônibus deve adicionar às informações existentes.
  
  Se não houver nenhum dispositivo filho presente no barramento, o driver definirá a contagem como zero na estrutura DEVICE_RELATIONS e retornará êxito.
- Define os valores apropriados no bloco de E/S status e passa o IRP para o próximo driver inferior. O driver de barramento para o adaptador ou controlador não conclui o IRP.
Um filtro inferior opcional, se presente, normalmente não manipula esse IRP. Esse driver de filtro passa o IRP para baixo na pilha. Se um driver de filtro inferior manipular esse IRP, ele poderá adicionar PDO(s) à lista de dispositivos filho, mas não deverá excluir nenhum PDOs criado por outros drivers.
O driver de barramento pai não manipula esse IRP, a menos que seja o único driver na pilha do dispositivo (o dispositivo está no modo bruto). Assim como acontece com todos os IRPs PnP, o motorista do barramento pai conclui o IRP com IoCompleteRequest.

Se houver um ou mais drivers de filtro de ônibus na pilha do dispositivo, esses drivers poderão manipular o IRP no caminho até o motorista do ônibus e/ou no caminho do IRP para fazer backup da pilha do dispositivo (se houver rotinas IoCompletion ). De acordo com as regras de PnP IRP, esse driver pode adicionar PDOs ao IRP no caminho para baixo na pilha e/ou modificar a lista de relações no caminho do IRP para fazer backup da pilha (em rotinas IoCompletion ).

Solicitação EjectionRelations

Um driver retorna ponteiros para PDOs de todos os dispositivos que podem ser fisicamente removidos do sistema quando o dispositivo especificado é ejetado. Não relate os PDOs de filhos do dispositivo; o gerenciador PnP sempre solicita que os dispositivos filho sejam removidos antes do dispositivo pai.

O gerenciador PnP envia um IRP IRP_MN_EJECT para um dispositivo que está sendo ejetado. O driver para esse dispositivo também recebe um IRP de remoção. As relações de ejeção do dispositivo recebem um IRP IRP_MN_REMOVE_DEVICE (não um IRP IRP_MN_EJECT ).

Somente um motorista de ônibus pai pode responder a uma consulta EjectionRelations para um de seus dispositivos filho. Os drivers de função e filtro devem passá-lo para o próximo driver inferior na pilha do dispositivo. Se um motorista de ônibus receber esse IRP como o driver de função para seu adaptador ou controlador, o motorista do ônibus está executando as tarefas de um driver de função e deve passar o IRP para o próximo driver inferior.

Solicitação do PowerRelations

A partir do Windows 7, a consulta do PowerRelations permite que um driver especifique uma relação de gerenciamento de energia fora da relação convencional entre um barramento pai que dá suporte à enumeração PnP e um dispositivo filho enumerado no barramento. Por exemplo, se um motorista de ônibus não puder enumerar um dispositivo filho no ônibus ou se um dispositivo for filho de mais de um ônibus, a consulta do PowerRelations poderá descrever as relações de energia do dispositivo filho com o ônibus ou os ônibus.

O gerenciador de PnP emite uma consulta do PowerRelations para um dispositivo quando o driver do dispositivo chama a rotina IoInvalidateDeviceRelations e especifica um valor de parâmetro Type de PowerRelations.

Em resposta a essa consulta, o driver do dispositivo de destino (ou seja, o dispositivo que é o destino da consulta) fornece uma estrutura DEVICE_RELATIONS que contém ponteiros para os PDOs de qualquer outro dispositivo que deve ser ativado pelo power manager antes que o dispositivo de destino seja ativado. Por outro lado, esses outros dispositivos devem ser desativados somente depois que o dispositivo de destino estiver desativado. O power manager usa as informações da consulta para garantir que esses dispositivos estejam ativados e desativados na ordem correta.

Essa garantia de ordenação se aplica somente às transições de estado de suspensão do sistema global, que incluem transições de e para os estados de energia do sistema S1, S2, S3 (suspensão), S4 (hibernação) e S5 (desligamento). A garantia de ordenação do PowerRelations não se aplica às transições de estado de energia do dispositivo Dx enquanto o sistema permanece no estado do sistema S0 (em execução), exceto no caso de transições de DFx (Gerenciamento de Energia de Runtime Direcionado ).

Se o dispositivo de destino estiver no caminho do dispositivo para um arquivo especial (como o arquivo de paginação, o arquivo de hibernação ou o arquivo de despejo de memória), o driver do dispositivo de destino deverá executar uma etapa adicional ao manipular um IRP IRP_MN_DEVICE_USAGE_NOTIFICATION no qual InPath é TRUE. Esse driver deve garantir que os dispositivos cujos PDOs sejam fornecidos para a consulta do PowerRelations também possam dar suporte a estar no caminho do dispositivo para o arquivo especial. Para confirmar esse suporte, o driver do dispositivo de destino deve primeiro enviar o IRP_MN_DEVICE_USAGE_NOTIFICATION IRP para cada um desses dispositivos, e esse IRP deve especificar o mesmo UsageNotification.Type que o dispositivo de destino. Somente se todos os dispositivos que recebem esse IRP concluirem o IRP com um código de status de êxito o driver do dispositivo de destino poderá concluir seu IRP_MN_DEVICE_USAGE_NOTIFICATION IRP com êxito. Caso contrário, esse driver deve concluir esse IRP com uma falha status código.

Quando esse mesmo driver manipula um IRP IRP_MN_DEVICE_USAGE_NOTIFICATION para o qual InPath é FALSE, o driver deve enviar o IRP IRP_MN_DEVICE_USAGE_NOTIFICATION para o mesmo conjunto de dispositivos dependentes que para o caso em que InPath é TRUE. No entanto, o driver nunca deve concluir esse IRP com uma falha status código quando InPath for FALSE.

O driver que responde à consulta do PowerRelations deve se registrar para notificações de alteração de dispositivo de destino em todos os dispositivos cujos PDOs são fornecidos para a consulta do PowerRelations . Para se registrar para essas notificações, o driver pode chamar a rotina IoRegisterPlugPlayNotification e especificar um valor de parâmetro EventCategoryeventCategoryTargetDeviceChange.

Solicitação RemovalRelations

Um driver retorna ponteiros para PDOs de todos os dispositivos cujos drivers devem ser removidos quando os drivers do dispositivo especificado são removidos. Não relate os PDOs de filhos do dispositivo; o gerenciador PnP já solicita a remoção de dispositivos filho antes de remover um dispositivo.

A ordem na qual as relações de remoção são removidas é indefinida.

Qualquer driver na pilha de dispositivos pode lidar com esse tipo de consulta de relações. Um driver de função ou filtro manipula o IRP antes de passá-lo para o próximo driver inferior. Um motorista de ônibus manipula o IRP e o conclui.

Solicitação TargetDeviceRelation

A consulta TargetDeviceRelation permite que o gerenciador PnP consulte uma pilha de dispositivos não PnP para o PDO na pilha de dispositivos PnP que controla o hardware.

Em geral, os drivers encaminham o IRP_MN_QUERY_DEVICE_RELATIONS IRP para baixo em sua pilha até que o IRP atinja a parte inferior de uma pilha de dispositivos específica. Um driver na parte inferior de uma pilha não PnP encaminha ou emite novamente o IRP para a pilha PnP relevante. Por exemplo, o gerenciador PnP pode enviar uma consulta TargetDeviceRelation para o objeto de dispositivo na parte superior da pilha do sistema de arquivos, que é uma pilha não PnP. Cada objeto de dispositivo na pilha do sistema de arquivos passaria a consulta para o objeto de dispositivo abaixo dele até que a consulta alcançasse o objeto de dispositivo na parte inferior da pilha. O objeto de dispositivo mais baixo na pilha encaminharia ou emitiria novamente a consulta TargetDeviceRelation para o objeto de dispositivo na parte superior da pilha de volumes de armazenamento PnP e, em seguida, a consulta seria passada para o PDO na parte inferior da pilha de volumes de armazenamento.

A lista a seguir resume as situações em que você pode adquirir com segurança um ponteiro para o PDO na parte inferior de uma pilha de dispositivos PnP:

Objeto device em um PnP

Um objeto de dispositivo que está em uma pilha de dispositivos PnP aprende sobre o PDO da pilha quando a rotina AddDevice para o dispositivo é chamada. O driver poderá armazenar em cache com segurança o ponteiro para o PDO se o uso do ponteiro for sincronizado corretamente com mensagens de entrada IRP_MN_REMOVE_DEVICE usando as rotinas de remoção de bloqueio.
Objeto de dispositivo em uma pilha não PnP, não na parte inferior da pilha

Para um objeto de dispositivo que não está na parte inferior de uma pilha não PnP, um driver pode enviar uma consulta TargetDeviceRelation para obter um ponteiro para o PDO na parte inferior da pilha de dispositivos PnP correspondente.
Objeto file para o dispositivo

Dado um objeto de arquivo para o dispositivo, um driver pode chamar IoGetRelatedDeviceObject para obter o objeto do dispositivo e, em seguida, seguir as instruções no item de lista anterior.
Identificador para o objeto do dispositivo

Dado um identificador para o objeto de dispositivo, um driver pode chamar ObReferenceObjectByHandle para obter o objeto de arquivo para o dispositivo e, em seguida, seguir as instruções no item de lista anterior.

Um motorista de barramento pai deve manipular uma consulta de relações TargetDeviceRelation para seus dispositivos filho. O driver de barramento faz referência ao PDO do dispositivo filho com ObReferenceObject e retorna um ponteiro para o PDO na estrutura DEVICE_RELATIONS . Há apenas um ponteiro PDO na estrutura para esse tipo de relação. O gerenciador PnP remove a referência ao PDO quando o driver ou aplicativo cancela o registro para notificação no dispositivo.

Somente um motorista de barramento pai responde a uma consulta TargetDeviceRelation . Os drivers de função e filtro devem passá-lo para o próximo driver inferior na pilha do dispositivo. Se um motorista de ônibus receber esse IRP como o driver de função para seu adaptador ou controlador, o motorista do barramento está executando as tarefas de um driver de função e deve passar o IRP para o próximo driver inferior.

Se um driver não estiver em uma pilha baseada em PDO, o driver enviará um novo IRP de consulta de destino-dispositivo para o objeto de dispositivo associado ao identificador de arquivo no qual o driver executa E/S.

Enviando este IRP

Os motoristas não devem enviar IRP_MN_QUERY_DEVICE_RELATIONS para solicitar BusRelations. Os drivers não estão impedidos de enviar esse IRP para RemovalRelations ou EjeçãoRelations, mas não é provável que um driver o faça.

Os drivers podem consultar uma pilha de dispositivos para TargetDeviceRelation. Consulte Manipulando IRPs para obter informações sobre como enviar IRPs. As seguintes etapas se aplicam especificamente a este IRP:

Defina os valores no próximo local da pilha de E/S do IRP: defina MajorFunctioncomo IRP_MJ_PNP, defina MinorFunction como IRP_MN_QUERY_DEVICE_RELATIONS, defina Parameters.QueryDeviceRelations.Type como TargetDeviceRelation e defina Irp-FileObject> como um objeto de arquivo válido.
Inicialize IoStatus.Status para STATUS_NOT_SUPPORTED.

Se um driver enviou esse IRP para fazer com que o PDO relatasse em resposta a um IRP_MN_QUERY_DEVICE_RELATIONS para TargetDeviceRelation que o driver recebeu, o driver relatará o PDO e liberará a estrutura de relações retornada quando o IRP for concluído. Se um driver iniciou esse IRP por outro motivo, o driver libera a estrutura de relações quando o IRP conclui e desreferencia o PDO quando ele não é mais necessário.