PSOC E8XXGP Device Support Library

| PSOC E8XXGP Device Support Library

Data Structures | Macros | Functions
SMIFNUM (Serial MemoryNum Interface)
PDL API Reference

## General Description

# Secure Aware SMIF

Some SMIF APIs are marked as Secure Aware. This means that if the SMIF is marked as a secure resource in the Peripheral Protection Controller (PPC) and these APIs are called from a non-secure CPU state, the PDL will submit a request to the Secure Request Framework (SRF) middleware to transition to a secure CPU state to perform the operation. From the application's perspective, the API will behave the same whether it is called from a secure or non-secure CPU state albeit slower.

This functionality is automatically enabled on devices with ARM TrustZone processors. To disable, set the DEFINE+=CY_PDL_ENABLE_SECURE_AWARE_SMIF=0 in the application Makefile.

For more information on Secure Aware PDL behavior, see Secure Aware PDL.

## Data Structures
struct | cy_stc_smif_mem_context_t
| The SMIF Device internal context data. More...
struct | cy_stc_smif_hyb_sectors_info_t
| This structure specifies data relevant to the non-secure side relative to hybrid sectors. More...
struct | cy_stc_smif_mem_info_t
| This SMIF memory info structure is used to store the memory information that are useful to the non-secure side in Secure-Aware environments. More...

## Macros
#define | CY_SMIF_MAX_HYBRID_REGION (5U)
| Maximum number of hybrid regions in the supported external memories.
#define | CY_SMIF_SUB_BLOCK_0 (0UL)
| SMIF sub-block 0.
#define | CY_SMIF_SUB_BLOCK_1 (1UL)
| SMIF sub-block 1.
#define | CY_SMIF_FLAG_SPI_DEVICE (1UL)
| SMIF flag to identify regular SPI devices.
#define | CY_SMIF_FLAG_HYPERBUS_DEVICE (2UL)
| SMIF flag to identify HyperBus devices.

## Functions
cy_en_smif_status_t | Cy_SMIF_MemNumInit (SMIF_Type *base, cy_stc_smif_block_config_t const *blockConfig, cy_stc_smif_mem_context_t *context)
| This function initializes the slots of the memory device in the SMIF configuration. More...
cy_en_smif_status_t | Cy_SMIF_MemNumGetInfo (const cy_stc_smif_mem_context_t *context, uint8_t memNum, cy_stc_smif_mem_info_t *memNumInfo)
| This function is to be called from the non secure partition in trustzone devices to gather all information about the memory size, erase and program size to be used in subsequent MemNum calls instead of polling the secure partition repeatedly for the information. More...
cy_en_smif_status_t | Cy_SMIF_MemNumRead (cy_stc_smif_mem_context_t *context, uint8_t memNum, uint32_t address, uint8_t rxBuffer[], uint32_t length)
| Reads data from the external memory and blocks until the read transfer is complete or a timeout occurs. More...
cy_en_smif_status_t | Cy_SMIF_MemNumWrite (cy_stc_smif_mem_context_t *context, uint8_t memNum, uint32_t address, uint8_t const txBuffer[], uint32_t length)
| This function writes data to the external memory. More...
cy_en_smif_status_t | Cy_SMIF_MemNumEraseSector (cy_stc_smif_mem_context_t *context, uint8_t memNum, uint32_t address, uint32_t length)
| Erases a block/sector of the external memory. More...
cy_en_smif_status_t | Cy_SMIF_MemNumEraseChip (cy_stc_smif_mem_context_t *context, uint8_t memNum)
| Erases the entire chip of the external memory. More...
cy_en_smif_status_t | Cy_SMIF_MemNumHyperBusRead (cy_stc_smif_mem_context_t *context, uint8_t memNum, uint32_t address, uint8_t rxBuffer[], uint32_t length)
| This function reads data from hyper bus memory in MMIO mode. More...
cy_en_smif_status_t | Cy_SMIF_MemNumHyperBusWrite (cy_stc_smif_mem_context_t *context, uint8_t memNum, uint32_t address, uint8_t const txBuffer[], uint32_t length)
| This function writes data into hyper bus memory in MMIO mode. More...

## Data Structure Documentation

## ◆ cy_stc_smif_mem_context_t

struct cy_stc_smif_mem_context_t

Data Fields
SMIF_Type * | base | This stores the pointer to the base address of the SMIF instance.
cy_stc_smif_block_config_t const * | block_config | This stores the pointer to the block config where applicable.
cy_stc_smif_context_t | smif_context | This stores the info on the smif driver context.
bool | requires_secure_call | This specifies whether secure calls are needed.

## ◆ cy_stc_smif_hyb_sectors_info_t

struct cy_stc_smif_hyb_sectors_info_t

