RA Flexible Software Package Documentation  Release v4.2.0

 
UART (r_sci_uart)

Functions

fsp_err_t R_SCI_UART_Open (uart_ctrl_t *const p_api_ctrl, uart_cfg_t const *const p_cfg)
 
fsp_err_t R_SCI_UART_Close (uart_ctrl_t *const p_api_ctrl)
 
fsp_err_t R_SCI_UART_Read (uart_ctrl_t *const p_api_ctrl, uint8_t *const p_dest, uint32_t const bytes)
 
fsp_err_t R_SCI_UART_Write (uart_ctrl_t *const p_api_ctrl, uint8_t const *const p_src, uint32_t const bytes)
 
fsp_err_t R_SCI_UART_CallbackSet (uart_ctrl_t *const p_api_ctrl, void(*p_callback)(uart_callback_args_t *), void const *const p_context, uart_callback_args_t *const p_callback_memory)
 
fsp_err_t R_SCI_UART_BaudSet (uart_ctrl_t *const p_api_ctrl, void const *const p_baud_setting)
 
fsp_err_t R_SCI_UART_InfoGet (uart_ctrl_t *const p_api_ctrl, uart_info_t *const p_info)
 
fsp_err_t R_SCI_UART_Abort (uart_ctrl_t *const p_api_ctrl, uart_dir_t communication_to_abort)
 
fsp_err_t R_SCI_UART_ReadStop (uart_ctrl_t *const p_api_ctrl, uint32_t *remaining_bytes)
 
fsp_err_t R_SCI_UART_BaudCalculate (uint32_t baudrate, bool bitrate_modulation, uint32_t baud_rate_error_x_1000, baud_setting_t *const p_baud_setting)
 

Detailed Description

Driver for the SCI peripheral on RA MCUs. This module implements the UART Interface.

Overview

Features

The SCI UART module supports the following features:

Configuration

Build Time Configurations for r_sci_uart

The following build time configurations are defined in fsp_cfg/r_sci_uart_cfg.h:

ConfigurationOptionsDefaultDescription
Parameter Checking
  • Default (BSP)
  • Enabled
  • Disabled
Default (BSP) If selected code for parameter checking is included in the build.
FIFO Support
  • Enable
  • Disable
Disable Enable FIFO support for the SCI_UART module.
DTC Support
  • Enable
  • Disable
Disable Enable DTC support for the SCI_UART module.
Flow Control Support
  • Enable
  • Disable
Disable Enable RS232 and RS-485 flow control support using a user provided pin.
RS-485 Support
  • Enable
  • Disable
Disable Enable support for controlling the RS-485 DE pin.

Configurations for Connectivity > UART (r_sci_uart)

This module can be added to the Stacks tab via New Stack > Connectivity > UART (r_sci_uart). Non-secure callable guard functions can be generated for this module by right clicking the module in the RA Configuration tool and checking the "Non-secure Callable" box.

ConfigurationOptionsDefaultDescription
General > NameName must be a valid C symbolg_uart0 Module name.
General > ChannelValue must be a non-negative integer0 Select the SCI channel.
General > Data Bits
  • 8bits
  • 7bits
  • 9bits
8bits Select the number of bits per word.
General > Parity
  • None
  • Odd
  • Even
None Select the parity mode.
General > Stop Bits
  • 1bit
  • 2bits
1bit Select the number of stop bits.
Baud > Baud RateValue must be an integer greater than 0115200 Enter the desired baud rate.

If the requested baud rate cannot be achieved, the settings with the smallest percent error are used. The theoretical calculated baud rate and percent error are printed in a comment in the generated baud_setting_t structure.
Baud > Baud Rate Modulation
  • Disabled
  • Enabled
Disabled Enabling baud rate modulation reduces the percent error of the actual baud rate with respect to the requested baud rate. It does this by modulating the number of cycles per clock, so some bits are slightly longer than others.
Baud > Max Error (%)Must be a valid non-negative integer with a maximum configurable value of 1005 Maximum percent error allowed during baud calculation. This is used by the algorithm to determine whether or not to consider using less accurate alternative register settings.

