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.

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.

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.

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.

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.

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.

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.

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.

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_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.

General Description

Secure Aware SMIF

Data Structures

Macros

Functions

Data Structure Documentation

◆ cy_stc_smif_mem_context_t

◆ cy_stc_smif_hyb_sectors_info_t

◆ cy_stc_smif_mem_info_t

Function Documentation

◆ Cy_SMIF_MemNumInit()

◆ Cy_SMIF_MemNumGetInfo()

◆ Cy_SMIF_MemNumRead()

◆ Cy_SMIF_MemNumWrite()

◆ Cy_SMIF_MemNumEraseSector()

◆ Cy_SMIF_MemNumEraseChip()

◆ Cy_SMIF_MemNumHyperBusRead()

◆ Cy_SMIF_MemNumHyperBusWrite()