Desajuste de max packet size en endpoints USB: depurando wMaxPacketSize, short packets, bulk transfers y bugs de buffer en firmware

El wMaxPacketSize del endpoint USB parece un campo pequeño del descriptor, pero un valor erróneo puede romper bulk transfers, interrupt reports, operación en high-speed, buffering del firmware y las suposiciones del driver del host. Los usuarios buscan "USB wMaxPacketSize mismatch", "USB short packet problem", "bulk transfer stops at 64 bytes", "USB endpoint packet size high speed full speed" y "USB descriptor max packet size bug" cuando las transferencias fallan solo a ciertos tamaños o velocidades.

Bus Scope ayuda porque el fallo solo es visible cuando los descriptores y los paquetes de transferencia se comparan juntos. El descriptor puede reclamar un packet size mientras el firmware, el código del host o el hardware del endpoint se comportan como otro.

Qué controla wMaxPacketSize

Cada endpoint descriptor incluye wMaxPacketSize. Indica al host el payload máximo por paquete para ese endpoint. Los valores típicos dependen de la velocidad y del tipo de endpoint.

Ejemplos:

• Endpoint bulk en full-speed: a menudo 64 bytes.
• Endpoint bulk en high-speed: a menudo 512 bytes.
• Endpoints interrupt: varían según velocidad e interval.
• Endpoints isochronous: usan packet sizes ligados al ancho de banda.

Si el firmware configura los buffers del endpoint para 64 bytes pero anuncia 512, el host puede mandar transferencias que el dispositivo no maneja bien.

Síntomas habituales

Los bugs de max packet size pueden aparecer como:

• La bulk transfer va con mensajes pequeños pero falla con los grandes.
• El dispositivo funciona en full-speed pero falla en high-speed.
• La transferencia se para justo después de 64 bytes.
• El host espera eternamente un short packet.
• El firmware recibe datos partidos de forma inesperada.
• El dispositivo hace STALL en transferencias OUT.
• Las transferencias IN devuelven datos truncados.
• El driver reporta timeout aunque haya tráfico.
• El dispositivo compuesto funciona en una interfaz pero no en otra.

El conteo exacto de bytes suele ser la pista.

Comportamiento de short packet

Las bulk transfers USB suelen usar short packets para indicar el fin de la transferencia cuando la longitud pedida es mayor que los datos reales. Si el dispositivo devuelve exactamente un múltiplo del max packet size, el host puede esperar más datos a menos que el protocolo defina la longitud aparte o mande un zero-length packet.

Por ejemplo:

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

Por eso "USB short packet" y "USB zero length packet" son términos muy buscados. Un dispositivo puede pasar tests simples y luego colgarse cuando la longitud del payload cae justo en un límite de paquete.

Desajuste high-speed frente a full-speed

Algunos dispositivos se comportan bien en full-speed pero fallan en high-speed. Las causas incluyen:

• El descriptor high-speed anuncia 512 bytes.
• El buffer del firmware sigue siendo de 64 bytes.
• Cambia la alineación de DMA en high-speed.
• El FIFO del endpoint es demasiado pequeño.
• El driver del host asume packetization de high-speed.
• El device descriptor difiere entre modos de velocidad.

Bus Scope debería ayudar a comparar la velocidad de enumeración, los valores del endpoint descriptor y el chunking real de la transferencia.

Errores de copy-paste en descriptores

Los equipos de firmware suelen copiar endpoint descriptors entre interfaces o modos. Eso puede generar bugs sutiles:

• El endpoint interrupt anuncia un tamaño estilo bulk.
• El tamaño del endpoint OUT difiere del IN sin razón.
• El alternate setting tiene otro tamaño pero el firmware no reconfigura el endpoint.
• Los árboles de descriptores full-speed y high-speed no coinciden.
• Los descriptores asociados no encajan con el throughput esperado.

La vista de diagnóstico correcta vincula la dirección del endpoint con su descriptor y con cada transferencia sobre ese endpoint.

Bugs de buffer en el firmware

Incluso cuando el descriptor es correcto, el firmware puede procesar mal los datos:

• Asume que un paquete USB equivale a un mensaje de aplicación.
• No maneja mensajes partidos.
• Pierde zero-length packets.
• Trata el short packet como error.
• Sobrescribe el buffer de recepción tras el primer paquete.
• Falla cuando la longitud de la transferencia es igual al max packet size.
• No hace flush del endpoint IN tras el short packet final.

Estos bugs son frecuentes en dispositivos vendor-specific y bootloaders porque el protocolo suele ser a medida.

Suposiciones del driver del host

El código del host también puede estar mal. Puede:

• Pedir un buffer demasiado pequeño.
• Esperar que una read equivalga a un mensaje del dispositivo.
• Ignorar la terminación por short packet.
• Usar un timeout en lugar de framing por longitud de protocolo.
• Mandar un comando más grande que el buffer del firmware.
• Olvidarse del comportamiento del zero-length packet.

Cuando ambos lados son a medida, la traza de paquetes se vuelve el contrato.

Evidencia a recoger

Para diagnosticar un max packet size, reúne:

• Velocidad del dispositivo.
• Endpoint descriptor.
• Dirección del endpoint.
• wMaxPacketSize.
• Tamaño de transferencia pedido por el host.
• Tamaños de paquete realmente observados.
• Presencia de short packet o zero-length packet.
• STALL, NAK, timeout o reset tras la transferencia.
• Diferencia entre enumeración full-speed y high-speed.
• Logs de firmware si están disponibles.

Los mejores informes incluyen conteos exactos de bytes. Los motores de búsqueda también hacen match con esos detalles prácticos.

Checklist de depuración

Usa este proceso:

1. Identifica el endpoint descriptor.
2. Apunta wMaxPacketSize.
3. Compara el modo de velocidad.
4. Envía payloads por debajo, igual y por encima del max packet size.
5. Prueba múltiplos exactos del max packet size.
6. Busca short packet o zero-length packet.
7. Comprueba si el host espera tras el paquete final.
8. Compara comportamiento de endpoints IN y OUT.
9. Revisa cambios de alternate setting.
10. Conserva la secuencia de la transferencia que falla.

Diagnóstico final

Los bugs de max packet size en endpoints USB son problemas de descriptor, transferencia y contrato de firmware. La evidencia útil es el wMaxPacketSize anunciado, la packetization real, el comportamiento del short packet, el manejo del zero-length packet, el modo de velocidad y los fallos específicos del endpoint.

Bus Scope ayuda a los ingenieros a demostrar si el bug está en el descriptor, en el manejo de buffers del firmware, en las suposiciones del driver del host o en el framing de la transferencia.