SPI Interface

SPI Platform interface

SPI Overview

The Serial Peripheral Interface (SPI) is a widely-used synchronous serial communication protocol that facilitates high-speed data exchange between a master device and one or more slave devices. It is commonly employed in embedded systems to connect microcontrollers, sensors, displays, memory devices, and other peripherals.

An SPI interface operates in a master-slave architecture, where the master controls the communication and provides the clock signal. The protocol is simple, efficient, and highly configurable, making it ideal for applications requiring fast and reliable data transfer.

Supported Communication Modes

The following modes of spi communication are supported:

  • Blocking - Here the read/write register function waits(blocked) till the operation is performed or time out

  • Non-Blocking - The read/write register function returns immediately and the registered callback is invoked after the completion of operation or time out

SPI Role Operation

The role operation for SPI determines whether a device operates as the Master or Slave in the SPI communication setup. The role defines how the device behaves in terms of generating the clock signal and controlling data flow during communication.

Further all the transfer counts will be in bits(rather than bytes) as there are many devices that will need it. Each SPI port+ChipSel will be created as a separate handle each.

Application Interface

Users can directly call the API’s though most of them will be called by device drivers.

The below table captures the functions that are to be called from the application layer.

API Functions

Function

Description

rs_spi_open

To open the SPI interface.

rs_spi_set_config

To configure the SPI interface.

rs_spi_master_transfer

To performs transfers over SPI master mode.

rs_spi_master_write_reg8

To transfer given number of bits

rs_spi_master_read_reg8

To receive given number of bits

rs_spi_master_set_chip_select

To sets the chip select signal as given

rs_spi_register_callback

To registers the given callback function for completion of SPI transfer operation

rs_spi_close

To close the SPI interface.

Error Code

  • Every API’s for the SPI returns some success or failure values. Please refer below section,

Implementation Guide

This section explains how to implement the SPI interface using the RAPIDSEA stack, the steps to be followed are

  • Configure the preferred method of RX or TX communication(Blocking / Non-Blocking)

  • Configure the SPI interface(port, chip select control, direction, mode, bit rate, mode, role, datasize).

  • Then call the open call of the SPI interface.

  • Register the callback function.

  • Perform the read and write register functions as required and handle the error codes.

  • Close the SPI interface.

Documentation from the relevant header as follows:

SPI Specific APIs.

Defines macros and functions specific to SPI functionality

Author

Embien RAPIDSEA Team

Copyright

Embien Technologies India Pvt. Ltd.

Defines

RS_SPI_CHIP_SELECT_NUM_0

Chip select.

Chip Select 0

RS_SPI_CHIP_SELECT_NUM_1

Chip Select 1.

RS_SPI_CHIP_SELECT_NUM_2

Chip Select 2.

RS_SPI_CHIP_SELECT_NUM_3

Chip Select 3.

RS_SPI_CHIP_SELECT_ACTIVE_LOW

Chip select control.

Chip Select is active low signal

RS_SPI_CHIP_SELECT_ACTIVE_HIGH

Chip Select is active high signal.

RS_SPI_CHIP_SELECT_MANUAL

Chip Select is handled by high level module.

RS_SPI_ROLE_MASTER

Operation role.

Master mode operation

RS_SPI_ROLE_SLAVE

Slave mode operation.

RS_SPI_MODE_0

Operation mode.

Mode 0 operation

RS_SPI_MODE_1

Mode 1 operation.

RS_SPI_MODE_2

Mode 2 operation.

RS_SPI_MODE_3

Mode 3 operation.

RS_SPI_BLOCKING

Operation mode.

Blocking Mode operation

RS_SPI_NON_BLOCKING

Non-Blocking Mode operation.

RS_SPI_MSB_DIRECTION

direction of the data to be transmitted

MSB mode - left most data is transmitted first

RS_SPI_LSB_DIRECTION

LSB mode - right most data is transmitted first.

RS_SPI_DATA4BITS

width of the data

4 Databits

RS_SPI_DATA5BITS