NOTE: The baud calculation does not show an error in the tool if this percent error was not achieved. The calculated percent error is recorded in a comment in the generated baud_setting_t structure.
Flow Control > CTS/RTS SelectionMCU Specific OptionsSelect either CTS or RTS function on the CTSn_RTSn pin of SCI channel n or select CTS function on CTSn pin and RTS function on CTSn_RTSn pin of SCI channel n (Available on selected MCUs and channels).
Flow Control > Software RTS PortRefer to the RA Configuration tool for available options.Disabled Specify the flow control pin port for the MCU.
Flow Control > Software RTS PinRefer to the RA Configuration tool for available options.Disabled Specify the flow control pin for the MCU.
Extra > RS-485 > DE Pin
  • Disable
  • Enable
Disable Enable or disable the DE pin for use in RS-485 half-duplex mode.
Extra > RS-485 > DE Pin Polarity
  • Active Low
  • Active High
Active High Select the polarity of the DE pin.
Extra > RS-485 > DE Port NumberRefer to the RA Configuration tool for available options.Disabled GPIO output port number to use for generating the DE signal.
Extra > RS-485 > DE Pin NumberRefer to the RA Configuration tool for available options.Disabled GPIO output pin number to use for generating the DE signal.
Extra > Clock Source
  • Internal Clock
  • Internal Clock With Output on SCK
  • External Clock 8x baud rate
  • External Clock 16x baud rate
Internal Clock Selection of the clock source to be used in the baud-rate clock generator. When internal clock is used the baud rate can be output on the SCK pin.
Extra > Start bit detection
  • Falling Edge
  • Low Level
Falling Edge Start bit detected as falling edge or low level.
Extra > Noise Filter
  • Enable
  • Disable
Disable Enable the digital noise filter on RXDn pin. The digital noise filter block in SCI consists of two-stage flipflop circuits.
Extra > Receive FIFO Trigger Level
  • One
  • Max
Max Unused if the channel has no FIFO or if DTC is used for reception. Set to One to get a callback immediately when each byte is received. Set to Max to get a callback when FIFO is full or after 15 bit times with no data (fewer interrupts).
Interrupts > CallbackName must be a valid C symbolNULL A user callback function can be provided. If this callback function is provided, it will be called from the interrupt service routine (ISR).
Interrupts > Receive Interrupt PriorityMCU Specific OptionsSelect the receive interrupt priority.
Interrupts > Transmit Data Empty Interrupt PriorityMCU Specific OptionsSelect the transmit interrupt priority.
Interrupts > Transmit End Interrupt PriorityMCU Specific OptionsSelect the transmit end interrupt priority.
Interrupts > Error Interrupt PriorityMCU Specific OptionsSelect the error interrupt priority.

Clock Configuration

The clock for this module is derived from the following peripheral clock for each MCU group:

MCU GroupPeripheral Clock
RA2A1PCLKB
RA2E1PCLKB
RA2E2PCLKB
RA2L1PCLKB
RA4E1PCLKA
RA4M1PCLKA
RA4M2PCLKA
RA4M3PCLKA
RA4W1PCLKA
RA6E1PCLKA
RA6M1PCLKA
RA6M2PCLKA
RA6M3PCLKA
RA6M4PCLKA
RA6M5PCLKA
RA6T1PCLKA

The clock source for the baud-rate clock generator can be selected from the internal clock, the external clock times 8 or the external clock times 16. The external clock is supplied to the SCK pin.

Pin Configuration

This module uses TXD and RXD to communicate to external devices. CTS or RTS or both (CTS and RTS) can be controlled by the hardware. Some MCUs support hardware flow control for both CTS and RTS on some channels. Some MCUs and channels support hardware flow control for either CTS or RTS but not both. If both are desired a GPIO pin can be used for RTS. When the internal clock is the source for the baud-rate generator the SCK pin can be used to output a clock with the same frequency as the bit rate.

Usage Notes

Limitations

