feat(usb_host): Remote wakeup

    - HCD and USB Host tests

Author: peter-marcisovsky

.github/workflows/build_idf_examples.yml

@@ -16,7 +16,7 @@ name: Build ESP-IDF USB examples
 
 on:
   pull_request:
-    types: [opened, reopened, synchronize]
+    types: [opened, reopened]
 
 jobs:
   build:

host/usb/include/usb/usb_host.h

@@ -548,6 +548,50 @@ esp_err_t usb_host_get_config_desc(usb_host_client_handle_t client_hdl, usb_devi
  */
 esp_err_t usb_host_free_config_desc(const usb_config_desc_t *config_desc);
 
+/**
+ * @brief Set remote wakeup feature on a device
+ *
+ * This function enables, or disables remote wakeup feature on a connected device. Device must support remote wakeup
+ * at fist place
+ *
+ * @note A control transfer is sent to a device, to enable/disable the feature
+ * @note A client must open the device first
+ *
+ * @param[in] client_hdl Handle of a client, that opened the device
+ * @param[in] dev_hdl Handle of a device, on which the remote wakeup is about to be enabled/disabled
+ * @param[in] enable Remote wakeup enable/disable
+ *
+ * @return
+ *    - ESP_OK: Remote wakeup set successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_INVALID_STATE: Client did not open the device
+ *    - ESP_ERR_NOT_ALLOWED: Device does not support remote wakeup
+ *    - ESP_ERR_NO_MEM: Not enough memory
+ */
+esp_err_t usb_host_device_remote_wakeup_enable(usb_host_client_handle_t client_hdl, usb_device_handle_t dev_hdl, bool enable);
+
+/**
+ * @brief Check if a remote wakeup is currently set
+ *
+ * This function checks if a remote wakeup feature is currently enabled or disabled on a connected device. Device must
+ * support remote wakeup at fist place
+ *
+ * @note A control transfer is sent to a device, get a device status descriptor
+ * @note A client must open the device first
+ *
+ * @param[in] client_hdl Handle of a client, that opened the device
+ * @param[in] dev_hdl Handle of a device, on which the remote wakeup is about to be checked
+ * @param[out] enabled Remote wakeup is currently enabled/disabled
+ *
+ * @return
+ *    - ESP_OK: Remote wakeup status checked successfully
+ *    - ESP_ERR_INVALID_ARG: Invalid argument
+ *    - ESP_ERR_INVALID_STATE: Client did not open the device
+ *    - ESP_ERR_NOT_ALLOWED: Device does not support remote wakeup
+ *    - ESP_ERR_NO_MEM: Not enough memory
+ */
+esp_err_t usb_host_device_remote_wakeup_check(usb_host_client_handle_t client_hdl, usb_device_handle_t dev_hdl, bool *enabled);
+
 // ----------------------------------------------- Interface Functions -------------------------------------------------
 
 /**

host/usb/include/usb/usb_types_ch9.h

@@ -153,10 +153,19 @@ ESP_STATIC_ASSERT(sizeof(usb_device_status_t) == sizeof(uint16_t), "Size of usb_
 #define USB_W_VALUE_DT_OTHER_SPEED_CONFIG   0x07
 #define USB_W_VALUE_DT_INTERFACE_POWER      0x08
 
+/**
+ * @brief Feature selector bit masks belonging to the wValue field of a setup packet
+ *
+ * See Table 9-6 of USB2.0 specification for more details
+ */
+#define ENDPOINT_HALT                       0x00
+#define DEVICE_REMOTE_WAKEUP                0x01
+#define TEST_MODE                           0x02
+
 /**
  * @brief Initializer for a GET_STATUS request
  *
- * Sets the address of a connected device
+ * Gets the status of a connected device
  */
 #define USB_SETUP_PACKET_INIT_GET_STATUS(setup_pkt_ptr) ({  \
     (setup_pkt_ptr)->bmRequestType = USB_BM_REQUEST_TYPE_DIR_IN | USB_BM_REQUEST_TYPE_TYPE_STANDARD | USB_BM_REQUEST_TYPE_RECIP_DEVICE;   \
@@ -166,6 +175,36 @@ ESP_STATIC_ASSERT(sizeof(usb_device_status_t) == sizeof(uint16_t), "Size of usb_
     (setup_pkt_ptr)->wLength = 2;   \
 })
 
