Depuración del descriptor USB BOS y Microsoft OS: WebUSB, WinUSB, WCID y binding de drivers en Windows

Muchos dispositivos USB modernos dependen de descriptores más allá de los clásicos device y configuration. Los descriptores BOS, Microsoft OS, WCID, capacidades de plataforma WebUSB y compatible IDs de WinUSB controlan cómo Windows enlaza drivers y cómo navegadores o herramientas descubren capacidades del dispositivo. Cuando esos descriptores fallan, los usuarios ven "WinUSB driver not binding", "WebUSB device not found", "USB BOS descriptor failed", "Microsoft OS descriptor invalid" o "device works on Linux but not Windows".

Bus Scope ayuda porque los problemas derivados de descriptores ocurren durante la enumeración. Si no capturas las peticiones de descriptor, solo verás el síntoma final en el Administrador de dispositivos o en la aplicación.

Qué es el descriptor BOS

BOS significa Binary Object Store. Permite a un dispositivo USB anunciar capacidades de plataforma e información a nivel de dispositivo adicional. En dispositivos modernos, BOS puede incluir capacidades para:

• Extensión USB 2.0.
• Capacidad SuperSpeed.
• Platform capability WebUSB.
• Platform capability Microsoft OS 2.0.

Si el descriptor BOS está mal formado, Windows o las herramientas basadas en navegador pueden ignorar funciones o fallar la validación.

Descriptores Microsoft OS y WinUSB

Los descriptores Microsoft OS pueden ayudar a Windows a enlazar WinUSB de forma automática sin un INF personalizado en algunos casos. Los descriptores antiguos estilo WCID y los más nuevos Microsoft OS 2.0 aparecen en dispositivos reales.

Evidencia importante:

• Petición del string descriptor index 0xEE en flujos antiguos.
• Vendor code usado para pedir OS descriptors.
• Compatible ID como WINUSB.
• Extended properties.
• Asociación con número de interfaz.
• Si el dispositivo hace STALL correctamente ante peticiones de descriptor no soportadas.

Si el firmware devuelve datos mal formados, Windows puede no enlazar WinUSB aunque el dispositivo enumere.

WebUSB

WebUSB usa platform capabilities en BOS para anunciar una landing page y la capacidad accesible desde el navegador. Si la entrada BOS está mal, el navegador puede no exponer el dispositivo como debería.

Síntomas:

• El navegador no encuentra el dispositivo.
• El dispositivo aparece en el SO pero no en el selector WebUSB.
• La URL de la landing page falta o es incorrecta.
• El dispositivo funciona con la herramienta nativa pero no con la web.

La traza del bus puede enseñar si el host pidió BOS y qué devolvió el dispositivo.

Comportamiento válido de STALL

Para algunos mecanismos opcionales de descriptores Microsoft, un dispositivo que no soporta la feature debe hacer STALL en la petición. Un STALL no siempre es un bug. El bug es devolver datos de descriptor inválidos o reclamar soporte y fallar después la petición siguiente.

Por eso importa el contexto de la transferencia de control.

Complicaciones en dispositivos compuestos

Los descriptores Microsoft OS suelen apuntar a una interfaz concreta. Los dispositivos compuestos pueden fallar si el descriptor apunta a un número de interfaz equivocado o si Windows solo enlaza parte del dispositivo.

Inspecciona:

• Números de interfaz.
• Interface Association Descriptors.
• Secciones de Compatible ID.
• Function subset headers.
• Si WinUSB está pensado para una interfaz o para todas.

Checklist de depuración

Usa este flujo:

1. Captura desde el momento del plug-in.
2. Conserva los descriptores device, configuration, interface, endpoint y BOS.
3. Busca peticiones de descriptores Microsoft OS.
4. Decodifica el vendor code y la longitud del descriptor.
5. Comprueba los números de interfaz en los datos del descriptor.
6. Verifica los valores de Compatible ID como WINUSB.
7. Mira si las peticiones no soportadas hacen STALL correctamente.
8. Compara el comportamiento de enumeración en Windows y Linux.
9. Revisa el binding del Administrador de dispositivos tras enumerar.
10. Conserva los bytes de descriptor para depurar el firmware.

Diagnóstico final

Los fallos en BOS y Microsoft OS son problemas de contrato de descriptor. El dispositivo puede enumerar y aun así fallar WinUSB, WebUSB o el binding de driver específico de interfaz porque los descriptores opcionales están mal formados, faltan o están mapeados a la interfaz incorrecta.

Bus Scope ayuda enseñando la enumeración y las peticiones de descriptor directamente, para que los fallos de binding de driver se depuren desde la evidencia USB en lugar de solo a partir de síntomas del SO.