Data Fields
uint32_t | regionStartAddress | This specifies the address where a region starts.
uint32_t | regionEndAddress | This specifies the address where a region ends
uint32_t | eraseSize | This specifies the erase size of one sector.

## ◆ cy_stc_smif_mem_info_t

struct cy_stc_smif_mem_info_t

Data Fields
uint32_t | flags | Determines if the device is SPI/HyperBus.
uint32_t | memSize | The memory size: For densities of 2 gigabits or less - the size in bytes; For densities 4 gigabits and above - bit-31 is set to 1b to define that this memory is 4 gigabits and above; and other 30:0 bits define N where the density is computed as 2^N bytes. For example, 0x80000021 corresponds to 2^30 = 1 gigabyte.
uint32_t | eraseSize | This specifies the sector size of each Erase.
uint32_t | programSize | This specifies the page size for programming.
uint32_t | hybridRegionCount | This specifies the number of regions for memory with hybrid sectors.
cy_stc_smif_hyb_sectors_info_t | hybridRegionInfo[CY_SMIF_MAX_HYBRID_REGION] | This stores the information for the hybrid regions.

## Function Documentation

## ◆ Cy_SMIF_MemNumInit()

cy_en_smif_status_t Cy_SMIF_MemNumInit | ( | SMIF_Type * | base,
|  | cy_stc_smif_block_config_t const * | blockConfig,
|  | cy_stc_smif_mem_context_t * | context
| ) |  |

This function initializes the slots of the memory device in the SMIF configuration.

It's security aware and is a thin wrapper around Cy_SMIF_MemInit. It can either be called in a secure partition or in the non-secure partition if the peripheral itself is not secured.

Parameters

  base | The address of the slave-slot device register to initialize.
  blockConfig | The configuration structure array that configures the SMIF memory device to be mapped into the device's memory map. cy_stc_smif_mem_config_t
  context | This is the pointer to the context structure cy_stc_smif_mem_context_t allocated by the user. The structure is used during the SMIF operation for internal configuration and data retention. The user must not modify anything in this structure.

Returns
  The memory slot initialization status.
  - CY_SMIF_SUCCESS
  - CY_SMIF_BAD_PARAM
  - CY_SMIF_SFDP_SS0_FAILED
  - CY_SMIF_SFDP_SS1_FAILED
  - CY_SMIF_SFDP_SS2_FAILED
  - CY_SMIF_SFDP_SS3_FAILED

## ◆ Cy_SMIF_MemNumGetInfo()

cy_en_smif_status_t Cy_SMIF_MemNumGetInfo | ( | const cy_stc_smif_mem_context_t * | context,
|  | uint8_t | memNum,
|  | cy_stc_smif_mem_info_t * | memNumInfo
| ) |  |

This function is to be called from the non secure partition in trustzone devices to gather all information about the memory size, erase and program size to be used in subsequent MemNum calls instead of polling the secure partition repeatedly for the information.

Parameters

  context | This is the pointer to the context structure cy_stc_smif_mem_context_t allocated by the user. The structure is used during the SMIF operation for internal configuration and data retention. The user must not modify anything in this structure.
  memNum | The Slave Slot number associated to the memory in qspi-configurator to get information for.
  memNumInfo | This is the pointer to the info structure ot type cy_stc_smif_mem_info_t to populate.

Returns
  The memory slot initialization status.
  - CY_SMIF_SUCCESS

Note
  This API is Secure Aware. On devices with ARM TrustZone enabled, it is safe to call on a Secure hardware resource from a Non-Secure CPU state. See Secure Aware SMIF for further details. The involved PPC regions are SMIF<inst>_CORE_MAIN, SMIF<inst>_CORE_CRYPTO, SMIF<inst>_CORE_MAIN2, and SMIF<inst>_CORE_DEVICE. These four regions must have the same security state.
  Ensure that context and memNumInfo arguments are DCache aligned when calling from a non-secured Core onto a secured hardware resource. This is only relevent for cross-core calls, not calls between security contexts on the same core.

## ◆ Cy_SMIF_MemNumRead()

cy_en_smif_status_t Cy_SMIF_MemNumRead | ( | cy_stc_smif_mem_context_t * | context,
|  | uint8_t | memNum,
|  | uint32_t | address,
|  | uint8_t | rxBuffer[],
|  | uint32_t | length
| ) |  |

Reads data from the external memory and blocks until the read transfer is complete or a timeout occurs.

This is a blocking function, it will block the execution flow until the command transmission is completed. It is security aware.

Parameters

  context | This is the pointer to the context structure cy_stc_smif_mem_context_t allocated by the user. The structure is used during the SMIF operation for internal configuration and data retention. The user must not modify anything in this structure.
  memNum | The Slave Slot number associated to the memory in qspi-configurator to perform read operation on.
  address | The address to read data from. In case of Octal DDR, address must be an even address.
  rxBuffer | The buffer for storing the read data.
  length | The size of data to read.

