MemorySPI (Memory Serial Peripheral Interface)

General Description

High level interface for interacting with the Memory SPI interface.

MemorySPI is an SPI-based communication interface, often used with external memory devices. The MemorySPI driver supports sending and receiving commands to/from from another device via a single, dual, quad, or octal SPI interface.

Features

• Standard SPI Master interface
• Supports Single/Dual/Quad/Octal SPI memories
• Supports Dual-Quad SPI mode
• Execute-In-Place (XIP) from external Quad SPI Flash
• Supports external serial memory initialization via Serial Flash Discoverable Parameters (SFDP) standard

Code Snippets

Note

The following snippets show commands specific to the S25FL512S Cypress NOR Flash device. Refer to the datasheet of the external memory device for device specific memory commands.

Code Snippet 1: Initializing the mtb_hal_memoryspi_command_t structure

The following code snip demonstrates an example for initializing the mtb_hal_memoryspi_command_t structure for any given flash command. The mtb_hal_memoryspi_command_t.mode_bits structure has several other components which should be set as per the command. Mode bits are not required for single SPI read command, hence, mode_bits.disabled is set to TRUE in the below example code.

// Commands
#define DEVICE_SPECIFIC_READ_COMMAND                    (0x03)
 
// Defining MEMORYSPI command structure for READ command
mtb_hal_memoryspi_command_t device_specific_read_command =
{
    .instruction.bus_width      = MTB_HAL_MEMORYSPI_CFG_BUS_SINGLE,    // Bus width for the
                                                                       // instruction
    .instruction.data_rate      = MTB_HAL_MEMORYSPI_DATARATE_SDR,      // Data rate for instruction
    // (SDR/DDR)
    .instruction.two_byte_cmd   = false,                        // command is 1-byte value
    .instruction.value          = DEVICE_SPECIFIC_READ_COMMAND, // Instruction value
    .instruction.disabled       = false,                        // Instruction phase skipped if
                                                                // disabled
                                                                //   set to true
    .address.bus_width          = MTB_HAL_MEMORYSPI_CFG_BUS_SINGLE,    // Bus width for the address
    .address.data_rate          = MTB_HAL_MEMORYSPI_DATARATE_SDR,      // Data rate for address
                                                                       // (SDR/DDR)
    .address.size               = MTB_HAL_MEMORYSPI_CFG_SIZE_24,       // Address size in bits
    .address.disabled           = false,                        // Address phase skipped if disabled
                                                                // set to true
    .mode_bits.disabled         = true,                         // Mode bits phase skipped if
                                                                // disabled set to true
    .dummy_cycles.dummy_count   = 0,                            // Dummy cycles count
    .data.bus_width             = MTB_HAL_MEMORYSPI_CFG_BUS_SINGLE,    // Bus width for data
    .data.data_rate             = MTB_HAL_MEMORYSPI_DATARATE_SDR,      // Data rate for data
                                                                       // (SDR/DDR)
};

Code Snippet 2: MemorySPI initialization and Reading Flash memory

This example function demonstrates the initialization of the MemorySPI component and use of the mtb_hal_memoryspi_read() function to complete the read operation and receive the read data in a buffer.

    cy_rslt_t    result;
    mtb_hal_memoryspi_t memoryspi_object;
    uint8_t      rx_buf[PACKET_SIZE];
    size_t       length = PACKET_SIZE;
    cy_stc_smif_context_t       context;
 
    // Initialize the SMIF using PDL call
    cy_en_smif_status_t pdl_res = Cy_SMIF_Init((MY_MEMORYSPI0_hal_config.base),
                                               (MY_MEMORYSPI0_hal_config.config), 10000,
                                               &context);
    // Setup MEMORYSPI peripheral with configurator generated structure
    result = mtb_hal_memoryspi_setup(&memoryspi_object, &configurator_cfg, &context);
 
    // Complete the set up of SMIF using PDL calls
    Cy_SMIF_SetDataSelect(memoryspi_object.base, (memoryspi_object.chip_select),
                          CY_SMIF_DATA_SEL0);
    Cy_SMIF_Enable(memoryspi_object.base, &context);
 
    result = mtb_hal_memoryspi_select_active_csel(&memoryspi_object,
                                                  (mtb_hal_memoryspi_chip_select_t)memoryspi_object.chip_select);
 
    // HAL API for read operation
    result =
        mtb_hal_memoryspi_read(&memoryspi_object, &device_specific_read_command, ADDRESS, rx_buf,
                               &length);

