USB Host: integrate class API [2: helpers] by josuah · Pull Request #94590 · zephyrproject-rtos/zephyr

josuah · 2025-08-17T20:03:03Z

Main thread:

Planned USB host support work #95661

Downstream:

It contains all the commits of the previous PR, and in addition:

Wrapper for the class API
Split the struct usbh_class_data and usbh_class_api
Add utilities to register classes as a linked list (NXP)
Add a filter logic to match a device class to host class instances (NXP)

This also contains functions imported from #94085 by @AidenHu.

So far, this was only tested with this command to make sure it builds and run, but not in hardware yet:

west build -t run -b native_sim samples/subsys/usb/shell/ \
-DEXTRA_CONF_FILE=virtual.conf \
-DDTC_OVERLAY_FILE=virtual.overlay \
-DEXTRA_CONF_FILE=device_and_host_prj.conf

The PR #94085 got then completely rebased on top of this, available at josuah:enable_usb_host_video_class_api2, which is meant as a drop-in replacement for #94085.

It was also built (but not run) with this command:

west build -b rd_rw612_bga -S video-sw-generator samples/drivers/video/capture

All tests are done on top of main...josuah:zephyr:pr_usb_host_class_api2

josuah · 2026-01-24T01:38:45Z

more proofreading of the comments, which was much needed
remove unrelated change in header
rebase on latest main

Add API wrappers around the function pointers in struct usbh_class_api, while also documenting the USB host class internal API. Signed-off-by: Josuah Demangeon <josuah.demangeon@nordicsemi.no>

In addition to storing the interface pointers, also store the pointers for the interface association. Also add comments to the other fields of the structs to adapt to a new CI check. Signed-off-by: Josuah Demangeon <josuah.demangeon@nordicsemi.no>

carlescufi · 2026-02-02T12:34:00Z

@tmon-nordic @MarkWangChinese

MarkWangChinese

We do some basic tests with video, hub and ecm PRs, and find the follow two issues. Please check.

josuah · 2026-02-02T13:43:17Z

I am surprised CI did not catch that so will reproduce it on CI shortly and will add the modifications.
Thank you for the tests!

tmon-nordic · 2026-02-02T13:51:50Z

+		if ((uint8_t *)dhp + sizeof(struct usb_desc_header) > (uint8_t *)desc_end ||
+		    (uint8_t *)dhp + dhp->bLength > (uint8_t *)desc_end ||
+		    dhp->bLength <= sizeof(struct usb_desc_header)) {
+			LOG_ERR("Invalid descriptor size %d.", dhp->bLength);
+			return -EINVAL;
+		}


I think it is good to go as-is for now, but eventually there should be also other sanity checks because descriptors are essentially tainted (coming from untrusted source).

One pitfall I can see is if dhp + sizeof(struct some_class_specific_descriptor) > desc_end.

It seems like it is up to the classes to verify this given only the classes know sizeof(...)?

You are right that only classes know the class specific descriptors.

Endpoint descriptor is problematic because it can be 7 (USB specification itself) or 9 (USB Audio 1.0 class). I believe this is the only instance of such thing happening and there was some note that this won't happen again.

Add helpers to parse and validate USB descriptors. Signed-off-by: Johann Fischer <johann.fischer@nordicsemi.no> Signed-off-by: Josuah Demangeon <josuah.demangeon@nordicsemi.no>

Add basic functions to initialize and probe class drivers. Signed-off-by: Johann Fischer <johann.fischer@nordicsemi.no> Signed-off-by: Josuah Demangeon <josuah.demangeon@nordicsemi.no>

Add functions to probe/remove all classes as part of a new usbh_class.c and a matching usbh_class.h. These functions are called from the function usbh_init_device_intl() in usbh_core.c to initialize every class upon connection of a device. Every class driver provide filters to match the interfaces of the device. Co-authored-by: Aiden Hu <weiwei.hu@nxp.com> Signed-off-by: Josuah Demangeon <josuah.demangeon@nordicsemi.no>

Move the UVC header with all the definitions from the UVC standard to share it between USB host and device class implementation. Signed-off-by: Josuah Demangeon <josuah.demangeon@nordicsemi.no>