Returns
  The status of the operation. See cy_en_smif_status_t.

Note
  This API is Secure Aware. On devices with ARM TrustZone enabled, it is safe to call on a Secure hardware resource from a Non-Secure CPU state. See Secure Aware SMIF for further details. When determining whether an address range is accessible or not, there is a limitation that only XIP mapped addresses are considered. So if only a portion of the external memory is memory mapped, the remaining portion will be considered secured. The involved PPC regions are SMIF<inst>_CORE_MAIN, SMIF<inst>_CORE_CRYPTO, SMIF<inst>_CORE_MAIN2, and SMIF<inst>_CORE_DEVICE. These four regions must have the same security state.
  Ensure that context and rxBuffer arguments are DCache aligned when calling from a non-secured Core onto a secured hardware resource. This is only relevent for cross-core calls, not calls between security contexts on the same core.

## ◆ Cy_SMIF_MemNumWrite()

cy_en_smif_status_t Cy_SMIF_MemNumWrite | ( | cy_stc_smif_mem_context_t * | context,
|  | uint8_t | memNum,
|  | uint32_t | address,
|  | uint8_t const | txBuffer[],
|  | uint32_t | length
| ) |  |

This function writes data to the external memory.

This is a blocking function, it will block the execution flow until the command transmission is completed. It is security aware.

Parameters

  context | This is the pointer to the context structure cy_stc_smif_mem_context_t allocated by the user. The structure is used during the SMIF operation for internal configuration and data retention. The user must not modify anything in this structure.
  memNum | The Slave Slot number associated to the memory in qspi-configurator to perform write operation on.
  address | The address to write data at. In case of Octal DDR, address must be an even address.
  txBuffer | The buffer holding the data to write in the external memory.
  length | The size of data to write.

Returns
  The status of the operation. See cy_en_smif_status_t.

Note
  This API is Secure Aware. On devices with ARM TrustZone enabled, it is safe to call on a Secure hardware resource from a Non-Secure CPU state. See Secure Aware SMIF for further details. When determining whether an address range is accessible or not, there is a limitation that only XIP mapped addresses are considered. So if only a portion of the external memory is memory mapped, the remaining portion will be considered secured. The involved PPC regions are SMIF<inst>_CORE_MAIN, SMIF<inst>_CORE_CRYPTO, SMIF<inst>_CORE_MAIN2, and SMIF<inst>_CORE_DEVICE. These four regions must have the same security state.
  Ensure that context and txBuffer arguments are DCache aligned when calling from a non-secured Core onto a secured hardware resource. This is only relevent for cross-core calls, not calls between security contexts on the same core.

## ◆ Cy_SMIF_MemNumEraseSector()

cy_en_smif_status_t Cy_SMIF_MemNumEraseSector | ( | cy_stc_smif_mem_context_t * | context,
|  | uint8_t | memNum,
|  | uint32_t | address,
|  | uint32_t | length
| ) |  |

Erases a block/sector of the external memory.

This is a blocking function, it will block the execution flow until the command transmission is completed.

Parameters

  context | This is the pointer to the context structure cy_stc_smif_mem_context_t allocated by the user. The structure is used during the SMIF operation for internal configuration and data retention. The user must not modify anything in this structure.
  memNum | The Slave Slot number associated to the memory in qspi-configurator to perform erase sector operation on.
  address | The address of the block to be erased. The address will be aligned to the start address of the sector in which address is located.
  length | The length of data to erase. The length will be aligned to the sector boundary where end address is located. If length exceeds memory size API returns CY_SMIF_BAD_PARAM without performing erase operation.

Returns
  The status of the operation. See cy_en_smif_status_t.

Note
  Memories like hybrid have sectors of different sizes.
  Check the address and length parameters before calling this function.
  This API is Secure Aware. On devices with ARM TrustZone enabled, it is safe to call on a Secure hardware resource from a Non-Secure CPU state. See Secure Aware SMIF for further details. When determining whether an address range is accessible or not, there is a limitation that only XIP mapped addresses are considered. So if only a portion of the external memory is memory mapped, the remaining portion will be considered secured. The involved PPC regions are SMIF<inst>_CORE_MAIN, SMIF<inst>_CORE_CRYPTO, SMIF<inst>_CORE_MAIN2, and SMIF<inst>_CORE_DEVICE. These four regions must have the same security state.
  Ensure that context argument is DCache aligned when calling from a non-secured Core onto a secured hardware resource. This is only relevent for cross-core calls, not calls between security contexts on the same core.

## ◆ Cy_SMIF_MemNumEraseChip()

cy_en_smif_status_t Cy_SMIF_MemNumEraseChip | ( | cy_stc_smif_mem_context_t * | context,
|  | uint8_t | memNum
| ) |  |