DTC Limitations

Examples

SCI UART Example

uint8_t g_dest[TRANSFER_LENGTH];
uint8_t g_src[TRANSFER_LENGTH];
uint8_t g_out_of_band_received[TRANSFER_LENGTH];
uint32_t g_transfer_complete = 0;
uint32_t g_receive_complete = 0;
uint32_t g_out_of_band_index = 0;
void r_sci_uart_basic_example (void)
{
/* Initialize p_src to known data */
for (uint32_t i = 0; i < TRANSFER_LENGTH; i++)
{
g_src[i] = (uint8_t) ('A' + (i % 26));
}
/* Open the transfer instance with initial configuration. */
fsp_err_t err = R_SCI_UART_Open(&g_uart0_ctrl, &g_uart0_cfg);
assert(FSP_SUCCESS == err);
err = R_SCI_UART_Read(&g_uart0_ctrl, g_dest, TRANSFER_LENGTH);
assert(FSP_SUCCESS == err);
err = R_SCI_UART_Write(&g_uart0_ctrl, g_src, TRANSFER_LENGTH);
assert(FSP_SUCCESS == err);
while (!g_transfer_complete)
{
}
while (!g_receive_complete)
{
}
}
void example_callback (uart_callback_args_t * p_args)
{
/* Handle the UART event */
switch (p_args->event)
{
/* Received a character */
{
/* Only put the next character in the receive buffer if there is space for it */
if (sizeof(g_out_of_band_received) > g_out_of_band_index)
{
/* Write either the next one or two bytes depending on the receive data size */
if (UART_DATA_BITS_8 >= g_uart0_cfg.data_bits)
{
g_out_of_band_received[g_out_of_band_index++] = (uint8_t) p_args->data;
}
else
{
uint16_t * p_dest = (uint16_t *) &g_out_of_band_received[g_out_of_band_index];
*p_dest = (uint16_t) p_args->data;
g_out_of_band_index += 2;
}
}
break;
}
/* Receive complete */
{
g_receive_complete = 1;
break;
}
/* Transmit complete */
{
g_transfer_complete = 1;
break;
}
default:
{
}
}
}

SCI UART Baud Set Example

#define SCI_UART_BAUDRATE_19200 (19200)
#define SCI_UART_BAUDRATE_ERROR_PERCENT_5 (5000)
void r_sci_uart_baud_example (void)
{
baud_setting_t baud_setting;
uint32_t baud_rate = SCI_UART_BAUDRATE_19200;
bool enable_bitrate_modulation = false;
uint32_t error_rate_x_1000 = SCI_UART_BAUDRATE_ERROR_PERCENT_5;
fsp_err_t err = R_SCI_UART_BaudCalculate(baud_rate, enable_bitrate_modulation, error_rate_x_1000, &baud_setting);
assert(FSP_SUCCESS == err);
err = R_SCI_UART_BaudSet(&g_uart0_ctrl, (void *) &baud_setting);
assert(FSP_SUCCESS == err);
}

Data Structures

struct  sci_uart_instance_ctrl_t
 
struct  baud_setting_t
 
struct  sci_uart_rs485_setting_t
 
struct  sci_uart_extended_cfg_t
 

Enumerations

enum  sci_clk_src_t
 
enum  sci_uart_flow_control_t
 
enum  sci_uart_rx_fifo_trigger_t
 
enum  sci_uart_start_bit_t
 
enum  sci_uart_noise_cancellation_t
 
enum  sci_uart_rs485_enable_t
 
enum  sci_uart_rs485_de_polarity_t
 

Data Structure Documentation

◆ sci_uart_instance_ctrl_t

struct sci_uart_instance_ctrl_t

UART instance control block.

◆ baud_setting_t

struct baud_setting_t

Register settings to acheive a desired baud rate and modulation duty.

Data Fields
union baud_setting_t __unnamed__
uint8_t cks: 2 CKS value to get divisor (CKS = N)
uint8_t brr Bit Rate Register setting.
uint8_t mddr Modulation Duty Register setting.

