Verificador de hardware USB (USB3HWVerifierAnalyzer.exe)
Este artigo descreve a ferramenta de verificação de hardware USB (USB3HWVerifierAnalyzer.exe) que é usada para testar e depurar eventos de hardware específicos.
A maioria dos problemas de hardware se manifesta de maneiras que levam a uma experiência insatisfatória para o usuário final e muitas vezes é difícil determinar a falha exata. O verificador de hardware USB visa capturar falhas de hardware que ocorrem em um dispositivo, porta, hub, controlador ou uma combinação deles.
O verificador de hardware USB pode executar as seguintes tarefas:
- Capturar eventos de hardware e exibir informações em tempo real.
- Gerar um arquivo de rastreamento com informações sobre todos os eventos.
- Analisar um arquivo de rastreamento existente para obter informações sobre eventos.
Este artigo inclui as seções a seguir:
- Como obter a ferramenta de analisador do verificador de hardware USB
- Como capturar eventos usando um verificador de hardware USB
- Sinalizadores de verificador de hardware USB
Como obter a ferramenta de analisador do verificador de hardware USB
A ferramenta de verificação de hardware USB está incluída no pacote de software do MUTT que está disponível para download em Ferramentas no pacote de software do MUTT.
O pacote de ferramentas contém várias ferramentas que realizam testes de estresse e transferência (incluindo transições de energia) e testes de SuperSpeed. O pacote também tem um documento Leiame (disponível como um download separado). O documento fornece uma breve visão geral dos tipos de hardware do MUTT. Ele fornece orientação passo a passo sobre vários testes que devem ser executados e sugere topologias para testes de controlador, hub, dispositivo e BIOS/UEFI.
Como capturar eventos usando um verificador de hardware USB
Para capturar eventos usando o verificador de hardware, execute as seguintes etapas:
Inicie uma sessão executando este comando em um prompt de comandos com privilégios elevados.
USB3HWVerifierAnalyzer.exeA ferramenta oferece suporte às seguintes opções:
Opção Descrição -v <VendorID> Registra todos os eventos do verificador de hardware para o VendorID especificado. -p <ProductID> Registra todos os eventos do verificador de hardware para o ProductID especificado. -f <ETL file> Analisa o arquivo ETL especificado. Não há suporte para a análise em tempo real. Com esta opção, a ferramenta analisa o arquivo offline. /v output Exibe todos os eventos no console. Execute o cenário de teste para o qual você deseja capturar eventos de hardware.
Durante uma sessão, o verificador de hardware USB captura informações sobre eventos de hardware à medida que ocorrem. Se desejar filtrar eventos para um hardware específico, especifique o VendorId e o ProductId do hardware. A ferramenta pode não capturar algumas informações (como VID/PID) sobre eventos que ocorrem antes que o dispositivo seja totalmente enumerado. As informações ausentes estão disponíveis no relatório detalhado gerado no final da sessão (discutido a seguir).
Observação
O arquivo ETL AllEvents sempre conterá todos os eventos ETW de todos os dispositivos. Ele não é afetado pelas opções -v e -p.
Esta é a linha de comando para filtrar por VendorId e ProductId:
USB3HWVerifierAnalyzer.exe -v 0781 -p 5595Este é um exemplo de saída da ferramenta de verificação de hardware:
Session Name : TraceSessionFriJan271351112023 Attempting to start session TraceSessionFriJan271351112023... Trace Session created...Status : 0 Provider Enable Success, Status : 0 Provider Enable Success, Status : 0 Provider Enable Success, Status : 0 Provider Enable Success, Status : 0 Provider Enable Success, Status : 0 Provider Enable Success, Status : 0 13319329877.425596: (UsbHub3/179) Event Message: Client Initiated Recovery Action VendorID/ProductID: 0x5e3/0x612 DeviceInterfacePath: \??\USB#VID_05E3&PID_0612#6&130491ac&0&4#{f18a0e88-c30c-11d0-8815-00a0c906bed8} DeviceDescription: Generic SuperSpeed USB Hub PortPath: 0x12, 0x4, 0x0, 0x0, 0x0, 0x0 Provider disable Success, Status : 0 Provider disable Success, Status : 0 Provider disable Success, Status : 0 Provider disable Success, Status : 0 Provider disable Success, Status : 0 Provider disable Success, Status : 0 Session Stopped...Status : 0Pare a sessão pressionando CTRL+C.
No final da sessão, um arquivo chamado AllEvents.etl é adicionado ao diretório atual. Esse arquivo contém informações de rastreamento sobre todos os eventos que foram capturados durante a sessão.
Além de AllEvents.etl, a janela de comando exibe um relatório. O relatório inclui certas informações que foram perdidas na saída em tempo real. A saída a seguir mostra um exemplo de relatório de teste para a sessão anterior. O relatório mostra todos os eventos que o verificador de hardware USB encontrou.
Record #1 (Key = 0x57ff0de4858) VendorID/ProductID: 0x451/0x2077 DeviceInterfacePath: \??\USB#VID_0451&PID_2077#6&c4be011&0&2#{f18a0e88-c30c-11d0-8815-00a0c906bed8} DeviceDescription: Generic USB Hub PortPath: 0x2, 0x0, 0x0, 0x0, 0x0, 0x0 All errors encountered: #1: (UsbHub3/176): DescriptorValidationError20HubPortPwrCtrlMaskZero #2: (UsbHub3/179): Client Initiated Recovery Action #3: (UsbHub3/179): Client Initiated Recovery Action #4: (UsbHub3/179): Client Initiated Recovery Action #5: (UsbHub3/179): Client Initiated Recovery Action #6: (UsbHub3/179): Client Initiated Recovery Action #7: (UsbHub3/179): Client Initiated Recovery Action #8: (UsbHub3/179): Client Initiated Recovery Action #9: (UsbHub3/179): Client Initiated Recovery Action #10: (UsbHub3/179): Client Initiated Recovery Action #11: (UsbHub3/179): Client Initiated Recovery Action #12: (UsbHub3/179): Client Initiated Recovery Action #13: (UsbHub3/179): Client Initiated Recovery Action #14: (UsbHub3/179): Client Initiated Recovery Action Record #2 (Key = 0x57ff62a36a8) VendorID/ProductID: 0x1058/0x740 DeviceInterfacePath: \??\USB#VID_1058&PID_0740#57583931453631414E5A3331#{a5dcbf10-6530-11d2-901f-00c04fb951ed} DeviceDescription: USB Mass Storage Device PortPath: 0x2, 0x4, 0x0, 0x0, 0x0, 0x0 All errors encountered: #1: (UsbHub3/173): SuperSpeed Device is Connected on the 2.0 Bus Record #3 (Key = 0x57ff79fd4e8) VendorID/ProductID: 0x1edb/0xbd3b PortPath: 0x3, 0x0, 0x0, 0x0, 0x0, 0x0 All errors encountered: #1: (UsbHub3/176): DescriptorValidationErrorCompanionIsochEndpointWBytesPerIntervalTooLarge #2: (UsbHub3/176): DescriptorValidationErrorCompanionIsochEndpointWBytesPerIntervalTooLarge #3: (UsbHub3/176): DescriptorValidationErrorCompanionIsochEndpointWBytesPerIntervalTooLarge #4: (UsbHub3/176): DescriptorValidationErrorCompanionIsochEndpointWBytesPerIntervalTooLarge #5: (UsbHub3/176): DescriptorValidationErrorCompanionIsochEndpointWBytesPerIntervalTooLarge #6: (UsbHub3/176): DescriptorValidationErrorCompanionIsochEndpointWBytesPerIntervalTooLarge #7: (UsbHub3/176): DescriptorValidationErrorStringMismatchBetweenBlengthAndBufferLength #8: (UsbHub3/176): DescriptorValidationErrorStringMismatchBetweenBlengthAndBufferLengthNo relatório de exemplo anterior, observe o valor do campo Chave de cada registro. O relatório categoriza as informações por esses valores de Chave, facilitando a leitura. Os mesmos valores de Chave são usados em eventos capturados em AllEvents.etl.
Converta AllEvents.etl em formato de texto executando o seguinte comando:
USB3HWVerifierAnalyzer.exe -f AllEvents.etl /v > Output.txtNo arquivo de saída, procure os valores de Chave observados anteriormente. Os valores estão associados a um destes campos: fid_UcxController, fid_HubDevice e fid_UsbDevice.
Abra AllEvents.etl no Netmon e selecione Adicionar <field_name> para exibir o filtro para filtrar eventos por controlador, hub e dispositivo. Para obter mais informações, consulte Como instalar analisadores Netmon e USB ETW.
Sinalizadores de verificador de hardware USB
| Sinalizador | Indica que... |
|---|---|
| DeviceHwVerifierClientInitiatedResetPipe | O driver do cliente iniciou uma ação de recuperação redefinindo um pipe específico em resposta a falhas de E/S. Determinados drivers do cliente podem executar a recuperação de erros em outros cenários. |
| DeviceHwVerifierClientInitiatedResetPort | O driver do cliente iniciou uma ação de recuperação redefinindo o dispositivo em resposta a falhas de E/S. Determinados drivers do cliente podem executar a recuperação de erros em outros cenários. |
| DeviceHwVerifierClientInitiatedCyclePort | O driver do cliente iniciou uma ação de recuperação ao ciclar a porta. Esse sinalizador faz com que o gerenciador Plug and Play reenumere o dispositivo. |
| DeviceHwVerifierSetIsochDelayFailure | Um dispositivo USB 3.0 falhou na solicitação SET_ISOCH_DELAY. O dispositivo pode falhar na solicitação porque o driver não requer as informações da solicitação ou ocorreu um erro transitório. No entanto, o driver não consegue diferenciar esses motivos. Esse erro não é capturado no relatório. |
| DeviceHwVerifierSetSelFailure | Um dispositivo USB 3.0 falhou na solicitação SET_SEL. O dispositivo usa as informações de solicitação para o LPM (Link Power Management). O dispositivo pode falhar na solicitação porque o driver não requer as informações da solicitação ou ocorreu um erro transitório. No entanto, o driver não consegue diferenciar esses motivos. Esse erro não é capturado no relatório. |
| DeviceHwVerifierSerialNumberMismatchOnRenumeration | O dispositivo relatou um número de série diferente durante a reenumeração, em oposição ao que relatou durante a enumeração inicial. Uma reenumeração pode ocorrer como resultado de uma porta de redefinição ou operação de retomada do sistema. |
| DeviceHwVerifierSuperSpeedDeviceWorkingAtLowerSpeed | O dispositivo USB 3.0 está operando uma velocidade de barramento menor do que SuperSpeed. |
| DeviceHwVerifierControlTransferFailure | Uma transferência de controle para o ponto de extremidade padrão do dispositivo falhou. A transferência pode falhar como resultado de um erro do dispositivo ou do controlador. Os logs do hub indicam o código de status USBD para a falha de transferência. Esse sinalizador exclui falhas de transferências de controle SET_SEL e SET_ISOCH_DELAY. Esses tipos de solicitações são cobertos pelos sinalizadores DeviceHwVerifierSetIsochDelayFailure e DeviceHwVerifierSetSelFailure. |
| DeviceHwVerifierDescriptorValidationFailure | Um descritor retornado pelo dispositivo não está em conformidade com a especificação USB. O log do hub indica o erro exato. |
| DeviceHwVerifierInterfaceWakeCapabilityMismatch | O bit RemoteWake está definido incorretamente no dispositivo. Os dispositivos USB 3.0 compatíveis com a ativação remota também devem ser compatíveis com a função de ativação. Há duas maneiras pelas quais o dispositivo indica seu suporte para a função de ativação. A primeira maneira é por meio do campo bmAttributes do descritor de configuração e a segunda maneira é em sua resposta à solicitação GET_STATUS direcionada para a interface. Para um dispositivo não composto, o valor de bit RemoteWake deve corresponder ao valor retornado pela solicitação GET_STATUS direcionada à interface 0. Para dispositivos compostos, o bit RemoteWake deve ser 1 para pelo menos uma das funções. Caso contrário, esse sinalizador indica que o dispositivo relatou valores contraditórios. |
| DeviceHwVerifierBusRenumeration | O dispositivo é reenumerado no barramento. Uma reenumeração pode ocorrer como resultado de uma porta de redefinição ou operação de retomada do sistema. A reenumeração também ocorre quando o dispositivo é desabilitado/habilitado ou interrompido/iniciado. |
| HubHwVerifierTooManyResets | Um hub passou por muitas operações de redefinição em um curto período. Mesmo que essas redefinições tenham sido bem-sucedidas, o hub não está processando solicitações e ocorrem erros repetidos. |
| HubHwVerifierControlTransferFailure | Uma transferência de controle direcionada para o ponto de extremidade padrão do hub falhou. A transferência pode falhar como resultado de um erro do dispositivo ou do controlador. Os logs do hub indicam o código de status USBD para a falha. |
| HubHwVerifierInterruptTransferFailure | Uma transferência de dados direcionada ao ponto de extremidade de interrupção do hub falhou. A transferência pode falhar como resultado de um erro do dispositivo ou do controlador. Os logs do hub indicam o código de status USBD para a falha. Se a transferência falhou porque a solicitação foi cancelada, a falha não é capturada. |
| HubHwVerifierNoSelectiveSuspendSupport | O bit RemoteWake não está definido como 1 no descritor de configuração do hub. |
| HubHwVerifierPortResetTimeout | Ao enumerar ou reenumerar um dispositivo, a operação de redefinição de porta está atingindo o tempo limite. Uma notificação de alteração de porta não é recebida indicando que a redefinição de porta está concluída. |
| HubHwVerifierInvalidPortStatus | O status da porta de destino não é válido de acordo com a especificação USB. Determinados dispositivos podem fazer com que o hub relate o status inválido. |
| HubHwVerifierPortLinkStateSSInactive | O link entre a porta de destino e o dispositivo downstream está em um estado de erro. |
| HubHwVerifierPortLinkStateCompliance | O link entre a porta de destino e o dispositivo downstream está no modo de conformidade. Em alguns cenários envolvendo a retomada do modo de suspensão do sistema, o erro do modo de conformidade é esperado e, nesses casos, a falha não é capturada. |
| HubHwVerifierPortDeviceDisconnected | O dispositivo downstream na porta de destino não está mais conectado ao barramento. |
| HubHwVerifierPortOverCurrent | A porta downstream relatou estado de sobrecarga. |
| HubHwVerifierControllerOperationFailure | Uma operação do controlador (como habilitar dispositivo, configurar pontos de extremidade) falhou para o dispositivo conectado à porta de destino. As falhas de solicitações SET_ADDRESS e ponto de extremidade Reset não são capturadas. |