usb: host: class: support for usb host video class

[AidenHu]

Dependency:
USB Host: integrate class API [4: aggregated] #99775

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

[github-actions]

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]

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

[AidenHu]

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

Thanks, done it.

[dleach02]

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

[dleach02]

@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

[AidenHu]

@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.

[josuah]

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:

• USB Host: integrate class API [1: types] #94504
• USB Host: integrate class API [2: helpers] #94590
• USB Host: integrate class API [3: UVC] #94591

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]

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

[josuah]

Hello @AidenHu,

Your current PR implements everything at once, which is impressive, but we have no guarantee that the USB host API will look like this in the final version, so maybe we will need to update the current PR many times.

I used some of your code to make 3 small PRs to make an USB host class API. Hopefully these will be merged soon:

Pull request	Rebased version of #94085	Summary
API1: #94504	main...josuah:zephyr:enable_usb_host_video_class_api1	Data type changes only
API2: #94590	main...josuah:zephyr:enable_usb_host_video_class_api2	Helper functions
API3: #94591	main...josuah:zephyr:enable_usb_host_video_class_api3	Shared UVC code

They are stacked together: API3 is based on API2 which is based on API1.

I believe, if you rebase the current PR on top of them, the current PR will be easier to review, and require fewer changes in the future.

I already rebased the current PR #94085 on top of them, see the "rebased version" column of the table.
The most complete is enable_usb_host_video_class_api3, which contains all the rebase effort from _api2 and _api1 as well as this current PR.

Would you like to integrate these API changes into this current PR? To illustrate what I mean:

cd ~/zephyrproject/zephyr
git remote add josuah https://github.com/josuah/zephyr
git fetch josuah
git checkout josuah/enable_usb_host_video_class_api3
git cherry-pick <<< extra commits from 2025/08/16, missing from enable_usb_host_video_class_apiX >>>
west build -b rd_rw612_bga samples/drivers/video/capture
west flash
<<< now testing that the USB camera input still works >>>
git checkout enable_usb_host_video_class
git reset --hard enable_usb_host_video_class
git push -f

Thank you again for your progress on this PR!

[josuah]

I just noticed that when I did the rebased versions (enable_usb_host_video_class_api1/2/3), I did not integrated your latest progress, but used the version from 2025/08/14, without the extra change from 2025/08/16.

I updated the snippet above.

[josuah]

Here is now a comparison between this current PR, and the updated versions of that PR:

• main...josuah:zephyr:enable_usb_host_video_class_api1
• main...josuah:zephyr:enable_usb_host_video_class_api2
• main...josuah:zephyr:enable_usb_host_video_class_api3

The easiest is probably to start from enable_usb_host_video_class_api3 directly (see shell commands above) and test the hardware again.

[josuah]

This function got integrated in the prosposed API2 #94590:

zephyr/subsys/usb/host/usbh_class.c

Lines 61 to 95 in e57477d

	bool usbh_class_is_matching(struct usbh_class_data *cdata,
	struct usbh_class_filter *device_info)
	{
	/* Traverse the filter table until a terminator (empty flags) is found */
	for (int i = 0; cdata->filters[i].flags != 0; i++) {
	const struct usbh_class_filter *filter = &cdata->filters[i];
	if (filter->flags & USBH_CLASS_FILTER_VID) {
	if (filter->vid != device_info->vid) {
	continue;
	}
	}
	if (filter->flags & USBH_CLASS_FILTER_VID) {
	if (filter->vid == device_info->vid) {
	continue;
	}
	}
	if (filter->flags & USBH_CLASS_FILTER_CODE_TRIPLE) {
	if (filter->code_triple.dclass != device_info->code_triple.dclass ||
	(filter->code_triple.sub != 0xFF &&
	filter->code_triple.sub != device_info->code_triple.sub) ||
	(filter->code_triple.proto != 0x00 &&
	filter->code_triple.proto != device_info->code_triple.proto)) {
	continue;
	}
	}
	/* All the filters enabled did match */
	return true;
	}
	return false;
	}

[josuah]

This part got integrated into the proposed API2 PR #94590 as a helper to search a descriptor:

zephyr/subsys/usb/host/usbh_desc.c

Lines 10 to 29 in e57477d

	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)
	{
	const uint8_t *curr_addr = start_addr;
	while (curr_addr < end_addr) {
	struct usb_desc_header *desc = (void *)curr_addr;
	if (desc->bLength == 0) {
	break;
	}
	if ((BIT(desc->bDescriptorType) & type_mask) != 0) {
	return desc;
	}
	}
	return NULL;
	}

