SPI (r_sau_spi)

Functions
fsp_err_t	R_SAU_SPI_Open (spi_ctrl_t *p_api_ctrl, spi_cfg_t const *const p_cfg)
fsp_err_t	R_SAU_SPI_Read (spi_ctrl_t *const p_api_ctrl, void *p_dest, uint32_t const length, spi_bit_width_t const bit_width)
fsp_err_t	R_SAU_SPI_Write (spi_ctrl_t *const p_api_ctrl, void const *p_src, uint32_t const length, spi_bit_width_t const bit_width)
fsp_err_t	R_SAU_SPI_WriteRead (spi_ctrl_t *const p_api_ctrl, void const *p_src, void *p_dest, uint32_t const length, spi_bit_width_t const bit_width)
fsp_err_t	R_SAU_SPI_CallbackSet (spi_ctrl_t *const p_api_ctrl, void(*p_callback)(spi_callback_args_t *), void const *const p_context, spi_callback_args_t *const p_callback_memory)
fsp_err_t	R_SAU_SPI_Close (spi_ctrl_t *const p_api_ctrl)
fsp_err_t	R_SAU_SPI_CalculateBitrate (uint32_t bitrate, sau_spi_div_setting_t *sclk_div, uint8_t sau_unit, uint8_t channel)

Detailed Description

Driver for the SAU peripheral on RA MCUs. This module implements the SPI Interface.

Overview

Features

• Standard SPI Modes
  • Master or Slave Mode
  • Single Transfer Mode or Continuous Transfer Mode
  • Data Phase (DAPmn)
    • DAPmn=0 Data output starts from the start of the operation of the serial clock
    • DAPmn=1 Data output starts half a clock cycle before the start of the serial clock operation
  • Clock Phase (CKPmn)
    • CKPmn=0 Non-reverse
    • CKPmn=1 Reverse
  • MSB/LSB first
• DTC Support
• Callback Events
  • Transfer Complete

Configuration

• RX Overflow Error (The SAU shift register is copied to the data register before previous data was read)

  Build Time Configurations for r_sau_spi

  The following build time configurations are defined in fsp_cfg/r_sau_spi_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 or R_SAU_UART module is being used simultaneously with this module.
  Enable Single Channel	00 20 11 Disabled	Disabled	Enable single channel to reduce code size if only one channel (00, 11, or 20) is to be configured for SAU SPI.
  Transfer Operating Mode	Reception Transmission Transmission/Reception	Transmission/Reception	Select transfer operation mode.
  DTC Support	Enable Disable	Disable	Enable DTC support for the SAU SPI module.

  Configurations for Connectivity > SPI (r_sau_spi)

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

  Configuration	Options	Default	Description
  Name	Name must be a valid C symbol	g_spi0	Module name.
  Channel	MCU Specific Options		Select the SAU channel.
  Operating Mode	Master Slave	Master	Select the SPI operating mode.
  Operation Clock	CK0 CK1	CK0	Select the operation clock. Use the Clocks tab to set the operation clock divider.
  Transfer Mode	Single transfer mode Continuous transfer mode	Single transfer mode	Select transfer mode in transfer end interrupt. But buffer empty interrupt (in continuous transfer mode) cannot be selected in Slave Reception.
  Bit Order	MSB First LSB First	MSB First	Select of data transfer sequence.
  Data Phase	Data sampling on odd edge, data variation on even edge Data sampling on even edge, data variation on odd edge	Data sampling on odd edge, data variation on even edge	Select when data output shall start compared with the serial clock operation.
  Clock Phase	High when idle Low when idle	High when idle	Select clock phase.
  Bitrate	Value must be an integer greater than 0	500000	Enter the desired bitrate. If the requested bitrate cannot be achieved, adjust the operation clock frequency until the bitrate is achievable. The calculated bitrate is printed in a comment in the generated sau_spi_extended_cfg_t structure.
  Callback	Name must be a valid C symbol	sau_spi_callback	A user callback function that is called from the sau spi interrupts when a transfer is completed or an error has occurred.
  Transmit End Interrupt Priority	MCU Specific Options		Select the transmit end 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).

Clock Phase/Polarity Configuration

The following table illustrates the settings of the Clock Phase/Polarity corresponding SCRmn register DCP[1:0] bits in the SAU SPI.

Clock Phase	Clock Polarity	DCP[1:0] Value
Data sampling on odd edge, data variation on even edge	High when idle	0b00
Data sampling on odd edge, data variation on even edge	Low when idle	0b01
Data sampling on even edge, data variation on odd edge	High when idle	0b10
Data sampling on even edge, data variation on odd edge	Low when idle	0b11

Pin Configuration

