Synergy Software Package User's Manual
Block Media Framework on sf_block_media_lx_nor

Table of Contents

Block Media Framework Module Introduction

The Block Media Framework on sf_block_media_lx_nor module provides a high-level API for interfacing with QSPI NOR flash memory devices. It provides API functions for reading, writing and controlling the QSPI NOR Flash memory. The framework includes the Azure RTOS wear leveling component LevelX NOR. The LevelX functions to support wear leveling are automatic and transparent to the developer. File system accesses, using the Azure RTOS FileX system, are also supported, making it easy to implement file system based applications.

Block Media Framework Module Features

  • Supports Block Media Framework interface for NOR flash memory device.
  • Supports file system access on NOR flash memory.
  • Supports LevelX wear leveling functions transparently to the developer.
sf_block_media_lx_nor_BD.png
Block Media Framework Module Block Diagram

Block Media Framework Module APIs Overview

The Block Media Framework module defines API functions to open, read from, write to and close the module. A complete list of the available API functions, 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.

Block Media Framework Module API Summary

Function Name Example API Call and Description
open   g_sf_block_media_lx_nor0.p_api->open(g_sf_block_media_lx_nor0.p_ctrl, g_sf_block_media_lx_nor0.p_cfg);
Open LevelX flash device for read/write and control. This function initializes the LevelX driver and hardware the first time it is called out of reset. The underlying flash needs to either be erased or already initialized with LevelX.
read g_sf_block_media_lx_nor0.p_api->read(g_sf_block_media_lx_nor0.p_ctrl, p_dest, start_sector, sector_count);
Read data from flash using LevelX.
write g_sf_block_media_lx_nor0.p_api->write(g_sf_block_media_lx_nor0.p_ctrl, p_src, start_sector, sector_count);
Write data to flash using LevelX.
ioctl g_sf_block_media_lx_nor0.p_api->ioctl(g_sf_block_media_lx_nor0.p_ctrl, command, p_data);
Send control commands to Block Media LevelX NOR driver.
close g_sf_block_media_lx_nor0.p_api->close(g_sf_block_media_lx_nor0.p_ctrl);
Close an open Block Media LevelX NOR driver.
versionGet g_sf_block_media_lx_nor0.p_api->versionGet(&version);
Return the version of the firmware and API using the version pointer.
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 LevelX flash is available and is now open for read, write and control access.
SSP_ERR_ASSERTION p_ctrl, p_cfg or an input pointer is NULL.
SSP_ERR_ALREADY_OPEN The block media LevelX NOR instance has already been opened. No configurations were changed. Call the associated Close function or use associated Control commands to reconfigure the instance.
SSP_ERR_MEDIA_OPEN_FAILED LevelX NOR or the underlying flash failed to open. The underlying flash needs to either be erased or already initialized with LevelX.
SSP_ERR_NOT_OPEN The block media is not open.
SSP_ERR_READ_FAILED Data read failed.
SSP_ERR_WRITE_FAILED Data write failed.
SSP_ERR_UNSUPPORTED This module does not support requested command.
SSP_ERR_SECTOR_RELEASE_FAILED Sector release command failed.
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.

Block Media Framework Module Operational Overview

The Block Media Framework on sf_block_media_lx_nor framework module provides a high-level API for interfacing with QSPI NOR flash memory devices while supporting wear leveling and file system operations. Wear leveling is implemented, transparently to the developer, using the Azure RTOS LevelX component within the SSP. File system support is implemented using the Azure RTOS FileX component, integrated with the SSP. These components work together to make it easy to support embedded applications that require QSPI NOR Flash file system operations.

The Block Media Framework provides API functions for reading, writing and controlling the QSPI NOR Flash memory. In addition to these functions, all FileX related API functions become available once the Block Media Framework module is successfully opened and initialized. Refer to the FileX User's Manual for a complete description of these functions.

The Block Media Framework module uses a standard interface that is common to other SSP media modules. For example, the modules that support SDMMC, SPI Flash and SDRAM/RAM memories use the same API calls, so the programming interface remains the same for any media driver. These modules can be interchanged with one another easily. Device adaptation drivers, such as r_qspi, are accessed through the Memory Framework interface and provide device specific code needed to perform media I/O operations. Configuration and control structures passed through memory interface function calls are generally device specific as well.

Block Media Framework Module Important Operational Notes and Limitations

Block Media Framework Module Operational Notes

The media must be erased and formatted before using sf_block_media_lx_nor for creating, writing and reading files.

Block Media Framework Module Limitations

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

Including the Block Media Framework Module in an Application

This section describes how to include the Block Media 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 Block Media 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 Block Media Framework is g_sf_block_media_lx_nor. This name can be changed in the associated Properties window.)

Block Media Framework Module Selection Sequence

Resource ISDE Tab Stacks Selection Sequence
g_sf_block_media_lx_nor0 Block Media Framework on sf_block_media_lx_nor Threads New Stack> Framework> File System> Block Media Framework on sf_block_media_lx_nor

When the Block Media Framework on sf_block_media_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 includes Add in the text. Clicking on any Pink banded modules brings up the New icon and displays possible choices.

sf_block_media_lx_nor_MS.png
Block Media Framework Module Stack

Configuring the Block Media Framework Module

The Block Media 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 Block Media Framework Module on sf_block_media_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_block_media_lx_nor0 Module name.
Note
The example settings and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

Configuration Settings for the Block Media 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 LevelX NOR Common Instance

ISDE Property Value Description
Name g_lx_nor0 Module name.
Note
The example settings and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

Configuration Settings for the LevelX Common Instance

ISDE Property Value Description
Thread Safety Enabled, Disabled

Default: Disabled 		If Enabled, this makes LevelX thread-safe by using a ThreadX mutex object throughout the API.
Note
The example settings and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

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.
Note
The example settings and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

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 Group. 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.
Note
The example settings and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

Block Media Framework Module Clock Configuration

The Block Media 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.

Block Media Framework Module Pin Configuration

To use the Block Media 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 Block Media Framework Module on sf_block_media_lx_nor

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

Using the Block Media Framework Module in an Application

The typical steps in using the Block Media Framework module in an application are:

1. Initialize the media using the FileX API function fx_system_initialize (sf_el_fx calls it automatically).

2. Initialize the LevelX NOR using the API function lx_nor_flash_initialize (g_common_init calls it automatically).

3. Format the media using the FileX API function fx_media_format (sf_el_fx calls it automatically if "Format media during initialization" property is set to Enabled). This Format media is optional if media has already been formatted. Anything on the media will erase while media format. (Optional)

4. Open the media using the FileX API function fx_media_open (sf_el_fx opens the media automatically).

5. Read the media as required using the sf_block_media_api_t::read API function (Block Media Framework) or one of the FileX API functions, for example, fx_media_read(), fx_file_read().

6. Write to the media as required using the sf_block_media_api_t::write API function (Block Media Framework) or one of the FileX API functions, for example, fx_media_write(), fx_file_write().

Note
  1. After a successful fx_media_open call, all FileX APIs can be used (not just read and write).
  2. If the media has been formatted by FileX without LevelX earlier, erase it using the qspi_api_t::erase API function before initializing the file media. The erase size should be not less than the size of the memory FileX uses. Users can disable the "Format media during initialization" property in the project configuration, erase the FileX media and then format it in the application.

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

sf_block_media_lx_nor_TA.png
Flow Diagram of a Typical Block Media Framework Module Application