From 2bf73b363d6acf0bacd0818c21da6d673a7ff23c Mon Sep 17 00:00:00 2001
From: songruojing <songruojing@espressif.com>
Date: Wed, 29 Jun 2022 17:56:38 +0800
Subject: [PATCH] uart: Add a new API to get the free space size of tx buffer

Closes https://github.com/espressif/esp-idf/issues/8932

Closes https://github.com/espressif/esp-idf/issues/3078

(cherry picked from commit 9d73475e44b08db4f648957496426c3d4d6b02ef)
---
 components/driver/include/driver/uart.h | 12 ++++++++++++
 components/driver/test/test_uart.c      |  9 +++++++++
 components/driver/uart.c                |  9 +++++++++
 3 files changed, 30 insertions(+)

diff --git a/components/driver/include/driver/uart.h b/components/driver/include/driver/uart.h
index 4524516338b9..f0c2ae101322 100644
--- a/components/driver/include/driver/uart.h
+++ b/components/driver/include/driver/uart.h
@@ -594,6 +594,18 @@ esp_err_t uart_flush_input(uart_port_t uart_num);
  */
 esp_err_t uart_get_buffered_data_len(uart_port_t uart_num, size_t* size);
 
+/**
+ * @brief   UART get TX ring buffer free space size
+ *
+ * @param   uart_num UART port number, the max port number is (UART_NUM_MAX -1).
+ * @param   size Pointer of size_t to accept the free space size
+ *
+ * @return
+ *     - ESP_OK Success
+ *     - ESP_ERR_INVALID_ARG Parameter error
+ */
+esp_err_t uart_get_tx_buffer_free_size(uart_port_t uart_num, size_t *size);
+
 /**
  * @brief   UART disable pattern detect function.
  *          Designed for applications like 'AT commands'.
diff --git a/components/driver/test/test_uart.c b/components/driver/test/test_uart.c
index 571d3d097226..62626f82258b 100644
--- a/components/driver/test/test_uart.c
+++ b/components/driver/test/test_uart.c
@@ -353,8 +353,17 @@ TEST_CASE("uart tx with ringbuffer test", "[uart]")
         wr_data[i] = i;
         rd_data[i] = 0;
     }
+
+    size_t tx_buffer_free_space;
+    uart_get_tx_buffer_free_size(uart_num, &tx_buffer_free_space);
+    TEST_ASSERT_EQUAL_INT(2048, tx_buffer_free_space); // full tx buffer space is free
     uart_write_bytes(uart_num, (const char*)wr_data, 1024);
+    uart_get_tx_buffer_free_size(uart_num, &tx_buffer_free_space);
+    TEST_ASSERT_LESS_THAN(2048, tx_buffer_free_space); // tx transmit in progress: tx buffer has content
+    TEST_ASSERT_GREATER_OR_EQUAL(1024, tx_buffer_free_space);
     uart_wait_tx_done(uart_num, (TickType_t)portMAX_DELAY);
+    uart_get_tx_buffer_free_size(uart_num, &tx_buffer_free_space);
+    TEST_ASSERT_EQUAL_INT(2048, tx_buffer_free_space); // tx done: tx buffer back to empty
     uart_read_bytes(uart_num, rd_data, 1024, (TickType_t)1000);
     TEST_ASSERT_EQUAL_HEX8_ARRAY(wr_data, rd_data, 1024);
     TEST_ESP_OK(uart_driver_delete(uart_num));
diff --git a/components/driver/uart.c b/components/driver/uart.c
index dda1f3b69ab4..b0d80f62050e 100644
--- a/components/driver/uart.c
+++ b/components/driver/uart.c
@@ -1343,6 +1343,15 @@ esp_err_t uart_get_buffered_data_len(uart_port_t uart_num, size_t *size)
     return ESP_OK;
 }
 
+esp_err_t uart_get_tx_buffer_free_size(uart_port_t uart_num, size_t *size)
+{
+    ESP_RETURN_ON_FALSE((uart_num < UART_NUM_MAX), ESP_ERR_INVALID_ARG, UART_TAG, "uart_num error");
+    ESP_RETURN_ON_FALSE((p_uart_obj[uart_num]), ESP_ERR_INVALID_ARG, UART_TAG, "uart driver error");
+    ESP_RETURN_ON_FALSE((size != NULL), ESP_ERR_INVALID_ARG, UART_TAG, "arg pointer is NULL");
+    *size = p_uart_obj[uart_num]->tx_buf_size - p_uart_obj[uart_num]->tx_len_tot;
+    return ESP_OK;
+}
+
 esp_err_t uart_flush(uart_port_t uart_num) __attribute__((alias("uart_flush_input")));
 
 esp_err_t uart_flush_input(uart_port_t uart_num)