AN228740  Usage of Quad SPI (QSPI)/Serial Memory Interface (SMIF) in PSoC™ 6 MCU   

The Serial Flash Library is an easy way to get started with the QSPI block. This library supports all features necessary for accessing most serial flash memory devices. This library also provides simple function calls that handle most of the configuration steps automatically. As a result, the Serial Flash Library is simple to use and is suitable for most use cases. The Serial Flash Library functions call a combination of functions from Hardware Abstraction Layer (HAL) and Peripheral Driver Library (PDL).

Follow these steps to get started with the Serial Flash Library using the Eclipse IDE for ModusToolbox™.

1. Enable the library in the Library Manager (see Figure 1)
   1. Select the Library Manager
   2. Go to the Libraries tab
   3. Select the Serial Flash Library
   4. Select Apply

   
   

2. Include the necessary libraries in your application’s main.c file

   #include "cyhal.h" /* HAL */
   #include "cycfg.h" /* Auto-generated system configuration headers */
   #include "cybsp.h" /* Board specific pin and peripheral definitions */
   #include "cycfg_qspi_memslot.h" /*QSPI external memory configuration structures */
   #include "cy_serial_flash_qspi.h" /* QSPI library functions */
   

3. In the main function, initialize the board peripherals, the UART, and the QSPI block. The QSPI configuration is included in the board support package (BSP) for your kit

   /* Initialize the device and board peripherals */
   result = cybsp_init();
   CY_ASSERT(result == CY_RSLT_SUCCESS);
   /* Enable global interrupts */
    __enable_irq();
   /* Initialize retarget-io to use the debug UART port */
   cy_retarget_io_init(CYBSP_DEBUG_UART_TX, CYBSP_DEBUG_UART_RX, CY_RETARGET_IO_BAUDRATE);
   /* Initialize qspi block and external memory device */
   cy_serial_flash_qspi_init(smifMemConfigs[MEM_SLOT_NUM], CYBSP_QSPI_D0, CYBSP_QSPI_D1, CYBSP_QSPI_D2, CYBSP_QSPI_D3, NC, NC, NC, NC, CYBSP_QSPI_SCK, CYBSP_QSPI_SS, QSPI_BUS_FREQUENCY_HZ);
   

4. Create data buffers to store read and write data. Transfer the data to the external memory. Read back the data and print it to a UART terminal for verification. In the below example, the data is written to and read from the address 0x00040000 in external memory. This address is offset from the base address of external memory, not from the PSoC™ 6 MCU’s local addressing range.

   /* Read/write buffers */
   uint8 rxBuffer[PACKET_SIZE];
   uint8 txBuffer[PACKET_SIZE];
   /* Write the content of the txBuffer to the memory */
   cy_serial_flash_qspi_write(0x00040000, PACKET_SIZE, txBuffer);
   
   /* Read back after Write for verification */
   cy_serial_flash_qspi_read(0x00040000, PACKET_SIZE, rxBuffer);
   

PDL provides a set of functions and structures that access the registers of the QSPI block directly, enabling you to fully configure transactions performed through the QSPI block. This configurability makes the PDL suitable for use in applications where finer control is required.

To get started with the PDL for QSPI using the Eclipse IDE for ModusToolbox™ software, do the following:

1. Enable the QSPI hardware using the device configurator. Figure 2 shows an example configuration suitable for use with any PSoC™ 6 MCU kit that has an external flash device.
   1. Select the Device Configurator from the Quick Panel
   2. Check the box Quad Serial Memory Interface (QSPI) 0 to enable it
   3. Configure the QSPI block as shown in Figure 2
   4. Select the “Go to Signal” button next to Interface Clock to open the clock configuration tab
   5. Change the clock Divider to 2
   6. Save your changes and close the device configurator

   
   

2. Generate the QSPI configuration structures using the QSPI Configurator. Figure 3 shows an example configuration suitable for use with any PSoC™ 6 MCU kit that has an external flash device.
   Note: These instructions describe the process for using an SFDP compliant device. For more information on how to use the QSPI Configurator, including information about how you can generate code for your specific memory configuration, see the QSPI configurator guide.
   1. Select the QSPI Configurator
   2. Select Auto detect SFDP from the drop-down menu
   3. Save the configuration

   
   

