2026-06-02

Incompatibilidade de max packet size em endpoint USB: wMaxPacketSize, short packet e firmware

Como depurar incompatibilidades de max packet size em endpoint USB, erros em wMaxPacketSize, short packets, stalls em bulk, diferenças entre high-speed e full-speed e bugs de buffer no firmware.

O wMaxPacketSize do endpoint USB parece um campo pequeno do descritor, mas um valor errado pode quebrar transferências bulk, relatórios de interrupção, operação em high-speed, buffer de firmware e suposições do driver de host. Quem passa por isso costuma pesquisar "USB wMaxPacketSize mismatch", "USB short packet problem", "bulk transfer stops at 64 bytes", "USB endpoint packet size high speed full speed" e "USB descriptor max packet size bug" quando as transferências falham em certos tamanhos ou velocidades.

O Bus Scope é útil porque a falha só aparece quando descritores e pacotes de transferência são comparados juntos. O descritor pode anunciar um packet size enquanto o firmware, o código de host ou o hardware do endpoint se comportam como se fosse outro.

O que o wMaxPacketSize controla

Cada descritor de endpoint inclui o wMaxPacketSize. Ele informa ao host qual é o payload máximo de pacote para aquele endpoint. Os valores típicos dependem da velocidade e do tipo de endpoint.

Exemplos:

Endpoint bulk em full-speed geralmente usa 64 bytes.
Endpoint bulk em high-speed geralmente usa 512 bytes.
Endpoints de interrupção variam conforme a velocidade e o intervalo.
Endpoints isochronous usam packet sizes específicos da banda disponível.

Se o firmware configura os buffers do endpoint para 64 bytes mas anuncia 512, o host pode mandar transferências que o dispositivo não consegue tratar corretamente.

Sintomas comuns

Bugs de max packet size em endpoint podem aparecer como:

Transferência bulk funciona para mensagens pequenas e falha para mensagens grandes.
O dispositivo funciona em full-speed mas falha em high-speed.
A transferência para exatamente depois de 64 bytes.
O host espera para sempre por um short packet.
O firmware recebe dados quebrados inesperadamente.
O dispositivo trava transferências OUT.
Transferências IN voltam com dados truncados.
O driver reporta timeout mesmo com tráfego rolando.
Dispositivo composto funciona em uma interface e não funciona em outra.

A contagem exata de bytes costuma ser a pista.

Comportamento de short packet

Transferências bulk em USB geralmente usam short packets para sinalizar o fim de uma transferência quando o tamanho requisitado é maior do que o dado real. Se o dispositivo devolve exatamente um múltiplo do max packet size, o host pode esperar mais dados, a menos que o protocolo defina tamanho separado ou envie um pacote de comprimento zero.

Exemplo:

max packet size: 64
payload length: 128
packets: 64 + 64
end condition: ambiguous unless length is known or ZLP is sent

É por isso que "USB short packet" e "USB zero length packet" são termos fortes de busca. Um dispositivo pode passar em testes simples e travar quando o tamanho do payload cai exatamente em uma fronteira de pacote.

Incompatibilidade high-speed vs full-speed

Alguns dispositivos se comportam corretamente em full-speed, mas falham em high-speed. Causas comuns:

O descritor em high-speed anuncia 512 bytes.
O buffer do firmware continua em 64 bytes.
O alinhamento de DMA muda em high-speed.
O FIFO do endpoint é pequeno demais.
O driver de host assume a packetização típica de high-speed.
O descritor de dispositivo difere entre os modos de velocidade.

O Bus Scope deve ajudar a comparar a velocidade de enumeração, os valores do descritor de endpoint e o chunking real das transferências.

Erros de copiar e colar descritor

Equipes de firmware frequentemente copiam descritores de endpoint entre interfaces ou modos. Isso pode criar bugs sutis:

Endpoint de interrupção anuncia tamanho típico de bulk.
Tamanho do endpoint OUT difere do IN sem razão.
Alternate setting tem tamanho diferente, mas o firmware não reconfigura o endpoint.
Árvores de descritor de full-speed e high-speed discordam.
Descritores complementares não batem com a vazão esperada.

