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

Table of Contents

Block Media QSPI Framework Module Introduction

The Block Media Framework Module can implement the QSPI channel for reading, writing and controlling the QSPI Flash memory peripheral through the r_qspi driver. The driver has all the functionality needed to interface with a file system through a block media interface.

Block Media QSPI Framework Module Features

  • Supports QSPI channel interface for QSPI flash memory device.
  • Support file system on QSPI flash memory.
block_media_qspi_BD.png
Block Media QSPI Framework Module Block Diagram

Block Media QSPI Framework Module APIs Overview

The Block Media QSPI Framework module defines APIs to open, control, read and write to the media.  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.

Block Media QSPI Framework Module API Summary

Function Name Example API Call and Description
open g_sf_block_media_qspi0.p_api->open (g_sf_block_media_qspi0.p_ctrl, g_sf_block_media_qspi0.p_cfg);
Open a device channel for read/write and control.
read g_sf_block_media_qspi0.p_api->read (g_sf_block_media_qspi0.p_ctrl, p_dest, start_block, block_count);
Read data from a media channel.
write g_sf_block_media_qspi0.p_api->write (g_sf_block_media_qspi0.p_ctrl, p_src, start_block, block_count);
Write data to a media channel.
ioctl g_sf_block_media_qspi0.p_api->ioctl (g_sf_block_media_qspi0.p_ctrl, command, p_data);
Send control commands to and receives the status from the media port.
close g_sf_block_media_qspi0.p_api->close (g_sf_block_media_qspi0.p_ctrl);
Close the open media channel.
versionGet g_sf_block_media_qspi0.p_api->versionGet(&version);
Return the version of the driver 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 API Call Successful.
SSP_ERR_INVALID_ARGUMENT Parameter has invalid value.
SSP_ERR_INTERNAL An internal TheadX error has occurred.
SSP_ERR_NOT_OPEN Unit is not open.
SSP_ERR_ASSERTION The parameter p_ctrl or p_sample is NULL.
SSP_ERR_IN_USE Peripheral is still running in another mode; perform Close first.
SSP_ERR_UNSUPPORTED Command not supported.
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 QSPI Framework Module Operational Overview

The Block Media Framework Interface is simply an abstract interface using function pointers instead of direct function calls. Functions are called between FileX and the SSP block media drivers, such as the SDMMC, SPI Flash and SDRAM/RAM. The interface remains the same for any media driver so all media drivers appear functionally identical at file I/O layer and can be interchanged with one another without changing code. Device adaptation drivers, such as sf_block_media_qspi, are accessed through the Block Media Framework Interface and provide device specific code needed to perform media I/O operations. Configuration and control structures passed through block media function calls are generally device specific as well.

Block Media QSPI Framework Module Important Operational Notes and Limitations

Block Media QSPI Framework Module Operational Notes

  • The media must be formatted at least once before you can begin creating, writing and reading files.

Block Media QSPI Framework Module Limitations

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

Including the Block Media QSPI Framework Module in an Application

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

Block Media QSPI Framework Module Selection Sequence

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

When the Block Media QSPI Framework on sf_block_media_qspi 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.

block_media_qspi_MS.png
Block Media QSPI Framework Module Stack

Configuring the Block Media QSPI Framework Module

The Block Media QSPI 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 QSPI Framework Module on sf_block_media_qspi

ISDE Property Value Description
Parameter Checking BSP, Enabled, Disabled

Default: BSP 		Enable or disable the parameter checking.
Name g_sf_block_media_qspi Module name.
Block size of media in bytes 4096 Block size selection.
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 QSPI Framework Module 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 		Enable or disable the parameter checking.
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 QSPI Framework Module Clock Configuration

The Block Media QSPI Framework module uses the PCLKA as its clock source.

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

Block Media QSPI Framework Module Pin Configuration

To use the Block Media QSPI Framework module, the port pins for the peripheral inputs and outputs must be set in the pin configurator in the ISDE. The following table illustrates the method for selecting the pins within the ISDE configuration window:

Pin Selection for the Block Media QSPI Framework Module on sf_block_media_qspi

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

Using the Block Media QSPI Framework Module in an Application

The steps in using the Block Media QSPI Framework module on sf_block_media_qspi in a typical application are:

  1. Initialize the media using the FileX API fx_system_initialize (sf_el_fx calls it automatically).
  2. Format the media using FileX API 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)
  3. Open the media using the FileX API fx_media_open (sf_el_fx opens the media automatically).
  4. Read the media as required using the sf_block_media_api_t::read API (Block Media Framework) or one of the FileX APIs, for example, fx_media_read(), fx_file_read().
  5. Write to the media as required using the sf_block_media_api_t::write API (Block Media Framework) or one of the FileX APIs, for example, fx_media_write(), fx_file_write().

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

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