Synergy Software Package User's Manual
UART Communications Framework

Table of Contents

UART Communications Framework Module Introduction

The UART communications framework implements a high-level API for serial communications supporting the industry standard UART protocol on a UART-compliant Synergy MCU peripheral. It utilizes the r_sci_uart HAL driver to configure and operate the Synergy MCU SCI peripheral in the UART mode.

UART Communications Framework Module Features

This module is a ThreadX-aware communications framework; it uses ThreadX objects to ensure that the operations are thread safe.

Key features include:

  • Support for UART Communications protocol
  • Support for locking a channel to reserve exclusive access
  • ThreadX-aware implementation
uart_comms_BD.png
UART Communications Framework Module Block Diagram

UART Communications Framework Module APIs Overview

The UART Communications Framework module defines APIs for opening, closing, reading and writing to the communications channel. A complete list of the available APIs, an example API call and a short description of each can be found in the following table. A table of status return values follows the API summary table.

UART Communications Framework Module API Summary

Function Name Example API Call and Description
open g_sf_comms0.p_api->open(g_sf_comms0.p_ctrl, g_sf_comms0.p_cfg);
Initialize communications driver.
close g_sf_comms0.p_api->close(g_sf_comms0.p_ctrl);
Clean up communications driver.
read g_sf_comms0.p_api->read(g_sf_comms0.p_ctrl, &destination, bytes, timeout);
Read data from communications driver. This call will return after the number of bytes requested is read or if a timeout occurs while waiting for access to the driver.
write g_sf_comms0.p_api->write(g_sf_comms0.p_ctrl, &source, bytes, timeout);
Write data to communications driver. This call will return after all bytes are written or if a timeout occurs while waiting for access to the driver.
lock g_sf_comms0.p_api->lock(g_sf_comms0.p_ctrl, lock_type, timeout);
Lock the communications driver. Reserve exclusive access to the communications driver.
unlock g_sf_comms0.p_api->unlock(g_sf_comms0.p_ctrl, lock_type);
Unlock the communications driver. Release exclusive access to the communications driver.
versionGet g_sf_comms0.p_api->version(&version);
Store the driver version in the provided version.
Note
For more complete descriptions of operation and definitions for the function data structures, typedefs, defines, API data, API structures, and function variables, review the SSP User's Manual API References for the associated module.

Status Return Values

Name Description
SSP_SUCCESS Channel opened successfully.
SSP_ERR_IN_USE Channel already in use.
SSP_ERR_ASSERTION Pointer to UART control block or configuration structure is NULL.
SSP_ERR_HW_LOCKED Channel is locked.
SSP_ERR_INVALID_MODE Channel is used for non-UART mode or illegal mode is set.
SSP_ERR_INVALID_ARGUMENT Invalid parameter setting found in the configuration structure.
SSP_ERR_QUEUE_UNAVAILABLE Cannot open transmit or receive queue or both.
SSP_ERR_INTERNAL Internal error occurs.
SSP_ERR_TIMEOUT Timeout error.
SSP_ERR_INSUFFICIENT_DATA Not enough data in receive circular buffer.
SSP_ERR_RXBUF_OVERFLOW Receive queue overflow.
SSP_ERR_OVERFLOW Hardware overflow.
SSP_ERR_FRAMING Framing error.
SSP_ERR_PARITY Parity error.
SSP_ERR_INSUFFICIENT_SPACE Not enough space in transmission circular buffer.
Note
Lower-level drivers may return common error codes. Refer to the SSP User's Manual API References for the associated module for a definition of all relevant status return values.

UART Communications Framework Module Operational Overview

The UART Framework provides an easy-to-use communication framework using the standard UART protocol. In addition to the high-level API functions to read and write data from the UART device in a thread safe manner, the framework also provides API functions for applications to lock (and unlock) the UART channel to a thread. This is particularly useful when multiple application threads try to communicate with the same UART device and a context switch could upset the high-level application protocols and/or state machines implemented on top of the UART (like Kermit, for example).

UART Communications Framework Module Important Operational Notes and Limitations

