MTB CAT1 Peripheral driver library

General Description

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:

Configuration Considerations

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

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 */
/* Populate configuration structure */
#if (USE_SPI_SLAVE)
/* Slave configuration */
{
.subMode = CY_SCB_SPI_MOTOROLA,
.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 */
{
.subMode = CY_SCB_SPI_MOTOROLA,
.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_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);
#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_NUMBER (0U)
/* Connect assigned divider to be a clock source for SPI */
Cy_SysClk_PeriphAssignDivider(PCLK_SCB1_CLOCK, SPI_CLK_DIV_TYPE, SPI_CLK_DIV_NUMBER);

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 oversample parameter in configuration structure 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);
Note
In CAT1D devices, to avoid potential metastable conditions at 50 MHz, set clock to 200 MHz, oversample to 4 and median filter to 1.

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);
}
void SPI_Cfg_Isr(void)
{
/* 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);
}
void SPI_EventHandler(uint32_t events)
{
{
/* Handle the error condition */
}
}
void SPI_Reg_Callback(void)
{
/* Configure the interrupt */
SPI_Cfg_Isr();
/* Set the slave interrupt mask register bit for SPI_BUS_ERROR field */
/* Register callback for event notification.
* It is better to do this during initialization before SPI is enabled.
*/
Cy_SCB_SPI_RegisterCallback(SCB1, SPI_EventHandler, &spiContext);
}

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 */
/* 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 High-Level and Low-Level 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.

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 */
{
}
/* 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.

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.

API Reference

 Macros
 
 Functions
 
 Data Structures
 
 Enumerated Types