Hide navigation sidebar
Hide table of contents sidebar
Back to top
Toggle table of contents sidebar

# UART Tx

## UART Tx Usage

The following code snippet demonstrates the basic blocking usage of an UART Tx device.

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

    uart_tx_t uart;

    port_t p_uart_tx = XS1_PORT_1A;
    hwtimer_t tmr = hwtimer_alloc();

    uint8_t tx_data[4] = {0x01, 0x02, 0x04, 0x08};

    // Initialize the UART Tx
    uart_tx_blocking_init(&uart, p_uart_tx, 115200, 8, UART_PARITY_NONE, 1, tmr);

    // Transfer some data
    for(int i = 0; i < sizeof(tx_data); i++){
       uart_tx(&uart, tx_data[i]);
    }

## UART Tx Usage ISR/Buffered

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

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

    HIL_UART_TX_CALLBACK_ATTR void tx_empty_callback(void *app_data){
          int *tx_empty = (int *)app_data;
          *tx_empty = 1;
    }

    void uart_tx(void){

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

        uint8_t tx_data[4] = {0x01, 0x02, 0x04, 0x08};
        volatile int tx_empty = 0;

        // Initialize the UART Tx
        uart_tx_init(&uart, p_uart_tx, 115200, 8, UART_PARITY_NONE, 1, tmr, buffer, sizeof(buffer), tx_empty_callback, &tx_empty);

        // Transfer some data
        for(int i = 0; i < sizeof(tx_data); i++){
           uart_tx(&uart, tx_data[i]);
        }

        // Wait for it to complete
        while(!tx_empty);

## UART Tx API

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

enum uart_parity

  Enum type representing the different options parity types.

  Values:

  enumerator UART_PARITY_NONE
  enumerator UART_PARITY_EVEN
  enumerator UART_PARITY_ODD

enum uart_callback_code_t

  Enum type representing the callback error codes.

  Values:

  enumerator UART_RX_COMPLETE
  enumerator UART_UNDERRUN_ERROR
  enumerator UART_START_BIT_ERROR
  enumerator UART_PARITY_ERROR
  enumerator UART_FRAMING_ERROR
  enumerator UART_OVERRUN_ERROR

enum uart_state_t

  Enum type representing the different states for the UART logic.

  Values:

  enumerator UART_IDLE
  enumerator UART_START
  enumerator UART_DATA
  enumerator UART_PARITY
  enumerator UART_STOP

typedef enum uart_parity uart_parity_t

  Enum type representing the different options parity types.

void uart_tx_init(uart_tx_t *uart, port_t tx_port, uint32_t baud_rate, uint8_t data_bits, uart_parity_t parity, uint8_t stop_bits, hwtimer_t tmr, uint8_t *tx_buff, size_t buffer_size_plus_one, void (*uart_tx_empty_callback_fptr)(void *app_data), void *app_data)

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

  Parameters:

    - uart – The uart_tx_t context to initialise.

    - tx_port – The port used transmit 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.

    - tx_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 tx_buff. Note that the buffer allocation and size argument must be one greater than needed. Eg. buff[65] for a 64 byte buffer.

    - uart_tx_empty_callback_fptr – Callback function pointer for UART buffer empty in buffered mode.

    - 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_tx_blocking_init(uart_tx_t *uart, port_t tx_port, uint32_t baud_rate, uint8_t data_bits, uart_parity_t parity, uint8_t stop_bits, hwtimer_t tmr)

  Initializes a UART Tx I/O interface. The API is hard wired to blocking mode where the call to uart_tx will return at the end of sending the stop bit.

  Parameters:

    - uart – The uart_tx_t context to initialise.

    - tx_port – The port used transmit 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.

void uart_tx(uart_tx_t *uart, uint8_t data)

  Transmits a single UART frame with parameters as specified in uart_tx_init()

  Parameters:

    - uart – The uart_tx_t context to initialise.

    - data – The word to transmit.

void uart_tx_deinit(uart_tx_t *uart)

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

  Parameters:

    - uart – The uart_tx_t context to de-initialise.

UART_START_BIT_ERROR_VAL

  Define which sets the enum start point of RX errors. This is relied upon by the RTOS drivers and allows optimisation of error handling.

HIL_UART_TX_CALLBACK_ATTR

  This attribute must be specified on the UART TX UNDERRUN callback function provided by the application. It ensures the correct stack usage is calculated.

HIL_UART_RX_CALLBACK_ATTR

  This attribute must be specified on the UART Rx callback functions (both ERROR and Rx complete callbacks) provided by the application. It ensures the correct stack usage is correctly calculated.

struct uart_tx_t
  #include <uart.h>

  Struct to hold a UART Tx context.

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