Then this got integrated back into this PR on main...josuah:zephyr:enable_usb_host_video_class_api2 or main...josuah:zephyr:enable_usb_host_video_class_api3

zephyr/subsys/usb/host/usbh_core.c

Lines 93 to 111 in ca2b214

	desc = usbh_desc_get_by_type(start_addr, end_addr, mask);
	if (desc == NULL) {
	LOG_ERR("No IAD or interface descriptor found - error condition");
	break;
	}
	start_addr = (uint8_t *)desc;
	if (desc->bDescriptorType == USB_DESC_INTERFACE_ASSOC) {
	found_iad = true;
	}
	if (desc->bDescriptorType == USB_DESC_INTERFACE) {
	struct usb_if_descriptor *if_desc = (void *)desc;
	device_info.code_triple.dclass = if_desc->bInterfaceClass;
	device_info.code_triple.sub = if_desc->bInterfaceSubClass;
	device_info.code_triple.proto = if_desc->bInterfaceProtocol;
	found_interface = true;
	}

[josuah]

Likewise, this got integrated into the proposed API2 PR #94590 as a helper to search a descriptor:

zephyr/subsys/usb/host/usbh_desc.c

Lines 10 to 29 in e57477d

	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)
	{
	const uint8_t *curr_addr = start_addr;
	while (curr_addr < end_addr) {
	struct usb_desc_header *desc = (void *)curr_addr;
	if (desc->bLength == 0) {
	break;
	}
	if ((BIT(desc->bDescriptorType) & type_mask) != 0) {
	return desc;
	}
	}
	return NULL;
	}

Then this got integrated back into this PR on main...josuah:zephyr:enable_usb_host_video_class_api2 or main...josuah:zephyr:enable_usb_host_video_class_api3

zephyr/subsys/usb/host/usbh_core.c

Lines 113 to 119 in ca2b214

	/* Step 2: Continue searching for subsequent descriptors to determine end_addr */
	start_addr += ((struct usb_desc_header *)start_addr)->bLength;
	/* Find next IAD */
	mask = BIT(USB_DESC_INTERFACE_ASSOC);
	desc = usbh_desc_get_by_type(start_addr, end_addr, mask);
	next_iad_addr = (uint8_t *)desc;

[josuah]

Likewise, this got integrated into the proposed API2 PR #94590 as a helper to search a descriptor:

zephyr/subsys/usb/host/usbh_desc.c

Lines 10 to 29 in e57477d

	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)
	{
	const uint8_t *curr_addr = start_addr;
	while (curr_addr < end_addr) {
	struct usb_desc_header *desc = (void *)curr_addr;
	if (desc->bLength == 0) {
	break;
	}
	if ((BIT(desc->bDescriptorType) & type_mask) != 0) {
	return desc;
	}
	}
	return NULL;
	}

Then this got integrated back into this PR on main...josuah:zephyr:enable_usb_host_video_class_api2 or main...josuah:zephyr:enable_usb_host_video_class_api3

zephyr/subsys/usb/host/usbh_core.c

Lines 135 to 144 in ca2b214

	/* Get class code from first interface after IAD */
	mask = BIT(USB_DESC_INTERFACE_ASSOC);
	desc = usbh_desc_get_by_type(start_addr, end_addr, mask);
	if (desc != NULL) {
	struct usb_if_descriptor *if_desc = (void *)desc;
	device_info.code_triple.dclass = if_desc->bInterfaceClass;
	device_info.code_triple.sub = if_desc->bInterfaceSubClass;
	device_info.code_triple.proto = if_desc->bInterfaceProtocol;
	}

[josuah]

Likewise, this got integrated into the proposed API2 PR #94590 as a helper to search a descriptor:

zephyr/subsys/usb/host/usbh_desc.c

Lines 10 to 29 in e57477d

	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)
	{
	const uint8_t *curr_addr = start_addr;
	while (curr_addr < end_addr) {
	struct usb_desc_header *desc = (void *)curr_addr;
	if (desc->bLength == 0) {
	break;
	}
	if ((BIT(desc->bDescriptorType) & type_mask) != 0) {
	return desc;
	}
	}
	return NULL;
	}

Then this got integrated back into this PR on main...josuah:zephyr:enable_usb_host_video_class_api2 or main...josuah:zephyr:enable_usb_host_video_class_api3

zephyr/subsys/usb/host/usbh_core.c