Code Snippet 3: Erasing Flash memory

The following code snippet demonstrates the use of mtb_hal_memoryspi_transfer() API for sending single byte instruction that may or may not need any address or data bytes. It also shows the usage of status register read command within a while loop to poll the WIP bit status.

    cy_rslt_t    result;
    mtb_hal_memoryspi_t memoryspi_object;
    uint8_t      rx_buf[PACKET_SIZE];
    uint8_t      wip    = 0x01;
    size_t       length = 1;
 
    // HAL API for TX-RX transaction used for sending WREN command
    result = mtb_hal_memoryspi_transfer(&memoryspi_object, &device_specific_wren_command, ADDRESS,
                                        NULL, 0,
                                        NULL, 0);
 
    // HAL API for TX-RX transaction used for sending SE command
    result = mtb_hal_memoryspi_transfer(&memoryspi_object, &device_specific_se_command, ADDRESS,
                                        NULL, 0,
                                        NULL, 0);
 
    while (wip)
    {
        // Wait until the Erase operation is completed
        mtb_hal_memoryspi_read(&memoryspi_object, &device_specific_rdsr1_command, ADDRESS, rx_buf,
                               &length);
        wip = rx_buf[0] & 0x01;
    }

Note

Flash memories need erase operation before programming.

Code Snippet 4: Programming Flash memory

This code snippet demonstrates the usage mtb_hal_memoryspi_write() API for executing program operation on flash memory.

    cy_rslt_t    result;
    mtb_hal_memoryspi_t memoryspi_object;
    uint8_t      tx_buf[PACKET_SIZE];
    uint8_t      rx_buf[PACKET_SIZE];
    size_t       length = PACKET_SIZE;
    uint8_t      wip    = 0x01;
 
    // Initialization of tx_buffer
    for (int i = 0; i < PACKET_SIZE; i++)
    {
        tx_buf[i] = i;
    }
 
    // HAL API for TX-RX transaction used for sending WREN command
    result = mtb_hal_memoryspi_transfer(&memoryspi_object, &device_specific_wren_command, ADDRESS,
                                        NULL, 0,
                                        NULL, 0);
 
    // HAL API for write operation
    result =
        mtb_hal_memoryspi_write(&memoryspi_object, &device_specific_pp_command, ADDRESS, tx_buf,
                                &length);
 
    while (wip)
    {
        // Wait until the Write operation is completed
        mtb_hal_memoryspi_read(&memoryspi_object, &device_specific_rdsr1_command, ADDRESS, rx_buf,
                               &length);
        wip = rx_buf[0] & 0x01;
    }

Code Snippet 5: Configuring multiple memories

This code snippet demonstrates the usage and mtb_hal_memoryspi_select_active_csel() API for switching between memories.

    cy_rslt_t                       result;
    mtb_hal_memoryspi_t             memoryspi_object;
    cy_stc_smif_context_t           context;
 
    // Initialize MEMORYSPI peripheral with appropriate GPIOs
    result = mtb_hal_memoryspi_setup(&memoryspi_object, &configurator_cfg, &context);
 
    // Perform needed transfers with memory A
 
    // Configure pins for memory B
    result =
        mtb_hal_memoryspi_chip_configure(&memoryspi_object, MTB_HAL_MEMORYSPI_CHIP_SELECT_0,
                                         MTB_HAL_MEMORYSPI_DATA_SELECT_0);
    // Make memory #1 chip select active
    result =
        mtb_hal_memoryspi_select_active_csel(&memoryspi_object, MTB_HAL_MEMORYSPI_CHIP_SELECT_1);
 
    // Perform needed transfers with memory B
 
    // Make memory A chip select active again
    result =
        mtb_hal_memoryspi_select_active_csel(&memoryspi_object, MTB_HAL_MEMORYSPI_CHIP_SELECT_0);

Usage of driver within devices with preinitialized hardware