This module uses SCKmn, SOmn, and SImn pins to communicate with on board devices.

Note

At high bit rates, it might be necessary to configure the pins with IOPORT_CFG_DRIVE_HIGH.

Enabling DTC with the SAU SPI

• DTC transfer is disabled by default. When DTC is enabled, error event will not be handled until transfer is completed.
• For further details on DTC please refer Transfer (r_dtc)

Usage Notes

Enabling Single Channel By User With The SAU SPI

• The Common > Single Channel property is used for reducing code size when only 1 SAU channel is to be configured for SAU SPI.
• Single Channel is configurable and disabled by default in the driver code.
• Note: Not all SAU channels are available on all pin layouts. Check the Hardware User Manual for your device to confirm available function assignment for each SAU channel.

Transfer Complete Event

The transfer complete event is triggered when all of the data has been transferred. In slave mode if the SS pin is de-asserted then no transfer complete event is generated until the SS pin is asserted and the remaining data is transferred.

Performance

At high bit rates, interrupts may not be able to service transfers fast enough. In master mode this means there will be a delay between each data frame. In slave mode this could result in RX Overflow errors.

To improve performance at high bit rates, it is recommended that the instance be configured to service transfers using the DTC.

Slave Select Pin

• In master mode the slave select pin must be driven in software.
• In slave mode the hardware handles the slave select pin and will only transfer data when the SS pin is low.

Single Channel Use Case

If only SAU channel 00 is to be used for I2C or SPI or UART, enable single channel can reduce the code size.

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 [0, 127] for SAU SPI
• 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 bitrate. Set the CKmn operation clock divider in the Clocks tab to select the desired operation clock frequency.

Runtime bitrate calculation

The function R_SAU_SPI_CalculateBitrate can be used at runtime to calculate alternate bitrate settings.

This function computes settings with both operation clocks CK0 and CK1. If valid settings are possible with both clocks, it selects the settings and clock that would produce the lowest error.

Set the divisors for CK0 and CK01 in the clocks tab such that all required bitrate settings for the application are possible. A large range of bitrates can be achieved by having one "slow" operation clock for low speed modes and one "fast" operation clock for high speed modes.

Limitations

• When multiple channels on the same SAU unit need to be used, and one is configured as I2C, then critical section property needs to be enabled.
• Continuous transfer mode will be deprecated.

Examples

Basic Example

This is a basic example of minimal use of the SAU_SPI in an application.

static volatile bool g_transfer_complete = false;

static void r_sau_spi_callback (spi_callback_args_t * p_args)
{
    if (SPI_EVENT_TRANSFER_COMPLETE == p_args->event)
    {
        g_transfer_complete = true;
    }
}

void sau_spi_basic_example (void)
{
    uint8_t tx_buffer[TRANSFER_SIZE];
    uint8_t rx_buffer[TRANSFER_SIZE];

    /* Configure Slave Select Line 1 */
    R_BSP_PinWrite(SLAVE_SELECT_LINE_1, BSP_IO_LEVEL_HIGH);

    /* Configure Slave Select Line 2 */
    R_BSP_PinWrite(SLAVE_SELECT_LINE_2, BSP_IO_LEVEL_HIGH);

    fsp_err_t err = FSP_SUCCESS;

    /* Initialize the SPI module. */
    err = R_SAU_SPI_Open(&g_spi_ctrl, &g_spi_cfg);

    /* Handle any errors. This function should be defined by the user. */
    assert(FSP_SUCCESS == err);

    /* Assert Slave Select Line 1 */
    R_BSP_PinWrite(SLAVE_SELECT_LINE_1, BSP_IO_LEVEL_LOW);

    /* Start a write/read transfer */
    g_transfer_complete = false;

    err = R_SAU_SPI_WriteRead(&g_spi_ctrl, tx_buffer, rx_buffer, TRANSFER_SIZE, SPI_BIT_WIDTH_8_BITS);
    assert(FSP_SUCCESS == err);

    /* Wait for SPI_EVENT_TRANSFER_COMPLETE callback event. */
    while (false == g_transfer_complete)
    {
        ;
    }

    /* De-assert Slave Select Line 1 */
    R_BSP_PinWrite(SLAVE_SELECT_LINE_1, BSP_IO_LEVEL_HIGH);

    /* Wait for minimum time required between transfers. */
    R_BSP_SoftwareDelay(NEXT_ACCESS_DELAY, BSP_DELAY_UNITS_MICROSECONDS);

    /* Assert Slave Select Line 2 */
    R_BSP_PinWrite(SLAVE_SELECT_LINE_2, BSP_IO_LEVEL_LOW);

    /* Start a write/read transfer */
    g_transfer_complete = false;

    err = R_SAU_SPI_WriteRead(&g_spi_ctrl, tx_buffer, rx_buffer, TRANSFER_SIZE, SPI_BIT_WIDTH_8_BITS);
    assert(FSP_SUCCESS == err);

    /* Wait for SPI_EVENT_TRANSFER_COMPLETE callback event. */
    while (false == g_transfer_complete)
    {
        ;
    }

    /* De-assert Slave Select Line 2 */
    R_BSP_PinWrite(SLAVE_SELECT_LINE_2, BSP_IO_LEVEL_HIGH);
}

