Débogage du descripteur de rapport HID : pourquoi le périphérique s'énumère mais que l'hôte lit les mauvaises données

HID est attrayant car de nombreux périphériques fonctionnent sans pilote personnalisé. Claviers, capteurs, boutons rotatifs, lecteurs de codes-barres, panneaux de contrôle et périphériques HID vendor tirent tous parti d'une pile hôte standard. Mais HID déplace aussi la complexité dans le descripteur de rapport. Un périphérique peut s'énumérer correctement et néanmoins envoyer des données que l'hôte interprète mal.

C'est l'un des pièges les plus courants du firmware USB : on confond la réussite de l'énumération avec la correction HID.

Le descripteur de rapport définit le contrat de données

Le descripteur de rapport HID indique à l'hôte comment interpréter les octets. Il définit les usages, tailles et nombres de rapports, plages logiques, plages physiques, collections et report IDs. Si le descripteur dit une chose et que le firmware en envoie une autre, l'hôte suit le descripteur.

Problèmes fréquents :

• le firmware envoie 8 octets mais le descripteur en décrit 7
• report ID manquant ou en trop
• valeurs signées déclarées comme non signées
• logical min/max ne couvrant pas la plage réelle
• usage page erronée
• bits de padding mal comptés
• plusieurs rapports partagent une disposition confuse
• input et output reports mélangés

Le symptôme peut apparaître côté application comme des valeurs fausses, des boutons manquants, des rapports ignorés ou des lectures intermittentes.

Capturer le descripteur et les rapports ensemble

Déboguer HID uniquement à partir du descripteur de rapport est incomplet. Déboguer uniquement à partir des octets de charge utile l'est aussi. Il faut les deux.

Une capture HID utile montre :

• le descripteur de périphérique
• les descripteurs de configuration et d'interface
• le descripteur HID
• la requête et la réponse du descripteur de rapport
• les rapports interrupt IN
• les rapports interrupt OUT s'il y en a
• les transferts de contrôle pour les feature reports
• les report IDs et longueurs de charge utile

L'ingénieur peut alors comparer la disposition déclarée avec les octets réels. Si le descripteur indique Report Count 3 et que la charge utile d'interruption porte quatre valeurs, la capture doit le rendre visible.

Le comportement de l'hôte peut être correct même s'il semble faux

Les développeurs firmware croient parfois que l'hôte perd des données. En réalité, l'hôte peut parser selon le descripteur qu'il a reçu. Si le descripteur déclare du padding ou un report ID différent, les données peuvent paraître décalées, tronquées ou ignorées.

C'est pourquoi un bon rapport de support doit inclure les octets bruts. L'interprétation décodée est utile, mais les octets bruts tranchent les litiges. La question devient :

• qu'a envoyé le firmware ?
• qu'a déclaré le firmware ?
• qu'a demandé l'hôte ?
• qu'a reçu l'hôte ?

C'est la bonne frontière pour le débogage HID.

Les périphériques HID composites demandent une attention particulière

Les périphériques composites peuvent exposer HID plus CDC, stockage ou interfaces vendor. La partie HID peut être correcte seule mais affectée par la numérotation d'interfaces, l'affectation de points de terminaison ou des erreurs de longueur totale de descripteurs.

Pour le débogage d'un HID composite, inspectez :

• l'interface association le cas échéant
• le numéro d'interface
• l'unicité des adresses de points de terminaison
• l'emplacement du descripteur HID
• la longueur du descripteur de rapport
• le routage des requêtes spécifiques à la classe

Si l'hôte demande le descripteur de rapport à la mauvaise interface ou reçoit une mauvaise longueur, le trafic de rapports qui suit devient trompeur.

Où Bus Scope s'inscrit

Bus Scope est conçu pour les équipes firmware et périphériques qui ont besoin d'un débogage USB guidé par les preuves. Pour les cas de descripteur de rapport HID, il doit permettre d'inspecter ensemble l'arborescence du descripteur, les octets bruts, le trafic sur les points de terminaison et la session .bscope enregistrée.

Le résultat concret doit être un rapport indiquant :

• le descripteur de rapport HID a été demandé et renvoyé
• la longueur de rapport déclarée par le descripteur
• la longueur réelle de la charge utile d'interruption
• le comportement du report ID
• la cohérence (ou le décalage) entre la déclaration et le trafic
• l'action suivante côté firmware : descripteur, empaquetage des rapports ou attentes du parseur hôte

C'est bien plus utile qu'un « périphérique HID qui ne marche pas ». Cela transforme un problème d'entrée vague en un décalage concret du contrat USB.