Synergy Software Package User's Manual
UART Driver

Table of Contents

UART HAL Module Introduction

The UART HAL Module provides a high-level API for industry standard UART serial communications applications and uses the SCI peripherals on the Synergy MCU. A user-defined callback can be created to manage hardware-handshake and data operation, if needed.

UART HAL Module Features

The UART HAL module supports the standard UART protocol. The UART HAL module used in concert with the SCI peripheral in UART mode (UART on SCI) supports the following features (in addition to the standard UART protocol):

  • Full-duplex UART communication
  • Simultaneous communication with multiple channels
  • Interrupt-driven data transmission and reception
  • Invoking the user-callback function with an event code in the argument
  • Baud-rate change at run-time
  • Hardware resource locking during UART transaction
  • CTS/RTS hardware flow control (with an associated IOPORT pin and supported by user-defined callback function)
  • Integration with the DTC transfer module
  • Abort in-progress read/write operations
r_sci_uart_BD.png
UART HAL Module Block Diagram

UART Hardware Support Details

The following hardware features are, or are not, supported by SSP for the UART (SCI).

Legend:

Symbol Meaning
✓ Available (Tested)
⌧ Not Available (Not tested/not functional or both)
N/A Not supported by MCU 
MCU Group Serial communication mode: Asynchronous Serial communication mode: Clock synchronous Serial communication mode: Smart card
S124 ✓ ✓ ⌧
S128 ✓ ✓ ⌧
S1JA ✓ ✓ ⌧
S3A1 ✓ ✓ ⌧
S3A3 ✓ ✓ ⌧
S3A6 ✓ ✓ ⌧
S3A7 ✓ ✓ ⌧
S5D3 ✓ ✓ ⌧
S5D5 ✓ ✓ ⌧
S5D9 ✓ ✓ ⌧
S7G2 ✓ ✓ ⌧
MCU Group Bit selectable transfer speed Data Length 7, 8, or 9 bits Support all Interrupt Sources Transmission stop bit 1 or 2 bits Parity:
Even parity,
odd parity, or
no parity 		Receive error detection
S124 ✓ ✓ ✓ ✓ ✓ ✓
S128 ✓ ✓ ✓ ✓ ✓ ✓
S1JA ✓ ✓ ✓ ✓ ✓ ✓
S3A1 ✓ ✓ ✓ ✓ ✓ ✓
S3A3 ✓ ✓ ✓ ✓ ✓ ✓
S3A6 ✓ ✓ ✓ ✓ ✓ ✓
S3A7 ✓ ✓ ✓ ✓ ✓ ✓
S5D3 ✓ ✓ ✓ ✓ ✓ ✓
S5D5 ✓ ✓ ✓ ✓ ✓ ✓
S5D9 ✓ ✓ ✓ ✓ ✓ ✓
S7G2 ✓ ✓ ✓ ✓ ✓ ✓
MCU Group Hardware flow control Transmission and reception Address match Address
un-match 		Start-bit detection Break detection
S124 ✓ Register ⌧ ⌧ ✓ ⌧
S128 ✓ Register ⌧ ⌧ ✓ ⌧
S1JA ✓ Register ⌧ ⌧ ✓ ⌧
S3A1 ✓ FIFO ⌧ ⌧ ✓ ⌧
S3A3 ✓ FIFO ⌧ ⌧ ✓ ⌧
S3A6 ✓ FIFO ⌧ ⌧ ✓ ⌧
S3A7 ✓ FIFO ⌧ ⌧ ✓ ⌧
S5D3 ✓ FIFO ⌧ ⌧ ✓ ⌧
S5D5 ✓ FIFO ⌧ ⌧ ✓ ⌧
S5D9 ✓ FIFO ⌧ ⌧ ✓ ⌧
S7G2 ✓ FIFO ⌧ ⌧ ✓ ⌧
MCU Group Clock source Internal/ external Double speed mode Multi-processor communications Noise cancellation Bit rate modulation function iRDA support
S124 ✓ ⌧ ⌧ ✓ ✓ ⌧
S128 ✓ ⌧ ⌧ ✓ ✓ ⌧
S1JA ✓ ⌧ ⌧ ✓ ✓ ⌧
S3A1 ✓ ⌧ ⌧ ✓ ✓ ⌧
S3A3 ✓ ⌧ ⌧ ✓ ✓ ⌧
S3A6 ✓ ⌧ ⌧ ✓ ✓ ⌧
S3A7 ✓ ⌧ ⌧ ✓ ✓ ⌧
S5D3 ✓ ⌧ ⌧ ✓ ✓ ⌧
S5D5 ✓ ⌧ ⌧ ✓ ✓ ⌧
S5D9 ✓ ⌧ ⌧ ✓ ✓ ⌧
S7G2 ✓ ⌧ ⌧ ✓ ✓ ⌧

