Synergy Software Package User's Manual
LevelX Port Framework on sf_el_lx_nor

Table of Contents

Port LevelX Framework Module Introduction

The Port LevelX Framework implements the driver APIs (sector read, sector write, block erase and block erased verify) mandated by Azure RTOS LevelX NOR component. In addition to implementing the LevelX NOR driver method, it is also responsible for updating the flash geometry to perform LevelX NOR initialization. It uses the sf_memory_api implementation to perform operations on the NOR flash.

Unsupported Features

LevelX NAND is not supported in this version of SSP.

Port LevelX Framework Module Features

  • Implements LevelX NOR driver APIs to perform operations on NOR flash memory device.
  • Set up NOR flash geometry.
sf_el_lx_nor_BD.png
Port LevelX Framework Module Block Diagram

Port LevelX Framework Module APIs Overview

The Port LevelX Framework defines API functions to open, read from, write to and close the module. A complete list of the available APIs, an example API call and a short description of each can be found in the following table. A table of status return values follows the API summary table.

Port LevelX Framework Module API Summary

Function Name Example API Call and Description
SF_EL_LX_NOR_Open g_sf_el_lx_nor0.p_api->SF_EL_LX_NOR_Open(g_sf_el_lx_nor0.p_ctrl, g_sf_el_lx_nor0.p_cfg);
Initializes lower-level driver initialization function.
SF_EL_LX_NOR_Read g_sf_el_lx_nor0.p_api->SF_EL_LX_NOR_Read(g_sf_el_lx_nor0.p_ctrl, p_flash, p_dest, word_count);
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.
SF_EL_LX_NOR_Write g_sf_el_lx_nor0.p_api->SF_EL_LX_NOR_Write(g_sf_el_lx_nor0.p_ctrl, p_flash, p_src, word_count);
This is responsible for writing a specific sector into a block of the NOR flash. All error checking is the responsibility of this service.
SF_EL_LX_NOR_BlockErase g_sf_el_lx_nor0.p_api->SF_EL_LX_NOR_BlockErase(g_sf_el_lx_nor0.p_ctrl, block, erase_count);
This is responsible for erasing the specified block of the NOR flash.
SF_EL_LX_NOR_BlockErasedVerify g_sf_el_lx_nor0.p_api->SF_EL_LX_NOR_BlockErasedVerify(g_sf_el_lx_nor0.p_ctrl, block);
This is responsible for verifying that the specified block of the NOR flash is erased.
SF_EL_LX_NOR_Close g_sf_el_lx_nor0.p_api->SF_EL_LX_NOR_Close(g_sf_el_lx_nor0.p_ctrl);
This is responsible for closing the driver properly.
Note
For more complete descriptions of operation and definitions for the function data structures, typedefs, defines, API data, API structures, and function variables, review the SSP User's Manual API References for the associated module.

Status Return Values

Name Description
SSP_SUCCESS API Call Successful
SSP_ERR_ASSERTION p_ctrl or p_cfg in NULL.
SSP_ERR_ALREADY_OPEN Driver is already in OPEN state.
SSP_ERR_INVALID_ARGUMENT Requested range can't fit in the flash address range.
SSP_ERR_NOT_OPEN Driver not in OPEN state for writing.
SSP_ERR_NOT_ERASED The block in not erased properly.
Note
Lower-level drivers may return common error codes. Refer to the SSP User's Manual API References for the associated module for a definition of all relevant status return values.

Port LevelX Framework Module Operational Overview

The Port LevelX Framework is simply an abstract interface using function pointers instead of direct function calls. Functions are called between LevelX or FileX and the SSP memory interface implementations such as sf_memory_qspi_nor. Memory adaptation drivers, such as sf_memory_qspi_nor, are accessed through the Port LevelX Framework and provide device specific code needed to perform data I/O operations.

Port LevelX Framework Module Important Operational Notes and Limitations

Port LevelX Framework Module Operational Notes

None.

Port LevelX Framework Module Limitations

Refer to the most recent SSP Release Notes for any additional operational limitations for this module.

Including the Port LevelX Framework Module in an Application

This section describes how to include the Port LevelX Framework Module in an application using the SSP configurator.

Note
This section assumes you are familiar with creating a project, adding threads, adding a stack to a thread and configuring a block within the stack. If you are unfamiliar with any of these items, refer to the first few chapters of the SSP User's Manual to learn how to manage each of these important steps in creating SSP-based applications.

To add the Port LevelX Framework to an application, simply add it to a thread using the stacks selection sequence given in the following table. (The default name for the Port LevelX Framework is g_sf_el_lx_nor0. This name can be changed in the associated Properties window.)

Port LevelX Framework Module Selection Sequence

Resource ISDE Tab Stacks Selection Sequence
g_sf_el_lx_nor0 Port LevelX Framework on sf_el_lx_nor Threads New Stack> Framework> LevelX> Port LevelX Framework on sf_el_lx_nor

