Merge branch 'feat/uhci_esp32s31_support' into 'master'

feat(uhci): Add support for uhci on esp32s31

Closes IDF-14791

See merge request espressif/esp-idf!47730

components/esp_driver_uart/test_apps/uhci/README.md

@@ -1,2 +1,2 @@
-| Supported Targets | ESP32-C3 | ESP32-C5 | ESP32-C6 | ESP32-H2 | ESP32-H21 | ESP32-H4 | ESP32-P4 | ESP32-S3 |
+| Supported Targets | ESP32-C3 | ESP32-C5 | ESP32-C6 | ESP32-H2 | ESP32-H21 | ESP32-H4 | ESP32-P4 | ESP32-S3 | ESP32-S31 |
-| ----------------- | -------- | -------- | -------- | -------- | --------- | -------- | -------- | -------- |
+| ----------------- | -------- | -------- | -------- | -------- | --------- | -------- | -------- | -------- | --------- |

components/esp_driver_uart/test_apps/uhci/pytest_uhci.py

@@ -14,7 +14,7 @@ from pytest_embedded_idf.utils import idf_parametrize
     ],
     indirect=True,
 )
-@idf_parametrize('target', ['esp32c3', 'esp32c5', 'esp32c6', 'esp32h2', 'esp32p4'], indirect=['target'])
+@idf_parametrize('target', ['esp32c3', 'esp32c5', 'esp32c6', 'esp32h2', 'esp32p4', 'esp32s31'], indirect=['target'])
 def test_uhci(dut: Dut) -> None:
     dut.run_all_single_board_cases()
 

components/esp_hal_uart/esp32s31/include/hal/uhci_ll.h