UART Communications Framework Module Operational Notes

  • The UART Framework module is reentrant for any channel.
  • The UART Framework uses the UART Driver on r_sci_uart module for communicating with a UART device. The UART Driver can be augmented by adding DTC drivers (using the Synergy Platform configurator in the ISDE) to perform read or write transactions with a UART device without interrupting the CPU. When the UART Framework is used to read data from a UART device, it will rely on the UART Driver's callback feature to read data and will not use the DTC (even if the DTC module support is added to the UART Driver through the configurator). This is done to avoid any potential timing and synchronization issues that could arise when the driver uses the DTC to read data from the device. When using the UART Framework to write data to a UART device, it will use the DTC to perform the transaction (if the driver is configured to use the DTC).

UART Communications Framework Module Limitations

  • Refer to the most recent SSP Release Notes for any additional operational limitations for this module.

Including the UART Communications Framework Module in an Application

This section describes how to include the UART Communications Framework Module in an application using the SSP configurator.

Note
This section assumes you are familiar with creating a project, adding threads, adding a stack to a thread and configuring a block within the stack. If you are unfamiliar with any of these items, refer to the first few chapters of the SSP User's Manual to learn how to manage each of these important steps in creating SSP-based applications.

To add the UART Communications Framework to an application, simply add it to a thread using the stacks selection sequence given in the following table. (The default name for the UART Communications Framework is g_sf_comms0. This name can be changed in the associated Properties window.)

UART Communications Framework Module Selection Sequence

Resource ISDE Tab Stacks Selection Sequence
g_sf_comms0 Communications Framework on sf_uart_comms Threads Framework > Connectivity > Communications Framework on sf_uart_comms

When the UART Communications Framework on sf_uart_comms is added to the thread stack as shown in the following figure, the configurator automatically adds any needed lower‑level modules. Any modules needing additional configuration information have the box text highlighted in Red. Modules with a Gray band are individual modules that stand alone. Modules with a Blue band are shared or common; they need only be added once and can be used by multiple stacks. Modules with a Pink band can require the selection of lower-level modules; these are either optional or recommended. (This is indicated in the block with the inclusion of this text.) If the addition of lower-level modules is required, the module description include Add in the text. Clicking on any Pink banded modules brings up the New icon and displays possible choices.

uart_comms_MS.png
UART Communications Framework Module Stack

Configuring the UART Communications Framework Module

The UART Communications Framework Module must be configured by the user for the desired operation. The available configuration settings and defaults for all the user-accessible properties are given in the properties tab within the SSP configurator and are shown in the following tables for easy reference. Only properties that can be changed without causing conflicts are available for modification. Other properties are locked and not available for changes and are identified with a lock icon for the locked property in the Properties window in the ISDE. This approach simplifies the configuration process and makes it much less error-prone than previous manual approaches to configuration. The available configuration settings and defaults for all the user-accessible properties are given in the Properties tab within the SSP Configurator and are shown in the following tables for easy reference.

Note
You may want to open your ISDE, create the module and explore the property settings in parallel with looking over the following configuration table settings. This will help orient you and can be a useful 'hands-on' approach to learning the ins and outs of developing with SSP.

Configuration Settings for the UART Communications Framework Module on sf_uart_comms

ISDE Property Value Description
Parameter Checking BSP, Enabled, Disabled

Default: BSP 		Selects if parameter checking is included.
Read Input Queue Size (4-Byte Words) 15 Buffer size for data reception queue. sf_uart_comms utilizes the ThreadX Queue for the queue management.
Name g_sf_comms0 Name of UART communications framework module.
Name of generated initialization function sf_comms_init0 Name of generated initialization function selection.
Auto Initialization Enable, Disable

Default: Enable 		Auto initialization selection.
Note
The example settings and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

Configuration Settings for the UART Communications Framework Module Lower Level Modules

Typically, only a small number of settings must be modified from the default for lower level drivers as indicated via the red text in the thread stack block. Notice that some of the configuration properties must be set to a certain value for proper framework operation and will be locked to prevent user modification. The following tables identify all the settings within the properties section for the module.

Configuration Settings for the UART HAL Module on r_sci_uart

ISDE Property Value Description
External RTS Operation Enable, Disable

Default: Disable 		Enable an IOPORT pin to be used as RTS signal. For RTS functionality set this configuration parameter to "Enable" and specify the configuration "Name of UART callback function for the RTS external pin control".
Reception Enable, Disable

Default: Enable 		Enable or disable UART reception for all UART channels on SCI. Setting this configuration parameter to "Disable" reduces code size because the portion of code for UART reception is not compiled. You cannot set this parameter for individual UART channels.
Transmission Enable, Disable