+/**
+ * @brief Initializer for a CLEAR_FEATURE request
+ *
+ * Clears the feature of a connected device
+ *
+ * See Chapter 9.4.1 of USB2.0 specification for more details
+ */
+#define USB_SETUP_PACKET_INIT_CLEAR_FEATURE(setup_pkt_ptr, feature_to_clear) ({  \
+    (setup_pkt_ptr)->bmRequestType = USB_BM_REQUEST_TYPE_DIR_OUT | USB_BM_REQUEST_TYPE_TYPE_STANDARD | USB_BM_REQUEST_TYPE_RECIP_DEVICE;   \
+    (setup_pkt_ptr)->bRequest = USB_B_REQUEST_CLEAR_FEATURE;  \
+    (setup_pkt_ptr)->wValue = feature_to_clear;   \
+    (setup_pkt_ptr)->wIndex = 0;    \
+    (setup_pkt_ptr)->wLength = 0;   \
+})
+
+/**
+ * @brief Initializer for a SET_FEATURE request
+ *
+ * Sets the feature of a connected device
+ *
+ * See Chapter 9.4.9 of USB2.0 specification for more details
+ */
+#define USB_SETUP_PACKET_INIT_SET_FEATURE(setup_pkt_ptr, feature_to_set) ({  \
+    (setup_pkt_ptr)->bmRequestType = USB_BM_REQUEST_TYPE_DIR_OUT | USB_BM_REQUEST_TYPE_TYPE_STANDARD | USB_BM_REQUEST_TYPE_RECIP_DEVICE;   \
+    (setup_pkt_ptr)->bRequest = USB_B_REQUEST_SET_FEATURE;  \
+    (setup_pkt_ptr)->wValue = feature_to_set;   \
+    (setup_pkt_ptr)->wIndex = 0;    \
+    (setup_pkt_ptr)->wLength = 0;   \
+})
+
 /**
  * @brief Initializer for a SET_ADDRESS request
  *

host/usb/private_include/hcd.h

@@ -69,6 +69,7 @@ typedef enum {
     HCD_PORT_EVENT_DISCONNECTION,   /**< A device disconnection has been detected */
     HCD_PORT_EVENT_ERROR,           /**< A port error has been detected. Port is now HCD_PORT_STATE_RECOVERY  */
     HCD_PORT_EVENT_OVERCURRENT,     /**< Overcurrent detected on the port. Port is now HCD_PORT_STATE_RECOVERY */
