feature(esp_tinyusb): Added the vbus software monitoring for esp23p4

roma-jam · roma-jam · commit 85e04eff5a03 · 2025-10-31T02:15:31.000+01:00
- added GPIO ISR, debounce timer, debounce logic
- added GOTGCTL.BVALID driving on VBUS appear/disappear
- added DCTL.SFTDISCON driving on VBUS appear/dissapear
diff --git a/device/esp_tinyusb/include_private/tinyusb_vbus_monitor.h b/device/esp_tinyusb/include_private/tinyusb_vbus_monitor.h
@@ -26,17 +26,23 @@ typedef struct {
  * - This function should be called after tusb_init() when GOTGCTL register is initialized
  * - This is a single-threaded implementation, so only one instance of VBUS monitoring is supported
  *
- * @param vbus_io_num GPIO number used for VBUS monitoring, 3.3 V tolerant (use a comparator or a resistor divider to detect the VBUS valid condition).
+ * @param config  Pointer to VBUS monitoring configuration structure
  *
  * @return
- *    - ESP_ERR_NOT_SUPPORTED: VBUS monitoring is not supported yet
+ *    - ESP_ERR_INVALID_STATE if VBUS monitoring is already initialized
+ *    - ESP_ERR_NO_MEM if debounce timer creation failed
+ *    - ESP_OK on success
  */
 esp_err_t tinyusb_vbus_monitor_init(tinyusb_vbus_monitor_config_t *config);
 
 /**
  * @brief Deinitialize VBUS monitoring
+ *
+ * @return
+ *    - ESP_ERR_INVALID_STATE if VBUS monitoring is not initialized
+ *    - ESP_OK on success
  */
-void tinyusb_vbus_monitor_deinit(void);
+esp_err_t tinyusb_vbus_monitor_deinit(void);
 
 #ifdef __cplusplus
 }
