SPI (Serial Peripheral Interface)

General Description

High level interface for interacting with the Serial Peripheral Interface (SPI).

The SPI protocol is a synchronous serial interface protocol. Devices operate in either master or slave mode. The master initiates the data transfer.

Motorola SPI modes 0, 1, 2, and 3 are supported, with either MSB or LSB first. The operating mode and data frame size can be configured via cyhal_spi_cfg_t.

Features

• Supports master and slave functionality.
• Supports Motorola modes - 0, 1, 2 and 3 - cyhal_spi_mode_t
• MSb or LSb first shift direction - cyhal_spi_mode_t
• Master supports up to four slave select lines
• Supports data frame size of 8 or 16 bits
• Configurable interrupt and callback assignment on SPI events: Data transfer to FIFO complete, Transfer complete and Transmission error - cyhal_spi_event_t
• Supports changing baud rate of the transaction in run time.
• Provides functions to send/receive a single byte or block of data.

Quick Start

Initialise a SPI master or slave interface using cyhal_spi_init() and provide the SPI pins (mosi, miso, sclk, ssel), number of bits per frame (data_bits) and SPI Motorola mode. The data rate can be set using cyhal_spi_set_frequency().
See Code snippets for code snippets to send or receive the data.

Code snippets

Snippet 1: SPI Master - Single byte transfer operation (Read and Write)

The following code snippet initializes an SPI Master interface using the cyhal_spi_init(). The data rate of transfer is set using cyhal_spi_set_frequency(). The code snippet shows how to transfer a single byte of data using cyhal_spi_send() and cyhal_spi_recv().

    cy_rslt_t rslt;
    cyhal_spi_t mSPI;
    uint32_t spi_master_frequency = 1000000;
    uint32_t transmit_data = 0x01;
    uint32_t receive_data;

    /* Configuring the  SPI master:  Specify the SPI interface pins, frame size, SPI Motorola mode and master mode */
    rslt = cyhal_spi_init(&mSPI, CYBSP_SPI_MOSI, CYBSP_SPI_MISO, CYBSP_SPI_CLK, CYBSP_SPI_CS, NULL, 8, CYHAL_SPI_MODE_00_MSB, false);

    /* Set the data rate to 1 Mbps */
    rslt = cyhal_spi_set_frequency(&mSPI, spi_master_frequency);

    /* Transfer one byte of data to the slave. */
    if (CY_RSLT_SUCCESS == cyhal_spi_send(&mSPI, transmit_data))
    {
    /* Receives one byte of data from the slave by transmiting a dummy byte 0xFF. */
        if (CY_RSLT_SUCCESS == cyhal_spi_recv(&mSPI, &receive_data))
        {
            /* Transfer Complete and successful */
        }
    }

Snippet 2: SPI Slave - Single byte transfer operation (Read and Write)

The following code snippet initializes an SPI Slave interface using the cyhal_spi_init(). The data rate of transfer is set using cyhal_spi_set_frequency. The code snippet shows how to transfer a single byte of data using cyhal_spi_send() and cyhal_spi_recv.

    cy_rslt_t rslt;
    cyhal_spi_t sSPI;
    uint32_t spi_slave_frequency = 1000000;
    uint32_t transmit_data = 1;
    uint32_t receive_data;

    /* Configuring the  SPI slave:  Specify the SPI interface pins, frame size, SPI Motorola mode and slave mode */
    rslt = cyhal_spi_init(&sSPI, CYBSP_SPI_MOSI, CYBSP_SPI_MISO, CYBSP_SPI_CLK, CYBSP_SPI_CS, NULL, 8, CYHAL_SPI_MODE_00_MSB, true);

    /* Set the data rate to 1 Mbps */
    rslt = cyhal_spi_set_frequency(&sSPI, spi_slave_frequency);

    /* Place a byte in the TX FIFO to be read by the master */
    if (CY_RSLT_SUCCESS == cyhal_spi_send(&sSPI, transmit_data))
    {
        /* Get a received value out of the SPI receive buffer. This API Blocks until a value is available */
        if (CY_RSLT_SUCCESS == cyhal_spi_recv(&sSPI, &receive_data))
        {
            /* Transfer successful */
        }
    }

Snippet 3: SPI Block Data transfer

