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

Author: Josuah Demangeon

include/zephyr/usb/usbh.h

@@ -1,5 +1,6 @@
 /*
- * Copyright (c) 2022 Nordic Semiconductor ASA
+ * Copyright (c) 2025 Nordic Semiconductor ASA
+ * Copyright 2025 NXP
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -17,6 +18,7 @@
 #include <stdint.h>
 #include <zephyr/device.h>
 #include <zephyr/net_buf.h>
+#include <zephyr/sys/util.h>
 #include <zephyr/sys/dlist.h>
 #include <zephyr/sys/bitarray.h>
 #include <zephyr/drivers/usb/uhc.h>
@@ -72,20 +74,26 @@ struct usbh_context {
 		.addr_ba = &ba_##device_name,				\
 	}
 
+struct usbh_class_data;
+
 /**
- * @brief USB Class Code triple
+ * @brief Information about a device, which is relevant for matching a particular class.
  */
-struct usbh_code_triple {
-	/** Device Class Code */
-	uint8_t dclass;
-	/** Class Subclass Code */
+struct usbh_class_filter {
+	/** Vendor ID */
+	uint16_t vid;
+	/** Product ID */
+	uint16_t pid;
+	/** Class Code */
+	uint8_t class;
+	/** Subclass Code */
 	uint8_t sub;
-	/** Class Protocol Code */
+	/** Protocol Code */
 	uint8_t proto;
+	/** Flags that tell which field to match */
+	uint8_t flags;
 };
 
-struct usbh_class_data;
-
 /**
  * @brief USB host class instance API
  */
@@ -123,10 +131,59 @@ struct usbh_class_data {
 };
 
 /**
+ * @cond INTERNAL_HIDDEN
+ *
+ * Internal state of an USB class. Not corresponding to an USB protocol state,
+ * but instead software life cycle.
  */
-#define USBH_DEFINE_CLASS(name) \
-	static STRUCT_SECTION_ITERABLE(usbh_class_data, name)
+enum usbh_class_state {
+	/** The class is available to be associated to an USB device function. */
+	USBH_CLASS_STATE_IDLE,
+	/** The class got bound to an USB function of a particular device on the bus. */
+	USBH_CLASS_STATE_BOUND,
+	/** The class failed to initialize and cannot be used. */
+	USBH_CLASS_STATE_ERROR,
+};
+/* @endcond */
 
+/**
+ * @cond INTERNAL_HIDDEN
+ *
+ * Variables used by the USB host stack but not exposed to the class
+ * through the class API.
+ */
+struct usbh_class_node {
+	/** Class information exposed to host class implementations (drivers). */
+	struct usbh_class_data *const c_data;
+	/** Filter rules to match this USB host class instance against a device class **/
+	struct usbh_class_filter *filters;
+	/** State of the USB class instance */
+	enum usbh_class_state state;
+};
+/* @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
+ * @param[in] filt Array of @ref usbh_class_filter to match this class or NULL to match everything.
+ *                 When non-NULL, the it has to be terminated by an entry with @c flags set to 0.
+ */
+#define USBH_DEFINE_CLASS(class_name, class_api, class_priv, filt)		\
+	static struct usbh_class_data UTIL_CAT(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 = &UTIL_CAT(class_data_, class_name),			\
+		.filters = filt,						\
+	};
 
 /**
  * @brief Initialize the USB host support;

subsys/usb/host/CMakeLists.txt

@@ -5,9 +5,11 @@ 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_desc.c
   usbh_device.c
 )
 

subsys/usb/host/usbh_class.c

@@ -0,0 +1,188 @@
+/*
+ * Copyright (c) 2025 Nordic Semiconductor ASA
+ * Copyright 2025 NXP
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <zephyr/usb/usbh.h>
+#include <zephyr/logging/log.h>
+
+#include "usbh_class.h"
+#include "usbh_class_api.h"
+#include "usbh_desc.h"
+#include "usbh_host.h"
+
+LOG_MODULE_REGISTER(usbh_class, CONFIG_USBH_LOG_LEVEL);
+
+void usbh_class_init_all(struct usbh_context *const uhs_ctx)
+{
+	int ret;
+
+	usbh_host_lock(uhs_ctx);
+
+	STRUCT_SECTION_FOREACH(usbh_class_node, c_node) {
+		struct usbh_class_data *const c_data = c_node->c_data;
+
+		if (c_node->state != USBH_CLASS_STATE_IDLE) {
+			LOG_DBG("Skipping '%s' in state %u", c_data->name, c_node->state);
+			continue;
+		}
+
+		ret = usbh_class_init(c_data, uhs_ctx);
+		if (ret != 0) {
+			LOG_WRN("Failed to initialize class %s (%d)", c_data->name, ret);
+			c_node->state = USBH_CLASS_STATE_ERROR;
+		}
+	}
+
+	usbh_host_unlock(uhs_ctx);
+}
+
+void usbh_class_remove_all(struct usb_device *const udev)
+{
+	int ret;
+
+	k_mutex_lock(&udev->mutex, K_FOREVER);
+
+	STRUCT_SECTION_FOREACH(usbh_class_node, c_node) {
+		struct usbh_class_data *const c_data = c_node->c_data;
+
+		if (c_data->udev == udev) {
+			ret = usbh_class_removed(c_data);
+			if (ret != 0) {
+				LOG_ERR("Failed to handle device removal for each class (%d)", ret);
+				c_node->state = USBH_CLASS_STATE_ERROR;
+				continue;
+			}
+
+			/* The class instance is now free to bind to a new device */
+			c_data->udev = NULL;
+			c_node->state = USBH_CLASS_STATE_IDLE;
+		}
+	}
+
+	k_mutex_unlock(&udev->mutex);
+}
+
+/*
+ * Probe an USB device function against all available classes of the system.
+ *
+ * Try to match a class from the global list of all system classes, using their filter rules
+ * and return status to tell if a class matches or not.
+ *
+ * The first matched class will stop the loop, and the status will be updated so that classes
+ * are only matched for a single USB function at a time.
+ *
+ * USB functions will only have one class matching, and calling usbh_class_probe_function()
+ * multiple times consequently has no effect.
+ */
+static void usbh_class_probe_function(struct usb_device *const udev,
+				      struct usbh_class_filter *const info, const uint8_t iface)
+{
+	int ret;
+
+	/* Assumes that udev->mutex is locked */
+
+	/* First check if any interface is already bound to this */
+	STRUCT_SECTION_FOREACH(usbh_class_node, c_node) {
+		struct usbh_class_data *const c_data = c_node->c_data;
+
+		if (c_node->state == USBH_CLASS_STATE_BOUND &&
+		    c_data->udev == udev && c_data->iface == iface) {
+			LOG_DBG("Interface %u bound to '%s', skipping", iface, c_data->name);
+			return;
+		}
+	}
+
+	/* Then try to match this function against all interfaces */
+	STRUCT_SECTION_FOREACH(usbh_class_node, c_node) {
+		struct usbh_class_data *const c_data = c_node->c_data;
+
+		if (c_node->state != USBH_CLASS_STATE_IDLE) {
+			LOG_DBG("Class %s already matched, skipping", c_data->name);
+			continue;
+		}
+
+		if (!usbh_class_is_matching(c_node->filters, info)) {
+			LOG_DBG("Class %s not matching interface %u", c_data->name, iface);
+			continue;
+		}
+
+		ret = usbh_class_probe(c_data, udev, iface);
+		if (ret == -ENOTSUP) {
+			LOG_DBG("Class %s not supporting this device, skipping", c_data->name);
+			continue;
+		}
+
+		LOG_INF("Class '%s' matches interface %u", c_data->name, iface);
+		c_node->state = USBH_CLASS_STATE_BOUND;
+		c_data->udev = udev;
+		c_data->iface = iface;
+		break;
+	}
+}
+
+void usbh_class_probe_device(struct usb_device *const udev)
+{
+	const void *desc_end;
+	const struct usb_desc_header *desc;
+	struct usbh_class_filter info;
+	uint8_t iface;
+	int ret;
+
+	k_mutex_lock(&udev->mutex, K_FOREVER);
+
+	desc = usbh_desc_get_cfg(udev);
+	desc_end = usbh_desc_get_cfg_end(udev);
+	info.vid = udev->dev_desc.idVendor;
+	info.pid = udev->dev_desc.idProduct;
+
+	while (true) {
+		desc = usbh_desc_get_next_function(desc, desc_end);
+		if (desc == NULL) {
+			break;
+		}
+
+		ret = usbh_desc_get_iface_info(desc, &info, &iface);
+		if (ret < 0) {
+			LOG_ERR("Failed to collect class codes for matching interface %u", iface);
+			continue;
+		}
+
+		usbh_class_probe_function(udev, &info, iface);
+	}
+
+	k_mutex_unlock(&udev->mutex);
+}
+
+bool usbh_class_is_matching(struct usbh_class_filter *const filters,
+			    struct usbh_class_filter *const info)
+{
+	/* Make empty filter set match everything (use class_api->probe() only) */
+	if (filters == NULL) {
+		return true;
+	}
+
+	/* Try to find a rule that matches completely */
+	for (size_t i = 0; filters[i].flags != 0; i++) {
+		const struct usbh_class_filter *filt = &filters[i];
+
+		if (filt->flags & USBH_CLASS_MATCH_VID_PID &&
+		    (info->vid != filt->vid || info->pid != filt->pid)) {
+			continue;
+		}
+
+		if (filt->flags & USBH_CLASS_MATCH_CODE_TRIPLE &&
+		    (info->class != filt->class || info->sub != filt->sub ||
+		     info->proto != filt->proto)) {
+			continue;
+		}
+
+		/* All the selected filters did match */
+		return true;
+	}
+
+	/* At the end of the filter table and still no match */
+	return false;
+}

