RA Flexible Software Package Documentation  Release v5.6.0

 
SPI (r_spi)

Functions

fsp_err_t R_SPI_Open (spi_ctrl_t *p_api_ctrl, spi_cfg_t const *const p_cfg)
 
fsp_err_t R_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_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_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_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_SPI_Close (spi_ctrl_t *const p_api_ctrl)
 
fsp_err_t R_SPI_CalculateBitrate (uint32_t bitrate, rspck_div_setting_t *spck_div)
 

Detailed Description

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

Overview

Features

Configuration

Build Time Configurations for r_spi

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

ConfigurationOptionsDefaultDescription
Parameter Checking
  • Default (BSP)
  • Enabled
  • Disabled
Default (BSP) If selected code for parameter checking is included in the build.
Enable Support for using a transfer API
  • Enabled
  • Disabled
Enabled If enabled, transfer instances will be included in the build for both transmission and reception.
Enable Transmitting from RXI Interrupt
  • Enabled
  • Disabled
Disabled If enabled, all operations will be handled from the RX (receive) interrupt. This setting only provides a performance boost when neither DTC nor DMAC is used. In addition, Transmit Only mode is not supported when this configuration is enabled.

Configurations for Connectivity > SPI (r_spi)

This module can be added to the Stacks tab via New Stack > Connectivity > SPI (r_spi). 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
NameName must be a valid C symbolg_spi0 Module name.
ChannelValue must be a non-negative integer0 Select the SPI channel.
Receive Interrupt PriorityMCU Specific OptionsSelect the interrupt priority for all SPI interrupts.
Transmit Buffer Empty Interrupt PriorityMCU Specific OptionsSelect the interrupt priority for all SPI interrupts.
Transfer Complete Interrupt PriorityMCU Specific OptionsSelect the interrupt priority for all SPI interrupts.
Error Interrupt PriorityMCU Specific OptionsSelect the interrupt priority for all SPI interrupts.
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.
Mode Fault Error
  • Enable
  • Disable
Disable Detect master/slave mode conflicts.
Bit Order
  • MSB First
  • LSB First
MSB First Select the data bit order.
CallbackName must be a valid C symbolspi_callback A user callback function can be provided. If this callback function is provided, it will be called from the interrupt service routine (ISR).
SPI Mode
  • SPI Operation
  • Clock Synchronous Operation
Clock Synchronous Operation Select the clock sync mode.
Full or Transmit Only Mode
  • Full Duplex
  • Transmit Only
Full Duplex Select Full Duplex or Transmit Only Mode.
Slave Select Polarity
  • Active Low
  • Active High
Active Low Select the slave select active level.
Select SSL(Slave Select)MCU Specific OptionsSelect which slave to use.
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.
Parity Mode
  • Disabled
  • Odd
  • Even
Disabled Select the parity mode if parity is enabled.
Byte Swapping
  • Disable
  • Enable
Disable Select the byte swap mode for 16/32-Bit Data Frames.
BitrateValue must be an integer greater than 016000000 Enter the desired bitrate, change the bitrate to a value supported by MCU. 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 spi_extended_cfg_t structure.
Clock Delay
  • 1 Clock
  • 2 Clocks
  • 3 Clocks
  • 4 Clocks
  • 5 Clocks
  • 6 Clocks
  • 7 Clocks
  • 8 Clocks
1 Clock Configure the number of SPI clock cycles before each data frame.
SSL Negation Delay
  • 1 Clock
  • 2 Clocks
  • 3 Clocks
  • 4 Clocks
  • 5 Clocks
  • 6 Clocks
  • 7 Clocks
  • 8 Clocks
1 Clock Configure the number of SPI clock cycles after each data frame.
Next Access Delay
  • 1 Clock
  • 2 Clocks
  • 3 Clocks
  • 4 Clocks
  • 5 Clocks
  • 6 Clocks
  • 7 Clocks
  • 8 Clocks
1 Clock Configure the number of SPI clock cycles between each data frame.

Clock Configuration

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

MCU GroupPeripheral Clock
RA2A1PCLKB
RA2A2PCLKB
RA2E1PCLKB
RA2E2PCLKB
RA2E3PCLKB
RA2L1PCLKB
RA4E1PCLKA
RA4E2PCLKA
RA4M1PCLKA
RA4M2PCLKA
RA4M3PCLKA
RA4T1PCLKA
RA4W1PCLKA
RA6E1PCLKA
RA6E2PCLKA
RA6M1PCLKA
RA6M2PCLKA
RA6M3PCLKA
RA6M4PCLKA
RA6M5PCLKA
RA6T1PCLKA
RA6T3PCLKA

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_HIGH.

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 TX Underrun and RX Overflow errors.

