<< >>

Generic UART

This UART has two modules, one for RX and one for TX each of which uses one thread and is connected via channel to another thread using the UART Client API .

The thread for the UART TX component receives data from the client via a buffer (configurable between 1 and 64 bytes). A full buffer will block the client.

The thread for the UART RX component receives data from external into the RX buffer (configurable between 1 and 64 bytes) which is read by the client using channel. An empty RX buffer will block the client.

Hardware Platforms

This UART is supported by all the hardware platforms from XMOS having suitable IO such as XC-1,XC-1A,XC-2,XK-1,etc and can be run on any XS1-L or XS1-G series devices.

Programming Guide

Key Files

File Description
module_uart_tx/src/uart_tx.h Client API header file for Generic UART TX
module_uart_tx/src/uart_tx.xc Client API implementation for Generic UART TX
module_uart_tx/src/uart_tx_impl.h UART TX Server Header File
module_uart_tx/src/uart_tx_impl.xc UART TX Server implementation
module_uart_rx/src/uart_rx.h Client API header file for Generic UART RX
module_uart_rx/src/uart_rx.xc Client API implementation for Generic UART RX
module_uart_rx/src/uart_rx_impl.h UART RX Server Header File
module_uart_rx/src/uart_rx_impl.xc UART RX Server implementation

Required Repositories

  • xcommon git@github.com:xcore/xcommon.git

Resource Usage

The following table details the resource usage of the component.

Resource Usage
Code Memory 2110
Ports 2 x 1b
ChannelEnds 2

Demo Application

The UART functionality is demonstrated using the app_uart_back2back. This has been rpepared to run on an XK-1 board, but can easily be ported to other development boards with small modificatiosn to the code. To prepare the XK-1 board to run this app, simply connect a jumper such that ports 1A and 1B are connected (e.g. connect X0D1 and X0D0 pins on the GPIO header). Refer to the XK-1 Hardware Manual for pni positions.

The app can then be built and run.

It will send the full set of characters from the UART TX, receive them on UART RX and then print them out in batches of 10 characters.

app_uart_back2back

It will receive via the RX component and echo via TX component.

UART TX component Overview

The UART TX component is started using the uart_tx() function, which causes the TX server (called “_impl” in the code) to run in a while(1) loop until it receives and instruction to shut down via the channel from the client. Additionally a set of client functions are provided to transmit a byte and to alter the baud rate, parity, bits per byte and stop bit settings. Any such action except transmitting a byte causes the TX server to terminate and then be restarted with the new settings. Any data in the TX buffer is preserved and then sent with the new settings.

UART TX API

void uart_tx(out port txd, unsigned char buffer[], unsigned buffer_size, unsigned baud_rate, unsigned bits, enum uart_tx_parity parity, unsigned stop_bits, chanend c)

UART TX server function.

