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

AidenHu · 2025-08-04T14:52:17Z

Add USB host video class driver usbh_uvc.c/h . This class driver is implemented based on UVC 1.5
The USB host video class driver is tightly coupled with the video subsystem. Users still use video API to operate it.
Some key changes for usbh_core.c to support multiple classes that one USB device supports.
Some necessary changes to make video capture example connect with USB device camera based on the new USB host video class driver.

github-actions · 2025-08-04T14:52:55Z

Hello @AidenHu, and thank you very much for your first pull request to the Zephyr project!
Our Continuous Integration pipeline will execute a series of checks on your Pull Request commit messages and code, and you are expected to address any failures by updating the PR. Please take a look at our commit message guidelines to find out how to format your commit messages, and at our contribution workflow to understand how to update your Pull Request. If you haven't already, please make sure to review the project's Contributor Expectations and update (by amending and force-pushing the commits) your pull request if necessary.
If you are stuck or need help please join us on Discord and ask your question there. Additionally, you can escalate the review when applicable. 😊

dleach02 · 2025-08-05T19:01:20Z

samples/drivers/video/capture/boards/rd_rw612_bga.overlay

+	uvc_host: uvc_host {
+		compatible = "zephyr,uvc-host";
+	};
+};


need blank line (repeat this on a couple of the files)

need blank line (repeat this on a couple of the files)

Thanks, done it.

dleach02 · 2025-08-05T19:02:58Z

samples/drivers/video/capture/src/main.c

 #include <zephyr/kernel.h>
 #include <zephyr/device.h>

 #include <zephyr/drivers/display.h>


I know this is draft but I think we want to allow this sample to support Video host and video device

dleach02 · 2025-08-05T19:07:46Z

@AidenHu you are going to need to break this up into multiple commits. My suggestion is:

subsys/usb/host, dts binding, and usbh.h changes
RW612 board/soc changes
sample changes

AidenHu · 2025-08-06T00:44:17Z

@AidenHu you are going to need to break this up into multiple commits. My suggestion is:
1. subsys/usb/host, dts binding, and usbh.h changes

2. RW612 board/soc changes

3. sample changes

Thanks @dleach02, I will split now.

Make the struct name match the device naming for ease of use, although slightly longer name. Propagate the change to the subsystem, includes, tests and samples. Signed-off-by: Josuah Demangeon <[email protected]>

Allocate extra room at the end of the USB descriptor buffer to ensure that the device ends with `desc->bLength == 0`. For now, validating `desc->bLength` from the device to ensure no access past the buffer is still not done. Signed-off-by: Josuah Demangeon <[email protected]>

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. Add helpers to check the status. Signed-off-by: Josuah Demangeon <[email protected]>

Hide the mutex lock details inside a wrapper call, like done for the device stack API. This is not used for the per-device lock of the host stack which use a different mutex lock. Signed-off-by: Josuah Demangeon <[email protected]>

Update the USB shell sample to the new syntax. This is based on tests done with native_sim, along with the virtual.conf, virtual.overlay and device_and_host_prj.conf extra config files. Signed-off-by: Josuah Demangeon <[email protected]>

josuah · 2025-08-14T17:38:32Z

Thank you for updating this PR with a more fine-grained commit history.

In parallel, I opened #94504 to add the missing USB Host API bits to enable this class to be implemented, using the content of this current PR:

And here is this current PR nxp-upstream:enable_usb_host_video_class but rebased on top of pr_usb_host_class_api2:

main...josuah:zephyr:enable_usb_host_video_class_api2

AidenHu · 2025-08-15T01:38:28Z

