Functions
fsp_err_t	R_SAU_UART_Open (uart_ctrl_t const p_api_ctrl, uart_cfg_t const const p_cfg)

fsp_err_t	R_SAU_UART_Close (uart_ctrl_t *const p_api_ctrl)

fsp_err_t	R_SAU_UART_Read (uart_ctrl_t const p_api_ctrl, uint8_t const p_dest, uint32_t const bytes)

fsp_err_t	R_SAU_UART_Write (uart_ctrl_t const p_api_ctrl, uint8_t const const p_src, uint32_t const bytes)

fsp_err_t	R_SAU_UART_BaudSet (uart_ctrl_t const p_api_ctrl, void const const p_baud_setting)

fsp_err_t	R_SAU_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_SAU_UART_InfoGet (uart_ctrl_t const p_api_ctrl, uart_info_t const p_info)

fsp_err_t	R_SAU_UART_Abort (uart_ctrl_t *const p_api_ctrl, uart_dir_t communication_to_abort)

fsp_err_t	R_SAU_UART_ReadStop (uart_ctrl_t const p_api_ctrl, uint32_t remaining_bytes)

fsp_err_t	R_SAU_UART_BaudCalculate (sau_uart_instance_ctrl_t const p_ctrl, uint32_t baudrate, sau_uart_baudrate_setting_t const p_baud_setting)

Detailed Description

UART driver for the SAU peripheral on RA MCUs. This module implements the UART Interface.

Overview

Features

The SAU UART module supports the following features:

Full-duplex UART communication
Interrupt-driven data transmission and reception
Invoking the user-callback function with an event code (RX/TX complete, TX data empty, RX char, error, etc)
Baud-rate change at run-time
Integration with the DTC transfer module
Abort in-progress read/write operations

Configuration

Build Time Configurations for r_sau_uart

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

Configuration	Options	Default	Description
Parameter Checking	Default (BSP) Enabled Disabled	Default (BSP)	If selected code for parameter checking is included in the build.
Critical Section Guarding	Enabled Disabled	Disabled	Enable critical section guarding around peripheral configuration updates. This should be enabled if the R_SAU_I2C module is being used simultaneously with this module.
DTC Support	Enable Disable	Disable	Enable DTC support for the SAU_UART module.
Enable Single Channel	Disable Channel 0 Channel 1 Channel 2	Disable	Enable single channel to reduce code size if only channel 0, 1, or 2 is needed.
Enable Fixed Baudrate	Enable Disable	Enable	Disable baudrate calculation and setter functions to reduce code size.

Configurations for Connectivity > UART (r_sau_uart)

This module can be added to the Stacks tab via New Stack > Connectivity > UART (r_sau_uart).

Configuration	Options	Default	Description
General
Name	Name must be a valid C symbol	g_uart0	Module name.
Channel	Value must be a non-negative integer	0	Select the UART channel.
Data Bits	7 bits 8 bits 9 bits	8 bits	Select the number of bits per word.
Parity	None Zero Odd Even	None	Select the parity mode.
Stop Bits	1 bit 2 bits	1 bit	Select the number of stop bits. In receive, 2 bit is not available.
Bit Order	LSB First MSB First	LSB First	Select of data transfer sequence.
Baud
Baud Rate	Value must be an integer greater than 0	115200	Enter the desired baud rate. If the requested baud rate cannot be achieved, adjust the operation clock frequency until the baud rate is achievable. The calculated baud rate is printed in a comment in the generated sau_uart_baudrate_setting_t structure.
Extra
Operation Clock	CKm0 CKm1	CKm0	Select the operation clock. Use the Clocks tab to set the operation clock divider.
Tx Signal Level	Standard Inverted	Standard	Select the level of transmitted signal.
Interrupts
Callback	Name must be a valid C symbol	NULL	A user callback function can be provided. If this callback function is provided, it will be called from the interrupt service routine (ISR).
Transmit End Interrupt Priority	MCU Specific Options		Select the transmit end interrupt priority.
Receive End Interrupt Priority	MCU Specific Options		Select the receive end interrupt priority.
Error Interrupt Priority	MCU Specific Options		Select the error interrupt priority.