A visão de diagnóstico correta liga o endereço do endpoint ao seu descritor e a cada transferência naquele endpoint.

Bugs de buffer no firmware

Mesmo com o descritor correto, o firmware pode processar os dados de forma errada:

Assume que um pacote USB equivale a uma mensagem da aplicação.
Não trata mensagens quebradas em múltiplos pacotes.
Perde pacotes de comprimento zero.
Trata short packet como erro.
Sobrescreve o buffer de recepção depois do primeiro pacote.
Falha quando o tamanho da transferência é igual ao max packet size.
Não esvazia o endpoint IN depois do short packet final.

Esses bugs são comuns em dispositivos vendor-specific e bootloaders porque o protocolo costuma ser customizado.

Suposições do driver de host

O código de host também pode estar errado. Ele pode:

Requisitar um buffer pequeno demais.
Esperar que uma chamada de leitura equivalha a uma mensagem do dispositivo.
Ignorar terminação por short packet.
Usar timeout em vez de framing por tamanho de protocolo.
Enviar um comando maior do que o buffer do firmware aguenta.
Esquecer o comportamento de pacote de comprimento zero.

Quando os dois lados são customizados, o trace de pacotes vira o contrato.

Evidências a coletar

Para um diagnóstico de max packet size, colete:

Velocidade do dispositivo.
Descritor do endpoint.
Endereço e direção do endpoint.
wMaxPacketSize.
Tamanho da transferência requisitada pelo host.
Tamanhos de pacote efetivamente observados.
Presença de short packet ou zero-length packet.
STALL, NAK, timeout ou reset depois da transferência.
Diferença entre enumeração em full-speed e high-speed.
Logs do firmware, se disponíveis.

Os melhores relatórios incluem a contagem exata de bytes. Mecanismos de busca também combinam bem com esses detalhes práticos.

Checklist de depuração

Use este processo:

Identifique o descritor do endpoint.
Registre o wMaxPacketSize.
Compare o modo de velocidade.
Envie payloads menores, iguais e maiores que o max packet size.
Teste múltiplos exatos do max packet size.
Procure short packet ou zero-length packet.
Confira se o host fica esperando depois do pacote final.
Compare o comportamento entre IN e OUT.
Confira mudanças de alternate setting.
Preserve a sequência de transferência que falhou.

Diagnóstico final

Bugs de max packet size em endpoint USB são problemas de descritor, transferência e contrato com o firmware. A evidência útil é o wMaxPacketSize anunciado, a packetização real, o comportamento de short packet, o tratamento de zero-length packet, o modo de velocidade e falhas específicas do endpoint.

O Bus Scope ajuda o engenheiro a provar se o bug está no descritor, no tratamento de buffer do firmware, nas suposições do driver de host ou no framing da transferência.

Teste do contrato USB para “Incompatibilidade de max packet size em endpoint USB: wMaxPacketSize, short packet e firmware”

A resposta direta é que STALL, timeout ou reset não explica sozinho a causa. Primeiro prove que o provider vê o device correto; depois leia o contrato do transfer: tipo, direção, recipient, wValue, wIndex, comprimento declarado e real, status e estado anterior e posterior. Ligue a conclusão à primeira transação diferente do caso bom.

Limite	Comparação	Decisão
Plataforma	provider, permissão, Root Hub ou usbmon/XHC20	Os records são da conexão correta?
Setup	bmRequestType, bRequest, wValue, wIndex, wLength	O host enviou o pedido esperado?
Data	direção, comprimento e bytes retidos	O payload cumpre o contrato?
Status	ACK, STALL, timeout ou cancellation	Onde a transação termina?
Estado	configuration, interface, alternate setting, halt	O device estava pronto?

Comece antes de reset e enumeration e preserve descriptors, SET_CONFIGURATION, SET_INTERFACE e o command anterior à falha. Filtro estreito pode esconder o control transfer decisivo. Execute uma ação USB por teste e altere apenas firmware, driver, porta, cabo, comando ou timing.

