En DM00629856

UM2609
User manual
Description of the integrated development environment for STM32 products
Introduction
STM32CubeIDE is an all-in-one multi-OS development tool part of the STM32Cube software ecosystem. It contains an
advanced C/C++ development platform supporting software development of STM32-based products.
This document details the STM32CubeIDE features and usage, including how to get started, create and build projects, debug
with standard and advanced techniques, and many other software analysis solutions. STM32CubeIDE is based on the Eclipse
C/C++ Development Tools™ (CDT™) and GCC toolchain, which cannot be entirely described in this user manual. Additional
information on Eclipse® is available from STM32CubeIDE embedded help system. Special documents covering the details of
the toolchain and GDB servers are included within the product.
UM2609 - Rev 1 - July 2020 www.st.com

For further information contact your local STMicroelectronics sales office.
UM2609
Getting started
1 Getting started
STM32CubeIDE supports STM32 products based on the Arm® Cortex® processor. Refer to STMicroelectronics
documents listed in Section 10 References for details.
Note: Arm is a registered trademark of Arm Limited (or its subsidiaries) in the US and/or elsewhere.
1.1 Product information

STM32CubeIDE is an advanced C/C++ development platform with peripheral configuration, code generation,
code compilation, linking, and debug features. It is based on the Eclipse®/CDT framework and GCC toolchain for
the development, and GDB for the debugging. It allows the integration of the hundreds of existing plugins that
complete the features of the Eclipse® IDE.
STM32CubeIDE integrates ST MCUFinder (ST-MCU-FINDER-PC) and STM32CubeMX functionalities to offer all-
in-one tool experience. It makes it easy to create new STM32 MCU or board projects and build them using the
included GCC toolchain.
STM32CubeIDE includes a build analyzer and a static stack analyzer that provide the user with useful information
about project status and memory requirements.
STM32CubeIDE also includes standard and advanced debugging features including views of CPU core registers,
memories, and peripheral registers, as well as live variable watch, and serial wire viewer interface. A fault
analyzer displays error information if an error is triggered by the STM32 processor during a debug session.
UM2609 - Rev 1 page 2/186

UM2609
Product information
Figure 1. STM32CubeIDE key features
Device support Project Debugging
STMicroelectronics STM32 products
System Workbench for STM32
Import Atollic® TrueSTUDIO®
SEGGER J-Link GDB server

Integrated ST-MCU-FINDER
Integrated STM32CubeMX
Multi-core and multi-board
OpenOCD GDB server

Live Expressions view
ST-LINK GDB server

SWV and ITM views
Static Stack Analyzer
debugging
Build Analyzer
Import
SFRs view
Project wizard Debug configuration and launch
GNU toolchain GDB debugger
Eclipse® plugins Modified plugins Eclipse C/C++ Development Tools™ (CDT™)
Eclipse® core platform
Supporting Windows®, Linux®, and macOS®
Legend: Specific STM32CubeIDE functions Open-based updated by ST Base technology platform
STM32CubeIDE main function groups Third-party solutions Operating systems
1.1.1 System requirements

STM32CubeIDE is tested and verified on the Microsoft® Windows®, Linux®, and macOS® operating systems.
Important:
STM32CubeIDE supports only 64-bit OS versions. For more details about supported versions of operating systems, refer to
[ST-02].
Note: macOS® is a trademark of Apple Inc. registered in the U.S. and other countries.
All other trademarks are the property of their respective owners.
1.1.2 Downloading the latest STM32CubeIDE version

The latest version of STM32CubeIDE is available for free download from the www.st.com/stm32softwaretools
website.
1.1.3 Installing STM32CubeIDE

The STM32CubeIDE installation guide [ST-04] gives directions on how to install on supported versions of
Windows®, Linux® and macOS®. It is possible to have several versions of STM32CubeIDE installed in parallel.
Read the installation guide if STM32CubeIDE is not already installed or if a new version must be installed.
Installing updates and additional Eclipse plugins in this manual also provides information on how to install
updates.
UM2609 - Rev 1 page 3/186

UM2609
Using STM32CubeIDE
1.1.4 License
STM32CubeIDE is delivered under the Mix Ultimate Liberty+OSS+3rd-party V1 software license agreement
(SLA0048).
For more details about the license agreement of each component, refer to [ST-02].
1.1.5 Support
There are several different support options provided by STMicroelectronics. For instance, the ST Community is
offering places to meet people with similar mind-set all over the world at any time. Choose the support option by
visiting my.st.com/content/my_st_com/en/support/support-home.html.
1.2 Using STM32CubeIDE
1.2.1 Basic concept and terminology

The basic concept using STM32CubeIDE and Eclipse® terminology is outlined in this section.
Workspaces
When starting STM32CubeIDE, a workspace is selected. The workspace contains the development environment
to be used. Technically, the workspace is a directory that may hold projects. The user may access any project
within the active workspace.
A project contains files, which may be organized into sub-directories. Files existing somewhere else on the
computer can also be linked to the project.
A single computer may hold several workspaces at various locations in the file system. The user may switch
between workspaces, but only one workspace can be active at a time. Switching workspace is a quick way of
switching from one set of projects to another.
In practice, the workspace and project model facilitate a well-structured hierarchy of workspaces, containing
projects, which in turn contain files.
Information center
The first time STM32CubeIDE is started and a workspace is selected, the Information Center is opened. The
Information Center provides quick access to start a new project, read STM32CubeIDE documentation, or get
access to ST support & community. The Information Center can be easily accessed at any time via the
Information Center toolbar button or from the Help menu.
Perspectives, menu bar, toolbar

When the Information Center is closed, STM32CubeIDE displays a perspective, which contains a menu bar,
toolbar, views and editors. Each perspective is optimized for a special type of work. For instance, the C/C++
perspective is meant for creating, editing and building projects. The Debug perspective is intended to be used
when debugging code on hardware.
Each perspective can be customized according to the user's need. It is possible to reset the perspective at any
time if, for instance, too many views are opened or if the views are reordered. It is also possible to create new
perspectives.
Views and editors

A perspective normally displays many views. Each view is developed to present specific information, which for
instance can be collected from the project or from an embedded system under debug.
A perspective has one editor area. The editor can be used to edit project files. Many files can be edited in different
tabs in the editor.
UM2609 - Rev 1 page 4/186

UM2609
Using STM32CubeIDE
STM32CubeIDE window
Figure 2. STM32CubeIDE window
Name of current workspace Menu bar Toolbar Editor area Outline view
Project Explorer Console view Build Analyzer
1.2.2 Starting STM32CubeIDE

Start STM32CubeIDE by performing the following steps depending on the operating system used.
Windows®
If a desktop shortcut is created during the installation of the product, the shortcut can be used to start
STM32CubeIDE. The product can also be started from the Windows® start menu under STMicroelectronics
programs.
Otherwise:
1. Locate where STM32CubeIDE is installed, for instance in C:\ST\STM32CubeIDE_1.0.2
2. Open the STM32CubeIDE folder
3. Start the stm32cubeide.exe program
Linux® or macOS®
When using Linux® or macOS®, the program can be started in a similar way by opening the STM32CubeIDE
folder where the product is installed.
STM32CubeIDE Launcher
When the product is started, it displays the STM32CubeIDE Launcher dialog with workspace selection. The first
time the product is started, it presents a default location and workspace name. The dialog enables the user to
select the name and location of the active workspace for holding all the projects currently accessible by the user.
Any newly created project is stored in this workspace. The workspace is created if it does not yet exist.
UM2609 - Rev 1 page 5/186

UM2609
Information Center
Note: If Windows® is used, avoid locating the workspace folder too many levels below the file system root to avoid
exceeding the Windows® path length character limitations. Build errors occur if the file paths become longer
than what Windows® can handle.
Figure 3. STM32CubeIDE Launcher – Workspace selection
Click on the [Launch] button to launch STM32CubeIDE. The first time, it opens the Information Center, which is
described in Section 1.3 Information Center.
1.2.3 Help system

The Help menu provides several different help systems as seen in Figure 4. The Information Center contains links
to all available STM32CubeIDE documentation. It is also recommended for new users to try different Eclipse®
built-in help systems to get an understanding of Eclipse® basics.
Figure 4. Help menu
1.3 Information Center

The Information Center provides quick access to:
1. Start a new project
2. Import an existing project
3. Read STM32CubeIDE documentation
4. Get access to Getting Started with STM32CubeIDE (STM32CubeIDE quick start guide [ST-03])
5. Explore What’s New in STM32CubeIDE (STM32CubeIDE release note [ST-02])
6. Get access to STMicroelectronics support and community on Twitter™, Facebook™, YouTube™, or ST
community at community.st.com
UM2609 - Rev 1 page 6/186

UM2609
Information Center
It is not required to read all material before using the product for the first time. Rather, it is recommended to
consider the Information Center as a collection of reference information to return to, whenever required.
1.3.1 Accessing the Information Center

The Information Center can easily be accessed at any time, from any perspective, using the [Information Center]
toolbar button . This icon is located at the right of the toolbar. It is also possible to open the Information Center
from the [Help]>[Information Center] menu command.
Figure 5. Help - Information Center menu
1.3.2 Home page

When the Information Center is opened, the Home page is displayed. It contains links to start a new project,
import projects, read documentation and access STMicroelectronics support and community.
Figure 6. Information Center – Home page
When using an old workspace, the Information Center may not display valid information, showing “This page can’t
be displayed” or opening old manuals when accessing documents. In such case, reload the page by clicking on
the [Home] button at the top right corner of the Information Center window.
1.3.3 Technical documentation

The Information Center also contains a Technical Documentation page, which is opened from the Home page
when clicking on the Read STM32CubeIDE Documentation link.
UM2609 - Rev 1 page 7/186

UM2609
Perspectives, editors and views
Figure 7. Information Center – Technical documentation page
Scroll through the Technical Documentation page and click on a document in the list to open it. The documents
are listed in groups:
• IDE documentation
• STM32Cube ecosystem documentation
• Build tools
• Debugger documentation
• Toolchain manuals (GNU Tools for STM32)
• Toolchain manuals (GNU Arm Embedded)
Note: There are two toolchain manual groups because STM32CubeIDE is distributed with both a GNU Arm Embedded
toolchain and a GNU Tools for STM32 toolchain with patched enhancements.
To navigate back to the Home page, press STM32CubeIDE Home at the top left side of the Information Center.
1.3.4 Closing the Information Center

Close the Information Center tab to close the Information Center.
1.4 Perspectives, editors and views

STM32CubeIDE is a powerful product with many views, loaded with various features. Displaying all views
simultaneously would overload the user with information that may not be relevant to the task at hand.
To overcome such a situation, views can be organized in perspectives, where a perspective contains a number of
predefined views and an editor area visible by default. A perspective typically handles one development task,
such as C/C++ Code Editing or Debugging.
UM2609 - Rev 1 page 8/186

UM2609
1.4.1 Perspectives
The perspectives can be customized according to the user's need; Views can be moved, resized and new views
can be opened. It is possible to reset the perspective at any time if, for instance, too many views are opened or if
the views are reordered. The perspective is reset by right-clicking the perspective icon in the toolbar and selecting
[Reset] from the list. This resets the views; Added views in the perspective are closed and the default views are
moved to their original location.
Figure 8. Reset perspective
As seen in Figure 8, it is also possible to customize a perspective and save the perspective with a new name.
Switching from one perspective to another is a quick way to hide some views and display others. To switch
perspective, select the [Open Perspective] toolbar buttons at the right of the toolbar.
Figure 9. Toolbar buttons for switching perspective
Another way to switch perspective is to use the menu command [Window]>[Perspective]>[Open

Perspective]>[Other…] and select the perspective to use.
1.4.1.1 C/C++ perspective

The C/C++ perspective is intended for creating new projects, editing files, and building the project. The left part of
the perspective contains the Project Explorer view. The editor is located in the middle. The right part contains
some views for the project (Outline and Build Targets views). At the bottom in the example illustrated in Figure 10,
there are the Problems, Tasks, Console and Properties views. At the lowest right, the Build analyzer and Static
stack analyzer views are displayed.
UM2609 - Rev 1 page 9/186

UM2609
Figure 10. C/C++ perspective
1.4.1.2 Debug perspective

The Debug perspective is intended for debugging the code. The Debug perspective is normally opened
automatically when a new debug session is started. Later, when the debug session is closed, the perspective is
switched back to the C/C++ perspective.
Figure 11. Debug perspective
UM2609 - Rev 1 page 10/186

UM2609
1.4.1.3 Device Configuration Tool perspective

The Device Configuration Tool perspective contains the STM32CubeMX device configuration tool integrated in
STM32CubeIDE. This perspective is used for device configuration. When an *.ioc file is opened in an editor and
the Device Configuration Tool perspective is used, the device can be configured in this perspective. How the
device configuration is made is described in [ST-12].
Figure 12. Device Configuration Tool perspective
1.4.1.4 Remote System Explorer perspective

The Remote System Explorer perspective is basically used when developing STM32 Arm® Cortex® MPU-based
systems. The Remote Systems view is used to view files and the Remote Shell view is used to run commands.
UM2609 - Rev 1 page 11/186

UM2609
Figure 13. Remote System Explorer perspective
The Remote Systems view contains buttons to open a new connection via FTP, Linux®, Local, SSH, Telnet and
others.
Figure 14. New connection
UM2609 - Rev 1 page 12/186

UM2609
1.4.2 Editors
The editor area in a perspective is used by editors. Any number of editors can be opened simultaneously but only
one can be active at a time. Different editors can be associated with different file extensions. Example of editors
are; c-editor, linker script editor, ioc-file editor for STM32CubeMX device configuration.
To open a file in the editor, double-click on the file in the Project Explorer view or open the file via the [File] menu.
When a file is modified in the editor,it is displayed with an asterisk (*) indicating that the file has unsaved changes.
1.4.3 Views
Only the most common views associated with the perspective are displayed by default. There are many more
views in the product supporting different features. Some of these views only provide valid data when a debug
session is ongoing, while others always display data.
Views can be opened from the [Window]>[Show View] menu by selecting one of the views in the list.
Figure 15. [Show View] menu
UM2609 - Rev 1 page 13/186

UM2609
The above list of views in Figure 15 is still not complete. It contains only the most common views for the work task
related to the perspective currently selected. To access even more views, select [Other…] from the list. This
opens the Show View dialog box. Double-click on any view to open it and access its additional features.
Figure 16. Show View dialog
The views can be resized and their positions can be changed: Simply drag the view to a new place in
STM32CubeIDE. The view can also be dragged outside the STM32CubeIDE window on the screen. Such
detached views are shown in separate windows. Detached views works like the other views but are always shown
in front of the workbench. Detached views can be attached again by dragging the tab in the detached view into
the STM32CubeIDE window.
To restore the perspective to original state, right-click the perspective icon in the toolbar and select [Reset] from
the list. Another way to reset the perspective is to use the menu [Window]>[Perspective]>[Reset Perspective].
UM2609 - Rev 1 page 14/186

UM2609
Configuration - Preferences
1.4.4 Quick Access edit field

The Quick Access is an edit field in the toolbar, where any search phrase or keyword can be entered. GUI objects
like menu commands, toolbar buttons, preference settings or views can be found using this field. As any search
string is typed, the Quick Access shows all the GUI objects that match the criteria, in real time. Type a couple of
characters or more and see how the list of results is refined correspondingly on-the-fly.
The Quick Access is a time saver when looking for a specific GUI object that cannot be found quickly otherwise,
such as a preference setting deeply buried in the configuration dialogs. It is also convenient to retrieve a menu
command or toolbar button hidden in the currently active perspective.
For example, in Figure 17, the search string “SWV” entered in the Quick Access provides immediately the list of
matching views, GUI commands and preference settings. To open the view or preference setting, click on the GUI
object in the search result list.
Figure 17. Quick access
1.5 Configuration - Preferences

STM32CubeIDE can be customized in many ways. The menu [Window]>[Preferences] is used to open the
Preferences dialog. In this dialog, the left pane is used to navigate to certain preference pages. There is also a
filter field, which can be used to narrow down the content displayed. The arrow controls on the upper-right side of
the dialog can be used to navigate back and forth across pages. The right pane contains the setting of the
displayed preferences. Make any preferred change and press [Apply] to update the setting.
UM2609 - Rev 1 page 15/186

UM2609
[Restore Defaults] resets all changes. The preference settings are stored in a metadata folder in the workspace
of the application. Section 1.7 Managing existing workspaces in this user manual provides information on how to
backup preferences and copy preferences across workspaces.
Figure 18. Preferences
It is advised to walk through the preferences pages and get an understanding of the possible configuration
options. The following sections present some of them.
UM2609 - Rev 1 page 16/186

UM2609
1.5.1 Preferences - Editors

The editor can be configured in many ways. For instance, the menu selection [General]>[Editors]>[Text Editors]
provides a Preferences pane containing general editor settings such as:
• Displayed tab width
• Insert spaces for tabs
• Highlight current tab
• Show line numbers
• Others
Figure 19. Preferences - Text Editors
1.5.2 Preferences - Code style formatter

It is possible to configure the editor to use special formatting.
UM2609 - Rev 1 page 17/186

UM2609
The menu selection [C/C++]>[Code Style]>[Formatter] provides a Preferences pane containing settings to set an
active profile.
Figure 20. Preferences - Formatter
UM2609 - Rev 1 page 18/186

UM2609
At this point, if [Edit…] is pressed, a new dialog is opened, where the selected profile can be updated according
to specific coding rules. This is displayed in Figure 21.
Figure 21. Preferences - Code style edit
UM2609 - Rev 1 page 19/186

UM2609
1.5.3 Preferences - Network proxy settings

STM32CubeIDE uses the Internet for instance to get access to STM32 devices information. If a proxy server is
used for Internet access, some configuration settings are required in STM32CubeIDE. The proxy settings are set
in the Preferences pane obtained through [General]>[Network Connections]. To change the settings, set [Active
provider] to Manual and update the Proxy entries for HTTP and HTTPS with specific Host, Port, User and
Password using the [Edit…] button.
Figure 22. Preferences - Network Connections
Note: If there is a problem to save the proxy settings, the reason can be a corrupt secure_storage file. Proceed as
follows to solve the problem:
1. Rename file C:\Users\user_name\.eclipse\org.eclipse.equinox.security\secure_stora
ge to a new name
2. Restart STM32CubeIDE
3. Update the proxy network settings, with user and password information, and save them to create a new se
cure_storage file
UM2609 - Rev 1 page 20/186

UM2609
Workspaces and projects
1.6 Workspaces and projects

The basic concepts of workspaces and projects compares as follows:
• A workspace contains projects. Technically, a workspace is a directory containing project directories or
references to them.
• A project contains files. Technically, a project is a directory containing files that may be organized in sub-
directories.
• A single computer may hold several workspaces at various locations in the file system. Each workspace may
contain several projects.
• The user may switch between workspaces, but only one workspace can be active at one time.
• The user may access any project within the active workspace. Projects located in another workspace cannot
be accessed, unless the user switches to that workspace.
• The files included in a project do not need to be physically located in a folder in the project but can be
located somewhere else and linked into the project.
• Switching workspaces is a quick way of shifting from one set of projects to another. It triggers a quick restart
of the product.
In practice, the project and workspace model facilitates a well-structured hierarchy of workspaces, containing
projects, containing files.
1.7 Managing existing workspaces

The workspace can be selected when starting STM32CubeIDE. It is also possible to switch to another workspace
during the use of STM32CubeIDE. In this case STM32CubeIDE restarts after the new workspace is selected. To
restart STM32CubeIDE with a new workspace, select menu [File]>[Switch Workspace].
The workspaces known to STM32CubeIDE can be managed by selecting [Window]>[Preferences] then, in the
Preferences dialog, selecting [General]>[Startup and Shutdown]>[Workspaces]. In the right pane, it is possible
to enable [Prompt for workspace on startup] and set [Number of recent workspaces to remember] to the
desired value.
Figure 23. Preferences - Workspaces
It is also possible to select and remove recent workspaces from the list of recent workspaces. However, removing
a workspace from that list does not remove the files. Neither does it remove the files from the file system.
UM2609 - Rev 1 page 21/186

UM2609
Managing existing workspaces
1.7.1 Backup of preferences for a workspace

It is generally a good practice to take a copy of the existing preferences for a workspace. It can be especially
useful to recreate the workspace after a crash without the time-consuming process to redo the settings manually.
In the menu, select [File]>[Export]. Then, in the panel, select [General]>[Preferences]. Press the [Next] button
and, in the next page, enable [Export All] along with a correct filename.
1.7.2 Copy preferences between workspaces

To copy workspace preferences from one workspace to another, an existing export of preferences must first be
created as explained in Backup of preferences for a workspace.
Then select [File]>[Switch Workspace] and the new workspace. STM32CubeIDE restarts and opens with the
new workspace.
In the menu, select [File]>[Import] and in the panel select [General]>[Preferences]. Press the [Next] button and,
on the next page, enable [Import All] and enter the file name. The preferences are now the same in both
workspaces.
1.7.3 Keeping track of Java heap space

To keep track on how much Java heap space is used, select the [Window]>[Preferences] menu. In the
Preferences page, select the [General] node and then enable [Show heap status]. The currently used and
available Java heap space is then displayed in the STM32CubeIDE status bar. The garbage collector can also be
triggered manually from the status bar.
Figure 24. Display of Java heap space status
1.7.4 Unavailable workspace

Only one instance of STM32CubeIDE can access one workspace at a time. This is to prevent conflicting changes
in the workspace. If STM32CubeIDE is started with a workspace that is already used by another instance of the
program, the following error message is displayed.
UM2609 - Rev 1 page 22/186

UM2609
STM32CubeIDE and Eclipse® basics
Figure 25. Workspace unavailable
If this message is displayed, choose a different workspace, or return to the already running STM32CubeIDE.
1.8 STM32CubeIDE and Eclipse® basics

STM32CubeIDE contains so many features that it is easy to miss some really useful capabilities. Noteworthy
features are spell checking of C/C++ comments, word- and code completion, content assist, parameter hints and
code templates. The editor also includes an include-file dependency browser, code navigation using hypertext-
links, bookmark and to-do lists, and powerful search mechanisms. The next sections remind some of the useful
tools that can be easily missed.
1.8.1 Keyboard shortcuts

It is convenient to use keyboard shortcuts instead of the mouse. One important shortcut to know is the shortcut
CTRL+Shift+L. This shortcut opens a cheat sheet with all available shortcuts.
Figure 26. Shortcut keys
Pressing CTRL+Shift+L in this sheet opens the Keys pane in the Preferences dialog.
UM2609 - Rev 1 page 23/186

UM2609
Figure 27. Shortcut preferences
The Keys pane offers the possibility to examine the shortcuts in detail and change the scheme (Default, Emacs,
or Microsoft® Visual Studio), reconfigure shortcut keys, and others.
Table 1 presents some of the keys to mention with their default bindings.
Table 1. Key shortcut examples
Command Binding Where
Copy Ctrl+C In dialogs and windows

Cut Ctrl+X In dialogs and windows
Paste Ctrl+V In dialogs and windows
Debug F11 In windows
Open declaration F3 In C/C++ editor
References Ctrl+Shift+G In C/C++ editor/views
Find and open files Ctrl+Shift+R In C/C++ editor/views
Toggle selection mode normal/block Alt+Shift+A In C/C++ editor/views
Zoom In Ctrl++ Editing text
Zoom Out Ctrl+- Editing text
UM2609 - Rev 1 page 24/186

