refactor(enum): Curved out Enumeration process from Hub Driver

components/usb/private_include/enum.h

@@ -0,0 +1,159 @@
+/*
+ * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#pragma once
+
+#include <stdint.h>
+#include "sdkconfig.h"
+#include "esp_err.h"
+#include "hcd.h"
+#include "usbh.h"
+#include "usb/usb_types_stack.h"
+#include "usb/usb_types_ch9.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// ---------------------- Settings & Configuration -----------------------------
+#ifdef CONFIG_USB_HOST_ENABLE_ENUM_FILTER_CALLBACK
+#define ENABLE_ENUM_FILTER_CALLBACK                 1
+#endif // CONFIG_USB_HOST_ENABLE_ENUM_FILTER_CALLBACK
+
+// -------------------------- Public Types -------------------------------------
+
+// ---------------------------- Handles ----------------------------------------
+
+/**
+ * @brief Handle of enumeration control object
+ */
+typedef struct enum_ctx_handle_s * enum_ctx_handle_t;
+
+// ------------------------------ Events ---------------------------------------
+
+/**
+ * @brief Event data object for Enumerator driver events
+ */
+typedef enum {
+    ENUM_EVENT_STARTED,             /**< Enumeration of a device has started */
+    ENUM_EVENT_RESET_REQUIRED,      /**< Enumerating device requires a reset */
+    ENUM_EVENT_COMPLETED,           /**< Enumeration of a device has completed */
+    ENUM_EVENT_CANCELED,            /**< Enumeration of a device was canceled */
+} enum_event_t;
+
+typedef struct {
+    enum_event_t event;                         /**< Enumerator driver event */
+    union {
+        struct {
+            unsigned int uid;                   /**< Device unique ID */
+            usb_device_handle_t parent_dev_hdl; /**< Parent of the enumerating device */
+            uint8_t parent_port_num;            /**< Parent port number of the enumerating device */
+        } started;                              /**< ENUM_EVENT_STARTED specific data */
+
+        struct {
+            usb_device_handle_t parent_dev_hdl; /**< Parent of the enumerating device */
+            uint8_t parent_port_num;            /**< Parent port number of the enumerating device */
+        } reset_req;                            /**< ENUM_EVENT_RESET_REQUIRED specific data */
+
+        struct {
+            usb_device_handle_t parent_dev_hdl; /**< Parent of the enumerating device */
+            uint8_t parent_port_num;            /**< Parent port number of the enumerating device */
+            usb_device_handle_t dev_hdl;        /**< Handle of the enumerating device */
+            uint8_t dev_addr;                   /**< Address of the enumerating device */
+        } complete;                             /**< ENUM_EVENT_COMPLETED specific data */
+
+        struct {
+            usb_device_handle_t parent_dev_hdl; /**< Parent of the enumerating device */
+            uint8_t parent_port_num;            /**< Parent port number of the enumerating device */
+        } canceled;                             /**< ENUM_EVENT_CANCELED specific data */
+    };
+} enum_event_data_t;
+
+// ---------------------------- Callbacks --------------------------------------
+
+/**
+ * @brief Callback used to indicate that the Enumerator has an event
+ */
+typedef void (*enum_event_cb_t)(enum_event_data_t *event_data, void *arg);
+
+/**
+ * @brief Enum driver configuration
+ */
+typedef struct {
+    usb_proc_req_cb_t proc_req_cb;                  /**< Processing request callback */
+    void *proc_req_cb_arg;                          /**< Processing request callback argument */
+    enum_event_cb_t enum_event_cb;                  /**< Enum event callback */
+    void *enum_event_cb_arg;                        /**< Enum event callback argument */
+#if ENABLE_ENUM_FILTER_CALLBACK
+    usb_host_enum_filter_cb_t enum_filter_cb;       /**< Set device configuration callback */
+    void *enum_filter_cb_arg;                       /**< Set device configuration callback argument */
+#endif // ENABLE_ENUM_FILTER_CALLBACK
+} enum_config_t;
+
+/**
+ * @brief Install Enumerator driver
+ *
+ * Entry:
+ * - USBH must already be installed
+ * - HUB must already be installed
+ *
+ * @param[in]  enum_config Enumeration driver configuration
+ * @param[out] client_ret Unique pointer to identify Enum Driver as a USB Host client
+ * @return esp_err_t
+ */
+esp_err_t enum_install(enum_config_t *enum_config, void **client_ret);
+
+/**
+ * @brief Uninstall Enumerator driver
+ *
+ * This must be called before uninstalling the HUB and USBH
+ *
+ *  @return esp_err_t
+ */
+esp_err_t enum_uninstall(void);
+
+/**
+ * @brief Start the enumeration process
+ *
+ * This will start the enumeration process for the device currently at address 0
+ *
+ * @param[in] uid  Unique device ID
+ * @retval ESP_OK: Enumeration process started
+ * @retval ESP_ERR_NOT_FOUND: No device at address 0
+ */
+esp_err_t enum_start(unsigned int uid);
+
+/**
+ * @brief Continue enumeration process
+ *
+ * This will continue the enumeration process. Typically called after the successful
+ * handling of a request from the Enumerator driver (such as ENUM_EVENT_RESET_REQUIRED)
+ *
+ * @param[in] uid  Unique device ID
+ * @return esp_err_t
+ */
+esp_err_t enum_proceed(unsigned int uid);
+
+/**
+ * @brief Cancel the enumeration process
+ *
+ * This will cancel enumeration process for device object under enumeration
+ *
+ * @return esp_err_t
+ */
+esp_err_t enum_cancel(unsigned int uid);
+
+/**
+ * @brief Enumerator processing function
+ *
+ * Processing function that must be called repeatedly to process enumeration stages
+ *
+ * @return esp_err_t
+ */
+esp_err_t enum_process(void);
+
+#ifdef __cplusplus
+}
+#endif