Renesas Serial Peripheral Interface (r_rspi)

Functions
fsp_err_t	R_RSPI_Open (spi_ctrl_t *p_api_ctrl, spi_cfg_t const *const p_cfg)
fsp_err_t	R_RSPI_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_RSPI_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_RSPI_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_RSPI_Close (spi_ctrl_t *const p_api_ctrl)
fsp_err_t	R_RSPI_CalculateBitrate (uint32_t bitrate, rspi_rspck_div_setting_t *spck_div)
fsp_err_t	R_RSPI_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)

Detailed Description

Driver for the RSPI peripheral on RZ MPUs. 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 Data is sampled at an odd edge and changes at an even edge.
    • CPHA=1 Data changes at an odd edge and is sampled at an even edge.
  • MSB/LSB first
  • 8-Bit, 16-Bit, 32-Bit data frames
    • Hardware endian swap in 16-Bit and 32-Bit mode
  • 4-Wire (SPI) Mode
• Configurable bitrate
• Supports Full Duplex Mode
• Callback Events
  • Transfer Complete
  • RX Overflow Error (The RSPI shift register is copied to the data register before previous data was read)
  • Mode Fault Error (The SSL input signal is negated during the serial transfer period)

Configuration

Build Time Configurations for r_rspi

The following build time configurations are defined in fsp_cfg/r_rspi_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	MCU Specific Options		If enabled, DMAC instances will be included in the build for both transmission and reception.

Configurations for Connectivity > SPI (r_rspi)

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

Configuration	Options	Default	Description
General > Name	Name must be a valid C symbol	g_spi0	Module name.
General > Channel	Channel number must be a positive integer	0	Select the RSPI channel.
General > Operating Mode	Master Slave	Master	Select the RSPI operating mode.
General > Clock Phase	CPHA=0 CPHA=1	CPHA=0	Select the clock edge to sample data.
General > Clock Polarity	CPOL=0 CPOL=1	CPOL=0	Select clock level when idle.
General > Mode Fault Error	Enable Disable	Disable	Detect master/slave mode conflicts.
General > Bit Order	MSB First LSB First	MSB First	Select the data bit order.
Extra > Slave Select Polarity	Active Low Active High	Active Low	Select the slave select active level.
Extra > MOSI Idle State	MOSI Idle Value Fixing Disable MOSI Idle Value Fixing Low MOSI Idle Value Fixing High	MOSI Idle Value Fixing Disable	Select the MOSI idle level if MOSI idle is enabled.
Extra > Bitrate	Value must be an integer greater than 0	10000000	Enter the desired bitrate, change the bitrate to a value supported by MPU. 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 theoretical bitrate is printed in a comment in the generated rspi_extended_cfg_t structure.
Extra > Clock Delay	RSPI_DELAY_COUNT_1 RSPI_DELAY_COUNT_2 RSPI_DELAY_COUNT_3 RSPI_DELAY_COUNT_4 RSPI_DELAY_COUNT_5 RSPI_DELAY_COUNT_6 RSPI_DELAY_COUNT_7 RSPI_DELAY_COUNT_8	RSPI_DELAY_COUNT_1	Configure the number of RSPI clock cycles before each data frame.
Extra > SSL Negation Delay	RSPI_DELAY_COUNT_1 RSPI_DELAY_COUNT_2 RSPI_DELAY_COUNT_3 RSPI_DELAY_COUNT_4 RSPI_DELAY_COUNT_5 RSPI_DELAY_COUNT_6 RSPI_DELAY_COUNT_7 RSPI_DELAY_COUNT_8	RSPI_DELAY_COUNT_1	Configure the number of RSPI clock cycles after each data frame.
Extra > Next Access Delay	RSPI_DELAY_COUNT_1 RSPI_DELAY_COUNT_2 RSPI_DELAY_COUNT_3 RSPI_DELAY_COUNT_4 RSPI_DELAY_COUNT_5 RSPI_DELAY_COUNT_6 RSPI_DELAY_COUNT_7 RSPI_DELAY_COUNT_8	RSPI_DELAY_COUNT_1	Configure the number of RSPI clock cycles between each data frame.
Extra > SSL Level Keep	Disable Enable	Disable	Select whether to negate the SSL level for each frame transfer.
Extra > Receiver FIFO Trigger Level	1 2 4 8 16 24 32 5	24	Configure the trigger level of RSPI receiver FIFO.
Extra > Transmitter FIFO Trigger Level	1 2 4 8	4	Configure the trigger level of RSPI transmitter FIFO.
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).
Interrupts > Receive Interrupt Enable	MCU Specific Options		Enable the receive interrupt.
Interrupts > Receive Interrupt Priority	Value must be an integer between 0 and 255	8	Select the interrupt priority for all RSPI interrupts.
Interrupts > Transmit Buffer Empty Interrupt Enable	MCU Specific Options		Enable the transmit buffer empty interrupt.
Interrupts > Transmit Buffer Empty Interrupt Priority	Value must be an integer between 0 and 255	8	Select the interrupt priority for all RSPI interrupts.
Interrupts > Error Interrupt Priority	Value must be an integer between 0 and 255	8	Select the interrupt priority for all RSPI interrupts.