+    HCD_PORT_EVENT_REMOTE_WAKEUP,   /**< A remote-wakeup event from device has been detected */
 } hcd_port_event_t;
 
 /**

host/usb/src/hcd_dwc.c

@@ -831,6 +831,11 @@ static hcd_port_event_t _intr_hdlr_hprt(port_t *port, usb_dwc_hal_port_event_t h
         port->flags.conn_dev_ena = 0;
         break;
     }
+    case USB_DWC_HAL_PORT_EVENT_REMOTE_WAKEUP: {
+        esp_rom_printf("WAKE\n");
+        port_event = HCD_PORT_EVENT_REMOTE_WAKEUP;
+        break;
+    }
     default: {
         abort();
         break;
@@ -1217,6 +1222,34 @@ static inline bool _is_fifo_config_by_bias(const usb_dwc_hal_fifo_config_t *cfg)
             cfg->ptx_fifo_lines == 0);
 }
 
+/**
+ * @brief Gate internal clock
+ *
+ * @param[in] port Pointer to the port object
+ * @param[in] enable enable/disable internal clock gating
+ * @return True internal clk successfully gated/un-gated
+ * @return False internal clk not gated/un-gated
+ */
+static inline bool _internal_clk_gate(port_t *port, bool enable)
+{
+    // Stop PHY Clock and gate HCLK
+    usb_dwc_hal_pwr_clk_internal_clock_gate(port->hal, enable);
+
+    // Wait 10 PHY clock cycles, PHY Clock is 30MHz when using 16bit interface, 60MHz when 8bit interface
+    // which makes 33.3 nS. Busy wait for 1uS just to be sure
+    esp_rom_delay_us(1);
+
+    const bool phy_clk_stopped = usb_dwc_hal_pwr_clk_check_phy_clk_stopped(port->hal);
+    const bool hclk_gated = usb_dwc_hal_pwr_clk_check_hclk_gated(port->hal);
+
+    // enable == phy_clk_stopped == hclk_gated
+    // When gating the clock, all 3 variables must be 1. When un-gating, all 3 must be 0.
+    if ((enable == phy_clk_stopped) && (enable == hclk_gated)) {
+        return true;
+    }
+    return false;
+}
+
 // ---------------------- Commands -------------------------
 
 static esp_err_t _port_cmd_power_on(port_t *port)
@@ -1225,6 +1258,7 @@ static esp_err_t _port_cmd_power_on(port_t *port)
     // Port can only be powered on if it's currently unpowered
     if (port->state == HCD_PORT_STATE_NOT_POWERED) {
         port->state = HCD_PORT_STATE_DISCONNECTED;
+        //assert(_internal_clk_gate(port, false));           // Un-gate the phy clock                  TODO: Test this
         usb_dwc_hal_port_init(port->hal);
         usb_dwc_hal_port_toggle_power(port->hal, true);
         ret = ESP_OK;
@@ -1239,7 +1273,13 @@ static esp_err_t _port_cmd_power_off(port_t *port)
     esp_err_t ret;
     // Port can only be unpowered if already powered
     if (port->state != HCD_PORT_STATE_NOT_POWERED) {
+
+        if (port->state == HCD_PORT_STATE_SUSPENDED) {
+            // un-gate internal clock, to be able to toggle power on the port
+            assert(_internal_clk_gate(port, false));            // Un-gate the phy clock
+        }
         port->state = HCD_PORT_STATE_NOT_POWERED;
+        //assert(_internal_clk_gate(port, false));            // Gate the phy clock                  TODO: Test this
         usb_dwc_hal_port_deinit(port->hal);
         usb_dwc_hal_port_toggle_power(port->hal, false);
         // If a device is currently connected, this should trigger a disconnect event
@@ -1267,6 +1307,10 @@ static esp_err_t _port_cmd_reset(port_t *port)
         ret = ESP_ERR_INVALID_STATE;
         goto exit;
     }
+    // If resetting from suspended state, we must un-gate the internal clock
+    if (port->state == HCD_PORT_STATE_SUSPENDED) {
+        _internal_clk_gate(port, false);
+    }
     /*
     Proceed to resetting the bus
     - Update the port's state variable
@@ -1323,6 +1367,21 @@ static esp_err_t _port_cmd_reset(port_t *port)
     return ret;
 }
 
+/**
+ * @brief Suspend the root port
+ *
+ * This sequence equals to a sequence from the DesignWare Cores USB 2.0 Programming Guide version 4.00a
+ * 14.2.3.3 External HCLK Gating When the Host Core is in Partial Power Down Mode
+ * Sequence Entering suspend state
+ *
+ * @param[in] port Pointer to the port object
+ * @return:
+ *    - ESP_ERR_INVALID_STATE Port is not in a correct state to be suspended, or pipe(s) routed through this port is not halted
+ *    - ESP_ERR_INVALID_RESPONSE Port state unexpectedly changed (for example: device was disconnected)
+ *    - ESP_ERR_NOT_FINISHED Port did not finish the suspending sequence and is not in the suspended state
+ *    - ESP_ERR_NOT_ALLOWED PHY clk was not suspended
+ *    - ESP_OK Root port suspended
+ */
 static esp_err_t _port_cmd_bus_suspend(port_t *port)
 {
     esp_err_t ret;
@@ -1356,13 +1415,34 @@ static esp_err_t _port_cmd_bus_suspend(port_t *port)
         goto exit;
     }
 
+    if (! _internal_clk_gate(port, true)) {
+        ret = ESP_ERR_NOT_ALLOWED;
+        goto exit;
+    }
+
     port->state = HCD_PORT_STATE_SUSPENDED;
     ret = ESP_OK;
 
 exit:
     return ret;
 }
 
