SPI Communication Device (rm_comms_spi)

Functions
fsp_err_t	RM_COMMS_SPI_Open (rm_comms_ctrl_t *const p_api_ctrl, rm_comms_cfg_t const *const p_cfg)
	Opens and configures the SPI Comms module. Implements rm_comms_api_t::open. More...
fsp_err_t	RM_COMMS_SPI_Close (rm_comms_ctrl_t *const p_api_ctrl)
	Disables specified SPI Comms module. Implements rm_comms_api_t::close. More...
fsp_err_t	RM_COMMS_SPI_CallbackSet (rm_comms_ctrl_t *const p_api_ctrl, void(*p_callback)(rm_comms_callback_args_t *), void const *const p_context)
	Updates the SPI Comms callback. Implements rm_comms_api_t::callbackSet. More...
fsp_err_t	RM_COMMS_SPI_Read (rm_comms_ctrl_t *const p_api_ctrl, uint8_t *const p_dest, uint32_t const bytes)
	Performs a read from the SPI bus. Implements rm_comms_api_t::read. More...
fsp_err_t	RM_COMMS_SPI_Write (rm_comms_ctrl_t *const p_api_ctrl, uint8_t *const p_src, uint32_t const bytes)
	Performs a write to the SPI bus. Implements rm_comms_api_t::write. More...
fsp_err_t	RM_COMMS_SPI_WriteRead (rm_comms_ctrl_t *const p_api_ctrl, rm_comms_write_read_params_t const write_read_params)
	Performs simultaneous read and write. Implements rm_comms_api_t::writeRead.. More...
void	rm_comms_spi_callback (spi_callback_args_t *p_args)
	Common callback function called in the SPI driver callback function.

Detailed Description

Middleware to implement a generic communications interface over SPI. This module implements the Communicatons Middleware Interface.

Overview

The RM_COMMS_SPI module implements COMMS API for SPI interface.

Features

The implementation of the SPI communications interface has the following key features:

• Read data from SPI bus
• Write data to SPI bus
• Simultaneously read from and write to SPI bus
• Support slave select and multiple slaves

Configuration

Build Time Configurations for rm_comms_spi

The following build time configurations are defined in fsp_cfg/rm_comms_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.
Auto Slave Select	Enabled Disabled	Disabled	if selected slave select pin will be configured by module instance.

Configurations for Connectivity > SPI Shared Bus (rm_comms_spi)

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

Configuration	Options	Default	Description
Name	Name must be a valid C symbol	g_comms_spi_bus0	Module name.
Bus Timeout	Value must be a non-negative integer less than or equal to 0xFFFFFFFF	0xFFFFFFFF	Set timeout for locking bus in using RTOS.
Semaphore for Blocking (RTOS only)	Unuse Use	Use	Set Semaphore for blocking in using RTOS.
Recursive Mutex for Bus (RTOS only)	Unuse Use	Use	Set Mutex for locking bus in using RTOS.

Configurations for Connectivity > SPI Communication Device (rm_comms_spi)

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

Configuration	Options	Default	Description
Name	Name must be a valid C symbol	g_comms_spi_device0	Module name.
SSL Port Number	Refer to the RA Configuration tool for available options.	Disabled	GPIO output port number to select slave device.
SSL Pin Number	Refer to the RA Configuration tool for available options.	Disabled	GPIO output pin number to select slave device.
SSL Next Access Delay (Microseconds)	Value must be a non-negative integer	1	SSL next access delay.
Slave Select Polarity	Active Low Active High	Active Low	Select the slave select active level.
Semaphore Timeout (RTOS only)	Value must be a non-negative integer less than or equal to 0xFFFFFFFF	0xFFFFFFFF	Set timeout for blocking in using RTOS.
Callback	Name must be a valid C symbol	NULL	A user callback function can be provided.

Pin Configuration

A GPIO can be configured for slave select.

Usage Notes

If an RTOS is used, blocking and bus lock is available via SPI shared bus. Bus lock is only available when blocking is used.

Limitations

• Only 8-bit data width is supported
• RM_COMMS_API are not reentrant in non blocking mode
• When in blocking mode, RM_COMMS_SPI_Write(), RM_COMMS_SPI_Read() and RM_COMMS_SPI_WriteRead() cannot be called in callback.
• COMMS SPI devices on the same SPI bus must sit on the same SPI shared bus.

Examples

Basic Example

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

