fix(usbh_cdc/ecm): fix data pipe stalls for CDC-ECM on SW reboot and alt-setting switch

Three related fixes for CDC-ECM bulk data pipe reliability:

1. in_xfer_cb: handle CANCELED separately — resubmit the IN transfer so
   the receive chain restarts automatically after SET_INTERFACE flushes
   the endpoint during alt=0→alt=1 switch. Remove the retry logic from
   the default (error) case: leave the pipe HALTED so the USB host
   client's USBH_EP_CMD_FLUSH can run without hitting
   ESP_ERR_INVALID_STATE.

2. Add usbh_cdc_restart_in_transfer(): called by the ECM layer after
   SET_INTERFACE(alt=1) completes to clear the HALTED IN pipe and
   resubmit the IN transfer chain.

3. Add usbh_cdc_restart_out_transfer(): on a software reboot the device
   is not power-cycled, so the OUT pipe may be left HALTED from the
   previous session. Clears the halt and releases the semaphore, guarded
   by a semaphore-count check so it is a no-op on a healthy pipe (safe
   to call on both HW and SW reboots).

4. Set USB_TRANSFER_FLAG_ZERO_PACK on the bulk OUT transfer so a ZLP is
   sent when payload size is an exact multiple of the 64-byte MPS, as
   required by CDC-ECM spec §3.3.1.

Both restart functions are called from iot_usbh_ecm after
SET_INTERFACE(alt=1) completes.

Tested on ESP32-S3 with a USB modem (VID:1F94 PID:3002),verified on both
hardware power-cycle and software reboot (esp_restart()).

Author: Vyacheslav Furyst

components/usb/iot_usbh_cdc/include/iot_usbh_cdc.h

@@ -381,6 +381,34 @@ esp_err_t usbh_cdc_get_dev_handle(usbh_cdc_port_handle_t cdc_port_handle, usb_de
  */
 esp_err_t usbh_cdc_port_get_intf_desc(usbh_cdc_port_handle_t port_handle, const usb_intf_desc_t **notif_intf,  const usb_intf_desc_t **data_intf);
 
+/**
+ * @brief Restart the bulk IN transfer chain after SET_INTERFACE(alt=1) completes.
+ *
+ * The IN endpoint is unavailable while the data interface is in alt=0.  Any
+ * pending IN transfer fails with STATUS_ERROR and leaves the pipe HALTED.
+ * Call this from the ECM layer once alt=1 is active so the receive path
+ * becomes live again.
+ *
+ * @param[in] cdc_port_handle CDC port handle
+ * @return ESP_OK on success, ESP_ERR_INVALID_STATE if handle or transfer is NULL
+ */
+esp_err_t usbh_cdc_restart_in_transfer(usbh_cdc_port_handle_t cdc_port_handle);
+
+/**
+ * @brief Recover the bulk OUT pipe after a software reboot.
+ *
+ * On a software reboot the USB device is not power-cycled.  A failed OUT
+ * transfer from the previous session can leave the pipe HALTED, blocking all
+ * future transmits.  This function clears the halt and releases the semaphore
+ * only when the pipe is actually stalled (semaphore count == 0), so it is
+ * safe to call unconditionally after SET_INTERFACE(alt=1) on both HW and SW
+ * reboots.
+ *
+ * @param[in] cdc_port_handle CDC port handle
+ * @return ESP_OK on success, ESP_ERR_INVALID_STATE if handle or transfer is NULL
+ */
+esp_err_t usbh_cdc_restart_out_transfer(usbh_cdc_port_handle_t cdc_port_handle);
+
 #ifdef __cplusplus
 }
 #endif

components/usb/iot_usbh_cdc/iot_usbh_cdc.c

@@ -570,15 +570,36 @@ static void in_xfer_cb(usb_transfer_t *in_xfer)
         return;
     }
     case USB_TRANSFER_STATUS_NO_DEVICE:
-    case USB_TRANSFER_STATUS_CANCELED:
         return;
-    default:
-        // Any other error
-        ESP_LOGW(TAG, "IN Transfer failed, EP:%d, status %d", in_xfer->bEndpointAddress & USB_B_ENDPOINT_ADDRESS_EP_NUM_MASK, in_xfer->status);
-        if (retry_count++ < CONFIG_USBH_CDC_IN_EP_RETRY_COUNT) {
-            _cdc_reset_transfer_endpoint(cdc_port->cdc_dev->dev_hdl, in_xfer);
+    case USB_TRANSFER_STATUS_CANCELED:
+        /*
+         * CANCELED fires when the USB host flushes the endpoint during
+         * SET_INTERFACE (alt=0 → alt=1 for CDC-ECM).  Resubmit so the IN
+         * transfer chain restarts automatically once alt=1 is active and the
+         * bulk endpoint physically exists.  Skip if the port is being closed.
+         */
+        if (!cdc_port->to_close) {
+            retry_count = 0;
             _cdc_host_transfer_submit(cdc_port, in_xfer);
         }
+        return;
+    default:
+        /*
+         * IN transfer failed (typically STATUS_ERROR on alt=0 before SET_INTERFACE).
+         *
+         * Do NOT clear the pipe or resubmit here.  _handle_pending_ep (USB host
+         * client error handler) calls USBH_EP_CMD_FLUSH on the endpoint, which
+         * requires the pipe to be in HALTED state.  Calling endpoint_clear
+         * (HALTED→ACTIVE) before that FLUSH runs causes an ESP_ERR_INVALID_STATE
+         * crash.
+         *
+         * The pipe stays HALTED after every error.  The ECM layer calls
+         * usbh_cdc_restart_in_transfer() after SET_INTERFACE completes (alt=1
+         * is active) to restart the IN transfer chain cleanly.
+         */
+        ESP_LOGW(TAG, "IN Transfer failed, EP:%d, status %d",
+                 in_xfer->bEndpointAddress & USB_B_ENDPOINT_ADDRESS_EP_NUM_MASK,
+                 in_xfer->status);
         break;
     }
 }
