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
© Copyright 2024