Default: Enable 		Enable or disable UART transmission for all UART channels on SCI. Setting "Disable" to this configuration allows to get smaller code size due to the portion of code for UART transmission is compiled out, however, you can only set "Disable" to this configuration if any other SCI channels which work as UART ports do not perform the transmission.
Parameter Checking BSP, Enabled, Disabled

Default: BSP 		Enable or disable the parameter error checking.
Name g_uart0 The name to be used for UART on SCI module control block instance. This name is also used as the prefix of the other variable instances.
Channel 0 SCI channel number.
Baud Rate 9600 Baud rate selection.
Data Bits 7 bits, 8, bits, 9 bits

Default: 8 bits 		UART data bits.
Parity None, Odd, Even

Default: None 		UART parity bits.
Stop Bits 1 bit, 2 bits

Default: 1 bit 		UART stop bits.
CTS/RTS Selection CTS (Note that RTS is available when enabling External RTS Operation mode which uses 1 GPIO pin), RTS (CTS is disabled)

Default: RTS (CTS is disabled) 		Select CTS or RTS for the CTSn/RTSn pin of SCI channel n. The SCI hardware supports either the CTS or the RTS control signal on this pin but not both. For an application that uses both CTS and RTS, select "CTS" for this configuration parameter and enable the configuration "External RTS Operation" specifying the configuration "Name of UART callback function for the RTS external pin control".
Name of UART callback function to be defined by user NULL Name must be a valid C symbol.
Name of UART callback function for the RTS external pin control to be defined by user NULL Name must be a valid C symbol.
Clock Source Internal Clock, External Clock 8x baudrate, External Clock 16x baudrate

Default: Internal Clock 		Selection of the clock source to be used in the baud-rate clock generator block.
Baudrate Clock Output from SCK pin Enable, Disable

Defaualt: Disable 		Optional setting to output the baud-rate clock on the SCKn pin for the selected channel n.
Start bit detection Fallling Edge, Low Level

Default: Falling Edge 		Start bit detection mode in the reception, usually set "Falling Edge" to this configuration.
Noise Cancel Enable, Disable

Defaualt: Disable 		Enable the digital noise cancellation on RXDn pin. The digital noise filter block in SCI consists of two-stage flip-flop circuits. For detail, refer to the Noise cancellation section in the Renesas Synergy hardware manual.
Bit Rate Modulation Enable Enable, Disable

Defaualt: Enable 		Bit rate modulation enable selection.
Receive FIFO Trigger Level One, Max

Default: Max 		Receive FIFO trigger level selection.
Receive Interrupt Priority Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX)

Default: Priority 12 		Receive interrupt priority selection.
Transmit Interrupt Priority Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX)

Default: Priority 12 		Transmit interrupt priority selecition.
Transmit End Interrupt Priority Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX)

Default: Priority 12 		Transmit end interrupt priority selection.
Error Interrupt Priority Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX)

Default: Disabled 		Error interrupt priority selection.
Note
The example settings and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

Configuration Settings for the Transfer Driver on r_dtc Event SCI0 TXI

ISDE Property Value Description
Parameter Checking BSP, Enabled, Disabled

Default: BSP 		Selects if code for parameter checking is to be included in the build.
Software Start Enabled, Disabled

Defaualt: Disabled 		Software start selection.
Linker section to keep DTC vector table .ssp_dtc_vector_table Linker section to keep DTC vector table.
Name g_transfer0 Module name.
Mode Normal Mode selection.
Transfer Size 1 Byte Transfer size selection.
Destination Address Mode Fixed Destination address mode selection.
Source Address Mode Incremented Source address mode selection.
Repeat Area (Unused in Normal Mode Source Repeat area selection.
Interrupt Frequency After all transfers have completed Interrupt frequency selection.
Destination Pointer NULL Destination pointer selection.
Source Pointer NULL Source pointer selection.
Number of Transfers 0 Number of transfers selection.
Number of Blocks (Valid only in Block Mode) 0 Number of blocks selection.
Activation Source (Must enable IRQ) Event SCI0 TXI Activation source selection.
Auto Enable FALSE Auto enable selection.
Callback (Only valid with Software start) NULL Callback selection.
ELC Software Event Interrupt Priority Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX)

Default: Disabled 		ELC Software Event interrupt priority selection.
Note
The example settings and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

Configuration Settings for the Transfer Driver on r_dtc Event SCI0 RXI

