Recuperação de halt em endpoint USB: CLEAR_FEATURE, loops de STALL e reset do driver

Halts em endpoint USB são uma causa comum do tipo de bug "funciona uma vez, depois falha". Uma transferência bulk trava, o driver limpa o halt, o dispositivo trava de novo e, no fim, a aplicação reporta timeout, erro de I/O, reset do dispositivo ou desconexão. Quem passa por isso costuma pesquisar por "USB endpoint halt", "CLEAR_FEATURE ENDPOINT_HALT", "USB STALL loop", "bulk endpoint stalled" e "libusb clear halt" quando o dispositivo não desaparece, mas simplesmente para de aceitar tráfego em um endpoint específico.

O Bus Scope é útil porque a recuperação de halt em endpoint é uma sequência, não um evento isolado. Você precisa ver o primeiro STALL, a requisição de recuperação do host, o que o dispositivo fez depois e se o mesmo comando provocou o halt de novo.

O que significa halt em endpoint

Um halt em endpoint significa que o endpoint está travado e não pode continuar as transferências normais até a condição de halt ser limpa. O host pode emitir:

CLEAR_FEATURE(ENDPOINT_HALT)

para o endpoint afetado. Depois disso, o data toggle do endpoint e o estado interno do dispositivo precisam estar coerentes para a transferência voltar ao normal.

Se o firmware limpa só o flag de hardware do USB, mas não o estado interno do protocolo, a próxima transferência pode falhar de novo.

STALL versus timeout

STALL é explícito. Timeout significa que não houve conclusão dentro do tempo esperado. Um timeout pode acontecer porque o endpoint nunca respondeu, o dispositivo ficou mandando NAK ou porque o dispositivo se desconectou.

A recuperação de halt em endpoint começa com um STALL. Se o host nunca vê um STALL e só vê timeout, o caminho de recuperação é outro.

Halt em endpoint bulk

Endpoints bulk geralmente travam quando um comando é inválido, uma fase do protocolo está errada ou o firmware detecta um erro.

Exemplo:

Host -> Device bulk OUT command
Device -> Host STALL on bulk IN
Host -> Device CLEAR_FEATURE(ENDPOINT_HALT)
Host retries bulk IN
Device stalls again

Esse padrão sugere que o halt do endpoint é sintoma de estado do protocolo do dispositivo, não apenas um erro transitório de barramento.

A recuperação precisa casar com a direção do endpoint

Os endereços de endpoint incluem direção. O endpoint 0x81 e o endpoint 0x01 são direções diferentes. Limpar o endpoint errado não recupera o pipe travado.

Confira:

• Qual endpoint travou?
• Direção IN ou OUT?
• O host limpou o mesmo endpoint?
• As transferências voltaram ao normal depois do clear?
• O data toggle e o estado foram recuperados de forma coerente?

Essa é uma fonte comum de relatórios enganosos do tipo "o clear halt não funcionou".

Loops de STALL repetido

STALL repetido depois do clear normalmente significa que a causa de fundo continua:

• O host envia de novo um comando não suportado
• A máquina de estado do firmware continua em erro
• O dispositivo espera um reset antes de tentar de novo
• O host lê do endpoint errado
• O tamanho do comando ou o checksum está errado
• O data toggle ou o estado do endpoint está incoerente
• O firmware exige uma requisição de classe/vendor antes de continuar

O trace precisa incluir o comando antes do primeiro STALL, não só as tentativas de recuperação.

Comportamento de reset do driver

Se a recuperação por clear halt falha, o driver pode resetar o dispositivo. Isso pode esconder o erro original do endpoint. O usuário vê uma reconexão ou o dispositivo sumir, mas a evidência do barramento mostra que a primeira falha real foi um loop de STALL.

Preserve a linha do tempo:

1. Último comando bem-sucedido.
2. Primeiro STALL.
3. Tentativa de clear halt.
4. Retry.
5. STALL ou timeout repetido.
6. Reset ou desconexão do dispositivo.

Checklist de depuração

Use este fluxo:

1. Identifique o endpoint que travou.
2. Registre a direção e o tipo de transferência do endpoint.
3. Inspecione o comando ou a transferência imediatamente antes do STALL.
4. Confira se o host envia CLEAR_FEATURE(ENDPOINT_HALT).
5. Confirme que ele mira o endpoint correto.
6. Veja se a transferência voltou ao normal.
7. Se o STALL se repete, inspecione o estado do protocolo no firmware.
8. Procure por reset do dispositivo depois de uma recuperação malsucedida.
9. Compare com uma sequência de comandos sabidamente boa.
10. Preserve contexto suficiente antes do STALL.

Diagnóstico final

A recuperação de halt em endpoint USB é um problema de máquina de estado. CLEAR_FEATURE(ENDPOINT_HALT) pode limpar a condição do endpoint USB, mas não corrige sozinho o estado do protocolo no firmware, comandos inválidos, endpoints errados ou a lógica de retry do driver.

O Bus Scope ajuda a expor a sequência completa de halt e recuperação para que as falhas de endpoint possam ser diagnosticadas a partir do comportamento real do barramento.