usb: host: implement class filtering and descriptor browsing

Add utilities to filter a class and search the next descriptor of
a given type. This can be used to in combination to seek device
information from the USB descriptors and try to match a host class
instance given a set of filters.

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
  */
@@ -72,18 +73,6 @@ struct usbh_context {
 		.addr_ba = &ba_##device_name,				\
 	}
 
-/**
- * @brief USB Class Code triple
- */
-struct usbh_code_triple {
-	/** Device Class Code */
-	uint8_t dclass;
-	/** Class Subclass Code */
-	uint8_t sub;
-	/** Class Protocol Code */
-	uint8_t proto;
-};
-
 struct usbh_class_data;
 
 /**
@@ -120,8 +109,6 @@ struct usbh_class_data {
 	const char *name;
 	/** Pointer to USB host stack context structure */
 	struct usbh_context *uhs_ctx;
-	/** Class code supported by this instance */
-	struct usbh_code_triple code;
 	/** Pointer to host support class API */
 	struct usbh_class_api *api;
 	/** Pointer to private data */

subsys/usb/host/CMakeLists.txt

@@ -9,6 +9,7 @@ zephyr_library_sources(
 	usbh_ch9.c
 	usbh_class.c
 	usbh_core.c
+	usbh_desc.c
 	usbh_device.c
 )
 

subsys/usb/host/usbh_class.h

@@ -0,0 +1,61 @@
+/*
+ * 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 Information about a device, which is relevant for matching a particular class.
+ */
+struct usbh_class_filter {
+	/** Vendor ID */
+	uint16_t vid;
+	/** Product ID */
+	uint16_t pid;
+	/** Device Class Code */
+	uint8_t dclass;
+	/** Class Subclass Code */
+	uint8_t sub;
+	/** Class Protocol Code */
+	uint8_t proto;
+	/** Flags that tell which field to match */
+	uint8_t flags;
+};
+
+/** 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_DCLASS BIT(3)
+
+/** Match a subclass code */
+#define USBH_CLASS_MATCH_SUB BIT(4)
+
+/** Match a protocol code */
+#define USBH_CLASS_MATCH_PROTO BIT(5)
+
+/** Match a code triple */
+#define USBH_CLASS_MATCH_CODE_TRIPLE \
+	(USBH_CLASS_MATCH_DCLASS | USBH_CLASS_MATCH_SUB | USBH_CLASS_MATCH_PROTO)
+
+/**
+ * @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);
+
+#endif /* ZEPHYR_INCLUDE_USBD_CLASS_H */

subsys/usb/host/usbh_desc.c

@@ -0,0 +1,73 @@
+/*
+ * Copyright (c) 2025 Nordic Semiconductor ASA
+ * Copyright NXP
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <zephyr/usb/usb_ch9.h>
+#include "usbh_desc.h"
+
+const struct usb_desc_header *usbh_desc_get_next(const struct usb_desc_header *const desc,
+						 const void *const desc_end)
+{
+	const struct usb_desc_header *next;
+
+	if (desc == NULL) {
+		return NULL;
+	}
+
+	next = (const struct usb_desc_header *)((uint8_t *)desc + desc->bLength);
+
+	/* Validate the bLength field to make sure it does not point past the end */
+	if ((uint8_t *)next >= (uint8_t *)desc_end ||
+	    (uint8_t *)next + next->bLength > (uint8_t *)desc_end ||
+	    desc->bLength == 0) {
+		return NULL;
+	}
+
+	return next;
+}
+
+const struct usb_desc_header *usbh_desc_get_by_type(const void *const desc_beg,
+						    const void *const desc_end,
+						    uint32_t type_mask)
+{
+	const struct usb_desc_header *desc;
+
+	if (desc_beg == NULL) {
+		return NULL;
+	}
+
+	for (desc = desc_beg; desc != NULL; desc = usbh_desc_get_next(desc, desc_end)) {
+		if ((BIT(desc->bDescriptorType) & type_mask) != 0) {
+			return desc;
+		}
+	}
+
+	return NULL;
+}
+
+const struct usb_desc_header *usbh_desc_get_by_ifnum(const void *const desc_beg,
+						     const void *const desc_end,
+						     const uint8_t ifnum)
+{
+	const struct usb_desc_header *desc;
+
+	if (desc_beg == NULL) {
+		return NULL;
+	}
+
+	for (desc = desc_beg; desc != NULL; desc = usbh_desc_get_next(desc, desc_end)) {
+		if (desc->bDescriptorType == USB_DESC_INTERFACE &&
+		    ((struct usb_if_descriptor *)desc)->bInterfaceNumber == ifnum) {
+			return desc;
+		}
+		if (desc->bDescriptorType == USB_DESC_INTERFACE_ASSOC &&
+		    ((struct usb_association_descriptor *)desc)->bFirstInterface == ifnum) {
+			return desc;
+		}
+	}
+
+	return NULL;
+}

