User Guide Atollic True STUDIO For STM32

User Manual:

Open the PDF directly: View PDF PDF.
Page Count: 421 [warning: Documents this large are best viewed by clicking the View PDF Link!]

Atollic TrueSTUDIO® for ARM®
Quick Start Guide
User Guide
Document Data
ii | P a g e
COPYRIGHT
© Copyright 2009-2018 STMicroelectronics. All rights reserved. No part of this document may be
reproduced or distributed without prior written consent of STMicroelectronics. The software
product described in this document is furnished under a license and may only be used, or copied,
according to the license terms.
TRADEMARKS
Atollic, Atollic TrueSTUDIO, Atollic TrueSTORE and the Atollic logotype are trademarks, or registered
trademarks, owned by STMicroelectronics. ARM, ARM7, ARM9 and Cortex are trademarks, or
registered trademarks, of ARM Limited. ECLIPSE is a registered trademark of the Eclipse foundation.
Microsoft, Windows, Word, Excel and PowerPoint are registered trademarks of Microsoft
Corporation. Adobe and Acrobat are registered trademarks of Adobe Systems Incorporated. All other
product names are trademarks, or registered trademarks, of their respective owners.
DISCLAIMER
The information in this document is subject to change without notice and does not represent a
commitment of STMicroelectronics. The information contained in this document is assumed to be
accurate, but STMicroelectronics assumes no responsibility for any errors or omissions. In no event
shall STMicroelectronics, its employees, its contractors, or the authors of this document be liable for
any type of damage, losses, costs, charges, claims, demands, claim for lost profits, fees, or expenses
of any nature or kind.
DOCUMENT IDENTIFICATION
TS-UG November 2012
REVISION HISTORY
20th January 2018 – Applies to Atollic TrueSTUDIO® for STM32 v9.0.0
21th August 2018 – Applies to Atollic TrueSTUDIO® for STM32 v9.1.0
STMicroelectronics Software AB
Science Park
Gjuterigatan 7
SE- 553 18 Jönköping
Sweden
Email: sales@atollic.com
Web: www.atollic.com
STMicroelectronics
Web: www.st.com
Table of Contents
iii | P a g e
Contents
About this Document ............................................................. 29
Intended Readers ..................................................................................... 29
Document Conventions ........................................................................... 30
Getting Started .................................................... 31
Introduction .............................................................................................. 32
Preparing for Start .................................................................................... 33
Workspaces & Projects ................................................................................... 33
Perspectives & Views ...................................................................................... 34
Views ................................................................................................ 36
Starting the Program ................................................................................ 39
Starting With Different Language ................................................................... 41
Change What is Started ................................................................................... 42
Creating a New Project ............................................................................. 43
One-Click Example Project Installation ........................................................... 54
Using an Existing Project ................................................................................. 55
Prevent “GCC not found in PATH” Error ......................................................... 56
Creating a Static Library .................................................................................. 56
Hide Information in a Static Library ................................................................ 57
Creating a Makefile Project From Existing Code ............................................. 58
Importing EWARM Projects ...................................................................... 61
Using the Project Import Converter ................................................................ 61
Import Projects from Folder or Archive .......................................................... 61
Before Building Imported Project ................................................................... 67
Step-by-step checklist ..................................................................................... 68
Common Build Errors ...................................................................................... 72
Configuring the Debugger ............................................................................... 72
Importing AC6 Projects ............................................................................. 75
Table of Contents
iv | P a g e
Using the Project Import Converter ................................................................ 75
Import Projects from Folder or Archive .......................................................... 76
Import Projects using Double-Click ................................................................. 80
Using Imported Projects .................................................................................. 81
Restoring Converted Projects ......................................................................... 82
Configuring the Project’s Build Settings ................................................... 84
Build Configurations ........................................................................................ 88
Create a New Build Configuration for Release ................................ 89
Changing Active Build Configuration ............................................... 90
Source Folders ................................................................................................. 90
Include Libraries .............................................................................................. 93
Compiler settings ............................................................................................ 95
Set the Compiler to Use The C99-Standard ..................................... 96
Compiler Optimization ..................................................................... 97
Link Time Optimization (LTO) .......................................................................... 98
Changing Toolchain Version .......................................................................... 100
Create a New Build Configuration For an Old Toolchain Version .. 101
Convert .elf-File to Another Output Format ................................................. 103
Temporary Assembly File .............................................................................. 105
Building the Project ................................................................................ 106
Enable Parallel Build ...................................................................................... 107
Enable Build on Save ..................................................................................... 107
Rebuild Project .............................................................................................. 108
Build All Projects ........................................................................................... 109
Build All Build Configurations ........................................................................ 109
Headless Build ............................................................................................... 110
Logging .......................................................................................................... 112
The Build Size ................................................................................................ 112
Command Line Patterns ................................................................................ 115
Create .list-Files .............................................................................. 115
Table of Contents
v | P a g e
Building One File ........................................................................................... 116
Linking the Project .................................................................................. 119
Referring Project ........................................................................................... 119
Dead Code Removal ...................................................................................... 121
Adding Code to be Executed Before Main() .................................................. 122
Page Size Allocation for Malloc ..................................................................... 123
Include Additional Object Files ..................................................................... 124
Treat Linker Warnings as Errors .................................................................... 126
Linker Script ................................................................................................... 127
Generate a New Linker Script ....................................................................... 131
Automatically ................................................................................. 131
Manually ........................................................................................ 132
Modify Existing Linker Script ......................................................................... 133
Place Code in a New Memory Region ............................................ 133
Place Code in External Ram ........................................................... 135
Place Variables at Specific Addresses ............................................ 136
Linking in a Block of Binary Data .................................................... 137
Locate Uninitialized Data in Memory ............................................ 138
Managing Existing Workspaces .............................................................. 140
Backup of Preferences for a Workspace ....................................................... 140
Copy Preferences Between Workspaces ...................................................... 140
Keeping Track on Java Heap Space ............................................................... 141
Unlocking Locked Workspaces ...................................................................... 141
Managing Existing Projects ..................................................................... 143
Edit ................................................................................................................ 143
Editor Zoom In / Zoom Out ............................................................ 143
Quickly Find and Open a File.......................................................... 144
Branch Folding ............................................................................... 144
Block selection mode ..................................................................... 145
Table of Contents
vi | P a g e
Find all Keyboard Shortcuts ........................................................... 147
The Index ....................................................................................................... 148
Finding Include Paths, Macros etc. ............................................................... 151
Add or Remove Folder to Include Path ......................................................... 153
Locate Where a File is Included .................................................................... 153
Creating Links to External Files ..................................................................... 154
Update CMSIS Math library ........................................................................... 155
Converting a C-Project to a C++-Project ....................................................... 156
Disassemble/List Object and Elf Files ..................................................... 158
I/O Redirection ....................................................................................... 160
Position Independent Code .................................................................... 163
Using CMSIS-Pack in TrueSTUDIO .......................................................... 166
Configuration ................................................................................................ 166
CMSIS Pack Manager Perspective ................................................................. 167
Open Installed CMSIS Packs View ................................................................. 173
Install CMSIS Packages .................................................................................. 174
Create CMSIS-Pack Based Projects ......................................................... 177
Create CMSIS C/C++ Project .......................................................................... 177
Configure the CMSIS C/C++ Project .............................................................. 180
Updating Linker Script for CMSIS C/C++ Project ........................................... 184
Disable CMSIS Startup File ............................................................................ 185
Debugging the CMSIS C/C++ Project ............................................................. 185
Adding more CMSIS-Pack Features Into Project ........................................... 187
Installing 3rd Party Plugins ...................................................................... 188
Install From Eclipse Marketplace .................................................................. 188
Install Using “Install New Software” ............................................................. 189
Uninstalling 3rd Party Plugins ........................................................................ 192
Solving Upgrade Problem .............................................................................. 193
Using ST-Link Utility Inside Atollic TrueSTUDIO ..................................... 194
Requirements ................................................................................................ 194
Table of Contents
vii | P a g e
Steps That Needs to be Performed ............................................................... 195
Setup ST-Link Utility as an External Tool ....................................................... 195
Convert the Build Output to Intel Hex .......................................................... 196
Modify the Debug Configuration .................................................................. 197
Create a Launch Group.................................................................................. 198
Finished ......................................................................................................... 200
Miscellaneous Tools ............................................................................... 201
Quick Access Search Bar ................................................................................ 201
Version control .............................................................................................. 202
Subversion - SVN ............................................................................ 202
Locks in SVN ................................................................................... 204
Include SVN Revision-Number in a String ...................................... 205
Ignore a File .................................................................................... 206
Local SVN Repository ..................................................................... 206
Using SVN on External Resources .................................................. 209
Multi Monitor Support .................................................................................. 210
Open Additional Instance of TrueSTUDIO ..................................................... 211
Shell Access ................................................................................................... 212
Debugging ..........................................................215
Introduction to Debugging with TrueSTUDIO ........................................ 216
Starting the Debugger ............................................................................ 218
External GDB Server ...................................................................................... 224
JTAG Scan Chain ............................................................................................ 225
The Startup Script ................................................................................... 227
Start Debugging at the Very Beginning .......................................... 227
Load the Program Without Debugging .......................................... 227
Hardware Initialization Code ......................................................... 227
Managing the Debug Configurations ..................................................... 228
Generic Binary Path ....................................................................................... 229
Table of Contents
viii | P a g e
Debug Launch Configuration Settings File .................................................... 230
Customize the Debug Perspective .......................................................... 232
Debugging ............................................................................................... 233
Terminate, Rebuild and Re-launch ................................................................ 234
Disassembly View .......................................................................................... 234
Breakpoints ................................................................................................... 235
Conditional Breakpoint .................................................................. 236
Expressions .................................................................................................... 237
Live Expressions ............................................................................................ 238
Local Variables .............................................................................................. 239
Fill Memory with a Byte Pattern ................................................................... 241
SFRs ............................................................................................................... 241
Fault Analyzer ................................................................................................ 245
Fault Analyzer View........................................................................ 246
Terminal View ............................................................................................... 247
Segger Real Time Terminal ............................................................ 249
Attach to Running Target Using SEGGER Probe ..................................... 251
Stopping the Debugger ........................................................................... 254
Upgrading the GDB Server ..................................................................... 256
Configure Segger’s GDB Server .............................................................. 257
Change Flash Caching .................................................................................... 258
Enable Log File ............................................................................................... 258
Settings Command Line Option .................................................................... 259
Debugging Code in RAM ......................................................................... 260
Debugging Two Targets at the Same Time ............................................. 261
First Alternative - Local GDB-server Using GUI Options................................ 261
Second Alternative - Remote GDB-server Using Command-line
Options ......................................................................................................... 262
Build Analyzer ....................................................263
Introduction to Build Analyzer ............................................................... 264
Table of Contents
ix | P a g e
Using Build Analyzer ............................................................................... 265
Memory Regions ........................................................................................... 265
Memory Details ............................................................................................. 266
Size Information ............................................................................. 267
Sorting ............................................................................................ 269
Search and Filter ............................................................................ 270
Calculate Sum of Size ..................................................................... 271
Display Size Information in Byte Format ....................................... 271
Copy and Paste ............................................................................... 273
Static Stack Analyzer...........................................274
Introduction to Static Stack Analyzer ..................................................... 275
Using Static Stack Analyzer ..................................................................... 276
Enable Stack Usage Information ................................................................... 276
Basic Column Information ............................................................................. 277
Function column ............................................................................ 277
Depth Column ................................................................................ 278
Max Cost Column ........................................................................... 278
Local Cost Column .......................................................................... 278
Type Column .................................................................................. 278
Info Column .................................................................................... 278
List Tab .......................................................................................................... 279
Call Graph Tab ............................................................................................... 280
Using Search Field ......................................................................................... 281
Copy and Paste .............................................................................................. 282
Serial Wire Viewer Tracing ..................................284
Using Serial Wire Viewer Tracing ........................................................... 285
Serial Wire Debug (SWD) .............................................................................. 285
Serial Wire Output (SWO) ............................................................................. 285
Serial Wire Viewer (SWV) .............................................................................. 285
Table of Contents
x | P a g e
Instrumentation Trace Macrocell (ITM) ........................................................ 286
Starting SWV Tracing .............................................................................. 287
The SWV Views ....................................................................................... 294
The Timeline Graphs ..................................................................................... 296
Statistical Profiling ......................................................................................... 296
Exception Tracing .......................................................................................... 298
Exception Data ............................................................................... 298
Exception Statistics ........................................................................ 299
Printf() Redirection over ITM ................................................................. 302
Change the Trace Buffer Size ................................................................. 303
Common SWV Problems ........................................................................ 304
MTB Tracing (Cortex-M0+) ..................................305
Introduction to MTB ............................................................................... 306
Configure MTB ........................................................................................ 307
Using MTB ............................................................................................... 309
Analyzing MTB Information .................................................................... 310
Copy the MTB Log ......................................................................................... 312
Instruction Tracing ..............................................313
Instruction Tracing .................................................................................. 314
Cortex-M7 and ETMv4 .................................................................................. 314
Enable Trace .................................................................................................. 315
Writing a Trace Port Configuration File ......................................... 316
Configuring the Tracing Session .................................................................... 318
ETM Trace Port Configuration File Reference ............................................... 319
Add Trace Trigger .......................................................................................... 319
Add Trace Trigger in the Editor ...................................................... 321
Managing Trace Triggers ............................................................................... 321
Start Trace Recording .................................................................................... 322
Analyzing the Trace ....................................................................................... 322
Table of Contents
xi | P a g e
Display Options .............................................................................. 324
Search the Trace Log ..................................................................... 324
Exporting a Trace Log .................................................................................... 325
RTOS-Aware Debugging ......................................326
RTOS Kernel Awareness Debugging ....................................................... 327
Segger embOS ........................................................................................ 328
Requirements ................................................................................................ 328
Finding the Views .......................................................................................... 328
System Information ....................................................................................... 329
Task List ......................................................................................................... 330
Timers ............................................................................................................ 331
Resource Semaphores ................................................................................... 332
Mailboxes ...................................................................................................... 333
HCC Embedded eTaskSync ..................................................................... 335
Requirements ................................................................................................ 335
Finding the View ............................................................................................ 335
Task List ......................................................................................................... 336
FreeRTOS and OpenRTOS ....................................................................... 337
Requirements ................................................................................................ 337
Finding the Views .......................................................................................... 337
Task List ......................................................................................................... 338
Queues .......................................................................................................... 340
Semaphores .................................................................................................. 341
Timers ............................................................................................................ 342
Quadros RTXC ......................................................................................... 344
Requirements ................................................................................................ 344
Finding the Views .......................................................................................... 344
Kernel Information ........................................................................................ 345
Tasks (Task List and Stack Info) ..................................................................... 345
Task List tab .................................................................................... 346
Table of Contents
xii | P a g e
Stack Info tab ................................................................................. 347
Alarms ........................................................................................................... 348
Counters ........................................................................................................ 349
Event Sources ................................................................................................ 349
Exception Backtrace ...................................................................................... 350
Exceptions ..................................................................................................... 351
Mailboxes ...................................................................................................... 352
Mutexes......................................................................................................... 353
Partitions ....................................................................................................... 354
Pipes .............................................................................................................. 355
Queues .......................................................................................................... 356
Semaphores .................................................................................................. 357
Express Logic ThreadX ............................................................................ 359
Requirements ................................................................................................ 359
Finding the Views .......................................................................................... 359
Thread List ..................................................................................................... 360
Semaphores .................................................................................................. 361
Mutexes......................................................................................................... 362
Message Queues ........................................................................................... 363
Event Flags .................................................................................................... 364
Timers ............................................................................................................ 365
Memory Block Pools...................................................................................... 365
Memory Byte Pools ....................................................................................... 366
TOPPERS/ASP .......................................................................................... 368
Requirements ................................................................................................ 368
Finding the Views .......................................................................................... 368
Tasks .............................................................................................................. 369
Static Information Tab ................................................................... 369
Current Status Tab ......................................................................... 370
Dataqueues ................................................................................................... 371
Table of Contents
xiii | P a g e
Static Information Tab ................................................................... 371
Current Status Tab ......................................................................... 372
Event Flags .................................................................................................... 373
Static Information Tab ................................................................... 373
Current Status Tab ......................................................................... 374
Mailboxes ...................................................................................................... 374
Static Information Tab ................................................................... 375
Current Status Tab ......................................................................... 375
Memory Pools ............................................................................................... 376
Static Information Tab ................................................................... 376
Current Status Tab ......................................................................... 377
Cyclic Handlers .............................................................................................. 378
Static Information Tab ................................................................... 378
Current Status Tab ......................................................................... 379
Alarm Handlers .............................................................................................. 379
Static Information Tab ................................................................... 380
Current Status Tab ......................................................................... 380
Prioritized Dataqueues .................................................................................. 381
Static Information Tab ................................................................... 381
Current Status Tab ......................................................................... 382
System Status ................................................................................................ 383
Interrupt Line Configuration ......................................................................... 383
Interrupt Handler Static Information ............................................................ 384
CPU Exception Handler Static Information ................................................... 385
Micrium µC/OS-III ................................................................................... 387
Requirements ................................................................................................ 387
Finding the Views .......................................................................................... 387
System Information ....................................................................................... 388
Task List ......................................................................................................... 390
Table of Contents
xiv | P a g e
Semaphores .................................................................................................. 391
Mutexes......................................................................................................... 392
Message Queues ........................................................................................... 393
Event Flags .................................................................................................... 394
Timers ............................................................................................................ 395
Memory Partitions ........................................................................................ 396
Source Code Review ...........................................398
Introduction to Code Reviews ................................................................ 399
Planning a Review – Review ID Creation ................................................ 401
Creating a Review ID ..................................................................................... 402
Tailoring a Review ID Template ..................................................................... 407
Conducting a Source Code Review ......................................................... 409
Individual Phase ............................................................................................ 412
Team Phase ................................................................................................... 414
Rework Phase ................................................................................................ 416
Additional Settings ........................................................................................ 417
Revision History ................................................419
Revision History ...................................................................................... 420
List of Figures
xv | P a g e
Figures
Figure 1 - Workspaces and Projects ............................................................. 34
Figure 2 – Editing Perspective ...................................................................... 35
Figure 3 - Switch Perspective ....................................................................... 36
Figure 4 - Switch Perspective ....................................................................... 36
Figure 5 – Toolbar Buttons for Perspectives and Views .............................. 36
Figure 6 - View Menu toolbar button .......................................................... 37
Figure 7 - Show View Dialog Box .................................................................. 38
Figure 8 – Toolbar Buttons for Perspectives and Views .............................. 38
Figure 9 - Workspace Launcher .................................................................... 39
Figure 10 - Information Center .................................................................... 40
Figure 11 – Information Center Menu Command ....................................... 41
Figure 12 – Information Center Toolbar Button (A) ..................................... 41
Figure 13 – Startup Preferences ................................................................... 42
Figure 14 – Project Creation Buttons ........................................................... 43
Figure 15 - Starting the Project Wizard ........................................................ 43
Figure 16 - C Project Configuration .............................................................. 44
Figure 17 - C Project Configuration .............................................................. 45
Figure 18 - TrueSTUDIO Hardware Configuration ........................................ 46
Figure 19 - TrueSTUDIO Project Wizard Using Search Field......................... 47
Figure 20 – TrueSTUDIO Filter Board/Microcontroller ................................ 48
Figure 21 - TrueSTUDIO Hardware Configuration ........................................ 49
Figure 22 - TrueSTUDIO Software Configuration ......................................... 50
Figure 23 - TrueSTUDIO Debugger Configuration ........................................ 51
Figure 24 - Select Configurations ................................................................. 52
Figure 25 - Project Explorer View ................................................................. 53
Figure 26 – Editor View ................................................................................ 53
Figure 27 – Project Creation Buttons ........................................................... 54
igure 28 – Atollic TrueSTORE ........................................................................ 54
Figure 29 – Selection of Existing Project File ............................................... 55
Figure 30 – Selection of Static Library Project ............................................. 56
Figure 31 – Examples of options to be used with objcopy ...................... 58
Figure 32 – Create a Makefile Project from existing code ........................... 58
Figure 33 – Locate the code and select <none> .......................................... 59
Figure 34 – Edit the PATH variable ............................................................... 59
List of Figures
xvi | P a g e
Figure 35 - Import Projects (EWARM) .......................................................... 62
Figure 36 - Import Projects from Folder or Archive (EWARM) .................... 63
Figure 37 - Import Projects from File System (EWARM) .............................. 64
Figure 38 - Display Installed Project Configurators (EWARM) ..................... 64
Figure 39 - Import Several Projects from File System (EWARM) ................. 65
Figure 40 - EWARM CMSIS option................................................................ 69
Figure 41 - TrueSTUDIO compiler include paths .......................................... 69
Figure 42 - TrueSTUDIO linker script file option .......................................... 70
Figure 43 - Edit Debug Configuration ........................................................... 73
Figure 44 - Selecting Debug Probe ............................................................... 73
Figure 45 – Import Projects .......................................................................... 76
Figure 46 – Import Projects from Folder or Archive .................................... 77
Figure 47 – Import Projects from File System .............................................. 78
Figure 48 – Display Installed Project Configurators ..................................... 78
Figure 49 – Project Converter Conversion Information ............................... 79
Figure 50 – Project Imported Information ................................................... 79
Figure 51 – Import Several Projects from File System ................................. 80
Figure 52 – Project Converter Information .................................................. 80
Figure 53 – Project Imported Information ................................................... 81
Figure 54 – Edit Debugger Configuration ..................................................... 82
Figure 55 – Build Settings Toolbar Button ................................................... 84
Figure 56 – Build Settings Menu Selection................................................... 84
Figure 57 - Project Properties Dialog Box .................................................... 85
Figure 58 – Tool Settings, Miscellaneous Options ....................................... 86
Figure 59 – Target Settings Dialog Box......................................................... 87
Figure 60 – Select Affected Build Configuration .......................................... 88
Figure 61 – Change active Build Configuration ............................................ 90
Figure 62 – Source Folders ........................................................................... 91
Figure 63 – Source Location Tab .................................................................. 91
Figure 64 – Folder Selection Tab .................................................................. 92
Figure 65 – New Source Folder .................................................................... 92
Figure 66 – Include a Library ........................................................................ 93
Figure 67 – Add the Library to the Include Paths ......................................... 94
Figure 68 – Compiler Settings ...................................................................... 95
Figure 69 – Finding the C/C++ Manual in Information Center ..................... 96
Figure 70 – Compiler Optimization Settings for a Project ........................... 97
Figure 71 – Compiler Optimization Settings for a File ................................. 98
List of Figures
xvii | P a g e
Figure 72 – Linker LTO Settings for a Project ............................................... 99
Figure 73 – Linker LTO Settings for a Project ............................................. 100
Figure 74 – Build Settings Toolbar Button ................................................. 100
Figure 75 – Tool Chain Version tab ............................................................ 101
Figure 76 – Manage the Build Configurations............................................ 102
Figure 77 – Create New Configuration ....................................................... 103
Figure 78 – Old Tool Chain Version for the New Build Configuration ....... 103
Figure 79 – Output Format Selection ......................................................... 104
Figure 80 - Build Toolbar Button ................................................................ 106
Figure 81 – Parallel Build ............................................................................ 107
Figure 82 – Build on Save ........................................................................... 108
Figure 83 – Rebuild Toolbar Button ........................................................... 108
Figure 84 – Rebuild Active Configuration Menu Selection ........................ 109
Figure 85 – Build All Projects ...................................................................... 109
Figure 86 – Build All Build Configurations .................................................. 110
Figure 87 – Open the Properties view ....................................................... 113
Figure 88 – Open the Properties view ....................................................... 114
Figure 89 – Build Settings Toolbar Button ................................................. 115
Figure 90 – Generate –list Files .................................................................. 116
Figure 91 – Enable the Build Automatically Menu Item ............................ 117
Figure 92 – Build Selected File(s) ............................................................... 118
Figure 93 – GNU Linker manual link ........................................................... 119
Figure 94 – Set Project References ............................................................ 120
Figure 95 – Set Project References ............................................................ 121
Figure 96 – Enable Dead Code Removal .................................................... 122
Figure 97 – Do Not Use Standard Start Files .............................................. 123
Figure 98 – Linker Page Size Allocation for malloc() .................................. 124
Figure 99 – Add Additional Object Files ..................................................... 125
Figure 100 – Add File With a List of Object Files ........................................ 126
Figure 101 – Automatically Generate a New Linker Script ........................ 131
Figure 102 – Select New, Other… ............................................................... 132
Figure 103 – Select New, Other… ............................................................... 132
Figure 104 – Enter the name of the script ................................................. 133
Figure 105 – Manage Workspaces ............................................................. 140
Figure 106 – Display Java Heap Space Status............................................. 141
Figure 107 – Workspace Unavailable ......................................................... 142
Figure 108 – Editor with text zoomed in .................................................... 144
List of Figures
xviii | P a g e
Figure 109 – Folding Markers ..................................................................... 145
Figure 110 – Mark a column....................................................................... 146
Figure 111 – Add text to all rows ............................................................... 146
Figure 112 – Select a block of text ............................................................. 147
Figure 113 – Find all Shortcuts ................................................................... 147
Figure 114 – The Indexer Picks up the Documentation for a Function ..... 148
Figure 115 – Workspace Indexer Settings .................................................. 149
Figure 116 – Project Indexer Settings ........................................................ 150
Figure 117 – Scanner Discovery Settings ................................................... 151
Figure 118 – Preprocessor Include Paths, Macros etc. .............................. 152
Figure 119 – Add or remove include path ................................................. 153
Figure 120 – Include Browser ..................................................................... 154
Figure 121 – Create Linked File .................................................................. 155
Figure 122 – Create Linked File .................................................................. 156
Figure 123 – Build Tools ............................................................................. 158
Figure 124 – Disassemble file(s) without data ........................................... 159
Figure 125 – List symbols with size ............................................................ 159
Figure 126 – New, Other… ......................................................................... 160
Figure 127 – Select Minimal System Calls Implementation ....................... 161
Figure 128 – Select Location and Heap Implementation ........................... 161
Figure 129 – Add –fPIE for Assembler and C Compiler .............................. 163
Figure 130 – Use –fPIE for Linker ............................................................... 164
Figure 131 – Remove the monitor reset command ................................... 165
Figure 132 – CMSIS Packs Preferences ...................................................... 167
Figure 133 – Open CMSIS Pack Manager Perspective ............................... 168
Figure 134 – Packs View Empty .................................................................. 168
Figure 135 – Packs View Toolbar................................................................ 169
Figure 136 – Refresh all Packs .................................................................... 169
Figure 137 – Read error during refreshing packs ....................................... 169
Figure 138 – Packs View Updated .............................................................. 170
Figure 139 – Devices Software Pack .......................................................... 171
Figure 140 – Search STM32 Devices Software Pack................................... 172
Figure 141 – Boards Software Pack ............................................................ 173
Figure 142 – Open Installed CMSIS Packs View ......................................... 174
Figure 143 – Install Packs ........................................................................... 175
Figure 144 – Installing Pack ........................................................................ 175
Figure 145 – Installed Pack ......................................................................... 176
List of Figures
xix | P a g e
Figure 146 – Installed CMSIS-Packs ............................................................ 176
Figure 147 – Create CMSIS C/C++ Project .................................................. 177
Figure 148 – Create CMSIS C/C++ Project (main) ...................................... 178
Figure 149 – Create CMSIS C/C++ Project (device) .................................... 179
Figure 150 – Create CMSIS C/C++ Project (configurations) ....................... 179
Figure 151 – Configure CMSIS C/C++ Project ............................................. 180
Figure 152 – Configure CMSIS C/C++ Project with Startup file .................. 181
Figure 153 – Configure CMSIS C/C++ Project with CMSIS CORE files ........ 182
Figure 154 – Build CMSIS C/C++ Project .................................................... 183
Figure 155 – Setup CMSIS C/C++ Project Linker Script File ........................ 184
Figure 156 – Disable Startup File from CMSIS C/C++ Project .................... 185
Figure 157 – Debug CMSIS C/C++ Project Configurations ......................... 186
Figure 158 – Debug CMSIS RTE C/C++ Project ........................................... 187
Figure 159 – Select Eclipse Marketplace .................................................... 188
Figure 160 – Install Using Eclipse Marketplace .......................................... 189
Figure 161 – Select Install New Software................................................... 189
Figure 162 – Enter Download Site and Select Plugins ............................... 190
Figure 163 – Accept License Agreements .................................................. 191
Figure 164 – The Plugins are Installed ....................................................... 192
Figure 165 – Uninstalling Plugins ............................................................... 192
Figure 166 – ST-LINK_CLI.exe ..................................................................... 194
Figure 167 – ST-LINK_CLI.exe ..................................................................... 195
Figure 168 – Convert the Build Output to Intel Hex .................................. 196
Figure 169 – Modify the Debug Configuration .......................................... 197
Figure 170 – Create a Launch Group .......................................................... 198
Figure 171 – Edit a Launch Group .............................................................. 198
Figure 172 – Select Launch Mode: debug .................................................. 199
Figure 173 – Select Launch Mode: debug .................................................. 200
Figure 174 – Debug History ........................................................................ 200
Figure 175 – Quick Access Search Bar ........................................................ 201
Figure 176 – Enable SVN Command Group................................................ 203
Figure 177 – SVN Views .............................................................................. 204
Figure 178 – Add SVN Property .................................................................. 205
Figure 179 – Open SVN Repositories ......................................................... 207
Figure 180 – New Repository Button ......................................................... 207
Figure 181 – Create Repository Dialog ....................................................... 208
Figure 182 –Repository Created................................................................. 208
List of Figures
xx | P a g e
Figure 183 –Share Project Dialog ............................................................... 208
Figure 184 –Projects Version Controlled ................................................... 208
Figure 185 – Multiple Editors, Views and Windows used at the same time
.................................................................................................................... 211
Figure 186 – New Window ......................................................................... 211
Figure 187 – New Window ......................................................................... 212
Figure 188 – Terminal................................................................................. 213
Figure 189 –Terminal View ........................................................................ 213
Figure 190 –Launch Terminal ..................................................................... 214
Figure 191 –Terminal Opened .................................................................... 214
Figure 192 –Local Debugging ..................................................................... 216
Figure 193 –Remote Debugging ................................................................. 217
Figure 194 – Start Debug Session Toolbar Button ..................................... 218
Figure 195 - Debug Configuration Dialog Box ............................................ 218
Figure 196 – The Configure Debug Toolbar Button ................................... 219
Figure 197 - Debug Configuration, Debugger Panel for the SEGGER J-Link220
Figure 198 - Debug Configuration, Debugger Panel for the ST-Link .......... 220
Figure 199 - Debug Configuration, Startup Scripts Panel .......................... 222
Figure 200 – Debug Perspective ................................................................. 224
Figure 201 – JTAG Scan Chain Selected...................................................... 225
Figure 202 – The Configure Debug Toolbar Button ................................... 228
Figure 203 – The target ELF-file in Debug Session Configuration .............. 229
Figure 204 – Using variables in the path .................................................... 230
Figure 205 – Debug configuration as shared file ....................................... 231
Figure 206 – Customize Perspective Dialog Box ........................................ 232
Figure 207 - Run Menu ............................................................................... 233
Figure 208 - Run Control Command Toolbar ............................................. 233
Figure 209 – Terminate, Rebuild and Re-launch Toolbar Button .............. 234
Figure 210 – Instruction Stepping Button .................................................. 234
Figure 211 – Disassembly View .................................................................. 235
Figure 212 - Toggle Breakpoint Context Menu .......................................... 235
Figure 213 – Breakpoints View .................................................................. 235
Figure 214 – Breakpoints Properties .......................................................... 236
Figure 215 – Conditional Breakpoint ......................................................... 237
Figure 216 – Expressions View ................................................................... 237
Figure 217 – Drag and Drop of Variable to the Expressions View ............. 238
Figure 218 – Complex Expressions ............................................................. 238
List of Figures
xxi | P a g e
Figure 219 – Live Expressions View ............................................................ 239
Figure 220 – Live Expressions View Number Format ................................. 239
Figure 221 – Variables View ....................................................................... 240
Figure 222 – Variables View – change Number format ............................. 240
Figure 223 - The Memory Fill Toolbar Button ............................................ 241
Figure 224 - The Memory Fill dialog ........................................................... 241
Figure 225 - SFRs Menu Command ............................................................ 242
Figure 226 - SFRs View ............................................................................... 243
Figure 227 - SFRs Filter Clear ...................................................................... 243
Figure 228 – SFR View Buttons .................................................................. 244
Figure 229 – CMSIS-SVD Settings Properties Panel ................................... 244
Figure 230 – Fault Analyzer View with STKERR .......................................... 247
Figure 231 – Terminal View ........................................................................ 248
Figure 232 – Terminal Toolbars.................................................................. 248
Figure 233 – Terminal Settings ................................................................... 248
Figure 234 – Terminal Settings ................................................................... 250
Figure 235 – Modify Startup Script ............................................................ 252
Figure 236 - The Terminate Menu Command ............................................ 254
Figure 237 - C/C++ Editing Perspective ...................................................... 255
Figure 238 – Changing the Path to the GDB Server ................................... 256
Figure 239 –GDB Server Control Panel – General Tab ............................... 257
Figure 240 –GDB Server Control Panel – Settings tab ............................... 258
Figure 241 – Debug Configuration – Connect to Remote GDB Server....... 259
Figure 242 – Build Analyzer ........................................................................ 265
Figure 243 – Memory Regions Tab ............................................................ 266
Figure 244 – Memory Details Tab .............................................................. 267
Figure 245 – Memory Details Sorted ......................................................... 269
Figure 246 – Memory Details Search/Filter ............................................... 270
Figure 247 – Calculate Sum of Size ............................................................ 271
Figure 248 – Show Byte Count ................................................................... 271
Figure 249 – Size Information in Byte Format ........................................... 272
Figure 250 – Copy and Paste ...................................................................... 273
Figure 251 – Static Stack Analyzer List Tab ................................................ 275
Figure 252 – Static Stack Analyzer Call Graph Tab ..................................... 275
Figure 253 – Enable Generate per Function Stack Usage Information ...... 276
Figure 254 –Function Symbols in Static Stack Analyzer ............................. 277
Figure 255 –List tab .................................................................................... 279
List of Figures
xxii | P a g e
Figure 256 –Call Graph tab ......................................................................... 281
Figure 257 –List tab using filter .................................................................. 282
Figure 258 –Call Graph tab using search .................................................... 282
Figure 259 – Copy and Paste ...................................................................... 283
Figure 260 –Different Types of Tracing ...................................................... 286
Figure 261 – Open Debug Configurations Toolbar Button ........................ 287
Figure 262 – Change ST-Link Debug Configuration for SWV ...................... 287
Figure 263 – Change SEGGER J-Link Debug Configuration for SWV .......... 288
Figure 264 – SWV Data Trace Menu Command ......................................... 289
Figure 265 – Configure Serial Wire Viewer Button .................................... 289
Figure 266 – The Serial Wire Viewer Settings Dialog ................................. 290
Figure 267 – The Start/Stop Trace Button ................................................. 293
Figure 268 – Resume Debug Button .......................................................... 293
Figure 269 – Empty SWV Data Button ....................................................... 293
Figure 270 – Several SWV Views Displayed Simultaneously...................... 295
Figure 271 –Statistical Profiling Configuration .......................................... 297
Figure 272 – Statistical Profiling View ........................................................ 297
Figure 273 – Exception Tracing Configuration ........................................... 298
Figure 274 – Exception View, Data Tab ...................................................... 298
Figure 275 – Exception View, Statistics Tab ............................................... 299
Figure 276 – Serial Wire Viewer Preferences............................................. 303
Figure 277 –MTB Trace Log View ............................................................... 306
Figure 278 – Configure MTB Trace Setting Button .................................... 307
Figure 279 – Configure MTB Trace View .................................................... 307
Figure 280 – Configure MTB with Error Setting ......................................... 308
Figure 281 – The Start/Stop MTB Button ................................................... 309
Figure 282 – Clear Buffer Button ............................................................... 309
Figure 283 – Scroll Trace View on Update Button ..................................... 309
Figure 284 –MTB Trace Log Information ................................................... 311
Figure 285 –MTB Trace Buffer Wrapped ................................................... 311
Figure 286 – Enable Tracing in the Debug Configuration .......................... 315
Figure 287 – Configuration Toolbar Button ............................................... 318
Figure 288 - Trace Configuration ................................................................ 318
Figure 289 - Trace Configuration ................................................................ 320
Figure 290 – Add Trace Trigger in the Editor ............................................. 321
Figure 291 –Trace Trigger in the Editor ...................................................... 321
Figure 292 –Trace Trigger in the Editor ...................................................... 322
List of Figures
xxiii | P a g e
Figure 293 – Record Toolbar Button .......................................................... 322
Figure 294 - The Trace Log View ................................................................ 323
Figure 295 - Trace Restarted ...................................................................... 323
Figure 296 – Display Options Toolbar Button ............................................ 324
Figure 297 – Search Toolbar Button .......................................................... 324
Figure 298 – Export Toolbar Button ........................................................... 325
Figure 299 - Exporting the Trace Log ......................................................... 325
Figure 300 - View Top Level Menu ............................................................. 328
Figure 301 - embOS Show View Toolbar Button ........................................ 329
Figure 302 - embOS System Information View .......................................... 329
Figure 303 - embOS System Information View (Fault Condition) .............. 329
Figure 304 - embOS Task List View ............................................................ 330
Figure 305 - embOS Timers View ............................................................... 332
Figure 306 - embOS Resource Semaphores View ...................................... 333
Figure 307 - embOS Mailboxes View ......................................................... 333
Figure 308 – eTaskSync Show View Toolbar Button .................................. 335
Figure 309 - eTaskSync Task List View ....................................................... 336
Figure 310 – FreeRTOS View Top Level Menu ........................................... 338
Figure 311 – FreeRTOS Show View Toolbar Button ................................... 338
Figure 312 - FreeRTOS Task List View ........................................................ 339
Figure 313 - FreeRTOS Queues View .......................................................... 340
Figure 314 - FreeRTOS Semaphores View .................................................. 342
Figure 315 - FreeRTOS Timers View ........................................................... 343
Figure 316 – RTXC Show View Toolbar Button .......................................... 344
Figure 317 – RTXC Kernel Information View .............................................. 345
Figure 318 - RTXC Task List tab in Task view .............................................. 346
Figure 319 – RTXC Task Stack Info .............................................................. 347
Figure 320 - RTXC Alarms View .................................................................. 348
Figure 321 - RTXC Counters View ............................................................... 349
Figure 322 - RTXC Event Sources View ....................................................... 350
Figure 323 - RTXC Exception Backtrace View ............................................. 351
Figure 324 - RTXC Exceptions View ............................................................ 351
Figure 325 - RTXC Mailboxes View ............................................................. 352
Figure 326 - RTXC Mutexes View ............................................................... 353
Figure 327 - RTXC Partitions View .............................................................. 354
Figure 328 - RTXC Pipes View ..................................................................... 355
Figure 329 - RTXC Queues View ................................................................. 356
List of Figures
xxiv | P a g e
Figure 330 - RTXC Semaphores View ......................................................... 357
Figure 331 – ThreadX View Top Level Menu .............................................. 359
Figure 332 - ThreadX Show View Toolbar Button ...................................... 360
Figure 333 - ThreadX Thread List View ...................................................... 360
Figure 334 - ThreadX Semaphores View .................................................... 362
Figure 335 - ThreadX Mutexes View .......................................................... 362
Figure 336 - ThreadX Message Queues View ............................................. 363
Figure 337 - ThreadX Event Flags View ...................................................... 364
Figure 338 - ThreadX Timers View ............................................................. 365
Figure 339 - ThreadX Memory Block Pools View ....................................... 366
Figure 340 - ThreadX Memory Byte Pools View ........................................ 367
Figure 341 – TOPPERS Show View Toolbar Button .................................... 368
Figure 342 – TOPPERS Tasks Static Information Tab ................................. 369
Figure 343 – TOPPERS Tasks Current Status Tab ....................................... 370
Figure 344 – TOPPERS Dataqueues Static Information Tab ....................... 371
Figure 345 – TOPPERS Dataqueues Current Status Tab ............................. 372
Figure 346 – TOPPERS Event Flags Static Information Tab ........................ 373
Figure 347 – TOPPERS Event Flags Current Status Tab .............................. 374
Figure 348 – TOPPERS Mailboxes Static Information Tab ......................... 375
Figure 349 – TOPPERS Mailboxes Current Status Tab ............................... 375
Figure 350 – TOPPERS Memory Pools Static Information Tab ................... 376
Figure 351 – TOPPERS Memory Pools Current Status Tab ........................ 377
Figure 352 – TOPPERS Cyclic Handlers Static Information Tab .................. 378
Figure 353 – TOPPERS Cyclic Handlers Current Status Tab........................ 379
Figure 354 – TOPPERS Alarm Handlers Static Information Tab ................. 380
Figure 355 – TOPPERS Alarm Handlers Current Status Tab ....................... 380
Figure 356 – TOPPERS Prioritized Dataqueues Static Information Tab ..... 381
Figure 357 – TOPPERS Prioritized Dataqueues Current Status Tab ........... 382
Figure 358 – TOPPERS System Status View ................................................ 383
Figure 359 – TOPPERS Interrupt Line Config View ..................................... 384
Figure 360 – TOPPERS Interrupt Handler Static Info View ........................ 385
Figure 361 – TOPPERS Exception Handler Static Info View ....................... 385
Figure 362 - View Top Level Menu ............................................................. 388
Figure 363 - Show View Toolbar Button .................................................... 388
Figure 364 - µC/OS-III System Information View ....................................... 389
Figure 365 - µC/OS-III Task List View .......................................................... 390
Figure 366 - µC/OS-III Semaphores View ................................................... 392
List of Figures
xxv | P a g e
Figure 367 - µC/OS-III Mutexes View ......................................................... 393
Figure 368 - µC/OS-III Message Queues View............................................ 394
Figure 369 - µC/OS-III Event Flags View ..................................................... 395
Figure 370 - µC/OS-III Timers View ............................................................ 395
Figure 371 - µC/OS-III Memory Partitions View ......................................... 396
Figure 372 – Atollic TrueSTUDIO Support for the Code Review Workflow 399
Figure 373 – Project Properties Menu Selection ....................................... 402
Figure 374 - GUI for Creating and Managing Code Reviews ...................... 402
Figure 375 - Dialog for Creating a New Review ID ..................................... 403
Figure 376 - Dialog for Managing the Work Product of a Review ............. 403
Figure 377 - Add Reviewers to the Review ................................................ 404
Figure 378 - Choose Author for the Review Session .................................. 404
Figure 379 - Review Comment Parameter Options ................................... 405
Figure 380 - Setting Default Options for Review Parameters .................... 405
Figure 381 - Naming the Review Issue Data Folder ................................... 406
Figure 382 - Filter Settings for the Different Phases .................................. 406
Figure 383 - Editing the DEFAULT Review Template ................................. 408
Figure 384 - Code Review Selected via Open Perspective Command ....... 409
Figure 385 - The Code Review Perspective ................................................ 409
Figure 386 – The Code Review Table View ................................................ 410
Figure 387 – The Code Review Editor View ............................................... 411
Figure 388 - Individual Phase Selected in the Code Review Toolbar ......... 412
Figure 389 - Reviewer ID Selection Dialog ................................................. 412
Figure 390 - The Source Code Button & Drop-Down Menu ...................... 413
Figure 391 - Add Code Review Issue... ....................................................... 413
Figure 392 – A Code Review Issue in the Review Editor View ................... 414
Figure 393 - Review Marker Displayed on Editor Line 101 ........................ 414
Figure 394 - Team Phase Toolbar Button ................................................... 415
Figure 395 - Code Review Editor View Content in Team Phase ................. 415
Figure 396 - Review Markers and Tooltip Information in the Editor ......... 416
Figure 397 - Team Phase Toolbar Button ................................................... 416
Figure 398 - Code Review Editor View Content in the Rework Phase ....... 417
Figure 399 - Accessing Code Review Preference Settings ......................... 417
Figure 400 - Customize Filters Applied for All Phases ................................ 418
Figure 401 - Customize Visible Code Review Table Columns .................... 418
List of Tables
xxvi | Page
Tables
Table 1 – Typographic Conventions ............................................................. 30
Table 2 - EWARM vs TrueSTUDIO build options .......................................... 68
Table 3 – Memory Regions Usage Color .................................................... 266
Table 4 – Memory Details .......................................................................... 267
Table 5 – Static Stack Analyzer List tab ...................................................... 279
Table 6 – Static Stack Analyzer Call Graph tab ........................................... 280
Table 7 – Exception Data Columns ............................................................. 299
Table 8 – Exception Statistics Columns ...................................................... 301
Table 9 – MTB Trace Log View Columns .................................................... 310
Table 10 – embOS System Variables .......................................................... 330
Table 11 – embOS Task Parameters ........................................................... 331
Table 12 – embOS Timer Parameters ........................................................ 332
Table 13 – embOS Resource Semaphore Parameters ............................... 333
Table 14 – embOS Mailbox Parameters ..................................................... 334
Table 15 – eTaskSync Task Parameters ...................................................... 336
Table 16 – FreeRTOS Task Parameters....................................................... 340
Table 17 – FreeRTOS Queue Parameters ................................................... 341
Table 18 – FreeRTOS Semaphore Parameters ........................................... 342
Table 19 – FreeRTOS Timer Parameters .................................................... 343
Table 20 – RTXC Kernel Information .......................................................... 345
Table 21 – RTXC Task List Parameters ........................................................ 347
Table 22 – RTXC Stack Info ......................................................................... 347
Table 23 – RTXC Alarm Parameters ........................................................... 348
Table 24 – RTXC Counter Parameters ........................................................ 349
Table 25 – RTXC Event Source Parameters ................................................ 350
Table 26 – RTXC Exception Backtrace Parameters .................................... 351
Table 27 – RTXC Exception Parameters ..................................................... 352
Table 28 – RTXC Mailbox Parameters ........................................................ 352
Table 29 – RTXC Mutex Parameters ........................................................... 354
Table 30 – RTXC Partition Parameters ....................................................... 355
Table 31 – RTXC Pipe Parameters .............................................................. 356
Table 32 – RTXC Queue Parameters .......................................................... 357
Table 33 – RTXC Semaphore Parameters ................................................... 358
Table 34 – ThreadX Thread Parameters ..................................................... 361
Overview
xxvii | P a g e
Table 35 – ThreadX Semaphore Parameters ............................................. 362
Table 36 – ThreadX Mutex Parameters ..................................................... 363
Table 37 – ThreadX Message Queue Parameters ...................................... 364
Table 38 – ThreadX Event Flag Parameters ............................................... 364
Table 39 – ThreadX Timer Parameters ....................................................... 365
Table 40 – ThreadX Memory Block Pool Parameters ................................ 366
Table 41 – ThreadX Memory Byte Pool Parameters .................................. 367
Table 42 – TOPPERS Tasks Static Information ........................................... 370
Table 43 – TOPPERS Tasks Current Status ................................................. 371
Table 44 – TOPPERS Dataqueue Static Information .................................. 372
Table 45 – TOPPERS Dataqueues Current Status ....................................... 372
Table 46 – TOPPERS Event Flags Static Information .................................. 373
Table 47 – TOPPERS Event Flags Current Status ........................................ 374
Table 48 – TOPPERS Mailboxes Static Information .................................... 375
Table 49 – TOPPERS Mailboxes Current Status.......................................... 376
Table 50 – TOPPERS Memory Pools Static Information ............................. 377
Table 51 – TOPPERS Memory Pools Current Status ................................... 377
Table 52 – TOPPERS Cyclic Handlers Static Information ............................ 379
Table 53 – TOPPERS Cyclic Handlers Current Status .................................. 379
Table 54 – TOPPERS Alarm Handlers Static Information ........................... 380
Table 55 – TOPPERS Alarm Handlers Current Status Information ............. 381
Table 56 – TOPPERS Prioritized Dataqueue Static Information ................. 382
Table 57 – TOPPERS Prioritized Dataqueues Current Status Information . 382
Table 58 – TOPPERS System Status Information ....................................... 383
Table 59 – TOPPERS Interrupt Line Config Information ............................. 384
Table 60 – TOPPERS Interrupt Handlers Static Information ...................... 385
Table 61 – TOPPERS Interrupt Handlers Static Information ...................... 386
Table 62 – µC/OS-III System Variables ....................................................... 390
Table 63 – µC/OS-III Task Parameters ........................................................ 391
Table 64 – µC/OS-III Semaphore Parameters ............................................ 392
Table 65 – µC/OS-III Mutexes Parameters ................................................. 393
Table 66 – µC/OS-III Message Queue Parameters ..................................... 394
Table 67 – µC/OS-III Event Flag Parameters .............................................. 395
Table 68 – µC/OS-III Timer Parameters ...................................................... 396
Table 69 – µC/OS-III Memory Partitions Parameters ................................ 397
Table 70 – Atollic TrueSTUDIO Support for the Code Review Workflow... 400
Table 71 - Code Review Toolbar Buttons ................................................... 410
Overview
xxviii | P a g e
Table 72 - Code Review Table View Toolbar Button Description .............. 411
Table 73 – The Code Review Editor View Toolbar Button Description ...... 412
Table 74 – Revision History ........................................................................ 421
Introduction
29 | P a g e
ABOUT THIS DOCUMENT
Welcome to the Atollic TrueSTUDIO® for STM32 User Guide. The purpose of this
document is to provide information on how to use Atollic TrueSTUDIO®.
INTENDED READERS
This document is primarily intended for users of Atollic TrueSTUDIO®.
Please note that this manual applies to users of STM32 target devices only.
Introduction
30 | P a g e
DOCUMENT CONVENTIONS
The text in this document is formatted to ease understanding and provide clear and
structured information on the topics covered. The following typographic conventions
apply:
Table 1 – Typographic Conventions
Use
Keyboard Command or Source Code Section.
Name of a User Interface Object (Menu, Menu Command,
Button, Dialog Box, etc.) that appears on the computer
screen.
Cross reference within the document, or to an external
document.
Name of Atollic product.
Identifies instructions specific to the Graphical User
Interface (GUI).
Identifies instructions specific to the Command Line
Interface (CLI).
Identifies Help Tips and Hints.
Identifies a Caution.
Introduction
31 | P a g e
GETTING STARTED
This section provides information on how to begin using Atollic TrueSTUDIO® for STM32.
The following topics are covered:
Introduction
Preparing for Start
Starting the Program
Creating a New Project
Configuring the Project
Building the Project
Debugging
Getting Started
32 | P a g e
INTRODUCTION
Welcome to Atollic® TrueSTUDIO® for STM32. The product is available for free. Advanced
functionality which earlier required a license is now fully enabled directly after installation.
TrueSTUDIO has the following key features:
Built on Open Standards (Eclipse, CDT, GCC, and GDB)
Edit, Compile & Build (No code size limitation)
Project Management
o STM32 MCUs and Board support
o CMSIS-Pack project support
o Build/Memory Analyzer
o Stack Analyzer
o Bug Tracking
o Version Control
Debug
o Hard Fault Analyzer
o Live Variable Watch
o Trace (SWV, ETM, ETB, MTB)
o Statistical Profiling
o RTOS-aware Debug
o Multi Project Debug
Getting Started
33 | P a g e
PREPARING FOR START
Atollic TrueSTUDIO is built using the ECLIPSE™ framework, and thus inherits some
characteristics that may be unfamiliar to new users. The following sections outline
important information to users without previous experience of ECLIPSE™.
WORKSPACES & PROJECTS
As Atollic TrueSTUDIO is built using the ECLIPSE™ framework, the ECLIPSE™ project and
workspace model applies. The basic concept is outlined below:
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 many projects.
The user may switch between workspaces, but only one workspace can be active
at any 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.
Switching workspace is a quick way of shifting from one set of projects to another
set of projects. It will trigger a quick restart of the product.
In practice, the project and workspace model facilitates a well-structured hierarchy of
workspaces, containing projects, containing files.
Getting Started
34 | P a g e
PERSPECTIVES & VIEWS
Atollic TrueSTUDIO is a very powerful product with a great 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 this problem, views can be organized in perspectives, where a perspective
contains a number of predefined views. A perspective typically handles one development
task, such as:
C/C++ Code Editing
Debugging
Bug Database Access
Version Control
Code Review
As an example, the C/C++ Editing perspective displays views that relate to code editing,
such as Editor Outline and Class Browser. The Debug perspective displays views that relate
to Debugging, such as Breakpoints and CPU Registers.
Atollic TrueSTUDIO®
Workspace 1
(C:\Joe\Workspace)
Project A
Project B
. . .
Workspace 2
(C:\Customer1)
Project C
Project D
. . .
Workspace 3
(X:\NewProjects)
Project E
Project F
. . .
Workspace
currently inactive
Workspace
currently active
Workspace
currently inactive
Figure 1 - Workspaces and Projects
Getting Started
35 | P a g e
Switching from one perspective to another is a quick way to hide some views and display
others.
Atollic TrueSTUDIO comes with a number of pre-configured perspectives. Developers may
modify these, or create entirely new, at will. Atollic TrueSTUDIO is designed around a
philosophy that one perspective shall be used for one task, and that a perspective should
not contain a lot of GUI objects from other perspectives.
As the figure below outlines, the idea is that one perspective shall be used for each work
task. It is however clear that one perspective, the C/C++ editing perspective is the
“master” perspective where developers spend most time. Therefor that perspective is the
center-point of Atollic TrueSTUDIO, and developers temporarily jump to other
perspectives to do other tasks, and when completed, jump back to the editing and building
perspective again.
The C/C++ Editing perspective is also the perspective that is opened when Atollic
TrueSTUDIO is started the first time.
Figure 2 – Editing Perspective
We think it is valuable to use the editing and building perspective as the master
perspective, and all other perspectives used temporarily for other work tasks.
To switch perspective, select the Open Perspective toolbar button or use the menu
command View, Open Perspective:
Editing
Building
Debug
Version
control
. . .
Getting Started
36 | P a g e
Figure 3 - Switch Perspective
Alternatively, click any of the perspective buttons in the top right corner of the main
window (only the last few ones active are displayed here):
Figure 4 - Switch Perspective
Figure 5 – Toolbar Buttons for Perspectives and Views
One can always return to the default C/C++ Editing and Building perspective by clicking the
Return to editor and building perspective toolbar button (D). Editing and Building is the
main activity for most C/C++ developers, hence the dedicated button.
VIEWS
When Atollic TrueSTUDIO is started for the first time, the C/C++ Editing Perspective is
activated by default. This perspective does not show all available views by default, to
reduce information overload. The same principle applies to all perspectives.
Getting Started
37 | P a g e
To access additional features built into the product, open additional views. To do this,
select the View toolbar button (C) or use the menu command View:
Figure 6 - View Menu toolbar button
The above list of views, while comprehensive, is still not complete. This list only contains
the most common views for the work task related to the currently selected Perspective. 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 the additional features:
Getting Started
38 | P a g e
Figure 7 - Show View Dialog Box
The remaining toolbar buttons related to perspectives and views are:
Figure 8 – Toolbar Buttons for Perspectives and Views
Information Center (A) – Displays the initial welcome screen from the first time the
product was started, after being installed. More details will follow in “Starting the
Program” below.
Perspective (B) – A shortcut that opens a perspective of the user’s choice.
Getting Started
39 | P a g e
STARTING THE PROGRAM
After installing Atollic TrueSTUDIO according to Atollic TrueSTUDIO Installation Guide, start
the program by performing the following steps (applies to Microsoft® Windows® Vista®
and Windows 7®):
1. Open the Microsoft® Windows® Start Menu
2. Click on All Programs
3. Open the Atollic folder
4. Open the TrueSTUDIO for STM32 folder
5. Click on the Atollic TrueSTUDIO item in this folder
6. Wait for the program to start, and the Workspace Launcher dialog to be
displayed.
Figure 9 - Workspace Launcher
This dialog enables the user to select the name and location of the Active
Workspace. The Active Workspace is a folder that will hold all projects
currently accessible by the user. The user may open any existing project in the
workspace. Any newly created projects will be stored in the workspace.
7. Enter the full name (with path) of the workspace folder to be used for the
current session. Alternatively, browse to an existing workspace folder, or use
the default workspace folder. This is located within the home directory of the
current user, e.g. C:\Users\User\Atollic\TrueSTUDIO
If the appointed workspace folder does not yet exist, it will be created.
8. Click on the OK button
Getting Started
40 | P a g e
1. Wait for the Information Center window to be displayed.
Figure 10 - Information Center
The user must have write-access to the home directory to be able to start
Atollic TrueSTUDIO.
Atollic recommends that the Active Workspace folder is located not too
many levels below the file system root. This is to avoid exceeding the
Windows® path length character limitations. This can cause build errors if the
file paths become longer than Windows can handle.
Getting Started
41 | P a g e
This window enables the user to quickly reach information regarding the product, and how
to use it, by clicking on the corresponding hypertext links. 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 during development. When connected to internet also Atollic TruePERSPECTIVES
Blog articles can be reached.
The Information Center window may be reached at any time via the Help, Information
Center menu command or via the Information Center toolbar button.
Figure 11 – Information Center Menu Command
Figure 12 – Information Center Toolbar Button (A)
9. Start using Atollic TrueSTUDIO by closing the Information Center page (click
the “X” in the Information Center page tab above its main window area). The
Information Center window is closed, but may be restored at any time, as
described above.
STARTING WITH DIFFERENT LANGUAGE
Start Atollic TrueSTUDIO from command line using following options:
Sometimes when opening an old workspace the Information Center does not
display valid information, e.g. “This page can’t be displayed” is shown or old
manuals are opened when accessing documents. In such case reload the
page by clicking the Home button, , at the top right corner of the
Information Center window.
Getting Started
42 | P a g e
English TrueSTUDIO.exe -nl en
Japanese TrueSTUDIO.exe -nl ja
Korean TrueSTUDIO.exe -nl ko
Simplified Chinese TrueSTUDIO.exe -nl zh
CHANGE WHAT IS STARTED
If some parts of Atollic TrueSTUDIO is never used, it is a good idea to not start them at all.
That reduces the memory used and speeds things up a bit.
In the menu select Window, Preferences and in the Preference Dialog select General,
Startup and Shutdown.
Figure 13 – Startup Preferences
Getting Started
43 | P a g e
CREATING A NEW PROJECT
Atollic TrueSTUDIO supports both Managed and Unmanaged projects. Managed projects
are handled entirely by the IDE and may be configured via GUI settings. Unmanaged
projects require the existence of a makefile, which needs to be maintained manually.
The toolbar has three buttons for quick creation of new projects.
Figure 14 – Project Creation Buttons
To create a new Managed Mode C project, perform the following steps:
1. Click the button A to create a C Project (A).
As an alternative, select the File, New…, C Project menu command to start
the Atollic TrueSTUDIO project wizard.
Figure 15 - Starting the Project Wizard
Getting Started
44 | P a g e
Wait for the C Project configuration page to be displayed where different kind of
projects can be created. The Atollic TrueSTUDIO product contains two kind of
toolchains, an Atollic ARM Tools and a Atollic PC Tools. The Atollic ARM Tools
toolchain shall be used when building embedded projects. The Atollic PC Tools
toolchain is usable for testing code on the PC.
Figure 16 - C Project Configuration
Enter a Project name (such as “MyProject”), select Embedded C Project as
Project type. Click the Next button.
The project type CMSIS C/C++ Project requires some preparations before it
can be used. Please read the Using CMSIS-Pack in TrueSTUDIO section at
page 166 and Create CMSIS-Pack Based Projects at page 177.
Getting Started
45 | P a g e
Figure 17 - C Project Configuration
2. Wait for the TrueSTUDIO Hardware configuration page to be displayed.
Getting Started
46 | P a g e
Figure 18 - TrueSTUDIO Hardware Configuration
Getting Started
47 | P a g e
Configure the hardware settings according to your evaluation board or custom
board design. The Atollic TrueSTUDIO product contains support for STM32 and
BlueNRG microcontrollers and boards.
To make the selection easier to find a specific board or microcontroller the Select
Hardware Settings dialog includes a Target Filter search field. When this field
contains some characters only Board/Microcontroller matching the text in the
filter field is selectable in the Board/Microcontroller fields. Enter some
characters in the Filter field to reduce the number of selectable
boards/microcontrollers.
For instance if you know the name of your Board/MCU contains “F446” then
enter F446 into the search field. This will limit the number of items which can be
selected and makes it much more easy to find the Board/MCU.
Figure 19 - TrueSTUDIO Project Wizard Using Search Field
Getting Started
48 | P a g e
If the name of your board starts with “Disc” then just enter Disc into the search
field and only boards and devices containing Disc in the name will be listed.
Figure 20 – TrueSTUDIO Filter Board/Microcontroller
Select the board or microcontroller to create a project for.
The Info table in the Project Wizard displays Atollic TrueSTUDIO provided this
device. or CMSIS-Pack provided this device. The information depends on if the
project will be created based upon Atollic TrueSTUDIO Target Supported
Device information or if it will be based on installed CMSIS Pack files. See the
section Using CMSIS-Pack in TrueSTUDIO on page 166 for more information
about CMSIS-Pack.
Getting Started
49 | P a g e
Figure 21 - TrueSTUDIO Hardware Configuration
The default selection for floating point operations is either Software
implementation, Mix HW/SW implementation or Hardware
implementation, depending on the selected microcontroller.
Some microcontrollers have floating point support implemented in hardware.
For such microcontrollers, the selection Hardware implementation is more
efficient, and will thus be default.
However, this setting will not work properly on devices that do not have
floating point support in hardware. In such a case, Software implementation
will be default.
Please note that evaluation boards may have hardware switches for
configuration of Code location in RAM or FLASH. The setting selected in the
project wizard must correspond to the settings on the board.
The text field below the tree displays information about the used device when
a Board or MCU is selected in the tree.
Getting Started
50 | P a g e
The Mix HW/SW implementation is for those projects that have libraries that
aren’t compiled for hardware floating point. In this implementation the
function calls are not using the FPU-registers as in a pure Hardware
implementation. The FPU will however still be used inside the project
functions.
When finished, click the Next button.
3. Wait for the TrueSTUDIO Software configuration page to be displayed.
Figure 22 - TrueSTUDIO Software Configuration
Select the desired Runtime library to be used. For information about the
differences between Newlib–nano and the regular Newlib, please refer to
the Newlib-nano readme file, accessible from the Information Center (Figure
10).
If the target board has a limited amount of memory, the Use tiny
printf/sprinf/fprintf (small code size) setting is recommended.
When finished, click the Next button.
Getting Started
51 | P a g e
4. Wait for the TrueSTUDIO Debugger configuration page to be displayed.
Figure 23 - TrueSTUDIO Debugger Configuration
Atollic TrueSTUDIO supports several different types of JTAG probes. Select the
probe to be used during debugging.
When finished, click the Next button.
If Newlib-nano is used and float shall be used by scanf/printf add these options
to the “C Linker” options field
-u _scanf_float -u _printf_float
E.g. The option field line may now look like
-Wl,-cref,-u,Reset_Handler -u scanf_float -u_printf_float
If using an RTOS, it is recommended to generate a system calls file, and select
the Fixed Heap size option. This option requires that the _Min_Heap_Size
symbol is defined in the linker script .ld file. The .ld file is stored in the root
directory of the currently selected project. The heap size defined by
_Min_Heap_Size must meet the heap size required by the application.
Getting Started
52 | P a g e
5. Wait for the TrueSTUDIO Select Configurations page to be displayed.
Figure 24 - Select Configurations
Keep the default selections. Click on the Finish button.
A new Managed Mode C-project is now created. Atollic TrueSTUDIO
generates target specific sample files in the project folder to simplify
development.
Getting Started
53 | P a g e
6. Expand the project folder (“MyProject” in this example) and the src
subfolder in the Project Explorer view.
Figure 25 - Project Explorer View
7. Double click on the main.c file in the Project Explorer tree to open the file
in the editor.
Figure 26 – Editor View
Getting Started
54 | P a g e
ONE-CLICK EXAMPLE PROJECT INSTALLATION
The Atollic TrueSTORE system is a repository with hundreds of free example projects for
various evaluation boards. Atollic TrueSTUDIO users can easily find the latest available set
of example projects on our server, as well as download and install them into the Atollic
TrueSTUDIO Active Workspace, with a single mouse-click! Any example application of
interest is up and running on the target hardware in less than a minute.
To find the examples relevant to a specific target board, select the Download button in the
toolbar (C in the image below).
Figure 27 – Project Creation Buttons
Wait for the Atollic TrueSTORE Dialog box to open.
igure 28 – Atollic TrueSTORE
The Atollic TrueSTORE® requires an internet connection to work, as all
example projects are stored on our internet server.
Getting Started
55 | P a g e
Select the project(s) of interest and click Finish. The project is imported into the Active
Workspace and is immediately ready to be built and executed on the target board.
The whole process typically takes less than a minute.
USING AN EXISTING PROJECT
To use an existing project in Atollic TrueSTUDIO, double-click the .project file located
within the project folder to open it. This requires that Atollic TrueSTUDIO is associated to
be used for .project files.
Figure 29 – Selection of Existing Project File
Wait for Atollic TrueSTUDIO to start, as a result of double-clicking the .project file.
When clicking on the.project file the Project Import Converter will investigate the project
and if it is made for Atollic TrueSTUDIO it is directly imported. But if the project is made
from some other tool the Project Import Converter tries to identify if it is a known project
format and in such case will convert the project to an Atollic TrueSTUDIO project. There
are two sections which covers conversion of projects in this manual:
Importing AC6 Projects - conversion of STM32CubeMX (AC6) projects
Importing EWARM Projects – importing IAR EWARM projects
Please note that if the File Browser is configured not to display file extensions,
two nameless icons will appear in the file list, representing the .project and
the .cproject files. The use of files without a filename is an unfortunate
heritage from the ECLIPSE™ framework.
Atollic recommends that example projects downloaded from outside Atollic
TrueSTUDIO®, e.g. from STMicroelectronics, be located not too many levels
below the file system root. This is to avoid exceeding the Windows® path
length character limitations.
Getting Started
56 | P a g e
PREVENT “GCC NOT FOUND IN PATH” ERROR
Some old projects will issue an error in the Problems view saying Program “gcc” not found
in PATH. The error is caused when the project uses a deprecated discovery method
setting. The error can be removed by updating Window Preferences and Project
Properties settings.
1. Open Window, Preferences. In 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.
CREATING A STATIC LIBRARY
To create a Static Library-project select in the top menu File, New, C Project and in the
wizard-dialog that pops up select Static Library, Embedded C Library and Atollic ARM
Tools.
Figure 30 – Selection of Static Library Project
Press Next and select the device to be used. This will make the project build settings
correct. The project will then be built as an archive file with the name lib{project-
name}.a, as for an instance libMyLibrary.a
Getting Started
57 | P a g e
The GNU Binary Utilities command line tools are needed to create an archive file from an
object file without first creating a library project.
1. Open a Windows command prompter – cmd.exe
2. Move to the ARMTOOLS\bin folder in TrueSTUDIO installation folder
cd C:\%installdir%\ARMTools\bin
3. Run the archive command
arm-atollic-eabi-ar -r libStaticLibrary.a src\syscalls.o
HIDE INFORMATION IN A STATIC LIBRARY
The GNU Binary Utilities is included in the Atollic Toolchain and contains several programs.
The programs strip and objcopy takes parameters which removes information or
change information from the archive file.
For instance objcopy can be used if a library shall be exported and used by other people
and there is a need to hide information in the library such as function names or variables.
Below is an example on how to remove symbols and redefine some names in a library.
1. Open a Windows command prompter – cmd.exe
2. Move to the ARMTOOLS\bin folder in TrueSTUDIO installation folder
cd C:\%installdir%\ARMTools\bin
3. Run the objcopy command to change some information.
arm-atollic-eabi-objcopy --strip-unneeded --redefine-sym
myfunc=aaaa libTest.a libRenamed.a
This will open library libTest, remove all symbols that are not needed for relocation
processing and will also redefine myfunc to aaaa, and create a new library libRenamed.
Option
Information
-g
--strip-debug
Do not copy debugging symbols or sections from the source
file.
It is recommended to always place a library and the library code in a separate
project and never include them in the main-project.
If the library project should be recompiled at the same time as the project
that have included it, the library project should be added as a reference to
the other project. Select Project, Properties, C/C++ General, Paths and
Symbols and in References-tab select the library project.
For more information about Project referring, see Referring Project on page
119
Getting Started
58 | P a g e
--strip-unneeded
Strip all symbols that are not needed for relocation processing.
--redefine-sym old=new
Change the name of a symbol old, to new. This can be useful
when one is trying link two things together for which you
have no source, and there are name collisions.
Figure 31 – Examples of options to be used with objcopy
The GNU Binary Utilities Manual contains complete information on how to use the
included Binary Utilities software.
CREATING A MAKEFILE PROJECT FROM EXISTING
CODE
To import an existing makefile project select File, New and Makefile Project with Existing
Code.
Figure 32 – Create a Makefile Project from existing code
Enter the name of the new project and the location of the existing code.
Make sure to select <none> as the Toolchain for the Indexer Settings.
Getting Started
59 | P a g e
Figure 33 – Locate the code and select <none>
Then add the path to the existing toolchain to the system PATH environment variable.
That can be done from within Atollic TrueSTUDIO by select Project, Properties and then
C/C++ Build, Environment.
Locate the PATH variable in the list, select it and click Edit. If PATH can’t be located, click
Add and write PATH in the Name textbox.
Figure 34 – Edit the PATH variable
Getting Started
60 | P a g e
In the Value textbox, add the full path to the location of the toolchain, and also any other
location from where any executables in the makefile are located. Separate the paths with
a “;”.
Getting Started
61 | P a g e
IMPORTING EWARM PROJECTS
Atollic TrueSTUDIO v8.0 has a new Project Import Converter supporting IAR Embedded
Workbench® for ARM® (EWARM) projects. The new Project Import Converter
automatically updates EWARM projects to Atollic TrueSTUDIO format during import. After
an import the project will need manual updates in order to build correctly.
The Project Import Converter will not modify any source or project files for your original
EWARM project. It is however recommended that you backup or make a copy of the
original EWARM project since you most likely need to modify some of the source code
after the project has been imported to Atollic TrueSTUDIO.
A log file is created in the project folder during import. The name of this log file is
ProjectName_converter.log. This log file is placed into the same folder as the
.project file and can be investigated to find information about the conversion. The
ProjectName_converter.log. can for instance contain the following info.
Project: STM32F4-Discovery
Converter: IARProjectParser
Date: 20170421
Project needs GCC compatible startup code and linker script
USING THE PROJECT IMPORT CONVERTER
You must use Import Projects from Folder or Archive in Atollic TrueSTUDIO in order to
import EWARM projects into Atollic TrueSTUDIO.
IMPORT PROJECTS FROM FOLDER OR ARCHIVE
Use the following method to import one or many projects.
To open the Import wizard, select File, Import…
It is always recommended to make backups of the project files and source code
before converting projects.
Please note! The imported project will not be copied to the workspace. All
files in the project will be located at the original place and will be overwritten
when manual changes are made.
Getting Started
62 | P a g e
Figure 35 - Import Projects (EWARM)
In the Import wizard select Projects from Folder or Archive and press Next.
Getting Started
63 | P a g e
Figure 36 - Import Projects from Folder or Archive (EWARM)
The Import Projects from File System or Archive dialog is opened.
Getting Started
64 | P a g e
Figure 37 - Import Projects from File System (EWARM)
To see the Installed project configurators in the product, press the installed project
configurators link in the Import Projects from File System or Archive dialog.
Figure 38 - Display Installed Project Configurators (EWARM)
In the Import Projects from File System or Archive dialog browse to the folder containing
the project to be imported.
Getting Started
65 | P a g e
Select the project and make sure the checkbox Detect and configure project natures is
enabled otherwise the Project Import Converter will not be used. Press Finish to import
the project.
The project is now imported into the workspace. Please note that files included in the
project are not copied to the workspace, instead all files are linked to the workspace. This
means that the actual files will be updated in the original EWARM project. Press OK to use
the imported project.
If a folder which contains several projects are selected and Search for nested projects are
selected several projects will be seen in the dialog.
Figure 39 - Import Several Projects from File System (EWARM)
Eclipse cannot handle two projects with the same name in a workspace.
Therefore it may only be possible to import one project for a board into the
workspace. If an attempt is made to import a second project with the same
name, the import will be cancelled silently without any specific message.
Remove the first project from the workspace or create a new workspace if
another project shall be tested.
Getting Started
66 | P a g e
Many projects can then be imported in one step using this method. However, as
mentioned earlier, Eclipse requires different names to be used for each selected project. If
you run into this problem you can either rename the original EWARM project(s), or import
them into different Atollic TrueSTUDIO Workspaces.
Getting Started
67 | P a g e
BEFORE BUILDING IMPORTED PROJECT
Start by having a look in the generated log file that is included in your imported project.
This log file contains valuable information about the imported project, for example if there
were problems importing certain parts for EWARM.
Before we build we need to make some manual modifications to the source code and
make sure that the build options are set correctly. Below is a step-by-step list and we will
walk through this list and give examples on what typically needs to be done to get to a
project that builds in Atollic TrueSTUDIO.
There are essentially four parts of the migration process that you need to manually
update. Review and modify build options, modify assembler source code, add a linker
script file and watch out for tool specific code. These steps are described below and will in
most cases lead to a project that builds and functions correctly.
For more detailed information on how to migrate EWARM code and build
options, please see the IAR to Atollic Migration Guide, sections 3 and 4.
You can access the IAR to Atollic Migration Guide from Atollic TrueSTUDIO
Information Center.
Linker scripts, startup code and standard C/C++ libraries are tightly releated so
we must make sure to use either Atollic TrueSTUDIO or EWARM versions of
this code and scripts. It is strongly recommended to use Atollic TrueSTUDIO
versions since migrating all this from EWARM to Atollic TrueSTUDIO would be
very time consuming and prone to errors.
In the process of manullay updating our new Atollic TrueSTUDIO project we
will need startup code and a linker script file. We can easily get this if we
create a dummy project in our Atollic TrueSTUDIO Workspace. The only thing
you have to remember is to make sure that our dummy project is based on
the same ARM device as our original project.
Getting Started
68 | P a g e
STEP-BY-STEP CHECKLIST
The following steps are necessary to double-check in order to obtain a successful build.
1. Update Atollic TrueSTUDIO build options.
We should make sure that pre-defined symbols, include paths, FPU selection and
C/C++ language settings match the original project.
With one exception, all pre-defined symbols and search paths have already been
updated but you should make sure that options like FPU and C/C++ language
matches the original project. See table below for information on where to find
different build options.
Option
EWARM
TrueSTUDIO
FPU
General Options -> Target -> Floating point
settings
[Build tool] -> Taget -> Floating point / FPU
Note: [Build tool] is either Assembler, C Compiler,
C++ Compiler or C++ Linker. If you change the FPU
option then you should make the same change in
all four build tools.
C/C++ language
C/C++ Compiler -> Language 1
C Compiler -> General
C++ Compiler -> General
Note: The Atollic TrueSTUDIO project will by
default use the C compiler for C files and C++
compiler for C++ files.
Compiler defines
C/C++ Compiler -> Preprocessor -> Defined
Symbols
C Compiler -> Symbols -> Defined symbols
Compiler paths
Assembler -> Preprocessor -> Additional
include directories
C Compiler -> Directories -> Include path
Assembler defines
Assembler-> Preprocessor -> Defined
Symbols
Assembler -> Symbols -> Defined symbols
Assembler paths
C/C++ Compiler -> Preprocessor ->
Additional include directories
Assembler -> Directories -> Include path
Table 2 - EWARM vs TrueSTUDIO build options
The exception mentioned in the paragraph above is the CMSIS include path. In
EWARM you can specify to use CMSIS with the Use CMSIS option.
Getting Started
69 | P a g e
Figure 40 - EWARM CMSIS option
If Use CMSIS is checked then you will need to add a path to the CMSIS library to use in
your application. You can do this in the Directory part of the C Compiler settings. The path
to add is the absolute path the CMSIS/Include located in your EWARM installation,
typically something like this:
C:\Program Files (x86)\IAR Systems\Embedded Workbench x.x\arm\CMSIS\Include
In the Directory part of the C Compiler setting (see picture below), click the Add… icon ( )
to add your path.
Figure 41 - TrueSTUDIO compiler include paths
Getting Started
70 | P a g e
2. Modify or replace assembler source files.
The IAR assembler code syntax differs from what is used by Atollic TrueSTUDIO
so we will need to rewrite all assembler source code.
A special case is the startup file that comes with most projects and usually are
written in assembler code. Atollic TrueSTUDIO can generate this startup file for
you so that you do not have to write this code yourself. A recommended way is
to add an. iar extension to the startup file that was added to your imported
EWARM project. After this you can add a Atollic TrueSTUDIO startup file based
on the same ARM device to your imported project. If you created a dummy
project as described in the tip above, then you can simply drag-and-drop the
startup file from your dummy project to your imported project.
Once we have our new startup file we can compare it against the original startup
file. We can ignore the C/C++ initialization code since we will be using Atollic
TrueSTUDIO standard libraries and we are using an Atollic TrueSTUDIO
generated startup file now. What we should pay attention to is for example the
content of vector table and exception/interrupt handlers. For example, interrupt
handlers that was implemented and used in the original project must also be
implemented in our new startup file.
3. Add an Atollic TrueSTUDIO linker script file.
No linker script file is included so we need to add one that matches what we had
in our original EWARM project. A starting point is to have Atollic TrueSTUDIO
generate a linker script file that is based on the same ARM device as the original
project and add that linker script file to your imported project.
If you have your dummy project as described above, then you can simply, in
Atollic TrueSTUDIO Project Explorer, drag-and-drop that linker script file into the
root of your imported project.
We need to let the linker know which linker script file to use and this is done in
the General Settings of the C++ Linker.
Figure 42 - TrueSTUDIO linker script file option
Getting Started
71 | P a g e
You can either Browse to the linker script file, or if it is located in the root of your
imported project, type in the path.
In our example, we use STM32F4 so that path would be then “../stm32f4_flash.ld”.
With the linker script file in place we need to make sure that the memory
configuration in the linker script matches the configuration in the IAR .icf-file. Usually
most memory segments do not have to be located at a specific address, as long as it is
in the correct memory region. There are however applications that require that some
memory regions and entry labels are located at an absolute address. In this case you
should make sure your new application locate these regions/labels at the same
memory location. See the IAR to Atollic Migration Guide for more details on how this
can be done in Atollic TrueSTUDIO.
4. The last step before we try our build is to see if there are tool specific code in our
project, other than the startup file mentioned above.
Applications and libraries that comes from silicon vendors or 3’rd party
companies can contain source code, or libraries, that are created just for a
specific development toolchain. If this is the case in your project, then you
should see if you can find that corresponding code for TrueSTUDIO or GCC and
replace source code, libraries and include paths with the versions created for
TrueSTUDIO or possible GCC.
As an example, FreeRTOS have in their Source folder a sub-folder called
portable. Here you have source code ported to various development tool
vendors. An imported EWARM project using FreeRTOS would normally contain
files in the Source/portable/IAR folder. We should replace that code with
the code in Source/portable/GCC.
Once we have replaced this code we must also update our build tools include
paths so that any reference to Source/portable/IAR is changed to
Source/portable/GCC.
Intrinsic functions are also part of code that can differ from tool vendor to tool
vendor. Luckily CMSIS defines a set of intrinsic functions used for Cortex-M and
both EWARM and Atollic TrueSTUDIO follow CMSIS. In order to make sure that
we include declarations of CMSIS we should include CMSIS cmsis_gcc.h
instead of EWARM intrinsics.h in our source code.
For information about none CMSIS intrinsic functions and other ARM language
extensions used by, see ARM® C Language Extensions and CMSIS Core
documentation.
Getting Started
72 | P a g e
You are now ready to build the newly imported project and correct any remaining error
and check warnings. Depending on your project there might be more things that you
manually would need to modify in order to get to a Atollic TrueSTUDIO project that
matches the original EWARM project. For this reason, and for those who would not use
the EWARM import wizard, there is an IAR to Atollic Migration Guide available from Atollic
TrueSTUDIO Information Center with detailed information on how migrate a project from
EWARM to Atollic TrueSTUDIO.
COMMON BUILD ERRORS
This section will list and suggest solutions for the most common errors you would see after
building a project imported from EWARM to Atollic TrueSTUDIO.
fatal error: intrinsics.h: No such file or directory
EWARM intrinsics.h mostly contains declarations of various intrinsic functions. Most
the once used in a Cortex-M project are available in the CMSIS core_cmFunc.h and
cmsis_gcc.h header files. So, what we can do is to replace all occurrences of
intrinsics.h with for example cmsis_gcc.h.
undefined reference to ‘xyz'
Here ‘xyz’ can be a variable or a function that used in your application but not defined.
One way to find where this missing variable/function should be defined is to find the
definition in the original EWARM project.
There is a chance that the missing function could be defined as an intrinsic function that is
not included in our core_cmFunc.h or cmsis_gcc.h header files.
CONFIGURING THE DEBUGGER
After the imported project builds without errors we can test and debug the application
using any of the Atollic TrueSTUDIO supported debuggers. Before we download and debug
our application we need to configure the debugger and we do this in the Debug
Configuration dialog that we can access from the Run menu or the toolbar icon. (The
Unresolved issues? If still not successful after reading the IAR to Atollic
Migration Guide, please contact your local distributor or Atollic support for
assistance.
Getting Started
73 | P a g e
same dialog will open if we attempt to start a debug session before we have created our
debug configuration.)
In the Main tab, we need to make sure that the Name of the ElfDwarf file is correct as well
as the Application and the Project selected.
Figure 43 - Edit Debug Configuration
After this is done we select the Debugger tab. Here we first of all select which Debug
probe we will be using. Once we have selected our debug probe we can modify our GDB
Connection, select debug interface, add trace (if we have that available) and more.
Figure 44 - Selecting Debug Probe
Getting Started
74 | P a g e
If you like to get more control over the download and debug session, then you can do this
in the Startup Scripts tab. Here you can add commands to for example load additional files
or debug information, chose to download without starting a debug session, stop at the
application entry point or run to main (or any global label in your application) and much
more. For more information see The Startup Script chapter at page 227.
Now we are ready to download and test our application and we can do this by clicking on
OK or Debug (depending on how you started the Debug Configuration dialog).
For more detailed information on migrating EWARM projects, see the IAR to Atollic
TrueSTUDIO migration guide.
If you are uncertain on how to configure your debugger after selecting the
debug probe, then try the default vaules.
After you select a debug probe, Atollic TrueSTUDIO will default to a debug
configuration that works for most projects that use that particular debug
probe.
In case the default values does not work, check your debug settings in EWARM
and apply the same values to your debug configuration in Atollic TrueSTUDIO.
Getting Started
75 | P a g e
IMPORTING AC6 PROJECTS
As of Atollic TrueSTUDIO v7.1, there is a new Project Import Converter supporting System
Workbench for STM32 (AC6, SW4STM32) projects. Such projects can be found in
STMicroelectronics software such as STM32Cube Firmware Package projects.
The new Project Import Converter automatically updates System Workbench for STM32
(AC6, SW4STM32) projects to Atollic TrueSTUDIO format during import. After an import
the project shall build and it shall be possible to debug the project in Atollic TrueSTUDIO.
In some cases it may be needed to do some manual target or build setting changes.
The Project Import Converter makes it easy to import, build and debug ready-made
projects located in the STMicrolectronics STM32Cube Firmware Package projects even if
STMicrolelectronics only have prepared SW4STM32 projects in the examples package.
Example from STM32CubeF7:
G:ST\STM32Cube\en.stm32cubef7\STM32Cube_FW_F7_V1.5.0\Projects\STM32F
769I-
Discovery\Examples\DMA\DMA_FLASHToRAM\SW4STM32\STM32769I_DISCOVERY
The Project Import Converter will update the imported project but it will make backup
copies of the .project and .cproject files before these are changed. See the section
Restoring Converted Projects at page 82 for information on how to restore the project if it
shall be used with AC6 later.
During import a log file is created in the project folder. The name of this log file is
ProjectName_converter.log. This log file is placed into the same folder as the
.project file and can be investigated to find information about the conversion. The
ProjectName_converter.log. can for instance contain the following info. This is
normal behavior.
Project: STM32F4-Discovery
Converter: AC6 project converter
Date: 20170127
USING THE PROJECT IMPORT CONVERTER
The Project Import Converter can be started in two ways:
It is always recommended to take manual backups of the project files and
source code before converting projects. When using STM32Cube Firmware
Package projects it could be possible to reinstall the complete package.
Getting Started
76 | P a g e
1. Use Import Projects from Folder or Archive in Atollic TrueSTUDIO.
2. Double-click the .project file in Windows File Explorer.
These two different ways of using the Project Import Converter is described in next
sections.
IMPORT PROJECTS FROM FOLDER OR ARCHIVE
Use the following method to import one or many projects.
To open the Import wizard select File, Import…
Figure 45 – Import Projects
Please note! The imported project will not be copied to the workspace. All
files in the project will be located at the original place and will be overwritten
when changes are made.
Getting Started
77 | P a g e
In the Import wizard select Projects from Folder or Archive and press Next.
Figure 46 – Import Projects from Folder or Archive
The Import Projects from File System or Archive dialog is opened.
Getting Started
78 | P a g e
Figure 47 – Import Projects from File System
To see the Installed project configurators in the product press the installed project
configurators link in the Import Projects from File System or Archive dialog.
Figure 48 – Display Installed Project Configurators
In the Import Projects from File System or Archive dialog browse to the folder containing
the project to be imported.
Getting Started
79 | P a g e
Select the project and make sure the checkbox Detect and configure project natures is
enabled otherwise the Project Import Converter will not be used. Press Finish to import
the project.
The following dialog can be displayed if the Project Import Converter prepares to convert
the project.
Figure 49 – Project Converter Conversion Information
Press OK to import the project with conversion.
Figure 50 – Project Imported Information
The project is now imported into the workspace. Please note that files included in the
project are not copied to the workspace, instead all files are linked to the workspace. This
means that the actual files will be updated in the STM32Cube package in this case. Press
OK to use the imported project.
In the Import as column in the Import Projects from File System or Archive
dialog it displays TrueSTUDIO project or TrueSTUDIO project (Converted
from AC6) which informs how the project will be imported.
Do not try to import lines where no information is available in the Import as
column.
The Import as column may also display Folder already imported as project
and in such cases it will not be possible to import it again into current
workspace.
Some examples may use identical project names for projects aimed at
different boards. Eclipse cannot handle two ormore projects with the same
name in a workspace. Therefor, it may only be possible to import one project
for a board into the workspace. If an attempt to import a second project with
the same name is made, the import will be cancelled silently without any
specific message. To import a second project, remove the first project from
the workspace or create a new workspace.
Getting Started
80 | P a g e
If a folder which contains several projects are selected and Search for nested projects are
selected several projects will be seen in the dialog.
Figure 51 – Import Several Projects from File System
Many projects can then be imported in one step using this method. However, as
mentioned earlier the STM32Cube examples uses the same project name for each board
and as Eclipse requires different names to be used only one of the selected project in such
case will be imported.
IMPORT PROJECTS USING DOUBLE-CLICK
When using double-click on the .project file in Windows File Explorer to import an
STM32CubeMX (AC6, SW4STM32) project follow this guide.
After double-click on .project file, Atollic TrueSTUDIO will be opened if it is not already
started, and the following dialog is displayed.
Figure 52 – Project Converter Information
Getting Started
81 | P a g e
Press OK to convert the project and import it into the workspace and a new dialog is
opened after a successful conversion.
Figure 53 – Project Imported Information
The project is now imported into the workspace. Press OK to use the imported project.
Please note that files included in the project are not copied to the workspace, instead all
files are linked to the workspace. This means that the actual files will be updated in the
STM32Cube package in this case.
USING IMPORTED PROJECTS
When a STM32CubeMX (AC6, SW4STM32) project has been imported and is converted to
Atollic TrueSTUDIO project there could be some updates needed. But in most cases it
should work to build and debug the project directly.
The first step to use the project in Atollic TrueSTUDIO could be to make a build and verify
that it builds without errors. After the project has been built a debug session can be
started.
First time a debug session is started the Debug Configurations dialog will be opened. Make
sure to configure to use correct Debug probe, e.g. ST-LINK or SEGGER J-LINK, and Interface
SWD or JTAG according to hardware requirements. If SWV shall be used then make sure to
set the Core Clock to the speed of the clock that will used by the target when debugging
the project.
Some examples may use identical project names for projects aimed at
different boards. Eclipse cannot handle two ormore projects with the same
name in a workspace. Therefor, it may only be possible to import one project
for a board into the workspace. If an attempt to import a second project with
the same name is made, the import will be cancelled silently without any
specific message. To import a second project, remove the first project from
the workspace or create a new workspace.
Getting Started
82 | P a g e
Figure 54 – Edit Debugger Configuration
When correct setting for debugging is set make sure the debugger probe and board is
connected and start a debug session by pressing the OK button.
RESTORING CONVERTED PROJECTS
As mentioned earlier the Project Import Converter made copy of the .project and
.cproject files when the project was coverted. The original .project file was copied
to .project_org file. The original .cproject file was copied to .cproject_org
file.
One way to restore the project and use it with AC6 again is to replace these project files
with the original files. Open a command prompt and rename the files. (Note! The filename
can not be renamed using Windows File Explorer as this program does not allow to
rename a file to start with “.” .)
E.g. In a Command Prompt window use the move command to rename the files
1. Rename the converted projet files if you these files shall be kept.
move .project .project_ts
move.cproject .cproject_ts
2. Replace and use the original files
move .project_org .project
move.cproject_org .cproject
Getting Started
83 | P a g e
The project should now be ready to be opened with System Workbench for STM32 (AC6,
SW4STM32) again.
Getting Started
84 | P a g e
CONFIGURING THE PROJECT’S BUILD
SETTINGS
Managed Mode projects can be configured using dialog boxes. Unmanaged Mode projects
require a manually maintained makefile.
Atollic TrueSTUDIO provides extensive GUI controls for configuration of command line tool
options using a simple point-and-click mechanism.
To configure a Managed Mode project, perform the following steps:
1. Select a project in Project Explorer view.
2. Click on the Build settings toolbar button or select Project, Build
Settings….
Figure 55 – Build Settings Toolbar Button
Figure 56 – Build Settings Menu Selection
3. The project Properties dialog box is displayed.
4. Expand the C/C++ Build item in the tree in the left column. Then select the
Settings item to display the build Settings panel for the active Build
Configuration.
How a project is built is saved in a Build Configuration. Each configuration has
many Build settings.
Getting Started
85 | P a g e
Figure 57 - Project Properties Dialog Box
5. Select panels as desired and configure the command line tool options using
the GUI controls.
Advanced users may wish to enter command line options manually. This can be
done in the Miscellaneous panel for any tool.
Getting Started
86 | P a g e
Figure 58 – Tool Settings, Miscellaneous Options
6. Some project build settings are relevant for both Managed Mode projects
and Unmanaged Mode projects. For instance the selected microcontroller
or evaluation board may affect both the options to the compiler during a
Managed Mode build, and also how additional components in Atollic
TrueSTUDIO, for instance the SFR view, and debugger, will behave.
Project build settings relevant for both Managed Mode projects and
Unmanaged Mode projects are collected in the Target Settings panel.
Getting Started
87 | P a g e
Figure 59 – Target Settings Dialog Box
Any changes made here will be reflected in ALL build configurations for this
project.
Changing to a different hardware target, will cause a new linker script file
(.ld) to be generated, with FLASH and RAM settings adjusted to the
memory size of the new target device. See Generate a New Linker Script,
page 131 for more information.
However, libraries, header files, etc. will not be generated automatically for
the new target! These must be added manually to the project.
If the target device needs to be changed, Atollic recommends generating a
new project for that target. Copy the source code from the current project to
the new project.
Getting Started
88 | P a g e
7. Click the OK button to accept the new settings. This will change the
settings for the selected Build Configuration.
BUILD CONFIGURATIONS
A Build Configuration stores how a project is built. Each Build configuration has several
Build Settings. Each Build Setting can be individually set for each Build Configuration.
A Project can have an unlimited number of Build Configurations. This is a very powerful
tool to be able to quickly build a project in different ways, such as with different
optimization levels, tool chain versions and even different build behavior can be set. It is
even possible to have a project be built as both a library and an executable with two
different Build Configurations.
A project created in Atollic TrueSTUDIO contains by default two Build configurations, the
Debug and the Release configuration. In these configurations there are two build settings
that differentiate them. The Debug configuration is built with debugging information and
no optimization level. The Release configuration is optimized for small code size and with
no debugging information.
Settings done in the project will usually only affect the current configuration. However
what Build Configuration that is affected can be selected in the dropdown list located at
the top of the panel.
Figure 60 – Select Affected Build Configuration
The Build Analyzer view can be used to analyse the size and location of a
program in detail. Please read more about the Build Analyzer at page 264
Getting Started
89 | P a g e
This does not change what Build Configuration is used when building. To change that the
Active Configuration needs to be changed, see Changing Active Build Configuration on
page 90.
When building is done, the build-result such as an .elf-file, is stored in a folder with the
same name as the Build Configuration. This makes it easy to locate. For this reason it is
also a good idea to not use white space in the name of a Build Configuration.
CREATE A NEW BUILD CONFIGURATION FOR RELEASE
When most of the development is done and it is time to switching to the Release
configuration, there might be a lot of settings done under the development process that is
missing in the Release configuration.
To make sure that the Release configuration contains all necessary settings, it may be
easiest to create a new Release configuration, copy the settings from the Debug
configuration, and then just change the debug information level and optimization level.
1. Select the project in the Project Explorer and right click Project, Manage Build
Configurations…
2. Optional - Delete the old Release configuration or the configuration that does not have
all the used settings
3. Click New…
4. Name the new configuration. E.g. NewRelease. It is recommended not to use any
whitespaces in the name of the Build Configuration.
5. Select to copy settings from the existing Debug configuration.
6. Click OK.
7. Select the new NewRelease configuration and click Set Active. This determines what
Build Configuration is to be used when building the project.
8. Close the dialog by clicking the OK button.
Next, open up Project, Properties, and navigate to C/C++ Build, Settings, Tool Settings. In
the Debugging node, for the Assembler and C/C++ Compiler, set the debug level to none.
Then select an optimization level in the Optimization node for the C/C++ Compiler.
The build output folder will be named as the active build configuration. So when the
project is built, the .elf file will be located in the NewRelease folder for the new Release
configuration.
Building all Build Configurations
It is easy to build all Build Configurations at the same time.
Getting Started
90 | P a g e
For another example see Create a New Build Configuration For an Old Toolchain Version on
page 101.
CHANGING ACTIVE BUILD CONFIGURATION
To change what Build Configuration is used to build, right click the project and select Build
Configuration, Set Active and select the preferred Build Configuration
Figure 61 – Change active Build Configuration
SOURCE FOLDERS
A folder within a project can be recognized as a source folder if it is annotated with a small
C-icon in the Project Explorer.
Getting Started
91 | P a g e
For Atollic TrueSTUDIO to be able to recognize changes in a source file, it needs to be
located in a source folder. Either as a resource located within the project or linked from
some other location.
Figure 62 – Source Folders
To make Atollic TrueSTUDIO handle an existing folder as a new source folder do the
following steps:
1. Select the project and in the top menu select Project, Properties.
2. In the Properties panel open C/C++ General, Paths and Symbols and then the Source
Location tab.
Figure 63 – Source Location Tab
Getting Started
92 | P a g e
3. Click Add Folders… and select the new source location.
Figure 64 – Folder Selection Tab
There should then be a new Source folder in the project.
Figure 65 – New Source Folder
Getting Started
93 | P a g e
INCLUDE LIBRARIES
This guide is for including libraries into Atollic TrueSTUDIO projects. For information how
to refer to a library created in an existing project, see Referring Project on page 119. On
page 155 there is a guide for how to Update CMSIS Math library.
In order to include a library into a project right-click on the project where the library will
be included; select Properties, C/C++ Build and Settings. Then select the Tool Settings-tab,
select C Linker, Libraries.
Figure 66 – Include a Library
Getting Started
94 | P a g e
3. In the Libraries list add the name of the library - not the path! The name is the
filename without “lib” prefix and without the file extension (.a). It is important
not to include those parts of the name. This is a GCC convention.
Example: For a library-file named libMyLibrary.a add the name MyLibrary.
If by any chance the library’s name don’t confirm to the GCC convention, the full
name to the library can be entered, preceded by a colon “:”.
Example: For a library-file name STemWin524b_CM4_GCC.a add the name
:STemWin524b_CM4_GCC.a
4. In the Library Paths list, set the path to where the library is located. Do not
include the name of the library in the path.
Example: ../../MyLibrary/Debug, this is the path to the archive file of the
library project myLibrary residing in the same workspace as the application
project.
5. The source folder for the header files should also be added to the Include paths.
Do that by selecting Project, Properties, Tool Settings, C Compiler, Directories
and press the Add… button. Then add the path to the source folder for the
header files in the library.
Figure 67 – Add the Library to the Include Paths
Getting Started
95 | P a g e
The included libraries can also be found by right-clicking the project and select C/C++
General and open the Libraries-tab and the Libraries Path-tab.
See Referring Project on page 119 for more information if a project is referring to another
project, a library or a normal project.
COMPILER SETTINGS
All the settings for the compiler can be found by open the Build Configuration with the
Build Settings Toolbar button.
Then select the Build Configuration that should be changed and the Tool Setting tab.
Select the C Compiler tool node.
The compilers command line command and options are then displayed.
Figure 68 – Compiler Settings
Libraries added by include paths are considered static in that way that they
are provided by external parties. The .h files are not rescanned as the content
should not have changed for external header files.
If external libraries is to be treated as normal source folder, the folders must
also be added as source-folders to the project.
This is particularly important when using tools that generates external code,
such as STM32CubeMX
Getting Started
96 | P a g e
The different nodes below the C Compiler can then be selected to configure how the
compiling is done. More about these options are found in the following pages in this
chapter.
The options can also be manually changed by editing the All options field.
More about all options are found in the Compiler manual found in the Information Center
as the C/C++ Compiler link.
More information about compiler settings can be found in the Compiler manual. The
manual can be found from the Information Center view.
Figure 69 – Finding the C/C++ Manual in Information Center
SET THE COMPILER TO USE THE C99-STANDARD
User can set the compiler to use the C99 standard by adding the '-std=c99' switch to the c
compiler tool.
Do this by selecting the General node.
From the dropdown menu select C99.
See also section Add or Remove Folder to Include Path on page 153 for
information on an easy way to update the include path.
Getting Started
97 | P a g e
This change will also be reflected in the editor’s behavior.
Read more about the status of the C99 implementation here http://gcc.gnu.org/gcc-
4.5/c99status.html.
Other C standards can also be set with the same drop down menu.
COMPILER OPTIMIZATION
The GNU C/C++ compiler (and hence Atollic TrueSTUDIO) have 6 levels of compiler
optimization; -O0 for no optimization up to -O3 for full optimization. There is one level for
size optimization (-Os) which is commonly required in embedded projects and another
level for speed optimization (-Ofast).
Also available is a level for turning on optimizations that won’t interfere with the debug
experience (-Og).
To enable compiler optimization in the commercial versions of Atollic TrueSTUDIO, select
optimization option from the dropdown list in the C/C++ Build, Settings, Tool Settings, C
compiler, Optimization panel in the Project Properties dialog box. The optimization
options can also be set per file in the File Properties dialog box, found by right-clicking an
individual file.
Figure 70 – Compiler Optimization Settings for a Project
Getting Started
98 | P a g e
Figure 71 – Compiler Optimization Settings for a File
The optimization setting is per Build Configuration. Per default the Debug configuration is
optimized with –O0 and the Release configuration has -Os.
In addition to the simplified optimization settings mentioned above, about 100
optimization settings can be set individually using various command line options and
#pragmas. Consult the Compiler manual for details. It can be found from the Information
Center view.
To define a specific optimization level on a block of code, use the optimize attribute on the
block:
void __attribute__((optimize("O1"))) myFunc(unsigned char
data) {
// The code the needs to have the –O1 optimizing
}
LINK TIME OPTIMIZATION (LTO)
Using LTO means that when compiling individual files the output is not object code, but
instead an intermediate internal format between the original source code and assembly
code. This means that when the linker is doing the final link it has access to more
optimizable information about each file and a globally optimized program is generated.
However, because of the way this works also means that in order to use this feature fully it
is necessary to provide the linker tool with some extra information that usually has only
been supplied to the compiler tool. This extra information can be any optional extra flag
that you might have added to the compiler process.
Getting Started
99 | P a g e
In most cases however it will only be required to add the following flags to the Linker tool
Miscellaneous field
-flto -ffunction-sections -fdata-sections -Os -g
Figure 72 – Linker LTO Settings for a Project
The optimization flag (-Os) should have the same value as the optimization flag for the
compiler, see page 93 for more information.
Please note! -g shall be used to get extra debug information needed when debugging the
program.
It is also required to change the Compiler tool settings and there add the –flto flag to the
miscellaneous field.
Getting Started
100 | P a g e
Figure 73 – Linker LTO Settings for a Project
CHANGING TOOLCHAIN VERSION
When upgrading to a new version of Atollic TrueSTUDIO it is a good idea to not
immediately also switch the tool chain.
To change to an older version of the Atollic ARM Tools toolchain or the PC toolchain click
on the Build Settings toolbar button.
Figure 74 – Build Settings Toolbar Button
Select the Toolchain Version tab.
Getting Started
101 | P a g e
Figure 75 – Tool Chain Version tab
There are three options available here:
Default – This option will use the tool chain in the currently running installation of
TrueSTUDIO.
Fixed TrueSTUDIO version – if there are other versions of Atollic TrueSTUDIO
installed on the computer, this option allows the user to select from what version
the tool chain will be selected. It will then select that version even if the
installation folder for the selected version is changed.
Fixed toolchain location – Used to point to a specific folder.
These setting are saved individually for each Project’s Build Configuration. That way it is
possible to have different Build Configurations using different toolchain versions. This way
a quick regression test can be created.
CREATE A NEW BUILD CONFIGURATION FOR AN OLD
TOOLCHAIN VERSION
To create a new Build Configuration for an older version of the toolchain, do the following:
1. Right click the project and select Build Configurations, Manage…
When working with a version control system in a team, the second option is
strongly recommended for a project. That way all developers will use the same
toolchain even if using different versions of Atollic TrueSTUDIO.
Getting Started
102 | P a g e
Figure 76 – Manage the Build Configurations
2. In the panel select New… to create a new Build Configuration.
3. Enter a good name for the new Build Configuration. Use one word, such as
OldToolChain, without white space and press OK and OK again in the Manage
Configuration panel.
Getting Started
103 | P a g e
Figure 77 – Create New Configuration
4. In the Toolchain Version tab it is now possible to set the Default version of the tool
chain for the normal Debug Build Configuration and a Fixed TrueSTUDIO version for
the OldToolChain Build Configuration.
Figure 78 – Old Tool Chain Version for the New Build Configuration
CONVERT .ELF-FILE TO ANOTHER OUTPUT FORMAT
To convert your program to another output format, do the following:
1. Open up Project, Properties, C/C++ Build, Settings, Tool Settings, Other, Output
format
2. Check the box Convert build output and choose a format in the dropdown menu.
Getting Started
104 | P a g e
Figure 79 – Output Format Selection
3. Build the project
The converted output will be located in the output directory associated with the currently
active Build Configuration, typically Debug/Release directory.
Other supported file formats are: Binary, Motorola S-record, Motorola S-record with
symbols, IAR Simple Code and Verilog Hex Dump.
To manually create .hex, .srec and .bin-files, add Post-build steps in the Build Step tab:
arm-atollic-eabi-objcopy -O binary myfile.elf myfile.bin
arm-atollic-eabi-objcopy -O ihex myfile.elf myfile.hex
arm-atollic-eabi-objcopy -O srec myfile.elf myfile.srec
Conversion to the IAR Simple Code File Format can only be made using the
dropdown menu in Atollic TrueSTUDIO. The IAR Simple Code File Format can
not be generated with
objcopy
.
Getting Started
105 | P a g e
TEMPORARY ASSEMBLY FILE
Save the temporary assembly file by adding the -save-temps flag to the compiler.
In the menu select Project, Properties, C/C++ build, Settings.
Open the Tool Settings tab.
Then C Compiler, Miscellaneous. Add –save-temps and rebuild the project.
The assembler file will be located in the build output directory and will be called:
FILENAME.s
There will also be a FILENAME.i that is the preprocessed c-code. That is the code as it will
look after the preprocessor but before the code is compiled. If there might be a problem
with some #define then looking into this file is a good idea.
Getting Started
106 | P a g e
BUILDING THE PROJECT
To start a Build, click on the Build toolbar button. Only files that are changed since the last
build, or that depends on changed files or settings, will be built.
Figure 80 - Build Toolbar Button
The Build result is displayed in the Console window. At the end are the code size figures.
For example:
Print size information
text data bss dec hex filename
66232 2808 4004 73044 11d54 GSM lib cb1.elf
Print size information done
The values are organized according to memory sections and areas. Per default, the linker
arranges the memory into the sections text, data, bss. More information is found
in the linker script file (.ld).
The dec and hex figures express the size of the .elf file. Below the filename header
is the name of the .elf file.
The Build Analyzer view can be used to analyse the size and location of a
program in detail. Please read more about the Build Analyzer at page 264
Getting Started
107 | P a g e
ENABLE PARALLEL BUILD
Parallel Build is when more than one thread is used at the same time to compile and build
the code. Most of the times it will reduce the build time significantly. The optimal
number of threads to use is usually equal to the number of CPU cores on the computer.
To enable Parallel Build select Project, Properties and in the Properties panel select C/C++
Build. Open the Behavior tab and Enable Parallel Build.
Figure 81 – Parallel Build
ENABLE BUILD ON SAVE
To enable Atollic TrueSTUDIO to automatically build a file when it is saved, the Build
Behavior setting needs to be changed.
In the top menu select Project, Properties and in the Properties panel select C/C++ Build.
Open the Behavior tab and enable Build on resource save.
Getting Started
108 | P a g e
Figure 82 – Build on Save
REBUILD PROJECT
To force a Rebuild of all files included in the project, click on the Rebuild toolbar button or
select the menu command Project, Rebuild Project.
Figure 83 – Rebuild Toolbar Button
Getting Started
109 | P a g e
Figure 84 – Rebuild Active Configuration Menu Selection
BUILD ALL PROJECTS
To build all open projects in a workspace, select Project in the top menu and then Build All or
press Ctrl+B. This will build the active Build Configuration for each project.
Figure 85 – Build All Projects
BUILD ALL BUILD CONFIGURATIONS
To build all Build Configurations for a project, right-click the project and in the context menu select
Build Configurations and Build All.
Getting Started
110 | P a g e
Figure 86 – Build All Build Configurations
HEADLESS BUILD
This is intended for Managed Mode projects that are to be integrated into script-
controlled builds, such as nightly builds on build servers for continuous integration process
methods, etc. It is possible to start a build process from the operating system command
line also for Managed Mode projects. The IDE GUI is never displayed in this case, and the
user does not have to interact manually with the IDE at all.
The IDE installation folder, e.g. C:\Program Files (x86)\Atollic\TrueSTUDIO for
STM32 9.0.0\ide, contains the file headless.bat, which is used for running
headless builds.
Getting Started
111 | P a g e
Option
Description
-data {[uri:/]/path/to/workspace}
This option is always required and selects which workspace to
use for the headless build. If the selected workspace folder
does not exist, it will be created automatically.
-import {[uri:/]/path/to/project}
Optionally import a project into the workspace before the
headless build starts. Please note that importing into a
workspace is not the same as copying the files to the
workspace. It tells Atollic TrueSTUDIO that there exists new
files in a workspace.
-importAll {[uri:/]/path/to/projectTreeURI}
Optionally import several projects into the workspace before
the headless build starts.
-build {projname_reg_exp}
Build all build configurations (see page 88 for more
information) of the selected project. If the project name
contains wildcards (? and *), all matching projects will be
built.
-build {projname_reg_exp/configname}
Build the selected project using only the selected build
configuration. If the project name contains wildcards (? and
*), all matching projects will be built.
This option can be used several times. That way libraries can
be built before the project depending on them.
-build all
Build all configurations of all projects in the selected
workspace.
-cleanBuild {projname_reg_exp}
Rebuild all build configurations of the selected project. If the
project name contains wildcards (? and *), all matching
projects will be rebuilt.
-cleanBuild
{projname_reg_exp/configname}
Rebuild the selected build configuration of the selected
project. If the project name contains wildcards (? and *), all
matching projects will be rebuilt.
-cleanBuild all
Rebuild all build configurations of all projects in the selected
workspace.
-I {include_path}
Additional include path to add to tools.
-include {include_file}
Additional include file to pass to tools.
-D {prepoc_define}
Additional preprocessor defines to pass to the tools.
-E {var=value}
Replace/add value to environment variable when running all
tools.
-Ea {var=value}
Append value to environment variable when running all tools.
-Ep {var=value}
Append value to environment variable when running all tools.
Getting Started
112 | P a g e
Option
Description
-Er {var}
Remove/unset the given environment variable.
An option argument is parsed as a string, a comma separated list of strings, or a boolean,
depending on the type of option.
Example:
headless.bat -data "C:\Users\User\headless\buildWS" -
importAll "C:\Users\User\headless\checkOutDir" -cleanBuild
all > "C:\Users\User\headless\build.log"
This command will create a temporary workspace folder buildWS for this build. It will
import all projects from the folder checkOutDir (not copy, just import to the temporary
workspace) and build all build configurations defined in each project. The result will be
stored in the folder checkOutDir. A log file will be created in the folder headless.
Doing an import is vital if ether a temporary workspace is used or a batch-script is used
and the project to build is checked out from a repository before the build. This is because
Atollic TrueSTUDIO needs to know about the files before using them to build.
LOGGING
To enable project build logging, right-click on the project and select Properties. Then
select C/C++ Build, Loggings.
The logs can then by default be found in
WORKSPACE_PATH\.metadata\.plugins\org.eclipse.cdt.ui\MyProjec
t.build.log
A global build log for all projects in a workspace can be enabled by selecting Window,
Preferences