5 Databits

RS_SPI_DATA6BITS

6 Databits

RS_SPI_DATA7BITS

7 Databits

RS_SPI_DATA8BITS

8 Databits

Typedefs

typedef void (*rs_spi_callback_completion)(rs_handle_t handle, rs_ret_val_t result)

callback function-pointer

Callback function format.

This callback function is called on completion of given activity

Param handle:

[in] - Handle to the SPI interface

Param result:

[in] - Result of the last operation requested in non-blocking mode

Return:

None

typedef struct tag_rs_spi_config rs_spi_config_t

Structure for configuring the SPI config.

typedef struct tag_rs_spi_instance rs_spi_instance_t

Structure for configuring the SPI interface.

Functions

rs_handle_t rs_spi_open(rs_spi_instance_t *ptr_instance, rs_spi_config_t *ptr_config)

Configures the SPI port.

This function configures/re-configures the SPI port as per the given configuration

Parameters:

  • ptr_instance – [in] - pointer to the instance structure

  • ptr_config – [in] - Pointer to the configuration structure

Returns:

0 on success or error code on failure

rs_ret_val_t rs_spi_set_config(rs_spi_config_t *ptr_config, uint8_t u8_port, uint8_t u8_cs_ctrl, uint8_t u8_chip_sel_num, uint8_t u8_role, uint8_t u8_mode, uint8_t u8_non_blocking, uint32_t u32_bit_rate, uint8_t u8_datasize, uint8_t u8_direction)

Configures the SPI port.

This function configures/re-configures the SPI port as per the given configuration

Parameters:

  • ptr_config – [in] - Pointer to the configuration structure

  • u8_port – [in] - SPI port

  • u8_cs_ctrl – [in] -

  • u8_chip_sel_num – [in] - Slave select Number

  • u8_role – [in] - Role of the SPI port

  • u8_mode – [in] - operation mode

  • u8_non_blocking – [in] - Blocking or non-blocking

  • u32_bit_rate – [in] - Bit rate

  • u8_datasize – [in] - size of the data in bits

  • u8_direction – [in] - MSB or LSB

Returns:

0 on success or error code on failure

rs_ret_val_t rs_spi_master_transfer(rs_handle_t handle, void *ptr_tx_data, void *ptr_rx_data, uint32_t u32_num_bits)

Performs transfers over SPI master mode.

This function transfer the given data both ways simultaneously for given number of bits

Parameters:

  • handle – [in] - Handle to the SPI interface

  • ptr_tx_data – [in] - Pointer to transmit buffer. Can be NULL if no transmission is needed.

  • ptr_rx_data – [out] - Pointer to receive buffer. Can be NULL if no reception is needed.

  • u32_num_bits – [in] - Number of bits to be transmitted

Returns:

0 on success or error code on failure

rs_ret_val_t rs_spi_master_write_reg8(rs_handle_t handle, void *ptr_tx_data, uint32_t u32_num_bits, uint32_t u32_time_out)

Convenience function to transfer given number of bits.

This function sends the register address followed by given number of bits

Parameters:

  • handle – [in] - Handle to the SPI interface

  • ptr_tx_data – [in] - Pointer to transmit buffer

  • u32_num_bits – [in] - Number of bits to be transmitted

  • u32_time_out – [in] - u32_time_out - Time out in ms to wait for transfer complete

Returns:

0 on success or error code on failure

rs_ret_val_t rs_spi_master_write_reg16(rs_handle_t handle, void *ptr_tx_data, uint32_t u32_num_bits, uint32_t u32_time_out)

Convenience function to transfer given number of bits.

This function sends the given number of bits

Parameters:

  • handle – [in] - Handle to the SPI interface

  • ptr_tx_data – [in] - Pointer to transmit buffer

  • u32_num_bits – [in] - Number of bits to be transmitted

  • u32_time_out – [in] - u32_time_out - Time out in ms to wait for transfer complete

Returns:

0 on success or error code on failure