Some devices execute code from external memory rather than internal memory and therefore at boot already initialize the Hardware to correctly enable read, write, execute operations from the MCU to the external memory. In these cases, the MemorySPI interface can still be used to interact with the same external memory on which code is executing from but special attention is needed to avoid impacting the normal code operation. In these cases, the SMIF interface will have already been configured and set to XIP mode. It is still possible to execute MMIO operations to other parts of the memory that are free. In order to do so, the APIs in this driver need to be stored in a different storage (either RAM or internal memory of the device) so that there is no risk of trying to access the external memory while it's actively engaged in a different operation.

Note

The linker scripts of the devices for which this is true already handle this and users do not need to perform additional changes to them, but should keep this information in mind for their own code. Since the hardware is already initialized the MemorySPI initialization can be simplified a bit:

    cy_rslt_t    result;
    mtb_hal_memoryspi_t memoryspi_object;
    cy_stc_smif_context_t       context;
 
    // Setup MEMORYSPI peripheral with configurator generated structure
    result = mtb_hal_memoryspi_setup(&memoryspi_object, &configurator_cfg, &context);
 

However, calling the PDL APIs for a second time as shown in

    cy_rslt_t    result;
    mtb_hal_memoryspi_t memoryspi_object;
    uint8_t      rx_buf[PACKET_SIZE];
    size_t       length = PACKET_SIZE;
    cy_stc_smif_context_t       context;
 
    // Initialize the SMIF using PDL call
    cy_en_smif_status_t pdl_res = Cy_SMIF_Init((MY_MEMORYSPI0_hal_config.base),
                                               (MY_MEMORYSPI0_hal_config.config), 10000,
                                               &context);
    // Setup MEMORYSPI peripheral with configurator generated structure
    result = mtb_hal_memoryspi_setup(&memoryspi_object, &configurator_cfg, &context);
 
    // Complete the set up of SMIF using PDL calls
    Cy_SMIF_SetDataSelect(memoryspi_object.base, (memoryspi_object.chip_select),
                          CY_SMIF_DATA_SEL0);
    Cy_SMIF_Enable(memoryspi_object.base, &context);
 
    result = mtb_hal_memoryspi_select_active_csel(&memoryspi_object,
                                                  (mtb_hal_memoryspi_chip_select_t)memoryspi_object.chip_select);
 
    // HAL API for read operation
    result =
        mtb_hal_memoryspi_read(&memoryspi_object, &device_specific_read_command, ADDRESS, rx_buf,
                               &length);

will not create issues as long as the configuration matches the one that was used to initially configure the hardware and there are no calls to Disable or Deinit the peripheral. since XIP mode and MMIO mode can coexist on the board there is no special handling needed to successfully run MMIO operations. For more details see SMIF XIP Initialization section of PDL documentation. It's important to note that only blocking apis are allowed in this mode.

API Reference
	MemorySPI HAL Results
	MemorySPI specific return codes.

Data Structures
struct	mtb_hal_memoryspi_command_t
	MemorySPI command settings. More...
struct	mtb_hal_memoryspi_command_t.instruction
struct	mtb_hal_memoryspi_command_t.address
struct	mtb_hal_memoryspi_command_t.mode_bits
struct	mtb_hal_memoryspi_command_t.dummy_cycles
struct	mtb_hal_memoryspi_command_t.data

Typedefs
typedef void(*	mtb_hal_memoryspi_event_callback_t) (void *callback_arg, mtb_hal_memoryspi_event_t event)
	Handler for MemorySPI callbacks.

Enumerations
enum	mtb_hal_memoryspi_bus_width_t {   MTB_HAL_MEMORYSPI_CFG_BUS_SINGLE = 1 ,   MTB_HAL_MEMORYSPI_CFG_BUS_DUAL = 2 ,   MTB_HAL_MEMORYSPI_CFG_BUS_QUAD = 4 ,   MTB_HAL_MEMORYSPI_CFG_BUS_OCTAL = 8 }
	MemorySPI Bus width. More...
enum	mtb_hal_memoryspi_size_t {   MTB_HAL_MEMORYSPI_CFG_SIZE_8 = 8 ,   MTB_HAL_MEMORYSPI_CFG_SIZE_16 = 16 ,   MTB_HAL_MEMORYSPI_CFG_SIZE_24 = 24 ,   MTB_HAL_MEMORYSPI_CFG_SIZE_32 = 32 }
	Address size in bits. More...