UM2609
1.8.2 Editor zoom in and zoom out

It is possible to increase or decrease the default font size for text editors by pressing Ctrl++ and Ctrl+-:
• Ctrl++ : zoom in text
• Ctrl+- : zoom out text
Note: If a keyboard with a numeric keypad is used and the + or – keys are pressed on the numeric keypad, use the
Shift key in addition to make the zoom work (Ctrl+Shift+ or Ctrl+Shift-).
Figure 28. Editor with text zoomed in
1.8.3 Quickly find and open a file

Pressing Ctrl+Shift+R to find and open a file quickly is one of the featured easily missed. Type a couple of
characters part of the name of the file to open. It is possible to add the * and ? search wildcards as appropriate.
The editor then lists the matching filenames. Select the desired file in the search result list, and open the file using
any of these three ways:
• [Show In]: sends the file to one of the views chosen in the drop-down list (such as the #include file
dependency browser view)
• [Open With]: opens the file in the editor selected in the drop-down list
• [Open]: probably the most commonly used option, simply opens the file in the standard C/C++ editor
1.8.4 Branch folding

A block of code enclosed within #if and #endif can be folded. To activate the functionality, go to
[Window]>[Preferences], then [C/C++]>[Editor]>[Folding] and check the [Enable folding of preprocessor
branches (#if/#endif)] checkbox. Once the checkbox is checked, the editor must be restarted. Close the file,
open it again, and the small icon in the left margin of the editor showing that the functionality is activated.
UM2609 - Rev 1 page 25/186

UM2609
Figure 29. Editor folding
1.8.5 Block selection mode

Alt+Shift+A toggles the selection mode between normal and block. When the block mode is enabled, a block of
text can be selected by either the mouse or the keyboard using the SHIFT+ARROW buttons.
Use of the block selection mode

To start using the block selection mode, press Alt+Shift+A . Click somewhere in the text and drag down. A
column is then marked as shown in Figure 30.
UM2609 - Rev 1 page 26/186

UM2609
Figure 30. Editor block selection
Add some text and see that this text is entered in all marked rows. As an example, the text “My_” is added and
displayed in Figure 31.
Figure 31. Editor text block addition
UM2609 - Rev 1 page 27/186

UM2609
Selection and edition of areas

Select a block. In Figure 32, the block starting with “mem3” to “mem7” is selected.
Figure 32. Editor column block selection
Copy the selected block by using Ctrl+C. This copied text can then be inserted elsewhere. To do so, type Alt
+Shift+A to toggle the selection modeback to the normal mode, move the cursor to another line, and type Ctrl+V
to paste the copied columns to the new lines.
UM2609 - Rev 1 page 28/186

UM2609
Figure 33. Editor column block paste
1.8.6 Compare files

To compare two files easily in STM32CubeIDE:
1. Select the two files in the Project Explorer view
2. Click on one file
3. Press CTRL
4. Click on the other file
Both files are now marked in the Project Explorer view
5. Right-click and select [Compare With]>[Each Other]
UM2609 - Rev 1 page 29/186

UM2609
Figure 34. Editor - Compare files
The File Differences editor opens and compares both files.
Figure 35. Editor - File differences
Use the navigation buttons to navigate between differences, or simply navigate in the view using the scroll bar to
see the file differences.
UM2609 - Rev 1 page 30/186

UM2609
1.8.7 Local file history

It is recommended to maintain projects with a version control system such as Apache® Subversion® (SVN) or
Git™. Still, STM32CubeIDE contains a local file with the history of edited files, which can be useful if some
investigation is needed after a file has become not functional. The workspace preferences contain a Local History
page.
Figure 36. Local history
UM2609 - Rev 1 page 31/186

UM2609
To show the local history of a file:

1. Select the file in the Project Explorer view
2. Right-click
3. Select [Team]>[Show local History]
Figure 37. Show local history
UM2609 - Rev 1 page 32/186

UM2609
The History view opens and displays the file history.
Figure 38. File history
In the case presented in Figure 38, there are three revisions of main.c. Double-click on a file in the History view
to open it in the editor.
UM2609 - Rev 1 page 33/186

UM2609
Right-click on a file in the history and select [Compare Current with Local] to compare it with the current version
of the file.
Figure 39. Compare current history with local history
UM2609 - Rev 1 page 34/186

UM2609
This opens the File Differences editor and displays the file changes.
Figure 40. Compare local file differences
UM2609 - Rev 1 page 35/186

UM2609
Creating and building C/C++ projects
2 Creating and building C/C++ projects
As mentioned in Section 1.6 Workspaces and projects, a workspace is a directory containing projects. The first
time a workspace is created, it is empty without any projects. The projects need to be created or imported in the
workspace. This section contains information on how to create projects in the workspace and build projects. It
also covers how to import and export projects.
2.1 Introduction to projects

A project is a directory in the workspace containing files that may be organized in sub-directories. It is possible to
access any project within the active workspace. The files included in a project do not need to be physically
located in a folder in the project but can be located somewhere else and linked into the project. Projects located in
another workspace cannot be accessed, unless the user switches to that workspace or import some of these
projects into the workspace in use.
It is possible to rename and delete a project. If a workspace contains many projects, it is also possible to close
some of them to make the work easier. Closed projects can be reopened again at any time.
This section focuses on the two types of STM32 projects supported by STM32CubeIDE:
• Executable programs
• Static library projects
However, the Eclipse® C/C++ Development Toolkit (CDT), which STM32CubeIDE is based on, contains also
basic project wizards, which can be used to create C managed build, C++ managed build, and makefile projects.
The STM32 projects can be:
• C or C++
• Generated executable or library file
• Based on STM32Cube (using STM32 firmware library package) or empty projects
STM32 projects also support an advanced umbrella project structure, where one project contains many projects,
for instance one project per core for multi-core devices.
2.2 Creating a new STM32 project
2.2.1 Creating a new STM32 executable project

The easiest way to create a new STM32 C/C++ project is to use the STM32 project wizard. It is selected through
the menu [File]>[New STM32 Project].
Another way to create a new C/C++ project is to open the Information Center and press [Start new STM32
project]. As mentioned in Section 1.3 Information Center, the Information Center can be opened using the
button on the toolbar or via the menu [Help]>[Information Center].
Both ways initialize and launch the STM32 Project Target Selection tool.
UM2609 - Rev 1 page 36/186

UM2609
Creating a new STM32 project
Figure 41. STM32 target selection
The MCU/MPU selector and Board Selector tabs can be selected at the top of the window. Use the first tab to
create project for a specific device and the second if a project for a specific board is needed.
This section presents the creation of a project for the NUCLEO-F401RE board using the Board Selector.
Among the different filters available for use on the left of the window, type “401” in the Part Number Search field to
filter the boards with names containing this string. In Figure 42, two boards are listed, a Nucleo board board and a
Discovery board. The NUCLEO-F401RE board is selected.
Figure 42. STM32 board selection
UM2609 - Rev 1 page 37/186

UM2609
Five tabs, Features, Large Pictures, Docs & Resources, Datasheet, and Buy, offer the possibility to display
detailed information about the selected board or device. For instance, documentation available for the board is
displayed and can be opened when Docs & Resources is selected. When Datasheet is selected, the board
datasheet is downloaded from STMicroelectronics web site.
Pressing [Next] when the NUCLEO-F401RE board is selected opens the Project setup page.
Enter a project name and select the desired setting for the project in the dialog boxes. The project named
“NUCLEO-F401RE” is filled in as an example in Figure 43.
Figure 43. Project setup
According to the settings in Figure 43, the project is meant to be stored in the default location with the following
options set:
• C project
• Executable binary type
• STM32CubeIDE targeted project type
Press [Next] to open the Firmware Library Package Setup page.
UM2609 - Rev 1 page 38/186

UM2609
Figure 44. Firmware library package setup
In this page, it is possible to select the STM32Cube firmware package to use when creating the project. In this
case, the default settings are used. Press [Finish] to create the project.
As a result, the following dialog is displayed.
Figure 45. Initialization of all peripherals
Press [Yes] since it is a good practice to get the software needed to initialize the peripherals.
This opens the new dialog shown in Figure 46.
UM2609 - Rev 1 page 39/186

UM2609
Figure 46. STM32CubeMX perspective opening
Opening the STM32CubeMX perspective is a good decision if there are any needs to configure the device.
Enable [Remember my decision] if the question msut not be asked the next time a new project is created. Press
[Yes] to continue.
At this point, the project creation starts. The time it takes depends on the amount of files that need to be
downloaded to create the project.
Figure 47. Project creation started
When the project is created, the STM32CubeMX perspective is opened with a window for configuring the
peripherals, clock, middleware, and power consumption.
UM2609 - Rev 1 page 40/186

UM2609
Figure 48. STM32CubeMX
The new project is listed in the Project Explorer view with some of the folders and files it contains.
The NUCLEO-F401RE.ioc file contains the configuration settings and is opened in the STM32CubeMX editor.
This editor contains tabs for Pinout & configuration, Clock configuration, Project manager and Tools. When
changes are made in the STM32CubeMX editor, the .ioc file in the tab is marked as changed. If the file is saved,
a dialog opens asking “Do you want to generate Code?”, making it easy to generate new code in the project that
supports the new device configuration. For more information on how to use the STM32CubeMX editor, refer to
[ST-12].
2.2.2 Creating a new STM32 static library project

The process to create an STM32 static library project is similar to the process presented in
Section 2.2.1 Creating a new STM32 executable project. Open the STM32 project wizard through [File]>[New
STM32 Project] and select the device or board to create a library for. The selection lets the project wizard know
how to setup the compiler options appropriately for the library. When the dialog shown in Figure 49 appears, enter
a project name, such as “myLib” in this example, and select [Static Library] to create a library project.
Note: When creating an STM32 static library project, it is not important to select the correct device exactly, but the
selected device must have the same Cortex® core as the device the library is intended for, for instance Cortex®-
M0+ or Cortex®-M7.
UM2609 - Rev 1 page 41/186

UM2609
Figure 49. STM32 static library project
In Figure 49, the Targeted Project Type is selected to be empty. If project type [STM32Cube] is selected instead,
the generated project contains STM32 drivers also. Press [Finish] to create the project.
Once the project is created, the Project Explorer contains the library project and the previously created NUCLEO-
F401RE board project.
UM2609 - Rev 1 page 42/186

UM2609
Configure the project build setting
Figure 50. STM32 library and board project
As shown in the Project Explorer view in Figure 50, the myLib project only contains an Inc and Src folder. Folder
Inc is empty by default. It is intended that header files are added to this folder. The Src folder contains three C
files. The <myLib.c> file is intended to be updated with the library functions that must be included in the library.
The name of the library file is the same as the project name. The two other C files are used by Newlib if needed
and can be updated if required.
The name of the function in file myLib.c can be renamed. More functions can be added into the myLib.c file.
Additional C files can also be added if a bigger library is created. It is good practice to create header files
containing prototypes of the library functions that are callable from the applications.
Note: The library project folder does not contain any linker script. When building the library project, gcc is used as
compiler for the C files and ar is used to create an archive file, which can be linked into and used by other
executable projects. It is not important to select the correct device for memory settings. The device name is used
to set the Cortex® core to the one intended to be used with the library. This makes the compiler generate correct
instructions.
2.3 Configure the project build setting

When an STM32 project is created, it contains default C/C++ build settings for the project. There are however a
lot of different options that can be used by GCC, each embedded system having its own requirements. It is
therefore possible to configure the project build settings further than the default build settings.
It is also common to have different requirements on build settings during different phases of the project
development; for instance during the debugging and release phases. To handle this, different build configurations
for each project are supported by STM32CubeIDE. This section presents the build configurations first, and then
the project build settings.
2.3.1 Project build configuration

Each build configuration allows different variants of a project and contains a specific build setting. When an
STM32 project is created in STM32CubeIDE, two build configurations, Debug and Release, are created by
default. The Debug configuration makes the project built with debug information and without any optimization. The
Release configuration makes the project optimized for smaller code size and with no debug information. By
default, the Debug configuration is set as the active build configuration when the project is created.
UM2609 - Rev 1 page 43/186

UM2609
It is possible to create new build configurations for a project at any time. Such new build configuration can be
based on an earlier available build configuration.
When building the project, the active build configuration is used and during build the files generated are written
into a folder with the same name as the active build configuration.
Note: The build configuration only handles the build settings. How to configure debug settings is described later in this
manual.
2.3.1.1 Change the active build configuration

To change the active build configuration:
1. Select the project name in the Project Explorer
2. Use the toolbar in the C/C++ perspective and click on the arrow to the right of the [Build] toolbar button
3. The build configurations are listed

Select the build configuration to use from the list.
Figure 51. Set the active build configuration using the toolbar
Another way to change the active build configuration is to right-click on the project name in the Project Explorer
view, select [Build Configurations]>[Set Active], and select the preferred build configuration.
UM2609 - Rev 1 page 44/186

UM2609
Figure 52. Set active build configuration using right-click
UM2609 - Rev 1 page 45/186

UM2609
It is also possible to select the active build configurations using the menu [Project]>[Build Configurations]>[Set
Active] and select the chosen build configuration.
Figure 53. Set active build configuration using menu
2.3.1.2 Create a new build configuration

To create a new build configuration:
1. Right-click on the project name in the Project Explorer view
2. Either:
– Select [Build Configurations]>[Manage… ]
– Use the menu [Project]>[Build Configurations]>[Manage… ]
Both methodes open the Manage Configurations dialog.
Figure 54. Manage Configurations dialog
UM2609 - Rev 1 page 46/186

UM2609
As shown in Figure 54, some buttons in the dialog are used to manage the configurations:
• [Set Active] is used to change and select another configuration to be active
• [New…] is used to create a new build configuration
• [Delete] is used to delete an existing build configuration
• [Rename…] is used to rename the build configuration
To create a new build configuration, press the [New…] button. This opens the Create New Configuration dialog. In
this dialog, a name and description is entered. The name must be a valid directory name since it is used as the
directory name when building the project with the new configuration.
Figure 55. Create a new build configuration
As seen in Figure 55, the new build configuration is based on an existing build configuration. In the case
illustrated, the new configuration is based on the existing Debug configuration. Press [OK] when finished with the
settings.
The Manage Configurations dialog opens and the new debug configuration is displayed.
Figure 56. Updated Manage Configurations dialog
UM2609 - Rev 1 page 47/186

UM2609
Change the active configuration to another configuration if needed and press [OK] to save and close the
configurations dialog when finished managing configurations.
2.3.1.3 Delete a build configuration

To delete a build configuration:
1. Open the Manage Configurations dialog
2. Select the configuration to be deleted
3. Press the [Delete] button
For instance, if the Debug2 configuration is selected and [Delete] button is pressed, the following confirmation
dialog opens.
Figure 57. Configuration deletion dialog
In this case, select [No] to keep the Debug2 configuration.
2.3.1.4 Rename a build configuration

To rename a build configuration:
1. Open the Manage Configurations dialog
2. Select the configuration to be renamed
3. Press the [Rename…] button
For instance, if the Debug2 configuration is selected and [Rename…] button is pressed, the following
confirmation dialog opens.
Figure 58. Configuration renaming dialog
Update the name, description, or both and press [OK] to rename the Debug2 configuration. In this case, press
[Cancel] and keep the name.
2.3.2 Project C/C++ build settings

Each build configuration contains one project C/C++ build setting. The project C/C++ build setting is updated in
project properties. To update the build setting, right-click on the project name in the Project Explorer view and
select [Properties]or use the menu [Project]>[Properties]. Both these ways open the Properties window for the
project.
UM2609 - Rev 1 page 48/186

UM2609
Select [C/C++ Build]>[Settings] in the Properties left pane. The right part is then filled with tabs Toolchain
Version, Tool Settings, Build Steps, Build Artifact, Binary Parsers, and Error Parsers. The first three tabs are the
most useful ones.
Figure 59. Properties tabs
Note: Resize the dialog window or use the top-right arrow buttons if all tabs are not visible.
The Settings pane contains a [Configuration] selection to decide if new selections are used in the active
configuration only, in another configuration, in all configurations or in multiple configurations. Press [Manage
Configurations] to open the Manage Configurations dialog.
Figure 60. Properties configurations
The Toolchain Version tab is used to change from the default “GNU Tools for STM32” to the “GNU ARM
Embedded” toolchain or when wanting to use a specific older toolchain version. It is recommended to use the
latest GNU Tools for STM32 included in STM32CubeIDE.
UM2609 - Rev 1 page 49/186

UM2609
STM32CubeIDE is distributed with both the standard GNU ARM Embedded toolchain and an STM32 version with
patched enhancements. Information about patches made in GNU Tools for STM32 can be read in [EXT-12]. The
document can be opened from the Technical Documentation page in the Information Center.
Figure 61. Properties toolchain version
Select [Fixed] to enable the selection of [Type] and [Version] for the toolchain.
Figure 62. Properties toolchain selection
The Tool Settings tab is further split into MCU Settings, MCU Post build outputs, MCU GCC Assembler, MCU
GCC Compiler and MCU GCC Linker.
UM2609 - Rev 1 page 50/186

UM2609
MCU Settings displays the selected MCU and board for the project and proposes to select how to handle floating
point, instruction set and runtime library.
Figure 63. Properties tool MCU settings
UM2609 - Rev 1 page 51/186

UM2609
MCU Post build outputs proposes to convert the elf file to another file format, show build size information, and
generate list file. The output file can be converted to:
• Binary file
• Intel Hex file
• Motorola S-record file
• Motorola S-record symbols file
• Verilog file
Figure 64. Properties tool MCU post-build settings
UM2609 - Rev 1 page 52/186

UM2609
The MCU GCC Assembler settings contains selections for the assembler. The main node presents all the
assembler command-line options that are currently enabled in the sub-node settings. The sub-nodes are used to
view the current settings or change any settings for the assembler.
Figure 65. Properties tool GCC assembler settings
UM2609 - Rev 1 page 53/186

UM2609
The MCU GCC Compiler settings contains selections for the compiler. The main node presents all the compiler
command-line options that are currently enabled in the sub-node settings. The sub-nodes are used to view the
current settings or change any settings for the compiler.
Figure 66. Properties tool GCC compiler settings
UM2609 - Rev 1 page 54/186

UM2609
The MCU GCC Linker settings contains selections for the linker. The main node presents all the linker command-
line options that are currently enabled in the sub-node settings. The sub-nodes are used to view the current
settings or change any settings for the linker.
Figure 67. Properties tool GCC linker settings
UM2609 - Rev 1 page 55/186

UM2609
Building the project
The Build Steps settings contains fields used to provide pre-build and post-build steps, which run before and after
building the project. Edit the fields to run any pre-build or post-build step.
Figure 68. Properties build steps settings
2.4 Building the project
To start a build, select the corresponding project in the Project Explorer view and click on the [Build]
toolbar button.
Figure 69. Project build toolbar
The build can also be started from menu [Project]>[Build Project]. The [Project] menu contains also some other
usable build commands such as [Build All], [Build Project] or [Clean].
Another way to start a build is to right-click on the project in the Project Explorer view. This opens the context
menu with the [Build] command and some other build options.
During the build, the Console view lists the build process. At the end, when the elf file is created normally, it lists
size information.
UM2609 - Rev 1 page 56/186

UM2609
Figure 70. Project build console
2.4.1 Building all projects
The toolbar contains the [Build all] button, which is used to build the active build configuration for all open
projects in workspace.
It is also possible to use the menu [Project]>[Build All] to start a build of all projects.
Figure 71. Project build all
2.4.2 Build all build configurations

To build all build configurations for a project, right-click the project and select [Build Configurations]>[Build All]
in the context menu.
UM2609 - Rev 1 page 57/186

UM2609
Figure 72. Project build-all configurations
2.4.3 Headless build

Headless build is intended to be used to build projects that must be integrated into script-controlled builds, such
as nightly builds on build servers for continuous integration process methods or others. The STM32CubeIDE GUI
is never displayed in this case, and the user is not requested any manual interaction with STM32CubeIDE.
STM32CubeIDE includes a headless-build command file to run headless builds. For instance, when using
Windows®, it is located in the STM32CubeIDE installation folder, C:\ST\STM32CubeIDE_1.0.2\STM32CubeID
E. The headless-build.bat file is intended to be run from a command prompt.
Note: Before running any headless build, make sure that the workspace is not opened by STM32CubeIDE. If there is
an STM32CubeIDE running already using the workspace, it is not possible for the headless-build process to
open and build the project.
To run headless build in Windows®, use the following procedure:
1. Open a command prompt
UM2609 - Rev 1 page 58/186

UM2609
2. Setup the path environment to include the path to the STM32CubeIDE installation folder, C:\ST\STM32Cub
eIDE_1.0.2\STM32CubeIDE with the command PATH=C:\ST
\STM32CubeIDE_1.0.2\STM32CubeIDE;%PATH%
The headless-build command file takes some parameters, such as –help to get some help. Figure 73
shows the result of command headless-build.bat –help in the command prompt.
Figure 73. Headless build
3. If a clean build is needed with a log file, using workspace C:\Users\john\STM32CubeIDE\workspace

with project NUCLEO-F401RE, start the headless build with the command headless-build.bat -
project NUCLEO-F401RE -workspace C:\Users\john\STM32CubeIDE\workspace -clean -
build -console >headless_build.log
When the headless build is finished, the headless_build.log file contains all the build output.
2.4.4 Temporary assembly file and preprocessed C code

Save the temporary assembly file by adding the -save-temps flag to the compiler:
1. In the menu, select [Project]>[Properties]
2. Select [C/C++ build]>[Settings]
3. Open the Tool Settings tab
4. Add –save-temps in the [C Compiler]>[Miscellaneous] settings
5. Rebuild the project
The assembler file is located in the build output directory with name filename.s.
The file filenamz.i containing the preprocessed C code is generated also. It shows the code after the
preprocessor but before the compilation. It is advise to examine the content of this file in case of problems with
defines.
2.4.5 Build logging

To enable or disable project build logging, right-click on the project in the Project Explorer view and select
[Properties]. Then, select [C/C++ Build]>[Logging]. The log file location and name are also specified.
To enable a global build log for all projects in a workspace, select [Window], [Preferences], and open [C/C++,
Build, Logging]>[Enable global build logging].
2.4.6 Parallel build and build behaviour

Parallel build occurs when more than one thread is used at the same time to compile and build the code. Most
often, it reduces build time significantly. The optimal number of threads to use is usually equal to the number of
CPU cores of the computer. Parallel build can be enabled and disabled.
To configure parallel build:
1. Right-click on the project in the Project Explorer view
2. Select menu [Project]>[Properties]
3. Select [C/C++ Build] in the Properties panel
4. Open the Behavior tab and configure [Enable parallel build]
The Behavior tab also contains build settings on how to behave on errors, build on resource save, incremental
build, and clean.
UM2609 - Rev 1 page 59/186

UM2609
Linking the project
Figure 74. Parallel build
2.5 Linking the project

This section contains basic information about the linker and linker script files. Detailed information about the linker
can be found in the GNU Linker manual ([EXT-05]), which is accessed from the Information Center. Click on the
[Information Center] toolbar button and open the Information Center view. Open the linker documentation
using the [C/C++ Linker The GNU Linker PDF] link.
UM2609 - Rev 1 page 60/186

UM2609
Linking the project
Figure 75. Linker documentation
2.5.1 Run-time library

The toolchains included in STM32CubeIDE contain two prebuilt run-time C libraries based on newlib. One is the
standard C newlib library and the other is the reduced C newlib-nano. Use newlib-nano to achieve smaller
code size. For information about the differences between newlib-nano and the standard newlib, refer to the
newlib-nano readme file ([ST-09]), accessible from the Information Center.
To select the desired run-time library for use in the project.
1. Right-click on the project in the Project Explorer view
2. Select menu [Project]>[Properties]
3. Select [C/C++ Build]>[Settings] in the Properties panel
4. Open the Tool Settings tab, select [MCU Settings] and configure the [Runtime library] setting
UM2609 - Rev 1 page 61/186

UM2609
Linking the project
Figure 76. Linker run-time library
When newlib-nano is used while floating-point numbers must be handled by scanf/printf, additional options
are required. The reason is that newlib-nano and newlib handle floating-point numbers differently. In
newlib-nano, formatted floating-point number inputs and outputs are implemented as weak symbols. Therefore,
the symbols must be pulled by specifying explicitly if %f is used with scanf/printf using the –u option:
• -u _scanf_float
• -u _printf_float
For example, to enable output float with printf, the command line is as follows:
$ arm-none-eabi-gcc --specs=nano.specs -u _printf_float $(OTHER_LINK_OPTIONS)
The options can be enabled using the [Use float …] checkboxes in [MCU Settings] in the Tool Settings tab.
UM2609 - Rev 1 page 62/186

UM2609
Linking the project
Figure 77. Linker newlib-nano library and floating-point numbers
2.5.2 Discard unused sections

Linker optimization is the process where the linker removes unused code and data sections, dead code, from the
output binary. Run-time and middleware libraries typically include many functions that are not used by all
applications, thus wasting valuable memory unless removed from the output binary.
When using the project wizard to create new projects, the default configuration is that the linker discards unused
sections. To check or change the setting about unused sections, open at any time the build settings for the
project:
1. Right-click the project in the Project Explorer view and select [Properties]
2. In the dialog, select [C/C++ Build]>[Settings]
3. Select the Tool Settings tab in the panel
4. Select [MCU GCC Linker]>[General]
5. Configure [Discard unused sections (-Wl,--gc-sections)] according to the project requirements
6. Rebuild the project
UM2609 - Rev 1 page 63/186

UM2609
Linking the project
Figure 78. Linker discard unused sections
2.5.3 Page size allocation for malloc

When the GNU Tools for STM32 toolchain is used with the standard C newlib library, the page size setting for
malloc can be changed. The newlib default page size is 4096 bytes. If a sysconf() function is implemented
in the user project, this user function is called by _malloc_r().
The following example shows how to implement a sysconf() function with a 128-byte page size. Add a similar
function if there is a need for the application to use a smaller page size than the default 4096 bytes.
UM2609 - Rev 1 page 64/186

UM2609
Linking the project
/**
*****************************************************************************
** File : sysconf.c
*****************************************************************************
**/
/* Includes */
#include <errno.h>
#include <unistd.h>
/* Variables */
extern int errno;
long sysconf(int name)

{
if (name==_SC_PAGESIZE)
{
return 128;
}
else
{
errno=EINVAL;
return -1;
}
}
Note: : If the “GNU ARM Embedded” toolchain is used, it does not call any sysconf() function implemented in the
application but always uses the default sysconf() function in newlib. Also, no call to sysconf() is made if
the “GNU Tools for STM32” toolchain is used with the reduced C newlib-nano library.
2.5.4 Include additional object files

STM32CubeIDE makes it easy to include additional object files that must be linked to a project. They can be files
from other projects, precompiled libraries where no source code is available, or object files created with other
compilers.
4. Select [MCU GCC Linker]>[Miscellaneous]
5. Use the [Add...] icon to add additional object files in several possible ways:
– Enter the filenames in the Add file path dialog
– Use the [Workspace…] or [File system…] buttons to locate the files
UM2609 - Rev 1 page 65/186

UM2609
Linking the project
Figure 79. Linker include additional object files
2.5.5 Treat linker warnings and errors

The GNU linker is normally silent for warnings. One example of such silent warning is seen if the startup code
containing the normal Reset_Handler function is missing in the project. The GNU linker in normal silent mode
creates an elf file and only report a warning output in the Console window about the missing Reset_Handler.
Example of warning message:

arm-none-eabi-gcc -o "NUCLEO-F401RE.elf" @"objects.list" -mcpu=cortex-m4 -
T"C:\Users\johansse\STM32CubeIDE\workspace_um\NUCLEO-F401RE\STM32F401RETX_FLASH.ld"
--specs=nosys.specs -Wl,-Map="NUCLEO-F401RE.map" -Wl,--gc-sections -static -
mfpu=fpv4-sp-d16 -mfloat-abi=hard -mthumb -Wl,--start-group -lc -lm -Wl,--end-group
c:\st\stm32cubeide_1.1.0.19w37\stm32cubeide\plugins
\com.st.stm32cube.ide.mcu.externaltools.gnu-tools-for-stm32.7-2018-q2-
update.win32_1.0.0.201904181610\tools\arm-none-eabi\bin\ld.exe: warning: cannot
find entry symbol Reset_Handler; defaulting to 0000000008000000
Finished building target: NUCLEO-F401RE.elf
In this case, a new elf file is created but, if the warning is not detected, it will not work to debug the project
because the program does not contain the Reset_Handler function. It is possible to configure the linker to treat
warnings as errors by adding the --fatal-warnings option.
When the --fatal-warnings option is used, the linker does not generate the elf file but displays an error in the
console log:
UM2609 - Rev 1 page 66/186

UM2609
Linking the project
c:\st\stm32cubeide_1.1.0.19w37\stm32cubeide\plugins
\com.st.stm32cube.ide.mcu.externaltools.gnu-tools-for-stm32.7-2018-q2-
update.win32_1.0.0.201904181610\tools\arm-none-eabi\bin\ld.exe: warning: cannot
find entry symbol Reset_Handler; defaulting to 0000000008000000
collect2.exe: error: ld returned 1 exit status
make: *** [makefile:40: NUCLEO-F401RE.elf] Error 1
"make -j4 all" terminated with exit code 2. Build might be incomplete.
11:26:30 Build Failed. 1 errors, 6 warnings. (took 7s.193ms)
To use the -Wl,--fatal-warnings option:

4. Select [MCU GCC Linker]>[Miscellaneous]
5. Add -Wl,--fatal-warnings to the [Other flags] field.
Figure 80. Linker fatal warnings
2.5.6 Linker script

The linker script file (.ld) defines the files to include and where things end up in memory. Some important parts
of the linker script file are described in the next sections. For detailed information about the linker, read the C/C++
linker GNU Linker manual ([ST-05]). This manual is available in the documentation section of the Information
Center. Consider sections 3.6 and 3.7 especially.
UM2609 - Rev 1 page 67/186

UM2609
Linking the project
2.5.6.1 The ENTRY command defines the start of the program

The first instruction to execute in a program is defined with the ENTRY command.
Example:
/* Entry Point */
ENTRY(Reset_Handler)
The ENTRY information is used by GDB so that the program counter (PC) is set to the value of the ENTRY address
when a program is loaded. In the example, the program starts to execute from Reset_Handler when a step or
continue command is given to GDB after a load.
Note: The start of the program can be overridden if the GDB script contains a monitor reset command after the load
command. Then the code starts to run from reset.
2.5.6.2 Stack location

The stack location is normally used by the startup file using the _estack symbol. The startup code normally
initializes the stack pointer with the address given in the linker script. For Cortex®-M based devices, the stack
address is also set at the first address in the interrupt vector table.
Example:
/* Highest address of the user mode stack */

_estack = ORIGIN(RAM) + LENGTH(RAM); /* end of "RAM" Ram type memory */
2.5.6.3 Define heap and stack minimum sizes

It is common to define in the linker script the heap and stack minimum sizes to be used by the system.
Example:
Min_Heap_Size = 0x200; /* required amount of heap */

_Min_Stack_Size = 0x400; /* required amount of stack */
The values defined here are normally used later in the linker script to make it possible for the linker to test if the
heap and stack fit in the memory. The linker can then issue an error if there is not enough memory available.
2.5.6.4 Specify memory regions

The memory regions are specified with names ORIGIN and LENGTH. It is common also to have an attribute list
specifying the usage of a particular memory region, such as (rx) with “r” standing for read-only section and “x”
for executable section. It is not requested to specify any attribute.
Example:
/* Memories definition */
MEMORY
{
RAM (xrw) : ORIGIN = 0x20000000, LENGTH = 96K
FLASH (rx) : ORIGIN = 0x8000000, LENGTH = 512K
}
UM2609 - Rev 1 page 68/186

UM2609
Linking the project
2.5.6.5 Specify output sections (.text and .rodata)

The output sections define where the sections such as ‘.text’, ‘.data’ or others are located in the memmory. The
example below tells the linker to put all sections such as .text, .rodata and others in the Flash memory
region. The glue sections mentioned in the example are used by GCC if there are some mixed code in the
program. For instance, the glue code is used if some Arm® code makes a call to thumb code or vice versa.
Example:
/* Sections */
SECTIONS
{
/* The startup code into "FLASH" Rom type memory */
.isr_vector :
{
. = ALIGN(4);
KEEP(*(.isr_vector)) /* Startup code */
. = ALIGN(4);
} >FLASH
/* The program code and other data into "FLASH" Rom type memory */
.text :
{
. = ALIGN(4);
*(.text) /* .text sections (code) */
*(.text*) /* .text* sections (code) */
*(.glue_7) /* glue arm to thumb code */
*(.glue_7t) /* glue thumb to arm code */
*(.eh_frame)
KEEP (*(.init))
KEEP (*(.fini))
. = ALIGN(4);
_etext = .; /* define a global symbols at end of code */
} >FLASH
2.5.6.6 Specify initialized data (.data)

Initialized data values require extra handling as the initialization values must be placed in the Flash memory and
the startup code must be able to initialize the RAM variables with correct values. The example below creates
symbols _sidata, _sdata and _edata. The startup code can then use these symbols to copy the values from
Flash memory to RAM during program start.
Example:
/* Used by the startup to initialize data */

_sidata = LOADADDR(.data);
/* Initialized data sections into "RAM" Ram type memory */

.data :
{
. = ALIGN(4);
_sdata = .; /* create a global symbol at data start */
*(.data) /* .data sections */
*(.data*) /* .data* sections */
. = ALIGN(4);
_edata = .; /* define a global symbol at data end */
} >RAM AT> FLASH
UM2609 - Rev 1 page 69/186

UM2609
Linking the project
2.5.6.7 Specify uninitialized data (.bss)

Uninitialized data values must be reset to 0 by the startup code: the linker script file must identify the locations of
these variables. The example below creates symbols _sbss and _ebss. The startup code can then use these
symbols to set the values of the uninitialized variables to 0.
Example:
/* Uninitialized data section into "RAM" Ram type memory */

. = ALIGN(4);
.bss :
{
/* This is used by the startup in order to initialize the .bss section */
_sbss = .; /* define a global symbol at bss start */
__bss_start__ = _sbss;
*(.bss)
*(.bss*)
*(COMMON)
. = ALIGN(4);
_ebss = .; /* define a global symbol at bss end */
__bss_end__ = _ebss;
} >RAM
2.5.6.8 Check if user heap and stack fit in the RAM

One section of the code is normally dedicated to linker checks about the fact that the needed heap and stack fit
into the RAM together with all other data.
Example:
/* User_heap_stack section, used to check that there is enough "RAM" Ram type memory left
*/
._user_heap_stack :
{
. = ALIGN(8);
PROVIDE ( end = . );
PROVIDE ( _end = . );
. = . + _Min_Heap_Size;
. = . + _Min_Stack_Size;
. = ALIGN(8);
} >RAM
2.5.6.9 Linker map and list files

When building a project generated with STM32CubeIDE, a map and a list file are created in the debug or release
build output folders. These files contain detailed information on the final locations of code and data in the
program.
The Build Analyzer view can be used to analyse the size and location of a program in detail. Read more about
this in Section 7 Build Analyzer.
2.5.7 Modify the linker script

This section presents common use cases requiring to edit the linker script. Editing and managing the script allows
for more exact placements of the code and data.
2.5.7.1 Place code in a new memory region

Many devices have more than one memory region. It is possible to use the linker script to specifically place code
in different areas. The example below shows how to update a linker script to support code to be placed in a new
memory region named IP_CODE.
UM2609 - Rev 1 page 70/186

UM2609
Linking the project
Example:
Original MEMORY AREA
MEMORY
{
}
Add IP_CODE into MEMORY AREA
MEMORY
{
IP_CODE (rx) : ORIGIN = 0x8040000, LENGTH = 256K
}
Place the following code a bit further down in the script, between the .data { ... } and the .bss { ... }
section in the linker script file:
Example:
.ip_code :
{
*(.IP_Code*);
} > IP_CODE
This tells the linker to place all sections named .IP_Code* into the IP_CODE memory region, which is specified
to start at target memory address 0x804 0000.
In the C code, tell the compiler which functions must go to this section by adding
__attribute__((section(".IP_Code"))) before the function declaration.
Example:
__attribute__((section(".IP_Code"))) int myIP_read()

{
// Add code here...
return 1;
}
The myIP_read() function is now placed in the IP_CODE memory region by the linker.
2.5.7.2 Place code in RAM

To place code in the RAM, some modifications of the linker script and startup code are needed. The example
below describes the changes to be applied when the internal RAM is split into a few sections and the code is
placed and executed in one of the internal RAM sections.
UM2609 - Rev 1 page 71/186

UM2609
Linking the project
Define a new memory region in the MEMORY {} region in the linker script:
MEMORY
{
}
Split RAM into memory areas RAM1, RAM_CODE, RAM
MEMORY
{
RAM1 (xrw) : ORIGIN = 0x20000000, LENGTH = 16K
RAM_CODE (xrw) : ORIGIN = 0x20004000, LENGTH = 16K
}
Define an output section for the code in the linker script. This must be placed with a Load Memory Address (LMA)
belonging to the Flash memory, and a Virtual Memory Address (VMA) in RAM:
/* load code used by the startup code to initialize the ram code */
_siram_code = LOADADDR(.RAM_CODE);
.RAM_CODE :
{
. = ALIGN(4);
_sram_code = .; /* create a global symbol at ram_code start */
*(.RAM_Code) /* .RAM_Code sections */
*(.RAM_Code*) /* .RAM_Code* sections */
. = ALIGN(4);
_eram_code = .; /* define a global symbol at ram_code end */
} >RAM_CODE AT> FLASH
The RAM code area must be initialized and code copied from the Flash memory to the RAM code area. The
startup code can access the location information symbols _siram_code, _sram_code and _eram_code.
Add load address symbols for RAM_CODE into the startup file:
/* Load address for RAM_CODE */

.word _siram_code;
.word _sram_code;
.word _eram_code;
UM2609 - Rev 1 page 72/186

UM2609
Linking the project
Add a piece of code into the startup code to copy the RAM code from the Flash memory (LMA) to the RAM
(VMA):
Reset_Handler:
ldr sp, =_estack /* set stack pointer */
/* Copy the ram code from flash to RAM */

movs r1, #0
b LoopRamCodeInit
RamCodeInit:
ldr r3, =_siram_code
ldr r3, [r3, r1]
str r3, [r0, r1]
adds r1, r1, #4
LoopRamCodeInit:
ldr r0, =_sram_code
ldr r3, =_eram_code
adds r2, r0, r1
cmp r2, r3
bcc RamCodeInit
/* Copy the data segment initializers from flash to SRAM */

movs r1, #0
b LoopCopyDataInit
CopyDataInit:
In the C code, instruct the compiler about which functions must go to this section by adding
__attribute__((section(".RAM_Code"))) before the functions declarations:
__attribute__((section(".RAM_Code"))) int myRAM_read()

{
// Add code here...
return 2;
}
2.5.7.3 Place variables at specific addresses

It is possible to place variables at specific addresses in the memory. To achieve this, the linker script must be
modified. The example presented in this section places constant variables handling a product VERSION_NUMBER,
CRC_NUMBER, and BUILD_ID in memory.
UM2609 - Rev 1 page 73/186

UM2609
Linking the project
The first step is to create a new memory region in the linker script:
MEMORY
{
}
Add a new 2K FLASH_V memory region at end of flash

MEMORY
{
FLASH (rx) : ORIGIN = 0x8000000, LENGTH = 512K-2K
FLASH_V (rx) : ORIGIN = 0x807F800, LENGTH = 2K
}
At this point, the memory section must be added:
Place the following a bit further down in the script, between the .data { ... } and the .bss
{ ... } section
.flash_v :
{
*(.flash_v*);
} > FLASH_V
This instructs the linker to place all sections named flash_v* into the flash_v output section in the FLASH_V
memory region, which is specified to start at target memory address 0x807 F800.
A section can be called almost anything except some predefined names such as “data”.
Now, the variables that must be located into the FLASH_V memory must be defined with attributes in the C files:
__attribute__((section(".flash_v.VERSION"))) const uint32_t VERSION_NUMBER=0x00010003;

__attribute__((section(".flash_v.CRC"))) const uint32_t CRC_NUMBER=0x55667788;
__attribute__((section(".flash_v.BUILD_ID"))) const uint16_t BUILD_ID=0x1234;
When debugging this example and examining the memory, it can be observed that:
• Address 0x807 f800 contains VERSION_NUMBER
• Address 0x807 f804 contains CRC_NUMBER
• Address 0x807 f808 contains BUILD_ID
Figure 81. Linker memory output
UM2609 - Rev 1 page 74/186

UM2609
Linking the project
If the inserted data order in the Flash memory is important, map the order of the variables in the linker script. This
makes it possible to define the variables in any file. The linker outputs the variables in the defined order
independently on how the files are linked. As a result, if the CRC_NUMBER is calculated in some way after the
linker has built the file, the CRC_NUMBER can be inserted into the Flash memory file by another tool:
Decide the order in the linker script by adding the specially named sections in order
BUILD_ID, VERSION_NUMBER, CRC_NUMBER, and others(*).
.flash_v :
{
*(.flash_v.BUILD_ID*);
*(.flash_v.VERSION*);
*(.flash_v.CRC*);
*(.flash_v*);
} > FLASH_V
When debugging this example and examining the memory, it can be observed that:
• Address 0x807 f800 contains BUILD_ID
• Address 0x807 f804 contains VERSION_NUMBER
• Address 0x807 f808 contains CRC_NUMBER
Figure 82. Linker memory output specified order
2.5.7.4 Linking in a block of binary data

It is possible to link in a block of binary data into the linked file. The example below describes how to include a ..
/readme.txt file.
Example:
File: readme.txt
Revision: Version 2
Product news: This release ...
One way to include this in the project is to make a reference in a C file to include it using the incbin directive
and the allocatable (“a”) option on the section:
asm(".section .binary_data,\"a\";"
".incbin \"../readme.txt\";"
);
UM2609 - Rev 1 page 75/186

UM2609
Linking the project
The new section binary_data is then added into the linker script with instructions that the section must be put in
the Flash memory. The KEEP() keyword can be used to surround an input section so that the linker garbage
collector does not eliminate the section even if not called:
.binary_data :
{
_binary_data_start = .;
KEEP(*(.binary_data));
_binary_data_end = .;
} > FLASH
This block can then be accessed from the C code:
extern int _binary_data_start;

int main(void)
{
/* USER CODE BEGIN 1 */
int *bin_area = &_binary_data_start;
The binary data, in this case the readme file, can be observed in the Memory view when the project is debugged.
Figure 83. Linker memory displaying file readme
2.5.7.5 Locate uninitialized data in memory (NOLOAD)

There is sometimes a need to have variables located into the Flash, or some other non-volatile memory, which
must not be initialized at startup. In such cases, it is possible to create a specific MEMORY AREA in the linker script
(FLASH_D) and use the NOLOAD directive in the section using the area.
Example:
The MEMORY AREA can be defined like this
MEMORY
{
FLASH (rx) : ORIGIN = 0x8000000, LENGTH = 512K-4K
FLASH_D (rx) : ORIGIN = 0x807F000, LENGTH = 2K
FLASH_V (rx) : ORIGIN = 0x807F800, LENGTH = 2K
}
UM2609 - Rev 1 page 76/186

UM2609
Linking the project
Add a section for FLASH_D using the NOLOAD directive. This can be done using the following code a bit further
down in the linker script:
Place the following a bit further down in the script
.flash_d (NOLOAD) :
{
*(.flash_d*);
} > FLASH_D
Finally, data can be used somewhere in the program by adding a section attribute when declaring the variables
that must be located in the FLASH_D memory.
__attribute__((section(".flash_d"))) uint32_t Distance;

__attribute__((section(".flash_d"))) uint32_t Seconds;
2.5.8 Include libraries

To include a library into a project:
1. Right-click the project where the library must be included in the Project Explorer view and select
[Properties]
4. Select [C Linker]>[Libraries]
5. Add the library name to the [Libraries] field.
Make sure the libray name is added and not the path. According to the GCC convention, the library name is
its filename without the “lib”” prefix and “.a” extension.
Example: for a library file named libmyLib.a, add the library name myLib.
If by any chance the library name do not comply with the GCC convention, the full library name can be
entered, preceded by a colon “:”.
Example: for a library file named STemWin524b_CM4_GCC.a, add the library
name :STemWin524b_CM4_GCC.a.
6. In the [Library Paths] list, set the library location path. Do not include the name of the library in the path.
Example: ${workspace_loc:/myLib/Debug} is the path to the archive file of the library project myLib
residing in the same workspace as the application project.
UM2609 - Rev 1 page 77/186

UM2609
Linking the project
Figure 84. Include a library
The source folders for the header files must also be added to the [Include paths] field:
1. Select [Project]>[Properties]>[Tool Settings]>[C Compiler]>[Directories]
2. press the [Add…] button and add the paths to the source folders for the header files in the library
UM2609 - Rev 1 page 78/186

UM2609
Linking the project
Figure 85. Add library header files to the include paths
Note: Libraries added by include paths are considered as static libraries because they are provided by external
parties. The header files are not rescanned as the content must not have changed for external header files. If
external libraries must be treated as normal source folders, the folders must also be added as source folders to
the project.
Refer to Section 2.5.9 Referring to projects for more information if a project is referring to another project, a
library or a normal project.
2.5.9 Referring to projects

Whenever a project is using code from another project, both projects must be referring to each other.
For a project to refer to a specific build of another project:
1. Select instead [Project]>[Properties]
2. Select [C/C++ General]>[Paths and Symbols]
3. Open the References tab
4. select the [Configuration] that the current project is referring to
UM2609 - Rev 1 page 79/186

UM2609
I/O redirection
Figure 86. Set project references
Note: When multiple projects are used as references, use the [Move Up] and [Move Down] buttons to setup the
priorities.
There are many advantages to set project references correctly:
• The projects involved are not rebuilt more than necessary.
• The indexer is able to find functions from the library and open them. To use this possibility, press the Ctrl key
and, in the editor, click the library function where it is used to open the library source file in the editor.
• It is possible to create the call hierarchy for the functions in the library. To find the call hierarchy, mark the
function name and press Ctrl+Alt+H to display the call hierarchy in the Call Hierarchyview.
If a library project is added as a reference, all the correct settings in the Paths and Symbols property page for the
library is set. The tool settings that depend on this property page are adjusted also.
This is the recommended method of adding libraries developed locally. For more information about adding
libraries, refer to Section 2.5.8 Include libraries.
Another way to have projects referring to each other is as follows:
1. Select [Project]>[Properties]
2. Select [Project References]
3. Select and mark the project for reference
With this method, however, it is not possible to refer to different build configurations and libraries are not set up
automatically.
2.6 I/O redirection

The C run-time library contains many functions, including some to handle I/Os. The I/O-related run-time functions
include printf(), fopen(), fclose(), and many others. It is common practice to redirect the I/O from these
functions to the actual embedded platform. For instance, the printf() output can be redirected to an LCD
display or serial cable while file operations like fopen() and fclose() can be redirected to a Flash memory file
system middleware.
2.6.1 printf() redirection

There are several ways to perform printf() redirection, such as using UART or SWV/ITM. Another solution is
the Real-Time Transfer technology (RTT) provided by SEGGER.
The three techniques compare as follows:
UM2609 - Rev 1 page 80/186

UM2609
I/O redirection
• The UART output is maybe the most commonly used method, where the output from the embedded system
is sent for instance to a terminal using RS-232. It requires some CPU overhead and medium bandwidth.
• The Instrumentation Trace Macrocell (ITM) output is efficient but requires that the Arm® CoreSight™
debugger technology with Serial Wire Viewer (SWV) is supported by the device. This is normally the case for
Cortex®‑M3, Cortex®‑M4, and Cortex®‑M7 based devices. However, the SWV signals must be available and
connected to the board also. It requires low CPU overhead but limited bandwidth. ITM output is explained in
Section 4 Debug with Serial Wire Viewer tracing (SWV).
• The RTT solution is described by SEGGER on their website. RTT is a fast solution but requires SEGGER J-
LINK debug probe.
To enable I/O redirection with UART or ITM output, the file syscalls.c must be included and built into the
project. When printf() is used, it calls the _write() function, which is implemented in syscalls.c.
The syscalls.c file is normally created and included in the project when creating a new STM32CubeIDE
project. The _write() function in this file must be modified to enable printf() redirection by modifying the call
to __io_putchar(). The way to modify _write() depends on the hardware and library implementation.
The example below shows how to update syscalls.c so that printf ouput is redirected to ITM with an
STM32F4 Series device. This is done by adding some header files to access ITM_SendChar() and make a call
to ITM_SendChar().
Original _write() function
__attribute__((weak)) int _write(int file, char *ptr, int len)

{
int DataIdx;
for (DataIdx = 0; DataIdx < len; DataIdx++)

{
__io_putchar(*ptr++);
}
return len;
}
Modified with added header files calling ITM_SendChar(*ptr++);
#include "stm32f4xx.h"
#include "core_cm4.h"

{
int DataIdx;

{
//__io_putchar(*ptr++);
ITM_SendChar(*ptr++);
}
return len;
}
It can be noticed that the _write function in syscalls.c contains a weak attribute. This means that the
_write function can be implemented in any C file used by the project.
UM2609 - Rev 1 page 81/186

UM2609
Position-independent code
For instance, the new _write() function can be added directly into main.c. Omit the weak attribute in that
case, as shown in the example below.
int _write(int file, char *ptr, int len)

{
int DataIdx;

{
}
return len;
}
2.7 Position-independent code

This section is of interest to users working on applications where the final address location is not defined in the
system. This occurs for instance when using a bootloader: the system designer must be able to define the final
location of the application. In such case, position-independent code (PIC) can be used. The –fPIE compiler
option enables the compiler/linker to generate position-independent executable.
Compiling with option –fPIE generates position-independent executable so that if the application is linked for
address 0x800 0000 but placed at 0x800 1000, it still runs. The few things to know about PIC are listed further
in this section.
2.7.1 Adding the –fPIE option

To add the –fPIE option into the tool settings:
4. Select [MCU GCC Compiler]>[Miscellaneous]
5. Add -fPIE to the [Other flags] field.
UM2609 - Rev 1 page 82/186

UM2609
Figure 87. Position independent code, –fPIE
2.7.2 Run-time library

The C run-time library is compiled without using the –fPIE option. So any call to the library must be avoided
when generating position-independent executable. The startup code normally has a call to
__libc_init_array. This call must be removed as in the example below:
/* Call static constructors */

/* bl __libc_init_array */
2.7.3 Stack pointer configuration

Make sure that the stack pointer is set up correctly. The stack pointer must be set in the Reset_Handler in the
startup file as shown in the example below. It must not be assumed that the stack pointer is set by a reset reading
it from the vector table.
Reset_Handler:
UM2609 - Rev 1 page 83/186

UM2609
2.7.4 Interrupt vector table

The vectors in the vector table must be updated if the program is loaded to an offset address. If a program needs
to add the offset to each vector in the table, it can copy the interrupt vector table to the RAM and add the offset to
this vector table.
The vector base register must also be changed so that it points to the new located vector table as shown in the
example below:
/* Set Vector Base Address */

SCB->VTOR=RAM_VectorTable;
2.7.5 Global offset table

The global offset table (GOT) is a table of addresses normally stored in the data section when building and using
the –fPIE option. It is used by the executed program to find, during run-time, addresses of global variables,
unknown at compile time. If no global variable location change is needed, the variables can be located at same
place as located when linking the program. Then the GOT table can be placed in the .text section in the Flash
memory area instead.
The example below shows how to update the linker script with the .got* section. In this case the GOT_START
and GOT_END symbols are added also so that the tools are able to know the GOT location and size.
/* The program code and other data into "ROM" Rom type memory */
.text :
{
. = ALIGN(4);
GOT_START = .;
*(.got*)
GOT_END = .;
*(.eh_frame)
KEEP (*(.init))
KEEP (*(.fini))
. = ALIGN(4);
} >ROM
UM2609 - Rev 1 page 84/186

UM2609
2.7.6 Interrupt vector table and symbols

When debugging the code with an offset, both the load offset and the new symbol address must be specified. The
symbol address to provide is the .text section address. The linker script can be updated by
defining .isr_vector to be located into .text. This avoids the issue of finding the location of .text.
Remove the following
.isr_vector :
{
. = ALIGN(4);
. = ALIGN(4);
} >FLASH
Add KEEP(*(.isr_vector)) instead to first location of .text

/* The program code and other data into "FLASH" Rom type memory */
.text :
{
. = ALIGN(4);
GOT_START = .;
*(.got*)
GOT_END = .;
*(.eh_frame)
KEEP (*(.init))
KEEP (*(.fini))
. = ALIGN(4);
} >FLASH
2.7.7 Debugging position-independent code

When debugging position-independent code located at an offset, the download offset and new symbol address
must be set.
UM2609 - Rev 1 page 85/186

UM2609
Exporting projects
Figure 88. Debugging position independent code
Figure 88 illustrates an example where the download offset is 0x1000 and the symbol address is 0x800 1000. It
is possible to set the symbol address to 0x800 1000 in this case because the .isr_vector is added into
the .text section as described in Section 2.7.6 Interrupt vector table and symbols.
If instead the .isr_vector is located in another section outside .text, the start address of the .text section
must be used with the offset added. For instance, if the map file states that .text starts at
0x0000 0000 0800 0194, the symbol address in this case must be set to 0x800 1194.
Figure 88 shows that the breakpoint is set at main and that the program counter ($pc) is set to the
Reset_Handler symbol into [Run Commands]. This symbol contains the correct address to the
Reset_Handler because gdb uses the base symbol address 0x800 1000. If $pc is not setup during this
debug configuration, the [Resume] checkbox must be disabled to make the program stop after load. In this case,
the program counter must be set manually in the Registers view before starting the program.
2.8 Exporting projects

A project can be exported in many different ways. This section shows how to export a project as a compressed
zip file.
UM2609 - Rev 1 page 86/186

UM2609
Exporting projects
Right-click the project in the Project Explorer view and select [Export…].
Figure 89. Export project
UM2609 - Rev 1 page 87/186

UM2609
Exporting projects
The Export dialog opens. Select [General]>[Archive File] and press [Next >].
Figure 90. Export dialog
UM2609 - Rev 1 page 88/186

UM2609
Importing existing projects
The Export dialog is updated. Select the project to be exported. It is possible to exclude some project files from
the export. In the example in Figure 91, all project and library files are included. A file name must be entered into
the [To archive file] field, possibly browsing to a folder location for the file with the [Browse...] button. In the
example, the default options values are kept unchanged. Press [Finish] to export the project and create the zip
file.
Figure 91. Export archive
2.9 Importing existing projects

This chapter describes different ways to import existing projects into an STM32CubeIDE workspace. The
standard Eclipse® importer is capable of importing Eclipse® projects. This is used to import projects created with
STM32CubeIDE. The project importer is also extended to support the import of ac6 System Workbench for
STM32 projects and Atollic® TrueSTUDIO® projects. Such projects are converted during the import phase to
STM32CubeIDE projects.
2.9.1 Importing an STM32CubeIDE project

A project can be imported in many different ways. This section shows how to import a project that was exported
as a compressed zip file.
• One way to open the Import dialog is to use the menu [File]>[Import…]
• Another way is to right-click the Project Explorer view and select [Import…]
UM2609 - Rev 1 page 89/186

UM2609
Figure 92. Import project
Figure 93. Import dialog
UM2609 - Rev 1 page 90/186

UM2609
Figure 94. Import projects
2.9.2 Importing System Workbench and TrueSTUDIO® projects

To import an ac6 System Workbench for STM32 project or an Atollic® TrueSTUDIO® project into STM32CubeIDE,
it is advised to work on a project copy:
1. Create a copy of the project, either as a copy of the project folder or an export of the project in a zip file
2. Use the copied project for the import into STM32CubeIDE
The way to import the copied project is to open the Import dialog by means of the menu [File]>[Import…] or by
right-clicking the Project Explorer view.
UM2609 - Rev 1 page 91/186

UM2609
Select [Import ac6 System Workbench for STM32 project] or [Import Atollic TrueSTUDIO project] depending
on the original tool used to create the project and press [Next >].
Figure 95. Import System Workbench projects (1 of 3)
UM2609 - Rev 1 page 92/186

UM2609
In this example, the ac6 project is copied into the STM32CubeIDE workspace, hence the [Directory…] button is
used and project STM32F401_Ac6 is selected. The import wizard detects that this is a System Workbench
project.
Press [Finish] to open the Project converter dialog.
Press [OK] to convert the project to an STM32CubeIDE project.

There are two migration guides explaining how to migrate from ac6 System Workbench for STM32 ([ST-06]) and
Atollic® TrueSTUDIO® to STM32CubeIDE ([ST-05]). These guides can be opened from the Technical
Documentation page in the Information Center.
UM2609 - Rev 1 page 93/186

UM2609
2.9.3 Importing using project files association

When STM32CubeIDE is started, a pop-up window asks if .cproject and .project files must be associated
to the program.
Figure 98. Import using project files association
If the association is selected, double-clicking on a .project file in the personal computer file browser triggers
the project import by STM32CubeIDE into the current workspace. The project converter investigates the project,
which is imported directly if made for STM32CubeIDE. If the project comes from another tool, the project
converter tries to identify if it is a known project format and, in such case, converts the project to an
STM32CubeIDE project as described in Section 2.9.2 Importing System Workbench and TrueSTUDIO projects.
2.9.4 Prevent “GCC not found in path” error

When importing old projects, an error in the Problems view can state “Program “gcc” not found in PATH”. The
error is caused by the project use of a deprecated discovery method setting. The error can be removed by
updating the Window Preferences and Project Properties settings.
1. Open [Window]>[Preferences]. In the Preferences dialog, select [C/C++]>[Property Pages Settings] and
enable checkbox [Display “Discovery Options” page].
2. Open [Project Properties]>[C/C++ Build]>[Discovery Options] and disable checkbox [Automate
discovery of paths and symbols].
UM2609 - Rev 1 page 94/186

UM2609
Debugging
3 Debugging
3.1 Introduction to debugging
STM32CubeIDE includes a powerful graphical debugger based on the GDB command-line debugger. It also
bundles GDB servers for the ST-LINK and SEGGER J-Link JTAG probes.
The GDB server is a program that connects GDB on the PC to a target system. The STM32CubeIDE debug
session can autostart a local GDB server or connect to a remote GDB server.
The remote GDB server can be running on the same PC, or on a PC that is accessible via the network and
specified with Host name or IP address and a Port number. When connecting to a remote GDB server, this GDB
server must be started first before a debug session is started in STM32CubeIDE.
When autostart local debugging is selected, STM32CubeIDE automatically starts and stops the GDB server as
required during debugging, thus integrating the GDB server seamlessly.
Note: It is recommended to use compiler optimization level –O0 when building a project that must be debugged.
Debugging with optimization level –Og may work but higher optimization level is hard to debug because of
compiler code optimization.
3.2 Debug configurations

A debug configuration for the project is needed before a debug session can be started. To create the first debug
configuration for the project, right click on the project name in the Project Explorer view and select [Debug
As]>[STM32 Cortex-M C/C++ Application].
UM2609 - Rev 1 page 95/186

UM2609
Debug configurations
Figure 99. Debug as STM32 MCU
Another way to create a new debug configuration is to select the project name in the Project Explorer view and
use the menu [Run]>[Debug As]>[STM32 Cortex-M C/C++ Application].
UM2609 - Rev 1 page 96/186

UM2609
Figure 100. Debug as STM32 MCU menu
A third way to create a new debug configuration is to select project name in the Project Explorer view and press
[F11].
All three different ways open the Debug Configuration dialog.
3.2.1 Debug configuration

The Debug Configuration dialog contains the following tabs:
• Main
• Debugger
• Startup
• Source
• Common
The Debugger and Startup tabs must be updated when creating a new debug configuration while the others do
not require update.
3.2.2 Main tab

The Main tab contains the configuration of the C/C++ application to debug. Usually, when creating a debug
configuration using the sequence described earlier in this chapter, there is no need to make any change in the
Main tab. Make sure the correct elf file and project are selected.
UM2609 - Rev 1 page 97/186

UM2609
Figure 101. Debug configuration main tab
Note: It is possible in the Main tab to define if a build must be made before the debug session is started.
3.2.3 Debugger tab

The Debugger tab configures how to start the GDB server and connect to it. It also defines which GDB server
must be used if [Autostart local GDB server] is selected.
UM2609 - Rev 1 page 98/186

UM2609
Figure 102. Debug configuration debugger tab
The [Port number] edit field contains the default value used by the GDB server selected in field [Debug probe].
Field [Host name or IP address] must be set when [Connect to remote GDB server] is selected.
Field [Debug probe] selects the probe and GDB server to be used for debugging. When using an ST-LINK debug
probe, ST-LINK GDB server or OpenOCD can be used. When using a SEGGER J-LINK probe, use the
SEGGER J-LINK GDB server.
The [GDB Server Command Line options] selections are updated as a function of the [Debug probe] selected.
Detailed information about these settings are available in Section 3.4 Debug using different GDB servers and
sub-sections.
3.2.4 Startup tab

The Startup tab configures how to start a debug session.
UM2609 - Rev 1 page 99/186

UM2609
Figure 103. Debug configuration startup tab
The [Initialization Commands] edit field can be updated with for instance GDB server monitor commands if there
is any special need to send some commands to the GDB server before load commands are sent. For instance,
when using ST-LINK GDB server a monitor flash mass_erase command can be entered here if a Flash
memory erase is needed before load.
UM2609 - Rev 1 page 100/186

UM2609
Manage debug configurations
The [Load Image and Symbols] list box must contain the file(s) to debug. This list is associated with the
following command buttons:
• [Add…]: Add new lines for files for download and/or load symbols
• [Edit…]: Edit the selected line
• [Remove]: Remove the selected line from the list
• [Move up]: Move the selected line upwards
• [Move down]: Move selected line downwards
The [Runtime Options] section contains checkboxes to set the start address and breakpoint, and enable
exception handling and resume.
The start address can be selected as:
• [Default start address]: $pc is set to the start address found in the last loaded .elf file
• [Set program counter (hex)]: $pc is set to the hex value specified in the edit field
• [Specify vector table (hex)]: $pc is updated with the value found in memory using specified address +
offset of 4. This is similar to how $pc is set by a reset using vector table in a Cortex®-M device
When the [Resume] selection is enabled, a continue command is issued to GDB after load to start the program.
Usually, in this case, the program breaks at main if a breakpoint at main is set. Otherwise, when the [Resume]
selection is disabled, the program stays at the ENTRY location specified in the linker script, normally the
Reset_Handler function. A step may be needed in this case to display the Reset_Handler function in the
editor.
When a line in the listbox is selected and [Edit…] is pressed, the following dialog appears for selecting if the file
must be downloaded and if symbols must be loaded.
Figure 104. Add/Edit item
3.3 Manage debug configurations

Each project can have several debug configurations. It is easy to create a copy of an existing debug configuration
and update it with some changes. For instance, one configuration may contain Flash memory loading of new
programs while another does not load any program.
When opening debug configurations from the menu [Run]>[Debug Configurations…], the Debug Configurations
dialog opens. This dialog contains a navigation window on the left side with a toolbar, and the debug configuration
on the right side with the tabs and fields described in Section 3.2 Debug configurations.
UM2609 - Rev 1 page 101/186

UM2609
Debug using different GDB servers
Figure 105. Manage debug configurations
The [Name] field on top of the right pane can be edited using a name for the debug configuration which reflects
the configuration. This name then appears in the navigation window under the [STM32 MCU Debugging] node to
the left when pressing [Apply].
The toolbar left of the navigation window contains icons to manage configurations, for instance to duplicate or
delete a selected configuration.
Figure 106. Manage debug configurations toolbar
These icons are used for the following purpose, from left to right:
• Create new launch configuration
• New launch of configuration prototype
• Export launch configuration
• Duplicate currently selected launch configuration
• Delete selected launch configuration(s)
• Collapse all expanded launch configurations
• Filter launch configurations
3.4 Debug using different GDB servers

STM32CubeIDE includes the following GDB servers:
• ST-LINK GDB server (supports normal debug, live expressions and SWV)
• OpenOCD GDB server (supports normal debug)
• SEGGER J-LINK GDB server (supports normal debug, live expressions and SWV)
UM2609 - Rev 1 page 102/186

UM2609
Different command-line options are used when starting these GDB servers. Therefore the Debugger tab in the
Debug Configurations dialog displays different settings depending on the GDB server selected. This section
describes the individual settings for each server.
3.4.1 Debug using the ST-LINK GDB server

Usually, when the ST-LINK GDB server is used for debugging, there is no need to update the [GDB Server
Command Line Options] in the Debugger tab. In some cases, the default configuration must be updated, for
instance if SWV is intended to be used or if several STM32 boards are connected to the PC.
Figure 107. ST-LINK GDB server debugger tab
Select [SWD] or [JTAG] in [Interface] to define how the ST-LINK probe must connect with the microcontroller. The
SWD interface is usually the preferred choice. It must be selected if SWV is to be used.
When [ST-LINK S/N] is enabled, the serial number of the ST-LINK probe to be used must be entered in the edit/
list field. The [Scan] button can be used to scan and list all detected ST-LINK devices connected to the PC. After
a scan, the S/N of these ST-LINK devices are listed in the list box from which the desired ST-LINK can be
selected. When [Use specific ST-LINK S/N] is enabled, the ST-LINK GDB server is started and connects only to
the ST-LINK with the selected S/N.
UM2609 - Rev 1 page 103/186

UM2609
The [Frequency (kHz)] selection defines the communication speed between the ST-LINK and STM32 device.
When [Auto] is selected, the maximum speed provided by ST-LINK is used. Reduce the frequency in case of
hardware limitations.
The [Access port] selection is used only when debugging a multi-core STM32 device. In such case, the ST-LINK
is connected to the device and the ST-LINK GDB server must be informed of the core to debug.
The [Reset behaviour] contains selections for [Type] and [Halt all cores].
The [Type]can be set as follows:
• [Connect under reset] (default)
• [Software system reset]
• [None] (for attach to a running target where the program is downloaded into the device already. There must
not be any file program command in the Startup tab.)
Note: The selected reset behaviour is overridden if the debug configuration includes Flash programming, in which
case the ST-LINK GDB server uses the STM32CubeProgrammer (STM32CubeProg) command-line program
STM32_Programmer_CLI to program the Flash memory. This program is always started by the ST-LINK GDB
server with mode=UR reset=hwRst so that a device reset is done when loading a new program, disregarding
the selection of the [None] option. This ensures that device programming is made correctly.
[Halt all cores] can be used only when debugging multi-core devices.
The [Serial Wire Viewer (SWV)] selections can only be used when the [SWD] interface is selected. When [SWV]
is enabled, it is required to configure the [Clock Settings]. The [Core Clock] must be set to the speed of the
device and [SWO clock] to the desired speed of the SWO clock. The SWV [Port number] must be set to the port
to be used for the communication of SWV data. The SWV port cannot be set equal to the GDB connection [Port
number].
Enabling [Wait for sync packet] ensures that a larger part of the received SWV data packages are correct
(complete), but may also lead to an increased number of packages being lost. This is especially true if the data
load (number of packages) is high.
[Device settings] contains selections for [Debug in low power modes] and [Suspend watchdog counters
while halted]. These can be defined as:
• [No configuration]
• [Enable]
• [Disable]
The [Misc] selections contains:
• [Verify flash download]
• [Enable live expressions] (To be able to use the Live Expressions view during debugging, the live
expression mechanism must be enabled during startup. It is enabled by default.)
• [Log to file] (Enable in case of debugging problems. It starts the ST-LINK GDB server with a higher log level
and saves the log into a file.)
• [External Loader] (Enable if loading must be made to non-internal STM32 Flash memory). A [Scan] button
is available to access STM32CubeProgrammer external Flash loader files.
When [External Loader] is enabled, there is also an [Initialize] selection. When it is enabled, the Init()
funtion in STM32CubeProgrammer is called after reset. It can be used to configure the device for external
memory access. Usually, initialization must be done by the debugged application.
• [Shared ST-LINK] (Shared ST-LINK must be enabled if other programs must be able to connect to the same
ST-LINK during a debug session.). Refer to Section 3.6.2 Shared ST-LINK for details.
A detailed description of the ST-LINK GDB server is available in the GDB server manual ([ST-07]), which is
available from the Information Center.
Note: STM32_Programmer_CLI is used by the ST-LINK GDB server to program the STM32 or external Flash
memory. In this case, such external Flash memory programming is automatically done using the external loader.
3.4.2 Debug using OpenOCD and ST-LINK

When OpenOCD is used, the [GDB Server Command Line Options] in the Debugger tab contains a generator
options toggle field, which alternates between [Show generator options…] and [Hide generator options…].
When the field is set to [Hide generator options…], the dialog displays additional [GDB Server Command Line
Options] as shown in Figure 108.
UM2609 - Rev 1 page 104/186

UM2609
Figure 108. OpenOCD debugger tab
The [OpenOCD Command] edit field contains the openocd.exe file to be used when debugging. The [Browse]
button can be used to select another version of OpenOCD.
The [OpenOCD Options] edit field can be used to add additional command-line parameters to be used when
starting OpenOCD.
The [Configuration Script] selections can be [Automated Generation] or [User Defined]. When [Automated
Generation] is selected, an openocd.cfg file is created automatically based on the selections made in the
Debugger tab. When [User Defined] is selected, the file must be specified in the [Script File] edit field.
The [Interface]selection [Swd] or [Jtag] selects how the ST-LINK probe must connect with the microcontroller.
[Swd] is usually the preferred choice.
The Frequency selection configures the communication speed between the ST-LINK and STM32 device.
The [Reset Mode] selection contains:
• [Connect under reset]
• [Hardware reset]
• [Software system reset]
• [Core reset]
• [None]
[Enable debug in low power modes] enables debug also with the STM32 device in low-power mode.
UM2609 - Rev 1 page 105/186

UM2609
[Stop watchdog counters when halt] stops the watchdog when the debug session halts the STM32 device.
Otherwise, a watchdog interrupt may be triggered.
[Shared ST-LINK] must be enabled if other programs have to connect to the same ST-LINK during a debug
session. Refer to Section 3.6.2 Shared ST-LINK for details.
3.4.3 Debug using SEGGER J-Link

When [SEGGER J-LINK] is selected in the Debugger tab, the [GDB Server Command Line Options]
corresponds to SEGGER J-Link GDB server.
Figure 109. Segger debugger tab
The [Interface] selection [SWD] or [JTAG] selects how the SEGGER J-Link probe must connect with the
microcontroller. The [SWD] interface is usually the preferred choice; it is required if SWV is used.
The [Initial Speed] selection configures the communication speed used between SEGGER J-Link and the STM32
device.
When [Use specific J-Link S/N] is enabled, enter the S/N of the J-Link to be used when debugging in the edit/list
field. When [Use specific J-Link S/N] is enabled, the SEGGER J-Link GDB server is started and connects only
to the J-Link with the selected S/N.
UM2609 - Rev 1 page 106/186

UM2609
Start and stop debugging
The Device edit field is used if it contains an entry. This field can be used if there is a problem to start the
SEGGER J-Link GDB server with the default device name used in STM32CubeIDE. In such case, enter the
device name used by the SEGGER GDB server in the edit field.
The [Reset strategy] selection contains:
• [Type 0: Normal] - Default.
• [None] - Intended to be used for attaching to the running target. In this case, the program must already be
downloaded into the device. There must not be any file program command in the Startup tab.
The [JTAG Scan Chain] selections can be used only when the [JTAG] interface is selected.
The [Serial Wire Viewer (SWV)] selections can be used only when the [SWD] interface is selected. When [SWV]
is enabled, it is required to configure the [Core Clock]. The [Core Clock] must be set to the speed of the device
and [SWO clock] to either [Auto] or the desired SWO clock speed. Usually, [Auto] is the best choice. The
SWV [Port number] must be set to the port to be used for the communication of SWV data. The SWV port cannot
be set equal to the GDB connection [Port number].
The [Misc] selections contains:
• [Use J-Link script file]
• [Enable live expressions]
To be able to use the Live Expressions view during debug, the live expression mechanism must be enabled
during startup.
• [Verify flash download]
• [Select RTOS variant] list box can be used if [Thread-aware RTOS support] is used with [FreeRTOS] and
[embOS].
When [Thread-aware RTOS support] is used, update the Startup tab: disable [Resume] and [in Run
Commands], add thread 2 and continue. This forces a thread context switch before the continue
command is sent.
Note: A detailed description of SEGGER J-Link GDB server is available in the SEGGER J-Link manual, which can be
accessed from the “Information Center”.
3.5 Start and stop debugging

When a debug configuration is created for the project with the preferred JTAG probe, it is ready for debugging. In
the following sections, the ST-LINK GDB server is used. However, the way to debug the STM32 project is quite
independent of the choice among ST-LINK GDB server, OpenOCD or SEGGER J-Link.
Perform the following steps to prepare for debug:
1. Determine whether the board supports the JTAG debug, SWD debug, or both.
SWD-mode debug is usually the preferred choice.
2. Connect the JTAG cable between the JTAG probe and the target board.
When using STMicroelectronics STM32 Nucleo and Discovery boards, the ST-LINK is usually integrated on
the board. Also, most STMicroelectronics STM32 Evaluation boards contain an embedded ST-LINK.
3. Connect the USB cable between the PC and the JTAG probe.
4. Make sure that the target board has a proper power supply attached.
Once the steps above are performed, a debug session can be started.
3.5.1 Start debugging

Open the Debug Configurations dialog with a right click on the project name in the Project Explorer view and
select [Debug As]>[Debug Configurations…].
It is also possible to open the dialog using the menu [Run]>[Debug Configurations…].
This opens the Debug Configurations dialog.
Note: It is possible to select the project in the “Project Explorer” view and press [F11] to restart a debug session after it
has been closed.
UM2609 - Rev 1 page 107/186

UM2609
Figure 110. Debug configurations
Select in the left pane the debug configuration to use. Press the [Debug] button to start a debug session if all
debug configurations have been made. The project is built if file updates are made, but the building depends on
the debug configuration.
STM32CubeIDE launches the debugger and the following dialog is opened.
UM2609 - Rev 1 page 108/186

UM2609
Figure 111. Confirm perspective switch
It is recommended to enable [Remember my decision] and press [Switch]. It opens the Debug perspective,
which provides a number of views and windows suitable for debugging.
3.5.2 Debug perspective and views

The Debug perspective contains menus, toolbars and views frequently used during debugging.
Figure 112. Debug perspective
The most important views opened by default in the Debug perspective are:
• The Debug view, which displays the program under debug. It also lists threads and offers the possibility to
navigate in the thread by selecting a line in threads.
• The Editor view, which displays the program file. It is possible to set break points and follow program
execution in the file. It is also possible to hoover the cursor over a variable to display its current value. The
features available during file edition are available also during debug, such as opening the declaration of a
function and others.
UM2609 - Rev 1 page 109/186

UM2609
• The Variables view, which displays local variables automatically with their current value when the program is
not running.
• The Breakpoints view, which displays current breakpoints. It is possible to disable and enable breakpoints in
the list. The Breakpoints view also contains a toolbar, which, for instance, enables to remove breakpoints,
and skip breakpoints with one click on the [Skip All Breakpoints] icon.
• The Expressions view, which is used to add and view expressions. An expression may be a single global
variable, structure, or an expression calculating some variables. The values are only updated when the
program is stopped. It is possible to select a global variable in the Editor and drag it over to the Expressions
view instead of entering the variable name.
• The Registers view, which displays the debugged device current values. The values are only updated when
the program is stopped.
• The Live Expressions view, which displays expression values sampled and updated regularly during
program execution. The view allows the creation of mathematical expressions that are evaluated
automatically, such as (Index*4+Offset). The Live Expressions view update requires that live
expressions are enabled in the debug configuration. Refer to Section 3.6.1 Live Expressions view for
details.
The live expressions mechanism is not supported by OpenOCD.
• The SFRs view, which displays the Special Function Registers in the debugged device. Refer to
Section 5 Special Function Registers (SFRs) for details.
• The Console view, which displays different console outputs. By default, the console output from the GDB
server log is displayed. It is possible to change the console log by pressing the [Display Selected Console]
icon to the right of the Console view.
Other views are also useful during debug, among which:
• The Debugger Console view, which can be used if there is a need to manually enter GDB commands. The
easiest way to open the Debugger Console view is to use the [Quick Access] field and enter Debugger in
this field. It lists choices containing the Debugger Console view. Select it to open the view. GDB can be
entered in the Debugger Console view.
For instance, to display 16 words of memory from address 0x800 0000, enter the GDB command x /16
0x8000000.
x /16 0x8000000
0x8000000: 0x20018000 0x080008b1 0x080007e9 0x080007f7
0x8000010: 0x080007fd 0x08000803 0x08000809 0x00000000
0x8000020: 0x00000000 0x00000000 0x00000000 0x0800080f
0x8000030: 0x0800081d 0x00000000 0x0800082b 0x08000839
• The Memory and Memory Browser views, which can be used to display and update memory data.
• The Disassembly view, which is used to view and step in the assembly code.
• The SWV views. Refer to Section 4 Debug with Serial Wire Viewer tracing (SWV) for details.
• The Fault Analyzer view. Refer to Section 6 Fault Analyzer for details.
3.5.3 Main controls for debugging

The [Run] menu in the Debug perspective contains a number of execution control functions.
UM2609 - Rev 1 page 110/186

UM2609
Figure 113. [Run] menu
Alternatively, the Debug perspective toolbar has the following main debug control icons.
Figure 114. Debug toolbar
UM2609 - Rev 1 page 111/186

UM2609
• Reset the device and restart the debug session
• Skip all breakpoints (Ctrl+Alt+B)
• Terminate and relaunch
• Resume (F8)
• Suspend
• Terminate (Ctrl+F2)
• Disconnect
• Step into (F5)
• Step over (F6)
• Step return (F7)
• Instruction stepping mode (assembler stepping)
Press [Terminate and relaunch] to terminate the current debug session, build a new program if the source code
is modified, and relaunch the debug session.
When pressing [Instruction stepping mode], the Disassembly view is opened and further stepping uses
assembler instruction stepping level. Press [Instruction stepping mode] again to toggle back to C/C++ level
stepping.
3.5.4 Run, start and stop a program

Use the toolbar icons as follows to run, step, or stop the program:
• Run the program with the [Resume] toolbar icon ([F8])
• Step into a function with the [Step into] toolbar icon ([F5])
• Step over a function with the [Step over] toolbar icon ([F6])
• Step until return from a function with the [Step return] toolbar icon ([F7])
• Abort running program with the [Suspend] toolbar icon
3.5.5 Set breakpoints

It is common during a debug session to set breakpoints and let the code execute until it reaches a breakpoint.
3.5.5.1 Standard breakpoint

A standard code breakpoint at a source code line can easily be inserted by double-clicking in the left editor
margin, or by right-clicking in the left margin of the C/C++ source code editor. A context menu is proposed in the
latter case.
Figure 115. Debug breakpoint
UM2609 - Rev 1 page 112/186

UM2609
Select the [Toggle Breakpoint] menu command to set or remove a breakpoint at the corresponding source code
line.
3.5.5.2 Conditional breakpoint

When setting a standard breakpoint at a source code line, the program breaks each time it reaches this line. If
that is not the desired behaviour, a condition can be set on the breakpoint that regulates if the program should
actually break or not on that breakpoint.
Update breakpoint properties with a right-click on the breakpoint icon visible left of the editor on a line with
breakpoint set. The [Breakpoint Properties] can also be opened from the Breakpoints view.
Figure 116. Breakpoint properties
Select [Breakpoint Properties...]. The following window opens. In the example illustrated below, i>20 is entered
as a condition.
Figure 117. Conditional breakpoint
With the condition above set, the program breaks each time the line is executed, then GDB tests the condition
and restarts execution if the variable i is not greater than 20. It takes some time for GDB to evaluate the
condition.
The conditions are written in C-style. It is therefore possible to write expressions such as i%2==0” to set more
complex conditions.
UM2609 - Rev 1 page 113/186

UM2609
3.5.6 Attach to running target

It is possible to connect STM32CubeIDE and a debugger via JTAG/SWD to the embedded target without
performing a reset. This approach is useful when trying to resolve problems that occur at rare occasions. Finding
the root cause of the problem in case of a CPU crash is further simplified by learning how to use the Fault
Analyzer view (refer to Section 6 Fault Analyzer).
Before trying this approach, consider whether halting the application in the wrong state could potentially harm the
hardware (for instance in the case of a motor controller application). This is because when GDB connects to the
target, the CPU is halted. This behaviour cannot be modified.
The following three or four steps are needed to update the debug configuration and to attach to running target:
1. Modify the debug configuration to attach to the running target
2. Connect the debug probe to the embedded target
3. Start a debug session using the modified debug configuration
4. Optionally, analyze the CPU fault condition with the Fault Analyzer tool (refer to Fault Analyzer)
Step 1: Modify the debug configuration

The default generated debug configurations in STM32CubeIDE contains settings to reset the device and
download new program, and sets a breakpoint at main. This is not of any use when connecting to a running
system which may, or may not, have crashed.
In order to create a modified debug configuration, perform these steps:
1. Open the Debug Configurations dialog.
2. In the left frame of the Debug Configurations dialog, select the debug configuration associated to the project
to debug and make a copy of this by right-clicking it and selecting [Duplicate].
3. Give the duplicate debug configuration a name.
4. Update the Debugger tab in Debug Configurations:
– When using ST-LINK GDB server and OpenOCD, select [None] as [Reset behaviour].
– When using SEGGER J-Link GDB server, select [None] as [Reset strategy].
5. Change needed/recommended in the Startup tab of Debug Configurations for both ST-LINK GDB server and
SEGGER J-Link GDB server:
– Disable file [Download] in [Load Image and Symbols].
– Disable [Set program counter at (hex)].
– Disable [Set breakpoint at].
– [Exception on divide by zero]and [Exception on unaligned access] can be disabled or enabled.
– Disable [Resume].
If the [Resume] is enabled, the debugger stops the target during connection and, after a short period of
time, sends a continue command.
UM2609 - Rev 1 page 114/186

UM2609
Figure 118. Startup tab attach
Step 2: Connect ST-LINK or SEGGER J-Link to the embedded target

Connect first ST-LINK or the SEGGER J-link to the computer. Then connect it to the embedded target. No reset is
issued.
Step 3: Start a debug session using the modified debug configuration

Important:
Do not launch the debug session using the wrong debug configuration, which may reprogram and reset the target. Use
[Run]>[Debug Configurations...], select the modified debug configuration in the left frame, and click [Debug]. This is the
safest way to launch a debug session with full control of the debug configuration applied and prevents from a potential reset.
The debugger is now connected to the embedded target, which is automatically halted. At this point, different
status registers and variables can be investigated in the application. If the CPU has crashed, the Fault Analyzer
can be used to get a better understanding of the root causes.
3.5.7 Restart or terminate debugging

This section presents various ways to restart and stop a debug session.
UM2609 - Rev 1 page 115/186

UM2609
3.5.7.1 Restart
During debugging, it is sometimes needed to restart the program to examine more carefully problems observed
during debug. In such case, restart the program using the [Reset the chip and restart debug session] toolbar
button or [Run]>[Restart] menu command. This resets the device, and starts the program if [Resume] is enabled
in the debug configuration.
Note: To make restart work, the interrupt vector must be configured and used with the hardware reset. This is usually
the case for STM32 programs located in the Flash memory. However, if the program is located elsewhere such
as in RAM, some manual handling may be needed to make the program start from the expected
Reset_Handler.
3.5.7.2 Restart configurations

It is possible to create restart configurations defining how the reset and restart of a debug session must be
performed. Click on the arrow to the right of the [Reset the chip and restart debug session] toolbar icon.
Figure 119. Reset the chip toolbar
This expands the menu with the [Restart Configurations…] selection.
Figure 120. Restart configurations selection
UM2609 - Rev 1 page 116/186

UM2609
When [Restart Configurations…] is selected, the restart configurations dialog opens.
Figure 121. Restart configurations dialog
The dialog contains a left and right pane:

• The left pane is used to select and create new restart configuration, duplicate an existing restart
configuration, and delete the selected restart configuration. The default restart configurations cannot be
deleted.
• The right pane is used to set [Name] and select the [Type] of reset to be used for the selected configuration.
It is also possible to add additional commands to be used with the reset.
Press [Apply] to save a setting.
UM2609 - Rev 1 page 117/186

UM2609
Figure 122 shows a setting where a new restart configuration is created, which contains an additional command
to set pc to 0x8000ca0.
Figure 122. Restart configurations dialog with additional command
When several reset configurations are defined, they appear in the toolbar dropdown menu in order of use. Select
the desired one to perform a reset.
Figure 123. Select restart configuration
3.5.7.3 Terminate
The most common way to stop a debug session is by clicking the [Terminate] toolbar button. It is also possible to
stop the debug session with the [Run]>[Terminate] menu. When the debug session is stopped, STM32CubeIDE
switches automatically to the C/C++ perspective.
UM2609 - Rev 1 page 118/186

UM2609
Debug features
3.5.7.4 Terminate and relaunch

Use the [Terminate And Relaunch] toolbar button if changes in the source code have been made during the
debug session. Menu command [Run]>[Terminate And Relaunch] can also be used for this purpose. This stops
the debug session, rebuild the program, and relaunches a debug session with the new program loaded.
3.6 Debug features
3.6.1 Live Expressions view

The Live Expressions view in STM32CubeIDE works very much like the Expression view with the exceptions that
all the expressions are sampled live during debug execution. The sampling speed is determined by the number of
expressions being sampled. An increased number of expressions being sampled results in a slower sample rate.
The view displays many different types of global variables. The view also allows users to create mathematical
expressions that are evaluated automatically, such as (i * 4 + offset).
Figure 124. Live Expressions
The view can parse complicated data types and display complex data types like C-language structures. Only one
format of numbers is used at the same time. To change this format, use the dropdown menu.
Figure 125. Live expressions number format
Note: The Live Expressions view does not work with OpenOCD GDB server.
Note: To be able to use the Live Expressions view during debug, the live expression mechanism must be enabled
during startup. It is the case by default when ST-LINK GDB server or SEGGER J-Link is selected in the debug
configuration.
3.6.2 Shared ST-LINK

In the Debugger tab in Debug Configurations for ST-LINK GDB server and OpenOCD, a selection enables shared
ST-LINK. When shared ST-LINK is enabled, the communication to ST-LINK goes via the ST-LINK server. The ST-
LINK server makes it possible for several programs to access the same ST-LINK when shared ST-LINK is
enabled.
STM32CubeProgrammer (STM32CubeProg) also contains a configuration for shared ST-LINK. This means that
when shared ST-LINK is enabled in the debug configuration in STM32CubeIDE, it is possible to debug a program
and let STM32CubeProgrammer access and read the device Flash memory and RAM at the same time.
3.6.3 Debug multiple boards

Debugging with multiple boards is possible using two ST-LINK or SEGGER J-Link probes at the same time.
Connected to two different microcontrollers, both probes are connected to one PC on different USB ports. In this
section, let us suppose that two different boards/microcontrollers are used: HW_A and HW_B.
UM2609 - Rev 1 page 119/186

UM2609
Run configurations
It is possible to run one instance of STM32CubeIDE containing one project for HW_A and one project for HW_B.
The default port to be used is:
• 61234 for ST-LINK GDB server
• 3333 for OpenOCD
• 2331 SEGGER J-Link
This is presented in the Debugger tab in the Debug Configurations dialog. The port number must be changed for
one of the projects to use another port, such as port 61244.
The debug configuration can use GDB connection selection [Autostart local GDB server]. Note that when
debugging multiple boards, two or more debug probes are connected to the PC; the correct serial number must
be selected for each debug configuration.
When the debug configurations has been configured for both projects so that each board is associated to a
specific probe, it is time to test and debug each board individually first. When it is confirmed that this is working,
the debug of both targets at the same time can be started as follow:
1. Start to debug HW_A.
2. The perspective switches automatically to the Debug perspective in STM32CubeIDE when a debug session
for HW_A is started.
3. Switch to the C/C++ perspective.
4. Select the project for HW_B and start debugging it. The Debug perspective opens again.
5. There are two application stacks/nodes in the Debug view, one for each project. When changing the
selected node in the Debug view, the related editor, variable view and others are updated to present
information associated to the selected project.
It is also possible to start the GDB servers manually: select [Connect to remote GDB server] in the debug
configuration. In such case, make sure that the GDB servers are started with parameters defining the individual
ports and serial numbers to be used, and that the corresponding port numbers are used in the Debug
Configurations dialog for each project.
Below is an example using SEGGER J-Link GDB server connecting to SEGGER J-Link, with port=2341 and S/
N=123456789:
>JLinkGDBServerCL.exe -port 2341 -if SWD -select usb=123456789
Information on command-line parameters to be used when starting the GDB servers manually are provided in the
GDB server manuals available from the Information Center.
3.6.4 STM32H7 multicore debugging

Information about how to use STM32H7 multicore devices in STM32CubeIDE is available in [ST-09].
3.6.5 STM32MP1 debugging

Information about how to use STM32MP1 devices in STM32CubeIDE is available in [ST-08].
Users are advised to keep updated with the documentation evolution of the STM32MP1 Series at www.st.com/en/
microcontrollers-microprocessors/stm32mp1-series.
3.6.6 STM32L5 debugging

Information about how to use STM32L5 devices with TrustZone® in STM32CubeIDE is available in [ST-10].
3.7 Run configurations

It is possible to create run configurations to download applications and reset the target without launching a full
debug session. The Run Configurations dialog is similar to the Debug Configurations dialog, however disabled
widgets in the lower part of the Startup tab are not performed. When running a run configuration, the specified
program is flashed but, after program counter is set, the program execution is started in target and the "run"
session in STM32CubeIDE is closed.
To create a run configuration for the project, right-click on the project name in the Project Explorer view and select
[Run As]>[STM32 Cortex-M C/C++ Application].
UM2609 - Rev 1 page 120/186

UM2609
Run configurations
Another way to create a run configuration is to select the project name in the Project Explorer view and use the
menu [Run]>[Run As]>[STM32 Cortex-M C/C++ Application].
Figure 126. Run configurations startup tab
UM2609 - Rev 1 page 121/186

UM2609
Debug with Serial Wire Viewer tracing (SWV)
4 Debug with Serial Wire Viewer tracing (SWV)

4.1 Introduction to SWV and ITM
This section provides information on how to use Serial Wire Viewer tracing (SWV) in STM32CubeIDE.
System analysis and real-time tracing in STM32 requires a number of interaction technologies: Serial Wire Viewer
(SWV), Serial Wire Debug (SWD), Instrumentation Trace Macrocell (ITM) and Serial Wire Output (SWO). These
technologies are part of the Arm® CoreSight™ debugger technology. They are explained below.
Serial Wire Debug (SWD) is a debug port similar to JTAG. It provides the same debug capabilities (run, stop on
breakpoints, single-step) but with fewer pins. It replaces the JTAG connector with a 2-pin interface (one clock pin
and one bi-directional data pin). The SWD port alone does not allow real-time tracing.
The Serial Wire Output (SWO) pin can be used in combination with SWD. It is used by the processor to emit real-
time trace data, thus extending the two SWD pins with a third pin. The combination of the two SWD pins and
SWO pin enables Serial Wire Viewer (SWV) real-time tracing in compatible Arm® processors.
Beware that, SWO being just one pin, it is easy to set a configuration that produces more data than the SWO is
able to send.
The Serial Wire Viewer (SWV) is a real-time trace technology that uses the Serial Wire Debug (SWD) port and the
Serial Wire Output (SWO) pin. The Serial Wire Viewer provides advanced system analysis and real-time tracing
without the need to halt the processor to extract the debug information.
Serial Wire Viewer (SWD) provides the following types of target information:
• Event notification on data reading and writing
• Event notification on exception entry and exit
• Event counters
• Timestamp and CPU cycle information, which can be used for program statistical profiling
The Instrumentation Trace Macrocell (ITM) enables applications to write arbitrary data to the SWO pin, which can
be interpreted and visualized in the debugger. For example, ITM can be used to redirect printf() output to a
SWV console view in the debugger. The standard is to use port 0 for this purpose.
The ITM port has 32 channels. Writing different types of data to different ITM channels allows the debugger to
interpret or visualize the data on various channels differently.
Writing a byte to the ITM port takes only one write cycle, thus taking almost no execution time from the application
logic.
Based on SWV, and ITM trace data, STM32CubeIDE can provide advanced debugger capabilities with special
SWV views.
Note: Arm® does not include SWV/ITM in Cortex®‑M0 or Cortex®‑M0+ cores. Therefore, STM32 devices based on
these cores, such as STM32L053 microcontrollers, do not support SWV/ITM.
4.2 SWV debugging

To debug and use the Serial Wire Viewer (SWV) in STM32CubeIDE, the JTAG probe and the GDB server must
support SWV. The board must also support SWD, and the SWO pin needs to be available and connected to the
JTAG probe.
Note: SWV debugging is supported with ST-LINK GDB server and SEGGER J-Link GDB server. The OpenOCD GDB
server does not support SWV debugging.
The following sections describe the process to create a debug configuration, SWV settings configuration, and how
to use SWV tracing in a debug session.
4.2.1 SWV debug configuration
Step 1: Open the Debug Configurations dialog
Use for instance menu [Run]>[Debug Configurations…] and select the STM32 Cortex®-M debug configuration
to update.
UM2609 - Rev 1 page 122/186

UM2609
SWV debugging
Step 2: Select the SWD interface

Select the [SWD] interface in the Debug Configurations dialog.
Step 3: Enable SWV

Enable [SWV] in the Debug Configurations dialog.
Step 4: Enter the core clock frequency

Enter the [Core Clock] frequency in the Debug Configurations dialog. This must correspond to the value set by
the application program to be executed.
Usually, the core clock setting is stored in the SystemCoreClock variable when using projects imported from
STM32 firmware examples or created with STM32CubeMX. One method to inspect the core clock value is to start
a debug session and add the SystemCoreClock variable to the Expressions view. Make sure that the system
core clock is configured by the application before reading the value.
If the SystemCoreClock is not updated, change the program and add a call to the function
SystemCoreClockUpdate(). Rebuild the program, restart debugging and inspect the SystemCoreClock
value again.
Figure 127. SWV core clock
Step 5: Enter the SWO clock frequency

Enter the [SWO Clock] frequency in the Debug Configurations dialog. It depends on the JTAG probe and must be
a multiple of the [Core Clock] value. For SEGGER J-Link-based probes, it is also possible to select [Auto], which
automatically uses the highest available frequency by taking into account the capacity of the JTAG probe and the
[Core Clock].
Step 6: Save the configuration

Press [Apply]in the Debug Configurations dialog to save the configuration.
UM2609 - Rev 1 page 123/186

UM2609
SWV debugging
Figure 128. SWV configuration for ST-LINK GDB server
UM2609 - Rev 1 page 124/186

UM2609
SWV debugging
Figure 129. SWV configuration for SEGGER J-Link
Step 7: Start a debug session

Press [Debug] to start a debug session. Make sure that the probe and board are connected.
Step 8: Possibly suspend the target

[Suspend] the target if it has not stopped at a breakpoint.
Step 9: Open a SWV view

Open one of the SWV views. For first-time users, it is recommended to open the SWV Trace log view because it
gives a good overview of incoming SWV packages and how well the tracing is working.
Select the [Window]>[Show View]>[SWV]>[SWV Trace log ] menu command to open the SWV Trace log view.
UM2609 - Rev 1 page 125/186

UM2609
SWV debugging
Figure 130. SWV show view
Step 10: View the trace log

The SWV Trace log view is now visible.
Figure 131. SWV Trace log view
4.2.2 SWV settings configuration
Step 1: Open the Serial Wire Viewer settings

Click on the [Configure Trace] toolbar button in the SWV Trace Log view to open the Serial Wire Viewer settings
dialog.
UM2609 - Rev 1 page 126/186

UM2609
SWV debugging
Figure 132. SWV [Configure Trace] toolbar button
Note: The [Configure Trace] toolbar button is available in all SWV views.
Step 2: Configure the trace data

Configure the data to be traced in the Serial Wire Viewer settings dialog.
For this example [PC Sampling] and [Timestamps] are enabled.
Figure 133. SWV settings dialog
The SWV settings dialog has the following configurations:

• [Clock Settings]: These fields are disabled and only present the values used and configured in the Debug
Configurations for the debug session. If these values need to be changed, close the debug session and
open the Debug Configurations to modify them.
UM2609 - Rev 1 page 127/186

UM2609
SWV debugging
• [Trace Events]: The following events can be traced.

– [CPI]: Cycles per instruction. For each cycle beyond the first one that an instruction uses, an internal
counter is increased with one. The counter (DWT CPI count) can count up to 256 and is then set to 0.
Each time that happens, one of these packages are sent. This is one aspect of the processors
performance and used to calculate instructions per seconds. The lower the value, the better the
performance.
– [SLEEP]: Sleep cycles. The number of cycles the CPU is in sleep mode. Counted in DWT Sleep
count register. Each time the CPU has been in sleep mode for 256 cycles, one of these packages is
sent. This is used when debugging for power consumption or waiting for external devices.
– [FOLD]: Folded instructions. A counter for how many instructions are folded (removed). Every 256
instruction folded (taken zero cycles) will receive one of these events. Counted in DWT Fold count
register.
Branch folding is a technique where, on the prediction of most branches, the branch instruction is
completely removed from the instruction stream presented to the execution pipeline. Branch folding
can significantly improve the performance of branches, taking the CPI for branches below 1.
– [EXC]: Exception overhead. The DWT Exception count register keeps track of the number of CPU
cycles spent in exception overhead. This includes stack operations and returns but not the time spent
processing the exception code. When the timer overflows, one of these events is sent. Used to
calculate the actuel exception handling cost to the program.
– [LSU]: Load Store Unit Cycles. The DWT LSU count register counts the total number of cycles the
processor is processing an LSU operation beyond the first cycle. When the timer overflows, one of
these events is sent.
With this measurement, it is possible to track the amount of time spent in memory operations.
– [EXETRC]: Trace Exceptions. Whenever an exception occurs, exception entry, exception exit and
exception return events are sent. These events can be monitored in the SWV Exception Trace Log and
SWV Exception Timeline Graph views. From these views, it is possible to jump to the exception
handler code for that exception.
• [PC Sampling]: Enabling this starts sampling the Program Counter at some cycle interval. Since the SWO
pin has a limited bandwidth, it is not advised to sample to fast. Experiment with the [Resolution] (cycles/
sample setting) to be able to sample often enough. The results from the sampling are used, among other
things, for the SWV Statistical Profiling view.
• [Timestamps]: Must be enabled to know when an event occurred. The [Prescaler] should only be changed
as a last effort to reduce overflow packages.
• [Data Trace]: It is possible to trace up to four different C variable symbols, or fixed numeric areas of the
memory. To do that, enable one comparator and enter the name of the variable or the memory-address to
trace. The value of the traced variables can be displayed both in the Data Trace and Data Trace Timeline
Graph views.
• [ITM Stimulus Ports]: There are 32 ITM ports available, which can be used by the application. For instance,
the CMSIS function ITM_SendChar can be used to send characters to port 0 refer to Section 4.3.6 SWV
ITM Data Console and printf redirection). The packages from the ITM ports are displayed in the SWV ITM
Data Console view.
Note: It is recommended to limit the amount of data traced. Most STM32 microcontrollers read and write data faster
than the maximum SWO pin throughput. Too many trace data result in data overflow, lost packages and possibly
corrupt data. For optimum performance, trace only data necessary to the task at hand.
Overflow while running SWV is an indication that SWV is configured to trace more data than the SWO pin is able
to process. In such a case, decrease the amount of data traced.
Enable [Timestamps] to use any of the timeline views in STM32CubeIDE. The default [Prescaler] is 1. Keep this
value, unless problems occur related to SWV package overflow.
UM2609 - Rev 1 page 128/186

UM2609
SWV debugging
Three examples are provided below for illustrating SWV trace configuration:
• Example 1: To trace the value of a global variable, enable [Comparator] and enter the name of the variable
or the memory address to be traced.
The value of the traced variable is displayed both in the Data Trace and Data Trace Timeline Graph views.
• Example 2: To profile program execution, enable [PC sampling]. In the beginning, a high value for the
[Cycles/sample] is recommended.
The result from the PC sampling is then displayed in the SWV Statistical Profilingview.
• Example 3: To trace the exceptions occurring during program execution, enable [Trace Event EXETRC:
Trace Exceptions].
Information about the exceptions is then displayed in the SWV Exception Trace Log and SWV Exception
Timeline Graph views.
Step 3: Save the SWV configuration

Click on the [OK] button to save the SWV configuration. The configuration is saved together with other debug
configurations and remains effective until changed.
4.2.3 SWV tracing
Step 1: Start SWV trace recoding

Press the [Start/Stop Trace] toolbar button in one of the SWV views to send the SWV settings to the target board
and start the SWV trace recoding. This toolbar button is available in all SWV views. The board does not send any
SWV package until it is properly configured. The SWV configuration must be resent if the configuration registers
on the target board are reset. Actual tracing does not start until the target starts to execute.
Figure 134. SWV [Start/Stop Trace] toolbar button
Note: The tracing cannot be configured while the target is running. Pause the debugging before attempting to send a
new configuration to the board. Each new or updated configuration must be sent to the board to take effect. The
configuration is sent to the board when the [Start/Stop Trace] button is pressed.
Step 2: Start the target

Press the [Resume] toolbar button on top of the Debug perspective to start the target.
Step 3: SWV Trace Log view

SWV packages are displayed in the SWV Trace Log view.
Figure 135. SWV Trace Log PC sampling
UM2609 - Rev 1 page 129/186

UM2609
SWV views
Step 4: Clear collected SWV data

When the target is not running, the collected SWV data can be cleared by pressing the [Remove all collected
SWV data] toolbar button. This toolbar button is available in all SWV views.
Figure 136. [Remove all collected SWV data] toolbar button
4.3 SWV views

The SWV views that display SWV traces data are:
• SWV Trace Log: Lists all incoming SWV packages in a spreadsheet. Useful as a first diagnostic for the trace
quality.
• SWV Exception Trace Log: The view has two tabs, one is similar to the SWV Trace Log view and the other
tab displays statistical information about exception events.
• SWV Exception Timeline Graph: A graph displaying the distribution of exceptions over time.
• SWV Data Trace: Tracks up to four different symbols or areas in the memory.
• SWV Data Trace Timeline Graph: A graphical display that shows the distribution of variable values over
time.
• SWV ITM Data Console: Prints readable text output from the target application. Typically this is done via
printf() with output redirected to ITM channel 0.
• SWV Statistical Profiling: Displays statistics based on the Program Counter (PC) sampling. Shows the
amount of execution time spent within various functions.
Figure 137. SWV views selectable from the menu
Note: More than one SWV view may be open at the same time for the simultaneous tracking of various events.
The SWV views toolbars contain these usual control icons.
Figure 138. SVW views common toolbar
• Configure trace
• Start/Stop trace
• Remove all collected SWV data
• Scroll lock
• Minimize
• Maximize
UM2609 - Rev 1 page 130/186

UM2609
SWV views
The SWV graph views toolbars contain these extra control icons.
Figure 139. SVW graph views extra toolbar
• Save graph as image
• Switch between seconds and cycle scale
• Adjust the Y-axis to best fit
• Zoom in
• Zoom out
4.3.1 SWV Trace Log

The SWV Trace Log view lists all incoming SWV packages in a spreadsheet. The data in this view can be copied
to other applications in CSV format by selecting the rows to copy and type Ctrl+C. The copied data can be pasted
into another application with the Ctrl+V command.
Figure 140. SWV Trace Log PC sampling and exceptions
The column information in the SWV Trace Log view is described in Table 2.
Table 2. SWV Trace Log columns details
Name Description
Index The package ID. Shared with the other SWV packages.
Type The type of package (example PC sample, data PC value (comp 1), exceptions, overflow).
Data The package data information.
Cycles The timestamp of the package in cycles.
Time(s) The timestamp of the package in seconds.
Extra info Optional extra package information.
4.3.2 SWV Exception Trace Log

The SWV Exception Trace Log view is composed of two tabs.
UM2609 - Rev 1 page 131/186

UM2609
SWV views
Data tab
The first tab is similar to the SWV Trace Log view, but is restricted to exception events. It also provides additional
information about the type of event. The data can be copied and pasted into other applications. Each row is linked
to the code for the corresponding exception handler. Double-click on the event to open the corresponding
interrupt hander source code in the Editor view.
Note: Enable [Trace Event EXETRC: Trace Exceptions] in the Serial Wire Viewer settings dialog to trace exceptions
during program execution. Enable [Timestamps] to log cycle and time for each interrupt package.
Figure 141. SWV Exception Trace Log – Data tab
The column information in the SWV Exception Trace Log – Data tab is described in Table 3.
Table 3. SWV Exception Trace Log – Data columns details
Name Description
Index The exception package ID. Shared with the other SWV packages.
Type Each exception generates three packages: Exception entry, Exception exit and then an Exception return package.
Name The name of the exception. Also the exception or interrupt number.
Peripheral The peripheral for the exception.
The name of the interrupt handler function for this interrupt. Updated when debug is paused. Is cached during the
Function
whole debug session. By double clicking the function, the editor will open that function in the source code.
Cycles The timestamp for the exception in cycles.
Time(s) The timestamp for the exception in seconds.
Extra info Optional extra information about that package.
Statistics tab
The second tab displays statistical information about exception events. This information may be of great value
when optimizing the code. Hypertext links to exception handler source code in the editor is included.
UM2609 - Rev 1 page 132/186

UM2609
SWV views
Figure 142. SWV Exception Trace Log – Statistics tab
The column information in the SWV Exception Trace Log – Statistics tab is described in Table 4.
Table 4. SWV Exception Trace Log – Statistics columns details
Name Description
Exception The name of the exception provided by the manufacturer. Also the exception or interrupt number.
The name of the interrupt handler for this interrupt. Updated when debug is paused. Is cached during the
Handler whole debug session.
By double clicking the handler, the editor will open that function in the source code.
% of This exception type’s share, in percentage, of all exceptions.
Number of The total number of entry packets received by SWV of this exception type.
% of exception time How big part of the execution time for all exceptions that this exception type have.
How big part of the total execution time for this debug session that this exception type have. All the
% of debug time
timers are restarted when the Empty SWV-Data button is pressed.
Total runtime The total execution time in cycles for this exception type.
Avg runtime The average execution time in cycles for this exception type.
Fastest The execution time in cycles for the fastest exception of this exception type.
Slowest The execution time in cycles for the slowest exception of this exception type.
First The first encounter of an entry event for this exception type in cycles.
First(s) The first encounter of an entry event for this exception type in seconds.
Latest The latest encounter of an entry event for this exception type in cycles.
Latest(s) The latest encounter of an entry event for this exception type in seconds.
4.3.3 SWV Exception Timeline Graph

The SWV Exception Timeline Graph view contains a graph displaying the distribution of exceptions over time.
Remember that each exception sends up to three SWV packages. Moving the mouse over an exception bar in the
view displays a tooltip of the SWV exception package. Double-click on the event in the tooltip to open the code for
the exception handler in the Editor view.
Note: The SWV Exception Timeline Graph view does not work in STM32CubeIDE v1.1.0. The screen shot below is
taken with Atollic® TrueSTUDIO®.
UM2609 - Rev 1 page 133/186

UM2609
SWV views
Figure 143. SWV Exception Timeline Graph
Note: Each interrupt is displayed with 3 packages (Exception entry, Exception exit and Exception return).
4.3.4 SWV Data Trace

The SWV Data Trace view tracks up to four different symbols or areas in the memory. For example, global
variables can be referenced by name. The data can be traced on Read, Write and Read/Write.
Enable [Data Trace] in Serial Wire Viewer settings. In Figure 144, two global variables pos1 and pos2 in the
program are traced on [Write] access.
Figure 144. SWV Data Trace configuration
When running the program in debugger with SWV trace enabled the SWV Data Trace view displays this
information when [Comparator 0] with pos1 data is selected in the [Watch] list.
UM2609 - Rev 1 page 134/186

UM2609
SWV views
Figure 145. SWV Data Trace
The column information in the SWV Data Trace described in Table 5.
Table 5. SWV Data Trace columns details
Name Description
Access Read or Write access type.

Value The value of data read or written.
PC The PC location where read or write access occurs.
Cycles The timestamp for the package in cycles.
Time(s) The timestamp for the package in seconds.
4.3.5 SWV Data Trace Timeline Graph

The SWV Data Trace Timeline Graph view contains a graphical display that shows the distribution of variable
values over time. It applies to the variables or memory areas in the SWV Data Trace. The following is displayed
when using the timeline graph displaying global variables pos1 and pos2 counting up and down.
UM2609 - Rev 1 page 135/186

UM2609
SWV views
Figure 146. SWV Data Trace Timeline Graph
The SWV Data Trace Timeline Graph has the following features:
• The graph can be saved as a JPEG image file by clicking on the camera toolbar button.
• The graph shows the time in seconds by default but can be changed to cycles by clicking on the clock
toolbar button.
• Y-axis can be adjusted to best fit by clicking on the y-axis toolbar button.
• Zoom in and out by clicking on the [+] and [–] toolbar buttons.
• The zoom range is limited while debug is running. Zoom details are available when debug is paused.
4.3.6 SWV ITM Data Console and printf redirection

The SWV ITM Data Console prints readable text output from the target application. Typically, this is done via
printf() with output redirected to ITM channel 0. Other ITM channels can get their own console views.
To use the SWV ITM Data Console view, first enable one or more of the 32 ITM ports in the Serial Wire Viewer
settings dialog.
UM2609 - Rev 1 page 136/186

UM2609
SWV views
Figure 147. SWV settings
The packages from the ITM ports are displayed in the SWV ITM Data Console view. The CMSIS function
ITM_SendChar() can be used by the application to send characters to the port 0, and the printf() function
can be redirected to use the ITM_SendChar() function.
The following describes how to setup printf redirection over ITM:
1. Configure first file syscalls.c. Usually, the syscalls.c file is located in the same source folder as main
.c.
If no syscalls.c file is available in the project, it can be copied from another STM32CubeIDE project. One
way to get the file is to create a new STM32 empty project for the device. In the Src folder, this project
contains a syscall.c file. Copy this file to a source folder in the project where it is needed.
2. Inside the syscalls.c file, replace the _write() function with code calling ITM_SendChar() instead of
__io_putchar()

{
int DataIdx;

{
}
return len;
}
3. Locate the core_cmX.h file, which contains the function ITM_SendChar(). The core_cmX.h file is
included by the Device Peripheral Access Layer header file (for instance stm32f4xx.h, which in turn must
be included in the syscalls.c file).
#include "stm32f4xx.h"
Use the Include Browser view to find the Device Peripheral Access Layer header file. Drop the core file in
the Include Browser view, and check which files are including the core_cmX.h file.
UM2609 - Rev 1 page 137/186

UM2609
SWV views
4. Test by adding include stdio.h and call to printf() into the application. Make sure that printf() is not
called too often.
#include <stdio.h>
printf("Hello World %d\n", pos1);
5. Start a debug session and enable [ITM port 0] in the SWV ITM Data Console view.
6. Open the SWV ITM Data Console view and start tracing using the red [Start/Stop Trace] button on the
toolbar in this view.
7. Start the program. Print commands are logged to the Port 0 tab in the view.
Figure 148. SWV ITM Data Console
8. It is possible to open new port x tabs (x from 1 to 31) by pressing the green [+] button on the toolbar. This
opens the Add Port dialog. In the dialog select the [ITM Port number] to be opened to display it as a tab in
the SWV ITM Data Consoleview.
Figure 149. SWV ITM port configuration
Note: Study the ITM_SendChar() function to learn how to write a function that transmits characters to another ITM
port channel.
4.3.7 SWV Statistical Profiling

TheSWV Statistical Profiling view displays statistics based on Program Counter (PC) sampling. It shows the
amount of execution time spent within various functions. This is useful when optimizing code. The data can be
copied and pasted into other applications. The view is updated when debugging is suspended.
UM2609 - Rev 1 page 138/186

UM2609
SWV views
1. Configure SWV to send Program Counter samples, as shown in Figure 150. Enable [PC Sampling] and
[Timestamps].
With the given [Core Clock] cycle intervals, SWV reports the Program Counter values to STM32CubeIDE.
Set the [PC Sampling] to a high [Cycle/sample] value to avoid interface overflow.
Figure 150. SWV PC sampling enable
2. Open the SWV Statistical Profiling view by selecting [Window]>[Show View]>[SWV Statistical Profiling].
The view is empty since no data is collected yet.
3. Press the red [Start/Stop Trace] button to send the configuration to the board.
4. Resume program debugging. STM32CubeIDE starts collecting statistics about function usage via SWV
when the code is executing in the target system.
5. Suspend (Pause) the debugging. The view displays the collected data. The longer the debugging session,
the more statistics are collected.
UM2609 - Rev 1 page 139/186

UM2609
Change the SWV trace buffer size
Figure 151. SWV Statistical Profiling
Note: A double-click on a function line in the SWV Statistical Profiling view opens the file containing the function in the
editor.
The column information in the SWV Statistical Profiling is described in Table 6.
Table 6. SWV Statistical Profiling columns details
Name Description
The name of the function which is calculated by comparing address information in SWV packages with the
Function
program elf file symbol information.
% in use The calculated percentage of time the function is used.

Samples The number of samples received from the function.
Start address The start address for the function.
Size The size of the function.
4.4 Change the SWV trace buffer size

The incoming SWV packages are saved in the Serial Wire Viewer trace buffer, which has a default maximum size
of 2 000 000 packages. To trace more packages, this figure must be increased.
UM2609 - Rev 1 page 140/186

UM2609
Common SWV problems
Select the [Windows]>[Preferences] menu. In the Preferences dialog, select [STM32Cube]>[Serial Wire
Viewer]. Update [Trace buffer size] if needed.
Figure 152. SWV Preferences
The buffer is stored in the heap. The allocated heap is displayed by first selecting the [Windows]>[Preferences]
menu. In the Preferences dialog, select [General]. Enable [Show heap status] to display the current heap and
allocated memory in the bottom right corner of STM32CubeIDE. There is an upper limit to the amount of memory
STM32CubeIDE can allocate. This limit can be increased to store more information during a debug session.
To update the memory limit, proceed as follows:
1. Navigate to the STM32CubeIDE installation directory. Open the folder in which the IDE is stored.
2. Edit the stm32cubeide.ini file and change the –Xmx1024m parameter to the desired size in megabytes.
3. Save the file and restart STM32CubeIDE.
4.5 Common SWV problems

The following issues can occur when attempting to debut with SWV tracing:
• SWV is not enabled in the debug configuration currently used.
• The SWV Trace is not started, the red Start/Stop Trace button on the toolbar in some SWV view needs to
be pressed to enable SWV and send SWV configuration to the target board. Then start the program to
receive SWV data. For some SWV views the program then needs to be stopped again to visualize received
SWV information.
• The SWO receives an excess of data. Reduce the amount of data enabled for tracing.
• The JTAG probe, the GDB server, the target board, or possibly some other part, does not support SWV.
UM2609 - Rev 1 page 141/186

UM2609
Common SWV problems
• The target [Core Clock] is incorrectly set. It is very important to select the right [Core Clock].
If the frequency of the target [Core Clock] is unknown, it can sometimes be found by setting a breakpoint in
a program loop and open the Expressions view, when the breakpoint is hit.
Click on [Add new expression], type SystemCoreClock and press [Enter]. This is a global variable that,
according to the CMSIS standard, must be set by the software to the correct speed of the [Core Clock].
In CMSIS standard libraries, a function called SystemCoreClockUpdate() can be included in main() to
set the SystemCoreClock variable. Use the Variable view to track it.
Note: If the software dynamically changes the CPU clock speed during runtime, this might cause SWV to stop as the
clocking suddenly becomes wrong during execution.
To make sure that all data is received, apply the following steps:
1. Open the SWV configuration. Disable all tracing except [PC Sampling] and [Timestamps]. Set the
[Resolution] to the highest possible value.
2. Save, and open the SWV Trace Log view.
3. Start tracing.
4. Make sure that incoming packages can all be seen in the SWV Trace Log view.
UM2609 - Rev 1 page 142/186

UM2609
Special Function Registers (SFRs)
5 Special Function Registers (SFRs)

5.1 Introduction to SFRs
Special Function Registers (SFRs) can be viewed, accessed and edited via the SFRs view. The view displays the
information for the current project. Its content changes if another project is selected. To open the view from the
menu, select the [Window]>[Show View]>[SFRs] menu command or use the [Quick Access] field, search for
“SFR”, and select it from the views.
Figure 153. Open the SFRs view using the [Quick Access] field
5.2 Using the SFRs view

The SFRs view contains information about peripherals, registers and bit fields for the STM32 device used in the
project. When debugging the project, the registers and bit fields are populated with the values read from the
target.
Figure 154. SFRs view
UM2609 - Rev 1 page 143/186

UM2609
Updating CMSIS-SVD settings
The top of the SFRs view contains a search field to filter visible nodes, such as peripherals, registers, bit fields.
Upon text entry in the search field, only the nodes containing this text are displayed.
The information at the bottom of the SFRs view displays detailed information about the selected line. For registers
and bit fields, this includes [Access permission]and [Read action] information.
The [Access permission] contains the following details:
• [RO](read-only)
• [WO](write-only)
• [RW](read-write)
• [W1](writeOnce)
• [RW1](read-writeOnce)
The Read action contains information only if there is a read action when reading the register or bit field:
• [clear]
• [set]
• [modify]
• [modifyExternal]
The toolbar buttons are located at the top-right corner of the SFRsview.
Figure 155. SFRs view toolbar buttons
The [RD] button in the toolbar is used to force a read of the selected register. It causes a read of the register even
if the register, or some of the bit fields in the register, contains a ReadAction attribute set in the SVD file.
When the register is read by pressing the [RD] button, all the other registers visible in the view are read again also
to reflect all register updates.
The program must be stopped to read registers.
The base format buttons ([X16], [X10], [X2]) are used to change the registers display base.
The [Configure SVD settings] button opens the CMSIS-SVD Settings Properties Panelfor the current project.
The [Pin] button ("don’t follow" selection) can be used to keep focus on the current displayed SVD file even if the
Project Explorer view is switched to another project.
5.3 Updating CMSIS-SVD settings

The SFRs view for a project can display two CMSIS-SVD (System View Description) files for this project:
• The default file selected by STM32CubeIDE is the SVD file for the selected device in the project
• The other file can be a custom SVD file made to visualize specific user hardware configuration
To update the settings, use the [Configure SVD settings] toolbar button in the SFRs view to open the CMSIS-
SVD Settings properties.
Figure 156. SFRs CMSIS-SVD Settings
UM2609 - Rev 1 page 144/186

UM2609
Updating CMSIS-SVD settings
All SVD files must comply with the syntax outlined in the CMSIS-SVD specification available on Arm® website. If
these requirements are not met, the SFRs view is likely not to show any register information.
The [Device file] field is used for the System View Description (SVD) file. This file must describe the whole
device. Other views may fetch information from the SVD file pointed out by this field, therefore it is recommended
to use this field only for SVD files containing full STM32 device description. Updated SVD files can be obtained
from STMicroelectronics (refer to the HW Model, CAD Libraries and SVD columns in the device description
section on the STMicroelectronics website at www.st.com.
The [Custom file] field can be used to define special function registers related to custom hardware, in order to
simplify the viewing of different register states. Another possible use case is to create an SFR favourites’ file,
containing a subset of the content in the [Device file]. This subset may be for instance composed of frequently
checked registers. If a [Custom file] is pointed out, a new top-node in the SFRs view is created, which contains
the [Custom file] related register information.
Both fields may be changed by the user and both fields may be used at the same time.
Note: • It is possible to write new values in the value columns of registers and bit fields when these have write
access permission.
• It is possible to use the SFRs view while the target is running when using the ST-LINK GDB server.
However the [Live expression] option in the debug configuration must be enabled in this case.
• It is not possible to use SFRs view while the target is running when using OpenOCD or SEGGER J-Link.
• The SFRs view can also be useful in the C/C++ Editing perspective, however then only the names and
addresses of the registers are displayed.
UM2609 - Rev 1 page 145/186

UM2609
Fault Analyzer
6 Fault Analyzer
6.1 Introduction to the Fault Analyzer
The STM32CubeIDE Fault Analyzer feature interprets information extracted from the Cortex®-M nested vector
interrupt controller (NVIC) in order to identify the reasons that caused a fault. This information is visualized in the
Fault Analyzer view. It helps to identify and resolve hard-to-find system faults that occur when the CPU is driven
into a fault condition by the application software.
Among such conditions are:
• Accessing invalid memory locations
• Accessing memory locations on misaligned boundaries
• Executing undefined instruction
• Division by zero
Upon fault occurrence, the code line where the fault occurred is displayed in the debugger. The view displays the
reasons for the error condition. Faults are coarsely categorized into hard, bus, usage and memory faults.
• Hard and bus faults occur when an invalid access attempt is made across the bus, either of a peripheral
register or a memory location
• Usage faults are the result of illegal instructions or other program errors
• Memory faults include attempts of access to an illegal location or violations of rules maintained by the
memory protection unit (MPU)
To further assist fault analysis, an exception stack frame visualization option provides a snapshot of the MCU
register values at the time of the crash. Isolating the fault to an individual instruction allows to reconstruct the
MCU condition at the time the faulty instruction was executed.
In the Debugger perspective, the Fault Analyzer view is opened from the menu. Select the menu command
[Window]>[Show View]>[Fault Analyzer] or use the [Quick Access] field, search for “Fault Analyzer” and select
it from the views.
Figure 157. Open the Fault Analyzer view
UM2609 - Rev 1 page 146/186

UM2609
Using the Fault Analyzer view
6.2 Using the Fault Analyzer view

The Fault Analyzer view has five main sections, which can be expanded and collapsed. The sections contain
different kinds of information for better understanding the reason that caused a particular fault to occur. The
sections are:
• Hard Fault Details
• Bus Fault Details
• Usage Fault Details
• Memory Management Fault Details
• Register Content During Fault Exception
When a fault has occurred, it is possible to [Open editor on fault location] and [Open disassembly on fault
location] by pressing the buttons in the view.
Figure 158 shows an example of the Fault Analyzer view when an error is detected. In this example, the error is
caused by a project making a divide by zero with the debugger stopped in the HardFault_Handler().
Opening the Fault Analyzer view when this happens displays the reason of the error. In the example, it displays
[Usage Fault Detected] and [Attempt to perform a division by zero (DIVBYZERO)]. The Register Content
During Fault Exception presents register values when the problem occurred.
UM2609 - Rev 1 page 147/186

UM2609
Figure 158. Fault Analyzer view
UM2609 - Rev 1 page 148/186

UM2609
The Fault Analyzer view contains these toolbar buttons:
Figure 159. Fault Analyzer toolbar
• The first toolbar button (left) opens the Editor on the fault location return address by using the information in
the PC and LR registers in the stack and the symbol information in the debugged elf file.
• The second toolbar button (middle) opens the Disassembly view on the fault location return address by
using the information in PC and LR registers in the stack and the symbol information in the debugged elf
file.
• The third toolbar button (right) selects if the PC or LR register is used when opening the Editor or
Disassembly view on error location.
Figure 160 and Figure 161 show the Editor and Disassembly views opened using the toolbar buttons to find the
fault location in the example.
Figure 160. Fault analyzer open editor on fault
Figure 161. Fault Analyzer open disassembly on fault
Note: The Fault Analyzer can be used on all STM32 projects. It requires no special code and no special build
configuration. All data are collected for the Cortex®-M registers. The symbol information is read from the
debugged elf file.
UM2609 - Rev 1 page 149/186

UM2609
Build Analyzer
7 Build Analyzer
7.1 Introduction to the Build Analyzer
The STM32CubeIDE Build Analyzer feature interprets program information from the elf file in detail and presents
the information in a view. If a map file, with similar name, is found in the same folder as the elf file the
information from the map file is also used and even more information can be presented.
The Build Analyzer view is useful to optimize or simplify a program. The view contains two tabs, the Memory
Regions and Memory Details tabs:
• The Memory Regions tab is populated with data if the elf file contains a corresponding map file. When the
map file is available, this tab can be seen as a brief summary of the memory regions with information about
the region name, start address and size. The size information also comprises the total size, free and used
part of the region, and usage percentage.
• The Memory Details tab contains detailed program information based on the elf file. The different section
names are presented with address and size information. Each section can be expanded and collapsed.
When a section is expanded, functions/data in this section is listed. Each presented function/data contains
address and size information.
7.2 Using the Build Analyzer

The Build Analyzer view is by default open in the C/C++perspective. If the view is closed it can be opened from
the menu. Select the menu command [Window]>[Show View]>[Build Analyzer] or use the [Quick Access] field,
search for “Build Analyzer” and select it from the views.
When the Build Analyzer view is open, select an elf file in the Project Explorer view. The Build Analyzer view is
then updated with the information from this file. When an elf file is selected and a map file, with similar name, is
found in the same folder, additional information from the map file is also used by the view.
The Build Analyzer view is also updated if a project node in the Project Explorer view is selected. In this case the
Build Analyzer uses the elf file that corresponds to the current active build configuration of the project.
Figure 162. Build analyzer
7.2.1 Memory Regions tab

The Memory Regions tab in the Build Analyzer view displays information based on the corresponding map file. If
no information is displayed, it means that there is no corresponding map file found. When a map file is found, the
region names, start address, end address, total size of region, free size, used size and usage information are
presented.
These regions are usually defined in the linker script file (.ld) used when building the program. Update the linker
script file if a memory region location or size must be changed.
Note: The Memory Regions tab is empty if the elf file has no corresponding map file.
UM2609 - Rev 1 page 150/186

UM2609
Using the Build Analyzer
Figure 163. Memory Regions tab
The column information is described in the Table 7.
Table 7. Memory Regions tab information
Name Description
Region Name of memory region (if a corresponding map file is found).
Start address The start address of the region, defined in the linker script.
End address End address of the region.
Size The total size of memory region.
Free The free size in the memory region.
Used The used size in the memory region.
The percentage of used size relative to the total memory region size. See Table 8 for the bar icon color
Usage %
information.
The Usage (%) column contains a bar icon corresponding to the percentage value. The bar has different colors
depending on the percentage of used memory.
Table 8. Memory Regions usage color
Usage color Description
Green Less than 75% of memory used.

Yellow 75% to 90% of memory used.
Red More than 90% of memory used.
7.2.2 Memory Details tab

The Memory Details tab of the Build Analyzer view contains information for the elf file. Each section in the
Memory Details tab can be expanded so that individual functions and data can be seen. The tab presents
columns with name, run address, load address, and size information.
UM2609 - Rev 1 page 151/186

UM2609
Figure 164. Memory Details tab
The column information is described in Table 9.
Table 9. Memory Details tab information
Name Description
Name of memory region, section, function, and data. A green icon is used to mark functions while the
Name
blue icon is used for data variables.
Run Address (VMA) The Virtual Memory Address contains the address used when the program is running.
The Load Memory Address is the address used for load, for instance for the initialization values of
Load Address (LMA)
global variables.
Size Used size (total size for Memory Regions).
Note: The memory region name is only displayed if a corresponding map file is found.
7.2.2.1 Size information

The size information in the Memory Details tab is calculated from the symbol size in the elf file. If a
corresponding map file is investigated, it may contain a different size value. The size is usually correct for C files
but the value presented for assembler files depends on how the size information is written in the assembler files.
The constants used by the function must be defined within the section definition. At the end of the section, the
size directive is used by the linker to calculate the size of the function.
UM2609 - Rev 1 page 152/186

UM2609
Example: Reset_Handler in startup.s file
This example shows how to write the Reset_Handler in an assembler startup file to include the constants
_sidata, _sdata, _edata, _sbss, and _ebss in the Reset_Handler size information in the elf file. If these
constants are defined out of the Reset_Handler section definition, their sizes are not included in the calculated
size of the Reset_Handler. To include them in the size of the Reset_Handler, these definitions must be
placed inside the Reset_Handler section as presented in the code example below.
.section .text.Reset_Handler
.weak Reset_Handler
.type Reset_Handler, %function
Reset_Handler:
/* Copy the data segment initializers from flash to SRAM */

movs r1, #0
b LoopCopyDataInit
CopyDataInit:
ldr r3, =_sidata
/* initialization code data, bss, ... */

...
/* Call the application's entry point */

bl main
bx lr
/* start address for the initialization values defined in linker script */

.word _sidata
.word _sdata
.word _edata
.word _sbss
.word _ebss
.size Reset_Handler, .-Reset_Handler
UM2609 - Rev 1 page 153/186

UM2609
7.2.2.2 Sorting
The sort order of a Memory Details tab column can be changed by clicking on the column name.
Figure 165. Memory Details sorted by size
7.2.2.3 Search and filter

The information in the Memory Detailstab can be filtered by entering a string in the search field.
Figure 166 shows a search example for names including the string “sound”.
Figure 166. Memory Details search and filter
UM2609 - Rev 1 page 154/186

UM2609
7.2.2.4 Calculate the sum of sizes

The sum of the sizes of several lines in the Memory Details tab can be calculated by selecting these lines in the
view. The sum of the selection is presented above the Name column in the view.
Figure 167. Sum of sizes
7.2.2.5 Display the size information in byte format

The Build Analyzer view can display size information in different format according to the [Show Byte], [Show
Hex] or [Show Human] selection. The icon in the Build Analyzer toolbar is used to switch between these formats.
Prefer [Show Byte] or [Show Hex] when copying and pasting of data into an Excel® document for later
calculations.
Figure 168. Show byte count
UM2609 - Rev 1 page 155/186

UM2609
Figure 169. Show hex count
7.2.2.6 Copy and paste

The data in the Memory Details tab can be copied to other applications in CSV format by selecting the rows to
copy and typing Ctrl+C. The copied data can be pasted into another application with the Ctrl+V command.
Figure 170. Copy and paste
UM2609 - Rev 1 page 156/186

UM2609
The Ctrl+C copy of the lines selected in Figure 170 provides the Ctrl+V results below:
"sound4";"0x0807afc8";"0x0807afc8";"8500"
"sound3";"0x08079c40";"0x08079c40";"5000"
"sound2";"0x08074e20";"0x08074e20";"20000"
"sound1";"0x08070000";"0x08070000";"20000"
"image3";"0x08064c08";"0x08064c08";"35000"
"image2";"0x080561a8";"0x080561a8";"60000"
"image1";"0x08050000";"0x08050000";"25000"
"icons";"0x08040000";"0x08040000";"20000"
UM2609 - Rev 1 page 157/186

UM2609
Static Stack Analyzer
8 Static Stack Analyzer

8.1 Introduction to the Static Stack Analyzer
The STM32CubeIDE Static Stack Analyzer calculates the stack usage based on the built program. It analyzes the
.su files, generated by gcc, and the elf file in detail, and presents the resulting information in the view.
The view contains two tabs, the List and Call Graph tabs.
The List tab is populated with the stack usage for each function included in the program. The tab lists one line per
function, each line consisting of the Function, Local cost, Type, Location and Info columns.
Figure 171. Static Stack Analyzer List tab
UM2609 - Rev 1 page 158/186

UM2609
Using the Static Stack Analyzer
The Call Graph tab contains an expandable list with functions included in the program. Lines representing
functions calling other functions can be expanded to see the call hierarchy.
Figure 172. Static Stack Analyzer Call Graph tab
8.2 Using the Static Stack Analyzer

The Static Stack Analyzerview is by default open in the C/C++perspective. If the view is closed, it can be opened
from the menu. Select the menu command [Window]>[Show View]>[Static Stack Analyzer]. Another way to
open the Static Stack Analyzerview is to type “Static Stack Analyzer” in the [Quick Access search bar] and
select it from the views.
Figure 173. Open the Static Stack Analyzer view
UM2609 - Rev 1 page 159/186

UM2609
The Static Stack Analyzer view is populated when a built project is selected in the Project Explorer. The project
must be built with option [Generate per function stack usage information] enabled, otherwise the view cannot
present any stack information.
How to setup the compiler to generate stack usage information is explained in the next section.
8.2.1 Enable stack usage information

If the top of the view displays the message No stack usage information found, please enable in
the compiler settings, the build configuration must be updated for the compiler to generate stack
information:
1. Open the project properties, for instance with a right-click on the project in the Project Explorer view
2. Select Properties and, in the dialog, select [C/C++ Build]>[Settings]
3. Select the Tool Settings tab
4. Select [MCU GCC Compiler]>[Miscellanous]
5. Select [Enable stack usage information (-fstack-usage)] as shown in Figure 174
6. Save the setting and rebuild the program
Figure 174. Enable generate per function stack usage information
UM2609 - Rev 1 page 160/186

UM2609
8.2.2 List tab

The List tab contains a list of all functions included in the selected program with options to [Hide dead code]
functions and [Filter] visible functions.
Use the [Hide dead code] selection to enable or disable the listing of dead code functions.
If used, the [Filter] field restricts the display to functions matching the characters it contains.
Figure 175. Static Stack Analyzer List tab
The column information in the List tab is described in Table 10.
Table 10. Static Stack Analyzer List tab details
Name Description
Function Function name.

Local cost The number displays how many bytes of stack the function uses.
Tells if the function uses a STATIC or DYNAMIC stack allocation. When DYNAMIC allocation is used the actual
Type
stack size is run-time dependent and the the Local cost value is uncertain due to the dynamic size of stack.
Indicates where the function is declared. It is possible to double-click on a line and open the file with the defined
Location
function in the editor.
Info Additional information about the calculation.
The List tab sort order can be changed by clicking on a column name.
Note: By double-clicking on a line that displays the file location and line number in the List tab, the function is opened
in the Editor view.
UM2609 - Rev 1 page 161/186

UM2609
8.2.3 Call Graph tab

The Call Graph tab contains detailed program information in a tree view. Each function included in the program
but not called by any other function is presented at the top level. It is possible to expand the tree to see called
functions. Only functions available in the elf file can be visible in the tab.
When used, the [Search...] button triggers the display of the functions matching the characters in the search field.
The search can be made case sensitive or not depending on the selection in checkbox [Case sensitive].
Figure 176. Static Stack Analyzer Call Graph tab
The column information in the Call Graph tab is described in Table 11.
Table 11. Static Stack Analyzer Call Graph tab details
Name Description
Function Function name.

Specifies the call stack depth this function uses:
• 0: the function does not call any other functions
Depth
• Number ≥ 1: the function calls other functions
• ?: the function makes recursive calls or the depth cannot be calculated
Max cost Specifies how many bytes of stack the function uses including stack needed for called functions.
Specifies how many bytes of stack the function uses. This column does not take into account any stack that may
Local cost
be needed by the functions it may call.
Specifies if the function uses a STATIC or DYNAMIC stack allocation.
• STATIC: the function uses a fixed stack
Type
• DYNAMIC: the function uses a run-time dependent stack
• Empty field: no stack usage information available for the function
Indicates where the function is declared. It is possible to double-click on a line and open the file with the defined
Location
function in the editor.
Contains specific information about the stack usage calculation. For instance, it can hold a combination of the
following messages:
• Max cost uncertain: the reason can be that the function makes a call to some sub-function where
the stack information is not known, the function makes recursive calls, or others
Info • Recursive: the function makes recursive calls
• No stack usage information available for this function: no stack usage
information available for this function
• Local cost uncertain due to dynamic size, verify at run-time: the function
allocates stack dynamically, for instance depending on a parameter
UM2609 - Rev 1 page 162/186

UM2609
The Call Graph tab sort order can be changed by clicking on a column name.
By double-clicking on a line that displays the file location and line number in the tab, the function is opened in the
Editor view.
Note: The main function is usually called by the Reset_Handler and can in those cases be seen when expanding
the Reset_Handler node.
If unused functions are listed in the tab, check if linker option [dead code removal] is enabled to remove unused
code from the program. Read more on this in Section 2.5.2 Discard unused sections.
The small icon left of the function name in column Function column indicates the following:
• Green dot: the function uses STATIC stack allocation (fixed stack).
• Blue square: the function uses DYNAMIC stack allocation (run-time dependent).
• 010 icon: used if the stack information is not known. This can be the case for library functions or assembler
functions.
• Three arrows in a circle: used in the Call Graph tab when the function makes recursive calls.
Figure 177. Function symbols in Static Stack Analyzer
8.2.4 Using the filter and search field

The List and Call Graph tabs contain a filter/search field, which can be used to search a specific function or
functions matching the characters entered in the field.
UM2609 - Rev 1 page 163/186

UM2609
Figure 178 displays the List tab where the [Filter] field is used to seek functions containing the “read” string in
their name.
Figure 178. Static Stack Analyzer List tab using search
Figure 179 shows a use example of the [Search...] field in the Call Graph tab for filtering functions with name
matching the “read” string.
Figure 179. Static Stack Analyzer Call Graph using search
UM2609 - Rev 1 page 164/186

UM2609
8.2.5 Copy and paste

The data in the List tab can be copied to other applications in CSV format by selecting the rows to copy and
typing Ctrl+C. The copied data can be pasted into another application with the Ctrl+V command.
Figure 180. Copy and paste
The Ctrl+C copy of the lines selected in Figure 180 provides the Ctrl+V results below:
"SystemClock_Config";"88";"STATIC";"main.c:410";""
"main";"40";"STATIC";"main.c:183";""
"HAL_GPIO_Init";"40";"STATIC";"stm32f4xx_hal_gpio.c:171";""
UM2609 - Rev 1 page 165/186

UM2609
Installing updates and additional Eclipse® plugins
9 Installing updates and additional Eclipse® plugins

9.1 Check for updates
STM32CubeIDE checks for available updates regularly and opens the Available Updates dialog when a new
update is detected. It is also possible to check for updates manually. Use menu [Help]>[Check for Updates] to
check if new software is available.
When updates are found, select the update to install and press [Next].
Figure 181. STM32CubeIDE available updates
UM2609 - Rev 1 page 166/186

UM2609
Check for updates
Update details is displayed. Review and confirm the update. Press Next.
Figure 182. STM32CubeIDE update details
Review Licenses details are displayed. Review the licenses, select [I accept the terms of the license
agreements] and press [Finish] to install the update.
Figure 183. STM32CubeIDE update review licenses
UM2609 - Rev 1 page 167/186

UM2609
Install from the Eclipse® market place
The progress bar displayed at the bottom of the STM32CubeIDE window shows the installation completion rate.
Restart STM32CubeIDE when the update is finished.
9.2 Install from the Eclipse® market place

It is possible to install additional third-party Eclipse® plugins in STM32CubeIDE using the Eclipse Marketplace. To
install from Eclipse Marketplace, select menu [Help]>[Eclipse Marketplace…].
Figure 184. Eclipse Marketplace menu
UM2609 - Rev 1 page 168/186

UM2609
Install from the Eclipse® market place
The Eclipse Marketplace dialog opens. Search for the plugin or use the tabs (Recent, Popular, Favorites) to find
the software wanted and install it.
Figure 185. Eclipse marketplace
Wait until the installation is finished and restart STM32CubeIDE.
UM2609 - Rev 1 page 169/186

UM2609
Install using [Install new software...]
9.3 Install using [Install new software...]

Another way to install new software is to use menu [Help]>[Install New Software…].
Figure 186. Install new software menu
UM2609 - Rev 1 page 170/186

UM2609
Install using [Install new software...]
The Install dialog opens. Enter the plugin update site URL. If the URL is not known, use [--All Available Sites--].
Figure 187. Install new software
If no direct Internet connection is available, the plugin can be downloaded into an archive on a computer with an
Internet connection, and then manually transferred to the computer with an STM32CubeIDE installation. Add the
archived file by clicking on the [Add…] button and then select [Archive and select the downloaded file].
Figure 188. Install new software from computer
Select the appropriate plugins and install the software. Restart STM32CubeIDE when installation is finished.
Remember: Not all Eclipse® plugins are compatible with STM32CubeIDE.
UM2609 - Rev 1 page 171/186

UM2609
Uninstalling installed additional Eclipse® plugins
9.4 Uninstalling installed additional Eclipse® plugins

To uninstall a plugin that is no longer needed, select menu [Help]>[About STM32CubeIDE].
Figure 189. About STM32CubeIDE
Press the [Installation Details] button to open the STM32CubeIDE Installation Details dialog.
Figure 190. Installation details
Select the plugin to uninstall in the Installed Software tab and press [Uninstall…]. Restart STM32CubeIDE when
the uninstallation is finished.
UM2609 - Rev 1 page 172/186

UM2609
Update to new CDT
9.5 Update to new CDT

When a new version of STM32CubeIDE is installed based on a new version of Eclipse®, CDT or both, it is
recommended to create a new workspace instead of using a former workspace. The following warning is
displayed when trying to use an old workspace with a new STM32CubeIDE.
Figure 191. Older workspace version warning
UM2609 - Rev 1 page 173/186

UM2609
References
10 References
Table 12. STMicroelectronics reference documents
Reference Document short name Description Document source
[ST-01] DB3871 STM32CubeIDE data brief

[ST-02] RN0114 STM32CubeIDE release note
[ST-03] UM2553 STM32CubeIDE quick start guide
[ST-04] UM2563 STM32CubeIDE installation guide
Migration guide from TrueSTUDIO® to

[ST-05] UM2578
STM32CubeIDE
Migration guide from System Workbench to
[ST-06] UM2579
STM32CubeIDE
[ST-07] UM2576 STM32CubeIDE ST-LINK GDB server
www.st.com
Getting started with STM32MP1 in
[ST-08] AN5360
STM32CubeIDE
Getting started with STM32H7 multicore in
[ST-09] AN5361
STM32CubeIDE
Getting started with STM32L5 in
[ST-10] AN5394
STM32CubeIDE
License agreement applicable to
[ST-11] SLA0048
STM32CubeIDE
STM32CubeMX for STM32 configuration and
[ST-12] UM1718
initialization C code generation
Table 13. External reference documents
Reference Description Document source
[EXT-01] GNU Assembler

[EXT-02] GNU Compiler Collection
[EXT-03] GNU C Library
[EXT-04] GNU C Preprocessor
[EXT-05] GNU Linker
[EXT-06] GNU Binary Utilities GNU tool suite(1)
[EXT-07] Red Hat Newlib C Library
[EXT-08] Red Hat Newlib C Math Library
[EXT-09] Newlib nano readme
[EXT-10] Debugging with GDB
[EXT-11] GDB Quick Reference Card
[EXT-12] GNU Tools for STM32 Patch list Information Center
1. For GNU documentation principles, refer to www.gnu.org.
UM2609 - Rev 1 page 174/186

UM2609
Revision history
Table 14. Document revision history
Date Version Changes
24-Jul-2020 1 Initial release.
UM2609 - Rev 1 page 175/186

UM2609
Contents
Contents
1 Getting started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2
1.1 Product information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1.1 System requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1.2 Downloading the latest STM32CubeIDE version. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1.3 Installing STM32CubeIDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
1.1.4 License . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.1.5 Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.2 Using STM32CubeIDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

1.2.1 Basic concept and terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
1.2.2 Starting STM32CubeIDE. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
1.2.3 Help system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
1.3 Information Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

1.3.1 Accessing the Information Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.3.2 Home page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.3.3 Technical documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
1.3.4 Closing the Information Center . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
1.4 Perspectives, editors and views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

1.4.1 Perspectives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
1.4.2 Editors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
1.4.3 Views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
1.4.4 Quick Access edit field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
1.5 Configuration - Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

1.5.1 Preferences - Editors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
1.5.2 Preferences - Code style formatter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
1.5.3 Preferences - Network proxy settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
1.6 Workspaces and projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

1.7 Managing existing workspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
1.7.1 Backup of preferences for a workspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
1.7.2 Copy preferences between workspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
1.7.3 Keeping track of Java heap space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
UM2609 - Rev 1 page 176/186

UM2609
Contents
1.7.4 Unavailable workspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
1.8 STM32CubeIDE and Eclipse® basics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

1.8.1 Keyboard shortcuts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
1.8.2 Editor zoom in and zoom out. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
1.8.3 Quickly find and open a file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
1.8.4 Branch folding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
1.8.5 Block selection mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
1.8.6 Compare files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
1.8.7 Local file history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
2 Creating and building C/C++ projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .36

2.1 Introduction to projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
2.2 Creating a new STM32 project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
2.2.1 Creating a new STM32 executable project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
2.2.2 Creating a new STM32 static library project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
2.3 Configure the project build setting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

2.3.1 Project build configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
2.3.2 Project C/C++ build settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
2.4 Building the project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

2.4.1 Building all projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
2.4.2 Build all build configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
2.4.3 Headless build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
2.4.4 Temporary assembly file and preprocessed C code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
2.4.5 Build logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
2.4.6 Parallel build and build behaviour . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
2.5 Linking the project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

2.5.1 Run-time library. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
2.5.2 Discard unused sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
2.5.3 Page size allocation for malloc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
2.5.4 Include additional object files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
2.5.5 Treat linker warnings and errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
2.5.6 Linker script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
2.5.7 Modify the linker script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
UM2609 - Rev 1 page 177/186

UM2609
Contents
2.5.8 Include libraries. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
2.5.9 Referring to projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
2.6 I/O redirection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80

2.6.1 printf() redirection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
2.7 Position-independent code. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82

2.7.1 Adding the –fPIE option . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
2.7.2 Run-time library. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
2.7.3 Stack pointer configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
2.7.4 Interrupt vector table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
2.7.5 Global offset table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
2.7.6 Interrupt vector table and symbols . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
2.7.7 Debugging position-independent code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
2.8 Exporting projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86

2.9 Importing existing projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
2.9.1 Importing an STM32CubeIDE project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
2.9.2 Importing System Workbench and TrueSTUDIO® projects . . . . . . . . . . . . . . . . . . . . . . . . 91
2.9.3 Importing using project files association . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
2.9.4 Prevent “GCC not found in path” error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
3 Debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95
3.1 Introduction to debugging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
3.2 Debug configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
3.2.1 Debug configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
3.2.2 Main tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
3.2.3 Debugger tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
3.2.4 Startup tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
3.3 Manage debug configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

3.4 Debug using different GDB servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
3.4.1 Debug using the ST-LINK GDB server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
3.4.2 Debug using OpenOCD and ST-LINK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
3.4.3 Debug using SEGGER J-Link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
3.5 Start and stop debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

3.5.1 Start debugging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
UM2609 - Rev 1 page 178/186

UM2609
Contents
3.5.2 Debug perspective and views . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
3.5.3 Main controls for debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
3.5.4 Run, start and stop a program. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
3.5.5 Set breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
3.5.6 Attach to running target. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
3.5.7 Restart or terminate debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
3.6 Debug features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

3.6.1 Live Expressions view. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
3.6.2 Shared ST-LINK . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
3.6.3 Debug multiple boards . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
3.6.4 STM32H7 multicore debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
3.6.5 STM32MP1 debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
3.6.6 STM32L5 debugging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
3.7 Run configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
4 Debug with Serial Wire Viewer tracing (SWV) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122

4.1 Introduction to SWV and ITM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
4.2 SWV debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
4.2.1 SWV debug configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
4.2.2 SWV settings configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
4.2.3 SWV tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
4.3 SWV views. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

4.3.1 SWV Trace Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
4.3.2 SWV Exception Trace Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
4.3.3 SWV Exception Timeline Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
4.3.4 SWV Data Trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
4.3.5 SWV Data Trace Timeline Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
4.3.6 SWV ITM Data Console and printf redirection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
4.3.7 SWV Statistical Profiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
4.4 Change the SWV trace buffer size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

4.5 Common SWV problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
5 Special Function Registers (SFRs) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

5.1 Introduction to SFRs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
UM2609 - Rev 1 page 179/186

UM2609
Contents
5.2 Using the SFRs view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143

5.3 Updating CMSIS-SVD settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
6 Fault Analyzer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146

6.1 Introduction to the Fault Analyzer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
6.2 Using the Fault Analyzer view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
7 Build Analyzer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

7.1 Introduction to the Build Analyzer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
7.2 Using the Build Analyzer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
7.2.1 Memory Regions tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
7.2.2 Memory Details tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
8 Static Stack Analyzer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

8.1 Introduction to the Static Stack Analyzer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
8.2 Using the Static Stack Analyzer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
8.2.1 Enable stack usage information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
8.2.2 List tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
8.2.3 Call Graph tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
8.2.4 Using the filter and search field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
8.2.5 Copy and paste. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
9 Installing updates and additional Eclipse® plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

9.1 Check for updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
9.2 Install from the Eclipse® market place . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

9.3 Install using [Install new software...]. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
9.4 Uninstalling installed additional Eclipse® plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172

9.5 Update to new CDT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
10 References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
Contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 176
List of tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
List of figures. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
UM2609 - Rev 1 page 180/186

UM2609
List of tables
List of tables
Table 1. Key shortcut examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Table 2. SWV Trace Log columns details. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Table 3. SWV Exception Trace Log – Data columns details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Table 4. SWV Exception Trace Log – Statistics columns details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Table 5. SWV Data Trace columns details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Table 6. SWV Statistical Profiling columns details. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Table 7. Memory Regions tab information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Table 8. Memory Regions usage color . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Table 9. Memory Details tab information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Table 10. Static Stack Analyzer List tab details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Table 11. Static Stack Analyzer Call Graph tab details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Table 12. STMicroelectronics reference documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Table 13. External reference documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Table 14. Document revision history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175
UM2609 - Rev 1 page 181/186

UM2609
List of figures
List of figures
Figure 1. STM32CubeIDE key features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
Figure 2. STM32CubeIDE window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
Figure 3. STM32CubeIDE Launcher – Workspace selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Figure 4. Help menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6
Figure 5. Help - Information Center menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Figure 6. Information Center – Home page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Figure 7. Information Center – Technical documentation page . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Figure 8. Reset perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Figure 9. Toolbar buttons for switching perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Figure 10. C/C++ perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Figure 11. Debug perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Figure 12. Device Configuration Tool perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Figure 13. Remote System Explorer perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Figure 14. New connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
Figure 15. [Show View] menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Figure 16. Show View dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Figure 17. Quick access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Figure 18. Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Figure 19. Preferences - Text Editors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Figure 20. Preferences - Formatter. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Figure 21. Preferences - Code style edit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Figure 22. Preferences - Network Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Figure 23. Preferences - Workspaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Figure 24. Display of Java heap space status . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Figure 25. Workspace unavailable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Figure 26. Shortcut keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Figure 27. Shortcut preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
Figure 28. Editor with text zoomed in . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Figure 29. Editor folding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
Figure 30. Editor block selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Figure 31. Editor text block addition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Figure 32. Editor column block selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Figure 33. Editor column block paste . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
Figure 34. Editor - Compare files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Figure 35. Editor - File differences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Figure 36. Local history. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Figure 37. Show local history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
Figure 38. File history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
Figure 39. Compare current history with local history . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Figure 40. Compare local file differences. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
Figure 41. STM32 target selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Figure 42. STM32 board selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Figure 43. Project setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Figure 44. Firmware library package setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Figure 45. Initialization of all peripherals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Figure 46. STM32CubeMX perspective opening. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Figure 47. Project creation started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
Figure 48. STM32CubeMX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Figure 49. STM32 static library project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Figure 50. STM32 library and board project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Figure 51. Set the active build configuration using the toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
Figure 52. Set active build configuration using right-click . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45
UM2609 - Rev 1 page 182/186

UM2609
List of figures
Figure 53. Set active build configuration using menu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Figure 54. Manage Configurations dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
Figure 55. Create a new build configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Figure 56. Updated Manage Configurations dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Figure 57. Configuration deletion dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Figure 58. Configuration renaming dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Figure 59. Properties tabs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Figure 60. Properties configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
Figure 61. Properties toolchain version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Figure 62. Properties toolchain selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Figure 63. Properties tool MCU settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Figure 64. Properties tool MCU post-build settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Figure 65. Properties tool GCC assembler settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Figure 66. Properties tool GCC compiler settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
Figure 67. Properties tool GCC linker settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
Figure 68. Properties build steps settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Figure 69. Project build toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Figure 70. Project build console . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Figure 71. Project build all . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Figure 72. Project build-all configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Figure 73. Headless build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Figure 74. Parallel build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Figure 75. Linker documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Figure 76. Linker run-time library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
Figure 77. Linker newlib-nano library and floating-point numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
Figure 78. Linker discard unused sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
Figure 79. Linker include additional object files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Figure 80. Linker fatal warnings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Figure 81. Linker memory output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Figure 82. Linker memory output specified order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Figure 83. Linker memory displaying file readme . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Figure 84. Include a library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Figure 85. Add library header files to the include paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Figure 86. Set project references . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Figure 87. Position independent code, –fPIE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Figure 88. Debugging position independent code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Figure 89. Export project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Figure 90. Export dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Figure 91. Export archive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Figure 92. Import project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Figure 93. Import dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Figure 94. Import projects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
Figure 95. Import System Workbench projects (1 of 3) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Figure 98. Import using project files association . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Figure 99. Debug as STM32 MCU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Figure 100. Debug as STM32 MCU menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
Figure 101. Debug configuration main tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Figure 102. Debug configuration debugger tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Figure 103. Debug configuration startup tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Figure 104. Add/Edit item . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
Figure 105. Manage debug configurations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Figure 106. Manage debug configurations toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
UM2609 - Rev 1 page 183/186

UM2609
List of figures
Figure 107. ST-LINK GDB server debugger tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Figure 108. OpenOCD debugger tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Figure 109. Segger debugger tab. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 106
Figure 110. Debug configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
Figure 111. Confirm perspective switch. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Figure 112. Debug perspective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Figure 113. [Run] menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111
Figure 114. Debug toolbar. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111
Figure 115. Debug breakpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .112
Figure 116. Breakpoint properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113
Figure 117. Conditional breakpoint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113
Figure 118. Startup tab attach . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .115
Figure 119. Reset the chip toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116
Figure 120. Restart configurations selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116
Figure 121. Restart configurations dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117
Figure 122. Restart configurations dialog with additional command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .118
Figure 123. Select restart configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .118
Figure 124. Live Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119
Figure 125. Live expressions number format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119
Figure 126. Run configurations startup tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
Figure 127. SWV core clock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Figure 128. SWV configuration for ST-LINK GDB server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Figure 129. SWV configuration for SEGGER J-Link . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
Figure 130. SWV show view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Figure 131. SWV Trace log view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Figure 132. SWV [Configure Trace] toolbar button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Figure 133. SWV settings dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
Figure 134. SWV [Start/Stop Trace] toolbar button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Figure 135. SWV Trace Log PC sampling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Figure 136. [Remove all collected SWV data] toolbar button . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Figure 137. SWV views selectable from the menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Figure 138. SVW views common toolbar. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
Figure 139. SVW graph views extra toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Figure 140. SWV Trace Log PC sampling and exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
Figure 141. SWV Exception Trace Log – Data tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
Figure 142. SWV Exception Trace Log – Statistics tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
Figure 143. SWV Exception Timeline Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Figure 144. SWV Data Trace configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
Figure 145. SWV Data Trace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Figure 146. SWV Data Trace Timeline Graph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Figure 147. SWV settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Figure 148. SWV ITM Data Console. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Figure 149. SWV ITM port configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
Figure 150. SWV PC sampling enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
Figure 151. SWV Statistical Profiling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
Figure 152. SWV Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
Figure 153. Open the SFRs view using the [Quick Access] field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
Figure 154. SFRs view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
Figure 155. SFRs view toolbar buttons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Figure 156. SFRs CMSIS-SVD Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
Figure 157. Open the Fault Analyzer view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
Figure 158. Fault Analyzer view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Figure 159. Fault Analyzer toolbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
Figure 160. Fault analyzer open editor on fault . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
UM2609 - Rev 1 page 184/186

UM2609
List of figures
Figure 161. Fault Analyzer open disassembly on fault. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

Figure 162. Build analyzer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150
Figure 163. Memory Regions tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
Figure 164. Memory Details tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Figure 165. Memory Details sorted by size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Figure 166. Memory Details search and filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
Figure 167. Sum of sizes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Figure 168. Show byte count . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
Figure 169. Show hex count . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Figure 170. Copy and paste . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Figure 171. Static Stack Analyzer List tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Figure 172. Static Stack Analyzer Call Graph tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Figure 173. Open the Static Stack Analyzer view . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Figure 174. Enable generate per function stack usage information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
Figure 175. Static Stack Analyzer List tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
Figure 176. Static Stack Analyzer Call Graph tab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
Figure 177. Function symbols in Static Stack Analyzer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
Figure 178. Static Stack Analyzer List tab using search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Figure 179. Static Stack Analyzer Call Graph using search . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164
Figure 180. Copy and paste . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
Figure 181. STM32CubeIDE available updates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
Figure 182. STM32CubeIDE update details. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Figure 183. STM32CubeIDE update review licenses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167
Figure 184. Eclipse Marketplace menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
Figure 185. Eclipse marketplace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
Figure 186. Install new software menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Figure 187. Install new software. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Figure 188. Install new software from computer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
Figure 189. About STM32CubeIDE . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Figure 190. Installation details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 172
Figure 191. Older workspace version warning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
UM2609 - Rev 1 page 185/186

UM2609
IMPORTANT NOTICE – PLEASE READ CAREFULLY

STMicroelectronics NV and its subsidiaries (“ST”) reserve the right to make changes, corrections, enhancements, modifications, and improvements to ST
products and/or to this document at any time without notice. Purchasers should obtain the latest relevant information on ST products before placing orders. ST
products are sold pursuant to ST’s terms and conditions of sale in place at the time of order acknowledgement.
Purchasers are solely responsible for the choice, selection, and use of ST products and ST assumes no liability for application assistance or the design of
Purchasers’ products.
No license, express or implied, to any intellectual property right is granted by ST herein.
Resale of ST products with provisions different from the information set forth herein shall void any warranty granted by ST for such product.
ST and the ST logo are trademarks of ST. For additional information about ST trademarks, please refer to www.st.com/trademarks. All other product or service
names are the property of their respective owners.
Information in this document supersedes and replaces information previously supplied in any prior versions of this document.
© 2020 STMicroelectronics – All rights reserved
UM2609 - Rev 1 page 186/186

En DM00629856

Uploaded by

Document Informationclick to expand document information

Document Informationclick to expand document information

Copyright:

Available Formats

En DM00629856

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

En DM00629856

Uploaded by

Copyright:

Available Formats

UM2609

Description of the integrated development environment for STM32 products

UM2609 - Rev 1 - July 2020 www.st.com

1.1 Product information

UM2609 - Rev 1 page 2/186

Figure 1. STM32CubeIDE key features

Device support Project Debugging

STMicroelectronics STM32 products

System Workbench for STM32

Import Atollic® TrueSTUDIO®

SEGGER J-Link GDB server

Multi-core and multi-board

OpenOCD GDB server

ST-LINK GDB server

GNU toolchain GDB debugger

Eclipse® plugins Modified plugins Eclipse C/C++ Development Tools™ (CDT™)

Eclipse® core platform

Supporting Windows®, Linux®, and macOS®

Legend: Specific STM32CubeIDE functions Open-based updated by ST Base technology platform

STM32CubeIDE main function groups Third-party solutions Operating systems

1.1.1 System requirements

1.1.2 Downloading the latest STM32CubeIDE version

1.1.3 Installing STM32CubeIDE

UM2609 - Rev 1 page 3/186

1.2 Using STM32CubeIDE

1.2.1 Basic concept and terminology

Perspectives, menu bar, toolbar

Views and editors

UM2609 - Rev 1 page 4/186

Figure 2. STM32CubeIDE window

Project Explorer Console view Build Analyzer

1.2.2 Starting STM32CubeIDE

UM2609 - Rev 1 page 5/186

Figure 3. STM32CubeIDE Launcher – Workspace selection

1.2.3 Help system

Figure 4. Help menu

1.3 Information Center

UM2609 - Rev 1 page 6/186

1.3.1 Accessing the Information Center

Figure 5. Help - Information Center menu

1.3.2 Home page

Figure 6. Information Center – Home page

1.3.3 Technical documentation

UM2609 - Rev 1 page 7/186

Figure 7. Information Center – Technical documentation page

1.3.4 Closing the Information Center

1.4 Perspectives, editors and views

UM2609 - Rev 1 page 8/186

Figure 8. Reset perspective

Figure 9. Toolbar buttons for switching perspective

Another way to switch perspective is to use the menu command [Window]>[Perspective]>[Open

1.4.1.1 C/C++ perspective

UM2609 - Rev 1 page 9/186

Figure 10. C/C++ perspective

1.4.1.2 Debug perspective

Figure 11. Debug perspective

UM2609 - Rev 1 page 10/186