Merge pull request #335 from espressif/feat/usb_host_exit_suspend_by_port_reset

feat(usb_host): Exit suspend state by port reset

Author: peter-marcisovsky

host/usb/src/hcd_dwc.c

@@ -1254,8 +1254,11 @@ static esp_err_t _port_cmd_reset(port_t *port)
 {
     esp_err_t ret;
 
-    // Port can only a reset when it is in the enabled or disabled (in the case of a new connection)states.
-    if (port->state != HCD_PORT_STATE_ENABLED && port->state != HCD_PORT_STATE_DISABLED) {
+    // Port can only be reset when it is in the enabled or disabled (in the case of a new connection) states, or
+    // in suspended state, to exit suspended state through host initiated reset
+    if (port->state != HCD_PORT_STATE_ENABLED &&
+            port->state != HCD_PORT_STATE_DISABLED &&
+            port->state != HCD_PORT_STATE_SUSPENDED) {
         ret = ESP_ERR_INVALID_STATE;
         goto exit;
     }

host/usb/test/target_test/common/hcd_common.c

@@ -46,6 +46,7 @@
 #define EVENT_QUEUE_LEN         5
 #define ENUM_ADDR               1   // Device address to use for tests that enumerate the device
 #define ENUM_CONFIG             1   // Device configuration number to use for tests that enumerate the device
+#define TRANSFER_MAX_BYTES      256
 
 typedef struct {
     hcd_port_handle_t port_hdl;
@@ -382,6 +383,8 @@ void test_hcd_free_urb(urb_t *urb)
     heap_caps_free(urb);
 }
 
+// --------------------------------------------------- Enumeration -----------------------------------------------------
+
 uint8_t test_hcd_enum_device(hcd_pipe_handle_t default_pipe)
 {
     // We need to create a URB for the enumeration control transfers
@@ -427,3 +430,25 @@ uint8_t test_hcd_enum_device(hcd_pipe_handle_t default_pipe)
     test_hcd_free_urb(urb);
     return ENUM_ADDR;
 }
+
+// ---------------------------------------------- Transfer submit ------------------------------------------------------
+
+void test_hcd_ping_device(hcd_pipe_handle_t default_pipe, urb_t *default_urb)
+{
+    default_urb->transfer.num_bytes = sizeof(usb_setup_packet_t) + TRANSFER_MAX_BYTES;
+    USB_SETUP_PACKET_INIT_GET_CONFIG_DESC((usb_setup_packet_t *)default_urb->transfer.data_buffer, 0, TRANSFER_MAX_BYTES);
+    default_urb->transfer.context = URB_CONTEXT_VAL;
+
+    TEST_ASSERT_EQUAL(ESP_OK, hcd_urb_enqueue(default_pipe, default_urb));
+    test_hcd_expect_pipe_event(default_pipe, HCD_PIPE_EVENT_URB_DONE);
+    urb_t *urb = hcd_urb_dequeue(default_pipe);
+    TEST_ASSERT_EQUAL_MESSAGE(default_urb, urb, "URB pointers not equal");
+    TEST_ASSERT_EQUAL_MESSAGE(USB_TRANSFER_STATUS_COMPLETED, urb->transfer.status, "Transfer NOT completed");
+    TEST_ASSERT_EQUAL_MESSAGE(URB_CONTEXT_VAL, urb->transfer.context, "URB context not equal");
+
+    // We must have transmitted at least the setup packet, but device may return less bytes than bytes requested
+    TEST_ASSERT_GREATER_OR_EQUAL(sizeof(usb_setup_packet_t), urb->transfer.actual_num_bytes);
+    TEST_ASSERT_LESS_OR_EQUAL(urb->transfer.num_bytes, urb->transfer.actual_num_bytes);
+    usb_config_desc_t *config_desc = (usb_config_desc_t *)(urb->transfer.data_buffer + sizeof(usb_setup_packet_t));
+    TEST_ASSERT_EQUAL(USB_B_DESCRIPTOR_TYPE_CONFIGURATION, config_desc->bDescriptorType);
+}

host/usb/test/target_test/common/hcd_common.h

@@ -191,10 +191,14 @@ void test_hcd_free_urb(urb_t *urb);
 uint8_t test_hcd_enum_device(hcd_pipe_handle_t default_pipe);
 
 /**
- * @brief Set endpoint descriptor
+ * @brief Ping device to check whether the device is responsive or not
  *
- * Set endpoint descriptor of the mock device with different wMaxPacketSize according to the connected device's speed
+ * Use this function to check whether it is possible to communicate with a device.
+ * For example after resuming a device, to check whether the device has been resumed correctly.
+ * The function sends a get configuration descriptor request to a device, checking both, the IN and OUT transfers
  *
- * @param port_speed Port speed after the device is connected
+ * @note this function sends a control transfer to the device
+ * @param default_pipe The connected device's default pipe
+ * @param default_urb A default_pipe's URB used for get configuration descriptor request
  */
-void test_hcd_set_mock_msc_ep_descriptor(usb_speed_t port_speed);
+void test_hcd_ping_device(hcd_pipe_handle_t default_pipe, urb_t *default_urb);

host/usb/test/target_test/hcd/main/test_hcd_port.c

@@ -146,10 +146,12 @@ Test port suspend and resume with active pipes
     - Trigger a port connection
     - Create a default pipe
     - Test that port can't be suspended with an active pipe
+    - Ping a device (send get configuration descriptor transfer)
     - Halt the default pipe after a short delay
     - Suspend the port
     - Resume the port
     - Check that all the pipe is still halted
+    - Ping a device
     - Cleanup default pipe
     - Trigger disconnection and teardown
 */
@@ -161,6 +163,9 @@ TEST_CASE("Test HCD port suspend and resume", "[port][low_speed][full_speed][hig
     // Allocate some URBs and initialize their data buffers with control transfers
     hcd_pipe_handle_t default_pipe = test_hcd_pipe_alloc(port_hdl, NULL, TEST_DEV_ADDR, port_speed); // Create a default pipe (using a NULL EP descriptor)
 
+    urb_t *urb = test_hcd_alloc_urb(0, URB_DATA_BUFF_SIZE);
+    test_hcd_ping_device(default_pipe, urb);
+
     // Test that suspending the port now fails as there is an active pipe
     TEST_ASSERT_EQUAL(ESP_ERR_INVALID_STATE, hcd_port_command(port_hdl, HCD_PORT_CMD_SUSPEND));
 
@@ -185,6 +190,8 @@ TEST_CASE("Test HCD port suspend and resume", "[port][low_speed][full_speed][hig
     TEST_ASSERT_EQUAL(HCD_PIPE_STATE_ACTIVE, hcd_pipe_get_state(default_pipe));
     vTaskDelay(pdMS_TO_TICKS(100)); // Give some time for resumed URBs to complete
 
+    test_hcd_ping_device(default_pipe, urb);
+    test_hcd_free_urb(urb);
     test_hcd_pipe_free(default_pipe);
     // Cleanup
     test_hcd_wait_for_disconn(port_hdl, false);
@@ -197,17 +204,22 @@ Test port suspend and resume sudden disconnect
     - Test port suspend and resume procedure with sudden disconnect
     - When suspended, the port must react to power off command by disconnecting a device
     - When no device is connected, the port must NOT allow to enter and exit the suspended state
+    - Test exiting suspend state through device disconnect
 
 Procedure:
     - Setup the HCD and a port
     - Trigger a port connection
     - Create a default pipe
+    - Ping a device (send get configuration descriptor transfer)
     - Halt the default pipe after a short delay
     - Suspend the port
     - Cleanup default pipe
     - Power off the port and recover the port
     - Try to Suspend and Resume the port with no devices connected
     - Trigger connection and disconnection again (to make sure the port works post recovery)
+    - Trigger connection again (to make sure the port works post recovery)
+    - Ping a device
+    - Trigger disconnection and cleanup
     - Teardown port and HCD
 */
 TEST_CASE("Test HCD port suspend and resume sudden disconnect", "[port][low_speed][full_speed][high_speed]")
@@ -218,8 +230,8 @@ TEST_CASE("Test HCD port suspend and resume sudden disconnect", "[port][low_spee
     // Allocate some URBs and initialize their data buffers with control transfers
     hcd_pipe_handle_t default_pipe = test_hcd_pipe_alloc(port_hdl, NULL, TEST_DEV_ADDR, port_speed); // Create a default pipe (using a NULL EP descriptor)
 
-    // Test that suspending the port now fails as there is an active pipe
-    TEST_ASSERT_EQUAL(ESP_ERR_INVALID_STATE, hcd_port_command(port_hdl, HCD_PORT_CMD_SUSPEND));
+    urb_t *urb = test_hcd_alloc_urb(0, URB_DATA_BUFF_SIZE);
+    test_hcd_ping_device(default_pipe, urb);
 
     // Halt the default pipe before suspending
     TEST_ASSERT_EQUAL(HCD_PIPE_STATE_ACTIVE, hcd_pipe_get_state(default_pipe));
@@ -240,7 +252,8 @@ TEST_CASE("Test HCD port suspend and resume sudden disconnect", "[port][low_spee
     TEST_ASSERT_EQUAL(HCD_PORT_STATE_RECOVERY, hcd_port_get_state(port_hdl));
     printf("Sudden disconnect\n");
 
-    // Free the pipe, to be able to recover the port
+    // Free the pipe and its urb, to be able to recover the port
+    test_hcd_free_urb(urb);
     test_hcd_pipe_free(default_pipe);
     // Recover the port should return to the NOT POWERED state
     TEST_ASSERT_EQUAL(ESP_OK, hcd_port_recover(port_hdl));
@@ -250,8 +263,76 @@ TEST_CASE("Test HCD port suspend and resume sudden disconnect", "[port][low_spee
     TEST_ASSERT_EQUAL(ESP_ERR_INVALID_STATE, hcd_port_command(port_hdl, HCD_PORT_CMD_SUSPEND));
     TEST_ASSERT_EQUAL(ESP_ERR_INVALID_STATE, hcd_port_command(port_hdl, HCD_PORT_CMD_RESUME));
 
-    // Recovered port should be able to connect and disconnect again
-    test_hcd_wait_for_conn(port_hdl);
+    // Recovered port should be able to connect again
+    port_speed = test_hcd_wait_for_conn(port_hdl);
+    vTaskDelay(pdMS_TO_TICKS(100)); // Short delay send of SOF (for FS, HS) or EOPs (for LS)
+
+    // Allocate some URBs and initialize their data buffers with control transfers
+    default_pipe = test_hcd_pipe_alloc(port_hdl, NULL, TEST_DEV_ADDR, port_speed); // Create a default pipe (using a NULL EP descriptor)
+    urb = test_hcd_alloc_urb(0, URB_DATA_BUFF_SIZE);
+    test_hcd_ping_device(default_pipe, urb);
+
+    test_hcd_free_urb(urb);
+    test_hcd_pipe_free(default_pipe);
+    test_hcd_wait_for_disconn(port_hdl, false);
+}
+
+/*
+Test port suspend and resume with port reset
+
+Purpose:
+    - Test port suspend and resume procedure with port reset
+    - When suspended, the port must react to reset command
+    - Test exiting suspend state through port reset
+
+Procedure:
+    - Setup the HCD and a port
+    - Trigger a port connection
+    - Create a default pipe
+    - Ping a device (send get configuration descriptor transfer)
+    - Halt the default pipe
+    - Suspend the port
+    - Reset and recover the port
+    - Ping a device
+    - Trigger disconnection and cleanup
+    - Teardown port and HCD
+*/
+TEST_CASE("Test HCD port suspend and resume port reset", "[port][low_speed][full_speed][high_speed]")
+{
+    usb_speed_t port_speed = test_hcd_wait_for_conn(port_hdl);  // Trigger a connection
+    vTaskDelay(pdMS_TO_TICKS(100)); // Short delay send of SOF (for FS, HS) or EOPs (for LS)
+
+    // Allocate some URBs and initialize their data buffers with control transfers
+    hcd_pipe_handle_t default_pipe = test_hcd_pipe_alloc(port_hdl, NULL, TEST_DEV_ADDR, port_speed); // Create a default pipe (using a NULL EP descriptor)
+    urb_t *urb = test_hcd_alloc_urb(0, URB_DATA_BUFF_SIZE);
+    test_hcd_ping_device(default_pipe, urb);
+
+    // Halt the default pipe before suspending
+    TEST_ASSERT_EQUAL(HCD_PIPE_STATE_ACTIVE, hcd_pipe_get_state(default_pipe));
+    TEST_ASSERT_EQUAL(ESP_OK, hcd_pipe_command(default_pipe, HCD_PIPE_CMD_HALT));
+    TEST_ASSERT_EQUAL(HCD_PIPE_STATE_HALTED, hcd_pipe_get_state(default_pipe));
+
+    // Suspend the port
+    TEST_ASSERT_EQUAL(ESP_OK, hcd_port_command(port_hdl, HCD_PORT_CMD_SUSPEND));
+    TEST_ASSERT_EQUAL(HCD_PORT_STATE_SUSPENDED, hcd_port_get_state(port_hdl));
+    printf("Suspended\n");
+    vTaskDelay(pdMS_TO_TICKS(100)); // Give some time for bus to remain suspended
+
+    // Reset the port
+    TEST_ASSERT_EQUAL(ESP_OK, hcd_port_command(port_hdl, HCD_PORT_CMD_RESET));
+    printf("Port reset\n");
+
+    // Port should be in enabled state, and the default pipe still halted
+    TEST_ASSERT_EQUAL(HCD_PORT_STATE_ENABLED, hcd_port_get_state(port_hdl));
+    TEST_ASSERT_EQUAL(HCD_PIPE_STATE_HALTED, hcd_pipe_get_state(default_pipe));
+    // Clear the pipe
+    TEST_ASSERT_EQUAL(ESP_OK, hcd_pipe_command(default_pipe, HCD_PIPE_CMD_CLEAR));
+    TEST_ASSERT_EQUAL(HCD_PIPE_STATE_ACTIVE, hcd_pipe_get_state(default_pipe));
+
+    test_hcd_ping_device(default_pipe, urb);
+
+    test_hcd_free_urb(urb);
+    test_hcd_pipe_free(default_pipe);
     test_hcd_wait_for_disconn(port_hdl, false);
 }