enum	mtb_hal_memoryspi_event_t {   MTB_HAL_MEMORYSPI_EVENT_NONE = 0 ,   MTB_HAL_MEMORYSPI_IRQ_TRANSMIT_DONE = 1 << 0 ,   MTB_HAL_MEMORYSPI_IRQ_RECEIVE_DONE = 1 << 1 }
	MemorySPI interrupt triggers. More...
enum	mtb_hal_memoryspi_datarate_t {   MTB_HAL_MEMORYSPI_DATARATE_SDR = 0 ,   MTB_HAL_MEMORYSPI_DATARATE_DDR = 1 }
	MemorySPI data rate. More...
enum	mtb_hal_memoryspi_chip_select_t {   MTB_HAL_MEMORYSPI_CHIP_SELECT_0 = 1u ,   MTB_HAL_MEMORYSPI_CHIP_SELECT_1 = 1u << 1 ,   MTB_HAL_MEMORYSPI_CHIP_SELECT_2 = 1u << 2 ,   MTB_HAL_MEMORYSPI_CHIP_SELECT_3 = 1u << 3 }
	MemorySPI Chip Select Each chip select is represented by an enumeration that has the bit corresponding to the chip select number set. More...
enum	mtb_hal_memoryspi_data_select_t {   MTB_HAL_MEMORYSPI_DATA_SELECT_0 = 0 ,   MTB_HAL_MEMORYSPI_DATA_SELECT_1 = 1 ,   MTB_HAL_MEMORYSPI_DATA_SELECT_2 = 2 ,   MTB_HAL_MEMORYSPI_DATA_SELECT_3 = 3 }
	The data line-selection options for a chip device. More...

Functions
cy_rslt_t	mtb_hal_memoryspi_setup (mtb_hal_memoryspi_t *obj, const mtb_hal_memoryspi_configurator_t *config, cy_stc_smif_context_t *context)
	Sets up a HAL instance to use the specified hardware resource. More...
uint32_t	mtb_hal_memoryspi_get_frequency (mtb_hal_memoryspi_t *obj)
	Get the actual frequency that MemorySPI is configured for. More...
cy_rslt_t	mtb_hal_memoryspi_chip_configure (mtb_hal_memoryspi_t *obj, const mtb_hal_memoryspi_chip_select_t csel, mtb_hal_memoryspi_data_select_t data_select)
	Configure data select pin for the specified memory. More...
cy_rslt_t	mtb_hal_memoryspi_select_active_csel (mtb_hal_memoryspi_t *obj, mtb_hal_memoryspi_chip_select_t csel)
	Selects an active chip select (CSEL) line from one of available and configured. More...
cy_rslt_t	mtb_hal_memoryspi_read (mtb_hal_memoryspi_t *obj, const mtb_hal_memoryspi_command_t *command, uint32_t address, void *data, size_t *length)
	Sends a command to initiate a read, waits for the command to be accepted then reads a block of data in a blocking fashion. More...
cy_rslt_t	mtb_hal_memoryspi_read_async (mtb_hal_memoryspi_t *obj, const mtb_hal_memoryspi_command_t *command, uint32_t address, void *data, size_t *length)
	Sends a command to initiate a read, waits for the command to be accepted then reads a block of data in a non-blocking fashion. More...
cy_rslt_t	mtb_hal_memoryspi_write (mtb_hal_memoryspi_t *obj, const mtb_hal_memoryspi_command_t *command, uint32_t address, const void *data, size_t *length)
	Sends a command to initiate a write, waits for the command to be accepted then writes a block of data in a blocking fashion. More...
cy_rslt_t	mtb_hal_memoryspi_write_async (mtb_hal_memoryspi_t *obj, const mtb_hal_memoryspi_command_t *command, uint32_t address, const void *data, size_t *length)
	Sends a command to initiate a write, waits for the command to be accepted then writes a block of data in a non-blocking fashion. More...