Clock Configuration

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

MCU Group	Peripheral Clock
RZV2L	P0CLK

Pin Configuration

This module uses MOSI, MISO, RSPCK, and SSL pins to communicate with on board devices.

Note

At high bitrates, it might be nessecary to configure the pins with IOPORT_CFG_DRIVE_B11.

Usage Notes

Performance

At high bitrates, 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.

In order to improve performance is to transfer the data in 16/32 bit wide data frames when possible. A typical use-case where this is possible is when reading/writing to a block device.

Transmit From RXI Interrupt

After every data frame the RSPI peripheral generates a transmit buffer empty interrupt and a receive buffer full interrupt. It is possible to configure the driver to handle transmit buffer empty interrupts in the receive buffer full isr.

Clock Auto-Stopping

In master mode, if the Receive Buffer Full Interrupts are not handled fast enough, instead of generating a RX Overflow error, the last clock cycle will be stretched until the receive buffer is read.

Parity Mode

When parity mode is configured, the LSB of each data frame is used as a parity bit. When odd parity is selected, the LSB is set such that there are an odd number of ones in the data frame. When even parity is selected, the LSB is set such that there are an even number of ones in the data frame.

Limitations

Developers should be aware of the following limitations when using the RSPI:

• In master mode, the driver will only configure 4-Wire mode if the device supports SSL Level Keeping (SSLKP bit in SPCMD) and will return FSP_ERR_UNSUPPORTED if configured for 4-Wire mode on devices without SSL Level Keeping. Without SSL Level Keeping, the SSL pin is toggled after every data frame. In most cases this is not desirable behavior so it is recommended that the SSL pin be driven in software if SSL Level Keeping is not present on the device.
• In order to use CPHA=0 setting in slave mode, the master must toggle the SSL pin after every data frame (Even if the device supports SSL Level Keeping). Because of this hardware limitation, the module will return FSP_ERR_UNSUPPORTED when it is configured to use CPHA=0 setting in slave mode.
• The module does not support communicating with multiple slaves using different SSL pins. In order to achieve this, the module must either be closed and re-opened to change the SSL pin or drive SSL in software. It is recommended that SSL be driven in software when controlling multiple slave devices.
• The RSPI peripheral has a minimum 3 SPI CLK delay between each data frame.

Examples

Basic Example

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

static volatile bool g_transfer_complete = false;

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

    fsp_err_t err = FSP_SUCCESS;


    /* Initialize the RSPI module. */
    err = R_RSPI_Open(&g_rspi_ctrl, &g_spi_cfg);


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


    /* Start a write/read transfer */
    err = R_RSPI_WriteRead(&g_rspi_ctrl, tx_buffer, rx_buffer, TRANSFER_SIZE, SPI_BIT_WIDTH_8_BITS);
    handle_error(err);


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

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