3. Include the necessary libraries in your application’s main.c file.

   #include "cy_pdl.h" /* Peripheral Driver Library */
   #include "cybsp.h" /* Board specific pin and peripheral definitions */
   #include "cycfg_qspi_memslot.h" /*QSPI external memory configuration structures */
   

4. Create a global context variable for the QSPI block.

   cy_stc_smif_context_t smif_context;

5. Define a transaction packet size

   #define PACKET_SIZE             (64u)

6. Create an interrupt routine containing a call to the QSPI API interrupt function Cy_SMIF_Interrupt. All FIFO operations will use this interrupt.

   void SMIF_Interrupt_User(void)
   {
       Cy_SMIF_Interrupt(SMIF0, &smif_context);
   }
   

7. In the main function, initialize the peripherals and global interrupts.

   /* Initialize the device and board peripherals */
   result = cybsp_init();
   CY_ASSERT(result == CY_RSLT_SUCCESS);
   /* Enable global interrupts */
   __enable_irq();
   

8. In the main function, set up the SMIF interrupts.

        cy_stc_sysint_t smifIntConfig =
        {
            #if (CY_CPU_CORTEX_M0P)
                /* .intrSrc */ NvicMux7_IRQn,
                /* .cm0pSrc */ smif_interrupt_IRQn,
            #else
               /* .intrSrc */ smif_interrupt_IRQn, /* SMIF interrupt number */
            #endif
            /* .intrPriority */ 7u
        };
        (void) Cy_SysInt_Init(&smifIntConfig, SMIF_Interrupt_User);
   

9. In the main function, initialize and enable the QSPI block.

       /* SMIF initialization */
       Cy_SMIF_Init(SMIF0, &smif_0_config, TIMEOUT_1_S, &smif_context);
       Cy_SMIF_Enable(SMIF0, &smif_context);  /* Enable the SMIF Interrupt */
       #if (__CORTEX_M == 0)
          NVIC_EnableIRQ(NvicMux7_IRQn);
       #else
          NVIC_EnableIRQ(smif_interrupt_IRQn);
       #endif

10. If your external memory supports Serial Flash Discoverable Parameters (SFDP), detect the parameters. For manual memory configuration, this step is optional and only required if you intend to use the device in XIP mode.

        /* Memslot level initialization */
        Cy_SMIF_MemInit(SMIF0, &smifBlockConfig, &smif_context);
    

11. If your external memory device supports Quad mode, enable Quad mode.

      bool isQuadEnabled = false;
      Cy_SMIF_MemIsQuadEnabled(SMIF0, smifBlockConfig.memConfig[0],
                                                        &isQuadEnabled,
                                                        &smif_context);
      Cy_SMIF_MemEnableQuadMode(SMIF0,                       
                              smifBlockConfig.memConfig[0],
                              5000,                        
                              &smif_context);               
    

12. Begin transacting with the external memory device. The following is an example of a write sequence sending data from txBuffer.

    uint8_t txBuffer[PACKET_SIZE];
    uint8_t rxBuffer[PACKET_SIZE];
    /* Erase before write */
    Cy_SMIF_MemEraseSector(SMIF0, smifMemConfigs[0],
    			 0x00,
    			 smifMemConfigs[0]->deviceCfg->eraseSize,
    			 &smif_context);
    
    /* Read to rxBuffer after Erase to confirm that all data is 0xFF */
    Cy_SMIF_MemRead(SMIF0, smifMemConfigs[0],
    		   	smifMemConfigs[0]->deviceCfg->eraseSize,
    		   	rxBuffer,
    		   	PACKET_SIZE,
    		   	&smif_context);
    
    /* Write txBuffer to the external memory */
    Cy_SMIF_MemWrite(SMIF0, smifMemConfigs[0],
    		   	smifMemConfigs[0]->deviceCfg->eraseSize,
    		   	txBuffer, 
    		   	PACKET_SIZE, 
    		   	&smif_context);
    

The QSPI block has three AHB-Lite bus interfaces: two for XIP mode and one for Command mode. The XIP mode interfaces consist of a fast domain and a slow domain. Arm® Cortex®-M4 is the only bus master in the fast domain. In the slow domain, Cortex®-M0, Crypto, Datawire0, and Datawire1 can be bus masters. For Command mode operation, the bus interface is in the clk_sys domain, which is a divided clock from clk_hf. In Command mode, the bus master can be any of the bus masters in XIP mode.

The FIFOs in the block work in the SPI interface clock domain. The remainder of the block components, including the cryptography, mode multiplexer, and port arbiter operate in the high frequency clock domain.

The QSPI hardware provides a mode multiplexer, which allows you to operate the QSPI block in either Command mode or XIP mode. In the PDL, this mode can be changed during runtime by calling the Cy_QSPI_SetMode() function. Note that the mode should be changed only after any ongoing transfers are completed. A call to the Cy_SMIF_BusyCheck() function should be made to ensure that the QSPI block is not busy.

The QSPI block also has a dedicated 4 KB cache for each of the XIP interfaces; one for CM4 and another for CM0 and DMA. These caches are enabled by default. Read transfers that hit in the cache are processed by the cache, while read transfers that miss in the cache incur an XIP memory read transfer of 16 bytes to refill the missed subsector. There is also a prefetch buffer, which grabs the next 16 bytes of data to refill the cache. This means that XIP transfers will occur in 32-byte chunks, 16 bytes for the cache and 16 bytes from the prefetch buffer, before a SPI transfer occurs to refill the cache subsector and the prefetch buffer.

As a result, XIP mode is convenient and efficient for small transfers such as executing code out of external memory. For large reads, however, cache and prefetch buffer refills require repeat transmission of the opcode, device address, and dummy cycles every 32 bytes. These refills add latency to the transfer that would not exist in the Command mode.

For RAM devices, XIP mode can write to the external memory. Write transfers in XIP mode bypass the cache and incur a SPI transfer. If a bus master reads and writes to the external memory device, the writes will automatically invalidate the cache.

It is possible for data in the caches to be invalid when data is written to a location in the XIP addressing range. To avoid reading stale data from the caches, you should invalidate the cache when new data is written to the XIP memory region. An example of this would be if you were executing code out of external memory at address 0x18000000 when the QSPI block was transitioned into Command mode and a write occurred at the same address. Switching the block back into XIP mode and executing from that address could cause a failure.

It is also possible for two masters from different AHB clock domains to access the external memory through the SMIF block, such as the DMA hardware and CM4. In this use case, it is a good practice to make sure the regions being accessed by each master do not overlap. This minimizes the likelihood that the cache will contain invalid data. If the accessed regions do overlap, the cache can be disabled with the PDL function call Cy_QSPI_CacheDisable() or the cache will need to be invalidated after each write using Cy_QSPI_CacheInvalidate().

The QSPI block acts as a SPI master when communicating with external memory devices. QSPI only supports SPI configuration 0, where the clock polarity (CPOL) is 0 and the clock phase (CPHA) is 0. In addition, to standard SPI, the block is also capable of operating in Dual-SPI, Quad-SPI, Dual Quad-SPI, and Octal-SPI modes. For all modes, the block operates using Single Data Rate (SDR) mode.

QSPI can support up to four memory devices simultaneously, limited by the number of data select lines. For example, QSPI supports eight data lines, which means that four single or Dual-SPI memory devices can use all eight data lines and all of the available data select lines, or the same four memory devices can use the same data lines but different data select lines. Likewise, four Quad-SPI or Octal-SPI devices can be used simultaneously, sharing data lines but using unique data selects. For a given memory device, the data lines used must be adjacent. To see the signals used by specific memory device types, see Table 1.

Each memory device must be mapped to one of the four “slots” in the QSPI block. The slot for your memory device will have a corresponding I/O pin controlling the CS line. To ensure that firmware accesses the correct device, make sure that your QSPI configuration uses the same CS line to which your external memory CS is connected.

For each of the four select lines, there are legal and illegal configurations. Table 2 lists the legal configurations and the corresponding data select enumerated type defined in cy_smif.h. This data set is used automatically when configuring your device using the QSPI Configurator.

The spi_data values correspond to the QSPI I/O pins on your PSoC™ 6 MCU device. To determine which pins are available as spi_data pins for your device, see the Alternate Pin Function section of the device datasheet.

