Provides functions for interacting with an external memory connected through its Single SPI/Dual SPI/Quad SPI/Octal SPI interface. The read, write and erase operations are implemented as blocking functions. This library accepts the configuration generated using the QSPI Configurator tool.
The library is available for devices that define CY_IP_MXSMIF (devices with the MXSMIF peripheral); on other devices the API is not compiled. Read and write also work with HyperBus memories (through the PDL HyperBus functions), erase is supported only for SPI memories.
Use this library when your application needs to interact with an external memory device connected via a Single/Dual/Quad/Octal SPI interface. Common scenarios include:
Step 1. Add the library to the application using the Library Manager. The library needs a PDL that provides the SMIF MemNum API (Cy_SMIF_MemNum* functions and the cy_stc_smif_mem_context_t and cy_stc_smif_mem_info_t types) and a HAL that provides mtb_hal.h. Both are normally provided by the BSP of the target.
Step 2. Include the library header. The configurator-generated headers, including cycfg_qspi_memslot.h, are pulled in by cybsp.h:
Step 3. Select the operating flow:
Step 4. Declare the objects needed by the library and initialize the SMIF driver via PDL calls:
Objects used above:
| Object | Source |
|---|---|
| MEMORYSPI0_hal_config | Generated by the Device Configurator for the SMIF instance. Its name is <alias>_hal_config, where <alias> is the alias set on the SMIF personality (MEMORYSPI0 in this example). Available through cybsp.h. |
| smifBlockConfig | Generated by the QSPI Configurator and declared in cycfg_qspi_memslot.h. The name depends on the configurator setup, for example smif0BlockConfig. |
| mem_context | Declared by the application. mem_context.smif_context is initialized by Cy_SMIF_Init(), and the remaining fields are set by mtb_serial_memory_setup(). |
| mem_info | Declared by the application. It is an output filled in by mtb_serial_memory_setup() for the chip passed to it and refreshed by mtb_serial_memory_set_active_chip() for the selected chip, no initialization is needed. |
Note: serial_memory_obj, mem_context and mem_info are referenced by the library after setup, so they must remain valid for as long as the library is used (declare them as global or static). serial_memory_obj must be zero-initialized before mtb_serial_memory_setup() is called, because the function updates its fields with read-modify-write operations; global and static objects are zero-initialized by default, and the explicit = {0} shows the requirement. Call mtb_serial_memory_setup() once per object, calling it again on the same object is not supported.
Step 5. Set up the serial memory library. The chip select is taken from the QSPI Configurator output, so the snippet does not depend on the slot the memory is placed in:
memConfig[0] is the first memory configured in the QSPI Configurator. Use another index to select a different memory. The cy_en_smif_slave_select_t values match mtb_serial_memory_chip_select_t, so the cast is valid. The chip select can also be set explicitly using one of the following values:
| Chip select | Value |
|---|---|
| MTB_SERIAL_MEMORY_CHIP_SELECT_0 | 0x1 (SMIF slave select 0) |
| MTB_SERIAL_MEMORY_CHIP_SELECT_1 | 0x2 (SMIF slave select 1) |
| MTB_SERIAL_MEMORY_CHIP_SELECT_2 | 0x4 (SMIF slave select 2) |
| MTB_SERIAL_MEMORY_CHIP_SELECT_3 | 0x8 (SMIF slave select 3) |
Note: The functions that need a successful setup (read, write, erase and the others except mtb_serial_memory_setup()) check this with CY_ASSERT. A build without assertions has no supported recovery path after a failed setup, so always check the setup result and stop the flow on failure.
Note: For memories that use Quad mode, mtb_serial_memory_setup() enables the Quad Enable (QE) bit if it is not already set. The enable command is sent once; the library then polls the memory until it is ready and reads the QE bit back, up to MTB_SERIAL_MEMORY_QUAD_ENABLE_MAX_ATTEMPTS times (default 3, must be at least 1). More attempts do not resend the command. Each poll uses the timeout MTB_SERIAL_MEMORY_QUAD_ENABLE_TIMEOUT_US (default 5000 us). The possible outcomes are:
- The QE bit is already set: no command is sent and setup continues.
- The QE bit is set after the command: setup continues.
- The memory stays busy longer than the timeout (the QE bit is stored in a non-volatile register, so the write can keep the device busy for tens of milliseconds): setup returns CY_SMIF_EXCEED_TIMEOUT. Raise the timeout in the Makefile, for example DEFINES+=MTB_SERIAL_MEMORY_QUAD_ENABLE_TIMEOUT_US=1000000.
- The readback succeeds but the QE bit is not set: setup returns MTB_RSLT_SERIAL_MEMORY_ERR_QUAD_ENABLE.
- Another PDL SMIF error ends the sequence early and setup returns that status.
Note: Octal memories (MXSMIF version 4 and later) must already be in Octal mode (SDR or DDR, as configured) when mtb_serial_memory_setup() is called. The library sets the SMIF RX capture mode first and sends the Octal enable command only if the mode still differs, so for a memory with an explicit part number the command is not sent. This avoids a hang that can occur when SMIF is disabled and re-enabled while the code executes from the same memory (XIP). If the memory is still in single SPI mode, setup returns CY_RSLT_SUCCESS and the following operations fail, typically with CY_SMIF_EXCEED_TIMEOUT (0x00B20002). The PDL requires Cy_SMIF_MemOctalEnable() to be executed before octal commands are sent, so a memory that powers up in single SPI mode needs it from the application before setup: Cy_SMIF_MemNumInit(), Cy_SMIF_Enable(), Cy_SMIF_Reset_Memory(), Cy_SMIF_MemOctalEnable(), then set the RX capture mode required by the configuration. Nothing is needed for memories that power up in Octal mode or for Single, Dual and Quad SPI memories.
Step 6. Use the library to erase, write, and read external memory. All of these functions are blocking:
Note: The CY_ASSERT calls keep the snippet short. Production code must check the result of every call and handle the error without relying on assertions.
The define applies to all SPI memories, not only Octal DDR, and it restricts the access sizes that are accepted. See the description in mtb_serial_memory.h before enabling it.
All library functions that return a result code return CY_RSLT_SUCCESS (defined in cy_result.h) on success. Any other value is an error. The library error codes are defined and documented in mtb_serial_memory.h.
mtb_serial_memory_setup() can also return a PDL SMIF status code, such as CY_SMIF_EXCEED_TIMEOUT.
After a successful mtb_serial_memory_setup(), call mtb_serial_memory_enable_xip() to map the external memory into the MCU address space:
mtb_serial_memory_enable_xip() configures only the MCU and does not send any command to the memory. The erase, write and read functions must be called with XIP mode disabled.
Code placed in the mapped address range by the linker script can be executed directly. Code that executes from the external memory cannot run while XIP mode is disabled, so the calls to erase, write and read must be made from code located in internal memory.
To let a programming tool (for example Cypress Programmer, OpenOCD or pyOCD) program the external memory together with the internal memory, for example when the application code is placed into the external memory for XIP, add the following line to the application Makefile:
With this define, the library places the information about the memory in the .cy_sflash_user_data and .cy_toc_part2 sections. These sections must be provided by the application linker script. The .cy_toc_part2 data ends with a CRC16 checksum that must be recomputed whenever its content changes, which can be done by running cymcuelftool -S on the built ELF file. The section placement options and the data layout are described in the comments of mtb_serial_memory_prog.c.
After the application is built, the programming tool reads these sections to detect the attached memory and to learn how to program it. No API calls are needed at run time.
This library is licensed under the Apache License, Version 2.0.
(c) (2018-2026), Infineon Technologies AG, or an affiliate of Infineon Technologies AG. All rights reserved.