UART HAL Module APIs Overview

The UART HAL module interface defines APIs for key features such as opening, closing, reading, writing and setting the baud rate. 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 HAL Module API Summary

Function Name Example API Call and Description
open g_uart0.p_api->open(g_uart0.p_ctrl, g_uart0.p_cfg);
Open UART device.
read g_uart0.p_api->read(g_uart0.p_ctrl, uart0_buf, uart0_rcv_num);
Read from UART device. The received bytes are stored directly in the read input buffer, uart0_buf. When a transfer is complete/expected bytes are received, the callback is called with event UART_EVENT_RX_COMPLETE.
When the uart_api_t::read API is not called then the bytes will be received in the callback function with event UART_EVENT_RX_CHAR for each byte.
write g_uart0.p_api->write(g_uart0.p_ctrl, uart0_buf, uart0_send_num)
Write to UART device. The write buffer is used until write is complete. Do not overwrite write buffer contents until the write is finished. When the write is complete (all bytes are fully transmitted on the wire), the callback called with event UART_EVENT_TX_COMPLETE.
baudSet g_uart0.p_api->baudSet(g_uart0.p_ctrl, (uint32_t)9600);
Change baud rate.
infoGet g_uart0.p_api->infoGet(g_uart0.p_ctrl, &uart_info);
Get the driver specific information.
close g_uart0.p_api->close(g_uart0.p_ctrl);
Close UART device.
versionGet g_uart0.p_api->versionGet(version);
Retrieve the API version with the version pointer.
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 operates successfully.
SSP_ERR_IN_USE Control block has already been opened or channel is being used by another instance.
SSP_ERR_ASSERTION Pointer to UART control block is NULL 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. Or source/destination address or data size is invalid against data length.
SSP_ERR_NOT_OPEN The control block has not been opened.
SSP_ERR_UNSUPPORTED SCI_UART_CFG_RX_ENABLE is set to 0.
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 HAL Module Operational Overview

The UART HAL Module manages data flow using the standard UART protocol. The high-level APIs are used to read, write and set the baud rate for the UART interface. In addition, interrupts are typically used to simplify the management of low-level activities.

Note
Interrupts need to be enabled for the following functions to operate successfully.

UART on SCI RXI Interrupt

The RXI interrupt is used to control the flow of data received from the UART port. When the amount of received data reaches the expected read length, the ISR invokes a user-defined callback (sci_uart_instance_ctrl_t::p_callback) with the argument uart_callback_args_t to indicate that the received data is complete. When the External RTS Operation option is enabled, the ISR invokes the UART callback function for the RTS external pin control twice: once at the top of ISR and once at the bottom. You can use the callback function to emulate the RTS function (see the UART on SCI hardware flow-control section); this interrupt is activated as long as reception is enabled in the SCI_UART_CFG_RX_ENABLE configuration parameter.

UART on SCI TXI Interrupt