diff --git a/device/esp_tinyusb/test_apps/vbus_monitor/main/test_vbus_monitor.c b/device/esp_tinyusb/test_apps/vbus_monitor/main/test_vbus_monitor.c
@@ -510,7 +510,7 @@ TEST_CASE("Emulated VBUS USB OTG 2.0, verify attach/detach events callback (via
 
     test_device_wait_event(TINYUSB_EVENT_ATTACHED);
 
-    uint8_t dev_mounted = 0; /* TODO: Expect to fail on run. Enable in VBUS monitor part2 */
+    uint8_t dev_mounted = test_vbus_emulated_via_gotgctl_bvalid(&USB_DWC_HS);
 
     // Cleanup
     TEST_ASSERT_EQUAL_MESSAGE(ESP_OK, tinyusb_driver_uninstall(), "Failed to uninstall TinyUSB driver");
@@ -558,7 +558,7 @@ TEST_CASE("Controlled VBUS USB OTG 2.0, verify attach/detach events callback", "
     TEST_ASSERT_EQUAL_MESSAGE(ESP_OK, tinyusb_driver_install(&tusb_cfg), "Failed to install TinyUSB driver");
     test_device_wait_event(TINYUSB_EVENT_ATTACHED);
 
-    uint8_t dev_mounted = 0; /* TODO: Expect to fail on run. Enable in VBUS monitor part2 */
+    uint8_t dev_mounted = test_vbus_controlled_by_gpio();
 
     // Cleanup
     TEST_ASSERT_EQUAL_MESSAGE(ESP_OK, tinyusb_driver_uninstall(), "Failed to uninstall TinyUSB driver");
@@ -606,7 +606,7 @@ TEST_CASE("Real VBUS USB OTG 2.0, verify attach/detach events callback (requires
     TEST_ASSERT_EQUAL_MESSAGE(ESP_OK, tinyusb_driver_install(&tusb_cfg), "Failed to install TinyUSB driver");
     test_device_wait_event(TINYUSB_EVENT_ATTACHED);
 
-    uint8_t dev_mounted = 0; /* TODO: Expect to fail on run. Enable in VBUS monitor part2 */
+    uint8_t dev_mounted = test_vbus_manual_attach_detach();
 
     // Cleanup
     TEST_ASSERT_EQUAL_MESSAGE(ESP_OK, tinyusb_driver_uninstall(), "Failed to uninstall TinyUSB driver");
diff --git a/device/esp_tinyusb/tinyusb_vbus_monitor.c b/device/esp_tinyusb/tinyusb_vbus_monitor.c
@@ -7,10 +7,21 @@
 #include <stdlib.h>
 #include "esp_log.h"
 #include "esp_err.h"
+#include "esp_check.h"
+#include "freertos/FreeRTOS.h"
+#include "freertos/timers.h"
+#include "driver/gpio.h"
 #include "tinyusb_vbus_monitor.h"
 
 const static char *TAG = "VBUS mon";
 
+#if (CONFIG_IDF_TARGET_ESP32P4)
+#include "soc/usb_dwc_struct.h"
+// On ESP32-P4 USB OTG 2.0 signals are not wired to GPIO matrix
+// So we need to override the Bvalid signal from PHY
+#define USB_DWC_REG                     USB_DWC_HS
+#endif // CONFIG_IDF_TARGET_ESP32P4
+
 /**
  * @brief VBUS monitoring context
  *
@@ -22,15 +33,217 @@ typedef struct {
     TimerHandle_t debounce_timer;   /*!< Debounce timer handle */
 } vbus_monitor_context_t;
 
+static vbus_monitor_context_t _vbus_ctx = {
+    .gpio_num = GPIO_NUM_NC,
+    .prev_state = false,
+    .debounce_timer = NULL,
+};
+
+//
+// Additional low-level USB DWC functions, which are not present in the IDF USB DWC HAL
+//
+
+// --------------- GOTGCTL register ------------------
+
+static void usb_dwc_ll_gotgctl_set_bvalid_override_value(usb_dwc_dev_t *hw, uint8_t value)
+{
+    hw->gotgctl_reg.bvalidovval = value;
+}
+
+static void usb_dwc_ll_gotgctl_enable_bvalid_override(usb_dwc_dev_t *hw, bool enable)
+{
+    hw->gotgctl_reg.bvalidoven = enable ? 1 : 0;
+}
+
+// ------------------ DCTL register --------------------
+
+static void usb_dwc_ll_dctl_set_soft_disconnect(usb_dwc_dev_t *hw, bool enable)
+{
+    hw->dctl_reg.sftdiscon = enable ? 1 : 0;
+}
+
+// -------------- VBUS Internal Logic ------------------
+
+/**
+ * @brief Handle VBUS appeared event
+ */
+static void vbus_appeared(void)
+{
+    ESP_LOGD(TAG, "Appeared");
+    usb_dwc_ll_gotgctl_set_bvalid_override_value(&USB_DWC_REG, 1);
+    usb_dwc_ll_dctl_set_soft_disconnect(&USB_DWC_REG, false);
+}
+
+/**
+ * @brief Handle VBUS disappeared event
+ */
+static void vbus_disappeared(void)
+{
+    ESP_LOGD(TAG, "Disappeared");
+    usb_dwc_ll_gotgctl_set_bvalid_override_value(&USB_DWC_REG, 0);
+    usb_dwc_ll_dctl_set_soft_disconnect(&USB_DWC_REG, true);
+}
+
+/**
+ * @brief GPIO interrupt handler for VBUS monitoring io
+ *
+ * @param arg GPIO number
+ */
+static void vbus_io_cb(void *arg)
+{
+    (void) arg;
+    // disable interrupts for a while to debounce
+    gpio_intr_disable(_vbus_ctx.gpio_num);
+
+    bool vbus_curr_state = gpio_get_level(_vbus_ctx.gpio_num);
+
+    if (_vbus_ctx.prev_state != vbus_curr_state) {
+        _vbus_ctx.prev_state = vbus_curr_state;
+        // VBUS pin state has changed, start the debounce timer
+        BaseType_t yield = pdFALSE;
+        if (xTimerStartFromISR(_vbus_ctx.debounce_timer, &yield) != pdPASS) {
+            ESP_EARLY_LOGE(TAG, "Failed to start VBUS debounce timer");
+        }
+        if (yield == pdTRUE) {
+            portYIELD_FROM_ISR();
+        }
+    } else {
+        // VBUS gpio glitch, ignore and re-enable interrupt
+        gpio_intr_enable(_vbus_ctx.gpio_num);
+    }
+}
+
+/**
+ * @brief VBUS debounce timer callback
+ *
+ * @param xTimer Timer handle
+ */
+static void vbus_debounce_timer_cb(TimerHandle_t xTimer)
+{
+    bool vbus_prev_state = _vbus_ctx.prev_state;
+    bool vbus_curr_state = gpio_get_level(_vbus_ctx.gpio_num);
+
+    if (vbus_curr_state && vbus_prev_state) {
+        vbus_appeared();
+    } else if (!vbus_curr_state && !vbus_prev_state) {
+        vbus_disappeared();
+    } else {
+        // State changed again during debounce period, ignore
+    }
+    // Update the state
+    _vbus_ctx.prev_state = vbus_curr_state;
+    // Re-enable GPIO interrupt
+    gpio_intr_enable(_vbus_ctx.gpio_num);
+}
+
 // -------------- Public API ------------------
 
 esp_err_t tinyusb_vbus_monitor_init(tinyusb_vbus_monitor_config_t *config)
 {
+    esp_err_t ret;
+
+    // There could be only one instance of VBUS monitoring
+    if (_vbus_ctx.debounce_timer != NULL) {
+        ESP_LOGE(TAG, "Already initialized");
+        return ESP_ERR_INVALID_STATE;
+    }
+
+    _vbus_ctx.gpio_num = config->gpio_num;
+    _vbus_ctx.prev_state = false;
+
+    // VBUS Debounce timer
+    _vbus_ctx.debounce_timer = xTimerCreate("vbus_debounce_timer",
+                                            pdMS_TO_TICKS(config->debounce_delay_ms),
+                                            pdFALSE,
+                                            NULL,
+                                            vbus_debounce_timer_cb);
+
+    if (_vbus_ctx.debounce_timer == NULL) {
+        ESP_LOGE(TAG, "Create VBUS debounce timer failed");
+        return ESP_ERR_NO_MEM;
+    }
+
+    // Init gpio IRQ for VBUS monitoring
+    const gpio_config_t vbus_io_cfg = {
+        .pin_bit_mask = BIT64(_vbus_ctx.gpio_num),
+        .mode = GPIO_MODE_INPUT,
+        .pull_down_en = GPIO_PULLDOWN_ENABLE,
+        .intr_type = GPIO_INTR_ANYEDGE,
+    };
+
+    ret = gpio_config(&vbus_io_cfg);
+    if (ret != ESP_OK) {
+        ESP_LOGE(TAG, "Config VBUS GPIO failed");
+        goto gpio_fail;
+    }
+
+    ret = gpio_install_isr_service(ESP_INTR_FLAG_LOWMED);
+    // Service could be already installed, it is not an error
+    if (ret != ESP_OK && ret != ESP_ERR_INVALID_STATE) {
+        ESP_LOGE(TAG, "Install GPIO ISR service failed");
+        goto isr_fail;
+    }
+
+    ret = gpio_isr_handler_add(_vbus_ctx.gpio_num, vbus_io_cb, (void *) NULL);
+    if (ret != ESP_OK) {
+        ESP_LOGE(TAG, "Add GPIO ISR handler failed");
+        goto add_isr_hdl_fail;
+    }
+    // Disable GPIO interrupt
+    gpio_intr_disable(_vbus_ctx.gpio_num);
+    // Set initial Bvalid override value and enable override
+    usb_dwc_ll_gotgctl_set_bvalid_override_value(&USB_DWC_REG, 0);
+    // Wait 1 microsecond (sufficient for >5 PHY clocks)
+    esp_rom_delay_us(1);
+    // Enable to override the signal from PHY
+    usb_dwc_ll_gotgctl_enable_bvalid_override(&USB_DWC_REG, true);
+
+    // Device could be already connected, check the status and start the timer if needed
+    if (gpio_get_level(_vbus_ctx.gpio_num)) {
+        _vbus_ctx.prev_state = true;
+        // Start debounce timer
+        if (xTimerStart(_vbus_ctx.debounce_timer, 0) != pdPASS) {
+            ESP_LOGE(TAG, "Failed to start VBUS debounce timer");
+        }
+    } else {
+        // Enable GPIO interrupt
+        gpio_intr_enable(_vbus_ctx.gpio_num);
+    }
+
     ESP_LOGD(TAG, "Init GPIO%d, debounce delay: %"PRIu32" ms", config->gpio_num, config->debounce_delay_ms);
-    return ESP_ERR_NOT_SUPPORTED;
+    return ESP_OK;
+
+add_isr_hdl_fail:
+    gpio_uninstall_isr_service();
+isr_fail:
+    gpio_reset_pin(_vbus_ctx.gpio_num);
+gpio_fail:
+    if (_vbus_ctx.debounce_timer) {
+        xTimerDelete(_vbus_ctx.debounce_timer, 0);
+        _vbus_ctx.debounce_timer = NULL;
+    }
+    return ret;
 }
 
-void tinyusb_vbus_monitor_deinit(void)
+esp_err_t tinyusb_vbus_monitor_deinit(void)
 {
+    if (_vbus_ctx.debounce_timer == NULL) {
+        return ESP_ERR_INVALID_STATE;
+    }
+    // Deinit gpio IRQ for VBUS monitoring
+    if (xTimerIsTimerActive(_vbus_ctx.debounce_timer) == pdTRUE) {
+        xTimerStop(_vbus_ctx.debounce_timer, 0);
+    }
+    xTimerDelete(_vbus_ctx.debounce_timer, 0);
+    _vbus_ctx.debounce_timer = NULL;
+
+    // Disable to override the signal from PHY
+    usb_dwc_ll_gotgctl_enable_bvalid_override(&USB_DWC_REG, false);
+    // Deinit gpio IRQ for VBUS monitoring
+    ESP_ERROR_CHECK(gpio_isr_handler_remove(_vbus_ctx.gpio_num));
+    gpio_intr_disable(_vbus_ctx.gpio_num);
+    gpio_uninstall_isr_service();
+
     ESP_LOGD(TAG, "Deinit");
+    return ESP_OK;
 }
