USB Host: integrate class API [2: helpers] #94590

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

subsys/usb/host/usbh_device.c

jfischer-no · 2025-09-05T14:23:45Z

include/zephyr/usb/usbh.h

+	/** Pointer to host support class API */
+	struct usbh_class_api *api;
+	/** Pointer to private data */
+	void *priv;


I dug out the branch where I started working on the CDC ACM driver, cleaned it up a bit, and pushed it to my Zephyr repository, https://github.com/jfischer-no/zephyr/commits/wip-usbh-class-driver/, please take a look and reuse what makes sense.

I think I still have these checks missing, left for the class to implement them:

if_desc = (void *)udev->ifaces[i].dhp; if (if_desc->bInterfaceClass == code->dclass && if_desc->bInterfaceSubClass == code->sub && if_desc->bInterfaceProtocol == code->proto) {

But that is something that I can add. Is it possible for a standard device to only expect interface or interface-association to be used for class selection?

I really need to check the standards again.

I think I imported everything into the current PR (except the CDC ACM implementation itself).

include/zephyr/usb/usbh.h

subsys/usb/host/usbh_class.c

include/zephyr/usb/class/usb_uvc.h

subsys/usb/host/usbh_class.c

include/zephyr/usb/usbh.h

jfischer-no · 2025-09-05T15:23:34Z

subsys/usb/host/usbh_desc.c

+struct usb_desc_header *usbh_desc_get_by_type(const uint8_t *const start_addr,
+					      const uint8_t *const end_addr,
+					      uint32_t type_mask)


We need some simple function driver code to test it, IMO jfischer-no@28f064b is too ugly for that, maybe you or me can sand down it to loopback.c skeleton (to be counterpart of device_next/class/loopback.c), just checking for the testusb bulk interface and testusb sample VID/PID.

This should help downstream PRs a lot.

Should that be using UVB connecting the device and host class together? I tried it on a WIP branch and can try to collect bits from various branches and integrate unit tests into API2 that way.

Is there another way I should test the host functionality than UVB?

main...josuah:zephyr:pr_sample_uvc_uvb#diff-6b7a858e2f07001df9a5d4de454923a5cf06ed38afb7fd4040bb84b45089cc34

Or this can also be some manually crafted descriptor, it seems a different concern than testing everything end-to-end, and easier to reproduce bugs. I will try this thank you.

josuah · 2025-11-27T18:44:17Z

Force-push:

Rebase on latest main

jfischer-no · 2025-12-08T16:17:10Z

subsys/usb/host/usbh_data.ld

@@ -1,3 +1,9 @@
+/*
+ * Copyright 2025 Nordic Semiconductor ASA


I think we should use just
* SPDX-FileCopyrightText: Copyright The Zephyr Project Contributors
for this type of files.

Understood. Done.

jfischer-no · 2025-12-08T16:19:15Z

subsys/usb/host/usbh_class_api.h

@@ -0,0 +1,147 @@
+/*
+ * Copyright (c) 2025 Nordic Semiconductor ASA


SPDX-FileCopyrightText: Copyright Nordic Semiconductor ASA

Applied, thank you.

I applied to all files as a stand-alone commit. Not sure if that's what to be done...

jfischer-no · 2025-12-08T16:32:10Z

include/zephyr/usb/usbh.h

+	struct usbh_class_filter *filters;
+	/** Number of filters in the array */
+	size_t num_filters;


Should filters array be NULL pointer terminated instead of using num_filters?

I think this was the original version but was modified based on feedback of an earlier review.
I do not remember where exactly.

jfischer-no · 2025-12-08T16:40:28Z

subsys/usb/host/usbh_class.c

+	k_mutex_unlock(&udev->mutex);
+}
+
+bool usbh_class_is_matching(struct usbh_class_filter *const filters, size_t num_filters,


bool usbh_class_is_matching(struct usbh_class_filter *const filters, const size_t num_filters,

Removed num_filters in favor of a NULL terminator.

jfischer-no · 2025-12-08T16:43:36Z

subsys/usb/host/usbh_class.c

+ * multiple times consequently has no effect.
+ */
+static void usbh_class_probe_function(struct usb_device *const udev,
+				      struct usbh_class_filter *const info, uint8_t iface)


const uint8_t iface)

I forgot this one... done

jfischer-no · 2025-12-08T17:02:44Z

subsys/usb/host/usbh_desc.c

+	return usbh_desc_is_valid(desc, desc_end, sizeof(struct usb_if_descriptor)) &&
+	       ((struct usb_desc_header *)desc)->bDescriptorType == USB_DESC_INTERFACE;


I suggest writing it in more detail.

bool usbh_desc_is_valid_interface(const void *const desc, const void *const desc_end) { struct usb_desc_header *const head = desc; if (head->bDescriptorType != USB_DESC_INTERFACE) return false; } return usbh_desc_is_valid(desc, desc_end, sizeof(struct usb_if_descriptor)); }

btw, why not pass type parameter to usbh_desc_is_valid()? Like

const bool usbh_desc_is_valid(const void *const desc_ptr, const void *const desc_end, size_t expected_size, const uint8_t type)