Erases the entire chip of the external memory.

This is a blocking function, it will block the execution flow until the command transmission is completed.

Parameters

  context | This is the pointer to the context structure cy_stc_smif_mem_context_t allocated by the user. The structure is used during the SMIF operation for internal configuration and data retention. The user must not modify anything in this structure.
  memNum | The Slave Slot number associated to the memory in qspi-configurator to perform erase sector operation on.

Returns
  The status of the operation. See cy_en_smif_status_t.

Note
  This API is Secure Aware. On devices with ARM TrustZone enabled, it is safe to call on a Secure hardware resource from a Non-Secure CPU state. See Secure Aware SMIF for further details. When determining whether an address range is accessible or not, there is a limitation that only XIP mapped addresses are considered. So if only a portion of the external memory is memory mapped, the remaining portion will be considered secured and therefore the EraseChip function will not be run. The involved PPC regions are SMIF<inst>_CORE_MAIN, SMIF<inst>_CORE_CRYPTO, SMIF<inst>_CORE_MAIN2, and SMIF<inst>_CORE_DEVICE. These four regions must have the same security state.
  Ensure that context argument is DCache aligned when calling from a non-secured Core onto a secured hardware resource. This is only relevent for cross-core calls, not calls between security contexts on the same core.

## ◆ Cy_SMIF_MemNumHyperBusRead()

cy_en_smif_status_t Cy_SMIF_MemNumHyperBusRead | ( | cy_stc_smif_mem_context_t * | context,
|  | uint8_t | memNum,
|  | uint32_t | address,
|  | uint8_t | rxBuffer[],
|  | uint32_t | length
| ) |  |

This function reads data from hyper bus memory in MMIO mode.

It's security aware and is a thin wrapper around Cy_SMIF_HyperBus_Read.

Parameters

  context | This is the pointer to the context structure cy_stc_smif_mem_context_t allocated by the user. The structure is used during the SMIF operation for internal configuration and data retention. The user must not modify anything in this structure.
  memNum | The Slave Slot number associated to the memory in qspi-configurator to perform read operation on.
  address | The address to read data from. In case of Octal DDR, address must be an even address.
  rxBuffer | The buffer for storing the read data.
  length | The size of data to read.

Returns
  cy_en_smif_status_t

Note
  This API is Secure Aware. On devices with ARM TrustZone enabled, it is safe to call on a Secure hardware resource from a Non-Secure CPU state. See Secure Aware SMIF for further details. When determining whether an address range is accessible or not, there is a limitation that only XIP mapped addresses are considered. So if only a portion of the external memory is memory mapped, the remaining portion will be considered secured. The involved PPC regions are SMIF<inst>_CORE_MAIN, SMIF<inst>_CORE_CRYPTO, SMIF<inst>_CORE_MAIN2, and SMIF<inst>_CORE_DEVICE. These four regions must have the same security state.
  Ensure that context and rxBuffer arguments are DCache aligned when calling from a non-secured Core onto a secured hardware resource. This is only relevent for cross-core calls, not calls between security contexts on the same core.

## ◆ Cy_SMIF_MemNumHyperBusWrite()

cy_en_smif_status_t Cy_SMIF_MemNumHyperBusWrite | ( | cy_stc_smif_mem_context_t * | context,
|  | uint8_t | memNum,
|  | uint32_t | address,
|  | uint8_t const | txBuffer[],
|  | uint32_t | length
| ) |  |

This function writes data into hyper bus memory in MMIO mode.

It's security aware and is a thin wrapper around Cy_SMIF_HyperBus_Write.

Parameters

  context | This is the pointer to the context structure cy_stc_smif_mem_context_t allocated by the user. The structure is used during the SMIF operation for internal configuration and data retention. The user must not modify anything in this structure.
  memNum | The Slave Slot number associated to the memory in qspi-configurator to perform write operation on.
  address | The address to write data at. In case of Octal DDR, address must be an even address.
  txBuffer | The buffer holding the data to write in the external memory.
  length | The size of data to write.

Returns
  cy_en_smif_status_t

Note
  This API is Secure Aware. On devices with ARM TrustZone enabled, it is safe to call on a Secure hardware resource from a Non-Secure CPU state. See Secure Aware SMIF for further details. When determining whether an address range is accessible or not, there is a limitation that only XIP mapped addresses are considered. So if only a portion of the external memory is memory mapped, the remaining portion will be considered secured. The involved PPC regions are SMIF<inst>_CORE_MAIN, SMIF<inst>_CORE_CRYPTO, SMIF<inst>_CORE_MAIN2, and SMIF<inst>_CORE_DEVICE. These four regions must have the same security state.
  Ensure that context and txBuffer arguments are DCache aligned when calling from a non-secured Core onto a secured hardware resource. This is only relevent for cross-core calls, not calls between security contexts on the same core.