Make sure that there is at least enough room for the header before dereferencing the fields such as bLength. Signed-off-by: Josuah Demangeon <josuah.demangeon@nordicsemi.no>

Allocate a larger size to keep room for a nil descriptor at the end of the configuration descriptor. This is used to walk through the list of descriptors until this empty descriptor happens. Signed-off-by: Josuah Demangeon <josuah.demangeon@nordicsemi.no>

Add tests making sure the USB Host class APIs introduced build and run as expected. Use USB device samples common code for initialization. Co-authored-by: Johann Fischer <johann.fischer@nordicsemi.no> Signed-off-by: Johann Fischer <johann.fischer@nordicsemi.no> Signed-off-by: Josuah Demangeon <josuah.demangeon@nordicsemi.no>

The USB host will have to select the appropriate size for the configurtion descriptor, and the defaults will not be enough for some classes that encode a lot of information in the configuration descriptor. Add logging to debug this. Signed-off-by: Josuah Demangeon <josuah.demangeon@nordicsemi.no>

sonarqubecloud · 2026-02-03T01:57:12Z

Quality Gate passed

Issues
7 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
3.0% Duplication on New Code

See analysis details on SonarQube Cloud

fabiobaltieri · 2026-02-05T13:44:50Z

heya, spotted this in the main CI run