void rm_comms_spi_basic_example (void)
{
    fsp_err_t err = FSP_SUCCESS;


    err = RM_COMMS_SPI_Open(&g_comms_spi_ctrl, &g_comms_spi_cfg);
    if (FSP_SUCCESS != err)
    {
        /* Handle any errors. */
    }


    while (true)
    {
        /* Send data. */
        g_error     = 0;
        g_completed = 0;


        err = RM_COMMS_SPI_Write(&g_comms_spi_ctrl, g_tx_buf, TX_BUF_LEN);
        if (FSP_SUCCESS != err)
        {
            /* Handle any errors. */
        }


        while ((0 == g_completed) && (0 == g_error))
        {
            /* Wait callback */
        }

        /* Receive data. */
        g_error     = 0;
        g_completed = 0;

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


        err = RM_COMMS_SPI_Read(&g_comms_spi_ctrl, g_rx_buf, RX_BUF_LEN);
        if (FSP_SUCCESS != err)
        {
            /* Handle any errors.*/
        }


        while ((0 == g_completed) && (0 == g_error))
        {
            /* Wait callback */
        }
    }
}

static void rm_comms_user_callback (rm_comms_callback_args_t * p_args)
{
    if (p_args->event == RM_COMMS_EVENT_OPERATION_COMPLETE)
    {
        g_completed = 1;
    }
    else
    {
        g_error = 1;
    }
}

Data Structures
struct	rm_comms_spi_instance_ctrl_t

---

Data Structure Documentation

rm_comms_spi_instance_ctrl_t

struct rm_comms_spi_instance_ctrl_t

Communications middleware control structure.

Data Fields
uint32_t	open
	Open flag.
rm_comms_cfg_t const *	p_cfg
	Middleware configuration.
rm_comms_spi_bus_extended_cfg_t *	p_bus
	Pointer to extended configuration structure.
rm_comms_spi_device_extended_cfg_t *	p_device
	Pointer to device specific settings (lower level configuration structure)
void(*	p_callback )(rm_comms_callback_args_t *p_args)
	Pointer to callback that is called when a spi_event_t occurs.
void const *	p_context
	Pointer to context passed into callback function.

Function Documentation

RM_COMMS_SPI_Open()

fsp_err_t RM_COMMS_SPI_Open	(	rm_comms_ctrl_t *const	p_api_ctrl,
		rm_comms_cfg_t const *const	p_cfg
	)

Opens and configures the SPI Comms module. Implements rm_comms_api_t::open.

Return values

FSP_SUCCESS	SPI Comms module successfully configured.
FSP_ERR_ASSERTION	Null pointer, or one or more configuration options is invalid.
FSP_ERR_ALREADY_OPEN	Module is already open. This module can only be opened once.

Returns

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

RM_COMMS_SPI_Close()

fsp_err_t RM_COMMS_SPI_Close

(

rm_comms_ctrl_t *const

p_api_ctrl

)

Disables specified SPI Comms module. Implements rm_comms_api_t::close.

Return values

FSP_SUCCESS	Successfully closed.
FSP_ERR_ASSERTION	Null pointer passed as a parameter.
FSP_ERR_NOT_OPEN	Module is not open.

Returns

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

RM_COMMS_SPI_CallbackSet()

fsp_err_t RM_COMMS_SPI_CallbackSet	(	rm_comms_ctrl_t *const	p_api_ctrl,
		void(*)(rm_comms_callback_args_t *)	p_callback,
		void const *const	p_context
	)

Updates the SPI Comms callback. Implements rm_comms_api_t::callbackSet.

Return values

FSP_SUCCESS	Successfully set.
FSP_ERR_ASSERTION	Null pointer passed as a parameter.
FSP_ERR_NOT_OPEN	Module is not open.

RM_COMMS_SPI_Read()

fsp_err_t RM_COMMS_SPI_Read	(	rm_comms_ctrl_t *const	p_api_ctrl,
		uint8_t *const	p_dest,
		uint32_t const	bytes
	)

Performs a read from the SPI bus. Implements rm_comms_api_t::read.

Return values

FSP_SUCCESS	Successfully data decoded.
FSP_ERR_ASSERTION	Null pointer passed as a parameter.
FSP_ERR_NOT_OPEN	Module is not open.

Returns

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

RM_COMMS_SPI_Write()

fsp_err_t RM_COMMS_SPI_Write	(	rm_comms_ctrl_t *const	p_api_ctrl,
		uint8_t *const	p_src,
		uint32_t const	bytes
	)

Performs a write to the SPI bus. Implements rm_comms_api_t::write.

Return values

FSP_SUCCESS	Successfully writing data .
FSP_ERR_ASSERTION	Null pointer passed as a parameter.
FSP_ERR_NOT_OPEN	Module is not open.

Returns

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

RM_COMMS_SPI_WriteRead()

fsp_err_t RM_COMMS_SPI_WriteRead	(	rm_comms_ctrl_t *const	p_api_ctrl,
		rm_comms_write_read_params_t const	write_read_params
	)

Performs simultaneous read and write. Implements rm_comms_api_t::writeRead..

Return values

FSP_SUCCESS	Transfer was started successfully.
FSP_ERR_ASSERTION	Null pointer passed as a parameter.
FSP_ERR_NOT_OPEN	Module is not open.
FSP_ERR_INVALID_ARGUMENT	Read bytes and write bytes are not the same.

Returns

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