In order to improve performance at high bitrates, it is recommended that the instance be configured to service transfers using the DTC or DMAC.

Another way 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 SPI 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. This only improves performance when neither the DTC nor DMAC is being used.

Note
Configuring the module to use an RX DTC/DMAC instance without also providing a TX DTC/DMAC instance results in an invalid configuration when RXI transmit is enabled.
Transmit Only mode is not supported when Transmit from RXI is enabled.

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 SPI:

Examples

Basic Example

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

static volatile bool g_transfer_complete = false;
void spi_basic_example (void)
{
uint8_t tx_buffer[TRANSFER_SIZE];
uint8_t rx_buffer[TRANSFER_SIZE];
fsp_err_t err = FSP_SUCCESS;
/* Initialize the SPI module. */
err = R_SPI_Open(&g_spi_ctrl, &g_spi_cfg);
/* Handle any errors. This function should be defined by the user. */
assert(FSP_SUCCESS == err);
/* Start a write/read transfer */
err = R_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)
{
;
}
}
static void r_spi_callback (spi_callback_args_t * p_args)
{
{
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 spi_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 SPI module. */
err = R_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_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. */
/* 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_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);
}

Configuring the SPI Clock Divider Registers

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

void spi_bitrate_example (void)
{
fsp_err_t err = FSP_SUCCESS;
g_spi_cfg.p_extend = &g_spi_extended_cfg;
/* Configure SPI Clock divider to achieve largest bitrate less than or equal to the desired bitrate. */
err = R_SPI_CalculateBitrate(BITRATE, &(g_spi_extended_cfg.spck_div));
assert(FSP_SUCCESS == err);
/* Initialize the SPI module. */
err = R_SPI_Open(&g_spi_ctrl, &g_spi_cfg);
/* Handle any errors. This function should be defined by the user. */
assert(FSP_SUCCESS == err);
}

Data Structures

struct  rspck_div_setting_t
 
struct  spi_extended_cfg_t
 
struct  spi_instance_ctrl_t
 

Enumerations

enum  spi_ssl_mode_t
 
enum  spi_communication_t
 
enum  spi_ssl_polarity_t
 
enum  spi_ssl_select_t
 
enum  spi_mosi_idle_value_fixing_t
 
enum  spi_parity_t
 
enum  spi_byte_swap_t
 
enum  spi_delay_count_t
 

Data Structure Documentation

◆ rspck_div_setting_t

struct rspck_div_setting_t

SPI Clock Divider settings.

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

◆ spi_extended_cfg_t

struct spi_extended_cfg_t

Extended SPI interface configuration

Data Fields
spi_ssl_mode_t spi_clksyn Select spi or clock syn mode operation.
spi_communication_t spi_comm Select full-duplex or transmit-only communication.
spi_ssl_polarity_t ssl_polarity Select SSLn signal polarity.
spi_ssl_select_t ssl_select Select which slave to use: 0-SSL0, 1-SSL1, 2-SSL2, 3-SSL3.
spi_mosi_idle_value_fixing_t mosi_idle Select MOSI idle fixed value and selection.
spi_parity_t parity Select parity and enable/disable parity.
spi_byte_swap_t byte_swap Select byte swap mode.
rspck_div_setting_t spck_div Register values for configuring the SPI Clock Divider.
spi_delay_count_t spck_delay SPI Clock Delay Register Setting.
spi_delay_count_t ssl_negation_delay SPI Slave Select Negation Delay Register Setting.
spi_delay_count_t next_access_delay SPI Next-Access Delay Register Setting.

◆ spi_instance_ctrl_t

struct spi_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.
 
R_SPI0_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)
 
uint32_t 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)
 

Enumeration Type Documentation

◆ spi_ssl_mode_t

3-Wire or 4-Wire mode.

Enumerator
SPI_SSL_MODE_SPI 

SPI operation (4-wire method)

SPI_SSL_MODE_CLK_SYN 

Clock Synchronous operation (3-wire method)

◆ spi_communication_t

Transmit Only (Half Duplex), or Full Duplex.

Enumerator
SPI_COMMUNICATION_FULL_DUPLEX 

Full-Duplex synchronous serial communication.

SPI_COMMUNICATION_TRANSMIT_ONLY 

Transit only serial communication.

◆ spi_ssl_polarity_t

Slave Select Polarity.

Enumerator
SPI_SSLP_LOW 

SSLP signal polarity active low.

SPI_SSLP_HIGH 

SSLP signal polarity active high.

◆ spi_ssl_select_t

