RA Flexible Software Package Documentation  Release v5.2.0

 
LevelX NOR Port (rm_levelx_nor_spi)

Functions

fsp_err_t RM_LEVELX_NOR_SPI_Open (rm_levelx_nor_spi_instance_ctrl_t *const p_ctrl, rm_levelx_nor_spi_cfg_t const *const p_cfg)
 Initializes LevelX NOR SPI port read/write and control. More...
 
fsp_err_t RM_LEVELX_NOR_SPI_Read (rm_levelx_nor_spi_instance_ctrl_t *const p_ctrl, ULONG *const p_flash_addr, ULONG *const p_dest, ULONG word_count)
 LevelX NOR driver "read sector" service. More...
 
fsp_err_t RM_LEVELX_NOR_SPI_Write (rm_levelx_nor_spi_instance_ctrl_t *const p_ctrl, ULONG *const p_flash_addr, ULONG *const p_src, ULONG word_count)
 LevelX NOR driver "write sector" service. More...
 
fsp_err_t RM_LEVELX_NOR_SPI_BlockErase (rm_levelx_nor_spi_instance_ctrl_t *const p_ctrl, ULONG block, ULONG erase_count)
 LevelX NOR driver "block erase" service. More...
 
fsp_err_t RM_LEVELX_NOR_SPI_BlockErasedVerify (rm_levelx_nor_spi_instance_ctrl_t *const p_ctrl, ULONG block)
 LevelX NOR driver "block erased verify" service. More...
 
fsp_err_t RM_LEVELX_NOR_SPI_Close (rm_levelx_nor_spi_instance_ctrl_t *const p_ctrl)
 LevelX NOR driver close service. More...
 

Detailed Description

Middleware for using Azure RTOS LevelX on NOR SPI memory.

Overview

This module provides the hardware port layer for LevelX on NOR SPI flash memory. Setup for this module is done solely through calling LevelX APIs. Please refer to the LevelX API reference: https://docs.microsoft.com/en-us/azure/rtos/levelx/

Configuration

Build Time Configurations for rm_levelx_nor_spi

The following build time configurations are defined in fsp_cfg/middleware/rm_levelx_nor_spi_cfg.h:

ConfigurationOptionsDefaultDescription
Parameter Checking
  • Default (BSP)
  • Enabled
  • Disabled
Default (BSP) Selects if code for parameter checking is to be included in the build.
Write Verify
  • Enabled
  • Disabled
Disabled When enabled reads back data written to SPI memory in order to verify it.
Page Buffer Size (bytes)Size should be greater than zero256 When direct read is enabled in LevelX a situation can occur where the driver has to write to SPI memory with the source locaiton also being within the SPI memory address range. In this situation the driver needs a buffer that is at least the same size as a page in order to temporarily store data to write out.

Configurations for Storage > LevelX NOR Port (rm_levelx_nor_spi)

ConfigurationOptionsDefaultDescription
NameName must be a valid C symbolg_rm_levelx_nor_spi0 Module name.
Memory Start Adress Offset (bytes)Offset should be greater than or equal to zero0 Enter the starting offset to use in the SPI memory. The starting address for LevelX memory will be the SPI memory base address plus this offset.
Memory Size (bytes)Size should be greater than zero33554432 Enter the size that the LevelX Memory should be. This can be smaller than the SPI memory size in order to use a subset of SPI memory.
Poll Status CountPoll Status Count should be greater than or equal to zero0xFFFFFFFF Number of times to poll for operation complete status for blocking memory operations.

Build Time Configurations for lx

The following build time configurations are defined in fsp_cfg/azure/lx/lx_user.h:

ConfigurationOptionsDefaultDescription
NOR
Direct Read
  • Enabled (default)
  • Disabled
Enabled (default) When enabled, this option bypasses the NOR flash driver read routine in favor or reading the NOR memory directly, resulting in a significant performance increase.
Free Sector Data Verify
  • Enabled
  • Disabled (default)
Disabled (default) When enabled, this causes the LevelX NOR instance open logic to verify free NOR sectors are all ones.
Extended Cache
  • Enabled (default)
  • Disabled
Enabled (default) Enables the extended NOR cache.
Extended Cache SizeManual EntryIf not set this value defaults to 8, which represents a maximum of 8 sectors that can be cached in a NOR instance.
Sector Mapping Cache SizeValue must be greater than or equal to 8 and a power of 2, or emptyIf not set this value defaults to 16 and defines the logical sector mapping cache size. Large values improve performance, but cost memory. The minimum size is 8 and all values must be a power of 2.
NAND
Sector Mapping Cache SizeValue must be greater than or equal to 8 and a power of 2, or emptyIf not set this value defaults to 128 and defines the logical sector mapping cache size. Large values improve performance, but cost memory. The minimum size is 8 and all values must be a power of 2.
Flash Direct Mapping Cache
  • Enabled
  • Disabled (default)