subsys/usb/host/usbh_class.h

@@ -0,0 +1,59 @@
+/*
+ * Copyright (c) 2025 Nordic Semiconductor ASA
+ * Copyright 2025 NXP
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#ifndef ZEPHYR_INCLUDE_USBH_CLASS_H
+#define ZEPHYR_INCLUDE_USBH_CLASS_H
+
+#include <zephyr/usb/usbh.h>
+
+/** Match both the device's vendor ID and product ID */
+#define USBH_CLASS_MATCH_VID_PID BIT(1)
+
+/** Match a class/subclass/protocol code triple */
+#define USBH_CLASS_MATCH_CODE_TRIPLE BIT(2)
+
+/**
+ * @brief Match an USB host class (a driver) against a device descriptor.
+ *
+ * An empty filter set matches everything.
+ * This can be used to only rely on @c class_api->probe() return value.
+ *
+ * @param[in] filters Array of filter rules to match
+ * @param[in] device_info Device information filled by this function
+ *
+ * @retval true if the USB Device descriptor matches at least one rule.
+ */
+bool usbh_class_is_matching(struct usbh_class_filter *const filters,
+			    struct usbh_class_filter *const device_info);
+
+/**
+ * @brief Initialize every class instantiated on the system
+ *
+ * @param[in] uhs_ctx USB Host context to pass to the class.
+ */
+void usbh_class_init_all(struct usbh_context *const uhs_ctx);
+
+/**
+ * @brief Probe an USB device function against all available classes.
+ *
+ * Try to match a class from the global list of all system classes using their filter rules
+ * and return status to update the state of each matched class.
+ *
+ * The first matched class
+ *
+ * @param[in] udev USB device to probe.
+ */
+void usbh_class_probe_device(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.
+ */
+void usbh_class_remove_all(struct usb_device *const udev);
+
+#endif /* ZEPHYR_INCLUDE_USBH_CLASS_H */