ESP32 UART buffering of received data

[Siddle34]

If we look in uart.c, which I think I'm correct in saying lives in the ESP-IDF API layer underlying the Arduino-esp32 API, we find functions like:

Code: Select all

esp_err_t uart_get_buffered_data_len(uart_port_t uart_num, size_t *size)
{
    ESP_RETURN_ON_FALSE((uart_num < UART_NUM_MAX), ESP_FAIL, UART_TAG, "uart_num error");
    ESP_RETURN_ON_FALSE((p_uart_obj[uart_num]), ESP_FAIL, UART_TAG, "uart driver error");
    UART_ENTER_CRITICAL(&(uart_context[uart_num].spinlock));
    *size = p_uart_obj[uart_num]->rx_buffered_len;
    UART_EXIT_CRITICAL(&(uart_context[uart_num].spinlock));
    return ESP_OK;
}

Is this function, and the ones that accompany it, accessing a ring buffer or the actual UART FIFO RX buffer?

I've made a number of assumptions in asking this question, and I apologise for my naivety. However, I'd be extremely grateful for clarification on a number of basic matters.

1) Is the UART FIFO buffer a "normal" linear buffer of fixed length? (I believe it is.)
2) Is the UART FIFO memory that exists in the UART chip rather than in the ESP32's RAM or flash memory? (I understand that the ESP is a SoC, so it's all one chip, but...)
3) Does FreeRTOS implement its own ring buffer "on top of" the UART FIFO buffer? (I think it does.)
4) Why have a ring buffer and a UART FIFO buffer in the first place?
5) When does FreeRTOS copy data from the UART FIFO buffer to the ring buffer? Based on what sort of criteria?

Many thanks.

[MicroController]

1) Is the UART FIFO buffer a "normal" linear buffer of fixed length? (I believe it is.)

It mostly is. There's one piece of hardware buffer memory (1KB I believe) which can be divided into pieces of the same or different sizes and allocated to the different UARTs on the SoC.

2) Is the UART FIFO memory that exists in the UART chip rather than in the ESP32's RAM or flash memory? (I understand that the ESP is a SoC, so it's all one chip, but...)

Yes, the UART (hardware) FIFO is dedicated memory inside the UART peripheral.

3) Does FreeRTOS implement its own ring buffer "on top of" the UART FIFO buffer? (I think it does.)

Yes, the IDF driver can do this, but you can configure the size of the in-RAM ringbuffer, including a size of 0.

4) Why have a ring buffer and a UART FIFO buffer in the first place?

The hardware FIFO has a limited size (set to 128 bytes per buffer (RX, TX for each UART) by default), which may not be big enough at high-ish transmission speeds and/or high CPU load.

5) When does FreeRTOS copy data from the UART FIFO buffer to the ring buffer? Based on what sort of criteria?

Data is retrieved from the hardware FIFO upon a UART interrupt. When this interrupt is triggered is configurable (uart_intr_config()); there is a size threshold (interrupt when at least X bytes are pending in the FIFO) and there is a timeout (interrupt when there's at least one byte in the FIFO and no new data received for X byte periods).

[Siddle34]

Thank you Mr MicroController! You have cleared up some fundamental things for me.