Add ESP32-S31 as a supported MCU in TinyUSB

7 files changed, 54 insertions, 14 deletions

diff --git a/README.rst b/README.rst
index 6be9d4873..04998abaa 100644
--- a/README.rst
+++ b/README.rst
@@ -157,6 +157,8 @@ Supported CPUs
 | Espressif    | S2, S3, H4                  | ✔      | ✔    | ✖         | dwc2                   |                    |
 | ESP32        +-----------------------------+--------+------+-----------+------------------------+--------------------+
 |              | P4                          | ✔      | ✔    | ✔         | dwc2                   |                    |
+|              +-----------------------------+--------+------+-----------+------------------------+--------------------+
+|              | S31                         | ✔      | ✔    | ✔         | dwc2                   |                    |
 +--------------+-----------------------------+--------+------+-----------+------------------------+--------------------+
 | GigaDevice   | GD32VF103                   | ✔      |      | ✖         | dwc2                   |                    |
 +--------------+-----------------------------+--------+------+-----------+------------------------+--------------------+
diff --git a/hw/bsp/espressif/boards/family.c b/hw/bsp/espressif/boards/family.c
index 48b1253b6..4b28cecf2 100644
--- a/hw/bsp/espressif/boards/family.c
+++ b/hw/bsp/espressif/boards/family.c
@@ -49,7 +49,7 @@ static led_strip_handle_t led_strip;
 static void max3421_init(void);
 #endif
 
-#if TU_CHECK_MCU(OPT_MCU_ESP32S2, OPT_MCU_ESP32S3, OPT_MCU_ESP32H4, OPT_MCU_ESP32P4)
+#if TU_CHECK_MCU(OPT_MCU_ESP32S2, OPT_MCU_ESP32S3, OPT_MCU_ESP32H4, OPT_MCU_ESP32P4, OPT_MCU_ESP32S31)
 static bool usb_init(uint8_t rhport, bool is_host);
 #endif
 
@@ -111,10 +111,6 @@ void board_init(void) {
 #endif
 }
 
-#if TU_CHECK_MCU(OPT_MCU_ESP32S2, OPT_MCU_ESP32S3, OPT_MCU_ESP32H4)
-
-#endif
-
 //--------------------------------------------------------------------+
 // Board porting API
 //--------------------------------------------------------------------+