Dual-quad configurations are also supported by QSPI. In dual-quad configuration, two quad-SPI devices are used simultaneously, with each device contributing a nibble of a byte per transfer. The devices will share the interface clock signal, but will use different CS lines and separate I/O lines. Table 3 lists the configuration for dual-quad mode.

For more information about the legal configurations and example diagrams of proper configurations, see the PSoC™ 6 MCU architecture TRM.

The QSPI block includes a cryptography component to make sure data can be securely stored in external memory. The encryption and decryption are based on the AES-128 forward block cypher. A 128-bit key, stored in dedicated write-only QSPI registers SMIF_CRYPTO_KEY3, …, SMIF_CRYPTO_KEY0, is used with a 128-bit plaintext to generate a cyphertext. The method of generating the cyphertext depends on whether the QSPI block is in Command or XIP mode.

The Serial Flash Library does not support encryption, so the PDL functions for encryption must be used. If you prefer the Serial Flash Library for configuration and data transfers, a combination of Serial Flash Library and PDL can be used.

SMIF0->DEVICE[2].CTL |= (1 << SMIF_DEVICE_CTL_CRYPTO_EN_Pos /* 8U */);

The ModusToolbox™ Software Environment includes the libraries and files necessary to use QSPI without the need to access the hardware registers directly. The PDL provides low-level configuration for the QSPI block and the API necessary to transfer data to the memory device. The Serial Flash Library and the HAL provide layers of access above the PDL. Table 4 lists the files used by these libraries and the library to which they belong.

The ModusToolbox™ Software Environment includes the QSPI Configurator. The Configurator tool provides a simple graphical interface to set up QSPI to use an external memory device. You can launch the Configurator from within ModusToolbox™ IDE, following step 1 from Using the Peripheral Driver Library. You can also launch the standalone Configurator tool to generate source files that can be used in most IDEs. Navigate to your ModusToolbox™ installation folder and follow this path:

{Install Dir}\ModusToolbox\tools_2.0\qspi-configurator\qspi-configurator.exe

In the Configurator, you can select your memory device, slot or select line it is connected to, SPI width, memory address ranges, and encryption (for XIP mode). Once you have set your choices, the QSPI Configurator tool automatically generates the source and header files containing the parameters of your external memory device. The parameters of the device are stored in configuration structures, which can be passed as arguments to the PDL or Serial Flash Library functions to easily access your memory device.

The Configurator tool pulls configurations from a database of memory files in XML format, called .cymem files. These files, and an editable template memory file, are typically installed along with the ModusToolbox™ IDE. For more information on these files and how to use the QSPI Configurator Tool, see the user guide.

The QSPI block supports programming of external memories through programming tools such as the KitProg3 provided with Infineon kits. For detailed information about how to setup your application to support external memory programming, see Programming external memory.

To access an external memory device, you need to make sure your QSPI block is configured correctly for the memory device that you are using. The cycfg_qspi_memslot.c/h files generated by the QSPI Configurator tool provides a set of nested structures that contain each configuration parameter for your system. This reduces the amount of time you need to spend on creating command lists and setting up the transfer parameters for each transfer. Figure 8 shows organization of the generated structures.

At the highest level is the cy_stc_smif_block_config_t structure. This simple structure contains the number of memory devices connected to the block, the QSPI driver version, and a double pointer to the memory configuration structure.

Nested within the block configuration structure is the memory configuration structure. This structure contains application-level information about the external memory device, including the SPI slave select slot, the slot of the data lines, the base address, the size of the external address, the number of dual-quad SPI slots, and a pointer to the memory device configuration structures.

The memory device configuration structure, cy_stc_smif_mem_device_cfg_t,contains device-specific information including the default memory commands necessary to access the memory device. Typically, the details of this structure can be filled in using information from your memory device’s datasheet.

The lowest level structure within the overall QSPI architecture is the memory device command structure, cy_stc_smif_mem_cmd_t. For each of the commands listed in the memory device configuration structure, there is a corresponding command structure. These structures specify the requirements of the commands, including command width, address width, mode, mode width, data width, and the number of dummy cycles.