+/**
+ * @brief Resume the root port
+ *
+ * This sequence equals to a sequence from the DesignWare Cores USB 2.0 Programming Guide version 4.00a
+ * 14.2.3.3 External HCLK Gating When the Host Core is in Partial Power Down Mode
+ * Sequence Exiting Suspend State Through Host Initiated Resume
+ *          Exiting Suspend State Through Device Initiated Remote Wakeup
+ *
+ * @note this sequence is used for both resume scenarios: the host initiated and the device initiated (remote wakeup) resume
+ * @param[in] port Pointer to the port object
+ * @return:
+ *    - ESP_ERR_INVALID_STATE Port is not in a correct state to be resumed
+ *    - ESP_ERR_NOT_ALLOWED PHY clk was not resumed
+ *    - ESP_ERR_INVALID_RESPONSE Port state unexpectedly changed (for example: device was disconnected)
+ *    - ESP_OK Root port resumed
+ */
 static esp_err_t _port_cmd_bus_resume(port_t *port)
 {
     esp_err_t ret;
@@ -1371,6 +1451,12 @@ static esp_err_t _port_cmd_bus_resume(port_t *port)
         ret = ESP_ERR_INVALID_STATE;
         goto exit;
     }
+
+    if (!_internal_clk_gate(port, false)) {
+        ret = ESP_ERR_NOT_ALLOWED;
+        goto exit;
+    }
+
     // Put and hold the bus in the K state.
     usb_dwc_hal_port_toggle_resume(port->hal, true);
     port->state = HCD_PORT_STATE_RESUMING;
@@ -1596,6 +1682,7 @@ esp_err_t hcd_port_recover(hcd_port_handle_t port_hdl)
                         ESP_ERR_INVALID_STATE);
 
     // We are about to do a soft reset on the peripheral. Disable the peripheral throughout
+    //assert(_internal_clk_gate(port, false));           // Gate the phy clock
     esp_intr_disable(port->isr_hdl);
     usb_dwc_hal_core_soft_reset(port->hal);
     port->state = HCD_PORT_STATE_NOT_POWERED;
@@ -1605,6 +1692,7 @@ esp_err_t hcd_port_recover(hcd_port_handle_t port_hdl)
     // Clear the frame list. We set the frame list register and enable periodic scheduling after a successful reset
     memset(port->frame_list, 0, FRAME_LIST_LEN * sizeof(uint32_t));
     esp_intr_enable(port->isr_hdl);
+    //assert(_internal_clk_gate(port, true));           // Gate the phy clock
     HCD_EXIT_CRITICAL();
     return ESP_OK;
 }

host/usb/src/hub.c

@@ -455,6 +455,10 @@ static void root_port_handle_events(hcd_port_handle_t root_port_hdl)
 
         break;
     }
+    case HCD_PORT_EVENT_REMOTE_WAKEUP:
+        // Mark root port as ready to be resumed
+        hub_root_mark_resume();
+        break;
     default:
         abort();    // Should never occur
         break;