QSPI Driver

Table of Contents

• QSPI HAL Module Introduction
  • QSPI HAL Module Features
  • QSPI Hardware Support Details
• QSPI HAL Module APIs Overview
• QSPI HAL Module Operational Overview
  • QSPI HAL Module Important Operational Notes and Limitations
  • QSPI HAL Module Operational Notes
  • QSPI HAL Module Limitations
• Including the QSPI HAL Module in an Application
• Configuring the QSPI HAL Module
  • QSPI HAL Module Pin Configuration
• Using the QSPI HAL Module in an Application

QSPI HAL Module Introduction

The Quad SPI (QSPI) HAL module provides a high-level API for erasing and programming the contents of a QSPI flash device connected to the microcontroller. Unlike many other modules, there is no callback function for the QSPI.

QSPI HAL Module Features

The QSPI HAL Module is used to initialize the QSPI peripheral that allows erasing and programming the contents of a QSPI flash device connected to the microcontroller over the Quad SPI interface. Key features include:

• Accessing Quad SPI flash devices using Direct Communication Mode
• Reading data from a QSPI flash device
• Programming the page of a QSPI flash device
• Erasing sectors of a QSPI flash device
• Selecting a bank to control access to a QSPI flash device
• Accessing Quad SPI flash devices using 3-byte/4-byte Addressing Mode

QSPI HAL Module Block Diagram

QSPI Hardware Support Details

The following hardware features are, or are not, supported by SSP for the QSPI.

Legend:

Symbol	Meaning
✓	Available (Tested)
⌧	Not Available (Not tested/not functional or both)
N/A	Not supported by MCU

MCU Group	Extended SPI	Dual SPI	Quad SPI	SPI Mode 0 & 3	Selectable Address (8, 16, 24, 32 bits) via SFMSAC register	Timing adjustment function
S124	N/A	N/A	N/A	N/A	N/A	N/A
S128	N/A	N/A	N/A	N/A	N/A	N/A
S1JA	N/A	N/A	N/A	N/A	N/A	N/A
S3A1	✓	⌧	⌧	Mode 0	3-byte and 4-byte addresses	⌧
S3A3	✓	⌧	⌧	Mode 0	3-byte and 4-byte addresses	⌧
S3A6	✓	⌧	⌧	Mode 0	3-byte and 4-byte addresses	⌧
S3A7	✓	⌧	⌧	Mode 0	3-byte and 4-byte addresses	⌧
S5D3	✓	⌧	⌧	Mode 0	3-byte and 4-byte addresses	⌧
S5D5	✓	⌧	⌧	Mode 0	3-byte and 4-byte addresses	⌧
S5D9	✓	⌧	⌧	Mode 0	3-byte and 4-byte addresses	⌧
S7G2	✓	⌧	⌧	Mode 0	3-byte and 4-byte addresses	⌧

MCU Group	Flash read function: Read	Flash read function: Fast Read	Flash read function: Fast Read/Dual Output	Flash read function: Fast Read/Dual I/O	Flash read function: Fast Read/Quad Output	Flash read function: Fast Read/Quad I/O
S124	N/A	N/A	N/A	N/A	N/A	N/A
S128	N/A	N/A	N/A	N/A	N/A	N/A
S1JA	N/A	N/A	N/A	N/A	N/A	N/A
S3A1	⌧	⌧	⌧	⌧	⌧	✓
S3A3	⌧	⌧	⌧	⌧	⌧	✓
S3A6	⌧	⌧	⌧	⌧	⌧	✓
S3A7	⌧	⌧	⌧	⌧	⌧	✓
S5D3	⌧	⌧	⌧	⌧	⌧	✓
S5D5	⌧	⌧	⌧	⌧	⌧	✓
S5D9	⌧	⌧	⌧	⌧	⌧	✓
S7G2	⌧	⌧	⌧	⌧	⌧	✓

