SPI (r_sci_spi)

Functions
fsp_err_t	R_SCI_SPI_Open (spi_ctrl_t *p_ctrl, spi_cfg_t const *const p_cfg)
fsp_err_t	R_SCI_SPI_Read (spi_ctrl_t *const p_ctrl, void *p_dest, uint32_t const length, spi_bit_width_t const bit_width)
fsp_err_t	R_SCI_SPI_Write (spi_ctrl_t *const p_ctrl, void const *p_src, uint32_t const length, spi_bit_width_t const bit_width)
fsp_err_t	R_SCI_SPI_WriteRead (spi_ctrl_t *const p_ctrl, void const *p_src, void *p_dest, uint32_t const length, spi_bit_width_t const bit_width)
fsp_err_t	R_SCI_SPI_CallbackSet (spi_ctrl_t *const p_ctrl, void(*p_callback)(spi_callback_args_t *), void *const p_context, spi_callback_args_t *const p_callback_memory)
fsp_err_t	R_SCI_SPI_Close (spi_ctrl_t *const p_ctrl)
fsp_err_t	R_SCI_SPI_CalculateBitrate (uint32_t bitrate, sci_spi_clock_source_t clock_source, sci_spi_div_setting_t *sclk_div)

Detailed Description

Driver for the SCI peripheral on RZ microprocessor. This module implements the SPI Interface.

Overview

Features

• Standard SPI Modes
  • Master or Slave Mode
  • Clock Polarity (CPOL)
    • CPOL=0 SCLK is low when idle
    • CPOL=1 SCLK is high when idle
  • Clock Phase (CPHA)
    • CPHA=0 Select data sampling on leading edge, data change on trailing edge
    • CPHA=1 Select data change on leading edge, data sampling on trailing edge
  • MSB/LSB first
• Configurable bit rate
• DMAC Support (with or without FIFO mode)
• Callback Events
  • Transfer Complete
  • RX Overflow Error (The SCI shift register is copied to the data register before previous data was read)

Configuration

Build Time Configurations for r_sci_spi

The following build time configurations are defined in fsp_cfg/r_sci_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.
DMAC Support	Enabled Disabled	Enabled	If support for transferring data using the DMAC will be compiled in. Even if DMAC support is enabled, DMAC is not used without adding DMAC driver.
Nested Interrupt (Multiplex Interrupt)	Enabled Disabled	Disabled	Enable nested interrupt for a single driver.
FIFO Support	Enabled Disabled	Disabled	Enable FIFO support for the SCI_SPI module.

Configurations for Connectivity > SPI (r_sci_spi)

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

Configuration	Options	Default	Description
Name	Name must be a valid C symbol	g_sci_spi0	Module name.
Channel	Value must be a non-negative integer	0	Select the SCI channel. Do not select the safety channel when using DMAC.
Operating Mode	Master Slave	Master	Select the SPI operating mode.
Clock 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 the clock edge to sample data.
Clock Polarity	Low when idle High when idle	Low when idle	Select clock level when idle.
Bit Order	MSB First LSB First	MSB First	Select the data bit order.
Clock Source	SCInASYNCCLK PCLKM	SCInASYNCCLK	Select whether the SCInASYNCCLK or peripheral clock (PCLKM) is used for generating the SCK frequency.
Callback	Name must be a valid C symbol	sci_spi_callback	A user callback function that is called from the sci spi interrupts when a transfer is completed or an error has occurred.
Receive Interrupt Priority	MCU Specific Options		Select the receive interrupt priority.
Transmit Interrupt Priority	MCU Specific Options		Select the transmit interrupt priority.
Transmit End Interrupt Priority	MCU Specific Options		Select the transmit end interrupt priority.
Error Interrupt Priority	MCU Specific Options		Select the error interrupt priority.
Bitrate	Value must be an integer greater than 0	8000000	Enter the desired bitrate. If the requested bitrate cannot be achieved, the settings with the largest possible value that is less than or equal to the requested bitrate is used. The actual bitrate is printed in a comment in the generated sci_spi_extended_cfg_t structure.
Transmit FIFO Trigger Level	Disabled 15 (Max)	Disabled	Select Disabled to disable the TX FIFO trigger, or 15 (Max) to trigger the reload when the FIFO is full or after 15 bit times with no data.
Receive Sampling Timing Adjustment (Master Only)	Default (No Delay) 1 PCLKSCIn Cycle 2 PCLKSCIn Cycles 3 PCLKSCIn Cycles 4 PCLKSCIn Cycles	Default (No Delay)	Select the sampling timing delay of the RXDn pin (master mode only). Configuring this property may be required at high bitrates for the master to sample the received data accurately. This setting has no effect in slave mode.

Clock Configuration

The SCI peripheral uses the SCInASYNCCLK or PCLKM for communication and PCLKM for internal operations. Both can be configured via the Clocks tab of the Configuration editor or by using the CGC Interface at run-time.

Pin Configuration

This module uses SCIn_MOSI, SCIn_MISO, SCIn_SPCK, and SCIn_SS pins to communicate with on board devices.

