<< >>

Multi-UART Common API

The following describes the shared API between the UART RX Server and UART TX Server code.

Enum Definitions

ENUM_UART_CONFIG_PARITY

Define the parity configuration.

Enum Values:

odd
0x1

Odd parity.

even
0x2

Even parity.

mark
0x3

Mark (always 1) parity bit.

space
0x4

Space (always 0) parity bit.

none
0x0

No parity bit.

ENUM_UART_CONFIG_STOP_BITS

Configure the number of stop bits.

Enum Values:

sb_1

Single stop bit.

sb_2

Two stop bits.

ENUM_UART_CONFIG_POLARITY

Start bit polarity configuration (currently unused).

Enum Values:

start_1
1

Start bit is a 1, implies stop bit/idle is a 0.

start_0
0

Start bit is a 0, implies stop bit/idle is a 1.

Combined RX & TX Server Launch Functions

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)

Configure and run the Multi-UART TX & RX server threads using internal clocks for TX & RX.

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
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)

Configure and run the Multi-UART TX & RX server threads using an external clock for 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

Multi-UART Transmit API

The following describes the public API for use in applications and the API’s usage.

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

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

Data Structures

STRUCT_MULTI_UART_TX_PORTS

Structure used to hold ports - used to enable extensibility in the future.

Structure Members:

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.

Configuration Functions

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)

Configure the UART channel.

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
void uart_tx_reconf_pause(streaming chanend cUART, timer t)

Pause the Multi-UART TX thread for reconfiguration.

Parameters:
  • cUART – chanend to UART TX thread
  • t – timer for running buffer clearance pause
void uart_tx_reconf_enable(streaming chanend cUART)

Release the UART into normal operation - must be called after uart_tx_reconf_pause.

Parameters:
  • cUART – channel end to TX UART

Transmission Functions

unsigned int uart_tx_assemble_word(int channel_id, unsigned int uart_char)

Assemble full word for transmission.

Parameters:
  • channel_id – Channel identifier
  • uart_char – The character being sent
Returns:

Full UART word in the format (msb -> lsb) STOP|PARITY|DATA|START
int uart_tx_put_char(int channel_id, unsigned int uart_char)

Assemble UART word from UART Character and insert into the appropriate UART buffer.

Parameters:
  • channel_id – Channel identifier
  • uart_char – Character to be sent over UART
Returns:

0 for OK, -1 for buffer full

Multi-UART TX Server

void run_multi_uart_tx(streaming chanend cUART, s_multi_uart_tx_ports &tx_ports, clock uart_clock)

Multi UART Transmit Thread.

Multi-UART Receive API

The following describes the public API for use in applications and the API’s usage.

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.

Data Structures

STRUCT_MULTI_UART_RX_PORTS

Structure used to hold ports - used to enable extensibility in the future.

Structure Members:

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.

Structure Members:

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.

Configuration Functions

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)

Configure the UART channel.

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
void uart_rx_reconf_pause(streaming chanend cUART)

Pause the UART via channel for reconfiguration.

Parameters:
  • cUART – streaming channel end to RX server
void uart_rx_reconf_enable(streaming chanend cUART)

Release the UART into normal operation - must be called after uart_rx_reconf_pause.

Parameters:
  • cUART – channel end to RX UART

Data Validation Functions

int uart_rx_validate_char(int chan_id, unsigned &uart_word)

Validate received UART word according to channel configuration and provide a cleaned UART character.

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 charcater on successful * return
Returns:

Return 0 on valid data, -1 on validation fail

Data Fetch Functions

unsigned uart_rx_grab_char(unsigned chan_id)

Get the received value from an RX slot.

Parameters:
  • chan_id – channel id to grab
Returns:

value in slot

Multi-UART RX Server

void run_multi_uart_rx(streaming chanend cUART, s_multi_uart_rx_ports &tx_ports, clock uart_clock)

Multi-UART Receive Server.

Parameters:
  • cUART – channel interface for RX UART
  • tx_ports – port structure
  • uart_clock – clock block for UART

Multi-UART 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.

unsigned get_time(timer t)

Get time from timer.

Parameters:
  • t – timer
Returns:

timestamp from timer
unsigned wait_for(timer t, unsigned delta)

Wait for a time period defined by delta.

Parameters:
  • t – timer to use
  • delta – time period to wait
Returns:

timestamp on completion of pause
unsigned wait_until(timer t, unsigned ts)

Wait until a specific time stamp.

Parameters:
  • t – timer to use
  • ts – time stamp to wait until
Returns:

timestamp on completion of pause
void send_streaming_int(streaming_chanend c, int i)

Send integer value across a streaming channel end.

Parameters:
  • c – chanend to use
  • i – integer to send
unsigned get_streaming_uint(streaming_chanend c)

Get unsigned integer from streaming chanend.

Parameters:
  • c – chanend to use
Returns:

value received over the channel
char get_streaming_token(streaming_chanend c)

Get token from streaming chanend.

Parameters:
  • c – chanend to use
Returns:

token received over channel

Multi-UART Module Usage (0.1)