Testes PnP (Fundamentos do dispositivo)

Os testes PnP de Fundamentos do Dispositivo forçam um driver a lidar com quase todos os IRPs PnP; no entanto, três áreas recebem ênfase especificamente: remoção, rebalanceamento e remoção surpresa. O teste PnP fornece um mecanismo para testar cada um deles separadamente ou testá-los todos juntos (ou seja, como um teste de estresse). Esse teste PnP é realizado usando uma combinação de chamadas à API no modo de usuário (por meio do aplicativo de teste) e chamadas à API no modo kernel (por meio de um driver de filtro superior).

Testes PNP

Os testes de PnP (Plug and Play) executam vários caminhos de código relacionados a PnP nos componentes do driver e do modo de usuário. Os testes PnP devem ser executados com o Verificador de Driver habilitado no computador de teste. Para obter informações sobre como habilitar o Verificador de Driver, consulte as propriedades do Verificador de Driver para projetos de driver.

Sobre os testes de Remoção de Dispositivo

• Teste de Remoção de Dispositivo PNP
• Teste de Cancelamento/Remoção de Dispositivo PNP

O teste de Remoção de Dispositivo abrange IRP_MN_QUERY_REMOVE_DEVICE, IRP_MN_CANCEL_REMOVE_DEVICE e IRP_MN_REMOVE_DEVICE.

O teste tenta instalar o driver de filtro superior na pilha de dispositivos de destino. Essa tentativa resulta em um IRP de remoção de consulta.

Se esse IRP de remoção da consulta falhar, o teste irá reiniciar o computador para colocar o driver de filtro na pilha do dispositivo. Se a solicitação de remoção não for vetada, a pilha do dispositivo será removida e reiniciada com o driver de filtro na pilha do dispositivo.

O teste, utilizando APIs de configuração, faz com que um IRP de consulta-removal seja enviado para a stack de dispositivos. O driver de filtro não atende a esta solicitação de remoção, portanto, um IRP de cancelamento de remoção é enviado. O driver de filtro afirmará que a remoção de cancelamento foi bem-sucedida.

Em seguida, o aplicativo de teste chama o instalador de classe apropriado e todos os co-instaladores registrados para desabilitar ou habilitar e remover ou reenumerar o dispositivo (isso testa a classe e os co-instaladores que manipulam DIF_PROPERTYCHANGE com DICS_DISABLE, DICS_ENABLE e DICS_PROPCHANGE). Ao receber IRP_MN_REMOVE_DEVICE, o driver de filtro afirmará que os drivers inferiores o concluíram com êxito.

Cada uma dessas etapas envolve uma solicitação de remoção preliminar. Se essa solicitação for vetada, o dispositivo não será removido. Você pode optar por recusar uma solicitação de remoção quando apropriado, como ao transmitir vídeo em uma câmera USB ou se o dispositivo de destino estiver no caminho de inicialização ou paginação. Lembre-se de que simplesmente falhar todas as solicitações de remoção geralmente não é uma boa prática. Falhar em todas as solicitações de remoção não garantirá que o driver nunca receberá uma remoção porque um IRP de remoção ainda será emitido após uma remoção surpresa ou se alguém na pilha de dispositivos falhar um IRP inicial.

Sobre o teste de remoção surpresa

• Teste de PNP de remoção surpresa do dispositivo

O teste de Remoção Surpresa abrange IRP_MN_SURPRISE_REMOVAL seguido de IRP_MN_REMOVE_DEVICE.

Assim como nos testes anteriores, o aplicativo de teste tentará adicionar um filtro superior à pilha do dispositivo de destino e, em seguida, reiniciará a pilha. Se essa tentativa não for bem-sucedida, o teste reiniciará o computador.

Quando acionado pelo aplicativo de teste, o driver de filtro fará com que o sistema envie um IRP_MN_SURPRISE_REMOVAL para a pilha de dispositivos, seguido por uma solicitação de IRP_MN_REMOVE_DEVICE. O driver de filtro afirmará que ambos os IRPs tenham sido concluídos com êxito por drivers de nível inferior.