ISDE Property Value Description
Parameter Checking BSP, Enabled, Disabled

Default: BSP 		Selects if code for parameter checking is to be included in the build.
Name g_transfer1 Module name.
Mode Normal Mode selection.
Transfer Size 1 Byte Transfer size selection.
Destination Address Mode Incremented Destination address mode selection.
Source Address Mode Fixed Source address mode selection.
Repeat Area (Unused in Normal Mode Destination Repeat area selection.
Interrupt Frequency After all transfers have completed Interrupt frequency selection.
Destination Pointer NULL Destination pointer selection.
Source Pointer NULL Source pointer selection.
Number of Transfers 0 Number of transfers selection.
Number of Blocks (Valid only in Block Mode) 0 Number of blocks selection.
Activation Source (Must enable IRQ) Event SPI0 RXI Activation source selection.
Auto Enable FALSE Auto enable selection.
Callback (Only valid with Software start) NULL Callback selection.
ELC Software Event Interrupt Priority Priority 0 (highest), Priority 1:14, Priority 15 (lowest - not valid if using ThreadX)

Default: Disabled 		ELC Software Event interrupt priority selection.
Note
The example settings and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

UART Communications Framework Module Clock Configuration

The UART Communications Framework has no specific clock configuration requirements.

UART Communications Framework Module Pin Configuration

The UART Communications Framework uses pins on the MCU to communicate to external devices based on the lower level implementation selected. I/O pins must be selected and configured as required by the external device.  The following table illustrates the method for selecting the pins within the SSP configuration window and the subsequent table illustrates an example selection for the lower level implementation pins.

Note
For some peripherals, the operation mode selection determines what peripheral signals are available and what MCU pins are required.

Pin Selection for the UART Communications Framework Module on sf_uart_comms

Resource ISDE Tab Pin selection Sequence
UART Pins Select Peripherals> Connectivity: SCI> SCI8
Note
The selection sequence assumes SCI0 is the desired hardware target for the driver.

Pin Configuration Settings for the UART Communications Framework Module on sf_uart_comms

Property Value Description
Pin Group Selection Mixed, _A Only, _B Only Pin group selection.
Operation Mode Disabled, Custom, Asynchronous UART, Synchronous UART, Simple I2C, Simple SPI, SmartCard

Default: Disabled 		Select Asynchronous UART as the Operation Mode for a UART Receiver implementation.
TXD_MOSI None, PB05, P105

Default: None 		TXD pin P105.
RXD_MISO None, PB05, P104

Default: None 		RXD pin P104.
Note
The example settings are for a project using the Synergy S7G2 MCU Group and the SK-S7G2 Kit. Other Synergy MCUs and Synergy Kits may have different available pin configuration settings.

Pin Selection Sequence for Communications Framework on UART, USB or Telnet (Transmitter)

Resource ISDE Tab Pin selection Sequence
UART Pins Select Peripherals > Connectivity: SCI> SCI3
Note
These selection sequences are examples for selected implementations. Others are also possible depending on the target hardware.

Pin Configuration Settings for UART

Pin Configuration Property Settings Description
Pin Group Selection Mixed, _A Only, _B Only Pin group selection.
Operation Mode Disabled, Custom, Asynchronous UART, Synchronous UART, Simple I2C, Simple SPI, SmartCard

Default: Disabled 		Select Asynchronous UART as the Operation Mode for a UART Transmitter implementation.
TXD_MOSI None, P707, P409

Default: None 		TXD pin P707.
RXD_MISO None, P706, P408

Default: None 		RXD pin P706.
Note
These selection sequences are examples for selected implementations. Others are also possible depending on the target hardware.

Using the UART Communications Framework Module in an Application

The steps in using the UART Communications Framework module on sf_audio_record_adc in a typical application are:

  1. Initialize the UART Communications Framework using the sf_comms_api_t::open API.
  2. Lock the channel for continuous communications using the sf_comms_api_t::lock API if needed.
  3. Receive data using the sf_comms_api_t::read API.
  4. Send data using the sf_comms_api_t::write API.
  5. Unlock the channel from continuous communication using the sf_comms_api_t::unlock API if needed.
  6. Close the channel using the sf_comms_api_t::close API.

These common steps are illustrated in a typical operational flow diagram in the following figure:

uart_comms_TA.png
Flow Diagram of a Typical UART Communications Framework Module Application