cy_rslt_t	mtb_hal_memoryspi_transfer (mtb_hal_memoryspi_t *obj, const mtb_hal_memoryspi_command_t *command, uint32_t address, const void *tx_data, size_t tx_size, void *rx_data, size_t rx_size)
	Send a command (and optionally data , if tx_buffer is specified) and get the response (and optionally data if trx_buffer is specified). More...
void	mtb_hal_memoryspi_register_callback (mtb_hal_memoryspi_t *obj, mtb_hal_memoryspi_event_callback_t callback, void *callback_arg)
	Register a MemorySPI event handler. More...
void	mtb_hal_memoryspi_enable_event (mtb_hal_memoryspi_t *obj, mtb_hal_memoryspi_event_t event, bool enable)
	Configure MemorySPI interrupt enablement. More...
cy_rslt_t	mtb_hal_memoryspi_process_interrupt (mtb_hal_memoryspi_t *obj)
	Process interrupts related related to a MemorySPI instance. More...
bool	mtb_hal_memoryspi_is_async_in_progress (mtb_hal_memoryspi_t *obj)
	Checks if an async operation is in progress. More...
bool	mtb_hal_memoryspi_is_busy (mtb_hal_memoryspi_t *obj)
	Checks if the specified MemorySPI peripheral is in use. More...

---

Data Structure Documentation

mtb_hal_memoryspi_command_t

struct mtb_hal_memoryspi_command_t

Data Fields
struct mtb_hal_memoryspi_command_t.instruction	instruction	Instruction structure.
struct mtb_hal_memoryspi_command_t.address	address	Address structure.
struct mtb_hal_memoryspi_command_t.mode_bits	mode_bits	Mode bits structure.
struct mtb_hal_memoryspi_command_t.dummy_cycles	dummy_cycles	Dummy cycles structure.
struct mtb_hal_memoryspi_command_t.data	data	Data structure.

mtb_hal_memoryspi_command_t.instruction

struct mtb_hal_memoryspi_command_t.instruction

Data Fields
mtb_hal_memoryspi_bus_width_t	bus_width	Bus width for the instruction.
mtb_hal_memoryspi_datarate_t	data_rate	Data rate SDR/DDR.
bool	two_byte_cmd	Defines whether cmd is 2-byte value, or 1-byte (if false)
uint16_t	value	Instruction value.
bool	disabled	Instruction phase skipped if disabled is set to true.

mtb_hal_memoryspi_command_t.address

struct mtb_hal_memoryspi_command_t.address

Data Fields
mtb_hal_memoryspi_bus_width_t	bus_width	Bus width for the address.
mtb_hal_memoryspi_datarate_t	data_rate	Data rate SDR/DDR.
mtb_hal_memoryspi_size_t	size	Address size.
bool	disabled	Address phase skipped if disabled is set to true.

mtb_hal_memoryspi_command_t.mode_bits

struct mtb_hal_memoryspi_command_t.mode_bits

Data Fields
mtb_hal_memoryspi_bus_width_t	bus_width	Bus width for mode bits
mtb_hal_memoryspi_datarate_t	data_rate	Data rate SDR/DDR.
mtb_hal_memoryspi_size_t	size	Mode bits size.
uint32_t	value	Mode bits value.
bool	disabled	Mode bits phase skipped if disabled is set to true.

mtb_hal_memoryspi_command_t.dummy_cycles

struct mtb_hal_memoryspi_command_t.dummy_cycles

Data Fields
mtb_hal_memoryspi_bus_width_t	bus_width	Bus width for mode bits
mtb_hal_memoryspi_datarate_t	data_rate	Data rate SDR/DDR.
uint32_t	dummy_count	Dummy cycles count.

mtb_hal_memoryspi_command_t.data

struct mtb_hal_memoryspi_command_t.data

Data Fields
mtb_hal_memoryspi_bus_width_t	bus_width	Bus width for data.
mtb_hal_memoryspi_datarate_t	data_rate	Data rate SDR/DDR.

Enumeration Type Documentation

mtb_hal_memoryspi_bus_width_t

enum mtb_hal_memoryspi_bus_width_t

MemorySPI Bus width.

Some parts of commands provide variable bus width.