Disabled (default) When enabled, this creates a direct mapping cache, such that there are no cache misses. It also required that LX_NAND_SECTOR_MAPPING_CACHE_SIZE represents the exact number of total pages in your flash device.
Thread Safe
  • Enabled
  • Disabled (default)
Disabled (default) When enabled, this makes LevelX thread-safe by using a ThreadX mutex object throughout the API.
Standalone Mode
  • Enabled
  • Disabled (default)
Disabled (default) When enabled, allows LevelX to be used in standalone mode (without Azure RTOS).

Usage Notes

Pending during Erase/Write

The LevelX NOR SPI driver is blocking on all SPI operations and will poll device status for operation completion on Writes and Erases. A callback can be provided by the user to wait with an OS-specific thread wait in these instances.

Closing the driver

When lx_nor_flash_close is called to close the LevelX instance it does not call any services within the LevelX NOR SPI driver to close out the driver instance. The user should call the generated close function (i.e. g_rm_levelx_nor_spi0_close) in order to close out the driver instance.

Erasing Flash Memory Prior to Usage

The area of the flash memory being used for the LevelX instance should be erased using the lower level flash API prior to usage. Otherwise, LevelX API may fail on lx_nor_flash_open due to any areas in flash memory that have been written/set.

Examples

Basic Example

This is a basic example of using the LevelX NOR SPI driver with the LevelX API in an application.

#define RM_LEVELX_NOR_SPI_EXAMPLE_SECTOR_SIZE (512)
#define RM_LEVELX_NOR_SPI_EXAMPLE_BUFFER_FILL_VALUE (0xA5)
#define RM_LEVELX_NOR_SPI_EXAMPLE_SPI_SECTOR_SIZE (4096)
extern rm_levelx_nor_spi_instance_ctrl_t g_levelx_nor_spi0_ctrl;
extern rm_levelx_nor_spi_cfg_t g_levelx_nor_spi0_cfg;
extern LX_NOR_FLASH g_lx_nor_flash0;
void rm_levelx_nor_spi_example (void)
{
uint8_t read_buffer[RM_LEVELX_NOR_SPI_EXAMPLE_SECTOR_SIZE];
uint8_t write_buffer[RM_LEVELX_NOR_SPI_EXAMPLE_SECTOR_SIZE];
spi_flash_instance_t * p_spi_flash_instance = (spi_flash_instance_t *) g_levelx_nor_spi0_cfg.p_lower_lvl;
memset(write_buffer, RM_LEVELX_NOR_SPI_EXAMPLE_BUFFER_FILL_VALUE, sizeof(write_buffer));
/* Erase flash prior to usage */
fsp_err_t err = p_spi_flash_instance->p_api->open(p_spi_flash_instance->p_ctrl, p_spi_flash_instance->p_cfg);
assert(FSP_SUCCESS == err);
for (uint32_t i = g_levelx_nor_spi0_cfg.address_offset;
i < g_levelx_nor_spi0_cfg.size;
i += RM_LEVELX_NOR_SPI_EXAMPLE_SPI_SECTOR_SIZE)
{
err = p_spi_flash_instance->p_api->erase(p_spi_flash_instance->p_ctrl,
(uint8_t *) g_levelx_nor_spi0_cfg.base_address + i,
RM_LEVELX_NOR_SPI_EXAMPLE_SPI_SECTOR_SIZE);
assert(FSP_SUCCESS == err);
status.write_in_progress = true;
while (status.write_in_progress)
{
err = p_spi_flash_instance->p_api->statusGet(p_spi_flash_instance->p_ctrl, &status);
assert(FSP_SUCCESS == err);
}
}
err = p_spi_flash_instance->p_api->close(p_spi_flash_instance->p_ctrl);
assert(FSP_SUCCESS == err);
/* Initialize LevelX */
lx_nor_flash_initialize();
UINT lx_err = lx_nor_flash_open(&g_lx_nor_flash0, "LX_NOR_SPI_EXAMPLE", g_levelx_nor_spi0_initialize);
handle_lx_error(lx_err);
/* Write test value to sector 0 then read back to verify */
lx_err = lx_nor_flash_sector_write(&g_lx_nor_flash0, 0, write_buffer);
handle_lx_error(lx_err);
lx_err = lx_nor_flash_sector_read(&g_lx_nor_flash0, 0, read_buffer);
handle_lx_error(lx_err);
assert(0 == memcmp(read_buffer, write_buffer, sizeof(read_buffer)));
}