@@ -178,7 +174,7 @@ void board_reset_to_bootloader(void) {
 // PHY Init
 //--------------------------------------------------------------------
 
-#if TU_CHECK_MCU(OPT_MCU_ESP32S2, OPT_MCU_ESP32S3, OPT_MCU_ESP32H4, OPT_MCU_ESP32P4)
+#if TU_CHECK_MCU(OPT_MCU_ESP32S2, OPT_MCU_ESP32S3, OPT_MCU_ESP32H4, OPT_MCU_ESP32P4, OPT_MCU_ESP32S31)
 #if ESP_IDF_VERSION >= ESP_IDF_VERSION_VAL(5, 3, 0)
 
 #include "esp_private/usb_phy.h"
diff --git a/hw/bsp/espressif/family.cmake b/hw/bsp/espressif/family.cmake
index ca9eadaf6..30d5a6ac9 100644
--- a/hw/bsp/espressif/family.cmake
+++ b/hw/bsp/espressif/family.cmake
@@ -2,7 +2,10 @@
 include("${CMAKE_CURRENT_LIST_DIR}/boards/${BOARD}/board.cmake")
 string(TOUPPER ${IDF_TARGET} FAMILY_MCUS)
 
-# Device port default to Port1 for P4 (highspeed), Port0 for others (fullspeed)
+# Device/host port defaults:
+# - ESP32-P4 uses Port1 (highspeed)
+# - ESP32-S31 uses Port0 (highspeed)
+# - Other targets use Port0 and derive the default speed from RHPORT_SPEED
 set(RHPORT_SPEED OPT_MODE_FULL_SPEED OPT_MODE_HIGH_SPEED)
 
 if (NOT DEFINED RHPORT_DEVICE)
@@ -22,10 +25,18 @@ if (NOT DEFINED RHPORT_HOST)
 endif()
 
 if (NOT DEFINED RHPORT_DEVICE_SPEED)
-  list(GET RHPORT_SPEED ${RHPORT_DEVICE} RHPORT_DEVICE_SPEED)
+  if (IDF_TARGET STREQUAL "esp32s31")
+    set(RHPORT_DEVICE_SPEED OPT_MODE_HIGH_SPEED)
+  else ()
+    list(GET RHPORT_SPEED ${RHPORT_DEVICE} RHPORT_DEVICE_SPEED)
+  endif ()
 endif ()
 if (NOT DEFINED RHPORT_HOST_SPEED)
-  list(GET RHPORT_SPEED ${RHPORT_HOST} RHPORT_HOST_SPEED)
+  if (IDF_TARGET STREQUAL "esp32s31")
+    set(RHPORT_HOST_SPEED OPT_MODE_HIGH_SPEED)
+  else ()
+    list(GET RHPORT_SPEED ${RHPORT_HOST} RHPORT_HOST_SPEED)
+  endif ()
 endif ()
 
 # Add example src and bsp directories
diff --git a/src/common/tusb_mcu.h b/src/common/tusb_mcu.h
index 77a0bbf1d..a17c76a3b 100644
--- a/src/common/tusb_mcu.h
+++ b/src/common/tusb_mcu.h
@@ -455,7 +455,7 @@
   #define CFG_TUSB_OS_INC_PATH_DEFAULT freertos/
   // clang-format on
 
-  #if CFG_TUSB_MCU == OPT_MCU_ESP32S3
+  #if CFG_TUSB_MCU == OPT_MCU_ESP32S3 || CFG_TUSB_MCU == OPT_MCU_ESP32H4
     #define TUP_MCU_MULTIPLE_CORE 1
   #endif
 
@@ -476,6 +476,22 @@
   #define CFG_TUH_MEM_DCACHE_ENABLE_DEFAULT     CFG_TUH_DWC2_DMA_ENABLE
   #define CFG_TUSB_MEM_DCACHE_LINE_SIZE_DEFAULT 64
 
+#elif TU_CHECK_MCU(OPT_MCU_ESP32S31)
+  #define TUP_USBIP_DWC2
+  #define TUP_USBIP_DWC2_ESP32
+  #define TUP_RHPORT_HIGHSPEED                  1
+  #define TUP_DCD_ENDPOINT_MAX                  16
+
+  // clang-format off
+  #define CFG_TUSB_OS_INC_PATH_DEFAULT          freertos/
+  // clang-format on
+
+  #define TUP_MCU_MULTIPLE_CORE                 1
+
+  // Disable slave if DMA is enabled
+  #define CFG_TUD_DWC2_SLAVE_ENABLE_DEFAULT     !CFG_TUD_DWC2_DMA_ENABLE
+  #define CFG_TUH_DWC2_SLAVE_ENABLE_DEFAULT     !CFG_TUH_DWC2_DMA_ENABLE
+
 #elif TU_CHECK_MCU(OPT_MCU_ESP32, OPT_MCU_ESP32C2, OPT_MCU_ESP32C3, OPT_MCU_ESP32C5, OPT_MCU_ESP32C6, \
                    OPT_MCU_ESP32C61, OPT_MCU_ESP32H2)
   #if (CFG_TUD_ENABLED || !(defined(CFG_TUH_MAX3421) && CFG_TUH_MAX3421))