Clock Configuration

The SAU clock uses the system clock (ICLK) as its clock source.

A prescaler is applied to the ICLK in order to produce the operation clock frequency. The operation clock is used to generate the desired transfer period of the SAU module.

SAU operation clocks are shared among all channels within a SAU unit. Check the Hardware User's Manual for your MCU for available units and channels. SAU operation clock dividers are configurable in the Clocks tab.

The operation clock dividers are named SAU CKmn where m is the SAU unit, and n is the operation clock. For example, SAU CK01 applies to all SAU0 instances using CK1 as the operation clock (m=0, n=1).

Pin Configuration

This module uses TXD and RXD to communicate to external devices.

Usage Notes

9-bit data transfers

p_src: the address for the send data buffer. p_src in R_SAU_UART_Write must be aligned on a 16-bit boundary. (the data order in buffer: the lower 8-bits of the first number, the highest 1-bit of the first number, the lower 8-bits of the second number, the highest 1-bit of the second number, etc)
byte: the size of send data buffer.

Selecting Operation Clock Frequency

The relationship between operation clock frequency and bitrate is: bitrate = f_mck / [ 2 * (SDRmn.STCLK + 1) ] where:

SDRmn.STCLK is an integer in the range [2, 127] for SAU UART
f_mck is the operation clock (SAU CKmn) frequency

By plugging in the minimum and maximum SDRmn.STCLK values, the range of bitrates for a given operation clock frequency can be obtained.

Note that due to STCLK being set as discrete integers, the actual bitrate may not be exact. The actual bitrate and percent errors can be calculated by the formulas:

actual_bitrate = f_mck / [ 2 * (SDRmn.STCLK + 1) ]

percent_error = 100 * abs [(actual_bitrate - expected_bitrate) / expected_bitrate]

Using the fastest possible operation clock for the desired bitrate will result in the lowest deviation from the requested baud rate. Set the CKmn operation clock divider in the Clocks tab to select the desired operation clock frequency.

Example of Selecting Operation Clock Frequency

Suppose an example application with a 32MHz ICLK requires:

1 SAU0 UART0 instance running at 1000 bps
1 SAU0 UART1 instance running at 115200 bps

The following operation clocks could be used:

# Operation clock frequency of 250 kHz with 32 Mhz ICLK (32MHz/128=250 kHz)
bitrate_min = 250e3 / [ 2 * (127 + 1) ] = ~976 bps
bitrate_max = 250e3 / [ 2 * (2 + 1) ] = ~41,666 bps
# Operation clock frequency of 16 MHz with 32 MHz ICLK (32MHz/2=16 MHz)
bitrate_min = 16e6 / [ 2 * (127 + 1) ] = ~62,500 bps
bitrate_max = 16e6 / [ 2 * (2 + 1) ] = ~2,666,666 bps

An operation clock of 250 kHz works for UART0 because 1000 is in the range [976, 41.6k]. An operation clock of 16 MHz works for UART1 because 115200 is in the range [62.5k, 2.6M].

Applying the settings:

Select CK0 for UART0 and CK1 for UART1 using the SAU UART "Extra > Operation Clock" property
Set CK00 Div to /128 for SAU0, CK0 (UART0) in the Clocks tab
Set CK01 Div to /2 for for SAU0, CK1 (UART1) in the Clocks tab

Runtime Baud Rate Change

In order to change the baud rate at runtime, "Common > Enable Fixed Baudrate" must be set to "Disabled" in the module properties.

If changing the baud rate is required at runtime, use a unique operation clock for each SAU instance. This is required because R_SAU_UART_BaudSet may change the operation clock divider. Since the operation clocks are shared between SAU channels on each SAU unit, changing a shared operation clock of one instance will cause an incorrect bitrate to be generated on the other instance(s).