rs_ret_val_t rs_spi_master_read_reg8(rs_handle_t handle, void *ptr_rx_data, uint32_t u32_num_bits, uint32_t u32_time_out)

Convenience function to receive given number of bits.

This function reads given number of bits

Parameters:

  • handle – [in] - Handle to the SPI interface

  • ptr_rx_data – [out] - Pointer to receive buffer

  • u32_num_bits – [in] - Number of bits to be received

  • u32_time_out – [in] - u32_time_out - Time out in ms to wait for transfer complete

Returns:

0 on success or error code on failure

rs_ret_val_t rs_spi_master_read_reg16(rs_handle_t handle, void *ptr_rx_data, uint32_t u32_num_bits, uint32_t u32_time_out)

Convenience function to receive given number of bits.

This function reads given number of bits

Parameters:

  • handle – [in] - Handle to the SPI interface

  • ptr_rx_data – [out] - Pointer to receive buffer

  • u32_num_bits – [in] - Number of bits to be received

  • u32_time_out – [in] - u32_time_out - Time out in ms to wait for transfer complete

Returns:

0 on success or error code on failure

rs_ret_val_t rs_spi_master_set_chip_select(rs_handle_t handle, uint8_t u8_level)

Sets the chip select signal as given.

This function drives the chip select signal as requested

Parameters:

  • handle – [in] - Handle to the SPI interface

  • u8_level – [in] - Signal level to drive to

Returns:

0 on success or error code on failure

rs_ret_val_t rs_spi_register_callback(rs_handle_t handle, rs_spi_callback_completion ptr_func)

Registers the given callback function for completion of SPI transfer operation.

This function registers the given callback function for completion of transfer operation

Parameters:

  • handle – [in] - Handle to the SPI interface

  • ptr_func – [in] - Callback function to call to

Returns:

0 on success or error code on failure

rs_ret_val_t rs_spi_close(rs_handle_t handle)

Un-initializes the SPI interface.

This function un-initializes the SPI interface and releases the handle

Parameters:

handle – [in] - Handle to the SPI interface

Returns:

0 on success or error code on failure

rs_ret_val_t rs_spi_set_bitrate(rs_handle_t handle, uint32_t u32_bit_rate)

Update bit rate for spi.

This function updates the spi bit rate.

Parameters:

  • handle – [in] - Handle to the SPI interface

  • u32_bit_rate – [in] - bit rate to change

Returns:

0 on success or error code on failure

struct tag_rs_spi_config
#include <rs_spi.h>

Structure for configuring the SPI config.

Public Members

uint8_t port

Index to SPI Port.

uint8_t chip_sel_num

Chip select signal associated with this port.

uint8_t chip_sel_ctrl

Chip select control.

uint8_t role

Master or Slave operation.

uint8_t mode

Mode of operation.

uint8_t non_blocking

Blocking vs Non-blocking.

uint8_t data_order

MSB vs LSB.

uint8_t chip_sel_polarity

CS polarity for SPI port.

uint8_t clock_polarity

clock polarity

uint8_t clock_phase

Clock phase - First edge vs Second.

uint8_t data_width

Width of the data.

uint32_t bit_rate

Baud rate/Clock speed.

struct tag_rs_spi_instance
#include <rs_spi.h>

Structure for configuring the SPI interface.

Public Members

rs_spi_config_t *ptr_config

Pointer to the SPI configuration.

uint16_t num_tx_buffers

Number of transmit buffers to be allocated.

uint16_t num_rx_buffers

Number of receive buffers to be allocated.

uint32_t *ptr_rx_buffers

Pointer to Rx buffer.

uint32_t configFlags

Additional option to control transfer.

uint32_t *ptr_tx_buffers

TX buffer.

uint32_t tx_exp_buf_len

Expected TX Buffer length.

uint32_t txed_buf_len

TXed Buffer length.

uint32_t tx_timeout_time

Last received char time.

rs_spi_callback_completion ptr_cb

Pointer to callback function.

rs_fevent_t fevent_transfer_complete

Transfer Complete Event.