The TXI interrupt handles consecutive transmissions of data to the UART port as requested by the uart_api_t::write API. When no data is left in the transmit circular buffer, the ISR deactivates the TXI interrupt and activates the TEI interrupt to handle the last sequence in the data transmission. This interrupt is activated in the uart_api_t::write API as long as the transmission is enabled by the SCI_UART_CFG_TX_ENABLE configuration parameter.

UART on SCI TEI Interrupt

The TEI interrupt is used to handle a last data transmission to the UART port requested by uart_api_t::write API; this interrupt is activated by TXI ISR and deactivates itself. The ISR invokes a user-defined callback (sci_uart_instance_ctrl_t::p_callback) with the argument uart_callback_args_t to indicate that the end of data istransmit.

UART on SCI ERI Interrupt

The ERI interrupt is used to handle errors that occur in the UART reception. This interrupt is activated in the uart_api_t::open API as long as the reception is enabled by the SCI_UART_CFG_RX_ENABLE configuration parameter. The ISR invokes a user-defined callback (sci_uart_instance_ctrl_t::p_callback) with the argument uart_callback_args_t to indicate uart_event_t cause of an error.

UART HAL Module Important Operational Notes and Limitations

UART HAL Module Operational Notes

UART on SCI Hardware Flow Control

The SCI hardware module supports hardware flow-control for only one of the RTS or CTS signals at a time. CTS and RTS are multiplexed on the CTSn/RTSn pin so that one of the hardware flow-control signals can be used exclusively depending on the use-case. The UART HAL module expands this specification and allows control of both the CTS and the RTS signal by enabling an additional pin for the RTS signal. To enable this mode, set the UART on SCI configurations as follows:

The UART on SCI HAL module invokes the user-callback function from the RXI ISR at the top and at the end of processing.

The callback function argument "level" refers to the signal level on the RTS pin for the selected SCI channel.

Note
The HAL module does not handle the GPIO pin-initialization or control it; instead, the user needs to initialize the GPIO pin before starting the UART reception.

The following figure shows the timing diagram of CTS/RTS hardware flow-control with an external GPIO pin used as the RTS signal:

r_sci_uart_HC.png
UART HAL Module CTS/RTS Hardware Control with an External GPIO
Note
The UART on SCI module on the SK-S7G2 board uses PORT8 pin0 (pin P800) and J8 to activate the RS232C port on the RS-232C transceiver. Connect pin 1 and pin 2 of J8. Configure pins P800 as IOPORT pins and set its level for the desired operation.

Notes on RS485 Implementations

  • For RS485 communication mode, ON pin and RXEN pin should be controlled from the application
  • In the case of RS485 Full Duplex communication, configuration of ON pin is not required and in the case of RS485 half-duplex communication, ON should be configured as level Low
  • RXEN pin is usually DIP switch (HALF or HD/FD) in Synergy MCUs and is made LOW (ON) for RS485 half-duplex and made HIGH (OFF) for RS485 Full Duplex communication

UART HAL Module Limitations

  • The module supports interrupt-based operation but does not support a polled UART mode.
  • The module does not support non-buffered UART mode.
  • The module does not support Event Link functionality.
  • Transfer size must be less than or equal to 64K bytes if DTC interface is used for transfer. uart_api_t::infoGet API can be used to get the max transfer size allowed.
  • Reception is still enabled after uart_api_t::communicationAbort API is called. Any characters received after abort and before the next call to read, will arrive via the callback function with event UART_EVENT_RX_CHAR.
  • Refer to the most recent SSP Release Notes for any additional operational limitations for this module.

Including the UART HAL Module in an Application

This section describes how to include the UART HAL 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 Driver 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 Driver is g_uart0. This name can be changed in the associated Properties window.)

UART HAL Module Selection Sequence

Resource ISDE Tab Stacks Selection Sequence
g_uart0 UART on r_sci_uart Threads Threads> Driver> Connectivity> UART Driver on r_sci_uart

When the UART HAL module on r_sci_uartis 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.

r_sci_uart_MS.png
UART HAL Module Stack

Configuring the UART HAL Module

