feat: Add UART support

This commit adds support for UART with interrupt possibility and
helper functions especially for RX path

Author: Dzarda7

.check_copyright_config.yaml

@@ -18,3 +18,4 @@ ignore:
   include:
     - src/target/*/ld/*.ld
     - example/ld/*.ld
+    - src/target/*/include/soc/uart_reg.h

README.md

@@ -31,6 +31,10 @@ A complete example project is provided in the [example](example/) directory. It
 
 See the [example README](example/README.md) for build instructions.
 
+## Function Naming Conventions
+
+Functions that contain `rominit` (e.g., `stub_target_uart_rominit_intr_attach`) require ROM preinitialization by entering download mode to work correctly. These functions are simplified compared to full implementation and expect some initialization done by ROM. They should only be called in contexts where the ROM download mode has been entered.
+
 ## Project Structure
 
 The library uses a three-layer architecture to eliminate circular dependencies and maximize code reuse:

example/stub_main.c

@@ -13,6 +13,7 @@
 #include <esp-stub-lib/flash.h>
 #include <esp-stub-lib/err.h>
 #include <esp-stub-lib/mem_utils.h>
+#include <target/uart.h>
 
 #include "stub_main.h"
 
@@ -37,6 +38,24 @@ static void example_mem_utils(void)
     (void)stub_lib_mem_is_tcm(0x0);
 }
 
+static int handle_test_uart(void)
+{
+    void *uart_rx_interrupt_handler = NULL;
+    stub_target_uart_wait_idle(UART_NUM_0);
+
+    stub_target_uart_init(UART_NUM_0, 115200);
+    stub_target_uart_set_rx_timeout(UART_NUM_0, 10);
+    (void)stub_target_uart_get_rxfifo_count(UART_NUM_0);
+    (void)stub_target_uart_get_intr_flags(UART_NUM_0);
+    (void)stub_target_uart_read_rxfifo_byte(UART_NUM_0);
+    (void)stub_target_uart_rx_one_char();
+    stub_target_uart_rominit_intr_attach(UART_NUM_0, 5, uart_rx_interrupt_handler, UART_INTR_RXFIFO_FULL | UART_INTR_RXFIFO_TOUT);
+    stub_target_uart_tx_one_char('A');
+    stub_target_uart_tx_flush();
+
+    return 0;
+}
+
 static  __attribute__((unused)) int handle_test1(va_list ap)
 {
     (void)ap;

include/esp-stub-lib/rom_wrappers.h

@@ -29,26 +29,6 @@ void stub_lib_delay_us(uint32_t us);
  */
 uint16_t stub_lib_crc16_le(uint16_t crc, const uint8_t *buf, uint32_t len);
 
-/**
- * @brief Transmit a single byte over UART.
- *
- * @param c Byte to transmit.
- * @return 0 if successful, non-zero if error occurred.
- */
-uint8_t stub_lib_uart_tx_one_char(uint8_t c);
-
-/**
- * @brief Receive a single byte (blocking) from UART.
- *
- * @return Received byte.
- */
-uint8_t stub_lib_uart_rx_one_char(void);
-
-/**
- * @brief Flush any buffered transmit data.
- */
-void stub_lib_uart_tx_flush(void);
-
 #ifdef __cplusplus
 }
 #endif // __cplusplus

src/rom_wrappers.c

@@ -7,9 +7,6 @@
 
 extern void ets_delay_us(uint32_t us);
 extern uint16_t crc16_le(uint16_t crc, const uint8_t *buf, uint32_t len);