@@ -0,0 +1,221 @@
+/*
+ * SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+#include <stdio.h>
+#include "hal/uhci_types.h"
+#include "soc/uhci_struct.h"
+#include "soc/hp_sys_clkrst_struct.h"
+#include "hal/misc.h"
+
+#define UHCI_LL_NUM (1UL)
+#define UHCI_LL_GET_HW(num) (((num) == 0) ? (&UHCI0) : (NULL))
+#define UHCI_LL_MAX_RECEIVE_PACKET_THRESHOLD  (8192)
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+typedef enum {
+    UHCI_RX_BREAK_CHR_EOF = 0x1,
+    UHCI_RX_IDLE_EOF      = 0x2,
+    UHCI_RX_LEN_EOF       = 0x4,
+    UHCI_RX_EOF_MAX       = 0x7,
+} uhci_rxeof_cfg_t;
+
+/**
+ * @brief Enable the bus clock for UHCI module
+ *
+ * @param group_id Group ID
+ * @param enable true to enable, false to disable
+ */
+static inline void uhci_ll_enable_bus_clock(int group_id, bool enable)
+{
+    (void)group_id;
+    HP_SYS_CLKRST.uhci_ctrl0.reg_uhci_sys_clk_en = enable;
+    HP_SYS_CLKRST.uhci_ctrl0.reg_uhci_apb_clk_en = enable;
+}
+
+/**
+ * @brief Reset the UHCI module
+ *
+ * @param group_id Group ID
+ */
+static inline void uhci_ll_reset_register(int group_id)
+{
+    (void)group_id;
+    HP_SYS_CLKRST.uhci_ctrl0.reg_uhci_rst_en = 1;
+    HP_SYS_CLKRST.uhci_ctrl0.reg_uhci_rst_en = 0;
+}
+
+/**
+ * @brief Initialize the UHCI module. Reset configuration registers and keep the clock enabled
+ *
+ * @param hw Pointer to the UHCI device
+ */
+static inline void uhci_ll_init(uhci_dev_t *hw)
+{
+    uhci_conf0_reg_t conf0_reg;
+    conf0_reg.val = 0;
+    conf0_reg.clk_en = 1;
+    hw->conf0.val = conf0_reg.val;
+    hw->conf1.val = 0;
+}
+
+/**
+ * @brief Attach the UHCI module to a UART port
+ *
+ * @param hw Pointer to the UHCI device
+ * @param uart_num The UART port number to attach the UHCI module to
+ */
+static inline void uhci_ll_attach_uart_port(uhci_dev_t *hw, int uart_num)
+{
+    hw->conf0.uart_sel = uart_num;
+}
+
+/**
+ * @brief UHCI escape sequence configuration
+ *
+ * @param hw Pointer to the UHCI device
+ * @param seper_char UHCI escape sequence configuration
+ */
+static inline void uhci_ll_set_seper_chr(uhci_dev_t *hw, uhci_seper_chr_t *seper_char)
+{
+    if (seper_char->sub_chr_en) {
+        hw->conf0.seper_en = 1;
+        uhci_esc_conf0_reg_t esc_conf0_reg;
+        esc_conf0_reg.val = hw->esc_conf0.val;
+
+        HAL_FORCE_MODIFY_U32_REG_FIELD(esc_conf0_reg, seper_char, seper_char->seper_chr);
+        HAL_FORCE_MODIFY_U32_REG_FIELD(esc_conf0_reg, seper_esc_char0, seper_char->sub_chr1);
+        HAL_FORCE_MODIFY_U32_REG_FIELD(esc_conf0_reg, seper_esc_char1, seper_char->sub_chr2);
+        hw->esc_conf0.val = esc_conf0_reg.val;
+        hw->escape_conf.tx_c0_esc_en = 1;
+        hw->escape_conf.rx_c0_esc_en = 1;
+    } else {
+        hw->conf0.seper_en = 0;
+        hw->escape_conf.val = 0;
+    }
+}
+
+/**
+ * @brief UHCI software flow control configuration
+ *
+ * @param hw Pointer to the UHCI device
+ * @param sub_ctr UHCI software flow control configuration
+ */
+static inline void uhci_ll_set_swflow_ctrl_sub_chr(uhci_dev_t *hw, uhci_swflow_ctrl_sub_chr_t *sub_ctr)
+{
+    uhci_escape_conf_reg_t escape_conf_reg;
+    escape_conf_reg.val = hw->escape_conf.val;
+
+    if (sub_ctr->flow_en == 1) {
+        uhci_esc_conf2_reg_t esc_conf2_reg;
+        esc_conf2_reg.val = hw->esc_conf2.val;
+        uhci_esc_conf3_reg_t esc_conf3_reg;
+        esc_conf3_reg.val = hw->esc_conf3.val;
+
+        HAL_FORCE_MODIFY_U32_REG_FIELD(esc_conf2_reg, esc_seq1, sub_ctr->xon_chr);
+        HAL_FORCE_MODIFY_U32_REG_FIELD(esc_conf2_reg, esc_seq1_char0, sub_ctr->xon_sub1);
+        HAL_FORCE_MODIFY_U32_REG_FIELD(esc_conf2_reg, esc_seq1_char1, sub_ctr->xon_sub2);
+        HAL_FORCE_MODIFY_U32_REG_FIELD(esc_conf3_reg, esc_seq2, sub_ctr->xoff_chr);
+        HAL_FORCE_MODIFY_U32_REG_FIELD(esc_conf3_reg, esc_seq2_char0, sub_ctr->xoff_sub1);
+        HAL_FORCE_MODIFY_U32_REG_FIELD(esc_conf3_reg, esc_seq2_char1, sub_ctr->xoff_sub2);
+        escape_conf_reg.tx_11_esc_en = 1;
+        escape_conf_reg.tx_13_esc_en = 1;
+        escape_conf_reg.rx_11_esc_en = 1;
+        escape_conf_reg.rx_13_esc_en = 1;
+        hw->esc_conf2.val = esc_conf2_reg.val;
+        hw->esc_conf3.val = esc_conf3_reg.val;
+    } else {
+        escape_conf_reg.tx_11_esc_en = 0;
+        escape_conf_reg.tx_13_esc_en = 0;
+        escape_conf_reg.rx_11_esc_en = 0;
+        escape_conf_reg.rx_13_esc_en = 0;
+    }
+    hw->escape_conf.val = escape_conf_reg.val;
+}
+
+/**
+ * @brief Enable UHCI interrupt
+ *
+ * @param hw Pointer to the UHCI device
+ * @param intr_mask The interrupt mask to enable
+ */
+static inline void uhci_ll_enable_intr(uhci_dev_t *hw, uint32_t intr_mask)
+{
+    hw->int_ena.val |= intr_mask;
+}
+
+/**
+ * @brief Disable UHCI interrupt
+ *
+ * @param hw Pointer to the UHCI device
+ * @param intr_mask The interrupt mask to disable
+ */
+static inline void uhci_ll_disable_intr(uhci_dev_t *hw, uint32_t intr_mask)
+{
+    hw->int_ena.val &= (~intr_mask);
+}
+
+/**
+ * @brief Clear UHCI interrupt
+ *
+ * @param hw Pointer to the UHCI device
+ * @param intr_mask The interrupt mask to clear
+ */
+static inline void uhci_ll_clear_intr(uhci_dev_t *hw, uint32_t intr_mask)
+{
+    hw->int_clr.val = intr_mask;
+}
+
+/**
+ * @brief Get UHCI interrupt masked status
+ *
+ * @param hw Pointer to the UHCI device
+ * @return The interrupt masked status
+ */
+static inline uint32_t uhci_ll_get_intr(uhci_dev_t *hw)
+{
+    return hw->int_st.val;
+}
+
+/**
+ * @brief Set the EOF mode for payload receive
+ *
+ * @param hw Pointer to the UHCI device
+ * @param eof_mode The EOF mode to set. The following modes are supported:
+ * - UHCI_RX_BREAK_CHR_EOF: UHCI will end payload receive process when NULL frame is received by UART.
+ * - UHCI_RX_IDLE_EOF: UHCI will end payload receive process when UART has been in idle state.
+ * - UHCI_RX_LEN_EOF: UHCI will end payload receive process when the receiving byte count has reached the specific value.
+ */
+static inline void uhci_ll_rx_set_eof_mode(uhci_dev_t *hw, uint32_t eof_mode)
+{
+    if (eof_mode & UHCI_RX_BREAK_CHR_EOF) {
+        hw->conf0.uart_rx_brk_eof_en = 1;
+    }
+    if (eof_mode & UHCI_RX_IDLE_EOF) {
+        hw->conf0.uart_idle_eof_en = 1;
+    }
+    if (eof_mode & UHCI_RX_LEN_EOF) {
+        hw->conf0.len_eof_en = 1;
+    }
+}
+
+/**
+ * @brief Set the packet threshold (maximum value of the packet length)
+ *
+ * @param hw Pointer to the UHCI device
+ * @param length Measurement unit: byte.
+ */
+static inline void uhci_ll_rx_set_packet_threshold(uhci_dev_t *hw, uint16_t length)
+{
+    hw->pkt_thres.pkt_thrs = length;
+}
+
+#ifdef __cplusplus
+}
+#endif

components/soc/esp32s31/include/soc/Kconfig.soc_caps.in

@@ -15,6 +15,10 @@ config SOC_GDMA_SUPPORTED
     bool
     default y
 
+config SOC_UHCI_SUPPORTED
+    bool
+    default y
+
 config SOC_AHB_GDMA_SUPPORTED
     bool
     default y

components/soc/esp32s31/include/soc/soc_caps.h

@@ -28,7 +28,7 @@
 #define SOC_DEDICATED_GPIO_SUPPORTED    1
 #define SOC_UART_SUPPORTED              1
 #define SOC_GDMA_SUPPORTED              1
-// #define SOC_UHCI_SUPPORTED              1      // TODO: [ESP32S31] IDF-14791
+#define SOC_UHCI_SUPPORTED              1
 #define SOC_AHB_GDMA_SUPPORTED          1
 #define SOC_AXI_GDMA_SUPPORTED          1
 #define SOC_LP_AHB_GDMA_SUPPORTED       1

components/soc/esp32s31/register/soc/uhci_struct.h

@@ -1,5 +1,5 @@
 /**
- * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ * SPDX-FileCopyrightText: 2025-2026 Espressif Systems (Shanghai) CO LTD
  *
  *  SPDX-License-Identifier: Apache-2.0 OR MIT
  */