The following snippet sends and receives an array of data in a single SPI transaction using cyhal_spi_transfer(). The example uses SPI master to transmit 5 bytes of data and receive 5 bytes of data in a single transaction.

    cy_rslt_t rslt;
    cyhal_spi_t mSPI;
    uint32_t spi_frequency = 1000000;
    uint8_t transmit_data[5] = {0x1, 0x2, 0x3, 0x4, 0x5};
    uint8_t receive_data[5];

    /* BSP-1637 workaround  */
    memset(&mSPI, 0, sizeof(mSPI));

    /* Configuring the  SPI interface:  Specify the SPI interface pins, frame size, SPI Motorola mode and master/slave mode */
    rslt = cyhal_spi_init(&mSPI, CYBSP_SPI_MOSI, CYBSP_SPI_MISO, CYBSP_SPI_CLK, CYBSP_SPI_CS, NULL, 8, CYHAL_SPI_MODE_00_MSB, false);

    /* Set the data rate to 1 Mbps */
    rslt = cyhal_spi_set_frequency(&mSPI, spi_frequency);

    /* Master: Starts a data transfer. Slave: Prepares the slave for data transfer. It is a blocking function */
    if (CY_RSLT_SUCCESS ==  cyhal_spi_transfer(&mSPI, transmit_data, 5u, receive_data, 5u, 0xFF))
    {
        /* Transfer Complete */
    }

Snippet 4: Interrupts on SPI events

SPI interrupt events ( cyhal_spi_event_t) can be mapped to an interrupt and assigned to a callback function. The callback function needs to be first registered and then the event needs to be enabled. The following snippet initialises a SPI master to perform a block transfer using cyhal_spi_transfer_async(). This is a non-blocking function. A callback function is registered using cyhal_spi_register_callback to notify whenever the SPI transfer is complete.

void spi_interrupt_callback(void *arg, cyhal_spi_event_t event)
{
    (void)arg;
    if ((event & CYHAL_SPI_IRQ_DONE ) != 0u)
    {
        /* Transmission is complete. Handle Event */
    }
}

void snippet_cyhal_interrupt_callback_events(void)
{
    cy_rslt_t rslt;
    cyhal_spi_t mSPI;
    uint32_t spi_frequency = 1000000;
    uint32_t rx_transfer_count = 5, tx_transfer_count = 5;
    uint8_t receive_data[5];
    uint8_t transmit_data[5] = {0x1, 0x2, 0x3, 0x4, 0x5};

    /* Configuring the  SPI interface:  Specify the SPI interface pins, frame size, SPI Motorola mode and master/slave mode */
    rslt = cyhal_spi_init(&mSPI, CYBSP_SPI_MOSI, CYBSP_SPI_MISO, CYBSP_SPI_CLK, CYBSP_SPI_CS, NULL, 8, CYHAL_SPI_MODE_00_MSB, false);
    CY_ASSERT(CY_RSLT_SUCCESS == rslt);

    /* Set the data rate to 1 Mbps */
    rslt = cyhal_spi_set_frequency(&mSPI, spi_frequency);
    CY_ASSERT(CY_RSLT_SUCCESS == rslt);

    /* Register a callback function to be called when the interrupt fires */
    cyhal_spi_register_callback(&mSPI, (cyhal_spi_event_callback_t) spi_interrupt_callback, NULL);

    /* Enable the events that will trigger the call back function */
    cyhal_spi_enable_event(&mSPI, CYHAL_SPI_IRQ_DONE, 3, true);

    /* Master: Initiates a data transfer. Slave: Prepares the slave for data transfer. It is a non-blocking function  */
    if (CY_RSLT_SUCCESS == cyhal_spi_transfer_async(&mSPI, transmit_data, rx_transfer_count, receive_data, tx_transfer_count))
    {
        /* SPI Master: Transfer started. SPI Slave: Prepares for data transfer */
    }
}

More Information

• mtb-example-psoc6-spi-master: This example project demonstrates use of SPI (HAL) resource in PSoC® 6 MCU in Master mode to write data to an SPI slave.

API Reference
	SPI HAL Results
	SPI specific return codes.

Data Structures
struct	cyhal_spi_cfg_t
	Initial SPI configuration. More...

Macros
#define	cyhal_spi_frequency   cyhal_spi_set_frequency
	Compatibility define for cyhal_spi_set_frequency. More...
