From 6b3f1f077feb237e7522914706697d95f38d4285 Mon Sep 17 00:00:00 2001
From: JiangGuangMing <jiangguangming@espressif.com>
Date: Thu, 28 May 2026 11:37:13 +0800
Subject: [PATCH] feat(esp_hal_usb): add usb suspend wakeup status in ll layer

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 .../esp32p4/include/hal/usb_utmi_ll.h         | 45 ++++++++++++++++++-
 .../esp_hal_usb/include/hal/usb_utmi_hal.h    | 24 +++++++++-
 components/esp_hal_usb/usb_utmi_hal.c         | 17 ++++++-
 3 files changed, 83 insertions(+), 3 deletions(-)

diff --git a/components/esp_hal_usb/esp32p4/include/hal/usb_utmi_ll.h b/components/esp_hal_usb/esp32p4/include/hal/usb_utmi_ll.h
index f64250a66e6..ea02eff9d1e 100644
--- a/components/esp_hal_usb/esp32p4/include/hal/usb_utmi_ll.h
+++ b/components/esp_hal_usb/esp32p4/include/hal/usb_utmi_ll.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2024-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -11,7 +11,9 @@
 #include "soc/lp_clkrst_struct.h"
 #include "soc/hp_sys_clkrst_struct.h"
 #include "soc/hp_system_struct.h"
+#include "soc/lp_system_struct.h"
 #include "soc/usb_utmi_struct.h"
+#include "hal/config.h"
 
 #ifdef __cplusplus
 extern "C" {
@@ -81,6 +83,29 @@ FORCE_INLINE_ATTR void _usb_utmi_ll_reset_register(void)
         _usb_utmi_ll_reset_register(__VA_ARGS__); \
     } while(0)
 
+/**
+ * @brief Enable/disable 15k pulldown resistors on D+/D- lines
+ *
+ * In USB Host mode, 15k pulldown resistors must be connected on both D+ and D-.
+ * In USB Device mode, pulldown resistors must be disconnected.
+ *
+ * @note On ESP32-P4 v3+, pulldowns are no longer controlled by USB-OTG peripheral
+ *       and must be controlled by software via LP_SYS registers.
+ *       On earlier revisions, pulldowns are controlled by the USB-OTG hardware.
+ *
+ * @param[in] enable true to connect pulldowns (Host mode), false to disconnect (Device mode)
+ */
+FORCE_INLINE_ATTR void usb_utmi_ll_enable_data_pulldowns(bool enable)
+{
+#if HAL_CONFIG(CHIP_SUPPORT_MIN_REV) >= 300
+    LP_SYS.hp_usb_otghs_phy_ctrl.hp_utmiotg_dppulldown = enable;
+    LP_SYS.hp_usb_otghs_phy_ctrl.hp_utmiotg_dmpulldown = enable;
+#else
+    // On pre-v3 ESP32-P4, pulldowns are controlled by the USB-OTG peripheral
+    (void)enable;
+#endif
+}
+
 /**
  * @brief Enable precise detection of VBUS
  *
@@ -92,6 +117,24 @@ FORCE_INLINE_ATTR void usb_utmi_ll_enable_precise_detection(bool enable)
     HP_SYSTEM.sys_usbotg20_ctrl.sys_otg_suspendm = enable;
 }
 
+/**
+ * @brief Set USB OTG2.0 suspend state for PMU USB wakeup logic
+ *
+ * @param[in] in_suspend True if USB OTG2.0 is suspended
+ */
+FORCE_INLINE_ATTR void usb_utmi_ll_set_suspend_state(bool in_suspend)
+{
+    LP_SYS.usb_ctrl.usbotg20_in_suspend = in_suspend;
+}
+
+/**
+ * @brief Clear USB OTG2.0 wakeup status sent to PMU
+ */
+FORCE_INLINE_ATTR void usb_utmi_ll_clear_wakeup_status(void)
+{
+    LP_SYS.usb_ctrl.usbotg20_wakeup_clr = 1;
+}
+
 #ifdef __cplusplus
 }
 #endif
diff --git a/components/esp_hal_usb/include/hal/usb_utmi_hal.h b/components/esp_hal_usb/include/hal/usb_utmi_hal.h
index dcb859a21c3..1466c57b516 100644
--- a/components/esp_hal_usb/include/hal/usb_utmi_hal.h
+++ b/components/esp_hal_usb/include/hal/usb_utmi_hal.h
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2024-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -57,6 +57,28 @@ void _usb_utmi_hal_disable(void);
 #define usb_utmi_hal_disable(...) do {(void)__DECLARE_RCC_ATOMIC_ENV; _usb_utmi_hal_disable(__VA_ARGS__);} while(0)
 #endif
 
+/**
+ * @brief Enable/disable 15k pulldown resistors on D+/D- lines
+ *
+ * In USB Host mode, 15k pulldown resistors must be connected on both D+ and D-.
+ * In USB Device mode, pulldown resistors must be disconnected.
+ *
+ * @param[in] enable true to connect pulldowns (Host mode), false to disconnect (Device mode)
+ */
+void usb_utmi_hal_enable_data_pulldowns(bool enable);
+
+/**
+ * @brief Set USB OTG2.0 suspend state for PMU USB wakeup logic
+ *
+ * @param[in] in_suspend True if USB OTG2.0 is suspended
+ */
+void usb_utmi_hal_set_suspend_state(bool in_suspend);
+
+/**
+ * @brief Clear USB OTG2.0 wakeup status sent to PMU
+ */
+void usb_utmi_hal_clear_wakeup_status(void);
+
 #endif // (SOC_USB_UTMI_PHY_NUM > 0)
 
 #ifdef __cplusplus
diff --git a/components/esp_hal_usb/usb_utmi_hal.c b/components/esp_hal_usb/usb_utmi_hal.c
index cb7ceb49ba2..76ba413852c 100644
--- a/components/esp_hal_usb/usb_utmi_hal.c
+++ b/components/esp_hal_usb/usb_utmi_hal.c
@@ -1,5 +1,5 @@
 /*
- * SPDX-FileCopyrightText: 2024 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2024-2026 Espressif Systems (Shanghai) CO LTD
  *
  * SPDX-License-Identifier: Apache-2.0
  */
@@ -23,6 +23,21 @@ void _usb_utmi_hal_init(usb_utmi_hal_context_t *hal)
     usb_utmi_ll_configure_ls(hal->dev, true);
 }
 
+void usb_utmi_hal_enable_data_pulldowns(bool enable)
+{
+    usb_utmi_ll_enable_data_pulldowns(enable);
+}
+
+void usb_utmi_hal_set_suspend_state(bool in_suspend)
+{
+    usb_utmi_ll_set_suspend_state(in_suspend);
+}
+
+void usb_utmi_hal_clear_wakeup_status(void)
+{
+    usb_utmi_ll_clear_wakeup_status();
+}
+
 void _usb_utmi_hal_disable(void)
 {
     _usb_utmi_ll_enable_bus_clock(false);