◆ sci_uart_rs485_setting_t

struct sci_uart_rs485_setting_t

Configuration settings for controlling the DE signal for RS-485.

Data Fields
sci_uart_rs485_enable_t enable Enable the DE signal.
sci_uart_rs485_de_polarity_t polarity DE signal polarity.
bsp_io_port_pin_t de_control_pin UART Driver Enable pin.

◆ sci_uart_extended_cfg_t

struct sci_uart_extended_cfg_t

UART on SCI device Configuration

Data Fields
sci_clk_src_t clock The source clock for the baud-rate generator. If internal optionally output baud rate on SCK.
sci_uart_start_bit_t rx_edge_start Start reception on falling edge.
sci_uart_noise_cancellation_t noise_cancel Noise cancellation setting.
baud_setting_t * p_baud_setting Register settings for a desired baud rate.
sci_uart_rx_fifo_trigger_t rx_fifo_trigger Receive FIFO trigger level, unused if channel has no FIFO or if DTC is used.
bsp_io_port_pin_t flow_control_pin UART Driver Enable pin.
sci_uart_flow_control_t flow_control CTS/RTS function of the SSn pin.
sci_uart_rs485_setting_t rs485_setting RS-485 settings.

Enumeration Type Documentation

◆ sci_clk_src_t

Enumeration for SCI clock source

Enumerator
SCI_UART_CLOCK_INT 

Use internal clock for baud generation.

SCI_UART_CLOCK_INT_WITH_BAUDRATE_OUTPUT 

Use internal clock for baud generation and output on SCK.

SCI_UART_CLOCK_EXT8X 

Use external clock 8x baud rate.

SCI_UART_CLOCK_EXT16X 

Use external clock 16x baud rate.

◆ sci_uart_flow_control_t

UART flow control mode definition

Enumerator
SCI_UART_FLOW_CONTROL_RTS 

Use SCI pin for RTS.

SCI_UART_FLOW_CONTROL_CTS 

Use SCI pin for CTS.

SCI_UART_FLOW_CONTROL_CTSRTS 

Use SCI pin for CTS, external pin for RTS.

SCI_UART_FLOW_CONTROL_HARDWARE_CTSRTS 

Use CTSn_RTSn pin for RTS and CTSn pin for CTS. Available only for some channels on selected MCUs. See hardware manual for channel specific options.

◆ sci_uart_rx_fifo_trigger_t

Receive FIFO trigger configuration.

Enumerator
SCI_UART_RX_FIFO_TRIGGER_1 

Callback after each byte is received without buffering.

SCI_UART_RX_FIFO_TRIGGER_MAX 

Callback when FIFO is full or after 15 bit times with no data (fewer interrupts)

◆ sci_uart_start_bit_t

Asynchronous Start Bit Edge Detection configuration.

Enumerator
SCI_UART_START_BIT_LOW_LEVEL 

Detect low level on RXDn pin as start bit.

SCI_UART_START_BIT_FALLING_EDGE 

Detect falling level on RXDn pin as start bit.

◆ sci_uart_noise_cancellation_t

Noise cancellation configuration.

Enumerator
SCI_UART_NOISE_CANCELLATION_DISABLE 

Disable noise cancellation.

SCI_UART_NOISE_CANCELLATION_ENABLE 

Enable noise cancellation.

◆ sci_uart_rs485_enable_t

RS-485 Enable/Disable.

Enumerator
SCI_UART_RS485_DISABLE 

RS-485 disabled.

SCI_UART_RS485_ENABLE 

RS-485 enabled.

◆ sci_uart_rs485_de_polarity_t

The polarity of the RS-485 DE signal.

Enumerator
SCI_UART_RS485_DE_POLARITY_HIGH 

The DE signal is high when a write transfer is in progress.

SCI_UART_RS485_DE_POLARITY_LOW 

The DE signal is low when a write transfer is in progress.

Function Documentation

◆ R_SCI_UART_Open()

