ModusToolbox™ QSPI Configurator user guide¶
ModusToolbox™ tools package version 3.0.0
QSPI Configurator version4.0
About this document
Scope and purpose
The Quad Serial Peripheral Interface (QSPI) Configurator is a stand-alone tool included with the ModusToolbox™ software intended to open or create configuration files, configure memory slots, and generate code for your application.
Intended audience
This document helps application developers understand how to use the QSPI Configurator as part of creating a ModusToolbox™ application.
Document conventions
Convention |
Explanation |
|---|---|
Bold |
Emphasizes heading levels, column headings, menus and sub-menus |
Italics |
Denotes file names and paths. |
Courier New |
Denotes APIs, functions, interrupt handlers, events, data types, error handlers, file/folder names, directories, command line inputs, code snippets |
File > New |
Indicates that a cascading sub-menu opens when you select a menu item |
Abbreviations and definitions
The following define the abbreviations and terms used in this document:
MPN – memory part number
QSPI – quad serial peripheral interface
SFDP – serial flash discoverable parameter
SMIF – serial memory interface
Reference documents
Refer to the following documents for more information as needed:
Device datasheets
Device technical reference manuals
1 Overview¶
The QSPI Configurator is intended to create and configure QSPI configuration for external memory chips and generate code to control the application firmware.
The CAT1 devices allow you to extend the default RAM and flash with external memory chips of the following types: flash, non-volatile FRAM, or RAM. Use the SPI to connect a chip to the device. You can attach up to four external memory parts and configure them with the QSPI Configurator.
The QSPI Configurator bears information about the set of default memory parts. However, if your specific memory part is not present, you can create a new one. In the QSPI Configurator, you can select an attached memory part or Serial Flash Discoverable Parameter (SFDP), which is a standard to query the information about attached memory parts at run-time, for each slot and configure the slot parameters.
1.1 Supported software¶
Name |
version |
Link |
|---|---|---|
CAT1 Peripheral Driver Library |
2.3.0 |
GitHub repo: https://github.com/Infineon/mtb-pdl-cat1 SMIF Driver Documentation: https://Infineon.github.io/mtb-pdl- |
2 Launch the QSPI Configurator¶
There are numerous ways to launch the QSPI Configurator, and those ways depend on how you use the various tools in ModusToolbox™ software.
2.1 make command¶
As described in the ModusToolbox™ user guide build system chapter, you can run numerous make commands in the application directory, such as launching the QSPI Configurator. After you have created a ModusToolbox™ application, navigate to the application directory and type the following command in the appropriate bash terminal window:
make qspi-configurator
This command opens the QSPI Configurator GUI for the specific application in which you are working.
2.2 Eclipse IDE¶
If you use the Eclipse IDE for ModusToolbox™, you can launch the QSPI Configurator for the selected application. In the Project Explorer, right-click on the project and select ModusToolbox™ > QSPI Configurator
<version>. You can also click the QSPI Configurator link in the IDE Quick Panel.
Similar to the make command method, launching the QSPI Configurator using the Eclipse IDE opens the tool for the selected application. Refer to the Eclipse IDE for ModusToolbox™ User Guide for details about the IDE.
2.3 From the Device Configurator¶
You can also launch the QSPI Configurator from the Device Configurator:
Open the Device Configurator. See the Device Configurator user guide for details.
On the Peripherals tab, enable the QSPI resource.
Optionally, review and resolve the tasks in the Notice List pane. These can be resolved later.
On the Parameters tab, click the Launch QSPI Configurator button.
The QSPI Configurator saves configuration information in a *.cyqspi file, which contains all the required information about the device and the application. When you save changes, the QSPI Configurator generates/updates firmware in the BSP’s “GeneratedSource” folder.
2.4 Executable (GUI)¶
If you don’t have an application or if you just want to see what the configurator looks like, you can launch the QSPI Configurator GUI by running its executable as appropriate for your operating system (for example, double- click it or select it using the Windows Start menu). By default, it is installed here:
<Install_dir>/ModusToolbox/tools_<version>/qspi-configurator-<version>
When launched this way, the QSPI Configurator opens without any memories configured.
You can either open a specific Configuration file or create a new one. See Menus for more information.
2.5 Executable (CLI)¶
The QSPI Configurator executable can be run from the command line, and it also has a “cli” version of the executable as well. Running configurator executables from the command line can be useful as part of batch
files or shell scripts to re-generate the source code based on the latest configuration settings. The exit code for the executable is zero if the operation is successful, or non-zero if the operation encounters an error. For more information about the command-line options, run the executable using the -h option.
3.Quick start¶
This section provides a simple workflow for how to use the QSPI Configurator.
Open an existing or create a new configuration file.
Specify the configuration file location.
Select a memory from the Memory Part Number list.
a.If your memory device supports SFDP, select Auto detect SFDP.
b. If your memory device does not support SFDP, or for manual configuration, select a memory from the Memory Part Number list, and specify the configuration parameters as required (for example, memory mapped, write enable, etc.). See QSPI Configuration Fields.
Note
If the required memory part number is not present in the list, you can add it. Select* <Browse>…, navigate to the memory file location, and select it.
Save the Configuration file to generate source code. See Code generation.
Use the generated structures as input parameters for QSPI functions in your application.
4. Code generation¶
The QSPI Configurator generates code into the GeneratedSource directory in your BSP, or in the same location you saved the Configuration file for non-Eclipse IDE applications. That directory contains the necessary source (.c) and header (.h) files for the generated firmware, which uses the relevant driver APIs to configure the hardware.
4.1 Files used by the configuration tool¶
The QSPI Configurator uses and provides write access to two types of files: the QSPI configuration file (*.cyqspi), and the memory configuration files: ( .cymem). The QSPI Configurator uses the information from these files to generate the following files:
*.cyqspi – Controls the application-level settings used to provide access to the serial memory device. In the GUI, these settings are at the top of the main window. For the format and contents of the *.cyqspi file, see
*.cymem – Contains parameters of a specific serial memory device, including command formats, memory access sizes, and memory access timings. Unless you are creating a new *.cymem file, these settings are typically read-only and are shown in the lower part of the main window. For the format and contents of
*.cymem files, see *.cymem schema.
cy_qspi_memslot.c – Contains structures populated with parameters specified by the *.cyqspi file and the
*.cymem file or files.
cy_qspi_memslot.h – Contains the declarations of the structures defined in cy_qspi_memslot.c.
qspi_config.cfg – Contains a SMIF Bank layout for use with OpenOCD. It can be ignored if OpenOCD is not in use.
5 GUI description¶
The top area of the QSPI Configurator is used for configuring memories; the read-only area below it displays information about the selected memory part number.
5.3 Target Device Family¶
This pull-down menu allows you to select the device family for which the memory settings apply.
Note
If you do not know to which family your MPN belongs, select only the MPN name.
CAT1A = PSoC™ 6 MCUs
CAT1B = AIROC™ CYW20829
CAT1C = XMC™ 7xxx and Traveo™ T2G
5.4 Flashloader Directory¶
A flashloader is an ELF file containing the algorithms and data structures required for flash memory programming. The QSPI Configurator can patch flashloaders so that their data structures contain data about the external flash memory that will be connected to your design, as well as how the memory is configured. The patched files are placed in the GeneratedSource/ directory alongside the source code and header files generated by the QSPI Configurator.
To enable flashloader patching, select the Flashloader Directory check box and use the […] button to find and select the appropriate directory (or type the directory location in the text field). When you enable the Flashloader Directory check box, the following fields also become active to set appropriate chunk sizes:
Program Chuck Size
Erase Chunk Size
These settings allow you to control the granularity of the operations done while programming the flash memory. Larger values allow for more efficient data transfer, while smaller values can use memory more efficiently. When a memory slot is configured for Auto detect SFDP, the QSPI Configurator cannot know what values are legal, so ensure that these values are at least as large as the largest size of the program/erase operations of all the memories in use. Also, neither value can be larger than the smallest memory in use.
Note
You can also run qspi-configurator or qspi-configurator-cli via the command line using the –flashloader-dir option. If so, the next argument must be the directory path containing the flashloader(s) to patch. If you provide this argument on the command line, the flashloader directory cannot be changed in the GUI.
5.5 QSPI configuration fields¶
The top part of the QSPI Configurator contains the following parameters:
Parameter |
Description |
|---|---|
Slave Slot |
Specifies the slave slot being configured. This number corresponds to the slave select line that will be connected to the memory device. |
Memory Part Number |
Device part number represents the memory device that is being interfaced to the corresponding slave slot. You can select a memory device from the list, or select the option to auto detect the device. Based on the memory device selected, the corresponding *.cymem file is linked into the slave slot. |
Configuration |
For certain Memory Part Numbers, there is additional configuration information, such as 3- byte or 4-byte Addressing Mode. |
Data Select |
Allows you to select the data line options for the corresponding memory slot. |
Memory Mapped |
When this option is enabled, the configured memory device is mapped to the PSoC™ MCU’s memory map. If disabled, access to memory must be done through the QSPI API. |
Pair with Slot |
Determines the paired slot for dual Quad operation. |
Start Address |
Determines the starting address where the memory device is going to be mapped in the PSoC™ memory map. |
Size |
Determines size in bytes of the memory device to be mapped in the PSoC™ memory map. |
End Address |
Represents the end address of the memory device as mapped in the PSoC™ MCU’s memory map. This is a read-only field that is calculated automatically from “Start Address” and “Size” cells values. |
Write Enable |
This lets you enable or disable writes to the external memory in a memory mapped mode of operation. |
Config Data in Flash |
Determines whether a specific memory slot’s config structures are to be placed in Flash or SRAM. When chosen to be placed in SRAM, the support for the programmer is not provided. Refer to AN228740 – Usage of Quad SPI (QSPI)Serial Memory Interface (SMIF) in PSoC™6). |
Encrypt |
Determines whether to treat the memory device in the corresponding slave slot as an encrypted device. If the memory is mapped, all access to this memory will be decrypted on- the-fly. Setting this field does expect that the right encryption key is loaded as a part of the secure image. |
Merge XIP Transactions |
Specifies how many cycles can pass between memory accesses while still skipping the overhead of re-sending the read command. For CAT1A (PSoC™ 6) devices, this field must be Disabled. |
5.6 Edit memory file fields¶
The Edit Memory dialog contains the following fields. These fields also display as read-only in the lower part of the QSPI Configurator.
Field |
Description |
|---|---|
Location |
The path and file name of the current memory file. |
Memory Part Number |
The is the name of the memory chip for which this configuration file is designed. This field will be displayed in the main QSPI Configurator window in the Memory Part Number drop-down menu. |
Configuration |
Some memory parts can be configured in more than one way, and each configuration is contained in a separate memory file. When creating more than one memory file for a part, use this field to describe how this file differs from the others. For example, “3-byte Addressing Mode” or “Hybrid Sectors at Bottom”. |
Configuration Is Default |
For memory parts with more than one configuration, this check box specifies whether this configuration is the one that should be automatically selected when this memory part is chosen in the Memory Part Number drop-down menu. |
Status Register Busy (WIP) Mask |
Mask for the busy bit in the status register. |
Status Register Quad Enable (QE) Mask |
Mask for the quad enable bit in the status register. |
Size of Memory (bytes) |
Denotes the actual size of the memory device. |
Program Page Size (bytes) |
Denotes the page size for a program operation. This size provides the granularity with which program operations can be committed in the memory device. |
Erase Block Size (bytes) |
Provides the erase block size. |
Number of Address Bytes for SPI Transactions |
Sets the number of bytes that are expected for the address field in the QSPI transaction. |
Max Erase Time |
Time the device typically takes to erase a Erase Type 1 size. You must poll the device’s busy status to determine whether the operation has completed. This field has no meaning if the corresponding Erase Type size is 00h. |
Max Chip Erase Time |
Typical time to erase one chip (die). You must poll the device’s busy status to determine whether the operation has completed. For a device consisting of multiple dies that are individually accessed, the time is for each die to which a chip erase command is applied. |
Max Program Time (µs) |
Typical time the device takes to write a full page. You must poll the device’s busy status to determine whether the operation has completed. You may scale this by half or a quarter to determine approximate times for half and quarter page program operations. |
Description |
Blank field to type a description for the memory. |
The Commands table tabs – Single SPI, Dual SPI, Quad SPI, Octal SPI – show the SPI data widths supported by the selected memory.
Field |
Description |
|---|---|
Description |
List of commands:
|
Number |
Byte command word. |
Command Width |
Width of the command transfer. |
Command Rate |
Determines whether the command byte should be sent in Single Data Rate (SDR) or Double Data Rate (DDR) mode. CAT1A (PSoC™ 6) devices only support SDR. |
Address Width |
Width of the address transfer. |
Address Rate |
Determines whether the address bytes should be sent in SDR or DDR mode. CAT1A (PSoC™ 6) devices only support SDR. |
Mode |
Provides the mode word for the command. |
Mode Width |
Provides the width of the mode word transfer. |
Mode Rate |
Determines whether the mode byte should be sent in SDR or DDR mode. CAT1A (PSoC™ 6) devices only support SDR. |
Dummy Cycles |
Provides the number of dummy cycles in the transfer. |
Data Width |
Provides the width of data bytes in the transfer. |
Data Rate |
Determines whether the data bytes should be sent in SDR or DDR mode. CAT1A (PSoC™ 6) devices only support SDR. |
Hybrid Erase Sectors Section
Hybrid Erase Sectors |
This check box specifies whether sectors of different sizes are present in this configuration. The table below contains details about those sectors. If this check box is not enabled, then there are no sectors with different sizes, and none of the other fields are active. |
Row Buttons |
Use these buttons to add and delete rows, as well as move rows up and down. |
Region Table |
This table contains information about the various erase sector regions:
|
6 Create new memory file¶
Select New *.cymem File… to open the Edit Memory window from the main QSPI Configurator:
Click [ … ] button next to the Location field to specify the file name and location of the memory configuration file (.cymem). If you prefer, you can ignore the **Location* field for now, and then specify the file name and location when saving the file.
Enter a desired Memory Part Number. When selected, this field will be displayed in the main QSPI Configurator window in the Memory Part Number.
Complete the information for the remaining fields, as appropriate. See Edit memory file fields.
Click Save to save the configured memory. If Location was not specified previously, this will open a save dialog to navigate to the appropriate location, type a file name, and click Save.
Clock Close to return to the QSPI Configurator.
6.1 Memory database¶
The QSPI Configurator memory database is a set of default memory configurations, based on values from each memory’s datasheet. Check that the selected memory configuration is aligned with a particular part number.
Note
By default, some memory parts are configured with protected regions, which prevents the successful execution of program/erase memory commands.
Note
Dummy cycles may vary based on memory part configuration.
Note
The list of supported commands may vary between memory parts.
7 XML schemas¶
7.1 * .cyqspi schema¶
<xs:schema attributeFormDefault="unqualified"
elementFormDefault="qualified"
xmlns:xs=\ `"http://www.w3.org/2001/XQSPISchema <http://www.w3.org/2001/XQSPISchema>`__">
<xs:element name="Configuration">
<xs:complexType>
<xs:sequence>
<xs:element type="xs:string" name="DevicePath"/>
<xs:element type="xs:string" name="FlashloaderDir"/>
<xs:element type="xs:int" name="FlashloaderProgramChunkSize"/>
<xs:element type="xs:int" name="FlashloaderEraseChunkSize"/>
<xs:element name="SlotConfigs">
<xs:complexType>
<xs:sequence>
<xs:element name="SlotConfig" maxOccurs="4" minOccurs="0">
<xs:complexType>
<xs:sequence>
<xs:element type="xs:byte" name="SlaveSlot"/>
<xs:element type="xs:string" name="PartNumber"/>
<xs:element type="xs:boolean" name="MemoryMapped"/>
<xs:element type="xs:string" name="DualQuad"/>
<xs:element type="xs:string" name="StartAddress"/>
<xs:element type="xs:string" name="Size"/>
<xs:element type="xs:string" name="EndAddress"/>
<xs:element type="xs:boolean" name="WriteEnable"/>
<xs:element type="xs:boolean" name="Encrypt"/>
<xs:element type="xs:string" name="DataSelect"/>
<xs:element type="xs:string" name="MemoryConfigsPath"/>
<xs:element type="xs:boolean" name="ConfigDataInFlash"/>
<xs:element type="xs:string" name="MergeTimeout"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
<xs:attribute type="xs:string" name="app" fixed="QSPI"/>
<xs:attribute type="xs:int" name="major"/>
<xs:attribute type="xs:int" name="minor"/>
</xs:complexType>
</xs:element>
</xs:schema>
7.2 * .cymem schema¶
<xs:schema attributeFormDefault="unqualified"
elementFormDefault="qualified"
xmlns:xs=\ `"http://www.w3.org/2001/XQSPISchema <http://www.w3.org/2001/XQSPISchema>`__">
<xs:element name="CyMemoryConfiguration">
<xs:complexType>
<xs:sequence>
<xs:element type="xs:string" name="PartNumber"/>
<xs:element type="xs:string" name="Configuration" minOccurs="0"/>
<xs:element type="xs:string" name="DisplayName" minOccurs="0"/>
<xs:element type="xs:string" name="Description"/>
<xs:element type="xs:string" name="NumberOfAddress"/>
<xs:element type="xs:string" name="SizeOfMemory"/>
<xs:element type="xs:string" name="EraseBlockSize"/>
<xs:element type="xs:string" name="ProgramPageSize"/>
<xs:element type="xs:string" name="StatusRegisterBusyMask"/>
<xs:element type="xs:string" name="StatusRegisterQuadEnableMask"/>
<xs:element type="xs:int" name="EraseTime"/>
<xs:element type="xs:int" name="ChipEraseTime"/>
<xs:element type="xs:int" name="ProgramTime"/>
<xs:element name="HybridInfo" minOccurs="0" maxOccurs="1">
<xs:complexType>
<xs:sequence>
<xs:element maxOccurs="unbounded" name="Region">
<xs:complexType>
<xs:sequence>
<xs:element name="RegionIndex" type="xs:int" />
<xs:element name="SectorCount" type="xs:int" />
<xs:element name="SectorSize" type="xs:string" />
<xs:element name="EraseCommand" type="xs:string" />
<xs:element name="EraseTime" type="xs:int" />
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="Commands" maxOccurs="4" minOccurs="1">
<xs:complexType>
<xs:sequence>
<xs:element name="Command" maxOccurs="unbounded" minOccurs="0">
<xs:complexType>
<xs:sequence>
<xs:element type="xs:string" name="CommandDescription"/>
<xs:element type="xs:string" name="CommandName"/>
<xs:element type="xs:string" name="CommandNumber"/>
<xs:element type="xs:string" name="CmdWidth"/>
<xs:element type="xs:string" name="CmdRate"/>
<xs:element type="xs:string" name="AddrWidth"/>
<xs:element type="xs:string" name="AddrRate"/>
<xs:element type="xs:string" name="Mode"/>
<xs:element type="xs:string" name="ModeWidth"/>
<xs:element type="xs:string" name="ModeRate"/>
<xs:element type="xs:byte" name="DummyCycles"/>
<xs:element type="xs:string" name="DataWidth"/>
<xs:element type="xs:string" name="DataRate"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:sequence>
<xs:attribute type="xs:string" name="mode" use="optional"
default="Quad"/>
</xs:complexType>
</xs:element>
</xs:sequence>
<xs:attribute type="xs:string" name="version" use="optional"
default="1"/>
</xs:complexType>
</xs:element>
</xs:schema>
8 Version changes¶
This section lists and describes the changes for each version of this tool.
Version |
Change Descriptions |
|---|---|
1.0 |
New tool. |
1.1 |
Added Notice List and toolbar. Updated to accommodate back end changes. |
2.0 |
Added Import/Export functionality. Moved configuration data from being embedded in the .h file to a new .cyqspi file. Set EraseTime, ChipEraseTime and ProgramTime to max. Allowed memory mapping for any Data Select selections. Added warning when “Config Data in Flash” check box isn’t selected, and the device part number is not in “auto detect mode.” Disabled the “Config Data in Flash” check box when the “Memory Part Number” is set to “Auto detect SFDP.” Added handling of invalid command line arguments. Made it impossible for paired slots to have different memory part numbers. Fixed the Pair with Slot Memory Overlap Error. |
2.1 |
Separated the Memory Part Number combo box into Memory Part Number and Configuration. Added support for hybrid erase sectors. |
2.20 |
Added Undo/Redo commands. Added Copy feature to the Notice List. |
2.30 |
Removed the command-line generate options: -g and –generate. |
Removed version 1.1 personality support. |
|
3.0 |
Added support for flashloader patching, and added the Flashloader directory field. |
Removed support for loading configuration data from .h files. Configuration information is now always located in the design.cyqspi file. |
|
4.0 |
Changed the device library file from xml to props.json. |
Updated the GUI layout. Added the ability to load memory configuration from device-db. |
Revision history¶
Date |
Revision |
Description |
|---|---|---|
2018-11-27 |
** |
New document. |
2019-02-27 |
*A |
Added Notice List and toolbar. Updated to accommodate back end changes. |
2019-10-16 |
*B |
Updated to version 2.0. |
2020-03-27 |
*C |
Updated to version 2.1. |
2020-04-21 |
*D |
Updated text for hybrid memory descriptions. |
2020-08-28 |
*E |
Updated to version 2.20. |
2020-09-07 |
*F |
Updated to mention the UNITS (bytes/word) of size explicitly. Updated description for “End Address” field. Updated description for “Start address” field. Added a link to App Note AN228740 for the “Config Data in Flash” field. |
2021-03-12 |
*G |
Updated to version 2.30. |
2022-01-20 |
*H |
Updated to version 3.0. |
2022-09-28 |
*I |
Updated to version 4.0. |