#define	CYHAL_SPI_MODE_FLAG_LSB   (0x01u)
	Flag for SPI cyhal_spi_mode_t values indicating that the LSB is sent first. More...
#define	CYHAL_SPI_MODE_FLAG_CPHA   (0x02u)
	Flag for SPI cyhal_spi_mode_t values indicating that the CPHA=1. More...
#define	CYHAL_SPI_MODE_FLAG_CPOL   (0x04u)
	Flag for SPI cyhal_spi_mode_t values indicating that the CPOL=1. More...
#define	CYHAL_SPI_MODE(cpol, cpha, lsb)
	Creates a cyhal_spi_mode_t value given the cpol, cpha, lsb values. More...

Typedefs
typedef void(*	cyhal_spi_event_callback_t) (void *callback_arg, cyhal_spi_event_t event)
	Handler for SPI interrupts.

Enumerations
enum	cyhal_spi_event_t {   CYHAL_SPI_IRQ_DATA_IN_FIFO = 1 << 1,   CYHAL_SPI_IRQ_DONE = 1 << 2,   CYHAL_SPI_IRQ_ERROR = 1 << 3 }
	SPI interrupt triggers. More...
enum	cyhal_spi_ssel_polarity_t {   CYHAL_SPI_SSEL_ACTIVE_LOW = 0,   CYHAL_SPI_SSEL_ACTIVE_HIGH = 1 }
	SPI Slave Select polarity. More...
enum	cyhal_spi_mode_t {   CYHAL_SPI_MODE_00_MSB = CYHAL_SPI_MODE(0, 0, 0),   CYHAL_SPI_MODE_00_LSB = CYHAL_SPI_MODE(0, 0, 1),   CYHAL_SPI_MODE_01_MSB = CYHAL_SPI_MODE(0, 1, 0),   CYHAL_SPI_MODE_01_LSB = CYHAL_SPI_MODE(0, 1, 1),   CYHAL_SPI_MODE_10_MSB = CYHAL_SPI_MODE(1, 0, 0),   CYHAL_SPI_MODE_10_LSB = CYHAL_SPI_MODE(1, 0, 1),   CYHAL_SPI_MODE_11_MSB = CYHAL_SPI_MODE(1, 1, 0),   CYHAL_SPI_MODE_11_LSB = CYHAL_SPI_MODE(1, 1, 1) }
	SPI operating modes. More...

Functions
cy_rslt_t	cyhal_spi_init (cyhal_spi_t *obj, cyhal_gpio_t mosi, cyhal_gpio_t miso, cyhal_gpio_t sclk, cyhal_gpio_t ssel, const cyhal_clock_t *clk, uint8_t bits, cyhal_spi_mode_t mode, bool is_slave)
	Initialize the SPI peripheral. More...
void	cyhal_spi_free (cyhal_spi_t *obj)
	Release a SPI object. More...
cy_rslt_t	cyhal_spi_set_frequency (cyhal_spi_t *obj, uint32_t hz)
	Set the SPI baud rate. More...
cy_rslt_t	cyhal_spi_slave_select_config (cyhal_spi_t *obj, cyhal_gpio_t ssel, cyhal_spi_ssel_polarity_t polarity)
	Configures provided ssel pin to work as SPI slave select with specified polarity. More...
cy_rslt_t	cyhal_spi_select_active_ssel (cyhal_spi_t *obj, cyhal_gpio_t ssel)
	Selects an active slave select line from one of available. More...
cy_rslt_t	cyhal_spi_recv (cyhal_spi_t *obj, uint32_t *value)
	Synchronously get a received value out of the SPI receive buffer. More...
cy_rslt_t	cyhal_spi_send (cyhal_spi_t *obj, uint32_t value)
	Synchronously send a byte out. More...
cy_rslt_t	cyhal_spi_transfer (cyhal_spi_t *obj, const uint8_t *tx, size_t tx_length, uint8_t *rx, size_t rx_length, uint8_t write_fill)
	Synchronously Write a block out and receive a value. More...
cy_rslt_t	cyhal_spi_transfer_async (cyhal_spi_t *obj, const uint8_t *tx, size_t tx_length, uint8_t *rx, size_t rx_length)
	Start an asynchronous SPI transfer. More...
