STALL em transferências de controle USB: depuração de pacotes de setup, endpoint zero e requisições com falha

Transferências de controle USB são a base da enumeração e do gerenciamento do dispositivo. Elas leem descritores, definem endereços, selecionam configurações, trocam interfaces, emitem class requests e enviam comandos vendor-specific. Quando uma control transfer trava, o usuário pode ver "USB device not recognized", "control transfer failed", "libusb control transfer error", "endpoint zero stalled" ou um atualizador de firmware que para na inicialização.

Buscas como "USB control transfer STALL", "USB setup packet debugging", "endpoint zero stall", "GET_DESCRIPTOR failed" e "vendor request stalled" geralmente significam que a falha aconteceu antes do tráfego bulk, interrupt ou isochronous normal poder prosseguir.

O Bus Scope ajuda porque o pacote de setup explica a requisição. Sem ele, um STALL é só um erro genérico.

O que uma control transfer contém

Uma control transfer USB tem etapas:

1. Setup stage
2. Data stage opcional
3. Status stage

O pacote de setup contém:

• bmRequestType
• bRequest
• wValue
• wIndex
• wLength

Esses campos definem direção, tipo de requisição, recipient, request code, tipo de descritor, interface, endpoint e tamanho de dado esperado.

Se o dispositivo trava, inspecione o pacote de setup primeiro.

Endpoint zero é especial

Endpoint zero existe em todo dispositivo USB. Ele é usado durante a enumeração e em operações de controle. Se o endpoint zero se comportar errado, o host pode nunca vincular o driver normal.

Falhas no endpoint zero podem aparecer como:

• Device descriptor request failed.
• Configuration descriptor read failed.
• String descriptor request stalled.
• SET_CONFIGURATION failed.
• Class-specific request failed.
• Vendor command failed.

Para firmware custom, a correção do endpoint zero não é negociável.

STALL pode ser válido

Nem todo STALL é bug. Um dispositivo pode legitimamente travar uma requisição não suportada. A pergunta é se o host esperava suporte e se o estado do dispositivo permite a requisição.

Exemplos:

• Vendor request não suportado: STALL pode ser correto.
• Índice de descritor inválido: STALL pode ser correto.
• Class request obrigatória durante a enumeração: STALL pode quebrar o vínculo de driver.
• Requisição DFU no estado errado: STALL pode indicar divergência de máquina de estado.

O significado depende do tipo de requisição e do timing.

Falhas em requisições de descritor

STALLs em descritores são comuns em stacks USB customizados. Fique de olho em:

• Tipo de descritor errado no wValue.
• Índice de string não suportado.
• Mismatch no comprimento total da configuração.
• Dispositivo devolve menos dados do que o pedido de forma incorreta.
• Dispositivo não trata leituras iniciais curtas de descritor.
• Firmware assume um único padrão de requisição do host.

Sistemas operacionais diferentes pedem descritores em ordens diferentes. Um dispositivo que funciona no Linux pode travar uma requisição que o Windows envia durante a enumeração.

Class e vendor requests

Class requests são interpretadas pela classe USB. HID, CDC, DFU, Audio, Video, Mass Storage e dispositivos vendor-specific têm expectativas de requisição.

Exemplos comuns:

• HID GET_REPORT
• HID SET_REPORT
• CDC SET_LINE_CODING
• CDC SET_CONTROL_LINE_STATE
• DFU GETSTATUS
• UVC probe/commit controls
• Comandos vendor-specific de bootloader

Se uma class request trava, confira se o número de interface em wIndex bate com a interface pretendida. Dispositivos compostos frequentemente falham porque o host envia a requisição para uma interface e o firmware trata outra.

Checklist de depuração

Use este fluxo:

1. Capture desde a conexão.
2. Encontre o primeiro STALL em control transfer.
3. Decodifique os campos do pacote de setup.
4. Determine se a requisição é standard, class ou vendor-specific.
5. Determine o recipient: device, interface, endpoint ou outro.
6. Confira wValue, wIndex e wLength.
7. Compare com descritores e o estado atual do dispositivo.
8. Confira se o STALL é esperado ou fatal.
9. Procure requisição de recuperação, como clear feature ou reset.
10. Compare a ordem de requisição entre SOs se o comportamento for diferente entre plataformas.

Diagnóstico final

STALL em control transfer USB não é informação suficiente sozinho. O pacote de setup é a âncora do diagnóstico. Ele diz qual requisição falhou, qual recipient foi endereçado, quanto de dado era esperado e se o estado do dispositivo tornava a requisição válida.

O Bus Scope ajuda a expor a evidência de endpoint zero e do pacote de setup para que equipes de firmware, driver e QA consigam depurar falhas do caminho de controle com precisão.