usb: host: introduce usbh_class with init/remove functions

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

Author: Josuah Demangeon

include/zephyr/usb/usbh.h

@@ -127,10 +127,36 @@ struct usbh_class_data {
 };
 
 /**
+ * @cond INTERNAL_HIDDEN
+ *
+ * Variables used by the USB host stack but not exposed to the class
+ * through the class API.
  */
-#define USBH_DEFINE_CLASS(name) \
-	static STRUCT_SECTION_ITERABLE(usbh_class_data, name)
+struct usbh_class_node {
+	/** Class information exposed to host class implementations (drivers). */
+	struct usbh_class_data *const c_data;
+};
+/* @endcond */
 
+/**
+ * @brief Define USB host support class data
+ *
+ * Macro defines class (function) data, as well as corresponding node
+ * structures used internally by the stack.
+ *
+ * @param[in] class_name Class name
+ * @param[in] class_api  Pointer to struct usbh_class_api
+ * @param[in] class_priv Class private data
+ */
+#define USBH_DEFINE_CLASS(class_name, class_api, class_priv)			\
+	static struct usbh_class_data class_data_##class_name = {		\
+		.name = STRINGIFY(class_name),					\
+		.api = class_api,						\
+		.priv = class_priv,						\
+	};									\
+	static STRUCT_SECTION_ITERABLE(usbh_class_node, class_name) = {		\
+		.c_data = &class_data_##class_name,				\
+	};
 
 /**
  * @brief Initialize the USB host support;

subsys/usb/host/CMakeLists.txt

@@ -5,9 +5,10 @@ zephyr_library()
 zephyr_library_include_directories(${CMAKE_CURRENT_SOURCE_DIR})
 
 zephyr_library_sources(
+	usbh_api.c
 	usbh_ch9.c
+	usbh_class.c
 	usbh_core.c
-	usbh_api.c
 	usbh_device.c
 )
 

subsys/usb/host/usbh_class.c

@@ -10,9 +10,107 @@
 
 #include "usbh_class.h"
 #include "usbh_class_api.h"
+#include "usbh_desc.h"
 
 LOG_MODULE_REGISTER(usbh_class, CONFIG_USBH_LOG_LEVEL);
 
+int usbh_class_init_all(struct usbh_context *const uhs_ctx)
+{
+	int ret;
+
+	STRUCT_SECTION_FOREACH(usbh_class_node, c_node) {
+		ret = usbh_class_init(c_node->c_data, uhs_ctx);
+		if (ret != 0) {
+			LOG_ERR("Failed to initialize all registered class instances");
+			return ret;
+		}
+	}
+
+	return 0;
+}
+
+int usbh_class_remove_all(const struct usb_device *const udev)
+{
+	int ret;
+
+	STRUCT_SECTION_FOREACH(usbh_class_node, c_node) {
+		if (c_node->c_data->udev == udev) {
+			ret = usbh_class_removed(c_node->c_data);
+			if (ret != 0) {
+				LOG_ERR("Failed to handle device removal for each classes");
+				return ret;
+			}
+
+			/* The class instance is now free to bind to a new device */
+			c_node->c_data->udev = NULL;
+		}
+	}
+
+	return 0;
+}
+
+static int usbh_class_probe_one(struct usbh_class_data *const c_data, struct usb_device *const udev)
+{
+	const uint8_t *const desc_beg = usbh_desc_get_cfg_beg(udev);
+	const uint8_t *const desc_end = usbh_desc_get_cfg_end(udev);
+	const struct usb_desc_header *desc;
+	const struct usb_cfg_descriptor *cfg_desc;
+	int ret;
+
+	desc = usbh_desc_get_by_type(desc_beg, desc_end, USB_DESC_CONFIGURATION);
+	if (desc == NULL) {
+		LOG_ERR("Unable to find a configuration descriptor");
+		return -EBADMSG;
+	}
+
+	cfg_desc = (struct usb_cfg_descriptor *)desc;
+
+	for (uint8_t ifnum = 0; ifnum < cfg_desc->bNumInterfaces; ifnum++) {
+		ret = usbh_class_probe(c_data, udev, ifnum);
+		if (ret == -ENOTSUP) {
+			LOG_DBG("Class %s not supporting this device, skipping", c_data->name);
+			continue;
+		}
+		if (ret != 0) {
+			LOG_ERR("Failed to register the class %s for interface %u",
+				c_data->name, ifnum);
+			return ret;
+		}
+		if (ret == 0) {
+			LOG_INF("Class %s is matching this device for interface %u, assigning it",
+				c_data->name, ifnum);
+			c_data->udev = udev;
+			c_data->ifnum = ifnum;
+			return 0;
+		}
+	}
+
+	return -ENOTSUP;
+}
+
+int usbh_class_probe_all(struct usb_device *const udev)
+{
+	int ret;
+
+	STRUCT_SECTION_FOREACH(usbh_class_node, c_node) {
+		struct usbh_class_data *const c_data = c_node->c_data;
+
+		/* If the class is not already having a device */
+		if (c_data->udev == NULL) {
+			ret = usbh_class_probe_one(c_data, udev);
+			if (ret == -ENOTSUP) {
+				continue;
+			}
+			if (ret != 0) {
+				return ret;
+			}
+		}
+	}
+
+	LOG_WRN("Could not find any class for this device");
+	return -ENODEV;
+}
+
 bool usbh_class_is_matching(struct usbh_class_filter *const filters, size_t n_filters,
 			    struct usb_device_descriptor *const desc)
 {

subsys/usb/host/usbh_class.h

@@ -0,0 +1,48 @@
+/*
+ * Copyright (c) 2025 Nordic Semiconductor ASA
+ * Copyright 2025 NXP
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#ifndef ZEPHYR_INCLUDE_USBD_CLASS_H
+#define ZEPHYR_INCLUDE_USBD_CLASS_H
+
+#include <zephyr/usb/usbh.h>
+
+/**
+ * @brief Match an USB host class (a driver) against a device descriptor.
+ *
+ * @param[in] filters Array of filter rules to match
+ * @param[in] n_filters Number of rules in the array.
+ * @param[in] desc USB Device descriptor to match against each rule
+ * @retval true if the USB Device descriptor matches at least one rule.
+ */
+bool usbh_class_is_matching(struct usbh_class_filter *const filters, size_t n_filters,
+			    struct usb_device_descriptor *const desc);
+
+/**
+ * @brief Initialize every class instantiated on the system
+ *
+ * @param[in] uhs_ctx USB Host context to pass to the class.
+ * @retval 0 on success or negative error code on failure
+ */
+int usbh_class_init_all(struct usbh_context *const uhs_ctx);
+
+/**
+ * @brief Probe all classes to against a newly connected USB device.
+ *
+ * @param[in] udev USB device to probe.
+ * @retval 0 on success or negative error code on failure
+ */
+int usbh_class_probe_all(struct usb_device *const udev);
+
+/**
+ * @brief Call the device removal handler for every class configured with it
+ *
+ * @param[in] udev USB device that got removed.
+ * @retval 0 on success or negative error code on failure
+ */
+int usbh_class_remove_all(const struct usb_device *const udev);
+
+#endif /* ZEPHYR_INCLUDE_USBD_CLASS_H */

subsys/usb/host/usbh_core.c

@@ -10,9 +10,12 @@
 #include <zephyr/devicetree.h>
 #include <zephyr/init.h>
 #include <zephyr/sys/iterable_sections.h>
+#include <zephyr/usb/usbh.h>
 
-#include "usbh_internal.h"
+#include "usbh_class.h"
+#include "usbh_class_api.h"
 #include "usbh_device.h"
+#include "usbh_internal.h"
 
 #include <zephyr/logging/log.h>
 LOG_MODULE_REGISTER(uhs, CONFIG_USBH_LOG_LEVEL);
@@ -46,6 +49,7 @@ static int usbh_event_carrier(const struct device *dev,
 static void dev_connected_handler(struct usbh_context *const ctx,
 				  const struct uhc_event *const event)
 {
+	int ret;
 
 	LOG_DBG("Device connected event");
 	if (ctx->root != NULL) {
@@ -71,6 +75,11 @@ static void dev_connected_handler(struct usbh_context *const ctx,
 	if (usbh_device_init(ctx->root)) {
 		LOG_ERR("Failed to reset new USB device");
 	}
+
+	ret = usbh_class_probe_all(ctx->root);
+	if (ret != 0) {
+		LOG_ERR("Failed to probe all classes for this new USB device");
+	}
 }
 
 static void dev_removed_handler(struct usbh_context *const ctx)
@@ -194,12 +203,10 @@ int usbh_init_device_intl(struct usbh_context *const uhs_ctx)
 
 	sys_dlist_init(&uhs_ctx->udevs);
 
-	STRUCT_SECTION_FOREACH(usbh_class_data, cdata) {
-		/*
-		 * For now, we have not implemented any class drivers,
-		 * so just keep it as placeholder.
-		 */
-		break;
+	ret = usbh_class_init_all(uhs_ctx);
+	if (ret != 0) {
+		LOG_ERR("Failed to initialize all classes");
+		return ret;
 	}
 
 	return 0;

subsys/usb/host/usbh_data.ld

@@ -1,4 +1,4 @@
 #include <zephyr/linker/iterable_sections.h>
 
 ITERABLE_SECTION_RAM(usbh_context, Z_LINK_ITERABLE_SUBALIGN)
-ITERABLE_SECTION_RAM(usbh_class_data, Z_LINK_ITERABLE_SUBALIGN)
+ITERABLE_SECTION_RAM(usbh_class_node, Z_LINK_ITERABLE_SUBALIGN)