fix[usb]: correct bInterfaceProtocol selection in HID descriptor by sexenteen · Pull Request #11873 · RT-Thread/rt-thread

sexenteen · 2026-10-16T16:03:15Z

拉取/合并请求描述：(PR description)

[

为什么提交这份PR (why to submit this PR)

In components/legacy/usb/usbdevice/class/hid.c the HID interface protocol is selected at
compile time with:

#if !defined(RT_USB_DEVICE_HID_KEYBOARD)||!defined(RT_USB_DEVICE_HID_MOUSE)||!defined(RT_USB_DEVICE_HID_MEDIA)

A || B || C is already true when any one of the features is not defined, so the condition
holds in almost every configuration and the field is always USB_HID_PROTOCOL_NONE (0):

configuration	before	expected
keyboard only	0	1
mouse only	0	2
keyboard + media	0	1
keyboard + mouse	0	0

The #elif !defined(RT_USB_DEVICE_HID_MOUSE) branch is unreachable (reaching it already
implies MOUSE is defined), while the interface is declared with bInterfaceSubClass = BOOT
— a BOOT subclass reporting protocol NONE is self-contradictory. Hosts that rely on the boot
protocol (BIOS/UEFI setup, KVMs) cannot treat this interface as a boot keyboard/mouse.

你的解决方案是什么 (what is your solution)

Judge keyboard and mouse separately, and stop letting the media-key feature influence this
field (media is not a boot-protocol device):

#if defined(...KEYBOARD) && !defined(...MOUSE)   -> USB_HID_PROTOCOL_KEYBOARD
#elif !defined(...KEYBOARD) && defined(...MOUSE) -> USB_HID_PROTOCOL_MOUSE
#else                                            -> USB_HID_PROTOCOL_NONE

When keyboard and mouse are enabled together, a single interface cannot declare itself as
both, so the protocol stays NONE (the combination is described by the IAD). The same block
appears twice (IAD bFunctionProtocol and interface bInterfaceProtocol); both are fixed
identically.

请提供验证的bsp和config (provide the config and bsp)

BSP: bsp/qemu-vexpress-a9
.config: default configuration (unchanged)
action: https://github.com/sexenteen/rt-thread/actions/runs/41662248322

Verification, stated honestly:

scons -j4 on bsp/qemu-vexpress-a9 passes, but this BSP has no USB device controller, so
class/hid.c is not compiled there (if GetDepend('RT_USB_DEVICE_HID') in
components/legacy/usb/usbdevice/SConscript). The build only shows that the change does not
break the existing build.
The descriptor value itself was verified with the preprocessor for all four feature
combinations (table above). A full USB enumeration test would need a board with a USB device
controller (e.g. an STM32 BSP); I could not run that here. Please let me know if you want
that covered, or if a different verification is preferred.

About the "Check File Format and License" (clang-format) check: it may report violations for
this file, but the file already fails the same check without my change. Reproduced locally with
tools/ci/clang_format_check.py and the same clang-format package used by CI:

checked content	reported violations
the unmodified file, same line ranges	40
my version, same line ranges	65

The cause is that rt_align(4) has no trailing semicolon, so clang-format treats the following
declaration as a continuation and wants to re-indent the whole _hid_comm_desc initializer
(the --lines range is expanded to that construct). I did not reformat the file, because that
would add a few hundred unrelated line changes. Happy to follow whatever you prefer here.

Also: this file lives under components/legacy/. If fixes to the legacy USB device stack are no
longer accepted (and the same issue should instead be addressed in the CherryUSB stack), please
tell me and I will re-target the change.

Note on the diff size: components/legacy/usb/usbdevice/class/hid.c is not clang-format clean on
master (605 violations when checked with the pinned clang-format 22.1.8 from
tools/ci/requirements-format.txt). Because this change lives inside the HID report descriptor
initializer, the "Scan code format and license" job checks the whole enclosing initializer, so the
descriptor region is formatted with the pinned clang-format in this PR. That is where the extra
lines come from - there is no behaviour change.
]

当前拉取/合并请求的状态 Intent for your PR

必须选择一项 Choose one (Mandatory):

本拉取/合并请求是一个草稿版本 This PR is for a code-review and is intended to get feedback
本拉取/合并请求是一个成熟版本 This PR is mature, and ready to be integrated into the repo

代码质量 Code Quality：

我在这个拉取/合并请求中已经考虑了 As part of this pull request, I've considered the following:

已经仔细查看过代码改动的对比 Already check the difference between PR and old code
代码风格正确，包括缩进空格，命名及其他风格 Style guide is adhered to, including spacing, naming and other styles
没有垃圾代码，代码尽量精简，不包含#if 0代码，不包含已经被注释了的代码 All redundant code is removed and cleaned up
所有变更均有原因及合理的，并且不会影响到其他软件组件代码或BSP All modifications are justified and not affect other components or BSP
对难懂代码均提供对应的注释 I've commented appropriately where code is tricky
代码是高质量的 Code in this PR is of high quality
已经使用clang-format 源码格式化工具确保格式符合RT-Thread代码规范 This PR has been formatted with clang-format and complies with RT-Thread code specification
如果是新增bsp, 已经添加ci检查到.github/ALL_BSP_COMPILE.json 详细请参考链接BSP自查

github-actions · 2026-10-16T16:03:24Z

👋 感谢您对 RT-Thread 的贡献！Thank you for your contribution to RT-Thread!

为确保代码符合 RT-Thread 的编码规范，请在你的仓库中执行以下步骤运行代码格式化工作流（如果格式化CI运行失败）。
To ensure your code complies with RT-Thread's coding style, please run the code formatting workflow by following the steps below (If the formatting of CI fails to run).