Lines 147 to 157 in ca2b214

	/* Get class code from first interface after IAD */
	start_addr += iad_desc->bLength;
	mask = BIT(USB_DESC_INTERFACE);
	desc = usbh_desc_get_by_type(start_addr, end_addr, mask);
	if (desc != NULL) {
	struct usb_if_descriptor *if_desc = (void *)start_addr;
	device_info.code_triple.dclass = if_desc->bInterfaceClass;
	device_info.code_triple.sub = if_desc->bInterfaceSubClass;
	device_info.code_triple.proto = if_desc->bInterfaceProtocol;
	}

[josuah]

In the proposed API2 PR #94590, this got moved to usbh_class.c:

zephyr/subsys/usb/host/usbh_class.c

Lines 45 to 59 in ca2b214

	int usbh_init_registered_classes(struct usbh_context *uhs_ctx)
	{
	struct usbh_class_data *cdata;
	int ret;
	SYS_SLIST_FOR_EACH_CONTAINER(&uhs_ctx->class_list, cdata, node) {
	ret = usbh_class_init(cdata);
	if (ret != 0) {
	LOG_ERR("Failed to initialize class instance");
	return ret;
	}
	}
	return 0;
	}

[josuah]

In the prosposed API2 #94590, there is no more check for cdata->api == NULL (could be an assert instead eventually), and the check for cdata->api->connected == NULL is integrated into an API wrapper, like it is done for USB device class API:

7aa4f8d

/**
 * @brief Device connected handler
 *
 * Called when a device is connected to the bus
 * and it matches the class filters of this instance.
 *
 * @param[in] c_data Pointer to USB host class data
 * @param[in] desc_start_addr Pointer to the start of the descriptor
 * @param[in] desc_end_addr Pointer after the end of the USB descriptor
 *
 * @return 0 on success, negative error code on failure.
 */
static inline int usbh_class_connected(struct usbh_class_data *const c_data,
				       void *const desc_start_addr,
				       void *const desc_end_addr)
{
	const struct usbh_class_api *api = c_data->api;

	if (api->connected != NULL) {
		return api->connected(c_data, desc_start_addr, desc_end_addr);
	}

	return -ENOTSUP;
}

[josuah]

This code is already present on the UVC device class. In the proposed API3 PR #94590, there is a common definition in usb_common_uvc.c that can be used by both host and device:

zephyr/subsys/usb/common/usb_common_uvc.c

Lines 16 to 25 in ca2b214

	static const struct uvc_guid_quirk uvc_guid_quirks[] = {
	{
	.fourcc = VIDEO_PIX_FMT_YUYV,
	.guid = UVC_FORMAT_GUID("YUY2"),
	},
	{
	.fourcc = VIDEO_PIX_FMT_GREY,
	.guid = UVC_FORMAT_GUID("Y800"),
	},
	};

[josuah]

This code is already present on the UVC device class. In the proposed API3 PR #94590, there is a common definition in usb_common_uvc.c that can be used by both host and device:

https://github.com/josuah/zephyr/blob/ca2b214d13ee96dbe65275dcac70dc93738e5873/subsys/usb/common/usb_common_uvc.c#L198-L234

[josuah]

As you noticed there is the need to specify the min/max/step/def for every video control.

Using arbitrary values works great for a first implementation, however a complete support would require querying the UVC device for GET_MIN, GET_MAX, GET_DEF... and map the UVC types to the Zephyr Video types.

There is a database that specify how these two are related in the UVC device class, an in the proposed API3 PR #94590, this is extracted into a separate file, along with helper functions to access these tables:

https://github.com/josuah/zephyr/blob/enable_usb_host_video_class_api3/subsys/usb/common/usb_common_uvc.c#L27-L196

I have not yet integrated this into the current PR #94085 but can be working on it soon.

[josuah]

I forgot to say: the comments are only there to give an illustration of how it is possible to adapt this PR to integrate it with the WIP USB Host class API proposed (API1/2/3/...). Maybe a different adaptation is better.

[AidenHu]

@josuah, Thank you so much for the comments, I will do it soon.

[AidenHu]

git checkout josuah/enable_usb_host_video_class_api3
git cherry-pick <<< extra commits from 2025/08/16, missing from enable_usb_host_video_class_apiX >>>

@josuah, Consider to speed up to do the merging tomorrow, just want to make sure with you that enable_usb_host_video_class_apiX means enable_usb_host_video_class_api1 and enable_usb_host_video_class_api2 in the condition of using enable_usb_host_video_class_api3 branch directly?

[sonarqubecloud]

Quality Gate failed

Failed conditions
E Reliability Rating on New Code (required ≥ C)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE