feat(uhci): Add uhci (uart-dma) support on esp32c3, esp32c6, esp32s3, esp32p4

Author: mythbuster5

components/esp_driver_uart/CMakeLists.txt

@@ -4,12 +4,16 @@ set(srcs)
 set(public_include "include")
 if(CONFIG_SOC_UART_SUPPORTED)
     list(APPEND srcs "src/uart.c" "src/uart_wakeup.c")
+    if(CONFIG_SOC_UHCI_SUPPORTED)
+        list(APPEND srcs "src/uhci.c")
+    endif()
 endif()
 
+
 if(${target} STREQUAL "linux")
     set(priv_requires esp_ringbuf)
 else()
-    set(priv_requires esp_pm esp_driver_gpio esp_ringbuf)
+    set(priv_requires esp_pm esp_driver_gpio esp_ringbuf esp_mm)
 endif()
 
 idf_component_register(

components/esp_driver_uart/Kconfig

@@ -10,3 +10,31 @@ menu "ESP-Driver:UART Configurations"
             may cause data lost when doing spi flash operation.
 
 endmenu
+
+menu "ESP-Driver:UHCI Configurations"
+
+    config UHCI_ISR_HANDLER_IN_IRAM
+        bool "Place UHCI ISR function into IRAM"
+        default n
+        help
+            If this option is not selected, UHCI interrupt will be disabled for a long time and
+            may cause data lost when doing spi flash operation.
+
+    config UHCI_ISR_CACHE_SAFE
+        bool "Allow UHCI ISR to execute when cache is disabled" if !SPI_FLASH_AUTO_SUSPEND
+        select UHCI_ISR_HANDLER_IN_IRAM
+        select GDMA_ISR_HANDLER_IN_IRAM if SOC_GDMA_SUPPORTED
+        default n
+        help
+            Enable this option to allow the ISR for UHCI to execute even when the cache is disabled.
+            This can be useful in scenarios where the cache might be turned off, but the UHCI
+            functionality is still required to operate correctly.
+
+    config UHCI_ENABLE_DEBUG_LOG
+        bool "Enable debug log"
+        default n
+        help
+            whether to enable the debug log message for UHCI driver.
+            Note that, this option only controls the UHCI driver log, won't affect other drivers.
+
+endmenu

components/esp_driver_uart/include/driver/uhci.h

@@ -0,0 +1,161 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include "esp_err.h"
+#include "freertos/FreeRTOS.h"
+#include "freertos/queue.h"
+#include "driver/uhci_types.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief UHCI controller specific configurations
+ */
+typedef struct {
+    uart_port_t uart_port;                                /*!< UART port that connect to UHCI controller */
+    size_t tx_trans_queue_depth;                          /*!< Depth of internal transfer queue, increase this value can support more transfers pending in the background */
+    size_t max_transmit_size;                             /*!< Maximum transfer size in one transaction, in bytes. This decides the number of DMA nodes will be used for each transaction */
+    size_t max_receive_internal_mem;                      /*!< Maximum transfer size in one transaction, in bytes. Each DMA node can point to a maximum of 4096 bytes. This value determines the number of DMA nodes used for each transaction. When your transfer size is large enough, it is recommended to set this value greater than 4096 to facilitate efficient ping-pong operations, such as 10 * 1024. */
+    size_t dma_burst_size;                                /*!< DMA burst size, in bytes */
+
+    struct {
+        uint16_t rx_brk_eof: 1;                           /*!< UHCI will end payload receive process when NULL frame is received by UART. */
+        uint16_t idle_eof: 1;                             /*!< UHCI will end payload receive process when UART has been in idle state. */
+        uint16_t length_eof: 1;                           /*!< UHCI will end payload receive process when the receiving byte count has reached the specific value. */
+    } rx_eof_flags;                                       /*!< UHCI eof flags */
+} uhci_controller_config_t;
+
+/**
+ * @brief Structure for defining callback functions for UHCI events.
+ */
+typedef struct {
+    uhci_rx_event_callback_t on_rx_trans_event;           /*!< Callback function for handling the completion of a reception. */
+    uhci_tx_done_callback_t on_tx_trans_done;             /*!< Callback function for handling the completion of a transmission. */
+} uhci_event_callbacks_t;
+
+/**
+ * @brief Create and initialize a new UHCI controller.
+ *
+ * This function initializes a new UHCI controller instance based on the provided configuration.
+ * It allocates and configures resources required for the UHCI controller, such as DMA and
+ * communication settings. The created controller handle is returned through the output parameter.
+ *
+ * @param[in] config       Pointer to a `uhci_controller_config_t` structure containing the
+ *                         configuration parameters for the UHCI controller.
+ * @param[out] ret_uhci_ctrl   Pointer to a variable where the handle to the newly created UHCI controller
+ *                         will be stored. This handle is used in subsequent operations involving the
+ *                         controller.
+ *
+ * @return
+ * - `ESP_OK`: Controller successfully created and initialized.
+ * - `ESP_ERR_INVALID_ARG`: One or more arguments are invalid (e.g., null pointers or invalid config).
+ * - `ESP_ERR_NO_MEM`: Memory allocation for the controller failed.
+ * - Other error codes: Indicate failure in the underlying hardware or driver initialization.
+ */
+esp_err_t uhci_new_controller(const uhci_controller_config_t *config, uhci_controller_handle_t *ret_uhci_ctrl);
+
+/**
+ * @brief Receive data from the UHCI controller.
+ *
+ * This function retrieves data from the UHCI controller into the provided buffer. It is typically
+ * used for receiving data that was transmitted via UART and processed by the UHCI DMA controller.
+ *
+ * @param[in] uhci_ctrl       Handle to the UHCI controller, which was previously created using
+ *                            `uhci_new_controller()`.
+ * @param[out] read_buffer    Pointer to the buffer where the received data will be stored.
+ *                            The buffer must be pre-allocated by the caller.
+ * @param[in] buffer_size     The size of read buffer.
+ *
+ * @note @note The function is non-blocking, it just mounts the user buffer to the DMA.
+ * The return from the function doesn't mean a finished receive. You need to register corresponding
+ * callback function to get notification.
+ *
+ * @return
+ * - `ESP_OK`: Data successfully received and written to the buffer.
+ * - `ESP_ERR_INVALID_ARG`: Invalid arguments (e.g., null buffer or invalid controller handle).
+ */
+esp_err_t uhci_receive(uhci_controller_handle_t uhci_ctrl, uint8_t *read_buffer, size_t buffer_size);
+
+/**
+ * @brief Transmit data using the UHCI controller.
+ *
+ * This function sends data from the provided buffer through the UHCI controller. It uses the DMA
+ * capabilities of UHCI to efficiently handle data transmission via UART.
+ *
+ * @param[in] uhci_ctrl     Handle to the UHCI controller, which was previously created using
+ *                          `uhci_new_controller()`.
+ * @param[in] write_buffer  Pointer to the buffer containing the data to be transmitted.
+ *                          The buffer must remain valid until the transmission is complete.
+ * @param[in] write_size    The number of bytes to transmit from the buffer.
+ *
+ * @note The function is an non-blocking api, which means this function will return immediately. You can
+ * get corresponding event from callbacks.
+ *
+ * @return
+ * - `ESP_OK`: Data successfully queued for transmission.
+ * - `ESP_ERR_INVALID_ARG`: Invalid arguments (e.g., null buffer, invalid handle, or zero `write_size`).
+ */
+esp_err_t uhci_transmit(uhci_controller_handle_t uhci_ctrl, uint8_t *write_buffer, size_t write_size);
+
+/**
+ * @brief Uninstall the UHCI (UART Host Controller Interface) driver and release resources.
+ *
+ * This function deinitializes the UHCI controller and frees any resources allocated during its
+ * initialization. It ensures proper cleanup and prevents resource leaks when the UHCI controller
+ * is no longer needed.
+ *
+ * @param[in] uhci_ctrl   Handle to the UHCI controller, which was previously created using
+ *                        `uhci_new_controller()`. Passing an invalid or uninitialized handle
+ *                        may result in undefined behavior.
+ *
+ * @return
+ * - `ESP_OK`: The UHCI driver was successfully uninstalled, and resources were released.
+ * - `ESP_ERR_INVALID_ARG`: The provided `uhci_ctrl` handle is invalid or null.
+ */
+esp_err_t uhci_del_controller(uhci_controller_handle_t uhci_ctrl);
+
+/**
+ * @brief Register event callback functions for a UHCI controller.
+ *
+ * This function allows the user to register callback functions to handle specific UHCI events, such as
+ * transmission or reception completion. The callbacks provide a mechanism to handle asynchronous events
+ * generated by the UHCI controller.
+ *
+ * @param[in] uhci_ctrl   Handle to the UHCI controller, which was previously created using
+ *                        `uhci_new_controller()`.
+ * @param[in] cbs         Pointer to a `uhci_event_callbacks_t` structure that defines the callback
+ *                        functions to be registered. This structure includes pointers to the callback
+ *                        functions for handling UHCI events.
+ * @param[in] user_data   Pointer to user-defined data that will be passed to the callback functions
+ *                        when they are invoked. This can be used to provide context or state information
+ *                        specific to the application.
+ *
+ * @return
+ * - `ESP_OK`: Event callbacks were successfully registered.
+ * - `ESP_ERR_INVALID_ARG`: Invalid arguments (e.g., null `uhci_ctrl` handle or `cbs` pointer).
+ */
+esp_err_t uhci_register_event_callbacks(uhci_controller_handle_t uhci_ctrl, const uhci_event_callbacks_t *cbs, void *user_data);
+
+/**
+ * @brief Wait for all pending TX transactions done
+ *
+ * @param[in] uhci_ctrl UHCI controller that created by `uhci_new_controller`
+ * @param[in] timeout_ms Timeout in milliseconds, `-1` means to wait forever
+ * @return
+ *      - ESP_OK: All pending TX transactions is finished and recycled
+ *      - ESP_ERR_INVALID_ARG: Wait for all pending TX transactions done failed because of invalid argument
+ *      - ESP_ERR_TIMEOUT: Wait for all pending TX transactions done timeout
+ *      - ESP_FAIL: Wait for all pending TX transactions done failed because of other error
+ */
+esp_err_t uhci_wait_all_tx_transaction_done(uhci_controller_handle_t uhci_ctrl, int timeout_ms);
+
+#ifdef __cplusplus
+}
+#endif