Note

It is recommended to configure the pins with high drive strength (or high-speed high if available) to maintain signal integrity, particularly at high bitrates. The drive strength can be set by opening the e2 studio pin configuration editor, selecting the pin, and configuring 'Drive Capacity'.

Usage Notes

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. This may also result in SPI_EVENT_ERR_READ_OVERFLOW errors.

In order to improve performance at high bit rates, consider the following recommendations:

• Enable DMAC. Note that DMAC will provide the best performance.
• Enable the Transmit Fifo Trigger in the module properties.
• Configure the Receive Sampling Timing Adjustment in the module properties (master mode only). For more information about Receive Sampling Timing Adjustment, refer to the diagram "Reception Sampling Timing Adjustment Operation in Clock Synchronous Mode (Master)" in the HW User's Manual for the selected MCU.
• When using DMAC, set the RX DMAC channel to a higher priority (lower channel number) than the TX channel.
• When using DMAC, consider pausing operation of higher-priority DMAC instances in the project during SPI transfers or reassigning priorities to ensure high-speed SPI channels have top priority to avoid bus contention.

Also note when using DMAC for data transfer, SCI SPI can experience overrun error if the application makes heavy use of another DMAC instance. This is because the arbitration between different triggers/transfers in DMAC is done based on interrupt/trigger priority. Overrun error can be averted with one of the following options:

1. If SCI SPI uses DMAC for data transfer, avoid the use of another DMAC instance in an application.
2. If DMAC is a must for other data transfers, avoid the use of DMAC with SCI SPI.
3. Use the SPI instead of SCI SPI. The SPI hardware can handle overrun conditions.

Transmit From RXI Interrupt

After every byte, the SCI SPI peripheral generates a transmit buffer empty interrupt and a receive buffer full interrupt. Whenever possible, the SCI_SPI module handles both interrupts in the receive buffer full interrupt. This improves performance when the DMAC is not being used.

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.

Limitations

• DMAC activation is not available for safety channel.

Data coherency

Note

This section applies only when SCI SPI utilizes the DMAC.

Source and destination buffers must either be allocated to a non-cacheable region, or, if placed in a cacheable region, be managed via explicit cache maintenance operations (clean/invalidate) to ensure data coherency (This involves cleaning the cache before starting the transmission and invalidating it once the transmission is completed). In the case of the write-back policy, when a destination buffer is placed in a cacheable region, it must be aligned with 64 bytes. See Memory attributes for details.

Examples

Basic Example

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

static volatile bool g_transfer_complete = false;

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

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

    /* Configure Slave Select Line 1 */
    R_BSP_PinSet(R_BSP_IoRegionGet(SLAVE_SELECT_LINE_1), SLAVE_SELECT_LINE_1);

    /* Configure Slave Select Line 2 */
    R_BSP_PinSet(R_BSP_IoRegionGet(SLAVE_SELECT_LINE_2), SLAVE_SELECT_LINE_2);

    fsp_err_t err = FSP_SUCCESS;

    /* Initialize the SPI module. */
    err = R_SCI_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_PinClear(R_BSP_IoRegionGet(SLAVE_SELECT_LINE_1), SLAVE_SELECT_LINE_1);

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

    err = R_SCI_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_PinSet(R_BSP_IoRegionGet(SLAVE_SELECT_LINE_1), SLAVE_SELECT_LINE_1);

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

    /* Assert Slave Select Line 2 */
    R_BSP_PinClear(R_BSP_IoRegionGet(SLAVE_SELECT_LINE_2), SLAVE_SELECT_LINE_2);

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

    err = R_SCI_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_PinSet(R_BSP_IoRegionGet(SLAVE_SELECT_LINE_2), SLAVE_SELECT_LINE_2);
}

Classes
struct	st_sci_spi_div_setting
struct	st_sci_spi_extended_cfg
struct	st_sci_spi_instance_ctrl

Typedefs
typedef struct st_sci_spi_div_setting	sci_spi_div_setting_t
typedef struct st_sci_spi_extended_cfg	sci_spi_extended_cfg_t
typedef struct st_sci_spi_instance_ctrl	sci_spi_instance_ctrl_t

Enumerations
enum	sci_spi_clock_source_t
enum	sci_spi_rx_sampling_delay_t
enum	sci_spi_tx_fifo_trigger_t

---

Class Documentation

RZN::st_sci_spi_div_setting

struct RZN::st_sci_spi_div_setting

Settings for adjusting the SPI CLK.

RZN::st_sci_spi_extended_cfg

struct RZN::st_sci_spi_extended_cfg

SCI SPI extended configuration

Class Members
sci_spi_div_setting_t	clk_div
sci_spi_clock_source_t	clock_source	Clock source to generate SCK can either be selected as PCLKM or SCInASYNCCLK.
sci_spi_rx_sampling_delay_t	rx_sampling_delay	Receive sampling timing adjustment.
sci_spi_tx_fifo_trigger_t	tx_fifo_trigger	Transmit FIFO trigger level.
void *	p_reg	Register base address.