Enumerator
MTB_HAL_MEMORYSPI_CFG_BUS_SINGLE	Normal SPI Mode.
MTB_HAL_MEMORYSPI_CFG_BUS_DUAL	Dual SPI Mode.
MTB_HAL_MEMORYSPI_CFG_BUS_QUAD	Quad SPI Mode.
MTB_HAL_MEMORYSPI_CFG_BUS_OCTAL	Octal SPI Mode.

mtb_hal_memoryspi_size_t

enum mtb_hal_memoryspi_size_t

Address size in bits.

Enumerator
MTB_HAL_MEMORYSPI_CFG_SIZE_8	8 bits address
MTB_HAL_MEMORYSPI_CFG_SIZE_16	16 bits address
MTB_HAL_MEMORYSPI_CFG_SIZE_24	24 bits address
MTB_HAL_MEMORYSPI_CFG_SIZE_32	32 bits address

mtb_hal_memoryspi_event_t

enum mtb_hal_memoryspi_event_t

MemorySPI interrupt triggers.

Enumerator
MTB_HAL_MEMORYSPI_EVENT_NONE	No event.
MTB_HAL_MEMORYSPI_IRQ_TRANSMIT_DONE	Async transmit done.
MTB_HAL_MEMORYSPI_IRQ_RECEIVE_DONE	Async receive done.

mtb_hal_memoryspi_datarate_t

enum mtb_hal_memoryspi_datarate_t

MemorySPI data rate.

Enumerator
MTB_HAL_MEMORYSPI_DATARATE_SDR	Single data rate.
MTB_HAL_MEMORYSPI_DATARATE_DDR	Double data rate.

mtb_hal_memoryspi_chip_select_t

enum mtb_hal_memoryspi_chip_select_t

MemorySPI Chip Select Each chip select is represented by an enumeration that has the bit corresponding to the chip select number set.

Enumerator
MTB_HAL_MEMORYSPI_CHIP_SELECT_0	The SMIF chip select 0
MTB_HAL_MEMORYSPI_CHIP_SELECT_1	The SMIF chip select 1
MTB_HAL_MEMORYSPI_CHIP_SELECT_2	The SMIF chip select 2
MTB_HAL_MEMORYSPI_CHIP_SELECT_3	The SMIF chip select 3

mtb_hal_memoryspi_data_select_t

enum mtb_hal_memoryspi_data_select_t

The data line-selection options for a chip device.

Enumerator
MTB_HAL_MEMORYSPI_DATA_SELECT_0	smif.spi_data[0] = DATA0, smif.spi_data[1] = DATA1, ..., smif.spi_data[7] = DATA7. This value is allowed for the SPI, DSPI, QSPI, dual QSPI, and octal SPI modes.
MTB_HAL_MEMORYSPI_DATA_SELECT_1	smif.spi_data[2] = DATA0, smif.spi_data[3] = DATA1. This value is only allowed for the SPI and DSPI modes.
MTB_HAL_MEMORYSPI_DATA_SELECT_2	smif.spi_data[4] = DATA0, smif.spi_data[5] = DATA1, ..., smif.spi_data[7] = DATA3. This value is only allowed for the SPI, DSPI, QSPI and dual QSPI modes.
MTB_HAL_MEMORYSPI_DATA_SELECT_3	smif.spi_data[6] = DATA0, smif.spi_data[7] = DATA1. This value is only allowed for the SPI and DSPI modes.

Function Documentation

mtb_hal_memoryspi_setup()

cy_rslt_t mtb_hal_memoryspi_setup	(	mtb_hal_memoryspi_t *	obj,
		const mtb_hal_memoryspi_configurator_t *	config,
		cy_stc_smif_context_t *	context
	)

Sets up a HAL instance to use the specified hardware resource.

This hardware resource must have already been configured via the PDL.

Parameters

[out]	obj	The HAL driver instance object. The caller must allocate the memory for this object, but the HAL will initialize its contents
[in]	config	The configurator-generated HAL config structure for this peripheral instance
[in]	context	The pointer to the context structure for the SMIF driver

Returns

the status of the HAL setup

mtb_hal_memoryspi_get_frequency()

uint32_t mtb_hal_memoryspi_get_frequency

(

mtb_hal_memoryspi_t *

obj

)

Get the actual frequency that MemorySPI is configured for.

Parameters

[in]

obj

The MemorySPI object

Returns

