In addition to the APIs for reading and writing to memory at runtime, this library also provides support for informing programming tools about the external memory so it can be written at the same time as internal memory.
In QSPI configurator Memory Parts are tied to a specific slave slot that is linked to the actual slave select pin mappings of that specific device. So selecting a memory configuration for slot 0 means that physically that external memory will be the connected to slave select 0 pin. This is important for kits that have hardwired connections to external memories where the memory configuration needs to be in the correct slot depending on what slave select pin is hardwired to it.
For external memories that are configured in Octal DDR mode, read/write operations at odd addresses and with length equal to 1 are not natively supported due to limitations in the protocol that requires an even address and/or even lengths. For this reason a special handling of these cases is present in mtb_serial_memory_read and mtb_serial_memory_write to allow the use of odd addresses in a transparent way for the user.
For mtb_serial_memory_read when selecting a read one byte at an odd address, the function will instead perform a read at the even address preceding the specified address and then discard the extra byte returning to the user only the data they requested.
For mtb_serial_memory_write the function needs to take into consideration all four possible combinations of even/odd addresses and lengths:
This special handling needs to be enabled by setting the define _MTB_SERIAL_MEMORY_EMULATE_BYTE_ADDRESSABLE in the application Makefile:
HyperBus memories are not affected by this define.
This support can be enabled by defining MTB_SERIAL_MEMORY_ENABLE_XIP_PROGRAM while building the application. With this define in place, code will be generated in the .cy_sflash_user_data & .cy_toc_part2 sections. These sections must be provided by the linker script for the application. Once the application has been built, these locations can be read by programming tools (eg: Cypress Programmer, OpenOCD, pyOCD) to know that there is a memory device attached and how to program it.
Data Structures | |
| struct | mtb_serial_memory_t |
| Serial memory object. More... | |
Macros | |
| #define | MTB_SERIAL_MEMORY_THREAD_SAFE |
| Enables thread-safety for use with multi-threaded RTOS environment. | |
| #define | CY_IP_MXSMIF |
| The MXSMIF IP is available. | |
| #define | MTB_SERIAL_MEMORY_QUAD_ENABLE_TIMEOUT_US |
| Timeout in microseconds for each poll of the memory ready status during the quad enable sequence of mtb_serial_memory_setup. | |
| #define | MTB_SERIAL_MEMORY_QUAD_ENABLE_MAX_ATTEMPTS |
| Number of times the memory ready status and the QE bit are read back after the quad enable command has been sent. | |
| #define | MTB_SERIAL_MEMORY_VERSION_MAJOR (3U) |
| The major version of the serial memory asset. | |
| #define | MTB_RSLT_SERIAL_MEMORY_ERR_UNSUPPORTED (CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_BOARD_LIB_SERIAL_MEMORY, 1)) |
| The function or operation is not supported on the target or the memory. | |
| #define | MTB_RSLT_SERIAL_MEMORY_ERR_BAD_PARAM (CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_BOARD_LIB_SERIAL_MEMORY, 2)) |
| Parameters passed to a function are invalid. | |
| #define | MTB_RSLT_SERIAL_MEMORY_ERR_READ_BUSY (CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_BOARD_LIB_SERIAL_MEMORY, 3)) |
| Reserved. | |
| #define | MTB_RSLT_SERIAL_MEMORY_ERR_OCTAL_ENABLE (CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_BOARD_LIB_SERIAL_MEMORY, 4)) |
| Setting octal enabled failed. | |
| #define | MTB_RSLT_SERIAL_MEMORY_ERR_RX_CAPTURE (CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_BOARD_LIB_SERIAL_MEMORY, 5)) |
| Setting rx capture mode failed. | |
| #define | MTB_RSLT_SERIAL_MEMORY_ERR_QUAD_ENABLE (CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_BOARD_LIB_SERIAL_MEMORY, 6)) |
| Setting quad enabled failed: the QE bit did not read back as set. | |
Enumerations | |
| enum | mtb_serial_memory_chip_select_t { MTB_SERIAL_MEMORY_CHIP_SELECT_0 = 1u , MTB_SERIAL_MEMORY_CHIP_SELECT_1 = 1u << 1 , MTB_SERIAL_MEMORY_CHIP_SELECT_2 = 1u << 2 , MTB_SERIAL_MEMORY_CHIP_SELECT_3 = 1u << 3 } |
| Serial Memory Chip Select Each chip select is represented by an enumeration that has the bit corresponding to the chip select number set. More... | |
Functions | |
| cy_rslt_t | mtb_serial_memory_setup (mtb_serial_memory_t *obj, mtb_serial_memory_chip_select_t smif_active_chip, SMIF_Type *base, const mtb_hal_clock_t *clock, cy_stc_smif_mem_context_t *mem_context, cy_stc_smif_mem_info_t *mem_info, const cy_stc_smif_block_config_t *block_config) |
| Sets up the serial memory. | |
| cy_rslt_t | mtb_serial_memory_setup_nonsecure (mtb_serial_memory_t *obj, mtb_serial_memory_chip_select_t smif_active_chip, SMIF_Type *base, cy_stc_smif_mem_context_t *mem_context, cy_stc_smif_mem_info_t *mem_info) |
| Sets up the serial memory on non-secure world if the peripheral is secure. | |
| size_t | mtb_serial_memory_get_size (mtb_serial_memory_t *obj) |
| Returns the size of the serial memory in bytes. | |
| size_t | mtb_serial_memory_get_erase_size (mtb_serial_memory_t *obj, uint32_t addr) |
| Returns the size of the erase sector to which the given address belongs. | |
| size_t | mtb_serial_memory_get_prog_size (mtb_serial_memory_t *obj, uint32_t addr) |
| Returns the page size for programming of the memory. | |
| __STATIC_INLINE uint32_t | mtb_serial_memory_get_sector_start_address (mtb_serial_memory_t *obj, uint32_t addr) |
| Utility function to calculate the starting address of an erase sector to which the given address belongs. | |
| cy_rslt_t | mtb_serial_memory_read (mtb_serial_memory_t *obj, uint32_t addr, size_t length, uint8_t *buf) |
| Reads data from the serial memory. | |
| cy_rslt_t | mtb_serial_memory_write (mtb_serial_memory_t *obj, uint32_t addr, size_t length, const uint8_t *buf) |
| Writes the data to the serial memory. | |
| cy_rslt_t | mtb_serial_memory_erase (mtb_serial_memory_t *obj, uint32_t addr, size_t length) |
| Erases the serial memory, uses chip erase command when addr = 0 and length = flash_size otherwise uses sector erase command. | |
| cy_rslt_t | mtb_serial_memory_enable_xip (mtb_serial_memory_t *obj, bool enable) |
| Enables Execute-in-Place (memory mapped) mode on the MCU. | |
| cy_rslt_t | mtb_serial_memory_set_active_chip (mtb_serial_memory_t *obj, mtb_serial_memory_chip_select_t chip_select) |
| Sets the active memory device that the serial memory functions perform the operations on. | |
| uint32_t | mtb_serial_memory_get_chip_count (mtb_serial_memory_t *obj) |
| Returns the number of memory devices successfully initialized. | |
| uint32_t | mtb_serial_memory_get_active_chip (mtb_serial_memory_t *obj) |
| Returns the active chip select. | |
| cy_rslt_t | mtb_serial_memory_set_write_enable (mtb_serial_memory_t *obj, bool enable) |
| Send the Write Enable or Write Disable command to the external memory. | |
| struct mtb_serial_memory_t |
| #define MTB_SERIAL_MEMORY_THREAD_SAFE |
Enables thread-safety for use with multi-threaded RTOS environment.
When defined, mtb_serial_memory_read, mtb_serial_memory_write and mtb_serial_memory_erase take a mutex that belongs to the mtb_serial_memory_t object. The other functions (for example mtb_serial_memory_set_active_chip, mtb_serial_memory_enable_xip and mtb_serial_memory_set_write_enable) are not protected, the application must serialize calls to them and to the protected functions. Thread-safety is not provided between different objects or between CPU cores.
| #define MTB_SERIAL_MEMORY_QUAD_ENABLE_TIMEOUT_US |
Timeout in microseconds for each poll of the memory ready status during the quad enable sequence of mtb_serial_memory_setup.
Default: 5000. Define it in the application Makefile to override, for example DEFINES+=MTB_SERIAL_MEMORY_QUAD_ENABLE_TIMEOUT_US=1000000.
| #define MTB_SERIAL_MEMORY_QUAD_ENABLE_MAX_ATTEMPTS |
Number of times the memory ready status and the QE bit are read back after the quad enable command has been sent.
Default: 3. The value must be at least 1: with 0 no readback is done and mtb_serial_memory_setup returns MTB_RSLT_SERIAL_MEMORY_ERR_QUAD_ENABLE whenever the QE bit had to be programmed. The quad enable command itself is sent only once, more attempts do not resend it. The sequence ends early when the PDL returns an error status. Define it in the application Makefile to override.
| #define MTB_RSLT_SERIAL_MEMORY_ERR_READ_BUSY (CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_BOARD_LIB_SERIAL_MEMORY, 3)) |
Reserved.
This release has no asynchronous read, and the library does not return this value. It is kept for compatibility with earlier versions: a previously initiated read operation is not yet complete.
| #define MTB_RSLT_SERIAL_MEMORY_ERR_QUAD_ENABLE (CY_RSLT_CREATE(CY_RSLT_TYPE_ERROR, CY_RSLT_MODULE_BOARD_LIB_SERIAL_MEMORY, 6)) |
Setting quad enabled failed: the QE bit did not read back as set.
See the quad enable note in README.md about MTB_SERIAL_MEMORY_QUAD_ENABLE_TIMEOUT_US.
Serial Memory Chip Select Each chip select is represented by an enumeration that has the bit corresponding to the chip select number set.
| cy_rslt_t mtb_serial_memory_setup | ( | mtb_serial_memory_t * | obj, |
| mtb_serial_memory_chip_select_t | smif_active_chip, | ||
| SMIF_Type * | base, | ||
| const mtb_hal_clock_t * | clock, | ||
| cy_stc_smif_mem_context_t * | mem_context, | ||
| cy_stc_smif_mem_info_t * | mem_info, | ||
| const cy_stc_smif_block_config_t * | block_config ) |
Sets up the serial memory.
mem_context and mem_info must remain valid as long as the library is used.| obj | Pointer to the mtb_serial_memory_t object to setup |
| smif_active_chip | The slave select line to configure as active |
| base | Pointer to the SMIF base address |
| clock | Pointer to the clock object |
| mem_context | Pointer to the SMIF Device internal context data |
| mem_info | Pointer to the SMIF memory info structure |
| block_config | Pointer to the SMIF block configuration structure |
smif_active_chip is not configured in block_config (nothing is modified in this case), MTB_RSLT_SERIAL_MEMORY_ERR_UNSUPPORTED if a memory uses "Auto Detect SFDP" and the SMIF clock (HF clock frequency, divided by 2 for MXSMIF version 2 and later) exceeds 50 MHz, an error code otherwise. | cy_rslt_t mtb_serial_memory_setup_nonsecure | ( | mtb_serial_memory_t * | obj, |
| mtb_serial_memory_chip_select_t | smif_active_chip, | ||
| SMIF_Type * | base, | ||
| cy_stc_smif_mem_context_t * | mem_context, | ||
| cy_stc_smif_mem_info_t * | mem_info ) |
Sets up the serial memory on non-secure world if the peripheral is secure.
| obj | Pointer to the mtb_serial_memory_t object to setup |
| smif_active_chip | The slave select line to configure as active |
| base | Pointer to the SMIF base address |
| mem_context | Pointer to the SMIF Device internal context data |
| mem_info | Pointer to the SMIF memory info structure |
| size_t mtb_serial_memory_get_size | ( | mtb_serial_memory_t * | obj | ) |
Returns the size of the serial memory in bytes.
| obj | Pointer to the mtb_serial_memory_t object to obtain information from |
| size_t mtb_serial_memory_get_erase_size | ( | mtb_serial_memory_t * | obj, |
| uint32_t | addr ) |
Returns the size of the erase sector to which the given address belongs.
Address is used only for a memory with hybrid sector size.
| obj | Pointer to the mtb_serial_memory_t object to obtain information from. |
| addr | Address that belongs to the sector for which size is returned. |
| size_t mtb_serial_memory_get_prog_size | ( | mtb_serial_memory_t * | obj, |
| uint32_t | addr ) |
Returns the page size for programming of the memory.
| obj | Pointer to the mtb_serial_memory_t object to obtain information from. |
| addr | Not used in this release, the same value is returned for every address. |
| __STATIC_INLINE uint32_t mtb_serial_memory_get_sector_start_address | ( | mtb_serial_memory_t * | obj, |
| uint32_t | addr ) |
Utility function to calculate the starting address of an erase sector to which the given address belongs.
The calculation assumes that the erase sector size is a power of two.
| obj | Pointer to the mtb_serial_memory_t object to obtain information from. |
| addr | Address in the sector for which the starting address is returned. |
| cy_rslt_t mtb_serial_memory_read | ( | mtb_serial_memory_t * | obj, |
| uint32_t | addr, | ||
| size_t | length, | ||
| uint8_t * | buf ) |
Reads data from the serial memory.
This is a blocking function. Returns error if (addr + length) exceeds the memory size. A read with length 0 returns an error. For SPI memories the read is done with the PDL MemNum read function, for HyperBus memories with the PDL HyperBus read function. If _MTB_SERIAL_MEMORY_EMULATE_BYTE_ADDRESSABLE is set the function can emulate byte addressable memories (intended for Octal DDR memories, but it applies to all SPI memories) and handle one byte reads even at odd addresses. With the define set, a read at an even address is passed to the PDL with any length, and a read at an odd address is supported only with length 1. See Serial Memory handling for Octal DDR.
| obj | Pointer to the mtb_serial_memory_t object to obtain information from. |
| addr | Starting address to read from |
| length | Number of data bytes to read |
| buf | Pointer to the buffer to store the data read from the memory |
| cy_rslt_t mtb_serial_memory_write | ( | mtb_serial_memory_t * | obj, |
| uint32_t | addr, | ||
| size_t | length, | ||
| const uint8_t * | buf ) |
Writes the data to the serial memory.
The program area must have been erased prior to calling this API using mtb_serial_memory_erase() This is a blocking function. Returns error if (addr + length) exceeds the memory size. A write with length 0 returns an error. For SPI memories the write is done with the PDL MemNum write function, for HyperBus memories with the PDL HyperBus write function. If _MTB_SERIAL_MEMORY_EMULATE_BYTE_ADDRESSABLE is set the function can emulate byte addressable memories (intended for Octal DDR memories, but it applies to all SPI memories) and handle one byte writes even at odd addresses. A one-byte write then programs two bytes, starting at the requested address rounded down to an even address. The other byte is kept by reading it first. See Serial Memory handling for Octal DDR.
| obj | Pointer to the mtb_serial_memory_t object to write to. |
| addr | Starting address to write to |
| length | Number of bytes to write |
| buf | Pointer to the buffer storing the data to be written |
| cy_rslt_t mtb_serial_memory_erase | ( | mtb_serial_memory_t * | obj, |
| uint32_t | addr, | ||
| size_t | length ) |
Erases the serial memory, uses chip erase command when addr = 0 and length = flash_size otherwise uses sector erase command.
This is a blocking function.
addr and (addr + length) must be aligned to the erase sector size. For memories with hybrid sectors, each of the two addresses is checked against the sector size of the region it is located in, with the offset taken from the start of that region. An unaligned range is rejected with MTB_RSLT_SERIAL_MEMORY_ERR_BAD_PARAM and nothing is erased. The sector erase is done by the PDL function Cy_SMIF_MemNumEraseSector(), which would otherwise round addr down and (addr + length) up to sector boundaries and erase the whole rounded range, so data outside the requested range could be lost. A range that exceeds the memory size is not checked by the library, the PDL status CY_SMIF_BAD_PARAM is returned for it and nothing is erased.Erase is supported only for SPI memories, for other memory types (for example HyperBus) MTB_RSLT_SERIAL_MEMORY_ERR_UNSUPPORTED is returned. Call mtb_serial_memory_get_size() to get the flash size and call mtb_serial_memory_get_erase_size() to get the size of an erase sector.
| obj | Pointer to the mtb_serial_memory_t object to erase. |
| addr | Starting address to begin erasing |
| length | Number of bytes to erase |
| cy_rslt_t mtb_serial_memory_enable_xip | ( | mtb_serial_memory_t * | obj, |
| bool | enable ) |
Enables Execute-in-Place (memory mapped) mode on the MCU.
This function does not send any command to the serial memory.
| obj | Pointer to the mtb_serial_memory_t object to enable XIP on. |
| enable | true: XIP mode is set, false: normal mode is set |
| cy_rslt_t mtb_serial_memory_set_active_chip | ( | mtb_serial_memory_t * | obj, |
| mtb_serial_memory_chip_select_t | chip_select ) |
Sets the active memory device that the serial memory functions perform the operations on.
| obj | Pointer to the mtb_serial_memory_t object to set active chip for. |
| chip_select | The chip select of the memory device to be set as active. |
| uint32_t mtb_serial_memory_get_chip_count | ( | mtb_serial_memory_t * | obj | ) |
Returns the number of memory devices successfully initialized.
| obj | Pointer to the mtb_serial_memory_t object to get chip count for. |
| uint32_t mtb_serial_memory_get_active_chip | ( | mtb_serial_memory_t * | obj | ) |
Returns the active chip select.
| obj | Pointer to the mtb_serial_memory_t object to get the active chip for. |
| cy_rslt_t mtb_serial_memory_set_write_enable | ( | mtb_serial_memory_t * | obj, |
| bool | enable ) |
Send the Write Enable or Write Disable command to the external memory.
| obj | Pointer to the mtb_serial_memory_t object to send write enable/disable command to. |
| enable | if true the command to be sent is Write Enable, if false the command to be sent is Write Disable. |