The UART HAL 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.

ConfigurationSettings 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 user_uart_callback 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

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

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

Default: 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

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

Default: Max 		Receive FIFO trigger level selection:
One: an interrupt occurs for every byte received.
Max: an interrupt will be triggered if either of the below conditions are met:
a) The FIFO is filled to the Max level (15).
b) 15bit times have occurred with no data received.
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 selection.
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.
Baud rate Percent Error Value must be greater than 0.0 and less than 15.0
Default; 2.0 		Maximum baudrate percent error allowed in order for the module to function.
UART Communication Mode RS232, RS485
Default: RS232 		UART communication mode selection, usually it is RS232 mode.
UART RS485 Communication Mode Half Duplex, Full Duplex
Default: Half duplex 		UART RS485 communication mode selection as half duplex or full duplex.
RS485 DE Port 00 to 11
Default: 09 		Select the port number of Driver Enable Pin.
RS485 DE Pin 00 to 15
Default: 14 		Select the pin number of Driver Enable Pin.
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 HAL 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 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

Default: Disabled 		Software start selection.
Linker section to keep DTC vector table .ssp_dtc_vector_table Linker section to keep DTC vector table selection.
Name g_transfer0 Module name.
Mode Normal Mode selection.
Transfer Size 1 Bytes 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 True, False

Default: True 		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.
Software Start Enabled, Disabled

Default: Disabled 		Software start selection.
Linker section to keep DTC vector table .ssp_dtc_vector_table Linker section to keep DTC vector table selection.
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.

When using the UART with CTS and RTS function simultaneously, the transfer driver cannot be used; please delete all transfer drivers on the low level. After being deleted, the optional transfer driver will display in pink, meaning the driver is recommended but optional.

UART HAL Module Clock Configuration

The SCI UART peripheral uses PCLKA as its clock source (PCLKB for S124) or an external clock from the SCKn pin for the selected channel n.

UART HAL Module Pin Configuration

The SCI UART peripheral uses pins on the MCU to communicate to external devices. 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 UART pins.

Note
The operation mode selection determines what peripheral signals are available and what MCU pins are required.

Pin Selection Sequence for UART HAL Module on SCI

Resource ISDE Tab Pin selection Sequence
SCI Pins Select Peripherals> Connectivity: SCI > SCI0

Pin Configuration Settings for the UART HAL Module on r_sci_uart

Pin Configuration Property Value Description
Pin Group Selection Mixed, _A Only, _B Only
(Default: Mixed) 		Pin grouping selection.
Operation Mode Disabled, Custom, Asynchronous UART, Simple SPI, Simple I2C, Synchronous UART, SmartCard
(Default: Simple SPI) 		Select Operation Mode for UART on SCI.
TXD_MOSI None, P411, P101
(Default: P411) 		TXD Pin.
RXD_MISO None, P410, P100
(Default: P410) 		RXD Pin.
SCK None, P412, P102
(Default: P412) 		SCK Pin.
CTS_RTS_SS None, P413, P103
(Default: None) 		CTS Pin.
SDA Disabled SDA Pin (when Simple I2C is used).
SCL Disabled SCL Pin (when Simple I2C is used).
Note
The example settings are for a project using the Synergy S7G2 MCU Group and the SK-S7G2 Kit. Other Synergy Kits and other Synergy MCUs may have different available pin configuration settings.

Using the UART HAL Module in an Application

The steps in using the UART HAL module in a typical application are:

  1. Initialize the UART HAL Module using the uart_api_t::open API.
  2. Set Baud Rate with the uart_api_t::baudSet API (if needed.)
  3. Read and Write data as needed using the uart_api_t::read and uart_api_t::write APIs and callbacks.
  4. Read or Write operations can be aborted using uart_api_t::communicationAbort API if required.
  5. Close the UART HAL module using the uart_api_t::close API as needed.

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

r_sci_uart_TA.png
Flow Diagram of a Typical UART HAL Module Application