Depois que o teste de remoção surpresa for concluído, o dispositivo será desinstalado, reenumerado e o driver de filtro será removido da pilha.

Sobre os testes de reequilíbrio

• Teste de dispositivo PNP Stop (Rebalance)
• Teste de dispositivo de solicitação de reequilíbrio PNP
• Teste de Falha de Reequilíbrio PNP ao Reiniciar o Dispositivo
• Teste do Dispositivo de Cancelamento de Parada PNP

Assim como acontece com o teste de remoção, o aplicativo de teste tenta adicionar um filtro superior à pilha do dispositivo de destino e, em seguida, reinicia a pilha do dispositivo usando SetupDiCallClassInstaller com DIF_PROPERTYCHANGE. Se essa tentativa não for bem-sucedida (ou seja, se alguém na pilha do dispositivo de destino falhou no IRP de remoção de consulta), o teste reiniciará o computador para testar o reequilíbrio.

Dependendo de qual teste de reequilíbrio você escolher, os seguintes eventos ocorrerão:

1. Teste de dispositivo PNP Stop (Rebalance) Esse teste inicia um procedimento de rebalanceamento que resulta na IRP_MN_QUERY_STOP_DEVICE IRP PnP para o driver do dispositivo.

   Se algum driver na pilha falhar neste IRP, o procedimento de rebalanceamento será abandonado. Observe que, no Windows Vista, há suporte para reequilibramento de vários níveis. Se um rebalanceamento for iniciado em um nó de dispositivo não folha, todas as pilhas de dispositivo presentes na árvore de dispositivos com esse nó como raiz também serão reequilibradas. E se qualquer uma das pilhas de dispositivo filho falhar na interrupção de consulta, o procedimento de rebalanceamento inteiro é abandonado. Portanto, os drivers não devem falhar na parada de consulta sem uma razão genuína para fazê-lo. Se essa falha acontecer, o gerenciador PnP enviará a parada de cancelamento (IRP_MN_CANCEL_STOP) para todas as pilhas de dispositivo que foram enviadas paradas de consulta.

   Se todas as pilhas de dispositivos envolvidas passarem pela parada de consulta, o teste continuará com o reequilíbrio e enviará o IRP_MN_QUERY_RESOURCE_REQUIREMENTS e IRP_MN_FILTER_RESOURCE_REQUIREMENTS IRPS para localizar o requisito de recurso dos dispositivos.

   Após esse ponto, dois caminhos diferentes são possíveis dependendo se o dispositivo de destino consome recursos ou não:

   • Se o dispositivo não consumir recursos, o próprio gerenciador PnP enviará um cancelamento de parada (IRP_MN_CANCEL_STOP_DEVICE) como uma medida de otimização.

     Se o dispositivo realmente consumir recursos, o procedimento de rebalanceamento será concluído com os IRPs IRP_MN_STOP_DEVICE e IRP_MN_START_DEVICE.

   Com essa opção, os recursos do dispositivo não são alterados.

2. Teste de Dispositivo de Parada de Cancelamento de PNP: este teste inicia um procedimento de rebalanceamento, mas o driver de filtro falha deliberadamente na parada de consulta IRP. A ordem dos IRPs parece IRP_MN_QUERY_STOP_DEVICE (que falha no driver de filtro durante a inicialização, causando o cancelamento do rebalanceamento) e IRP_MN_CANCEL_STOP_DEVICE.

   Com essa opção, os recursos do dispositivo não são alterados