Frequency in MHz

mtb_hal_memoryspi_chip_configure()

cy_rslt_t mtb_hal_memoryspi_chip_configure	(	mtb_hal_memoryspi_t *	obj,
		const mtb_hal_memoryspi_chip_select_t	csel,
		mtb_hal_memoryspi_data_select_t	data_select
	)

Configure data select pin for the specified memory.

Multiple pins can be configured as MemorySPI chip select pins as well as IO pins may be (or may not be) shared and used to service multiple connected memories. This function can be called multiple times - each call for each additional memory. Please refer to device datasheet for details. Switching between configured chip select pins is done by mtb_hal_memoryspi_select_active_csel function. Unless modified with that function, the first CSEL pin provided as part of mtb_hal_memoryspi_setup is the default. Please refer to Code Snippet 5: Configuring multiple memories for example of configuration multiple memory devices and switching between them.

Note

IO pins can overlap between multiple memories.

Parameters

[in]	obj	The MemorySPI object to configure
[in]	csel	CSEL pin for which we want to configure the data select
[in]	data_select	Data select value we want to set for the csel

Returns

The status of pin configuration

mtb_hal_memoryspi_select_active_csel()

cy_rslt_t mtb_hal_memoryspi_select_active_csel	(	mtb_hal_memoryspi_t *	obj,
		mtb_hal_memoryspi_chip_select_t	csel
	)

Selects an active chip select (CSEL) line from one of available and configured.

Memories can be added with help of mtb_hal_memoryspi_chip_configure function.

Parameters

[in]	obj	The MemorySPI object to configure
[in]	csel	CSEL pin to be set as active

Returns

CY_RSLT_SUCCESS if slave select was switched successfully, otherwise - MTB_HAL_MEMORYSPI_RSLT_ERR_CANNOT_SWITCH_CSEL

mtb_hal_memoryspi_read()

cy_rslt_t mtb_hal_memoryspi_read	(	mtb_hal_memoryspi_t *	obj,
		const mtb_hal_memoryspi_command_t *	command,
		uint32_t	address,
		void *	data,
		size_t *	length
	)

Sends a command to initiate a read, waits for the command to be accepted then reads a block of data in a blocking fashion.

This will read either length bytes or the number of bytes that are currently available in the receive buffer, whichever is less, then return. The value pointed to by length will be updated to reflect the number of bytes that were actually read.

Parameters

[in]	obj	MemorySPI object
[in]	command	MemorySPI command
[in]	address	Address to access to
[out]	data	RX buffer
[in]	length	RX buffer length in bytes

Returns

The status of the read request

mtb_hal_memoryspi_read_async()

cy_rslt_t mtb_hal_memoryspi_read_async	(	mtb_hal_memoryspi_t *	obj,
		const mtb_hal_memoryspi_command_t *	command,
		uint32_t	address,
		void *	data,
		size_t *	length
	)

Sends a command to initiate a read, waits for the command to be accepted then reads a block of data in a non-blocking fashion.

This will transfer length bytes into the buffer pointed to by data in the background. When the requested quantity of data has been read, the MTB_HAL_MEMORYSPI_IRQ_RECEIVE_DONE event will be raised. See mtb_hal_memoryspi_register_callback and mtb_hal_memoryspi_enable_event.

Parameters

[in]	obj	MemorySPI object
[in]	command	MemorySPI command
[in]	address	Address to access to
[out]	data	RX buffer
[in]	length	RX buffer length in bytes

Returns

The status of the read request

mtb_hal_memoryspi_write()

cy_rslt_t mtb_hal_memoryspi_write	(	mtb_hal_memoryspi_t *	obj,
		const mtb_hal_memoryspi_command_t *	command,
		uint32_t	address,
		const void *	data,
		size_t *	length
	)

Sends a command to initiate a write, waits for the command to be accepted then writes a block of data in a blocking fashion.

This will write either length bytes or until the write buffer is full, whichever is less, then return. The value pointed to by length will be updated to reflect the number of bytes that were actually written. If length is 0, the function simply returns and does not send the command as for some memories the write commands has to be followed by at least one byte of data and otherwise the memory will be stuck in a perpetual busy state.

Parameters