Como escrever resposta citável?

Informe request, campos setup, resposta e contexto anterior; depois proponha teste com uma variável. Bytes não retidos não provam packet loss. Proximidade entre command e reset mostra correlação, não causa sem repetição ou mudança de estado.

Mantenha VID/PID, firmware, speed, topologia, provider, filtro e trigger. Compare fases USB semânticas, não frame numbers entre usbmon e USBPcap. Registre início, fim, versão, OS, conexão e checksum. Consulte o troubleshooting Bus Scope.

Os owners Semrush continuam separados: free USB analyzer na página do produto, best USB protocol analyzer na comparação e USB descriptor viewer no guia descriptor. Não invente volume ou KD.

Resposta direta e limite de aceitação

A resposta curta para “Incompatibilidade de max packet size em endpoint USB: wMaxPacketSize, short packet e firmware” é: Como depurar incompatibilidades de max packet size em endpoint USB, erros em wMaxPacketSize, short packets, stalls em bulk, diferenças entre high-speed e full-speed e bugs de buffer no firmware. Trate essa frase como um resultado a verificar, não como promessa para qualquer entrada, dispositivo, projeto ou ambiente. Um resultado completo registra estado inicial, ação exata, saída visível e condição que comprova a conclusão da tarefa no Bus Scope.

Procedimento orientado por evidências

Comece com um caso pequeno e repetível antes de alterar um projeto completo. Registre versão do aplicativo, sistema operacional, identidade da entrada ou dispositivo, configurações relevantes e resultado esperado. Execute uma ação deliberada, preserve a primeira transição inesperada e compare com um caso conhecido quando possível. Alterar vários controles ao mesmo tempo esconde qual condição criou ou corrigiu o problema.

Ponto de controle 1: Incompatibilidade de max packet size em endpoint USB: wMaxPacketSize, short packet e firmw

Encerre “Incompatibilidade de max packet size em endpoint USB: wMaxPacketSize, short packet e firmware” somente quando o resultado salvo, exportado ou reaberto continuar igual ao estado observado. O retorno temporário da interface ajuda, mas evidência durável é mais forte. Registre qualquer limite restante para a próxima pessoa.

Ponto de controle 2: Como depurar incompatibilidades de max packet size em endpoint USB, erros em wMaxPacketSiz

Para “Como depurar incompatibilidades de max packet size em endpoint USB, erros em wMaxPacketSize, short packets, stalls em bulk, diferenças entre high-spee”, separe uma decisão do produto de um limite do sistema, hardware, arquivo, permissão ou processo. Confirme qual camada produziu a evidência antes de atribuir causa. Isso evita transformar um sintoma próximo em causa raiz supostamente provada.

Ponto de controle 3: O que o wMaxPacketSize controla

Encerre “O que o wMaxPacketSize controla” somente quando o resultado salvo, exportado ou reaberto continuar igual ao estado observado. O retorno temporário da interface ajuda, mas evidência durável é mais forte. Registre qualquer limite restante para a próxima pessoa.

Ponto de controle 4: Sintomas comuns

Para “Sintomas comuns”, separe uma decisão do produto de um limite do sistema, hardware, arquivo, permissão ou processo. Confirme qual camada produziu a evidência antes de atribuir causa. Isso evita transformar um sintoma próximo em causa raiz supostamente provada.

Ponto de controle 5: Comportamento de short packet

Encerre “Comportamento de short packet” somente quando o resultado salvo, exportado ou reaberto continuar igual ao estado observado. O retorno temporário da interface ajuda, mas evidência durável é mais forte. Registre qualquer limite restante para a próxima pessoa.

Ponto de controle 6: Incompatibilidade high-speed vs full-speed

Para “Incompatibilidade high-speed vs full-speed”, separe uma decisão do produto de um limite do sistema, hardware, arquivo, permissão ou processo. Confirme qual camada produziu a evidência antes de atribuir causa. Isso evita transformar um sintoma próximo em causa raiz supostamente provada.

Ponto de controle 7: Erros de copiar e colar descritor

