|
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) |
|
Driver for the SPI peripheral on RA MCUs. This module implements the SPI Interface.
Overview
Features
- Standard SPI Modes
- Master or Slave Mode
- 3-Wire (clock synchronous) or 4-Wire (SPI) 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-16 bit, 20-bit, 24-bit, and 32-bit data frames
- Hardware endian swap in 16-bit and 32-bit modes
- SSL level keep (burst transfer) supported if available
- Configurable bitrate
- Supports Full Duplex or Transmit Only Mode
- DTC Support
- DMAC Support
- Callback Events
- Transfer Complete
- RX Overflow Error (The SPI shift register is copied to the data register before previous data was read)
- TX Underrun Error (No data to load into shift register for transmitting)
- Parity Error (When parity is enabled and a parity error is detected)
Configuration
Build Time Configurations for r_spi
The following build time configurations are defined in fsp_cfg/r_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. |
Enable Support for using a transfer API |
| Enabled | If enabled, transfer instances will be included in the build for both transmission and reception. |
Enable Transmitting from RXI Interrupt |
| 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.
Configuration | Options | Default | Description |
Name | Name must be a valid C symbol | g_spi0 | Module name. |
Channel | Value must be a non-negative integer | 0 | Select the SPI channel. |
Receive Interrupt Priority | MCU Specific Options | | Select the interrupt priority for all SPI interrupts. |
Transmit Buffer Empty Interrupt Priority | MCU Specific Options | | Select the interrupt priority for all SPI interrupts. |
Transfer Complete Interrupt Priority | MCU Specific Options | | Select the interrupt priority for all SPI interrupts. |
Error Interrupt Priority | MCU Specific Options | | Select the interrupt priority for all SPI interrupts. |
Operating Mode |
| 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 |
| Disable | Detect master/slave mode conflicts. |
Bit Order |
| MSB First | Select the data bit order. |
Callback | Name must be a valid C symbol | spi_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 | Select the slave select active level. |
Select SSL(Slave Select) | MCU Specific Options | | Select 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 | Select the parity mode if parity is enabled. |
Byte Swapping |
| Disable | Select the byte swap mode for 16/32-Bit Data Frames. |
Bitrate | Value must be an integer greater than 0 | 16000000 | 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 Group | Peripheral Clock |
RA2A1 | PCLKB |
RA2A2 | PCLKB |
RA2E1 | PCLKB |
RA2E2 | PCLKB |
RA2E3 | PCLKB |
RA2L1 | PCLKB |
RA4E1 | PCLKA |
RA4E2 | PCLKA |
RA4M1 | PCLKA |
RA4M2 | PCLKA |
RA4M3 | PCLKA |
RA4T1 | PCLKA |
RA4W1 | PCLKA |
RA6E1 | PCLKA |
RA6E2 | PCLKA |
RA6M1 | PCLKA |
RA6M2 | PCLKA |
RA6M3 | PCLKA |
RA6M4 | PCLKA |
RA6M5 | PCLKA |
RA6T1 | PCLKA |
RA6T3 | PCLKA |
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:
- In master mode, the driver will only configure 4-Wire mode if the device supports SSL Level Keeping (SSLKP bit in SPCMD0) 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 SPI peripheral has a minimum 3 SPI CLK delay between each data frame.
- The behavior for Byte Swap operation is not guaranteed for data frames other than 8-bit, 16-bit and 32bit.
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];
assert(FSP_SUCCESS == err);
assert(FSP_SUCCESS == err);
while (false == g_transfer_complete)
{
;
}
}
{
{
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];
assert(FSP_SUCCESS == err);
g_transfer_complete = false;
assert(FSP_SUCCESS == err);
while (false == g_transfer_complete)
{
;
}
g_transfer_complete = false;
assert(FSP_SUCCESS == err);
while (false == g_transfer_complete)
{
;
}
}
Configuring the SPI Clock Divider Registers
This example demonstrates how to set the SPI clock divisors at runtime.
void spi_bitrate_example (void)
{
g_spi_cfg.p_extend = &g_spi_extended_cfg;
assert(FSP_SUCCESS == err);
assert(FSP_SUCCESS == err);
}
◆ 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
◆ 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)
|
|
◆ 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.
|
◆ R_SPI_Open()
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_UNSUPPORTED | A requested setting is not possible on this device with the current build configuration. |
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. This function calls: transfer_api_t::open
- Note
- This function is reentrant.
◆ R_SPI_Read()
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. |
◆ R_SPI_Write()
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. |
◆ R_SPI_WriteRead()
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. |
◆ R_SPI_CallbackSet()
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. |
◆ R_SPI_Close()
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_SPI_CalculateBitrate()
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] | 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 not achievable |