usb: gadget: configfs: add MS OS 2.0 descriptors support - #369
Open
evgeny-boger wants to merge 2 commits into
Open
usb: gadget: configfs: add MS OS 2.0 descriptors support#369evgeny-boger wants to merge 2 commits into
evgeny-boger wants to merge 2 commits into
Conversation
Windows 8.1 and later read the MS OS 2.0 descriptor set announced through a BOS platform capability descriptor and ignore the older MS OS 1.0 descriptors the gadget stack already supports. Without MS OS 2.0 there is no way to tell Windows the DeviceInterfaceGUID of a function of a composite gadget: the MS OS 1.0 extended properties are not picked up for composite functions, and REG_MULTI_SZ properties cannot be emitted at all (composite.c rejects USB_EXT_PROP_UNICODE_MULTI). Without a registered interface GUID Windows creates no device interface for the function, so applications cannot obtain a device path for it and cannot talk to the device at all -- for instance Chromium fails to read the WebUSB landing page of a composite gadget. Add an "msos20" configfs group, modelled after the existing "webusb" one: echo 0x02 > msos20/bVendorCode cat descriptor_set.bin > msos20/descriptor_set echo 1 > msos20/use The descriptor set itself is opaque to the kernel and is supplied by userspace, which keeps the interface small and lets gadgets describe any number of functions and properties. Only the set header is validated on write, so that a truncated or mismatched blob is rejected there rather than confusing the host later. When enabled, the platform capability descriptor is added to the BOS descriptor and the device reports bcdUSB 0x0210, as the specification requires. Tested on a Wiren Board 8 (musb high-speed UDC) with a composite RNDIS + mass storage + FunctionFS gadget and Chromium 152 on Windows 11: the WinUSB function gets its DeviceInterfaceGUIDs registered, the RNDIS function keeps its compatible ID and the network interface keeps working, and the WebUSB landing page is read by the browser, which it is not without this change. Assisted-by: LLM Signed-off-by: Evgeny Boger <boger@wirenboard.com>
evgeny-boger
marked this pull request as ready for review
September 3, 2026 23:25
This was referenced Sep 5, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Что происходит; кому и зачем нужно:
Windows 8.1+ читает MS OS 2.0 descriptors из BOS и при этом игнорирует MS OS 1.0, которые gadget-стек уже умеет. Из-за этого функции композитного гаджета невозможно сообщить Windows её
DeviceInterfaceGUID: MS OS 1.0 extended properties Windows у функции композитного устройства не забирает, а свойства типаREG_MULTI_SZядро не отдаёт вовсе (composite.cотвергаетUSB_EXT_PROP_UNICODE_MULTI). Без зарегистрированного GUID Windows не создаёт device interface, приложение не может получить device path и вообще не может обратиться к устройству — например, Chromium не читает WebUSB landing page композитного гаджета.MS OS 2.0 в linux-gadget отсутствует и в 6.8, и в mainline (
grepпоD8DD60DF/MS_OS_20— пусто), готовых патчей найти не удалось.Добавляется configfs-группа
msos20, по образцу существующейwebusb:Сам набор дескрипторов для ядра непрозрачен и формируется в userspace — так интерфейс остаётся маленьким, а гаджет может описать любое число функций и свойств без новых патчей в ядре. При записи проверяется только заголовок набора, чтобы обрезанный или несогласованный блоб отвергался сразу, а не путал хост позже. При включении capability добавляется в BOS, и устройство отдаёт
bcdUSB 0x0210, как требует спецификация.Что поменялось для пользователей:
Само по себе ничего: без записи в
msos20/поведение прежнее. Когда wb-utils начнёт включать это для Debug Network, на Windows появится уведомление Chrome со ссылкой на веб-интерфейс контроллера.Важно: набор дескрипторов обязан описывать все функции, которым нужен compatible ID. Windows, увидев MS OS 2.0, перестаёт читать MS OS 1.0, поэтому если не описать там RNDIS — он потеряет свой compat ID и сеть на хосте отвалится. В wb-utils это учтено и проверено.
Как проверял/а:
scripts/checkpatch.pl(mainline): 0 errors. Остаются два warning: про длину строки в changelog коммита и «does MAINTAINERS need updating?» на новый заголовок.libcomposite.koдля 6.8.0-wb161 и установлен на WB 8.5 (wirenboard-ALFLOJF3, musb HS), гаджет RNDIS + mass storage + FunctionFS:descriptor_setи читаются обратно; capability видна в BOS (57 байт, три капабилити),bcdUSB2.10;DeviceInterfaceGUID/DeviceInterfaceGUIDs, аchrome://usb-internalsпоказываетWebUSB Landing Page: https://10-200-200-1.<sn>.ip.wirenboard.com/— без этого патча поле пустое;Ethernet 2 / Up), диск на месте, все четыре функции в состоянии OK.descriptor_setбольше 1024 байт (ограничено константой).Патч имеет смысл и для mainline — фичи там нет.
AI-assisted:
Патч и changelog подготовлены с помощью LLM-ассистента (тег
Assisted-by: LLMпо Documentation/process/coding-assistants.rst).Signed-off-byпроставлен по прямому указанию отправителя.