@@ -315,187 +315,31 @@ typedef union {
     uint32_t val;
 } uhci_quick_sent_reg_t;
 
-/** Type of reg_q0_word0 register
+/** Type of reg_qn_word0 register
- *  Q0 WORD0 quick send register
+ *  a
  */
 typedef union {
     struct {
-        /** send_q0_word0 : R/W; bitpos: [31:0]; default: 0;
+        /** send_word0 : R/W; bitpos: [31:0]; default: 0;
-         *  Data to be transmitted in Q0 register.
+         *  a
          */
-        uint32_t send_q0_word0:32;
+        uint32_t send_word0:32;
     };
     uint32_t val;
-} uhci_reg_q0_word0_reg_t;
+} uhci_reg_qn_word0_reg_t;
 
-/** Type of reg_q0_word1 register
+/** Type of reg_qn_word1 register
- *  Q0 WORD1 quick send register
+ *  a
  */
 typedef union {
     struct {
-        /** send_q0_word1 : R/W; bitpos: [31:0]; default: 0;
+        /** send_word1 : R/W; bitpos: [31:0]; default: 0;
-         *  Data to be transmitted in Q0 register.
+         *  a
          */
-        uint32_t send_q0_word1:32;
+        uint32_t send_word1:32;
     };
     uint32_t val;
-} uhci_reg_q0_word1_reg_t;
+} uhci_reg_qn_word1_reg_t;
-
-/** Type of reg_q1_word0 register
- *  Q1 WORD0 quick send register
- */
-typedef union {
-    struct {
-        /** send_q1_word0 : R/W; bitpos: [31:0]; default: 0;
-         *  Data to be transmitted in Q1 register.
-         */
-        uint32_t send_q1_word0:32;
-    };
-    uint32_t val;
-} uhci_reg_q1_word0_reg_t;
-
-/** Type of reg_q1_word1 register
- *  Q1 WORD1 quick send register
- */
-typedef union {
-    struct {
-        /** send_q1_word1 : R/W; bitpos: [31:0]; default: 0;
-         *  Data to be transmitted in Q1 register.
-         */
-        uint32_t send_q1_word1:32;
-    };
-    uint32_t val;
-} uhci_reg_q1_word1_reg_t;
-
-/** Type of reg_q2_word0 register
- *  Q2 WORD0 quick send register
- */
-typedef union {
-    struct {
-        /** send_q2_word0 : R/W; bitpos: [31:0]; default: 0;
-         *  Data to be transmitted in Q2 register.
-         */
-        uint32_t send_q2_word0:32;
-    };
-    uint32_t val;
-} uhci_reg_q2_word0_reg_t;
-
-/** Type of reg_q2_word1 register
- *  Q2 WORD1 quick send register
- */
-typedef union {
-    struct {
-        /** send_q2_word1 : R/W; bitpos: [31:0]; default: 0;
-         *  Data to be transmitted in Q2 register.
-         */
-        uint32_t send_q2_word1:32;
-    };
-    uint32_t val;
-} uhci_reg_q2_word1_reg_t;
-
-/** Type of reg_q3_word0 register
- *  Q3 WORD0 quick send register
- */
-typedef union {
-    struct {
-        /** send_q3_word0 : R/W; bitpos: [31:0]; default: 0;
-         *  Data to be transmitted in Q3 register.
-         */
-        uint32_t send_q3_word0:32;
-    };
-    uint32_t val;
-} uhci_reg_q3_word0_reg_t;
-
-/** Type of reg_q3_word1 register
- *  Q3 WORD1 quick send register
- */
-typedef union {
-    struct {
-        /** send_q3_word1 : R/W; bitpos: [31:0]; default: 0;
-         *  Data to be transmitted in Q3 register.
-         */
-        uint32_t send_q3_word1:32;
-    };
-    uint32_t val;
-} uhci_reg_q3_word1_reg_t;
-
-/** Type of reg_q4_word0 register
- *  Q4 WORD0 quick send register
- */
-typedef union {
-    struct {
-        /** send_q4_word0 : R/W; bitpos: [31:0]; default: 0;
-         *  Data to be transmitted in Q4 register.
-         */
-        uint32_t send_q4_word0:32;
-    };
-    uint32_t val;
-} uhci_reg_q4_word0_reg_t;
-
-/** Type of reg_q4_word1 register
- *  Q4 WORD1 quick send register
- */
-typedef union {
-    struct {
-        /** send_q4_word1 : R/W; bitpos: [31:0]; default: 0;
-         *  Data to be transmitted in Q4 register.
-         */
-        uint32_t send_q4_word1:32;
-    };
-    uint32_t val;
-} uhci_reg_q4_word1_reg_t;
-
-/** Type of reg_q5_word0 register
- *  Q5 WORD0 quick send register
- */
-typedef union {
-    struct {
-        /** send_q5_word0 : R/W; bitpos: [31:0]; default: 0;
-         *  Data to be transmitted in Q5 register.
-         */
-        uint32_t send_q5_word0:32;
-    };
-    uint32_t val;
-} uhci_reg_q5_word0_reg_t;
-
-/** Type of reg_q5_word1 register
- *  Q5 WORD1 quick send register
- */
-typedef union {
-    struct {
-        /** send_q5_word1 : R/W; bitpos: [31:0]; default: 0;
-         *  Data to be transmitted in Q5 register.
-         */
-        uint32_t send_q5_word1:32;
-    };
-    uint32_t val;
-} uhci_reg_q5_word1_reg_t;
-
-/** Type of reg_q6_word0 register
- *  Q6 WORD0 quick send register
- */
-typedef union {
-    struct {
-        /** send_q6_word0 : R/W; bitpos: [31:0]; default: 0;
-         *  Data to be transmitted in Q6 register.
-         */
-        uint32_t send_q6_word0:32;
-    };
-    uint32_t val;
-} uhci_reg_q6_word0_reg_t;
-
-/** Type of reg_q6_word1 register
- *  Q6 WORD1 quick register
- */
-typedef union {
-    struct {
-        /** send_q6_word1 : R/W; bitpos: [31:0]; default: 0;
-         *  Data to be transmitted in Q6 register.
-         */
-        uint32_t send_q6_word1:32;
-    };
-    uint32_t val;
-} uhci_reg_q6_word1_reg_t;
 
 /** Type of esc_conf0 register
  *  Escape sequence configuration register 0
@@ -861,7 +705,7 @@ typedef union {
 } uhci_date_reg_t;
 
 
-typedef struct {
+typedef struct uhci_dev_t {
     volatile uhci_conf0_reg_t conf0;
     volatile uhci_int_raw_reg_t int_raw;
     volatile uhci_int_st_reg_t int_st;
@@ -875,20 +719,10 @@ typedef struct {
     volatile uhci_ack_num_reg_t ack_num;
     volatile uhci_rx_head_reg_t rx_head;
     volatile uhci_quick_sent_reg_t quick_sent;
-    volatile uhci_reg_q0_word0_reg_t reg_q0_word0;
+    volatile struct {
-    volatile uhci_reg_q0_word1_reg_t reg_q0_word1;
+        uhci_reg_qn_word0_reg_t word0;
-    volatile uhci_reg_q1_word0_reg_t reg_q1_word0;
+        uhci_reg_qn_word1_reg_t word1;
-    volatile uhci_reg_q1_word1_reg_t reg_q1_word1;
+    } q_data[7];
-    volatile uhci_reg_q2_word0_reg_t reg_q2_word0;
-    volatile uhci_reg_q2_word1_reg_t reg_q2_word1;
-    volatile uhci_reg_q3_word0_reg_t reg_q3_word0;
-    volatile uhci_reg_q3_word1_reg_t reg_q3_word1;
-    volatile uhci_reg_q4_word0_reg_t reg_q4_word0;
-    volatile uhci_reg_q4_word1_reg_t reg_q4_word1;
-    volatile uhci_reg_q5_word0_reg_t reg_q5_word0;
-    volatile uhci_reg_q5_word1_reg_t reg_q5_word1;
-    volatile uhci_reg_q6_word0_reg_t reg_q6_word0;
-    volatile uhci_reg_q6_word1_reg_t reg_q6_word1;
     volatile uhci_esc_conf0_reg_t esc_conf0;
     volatile uhci_esc_conf1_reg_t esc_conf1;
     volatile uhci_esc_conf2_reg_t esc_conf2;
@@ -897,6 +731,7 @@ typedef struct {
     volatile uhci_date_reg_t date;
 } uhci_dev_t;
 
+extern uhci_dev_t UHCI0;
 
 #ifndef __cplusplus
 _Static_assert(sizeof(uhci_dev_t) == 0x84, "Invalid size of uhci_dev_t structure");

examples/peripherals/.build-test-rules.yml

@@ -778,7 +778,7 @@ examples/peripherals/uart/uart_dma_ota:
   disable:
     - if: SOC_UHCI_SUPPORTED != 1
   disable_test:
-    - if: IDF_TARGET in ["esp32p4", "esp32c5"]
+    - if: IDF_TARGET in ["esp32p4", "esp32s31"]
       temporary: true
       reason: Lack runners
   depends_components:

examples/peripherals/uart/uart_dma_ota/README.md

@@ -1,5 +1,5 @@
-| Supported Targets | ESP32-C3 | ESP32-C5 | ESP32-C6 | ESP32-H2 | ESP32-H21 | ESP32-H4 | ESP32-P4 | ESP32-S3 |
+| Supported Targets | ESP32-C3 | ESP32-C5 | ESP32-C6 | ESP32-H2 | ESP32-H21 | ESP32-H4 | ESP32-P4 | ESP32-S3 | ESP32-S31 |
-| ----------------- | -------- | -------- | -------- | -------- | --------- | -------- | -------- | -------- |
+| ----------------- | -------- | -------- | -------- | -------- | --------- | -------- | -------- | -------- | --------- |
 
 # UART OTA Example
 

examples/peripherals/uart/uart_dma_ota/pytest_uart_dma_ota.py

@@ -42,7 +42,7 @@ def send_file_via_uart(port: str, baud_rate: int, file_path: str, packet_size: i
     ],
     indirect=True,
 )
-@idf_parametrize('target', ['esp32c6', 'esp32c3', 'esp32s3', 'esp32h2'], indirect=['target'])
+@idf_parametrize('target', ['esp32c6', 'esp32c3', 'esp32c5', 'esp32s3', 'esp32h2'], indirect=['target'])
 def test_uart_dma_ota(dut: Dut) -> None:
     dut.expect_exact('uhci-example: OTA process started')
     # We OTA the same binary to another partition and switch to there.

examples/peripherals/uart/uart_dma_ota/sdkconfig.ci.defaults.esp32c5

@@ -0,0 +1,2 @@
+CONFIG_IDF_TARGET="esp32c5"
+CONFIG_UART_RX_IO=12