🛠 操作步骤 | Steps

前往 Actions 页面 | Go to the Actions page
点击进入工作流 → | Click to open workflow →
点击 Run workflow | Click Run workflow

Use workflow from 保持默认分支（通常为 master）
Keep the default branch (usually master) in Use workflow from
在 branch 输入框填写 PR 分支 fix/issue-7748-hid-interface-protocol
Enter PR branch fix/issue-7748-hid-interface-protocol in the branch field
设置需排除的文件/目录（目录请以"/"结尾）
Set files/directories to exclude (directories should end with "/")

等待工作流完成 | Wait for the workflow to complete
格式化后的代码将作为独立提交推送至你的分支。
The formatting changes will be pushed to your branch as a separate commit.

完成后，提交将自动更新至 fix/issue-7748-hid-interface-protocol 分支，关联的 Pull Request 也会同步更新。
Once completed, commits will be pushed to the fix/issue-7748-hid-interface-protocol branch automatically, and the related Pull Request will be updated.

如有问题欢迎联系我们，再次感谢您的贡献！💐
If you have any questions, feel free to reach out. Thanks again for your contribution!

CLAassistant · 2026-10-16T16:03:25Z

All committers have signed the CLA.

github-actions · 2026-10-16T16:03:29Z

📌 Code Review Assignment

🏷️ Tag: components

Reviewers: @Maihuanyi

Changed Files (Click to expand)

components/legacy/usb/usbdevice/class/hid.c

📊 Current Review Status (Last Updated: 2026-11-03 23:16 CST)

⌛ @Maihuanyi Pending Review

📝 Review Instructions

维护者可以通过单击此处来刷新审查状态: 🔄 刷新状态
Maintainers can refresh the review status by clicking here: 🔄 Refresh Status
确认审核通过后评论 LGTM/lgtm
Comment LGTM/lgtm after confirming approval
PR合并前需至少一位维护者确认
PR must be confirmed by at least one maintainer before merging

ℹ️ 刷新CI状态操作需要具备仓库写入权限。
ℹ️ Refresh CI status operation requires repository Write permission.

sexenteen · 2026-11-01T09:24:40Z

Hi,

A gentle ping on this PR — it has been open for two weeks without activity.

Fixes usb device bInterfaceProtocol 字段配置错误 #7748: the compile-time condition used || instead of &&, so bInterfaceProtocol was
always reported as NONE when only the keyboard or only the mouse was enabled. The PR includes
the resulting descriptor values for the four feature combinations.
The CI workflows for this PR are currently in action_required state, i.e. they need a
maintainer to approve running them, so the required checks have not run yet.

Two things I would like to close out:

This file lives under components/legacy/. If fixes to the legacy USB device stack are no
longer accepted, I can re-target the change to the CherryUSB stack instead — please let me
know which you prefer.
Is the verification sufficient (a preprocessor value table for the four feature combinations,
plus a passing build), or would you also want a board-level enumeration test?

Happy to adjust anything. Thanks for your time.

(For context: I have also claimed #7748, so the in progress label on the issue is from me.)

github-actions · 2026-11-03T04:27:05Z

MemBrowse Memory Report · Explore what changed →

No memory changes detected for:

_{Catch memory regressions in CI with MemBrowse. Free for open source.}

github-actions Bot added the Component label Oct 16, 2026

sexenteen force-pushed the fix/issue-7748-hid-interface-protocol branch from dbe8b2a to 7f3c0e0 Compare November 3, 2026 03:49

fix[usb]: correct bInterfaceProtocol selection in HID descriptor

ccf5abd

sexenteen force-pushed the fix/issue-7748-hid-interface-protocol branch from 7f3c0e0 to ccf5abd Compare November 3, 2026 15:16

Navigation Menu

Repository navigation

fix[usb]: correct bInterfaceProtocol selection in HID descriptor - #11873

fix[usb]: correct bInterfaceProtocol selection in HID descriptor#11873
sexenteen wants to merge 1 commit into
RT-Thread:masterfrom
sexenteen:fix/issue-7748-hid-interface-protocol

sexenteen commented Oct 16, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Oct 16, 2026

Uh oh!

CLAassistant commented Oct 16, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Oct 16, 2026 •

edited

Loading

Uh oh!

sexenteen commented Nov 1, 2026

Uh oh!

github-actions Bot commented Nov 3, 2026 •

edited

Loading

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

sexenteen commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

拉取/合并请求描述：(PR description)

为什么提交这份PR (why to submit this PR)

你的解决方案是什么 (what is your solution)

请提供验证的bsp和config (provide the config and bsp)

当前拉取/合并请求的状态 Intent for your PR

代码质量 Code Quality：

Uh oh!

github-actions Bot commented Oct 16, 2026

🛠 操作步骤 | Steps

Uh oh!

CLAassistant commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Oct 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

📌 Code Review Assignment

🏷️ Tag: components

📊 Current Review Status (Last Updated: 2026-11-03 23:16 CST)

📝 Review Instructions

Uh oh!

sexenteen commented Nov 1, 2026

Uh oh!

github-actions Bot commented Nov 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

MemBrowse Memory Report · Explore what changed →

Uh oh!

This branch has not been deployed

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

sexenteen commented Oct 16, 2026 •

edited

Loading

CLAassistant commented Oct 16, 2026 •

edited

Loading

github-actions Bot commented Oct 16, 2026 •

edited

Loading

github-actions Bot commented Nov 3, 2026 •

edited

Loading