UART Rx¶

UART Rx Usage¶

The following code snippet demonstrates the basic usage of an UART Rx device where the function call to Rx returns after the stop bit has been sampled. The function blocks until a complete byte has been received.

#include <xs1.h>
#include <print.h>
#include "uart.h"


HIL_UART_RX_CALLBACK_ATTR void rx_error_callback(uart_callback_code_t callback_code, void *app_data){
    switch(callback_code){
        case UART_START_BIT_ERROR:
            printstrln("UART_START_BIT_ERROR");
            break;
        case UART_PARITY_ERROR:
            printstrln("UART_PARITY_ERROR");
            break;
        case UART_FRAMING_ERROR:
            printstrln("UART_FRAMING_ERROR");
            test_abort = 1;
            break;
        case UART_OVERRUN_ERROR:
            printstrln("UART_OVERRUN_ERROR");
            break;
        case UART_UNDERRUN_ERROR:
            printstrln("UART_UNDERRUN_ERROR");
            break;
        default:
            printstr("Unexpected callback code: ");
            printintln(callback_code);
    }
}

void uart_rx(void){

    uart_rx_t uart;

    port_t p_uart_rx = XS1_PORT_1B;
    hwtimer_t tmr = hwtimer_alloc();

    char test_rx[16];

    // Initialize the UART Rx
    uart_rx_blocking_init(  &uart, p_uart_rx, 115200, 8, UART_PARITY_NONE, 1, tmr,
                            rx_error_callback, &uart);

    // Receive some data
    for(int i = 0; i < sizeof(rx_data); i++){
       test_rx[i] = uart_rx(&uart);
    }

UART Rx Usage ISR/Buffered¶

The following code snippet demonstrates the usage of an UART Rx device used in ISR/Buffered mode:

 #include <xs1.h>
 #include <print.h>
 #include "uart.h"


 HIL_UART_RX_CALLBACK_ATTR void rx_error_callback(uart_callback_code_t callback_code, void *app_data){
     switch(callback_code){
         case UART_START_BIT_ERROR:
             printstrln("UART_START_BIT_ERROR");
             break;
         case UART_PARITY_ERROR:
             printstrln("UART_PARITY_ERROR");
             break;
         case UART_FRAMING_ERROR:
             printstrln("UART_FRAMING_ERROR");
             test_abort = 1;
             break;
         case UART_OVERRUN_ERROR:
             printstrln("UART_OVERRUN_ERROR");
             break;
         case UART_UNDERRUN_ERROR:
             printstrln("UART_UNDERRUN_ERROR");
             break;
         default:
             printstr("Unexpected callback code: ");
             printintln(callback_code);
     }
 }


HIL_UART_RX_CALLBACK_ATTR void rx_callback(void *app_data){
      unsigned *bytes_received = (unsigned *)app_data;
      *bytes_received += 1;
}

void uart_rx(void){

    uart_rx_t uart;
    port_t p_uart_rx = XS1_PORT_1A;
    hwtimer_t tmr = hwtimer_alloc();
    uint8_t buffer[64 + 1] = {0}; // Note buffer size plus one

    volatile unsigned bytes_received = 0;

    // Initialize the UART Rx
    uart_rx_init(&uart, p_uart_rx, 115200, 8, UART_PARITY_NONE, 1, tmr,
                 buffer, sizeof(buffer), rx_callback, &bytes_received);

    // Wait for 16b of data
    while(bytes_received < 15);

    // Get the data
    uint8_t test_rx[NUM_RX_WORDS];
    for(int i = 0; i < 16; i++){
        test_rx[i] = uart_rx(&uart);
    }

UART Rx API¶

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

void uart_rx_init(uart_rx_t *uart, port_t rx_port, uint32_t baud_rate, uint8_t data_bits, uart_parity_t parity, uint8_t stop_bits, hwtimer_t tmr, uint8_t *rx_buff, size_t buffer_size_plus_one, void (*uart_rx_complete_callback_fptr)(void *app_data), void (*uart_rx_error_callback_fptr)(uart_callback_code_t callback_code, void *app_data), void *app_data)¶

Initializes a UART Rx I/O interface. Passing a valid buffer will enable buffered mode with ISR for use in bare-metal applications.

Parameters

uart – The uart_rx_t context to initialise.
rx_port – The port used receive the UART frames.
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. Polling mode will be used if set to 0.
rx_buff – Pointer to a buffer. Optional. If set to zero the UART will run in blocking mode. If initialised to a valid buffer, the UART will be interrupt driven.
buffer_size_plus_one – Size of the buffer if enabled in rx_buff. Note that the buffer allocation and size argument must be one greater than needed. Eg. buff[65] for a 64 byte buffer.
uart_rx_complete_callback_fptr – Callback function pointer for UART rx complete (one word) in buffered mode only. Optionally NULL.
uart_rx_error_callback_fptr – Callback function pointer for UART rx errors The error is contained in cb_code in the uart_rx_t struct.
app_data – A pointer to application specific data provided by the application. Used to share data between this callback function and the application.

void uart_rx_blocking_init(uart_rx_t *uart, port_t rx_port, uint32_t baud_rate, uint8_t data_bits, uart_parity_t parity, uint8_t stop_bits, hwtimer_t tmr, void (*uart_rx_error_callback_fptr)(uart_callback_code_t callback_code, void *app_data), void *app_data)¶

Initializes a UART Rx I/O interface. This API is fixed to blocking mode which is where the call to uart_rx returns as soon as the stop bit has been sampled.

Parameters

uart – The uart_rx_t context to initialise.
rx_port – The port used receive the UART frames.
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. Polling mode will be used if set to 0.
uart_rx_error_callback_fptr – Callback function pointer for UART rx errors The error is contained in cb_code in the uart_rx_t struct.
app_data – A pointer to application specific data provided by the application. Used to share data between the error callback function and the application.

uint8_t uart_rx(uart_rx_t *uart)¶

Receives a single UART frame with parameters as specified in uart_rx_init()

Parameters: uart – The uart_rx_t context to receive from.
Returns: The word received in the UART frame. In buffered mode it gets the oldest received word.

void uart_rx_deinit(uart_rx_t *uart)¶

De-initializes the specified UART Rx interface. This disables the port also. The timer, if used, needs to be freed by the application.

Parameters: uart – The uart_rx_t context to de-initialise.

struct uart_rx_t¶

#include <uart.h>

Struct to hold a UART Rx context.

The members in this struct should not be accessed directly. Use the API provided instead.