#define	SAU_SPI_TRANSFER_MODE_RECEPTION
	Reception only.
#define	SAU_SPI_TRANSFER_MODE_TRANSMISSION
	Transmission only.
#define	SAU_SPI_TRANSFER_MODE_TRANSMISSION_RECEPTION
	Transmission/reception.
enum	sau_spi_operation_clock_t
enum	sau_spi_transfer_mode_t
enum	sau_spi_data_phase_t
enum	sau_spi_clock_phase_t

Enumeration Type Documentation

sau_spi_operation_clock_t

enum sau_spi_operation_clock_t

Selection of operating clock (fMCK) of channel

sau_spi_transfer_mode_t

enum sau_spi_transfer_mode_t

Selection of transfer mode of channel

sau_spi_data_phase_t

enum sau_spi_data_phase_t

Data phase

sau_spi_clock_phase_t

enum sau_spi_clock_phase_t

Clock phase

Function Documentation

R_SAU_SPI_Open()

fsp_err_t R_SAU_SPI_Open	(	spi_ctrl_t *	p_api_ctrl,
		spi_cfg_t const *const	p_cfg
	)

Initialize a channel for SPI communication mode. Implements spi_api_t::open.

This function performs the following tasks:

• Performs parameter checking and processes error conditions.
• Enables the clock for the SAU channel.
• Initializes the associated registers with default value and the user-configurable options.
• Provides the channel handle for use with other API functions.

Parameters

p_api_ctrl	Pointer to the control structure.
p_cfg	Pointer to a configuration structure.

Return values

FSP_SUCCESS	Channel initialized successfully.
FSP_ERR_ASSERTION	An input parameter is invalid or NULL.
FSP_ERR_ALREADY_OPEN	The instance has already been opened.
FSP_ERR_IP_CHANNEL_NOT_PRESENT	The channel number is invalid.

R_SAU_SPI_Read()

fsp_err_t R_SAU_SPI_Read	(	spi_ctrl_t *const	p_api_ctrl,
		void *	p_dest,
		uint32_t const	length,
		spi_bit_width_t const	bit_width
	)

Receive data from an SPI device. Implements spi_api_t::read.

The function performs the following tasks:

• Performs parameter checking and processes error conditions.
• Enable transmitter.
• Enable receiver.
• Enable interrupts.
• Start data transmission by writing data to the TXD register.
• Receive data from receive buffer full interrupt occurs and copy data to the buffer of destination.
• Complete data reception via receive buffer full interrupt and transmitting dummy data.
• Disable transmitter.
• Disable receiver.
• Disable interrupts.

Parameters

	p_api_ctrl	Pointer to the control structure.
	p_dest	Pointer to the destination buffer.
[in]	length	The number of bytes to transfer.
[in]	bit_width	Data frame length (Set to SPI_BIT_WIDTH_7_BITS or SPI_BIT_WIDTH_8_BITS).

Return values

FSP_SUCCESS	Read operation successfully completed.
FSP_ERR_ASSERTION	One of the following invalid parameters passed: Pointer p_api_ctrl is NULL Bit width is not 8 bits Length is equal to 0 Pointer to destination is NULL
FSP_ERR_NOT_OPEN	The channel has not been opened. Open the channel first.
FSP_ERR_UNSUPPORTED	The given bit_width is not supported.
FSP_ERR_IN_USE	A transfer is already in progress.

Returns

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

• transfer_api_t::reconfigure

R_SAU_SPI_Write()

fsp_err_t R_SAU_SPI_Write	(	spi_ctrl_t *const	p_api_ctrl,
		void const *	p_src,
		uint32_t const	length,
		spi_bit_width_t const	bit_width
	)

Transmit data to a SPI device. Implements spi_api_t::write.

The function performs the following tasks:

• Performs parameter checking and processes error conditions.
• Enable transmitter.
• Enable interrupts.
• Start data transmission with data via transmit buffer empty interrupt.
• Copy data from source buffer to the SPI data register for transmission.
• Complete data transmission via transmit buffer empty interrupt.
• Disable transmitter.
• Disable receiver.
• Disable interrupts.

