PSOC E8XXGP Device Support Library

| PSOC E8XXGP Device Support Library

API Reference | Data Structures | Typedefs | Enumerations | Functions
MemorySPI (Memory Serial Peripheral Interface)
HAL API Reference » HAL Drivers

## 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)
};
mtb_hal_memoryspi_command_t::instruction
struct mtb_hal_memoryspi_command_t::@20 instruction
Instruction structure.
MTB_HAL_MEMORYSPI_CFG_SIZE_24
@ MTB_HAL_MEMORYSPI_CFG_SIZE_24
24 bits address
Definition: mtb_hal_memoryspi.h:170
MTB_HAL_MEMORYSPI_DATARATE_SDR
@ MTB_HAL_MEMORYSPI_DATARATE_SDR
Single data rate.
Definition: mtb_hal_memoryspi.h:185
MTB_HAL_MEMORYSPI_CFG_BUS_SINGLE
@ MTB_HAL_MEMORYSPI_CFG_BUS_SINGLE
Normal SPI Mode.
Definition: mtb_hal_memoryspi.h:159
mtb_hal_memoryspi_command_t
MemorySPI command settings.
Definition: mtb_hal_memoryspi.h:192

## 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);
mtb_hal_memoryspi_t::base
SMIF_Type * base
Base address for the SMIF.
Definition: mtb_hal_hw_types_memoryspi_smif.h:52
mtb_hal_memoryspi_t::chip_select
cy_en_smif_slave_select_t chip_select
Active chip select *‍/.
Definition: mtb_hal_hw_types_memoryspi_smif.h:53
mtb_hal_memoryspi_t
MemorySPI object.
Definition: mtb_hal_hw_types_memoryspi_smif.h:51
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.
Definition: mtb_hal_memoryspi.c:404
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 i...
Definition: mtb_hal_memoryspi.c:423
mtb_hal_memoryspi_chip_select_t
mtb_hal_memoryspi_chip_select_t
MemorySPI Chip Select Each chip select is represented by an enumeration that has the bit correspondin...
Definition: mtb_hal_memoryspi.h:238
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.
Definition: mtb_hal_memoryspi.c:335
cy_rslt_t
uint32_t cy_rslt_t
Provides the result of an operation as a structured bitfield.
Definition: cy_result.h:459
cy_stc_smif_context_t
The SMIF internal context data.
Definition: cy_smif.h:997
cy_en_smif_status_t
cy_en_smif_status_t
The SMIF API return values.
Definition: cy_smif.h:686
CY_SMIF_DATA_SEL0
@ CY_SMIF_DATA_SEL0
smif.spi_data[0] = DATA0, smif.spi_data[1] = DATA1, ..., smif.spi_data[7] = DATA7.
Definition: cy_smif.h:552
Cy_SMIF_SetDataSelect
void Cy_SMIF_SetDataSelect(SMIF_Type *base, cy_en_smif_slave_select_t slaveSelect, cy_en_smif_data_select_t dataSelect)
This function configures the data select option for a specific slave.
Definition: cy_smif.c:420
Cy_SMIF_Enable
void Cy_SMIF_Enable(SMIF_Type *base, cy_stc_smif_context_t *context)
Enables the operation of the SMIF block.
Definition: cy_smif.c:921
Cy_SMIF_Init
cy_en_smif_status_t Cy_SMIF_Init(SMIF_Type *base, cy_stc_smif_config_t const *config, uint32_t timeout, cy_stc_smif_context_t *context)
This function initializes the SMIF block as a communication block.
Definition: cy_smif.c:75

## 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;
}
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...
Definition: mtb_hal_memoryspi.c:679

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;
}
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...
Definition: mtb_hal_memoryspi.c:557

## 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);
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.
Definition: mtb_hal_memoryspi.c:390
MTB_HAL_MEMORYSPI_DATA_SELECT_0
@ MTB_HAL_MEMORYSPI_DATA_SELECT_0
smif.spi_data[0] = DATA0, smif.spi_data[1] = DATA1, ..., smif.spi_data[7] = DATA7.
Definition: mtb_hal_memoryspi.h:252
MTB_HAL_MEMORYSPI_CHIP_SELECT_0
@ MTB_HAL_MEMORYSPI_CHIP_SELECT_0
The SMIF chip select 0
Definition: mtb_hal_memoryspi.h:239
MTB_HAL_MEMORYSPI_CHIP_SELECT_1
@ MTB_HAL_MEMORYSPI_CHIP_SELECT_1
The SMIF chip select 1
Definition: mtb_hal_memoryspi.h:240

# 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