XCORE SDK
XCORE Software Development Kit
Classes | Macros | Typedefs | Functions
rtos_uart_rx_driver

Classes

struct  rtos_uart_rx_struct
 

Macros

#define UR_COMPLETE_CB_CODE   0
 
#define UR_STARTED_CB_CODE   1
 
#define UR_START_BIT_ERR_CB_CODE   2
 
#define UR_PARITY_ERR_CB_CODE   3
 
#define UR_FRAMING_ERR_CB_CODE   4
 
#define UR_OVERRUN_ERR_CB_CODE   5
 
#define UR_COMPLETE_CB_FLAG   (1 << UR_COMPLETE_CB_CODE)
 
#define UR_STARTED_CB_FLAG   (1 << UR_STARTED_CB_CODE)
 
#define UR_START_BIT_ERR_CB_FLAG   (1 << UR_START_BIT_ERR_CB_CODE)
 
#define UR_PARITY_ERR_CB_FLAG   (1 << UR_PARITY_ERR_CB_CODE)
 
#define UR_FRAMING_ERR_CB_FLAG   (1 << UR_FRAMING_ERR_CB_CODE)
 
#define UR_OVERRUN_ERR_CB_FLAG   (1 << UR_OVERRUN_ERR_CB_CODE)
 
#define RX_ERROR_FLAGS   (UR_START_BIT_ERR_CB_FLAG | UR_PARITY_ERR_CB_FLAG | UR_FRAMING_ERR_CB_FLAG)
 
#define RX_ALL_FLAGS   (UR_COMPLETE_CB_FLAG | UR_STARTED_CB_FLAG | RX_ERROR_FLAGS)
 
#define RTOS_UART_RX_BUF_LEN   (64 + 1)
 
#define RTOS_UART_RX_CALLBACK_ATTR   __attribute__((fptrgroup("rtos_uart_rx_callback_fptr_grp")))
 
#define RTOS_UART_RX_CALL_ATTR   __attribute__((fptrgroup("rtos_uart_rx_call_fptr_grp")))
 

Typedefs

typedef struct rtos_uart_rx_struct rtos_uart_rx_t
 
typedef void(* rtos_uart_rx_started_cb_t) (rtos_uart_rx_t *ctx)
 
typedef void(* rtos_uart_rx_complete_cb_t) (rtos_uart_rx_t *ctx)
 
typedef void(* rtos_uart_rx_error_t) (rtos_uart_rx_t *ctx, uint8_t err_flags)
 

Functions

size_t rtos_uart_rx_read (rtos_uart_rx_t *uart_rx_ctx, uint8_t *buf, size_t n, rtos_osal_tick_t timeout)
 
void rtos_uart_rx_reset_buffer (rtos_uart_rx_t *uart_rx_ctx)
 
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)
 
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)
 

Detailed Description

The public API for using the RTOS UART rx driver.

Macro Definition Documentation

◆ RTOS_UART_RX_BUF_LEN

#define RTOS_UART_RX_BUF_LEN   (64 + 1)

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_CALL_ATTR

#define RTOS_UART_RX_CALL_ATTR   __attribute__((fptrgroup("rtos_uart_rx_call_fptr_grp")))

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

◆ RTOS_UART_RX_CALLBACK_ATTR

#define RTOS_UART_RX_CALLBACK_ATTR   __attribute__((fptrgroup("rtos_uart_rx_callback_fptr_grp")))

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

◆ UR_COMPLETE_CB_CODE

#define UR_COMPLETE_CB_CODE   0

The callback code bit positions available for RTOS UART Rx.

◆ UR_COMPLETE_CB_FLAG

#define UR_COMPLETE_CB_FLAG   (1 << UR_COMPLETE_CB_CODE)

The callback code flag masks available for RTOS UART Rx.

Typedef Documentation

◆ rtos_uart_rx_complete_cb_t

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
ctxA pointer to the associated UART rx driver instance.

◆ rtos_uart_rx_error_t

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
ctxA pointer to the associated UART rx driver instance.
err_flagsAn 8b word containing error flags set during reception of last frame. See rtos_uart_rx.h for the bit field definitions.

◆ rtos_uart_rx_started_cb_t

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
ctxA pointer to the associated UART rx driver instance.

◆ rtos_uart_rx_t

Typedef to the RTOS UART rx driver instance struct.

Function Documentation

◆ rtos_uart_rx_init()

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_ctxA pointer to the UART rx driver instance to initialize.
io_core_maskA 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_portThe port containing the receive pin
baud_rateThe baud rate of the UART in bits per second.
data_bitsThe number of data bits per frame sent.
parityThe type of parity used. See uart_parity_t above.
stop_bitsThe number of stop bits asserted at the of the frame.
tmrThe resource id of the timer to be used by the UART Rx.

◆ rtos_uart_rx_read()

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_ctxA pointer to the UART Rx driver instance to use.
bufThe buffer to be written with the read UART bytes.
nThe number of bytes to write.
timeoutHow long in ticks before the read operation should timeout.
Returns
The number of bytes read.

◆ rtos_uart_rx_reset_buffer()

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_ctxA pointer to the UART Rx driver instance to use.

◆ rtos_uart_rx_start()

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_ctxA pointer to the UART rx driver instance to start.
app_dataA pointer to application specific data to pass to the callback functions available in rtos_uart_rx_struct.
startThe callback function that is called when the driver's thread starts. This is optional and may be NULL.
rx_completeThe callback function to indicate data received by the UART.
errorThe callback function called when a reception error has occured.
interrupt_core_idThe ID of the core on which to enable the UART rx interrupt.
priorityThe priority of the task that gets created by the driver to call the callback functions.
app_rx_buff_sizeThe size in bytes of the RTOS xstreambuffer used to buffer received words for the application.