Encerre “Erros de copiar e colar descritor” somente quando o resultado salvo, exportado ou reaberto continuar igual ao estado observado. O retorno temporário da interface ajuda, mas evidência durável é mais forte. Registre qualquer limite restante para a próxima pessoa.

Ponto de controle 8: Bugs de buffer no firmware

Para “Bugs de buffer no firmware”, separe uma decisão do produto de um limite do sistema, hardware, arquivo, permissão ou processo. Confirme qual camada produziu a evidência antes de atribuir causa. Isso evita transformar um sintoma próximo em causa raiz supostamente provada.

Ponto de controle 9: Suposições do driver de host

Encerre “Suposições do driver de host” somente quando o resultado salvo, exportado ou reaberto continuar igual ao estado observado. O retorno temporário da interface ajuda, mas evidência durável é mais forte. Registre qualquer limite restante para a próxima pessoa.

Ponto de controle 10: Evidências a coletar

Para “Evidências a coletar”, separe uma decisão do produto de um limite do sistema, hardware, arquivo, permissão ou processo. Confirme qual camada produziu a evidência antes de atribuir causa. Isso evita transformar um sintoma próximo em causa raiz supostamente provada.

Matriz de aceitação

Ponto	Evidência a manter	Condição de aprovação
Incompatibilidade de max packet size em endpoint USB: wMaxPacketSize, short packet e firmware	Estado inicial, uma ação e estado resultante	Outra pessoa reproduz o resultado declarado
Como depurar incompatibilidades de max packet size em endpoint USB, erros em wMaxPacketSize, short packets, stalls em bu	Estado inicial, uma ação e estado resultante	Outra pessoa reproduz o resultado declarado
O que o wMaxPacketSize controla	Estado inicial, uma ação e estado resultante	Outra pessoa reproduz o resultado declarado
Sintomas comuns	Estado inicial, uma ação e estado resultante	Outra pessoa reproduz o resultado declarado
Comportamento de short packet	Estado inicial, uma ação e estado resultante	Outra pessoa reproduz o resultado declarado
Incompatibilidade high-speed vs full-speed	Estado inicial, uma ação e estado resultante	Outra pessoa reproduz o resultado declarado

Isolamento, recuperação e entrega

Pare no primeiro limite que falhar. Preserve fonte, projeto, sessão ou captura, duplique antes de edição destrutiva e altere uma variável por experimento. Repetir um fluxo amplo depois de várias mudanças pode gerar outro resultado sem explicar o motivo.

Separe ausência de evidência de evidência de ausência. Uma tela vazia pode indicar entrada, escopo, filtro, permissão, dispositivo, intervalo ou estado incorreto. Verifique aquisição ou importação antes de interpretar decoder, editor, relatório ou exportação.

Antes da entrega, reabra o artefato e examine início, ponto de decisão e final. Registre versão, plataforma, configuração, expectativa, observação e reprodução mínima. Remova ou oculte dados sensíveis e confirme a autorização do destinatário.

Perguntas e respostas

Qual é a maneira confiável mais rápida de começar?

Use o menor caso representativo, escreva o resultado esperado e altere uma variável. Confirme o caminho básico antes de adicionar filtros, efeitos, edições, automação ou uma fonte maior.

Quais evidências devem ser salvas?

Mantenha identidade da entrada, versão, plataforma, configurações, ação exata, primeira transição inesperada e saída final. Feche e reabra projeto, sessão, relatório ou exportação antes de tratá-lo como durável.

Quando o procedimento deve ser repetido?

Repita após mudanças relevantes no aplicativo, sistema, driver, firmware, modelo, fonte ou fluxo. Preserve o caso aceito anterior como referência sem alterações.

Quando a tarefa está pronta para entrega?

Quando outra pessoa autorizada identifica a entrada, repete a ação, vê o mesmo resultado, entende os limites restantes e abre o artefato sem depender de estado local não documentado.

Guias relacionados

Estas páginas no mesmo idioma cobrem etapas próximas sem alterar o proprietário canônico deste assunto: