SPI (SCB)¶

group group_scb_spi

Driver API for SPI Peripheral.

The functions and other declarations used in this part of the driver are in cy_scb_spi.h. You can also include cy_pdl.h to get access to all functions and declarations in the PDL.

The SPI protocol is a synchronous serial interface protocol. Devices operate in either master or slave mode. The master initiates the data transfer. The SCB supports single-master-multiple-slaves topology for SPI. Multiple slaves are supported with individual slave select lines.

Features:

Supports master and slave functionalitySupports three types of SPI protocols:
- Motorola SPI - modes 0, 1, 2, and 3
- Texas Instruments SPI, with coinciding and preceding data frame indicator - mode 1 only
- National Semiconductor (MicroWire) SPI - mode 0 only
Master supports up to four slave select lines
- Each slave select has configurable active polarity (high or low)
- Slave select can be programmed to stay active for a whole transfer, or just for each byte
Master supports late sampling for better timing margin
Master supports continuous SPI clock
Data frame size programmable from 4 bits to 16 bits
Programmable oversampling
MSb or LSb first
Median filter available for inputs

Configuration Considerations

The SPI driver configuration can be divided to number of sequential steps listed below:

Configure SPI
Assign and Configure Pins
Assign Clock Divider
Configure Data Rate
Configure Interrupt
Enable SPI

note

The SPI driver is built on top of the SCB hardware block. The SCB1 instance is used as an example for all code snippets. Modify the code to match your design.

Configure SPI

To set up the SPI driver, provide the configuration parameters in the cy_stc_scb_spi_config_t structure. For example: provide spiMode, subMode, sclkMode, oversample, rxDataWidth, and txDataWidth. The other parameters are optional for operation. To initialize the driver, call Cy_SCB_SPI_Init function providing a pointer to the populated cy_stc_scb_spi_config_t structure and the allocated cy_stc_scb_spi_context_t structure.

/* Allocate context for SPI operation */
cy_stc_scb_spi_context_t spiContext;

/* Populate configuration structure */
#if (USE_SPI_SLAVE)
    /* Slave configuration */
    cy_stc_scb_spi_config_t spiConfig =
    {
        .spiMode  = CY_SCB_SPI_SLAVE,
        .subMode  = CY_SCB_SPI_MOTOROLA,
        .sclkMode = CY_SCB_SPI_CPHA0_CPOL0,
        .oversample = 0UL, 

        .rxDataWidth              = 8UL,
        .txDataWidth              = 8UL,
        .enableMsbFirst           = false,
        .enableInputFilter        = false,
        .enableFreeRunSclk        = false,
        .enableMisoLateSample     = false,
        .enableTransferSeperation = false,
        .ssPolarity               = CY_SCB_SPI_ACTIVE_LOW,
        .enableWakeFromSleep      = false,

        .rxFifoTriggerLevel  = 0UL,
        .rxFifoIntEnableMask = 0UL,
        .txFifoTriggerLevel  = 0UL,
        .txFifoIntEnableMask = 0UL,
        .masterSlaveIntEnableMask = 0UL,
    };
#else
    /* Master configuration */
    cy_stc_scb_spi_config_t spiConfig =
    {
        .spiMode  = CY_SCB_SPI_MASTER,
        .subMode  = CY_SCB_SPI_MOTOROLA,
        .sclkMode = CY_SCB_SPI_CPHA0_CPOL0,
        .oversample = 10UL,

        .rxDataWidth              = 8UL,
        .txDataWidth              = 8UL,
        .enableMsbFirst           = false,
        .enableInputFilter        = false,
        .enableFreeRunSclk        = false,
        .enableMisoLateSample     = true,
        .enableTransferSeperation = false,
        .ssPolarity               = CY_SCB_SPI_ACTIVE_LOW,
        .enableWakeFromSleep      = false,

        .rxFifoTriggerLevel  = 0UL,
        .rxFifoIntEnableMask = 0UL,
        .txFifoTriggerLevel  = 0UL,
        .txFifoIntEnableMask = 0UL,
        .masterSlaveIntEnableMask = 0UL,
    };
#endif

/* Configure SPI to operate */
(void) Cy_SCB_SPI_Init(SCB1, &spiConfig, &spiContext);

Assign and Configure Pins

Only dedicated SCB pins can be used for SPI operation. The HSIOM register must be configured to connect dedicated SCB SPI pins to the SCB block. Also, the SPI output pins must be configured in Strong Drive Input Off mode and SPI input pins in Digital High-Z.