components/esp_driver_uart/include/driver/uhci_types.h

@@ -0,0 +1,73 @@
+/*
+ * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include <stdint.h>
+#include <stdbool.h>
+#include <stdlib.h>
+#include <stddef.h>
+#include "hal/uart_types.h"
+#include "hal/uhci_types.h"
+#include "soc/soc_caps.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * @brief UHCI Controller Handle Type
+ */
+typedef struct uhci_controller_t *uhci_controller_handle_t;
+
+/**
+ * @brief UHCI TX Done Event Data
+ */
+typedef struct {
+    uint8_t *buffer;            /**< Pointer to the which data buffer has been finished the transaction */
+    size_t sent_size;           /**< Size has been sent out */
+} uhci_tx_done_event_data_t;
+
+/**
+ * @brief UHCI TX Done Callback Function Type
+ * @param uhci_ctrl Handle to the UHCI controller that initiated the transmission.
+ * @param edata Pointer to a structure containing event data related to the completed transmission.
+ *              This structure provides details such as the number of bytes transmitted and any
+ *              status information relevant to the operation.
+ * @param user_ctx User-defined context passed during the callback registration.
+ *                 It can be used to maintain application-specific state or data.
+ *
+ * @return Whether a high priority task has been waken up by this callback function
+ */
+typedef bool (*uhci_tx_done_callback_t)(uhci_controller_handle_t uhci_ctrl, const uhci_tx_done_event_data_t *edata, void *user_ctx);
+
+/**
+ * @brief UHCI RX Done Event Data Structure
+ */
+typedef struct {
+    uint8_t *data;                 /*!< Pointer to the received data buffer */
+    size_t recv_size;              /*!< Number of bytes received */
+    struct {
+        uint32_t totally_received: 1;     /*!< When callback is invoked, while this bit is not set, means the current event gives partial of whole data, the transaction has not been finished. If set, means the current event gives whole data, the transaction finished. */
+    } flags;                       /*!< I2C master config flags */
+} uhci_rx_event_data_t;
+
+/**
+ * @brief UHCI RX Done Callback Function Type
+ * @param uhci_ctrl Handle to the UHCI controller that initiated the transmission.
+ * @param edata Pointer to a structure containing event data related to receive event.
+ *              This structure provides details such as the number of bytes received and any
+ *              status information relevant to the operation.
+ * @param user_ctx User-defined context passed during the callback registration.
+ *                 It can be used to maintain application-specific state or data.
+ *
+ * @return Whether a high priority task has been waken up by this callback function
+ */
+typedef bool (*uhci_rx_event_callback_t)(uhci_controller_handle_t uhci_ctrl, const uhci_rx_event_data_t *edata, void *user_ctx);
+
+#ifdef __cplusplus
+}
+#endif

components/esp_driver_uart/linker.lf

@@ -9,3 +9,20 @@ archive: libhal.a
 entries:
     if UART_ISR_IN_IRAM = y:
         uart_hal_iram (noflash)
+
+[mapping:uhci]
+archive: libesp_driver_uart.a
+entries:
+    if UHCI_ISR_HANDLER_IN_IRAM = y:
+        uhci: uhci_gdma_rx_callback_done (noflash)
+        uhci: uhci_gdma_tx_callback_eof (noflash)
+        uhci: uhci_do_transmit (noflash)
+
+[mapping:uhci_driver_gdma]
+archive: libesp_hw_support.a
+entries:
+    if UHCI_ISR_HANDLER_IN_IRAM = y:
+        gdma_link: gdma_link_count_buffer_size_till_eof (noflash)
+        gdma_link: gdma_link_mount_buffers (noflash)
+        gdma_link: gdma_link_get_head_addr (noflash)
+        gdma: gdma_start (noflash)