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;
 
 /**
@@ -124,8 +113,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,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 */