-extern uint8_t uart_tx_one_char(uint8_t ch);
-extern uint8_t uart_rx_one_char(void);
-extern void uart_tx_flush(void);
 
 void stub_lib_delay_us(uint32_t us)
 {
@@ -20,18 +17,3 @@ uint16_t stub_lib_crc16_le(uint16_t crc, const uint8_t *buf, uint32_t len)
 {
     return crc16_le(crc, buf, len);
 }
-
-uint8_t stub_lib_uart_tx_one_char(uint8_t c)
-{
-    return uart_tx_one_char(c);
-}
-
-uint8_t stub_lib_uart_rx_one_char(void)
-{
-    return uart_rx_one_char();
-}
-
-void stub_lib_uart_tx_flush(void)
-{
-    uart_tx_flush();
-}

src/target/CMakeLists.txt

@@ -10,17 +10,31 @@ add_subdirectory(${ESP_TARGET} ${ESP_TARGET_LIB})
 # Build common library
 add_subdirectory(common ${ESP_COMMON_LIB})
 
+# Get target type to handle both STATIC and INTERFACE libraries
+get_target_property(target_type ${ESP_TARGET_LIB} TYPE)
+
 # Apply common configurations to target library
 # This ensures strong symbols override weak ones
-target_link_options(${ESP_TARGET_LIB}
-    PUBLIC -Wl,--whole-archive
-)
+if(target_type STREQUAL "INTERFACE_LIBRARY")
+    # target_link_options(${ESP_TARGET_LIB}
+    #     INTERFACE -Wl,--whole-archive
+    # )
+
+    target_include_directories(${ESP_TARGET_LIB}
+        INTERFACE ${CMAKE_CURRENT_LIST_DIR}/${ESP_TARGET}/include
+    )
+
+    target_link_libraries(${ESP_TARGET_LIB} INTERFACE ${ESP_BASE_LIB})
+else()
+    target_link_options(${ESP_TARGET_LIB}
+        PUBLIC -Wl,--whole-archive
+    )
+
+    target_include_directories(${ESP_TARGET_LIB}
+        PUBLIC ${CMAKE_CURRENT_LIST_DIR}/${ESP_TARGET}/include
+    )
 
-# Set common include directories for target library
-target_include_directories(${ESP_TARGET_LIB}
-    PUBLIC ${CMAKE_CURRENT_LIST_DIR}/${ESP_TARGET}/include
-)
+    target_link_libraries(${ESP_TARGET_LIB} PUBLIC ${ESP_BASE_LIB})
+endif()
 
-# Setup dependency chain: target → base, common → base + target
-target_link_libraries(${ESP_TARGET_LIB} PUBLIC ${ESP_BASE_LIB})
 target_link_libraries(${ESP_COMMON_LIB} PUBLIC ${ESP_BASE_LIB} ${ESP_TARGET_LIB})

src/target/base/include/target/uart.h

@@ -7,5 +7,126 @@
 #pragma once
 
 #include <stdint.h>
+#include <stdbool.h>
+#include "soc_caps.h"
 
+/**
+ * @brief UART port numbers
+ *
+ * Available UART ports depend on the chip's SOC_UART_HP_NUM capability.
+ */
+typedef enum {
+    UART_NUM_0,                         /*!< UART port 0 */
+    UART_NUM_1,                         /*!< UART port 1 */
+#if SOC_UART_HP_NUM > 2
+    UART_NUM_2,                         /*!< UART port 2 */
+#endif
+#if SOC_UART_HP_NUM > 3
+    UART_NUM_3,                         /*!< UART port 3 */
+#endif
+#if SOC_UART_HP_NUM > 4
+    UART_NUM_4,                         /*!< UART port 4 */
+#endif
+    UART_NUM_MAX,                       /*!< UART port max */
+} uart_port_t;
+
+#define UART_INTR_RXFIFO_FULL      (0x1<<0)
+#define UART_INTR_RXFIFO_TOUT      (0x1<<8)
+
+/**
+ * @brief Wait until UART is idle
+ *
+ * @param uart_num UART port number
+ */
+void stub_target_uart_wait_idle(uint8_t uart_num);
+
+/**
+ * @brief Initialize UART
+ *
+ * @param uart_num UART port number
+ * @param baudrate Baud rate
+ */
 void stub_target_uart_init(uint8_t uart_num, uint32_t baudrate);
+
+/**
+ * @brief Set UART baud rate
+ *
+ * @param uart_num UART port number
+ * @param baudrate Baud rate
+ */
+void stub_target_uart_set_baudrate(uint8_t uart_num, uint32_t baudrate);
+
+/**
+ * @brief Attach interrupt handler to UART and configure interrupts
+ *
+ * @note This function requires ROM preinit (download mode initialization) to work correctly.
+ *       It uses ROM functions (ets_isr_attach, ets_isr_unmask) that are only available
+ *       after the ROM has entered download mode and completed its initialization.
+ *       Functions that contain "rominit" have this requirement.
+ *
+ * @param uart_num UART port number
+ * @param intr_num CPU interrupt source
+ * @param handler Interrupt handler function pointer
+ * @param flags Interrupt enable flags (bitwise OR of UART_INTR_* values)
+ */
+void stub_target_uart_rominit_intr_attach(uint8_t uart_num, int intr_num, void *handler, uint32_t flags);
+
+/**
+ * @brief Get and clear UART interrupt status
+ *
+ * This function returns the interrupt status and automatically clears it.
+ * Call this at the beginning of your interrupt handler.
+ *
+ * @param uart_num UART port number
+ * @return Bitmask of active interrupts that were cleared
+ */
+uint32_t stub_target_uart_get_intr_flags(uint8_t uart_num);
+
+/**
+ * @brief Get number of bytes available in RX FIFO
+ *
+ * @param uart_num UART port number
+ * @return Number of bytes currently in the RX FIFO
+ */
+uint32_t stub_target_uart_get_rxfifo_count(uint8_t uart_num);
+
+/**
+ * @brief Read a single byte from UART RX FIFO
+ *
+ * This function reads one byte from the RX FIFO without checking
+ * if data is available. Call stub_target_uart_get_rxfifo_count()
+ * first to ensure data is available.
+ *
+ * @param uart_num UART port number
+ * @return The byte read from the FIFO
+ */
+uint8_t stub_target_uart_read_rxfifo_byte(uint8_t uart_num);
+
+/**
+ * @brief Configure RX timeout threshold
+ *
+ * @param uart_num UART port number
+ * @param timeout Timeout value in bit times (1-126, 0 to disable)
+ * timeout mean the multiple of UART packets (~11 bytes) that can be received before timeout
+ */
+void stub_target_uart_set_rx_timeout(uint8_t uart_num, uint8_t timeout);
+
+/**
+ * @brief Transmit a single byte over UART.
+ *
+ * @param c Byte to transmit.
+ * @return 0 if successful, non-zero if error occurred.
+ */
+uint8_t stub_target_uart_tx_one_char(uint8_t c);
+
+/**
+ * @brief Receive a single byte (blocking) from UART.
+ *
+ * @return Received byte.
+ */
+uint8_t stub_target_uart_rx_one_char(void);
+
+/**
+ * @brief Flush any buffered transmit data.
+ */
+void stub_target_uart_tx_flush(void);

src/target/common/src/uart.c

@@ -4,12 +4,105 @@
  * SPDX-License-Identifier: Apache-2.0 OR MIT
  */
 
+#include <stdbool.h>
 #include <stdint.h>
 #include <stddef.h>
 #include <target/uart.h>
+#include <target/soc_utils.h>
+#include <soc/uart_reg.h>
+
+extern void ets_update_cpu_frequency(uint32_t ticks_per_us);
+extern void uartAttach(void *rxBuffer);
+extern void Uart_Init(uint8_t uart_no);
+extern uint32_t ets_clk_get_cpu_freq(void);
+extern void uart_tx_switch(uint8_t uart_no);
+extern void uart_tx_wait_idle(uint8_t uart_num);
+extern void uart_div_modify(uint8_t uart_no, uint32_t divisor);
+extern void ets_isr_attach(int int_num, void *handler, void *arg);
+extern void ets_isr_unmask(int int_num);
+extern void uart_tx_flush(void);
+extern uint8_t uart_tx_one_char(uint8_t ch);
+extern uint8_t uart_rx_one_char(void);
+
+void __attribute__((weak)) stub_target_uart_wait_idle(uint8_t uart_num)
+{
+    uart_tx_wait_idle(uart_num);
+}
 
 void __attribute__((weak)) stub_target_uart_init(uint8_t uart_num, uint32_t baudrate)
 {
-    (void)baudrate;
-    (void)uart_num;
+    ets_update_cpu_frequency(ets_clk_get_cpu_freq() / 1000000);
+    uartAttach(NULL);
+    Uart_Init(uart_num);
+    uart_tx_switch(uart_num);
+    stub_target_uart_set_baudrate(uart_num, baudrate);
+}
+
+void __attribute__((weak)) stub_target_uart_set_baudrate(uint8_t uart_num, uint32_t baudrate)
+{
+    uint32_t clock = ets_clk_get_cpu_freq() << 4;
+    uint32_t divisor = clock / baudrate;
+    stub_target_uart_wait_idle(uart_num);
+    uart_div_modify(uart_num, divisor);
+    // TODO: Consider decimal part
+}
+
+void stub_target_uart_rominit_intr_attach(uint8_t uart_num, int intr_num, void *handler, uint32_t flags)
+{
+    // Clear pending interrupt flags
+    WRITE_PERI_REG(UART_INT_CLR_REG(uart_num), 0xFFFFFFFFU);
+
+    ets_isr_attach(intr_num, handler, NULL);
+
+    if (flags != 0U) {
+        SET_PERI_REG_MASK(UART_INT_ENA_REG(uart_num), flags);
+    }
+
+    ets_isr_unmask(1 << intr_num);
+}
+
+uint32_t __attribute__((weak)) stub_target_uart_get_intr_flags(uint8_t uart_num)
+{
+    uint32_t status = READ_PERI_REG(UART_INT_ST_REG(uart_num));
+    // Clear the interrupts
+    WRITE_PERI_REG(UART_INT_CLR_REG(uart_num), status);
+    return status;
+}
+
+uint32_t __attribute__((weak)) stub_target_uart_get_rxfifo_count(uint8_t uart_num)
+{
+    uint32_t status = READ_PERI_REG(UART_STATUS_REG(uart_num));
+    return (status >> UART_RXFIFO_CNT_S) & UART_RXFIFO_CNT_V;
+}
+
+uint8_t __attribute__((weak)) stub_target_uart_read_rxfifo_byte(uint8_t uart_num)
+{
+    return (uint8_t)(READ_PERI_REG(UART_FIFO_REG(uart_num)) & UART_RXFIFO_RD_BYTE_V);
+}
+
+void __attribute__((weak)) stub_target_uart_set_rx_timeout(uint8_t uart_num, uint8_t timeout)
+{
+    uint32_t conf1 = READ_PERI_REG(UART_CONF1_REG(uart_num));
+    conf1 &= ~(UART_RX_TOUT_THRHD_M | UART_RX_TOUT_EN_M);
+
+    if (timeout > 0U) {
+        conf1 |= (((uint32_t)timeout & UART_RX_TOUT_THRHD_V) << UART_RX_TOUT_THRHD_S) | UART_RX_TOUT_EN;
+    }
+
+    WRITE_PERI_REG(UART_CONF1_REG(uart_num), conf1);
+}
+
+uint8_t stub_target_uart_tx_one_char(uint8_t c)
+{
+    return uart_tx_one_char(c);
+}
+
+uint8_t stub_target_uart_rx_one_char(void)
+{
+    return uart_rx_one_char();
+}
+
+void __attribute__((weak)) stub_target_uart_tx_flush(void)
+{
+    uart_tx_flush();
 }

src/target/esp32/CMakeLists.txt

@@ -7,6 +7,7 @@ add_library(${ESP_TARGET_LIB} STATIC ${srcs})
 
 target_link_options(${ESP_TARGET_LIB}
     PUBLIC -T${CMAKE_CURRENT_LIST_DIR}/ld/esp32.rom.ld
+    PUBLIC -T${CMAKE_CURRENT_LIST_DIR}/ld/esp32.rom.redefined.ld
     PUBLIC -T${CMAKE_CURRENT_LIST_DIR}/ld/esp32.rom.libc-funcs.ld
     PUBLIC -T${CMAKE_CURRENT_LIST_DIR}/ld/esp32.rom.libgcc.ld
 )