Callback Wait Example

This shows how to use the LevelX NOR SPI driver callback with ThreadX in order to wait for operations to complete.

/* Callback called by LevelX NOR SPI driver needs to wait on operation. */
void rm_levelx_nor_spi_callback_wait_example (rm_levelx_nor_spi_callback_args_t * p_args)
{
{
/* Put the thread to sleep while waiting for operation to complete. */
tx_thread_sleep(1);
}
}

Data Structures

struct  rm_levelx_nor_spi_callback_args_t
 
struct  rm_levelx_nor_spi_cfg_t
 
struct  rm_levelx_nor_spi_instance_ctrl_t
 

Enumerations

enum  rm_levelx_nor_spi_event_t
 

Data Structure Documentation

◆ rm_levelx_nor_spi_callback_args_t

struct rm_levelx_nor_spi_callback_args_t

RM_LEVELX_NOR_SPI callback arguments definitions

Data Fields
rm_levelx_nor_spi_event_t event LevelX NOR driver callback event.
void const * p_context Placeholder for user data.

◆ rm_levelx_nor_spi_cfg_t

struct rm_levelx_nor_spi_cfg_t

SF_EL_LX_NOR Config Block Type

Data Fields

spi_flash_instance_t const * p_lower_lvl
 Lower level memory pointer.
 
LX_NOR_FLASH * p_lx_nor_flash
 Pointer to the LevelX nor flash instance.
 
uint32_t base_address
 Base address of memory mapped region.
 
uint32_t address_offset
 Offset to use subset of available flash size if desired.
 
uint32_t size
 Size of the partitioned region.
 
uint32_t poll_status_count
 Number of times to poll for operation complete status before returning an error.
 
void const * p_context
 Placeholder for user data. Passed to the user callback.
 
void(* p_callback )(rm_levelx_nor_spi_callback_args_t *p_args)
 Callback function.
 

◆ rm_levelx_nor_spi_instance_ctrl_t

struct rm_levelx_nor_spi_instance_ctrl_t

SF_EL_LX_NOR Control Block Type

Data Fields
rm_levelx_nor_spi_cfg_t const * p_cfg Pointer to instance configuration.
uint32_t start_address Start address of partition to use within memory mapped region.
uint32_t minimum_erase_size Minimum erase size of SPI memory.
uint8_t page_buffer[RM_LEVELX_NOR_SPI_CFG_BUFFER_SIZE] Page buffer for situations when writing to SPI memory from a source within SPI memory.
uint32_t open Used to determine if module is initialized.

Enumeration Type Documentation

◆ rm_levelx_nor_spi_event_t

Common macro for FSP header files. There is also a corresponding FSP_FOOTER macro at the end of this file. Options for the callback events.

Enumerator
RM_LEVELX_NOR_SPI_EVENT_BUSY 

Pending operation, user can define their own wait functionality.

Function Documentation

◆ RM_LEVELX_NOR_SPI_Open()

fsp_err_t RM_LEVELX_NOR_SPI_Open ( rm_levelx_nor_spi_instance_ctrl_t *const  p_ctrl,
rm_levelx_nor_spi_cfg_t const *const  p_cfg 
)

Initializes LevelX NOR SPI port read/write and control.

Calls lower level SPI memory functions.

Parameters
[in,out]p_ctrlControl block for the LevelX NOR SPI instance.
[in,out]p_cfgConfiguration for LevelX NOR SPI port.
Return values
FSP_SUCCESSLevelX NOR driver is successfully opened.
FSP_ERR_ASSERTIONp_ctrl or p_cfg is NULL.
FSP_ERR_ALREADY_OPENDriver is already in OPEN state.
Returns
See Common_Error_Codes or lower level drivers for other possible return codes. This function calls

◆ RM_LEVELX_NOR_SPI_Read()

fsp_err_t RM_LEVELX_NOR_SPI_Read ( rm_levelx_nor_spi_instance_ctrl_t *const  p_ctrl,
ULONG *const  p_flash_addr,
ULONG *const  p_dest,
ULONG  word_count 
)

LevelX NOR driver "read sector" service.

This is responsible for reading a specific sector in a specific block of the NOR flash. All error checking and correcting logic is the responsibility of this service.

