Débogage des feature reports USB HID : GET_REPORT, SET_REPORT, commandes vendor et paramètres manquants

Les périphériques HID ne sont pas que des claviers et souris. Ils incluent des clés de sécurité, capteurs, panneaux de contrôle, outils vendor, périphériques industriels, manettes de jeu, onduleurs et interfaces de configuration personnalisées. Beaucoup de ces périphériques utilisent des HID Feature Reports pour la configuration et le statut. Quand les Feature Reports échouent, les utilisateurs cherchent « HID Feature Report not working », « GET_REPORT failed », « SET_REPORT failed », « HID report ID mismatch » ou « USB HID vendor command timeout » car l'entrée normale peut marcher alors que la configuration non.

Bus Scope est utile car les Feature Reports passent souvent par l'endpoint zéro comme transferts de contrôle. Le setup packet réel, le type de rapport, le report ID, la longueur et le statut de réponse comptent.

Ce que sont les Feature Reports

HID a plusieurs types de rapports :

• Input reports
• Output reports
• Feature reports

Les input reports arrivent souvent sur des endpoints interrupt IN. Les feature reports sont généralement demandés avec des transferts de contrôle en utilisant GET_REPORT ou SET_REPORT.

Si les boutons d'un périphérique marchent mais que son panneau de paramètres échoue, la gestion des Feature Reports peut être en cause.

Décalages de report ID et de longueur

Beaucoup de périphériques HID utilisent des report IDs. Si l'hôte inclut le report ID 3 et que le firmware attend le report ID 0, la requête peut échouer ou renvoyer de mauvaises données.

Bugs fréquents :

• Le firmware omet l'octet de report ID.
• L'hôte envoie une mauvaise longueur de rapport.
• Le descripteur déclare une longueur, le firmware en renvoie une autre.
• Feature report existe dans le firmware mais pas dans le descripteur.
• Le descripteur déclare un rapport que le firmware n'implémente jamais.

Le HID report descriptor et le transfert de contrôle doivent être comparés.

Preuves GET_REPORT et SET_REPORT

Cherchez :

• Type de requête du setup packet.
• HID GET_REPORT ou SET_REPORT.
• Type de rapport Feature.
• Report ID.
• wLength.
• Octets de la data stage.
• STALL ou timeout.

Si le périphérique stall un Feature Report que son descripteur annonce, la cohérence firmware ou descripteur est suspecte.

Configuration vendor via HID

Beaucoup de produits utilisent HID parce que cela évite des pilotes noyau personnalisés. Les paramètres vendor peuvent être implémentés comme Feature Reports.

Exemples :

• Changer le taux d'échantillonnage.
• Lire la version firmware.
• Définir le mode LED.
• Configurer la plage du capteur.
• Activer le bootloader.
• Lire les données de calibration.

Si ces commandes échouent, le périphérique peut quand même apparaître comme un périphérique HID valide.

Checklist de débogage

Suivez ce processus :

1. Capturez l'énumération et le descripteur HID.
2. Enregistrez le HID report descriptor.
3. Identifiez les définitions de Feature Report.
4. Capturez le GET_REPORT ou SET_REPORT défaillant.
5. Vérifiez le report ID.
6. Vérifiez la longueur demandée.
7. Comparez la longueur du descripteur avec la longueur du transfert.
8. Cherchez STALL, timeout ou réponse courte.
9. Comparez les input reports qui marchent avec les feature reports défaillants.
10. Conservez ensemble descripteur et transfert de contrôle.

Diagnostic final

Les échecs de HID Feature Report sont généralement des problèmes de descripteur, report ID, longueur, état firmware ou de gestion de transfert de contrôle. L'entrée peut marcher alors que la configuration échoue.

Bus Scope aide à exposer le contrat HID et le transfert de contrôle exact qui a échoué, rendant les bugs de Feature Report diagnostiquables au lieu de mystérieuses erreurs d'outils vendor.