fsp_err_t R_SCI_UART_Open ( uart_ctrl_t *const  p_api_ctrl,
uart_cfg_t const *const  p_cfg 
)

Configures the UART driver based on the input configurations. If reception is enabled at compile time, reception is enabled at the end of this function. Implements uart_api_t::open

Return values
FSP_SUCCESSChannel opened successfully.
FSP_ERR_ASSERTIONPointer to UART control block or configuration structure is NULL.
FSP_ERR_IP_CHANNEL_NOT_PRESENTThe requested channel does not exist on this MCU.
FSP_ERR_INVALID_ARGUMENTFlow control is enabled but flow control pin is not defined or selected channel does not support "Hardware CTS and Hardware RTS" flow control.
FSP_ERR_ALREADY_OPENControl block has already been opened or channel is being used by another instance. Call close() then open() to reconfigure.
Returns
See Common Error Codes or functions called by this function for other possible return codes. This function calls:

◆ R_SCI_UART_Close()

fsp_err_t R_SCI_UART_Close ( uart_ctrl_t *const  p_api_ctrl)

Aborts any in progress transfers. Disables interrupts, receiver, and transmitter. Closes lower level transfer drivers if used. Removes power. Implements uart_api_t::close

Return values
FSP_SUCCESSChannel successfully closed.
FSP_ERR_ASSERTIONPointer to UART control block is NULL.
FSP_ERR_NOT_OPENThe control block has not been opened

◆ R_SCI_UART_Read()

fsp_err_t R_SCI_UART_Read ( uart_ctrl_t *const  p_api_ctrl,
uint8_t *const  p_dest,
uint32_t const  bytes 
)

Receives user specified number of bytes into destination buffer pointer. Implements uart_api_t::read

Return values
FSP_SUCCESSData reception successfully ends.
FSP_ERR_ASSERTIONPointer to UART control block is NULL. Number of transfers outside the max or min boundary when transfer instance used
FSP_ERR_INVALID_ARGUMENTDestination address or data size is not valid for 9-bit mode.
FSP_ERR_NOT_OPENThe control block has not been opened
FSP_ERR_IN_USEA previous read operation is still in progress.
FSP_ERR_UNSUPPORTEDSCI_UART_CFG_RX_ENABLE is set to 0
Returns
See Common Error Codes or functions called by this function for other possible return codes. This function calls:
Note
If 9-bit data length is specified at R_SCI_UART_Open call, p_dest must be aligned 16-bit boundary.

◆ R_SCI_UART_Write()

fsp_err_t R_SCI_UART_Write ( uart_ctrl_t *const  p_api_ctrl,
uint8_t const *const  p_src,
uint32_t const  bytes 
)

Transmits user specified number of bytes from the source buffer pointer. Implements uart_api_t::write

Return values
FSP_SUCCESSData transmission finished successfully.
FSP_ERR_ASSERTIONPointer to UART control block is NULL. Number of transfers outside the max or min boundary when transfer instance used
FSP_ERR_INVALID_ARGUMENTSource address or data size is not valid for 9-bit mode.
FSP_ERR_NOT_OPENThe control block has not been opened
FSP_ERR_IN_USEA UART transmission is in progress
FSP_ERR_UNSUPPORTEDSCI_UART_CFG_TX_ENABLE is set to 0
Returns
See Common Error Codes or functions called by this function for other possible return codes. This function calls:
Note
If 9-bit data length is specified at R_SCI_UART_Open call, p_src must be aligned on a 16-bit boundary.

◆ R_SCI_UART_CallbackSet()

fsp_err_t R_SCI_UART_CallbackSet ( uart_ctrl_t *const  p_api_ctrl,
void(*)(uart_callback_args_t *)  p_callback,
void const *const  p_context,
uart_callback_args_t *const  p_callback_memory 
)

Updates the user callback and has option of providing memory for callback structure. Implements uart_api_t::callbackSet

Return values
FSP_SUCCESSCallback updated successfully.
FSP_ERR_ASSERTIONA required pointer is NULL.
FSP_ERR_NOT_OPENThe control block has not been opened.
FSP_ERR_NO_CALLBACK_MEMORYp_callback is non-secure and p_callback_memory is either secure or NULL.