MCU Group	Substitutable Instruction Code	Adjustment # of Dummy cycles	Prefetch Function	SPI bus cycle extension Function	Direct communication function	XIP
S124	N/A	N/A	N/A	N/A	N/A	N/A
S128	N/A	N/A	N/A	N/A	N/A	N/A
S1JA	N/A	N/A	N/A	N/A	N/A	N/A
S3A1	⌧	⌧	⌧	⌧	✓	✓
S3A3	⌧	⌧	⌧	⌧	✓	✓
S3A6	⌧	⌧	⌧	⌧	✓	✓
S3A7	⌧	⌧	⌧	⌧	✓	✓
S5D3	⌧	⌧	⌧	⌧	✓	✓
S5D5	⌧	⌧	⌧	⌧	✓	✓
S5D9	⌧	⌧	⌧	⌧	✓	✓
S7G2	⌧	⌧	⌧	⌧	✓	✓

QSPI HAL Module APIs Overview

The QSPI interface defines API functions for opening, closing, reading, writing, erasing, and device bank selection using the QSPI HAL 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.

QSPI HAL Module API Summary

Function Name	Example API Call and Description
open	g_qspi0.p_api->open(g_qspi0.p_ctrl, g_qspi0.p_cfg); Open the QSPI HAL module.
close	g_qspi0.p_api->close(g_qspi0.p_ctrl); Close the QSPI HAL module.
read	g_qspi0.p_api->read(g_qspi0.p_ctrl, (uint8_t *) QSPI_DEVICE_ADDRESS, readBuffer, BUFFER_LENGTH); Read data from the flash.
pageProgram	g_qspi0.p_api->pageProgram(g_qspi0.p_ctrl, (uint8_t *) QSPI_DEVICE_ADDRESS, writeBuffer, BUFFER_LENGTH); Program a page of data to the flash.
sectorErase	g_qspi0.p_api->sectorErase(g_qspi0.p_ctrl, (uint8_t *) QSPI_DEVICE_ADDRESS); Erase a sector on the flash.
erase	g_qspi0.p_api->erase(g_qspi0.p_ctrl, (uint8_t *) QSPI_DEVICE_ADDRESS, BYTE_COUNT); Erase a block of memory depending on the input argument "byte_count"
statusGet	g_qspi0.p_api->statusGet(g_qspi0.p_ctrl, &in_progress); Get the write or erase status of the flash.
bankSelect	g_qspi0.p_api->bankSelect(0); Select the bank to access.
infoGet	g_qspi0.p_api->infoGet(g_qspi0.p_ctrl, &qspi_info); Provides information about the underlying QSPI flash, as specified in bsp_qspi.c
versionGet	g_qspi0.p_api->versionGet(& ssp_version); Retrieve the API version with 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	Invalid parameter is passed.
SSP_ERR_ASSERTION	p_cfg was NULL.
SSP_ERR_NOT_OPEN	Driver is not opened.
SSP_ERR_UNSUPPORTED	Driver not able to query the following information from the flash manufacturer id, memory capacity and memory type.

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.

QSPI HAL Module Operational Overview

The QSPI HAL module is used to initialize the QSPI peripheral so that the Synergy device can communicate (read, write and erase data) with a QSPI serial flash device.

The driver supports three operation modes: page program (write), read and erase.

• The Page program operation programs a single page of data to the flash device. Page size is specific to flash memory and may vary with the vendor to vendor. The typical page size of flash are 128, 256 or 512 bytes. Use qspi_api_t::infoGet API to get the supported page size by the underlying flash device.
• The Read operation will read the data from the flash and store it to the user provided buffer.
• The Erase operation will erase the block of data from the flash. Use qspi_api_t::infoGet API to get the supported erase size by the underlying flash device.

Note

1. After any Erase/Write operation and before starting the next operation, it is advisable to use the qspi_api_t::statusGet API to poll the status of operation.  Not doing so may corrupt user data.
2. For above mentioned operations, the value of  function parameter p_device_address should be in the range 0x60000000 – 0x63FFFFFF. Accessing the addresses beyond this range will cause data wrap around. To access the addresses beyond this range, select the valid and appropriate bank using qspi_api_t::bankSelect.

QSPI HAL Module Important Operational Notes and Limitations

QSPI HAL Module Operational Notes

