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
  */
@@ -111,6 +112,29 @@ struct usbh_class_api {
 	int (*resumed)(struct usbh_class_data *cdata);
 };
 
+/** Match a class code triple */
+#define USBH_CLASS_FILTER_CODE_TRIPLE BIT(0)
+
+/** Match a device's vendor ID */
+#define USBH_CLASS_FILTER_VID BIT(1)
+
+/** Match a device's product ID */
+#define USBH_CLASS_FILTER_PID BIT(2)
+
+/**
+ * @brief Filter rule for matching a host class instance to a device class
+ */
+struct usbh_class_filter {
+	/** Mask of match types for selecting which rules to apply */
+	uint32_t flags;
+	/** The device's class code, subclass code, protocol code. */
+	struct usbh_code_triple code_triple;
+	/** Vendor ID */
+	uint16_t vid;
+	/** Product ID */
+	uint16_t pid;
+};
+
 /**
  * @brief USB host class instance data
  */
@@ -121,8 +145,8 @@ struct usbh_class_data {
 	struct usbh_context *uhs_ctx;
 	/** System linked list node for registered classes */
 	sys_snode_t node;
-	/** Class code supported by this instance */
-	struct usbh_code_triple code;
+	/** Table of filter rules used to match device classes */
+	const struct usbh_class_filter *filters;
 	/** 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

@@ -57,3 +57,39 @@ int usbh_init_registered_classes(struct usbh_context *uhs_ctx)
 
 	return 0;
 }
+
+bool usbh_class_is_matching(struct usbh_class_data *cdata,
+			    struct usbh_class_filter *device_info)
+{
+	/* Traverse the filter table until a terminator (empty flags) is found */
+	for (int i = 0; cdata->filters[i].flags != 0; i++) {
+		const struct usbh_class_filter *filter = &cdata->filters[i];
+
+		if (filter->flags & USBH_CLASS_FILTER_VID) {
+			if (filter->vid != device_info->vid) {
+				continue;
+			}
+		}
+
+		if (filter->flags & USBH_CLASS_FILTER_VID) {
+			if (filter->vid == device_info->vid) {
+				continue;
+			}
+		}
+
+		if (filter->flags & USBH_CLASS_FILTER_CODE_TRIPLE) {
+			if (filter->code_triple.dclass != device_info->code_triple.dclass ||
+			    (filter->code_triple.sub != 0xFF &&
+			     filter->code_triple.sub != device_info->code_triple.sub) ||
+			    (filter->code_triple.proto != 0x00 &&
+			     filter->code_triple.proto != device_info->code_triple.proto)) {
+				continue;
+			}
+		}
+
+		/* All the filters enabled did match */
+		return true;
+	}
+
+	return false;
+}

subsys/usb/host/usbh_class.h

@@ -20,4 +20,15 @@ int usbh_register_all_classes(struct usbh_context *uhs_ctx);
  */
 int usbh_init_registered_classes(struct usbh_context *uhs_ctx);
 
+/**
+ * @brief Check if a device's descriptor information matches a host class instance
+ *
+ * @param cdata Pointer to class driver data
+ * @param device_info Information from the device descriptors
+ *
+ * @return true if matched, false otherwise
+ */
+bool usbh_class_is_matching(struct usbh_class_data *cdata,
+			    struct usbh_class_filter *device_info);
+
 #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 */