UART Rx RTOS Driver

This driver can be used to instantiate and control an UART Rx I/O interface on xcore in an RTOS application.

UART Rx API

The following structures and functions are used to initialize and start a UART Rx driver instance.

typedef struct rtos_uart_rx_struct rtos_uart_rx_t

Typedef to the RTOS UART rx driver instance struct.

typedef void (*rtos_uart_rx_started_cb_t)(rtos_uart_rx_t *ctx)

Function pointer type for application provided RTOS UART rx start callback functions.

This callback function is optionally (may be NULL) called by an UART rx driver’s thread when it is first started. This gives the application a chance to perform startup initialization from within the driver’s thread.

Parameters

ctx – A pointer to the associated UART rx driver instance.

typedef void (*rtos_uart_rx_complete_cb_t)(rtos_uart_rx_t *ctx)

Function pointer type for application provided RTOS UART rx receive callback function.

This callback functions are called when an UART rx driver instance has received data to a specified depth. Please use the xStreamBufferReceive(rtos_uart_rx_ctx->isr_byte_buffer, … to read the bytes.

Parameters

ctx – A pointer to the associated UART rx driver instance.

typedef void (*rtos_uart_rx_error_t)(rtos_uart_rx_t *ctx, uint8_t err_flags)

Function pointer type for application provided RTOS UART rx error callback functions.

This callback function is optionally (may be NULL_ called when an UART rx driver instance experiences an error in reception. These error types are defined in uart.h of the underlying HIL driver but can be of the following types for the RTOS rx: UART_START_BIT_ERROR, UART_PARITY_ERROR, UART_FRAMING_ERROR, UART_OVERRUN_ERROR.

Parameters

  • ctx – A pointer to the associated UART rx driver instance.

  • err_flags – An 8b word containing error flags set during reception of last frame. See rtos_uart_rx.h for the bit field definitions.

size_t rtos_uart_rx_read(rtos_uart_rx_t *uart_rx_ctx, uint8_t *buf, size_t n, rtos_osal_tick_t timeout)

Reads data from a UART Rx instance. It will read up to n bytes or timeout, whichever comes first.

Parameters

  • uart_rx_ctx – A pointer to the UART Rx driver instance to use.

  • buf – The buffer to be written with the read UART bytes.

  • n – The number of bytes to write.

  • timeout – How long in ticks before the read operation should timeout.

Returns

The number of bytes read.

void rtos_uart_rx_reset_buffer(rtos_uart_rx_t *uart_rx_ctx)

Resets the receive buffer. Clears the contents and sets number of items rto zero.

Parameters

uart_rx_ctx – A pointer to the UART Rx driver instance to use.

void rtos_uart_rx_init(rtos_uart_rx_t *uart_rx_ctx, uint32_t io_core_mask, port_t rx_port, uint32_t baud_rate, uint8_t data_bits, uart_parity_t parity, uint8_t stop_bits, hwtimer_t tmr)

Initializes an RTOS UART rx driver instance. This must only be called by the tile that owns the driver instance. It should be called before starting the RTOS, and must be called before calling rtos_uart_rx_start(). Note that UART rx requires a whole logical core for the underlying HIL UART Rx instance.

Parameters

  • uart_rx_ctx – A pointer to the UART rx driver instance to initialize.

  • io_core_mask – A bitmask representing the cores on which the low UART Rx thread created by the driver is allowed to run. Bit 0 is core 0, bit 1 is core 1, etc.

  • rx_port – The port containing the receive pin

  • baud_rate – The baud rate of the UART in bits per second.

  • data_bits – The number of data bits per frame sent.

  • parity – The type of parity used. See uart_parity_t above.

  • stop_bits – The number of stop bits asserted at the of the frame.

  • tmr – The resource id of the timer to be used by the UART Rx.

void rtos_uart_rx_start(rtos_uart_rx_t *uart_rx_ctx, void *app_data, rtos_uart_rx_started_cb_t start, rtos_uart_rx_complete_cb_t rx_complete, rtos_uart_rx_error_t error, unsigned interrupt_core_id, unsigned priority, size_t app_rx_buff_size)

Starts an RTOS UART rx driver instance. This must only be called by the tile that owns the driver instance. It must be called after starting the RTOS and from an RTOS thread.

rtos_uart_rx_init() must be called on this UART rx driver instance prior to calling this.

Parameters

  • uart_rx_ctx – A pointer to the UART rx driver instance to start.

  • app_data – A pointer to application specific data to pass to the callback functions available in rtos_uart_rx_struct.

  • start – The callback function that is called when the driver’s thread starts. This is optional and may be NULL.

  • rx_complete – The callback function to indicate data received by the UART.

  • error – The callback function called when a reception error has occured.

  • interrupt_core_id – The ID of the core on which to enable the UART rx interrupt.

  • priority – The priority of the task that gets created by the driver to call the callback functions.

  • app_rx_buff_size – The size in bytes of the RTOS xstreambuffer used to buffer received words for the application.

UR_COMPLETE_CB_CODE

The callback code bit positions available for RTOS UART Rx.

UR_STARTED_CB_CODE
UR_START_BIT_ERR_CB_CODE
UR_PARITY_ERR_CB_CODE
UR_FRAMING_ERR_CB_CODE
UR_OVERRUN_ERR_CB_CODE
UR_COMPLETE_CB_FLAG

The callback code flag masks available for RTOS UART Rx.

UR_STARTED_CB_FLAG
UR_START_BIT_ERR_CB_FLAG
UR_PARITY_ERR_CB_FLAG
UR_FRAMING_ERR_CB_FLAG
UR_OVERRUN_ERR_CB_FLAG
RX_ERROR_FLAGS
RX_ALL_FLAGS
RTOS_UART_RX_BUF_LEN

The size of the byte buffer between the ISR and the appthread. It needs to be able to hold sufficient bytes received until the app_thread is able to service it. This is not the same as app_byte_buffer_size which can be of any size, specified by the user at device start. At 1Mbps we get a byte every 10us so 64B allows 640us for the app thread to respond. Note buffer is size n+1 as required by lib_uart.

RTOS_UART_RX_CALLBACK_ATTR

This attribute must be specified on all RTOS UART rx callback functions provided by the application to allow compiler stack calculation.

RTOS_UART_RX_CALL_ATTR

This attribute must be specified on all RTOS UART functions provided by the application to allow compiler stack calculation.

struct rtos_uart_rx_struct
#include <rtos_uart_rx.h>

Struct representing an RTOS UART rx driver instance.

The members in this struct should not be accessed directly.