◆ R_SCI_UART_BaudSet()

fsp_err_t R_SCI_UART_BaudSet ( uart_ctrl_t *const  p_api_ctrl,
void const *const  p_baud_setting 
)

Updates the baud rate using the clock selected in Open. p_baud_setting is a pointer to a baud_setting_t structure. Implements uart_api_t::baudSet

Warning
This terminates any in-progress transmission.
Return values
FSP_SUCCESSBaud rate was successfully changed.
FSP_ERR_ASSERTIONPointer to UART control block is NULL or the UART is not configured to use the internal clock.
FSP_ERR_NOT_OPENThe control block has not been opened

◆ R_SCI_UART_InfoGet()

fsp_err_t R_SCI_UART_InfoGet ( uart_ctrl_t *const  p_api_ctrl,
uart_info_t *const  p_info 
)

Provides the driver information, including the maximum number of bytes that can be received or transmitted at a time. Implements uart_api_t::infoGet

Return values
FSP_SUCCESSInformation stored in provided p_info.
FSP_ERR_ASSERTIONPointer to UART control block is NULL.
FSP_ERR_NOT_OPENThe control block has not been opened

◆ R_SCI_UART_Abort()

fsp_err_t R_SCI_UART_Abort ( uart_ctrl_t *const  p_api_ctrl,
uart_dir_t  communication_to_abort 
)

Provides API to abort ongoing transfer. Transmission is aborted after the current character is transmitted. Reception is still enabled after abort(). Any characters received after abort() and before the transfer is reset in the next call to read(), will arrive via the callback function with event UART_EVENT_RX_CHAR. Implements uart_api_t::communicationAbort

Return values
FSP_SUCCESSUART transaction aborted successfully.
FSP_ERR_ASSERTIONPointer to UART control block is NULL.
FSP_ERR_NOT_OPENThe control block has not been opened.
FSP_ERR_UNSUPPORTEDThe requested Abort direction is unsupported.
Returns
See Common Error Codes or functions called by this function for other possible return codes. This function calls:

◆ R_SCI_UART_ReadStop()

fsp_err_t R_SCI_UART_ReadStop ( uart_ctrl_t *const  p_api_ctrl,
uint32_t *  remaining_bytes 
)

Provides API to abort ongoing read. Reception is still enabled after abort(). Any characters received after abort() and before the transfer is reset in the next call to read(), will arrive via the callback function with event UART_EVENT_RX_CHAR. Implements uart_api_t::readStop

Return values
FSP_SUCCESSUART transaction aborted successfully.
FSP_ERR_ASSERTIONPointer to UART control block is NULL.
FSP_ERR_NOT_OPENThe control block has not been opened.
FSP_ERR_UNSUPPORTEDThe requested Abort direction is unsupported.
Returns
See Common Error Codes or functions called by this function for other possible return codes. This function calls:

◆ R_SCI_UART_BaudCalculate()

fsp_err_t R_SCI_UART_BaudCalculate ( uint32_t  baudrate,
bool  bitrate_modulation,
uint32_t  baud_rate_error_x_1000,
baud_setting_t *const  p_baud_setting 
)

Calculates baud rate register settings. Evaluates and determines the best possible settings set to the baud rate related registers.

Parameters
[in]baudrateBaud rate [bps]. For example, 19200, 57600, 115200, etc.
[in]bitrate_modulationEnable bitrate modulation
[in]baud_rate_error_x_1000Max baud rate error. At most <baud_rate_percent_error> x 1000 required for module to function. Absolute max baud_rate_error is 15000 (15%).
[out]p_baud_settingBaud setting information stored here if successful
Return values
FSP_SUCCESSBaud rate is set successfully
FSP_ERR_ASSERTIONNull pointer
FSP_ERR_INVALID_ARGUMENTBaud rate is '0', error in calculated baud rate is larger than requested max error, or requested max error in baud rate is larger than 15%.