Driving Software Slave Select Line

This is an example of communicating with multiple slave devices by asserting SSL in software.

void rspi_software_ssl_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 RSPI module. */
    err = R_RSPI_Open(&g_rspi_ctrl, &g_spi_cfg);

    /* Handle any errors. This function should be defined by the user. */
    handle_error(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_RSPI_WriteRead(&g_rspi_ctrl, tx_buffer, rx_buffer, TRANSFER_SIZE, SPI_BIT_WIDTH_8_BITS);
    handle_error(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(SSL_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_RSPI_WriteRead(&g_rspi_ctrl, tx_buffer, rx_buffer, TRANSFER_SIZE, SPI_BIT_WIDTH_8_BITS);
    handle_error(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);
}

Configuring the RSPI Clock Divider Registers

This example demonstrates how to set the RSPI clock divisors at runtime.

void rspi_bitrate_example (void)
{
    fsp_err_t err = FSP_SUCCESS;

    g_spi_cfg.p_extend = &g_rspi_extended_cfg;

    /* Configure RSPI Clock divider to achieve largest bitrate less than or equal to the desired bitrate. */
    err = R_RSPI_CalculateBitrate(BITRATE, &(g_rspi_extended_cfg.spck_div));
    handle_error(err);

    /* Initialize the RSPI module. */
    err = R_RSPI_Open(&g_rspi_ctrl, &g_spi_cfg);

    /* Handle any errors. This function should be defined by the user. */
    handle_error(err);
}

Data Structures
struct	rspi_rspck_div_setting_t
struct	rspi_extended_cfg_t
struct	rspi_instance_ctrl_t

Enumerations
enum	rspi_ssl_polarity_t
enum	rspi_mosi_idle_value_fixing_t
enum	rspi_ssl_level_keep_t
enum	rspi_delay_count_t
enum	rspi_tx_trigger_level_t
enum	rspi_rx_trigger_level_t

---

Data Structure Documentation

rspi_rspck_div_setting_t

struct rspi_rspck_div_setting_t

RSPI Clock Divider settings.

Data Fields
uint8_t	spbr	SPBR register setting.
uint8_t	brdv: 2	BRDV setting in SPCMD0.

rspi_extended_cfg_t

struct rspi_extended_cfg_t

Extended RSPI interface configuration

Data Fields
rspi_ssl_polarity_t	ssl_polarity	Select SSLn signal polarity.
rspi_mosi_idle_value_fixing_t	mosi_idle	Select MOSI idle fixed value and selection.
rspi_rspck_div_setting_t	spck_div	Register values for configuring the RSPI Clock Divider.
rspi_delay_count_t	spck_delay	SPI Clock Delay Register Setting.
rspi_delay_count_t	ssl_negation_delay	SPI Slave Select Negation Delay Register Setting.
rspi_delay_count_t	next_access_delay	SPI Next-Access Delay Register Setting.
rspi_ssl_level_keep_t	ssl_level_keep	Select SSL signal level keep mode.
rspi_rx_trigger_level_t	rx_trigger_level	Receiver FIFO trigger level.
rspi_tx_trigger_level_t	tx_trigger_level	Transmitter FIFO trigger level.

rspi_instance_ctrl_t

struct rspi_instance_ctrl_t

Channel control block. DO NOT INITIALIZE. Initialization occurs when spi_api_t::open is called.

Data Fields
uint32_t	open
	Indicates whether the open() API has been successfully called.
spi_cfg_t const *	p_cfg
	Pointer to instance configuration.
rspi_extended_cfg_t *	p_ext
	Pointer to extended configuration.
R_RSPI0_Type *	p_regs
	Base register for this channel.
void const *	p_tx_data
	Buffer to transmit.
void *	p_rx_data
	Buffer to receive.
uint32_t	tx_count
	Number of Data Frames to transfer (8-bit, 16-bit, 32-bit)
uint32_t	rx_count
	Number of Data Frames to transfer (8-bit, 16-bit, 32-bit)
spi_bit_width_t	bit_width
	Bits per Data frame (8-bit, 16-bit, 32-bit)
uint32_t	rxfifo_trigger_bytes
	Receive buffer data triggering number.
volatile bool	transfer_is_pending
	Transfer is pending.

Enumeration Type Documentation

rspi_ssl_polarity_t

enum rspi_ssl_polarity_t

Slave Select Polarity.

Enumerator
RSPI_SSLP_LOW	SSLP signal polarity active low.
RSPI_SSLP_HIGH	SSLP signal polarity active high.

rspi_mosi_idle_value_fixing_t

enum rspi_mosi_idle_value_fixing_t

MOSI Idle Behavior.

Enumerator
RSPI_MOSI_IDLE_VALUE_FIXING_DISABLE	MOSI output value=value set in MOIFV bit.
RSPI_MOSI_IDLE_VALUE_FIXING_LOW	MOSIn level low during MOSI idling.
RSPI_MOSI_IDLE_VALUE_FIXING_HIGH	MOSIn level high during MOSI idling.

rspi_ssl_level_keep_t

enum rspi_ssl_level_keep_t

SSL Signal Level Keeping Enable/Disable.

Enumerator
RSPI_SSL_LEVEL_KEEP_DISABLE	Disable SSL Level Keep Mode.
RSPI_SSL_LEVEL_KEEP_ENABLE	Enable SSL Level Keep Mode.

rspi_delay_count_t

enum rspi_delay_count_t

Delay count for SPI delay settings.

Enumerator
RSPI_DELAY_COUNT_1	Set RSPCK delay count to 1 RSPCK.
RSPI_DELAY_COUNT_2	Set RSPCK delay count to 2 RSPCK.
RSPI_DELAY_COUNT_3	Set RSPCK delay count to 3 RSPCK.
RSPI_DELAY_COUNT_4	Set RSPCK delay count to 4 RSPCK.
RSPI_DELAY_COUNT_5	Set RSPCK delay count to 5 RSPCK.
RSPI_DELAY_COUNT_6	Set RSPCK delay count to 6 RSPCK.
RSPI_DELAY_COUNT_7	Set RSPCK delay count to 7 RSPCK.
RSPI_DELAY_COUNT_8	Set RSPCK delay count to 8 RSPCK.

rspi_tx_trigger_level_t

enum rspi_tx_trigger_level_t

Transmitter FIFO trigger level.

Enumerator
RSPI_TX_TRIGGER_7	Trigger when 7 or less bytes in TX FIFO.
RSPI_TX_TRIGGER_6	Trigger when 6 or less bytes in TX FIFO.
RSPI_TX_TRIGGER_4	Trigger when 4 or less bytes in TX FIFO.
RSPI_TX_TRIGGER_0	Trigger when TX FIFO is empty.

rspi_rx_trigger_level_t

enum rspi_rx_trigger_level_t

Receiver FIFO trigger level.

Enumerator
RSPI_RX_TRIGGER_1	Trigger when 1 or more bytes in RX FIFO.
RSPI_RX_TRIGGER_2	Trigger when 2 or more bytes in RX FIFO.
RSPI_RX_TRIGGER_4	Trigger when 4 or more bytes in RX FIFO.
RSPI_RX_TRIGGER_8	Trigger when 8 or more bytes in RX FIFO.
RSPI_RX_TRIGGER_16	Trigger when 16 or more bytes in RX FIFO.
RSPI_RX_TRIGGER_24	Trigger when 24 or more bytes in RX FIFO.
RSPI_RX_TRIGGER_32	Trigger when 32 or more bytes in RX FIFO.
RSPI_RX_TRIGGER_5	Trigger when 5 or more bytes in RX FIFO.

Function Documentation

R_RSPI_Open()

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

This functions initializes a channel for SPI communication mode. Implements spi_api_t::open.

This function performs the following tasks:

• Performs parameter checking and processes error conditions.
• Configures the pperipheral registers acording to the configuration.
• Initialize the control structure for use in other SPI Interface functions.

Return values

FSP_SUCCESS	Channel initialized successfully.
FSP_ERR_ALREADY_OPEN	Instance was already initialized.
FSP_ERR_ASSERTION	An invalid argument was given in the configuration structure.
FSP_ERR_IP_CHANNEL_NOT_PRESENT	The channel number is invalid.

Returns

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

Note

This function is reentrant.

R_RSPI_Read()

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

This function receives data from a SPI device. Implements spi_api_t::read.

The function performs the following tasks:

• Performs parameter checking and processes error conditions.
• Sets up the instance to complete a SPI read operation.

Return values

FSP_SUCCESS	Read operation successfully completed.
FSP_ERR_ASSERTION	NULL pointer to control or destination parameters or transfer length is zero.
FSP_ERR_NOT_OPEN	The channel has not been opened. Open channel first.
FSP_ERR_IN_USE	A transfer is already in progress.
FSP_ERR_INVALID_ARGUMENT	A bit length not supported by this device was assigned to the argument.

R_RSPI_Write()

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

This function transmits data to a SPI device using the TX Only Communications Operation Mode. Implements spi_api_t::write.

The function performs the following tasks:

• Performs parameter checking and processes error conditions.
• Sets up the instance to complete a SPI write operation.

Return values

FSP_SUCCESS	Write operation successfully completed.
FSP_ERR_ASSERTION	NULL pointer to control or source parameters or transfer length is zero.
FSP_ERR_NOT_OPEN	The channel has not been opened. Open the channel first.
FSP_ERR_IN_USE	A transfer is already in progress.
FSP_ERR_INVALID_ARGUMENT	A bit length not supported by this device was assigned to the argument.

R_RSPI_WriteRead()

fsp_err_t R_RSPI_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
	)

This function simultaneously transmits and receive data. Implements spi_api_t::writeRead.

The function performs the following tasks:

• Performs parameter checking and processes error conditions.
• Sets up the instance to complete a SPI writeRead operation.

Return values

FSP_SUCCESS	Write operation successfully completed.
FSP_ERR_ASSERTION	NULL pointer to control, source or destination parameters or transfer length is zero.
FSP_ERR_NOT_OPEN	The channel has not been opened. Open the channel first.
FSP_ERR_IN_USE	A transfer is already in progress.
FSP_ERR_INVALID_ARGUMENT	A bit length not supported by this device was assigned to the argument.

R_RSPI_Close()

fsp_err_t R_RSPI_Close

(

spi_ctrl_t *const

p_api_ctrl

)

This function manages the closing of a channel by the following task. Implements spi_api_t::close.

Disables SPI operations by disabling the SPI bus.

• Disables the SPI peripheral.
• Disables all the associated interrupts.
• Update control structure so it will not work with SPI Interface functions.

Return values

FSP_SUCCESS	Channel successfully closed.
FSP_ERR_ASSERTION	A required pointer argument is NULL.
FSP_ERR_NOT_OPEN	The channel has not been opened. Open the channel first.

R_RSPI_CalculateBitrate()

fsp_err_t R_RSPI_CalculateBitrate	(	uint32_t	bitrate,
		rspi_rspck_div_setting_t *	spck_div
	)

Calculates the SPBR register value and the BRDV bits for a desired bitrate. Calculates the SPBR register value and the BRDV bits for a desired bitrate. If the desired bitrate is faster than the maximum bitrate, then the bitrate is set to the maximum bitrate and an error is returned. If the desired bitrate is slower than the minimum bitrate, then an error is returned.

Parameters

[in]	bitrate	Desired bitrate.
[out]	spck_div	Memory location to store bitrate register settings.

Return values

FSP_SUCCESS	Valid spbr and brdv values were calculated.
FSP_ERR_UNSUPPORTED	Bitrate is out of the settable range.

R_RSPI_CallbackSet()

fsp_err_t R_RSPI_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.
FSP_ERR_NO_CALLBACK_MEMORY	p_callback is non-secure and p_callback_memory is either secure or NULL.