bool	cyhal_spi_is_busy (cyhal_spi_t *obj)
	Checks if the specified SPI peripheral is in use. More...
cy_rslt_t	cyhal_spi_abort_async (cyhal_spi_t *obj)
	Abort an SPI transfer. More...
void	cyhal_spi_register_callback (cyhal_spi_t *obj, cyhal_spi_event_callback_t callback, void *callback_arg)
	Register a SPI callback handler. More...
void	cyhal_spi_enable_event (cyhal_spi_t *obj, cyhal_spi_event_t event, uint8_t intr_priority, bool enable)
	Configure SPI interrupt. More...

---

Data Structure Documentation

cyhal_spi_cfg_t

struct cyhal_spi_cfg_t

Data Fields
cyhal_spi_mode_t	mode	The operating mode.
uint8_t	data_bits	The number of bits per transfer.
bool	is_slave	Whether the peripheral is operating as slave or master.

Macro Definition Documentation

cyhal_spi_frequency

#define cyhal_spi_frequency   cyhal_spi_set_frequency

Compatibility define for cyhal_spi_set_frequency.

CYHAL_SPI_MODE_FLAG_LSB

#define CYHAL_SPI_MODE_FLAG_LSB   (0x01u)

Flag for SPI cyhal_spi_mode_t values indicating that the LSB is sent first.

CYHAL_SPI_MODE_FLAG_CPHA

#define CYHAL_SPI_MODE_FLAG_CPHA   (0x02u)

Flag for SPI cyhal_spi_mode_t values indicating that the CPHA=1.

CYHAL_SPI_MODE_FLAG_CPOL

#define CYHAL_SPI_MODE_FLAG_CPOL   (0x04u)

Flag for SPI cyhal_spi_mode_t values indicating that the CPOL=1.

CYHAL_SPI_MODE

#define CYHAL_SPI_MODE	(		cpol,
			cpha,
			lsb
	)

Value:

(((cpol > 0) ? CYHAL_SPI_MODE_FLAG_CPOL : 0) | \
                                             ((cpha > 0) ? CYHAL_SPI_MODE_FLAG_CPHA : 0) | \
                                             (( lsb > 0) ? CYHAL_SPI_MODE_FLAG_LSB  : 0))

Creates a cyhal_spi_mode_t value given the cpol, cpha, lsb values.

Enumeration Type Documentation

cyhal_spi_event_t

enum cyhal_spi_event_t

SPI interrupt triggers.

Enumerator
CYHAL_SPI_IRQ_DATA_IN_FIFO	All transfer data has been moved into data FIFO.
CYHAL_SPI_IRQ_DONE	Transfer complete.
CYHAL_SPI_IRQ_ERROR	An error occurred while transferring data.

cyhal_spi_ssel_polarity_t

enum cyhal_spi_ssel_polarity_t

SPI Slave Select polarity.

Enumerator
CYHAL_SPI_SSEL_ACTIVE_LOW	SSEL signal is active low.
CYHAL_SPI_SSEL_ACTIVE_HIGH	SSEL signal is active high.

cyhal_spi_mode_t

enum cyhal_spi_mode_t

SPI operating modes.

Enumerator
CYHAL_SPI_MODE_00_MSB	Standard motorola SPI CPOL=0, CPHA=0 with MSB first operation.
CYHAL_SPI_MODE_00_LSB	Standard motorola SPI CPOL=0, CPHA=0 with LSB first operation.
CYHAL_SPI_MODE_01_MSB	Standard motorola SPI CPOL=0, CPHA=1 with MSB first operation.
CYHAL_SPI_MODE_01_LSB	Standard motorola SPI CPOL=0, CPHA=1 with LSB first operation.
CYHAL_SPI_MODE_10_MSB	Standard motorola SPI CPOL=1, CPHA=0 with MSB first operation.
CYHAL_SPI_MODE_10_LSB	Standard motorola SPI CPOL=1, CPHA=0 with LSB first operation.
CYHAL_SPI_MODE_11_MSB	Standard motorola SPI CPOL=1, CPHA=1 with MSB first operation.
CYHAL_SPI_MODE_11_LSB	Standard motorola SPI CPOL=1, CPHA=1 with LSB first operation.

Function Documentation

cyhal_spi_init()