Parameters
[in]p_ctrlControl block for the LevelX NOR SPI instance.
[in]p_flash_addrSpecifies the address of a logical sector within a NOR flash block of memory.
[in,out]p_destSpecifies where to place the sector contents.
[in]word_countSpecifies how many 32-bit words to read.
Return values
FSP_SUCCESSLevelX NOR flash sector read successful.
FSP_ERR_ASSERTIONp_ctrl, p_flash_addr or p_dest is NULL.
FSP_ERR_NOT_OPENDriver not in OPEN state for reading.
Returns
See Common_Error_Codes or lower level drivers for other possible return codes.

◆ RM_LEVELX_NOR_SPI_Write()

fsp_err_t RM_LEVELX_NOR_SPI_Write ( rm_levelx_nor_spi_instance_ctrl_t *const  p_ctrl,
ULONG *const  p_flash_addr,
ULONG *const  p_src,
ULONG  word_count 
)

LevelX NOR driver "write sector" service.

This is responsible for writing a specific sector into a block of the NOR flash. All error checking is the responsibility of the this service.

Parameters
[in]p_ctrlControl block for the LevelX NOR SPI instance.
[in,out]p_flash_addrSpecifies the address of a logical sector within a NOR flash block of memory.
[in]p_srcSpecifies the source of the write.
[in]word_countSpecifies how many 32-bit words to write.
Return values
FSP_SUCCESSLevelX NOR flash sector write successful.
FSP_ERR_ASSERTIONp_ctrl, p_flash_addr or p_src is NULL.
FSP_ERR_NOT_OPENDriver not in OPEN state for writing.
FSP_ERR_TIMEOUTTimeout occurred while waiting for operation to complete.
FSP_ERR_WRITE_FAILEDVerification of Write operation failed.
FSP_ERR_INVALID_ADDRESSWrite address or size falls outside of flash memory range.
Returns
See Common_Error_Codes or lower level drivers for other possible return codes. This function calls

◆ RM_LEVELX_NOR_SPI_BlockErase()

fsp_err_t RM_LEVELX_NOR_SPI_BlockErase ( rm_levelx_nor_spi_instance_ctrl_t *const  p_ctrl,
ULONG  block,
ULONG  erase_count 
)

LevelX NOR driver "block erase" service.

This is responsible for erasing the specified block of the NOR flash.

Parameters
[in]p_ctrlControl block for the LevelX NOR SPI instance.
[in]blockSpecifies which NOR block to erase.
[in]erase_countProvided for diagnostic purposes(currently unused).
Return values
FSP_SUCCESSLevelX NOR flash block erase successful.
FSP_ERR_ASSERTIONp_ctrl is NULL.
FSP_ERR_NOT_OPENDriver not in OPEN state for erasing.
FSP_ERR_TIMEOUTTimeout occurred while waiting for operation to complete.
Returns
See Common_Error_Codes or lower level drivers for other possible return codes. This function calls

◆ RM_LEVELX_NOR_SPI_BlockErasedVerify()

fsp_err_t RM_LEVELX_NOR_SPI_BlockErasedVerify ( rm_levelx_nor_spi_instance_ctrl_t *const  p_ctrl,
ULONG  block 
)

LevelX NOR driver "block erased verify" service.

This is responsible for verifying the specified block of the NOR flash is erased.

Parameters
[in]p_ctrlControl block for the LevelX NOR SPI instance.
[in]blockSpecifies which block to verify that it is erased.
Return values
FSP_SUCCESSLevelX flash block erase verification successful.
FSP_ERR_ASSERTIONp_ctrl or lower level driver is NULL.
FSP_ERR_NOT_OPENDriver not in OPEN state for verifying.
FSP_ERR_NOT_ERASEDThe block is not erased properly.
Returns
See Common_Error_Codes or lower level drivers for other possible return codes.

◆ RM_LEVELX_NOR_SPI_Close()

fsp_err_t RM_LEVELX_NOR_SPI_Close ( rm_levelx_nor_spi_instance_ctrl_t *const  p_ctrl)

LevelX NOR driver close service.

This is responsible for closing the driver properly.

Parameters
[in]p_ctrlControl block for the LevelX NOR SPI instance.
Return values
FSP_SUCCESSLevelX flash is available and is now open for read, write, and control access.
FSP_ERR_ASSERTIONp_ctrl is NULL.
FSP_ERR_NOT_OPENDriver not in OPEN state for closing.
Returns
See Common_Error_Codes or lower level drivers for other possible return codes. This function calls