When the Port LevelX Framework on sf_el_lx_nor is added to the thread stack as shown in the following figure, the configurator automatically adds any needed lower‑level modules. Any modules needing additional configuration information have the box text highlighted in Red. Modules with a Gray band are individual modules that stand alone. Modules with a Blue band are shared or common; they need only be added once and can be used by multiple stacks. Modules with a Pink band can require the selection of lower-level modules; these are either optional or recommended. (This is indicated in the block with the inclusion of this text.) If the addition of lower-level modules is required, the module description include Add in the text. Clicking on any Pink banded modules brings up the New icon and displays possible choices.

sf_el_lx_nor_MS.png
Port LevelX Framework Module Stack

Configuring the Port LevelX Framework Module

The Port LevelX Framework Module must be configured by the user for the desired operation. The available configuration settings and defaults for all the user-accessible properties are given in the properties tab within the SSP configurator and are shown in the following tables for easy reference. Only properties that can be changed without causing conflicts are available for modification. Other properties are locked and not available for changes and are identified with a lock icon for the locked property in the Properties window in the ISDE. This approach simplifies the configuration process and makes it much less error-prone than previous manual approaches to configuration. The available configuration settings and defaults for all the user-accessible properties are given in the Properties tab within the SSP Configurator and are shown in the following tables for easy reference.

Note
You may want to open your ISDE, create the module and explore the property settings in parallel with looking over the following configuration table settings. This will help orient you and can be a useful 'hands-on' approach to learning the ins and outs of developing with SSP.

Configuration Settings for the Port LevelX Framework Module on sf_el_lx_nor

ISDE Property Value Description
Parameter Checking BSP, Enabled, Disabled

Default: BSP 		Selects if code for parameter checking is to be included in the build.
Name g_sf_el_lx_nor0 Module name.
Event Callback NULL Name of the function to call when an event occurs.
Memory Partition Size Unit in (KB/MB) Kilobyte (KB), Megabyte (MB)
 
Default: Kilobyte (KB) 		The units of memory.
Memory Partition Size Positive Integer Number
 
Default: 0 		Size of the NOR Flash partition region.
 
 
Memory Partition Start Address(in hex format) Positive Integer Number in Hex
 
Default: 0x00000000 		The starting address of the partition region.
Note
The example settings and defaults are for a project using the Synergy S7G2 MCU Family. Other MCUs may have different default values and available configuration settings.

Configuration Settings for the Port LevelX Framework Lower-Level Modules

Typically, only a small number of settings must be modified from the default for lower level drivers as indicated via the red text in the thread stack block. Notice that some of the configuration properties must be set to a certain value for proper framework operation and will be locked to prevent user modification. The following tables identify all the settings within the properties section for the module.

Configuration Settings for the Memory Framework on sf_memory_qspi_nor

ISDE Property Value Description
Parameter Checking BSP, Enabled, Disabled
Default: BSP 		Selects if code for parameter checking is to be included in the build.
Name g_sf_memory_qspi_nor0 Module name.
Write of Erase Timeout (in ticks) 30000 Timeout ticks for waiting on write or erase to complete.
Note
The example settings and defaults are for a project using the Synergy S7G2 MCU Family. Other MCUs may have different default values and available configuration settings.

Configuration Settings for the QSPI HAL Module on r_qspi

ISDE Property Value Description
Parameter Checking BSP, Enabled, Disabled
Default: BSP 		Selects if code for parameter checking is to be included in the build.
Name g_qspi0 Module name.
Addressing Mode 3-BYTE, 4-BYTE
Default: 3-BYTE 		Addressing modes of flash memory
For memory > 16 MB, 4-Byte addressing mode should be selected
Note
The example settings and defaults are for a project using the Synergy S7G2 MCU Family. Other MCUs may have different default values and available configuration settings.

Port LevelX Framework Module Clock Configuration

The Port LevelX Framework module uses the QSPI peripheral which uses PCLKA as its clock source.

To change the clock frequency at run-time, use the CGC Interface.

Port LevelX Framework Module Pin Configuration

To use the Port LevelX Framework module, the port pins for the QSPI peripheral must be set as needed. The following table illustrates the method for selecting the pins within the ISDE configuration window:

Pin Selection for the Memory Framework Module on sf_memory_qspi_nor

Resource ISDE Tab Pin selection Sequence
QSPI Pins Select Peripherals> Storage:QSPI QSPI0

Using the Port LevelX Framework Module in an Application

The typical steps in using the Port LevelX Framework module in an application are:

1. Initialize the module using the lx_nor_flash_initialize API function (g_common_init calls it automatically).

2. Open the module for I/O operations using the LevelX NOR API function SF_EL_LX_NOR_Open (if using with FileX  fx_media_open opens the media automatically).

3. Read the media as required using the SF_EL_LX_NOR_Read API function (lx_nor_flash_sector_read calls this automatically).

4. Write to media as required using the SF_EL_LX_NOR_Write API function (lx_nor_flash_sector_write calls this automatically).

5. A block can be erased using the SF_EL_LX_NOR_BlockErase API function.

6. A block can be verified whether it is erase or not using the SF_EL_LX_NOR_BlockErasedVerify API function.

Note
After a successful SF_EL_LX_NOR_Open call, all LevelX NOR APIs can be used, not only read and write.

These common steps are illustrated in a typical operational flow diagram in the following figure:

sf_el_lx_nor_TA.png
Flow Diagram of a Typical Port LevelX Framework Module Application