Memory Framework on sf_memory_qspi_nor

Table of Contents

• Memory Framework Module Introduction
  • Memory Framework Module Features
• Memory Framework Module APIs Overview
• Memory Framework Module Operational Overview
  • Memory Framework Module Important Operational Notes and Limitations
    • Memory Framework Module Operational Notes
    • Memory Framework Module Limitations
• Including the Memory Framework Module in an Application
• Configuring the Memory Framework Module
  • Configuration Settings for the Memory Framework Lower-Level Modules
  • Memory Framework Module Clock Configuration
  • Memory Framework Module Pin Configuration
• Using the Memory Framework Module in an Application

Memory Framework Module Introduction

The Memory Framework on sf_memory_qspi_nor module provides a high-level API for interfacing with QSPI NOR memory devices. It provides API functions for reading, writing, and erasing data in QSPI NOR Flash memory.  The Memory Framework on sf_memory_qspi_nor module is also used by the higher-level Port LevelX Framework on sf_el_lx_nor framework module when support for LevelX wear leveling is required.

Memory Framework Module Features

• Supports memory interface for QSPI NOR flash memory device.
• Supports I/O Operations on QSPI NOR flash memory device.
  • Read
  • Write
  • Erase

Memory Framework Module Block Diagram

Memory Framework Module APIs Overview

The Memory Framework module defines API functions to read, write and erase QSPI NOR flash memory devices. 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.

Memory Framework Module API Summary

Function Name	Example API Call and Description
open	g_sf_memory_qspi_nor0.p_api->open(g_sf_memory_qspi_nor0.p_ctrl, g_sf_memory_qspi_nor0.p_cfg); Open the SF Memory QSPI NOR driver module for the purposes of reading and writing flash memory.
close	g_sf_memory_qspi_nor0.p_api->close(g_sf_memory_qspi_nor0.p_ctrl); Close the Memory QSPI NOR driver module.
read	g_sf_memory_qspi_nor0.p_api->read(g_sf_memory_qspi_nor0.p_ctrl, p_dest_address, memory_address, num_bytes); Read specified number of bytes of data from a particular address on the QSPI flash device.
write	g_sf_memory_qspi_nor0.p_api->write(g_sf_memory_qspi_nor0.p_ctrl, p_src_address, memory_address, num_bytes); Program data to the flash.
flush	g_sf_memory_qspi_nor0.p_api->flush(g_sf_memory_qspi_nor0.p_ctrl); Flush any pending data to the disk. This is not required for QSPI NOR flash.
erase	g_sf_memory_qspi_nor0.p_api->erase(g_sf_memory_qspi_nor0.p_ctrl, memory_address, num_bytes); Erase a number of bytes from the flash.
infoGet	g_sf_memory_qspi_nor0.p_api->infoGet(g_sf_memory_qspi_nor0.p_ctrl, p_info); Returns the information about the flash.
versionGet	g_sf_memory_qspi_nor0.p_api->versionGet(&version); Get the driver version based on compile time macros.

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	Configuration was successful.
SSP_ERR_ASSERTION	The parameter p_ctrl or p_cfg is NULL.
SSP_ERR_ALREADY_OPEN	Driver is already open.
SSP_ERR_NOT_OPEN	Driver is not opened.
SSP_ERR_INVALID_ARGUMENT	Number of bytes requested is invalid.
SSP_ERR_TIMEOUT	Wait timed out.

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.

Memory Framework Module Operational Overview

The Memory Framework module supports memory data transfers for a QSPI memory. High-level API functions are available to open, read, write, erase and close the module. If LevelX support is needed, the higher-level Port LevelX Framework on sf_el_lx_nor framework module can be used in conjunction with this module.

The Memory Framework module uses a standard interface that is common for 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.

A user-defined delay callback function can be specified to fine tune the amount of time to wait before starting to poll the QSPI chip after a write or erase operation. This option is provided since there is a large variation in the delay that could be required for a QSPI operation to complete and it varies from chip to chip.

If the delay callback is not specified, then the QSPI driver sleeps for one tick, before polling the status again.

The number of ticks to wait before a timeout error occurs, on a chip erase or write, can be specified in the "Write or Erase Timeout" field. The default is set to 30,000 ticks.

Memory Framework Module Important Operational Notes and Limitations

Memory Framework Module Operational Notes

The media must be erased before using sf_memory_qspi_nor for I/O operations.

Memory Framework Module Limitations

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

Including the Memory Framework Module in an Application

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

Memory Framework Module Selection Sequence

Resource	ISDE Tab	Stacks Selection Sequence
g_sf_memory_qspi_nor0 Memory Framework on sf_memory_qspi_nor	Threads	New Stack> Framework> Memory> Memory Framework on sf_memory_qspi_nor

When the Memory Framework on sf_memory_qspi_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.

Memory Framework Module Stack

Configuring the Memory Framework Module

The Memory 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 Memory Framework Module 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.
Delay Callback (Optional)	NULL	Callback used to add a delay between polling the QSPI chip.
Write or 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 Memory 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 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.

Memory Framework Module Clock Configuration

The Memory 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.

Memory Framework Module Pin Configuration

To use the Memory 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 Memory Framework Module in an Application

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

1. Initialize the instance using sf_memory_api_t::open API function.

2. Write data to QSPI flash using sf_memory_api_t::write API function.

3. Read data from QSPI flash using sf_memory_api_t::read API function.

4. Erase data from QSPI flash using sf_memory_api_t::erase API function.

5. Read QSPI flash information using sf_memory_api_t::infoGet API function.

6. Close the instance using sf_memory_api_t::close API function.

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

Flow Diagram of a Typical Memory Framework Module Application