Thank you for updating this PR with a more fine-grained commit history.
In parallel, I opened #94504 to add the missing USB Host API bits to enable this class to be implemented, using the content of this current PR.
For now pr_usb_host_class_api (#94504), pr_usb_host_class_api2, pr_usb_host_class_api3 etc.
And here is this current PR nxp-upstream:enable_usb_host_video_class but rebased on top of pr_usb_host_class_api2:
* [main...josuah:zephyr:enable_usb_host_video_class](https://github.com/zephyrproject-rtos/zephyr/compare/main...josuah:zephyr:enable_usb_host_video_class)

Thank you for the reply, @josuah

Add a "struct usbh_class_api" for the host implementation, and move all the function poitners to it, as it is done for the device support. Add more fields to the host struct usbh_class_data mirrorring the device side struct, including the API pointer. 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 register 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. The class instances are registered and connected together as a linked list. Co-authored-by: Aiden Hu <[email protected]> Signed-off-by: Josuah Demangeon <[email protected]>

Incorrect start address is used for usbh_class_connected for each supported independent class. Implement dev_removed_handler to properly notify class disconnection event. Signed-off-by: Aiden Hu <[email protected]>

Move the pointer to the next descriptor to prevent incorrect address usage. Signed-off-by: Aiden Hu <[email protected]>

Change the default value for QH/QTD/ITD/SITD of usb host ehci. Signed-off-by: Aiden Hu <[email protected]>

1. Delete uvc_guid_map and related functions, use the database and helper functions from usb_common_uvc.c 2. Rename uvc_host_parse_frame_intervals as uvc_host_parse_frame_default_intervals to select default frame interval. 3. Correct uvc_host_select_streaming_alternate to do right alternate selection. 4. Implement uvc_host_removed function. 5. Enhance the video_usb_uvc_host_set_stream function. Signed-off-by: Aiden Hu <[email protected]>

1. Use common usb_uvc.h header for usbh_uvc.c 2. Delete common definitions from usbh_uvc.h 3. Clean up and optimize usbh_uvc.c 4. Add necessary symbols for usb host uvc class. Signed-off-by: Aiden Hu <[email protected]>

Some necessary definitions are added. Do some improvements for the existing content based on the UVC spec. Signed-off-by: Aiden Hu <[email protected]>

Adjust video stream callback function to be more robust. Use multiple primes to improve the throughput. Signed-off-by: Aiden Hu <[email protected]>

This new symbol is used to set usb transfer prime count. Signed-off-by: Aiden Hu <[email protected]>

Set proper value for some resources. Use configurable fps. Signed-off-by: Aiden Hu <[email protected]>

AidenHu · 2025-09-05T08:56:02Z

@josuah, I have pushed another 3 commits to enhance the video stream transfer and optimize resource usage.
I noticed that you have successfully merged pr_usb_host_class_api2. To expedite the merging process for the current host video class, appreciate your any feedback. Thanks

josuah · 2025-09-05T16:33:42Z

There is a discussion about how to handle various aspects of the class API in:
#94590

So as of now, API1 is merged, and API2 is going to have slight modifications.
In addition, unit tests will be added, which will make it possible for this PR to include unit tests.

Something which can help getting favorable review is to get the CI passing.
For instance these NXP board status:

https://github.com/zephyrproject-rtos/zephyr/actions/runs/17488297525/job/49672041698?pr=94085

Thank you for the update!

josuah · 2025-09-10T10:52:12Z

The current roadmap as I understand it:

Completing the host class API on USB Host: integrate class API [2: helpers] #94590
Modifications on this current PR to get the latest APIs
A test framework for USB classes will be introduced, use it on this PR too
Discussing the organization of the UVC class to make it familiar to the rest of USB code.
Make this PR pass all CI tests (related to https://docs.zephyrproject.org/latest/contribute/index.html)
Final review by the USB maintainers and apply further change requests.

I think this would ready to merge after this.

Future improvement on the side of video can be done on follow-up PR to cover more features.
It might even be possible to remove the USB controls altogether for the sake of making this PR smaller and easier to review/merge.

Would that make sense?

AidenHu · 2025-09-16T06:53:18Z

@josuah,
I have updated the processing about the video control based on the usb_common_uvc.c . The commit is usb_video_ctrl
If you have time, please help to review. Based on the current code, I have to expose the video_find_ctrl as an API and I have created another commit video_subsys_video_ctrl. Hope your any comment, thanks.

AidenHu · 2025-09-16T06:55:34Z

subsys/usb/common/usb_common_uvc.c

+		.type = UVC_CONTROL_SIGNED,
+	},
+	{
+		.size = 1,


Hi @josuah,
Here the size should be 2 for PU_CONTRAST_CONTROL

Good catch, thanks for checking! This will need an update upstream to fix both device and host side.

1. Use the uvc_control_map from usb_common_uvc.c. 2. Use GET_MIN/GET_MAX/GET_RES/GET_DEF request to query device. 3. Unify the handling for single video control Signed-off-by: Aiden Hu <[email protected]>

video_find_ctrl becomes an API. Signed-off-by: Aiden Hu <[email protected]>

josuah

Hello and sorry for staying silent for such a long time.
I am still trying to gather as much time as I can to make progress on the host class API.

Before going into the point-by-point detail, I thought to wait that the class API is ready so that all the details are reviewed once, so that you do not have to repeat the work every change.

The host class API seems to be somewhat identical to what you built on top, except for one major point, which I will discuss below.

josuah · 2025-09-16T09:20:23Z

subsys/usb/common/usb_common_uvc.c

+		.type = UVC_CONTROL_SIGNED,
+	},
+	{
+		.size = 1,


Good catch, thanks for checking! This will need an update upstream to fix both device and host side.

subsys/usb/host/class/usbh_uvc.c

Do some improvement to meet the coding style of zephyr. Signed-off-by: Aiden Hu <[email protected]>

1. check class_list empty for class register. 2. cleanup the code for usbh_class_is_matching Signed-off-by: Aiden Hu <[email protected]>

The node field should be located the memory starting. Signed-off-by: Aiden Hu <[email protected]>

sonarqubecloud · 2025-10-21T07:04:48Z

Quality Gate passed

Issues
22 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud

AidenHu force-pushed the enable_usb_host_video_class branch 2 times, most recently from 669c434 to 4ca6d07 Compare August 5, 2025 08:50

dleach02 added the area: USB Universal Serial Bus label Aug 5, 2025

dleach02 reviewed Aug 5, 2025

View reviewed changes

dleach02 mentioned this pull request Aug 5, 2025

Planned USB host video implementation #93517

Open

15 tasks

AidenHu force-pushed the enable_usb_host_video_class branch 2 times, most recently from cb3ab4e to 76bed79 Compare August 6, 2025 02:59

carlescufi requested a review from josuah August 6, 2025 10:33

AidenHu force-pushed the enable_usb_host_video_class branch from 76bed79 to 9192550 Compare August 7, 2025 02:41

Josuah Demangeon added 5 commits August 13, 2025 15:13

usb: host: rename "struct usbh_contex" to "usbh_context"

0054ae9

Make the struct name match the device naming for ease of use, although slightly longer name. Propagate the change to the subsystem, includes, tests and samples. Signed-off-by: Josuah Demangeon <[email protected]>

usb: host: wrap the mutex lock with a helper

dedc29a

Hide the mutex lock details inside a wrapper call, like done for the device stack API. This is not used for the per-device lock of the host stack which use a different mutex lock. Signed-off-by: Josuah Demangeon <[email protected]>

josuah mentioned this pull request Aug 14, 2025

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

Merged

AidenHu force-pushed the enable_usb_host_video_class branch from 9192550 to 6e8acc7 Compare August 14, 2025 14:58

AidenHu closed this Aug 15, 2025

AidenHu reopened this Aug 15, 2025

AidenHu force-pushed the enable_usb_host_video_class branch 2 times, most recently from 90739a9 to aef5e85 Compare August 15, 2025 02:09

Josuah Demangeon and others added 3 commits August 15, 2025 13:56

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

7aa4f8d

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]>

AidenHu force-pushed the enable_usb_host_video_class branch from aef5e85 to 629e311 Compare August 16, 2025 14:02

AidenHu added 6 commits September 1, 2025 18:41

subsys: usb: host: fix class match issue and add remove handling

eea5207

Incorrect start address is used for usbh_class_connected for each supported independent class. Implement dev_removed_handler to properly notify class disconnection event. Signed-off-by: Aiden Hu <[email protected]>

subsys: usb: host: fix descriptor parsing by updating curr_addr

1362e88

Move the pointer to the next descriptor to prevent incorrect address usage. Signed-off-by: Aiden Hu <[email protected]>

modules: hal_nxp: mcux: update macros for usb host EHCI

96b6bec

Change the default value for QH/QTD/ITD/SITD of usb host ehci. Signed-off-by: Aiden Hu <[email protected]>

usb: host: class: use common usb uvc header for host uvc class

91fa606

1. Use common usb_uvc.h header for usbh_uvc.c 2. Delete common definitions from usbh_uvc.h 3. Clean up and optimize usbh_uvc.c 4. Add necessary symbols for usb host uvc class. Signed-off-by: Aiden Hu <[email protected]>

usb: uvc: add more contents for the header used by host and device

1ce0e22

Some necessary definitions are added. Do some improvements for the existing content based on the UVC spec. Signed-off-by: Aiden Hu <[email protected]>

AidenHu force-pushed the enable_usb_host_video_class branch from 9d15e7e to 1ce0e22 Compare September 1, 2025 10:45

AidenHu added 3 commits September 5, 2025 16:22

subsys: usb: host: enhance host video stream transfer

d12370e

Adjust video stream callback function to be more robust. Use multiple primes to improve the throughput. Signed-off-by: Aiden Hu <[email protected]>

usb: host: class: add symbol USBH_VIDEO_MULTIPLE_PRIME_COUNT

f428572

This new symbol is used to set usb transfer prime count. Signed-off-by: Aiden Hu <[email protected]>

samples: drivers: video: improve the video capture sample

0c21bc2

Set proper value for some resources. Use configurable fps. Signed-off-by: Aiden Hu <[email protected]>

josuah added the area: Video Video subsystem label Sep 5, 2025

AidenHu commented Sep 16, 2025

View reviewed changes

AidenHu added 2 commits September 17, 2025 15:52

usb: host: class: improve the video control handling

9328c37

1. Use the uvc_control_map from usb_common_uvc.c. 2. Use GET_MIN/GET_MAX/GET_RES/GET_DEF request to query device. 3. Unify the handling for single video control Signed-off-by: Aiden Hu <[email protected]>

drivers: video: expose video_find_ctrl by removing static keyword

7af56c4

video_find_ctrl becomes an API. Signed-off-by: Aiden Hu <[email protected]>

AidenHu force-pushed the enable_usb_host_video_class branch from 481d326 to 7af56c4 Compare September 17, 2025 08:35

jfischer-no mentioned this pull request Oct 14, 2025

Planned USB host support work #95661

Open

15 tasks

josuah reviewed Oct 16, 2025

View reviewed changes

subsys/usb/host/class/usbh_uvc.c Show resolved Hide resolved

AidenHu added 2 commits October 20, 2025 15:45

usb: host: class: update for required coding style

ef26921

Do some improvement to meet the coding style of zephyr. Signed-off-by: Aiden Hu <[email protected]>

samples: drivers: video: update for required coding style

af64db8

Do some improvement to meet the coding style of zephyr. Signed-off-by: Aiden Hu <[email protected]>

AidenHu force-pushed the enable_usb_host_video_class branch 2 times, most recently from 0a0e85c to 595ae12 Compare October 20, 2025 14:04

AidenHu added 2 commits October 21, 2025 14:31

subsys: usb: host: do enhancement for class register.

c9a92c3

1. check class_list empty for class register. 2. cleanup the code for usbh_class_is_matching Signed-off-by: Aiden Hu <[email protected]>

usb: host: move node member to the beginning of usbh_class_data

d9ef061

The node field should be located the memory starting. Signed-off-by: Aiden Hu <[email protected]>

AidenHu force-pushed the enable_usb_host_video_class branch from 595ae12 to d9ef061 Compare October 21, 2025 06:36

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

Are you sure you want to change the base?

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

Conversation

AidenHu commented Aug 4, 2025

Uh oh!

github-actions bot commented Aug 4, 2025

Uh oh!

dleach02 Aug 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!

AidenHu Aug 6, 2025

Choose a reason for hiding this comment

Uh oh!

dleach02 Aug 5, 2025

Choose a reason for hiding this comment

Uh oh!

dleach02 commented Aug 5, 2025

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

AidenHu commented Aug 15, 2025

Uh oh!

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

Uh oh!

Uh oh!

josuah commented Sep 5, 2025

Uh oh!

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

Uh oh!

Uh oh!

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

Uh oh!

Uh oh!

AidenHu Sep 16, 2025

Choose a reason for hiding this comment

Uh oh!

josuah Sep 16, 2025

Choose a reason for hiding this comment

Uh oh!

josuah left a comment

Choose a reason for hiding this comment

Uh oh!

josuah Sep 16, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

sonarqubecloud bot commented Oct 21, 2025

Quality Gate passed

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

dleach02 Aug 5, 2025 •

edited

Loading

AidenHu commented Aug 6, 2025 •

edited

Loading

josuah commented Aug 14, 2025 •

edited

Loading

AidenHu commented Sep 5, 2025 •

edited

Loading

josuah commented Sep 10, 2025 •

edited

Loading

AidenHu commented Sep 16, 2025 •

edited

Loading