Parameters

	p_api_ctrl	Pointer to the control structure.
	p_src	Pointer to the source buffer.
[in]	length	The number of bytes to transfer.
[in]	bit_width	Data frame length (Set to SPI_BIT_WIDTH_7_BITS or SPI_BIT_WIDTH_8_BITS).

Return values

FSP_SUCCESS	Write operation successfully completed.
FSP_ERR_ASSERTION	One of the following invalid parameters passed: Pointer p_api_ctrl is NULL Pointer to source is NULL Length is equal to 0 Bit width is not equal to 8 bits
FSP_ERR_NOT_OPEN	The channel has not been opened. Open the channel first.
FSP_ERR_UNSUPPORTED	The given bit_width is not supported.
FSP_ERR_IN_USE	A transfer is already in progress.

Returns

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

• transfer_api_t::reconfigure

R_SAU_SPI_WriteRead()

fsp_err_t R_SAU_SPI_WriteRead	(	spi_ctrl_t *const	p_api_ctrl,
		void const *	p_src,
		void *	p_dest,
		uint32_t const	length,
		spi_bit_width_t const	bit_width
	)

Simultaneously transmit data to SPI device while receiving data from SPI device (full duplex). Implements spi_api_t::writeRead.

The function performs the following tasks:

• Performs parameter checking and processes error conditions.
• Enable transmitter.
• Enable receiver.
• Enable interrupts.
• Start data transmission using transmit buffer empty interrupt (or by writing to the TDR register).
• Copy data from source buffer to the SPI data register for transmission.
• Receive data from receive buffer full interrupt and copy data to the destination buffer.
• Complete data transmission and reception via transmit end interrupt.
• Disable transmitter.
• Disable receiver.
• Disable interrupts.

Parameters

	p_api_ctrl	Pointer to the control structure.
	p_src	Pointer to the source buffer.
	p_dest	Pointer to the destination buffer.
[in]	length	The number of bytes to transfer.
[in]	bit_width	Data frame length (Set to SPI_BIT_WIDTH_7_BITS or SPI_BIT_WIDTH_8_BITS).

Return values

FSP_SUCCESS	Write operation successfully completed.
FSP_ERR_ASSERTION	One of the following invalid parameters passed: Pointer p_api_ctrl is NULL Pointer to source is NULL Pointer to destination is NULL Length is equal to 0 Bit width is not equal to 8 bits
FSP_ERR_NOT_OPEN	The channel has not been opened. Open the channel first.
FSP_ERR_UNSUPPORTED	The given bit_width is not supported.
FSP_ERR_IN_USE	A transfer is already in progress.

Returns

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

• transfer_api_t::reconfigure

R_SAU_SPI_CallbackSet()

fsp_err_t R_SAU_SPI_CallbackSet	(	spi_ctrl_t *const	p_api_ctrl,
		void(*)(spi_callback_args_t *)	p_callback,
		void const *const	p_context,
		spi_callback_args_t *const	p_callback_memory
	)

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

Return values

FSP_SUCCESS	Callback updated successfully.
FSP_ERR_ASSERTION	A required pointer is NULL.
FSP_ERR_NOT_OPEN	The control block has not been opened.

R_SAU_SPI_Close()

fsp_err_t R_SAU_SPI_Close

(

spi_ctrl_t *const

p_api_ctrl

)

Disable the SAU channel and set the instance as not open. Implements spi_api_t::close.

Parameters

p_api_ctrl

Pointer to an opened instance.

Return values

FSP_SUCCESS	Channel successfully closed.
FSP_ERR_ASSERTION	The parameter p_api_ctrl is NULL.
FSP_ERR_NOT_OPEN	The channel has not been opened. Open the channel first.

R_SAU_SPI_CalculateBitrate()

fsp_err_t R_SAU_SPI_CalculateBitrate	(	uint32_t	bitrate,
		sau_spi_div_setting_t *	sclk_div,
		uint8_t	sau_unit,
		uint8_t	channel
	)

Calculate the register settings required to achieve the desired bitrate.

Note

This function calculates the bitrate settings with both operation clocks CK0 and CK1, then selects the operation clock and register setting combination that would produce the lowest error.

Parameters

[in]	bitrate	bitrate [bps]. For example, 250,000; 500,00; 16,000,000 (max), etc.
[out]	sclk_div	Pointer to sau_spi_div_setting_t used to configure baudrate settings.
	sau_unit	SAU unit.
	channel	SAU channel.

Return values

FSP_SUCCESS	Bitrate is calculated successfully.
FSP_ERR_ASSERTION	Bitrate is not achievable or not valid for the selected unit/channel.