[in]	obj	MemorySPI object
[in]	command	MemorySPI command
[in]	address	Address to access to
[in]	data	TX buffer
[in]	length	TX buffer length in bytes

Returns

The status of the write request

mtb_hal_memoryspi_write_async()

cy_rslt_t mtb_hal_memoryspi_write_async	(	mtb_hal_memoryspi_t *	obj,
		const mtb_hal_memoryspi_command_t *	command,
		uint32_t	address,
		const void *	data,
		size_t *	length
	)

Sends a command to initiate a write, waits for the command to be accepted then writes a block of data in a non-blocking fashion.

This will transfer length bytes into the tx buffer in the background. When the requested quantity of data has been queued in the transmit buffer, the MTB_HAL_MEMORYSPI_IRQ_TRANSMIT_DONE event will be raised. See mtb_hal_memoryspi_register_callback and mtb_hal_memoryspi_enable_event. If length is 0, the function simply returns and does not send the command as for some memories the write commands has to be followed by at least one byte of data and otherwise the memory will be stuck in a perpetual busy state.

Parameters

[in]	obj	MemorySPI object
[in]	command	MemorySPI command
[in]	address	Address to access to
[in]	data	TX buffer
[in]	length	TX buffer length in bytes

Returns

The status of the write request

mtb_hal_memoryspi_transfer()

cy_rslt_t mtb_hal_memoryspi_transfer	(	mtb_hal_memoryspi_t *	obj,
		const mtb_hal_memoryspi_command_t *	command,
		uint32_t	address,
		const void *	tx_data,
		size_t	tx_size,
		void *	rx_data,
		size_t	rx_size
	)

Send a command (and optionally data , if tx_buffer is specified) and get the response (and optionally data if trx_buffer is specified).

Can be used to send/receive device specific commands

Parameters

[in]	obj	MemorySPI object
[in]	command	MemorySPI command
[in]	address	Address to access to
[in]	tx_data	TX buffer
[in]	tx_size	TX buffer length in bytes
[out]	rx_data	RX buffer
[in]	rx_size	RX buffer length in bytes

Returns

The status of the transfer request

mtb_hal_memoryspi_register_callback()

void mtb_hal_memoryspi_register_callback	(	mtb_hal_memoryspi_t *	obj,
		mtb_hal_memoryspi_event_callback_t	callback,
		void *	callback_arg
	)

Register a MemorySPI event handler.

This function will be called when one of the events enabled by mtb_hal_memoryspi_enable_event occurs.

Parameters

[in]	obj	The MemorySPI object
[in]	callback	The callback handler which will be invoked when the interrupt fires
[in]	callback_arg	Generic argument that will be provided to the handler when called

mtb_hal_memoryspi_enable_event()

void mtb_hal_memoryspi_enable_event	(	mtb_hal_memoryspi_t *	obj,
		mtb_hal_memoryspi_event_t	event,
		bool	enable
	)

Configure MemorySPI interrupt enablement.

When an enabled event occurs, the function specified by mtb_hal_memoryspi_register_callback will be called.

Parameters

[in]	obj	The MemorySPI object
[in]	event	The MemorySPI event type
[in]	enable	True to turn on interrupts, False to turn off

mtb_hal_memoryspi_process_interrupt()

cy_rslt_t mtb_hal_memoryspi_process_interrupt

(

mtb_hal_memoryspi_t *

obj

)

Process interrupts related related to a MemorySPI instance.

Parameters

obj	HAL object for which the interrupt should be processed

Returns

CY_RSLT_SUCCESS if the interrupt was processed successfully; otherwise an error

mtb_hal_memoryspi_is_async_in_progress()

bool mtb_hal_memoryspi_is_async_in_progress

(

mtb_hal_memoryspi_t *

obj

)

Checks if an async operation is in progress.

Parameters

[in]

obj

The MemorySPI peripheral to check

Returns

Indication of whether a MemorySPI async operation is in progress

mtb_hal_memoryspi_is_busy()

bool mtb_hal_memoryspi_is_busy

(

mtb_hal_memoryspi_t *

obj

)

Checks if the specified MemorySPI peripheral is in use.

Parameters

[in]

obj

The MemorySPI peripheral to check

Returns

Indication of whether the MemorySPI is busy