subsys/usb/host/usbh_desc.h

@@ -0,0 +1,76 @@
+/*
+ * Copyright (c) 2025 Nordic Semiconductor ASA
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @file
+ * @brief Descriptor matching and searching utilities
+ *
+ * This file contains utilities to browse USB descriptors returned by a device
+ * according to the USB Specification 2.0 Chapter 9.
+ */
+
+#ifndef ZEPHYR_INCLUDE_USBH_DESC_H
+#define ZEPHYR_INCLUDE_USBH_DESC_H
+
+#include <stdint.h>
+
+#include <zephyr/usb/usbh.h>
+
+/**
+ * @brief Get the next descriptor in an array of descriptors.
+ *
+ * This
+ * to search either an interface or  interface association descriptor:
+ *
+ * @code{.c}
+ * BIT(USB_DESC_INTERFACE) | BIT(USB_DESC_INTERFACE_ASSOC)
+ * @endcode
+ *
+ * @param[in] desc_beg Pointer to the beginning of the descriptor array; to search. May be NULL.
+ * @param[in] desc_end Pointer after the end of the descriptor array to search
+ * @param[in] type_mask Bitmask of bDescriptorType values to match
+ * @return A pointer to the first descriptor matching
+ */
+const struct usb_desc_header *usbh_desc_get_next(const struct usb_desc_header *const desc,
+						 const void *const desc_end);
+
+/**
+ * @brief Search the first descriptor matching the selected type(s).
+ *
+ * As an example, the @p type_mask argument can be constructed this way
+ * to search either an interface or  interface association descriptor:
+ *
+ * @code{.c}
+ * BIT(USB_DESC_INTERFACE) | BIT(USB_DESC_INTERFACE_ASSOC)
+ * @endcode
+ *
+ * @param[in] desc_beg Pointer to the beginning of the descriptor array; to search. May be NULL.
+ * @param[in] desc_end Pointer after the end of the descriptor array to search
+ * @param[in] type_mask Bitmask of bDescriptorType values to match
+ * @return A pointer to the first descriptor matching
+ */
+const struct usb_desc_header *usbh_desc_get_by_type(const void *const desc_beg,
+						    const void *const desc_end,
+						    uint32_t type_mask);
+
+/**
+ * @brief Search the first descriptor with the interace number wanted.
+ *
+ * The descriptors are going to be scanned until either an interface association
+ * @c bFirstInterface field or an interface @c bInterfaceNumber field match.
+ *
+ * The descriptors following it can be browsed using @ref usbh_desc_get_next
+ *
+ * @param[in] desc_beg Pointer to the beginning of the descriptor array; to search. May be NULL.
+ * @param[in] desc_end Pointer after the end of the descriptor array to search
+ * @param[in] ifnum The interface number to search
+ * @return A pointer to the first descriptor matching
+ */
+const struct usb_desc_header *usbh_desc_get_by_ifnum(const void *const desc_beg,
+						     const void *const desc_end,
+						     const uint8_t ifnum);
+
+#endif /* ZEPHYR_INCLUDE_USBH_DESC_H */