3. Teste de solicitação de reequilíbrio de novos recursos do dispositivo PNP Este teste inicia um reequilíbrio e também ajusta as demandas de recursos do dispositivo para maximizar as chances de que novos recursos sejam efetivamente alocados ao dispositivo. Essa opção também ajuda um dispositivo sem recursos a realmente passar pelo procedimento de reequilíbrio completo:

   1. Primeiro, o reequilíbrio simples é iniciado, causando os seguintes IRPs:

      • IRP_MN_QUERY_STOP_DEVICE (supondo que este IRP seja passado por todos os drivers. O teste já abordou o caso em que esse IRP falhou.)
      • IRP_MN_QUERY_RESOURCE_REQUIREMENTS
      • IRP_MN_FILTER_RESOURCE_REQUIREMENTS. Em resposta a esse IRP, ao subir, o driver de filtro toma medidas com base em se o dispositivo consome recursos ou não:
        • Se o dispositivo não tiver nenhum requisito de recurso, o filtro atribuirá um recurso falso.
        • Se o dispositivo tiver um requisito de recurso, ele tentará reestruturar a lista de requisitos de recursos de forma a maximizar a probabilidade de alterar a atribuição atual. Por exemplo, se um dispositivo precisar de 2 bytes de memória em qualquer lugar entre 00 a FF e atualmente for atribuído 3A-3B, modifique de modo que o novo requisito de recurso (em ordem de preferência) pareça 00-39 ou 3C-FF ou 3A-3B. Da mesma forma, se a lista de requisitos de recursos do dispositivo tiver requisitos alternativos, ela alterará sua ordem para que o requisito alternativo venha anteriormente na lista.

   2. Agora, o dispositivo deve sempre concluir o procedimento de rebalanceamento.

      IRP_MN_STOP_DEVICE

      IRP_MN_START_DEVICE (os novos recursos alocados. Se forem criados requisitos falsos, ocultar os novos recursos dos drivers reais.)

4. Teste de falha de rebalanceamento PNP com reinicialização do dispositivo Esse teste inicia um rebalanceamento, mas quando o driver de filtro recebe a inicialização após o rebalanceamento, ele falha deliberadamente, o que faz com que o IRP de remoção inesperada seja seguido pelo IRP de Remoção.

   Primeiro, ele inicia o procedimento de rebalanceamento e garante que o driver receba uma parada e uma inicialização gerando um requisito de recurso falso para um dispositivo que não consome nenhum recurso.

   • IRP_MN_QUERY_STOP_DEVICE (supondo que este IRP seja passado por todos os drivers. O teste já abordou o caso em que esse IRP falhou.)
   • IRP_MN_QUERY_RESOURCE_REQUIREMENTS
   • IRP_MN_FILTER_RESOURCE_REQUIREMENTS (Se o requisito de recurso real for nulo, aplique um filtro para atribuir um requisito de recurso falso; assim, ocorrerá uma parada e um reinício.)
   • IRP_MN_STOP_DEVICE
   • IRP_MN_START_DEVICE (o filtro falha nesse IRP ao subir. Essa ação causa a remoção surpresa do IRP.)
   • IRP_MN_SURPRISE_REMOVAL
   • IRP_MN_REMOVE

   Depois que o teste de rebalanceamento for concluído, o dispositivo será desinstalado e reenumerado, removendo também o driver de filtro da pilha.

Códigos de erro do dispositivo

Se o teste fornecer uma mensagem de erro informando que o status do dispositivo não está ok, você poderá saber mais sobre o status do dispositivo por meio do Gerenciador de Dispositivos. Para obter um resumo dos vários códigos de erro do dispositivo, consulte Mensagens de Erro do Gerenciador de Dispositivos.

Depurar falhas de instalação usando os logs da API de Instalação

Os logs de API de Instalação (setupapi.app.log e setupapi.dev.log) podem conter informações úteis para depurar falhas de instalação do driver registradas por este teste. Os logs da API de Configuração podem ser encontrados no diretório \inf\ em %windir%no sistema de teste.

Para aumentar a verbosidade e a potencial utilidade desses logs, defina a seguinte chave do Registro para 0x2000FFFF antes de executar o teste de reinstalação:

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

Tópicos relacionados

Como testar um driver em runtime usando o Visual Studio

Como selecionar e configurar os testes de Fundamentos do Dispositivo

Testes de fundamentos do dispositivo

Plug-ins simples de E/S fornecidos pelo WDTF

Como testar um driver em tempo de execução em um prompt de comando