This function never returns and the arguments specify the initial configuration of parity, bits per byte etc. These are checked and then the inner UART TX loop (uart_tx_impl() is started and runs in a while(1) loop until it receives and instruction to shut down via the channel from the client. Additionally a set of client functions are provided to transmit a byte and to alter the baud rate, parity, bits per byte and stop bit settings. Note that the buffer size can only be changed when this function is first called, it cannot be changed thereafter.

The client provides data to the server using the send byte function below.

Arguments are as follows:

Parameters:
  • txd – Transmitted data signal. Must be a 1-bit port.
  • buffer – Array for buffering bytes before they are transmitted.
  • buffer_size – Size of the array.
  • baud_rate – Initial baud rate.
  • bits – Initial bits per character. Must be less than 8.
  • parity – Type of parity to initially use. No parity bit is transmitted if is passed.
  • stop_bits – Initial number of stop bits to transmit.
  • c – Chanend to receive requests on, where a request is either a byte to transmit or a configuration change.
void uart_tx_send_byte(chanend c, unsigned char byte)

Adds a byte into the UART transmit buffer.

If the the buffer is full then this function blocks until there is room in the buffer.

Parameters:
  • chanend – Other end of the channel passed to the uart_tx() function.
  • byte – Byte to transmit.
void uart_tx_set_baud_rate(chanend c, unsigned baud_rate)

These functions Set the baud rate, parity, stop bits and bits-per-byte settings of the of the UART TX server.

The change of configuration takes effect after all remaining data in transmit buffer is sent, and the functions block until the change of configuration takes effect.

Parameters:
  • chanend – Other end of the channel passed to the uart_tx() function.
  • [setting] – The baud rate, parity or stop bits or bits-per-byte setting. Note parity is an enum.
void uart_tx_set_parity(chanend c, enum uart_tx_parity parity)
void uart_tx_set_stop_bits(chanend c, unsigned stop_bits)
void uart_tx_set_bits_per_byte(chanend c, unsigned bits)

UART RX component Overview

The UART RX component is started using the uart_tx() function, which causes the TX server (called “_impl” in the code) to run in a while(1) loop until it receives and instruction to shut down via the channel from the client. Additionally a set of client functions are provided to fetch a byte from teh recieve buffer and to alter the baud rate, parity, bits per byte and stop bit settings. Any such action except transmitting a byte causes the RX server to terminate, the receive buffer emptied, and then restarted immediately with the new settings.

UART RX API

void uart_rx(in buffered port:1 rxd, unsigned char buffer[], unsigned buffer_size, unsigned baud_rate, unsigned bits, enum uart_rx_parity parity, unsigned stop_bits, chanend c)

UART RX server function.

The client must call the uart_rx_init() function to initialize the server before calling any other client functions. Bytes received by the server are buffered in the array. When the buffer is full further incoming bytes of data will be dropped.

This function never returns, and will start the server RX inner loop which runs in a while(1) loop until it is stopped via a command over channelend, following whcih the inner loop is automatyically restarted.

The functions below are provided to change the UART RX parameters, parity, bits-per-byte, stop bits and baud rate, and all of these cause the RX inner loop to terminate while the new settings are applied. Bytes received during this time would be dropped, and any receive buffer contents are discarded when the settings are changed. Note that the buffer size can only be changed when this function is first called, it cannot be changed thereafter.

The client uses uart_rx_get_byte() to get bytes from the receive buffer.

unsigned char uart_rx_get_byte(chanend c, uart_rx_client_state &state)

Get a byte from the receive buffer.

This function blocks until there is a byte available.

void uart_rx_get_byte_byref(chanend c, uart_rx_client_state &state, unsigned char &byte)
void uart_rx_set_baud_rate(chanend c, uart_rx_client_state &state, unsigned baud_rate)

Set the baud rate of the UART RX server.

The change of configuration takes place immediately.

void uart_rx_set_parity(chanend c, uart_rx_client_state &state, enum uart_rx_parity parity)

Set the parity of the UART RX server.

The change of configuration takes place immediately.

void uart_rx_set_stop_bits(chanend c, uart_rx_client_state &state, unsigned stop_bits)

Set number of stop bits used by the UART RX server.

The change of configuration takes place immediately.

void uart_rx_set_bits_per_byte(chanend c, uart_rx_client_state &state, unsigned bits)

Set number of bits per byte used by the UART RX server.

The change of configuration takes place immediately.

Verification

An application app_uart_test is provided to run in XSIM using the Loopback Plugin DLL (see Tools User Guide for details) that validates the various combinations of parity, stop bit, bits-per-byte and baud rate settings. It will send data out via the UART TX component using single bit port and receive via UART RX component from another single bit port. It will check that the data matches.

The testbench is run using a python script: regression_script_UART.py. The test suites are executed as follows (after having built the application with the makefile provided:

+==========================+===================================================+===============================================================+
| |This test will confirm that buffer size is enough and data from |
check buffering | <script.py> -check_buffering |TX buffer to RX buffer passes correctly |
runtime parameter change <script.py> -runtime_parameter_change This test will confirm UART module supports change in parameter during runtime such as baud-rate,bits per byte, parity, stopbit
Parity test <script.py> -test_parity This test will confirm UART module discards data in case of mismatch in change in parity
single test script.py -buad_rate <baud_rate> -bitsperbyte <bitsperbyte> -parity <parity> -stopbit <stopbit> This test will confirm UART module discards data in case of mismatch in change in parity
regression test <script.py>
This will take all possible combinations of baud-rate,bits

per byte,parity and no. of stop bits.it will use testlist.txt

The output is dumped to log.txt. This file should be manually removed, if it exists, before re-running.

UART (0v1)