I have added the type to usbh_desc_is_valid() and kept the usbh_desc_is_valid_interface() to reduce boilerplate as these functions are frequently used across the source and classes.

jfischer-no · 2025-12-08T17:05:54Z

subsys/usb/host/usbh_class.c

+	}
+
+	/* Try to find a rule that matches completely */
+	for (int i = 0; i < num_filters; i++) {


for (size_t i = 0; i < num_filters; i++) { !
size_t can be very annoying.

tmon-nordic · 2025-12-09T11:23:13Z

subsys/usb/host/usbh_class_api.h

+/**
+ * @brief Device initialization handler
+ *
+ * Called when a device is connected to the bus for every device.


What does "for every device" mean here? Isn't it supposed to be called for every interface?

That is definitely confusing... This might probably need to be "for every USB function" instead. Updated!

tmon-nordic · 2025-12-09T11:24:16Z

subsys/usb/host/usbh_class_api.h

+		return api->suspended(c_data);
+	}
+
+	return -ENOTSUP;


Is suspended really mandatory?

This would permit to propagate the action to the subsystem associated.
It does not seem used by downstream PRs and can be introduced in a dedicated PR if needed.

Removed. Thanks.

I didn't mean to remove the suspend callback, but rather to allow it to be optional, i.e. to not return -ENOTSUP, but just 0 if there is no callback.

I remember now, it was rwup which needed to go away! Restored suspend()/resume() and applied return 0, thanks

tmon-nordic · 2025-12-09T11:28:47Z

subsys/usb/host/usbh_class.c

+void usbh_class_init_all(struct usbh_context *const uhs_ctx)
+{
+	int ret;
+


Is going without mutex safe here?

I assumed it would just because it is called in usbh_init() which calls usbh_host_lock()/usbh_host_unlock().

But this goes through several internal APIs that are expoed in .h, so from API point of view, maybe it is better to lock again here?

Mutexes support recursion anyway so it should work...

tmon-nordic · 2025-12-09T11:34:27Z

subsys/usb/host/usbh_class.c

+			    struct usbh_class_filter *const info)
+{
+	/* Make empty filter set match everything (use class_api->probe() only) */
+	if (filters[0].flags == 0) {


USBH_DEFINE_CLASS documentation mentions that NULL matches everything, not a filter with flags set to 0. Therefore it should be more like if (filters == NULL).

That is a better way to make a distinction... It also makes it possible to write classes that match nothing, which is safer and easier to debug if i.e. every rule is commented out by #ifdef CONFIG_....

tmon-nordic · 2025-12-09T11:35:14Z

include/zephyr/usb/usbh.h

+ * @param[in] class_name Class name
+ * @param[in] class_api  Pointer to struct usbh_class_api
+ * @param[in] class_priv Class private data
+ * @param[in] filt Array of @ref usbh_class_filter to match this class or NULL to match everything


It is not specified here that the array is expected to end with entry that has flags set to 0.

Thank you for the consistency check.

tmon-nordic · 2025-12-09T11:39:18Z

subsys/usb/host/usbh_class.h

+/** Match a device's vendor ID */
+#define USBH_CLASS_MATCH_VID BIT(1)
+
+/** Match a device's product ID */
+#define USBH_CLASS_MATCH_PID BIT(2)
+
+/** Match a class code */
+#define USBH_CLASS_MATCH_CLASS BIT(3)
+
+/** Match a subclass code */
+#define USBH_CLASS_MATCH_SUB BIT(4)
+
+/** Match a protocol code */
+#define USBH_CLASS_MATCH_PROTO BIT(5)


The individual criteria seem a bit odd. Matching on code triple is fine, but on individual fields seems questionable.

Matching on VID alone is very questionable, while matching on PID alone sounds outright wrong.

Good point, reduced to only USBH_CLASS_MATCH_VID_PID and USBH_CLASS_MATCH_CODE_TRIPLET.

tmon-nordic · 2025-12-09T11:44:22Z

subsys/usb/host/usbh_desc.h

+ *
+ * @return A pointer to the beginning of the descriptor
+ */
+const void *usbh_desc_get_cfg_beg(const struct usb_device *const udev);


Why not usbh_desc_get_cfg?

Just for symmetry with usbh_desc_get_cfg_end and to remind users they need to call both in combination for safety purpose. However it is enforced by all APIs...

Removed the _beg suffix.

tmon-nordic · 2025-12-09T11:44:57Z

subsys/usb/host/usbh_desc.h

+ *
+ * @param[in] udev The device holding the configuration descriptor
+ *
+ * @return A pointer to the beginning of the descriptor


Copy&paste error. THis function is supposed to return the end.

tmon-nordic · 2025-12-09T11:45:54Z

subsys/usb/host/usbh_desc.h

+bool usbh_desc_is_valid_interface(const void *const desc, const void *const desc_end);
+
+/**
+ * @brief Checks that the pointed descriptor is a valid interface descriptor.


Copy&pate error.

tmon-nordic · 2025-12-09T11:46:53Z

subsys/usb/host/usbh_desc.h

+ * If @p desc_beg is another type of descriptors, it will seek to a matching descriptor type and
+ * return it, without skipping to the next one after it.
+ *
+ * @param[in] desc_beg Pointer to the beginning of the descriptor array; to search. May be NULL.


A bit strange name. I would go with just desc.

Applying here like for usbh_desc_get_cfg.

Add a "struct usbh_status" that contains a bitmask of flags to keep track of the global state of the host context, like done for the device_next implementation. Signed-off-by: Josuah Demangeon <[email protected]>

Add missing copyright notice for the linker script to help with check_compliance.py. Signed-off-by: Josuah Demangeon <[email protected]>

josuah · 2025-12-10T01:38:59Z

Force-push:

Rebased on top of latest main
Apply review suggestions
Apply SonarQube suggestions
Extra proofreading of the documentation

Add a "struct usbh_class_api" for the host implementation, and move all the function poitners to it. Add more fields to "struct usbh_class_data". Signed-off-by: Josuah Demangeon <[email protected]>

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 <[email protected]>

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 <[email protected]> Signed-off-by: Josuah Demangeon <[email protected]>

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 <[email protected]>

Add tests making sure the USB Host class APIs introduced build and run as expected. Signed-off-by: Josuah Demangeon <[email protected]>

Switch to the SPDX-FileCopyrightText prefix for all sources in USB Host class. Signed-off-by: Josuah Demangeon <[email protected]>

sonarqubecloud · 2025-12-10T17:42:53Z

Quality Gate passed

Issues
6 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud

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

Open

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

Draft

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 [WIP] #94266

Draft

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

subsys/usb/host/usbh_device.c Outdated Show resolved Hide resolved

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

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

15 tasks

josuah mentioned this pull request Sep 10, 2025

Planned USB host video implementation #93517

Open

15 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

josuah force-pushed the pr_usb_host_class_api2 branch from d9c0620 to e21942e Compare November 27, 2025 18:44

jfischer-no reviewed Dec 8, 2025

View reviewed changes

josuah force-pushed the pr_usb_host_class_api2 branch 4 times, most recently from 15feead to e43dd89 Compare December 8, 2025 21:58

josuah mentioned this pull request Dec 8, 2025

USB class: support multiple USB host controllers #100703

Draft

josuah force-pushed the pr_usb_host_class_api2 branch from e43dd89 to bd931ba Compare December 8, 2025 23:12

tmon-nordic reviewed Dec 9, 2025

View reviewed changes

Josuah Demangeon added 2 commits December 9, 2025 14:35

usb: host: add host status to the host context

16b61db

Add a "struct usbh_status" that contains a bitmask of flags to keep track of the global state of the host context, like done for the device_next implementation. Signed-off-by: Josuah Demangeon <[email protected]>

usb: host: add copyright notice to linker script

010638b

Add missing copyright notice for the linker script to help with check_compliance.py. Signed-off-by: Josuah Demangeon <[email protected]>

josuah force-pushed the pr_usb_host_class_api2 branch 2 times, most recently from 099d7d7 to 13bcf60 Compare December 9, 2025 16:35

josuah marked this pull request as draft December 9, 2025 17:10

josuah force-pushed the pr_usb_host_class_api2 branch 5 times, most recently from 1e45a69 to 5bd97c9 Compare December 10, 2025 01:35

josuah force-pushed the pr_usb_host_class_api2 branch from 5bd97c9 to 3c6b1ab Compare December 10, 2025 14:55

Josuah Demangeon and others added 6 commits December 10, 2025 16:57

usb: host: class: implement more of the class/data struct fields

5d2d132

Add a "struct usbh_class_api" for the host implementation, and move all the function poitners to it. Add more fields to "struct usbh_class_data". Signed-off-by: Josuah Demangeon <[email protected]>

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

650ab53

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 <[email protected]>

usb: uvc: move the header definition to include/

cb94f8e

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 <[email protected]>

tests: usb: host: test basic API functionality

a8d02cb

Add tests making sure the USB Host class APIs introduced build and run as expected. Signed-off-by: Josuah Demangeon <[email protected]>

usb: host: use SPDX-FileCopyrightText prefix

c995d9b

Switch to the SPDX-FileCopyrightText prefix for all sources in USB Host class. Signed-off-by: Josuah Demangeon <[email protected]>

josuah force-pushed the pr_usb_host_class_api2 branch from 3c6b1ab to c995d9b Compare December 10, 2025 17:15

		@@ -0,0 +1,147 @@
		/*
		* Copyright (c) 2025 Nordic Semiconductor ASA

		return usbh_desc_is_valid(desc, desc_end, sizeof(struct usb_if_descriptor)) &&
		((struct usb_desc_header *)desc)->bDescriptorType == USB_DESC_INTERFACE;

USB Host: integrate class API [2: helpers] #94590

Are you sure you want to change the base?

USB Host: integrate class API [2: helpers] #94590

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

josuah commented Nov 27, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

josuah commented Aug 17, 2025 •

edited

Loading

josuah Sep 5, 2025 •

edited

Loading