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:

Configuration	Options	Default	Description
Parameter Checking	Default (BSP) Enabled Disabled	Default (BSP)	Selects if code for parameter checking is to be included in the build.
Page Buffer Size (bytes)	Size should be greater than zero	256	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)

Configuration	Options	Default	Description
Name	Name must be a valid C symbol	g_rm_levelx_nor_spi0	Module name.
Memory Start Adress Offset (bytes)	Offset should be greater than or equal to zero	0	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 zero	33554432	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 Count	Poll Status Count should be greater than or equal to zero	0xFFFFFFFF	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:

Configuration	Options	Default	Description
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 Size	Manual Entry		If 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 Size	Value must be greater than or equal to 8 and a power of 2, or empty		If 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 Size	Value must be greater than or equal to 8 and a power of 2, or empty		If 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;
    spi_flash_status_t     status;
    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)
{
    if (p_args->event & RM_LEVELX_NOR_SPI_EVENT_BUSY)
    {
        /* 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

enum 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_ctrl	Control block for the LevelX NOR SPI instance.
[in,out]	p_cfg	Configuration for LevelX NOR SPI port.

Return values

FSP_SUCCESS	LevelX NOR driver is successfully opened.
FSP_ERR_ASSERTION	p_ctrl or p_cfg is NULL.
FSP_ERR_ALREADY_OPEN	Driver is already in OPEN state.

Returns

See Common_Error_Codes or lower level drivers for other possible return codes. This function calls

spi_flash_api_t:open

◆ 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_ctrl	Control block for the LevelX NOR SPI instance.
[in]	p_flash_addr	Specifies the address of a logical sector within a NOR flash block of memory.
[in,out]	p_dest	Specifies where to place the sector contents.
[in]	word_count	Specifies how many 32-bit words to read.

Return values

FSP_SUCCESS	LevelX NOR flash sector read successful.
FSP_ERR_ASSERTION	p_ctrl, p_flash_addr or p_dest is NULL.
FSP_ERR_NOT_OPEN	Driver 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_ctrl	Control block for the LevelX NOR SPI instance.
[in,out]	p_flash_addr	Specifies the address of a logical sector within a NOR flash block of memory.
[in]	p_src	Specifies the source of the write.
[in]	word_count	Specifies how many 32-bit words to write.

Return values

FSP_SUCCESS	LevelX NOR flash sector write successful.
FSP_ERR_ASSERTION	p_ctrl, p_flash_addr or p_src is NULL.
FSP_ERR_NOT_OPEN	Driver not in OPEN state for writing.
FSP_ERR_TIMEOUT	Timeout occurred while waiting for operation to complete.
FSP_ERR_WRITE_FAILED	Verification of Write operation failed.
FSP_ERR_INVALID_ADDRESS	Write 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

spi_flash_api_t:write

◆ 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_ctrl	Control block for the LevelX NOR SPI instance.
[in]	block	Specifies which NOR block to erase.
[in]	erase_count	Provided for diagnostic purposes(currently unused).

Return values

FSP_SUCCESS	LevelX NOR flash block erase successful.
FSP_ERR_ASSERTION	p_ctrl is NULL.
FSP_ERR_NOT_OPEN	Driver not in OPEN state for erasing.
FSP_ERR_TIMEOUT	Timeout occurred while waiting for operation to complete.

Returns

See Common_Error_Codes or lower level drivers for other possible return codes. This function calls

spi_flash_api_t:erase

◆ 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_ctrl	Control block for the LevelX NOR SPI instance.
[in]	block	Specifies which block to verify that it is erased.

Return values

FSP_SUCCESS	LevelX flash block erase verification successful.
FSP_ERR_ASSERTION	p_ctrl or lower level driver is NULL.
FSP_ERR_NOT_OPEN	Driver not in OPEN state for verifying.
FSP_ERR_NOT_ERASED	The 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_ctrl Control block for the LevelX NOR SPI instance.

Return values

FSP_SUCCESS	LevelX flash is available and is now open for read, write, and control access.
FSP_ERR_ASSERTION	p_ctrl is NULL.
FSP_ERR_NOT_OPEN	Driver not in OPEN state for closing.

Returns

See Common_Error_Codes or lower level drivers for other possible return codes. This function calls

spi_flash_api_t:close

Functions

Detailed Description

Overview

Configuration

Build Time Configurations for rm_levelx_nor_spi

Configurations for Storage > LevelX NOR Port (rm_levelx_nor_spi)

Build Time Configurations for lx

Usage Notes

Pending during Erase/Write

Closing the driver

Erasing Flash Memory Prior to Usage

Examples

Basic Example

Callback Wait Example

Data Structures

Enumerations

Data Structure Documentation

◆ rm_levelx_nor_spi_callback_args_t

◆ rm_levelx_nor_spi_cfg_t

Data Fields

◆ rm_levelx_nor_spi_instance_ctrl_t

Enumeration Type Documentation

◆ rm_levelx_nor_spi_event_t

Function Documentation

◆ RM_LEVELX_NOR_SPI_Open()

◆ RM_LEVELX_NOR_SPI_Read()

◆ RM_LEVELX_NOR_SPI_Write()

◆ RM_LEVELX_NOR_SPI_BlockErase()

◆ RM_LEVELX_NOR_SPI_BlockErasedVerify()

◆ RM_LEVELX_NOR_SPI_Close()