The Slave Select Line

Enumerator
SPI_SSL_SELECT_SSL0 

Select SSL0.

SPI_SSL_SELECT_SSL1 

Select SSL1.

SPI_SSL_SELECT_SSL2 

Select SSL2.

SPI_SSL_SELECT_SSL3 

Select SSL3.

◆ spi_mosi_idle_value_fixing_t

MOSI Idle Behavior.

Enumerator
SPI_MOSI_IDLE_VALUE_FIXING_DISABLE 

MOSI output value=value set in MOIFV bit.

SPI_MOSI_IDLE_VALUE_FIXING_LOW 

MOSIn level low during MOSI idling.

SPI_MOSI_IDLE_VALUE_FIXING_HIGH 

MOSIn level high during MOSI idling.

◆ spi_parity_t

Parity Mode

Enumerator
SPI_PARITY_MODE_DISABLE 

Disable parity.

SPI_PARITY_MODE_ODD 

Select even parity.

SPI_PARITY_MODE_EVEN 

Select odd parity.

◆ spi_byte_swap_t

Byte Swapping Enable/Disable.

Enumerator
SPI_BYTE_SWAP_DISABLE 

Disable Byte swapping for 16/32-Bit transfers.

SPI_BYTE_SWAP_ENABLE 

Enable Byte swapping for 16/32-Bit transfers.

◆ spi_delay_count_t

Delay count for SPI delay settings.

Enumerator
SPI_DELAY_COUNT_1 

Set RSPCK delay count to 1 RSPCK.

SPI_DELAY_COUNT_2 

Set RSPCK delay count to 2 RSPCK.

SPI_DELAY_COUNT_3 

Set RSPCK delay count to 3 RSPCK.

SPI_DELAY_COUNT_4 

Set RSPCK delay count to 4 RSPCK.

SPI_DELAY_COUNT_5 

Set RSPCK delay count to 5 RSPCK.

SPI_DELAY_COUNT_6 

Set RSPCK delay count to 6 RSPCK.

SPI_DELAY_COUNT_7 

Set RSPCK delay count to 7 RSPCK.

SPI_DELAY_COUNT_8 

Set RSPCK delay count to 8 RSPCK.

Function Documentation

◆ R_SPI_Open()

fsp_err_t R_SPI_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_SUCCESSChannel initialized successfully.
FSP_ERR_ALREADY_OPENInstance was already initialized.
FSP_ERR_ASSERTIONAn invalid argument was given in the configuration structure.
FSP_ERR_UNSUPPORTEDA requested setting is not possible on this device with the current build configuration.
FSP_ERR_IP_CHANNEL_NOT_PRESENTThe channel number is invalid.
Returns
See Common Error Codes or functions called by this function for other possible return codes. This function calls: transfer_api_t::open
Note
This function is reentrant.

◆ R_SPI_Read()

fsp_err_t R_SPI_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_SUCCESSRead operation successfully completed.
FSP_ERR_ASSERTIONNULL pointer to control or destination parameters or transfer length is zero.
FSP_ERR_NOT_OPENThe channel has not been opened. Open channel first.
FSP_ERR_IN_USEA transfer is already in progress.

◆ R_SPI_Write()

fsp_err_t R_SPI_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_SUCCESSWrite operation successfully completed.
FSP_ERR_ASSERTIONNULL pointer to control or source parameters or transfer length is zero.
FSP_ERR_NOT_OPENThe channel has not been opened. Open the channel first.
FSP_ERR_IN_USEA transfer is already in progress.

◆ R_SPI_WriteRead()

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

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_SUCCESSWrite operation successfully completed.
FSP_ERR_ASSERTIONNULL pointer to control, source or destination parameters or transfer length is zero.
FSP_ERR_NOT_OPENThe channel has not been opened. Open the channel first.
FSP_ERR_IN_USEA transfer is already in progress.

◆ R_SPI_CallbackSet()

fsp_err_t R_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_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_SPI_Close()

fsp_err_t R_SPI_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_SUCCESSChannel successfully closed.
FSP_ERR_ASSERTIONA required pointer argument is NULL.
FSP_ERR_NOT_OPENThe channel has not been opened. Open the channel first.

◆ R_SPI_CalculateBitrate()

fsp_err_t R_SPI_CalculateBitrate ( uint32_t  bitrate,
rspck_div_setting_t spck_div 
)

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

Parameters
[in]bitrateDesired bitrate
[out]spck_divMemory location to store bitrate register settings.
Return values
FSP_SUCCESSValid spbr and brdv values were calculated
FSP_ERR_UNSUPPORTEDBitrate is not achievable