diff --git a/src/portable/synopsys/dwc2/dcd_dwc2.c b/src/portable/synopsys/dwc2/dcd_dwc2.c
index 9a9c734a0..c30af6196 100644
--- a/src/portable/synopsys/dwc2/dcd_dwc2.c
+++ b/src/portable/synopsys/dwc2/dcd_dwc2.c
@@ -541,8 +541,9 @@ void dcd_remote_wakeup(uint8_t rhport) {
 void dcd_connect(uint8_t rhport) {
   dwc2_regs_t* dwc2 = DWC2_REG(rhport);
 
-#ifdef TUP_USBIP_DWC2_ESP32
-  // On ESP32-P4 HS PHY, do not write to USB_WRAP register which belongs to FS PHY
+#if defined(TUP_USBIP_DWC2_ESP32) && !TU_CHECK_MCU(OPT_MCU_ESP32S31)
+  // S31 is excluded at compile time (no USB_WRAP peripheral).
+  // On P4, the HS PHY (port 1) must not touch USB_WRAP which belongs to the FS PHY.
   if (rhport == 0) {
     usb_wrap_otg_conf_reg_t conf = USB_WRAP.otg_conf;
     conf.pad_pull_override = 0;
@@ -560,8 +561,9 @@ void dcd_connect(uint8_t rhport) {
 void dcd_disconnect(uint8_t rhport) {
   dwc2_regs_t* dwc2 = DWC2_REG(rhport);
 
-#ifdef TUP_USBIP_DWC2_ESP32
-  // On ESP32-P4 HS PHY, do not write to USB_WRAP register which belongs to FS PHY
+#if defined(TUP_USBIP_DWC2_ESP32) && !TU_CHECK_MCU(OPT_MCU_ESP32S31)
+  // S31 is excluded at compile time (no USB_WRAP peripheral).
+  // On P4, the HS PHY (port 1) must not touch USB_WRAP which belongs to the FS PHY.
   if (rhport == 0) {
     usb_wrap_otg_conf_reg_t conf = USB_WRAP.otg_conf;
     conf.pad_pull_override = 1;
diff --git a/src/portable/synopsys/dwc2/dwc2_esp32.h b/src/portable/synopsys/dwc2/dwc2_esp32.h
index 6a10dc7f8..436f8dc30 100644
--- a/src/portable/synopsys/dwc2/dwc2_esp32.h
+++ b/src/portable/synopsys/dwc2/dwc2_esp32.h
@@ -37,7 +37,11 @@
 
 #include "esp_intr_alloc.h"
 #include "soc/periph_defs.h"
+
+// ESP32-S31 does not have USB_WRAP peripheral (HS-only with UTMI PHY)
+#if !TU_CHECK_MCU(OPT_MCU_ESP32S31)
 #include "soc/usb_wrap_struct.h"
+#endif
 
 #if TU_CHECK_MCU(OPT_MCU_ESP32S2, OPT_MCU_ESP32S3)
 #define DWC2_FS_REG_BASE   0x60080000UL
@@ -75,6 +79,14 @@ static const dwc2_controller_t _dwc2_controller[] = {
   { .reg_base = DWC2_FS_REG_BASE, .irqnum = ETS_USB_OTG11_CH0_INTR_SOURCE, .ep_count = 7, .ep_in_count = 5, .otg_dfifo_depth = 256 },
   { .reg_base = DWC2_HS_REG_BASE, .irqnum = ETS_USB_OTG_INTR_SOURCE, .ep_count = 16, .ep_in_count = 8, .otg_dfifo_depth = 1024 }
 };
+
+#elif TU_CHECK_MCU(OPT_MCU_ESP32S31)
+#define DWC2_HS_REG_BASE   0x20300000UL
+#define DWC2_EP_MAX        16
+
+static const dwc2_controller_t _dwc2_controller[] = {
+  { .reg_base = DWC2_HS_REG_BASE, .irqnum = ETS_USB_OTGHS_INTR_SOURCE, .ep_count = 16, .ep_in_count = 8, .otg_dfifo_depth = 1024 }
+};
 #endif
 
 //--------------------------------------------------------------------+
diff --git a/src/tusb_option.h b/src/tusb_option.h
index dd7af76f6..154f8e2a4 100644
--- a/src/tusb_option.h
+++ b/src/tusb_option.h
@@ -134,6 +134,7 @@
 #define OPT_MCU_ESP32C5           908 ///< Espressif ESP32-C5
 #define OPT_MCU_ESP32C61          909 ///< Espressif ESP32-C61
 #define OPT_MCU_ESP32H4           910 ///< Espressif ESP32-H4
+#define OPT_MCU_ESP32S31          911 ///< Espressif ESP32-S31
 
 // Dialog
 #define OPT_MCU_DA1469X          1000 ///< Dialog Semiconductor DA1469x