In the case of using a board supported by the SSP and a BSP based project (for example the SK-S7G2 and DK-S7G2) and the board having a QSPI memory device pre-installed, the BSP initializes and places the QSPI peripheral in ROM access mode with XIP (execute in place) enabled. This process enables the memory to be read like standard memory, meaning the QSPI HAL Module is only needed when erasing and programming the QSPI flash device.

Page programming by default uses only one line (D0).  To use multiple lines during page program, define the command QSPI_PAGE_PROGRAM_DATA_LINES as one of the following macros in bsp_qspi.h:

• QSPI_COMMAND_PAGE_PROGRAM_QUAD
• QSPI_COMMAND_4BYTE_PAGE_PROGRAM_QUAD
• QSPI_COMMAND_PAGE_PROGRAM_DUAL
• QSPI_COMMAND_4BYTE_PAGE_PROGRAM_DUAL

 Also, define QSPI_PAGE_PROGRAM_ADDRESS_ONE_LINE to 1 if the address should be sent on D0 only during dual input page program and quad input page program commands.  An example of this can be found in bsp_qspi.h for S7G2-DK starting in SSP version 1.5.0.

The accompanying code to this module guide demonstrates both modes of operation: access via the QSPI HAL Module and ROM access mode with XIP enabled.

The typical QSPI application programs or erases data on the QSPI flash device. When this driver is not open, the QSPI flash device contents get mapped to 0x60000000 and can be read as if ordinary memory.

This driver has been tested on the Micron N25Q256A QSPI flash device.

To configure a QSPI flash memory with 4-byte addressing mode on customized boards, follow the steps below:

1. Make sure QSPI chip supports 4-byte addressing mode by referring the user manual of the flash device.
2. Configure the following in bsp_qspi.c and bsp_qspi.h, referring to the user manual of the flash device.
   • bsp_qspi.c file:
     • Macros:
       • Dummy cycles required
       • Delay timings
       • Page size
     • Global variables:
       • Erase size
       • Erase commands (sector, block, and chip)
   • bsp_qspi.h file:
     • Manufacturer ID
     • Memory Type
     • Memory Capacity
   • Enum definitions:
     • qspi_command (if required)
3. In configuration window select addressing mode as 4-byte.

To use a QSPI flash memory on customized boards, follow the steps below:

1. Configure the following in bsp_qspi.c and bsp_qspi.h, referring to the user manual of the flash device.
   • bsp_qspi.c file:
     • Macros:
       • Dummy cycles required
       • Delay timings
       • Page size
     • Global variables:
       • Erase size
       • Erase commands (sector, block, and chip)
   • bsp_qspi.h file:
     • Manufacturer ID
     • Memory Type
     • Memory Capacity
   • Enum definitions:
     • qspi_command (if required)
2. Calculation of memory capacity in bsp qspi.c file by user (if required).
   • Memory capacity varies for different QSPI flash chips and it should be handled accordingly in bsp_qspi_config_get() function
   • Example: For MT23QL512QSPI FLASH memory capacity calculation should be:

     uint8_t actual_ memory_capacity = n25_device_characteristics.memory_capacity;    
     if(actual_ memory_capacity > 0x1F)
     {
          actual_ memory_capacity = 0x19 + (actual_ memory_capacity - 0x1F);
          *p_memory_capacity    = actual_ memory_capacity;
     }
     else
     {
          *p_memory_capacity    = n25_device_characteristics.memory_capacity;
     }

QSPI HAL Module Limitations

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

4-Byte supported MCU/board list:

Sl No.	Board	QSPI Flash Part No.	QSPI Memory Size	3-byte hardware support	3-byte software support	4-byte hardware support	4-byte software support	4-byte bsp changes	XIP Mode support	Remarks
1	s7g2_dk (v4.0,v4.1)	MX25L12835F (Macronix)	16MB	YES	YES	NO	NO	YES	YES	4-byte addressing not supported by device
2	s7g2_dk (v3.95 & below)	N25Q256A13E40 (Micron)	32MB	YES	YES	YES	NO	YES	YES	4-byte command is only for part numbers N25Q256A83ESF40x, N25Q256A83E1240x, and N25Q256A83ESFA0F
3	s7g2_sk	W25Q64FV (Winbond)	8MB	YES	YES	NO	NO	YES	YES	4-byte addressing not supported by device
4	s5d3_tbb	MX25L12835F (Macronix)	16MB	YES	YES	NO	NO	YES	YES	4-byte addressing not supported by device
5	s5d5_tbb	N25Q256A13E40 (Micron)	32MB	YES	YES	YES	NO	YES	YES	4-byte command is only for part numbers N25Q256A83ESF40x, N25Q256A83E1240x, and N25Q256A83ESFA0F
6	s5d9_pk	W25Q64FV (Winbond)	8MB	YES	YES	NO	NO	YES	YES	4-byte addressing not supported by device
7	s3a7_dk	N25Q256A83E40 (Micron)	32MB	YES	YES	YES	YES	YES	YES
8	s3a3_adk	N25Q256A83E40 (Micron)	32MB	YES	YES	YES	YES	YES	YES
9	s3a1_adk	N25Q256A83E40 (Micron)	32MB	YES	YES	YES	YES	YES	YES

Note

S1 MCU Series does not support QSPI.

Including the QSPI HAL Module in an Application

This section describes how to include the QSPI HAL 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 QSPI Driver to an application, simply add it to a thread using the stacks selection sequence given in the following table. (The default name for the QSPI Driver is g_qspi0. This name can be changed in the associated Properties window.)

QSPI HAL Module Selection Sequence

Resource	ISDE Tab	Stacks Selection Sequence
g_qspi0 QSPI Driver on r_qspi	Threads	New> Driver> Storage> QSPI Driver on r_qspi

When the QSPI Driver on r_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.

QSPI HAL Module Stack

Configuring the QSPI HAL Module

The QSPI HAL 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 QSPI HAL Module on r_qspi

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	If selected code for parameter checking is 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 Group. Other MCUs may have different default values and available configuration settings.

QSPI HAL Module Pin Configuration

The QSPI peripheral module uses pins on the MCU to communicate to external devices. I/O pins must be selected and configured as required by the external device. The following table indicates the method for selecting pins within the SSP configuration window and the subsequent table lists an example selection sequence for the QSPI pins.

Pin Selection Sequence for the QSPI HAL Module on r_qspi

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

Note

The selection sequence assumes the QSPI0 is the desired hardware target for the driver.

Pin Configuration Settings for the QSPI HAL Module

Property	Value	Description
Pin Group Selection	- Mixed - _A only	Pin group selection.
Operation Mode	- Disabled - Custom - Single or Dual - Quad	Operation mode.
QSPCLK	None, P500	QSPI clock output pin.
QSSL	None, P501	QSPI slave select pin.
QIO0	None, P502	Data 0 input/output.
QIO1	None, P503	Data 1 input/output.
QIO2	None, P504	Data 2 input/output.
QIO3	None, P505	Data 3 input/output.

Note

The example settings come from a project using the Synergy S7G2 MCU Group and the SK-S7G2 Kit. Other Synergy Kits and other Synergy MCUs may have different available pin configuration settings.

Using the QSPI HAL Module in an Application

The typical steps in using the QSPI HAL module in an application are:

1. Initialize the QSPI HAL module using the qspi_api_t::open API call.
2. Read a block of data using the qspi_api_t::read API call.
3. Erase a sector of data using the qspi_api_t::sectorErase API call.
4. Erase n bytes of data using the qspi_api_t::erase API call.
   1. qspi_api_t::infoGet can be used to get the supported erase sizes by the underlying flash.
   2. qspi_api_t::statusGet API can be used to poll the status of ease operation applicable for sectorErase API also.
5. Program a page of data using the qspi_api_t::pageProgram API call.
   1. Use qspi_api_t::infoGet API to get the page size supported by the underlying flash.
   2. qspi_api_t::statusGet API can be used to poll the status of write operation.
6. Close the QSPI HAL module using the qspi_api_t::close API call.

Note

It is advisable to use the qspi_api_t::erase API instead of the qspi_api_t::sectorErase API as a Sector is not a standard size for flash device and it varies with different vendors.

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

Flow Diagram of a Typical QSPI HAL Module Application