uart: Add a new API to get the free space size of tx buffer

Closes espressif#8932 Closes espressif#3078
ebisuke · Jul 5, 2022 · 9d73475 · 9d73475
1 parent 7ed45a9
commit 9d73475
Show file tree

Hide file tree

Showing 3 changed files with 30 additions and 0 deletions.
diff --git a/components/driver/include/driver/uart.h b/components/driver/include/driver/uart.h
@@ -566,6 +566,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
@@ -349,8 +349,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
@@ -1281,6 +1281,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)