/* Assign pins for SPI on SCB1: P10[0], P10[1], P10[2] and P10[3] */
#define SPI_PORT        P10_0_PORT
#define SPI_MISO_NUM    P10_0_NUM
#define SPI_MOSI_NUM    P10_1_NUM
#define SPI_SCLK_NUM    P10_2_NUM
#define SPI_SS_NUM      P10_3_NUM

/* Connect SCB1 SPI function to pins */
Cy_GPIO_SetHSIOM(SPI_PORT, SPI_MISO_NUM, P10_1_SCB1_SPI_MISO);
Cy_GPIO_SetHSIOM(SPI_PORT, SPI_MOSI_NUM, P10_0_SCB1_SPI_MOSI);
Cy_GPIO_SetHSIOM(SPI_PORT, SPI_SCLK_NUM, P10_2_SCB1_SPI_CLK);
Cy_GPIO_SetHSIOM(SPI_PORT, SPI_SS_NUM,   P10_3_SCB1_SPI_SELECT0);

#if (USE_SPI_SLAVE)
    /* Configure SCB1 pins for SPI Slave operation */
    Cy_GPIO_SetDrivemode(SPI_PORT, SPI_MISO_NUM, CY_GPIO_DM_STRONG_IN_OFF);
    Cy_GPIO_SetDrivemode(SPI_PORT, SPI_MOSI_NUM, CY_GPIO_DM_HIGHZ);
    Cy_GPIO_SetDrivemode(SPI_PORT, SPI_SCLK_NUM, CY_GPIO_DM_HIGHZ);
    Cy_GPIO_SetDrivemode(SPI_PORT, SPI_SS_NUM,   CY_GPIO_DM_HIGHZ);
#else /* (USE_SPI_SLAVE) */
    /* Configure SCB1 pins for SPI Master operation */
    Cy_GPIO_SetDrivemode(SPI_PORT, SPI_MISO_NUM, CY_GPIO_DM_HIGHZ);
    Cy_GPIO_SetDrivemode(SPI_PORT, SPI_MOSI_NUM, CY_GPIO_DM_STRONG_IN_OFF);
    Cy_GPIO_SetDrivemode(SPI_PORT, SPI_SCLK_NUM, CY_GPIO_DM_STRONG_IN_OFF);
    Cy_GPIO_SetDrivemode(SPI_PORT, SPI_SS_NUM,   CY_GPIO_DM_STRONG_IN_OFF);
#endif

Assign Clock Divider

A clock source must be connected to the SCB block to oversample input and output signals, in this document this clock will be referred as clk_scb. You must use one of the 8-bit or 16-bit dividers. Use the SysClk (System Clock) driver API to do this.

/* Assign divider type and number for SPI */
#define SPI_CLK_DIV_TYPE    (CY_SYSCLK_DIV_8_BIT)
#define SPI_CLK_DIV_NUM     (0U)

/* Connect assigned divider to be a clock source for SPI */
Cy_SysClk_PeriphAssignDivider(PCLK_SCB1_CLOCK, SPI_CLK_DIV_TYPE, SPI_CLK_DIV_NUM);

Configure Data Rate

To get the SPI slave to operate with the desired data rate, the clk_scb must be fast enough to provide sufficient oversampling. Use the SysClk (System Clock) driver API to do that.

/* SPI data rate is defined by the SPI master because it drives SCLK.
* This clk_scb enables SPI slave operate up to maximum supported data rate.
* For clk_peri = 50 MHz, select divider value 1 and get clk_scb = (50 MHz / 1) = 50 MHz.
*/
Cy_SysClk_PeriphSetDivider   (SPI_CLK_DIV_TYPE, SPI_CLK_DIV_NUMBER, 0UL);
Cy_SysClk_PeriphEnableDivider(SPI_CLK_DIV_TYPE, SPI_CLK_DIV_NUMBER);

To get the SPI master to operate with the desired data rate, multiply the oversample factor by the desired data rate to determine the required frequency for clk_scb. Use the SysClk (System Clock) driver API to configure clk_scb frequency. Set the to define number of SCB clocks in one SCLK period. When this value is even, the first and second phases of the SCLK period are the same. Otherwise, the first phase is one SCB clock cycle longer than the second phase. The level of the first phase of the clock period depends on CPOL settings: 0 - low level and 1 - high level.

