Back to top

Stand Alone Uart Components

Version: X5746A Date: October 16, 2012Download PDF
VersionReleased
X5746AOct 16, 2012 download view

Generic UART

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

The logical core 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 logical core 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.

Resource Requirements

A single generic uart consisting of module_uart_rx and module_uart_tx will consumer the following resources:

Resource

Usage

Code Memory

2110

Ports

2 x 1b

ChannelEnds

2

Evaluation Platforms

This module may be evaluated using the Slicekit Modular Development Platform, available from digikey. Required board SKUs are:

  • XP-SKC-L2 (Slicekit L2 Core Board) plus XA-SK-GPIO plus XA-SK-ATAG2 (Slicekit XTAG adaptor) plus XTAG2 (debug adaptor), OR
  • XK-SK-L2-ST (Slicekit Starter Kit, containing all of the above).

Demonstration Application

Example usage of this module can be found within the XSoftIP suite as follows:

  • Package: sw_gpio_examples
  • Application: app_slicekit_com_demo
  • Package: sc_uart
  • Application: app_uart_back2back

API and 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

TX API

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.

  • 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

    • c

      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)

    Set the baud rate of the of the UART TX server.

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

    Parameters

    • c

      Other end of the channel passed to the uart_tx() function.

    • baud_rate

      The baud rate setting.

  • void uart_tx_set_parity(chanend c, enum uart_tx_parity parity)

    Set the parity of the of the UART TX stop bit.

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

    Parameters

    • c

      Other end of the channel passed to the uart_tx() function.

    • parity

      The parity setting. Note parity is an enum.

  • void uart_tx_set_stop_bits(chanend c, unsigned stop_bits)

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

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

    Parameters

    • c

      Other end of the channel passed to the uart_tx() function.

    • stop_bits

      The stop bits or bits-per-byte setting. Note parity is an enum.

  • void uart_tx_set_bits_per_byte(chanend c, unsigned bits)

    Set the bits per byte rate of the of the UART TX server.

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

    Parameters

    • c

      Other end of the channel passed to the uart_tx() function.

    • bits

      The bits or bits-per-byte setting.

RX API

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.

  • 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.

Example Applications

GPIO Slice Examples

This uart is used in the GPIO Com Port Demo demo application to transfer commands from a host computer via uart to light the LEDs and read the adc on the Slicekit GPIO Slice Card. Refer to this item in xTIMEcomposer for more details on running this example application.

Basic Loopback Example

These modules can also be evaluated wired back to back using app_uart_back2back. To prepare the Slicekit core board to run this app connect wires between the 0.1” testpoints on the Triangle slot (or solder suitable headers on as shown in the picture below), such that ports 1A and 1E are connected. The headers corresponding to these ports are marked D0 and D12 respectively.

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.