fix esp32p4 utmi phy init in the new esp-idf, also update esp-idf to v5.5.3

4 files changed, 47 insertions, 12 deletions

diff --git a/.circleci/config2.yml b/.circleci/config2.yml
index a31b0a818..bb0ac350f 100644
--- a/.circleci/config2.yml
+++ b/.circleci/config2.yml
@@ -110,7 +110,7 @@ commands:
           no_output_timeout: 20m
           command: |
             if [ << parameters.toolchain >> == esp-idf ]; then
-              docker run --rm -v $PWD:/project -w /project espressif/idf:v5.3.2 python tools/build.py << parameters.build-args >> --target all << parameters.family >>
+              docker run --rm -v $PWD:/project -w /project espressif/idf:v5.5.3 python tools/build.py << parameters.build-args >> --target all << parameters.family >>
             else
               # Toolchain option default is gcc
               if [ << parameters.toolchain >> == arm-clang ]; then
diff --git a/.github/actions/setup_toolchain/espressif/action.yml b/.github/actions/setup_toolchain/espressif/action.yml
index e9d645ac8..90ef753c4 100644
--- a/.github/actions/setup_toolchain/espressif/action.yml
+++ b/.github/actions/setup_toolchain/espressif/action.yml
@@ -7,7 +7,7 @@ inputs:
   toolchain_version:
     description: 'Toolchain version'
     required: false
-    default: 'v5.3.2'
+    default: 'v5.5.3'
 
 runs:
   using: "composite"
diff --git a/AGENTS.md b/AGENTS.md
index 73bf1f599..53af39545 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -21,6 +21,8 @@ information that does not match the info here.
 - For specific board families: `python3 tools/get_deps.py FAMILY_NAME` (e.g., rp2040, stm32f4), or
   `python3 tools/get_deps.py -b BOARD_NAME`
 - Dependencies are cached in `lib/` and `hw/mcu/` directories
+- For **Espressif** boards, initialize the ESP-IDF environment before any build/flash/monitor command:
+  `. $HOME/code/esp-idf/export.sh`
 
 ## Build Examples
 
@@ -59,6 +61,19 @@ make BOARD=raspberry_pi_pico all
 
 -- takes 2-3 seconds. NEVER CANCEL. Set timeout to 5+ minutes.
 
+**Option 4: Espressif Example with ESP-IDF**
+
+Only ESP-IDF-enabled examples are supported for Espressif boards. Use FreeRTOS examples such as `examples/device/cdc_msc_freertos`
+that contain `idf_component_register()` support.
+
+```bash
+. $HOME/code/esp-idf/export.sh
+cd examples/device/cdc_msc_freertos
+idf.py -DBOARD=espressif_s3_devkitc build
+```
+
+Use `-DBOARD=...` with any supported board under `hw/bsp/espressif/boards/`. NEVER CANCEL. Set timeout to 10+ minutes.
+
 
 ## Build Options
 
@@ -90,6 +105,14 @@ make BOARD=raspberry_pi_pico all
     - CMake: `ninja cdc_msc-uf2`
     - Make: `make BOARD=raspberry_pi_pico all uf2`
 - **List all targets** (CMake/Ninja): `ninja -t targets`
+- **Espressif flash**:
+    - Run `. $HOME/code/esp-idf/export.sh`
+    - `cd examples/device/cdc_msc_freertos`
+    - `idf.py -DBOARD=espressif_s3_devkitc flash`
+- **Espressif serial monitor / chip log output**:
+    - Run `. $HOME/code/esp-idf/export.sh`
+    - `cd examples/device/cdc_msc_freertos`
+    - `idf.py -DBOARD=espressif_s3_devkitc monitor`
 
 ## Unit Testing
 
diff --git a/hw/bsp/espressif/boards/family.c b/hw/bsp/espressif/boards/family.c
index 623cdb8b9..2fad7feec 100644
--- a/hw/bsp/espressif/boards/family.c
+++ b/hw/bsp/espressif/boards/family.c
@@ -50,7 +50,7 @@ static void max3421_init(void);
 #endif
 
 #if TU_CHECK_MCU(OPT_MCU_ESP32S2, OPT_MCU_ESP32S3, OPT_MCU_ESP32H4, OPT_MCU_ESP32P4)
-static bool usb_init(void);
+static bool usb_init(uint8_t rhport, bool is_host);
 #endif
 
 //--------------------------------------------------------------------+
@@ -90,8 +90,14 @@ void board_init(void) {
   gpio_set_direction(BUTTON_PIN, GPIO_MODE_INPUT);
   gpio_set_pull_mode(BUTTON_PIN, BUTTON_STATE_ACTIVE ? GPIO_PULLDOWN_ONLY : GPIO_PULLUP_ONLY);
 
-#if TU_CHECK_MCU(OPT_MCU_ESP32S2, OPT_MCU_ESP32S3, OPT_MCU_ESP32P4)
-  usb_init();
+#if CONFIG_USB_OTG_SUPPORTED
+  #if CFG_TUD_ENABLED
+  usb_init(BOARD_TUD_RHPORT, false);
+  #endif
+
+  #if CFG_TUH_ENABLED
+  usb_init(BOARD_TUH_RHPORT, true);
+  #endif
 #endif
 
 #ifdef HIL_TS3USB30_MODE_PIN
@@ -179,24 +185,30 @@ void board_reset_to_bootloader(void) {
 
 static usb_phy_handle_t phy_hdl;
 
-bool usb_init(void) {
+bool usb_init(uint8_t rhport, bool is_host) {
+  (void) rhport;
   // Configure USB PHY
   usb_phy_config_t phy_conf = {
     .controller = USB_PHY_CTRL_OTG,
+#if defined(CONFIG_SOC_USB_UTMI_PHY_NUM) && CONFIG_SOC_USB_UTMI_PHY_NUM > 0
+    .target = USB_PHY_TARGET_UTMI,
+#else
     .target = USB_PHY_TARGET_INT,
+#endif
 
     // maybe we can use USB_OTG_MODE_DEFAULT and switch using dwc2 driver
-#if CFG_TUD_ENABLED
-    .otg_mode = USB_OTG_MODE_DEVICE,
-#elif CFG_TUH_ENABLED
-    .otg_mode = USB_OTG_MODE_HOST,
-#endif
+    .otg_mode = is_host ? USB_OTG_MODE_HOST : USB_OTG_MODE_DEVICE,
     // https://github.com/hathach/tinyusb/issues/2943#issuecomment-2601888322
     // Set speed to undefined (auto-detect) to avoid timinng/racing issue with S3 with host such as macOS
     .otg_speed = USB_PHY_SPEED_UNDEFINED,
   };
 
-  usb_new_phy(&phy_conf, &phy_hdl);
+  esp_err_t const err = usb_new_phy(&phy_conf, &phy_hdl);
+  if (err != ESP_OK) {
+    printf("usb_new_phy failed: %s\r\n", esp_err_to_name(err));
+    phy_hdl = NULL;
+    return false;
+  }
 
   return true;
 }