@@ -608,6 +629,49 @@ static void out_xfer_cb(usb_transfer_t *out_xfer)
     }
 }
 
+/*
+ * Restart the IN bulk transfer chain after the interface has switched to alt=1.
+ * Must be called from the ECM layer once SET_INTERFACE(alt=1) has completed and
+ * the bulk IN endpoint is physically present.
+ */
+esp_err_t usbh_cdc_restart_in_transfer(usbh_cdc_port_handle_t handle)
+{
+    usbh_cdc_port_t *cdc_port = (usbh_cdc_port_t *)handle;
+    if (!cdc_port || !cdc_port->data.in_xfer) {
+        return ESP_ERR_INVALID_STATE;
+    }
+    /* Clear HALTED→ACTIVE before submitting */
+    usb_host_endpoint_clear(cdc_port->cdc_dev->dev_hdl,
+                            cdc_port->data.in_xfer->bEndpointAddress);
+    return _cdc_host_transfer_submit(cdc_port, cdc_port->data.in_xfer);
+}
+
+/*
+ * Recover the OUT bulk pipe after a software reboot.
+ *
+ * On a software reboot the USB device is not power-cycled, so a failed OUT
+ * transfer from the previous session can leave the pipe in HALTED state.
+ * This function clears the halt and releases the semaphore so future writes
+ * can proceed.  The semaphore-count guard prevents touching a healthy pipe
+ * (which would produce a spurious ESP_ERR_INVALID_STATE from the USB host
+ * layer on a normal hardware reboot).
+ *
+ * Must be called from the ECM layer after SET_INTERFACE(alt=1) completes.
+ */
+esp_err_t usbh_cdc_restart_out_transfer(usbh_cdc_port_handle_t handle)
+{
+    usbh_cdc_port_t *cdc_port = (usbh_cdc_port_t *)handle;
+    if (!cdc_port || !cdc_port->data.out_xfer || cdc_port->out_ringbuf_handle) {
+        return ESP_ERR_INVALID_STATE;
+    }
+    if (uxSemaphoreGetCount(cdc_port->data.out_xfer_free_sem) == 0) {
+        usb_host_endpoint_clear(cdc_port->cdc_dev->dev_hdl,
+                                cdc_port->data.out_xfer->bEndpointAddress);
+        xSemaphoreGive(cdc_port->data.out_xfer_free_sem);
+    }
+    return ESP_OK;
+}
+
 static void _cdc_tx_xfer_submit(usb_transfer_t *out_xfer)
 {
     usbh_cdc_port_t *cdc_port = (usbh_cdc_port_t *) out_xfer->context;
@@ -706,6 +770,11 @@ static esp_err_t _cdc_transfers_allocate(usbh_cdc_port_t *cdc_port, const usb_ep
             cdc_port->data.out_xfer->context = cdc_port;
             cdc_port->data.out_xfer->num_bytes = out_buf_len;
             cdc_port->data.out_xfer->callback = out_xfer_cb;
+            /* CDC-ECM spec §3.3.1: host MUST send a ZLP when a segment size is
+             * an exact multiple of the bulk OUT MPS, so the device can detect
+             * end-of-transfer. Without this flag the device's BULK OUT endpoint
+             * stalls permanently on such transfers. */
+            cdc_port->data.out_xfer->flags = USB_TRANSFER_FLAG_ZERO_PACK;
         }
     }
     return ret;

components/usb/iot_usbh_ecm/iot_usbh_ecm.c

@@ -265,6 +265,19 @@ static void _usbh_ecm_task(void *arg)
         if (events & ECM_DEV_CONNECTED) {
             _ecm_config_intf(ecm);
             connected_time_ms = pdTICKS_TO_MS(xTaskGetTickCount());
+            /*
+             * The IN bulk endpoint fails with STATUS_ERROR while the interface
+             * is in alt=0 (no physical endpoint), leaving the pipe HALTED.
+             * The OUT pipe may also be HALTED after a software reboot (device
+             * not power-cycled, stale HALTED state from previous session).
+             *
+             * SET_INTERFACE(alt=1) is now complete — restart both transfer
+             * chains so the data path is live before "Connected" fires.
+             */
+            if (ecm->cdc_port) {
+                usbh_cdc_restart_in_transfer(ecm->cdc_port);
+                usbh_cdc_restart_out_transfer(ecm->cdc_port);
+            }
         }
         if (events & ECM_STOP) {
             ESP_LOGI(TAG, "USB ECM stop");