RZN::st_sci_spi_instance_ctrl

struct RZN::st_sci_spi_instance_ctrl

SPI instance control block. DO NOT INITIALIZE.

Typedef Documentation

sci_spi_div_setting_t

typedef struct st_sci_spi_div_setting sci_spi_div_setting_t

Settings for adjusting the SPI CLK. Please refer to the struct st_sci_spi_div_setting.

sci_spi_extended_cfg_t

typedef struct st_sci_spi_extended_cfg sci_spi_extended_cfg_t

SCI SPI extended configuration. Please refer to the struct st_sci_spi_extended_cfg.

sci_spi_instance_ctrl_t

typedef struct st_sci_spi_instance_ctrl sci_spi_instance_ctrl_t

SPI instance control block. DO NOT INITIALIZE. Please refer to the struct st_sci_spi_instance_ctrl.

Enumeration Type Documentation

sci_spi_clock_source_t

enum sci_spi_clock_source_t

Source clock selection options for SCI.

sci_spi_rx_sampling_delay_t

enum sci_spi_rx_sampling_delay_t

Adjustment value for receive sampling timing delay for RXDn

Enumerator
SCI_SPI_RX_SAMPLING_DELAY_CYCLES_0	Use the default receive sampling timing.
SCI_SPI_RX_SAMPLING_DELAY_CYCLES_1	Delay the receive sampling timing by 1 PCLKSCIn cycle.
SCI_SPI_RX_SAMPLING_DELAY_CYCLES_2	Delay the receive sampling timing by 2 PCLKSCIn cycles.
SCI_SPI_RX_SAMPLING_DELAY_CYCLES_3	Delay the receive sampling timing by 3 PCLKSCIn cycles.
SCI_SPI_RX_SAMPLING_DELAY_CYCLES_4	Delay the receive sampling timing by 4 PCLKSCIn cycles.

sci_spi_tx_fifo_trigger_t

enum sci_spi_tx_fifo_trigger_t

Transmit FIFO trigger configuration.

Enumerator
SCI_SPI_TX_FIFO_TRIGGER_DISABLED	FIFO mode not used.
SCI_SPI_TX_FIFO_TRIGGER_MAX	TXI is generated when FIFO is full or after 15 bit times with no data (fewer interrupts)

Function Documentation

R_SCI_SPI_Open()

fsp_err_t R_SCI_SPI_Open	(	spi_ctrl_t *	p_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 SCI 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_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.
FSP_ERR_INVALID_ARGUMENT	Invalid input parameter.
FSP_ERR_UNSUPPORTED	Fifo mode is requested but a transfer interface is not used

R_SCI_SPI_Read()

fsp_err_t R_SCI_SPI_Read	(	spi_ctrl_t *const	p_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_ctrl	Pointer to the control structure.
	p_dest	Pointer to the destination buffer.
[in]	length	The number of bytes to transfer.
[in]	bit_width	Invalid for SCI_SPI (Set to 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_ctrl is NULL 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_SCI_SPI_Write()

fsp_err_t R_SCI_SPI_Write	(	spi_ctrl_t *const	p_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_ctrl	Pointer to the control structure.
	p_src	Pointer to the source buffer.
[in]	length	The number of bytes to transfer.
[in]	bit_width	Invalid for SCI_SPI (Set to 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_ctrl is NULL Pointer to source is NULL Length is equal to 0
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_SCI_SPI_WriteRead()

fsp_err_t R_SCI_SPI_WriteRead	(	spi_ctrl_t *const	p_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_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	Invalid for SCI_SPI (Set to 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_ctrl is NULL Pointer to source is NULL Pointer to destination is NULL Length is equal to 0
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_SCI_SPI_CallbackSet()

fsp_err_t R_SCI_SPI_CallbackSet	(	spi_ctrl_t *const	p_ctrl,
		void(*)(spi_callback_args_t *)	p_callback,
		void *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_SCI_SPI_Close()

fsp_err_t R_SCI_SPI_Close

(

spi_ctrl_t *const

p_ctrl

)

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

Parameters

p_ctrl

Pointer to an opened instance.

Return values

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

R_SCI_SPI_CalculateBitrate()

fsp_err_t R_SCI_SPI_CalculateBitrate	(	uint32_t	bitrate,
		sci_spi_clock_source_t	clock_source,
		sci_spi_div_setting_t *	sclk_div
	)

Calculate the register settings required to achieve the desired bitrate.

Parameters

[in]	bitrate	bitrate [bps]. For example, 250,000; 500,00; 2,500,000; etc.
	clock_source	clock source (PCLKM or SCInASYNCCLK) used for bit rate calculation.
	sclk_div	Pointer to sci_spi_div_setting_t used to configure baudrate settings.

Return values

FSP_SUCCESS	Baud rate is set successfully.
FSP_ERR_ASSERTION	Baud rate is not achievable.
FSP_ERR_INVALID_ARGUMENT	Invalid input parameter.

Note

The application must pause for 1 bit time after the BRR register is loaded before transmitting/receiving to allow time for the clock to settle.