If the system clock frequency is changed at runtime, this setting should be disabled, as the baud rate settings will need to be updated after the system clock change.

Limitations

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.
If 9-bit data length is specified at R_SAU_UART_Open call, p_src in R_SAU_UART_Write must be aligned on a 16-bit boundary.
When multiple channels on the same SAU unit need to be used, and one is configured as UART, then critical section property needs to be enabled.

DTC Limitations

DTC support is available for reception, but labeled as [Not recommended]. This is because the UART bytes are received asynchronously. Bytes can be received between calls to R_SAU_UART_Read(). The logic required to combine bytes received through R_SAU_UART_Read() (UART_EVENT_RX_COMPLETE) and bytes received between calls (UART_EVENT_RX_CHAR) is complex. Reception length may also be unknown, and the driver will not issue an interrupt unless the entire DTC buffer is filled.
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.
When using 9-bit reception with DTC, clear the upper 7 bits of data before processing the read data. The upper 7 bits contain status flags that are part of the register used to read data in 9-bit mode.

Examples

SAU 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_sau_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_SAU_UART_Open(&g_uart0_ctrl, &g_uart0_cfg);
    assert(FSP_SUCCESS == err);
    err = R_SAU_UART_Read(&g_uart0_ctrl, g_dest, TRANSFER_LENGTH);
    assert(FSP_SUCCESS == err);
    err = R_SAU_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 */
        case UART_EVENT_RX_CHAR:
        {
            /* 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 */
        case UART_EVENT_RX_COMPLETE:
        {
            g_receive_complete = 1;
            break;
        }
        /* Transmit complete */
        case UART_EVENT_TX_COMPLETE:
        {
            g_transfer_complete = 1;
            break;
        }
        default:
        {
        }
    }
}

SAU UART Baud Set Example

#define SAU_UART_BAUDRATE_19200              (19200)
#define SAU_UART_BAUDRATE_ERROR_PERCENT_5    (5000)
void r_sau_uart_baud_example (void)
{
    sau_uart_baudrate_setting_t baud_setting;
    uint32_t baud_rate = SAU_UART_BAUDRATE_19200;
    fsp_err_t err = R_SAU_UART_BaudCalculate(&g_uart0_ctrl, baud_rate, &baud_setting);
    assert(FSP_SUCCESS == err);
    err = R_SAU_UART_BaudSet(&g_uart0_ctrl, (void *) &baud_setting);
    assert(FSP_SUCCESS == err);
}

Data Structures
struct	sau_uart_extended_cfg_t

struct	sau_uart_instance_ctrl_t

Enumerations
enum	sau_uart_data_sequence_t

enum	sau_operation_clock_t

enum	sau_uart_signal_level_t

Data Structure Documentation

◆ sau_uart_extended_cfg_t

struct sau_uart_extended_cfg_t

UART Configuration

Data Fields
sau_uart_data_sequence_t	sequence	Transfer sequence (LSB or MSB)
sau_uart_signal_level_t	signal_level	Transfer data signal level (standard or inverted)
sau_uart_baudrate_setting_t *	p_baudrate	Baud rate setting (SPS and SDR value)

◆ sau_uart_instance_ctrl_t

struct sau_uart_instance_ctrl_t

UART instance control block. DO NOT INITIALIZE.

Data Fields
uint8_t	extra_data_byte
	0 for 7 or 8 bit data length(1-byte), 1 for 9 bit data length(2-byte)

uint32_t	open
	Used to determine if the channel is configured.

uart_cfg_t const *	p_cfg
	Pointer to the configuration block.

R_SAU0_Type *	p_reg
	Base register for the transmit channel.

uint8_t	sau_unit
	SAU unit information.

uint8_t	sau_tx_channel
	SAU channel information.

uint8_t *	p_src
	Source buffer pointer.

