MultiUART module usage manual
Document Number: XM001964A
Publication Date: 2014/6/26
XMOS © 2014, All Rights Reserved.
MultiUART module usage manual
2/38
Table of Contents
1 Overview
1.1
Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1.2
sliceKIT compatibility (XA-SK-UART8) . . . . . . . . . . . . . . . . . . . . . . . . . . .
3
3
3
2 Resource requirements
2.1
Ports . . . . . . . . . . . . .
2.2
Logical cores . . . . . . . . .
2.3
Memory . . . . . . . . . . . .
2.4
Channel usage . . . . . . . .
2.5
Client timing requirements
.
.
.
.
.
4
4
4
4
5
5
3 Evaluation platforms
3.1
Recommended hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2
XA-SK-UART8 sliceCARD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.3
Demonstration application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6
6
7
7
4 Module description
4.1
Cores . . . . . . . . . .
4.2
Buffering . . . . . . . .
4.3
Communication model
4.4
Clocking . . . . . . . .
8
8
8
8
9
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
5 MultiUART common API
10
5.1
Enum definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
5.2
Combined RX & TX server launch functions . . . . . . . . . . . . . . . . . . . . . . . 11
6 MultiUART transmit API
6.1
Configuration defines .
6.2
Data structures . . . . .
6.3
Configuration functions
6.4
Transmission functions
6.5
MultiUART TX server . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
13
13
14
15
16
17
7 MultiUART receive API
7.1
Configuration defines . .
7.2
Data structures . . . . . .
7.3
Configuration functions .
7.4
Data validation functions
7.5
Data fetch functions . . .
7.6
MultiUART RX server . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
18
18
18
20
21
21
22
8 MultiUART helper API
9 Programming guide
9.1
Structure . . . . . . . . . . . . . . . . . .
9.1.1 Source code . . . . . . . . . . . . .
9.2
Configuration of MultiUART component
9.2.1 Static configuration of UART TX . .
9.2.2 Static configuration of UART RX . .
XM001964A
23
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
26
26
26
26
27
29
MultiUART module usage manual
9.3
9.4
9.5
9.6
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
31
32
32
33
10 Example applications
10.1 app_sk_muart_com_demo application
10.1.1 Required software tools . . . . . .
10.1.2 Build options . . . . . . . . . . . . .
10.1.3 Hardware settings . . . . . . . . . .
10.1.4 Application description . . . . . . .
10.1.5 Quickstart guide . . . . . . . . . .
10.1.6 Interacting with the application . .
10.1.7 Makefiles . . . . . . . . . . . . . . .
10.1.8 Using command line tools . . . . .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
34
34
34
34
35
36
37
37
37
37
XM001964A
Initialization . . . . . . . . . . . . .
Interfacing to the TX server . . . .
Interfacing to the RX server . . . .
Reconfiguration of RX & TX server
3/38
.
.
.
.
.
.
.
.
1 Overview
IN THIS CHAPTER
· Features
· sliceKIT compatibility (XA-SK-UART8)
This module provides a software library that allows multiple uarts to share 8 bit
ports for a multiple UART communication. It is dynamically re-configurable for
applications that require a level of flexibility during operation.
1.1
Features
MultiUART component provides the following functionality. All options are dynamically reconfigurable via the API.
1.2
Function
Operational Range
Notes
Baud Rate
150 to 115200 bps
Dependent on clocking
(see §4.4)
Parity
Stop Bits
Data Length
None, Mark, Space, Odd, Even
1,2
1 to 30 bits
Max 30 bits assumes 1 stop bit
and no parity.
sliceKIT compatibility (XA-SK-UART8)
This module is designed to work with the XA-SK-UART8 sliceCARD which has the
slot compatitbility shown above.
XM001964A
2 Resource requirements
IN THIS CHAPTER
· Ports
· Logical cores
· Memory
· Channel usage
· Client timing requirements
This section provides an overview of the required resources of sc_multi_uart
component so that the application designer can operate within these constraints
accordingly.
2.1
Ports
The following ports are required for each of the receive and transmit functions -
2.2
2.3
Operation
Port Type
Number required
Direction
Port purpose /
Notes
Transmit
Transmit
8 bit port
1 bit port
1
1
Output
Input
Receive
8 bit port
1
Input
Data transmission
Optional External
clocking (see §4.4)
Data Receive
Logical cores
Operation
Logical Core Count
Notes
Receive
1
Transmit
1
Single logical core server, may require
application defined buffering logical core requires 62.5MIPS per logical core
Single logical core server - requires
62.5MIPS per logical core
Memory
The following is a summary of memory usage of the component for all functionality
utilised by the echo test application when compiled at optimisation level 3. It
assumes a TX buffer of 16 slots and operating at the maximum of 8 UART channels.
XM001964A
MultiUART module usage manual
6/38
This is deemed to be a guide only and memory usage may differ according how
much of the API is utilised.
Stack usage is estimated at 460 bytes.
2.4
2.5
Operation
Code (bytes)
Data (bytes)
Total Usage (bytes)
Receive Logical Core
Receive API
Transmit Logical Core
Transmit API
Total
316
410
1322
480
2159
424
0
940
0
1364
740
410
2262
480
3523
Channel usage
Operation
Channel Usage & Type
Receive
Transmit
1 x Streaming Chanend
1 x Streaming Chanend
Client timing requirements
The application that interfaces to the receive side of UART component must meet
the following timing requirement. This requirement is dependent on configuration
so the worst case configuration must be accounted for - this means the shortest
UART word (length of the start, data parity and stop bits combined).
1
U ART _CHAN_COUNT ×
MAX_BAUD
MIN_BIT _COUNT
Taking an example where the following values are applied -
· UART_CHAN_COUNT = 8
· MAX_BAUD = 115200 bps
· MIN_BIT_COUNT = 10 (i.e 1 Start Bit, 8 data bits and 1 stop bit)
The resultant timing requirement is 10.85 µS. This would be defined and constrained using the XTA tool.
XM001964A
3 Evaluation platforms
IN THIS CHAPTER
· Recommended hardware
· XA-SK-UART8 sliceCARD
· Demonstration application
3.1
Recommended hardware
This module may be evaluated using the sliceKIT modular development platform,
available from digikey. Required boards are:
· XP-SKC-L16 plus XA-SK-UART8 plus XA-SK-XTAG2 (Slicekit XTAG-2 adaptor) plus
XTAG2 (debug adaptor)
XM001964A
MultiUART module usage manual
3.2
XA-SK-UART8 sliceCARD
3.3
Demonstration application
8/38
Example usage of this module can be found within the xSOFTip suite as follows:
· Package: sc_multi_uart
· Application: app_sk_muart_com_demo
XM001964A
4 Module description
IN THIS CHAPTER
· Cores
· Buffering
· Communication model
· Clocking
The MultiUART module consists of transmit and receive servers. These can be
employed independently or together based on the application needs.
4.1
Cores
The MultiUART component comprises two logical cores, one acting as a transmit
(TX) server for up to 8 uarts, and the other acting as a receive (RX) server for up to
8 uarts.
4.2
Buffering
Buffering for the TX server is handled within the UART TX logical core. The buffer is
configurable allowing the number of buffer slots that are available to be configured,
subject only to available memory. Data is transferred to the UART TX logical core
via a shared memory interface and therefore any client logical core must be on the
same tile as the UART logical core.
There is no buffering provided by the RX server. The application must provide a
logical core that is able to respond to received characters in real time and handle
any buffering requirements for the application that is being developed.
4.3
Communication model
The module utilises a combination of shared memory and channel communication.
Channel communication is used on both the RX and TX servers to pause the logical
core and subsequently release the logical core when required for reconfiguration.
The primary means of data transfer for both the RX and TX logical cores is shared
memory. The RX logical core utilises a channel to notify any client of available
data - this means that events can be utilised within an application to avoid the
requirement for polling for received data.
XM001964A
MultiUART module usage manual
4.4
10/38
Clocking
The module can be configured to either use an external clock source or an internal
clock source. External clock source only applies to the TX portion of the component
(see §9.2.1). The advantage of using an external clock source is that an exact baud
rate can be achieved by dividing down a master clock such as 1.8432MHz. This is
a typical method that standard RS232 devices will use.
Using internal clocking is possible, but for TX the implementation currently limits
the application to configuring baud rates that divide exactly into the internal clock.
So if the system reference runs at 100MHz the maximum baud rate is 100kbaud.
The RX implementation uses the internal clock under all circumstances. Clock drift
is handled by the implementation utilising oversampling to ensure that the bit is
sampled as close to the centre of the bit time as possible. This minimises error
due to the small drift that is encountered. The syncronisation of the sampling is
also reset on every start bit so drift is minimised in a stream of data.
It should be noted that if extremely long data lengths are used the drift encountered
may become large as the fractional error will accumulate over the length of the
UART word. By taking the fractional error (say for an internal clock of 100MHz and
a baud rate of 115200bps we have a fractional error of 0.055) and multiplying it
by the number of bits in a UART word (for 8 data bits, 1 parity and one stop bit we
have a word length of 11 bits). Thus for the described configuration a drift of 0.61
clock ticks is encountered. This equates to 0.07%.
XM001964A
5 MultiUART common API
IN THIS CHAPTER
· Enum definitions
· Combined RX & TX server launch functions
The following describes the shared API between the UART RX Server and UART TX Server code.
5.1
Enum definitions
ENUM_UART_CONFIG_PARITY
Define the parity configuration.
Values
odd
Odd parity.
even
Even parity.
mark
Mark (always 1) parity bit.
space
Space (always 0) parity bit.
none
No parity bit.
ENUM_UART_CONFIG_STOP_BITS
Configure the number of stop bits.
Values
sb_1
Single stop bit.
sb_2
Two stop bits.
ENUM_UART_CONFIG_POLARITY
Start bit polarity configuration (currently unused).
Values
XM001964A
MultiUART module usage manual
5.2
start_1
Start bit is a 1, implies stop bit/idle is a 0.
start_0
Start bit is a 0, implies stop bit/idle is a 1.
12/38
Combined RX & TX server launch functions
run_multi_uart_rxtx_int_clk()
Configure and run the Multi-UART TX & RX server threads using internal clocks for
TX & RX.
Type
void run_multi_uart_rxtx_int_clk(streaming chanend cTxUart,
s_multi_uart_tx_ports &uart_tx_ports,
streaming chanend cRxUart,
s_multi_uart_rx_ports &uart_rx_ports,
clock uart_clock_rx,
clock uart_clock_tx)
Parameters
cTxUart
TX Server Channel
uart_tx_ports
TX Ports structure
cRxUart
RX Server Channel
uart_rx_ports
RX Ports structure
uart_clock_rx
Clock block to run the RX port from
uart_clock_tx
Clock block to run the TX port from
XM001964A
MultiUART module usage manual
13/38
run_multi_uart_rxtx()
Configure and run the Multi-UART TX & RX server threads using an external clock
for TX.
Type
void run_multi_uart_rxtx(streaming chanend cTxUart,
s_multi_uart_tx_ports &uart_tx_ports,
streaming chanend cRxUart,
s_multi_uart_rx_ports &uart_rx_ports,
clock uart_clock_rx,
in port uart_ext_clk_pin,
clock uart_clock_tx)
Parameters
cTxUart
TX Server Channel
uart_tx_ports
TX Ports structure (reference parameter)
cRxUart
RX Server Channel
uart_rx_ports
RX Ports structure (reference parameter)
uart_clock_rx
Clock block to run the RX port from
uart_ext_clk_pin
External clock reference input pin
uart_clock_tx
Clock block to run the TX port from
XM001964A
6 MultiUART transmit API
IN THIS CHAPTER
· Configuration defines
· Data structures
· Configuration functions
· Transmission functions
· MultiUART TX server
The following describes the public API for use in applications and the API’s usage.
6.1
Configuration defines
The file multi_uart_tx_conf.h must be provided in the application source code. This file should
comprise of the following defines:
UART_TX_USE_EXTERNAL_CLOCK
Define whether to use an external clock reference for transmit - do not define this if using the
internal clocking
UART_TX_CHAN_COUNT
Define the number of channels that are to be supported, must fit in the port. Also, must be a
power of 2 (i.e. 1,2,4,8) - not all channels have to be utilised
UART_TX_CLOCK_RATE_HZ
This defines the master clock rate - if using an external clock then set this appropriately (e.g.
1843200 for a 1.8432MHz external clock)
UART_TX_MAX_BAUD
Define the maximum application baud rate - this implementation is validated to 115200 baud
UART_TX_CLOCK_DIVIDER
This should be defined as (UART_TX_CLOCK_RATE_HZ/UART_TX_MAX_BAUD_RATE). But some use
cases may require a custom divide.
UART_TX_OVERSAMPLE
Define the oversampling of the clock - this is where the UART_TX_CLOCK_DIVIDER is > 255
(otherwise set to 1) - only used when using an internal clock reference
XM001964A
MultiUART module usage manual
15/38
UART_TX_BUF_SIZE
Define the buffer size in UART word entries - needs to be a power of 2 (i.e. 1,2,4,8,16,32)
UART_TX_IFB
Define the number of interframe bits
6.2
Data structures
STRUCT_MULTI_UART_TX_PORTS
Structure used to hold ports - used to enable extensibility in the future.
Fields
buffered out port:8 pUart
STRUCT_MULTI_UART_TX_CHANNEL
Structure to hold configuration information and data for the UART channel TX side this should only be interacted with via the API and not accessed directly.
XM001964A
MultiUART module usage manual
6.3
16/38
Configuration functions
uart_tx_initialise_channel()
Configure the UART channel.
Type
int uart_tx_initialise_channel(int channel_id,
e_uart_config_parity parity,
e_uart_config_stop_bits stop_bits,
e_uart_config_polarity polarity,
int baud,
int char_len)
Parameters
channel_id
Channel Identifier
parity
Parity configuration
stop_bits
Stop bit configuration
polarity
Start/Stop bit polarity setting
baud
Required baud rate
char_len
Length of a character in bits (e.g. 8 bits)
Returns
Return 0 on success
uart_tx_reconf_pause()
Pause the Multi-UART TX task for reconfiguration.
Type
void uart_tx_reconf_pause(streaming chanend cUART, timer t)
Parameters
XM001964A
cUART
chanend to UART TX thread
t
timer for running buffer clearance pause
MultiUART module usage manual
17/38
uart_tx_reconf_enable()
Release the UART into normal operation - must be called after uart_tx_reconf_pause.
Type
void uart_tx_reconf_enable(streaming chanend cUART)
Parameters
cUART
6.4
channel end to TX UART
Transmission functions
uart_tx_assemble_word()
Assemble full word for transmission.
Type
unsigned int uart_tx_assemble_word(int channel_id, unsigned int uart_char)
Parameters
channel_id
Channel identifier
uart_char
The character being sent
Returns
Full UART word in the format (msb -> lsb) STOP|PARITY|DATA|START
uart_tx_put_char()
Assemble UART word from UART Character and insert into the appropriate UART
buffer.
Type
int uart_tx_put_char(int channel_id, unsigned int uart_char)
Parameters
channel_id
Channel identifier
uart_char
Character to be sent over UART
Returns
0 for OK, -1 for buffer full
XM001964A
MultiUART module usage manual
6.5
MultiUART TX server
run_multi_uart_tx()
Multi UART Transmit function.
Type
void run_multi_uart_tx(streaming chanend cUART,
s_multi_uart_tx_ports &tx_ports,
clock uart_clock)
XM001964A
18/38
7 MultiUART receive API
IN THIS CHAPTER
· Configuration defines
· Data structures
· Configuration functions
· Data validation functions
· Data fetch functions
· MultiUART RX server
The following describes the public API for use in applications and the API’s usage.
7.1
Configuration defines
The file multi_uart_rx_conf.h must be provided in the application source code. This file should
comprise of the following defines:
UART_RX_CHAN_COUNT
Define the number of channels that are to be supported, must fit in the port. Also, must be a
power of 2 (i.e. 1,2,4,8) - not all channels have to be utilised
UART_RX_CLOCK_RATE_HZ
This defines the master clock rate - in this implementation this is the system clock in Hertz.
This should be 100000000.
UART_RX_MAX_BAUD
Define the maximum application baud rate - this implementation is validated to 115200 baud
UART_RX_CLOCK_DIVIDER
This should be defined as (UART_RX_CLOCK_RATE_HZ/UART_RX_MAX_BAUD). But some use cases
may require a custom divide.
UART_RX_OVERSAMPLE
Define receive oversample for maximum baud rate. This should be left at 4.
7.2
Data structures
STRUCT_MULTI_UART_RX_PORTS
XM001964A
MultiUART module usage manual
20/38
Structure used to hold ports - used to enable extensibility in the future.
Fields
buffered in port:32 pUart
STRUCT_MULTI_UART_RX_CHANNEL
Structure to hold configuration information and data for the UART channel RX side this should only be interacted with via the API and not accessed directly.
Fields
int uart_char_len
length of the UART character
int uart_word_len
number of bits in UART word e.g.
Start bit + 8 bit data + parity + 2 stop bits is a 12 bit UART word
int clocks_per_bit
define baud rate in relation to max baud rate
int invert_output
define if output is inverted (set to 1)
int use_sample
sample in bit stream to use
e_uart_config_stop_bits sb_mode
Stop bit configuration.
e_uart_config_parity parity_mode
Parity mode configuration.
e_uart_config_polarity polarity_mode
Polarity mode of start/stop bits.
XM001964A
MultiUART module usage manual
7.3
21/38
Configuration functions
uart_rx_initialise_channel()
Configure the UART channel.
Type
int uart_rx_initialise_channel(int channel_id,
e_uart_config_parity parity,
e_uart_config_stop_bits stop_bits,
e_uart_config_polarity polarity,
int baud,
int char_len)
Parameters
channel_id
Channel Identifier
parity
Parity configuration
stop_bits
Stop bit configuration
polarity
Polarity configuration of start/stop bits
baud
Required baud rate
char_len
Length of a character in bits (e.g. 8 bits)
Returns
Return 0 on success
uart_rx_reconf_pause()
Pause the UART via channel for reconfiguration.
Type
void uart_rx_reconf_pause(streaming chanend cUART)
Parameters
cUART
streaming channel end to RX server
uart_rx_reconf_enable()
Release the UART into normal operation - must be called after uart_rx_reconf_pause.
Type
void uart_rx_reconf_enable(streaming chanend cUART)
Parameters
cUART
XM001964A
channel end to RX UART
MultiUART module usage manual
7.4
22/38
Data validation functions
uart_rx_validate_char()
Validate received UART word according to channel configuration and provide a
cleaned UART character.
Type
int uart_rx_validate_char(int chan_id, unsigned &uart_word)
Parameters
chan_id
UART channel ID from which the char came from
uart_word
UART char in the format DATA_BITS|PARITY|STOP BITS (parity
optional according to config), modified to clean UART character
on successful * return
Returns
Return 0 on valid data, -1 on validation fail
7.5
Data fetch functions
uart_rx_grab_char()
Get the received value from an RX slot.
Type
unsigned uart_rx_grab_char(unsigned chan_id)
Parameters
chan_id
Returns
value in slot
XM001964A
channel id to grab
MultiUART module usage manual
7.6
MultiUART RX server
run_multi_uart_rx()
Multi-UART Receive Server.
Type
void run_multi_uart_rx(streaming chanend cUART,
s_multi_uart_rx_ports &tx_ports,
clock uart_clock)
Parameters
XM001964A
cUART
channel interface for RX UART
tx_ports
port structure
uart_clock
clock block for UART
23/38
8 MultiUART helper API
This API provides a number of functions that allow the access of architecture specific functionality
within C where XC semantics are not available.
get_time()
Get time from timer.
Type
unsigned get_time(timer t)
Parameters
t
timer
Returns
timestamp from timer
wait_for()
Wait for a time period defined by delta.
Type
unsigned wait_for(timer t, unsigned delta)
Parameters
t
timer to use
delta
time period to wait
Returns
timestamp on completion of pause
XM001964A
MultiUART module usage manual
wait_until()
Wait until a specific time stamp.
Type
unsigned wait_until(timer t, unsigned ts)
Parameters
t
timer to use
ts
time stamp to wait until
Returns
timestamp on completion of pause
send_streaming_int()
Send integer value across a streaming channel end.
Type
void send_streaming_int(streaming_chanend c, int i)
Parameters
c
chanend to use
i
integer to send
get_streaming_uint()
Get unsigned integer from streaming chanend.
Type
unsigned get_streaming_uint(streaming_chanend c)
Parameters
c
chanend to use
Returns
value received over the channel
XM001964A
25/38
MultiUART module usage manual
get_streaming_token()
Get token from streaming chanend.
Type
char get_streaming_token(streaming_chanend c)
Parameters
c
chanend to use
Returns
token received over channel
XM001964A
26/38
9 Programming guide
IN THIS CHAPTER
· Structure
· Configuration of MultiUART component
· Initialization
· Interfacing to the TX server
· Interfacing to the RX server
· Reconfiguration of RX & TX server
This section discusses the programming aspects of the MultiUART component and
typical implementation and usage of the API.
9.1
Structure
This is an overview of the key header files that are required, as well as the logical
core structure and information regarding the buffering provision and requirements
for the component.
9.1.1
Source code
All of the files required for operation are located in the module_multi_uart directory.
The files that need to be included for use of this component in an application are:
File
Description
multi_uart_rxtx.h
Header file for simplified launch of both the TX and RX
server logical cores, also provides the headers for the
individual RX and TX API interfaces.
Header file providing configuration ENUM definitions
and other constants that may be required for operation
Header file for accessing the API of the RX UART server
- included by multi_uart_rxtx.h
Header file for accessing the API of the TX UART server
- included by multi_uart_rxtx.h
multi_uart_common.h
multi_uart_rx.h
multi_uart_tx.h
9.2
Configuration of MultiUART component
MultiUART component configuration takes place in two domains - a static compile
time configuration (discussed in this section) and a runtime dynamic configuration
(as discussed in §9.3 and §9.6).
XM001964A
MultiUART module usage manual
28/38
Static configuration is done by the application providing configuration header files
multi_uart_tx_conf.h and multi_uart_rx_conf.h.
9.2.1
Static configuration of UART TX
Below is a summary of the configuration options that are in the
multi_uart_tx_conf.h file, their suggested defaults and an explanation of their
function.
XM001964A
MultiUART module usage manual
Define
Default
UART_TX_USE_EXTERNAL_CLOCK
(None)
XM001964A
29/38
Other options
Not defined
Explanation
The presence
of this define
turns on or off
the requirement
to use external
clocking
this
is discussed in
§4.4.
UART_TX_CLOCK_RATE_HZ
1843200
| Any valid clock Defines
the
100000000
rate
clock rate that
the baud rates
are
derived
from
UART_TX_MAX_BAUD_RATE
115200
less
than Defines the max
or equal to baud rate the
115200
API will allow
configuration
of. Validated to
115200
UART_TX_CLOCK_DIVIDER
(UART_TX_CLOCK_RATE_HZ
Any appropriate It is recom/
divider
mended
to
UART_TX_MAX_BAUD_RATE)
leave this at the
default.
It is
used to set the
clock
divider
when
configuring clocking
from the internal
reference
clock
UART_TX_OVERSAMPLE
2
{1|2}
Define
the
oversampling
of the clock this is where the
UART_TX_CLOCK_DIVIDER
is > 255 (otherwise set to
1) - only used
when using an
internal clock
reference
UART_TX_BUF_SIZE 16
{1,2,4,8,16,32,...} Define
the
buffer
size
in
UART
word
entries
- needs to be a
power of 2 (i.e.
1,2,4,8,16,32)
UART_TX_CHAN_COUNT
8
{1,2,4,8}
Define the number of channels
that
are
to
be supported,
must fit in the
port. Also, must
be a power of
2 (i.e. 1,2,4,8)
MultiUART module usage manual
9.2.2
30/38
Static configuration of UART RX
Below is a summary of the configuration options that are in the
multi_uart_rx_conf.h file, their suggested defaults and an explanation of their
function.
XM001964A
MultiUART module usage manual
Define
Default
31/38
Other options
Explanation
UART_RX_CHAN_COUNT
8
{1,2,4,8}
UART_RX_CLOCK_RATE_HZ
100000000
System
erence
rate
UART_RX_MAX_BAUD
115200
less
than
or equal to
115200
Define the number of channels
that
are
to
be supported,
must fit in the
port. Also, must
be a power of
2 (i.e. 1,2,4,8)
- not all channels have to be
utilised
Defines
the
clock rate that
the baud rates
are
derived
from
Defines the max
baud rate the
API will allow
configuration
of. Validated to
115200.
It is recommended
to
leave this at the
default. Is used
to set the clock
divider
when
configuring
clocking using
either internal
or
external
clocks.
Oversample
count for the
max baud rate.
It is recommended
that
this value is left
as it is unless
the effects of
changing
it
are well understood.
refclock
UART_RX_CLOCK_DIVIDER
(UART_RX_CLOCK_RATE_HZ
Any appropriate
/
divider
UART_RX_MAX_BAUD)
UART_RX_OVERSAMPLE
4
XM001964A
Should remain
at 4
MultiUART module usage manual
9.3
32/38
Initialization
The initialisation and configuration process for both the RX and TX operations
is the same. For configuration, the functions uart_rx_initialise_channel() or
uart_tx_initialise_channel() are utilised. The flow is visualised in Figure 1 and a
working example taken from the app_sk_muart_com_demo application that is
used for verification.
Figure 1:
UART
Initialisation
Flow
The following working example is taken from uart_manager.xc and shows a typical
initial configuration.
/* configure UARTs */
for ( int i = 0; i < U A R T _ R X _ C H A N _ C O U N T ; i ++)
{
if ( u a r t _ t x _ i n i t i a l i s e _ c h a n n e l ( i , even , sb_1 , start_0 , uart_baud , 8 ) )
{
printstr ( " Uart TX configuration failed for channel : " ) ;
printintln ( i ) ;
}
if ( u a r t _ r x _ i n i t i a l i s e _ c h a n n e l ( i , even , sb_1 , start_0 , uart_baud , 8 ) )
{
printstr ( " Uart RX configuration failed for channel : " ) ;
printintln ( i ) ;
}
}
The next stage of initialisation is to release the server logical cores from their
paused state. Upon start up their default state is to be paused until the following
channel communication is completed.
XM001964A
MultiUART module usage manual
9.4
33/38
Interfacing to the TX server
To transmit data using the TX server the application should make use of
uart_tx_put_char(). An example use is shown below. This example, taken from the
demo application configuration simply takes a string from the application buffer
(simply can be a character array) and pushes it into the buffer one character at
a time. When the API indicates that the buffer is full by returning a value of -1
then the buffer index is not incremented in order to retain the character in the
application buffer until it is successfully pushed to UART TX server.
buffer_space = u a r t _ t x _ p u t _ c h a r ( st . uart_id , ( unsigned int ) data ) ;
if ( -1 != buffer_space )
{
/* Data is sent to uart successfully */
st . read_index ++;
if ( st . read_index >= UART_FIFO_LEN ) {
st . read_index = 0;
}
st . buf_depth - -;
} // if ( -1 != buffer_space )
This operation must be completed on the same tile as the TX server logical core as
the communication module utilises shared memory.
9.5
Interfacing to the RX server
To receive data from the RX server the application should make use of the channel
that is provided. The channel provides notification to the application of which
UART channel has data ready. The data itself is stored in a single storage slot
with no buffering. This means that if the application layer fails to meet the
timing requirements (as discussed in Client timing §2.5) data may be lost and/or
duplicated.
The application implements an level buffering for receiving data. This may or may
not be required in a particular implementation - dependant on whether timing
requirements can be met. The receive and processing loop is shown below.
select
{
# pragma ordered
case c_rx_uart : > rx_channel_id :
{
unsigned uart_char ;
uart_char = ( unsigned ) u a r t _ r x _ g r a b _ c h a r ( rx_channel_id ) ;
if ( u a r t _ r x _ v a l i d a t e _ c h a r ( rx_channel_id , uart_char ) == 0) {
Once the token is received over the channel informing the application of the UART
channel which has data ready the application uses the uart_rx_grab_char() function
XM001964A
MultiUART module usage manual
34/38
to collect the data from the receive slot. This provides an unvalidated word. The
application then utilises the uart_rx_validate_char() to ensure that the UART word
fits the requirements of the configuration (parity, stop bits etc) and provides the
data upon return in the uart_char variable. This data is then inserted into a buffer.
9.6
Reconfiguration of RX & TX server
The method for reconfiguring the UART software is the same for both the RX
and the TX servers. When the application requires a reconfiguration then a call
to uart_tx_reconf_pause() or uart_rx_reconf_pause() needs to be made. When
reconfiguring the RX side the server logical core will pause immediately, however
when pausing the TX side the server logical core will pause the application logical
core to allow the buffers to empty in the TX logical core.
Once the functions exit the server logical cores will be paused. Configuration is
then done utilising the same methodology as initial configuration using a function
such as the uart_tx_initialise_channel() or uart_rx_initialise_channel().
Following the reconfiguration the application must then call uart_tx_reconf_enable()
and uart_rx_reconf_enable() to re-enable the TX and RX logical cores respectively.
The listing below gives an example of reconfiguration that is taken from the echo
test demonstration and test application.
u a r t _ t x _ r e c o n f _ p a u s e ( c_tx_uart , t ) ;
u a r t _ r x _ r e c o n f _ p a u s e ( c_rx_uart ) ;
u a r t _ t x _ i n i t i a l i s e _ c h a n n e l ( uart_id_to_reconfig , even , sb_1 , start_0 ,
> uart_baud , 8 ) ;
u a r t _ r x _ i n i t i a l i s e _ c h a n n e l ( uart_id_to_reconfig , even , sb_1 , start_0 ,
> uart_baud , 8 ) ;
u a r t _ t x _ r e c o n f _ e n a b l e ( c_tx_uart ) ;
u a r t _ r x _ r e c o n f _ e n a b l e ( c_rx_uart ) ;
XM001964A
10Example applications
IN THIS CHAPTER
· app_sk_muart_com_demo application
This section discusses the demonstration application that uses MultiUART module.
10.1
app_sk_muart_com_demo application
This application is available as app_sk_muart_com_demo under sc_multi_uart component directory. See the evaluation platforms section of this document for
required hardware.
10.1.1
Required software tools
The following tools should be installed on the host system in order to run this
application
· For Win 7: Hercules Setup Utility by HW-Group
· http://www.hw-group.com/products/hercules/index_en.html
· For MAC users: SecureCRT7.0
· http://www.vandyke.com/download/securecrt/
10.1.2
Build options
app_sk_muart_com_demo application uses the following modules in order to achieve
its desired functionality.
· sc_multi_uart: utilizes TX and RX servers provided by the component
· sc_util: uses module_xc_ptr functions to perform pointer related arithmetic
such as reading from and writing into memory
This demo application is built by default for XP-SKC-L16 sliceKIT board, SQUARE
connector type. This application can also be built for TRIANGLE or STAR connectors
as follows:
To build for STAR connector, make the following changes in src\main.xc file:
· Modify tile number from 1 to 0
To build for TRIANGLE connector, make the following changes in src\main.xc file:
· Modify tile number from 1 to 0
XM001964A
MultiUART module usage manual
36/38
· Modify 8 bit port assignment of UART TX from XS1_PORT_8B to XS1_PORT_8D
· Modify 8 bit port assignment of UART RX from XS1_PORT_8A to XS1_PORT_8C
· Modify external clock refernce from XS1_PORT_1F to XS1_PORT_1L
The module requires 8-bit ports for both UART transmit and UART receive ports.
Upon selection of an appropriate type of connector, the port declarations for the
MultiUART component are derived automatically.
10.1.3
10.1.3.1
Hardware settings
Voltage levels
· CMOS TTL
· RS-232
By default, this sliceCARD uses the RS-232 levels. In order to use the CMOS TTL
levels, short J3 pins (25-26) of the sliceCARD. All 8 UART channels must use the
same voltage setting.
10.1.3.2
UART header connections
When using the RS-232 levels, UART device pins must be connected to J4 of
XA-SK-UART8 sliceCARD.
When using TTL levels, UART device pins must be connected to J3 of MultiUART
sliceCARD (along with J3 25-26 pins shorted). UART information of XA-SK-UART8
sliceCARD is as follows:
XM001964A
MultiUART module usage manual
37/38
XA-SK-UART8 sliceCARD for demo applications
UART Identifier
J3/J4 Pin no.(TX)
J3/J4 Pin no.(RX)
0
1
2
3
4
5
6
7
1
5
7
11
13
17
19
23
2
6
8
12
14
18
20
24
Optionally, Uart #0 may be accessed via the DB9 connector on the end of the
sliceCARD and thus connected directly to a PC COM port.
10.1.4
Application description
The demonstration application shows a typical application structure that would
employ the MultiUART module.
In addition to the two MultiUART logical cores used by sc_multi_uart, the application utilises one more logical core to manage UART data from transmit and receive
logical cores.
UART data received may be user commands or data related to a user command
selection (see §10.1.6).
The application provides some buffers (FIFO) to hold data received from UARTs.
When the RX logical core receives a character over the UART, it signals application
handler to process the data. Appliaction receive handler validates the data and
performs specific actions.
Generally, the data token received by RX buffering logical core tells which UART
channel a character has been received on. The logical core then extracts this
character out of the buffer slot, validates it utilising the provided validation function and inserts it into a larger, more comprehensive buffer.The RX buffering is
implemented as an example only and may not be necessary for other applications.
The TX logical core already provides some buffering supported at the component
level.
The TX handler operates by polling the buffer when it has to transmit data related
to any UARTS.
The channel for the TX logical core is primarily used for reconfiguration. This is
discussed in more detail in §9.6. Specific usage of the API is also discussed in §9.4
and §9.5.
XM001964A
MultiUART module usage manual
10.1.5
38/38
Quickstart guide
Quickstarter guide and application usage is available in doc_quickstart of the
application.
10.1.6
10.1.6.1
Interacting with the application
Command interface
The application provides the following commands to interact with it:
· e - in this mode, an entered character is echoed back on the console
· r - reconfigure UART for a different baud rate
· f - transfer a file using a single UART
· b - pipe file through all uart channels
· h - displays user menu
In order to come out of a selected mode, press the Esc key. At any instance
Esc key can be pressed to revert back to user menu.
10.1.7
Makefiles
The main Makefile for the project is in the application directory. This file specifies
build options and used modules. The Makefile uses the common build infrastructure in xcommon. This system includes the source files from the relevant modules
and is documented within xcommon.
10.1.8
Using command line tools
To build from the command line, change to app_sk_muart_com_demo directory
and execute the command:
xmake all
Open the XMOS command line tools (Desktop Tools Prompt) and execute the
following command:
xflash < binary >. xe
XM001964A
MultiUART module usage manual
39/38
Copyright © 2014, All Rights Reserved.
Xmos Ltd. is the owner or licensee of this design, code, or Information (collectively, the “Information”) and
is providing it to you “AS IS” with no warranty of any kind, express or implied and shall have no liability in
relation to its use. Xmos Ltd. makes no representation that the Information, or any particular implementation
thereof, is or will be free from any claims of infringement and again, shall have no liability in relation to any
such claims.
XMOS and the XMOS logo are registered trademarks of Xmos Ltd. in the United Kingdom and other countries,
and may not be used without written permission. All other trademarks are property of their respective owners.
Where those designations appear in this book, and XMOS was aware of a trademark claim, the designations
have been printed with initial capital letters or in all capitals.
XM001964A