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
  */
@@ -74,18 +75,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;
 
 /**
@@ -126,8 +115,8 @@ 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;
+	/** System linked list node for registered classes */
+	sys_snode_t node;
 	/** 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.c

@@ -64,13 +64,13 @@ bool usbh_class_is_matching(struct usbh_class_filter *const filters, size_t n_fi
 	for (int i = 0; i < n_filters; i++) {
 		const struct usbh_class_filter *filt = &filters[i];
 
-		if (filt->flags & USBH_CLASS_FILTER_VID) {
+		if (filt->flags & USBH_CLASS_MATCH_VID) {
 			if (desc->idVendor != filt->vid) {
 				continue;
 			}
 		}
 
-		if (filt->flags & USBH_CLASS_FILTER_PID) {
+		if (filt->flags & USBH_CLASS_MATCH_PID) {
 			if (desc->idProduct != filt->pid) {
 				continue;
 			}
@@ -83,7 +83,7 @@ bool usbh_class_is_matching(struct usbh_class_filter *const filters, size_t n_fi
 		}
 
 		if (filt->flags & USBH_CLASS_MATCH_SUB) {
-			if (desc->bDeviceSubclass != filt->sub) {
+			if (desc->bDeviceSubClass != filt->sub) {
 				continue;
 			}
 		}

subsys/usb/host/usbh_class.h

@@ -10,14 +10,63 @@
 
 #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;
+};
+
 /**
  * @brief Auto-register all compile-time defined class drivers
  */
-int usbh_register_all_classes(struct usbh_context *uhs_ctx);
+int usbh_register_all_classes(struct usbh_context *const uhs_ctx);
 
 /**
  * @brief Initialize registered class drivers
  */
-int usbh_init_registered_classes(struct usbh_context *uhs_ctx);
+int usbh_init_registered_classes(struct usbh_context *const uhs_ctx);
+
+/** 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 Check if information about a device matches the .
+ *
+ * @param filters Array of filters to match the class against.
+ * @param n_filters Number of filters in the array.
+ * @param desc Device descriptor with information to match against the filters.
+ *
+ * @return true if matched, false otherwise
+ */
+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,29 @@
+/*
+ * Copyright (c) 2025 Nordic Semiconductor ASA
+ * Copyright NXP
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include "usbh_desc.h"
+
+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;
+}

subsys/usb/host/usbh_desc.h

@@ -0,0 +1,35 @@
+/*
+ * 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 Search the first descriptor matching the selected type(s).
+ *
+ * @param[in] start_addr Pointer to the beginning of the descriptor array; to search
+ * @param[in] end_addr 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
+ */
+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);
+
+#endif /* ZEPHYR_INCLUDE_USBH_DESC_H */