/* SPI master desired data rate is 1 Mbps.
* The SPI master data rate = (clk_scb / Oversample).
* For clk_peri = 50 MHz, select divider value 5 and get SCB clock = (50 MHz / 5) = 10 MHz.
* Select Oversample = 10. These setting results SPI data rate = 10 MHz / 10 = 1 Mbps.
*/
Cy_SysClk_PeriphSetDivider   (SPI_CLK_DIV_TYPE, SPI_CLK_DIV_NUMBER, 4UL);
Cy_SysClk_PeriphEnableDivider(SPI_CLK_DIV_TYPE, SPI_CLK_DIV_NUMBER);

Refer to the technical reference manual (TRM) section SPI sub-section Oversampling and Bit Rate to get information about how to configure SPI to run with desired data rate.

Configure Interrupt

The interrupt is optional for the SPI operation. To configure the interrupt, the Cy_SCB_SPI_Interrupt function must be called in the interrupt handler for the selected SCB instance. Also, this interrupt must be enabled in the NVIC. The interrupt must be configured when High-Level API will be used.

void SPI_Isr(void)
{
    Cy_SCB_SPI_Interrupt(SCB1, &spiContext);
}

/* Assign SPI interrupt number and priority */
#define SPI_INTR_NUM        ((IRQn_Type) scb_1_interrupt_IRQn)
#define SPI_INTR_PRIORITY   (7U)

/* Populate configuration structure (code specific for CM4) */
const cy_stc_sysint_t spiIntrConfig =
{
    .intrSrc      = SPI_INTR_NUM,
    .intrPriority = SPI_INTR_PRIORITY,
};

/* Hook interrupt service routine and enable interrupt */
(void) Cy_SysInt_Init(&spiIntrConfig, &SPI_Isr);
NVIC_EnableIRQ(SPI_INTR_NUM);

Enable SPI

Finally, enable the SPI operation by calling Cy_SCB_SPI_Enable. For the slave, this means that SPI device starts responding to the transfers. For the master, it is ready to execute transfers.

/* Enable SPI to operate */
Cy_SCB_SPI_Enable(SCB1);

/* Enable global interrupts */
__enable_irq();

Common Use Cases

The SPI API is the same for the master and slave mode operation and is divided into two categories: Low-Level and High-Level. Do not mix and API because a Low-Level API can adversely affect the operation of a High-Level API.

Low-Level API

The Low-Level functions allow interacting directly with the hardware and do not use Cy_SCB_SPI_Interrupt. These functions do not require context for operation. Thus, NULL can be passed for context parameter in Cy_SCB_SPI_Init and Cy_SCB_SPI_Disable instead of a pointer to the context structure.

To write data into the TX FIFO, use one of the provided functions: Cy_SCB_SPI_Write, Cy_SCB_SPI_WriteArray or Cy_SCB_SPI_WriteArrayBlocking. Note that in the master mode, putting data into the TX FIFO starts a transfer. Due to the nature of SPI, the received data is put into the RX FIFO.
To read data from the RX FIFO, use one of the provided functions: Cy_SCB_SPI_Read or Cy_SCB_SPI_ReadArray. Again due to the nature of SPI these functions do not start a transfer on the bus, they only read data out of the RX FIFO that has already been received.
The statuses can be polled using: Cy_SCB_SPI_GetRxFifoStatus, Cy_SCB_SPI_GetTxFifoStatus and Cy_SCB_SPI_GetSlaveMasterStatus. The statuses are and after a status is set, it must be cleared. Note that there are statuses evaluated as level. These statuses remain set until an event is true. Therefore, after the clear operation, the status is cleared but then it is restored (if the event is still true). Also, the following functions can be used for polling as well Cy_SCB_SPI_IsBusBusy, Cy_SCB_SPI_IsTxComplete, Cy_SCB_SPI_GetNumInRxFifo and Cy_SCB_SPI_GetNumInTxFifo.

uint8_t txBuffer[BUFFER_SIZE];

/* Initialize txBuffer with command to transfer */
txBuffer[0] = CMD_START_TRANSFER;
txBuffer[1] = 0x00U;
txBuffer[2] = 0x01U;

/* Master: start a transfer. Slave: prepare for a transfer. */
Cy_SCB_SPI_WriteArrayBlocking(SCB1, txBuffer, sizeof(txBuffer));

/* Blocking wait for transfer completion */
while (!Cy_SCB_SPI_IsTxComplete(SCB1))
{
}

/* Handle results of a transfer */

High-Level API