cy_rslt_t cyhal_spi_init	(	cyhal_spi_t *	obj,
		cyhal_gpio_t	mosi,
		cyhal_gpio_t	miso,
		cyhal_gpio_t	sclk,
		cyhal_gpio_t	ssel,
		const cyhal_clock_t *	clk,
		uint8_t	bits,
		cyhal_spi_mode_t	mode,
		bool	is_slave
	)

Initialize the SPI peripheral.

Configures the pins used by SPI, sets a default format and frequency, and enables the peripheral

Parameters

[out]	obj	Pointer to a SPI object. The caller must allocate the memory for this object but the init function will initialize its contents.
[in]	mosi	The pin to use for MOSI

Note

At least MOSI or MISO pin should be non-NC

Parameters

[in]

miso

The pin to use for MISO

Note

At least MOSI or MISO pin should be non-NC

Parameters

[in]

sclk

The pin to use for SCLK

Note

This pin cannot be NC

Parameters

[in]

ssel

The pin to use for SSEL

Note

Provided pin will be configured for CYHAL_SPI_SSEL_ACTIVE_LOW polarity and set as active. This can be changed (as well as additional ssel pins can be added) by cyhal_spi_slave_select_config and cyhal_spi_select_active_ssel functions. This pin can be NC.

Parameters

[in]	clk	The clock to use can be shared, if not provided a new clock will be allocated
[in]	bits	The number of bits per frame

Note

bits should be 8 or 16

Parameters

[in]	mode	The SPI mode (clock polarity, phase, and shift direction)
[in]	is_slave	false for master mode or true for slave mode operation

Returns

The status of the init request

cyhal_spi_free()

void cyhal_spi_free

(

cyhal_spi_t *

obj

)

Release a SPI object.

Return the peripheral, pins and clock owned by the SPI object to their reset state

Parameters

[in,out]

obj

The SPI object to deinitialize

cyhal_spi_set_frequency()

cy_rslt_t cyhal_spi_set_frequency	(	cyhal_spi_t *	obj,
		uint32_t	hz
	)

Set the SPI baud rate.

Actual frequency may differ from the desired frequency due to available dividers and bus clock Configures the SPI peripheral's baud rate

Parameters

[in,out]	obj	The SPI object to configure
[in]	hz	The baud rate in Hz

Returns

The status of the set_frequency request

cyhal_spi_slave_select_config()

cy_rslt_t cyhal_spi_slave_select_config	(	cyhal_spi_t *	obj,
		cyhal_gpio_t	ssel,
		cyhal_spi_ssel_polarity_t	polarity
	)

Configures provided ssel pin to work as SPI slave select with specified polarity.

Multiple pins can be configured as SPI slave select pins. Please refer to device datasheet for details. Switching between configured slave select pins is done by cyhal_spi_select_active_ssel function. Unless modified with this function, the SSEL pin provided as part of cyhal_spi_init is the default.

Parameters

[in]	obj	The SPI object to add slave select for
[in]	ssel	Slave select pin to be added
[in]	polarity	Polarity of slave select

Returns

The status of ssel pin configuration

cyhal_spi_select_active_ssel()

cy_rslt_t cyhal_spi_select_active_ssel	(	cyhal_spi_t *	obj,
		cyhal_gpio_t	ssel
	)

Selects an active slave select line from one of available.

This function is applicable for the master and slave. SSEL pin should be configured by cyhal_spi_slave_select_config or cyhal_spi_init functions prior to selecting it as active. The active slave select line will automatically be toggled as part of any transfer.

Parameters

[in]	obj	The SPI object for switching
[in]	ssel	Slave select pin to be set as active

Returns

CY_RSLT_SUCCESS if slave select was switched successfully, otherwise - CYHAL_SPI_RSLT_ERR_CANNOT_SWITCH_SSEL

cyhal_spi_recv()

cy_rslt_t cyhal_spi_recv	(	cyhal_spi_t *	obj,
		uint32_t *	value
	)

Synchronously get a received value out of the SPI receive buffer.

In Master mode - transmits fill-in value and read the data from RxFifo In Slave mode - Blocks until a value is available

Parameters

[in]	obj	The SPI peripheral to read
[in]	value	The value received

Returns

The status of the read request

Note