uint32_t	tx_count
	Size of destination buffer pointer from transmit ISR.

uint8_t *	p_dest
	Destination buffer pointer.

uint32_t	rx_count
	Size of destination buffer pointer used for receiving data.

Enumeration Type Documentation

◆ sau_uart_data_sequence_t

enum sau_uart_data_sequence_t

UART Data transfer sequence definition

Enumerator
SAU_UART_DATA_SEQUENCE_MSB	Data sequence MSB first.
SAU_UART_DATA_SEQUENCE_LSB	Data sequence LSB first.

◆ sau_operation_clock_t

enum sau_operation_clock_t

UART operation clock selection definition

Enumerator
SAU_UART_OPERATION_CLOCK_CK0	Operating clock use CK0.
SAU_UART_OPERATION_CLOCK_CK1	Operating clock use CK1.

◆ sau_uart_signal_level_t

enum sau_uart_signal_level_t

UART data signal level definition

Enumerator
SAU_UART_SIGNAL_LEVEL_STANDARD	Uart data signal level standard.
SAU_UART_SIGNAL_LEVEL_INVERTED	Uart data signal level inverted.

Function Documentation

◆ R_SAU_UART_Open()

fsp_err_t R_SAU_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_SUCCESS	Channel opened successfully.
FSP_ERR_ASSERTION	Pointer to UART control block or configuration structure is NULL.
FSP_ERR_IP_CHANNEL_NOT_PRESENT	The requested channel does not exist on this MCU.
FSP_ERR_INVALID_ARGUMENT	Flow 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_OPEN	Control 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:

transfer_api_t::open

◆ R_SAU_UART_Close()

fsp_err_t R_SAU_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_SUCCESS	Channel successfully closed.
FSP_ERR_ASSERTION	Pointer to UART control block is NULL.
FSP_ERR_NOT_OPEN	The control block has not been opened

◆ R_SAU_UART_Read()

fsp_err_t R_SAU_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_SUCCESS	Data reception successfully ends.
FSP_ERR_ASSERTION	Pointer to UART control block is NULL. Number of transfers outside the max or min boundary when transfer instance used
FSP_ERR_INVALID_ARGUMENT	Destination address or data size is not valid for 9-bit mode.
FSP_ERR_NOT_OPEN	The control block has not been opened
FSP_ERR_IN_USE	A previous read operation is still in progress.
FSP_ERR_UNSUPPORTED	current operation mode is transmission only.

Returns

See Common Error Codes or functions called by this function for other possible return codes. This function calls:

transfer_api_t::reset

Note: If 9-bit data length is specified at R_SAU_UART_Open call, p_dest must be aligned 16-bit boundary.

◆ R_SAU_UART_Write()

fsp_err_t R_SAU_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_SUCCESS	Data transmission finished successfully.
FSP_ERR_ASSERTION	Pointer to UART control block is NULL. Number of transfers outside the max or min boundary when transfer instance used
FSP_ERR_INVALID_ARGUMENT	Source address or data size is not valid for 9-bit mode.
FSP_ERR_NOT_OPEN	The control block has not been opened
FSP_ERR_IN_USE	A UART transmission is in progress
FSP_ERR_UNSUPPORTED	SAU_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:

transfer_api_t::reset

Note: If 9-bit data length is specified at R_SAU_UART_Open call, p_src must be aligned on a 16-bit boundary.

◆ R_SAU_UART_BaudSet()

fsp_err_t R_SAU_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 sau_uart_baudrate_setting_t structure. Implements uart_api_t::baudSet

Warning: This terminates any in-progress transmission.; This function may change the operation clock frequency. Select a unique operation clock for each SAU instance if using this function.

Return values

FSP_SUCCESS	Baud rate was successfully changed.
FSP_ERR_ASSERTION	Pointer p_ctrl is NULL
FSP_ERR_INVALID_ARGUMENT	p_api_ctrl is empty.
FSP_ERR_NOT_OPEN	The control block has not been opened
FSP_ERR_UNSUPPORTED	Fixed baud rate is enabled