The High-Level API use Cy_SCB_SPI_Interrupt to execute the transfer. Call Cy_SCB_SPI_Transfer to start communication: for master mode calling this function starts a transaction with the slave. For slave mode the read and write buffers are prepared for the communication with the master. After a transfer is started, the Cy_SCB_SPI_Interrupt handles the transfer until its completion. Therefore, the Cy_SCB_SPI_Interrupt function must be called inside the user interrupt handler to make the High-Level API work. To monitor the status of the transfer operation, use Cy_SCB_SPI_GetTransferStatus. Alternatively, use Cy_SCB_SPI_RegisterCallback to register a callback function to be notified about SPI Callback Events.

uint8_t rxBuffer[BUFFER_SIZE];
uint8_t txBuffer[BUFFER_SIZE];

/* Initialize txBuffer with command to transfer */
txBuffer[0] = CMD_START_TRANSFER;
txBuffer[1] = 0x00U;
txBuffer[2] = 0x01U;

/* Master: start a transfer. Slave: prepare for a transfer. */
(void) Cy_SCB_SPI_Transfer(SCB1, txBuffer, rxBuffer, sizeof(txBuffer), &spiContext);

/* Blocking wait for transfer completion */
while (0UL != (CY_SCB_SPI_TRANSFER_ACTIVE & Cy_SCB_SPI_GetTransferStatus(SCB1, &spiContext)))
{
}

/* Handle results of a transfer */

DMA Trigger

The SCB provides TX and RX output trigger signals that can be routed to the DMA controller inputs. These signals are assigned based on the data availability in the TX and RX FIFOs appropriately.

The RX trigger signal is active while the number of data elements in the RX FIFO is greater than the value of RX FIFO level. Use function Cy_SCB_SetRxFifoLevel or set configuration structure rxFifoTriggerLevel parameter to configure RX FIFO level value. For example, the RX FIFO has 8 data elements and the RX FIFO level is 0. The RX trigger signal is active until DMA reads all data from the RX FIFO.
The TX trigger signal is active while the number of data elements in the TX FIFO is less than the value of TX FIFO level. Use function Cy_SCB_SetTxFifoLevel or set configuration structure txFifoTriggerLevel parameter to configure TX FIFO level value. For example, the TX FIFO has 0 data elements (empty) and the TX FIFO level is 7. The TX trigger signal is active until DMA loads TX FIFO with 8 data elements (note that after the first TX load operation, the data element goes to the shift register and TX FIFO is empty).

To route SCB TX or RX trigger signals to the DMA controller, use TrigMux (Trigger Multiplexer) driver API.

note

To properly handle DMA level request signal activation and de-activation from the SCB peripheral block the DMA Descriptor typically must be configured to re-trigger after 16 Clk_Slow cycles.

Low Power Support

The SPI driver provides callback functions to handle power mode transitions. The callback Cy_SCB_SPI_DeepSleepCallback must be called during execution of Cy_SysPm_CpuEnterDeepSleep; Cy_SCB_SPI_HibernateCallback must be called during execution of Cy_SysPm_SystemEnterHibernate. To trigger the callback execution, the callback must be registered before calling the power mode transition function. Refer to SysPm (System Power Management) driver for more information about power mode transitions and callback registration.

The SPI master is disabled during Deep Sleep and Hibernate and stops driving the output pins. The state of the SPI master output pins SCLK, SS, and MOSI is High-Z, which can cause unexpected behavior of the SPI Slave due to possible glitches on these lines. These pins must keep the inactive level (the same state when SPI master is enabled and does not transfer data) before entering Deep Sleep or Hibernate mode. To do that, write the GPIO data register of each pin to the inactive level for each output pin. Then configure High-Speed Input Output Multiplexer (HSIOM) of each pin to be controlled by the GPIO (use GPIO (General Purpose Input Output) driver API). After after exiting Deep Sleep mode the SPI master must be enabled and the pins configuration restored to return the SPI master control of the pins (after exiting Hibernate mode, the system initialization code does the same). Copy either or both Cy_SCB_SPI_DeepSleepCallback and Cy_SCB_SPI_HibernateCallback as appropriate, and make the changes described above inside the function. Alternately, external pull-up or pull-down resistors can be connected to the appropriate SPI lines to keep them inactive during Deep-Sleep or Hibernate.

note

Only applicable for rev-08 of the CY8CKIT-062-BLE. For proper operation, when the SPI slave is configured to be a wakeup source from Deep Sleep mode, the Cy_SCB_SPI_DeepSleepCallback must be copied and modified. Refer to the function description to get the details.