Depuración de descriptores USB para dispositivos HID y CDC

Los dispositivos HID y CDC son populares porque permiten a los equipos de firmware lanzar interfaces USB útiles sin escribir un driver a medida para cada host. Esa comodidad depende de que los descriptores sean precisos. Cuando un teclado HID, un sensor, un bridge serie o un dispositivo compuesto falla, la causa raíz suele ser visible en la evidencia de descriptores antes de aparecer en la aplicación.

Depurar descriptores no es glamuroso, pero es una de las formas más rápidas de cerrar casos de soporte USB.

HID: el report descriptor es el contrato

Para dispositivos HID, el host necesita más que información de endpoints. Necesita el HID report descriptor. Ese descriptor define los report IDs, usages, tamaños, recuentos, rangos lógicos y cómo se deben interpretar los bytes.

Errores HID frecuentes:

• La longitud del report no encaja con los payloads reales del endpoint interrupt.
• El report ID se usa en firmware pero no se declara de forma consistente.
• Los valores logical min y max no coinciden con la representación de los datos.
• El usage page o el usage no coinciden con lo que espera el host.
• El endpoint interval no es realista para el comportamiento del dispositivo.
• Las suposiciones de boot protocol entran en conflicto con el comportamiento de report protocol.

Un error del host puede sonar vago. Una captura que enseñe los bytes del descriptor y las transferencias de interrupt puede hacer evidente el desajuste.

CDC: el layout de interfaces importa

Los dispositivos CDC ACM suelen exponer una interfaz de comunicación y una interfaz de datos. El host espera un conjunto coherente de descriptores y class-specific requests. Un functional descriptor que falta, un interface association equivocado o un desajuste de endpoint pueden impedir que aparezca el puerto serie virtual.

Evidencia a inspeccionar:

• Interface class y subclass.
• Descriptores CDC header, ACM, union y call management.
• Notification endpoint.
• Endpoints bulk IN y OUT.
• SET_LINE_CODING.
• SET_CONTROL_LINE_STATE.
• Transferencias de datos tras la configuración.

Si el puerto serie aparece pero no se mueven bytes, el problema puede estar en el comportamiento del endpoint o en el protocolo de aplicación. Si el puerto serie nunca aparece, descriptores y class requests son lo primero que hay que mirar.

Los dispositivos compuestos exigen disciplina extra

Los dispositivos compuestos pueden combinar HID, CDC, mass storage, interfaces vendor-specific y más. Es útil, pero multiplica los modos de fallo. Un error de descriptor en una interfaz puede afectar al binding de host para todo el dispositivo.

Para depurar compuestos, inspecciona:

• Longitud total de la configuración.
• Números de interfaz.
• Interface Association Descriptors.
• Unicidad de endpoints.
• Posición de los class-specific descriptors.
• Peticiones del host por interfaz.

No des por sentado que "el firmware manda los bytes correctos" hasta que la captura demuestre que el host vio la estructura correcta.

Por qué importan tanto los bytes en crudo como la interpretación de clase

Los bytes en crudo son la verdad de los hechos. La interpretación de clase los hace útiles. Una buena herramienta de diagnóstico USB debería enseñar ambas. Los ingenieros necesitan ver los bytes exactos del descriptor cuando algo va mal, pero también necesitan campos decodificados para no tener que contar offsets a mano en cada caso.

El mejor flujo es:

1. Inspeccionar el árbol de descriptores decodificado.
2. Saltar a los bytes en crudo para los campos sospechosos.
3. Comparar las peticiones del host con las respuestas del firmware.
4. Inspeccionar las transferencias de endpoint tras la configuración.
5. Guardar la sesión para reproducción o entrega a soporte.

Ese flujo mantiene el diagnóstico atado a la evidencia.

Dónde encaja Bus Scope

Bus Scope está pensado para equipos de firmware, laboratorios de hardware y fabricantes de dispositivos que necesitan una respuesta repetible a por qué falla el tráfico USB. Mantiene el contexto del explorador de dispositivos, el detalle de paquetes, los bytes en crudo, los descriptores, las observaciones de clase, los filtros y las sesiones .bscope guardadas en un único banco de trabajo.

Para casos HID y CDC, Bus Scope debería ayudar a responder:

• ¿La enumeración terminó?
• ¿Los descriptores coincidían con la clase objetivo?
• ¿Mandó el host las class requests esperadas?
• ¿Las transferencias de endpoint coincidieron con las expectativas del report o del line coding?
• ¿Es esto un problema de firmware, driver del host o protocolo de aplicación?

Esa es la diferencia entre ver "driver failed" y entender qué contrato USB se rompió.