/__w/zephyr/zephyr/subsys/usb/host/usbh_desc.c:16:6: error: conflicting types for 'usbh_desc_is_valid'
   16 | bool usbh_desc_is_valid(const void *const desc,
      |      ^
/__w/zephyr/zephyr/subsys/usb/host/usbh_desc.h:92:12: note: previous declaration is here
   92 | const bool usbh_desc_is_valid(const void *const desc,
      |            ^

could you folks look into it?

fabiobaltieri · 2026-02-05T13:48:10Z

seems to be clang specific, can reproduce locally

$ export ZEPHYR_TOOLCHAIN_VARIANT=llvm
$ west build -p -b native_sim/native tests/subsys/usb/device_next
...
zephyrproject/zephyr/subsys/usb/host/usbh_desc.c:16:6: error: conflicting types for 'usbh_desc_is_valid'
   16 | bool usbh_desc_is_valid(const void *const desc,
      |      ^
/home/fabiobaltieri/zephyrproject/zephyr/subsys/usb/host/usbh_desc.h:92:12: note: previous declaration is here
   92 | const bool usbh_desc_is_valid(const void *const desc,
      |            ^

fabiobaltieri · 2026-02-05T13:50:32Z

nvm I'll open the fix myself #103579

josuah changed the title ~~USB Host: integrate class API [2]~~ USB Host: integrate class API [2: helpers] Aug 17, 2025

This was referenced Aug 17, 2025

USB Host: integrate class API [1: types] #94504

Merged

USB Host: integrate class API [3: UVC] #94591

Merged

usb: host: class: support for usb host video class #94085

Merged

josuah marked this pull request as ready for review August 17, 2025 21:05

zephyrbot added area: USB Universal Serial Bus area: Samples Samples labels Aug 17, 2025

zephyrbot requested review from jfischer-no, kartben, nashif and tmon-nordic August 17, 2025 21:06

zephyrbot assigned jfischer-no Aug 17, 2025

josuah mentioned this pull request Sep 4, 2025

drivers: uhc_dwc2: Initial support #94266

Closed

josuah force-pushed the pr_usb_host_class_api2 branch from e57477d to b3b4bc4 Compare September 4, 2025 13:46

zephyrbot requested a review from JarmouniA September 4, 2025 13:47

josuah force-pushed the pr_usb_host_class_api2 branch 3 times, most recently from e672ee8 to d04bbfb Compare September 5, 2025 12:01

tmon-nordic reviewed Sep 5, 2025

View reviewed changes

Comment thread subsys/usb/host/usbh_device.c

josuah force-pushed the pr_usb_host_class_api2 branch from d04bbfb to 7073da8 Compare September 5, 2025 13:27

jfischer-no reviewed Sep 5, 2025

View reviewed changes

Comment thread subsys/usb/host/usbh_desc.c Outdated

jfischer-no added the Experimental Experimental features not enabled by default label Sep 5, 2025

jfischer-no mentioned this pull request Sep 8, 2025

Planned USB host support work #95661

Open

18 tasks

josuah mentioned this pull request Sep 10, 2025

Planned USB host video implementation #93517

Open

16 tasks

josuah marked this pull request as draft September 11, 2025 00:05

josuah force-pushed the pr_usb_host_class_api2 branch 4 times, most recently from f095c02 to 3e111d0 Compare September 12, 2025 20:58

This was referenced Jan 24, 2026

uhc: dwc2: vendor quirks for nRF54LM20 #95723

Draft

subsys: usb: host: support for usb host cdc-ecm class #100289

Open

jfischer-no reviewed Jan 27, 2026

View reviewed changes

Comment thread subsys/usb/host/usbh_desc.c Outdated

Comment thread tests/subsys/usb/host/src/class.c Outdated

Comment thread tests/subsys/usb/host/src/main.c Outdated

Comment thread tests/subsys/usb/host/src/main.c

Josuah Demangeon added 2 commits January 28, 2026 03:09

usb: host: introduce wrappers to access the class function pointers

36ffc90

Add API wrappers around the function pointers in struct usbh_class_api, while also documenting the USB host class internal API. Signed-off-by: Josuah Demangeon <josuah.demangeon@nordicsemi.no>

jfischer-no previously approved these changes Jan 29, 2026

View reviewed changes

josuah mentioned this pull request Jan 30, 2026

usb: host: support multiple devices #103238

Closed

MarkWangChinese reviewed Feb 2, 2026

View reviewed changes

Comment thread subsys/usb/host/usbh_class.c Outdated

Comment thread subsys/usb/host/usbh_desc.c Outdated

tmon-nordic reviewed Feb 2, 2026

View reviewed changes

jfischer-no reviewed Feb 2, 2026

View reviewed changes

Comment thread subsys/usb/host/usbh_desc.c Outdated

jfischer-no and others added 8 commits February 3, 2026 02:22

usb: host: add helpers to parse USB descriptors

c0d73d7

Add helpers to parse and validate USB descriptors. Signed-off-by: Johann Fischer <johann.fischer@nordicsemi.no> Signed-off-by: Josuah Demangeon <josuah.demangeon@nordicsemi.no>

usb: host: add functions to initialize and probe class drivers

2a0b384

Add basic functions to initialize and probe class drivers. Signed-off-by: Johann Fischer <johann.fischer@nordicsemi.no> Signed-off-by: Josuah Demangeon <josuah.demangeon@nordicsemi.no>

usb: uvc: move the header definition to include/

189ec6a

Move the UVC header with all the definitions from the UVC standard to share it between USB host and device class implementation. Signed-off-by: Josuah Demangeon <josuah.demangeon@nordicsemi.no>

usb: host: improve safety of configuration descriptor parsing

252748e

Make sure that there is at least enough room for the header before dereferencing the fields such as bLength. Signed-off-by: Josuah Demangeon <josuah.demangeon@nordicsemi.no>

jfischer-no approved these changes Feb 3, 2026

View reviewed changes

MarkWangChinese approved these changes Feb 4, 2026

View reviewed changes

tmon-nordic approved these changes Feb 5, 2026

View reviewed changes

josuah commented Feb 5, 2026

View reviewed changes

Comment thread subsys/usb/device_next/class/usbd_uvc.c

MarkWangChinese mentioned this pull request Apr 27, 2026

MAINTAINERS: Add MarkWangChinese as collaborator for USB #107904

Merged

Conversation

josuah commented Aug 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

josuah commented Jan 24, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

carlescufi commented Feb 2, 2026

Uh oh!

MarkWangChinese left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

josuah commented Feb 2, 2026

Uh oh!

Uh oh!

tmon-nordic Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

josuah Feb 2, 2026

Choose a reason for hiding this comment

Uh oh!

tmon-nordic Feb 5, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sonarqubecloud Bot commented Feb 3, 2026

Quality Gate passed

Uh oh!

fabiobaltieri commented Feb 5, 2026

Uh oh!

fabiobaltieri commented Feb 5, 2026

Uh oh!

fabiobaltieri commented Feb 5, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

10 participants

josuah commented Aug 17, 2025 •

edited

Loading