• In Master mode, MISO pin required to be non-NC for this API to operate
• In Slave mode, MOSI pin required to be non-NC for this API to operate

cyhal_spi_send()

cy_rslt_t cyhal_spi_send	(	cyhal_spi_t *	obj,
		uint32_t	value
	)

Synchronously send a byte out.

In Master mode transmits value to slave and read/drop a value from the RxFifo. In Slave mode writes a value to TxFifo

Parameters

[in]	obj	The SPI peripheral to use for sending
[in]	value	The value to send

Returns

The status of the write request

Note

• In Master mode, MOSI pin required to be non-NC for this API to operate
• In Slave mode, MISO pin required to be non-NC for this API to operate

cyhal_spi_transfer()

cy_rslt_t cyhal_spi_transfer	(	cyhal_spi_t *	obj,
		const uint8_t *	tx,
		size_t	tx_length,
		uint8_t *	rx,
		size_t	rx_length,
		uint8_t	write_fill
	)

Synchronously Write a block out and receive a value.

The total number of bytes sent and received will be the maximum of tx_length and rx_length. The bytes written will be padded (at the end) with the value given by write_fill.

This function will block for the duration of the transfer. cyhal_spi_transfer_async can be used for non-blocking transfers.

Parameters

[in]	obj	The SPI peripheral to use for sending
[in]	tx	Pointer to the byte-array of data to write to the device
[in,out]	tx_length	Number of bytes to write, updated with the number actually written
[out]	rx	Pointer to the byte-array of data to read from the device
[in,out]	rx_length	Number of bytes to read, updated with the number actually read
[in]	write_fill	Default data transmitted while performing a read

Returns

The status of the transfer request

Note

Both MOSI and MISO pins required to be non-NC for this API to operate

cyhal_spi_transfer_async()

cy_rslt_t cyhal_spi_transfer_async	(	cyhal_spi_t *	obj,
		const uint8_t *	tx,
		size_t	tx_length,
		uint8_t *	rx,
		size_t	rx_length
	)

Start an asynchronous SPI transfer.

This will transfer rx_length bytes into the buffer pointed to by rx, while simultaneously transfering tx_length bytes of data from the buffer pointed to by tx, both in the background. When the transfer is complete, the CYHAL_SPI_IRQ_DONE event will be raised. See cyhal_spi_register_callback and cyhal_spi_enable_event.

Note

For blocking transfers cyhal_spi_transfer can be used.

Parameters

[in]	obj	The SPI object that holds the transfer information
[in]	tx	The transmit buffer
[in,out]	tx_length	The number of bytes to transmit
[out]	rx	The receive buffer
[in,out]	rx_length	The number of bytes to receive

Returns

The status of the transfer_async request

Note

Both MOSI and MISO pins required to be non-NC for this API to operate

cyhal_spi_is_busy()

bool cyhal_spi_is_busy

(

cyhal_spi_t *

obj

)

Checks if the specified SPI peripheral is in use.

Parameters

[in]

obj

The SPI peripheral to check

Returns

Indication of whether the SPI is still transmitting

cyhal_spi_abort_async()

cy_rslt_t cyhal_spi_abort_async

(

cyhal_spi_t *

obj

)

Abort an SPI transfer.

Parameters

[in]

obj

The SPI peripheral to stop

Returns

The status of the abort_async request

cyhal_spi_register_callback()

void cyhal_spi_register_callback	(	cyhal_spi_t *	obj,
		cyhal_spi_event_callback_t	callback,
		void *	callback_arg
	)

Register a SPI callback handler.

This function will be called when one of the events enabled by cyhal_spi_enable_event occurs.

Parameters

[in]	obj	The SPI object
[in]	callback	The callback handler which will be invoked when the interrupt fires
[in]	callback_arg	Generic argument that will be provided to the callback when called

cyhal_spi_enable_event()

void cyhal_spi_enable_event	(	cyhal_spi_t *	obj,
		cyhal_spi_event_t	event,
		uint8_t	intr_priority,
		bool	enable
	)

Configure SPI interrupt.

This function is used for word-approach

When an enabled event occurs, the function specified by cyhal_spi_register_callback will be called.

Parameters

[in]	obj	The SPI object
[in]	event	The SPI event type
[in]	intr_priority	The priority for NVIC interrupt events
[in]	enable	True to turn on interrupts, False to turn off