◆ R_SAU_UART_CallbackSet()

fsp_err_t R_SAU_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 for callback structure. Implements uart_api_t::callbackSet

Return values

FSP_SUCCESS	Callback updated successfully.
FSP_ERR_ASSERTION	Pointer p_ctrl is NULL or p_callback_memory is not NULL.
FSP_ERR_NOT_OPEN	The control block has not been opened.

◆ R_SAU_UART_InfoGet()

fsp_err_t R_SAU_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_SUCCESS	Information stored in provided p_info.
FSP_ERR_INVALID_ARGUMENT	Pointer to UART control block is NULL.
FSP_ERR_NOT_OPEN	The control block has not been opened

◆ R_SAU_UART_Abort()

fsp_err_t R_SAU_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_SUCCESS	UART transaction aborted successfully.
FSP_ERR_ASSERTION	Pointer to UART control block is NULL.
FSP_ERR_NOT_OPEN	The control block has not been opened.
FSP_ERR_UNSUPPORTED	The requested Abort direction is unsupported.

Returns

See Common Error Codes or functions called by this function for other possible return codes. This function calls:

transfer_api_t::disable

◆ R_SAU_UART_ReadStop()

fsp_err_t R_SAU_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_SUCCESS	UART transaction aborted successfully.
FSP_ERR_ASSERTION	Pointer to UART control block is NULL.
FSP_ERR_NOT_OPEN	The control block has not been opened.
FSP_ERR_UNSUPPORTED	The requested Abort direction is unsupported.

Returns

See Common Error Codes or functions called by this function for other possible return codes. This function calls:

transfer_api_t::disable

◆ R_SAU_UART_BaudCalculate()

fsp_err_t R_SAU_UART_BaudCalculate	(	sau_uart_instance_ctrl_t *const	p_ctrl,
		uint32_t	baudrate,
		sau_uart_baudrate_setting_t *const	p_baud_setting
	)

Calculates baud rate register settings (SDR.STCLK) for the specified SAU unit.

Parameters

[in]	p_ctrl	Pointer to the SAU UART control block.
[in]	baudrate	Baud rate [bps]. For example, 19200, 57600, 115200, etc.
[out]	p_baud_setting	Baud setting information stored here if successful

Return values

FSP_SUCCESS	Baud rate is successfully calculated
FSP_ERR_UNSUPPORTED	Fixed baudrate is being used
FSP_ERR_ASSERTION	Null pointer
FSP_ERR_INVALID_ARGUMENT	Baud rate is not achievable with selected operation clock frequency

Functions

Detailed Description

Overview

Features

Configuration

Build Time Configurations for r_sau_uart

Configurations for Connectivity > UART (r_sau_uart)

Clock Configuration

Pin Configuration

Usage Notes

9-bit data transfers

Selecting Operation Clock Frequency

Example of Selecting Operation Clock Frequency

Runtime Baud Rate Change

Limitations

DTC Limitations

Examples

SAU UART Example

SAU UART Baud Set Example

Data Structures

Enumerations

Data Structure Documentation

◆ sau_uart_extended_cfg_t

◆ sau_uart_instance_ctrl_t

Data Fields

Enumeration Type Documentation

◆ sau_uart_data_sequence_t

◆ sau_operation_clock_t

◆ sau_uart_signal_level_t

Function Documentation

◆ R_SAU_UART_Open()

◆ R_SAU_UART_Close()

◆ R_SAU_UART_Read()

◆ R_SAU_UART_Write()

◆ R_SAU_UART_BaudSet()

◆ R_SAU_UART_CallbackSet()

◆ R_SAU_UART_InfoGet()

◆ R_SAU_UART_Abort()

◆ R_SAU_UART_ReadStop()

◆ R_SAU_UART_BaudCalculate()