IAR C-SPY Debugging Guide - FTP Directory Listing - IAR Systems

IAR Embedded Workbench®
C-SPY® Debugging Guide
for the STMicroelectronics
STM8 microcontroller Family
UCSSTM8-2
COPYRIGHT NOTICE
© 2013-2014 IAR Systems AB.
No part of this document may be reproduced without the prior written consent of IAR
Systems AB. The software described in this document is furnished under a license and
may only be used or copied in accordance with the terms of such a license.
DISCLAIMER
The information in this document is subject to change without notice and does not
represent a commitment on any part of IAR Systems. While the information contained
herein is assumed to be accurate, IAR Systems assumes no responsibility for any errors
or omissions.
In no event shall IAR Systems, its employees, its contractors, or the authors of this
document be liable for special, direct, indirect, or consequential damage, losses, costs,
charges, claims, demands, claim for lost profits, fees, or expenses of any nature or kind.
TRADEMARKS
IAR Systems, IAR Embedded Workbench, C-SPY, visualSTATE, The Code to Success,
IAR KickStart Kit, I-jet, I-scope, IAR, and the logotype of IAR Systems are trademarks
or registered trademarks owned by IAR Systems AB.
Microsoft and Windows are registered trademarks of Microsoft Corporation.
STMicroelectronics is a registered trademark of STMicroelectronics Corporation.
STM8 is a trademark of STMicroelectronics Corporation.
Adobe and Acrobat Reader are registered trademarks of Adobe Systems Incorporated.
All other product names are trademarks or registered trademarks of their respective
owners.
EDITION NOTICE
Second edition: November 2014
Part number: UCSSTM8-2
This guide applies to version 2.x of IAR Embedded Workbench® for the
STMicroelectronics STM8 microcontroller family.
Internal reference: Hom7.1, IMAE.
C-SPY® Debugging Guide
2
for STM8
AFE1_AFE2-1:1
Brief contents
Brief contents
Tables
...................................................................................................................... 17
Preface
.................................................................................................................... 19
Part 1. Basic debugging
The IAR C-SPY Debugger
................................................................ 25
........................................................................... 27
Getting started using C-SPY
....................................................................... 37
Executing your application
........................................................................... 55
Variables and expressions
............................................................................ 73
Breakpoints
........................................................................................................ 107
Memory and registers
.................................................................................. 133
Part 2. Analyzing your application ................................ 163
Trace ...................................................................................................................... 165
Profiling
................................................................................................................ 189
Code coverage
................................................................................................. 199
Part 3. Advanced debugging ................................................. 203
Interrupts
............................................................................................................ 205
C-SPY macros
................................................................................................. 225
The C-SPY command line utility—cspybat
....................................... 279
Part 4. Additional reference information
............. 291
Debugger options ........................................................................................... 293
Additional information on C-SPY drivers
.......................................... 301
3
AFE1_AFE2-1:1
Index
C-SPY® Debugging Guide
4
for STM8
AFE1_AFE2-1:1
..................................................................................................................... 311
Contents
Contents
Tables
...................................................................................................................... 17
Preface
.................................................................................................................... 19
Who should read this guide ............................................................... 19
Required knowledge .......................................................................... 19
What this guide contains ..................................................................... 19
Part 1. Basic debugging ..................................................................... 19
Part 2. Analyzing your application .................................................... 20
Part 3. Advanced debugging .............................................................. 20
Part 4. Additional reference information ........................................... 20
Other documentation ........................................................................... 20
User and reference guides .................................................................. 21
The online help system ...................................................................... 21
Web sites ............................................................................................ 22
Document conventions ........................................................................ 22
Typographic conventions ................................................................... 22
Naming conventions .......................................................................... 23
Part 1. Basic debugging
The IAR C-SPY Debugger
................................................................ 25
........................................................................... 27
Introduction to C-SPY .......................................................................... 27
An integrated environment ................................................................. 27
General C-SPY debugger features ..................................................... 28
RTOS awareness ................................................................................ 29
Debugger concepts ................................................................................ 30
C-SPY and target systems .................................................................. 30
The debugger ...................................................................................... 31
The target system ............................................................................... 31
The application ................................................................................... 31
C-SPY debugger systems ................................................................... 31
The ROM-monitor program ............................................................... 32
5
AFE1_AFE2-1:1
Third-party debuggers ........................................................................ 32
C-SPY plugin modules ....................................................................... 32
C-SPY drivers overview ....................................................................... 33
Differences between the C-SPY drivers ........................................... 33
The IAR C-SPY Simulator .................................................................. 34
The C-SPY hardware debugger drivers ........................................ 34
Communication overview .................................................................. 35
Getting started using C-SPY
....................................................................... 37
Setting up C-SPY .................................................................................... 37
Setting up for debugging .................................................................... 37
Executing from reset .......................................................................... 38
Using a setup macro file ..................................................................... 38
Selecting a device description file ..................................................... 38
Loading plugin modules ..................................................................... 39
Starting C-SPY ......................................................................................... 39
Starting a debug session ..................................................................... 39
Loading executable files built outside of the IDE .............................. 40
Starting a debug session with source files missing ............................ 40
Loading multiple images ................................................................... 41
Adapting for target hardware ........................................................... 42
Modifying a device description file ................................................... 42
Initializing target hardware before C-SPY starts ............................... 42
Running example projects .................................................................. 43
Running an example project .............................................................. 43
Reference information on starting C-SPY ................................... 45
C-SPY Debugger main window ......................................................... 45
Images window .................................................................................. 50
Get Alternative File dialog box .......................................................... 51
Option Bytes window ......................................................................... 52
Executing your application
........................................................................... 55
Introduction to application execution ........................................... 55
Briefly about application execution ................................................... 55
Source and disassembly mode debugging ......................................... 55
C-SPY® Debugging Guide
6
for STM8
AFE1_AFE2-1:1
Contents
Single stepping ................................................................................... 56
Stepping speed ................................................................................... 58
Running the application ..................................................................... 59
Highlighting ....................................................................................... 60
Call stack information ........................................................................ 60
Terminal input and output .................................................................. 61
Debug logging .................................................................................... 61
Reference information on application execution ..................... 62
Disassembly window ......................................................................... 62
Call Stack window ............................................................................. 66
Terminal I/O window ......................................................................... 68
Terminal I/O Log File dialog box ...................................................... 69
Debug Log window ............................................................................ 70
Log File dialog box ............................................................................ 71
Report Assert dialog box .................................................................... 72
Autostep settings dialog box .............................................................. 72
Variables and expressions
............................................................................ 73
Introduction to working with variables and expressions ...... 73
Briefly about working with variables and expressions ...................... 73
C-SPY expressions ............................................................................. 74
Limitations on variable information .................................................. 76
Working with variables and expressions ...................................... 77
Using the windows related to variables and expressions ................... 77
Viewing assembler variables ............................................................. 78
Getting started using data sampling ................................................... 78
Getting started using data logging ..................................................... 79
Reference information on working with variables and
expressions ................................................................................................ 80
Auto window ...................................................................................... 81
Locals window ................................................................................... 82
Watch window ................................................................................... 84
Live Watch window ........................................................................... 86
Statics window ................................................................................... 88
7
AFE1_AFE2-1:1
Quick Watch window ......................................................................... 91
Symbols window ................................................................................ 93
Resolve Symbol Ambiguity dialog box ............................................. 94
Data Log window ............................................................................... 95
Data Log Summary window .............................................................. 97
Setup Data Sample window ............................................................... 99
Data Sample window ....................................................................... 100
Sampled Graphs window ................................................................. 102
Breakpoints
........................................................................................................ 107
Introduction to setting and using breakpoints ........................ 107
Reasons for using breakpoints ......................................................... 107
Briefly about setting breakpoints ..................................................... 107
Breakpoint types .............................................................................. 108
Breakpoint icons .............................................................................. 109
Breakpoints in the C-SPY simulator ................................................ 110
Breakpoints in the C-SPY hardware debugger drivers .................... 110
Breakpoint consumers ...................................................................... 111
Setting breakpoints .............................................................................. 111
Various ways to set a breakpoint ..................................................... 112
Toggling a simple code breakpoint .................................................. 112
Setting breakpoints using the dialog box ......................................... 112
Setting a data breakpoint in the Memory window ........................... 114
Setting breakpoints using system macros ........................................ 114
Useful breakpoint hints .................................................................... 115
Reference information on breakpoints ....................................... 117
Breakpoints window ........................................................................ 117
Breakpoint Usage window ............................................................... 119
Advanced breakpoints dialog box .................................................... 120
Code breakpoints dialog box ............................................................ 123
Log breakpoints dialog box .............................................................. 124
Data breakpoints dialog box ............................................................ 126
Data Log breakpoints dialog box ..................................................... 128
Immediate breakpoints dialog box ................................................... 129
C-SPY® Debugging Guide
8
for STM8
AFE1_AFE2-1:1
Contents
Enter Location dialog box ................................................................ 130
Resolve Source Ambiguity dialog box ............................................ 131
Memory and registers
.................................................................................. 133
Introduction to monitoring memory and registers ............... 133
Briefly about monitoring memory and registers .............................. 133
C-SPY memory zones ...................................................................... 134
Stack display .................................................................................... 135
Memory access checking ................................................................. 136
Monitoring memory and registers ................................................ 136
Defining application-specific register groups .................................. 137
Reference information on memory and registers .................. 138
Memory window .............................................................................. 139
Memory Save dialog box ................................................................. 143
Memory Restore dialog box ............................................................. 144
Fill dialog box .................................................................................. 144
Symbolic Memory window .............................................................. 146
Stack window ................................................................................... 148
Register window .............................................................................. 152
SFR Setup window ........................................................................... 154
Edit SFR dialog box ......................................................................... 157
Memory Access Setup dialog box ................................................... 158
Edit Memory Access dialog box ...................................................... 160
Part 2. Analyzing your application ................................ 163
Trace ...................................................................................................................... 165
Introduction to using trace .............................................................. 165
Reasons for using trace .................................................................... 165
Briefly about trace ............................................................................ 165
Requirements for using trace ........................................................... 166
Collecting and using trace data ...................................................... 166
Getting started with trace ................................................................. 166
Trace data collection using breakpoints ........................................... 166
9
AFE1_AFE2-1:1
Searching in trace data ..................................................................... 167
Browsing through trace data ............................................................ 167
Reference information on trace ..................................................... 168
Trace Settings dialog box ................................................................. 168
Trace window ................................................................................... 170
Function Trace window ................................................................... 174
Timeline window ............................................................................ 174
Viewing Range dialog box ............................................................... 181
Trace Start breakpoints dialog box .................................................. 182
Trace Stop breakpoints dialog box ................................................... 183
Trace Expressions window .............................................................. 184
Find in Trace dialog box .................................................................. 185
Find in Trace window ...................................................................... 186
Profiling
................................................................................................................ 189
Introduction to the profiler .............................................................. 189
Reasons for using the profiler .......................................................... 189
Briefly about the profiler .................................................................. 189
Requirements for using the profiler ................................................. 190
Using the profiler .................................................................................. 191
Getting started using the profiler on function level ......................... 191
Analyzing the profiling data ............................................................ 191
Getting started using the profiler on instruction level ...................... 193
Reference information on the profiler ........................................ 194
Function Profiler window ................................................................ 194
Code coverage
................................................................................................. 199
Introduction to code coverage ....................................................... 199
Reasons for using code coverage ..................................................... 199
Briefly about code coverage ............................................................ 199
Requirements and restrictions for using code coverage ................... 199
Reference information on code coverage .................................. 199
Code Coverage window ................................................................... 200
C-SPY® Debugging Guide
10
for STM8
AFE1_AFE2-1:1
Contents
Part 3. Advanced debugging ................................................. 203
Interrupts
............................................................................................................ 205
Introduction to interrupts ................................................................ 205
Briefly about interrupt logging ........................................................ 205
Briefly about the interrupt simulation system .................................. 206
Interrupt characteristics .................................................................... 207
Interrupt simulation states ................................................................ 207
C-SPY system macros for interrupt simulation ............................... 208
Target-adapting the interrupt simulation system ............................. 209
Using the interrupt system .............................................................. 209
Simulating a simple interrupt ........................................................... 210
Simulating an interrupt in a multi-task system ................................ 211
Getting started using interrupt logging ............................................ 212
Reference information on interrupts ........................................... 212
Interrupt Setup dialog box ................................................................ 213
Edit Interrupt dialog box .................................................................. 214
Forced Interrupt window .................................................................. 216
Interrupt Status window ................................................................... 217
Interrupt Log window ...................................................................... 219
Interrupt Log Summary window ...................................................... 222
C-SPY macros
................................................................................................. 225
Introduction to C-SPY macros ....................................................... 225
Reasons for using C-SPY macros .................................................... 225
Briefly about using C-SPY macros .................................................. 226
Briefly about setup macro functions and files ................................. 226
Briefly about the macro language .................................................... 226
Using C-SPY macros ........................................................................... 227
Registering C-SPY macros—an overview ....................................... 228
Executing C-SPY macros—an overview ......................................... 228
Registering and executing using setup macros and setup files ........ 229
Executing macros using Quick Watch ............................................ 229
Executing a macro by connecting it to a breakpoint ........................ 230
11
AFE1_AFE2-1:1
Aborting a C-SPY macro ................................................................. 231
Reference information on the macro language ....................... 232
Macro functions ............................................................................... 232
Macro variables ................................................................................ 232
Macro strings .................................................................................... 233
Macro statements ............................................................................. 234
Formatted output .............................................................................. 235
Reference information on reserved setup macro function
names ......................................................................................................... 237
execUserPreload ............................................................................... 237
execUserExecutionStarted ............................................................... 237
execUserExecutionStopped ............................................................. 238
execUserSetup .................................................................................. 238
execUserPreReset ............................................................................. 238
execUserReset .................................................................................. 238
execUserExit .................................................................................... 239
Reference information on C-SPY system macros .................. 239
__cancelAllInterrupts ...................................................................... 241
__cancelInterrupt ............................................................................. 241
__clearBreak .................................................................................... 242
__closeFile ....................................................................................... 242
__delay ............................................................................................. 242
__disableInterrupts .......................................................................... 243
__driverType .................................................................................... 243
__enableInterrupts ........................................................................... 244
__evaluate ........................................................................................ 244
__fillMemory8 ................................................................................ 245
__fillMemory16 .............................................................................. 246
__fillMemory32 .............................................................................. 246
__isBatchMode ................................................................................ 247
__loadImage .................................................................................... 248
__memoryRestore ............................................................................ 249
__memorySave ................................................................................ 250
__messageBoxYesNo ...................................................................... 250
C-SPY® Debugging Guide
12
for STM8
AFE1_AFE2-1:1
Contents
__openFile ....................................................................................... 251
__orderInterrupt ............................................................................... 252
__popSimulatorInterruptExecutingStack ........................................ 253
__readFile ........................................................................................ 254
__readFileByte ................................................................................. 255
__readMemory8, __readMemoryByte ............................................ 255
__readMemory16 ............................................................................. 256
__readMemory32 ............................................................................. 256
__registerMacroFile ......................................................................... 257
__resetFile ........................................................................................ 257
__setCodeBreak ............................................................................... 258
__setDataBreak ................................................................................ 259
__setDataLogBreak ......................................................................... 260
__setLogBreak ................................................................................. 261
__setSimBreak ................................................................................. 262
__setTraceStartBreak ....................................................................... 263
__setTraceStopBreak ....................................................................... 264
__sourcePosition .............................................................................. 265
__strFind .......................................................................................... 265
__subString ...................................................................................... 266
__targetDebuggerVersion ................................................................ 266
__toLower ........................................................................................ 267
__toString ........................................................................................ 267
__toUpper ........................................................................................ 268
__unloadImage ................................................................................ 268
__writeFile ....................................................................................... 269
__writeFileByte ............................................................................... 269
__writeMemory8, __writeMemoryByte ......................................... 270
__writeMemory16 ........................................................................... 270
__writeMemory32 ........................................................................... 271
Graphical environment for macros .............................................. 271
Macro Registration window ............................................................. 272
Debugger Macros window ............................................................... 274
Macro Quicklaunch window ............................................................ 276
13
AFE1_AFE2-1:1
The C-SPY command line utility—cspybat
....................................... 279
Using C-SPY in batch mode ............................................................. 279
Starting cspybat ................................................................................ 279
Output ............................................................................................... 279
Invocation syntax ............................................................................. 280
Summary of C-SPY command line options .............................. 280
General cspybat options .................................................................. 281
Options available for all C-SPY drivers .......................................... 281
Options available for the simulator driver ....................................... 281
Options available for the C-SPY hardware drivers .......................... 281
Options available for the C-SPY STice driver ................................. 282
Reference information on C-SPY command line options ... 282
--backend .......................................................................................... 282
--code_coverage_file ........................................................................ 282
--cycles ............................................................................................. 283
-d ...................................................................................................... 283
--disable_interrupts .......................................................................... 284
--download_only .............................................................................. 284
--erase_memory ............................................................................... 284
--leave_running ................................................................................ 285
--log_file ........................................................................................... 285
--macro ............................................................................................. 285
--mapu .............................................................................................. 286
--mcuname ....................................................................................... 286
-p ...................................................................................................... 287
--plugin ............................................................................................. 287
--silent .............................................................................................. 288
--suppress_download ....................................................................... 288
--swim .............................................................................................. 288
--timeout ........................................................................................... 289
--verify_download ............................................................................ 289
C-SPY® Debugging Guide
14
for STM8
AFE1_AFE2-1:1
Contents
Part 4. Additional reference information
............. 291
Debugger options ........................................................................................... 293
Setting debugger options .................................................................. 293
Reference information on debugger options ............................ 293
Setup ................................................................................................. 294
Images .............................................................................................. 295
Plugins .............................................................................................. 296
Extra Options ................................................................................... 297
Reference information on C-SPY hardware debugger driver
options ....................................................................................................... 298
Setup options for STice and ST-LINK ............................................ 298
Additional information on C-SPY drivers
.......................................... 301
Reference information on C-SPY driver menus ..................... 301
C-SPY driver .................................................................................... 301
Simulator menu ................................................................................ 302
The ST-LINK menu ......................................................................... 304
The STice menu ............................................................................... 305
Reference information on the C-SPY simulator ..................... 306
Simulated Frequency dialog box ...................................................... 306
Resolving problems .............................................................................. 307
Write failure during load .................................................................. 307
No contact with the target hardware ................................................ 308
Slow stepping speed ......................................................................... 308
Index
..................................................................................................................... 311
15
AFE1_AFE2-1:1
C-SPY® Debugging Guide
16
for STM8
AFE1_AFE2-1:1
Tables
Tables
1: Typographic conventions used in this guide ......................................................... 22
2: Naming conventions used in this guide ................................................................ 23
3: Driver differences .................................................................................................. 33
4: C-SPY assembler symbols expressions ................................................................ 75
5: Handling name conflicts between hardware registers and assembler labels ......... 75
6: Available breakpoints in C-SPY hardware debugger drivers ............................. 110
7: C-SPY macros for breakpoints ............................................................................ 115
8: Supported graphs in the Timeline window ......................................................... 176
9: C-SPY driver profiling support ........................................................................... 190
10: Project options for enabling the profiler ........................................................... 191
11: Project options for enabling code coverage ...................................................... 200
12: Timer interrupt settings ..................................................................................... 210
13: Examples of C-SPY macro variables ................................................................ 233
14: Summary of system macros .............................................................................. 239
15: __cancelInterrupt return values ......................................................................... 241
16: __disableInterrupts return values ...................................................................... 243
17: __driverType return values ............................................................................... 243
18: __enableInterrupts return values ....................................................................... 244
19: __evaluate return values ................................................................................... 244
20: __isBatchMode return values ........................................................................... 248
21: __loadImage return values ................................................................................ 248
22: __messageBoxYesNo return values ................................................................. 251
23: __openFile return values ................................................................................... 252
24: __readFile return values ................................................................................... 254
25: __setCodeBreak return values .......................................................................... 258
26: __setDataBreak return values ........................................................................... 259
27: __setDataLogBreak return values ..................................................................... 260
28: __setLogBreak return values ............................................................................ 261
29: __setSimBreak return values ............................................................................ 262
30: __setTraceStartBreak return values .................................................................. 263
31: __setTraceStopBreak return values .................................................................. 264
17
AFE1_AFE2-1:1
32: __sourcePosition return values ......................................................................... 265
33: __unloadImage return values ............................................................................ 269
34: cspybat parameters ............................................................................................ 280
C-SPY® Debugging Guide
18
for STM8
AFE1_AFE2-1:1
Preface
Preface
Welcome to the C-SPY® Debugging Guide . The purpose of this guide is to help
you fully use the features in the IAR C-SPY® Debugger for debugging your
application based on the STM8 microcontroller.
Who should read this guide
Read this guide if you plan to develop an application using IAR Embedded Workbench
and want to get the most out of the features available in C-SPY.
REQUIRED KNOWLEDGE
To use the tools in IAR Embedded Workbench, you should have working knowledge of:
●
The architecture and instruction set of the STM8 microcontroller (refer to the chip
manufacturer's documentation)
●
The C or C++ programming language
●
Application development for embedded systems
●
The operating system of your host computer.
For more information about the other development tools incorporated in the IDE, refer
to their respective documentation, see Other documentation, page 20.
What this guide contains
Below is a brief outline and summary of the chapters in this guide.
Note: Some of the screenshots in this guide are taken from a similar product and not
from IAR Embedded Workbench for STM8.
PART 1. BASIC DEBUGGING
●
The IAR C-SPY Debugger introduces you to the C-SPY debugger and to the
concepts that are related to debugging in general and to C-SPY in particular. The
chapter also introduces the various C-SPY drivers. The chapter briefly shows the
difference in functionality that the various C-SPY drivers provide.
●
Getting started using C-SPY helps you get started using C-SPY, which includes
setting up, starting, and adapting C-SPY for target hardware.
19
AFE1_AFE2-1:1
Other documentation
●
Executing your application describes the conceptual differences between source
and disassembly mode debugging, the facilities for executing your application, and
finally, how you can handle terminal input and output.
●
Variables and expressions describes the syntax of the expressions and variables
used in C-SPY, as well as the limitations on variable information. The chapter also
demonstrates the various methods for monitoring variables and expressions.
●
Breakpoints describes the breakpoint system and the various ways to set
breakpoints.
●
Memory and registers shows how you can examine memory and registers.
PART 2. ANALYZING YOUR APPLICATION
●
Collecting and using trace data describes how you can inspect the program flow up
to a specific state using trace data.
●
Using the profiler describes how the profiler can help you find the functions in your
application source code where the most time is spent during execution.
●
Code coverage describes how the code coverage functionality can help you verify
whether all parts of your code have been executed, thus identifying parts which have
not been executed.
PART 3. ADVANCED DEBUGGING
●
Interrupts contains detailed information about the C-SPY interrupt simulation
system and how to configure the simulated interrupts to make them reflect the
interrupts of your target hardware.
●
Using C-SPY macros describes the C-SPY macro system, its features, the purposes
of these features, and how to use them.
●
The C-SPY command line utility—cspybat describes how to use C-SPY in batch
mode.
PART 4. ADDITIONAL REFERENCE INFORMATION
●
Debugger options describes the options you must set before you start the C-SPY
debugger.
●
Additional information on C-SPY drivers describes menus and features provided by
the C-SPY drivers not described in any dedicated topics.
Other documentation
User documentation is available as hypertext PDFs and as a context-sensitive online
help system in HTML format. You can access the documentation from the Information
C-SPY® Debugging Guide
20
for STM8
AFE1_AFE2-1:1
Preface
Center or from the Help menu in the IAR Embedded Workbench IDE. The online help
system is also available via the F1 key.
USER AND REFERENCE GUIDES
The complete set of IAR Systems development tools is described in a series of guides.
Information about:
●
System requirements and information about how to install and register the IAR
Systems products, is available in the booklet Quick Reference (available in the
product box) and the Installation and Licensing Guide.
●
Getting started using IAR Embedded Workbench and the tools it provides, is
available in the guide Getting Started with IAR Embedded Workbench®.
●
Using the IDE for project management and building, is available in the IDE Project
Management and Building Guide.
●
Using the IAR C-SPY® Debugger, is available in the C-SPY® Debugging Guide for
STM8.
●
Programming for the IAR C/C++ Compiler for STM8 and linking using the IAR
ILINK Linker, is available in the IAR C/C++ Development Guide for STM8.
●
Programming for the IAR Assembler for STM8, is available in the IAR Assembler
Reference Guide for STM8.
●
Using the IAR DLIB Library, is available in the DLIB Library Reference
information, available in the online help system.
●
Developing safety-critical applications using the MISRA C guidelines, is available
in the IAR Embedded Workbench® MISRA C:2004 Reference Guide or the IAR
Embedded Workbench® MISRA C:1998 Reference Guide.
Note: Additional documentation might be available depending on your product
installation.
THE ONLINE HELP SYSTEM
The context-sensitive online help contains:
●
Information about project management, editing, and building in the IDE
●
Information about debugging using the IAR C-SPY® Debugger
●
Reference information about the menus, windows, and dialog boxes in the IDE
●
Compiler reference information
●
Keyword reference information for the DLIB library functions. To obtain reference
information for a function, select the function name in the editor window and press
F1.
21
AFE1_AFE2-1:1
Document conventions
WEB SITES
Recommended web sites:
●
The STMicroelectronics web site www.st.com, that contains information and news
about the STM8 microcontrollers.
●
The IAR Systems web site, www.iar.com, that holds application notes and other
product information.
●
The web site of the C standardization working group,
www.open-std.org/jtc1/sc22/wg14.
●
The web site of the C++ Standards Committee, www.open-std.org/jtc1/sc22/wg21.
●
Finally, the Embedded C++ Technical Committee web site,
www.caravan.net/ec2plus, that contains information about the Embedded C++
standard.
Document conventions
When, in the IAR Systems documentation, we refer to the programming language C, the
text also applies to C++, unless otherwise stated.
When referring to a directory in your product installation, for example stm8\doc, the
full path to the location is assumed, for example c:\Program Files\IAR
Systems\Embedded Workbench 7.n\stm8\doc.
TYPOGRAPHIC CONVENTIONS
The IAR Systems documentation set uses the following typographic conventions:
Style
Used for
computer
• Source code examples and file paths.
• Text on the command line.
• Binary, hexadecimal, and octal numbers.
parameter
A placeholder for an actual value used as a parameter, for example
filename.h where filename represents the name of the file.
[option]
An optional part of a directive, where [ and ] are not part of the actual
directive, but any [, ], {, or } are part of the directive syntax.
{option}
A mandatory part of a directive, where { and } are not part of the
actual directive, but any [, ], {, or } are part of the directive syntax.
[option]
An optional part of a command.
[a|b|c]
An optional part of a command with alternatives.
{a|b|c}
A mandatory part of a command with alternatives.
Table 1: Typographic conventions used in this guide
C-SPY® Debugging Guide
22
for STM8
AFE1_AFE2-1:1
Preface
Style
Used for
bold
Names of menus, menu commands, buttons, and dialog boxes that
appear on the screen.
italic
• A cross-reference within this guide or to another guide.
• Emphasis.
…
An ellipsis indicates that the previous item can be repeated an arbitrary
number of times.
Identifies instructions specific to the IAR Embedded Workbench® IDE
interface.
Identifies instructions specific to the command line interface.
Identifies helpful tips and programming hints.
Identifies warnings.
Table 1: Typographic conventions used in this guide (Continued)
NAMING CONVENTIONS
The following naming conventions are used for the products and tools from IAR
Systems®, when referred to in the documentation:
Brand name
Generic term
IAR Embedded Workbench® for STM8
IAR Embedded Workbench®
IAR Embedded Workbench® IDE for STM8
the IDE
IAR C-SPY® Debugger for STM8
C-SPY, the debugger
IAR C-SPY® Simulator
the simulator
IAR C/C++ Compiler™ for STM8
the compiler
IAR Assembler™ for STM8
the assembler
IAR ILINK Linker™
ILINK, the linker
IAR DLIB Library™
the DLIB library
Table 2: Naming conventions used in this guide
23
AFE1_AFE2-1:1
Document conventions
C-SPY® Debugging Guide
24
for STM8
AFE1_AFE2-1:1
Part 1. Basic debugging
This part of the C-SPY® Debugging Guide for STM8 includes these chapters:
●
The IAR C-SPY Debugger
●
Getting started using C-SPY
●
Executing your application
●
Variables and expressions
●
Breakpoints
●
Memory and registers
25
26
The IAR C-SPY Debugger
The IAR C-SPY Debugger
●
Introduction to C-SPY
●
Debugger concepts
●
C-SPY drivers overview
●
The IAR C-SPY Simulator
●
The C-SPY hardware debugger drivers
Introduction to C-SPY
These topics are covered:
●
An integrated environment
●
General C-SPY debugger features
●
RTOS awareness
AN INTEGRATED ENVIRONMENT
C-SPY is a high-level-language debugger for embedded applications. It is designed for
use with the IAR Systems compilers and assemblers, and is completely integrated in the
IDE, providing development and debugging within the same application. This will give
you possibilities such as:
●
Editing while debugging. During a debug session, you can make corrections directly
in the same source code window that is used for controlling the debugging. Changes
will be included in the next project rebuild.
●
Setting breakpoints at any point during the development cycle. You can inspect and
modify breakpoint definitions also when the debugger is not running, and
breakpoint definitions flow with the text as you edit. Your debug settings, such as
watch properties, window layouts, and register groups will be preserved between
your debug sessions.
All windows that are open in the Embedded Workbench workspace will stay open when
you start the C-SPY Debugger. In addition, a set of C-SPY-specific windows are opened.
27
AFE1_AFE2-1:1
Introduction to C-SPY
GENERAL C-SPY DEBUGGER FEATURES
Because IAR Systems provides an entire toolchain, the output from the compiler and
linker can include extensive debug information for the debugger, resulting in good
debugging possibilities for you.
C-SPY offers these general features:
●
Source and disassembly level debugging
C-SPY allows you to switch between source and disassembly debugging as required,
for both C or C++ and assembler source code.
●
Single-stepping on a function call level
Compared to traditional debuggers, where the finest granularity for source level
stepping is line by line, C-SPY provides a finer level of control by identifying every
statement and function call as a step point. This means that each function
call—inside expressions, and function calls that are part of parameter lists to other
functions—can be single-stepped. The latter is especially useful when debugging
C++ code, where numerous extra function calls are made, for example to object
constructors.
●
Code and data breakpoints
The C-SPY breakpoint system lets you set breakpoints of various kinds in the
application being debugged, allowing you to stop at locations of particular interest.
For example, you set breakpoints to investigate whether your program logic is correct
or to investigate how and when the data changes.
●
Monitoring variables and expressions
For variables and expressions there is a wide choice of facilities. You can easily
monitor values of a specified set of variables and expressions, continuously or on
demand. You can also choose to monitor only local variables, static variables, etc.
●
Container awareness
When you run your application in C-SPY, you can view the elements of library data
types such as STL lists and vectors. This gives you a very good overview and
debugging opportunities when you work with C++ STL containers.
●
Call stack information
The compiler generates extensive call stack information. This allows the debugger to
show, without any runtime penalty, the complete stack of function calls wherever the
program counter is. You can select any function in the call stack, and for each
function you get valid information for local variables and available registers.
●
Powerful macro system
C-SPY includes a powerful internal macro system, to allow you to define complex
sets of actions to be performed. C-SPY macros can be used on their own or in
C-SPY® Debugging Guide
28
for STM8
AFE1_AFE2-1:1
The IAR C-SPY Debugger
conjunction with complex breakpoints and—if you are using the simulator—the
interrupt simulation system to perform a wide variety of tasks.
Additional general C-SPY debugger features
This list shows some additional features:
●
Threaded execution keeps the IDE responsive while running the target application
●
Automatic stepping
●
The source browser provides easy navigation to functions, types, and variables
●
Extensive type recognition of variables
●
Configurable registers (CPU and peripherals) and memory windows
●
Graphical stack view with overflow detection
●
Support for code coverage and function level profiling
●
The target application can access files on the host PC using file I/O
●
Optional terminal I/O emulation.
RTOS AWARENESS
C-SPY supports RTOS-aware debugging.
These operating systems are currently supported:
●
Segger embOS
●
ORTI RTOS.
RTOS plugin modules can be provided by IAR Systems, and by third-party suppliers.
Contact your software distributor or IAR Systems representative, alternatively visit the
IAR Systems web site, for information about supported RTOS modules.
A C-SPY RTOS awareness plugin module gives you a high level of control and visibility
over an application built on top of an RTOS. It displays RTOS-specific items like task
lists, queues, semaphores, mailboxes, and various RTOS system variables. Task-specific
breakpoints and task-specific stepping make it easier to debug tasks.
A loaded plugin will add its own menu, set of windows, and buttons when a debug
session is started (provided that the RTOS is linked with the application). For
information about other RTOS awareness plugin modules, refer to the manufacturer of
the plugin module.
29
AFE1_AFE2-1:1
Debugger concepts
Debugger concepts
These topics are covered:
●
C-SPY and target systems
●
The debugger
●
The target system
●
The application
●
C-SPY debugger systems
●
The ROM-monitor program
●
Third-party debuggers
●
C-SPY plugin modules
This section introduces some of the concepts and terms that are related to debugging in
general and to C-SPY in particular. This section does not contain specific information
related to C-SPY features. Instead, you will find such information in the other chapters
of this documentation. The IAR Systems user documentation uses the terms described
in this section when referring to these concepts.
C-SPY AND TARGET SYSTEMS
You can use C-SPY to debug either a software target system or a hardware target system.
C-SPY® Debugging Guide
30
for STM8
AFE1_AFE2-1:1
The IAR C-SPY Debugger
This figure gives an overview of C-SPY and possible target systems:
Note: In IAR Embedded Workbench for STM8, there are no ROM-monitor drivers.
THE DEBUGGER
The debugger, for instance C-SPY, is the program that you use for debugging your
applications on a target system.
THE TARGET SYSTEM
The target system is the system on which you execute your application when you are
debugging it. The target system can consist of hardware, either an evaluation board or
your own hardware design. It can also be completely or partially simulated by software.
Each type of target system needs a dedicated C-SPY driver.
THE APPLICATION
A user application is the software you have developed and which you want to debug
using C-SPY.
C-SPY DEBUGGER SYSTEMS
C-SPY consists of both a general part which provides a basic set of debugger features,
and a target-specific back end. The back end consists of two components: a processor
module—one for every microcontroller, which defines the properties of the
31
AFE1_AFE2-1:1
Debugger concepts
microcontroller, and a C-SPY driver. The C-SPY driver is the part that provides
communication with and control of the target system. The driver also provides the user
interface—menus, windows, and dialog boxes—to the functions provided by the target
system, for instance, special breakpoints. Typically, there are three main types of C-SPY
drivers:
●
Simulator driver
●
ROM-monitor driver
●
Emulator driver.
C-SPY is available with a simulator driver, and depending on your product package,
optional drivers for hardware debugger systems. For an overview of the available C-SPY
drivers and the functionality provided by each driver, see C-SPY drivers overview, page
33.
THE ROM-MONITOR PROGRAM
The ROM-monitor program is a piece of firmware that is loaded to non-volatile memory
on your target hardware; it runs in parallel with your application. The ROM-monitor
communicates with the debugger and provides services needed for debugging the
application, for instance stepping and breakpoints.
THIRD-PARTY DEBUGGERS
You can use a third-party debugger together with the IAR Systems toolchain as long as
the third-party debugger can read ELF/DWARF, Intel-extended, or Motorola. For
information about which format to use with a third-party debugger, see the user
documentation supplied with that tool.
C-SPY PLUGIN MODULES
C-SPY is designed as a modular architecture with an open SDK that can be used for
implementing additional functionality to the debugger in the form of plugin modules.
These modules can be seamlessly integrated in the IDE.
Plugin modules are provided by IAR Systems, or can be supplied by third-party vendors.
Examples of such modules are:
C-SPY® Debugging Guide
32
for STM8
AFE1_AFE2-1:1
●
Code Coverage, which is integrated in the IDE.
●
The various C-SPY drivers for debugging using certain debug systems.
●
RTOS plugin modules for support for real-time OS aware debugging.
●
C-SPYLink that bridges IAR visualSTATE and IAR Embedded Workbench to make
true high-level state machine debugging possible directly in C-SPY, in addition to
the normal C level symbolic debugging. For more information, see the
documentation provided with IAR visualSTATE.
The IAR C-SPY Debugger
For more information about the C-SPY SDK, contact IAR Systems.
C-SPY drivers overview
These topics are covered:
●
Differences between the C-SPY drivers
At the time of writing this guide, the IAR C-SPY Debugger for the STM8
microcontrollers is available with drivers for these target systems and evaluation boards:
●
Simulator
●
STice
●
ST-LINK.
DIFFERENCES BETWEEN THE C-SPY DRIVERS
This table summarizes the key differences between the C-SPY drivers:
ST-LINK and
Feature
Simulator
STice
Code breakpoints1
Unlimited
x
x
x
--
x
--
x
x
x
x
x
Simulated interrupts
x
--
--
Real interrupts1
--
x
x
Interrupt logging
x
--
--
Data logging1
x
--
--
--
x
x
x
--
--
x
x
--
x
x
--
x
x
--
x
x
--
1
Data breakpoints
Execution in real time
1
Zero memory footprint
1
1
1
1
Live watch
Cycle counter
1
Code coverage
1
Data coverage1
Function/instruction profiling
Trace1
1
STice in SWIM mode
Table 3: Driver differences
1 With specific requirements or restrictions, see the respective chapter in this guide.
33
AFE1_AFE2-1:1
The IAR C-SPY Simulator
The IAR C-SPY Simulator
The C-SPY Simulator simulates the functions of the target processor entirely in
software, which means that you can debug the program logic long before any hardware
is available. Because no hardware is required, it is also the most cost-effective solution
for many applications.
The C-SPY Simulator supports:
●
Instruction-level simulation
●
Memory configuration and validation
●
Interrupt simulation
●
Peripheral simulation (using the C-SPY macro system in conjunction with
immediate breakpoints).
Simulating hardware instead of using a hardware debugging system means that some
limitations do not apply, but that there are other limitations instead. For example:
●
You can set an unlimited number of breakpoints in the simulator.
●
When you stop executing your application, time actually stops in the simulator.
When you stop application execution on a hardware debugging system, there might
still be activities in the system. For example, peripheral units might still be active
and reading from or writing to SFR ports.
●
Application execution is significantly much slower in a simulator compared to when
using a hardware debugging system. However, during a debug session, this might
not necessarily be a problem.
●
The simulator is not cycle accurate.
●
Peripheral simulation is limited in the C-SPY Simulator and therefore the simulator
is suitable mostly for debugging code that does not interact too much with
peripheral units.
The C-SPY hardware debugger drivers
These topics are covered:
●
Communication overview, page 35
C-SPY can connect to a hardware debugger using a C-SPY hardware debugger driver as
an interface. The C-SPY hardware debugger drivers are automatically installed during
the installation of IAR Embedded Workbench.
IAR Embedded Workbench for STM8 comes with two different C-SPY hardware
debugger drivers—STice and ST-LINK.
C-SPY® Debugging Guide
34
for STM8
AFE1_AFE2-1:1
The IAR C-SPY Debugger
COMMUNICATION OVERVIEW
Most target systems have a debug probe or a debug adapter connected between the host
computer and the evaluation board.
The C-SPY hardware debugger driver uses USB to communicate with the hardware
debugger. The hardware debugger communicates with the target STM8 microcontroller
over the SWIM interface. Alternatively, the STice emulator can emulate an STM8
microcontroller.
For further information, refer to the documentation supplied with the hardware
debugger.
When a debug session is started, your application is automatically downloaded and
programmed into flash memory. You can disable this feature, if necessary.
Hardware installation
For information about the hardware installation, see the documentation supplied with
the hardware debugger from STMicroelectronics. The following power-up sequence is
35
AFE1_AFE2-1:1
The C-SPY hardware debugger drivers
recommended to ensure proper communication between the target board, hardware
debugger, and C-SPY:
1 Power up the target board.
2 Power up the hardware debugger.
3 Start the C-SPY debugging session.
C-SPY® Debugging Guide
36
for STM8
AFE1_AFE2-1:1
Getting started using C-SPY
Getting started using
C-SPY
●
Setting up C-SPY
●
Starting C-SPY
●
Adapting for target hardware
●
Running example projects
●
Reference information on starting C-SPY
Setting up C-SPY
These tasks are covered:
●
Setting up for debugging
●
Executing from reset
●
Using a setup macro file
●
Selecting a device description file
●
Loading plugin modules
SETTING UP FOR DEBUGGING
1 Before you start C-SPY, choose Project>Options>Debugger>Setup and select the
C-SPY driver that matches your debugger system: simulator or a hardware debugger
system.
2 In the Category list, select the appropriate C-SPY driver and make your settings.
For information about these options, see Debugger options, page 293.
3 Click OK.
4 Choose Tools>Options to open the IDE Options dialog box:
●
Select Debugger to configure the debugger behavior
●
Select Stack to configure the debugger’s tracking of stack usage.
For more information about these options, see the IDE Project Management and
Building Guide.
37
AFE1_AFE2-1:1
Setting up C-SPY
See also Adapting for target hardware, page 42.
EXECUTING FROM RESET
The Run to option—available on the Debugger>Setup page—specifies a location you
want C-SPY to run to when you start a debug session as well as after each reset. C-SPY
will place a temporary breakpoint at this location and all code up to this point is executed
before stopping at the location.
The default location to run to is the main function. Type the name of the location if you
want C-SPY to run to a different location. You can specify assembler labels or whatever
can be evaluated to such, for instance function names.
If you leave the check box empty, the program counter will contain the regular hardware
reset address at each reset
If no breakpoints are available when C-SPY starts, a warning message notifies you that
single stepping will be required and that this is time-consuming. You can then continue
execution in single-step mode or stop at the first instruction. If you choose to stop at the
first instruction, the debugger starts executing with the PC (program counter) at the
default reset location instead of the location you typed in the Run to box.
Note: This message will never be displayed in the C-SPY Simulator, where breakpoints
are unlimited.
USING A SETUP MACRO FILE
A setup macro file is a macro file that you choose to load automatically when C-SPY
starts. You can define the setup macro file to perform actions according to your needs,
using setup macro functions and system macros. Thus, if you load a setup macro file you
can initialize C-SPY to perform actions automatically.
For more information about setup macro files and functions, see Introduction to C-SPY
macros, page 225. For an example of how to use a setup macro file, see the chapter
Initializing target hardware before C-SPY starts.
To register a setup macro file:
1 Before you start C-SPY, choose Project>Options>Debugger>Setup.
2 Select Use macro file and type the path and name of your setup macro file, for
example Setup.mac. If you do not type a filename extension, the extension mac is
assumed.
SELECTING A DEVICE DESCRIPTION FILE
C-SPY uses device description files to handle device-specific information.
C-SPY® Debugging Guide
38
for STM8
AFE1_AFE2-1:1
Getting started using C-SPY
A default device description file is automatically used based on your project settings. If
you want to override the default file, you must select your device description file. Device
description files are provided in the stm8\config directory and they have the filename
extension ddf.
For more information about device description files, see Adapting for target hardware,
page 42.
To override the default device description file:
1 Before you start C-SPY, choose Project>Options>Debugger>Setup.
2 Enable the use of a device description file and select a file using the Device
description file browse button.
Note: You can easily view your device description files that are used for your project.
Choose Project>Open Device Description File and select the file you want to view.
LOADING PLUGIN MODULES
On the Plugins page you can specify C-SPY plugin modules to load and make available
during debug sessions. Plugin modules can be provided by IAR Systems, and by
third-party suppliers. Contact your software distributor or IAR Systems representative,
or visit the IAR Systems web site, for information about available modules.
For more information, see Plugins, page 296.
Starting C-SPY
When you have set up the debugger, you are ready to start a debug session; this section
describes various ways to start C-SPY.
This section covers these tasks:
●
Starting a debug session
●
Loading executable files built outside of the IDE
●
Starting a debug session with source files missing
●
Loading multiple images
STARTING A DEBUG SESSION
You can choose to start a debug session with or without loading the current executable
file.
To start C-SPY and download the current executable file, click the Download and
Debug button. Alternatively, choose Project>Download and Debug.
39
AFE1_AFE2-1:1
Starting C-SPY
To start C-SPY without downloading the current executable file, click the Debug
without Downloading button. Alternatively, choose Project>Debug without
Downloading.
LOADING EXECUTABLE FILES BUILT OUTSIDE OF THE IDE
You can also load C-SPY with an application that was built outside the IDE, for example
applications built on the command line. To load an externally built executable file and
to set build options you must first create a project for it in your workspace.
To create a project for an externally built file:
1 Choose Project>Create New Project, and specify a project name.
2 To add the executable file to the project, choose Project>Add Files and make sure to
choose All Files in the Files of type drop-down list. Locate the executable file.
3 To start the executable file, click the Download and Debug button. The project can be
reused whenever you rebuild your executable file.
The only project options that are meaningful to set for this kind of project are options in
the General Options and Debugger categories. Make sure to set up the general project
options in the same way as when the executable file was built.
STARTING A DEBUG SESSION WITH SOURCE FILES MISSING
Normally, when you use the IAR Embedded Workbench IDE to edit source files, build
your project, and start the debug session, all required files are available and the process
works as expected.
However, if C-SPY cannot automatically find the source files, for example if the
application was built on another computer, the Get Alternative File dialog box is
displayed:
Typically, you can use the dialog box like this:
●
C-SPY® Debugging Guide
40
for STM8
AFE1_AFE2-1:1
The source files are not available: Click If possible, don’t show this dialog again
and then click Skip. C-SPY will assume that there simply is no source file available.
Getting started using C-SPY
The dialog box will not appear again, and the debug session will not try to display
the source code.
●
Alternative source files are available at another location: Specify an alternative
source code file, click If possible, don’t show this dialog again, and then click Use
this file. C-SPY will assume that the alternative file should be used. The dialog box
will not appear again, unless a file is needed for which there is no alternative file
specified and which cannot be located automatically.
If you restart the IAR Embedded Workbench IDE, the Get Alternative File dialog box
will be displayed again once even if you have clicked If possible, don’t show this
dialog again. This gives you an opportunity to modify your previous settings.
For more information, see Get Alternative File dialog box, page 51.
LOADING MULTIPLE IMAGES
Normally, a debuggable application consists of exactly one file that you debug.
However, you can also load additional debug files (images). This means that the
complete program consists of several images.
Typically, this is useful if you want to debug your application in combination with a
prebuilt ROM image that contains an additional library for some platform-provided
features. The ROM image and the application are built using separate projects in the
IAR Embedded Workbench IDE and generate separate output files.
If more than one image has been loaded, you will have access to the combined debug
information for all the loaded images. In the Images window you can choose whether
you want to have access to debug information for one image or for all images.
To load additional images at C-SPY startup:
1 Choose Project>Options>Debugger>Images and specify up to three additional
images to be loaded. For more information, see Images, page 295.
2 Start the debug session.
To load additional images at a specific moment:
Use the __loadImage system macro and execute it using either one of the methods
described in Using C-SPY macros, page 227.
To display a list of loaded images:
Choose Images from the View menu. The Images window is displayed, see Images
window, page 50.
41
AFE1_AFE2-1:1
Adapting for target hardware
Adapting for target hardware
These topics are covered:
●
Modifying a device description file
●
Initializing target hardware before C-SPY starts
MODIFYING A DEVICE DESCRIPTION FILE
C-SPY uses device description files provided with the product to handle several of the
target-specific adaptations, see Selecting a device description file, page 38. They contain
device-specific information such as:
●
Definitions of memory-mapped peripheral units, device-specific CPU registers, and
groups of these.
●
Definitions for device-specific interrupts, which makes it possible to simulate these
interrupts in the C-SPY simulator; see Interrupts, page 205.
Normally, you do not need to modify the device description file. However, if the
predefinitions are not sufficient for some reason, you can edit the file. Note, however,
that the format of these descriptions might be updated in future upgrades of the product.
Make a copy of the device description file that best suits your needs, and modify it
according to the description in the file. Reload the project to make the changes take
effect.
For information about how to load a device description file, see Selecting a device
description file, page 38.
INITIALIZING TARGET HARDWARE BEFORE C-SPY STARTS
You can use C-SPY macros to initialize target hardware before C-SPY starts. For
example, if your hardware uses external memory that must be enabled before code can
be downloaded to it, C-SPY needs a macro to perform this action before your
application can be downloaded.
1 Create a new text file and define your macro function.
By using the built-in execUserPreload setup macro function, your macro function
will be executed directly after the communication with the target system is established
but before C-SPY downloads your application.
C-SPY® Debugging Guide
42
for STM8
AFE1_AFE2-1:1
Getting started using C-SPY
For example, a macro that enables external SDRAM could look like this:
/* Your macro function. */
enableExternalSDRAM()
{
__message "Enabling external SDRAM\n";
__writeMemory32(...);
}
/* Setup macro determines time of execution. */
execUserPreload()
{
enableExternalSDRAM();
}
2 Save the file with the filename extension mac.
3 Before you start C-SPY, choose Project>Options>Debugger and click the Setup tab.
4 Select the option Use Setup file and choose the macro file you just created.
Your setup macro will now be loaded during the C-SPY startup sequence.
Running example projects
These tasks are covered:
●
Running an example project
Example applications are provided with IAR Embedded Workbench. You can use these
examples to get started using the development tools from IAR Systems. You can also
use the examples as a starting point for your application project.
You can find the examples in the stm8\examples directory. The examples are ready to
be used as is. They are supplied with ready-made workspace files, together with source
code files and all other related files.
RUNNING AN EXAMPLE PROJECT
Example applications are provided with IAR Embedded Workbench. You can use these
examples to get started using the development tools from IAR Systems. You can also
use the examples as a starting point for your application project.
You can find the examples in the stm8\examples directory. The examples are ready to
be used as is. They are supplied with ready-made workspace files, together with source
code files and all other related files.
43
AFE1_AFE2-1:1
Running example projects
To run an example project:
1 Choose Help>Information Center and click EXAMPLE PROJECTS.
2 Browse to the example that matches the specific evaluation board or starter kit you are
using.
Click the Open Project button.
3 In the dialog box that appears, choose a destination folder for your project.
4 The available example projects are displayed in the workspace window. Select one of
the projects, and if it is not the active project (highlighted in bold), right-click it and
choose Set As Active from the context menu.
5 To view the project settings, select the project and choose Options from the context
menu. Verify the settings for General Options>Target>Device and
Debugger>Setup>Driver. As for other settings, the project is set up to suit the target
system you selected.
For more information about the C-SPY options and how to configure C-SPY to interact
with the target board, see Debugger options, page 293.
Click OK to close the project Options dialog box.
6 To compile and link the application, choose Project>Make or click the Make button.
7 To start C-SPY, choose Project>Debug or click the Download and Debug button. If
C-SPY fails to establish contact with the target system, see Resolving problems, page
307.
8 Choose Debug>Go or click the Go button to start the application.
C-SPY® Debugging Guide
44
for STM8
AFE1_AFE2-1:1
Getting started using C-SPY
Click the Stop button to stop execution.
Reference information on starting C-SPY
Reference information about:
●
C-SPY Debugger main window, page 45
●
Images window, page 50
●
Get Alternative File dialog box, page 51
●
Option Bytes window, page 52
See also:
●
Tools options for the debugger in the IDE Project Management and Building Guide.
C-SPY Debugger main window
When you start a debug session, these debugger-specific items appear in the main IAR
Embedded Workbench IDE window:
●
A dedicated Debug menu with commands for executing and debugging your
application
●
Depending on the C-SPY driver you are using, a driver-specific menu, often
referred to as the Driver menu in this documentation. Typically, this menu contains
menu commands for opening driver-specific windows and dialog boxes.
●
A special debug toolbar
●
Several windows and dialog boxes specific to C-SPY.
The C-SPY main window might look different depending on which components of the
product installation you are using.
Menu bar
These menus are available during a debug session:
Debug
Provides commands for executing and debugging the source application. Most
of the commands are also available as icon buttons on the debug toolbar.
C-SPY driver menu
Provides commands specific to a C-SPY driver. The driver-specific menu is only
available when the driver is used. For information about the driver-specific
menu commands, see Reference information on C-SPY driver menus, page 301.
45
AFE1_AFE2-1:1
Reference information on starting C-SPY
Debug menu
The Debug menu is available during a debug session. The Debug menu provides
commands for executing and debugging the source application. Most of the commands
are also available as icon buttons on the debug toolbar.
These commands are available:
Go F5
Executes from the current statement or instruction until a breakpoint or program
exit is reached.
Break
Stops the application execution.
Reset
Resets the target processor. Click the drop-down button to access a menu with
additional commands.
Enable Run to 'label', where label typically is main. Enables and disables
the project option Run to without exiting the debug session. This menu
command is only available if you have selected Run to in the Options dialog
box.
Reset strategies, which contains a list of reset strategies supported by the C-SPY
driver you are using. This means that you can choose a different reset strategy
than the one used initially without exiting the debug session. Reset strategies are
only available if the C-SPY driver you are using supports alternate reset
strategies.
Stop Debugging (Ctrl+Shift+D)
Stops the debugging session and returns you to the project manager.
C-SPY® Debugging Guide
46
for STM8
AFE1_AFE2-1:1
Getting started using C-SPY
Step Over (F10)
Executes the next statement, function call, or instruction, without entering C or
C++ functions or assembler subroutines.
Step Into (F11)
Executes the next statement or instruction, or function call, entering C or C++
functions or assembler subroutines.
Step Out (Shift+F11)
Executes from the current statement up to the statement after the call to the
current function.
Next Statement
Executes directly to the next statement without stopping at individual function
calls.
Run to Cursor
Executes from the current statement or instruction up to a selected statement or
instruction.
Autostep
Displays a dialog box where you can customize and perform autostepping, see
Autostep settings dialog box, page 72.
Set Next Statement
Moves the program counter directly to where the cursor is, without executing
any source code. Note, however, that this creates an anomaly in the program
flow and might have unexpected effects.
C++ Exceptions>
Break on Throw
This menu command is not supported by your product package.
C++ Exceptions>
Break on Uncaught Exception
This menu command is not supported by your product package.
Memory>Save
Displays a dialog box where you can save the contents of a specified memory
area to a file, see Memory Save dialog box, page 143.
Memory>Restore
Displays a dialog box where you can load the contents of a file in, for example
Intel-extended or Motorola s-record format to a specified memory zone, see
Memory Restore dialog box, page 144.
47
AFE1_AFE2-1:1
Reference information on starting C-SPY
Refresh
Refreshes the contents of all debugger windows. Because window updates are
automatic, this is needed only in unusual situations, such as when target memory
is modified in ways C-SPY cannot detect. It is also useful if code that is
displayed in the Disassembly window is changed.
Macros
Displays a dialog box where you can list, register, and edit your macro files and
functions, see Using C-SPY macros, page 227.
Logging>Set Log file
Displays a dialog box where you can choose to log the contents of the Debug
Log window to a file. You can select the type and the location of the log file. You
can choose what you want to log: errors, warnings, system information, user
messages, or all of these. See Log File dialog box, page 71.
Logging>
Set Terminal I/O Log file
Displays a dialog box where you can choose to log simulated target access
communication to a file. You can select the destination of the log file. See
Terminal I/O Log File dialog box, page 69
C-SPY windows
Depending on the C-SPY driver you are using, these windows specific to C-SPY are
available during a debug session:
C-SPY® Debugging Guide
48
for STM8
AFE1_AFE2-1:1
●
C-SPY Debugger main window
●
Disassembly window
●
Memory window
●
Symbolic Memory window
●
Register window
●
Watch window
●
Locals window
●
Auto window
●
Live Watch window
●
Quick Watch window
●
Statics window
●
Call Stack window
●
Trace window
●
Function Trace window
Getting started using C-SPY
●
Timeline window
●
Terminal I/O window
●
Code Coverage window
●
Function Profiler window
●
Images window
●
Stack window
●
Symbols window.
Additional windows are available depending on which C-SPY driver you are using.
Editing in C-SPY windows
You can edit the contents of the Memory, Symbolic Memory, Register, Auto, Watch,
Locals, Statics, Live Watch, and Quick Watch windows.
Use these keyboard keys to edit the contents of these windows:
Enter
Makes an item editable and saves the new value.
Esc
Cancels a new value.
In windows where you can edit the Expression field and in the Quick Watch window,
you can specify the number of elements to be displayed in the field by adding a
semicolon followed by an integer. For example, to display only the three first elements
of an array named myArray, or three elements in sequence starting with the element
pointed to by a pointer, write:
myArray;3
To display three elements pointed to by myPtr, myPtr+1, and myPtr+2, write:
myPtr;3
Optionally, add a comma and another integer that specifies which element to start with.
For example, to display elements 10–14, write:
myArray;5,10
To display myPtr+10, myPtr+11, myPtr+12, myPtr+13, and myPtr+14, write:
myPtr;5,10
Note: For pointers, there are no built-in limits on displayed element count, and no
validation of the pointer value.
49
AFE1_AFE2-1:1
Reference information on starting C-SPY
Images window
The Images window is available from the View menu.
The Images window lists all currently loaded images (debug files).
Normally, a source application consists of exactly one image that you debug. However,
you can also load additional images. This means that the complete debuggable unit
consists of several images.
Requirements
None; this window is always available.
Display area
C-SPY can either use debug information from all of the loaded images simultaneously,
or from one image at a time. Double-click on a row to show information only for that
image. The current choice is highlighted.
This area lists the loaded images in these columns:
Name
The name of the loaded image.
Path
The path to the loaded image.
Context menu
This context menu is available:
These commands are available:
Show all images
Shows debug information for all loaded debug images.
Show only image
Shows debug information for the selected debug image.
C-SPY® Debugging Guide
50
for STM8
AFE1_AFE2-1:1
Getting started using C-SPY
Related information
For related information, see:
●
Loading multiple images, page 41
●
Images, page 295
●
__loadImage, page 248.
Get Alternative File dialog box
The Get Alternative File dialog box is displayed if C-SPY cannot automatically find
the source files to be loaded, for example if the application was built on another
computer.
Could not find the following source file
The missing source file.
Suggested alternative
Specify an alternative file.
Use this file
After you have specified an alternative file, Use this file establishes that file as the alias
for the requested file. Note that after you have chosen this action, C-SPY will
automatically locate other source files if these files reside in a directory structure similar
to the first selected alternative file.
The next time you start a debug session, the selected alternative file will be preloaded
automatically.
Skip
C-SPY will assume that the source file is not available for this debug session.
51
AFE1_AFE2-1:1
Reference information on starting C-SPY
If possible, don’t show this dialog again
Instead of displaying the dialog box again for a missing source file, C-SPY will use the
previously supplied response.
Related information
For related information, see Starting a debug session with source files missing, page 40.
Option Bytes window
The Option Bytes window is available from the C-SPY driver menu.
This window lists all MCU options present at the target device together with their
current values.
If you need the MCU options to be in effect before the target starts executing, you must
deselect the Run to option on the Project>Options>Debugger page.
C-SPY® Debugging Guide
52
for STM8
AFE1_AFE2-1:1
Getting started using C-SPY
For more information about the option bytes and their possible values, see the data sheet
for your device.
Requirements
●
The C-SPY ST-LINK driver
●
The C-SPY STice driver.
Display area
Option
The name of the option byte.
Value
The current value of the option byte.
Note: Not all option bytes can be modified. ROP is one such option byte.
Context menu
Lists the possible values of the selected option byte. To modify a value, select it on this
menu.
Buttons
Load
Loads an option bytes configuration file (obc) and shows the settings in the
display area.
Save
Stores the settings made in the display area to an option bytes configuration file
(obc).
OK
Writes the settings made in the display area to the target device.
53
AFE1_AFE2-1:1
Reference information on starting C-SPY
C-SPY® Debugging Guide
54
for STM8
AFE1_AFE2-1:1
Executing your application
Executing your application
●
Introduction to application execution
●
Reference information on application execution
Introduction to application execution
These topics are covered:
●
Briefly about application execution
●
Source and disassembly mode debugging
●
Single stepping
●
Stepping speed
●
Running the application
●
Highlighting
●
Call stack information
●
Terminal input and output
●
Debug logging
BRIEFLY ABOUT APPLICATION EXECUTION
C-SPY allows you to monitor and control the execution of your application. By
single-stepping through it, and setting breakpoints, you can examine details about the
application execution, for example the values of variables and registers. You can also use
the call stack to step back and forth in the function call chain.
The terminal I/O and debug log features let you interact with your application.
You can find commands for execution on the Debug menu and on the toolbar.
SOURCE AND DISASSEMBLY MODE DEBUGGING
C-SPY allows you to switch between source mode and disassembly mode debugging as
needed.
Source debugging provides the fastest and easiest way of developing your application,
without having to worry about how the compiler or assembler has implemented the
code. In the editor windows you can execute the application one statement at a time
while monitoring the values of variables and data structures.
55
AFE1_AFE2-1:1
Introduction to application execution
Disassembly mode debugging lets you focus on the critical sections of your application,
and provides you with precise control of the application code. You can open a
disassembly window which displays a mnemonic assembler listing of your application
based on actual memory contents rather than source code, and lets you execute the
application exactly one machine instruction at a time.
Regardless of which mode you are debugging in, you can display registers and memory,
and change their contents.
SINGLE STEPPING
C-SPY allows more stepping precision than most other debuggers because it is not
line-oriented but statement-oriented. The compiler generates detailed stepping
information in the form of step points at each statement, and at each function call. That
is, source code locations where you might consider whether to execute a step into or a
step over command. Because the step points are located not only at each statement but
also at each function call, the step functionality allows a finer granularity than just
stepping on statements.
There are several factors that can slow down the stepping speed. If you find it too slow,
see Slow stepping speed, page 308 for some tips.
The step commands
There are four step commands:
●
Step Into
●
Step Over
●
Next Statement
●
Step Out.
Using the Autostep settings dialog box, you can automate the single stepping. For more
information, see Autostep settings dialog box, page 72.
C-SPY® Debugging Guide
56
for STM8
AFE1_AFE2-1:1
Executing your application
Consider this example and assume that the previous step has taken you to the f(i)
function call (highlighted):
extern int g(int);
int f(int n)
{
value = g(n-1) + g(n-2) + g(n-3);
return value;
}
int main()
{
...
f(i);
value ++;
}
Step Into
While stepping, you typically consider whether to step into a function and continue
stepping inside the function or subroutine. The Step Into command takes you to the first
step point within the subroutine g(n-1):
extern int g(int);
int f(int n)
{
value = g(n-1) + g(n-2) + g(n-3);
return value;
}
The Step Into command executes to the next step point in the normal flow of control,
regardless of whether it is in the same or another function.
Step Over
The Step Over command executes to the next step point in the same function, without
stopping inside called functions. The command would take you to the g(n-2) function
call, which is not a statement on its own but part of the same statement as g(n-1). Thus,
you can skip uninteresting calls which are parts of statements and instead focus on
critical parts:
extern int g(int);
int f(int n)
{
value = g(n-1) + g(n-2) + g(n-3);
return value;
}
57
AFE1_AFE2-1:1
Introduction to application execution
Next Statement
The Next Statement command executes directly to the next statement, in this case
return value, allowing faster stepping:
extern int g(int);
int f(int n)
{
value = g(n-1) + g(n-2) + g(n-3);
return value;
}
Step Out
When inside the function, you can—if you wish—use the Step Out command to step
out of it before it reaches the exit. This will take you directly to the statement
immediately after the function call:
extern int g(int);
int f(int n)
{
value = g(n-1) + g(n-2) g(n-3);
return value;
}
int main()
{
...
f(i);
value ++;
}
The possibility of stepping into an individual function that is part of a more complex
statement is particularly useful when you use C code containing many nested function
calls. It is also very useful for C++, which tends to have many implicit function calls,
such as constructors, destructors, assignment operators, and other user-defined
operators.
This detailed stepping can in some circumstances be either invaluable or unnecessarily
slow. For this reason, you can also step only on statements, which means faster stepping.
STEPPING SPEED
Stepping in C-SPY is normally performed using breakpoints. When performing a step
command, a breakpoint is set on the next statement and the program executes until
reaching this breakpoint. If you are debugging using a hardware debugger system, the
number of hardware breakpoints—typically used for setting a stepping breakpoint, at
least in code that is located in flash/ROM memory—is limited. If you for example, step
into a C switch statement, breakpoints are set on each branch, and hence, this might
C-SPY® Debugging Guide
58
for STM8
AFE1_AFE2-1:1
Executing your application
consume several hardware breakpoints. If the number of available hardware breakpoints
is exceeded, C-SPY switches into single stepping at assembly level, which can be very
slow.
For this reason, it can be helpful to keep track of how many hardware breakpoints are
used and make sure to some of them are left for stepping. For more information, see
Breakpoints in the C-SPY hardware debugger drivers, page 110 and Breakpoint
consumers, page 111.
In addition to limited hardware breakpoints, these issues might also affect stepping
speed:
●
If Trace or Function profiling is enabled. This might slow down stepping because
collected Trace data is processed after each step. Note that it is not sufficient to
close the corresponding windows to disable Trace data collection. Instead, you must
disable the Enable/Disable button in both the Trace and the Function profiling
windows.
●
If the Register window is open and displays SFR registers. This might slow down
stepping because all registers in the selected register group must be read from the
hardware after each step. To solve this, you can choose to view only a limited
selection of SFR register; you can choose between two alternatives. Either type
#SFR_name (where #SFR_name reflects the name of the SFR you want to monitor)
in the Watch window, or create your own filter for displaying a limited group of
SFRs in the Register window. See Defining application-specific register groups,
page 137.
●
If any of the Memory or Symbolic memory windows is open. This might slow down
stepping because the visible memory must be read after each step.
●
If any of the expression related windows such as Watch, Live Watch, Locals, Statics
is open. This might slow down stepping speed because all these windows reads
memory after each step.
●
If the Stack window is open and especially if the option Enable graphical stack
display and stack usage tracking option is enabled. To disable this option, choose
Tools>Options>Stack and disable it.
●
If a too slow communication speed has been set up between C-SPY and the target
board/emulator you should consider to increase the speed, if possible.
RUNNING THE APPLICATION
Go
The Go command continues execution from the current position until a breakpoint or
program exit is reached.
59
AFE1_AFE2-1:1
Introduction to application execution
Run to Cursor
The Run to Cursor command executes to the position in the source code where you
have placed the cursor. The Run to Cursor command also works in the Disassembly
window and in the Call Stack window.
HIGHLIGHTING
At each stop, C-SPY highlights the corresponding C or C++ source or instruction with
a green color, in the editor and the Disassembly window respectively. In addition, a
green arrow appears in the editor window when you step on C or C++ source level, and
in the Disassembly window when you step on disassembly level. This is determined by
which of the windows is the active window. If none of the windows are active, it is
determined by which of the windows was last active.
For simple statements without function calls, the whole statement is typically
highlighted. When stopping at a statement with function calls, C-SPY highlights the first
call because this illustrates more clearly what Step Into and Step Over would mean at
that time.
Occasionally, you will notice that a statement in the source window is highlighted using
a pale variant of the normal highlight color. This happens when the program counter is
at an assembler instruction which is part of a source statement but not exactly at a step
point. This is often the case when stepping in the Disassembly window. Only when the
program counter is at the first instruction of the source statement, the ordinary highlight
color is used.
CALL STACK INFORMATION
The compiler generates extensive backtrace information. This allows C-SPY to show,
without any runtime penalty, the complete function call chain at any time.
Typically, this is useful for two purposes:
●
Determining in what context the current function has been called
●
Tracing the origin of incorrect values in variables and in parameters, thus locating
the function in the call chain where the problem occurred.
The Call Stack window shows a list of function calls, with the current function at the
top. When you inspect a function in the call chain, the contents of all affected windows
C-SPY® Debugging Guide
60
for STM8
AFE1_AFE2-1:1
Executing your application
are updated to display the state of that particular call frame. This includes the editor,
Locals, Register, Watch and Disassembly windows. A function would normally not
make use of all registers, so these registers might have undefined states and be displayed
as dashes (---).
In the editor and Disassembly windows, a green highlight indicates the topmost, or
current, call frame; a yellow highlight is used when inspecting other frames.
For your convenience, it is possible to select a function in the call stack and click the
Run to Cursor command to execute to that function.
Assembler source code does not automatically contain any backtrace information. To
see the call chain also for your assembler modules, you can add the appropriate CFI
assembler directives to the assembler source code. For further information, see the IAR
Assembler Reference Guide for STM8.
TERMINAL INPUT AND OUTPUT
Sometimes you might have to debug constructions in your application that use stdin
and stdout without an actual hardware device for input and output. The Terminal I/O
window lets you enter input to your application, and display output from it. You can also
direct terminal I/O to a file, using the Terminal I/O Log Files dialog box.
This facility is useful in two different contexts:
●
If your application uses stdin and stdout
●
For producing debug trace printouts.
For more information, see Terminal I/O window, page 68 and Terminal I/O Log File
dialog box, page 69.
DEBUG LOGGING
The Debug Log window displays debugger output, such as diagnostic messages,
macro-generated output, event log messages, and information about trace.
It can sometimes be convenient to log the information to a file where you can easily
inspect it. The two main advantages are:
●
The file can be opened in another tool, for instance an editor, so you can navigate
and search within the file for particularly interesting parts
●
The file provides history about how you have controlled the execution, for instance,
which breakpoints that have been triggered etc.
61
AFE1_AFE2-1:1
Reference information on application execution
Reference information on application execution
Reference information about:
●
Disassembly window, page 62
●
Call Stack window, page 66
●
Terminal I/O window, page 68
●
Terminal I/O Log File dialog box, page 69
●
Debug Log window, page 70
●
Log File dialog box, page 71
●
Report Assert dialog box, page 72
●
Autostep settings dialog box, page 72
See also Terminal I/O options in the IDE Project Management and Building Guide.
Disassembly window
The C-SPY Disassembly window is available from the View menu.
C-SPY® Debugging Guide
62
for STM8
AFE1_AFE2-1:1
Executing your application
This window shows the application being debugged as disassembled application code.
To change the default color of the source code in the Disassembly window:
1 Choose Tools>Options>Debugger.
2 Set the default color using the Source code coloring in disassembly window option.
To view the corresponding assembler code for a function, you can select it in the editor
window and drag it to the Disassembly window.
Requirements
None; this window is always available.
Toolbar
The toolbar contains:
Go to
The memory location or symbol you want to view.
Zone
Selects a memory zone, see C-SPY memory zones, page 134.
Toggle Mixed-Mode
Toggles between displaying only disassembled code or disassembled code
together with the corresponding source code. Source code requires that the
corresponding source file has been compiled with debug information
Display area
The display area shows the disassembled application code.
63
AFE1_AFE2-1:1
Reference information on application execution
This area contains these graphic elements:
Green highlight
Indicates the current position, that is the next assembler
instruction to be executed. To move the cursor to any line in
the Disassembly window, click the line. Alternatively, move
the cursor using the navigation keys.
Yellow highlight
Indicates a position other than the current position, such as
when navigating between frames in the Call Stack window
or between items in the Trace window.
Red dot
Indicates a breakpoint. Double-click in the gray left-side
margin of the window to set a breakpoint. For more
information, see Breakpoints, page 107.
Green diamond
Indicates code that has been executed—that is, code
coverage.
If instruction profiling has been enabled from the context menu, an extra column in the
left-side margin appears with information about how many times each instruction has
been executed.
Context menu
This context menu is available:
Note: The contents of this menu are dynamic, which means that the commands on the
menu might depend on your product package.
These commands are available:
Move to PC
Displays code at the current program counter location.
C-SPY® Debugging Guide
64
for STM8
AFE1_AFE2-1:1
Executing your application
Run to Cursor
Executes the application from the current position up to the line containing the
cursor.
Code Coverage
Displays a submenu that provides commands for controlling code coverage.
This command is only enabled if the driver you are using supports it.
Enable
Toggles code coverage on or off.
Show
Toggles the display of code coverage on or off.
Executed code is indicated by a green diamond.
Clear
Clears all code coverage information.
Instruction Profiling
Displays a submenu that provides commands for controlling instruction
profiling. This command is only enabled if the driver you are using supports it.
Enable
Toggles instruction profiling on or off.
Show
Toggles the display of instruction profiling on or off.
For each instruction, the left-side margin displays
how many times the instruction has been executed.
Clear
Clears all instruction profiling information.
Toggle Breakpoint (Code)
Toggles a code breakpoint. Assembler instructions and any corresponding label
at which code breakpoints have been set are highlighted in red. For more
information, see Code breakpoints dialog box, page 123.
Toggle Breakpoint (Log)
Toggles a log breakpoint for trace printouts. Assembler instructions at which log
breakpoints have been set are highlighted in red. For more information, see Log
breakpoints dialog box, page 124.
Toggle Breakpoint (Trace Start)
Toggles a Trace Start breakpoint. When the breakpoint is triggered, the trace
data collection starts. Note that this menu command is only available if the
C-SPY driver you are using supports trace. For more information, see Trace
Start breakpoints dialog box, page 182.
65
AFE1_AFE2-1:1
Reference information on application execution
Toggle Breakpoint (Trace Stop)
Toggles a Trace Stop breakpoint. When the breakpoint is triggered, the trace
data collection stops. Note that this menu command is only available if the
C-SPY driver you are using supports trace. For more information, see Trace
Stop breakpoints dialog box, page 183.
Enable/Disable Breakpoint
Enables and Disables a breakpoint. If there is more than one breakpoint at a
specific line, all those breakpoints are affected by the Enable/Disable
command.
Edit Breakpoint
Displays the breakpoint dialog box to let you edit the currently selected
breakpoint. If there is more than one breakpoint on the selected line, a submenu
is displayed that lists all available breakpoints on that line.
Set Next Statement
Sets the program counter to the address of the instruction at the insertion point.
Copy Window Contents
Copies the selected contents of the Disassembly window to the clipboard.
Mixed-Mode
Toggles between showing only disassembled code or disassembled code
together with the corresponding source code. Source code requires that the
corresponding source file has been compiled with debug information.
Call Stack window
The Call stack window is available from the View menu.
This window displays the C function call stack with the current function at the top. To
inspect a function call, double-click it. C-SPY now focuses on that call frame instead.
C-SPY® Debugging Guide
66
for STM8
AFE1_AFE2-1:1
Executing your application
If the next Step Into command would step to a function call, the name of the function is
displayed in the grey bar at the top of the window. This is especially useful for implicit
function calls, such as C++ constructors, destructors, and operators.
Requirements
None; this window is always available.
Display area
Provided that the command Show Arguments is enabled, each entry in the display area
has the format:
function(values)
where (values) is a list of the current value of the parameters, or empty if the function
does not take any parameters.
Context menu
This context menu is available:
These commands are available:
Go to Source
Displays the selected function in the Disassembly or editor windows.
Show Arguments
Shows function arguments.
Run to Cursor
Executes until return to the function selected in the call stack.
Toggle Breakpoint (Code)
Toggles a code breakpoint.
Toggle Breakpoint (Log)
Toggles a log breakpoint.
67
AFE1_AFE2-1:1
Reference information on application execution
Toggle Breakpoint (Trace Start)
Toggles a Trace Start breakpoint. When the breakpoint is triggered, trace data
collection starts. Note that this menu command is only available if the C-SPY
driver you are using supports it.
Toggle Breakpoint (Trace Stop)
Toggles a Trace Stop breakpoint. When the breakpoint is triggered, trace data
collection stops. Note that this menu command is only available if the C-SPY
driver you are using supports it.
Enable/Disable Breakpoint
Enables or disables the selected breakpoint
Terminal I/O window
The Terminal I/O window is available from the View menu.
Use this window to enter input to your application, and display output from it.
To use this window, you must:
1 Link your application with the option Include C-SPY debugging support.
C-SPY will then direct stdin, stdout and stderr to this window. If the Terminal I/O
window is closed, C-SPY will open it automatically when input is required, but not for
output.
Requirements
None; this window is always available.
C-SPY® Debugging Guide
68
for STM8
AFE1_AFE2-1:1
Executing your application
Input
Type the text that you want to input to your application.
Ctrl codes
Opens a menu for input of special characters, such as EOF (end of file) and NUL.
Input Mode
Opens the Input Mode dialog box where you choose whether to input data from the
keyboard or from a file.
For reference information about the options available in this dialog box, see Terminal
I/O options in IDE Project Management and Building Guide.
Terminal I/O Log File dialog box
The Terminal I/O Log File dialog box is available by choosing Debug>Logging>Set
Terminal I/O Log File.
Use this dialog box to select a destination log file for terminal I/O from C-SPY.
Requirements
None; this dialog box is always available.
69
AFE1_AFE2-1:1
Reference information on application execution
Terminal IO Log Files
Controls the logging of terminal I/O. To enable logging of terminal I/O to a file, select
Enable Terminal IO log file and specify a filename. The default filename extension is
log. A browse button is available for your convenience.
Debug Log window
The Debug Log window is available by choosing View>Messages.
This window displays debugger output, such as diagnostic messages, macro-generated
output, event log messages, and information about trace. This output is only available
during a debug session. When opened, this window is, by default, grouped together with
the other message windows, see IDE Project Management and Building Guide.
Double-click any rows in one of the following formats to display the corresponding
source code in the editor window:
<path> (<row>):<message>
<path> (<row>,<column>):<message>
Requirements
None; this window is always available.
Context menu
This context menu is available:
These commands are available:
Copy
Copies the contents of the window.
Select All
Selects the contents of the window.
C-SPY® Debugging Guide
70
for STM8
AFE1_AFE2-1:1
Executing your application
Clear All
Clears the contents of the window.
Log File dialog box
The Log File dialog box is available by choosing Debug>Logging>Set Log File.
Use this dialog box to log output from C-SPY to a file.
Requirements
None; this dialog box is always available.
Enable Log file
Enables or disables logging to the file.
Include
The information printed in the file is, by default, the same as the information listed in
the Log window. Use the browse button, to override the default file and location of the
log file (the default filename extension is log). To change the information logged,
choose between:
Errors
C-SPY has failed to perform an operation.
Warnings
An error or omission of concern.
Info
Progress information about actions C-SPY has performed.
User
Messages from C-SPY macros, that is, your messages using the __message
statement.
71
AFE1_AFE2-1:1
Reference information on application execution
Report Assert dialog box
The Report Assert dialog box appears if you have a call to the assert function in your
application source code, and the assert condition is false. In this dialog box you can
choose how to proceed.
Abort
The application stops executing and the runtime library function abort, which is part
of your application on the target system, will be called. This means that the application
itself terminates its execution.
Debug
C-SPY stops the execution of the application and returns control to you.
Ignore
The assertion is ignored and the application continues to execute.
Autostep settings dialog box
The Autostep settings dialog box is available from the Debug menu.
Use this dialog box to customize autostepping.
The drop-down menu lists the available step commands.
Requirements
None; this dialog box is always available.
Delay
Specify the delay between each step in milliseconds.
C-SPY® Debugging Guide
72
for STM8
AFE1_AFE2-1:1
Variables and expressions
Variables and expressions
●
Introduction to working with variables and expressions
●
Working with variables and expressions
●
Reference information on working with variables and expressions
Introduction to working with variables and expressions
These topics are covered:
●
Briefly about working with variables and expressions
●
C-SPY expressions
●
Limitations on variable information.
BRIEFLY ABOUT WORKING WITH VARIABLES AND
EXPRESSIONS
There are several methods for looking at variables and calculating their values:
●
Tooltip watch—in the editor window—provides the simplest way of viewing the
value of a variable or more complex expressions. Just point at the variable with the
mouse pointer. The value is displayed next to the variable.
●
The Auto window displays a useful selection of variables and expressions in, or
near, the current statement. The window is automatically updated when execution
stops.
●
The Locals window displays the local variables, that is, auto variables and function
parameters for the active function. The window is automatically updated when
execution stops.
●
The Watch window allows you to monitor the values of C-SPY expressions and
variables. The window is automatically updated when execution stops.
●
The Live Watch window repeatedly samples and displays the values of expressions
while your application is executing. Variables in the expressions must be statically
located, such as global variables.
●
The Statics window displays the values of variables with static storage duration. The
window is automatically updated when execution stops.
●
The Macro Quicklaunch window and the Quick Watch window give you precise
control over when to evaluate an expression.
73
AFE1_AFE2-1:1
Introduction to working with variables and expressions
●
The Symbols window displays all symbols with a static location, that is, C/C++
functions, assembler labels, and variables with static storage duration, including
symbols from the runtime library.
●
The Data Log window and the Data Log Summary window display logs of accesses
up to four different memory locations or areas you choose by setting Data Log
breakpoints. Data logging can help you locate frequently accessed data. You can
then consider whether you should place that data in more efficient memory.
●
The Data Sample window displays samples for up to four different variables. You
can also display the data samples as graphs in the Sampled Graphs window. By
using data sampling, you will get an indication of the data value over a length of
time. Because it is a sampled value, data sampling is best suited for slow-changing
data. Variables in the expressions must be of integer type and statically located, for
example global variables.
●
The Trace-related windows let you inspect the program flow up to a specific state.
For more information, see Trace, page 165.
C-SPY EXPRESSIONS
C-SPY expressions can include any type of C expression, except for calls to functions.
The following types of symbols can be used in expressions:
●
C/C++ symbols
●
Assembler symbols (register names and assembler labels)
●
C-SPY macro functions
●
C-SPY macro variables.
Expressions that are built with these types of symbols are called C-SPY expressions and
there are several methods for monitoring these in C-SPY. Examples of valid C-SPY
expressions are:
i + j
i = 42
myVar = cVar
cVar = myVar + 2
#asm_label
#R2
#PC
my_macro_func(19)
If you have a static variable with the same name declared in several different functions,
use the notation function::variable to specify which variable to monitor.
C-SPY® Debugging Guide
74
for STM8
AFE1_AFE2-1:1
Variables and expressions
C/C++ symbols
C symbols are symbols that you have defined in the C source code of your application,
for instance variables, constants, and functions (functions can be used as symbols but
cannot be executed). C symbols can be referenced by their names. Note that C++
symbols might implicitly contain function calls which are not allowed in C-SPY
symbols and expressions.
Note: Some attributes available in C/C++, like volatile, are not fully supported by
C-SPY. For example, this line will not be accepted by C-SPY:
sizeof(unsigned char volatile __memattr *)
However, this line will be accepted:
sizeof(unsigned char __memattr *)
Assembler symbols
Assembler symbols can be assembler labels or registers, for example the program
counter, the stack pointer, or other CPU registers. If a device description file is used, all
memory-mapped peripheral units, such as I/O ports, can also be used as assembler
symbols in the same way as the CPU registers. See Modifying a device description file,
page 42.
Assembler symbols can be used in C-SPY expressions if they are prefixed by #.
Example
What it does
#PC++
Increments the value of the program counter.
myVar = #SP
Assigns the current value of the stack pointer register to your
C-SPY variable.
myVar = #label
Sets myVar to the value of an integer at the address of label.
myptr = &#label7
Sets myptr to an int * pointer pointing at label7.
Table 4: C-SPY assembler symbols expressions
In case of a name conflict between a hardware register and an assembler label, hardware
registers have a higher precedence. To refer to an assembler label in such a case, you
must enclose the label in back quotes ` (ASCII character 0x60). For example:
Example
What it does
#PC
Refers to the program counter.
#`PC`
Refers to the assembler label PC.
Table 5: Handling name conflicts between hardware registers and assembler labels
Which processor-specific symbols are available by default can be seen in the Register
window, using the CPU Registers register group. See Register window, page 152.
75
AFE1_AFE2-1:1
Introduction to working with variables and expressions
C-SPY macro functions
Macro functions consist of C-SPY macro variable definitions and macro statements
which are executed when the macro is called.
For information about C-SPY macro functions and how to use them, see Briefly about
the macro language, page 226.
C-SPY macro variables
Macro variables are defined and allocated outside your application, and can be used in
a C-SPY expression. In case of a name conflict between a C symbol and a C-SPY macro
variable, the C-SPY macro variable will have a higher precedence than the C variable.
Assignments to a macro variable assign both its value and type.
For information about C-SPY macro variables and how to use them, see Reference
information on the macro language, page 232.
Using sizeof
According to standard C, there are two syntactical forms of sizeof:
sizeof(type)
sizeof expr
The former is for types and the latter for expressions.
Note: In C-SPY, do not use parentheses around an expression when you use the sizeof
operator. For example, use sizeof x+2 instead of sizeof (x+2).
LIMITATIONS ON VARIABLE INFORMATION
The value of a C variable is valid only on step points, that is, the first instruction of a
statement and on function calls. This is indicated in the editor window with a bright
green highlight color. In practice, the value of the variable is accessible and correct more
often than that.
When the program counter is inside a statement, but not at a step point, the statement or
part of the statement is highlighted with a pale variant of the ordinary highlight color.
Effects of optimizations
The compiler is free to optimize the application software as much as possible, as long
as the expected behavior remains. The optimization can affect the code so that
debugging might be more difficult because it will be less clear how the generated code
relates to the source code. Typically, using a high optimization level can affect the code
in a way that will not allow you to view a value of a variable as expected.
C-SPY® Debugging Guide
76
for STM8
AFE1_AFE2-1:1
Variables and expressions
Consider this example:
myFunction()
{
int i = 42;
...
x = computer(i); /* Here, the value of i is known to C-SPY */
...
}
From the point where the variable i is declared until it is actually used, the compiler
does not need to waste stack or register space on it. The compiler can optimize the code,
which means that C-SPY will not be able to display the value until it is actually used. If
you try to view the value of a variable that is temporarily unavailable, C-SPY will
display the text:
Unavailable
If you need full information about values of variables during your debugging session,
you should make sure to use the lowest optimization level during compilation, that is,
None.
Working with variables and expressions
These tasks are covered:
●
Using the windows related to variables and expressions
●
Viewing assembler variables
●
Getting started using data sampling
●
Getting started using data logging
USING THE WINDOWS RELATED TO VARIABLES AND
EXPRESSIONS
Where applicable, you can add, modify, and remove expressions, and change the display
format in the windows related to variables and expressions.
To add a value you can also click in the dotted rectangle and type the expression you
want to examine. To modify the value of an expression, click the Value field and modify
its content. To remove an expression, select it and press the Delete key.
For text that is too wide to fit in a column—in any of the these windows, except the Trace
window—and thus is truncated, just point at the text with the mouse pointer and tooltip
information is displayed.
77
AFE1_AFE2-1:1
Working with variables and expressions
Right-click in any of the windows to access the context menu which contains additional
commands. Convenient drag-and-drop between windows is supported, except for in the
Locals window, Data logging windows, and the Quick Watch window where it is not
relevant.
VIEWING ASSEMBLER VARIABLES
An assembler label does not convey any type information at all, which means C-SPY
cannot easily display data located at that label without getting extra information. To
view data conveniently, C-SPY by default treats all data located at assembler labels as
variables of type int. However, in the Watch, Live Watch, and Quick Watch windows,
you can select a different interpretation to better suit the declaration of the variables.
In this figure, you can see four variables in the Watch window and their corresponding
declarations in the assembler source file to the left:
Note that asmvar4 is displayed as an int, although the original assembler declaration
probably intended for it to be a single byte quantity. From the context menu you can
make C-SPY display the variable as, for example, an 8-bit unsigned variable. This has
already been specified for the asmvar3 variable.
GETTING STARTED USING DATA SAMPLING
1 Choose C-SPY driver>Data Sample Setup to open the Data Sample Setup window.
C-SPY® Debugging Guide
78
for STM8
AFE1_AFE2-1:1
Variables and expressions
2 In the Data Sample Setup window, perform these actions:
●
In the Expression column, type the name of the variable for which you want to
sample data. The variable must be an integral type with a maximum size of 32 bits
and you can specify up to four variables. Make sure that the checkbox is selected for
the variable that you want to sample data.
●
In the Sampling interval column, type the number of milliseconds to pass between
the samples.
3 To view the result of data sampling, you must enable it in the window in question:
●
Choose C-SPY driver>Data Sample to open the Data Sample window. From the
context menu, choose Enable.
●
Choose C-SPY driver>Sampled Graph to open the Sampled Graph window. From
the context menu, choose Enable.
4 Start executing your application program. This starts the data sampling. When the
execution stops, for example because a breakpoint is triggered, you can view the result
either in the Data Sample window or as the Data Sample Graph in the Sampled Graphs
window
5 If you want to save the log or summary to a file, choose Save to log file from the
context menu in the window in question.
6 To disable data sampling, choose Disable from the context menu in each window
where you have enabled it.
GETTING STARTED USING DATA LOGGING
1 In the Breakpoints or Memory window, right-click and choose New
Breakpoints>Data Log to open the breakpoints dialog box. Set a Data Log breakpoint
on the data you want to collect log information for. You can set up to four Data Log
breakpoints.
2 Choose C-SPY driver>Data Log to open the Data Log window. Optionally, you can
also choose:
●
C-SPY driver>Data Log Summary to open the Data Log Summary window
●
C-SPY driver>Timeline to open the Timeline window to view the Data Log graph.
3 From the context menu, available in the Data Log window, choose Enable to enable
the logging.
4 Start executing your application program to collect the log information.
5 To view the data log information, look in any of the Data Log, Data Log Summary, or
the Data graph in the Timeline window.
79
AFE1_AFE2-1:1
Reference information on working with variables and expressions
6 If you want to save the log or summary to a file, choose Save to log file from the
context menu in the window in question.
7 To disable data and interrupt logging, choose Disable from the context menu in each
window where you have enabled it.
Reference information on working with variables and expressions
Reference information about:
●
Auto window, page 81
●
Locals window, page 82
●
Watch window, page 84
●
Live Watch window, page 86
●
Statics window, page 88
●
Quick Watch window, page 91
●
Symbols window, page 93
●
Resolve Symbol Ambiguity dialog box, page 94
●
Data Log window, page 95
●
Data Log Summary window, page 97
●
Setup Data Sample window, page 99
●
Data Sample window, page 100
●
Sampled Graphs window, page 102
See also:
C-SPY® Debugging Guide
80
for STM8
AFE1_AFE2-1:1
●
Reference information on trace, page 168 for trace-related reference information
●
Macro Quicklaunch window, page 276
Variables and expressions
Auto window
The Auto window is available from the View menu.
This window displays a useful selection of variables and expressions in, or near, the
current statement. Every time execution in C-SPY stops, the values in the Auto window
are recalculated. Values that have changed since the last stop are highlighted in red.
For information about editing in C-SPY windows, see C-SPY Debugger main window,
page 45.
Requirements
None; this window is always available.
Context menu
This context menu is available:
These commands are available:
Default Format,
Binary Format,
Octal Format,
Decimal Format,
Hexadecimal Format,
Char Format
Changes the display format of expressions. The display format setting affects
different types of expressions in different ways. Your selection of display format
is saved between debug sessions. These commands are available if a selected
line in the window contains a variable.
81
AFE1_AFE2-1:1
Reference information on working with variables and expressions
The display format setting affects different types of expressions in these ways:
Variables
The display setting affects only the selected variable, not
other variables.
Array elements
The display setting affects the complete array, that is, the
same display format is used for each array element.
Structure fields
All elements with the same definition—the same field
name and C declaration type—are affected by the
display setting.
Show As
Displays a submenu that provides commands for changing the default type
interpretation of variables. The commands on this submenu are mainly useful
for assembler variables—data at assembler labels—because these are, by
default, displayed as integers. For more information, see Viewing assembler
variables, page 78.
Options
Displays the IDE Options dialog box where you can set the Update interval
option. The default value of this option is 1000 milliseconds, which means the
Live Watch window will be updated once every second during program
execution. Note that this command is only available from this context menu in
the Live Watch window.
Save to File
Saves content to a file in a tab-separated format.
Locals window
The Locals window is available from the View menu.
This window displays the local variables and parameters for the current function. Every
time execution in C-SPY stops, the values in the Locals window are recalculated. Values
that have changed since the last stop are highlighted in red.
For information about editing in C-SPY windows, see C-SPY Debugger main window,
page 45.
C-SPY® Debugging Guide
82
for STM8
AFE1_AFE2-1:1
Variables and expressions
Requirements
None; this window is always available.
Context menu
This context menu is available:
These commands are available:
Default Format,
Binary Format,
Octal Format,
Decimal Format,
Hexadecimal Format,
Char Format
Changes the display format of expressions. The display format setting affects
different types of expressions in different ways. Your selection of display format
is saved between debug sessions. These commands are available if a selected
line in the window contains a variable.
The display format setting affects different types of expressions in these ways:
Variables
The display setting affects only the selected variable, not
other variables.
Array elements
The display setting affects the complete array, that is, the
same display format is used for each array element.
Structure fields
All elements with the same definition—the same field
name and C declaration type—are affected by the
display setting.
83
AFE1_AFE2-1:1
Reference information on working with variables and expressions
Show As
Displays a submenu that provides commands for changing the default type
interpretation of variables. The commands on this submenu are mainly useful
for assembler variables—data at assembler labels—because these are, by
default, displayed as integers. For more information, see Viewing assembler
variables, page 78.
Options
Displays the IDE Options dialog box where you can set the Update interval
option. The default value of this option is 1000 milliseconds, which means the
Live Watch window will be updated once every second during program
execution. Note that this command is only available from this context menu in
the Live Watch window.
Save to File
Saves content to a file in a tab-separated format.
Watch window
The Watch window is available from the View menu.
Use this window to monitor the values of C-SPY expressions or variables. You can open
up to four instances of this window, where you can view, add, modify, and remove
expressions. Tree structures of arrays, structs, and unions are expandable, which means
that you can study each item of these.
Every time execution in C-SPY stops, the values in the Watch window are recalculated.
Values that have changed since the last stop are highlighted in red.
Be aware that expanding very huge arrays can cause an out-of-memory crash. To avoid
this, expansion is automatically performed in steps of 5000 elements.
C-SPY® Debugging Guide
84
for STM8
AFE1_AFE2-1:1
Variables and expressions
For more information about editing in C-SPY windows, see C-SPY Debugger main
window, page 45.
Requirements
None; this window is always available.
Context menu
This context menu is available:
These commands are available:
Default Format,
Binary Format,
Octal Format,
Decimal Format,
Hexadecimal Format,
Char Format
Changes the display format of expressions. The display format setting affects
different types of expressions in different ways. Your selection of display format
is saved between debug sessions. These commands are available if a selected
line in the window contains a variable.
The display format setting affects different types of expressions in these ways:
Variables
The display setting affects only the selected variable, not
other variables.
Array elements
The display setting affects the complete array, that is, the
same display format is used for each array element.
Structure fields
All elements with the same definition—the same field
name and C declaration type—are affected by the
display setting.
85
AFE1_AFE2-1:1
Reference information on working with variables and expressions
Show As
Displays a submenu that provides commands for changing the default type
interpretation of variables. The commands on this submenu are mainly useful
for assembler variables—data at assembler labels—because these are, by
default, displayed as integers. For more information, see Viewing assembler
variables, page 78.
Options
Displays the IDE Options dialog box where you can set the Update interval
option. The default value of this option is 1000 milliseconds, which means the
Live Watch window will be updated once every second during program
execution. Note that this command is only available from this context menu in
the Live Watch window.
Save to File
Saves content to a file in a tab-separated format.
Live Watch window
The Live Watch window is available from the View menu.
This window repeatedly samples and displays the value of expressions while your
application is executing. Variables in the expressions must be statically located, such as
global variables.
For information about editing in C-SPY windows, see C-SPY Debugger main window,
page 45.
Requirements
None; this window is always available.
Display area
This area contains these columns:
Expression
The name of the variable. The base name of the variable is followed by the full
name, which includes module, class, or function scope. This column is not
editable.
C-SPY® Debugging Guide
86
for STM8
AFE1_AFE2-1:1
Variables and expressions
Value
The value of the variable. Values that have changed are highlighted in red.
Dragging text or a variable from another window and dropping it on the Value
column will assign a new value to the variable in that row.
This column is editable.
Location
The location in memory where this variable is stored.
Type
The data type of the variable.
Context menu
This context menu is available:
These commands are available:
Default Format,
Binary Format,
Octal Format,
Decimal Format,
Hexadecimal Format,
Char Format
Changes the display format of expressions. The display format setting affects
different types of expressions in different ways. Your selection of display format
is saved between debug sessions. These commands are available if a selected
line in the window contains a variable.
The display format setting affects different types of expressions in these ways:
Variables
The display setting affects only the selected variable, not
other variables.
Array elements
The display setting affects the complete array, that is, the
same display format is used for each array element.
87
AFE1_AFE2-1:1
Reference information on working with variables and expressions
Structure fields
All elements with the same definition—the same field
name and C declaration type—are affected by the
display setting.
Show As
Displays a submenu that provides commands for changing the default type
interpretation of variables. The commands on this submenu are mainly useful
for assembler variables—data at assembler labels—because these are, by
default, displayed as integers. For more information, see Viewing assembler
variables, page 78.
Options
Displays the IDE Options dialog box where you can set the Update interval
option. The default value of this option is 1000 milliseconds, which means the
Live Watch window will be updated once every second during program
execution. Note that this command is only available from this context menu in
the Live Watch window.
Save to File
Saves content to a file in a tab-separated format.
Statics window
The Statics window is available from the View menu.
This window displays the values of variables with static storage duration that you have
selected. Typically, that is variables with file scope but it can also be static variables in
functions and classes. Note that volatile declared variables with static storage
duration will not be displayed.
Every time execution in C-SPY stops, the values in the Statics window are recalculated.
Values that have changed since the last stop are highlighted in red.
C-SPY® Debugging Guide
88
for STM8
AFE1_AFE2-1:1
Variables and expressions
For information about editing in C-SPY windows, see C-SPY Debugger main window,
page 45.
To select variables to monitor:
1 In the window, right-click and choose Select statics from the context menu. The
window now lists all variables with static storage duration.
2 Either individually select the variables you want to be displayed, or choose Select All
or Deselect All from the context menu.
3 When you have made your selections, choose Select statics from the context menu to
toggle back to the normal display mode.
Requirements
None; this window is always available.
Display area
This area contains these columns:
Expression
The name of the variable. The base name of the variable is followed by the full
name, which includes module, class, or function scope. This column is not
editable.
Value
The value of the variable. Values that have changed are highlighted in red.
Dragging text or a variable from another window and dropping it on the Value
column will assign a new value to the variable in that row.
This column is editable.
Location
The location in memory where this variable is stored.
Type
The data type of the variable.
89
AFE1_AFE2-1:1
Reference information on working with variables and expressions
Context menu
This context menu is available:
These commands are available:
Default Format,
Binary Format,
Octal Format,
Decimal Format,
Hexadecimal Format,
Char Format
Changes the display format of expressions. The display format setting affects
different types of expressions in different ways. Your selection of display format
is saved between debug sessions. These commands are available if a selected
line in the window contains a variable.
The display format setting affects different types of expressions in these ways:
Variables
The display setting affects only the selected variable, not
other variables.
Array elements
The display setting affects the complete array, that is, the
same display format is used for each array element.
Structure fields
All elements with the same definition—the same field
name and C declaration type—are affected by the
display setting.
Select Statics
Lists all variables with static storage duration. Select the variables you want to
be monitored. When you have made your selections, select this menu command
again to toggle back to normal display mode.
C-SPY® Debugging Guide
90
for STM8
AFE1_AFE2-1:1
Variables and expressions
Select all
Selects all variables.
Deselect all
Deselects all variables.
Quick Watch window
The Quick Watch window is available from the View menu and from the context menu
in the editor window.
Use this window to watch the value of a variable or expression and evaluate expressions
at a specific point in time.
In contrast to the Watch window, the Quick Watch window gives you precise control
over when to evaluate the expression. For single variables this might not be necessary,
but for expressions with possible side effects, such as assignments and C-SPY macro
functions, it allows you to perform evaluations under controlled conditions.
For information about editing in C-SPY windows, see C-SPY Debugger main window,
page 45.
To evaluate an expression:
1 In the editor window, right-click on the expression you want to examine and choose
Quick Watch from the context menu that appears.
2 The expression will automatically appear in the Quick Watch window.
Alternatively:
3 In the Quick Watch window, type the expression you want to examine in the
Expressions text box.
4 Click the Recalculate button to calculate the value of the expression.
For an example, see Using C-SPY macros, page 227.
Requirements
None; this window is always available.
91
AFE1_AFE2-1:1
Reference information on working with variables and expressions
Context menu
This context menu is available:
These commands are available:
Default Format,
Binary Format,
Octal Format,
Decimal Format,
Hexadecimal Format,
Char Format
Changes the display format of expressions. The display format setting affects
different types of expressions in different ways. Your selection of display format
is saved between debug sessions. These commands are available if a selected
line in the window contains a variable.
The display format setting affects different types of expressions in these ways:
Variables
The display setting affects only the selected variable, not
other variables.
Array elements
The display setting affects the complete array, that is, the
same display format is used for each array element.
Structure fields
All elements with the same definition—the same field
name and C declaration type—are affected by the
display setting.
Show As
Displays a submenu that provides commands for changing the default type
interpretation of variables. The commands on this submenu are mainly useful
for assembler variables—data at assembler labels—because these are, by
default, displayed as integers. For more information, see Viewing assembler
variables, page 78.
C-SPY® Debugging Guide
92
for STM8
AFE1_AFE2-1:1
Variables and expressions
Options
Displays the IDE Options dialog box where you can set the Update interval
option. The default value of this option is 1000 milliseconds, which means the
Live Watch window will be updated once every second during program
execution. Note that this command is only available from this context menu in
the Live Watch window.
Save to File
Saves content to a file in a tab-separated format.
Symbols window
The Symbols window is available from the View menu after you have enabled the
Symbols plugin module.
This window displays all symbols with a static location, that is, C/C++ functions,
assembler labels, and variables with static storage duration, including symbols from the
runtime library.
To enable the Symbols plugin module, choose Project>Options>Debugger>Select
plugins to load>Symbols.
Requirements
None; this window is always available.
Display area
This area contains these columns:
Symbol
The symbol name.
Location
The memory address.
93
AFE1_AFE2-1:1
Reference information on working with variables and expressions
Full name
The symbol name; often the same as the contents of the Symbol column but
differs for example for C++ member functions.
Click the column headers to sort the list by symbol name, location, or full name.
Context menu
This context menu is available:
These commands are available:
Functions
Toggles the display of function symbols on or off in the list.
Variables
Toggles the display of variables on or off in the list.
Labels
Toggles the display of labels on or off in the list.
Resolve Symbol Ambiguity dialog box
The Resolve Symbol Ambiguity dialog box appears, for example, when you specify a
symbol in the Disassembly window to go to, and there are several instances of the same
symbol due to templates or function overloading.
Requirements
None; this window is always available.
C-SPY® Debugging Guide
94
for STM8
AFE1_AFE2-1:1
Variables and expressions
Ambiguous symbol
Indicates which symbol that is ambiguous.
Please select one symbol
A list of possible matches for the ambiguous symbol. Select the one you want to use.
Data Log window
The Data Log window is available from the C-SPY driver menu.
Use this window to log accesses to up to four different memory locations or areas.
See also Getting started using data logging, page 79.
Requirements
The C-SPY simulator.
Display area
Each row in the display area shows the time, the program counter, and, for every tracked
data object, its value and address in these columns:
Time
If the time is displayed in italics, the target system has not been able to collect a
correct time, but instead had to approximate it.
This column is available when you have selected Show time from the context
menu.
95
AFE1_AFE2-1:1
Reference information on working with variables and expressions
Cycles
The number of cycles from the start of the execution until the event. This
information is cleared at reset.
If a cycle is displayed in italics, the target system has not been able to collect a
correct time, but instead had to approximate it.
This column is available when you have selected Show cycles from the context
menu.
Program Counter*
Displays one of these:
An address, which is the content of the PC, that is, the address of the instruction
that performed the memory access.
---, the target system failed to provide the debugger with any information.
Overflow in red, the communication channel failed to transmit all data from the
target system.
Value
Displays the access type and the value (using the access size) for the location or
area you want to log accesses to. For example, if zero is read using a byte access
it will be displayed as 0x00, and for a long access it will be displayed as
0x00000000.
To specify what data you want to log accesses to, use the Data Log breakpoint
dialog box. See Data Log breakpoints, page 109.
Address
The actual memory address that is accessed. For example, if only a byte of a
word is accessed, only the address of the byte is displayed. The address is
calculated as base address + offset, where the base address is retrieved from the
Data Log breakpoint dialog box and the offset is retrieved from the logs. If the
log from the target system does not provide the debugger with an offset, the
offset contains + ?.
* You can double-click a line in the display area. If the value of the PC for that line is
available in the source code, the editor window displays the corresponding source code
(this does not include library source code).
Context menu
Identical to the context menu of the Interrupt Log window, see Interrupt Log window,
page 219.
C-SPY® Debugging Guide
96
for STM8
AFE1_AFE2-1:1
Variables and expressions
Data Log Summary window
The Data Log Summary window is available from the C-SPY driver menu.
This window displays a summary of data accesses to specific memory location or areas.
See also Getting started using data logging, page 79.
Requirements
The C-SPY simulator.
Display area
Each row in this area displays the type and the number of accesses to each memory
location or area in these columns:
Data
The name of the data object you have selected to log accesses to. To specify
what data object you want to log accesses to, use the Data Log breakpoint
dialog box. See Data Log breakpoints, page 109.
The current time or cycles is displayed—execution time since the start of
execution or the number of cycles. Overflow count displays the number of
overflows.
Total Accesses
The number of total accesses.
If the sum of read accesses and write accesses is less than the total accesses,
there have been a number of access logs for which the target system for some
reason did not provide valid access type information.
Read Accesses
The number of total read accesses.
Write Accesses
The number of total write accesses.
97
AFE1_AFE2-1:1
Reference information on working with variables and expressions
Unknown Accesses
The number of unknown accesses, in other words, accesses where the access
type is not known.
Display area
Each row in this area displays the type and the number of accesses to each memory
location or area in these columns:
Data
The name of the data object you have selected to log accesses to. To specify
what data object you want to log accesses to, use the Data Log breakpoint
dialog box. See Data Log breakpoints, page 109.
The current time or cycles is displayed—execution time since the start of
execution or the number of cycles. Overflow count displays the number of
overflows.
Total Accesses
The number of total accesses.
If the sum of read accesses and write accesses is less than the total accesses,
there have been a number of access logs for which the target system for some
reason did not provide valid access type information.
Read Accesses
The number of total read accesses.
Write Accesses
The number of total write accesses.
Unknown Accesses
The number of unknown accesses, in other words, accesses where the access
type is not known.
C-SPY® Debugging Guide
98
for STM8
AFE1_AFE2-1:1
Variables and expressions
Setup Data Sample window
The Data Sample Setup window is available from the C-SPY driver menu.
Use this window to specify up to four variables to sample data for. You can view the
sampled data for the variables either in the Data Sample window or as graphs in the
Sampled Graphs window.
See also Getting started using data sampling, page 78.
Requirements
One of these alternatives:
●
The C-SPY ST-LINK driver
●
The C-SPY STice driver.
Display area
This area contains these columns:
Expression
Type the name of the variable which must be an integral type with a maximum
size of 32 bits. Click the checkbox to enable or disable data sampling for the
variable.
Alternatively, drag an expression from the editor window and drop it in the
display area.
Variables in the expressions must be statically located, for example global
variables.
Address
The actual memory address that is accessed. The column cells cannot be edited.
Size
The size of the variable, either 1, 2, or 4 bytes. The column cells cannot be
edited.
99
AFE1_AFE2-1:1
Reference information on working with variables and expressions
Sampling interval [ms]
Type the number of milliconds to pass between the samples, defined in
milliseconds. The shortest allowed interval is 10 ms and the interval you specify
must be a multiple of that.
Context menu
This context menu is available:
These commands are available:
Remove
Removes the selected variable.
Remove All
Removes all variables.
Data Sample window
The Data Sample window is available from the C-SPY driver menu.
Use this window to view the result of the data sampling for the variables you have
selected in the Data Sample Setup window.
Choose Enable from the context menu to enable data sampling.
See also Getting started using data sampling, page 78.
Requirements
C-SPY® Debugging Guide
100
for STM8
AFE1_AFE2-1:1
●
The C-SPY ST-LINK driver
●
The C-SPY STice driver.
Variables and expressions
Display area
This area contains these columns:
Sampling Time
The time when the data sample was collected. Time starts at zero after a reset.
Every time the execution stops, a red Stop indicates when the stop occurred.
The selected expression
The column headers display the names of the variables that you selected in the
Data Sample Setup window. The column cells display the sampling values for
the variable.
There can be up to four colums of this type, one for each selected variable.
* You can double-click a row in the display area. If you have enabled the data sample
graph in the Sampled Graphs window, the selection line will be moved to reflect the time
of the row you double-clicked.
Context menu
This context menu is available:
These commands are available:
Enable
Enables data sampling.
Clear
Clears the sampled data.
Hexadecimal (for var)
Toggles between displaying the values of selected variable in decimal or
hexadecimal format. The display format affects the Data Sample window and
the Sampled Graphs window.
Save to Log File
Displays a standard save dialog box.
Open setup window
Opens the Data Sample Setup window.
101
AFE1_AFE2-1:1
Reference information on working with variables and expressions
Sampled Graphs window
The Sampled Graphs window is available from the C-SPY driver menu.
Use this window to display graphs for up to four different variables, and where:
●
The graph displays how the value of the variable changes over time. The area on the
left displays the limits, or range, of the Y-axis for the variable. You can use the
context menu to change these limits. The graph is a graphical representation of the
information in the Data Sample window, see Data Sample window, page 100.
●
The graph can be displayed as levels, where a horizontal line—optionally
color-filled—shows the value until the next sample. Alternatively, the graph can be
linear, where a line connects consecutive samples.
●
A red vertical line indicates the time of application execution stops.
At the bottom of the window, there is a common time axis that uses seconds as the time
unit.
To navigate in the graph, use any of these alternatives:
●
Right-click and choose Zoom In or Zoom Out from the context menu.
Alternatively, use the + and - keys to zoom.
●
Right-click in the graph and choose Navigate and the appropriate command to
move backward and forward on the graph. Alternatively, use any of the shortcut
keys: arrow keys, Home, End, and Ctrl+End.
●
Double-click on a sample to highlight the corresponding source code in the editor
window and in the Disassembly window.
●
Click on the graph and drag to select a time interval. Press Enter or right-click and
choose Zoom>Zoom to Selection from the context menu. The selection zooms in.
Hover with the mouse pointer in the graph to get detailed tooltip information for that
location.
C-SPY® Debugging Guide
102
for STM8
AFE1_AFE2-1:1
Variables and expressions
See also Getting started using data sampling, page 78.
Requirements
●
The C-SPY ST-LINK driver
●
The C-SPY STice driver.
Context menu
This context menu is available:
These commands are available:
Navigate
Commands for navigating in the graphs. Choose between:
Next moves the selection to the next relevant point in the graph. Shortcut key:
right arrow.
Previous moves the selection to the previous relevant point in the graph.
Shortcut key: left arrow.
First moves the selection to the first data entry in the graph. Shortcut key:
Home.
Last moves the selection to the last data entry in the graph. Shortcut key: End.
End moves the selection to the last data in any displayed graph, in other words
the end of the time axis. Shortcut key: Ctrl+End.
Auto Scroll
Toggles auto scrolling on or off. When on, the most recently collected data is
automatically displayed if you have executed the command Navigate>End.
103
AFE1_AFE2-1:1
Reference information on working with variables and expressions
Zoom
Commands for zooming the window, in other words, changing the time scale.
Choose between:
Zoom to Selection makes the current selection fit the window. Shortcut key:
Return.
Zoom In zooms in on the time scale. Shortcut key: +.
Zoom Out zooms out on the time scale. Shortcut key: -.
1us, 10us, 100us makes an interval of 1 microseconds, 10 microseconds, or 100
microseconds, respectively, fit the window.
1ms, 10ms, 100ms makes an interval of 1 millisecond, 10 milliseconds, or 100
milliseconds, respectively, fit the window.
1s, 10s, 100s makes an interval of 1 second, 10 seconds, or 100 seconds,
respectively, fit the window.
1k s, 10k s, 100k s makes an interval of 1,000 seconds, 10,000 seconds, or
100,000 seconds, respectively, fit the window.
1M s, 10M s, makes an interval of 1,000,000 seconds or 10,000,000 seconds,
respectively, fit the window.
Data Sample
A menu item that shows that the Data Sample-specific commands below are
available.
Open Setup window (Data Sample Graph)
Opens the Data Sample Setup window.
Enable
Toggles the display of the graph on or off. If you disable a graph, that graph will
be indicated as OFF in the Data Sample window. If no data has been sampled for
a graph, no data will appear instead of the graph.
Clear
Clears the sampled data.
Variable
The name of the variable for which the Data Sample-specific commands below
apply. This menu item is context-sensitive, which means it reflects the Data
Sample Graph you selected in the Sampled Graphs window (one of up to four).
Viewing Range
Displays a dialog box, see Viewing Range dialog box, page 181.
C-SPY® Debugging Guide
104
for STM8
AFE1_AFE2-1:1
Variables and expressions
Size
Controls the vertical size of the graph; choose between Small, Medium, and
Large.
Style
Choose how to display the graph. Choose between:
Levels, where a horizontal line—optionally color-filled—shows the value until
the next sample.
Linear, where a line connects consecutive samples.
Solid Graph
Displays the graph as a color-filled solid graph instead of as a thin line. This is
only possible if the graph is displayed as Levels.
Hexadecimal (for var)
Toggles between displaying the selected variable in decimal or hexadecimal
format. The display format affects the Data Sample window and the Sampled
Graphs window.
Show Numerical Value
Shows the numerical value of the variable, in addition to the graph.
Select Graphs
Selects which graphs to display in the Sampled Graphs window.
105
AFE1_AFE2-1:1
Reference information on working with variables and expressions
C-SPY® Debugging Guide
106
for STM8
AFE1_AFE2-1:1
Breakpoints
Breakpoints
●
Introduction to setting and using breakpoints
●
Setting breakpoints
●
Reference information on breakpoints
Introduction to setting and using breakpoints
These topics are covered:
●
Reasons for using breakpoints
●
Briefly about setting breakpoints
●
Breakpoint types
●
Breakpoint icons
●
Breakpoints in the C-SPY simulator
●
Breakpoints in the C-SPY hardware debugger drivers
●
Breakpoint consumers
REASONS FOR USING BREAKPOINTS
C-SPY® lets you set various types of breakpoints in the application you are debugging,
allowing you to stop at locations of particular interest. You can set a breakpoint at a code
location to investigate whether your program logic is correct, or to get trace printouts.
In addition to code breakpoints, and depending on what C-SPY driver you are using,
additional breakpoint types might be available. For example, you might be able to set a
data breakpoint, to investigate how and when the data changes.
You can let the execution stop under certain conditions, which you specify. You can also
let the breakpoint trigger a side effect, for instance executing a C-SPY macro function,
by transparently stopping the execution and then resuming. The macro function can be
defined to perform a wide variety of actions, for instance, simulating hardware behavior.
All these possibilities provide you with a flexible tool for investigating the status of your
application.
BRIEFLY ABOUT SETTING BREAKPOINTS
You can set breakpoints in many various ways, allowing for different levels of
interaction, precision, timing, and automation. All the breakpoints you define will
107
AFE1_AFE2-1:1
Introduction to setting and using breakpoints
appear in the Breakpoints window. From this window you can conveniently view all
breakpoints, enable and disable breakpoints, and open a dialog box for defining new
breakpoints. The Breakpoint Usage window also lists all internally used breakpoints,
see Breakpoint consumers, page 111.
Breakpoints are set with a higher precision than single lines, using the same mechanism
as when stepping; for more information about the precision, see Single stepping, page
56.
You can set breakpoints while you edit your code even if no debug session is active. The
breakpoints will then be validated when the debug session starts. Breakpoints are
preserved between debug sessions.
Note: For most hardware debugger systems it is only possible to set breakpoints when
the application is not executing.
BREAKPOINT TYPES
Depending on the C-SPY driver you are using, C-SPY supports different types of
breakpoints.
Code breakpoints
Code breakpoints are used for code locations to investigate whether your program logic
is correct or to get trace printouts. Code breakpoints are triggered when an instruction is
fetched from the specified location. If you have set the breakpoint on a specific machine
instruction, the breakpoint will be triggered and the execution will stop, before the
instruction is executed.
Advanced breakpoints
Using the C-SPY ST-LINK driver, you can set advanced breakpoints. For this
breakpoint type, you can choose to use data values, fetch conditions, and data accesses
as breakpoint conditions.
Log breakpoints
Log breakpoints provide a convenient way to add trace printouts without having to add
any code to your application source code. Log breakpoints are triggered when an
instruction is fetched from the specified location. If you have set the breakpoint on a
specific machine instruction, the breakpoint will be triggered and the execution will
temporarily stop and print the specified message in the C-SPY Debug Log window.
Trace Start and Stop breakpoints
Trace Start and Stop breakpoints start and stop trace data collection—a convenient way
to analyze instructions between two execution points.
C-SPY® Debugging Guide
108
for STM8
AFE1_AFE2-1:1
Breakpoints
Data breakpoints
Data breakpoints are primarily useful for variables that have a fixed address in memory.
If you set a breakpoint on an accessible local variable, the breakpoint is set on the
corresponding memory location. The validity of this location is only guaranteed for
small parts of the code. Data breakpoints are triggered when data is accessed at the
specified location. The execution will usually stop directly after the instruction that
accessed the data has been executed.
Data Log breakpoints
Data Log breakpoints are triggered when data is accessed at the specified location. If
you have set a breakpoint on a specific address or a range, a log message is displayed in
the Data Log window for each access to that location. Data logs can also be displayed
on the Data Log graph in the Timeline window, if that window is enabled.
Immediate breakpoints
The C-SPY Simulator lets you set immediate breakpoints, which will halt instruction
execution only temporarily. This allows a C-SPY macro function to be called when the
simulated processor is about to read data from a location or immediately after it has
written data. Instruction execution will resume after the action.
This type of breakpoint is useful for simulating memory-mapped devices of various
kinds (for instance serial ports and timers). When the simulated processor reads from a
memory-mapped location, a C-SPY macro function can intervene and supply
appropriate data. Conversely, when the simulated processor writes to a memory-mapped
location, a C-SPY macro function can act on the value that was written.
BREAKPOINT ICONS
A breakpoint is marked with an icon in the left margin of the editor window, and the icon
varies with the type of breakpoint:
If the breakpoint icon does not appear, make sure the option Show bookmarks is
selected, see Editor options in the IDE Project Management and Building Guide.
109
AFE1_AFE2-1:1
Introduction to setting and using breakpoints
Just point at the breakpoint icon with the mouse pointer to get detailed tooltip
information about all breakpoints set on the same location. The first row gives user
breakpoint information, the following rows describe the physical breakpoints used for
implementing the user breakpoint. The latter information can also be seen in the
Breakpoint Usage window.
Note: The breakpoint icons might look different for the C-SPY driver you are using.
BREAKPOINTS IN THE C-SPY SIMULATOR
The C-SPY simulator supports all breakpoint types and you can set an unlimited amount
of breakpoints.
BREAKPOINTS IN THE C-SPY HARDWARE DEBUGGER
DRIVERS
Using the C-SPY drivers for hardware debugger systems you can set various breakpoint
types. The amount of breakpoints you can set depends on the number of hardware
breakpoints available on the target system.
The number of code breakpoints you can set in RAM and flash memory is unlimited.
Depending on your debugger system, the number of code breakpoints you can set in
ROM might be limited.
This table summarizes the characteristics of breakpoints for the different target systems:
Code
Data
Advanced
breakpoints
breakpoints
breakpoints
using N hardware breakpoints*
2*
1†
1†
using software breakpoints
Unlimited*
Unlimited
Unlimited
C-SPY hardware debugger driver
ST-LINK
STice
using N hardware breakpoints*
2
--
--
using software breakpoints
Unlimited
--
--
Table 6: Available breakpoints in C-SPY hardware debugger drivers
* The number of available code breakpoints in ROM is limited to 2.
† The number of available data breakpoints and advanced breakpoints depends on the
target system you are using.
If the driver and the device support software breakpoints, the debugger will first use any
available hardware breakpoints before using software breakpoints. Exceeding the
number of available hardware breakpoints causes the debugger to single step. This will
significantly reduce the execution speed. For this reason you must be aware of the
different breakpoint consumers.
C-SPY® Debugging Guide
110
for STM8
AFE1_AFE2-1:1
Breakpoints
BREAKPOINT CONSUMERS
A debugger system includes several consumers of breakpoints.
User breakpoints
The breakpoints you define in the breakpoint dialog box or by toggling breakpoints in
the editor window often consume one physical breakpoint each, but this can vary greatly.
Some user breakpoints consume several physical breakpoints and conversely, several
user breakpoints can share one physical breakpoint. User breakpoints are displayed in
the same way both in the Breakpoint Usage window and in the Breakpoints window, for
example Data @[R] callCount.
C-SPY itself
C-SPY itself also consumes breakpoints. C-SPY will set a breakpoint if:
●
The debugger option Run to has been selected, and any step command is used.
These are temporary breakpoints which are only set during a debug session. This
means that they are not visible in the Breakpoints window.
●
The linker option Include C-SPY debugging support has been selected.
In the DLIB runtime environment, C-SPY will set a system breakpoint on the
__DebugBreak label.
These types of breakpoint consumers are displayed in the Breakpoint Usage window, for
example, C-SPY Terminal I/O & libsupport module.
C-SPY plugin modules
For example, modules for real-time operating systems can consume additional
breakpoints. Specifically, by default, the Stack window consumes one physical
breakpoint.
To disable the breakpoint used by the Stack window:
1 Choose Tools>Options>Stack.
2 Deselect the Stack pointer(s) not valid until program reaches: label option.
To disable the Stack window entirely, choose Project>Options>Debugger>Plugins
and deselect the Stack plugin.
Setting breakpoints
These tasks are covered:
●
Various ways to set a breakpoint
111
AFE1_AFE2-1:1
Setting breakpoints
●
Toggling a simple code breakpoint
●
Setting breakpoints using the dialog box
●
Setting a data breakpoint in the Memory window
●
Setting breakpoints using system macros
●
Useful breakpoint hints.
VARIOUS WAYS TO SET A BREAKPOINT
You can set a breakpoint in various ways:
●
Toggling a simple code breakpoint.
●
Using the New Breakpoints dialog box and the Edit Breakpoints dialog box
available from the context menus in the editor window, Breakpoints window, and in
the Disassembly window. The dialog boxes give you access to all breakpoint
options.
●
Setting a data breakpoint on a memory area directly in the Memory window.
●
Using predefined system macros for setting breakpoints, which allows automation.
The different methods offer different levels of simplicity, complexity, and automation.
TOGGLING A SIMPLE CODE BREAKPOINT
Toggling a code breakpoint is a quick method of setting a breakpoint. The following
methods are available both in the editor window and in the Disassembly window:
●
Click in the gray left-side margin of the window
●
Place the insertion point in the C source statement or assembler instruction where
you want the breakpoint, and click the Toggle Breakpoint button in the toolbar
●
Choose Edit>Toggle Breakpoint
●
Right-click and choose Toggle Breakpoint from the context menu.
SETTING BREAKPOINTS USING THE DIALOG BOX
The advantage of using a breakpoint dialog box is that it provides you with a graphical
interface where you can interactively fine-tune the characteristics of the breakpoints.
You can set the options and quickly test whether the breakpoint works according to your
intentions.
All breakpoints you define using a breakpoint dialog box are preserved between debug
sessions.
You can open the dialog box from the context menu available in the editor window,
Breakpoints window, and in the Disassembly window.
C-SPY® Debugging Guide
112
for STM8
AFE1_AFE2-1:1
Breakpoints
To set a new breakpoint:
1 Choose View>Breakpoints to open the Breakpoints window.
2 In the Breakpoints window, right-click, and choose New Breakpoint from the context
menu.
3 On the submenu, choose the breakpoint type you want to set.
Depending on the C-SPY driver you are using, different breakpoint types are available.
4 In the breakpoint dialog box that appears, specify the breakpoint settings and click OK.
The breakpoint is displayed in the Breakpoints window.
To modify an existing breakpoint:
1 In the Breakpoints window, editor window, or in the Disassembly window, select the
breakpoint you want to modify and right-click to open the context menu.
If there are several breakpoints on the same source code line, the breakpoints will be
listed on a submenu.
2 On the context menu, choose the appropriate command.
3 In the breakpoint dialog box that appears, specify the breakpoint settings and click OK.
The breakpoint is displayed in the Breakpoints window.
113
AFE1_AFE2-1:1
Setting breakpoints
SETTING A DATA BREAKPOINT IN THE MEMORY WINDOW
You can set breakpoints directly on a memory location in the Memory window.
Right-click in the window and choose the breakpoint command from the context menu
that appears. To set the breakpoint on a range, select a portion of the memory contents.
The breakpoint is not highlighted in the Memory window; instead, you can see, edit, and
remove it using the Breakpoints window, which is available from the View menu. The
breakpoints you set in the Memory window will be triggered for both read and write
accesses. All breakpoints defined in this window are preserved between debug sessions.
Note: Setting breakpoints directly in the Memory window is only possible if the driver
you use supports this.
SETTING BREAKPOINTS USING SYSTEM MACROS
You can set breakpoints not only in the breakpoint dialog box but also by using built-in
C-SPY system macros. When you use system macros for setting breakpoints, the
breakpoint characteristics are specified as macro parameters.
Macros are useful when you have already specified your breakpoints so that they fully
meet your requirements. You can define your breakpoints in a macro file, using built-in
system macros, and execute the file at C-SPY startup. The breakpoints will then be set
automatically each time you start C-SPY. Another advantage is that the debug session
will be documented, and that several engineers involved in the development project can
share the macro files.
Note: If you use system macros for setting breakpoints, you can still view and modify
them in the Breakpoints window. In contrast to using the dialog box for defining
breakpoints, all breakpoints that are defined using system macros are removed when you
exit the debug session.
C-SPY® Debugging Guide
114
for STM8
AFE1_AFE2-1:1
Breakpoints
These breakpoint macros are available:
C-SPY macro for breakpoints
Simulator
ST-LINK
STice
__setCodeBreak
Yes
Yes
Yes
__setDataBreak
Yes
Yes
—
__setLogBreak
Yes
—
—
__setDataLogBreak
Yes
—
—
__setSimBreak
Yes
—
—
__setTraceStartBreak
Yes
—
—
__setTraceStopBreak
Yes
—
—
__clearBreak
Yes
Yes
Yes
Table 7: C-SPY macros for breakpoints
For information about each breakpoint macro, see Reference information on C-SPY
system macros, page 239.
Setting breakpoints at C-SPY startup using a setup macro file
You can use a setup macro file to define breakpoints at C-SPY startup. Follow the
procedure described in Using C-SPY macros, page 227.
USEFUL BREAKPOINT HINTS
Below are some useful hints related to setting breakpoints.
Tracing incorrect function arguments
If a function with a pointer argument is sometimes incorrectly called with a NULL
argument, you might want to debug that behavior. These methods can be useful:
●
Set a breakpoint on the first line of the function with a condition that is true only
when the parameter is 0. The breakpoint will then not be triggered until the
problematic situation actually occurs. The advantage of this method is that no extra
source code is needed. The drawback is that the execution speed might become
unacceptably low.
●
You can use the assert macro in your problematic function, for example:
int MyFunction(int * MyPtr)
{
assert(MyPtr != 0); /* Assert macro added to your source
code. */
/* Here comes the rest of your function. */
}
115
AFE1_AFE2-1:1
Setting breakpoints
The execution will break whenever the condition is true. The advantage is that the
execution speed is only very slightly affected, but the drawback is that you will get a
small extra footprint in your source code. In addition, the only way to get rid of the
execution stop is to remove the macro and rebuild your source code.
●
Instead of using the assert macro, you can modify your function like this:
int MyFunction(int * MyPtr)
{
if(MyPtr == 0)
MyDummyStatement; /* Dummy statement where you set a
breakpoint. */
/* Here comes the rest of your function. */
}
You must also set a breakpoint on the extra dummy statement, so that the execution
will break whenever the condition is true. The advantage is that the execution speed
is only very slightly affected, but the drawback is that you will still get a small extra
footprint in your source code. However, in this way you can get rid of the execution
stop by just removing the breakpoint.
Performing a task and continuing execution
You can perform a task when a breakpoint is triggered and then automatically continue
execution.
You can use the Action text box to associate an action with the breakpoint, for instance
a C-SPY macro function. When the breakpoint is triggered and the execution of your
application has stopped, the macro function will be executed. In this case, the execution
will not continue automatically.
Instead, you can set a condition which returns 0 (false). When the breakpoint is
triggered, the condition—which can be a call to a C-SPY macro that performs a task—
is evaluated and because it is not true, execution continues.
Consider this example where the C-SPY macro function performs a simple task:
__var my_counter;
count()
{
my_counter += 1;
return 0;
}
To use this function as a condition for the breakpoint, type count() in the Expression
text box under Conditions. The task will then be performed when the breakpoint is
triggered. Because the macro function count returns 0, the condition is false and the
execution of the program will resume automatically, without any stop.
C-SPY® Debugging Guide
116
for STM8
AFE1_AFE2-1:1
Breakpoints
Reference information on breakpoints
Reference information about:
●
Breakpoints window, page 117
●
Breakpoint Usage window, page 119
●
Advanced breakpoints dialog box, page 120
●
Code breakpoints dialog box, page 123
●
Log breakpoints dialog box, page 124
●
Data breakpoints dialog box, page 126
●
Data Log breakpoints dialog box, page 128
●
Immediate breakpoints dialog box, page 129
●
Enter Location dialog box, page 130
●
Resolve Source Ambiguity dialog box, page 131.
See also:
●
Reference information on C-SPY system macros, page 239
●
Reference information on trace, page 168.
Breakpoints window
The Breakpoints window is available from the View menu.
The Breakpoints window lists all breakpoints you define.
Use this window to conveniently monitor, enable, and disable breakpoints; you can also
define new breakpoints and modify existing breakpoints.
Requirements
None; this window is always available.
117
AFE1_AFE2-1:1
Reference information on breakpoints
Display area
This area lists all breakpoints you define. For each breakpoint, information about the
breakpoint type, source file, source line, and source column is provided.
Context menu
This context menu is available:
These commands are available:
Go to Source
Moves the insertion point to the location of the breakpoint, if the breakpoint has
a source location. Double-click a breakpoint in the Breakpoints window to
perform the same command.
Edit
Opens the breakpoint dialog box for the breakpoint you selected.
Delete
Deletes the breakpoint. Press the Delete key to perform the same command.
Enable
Enables the breakpoint. The check box at the beginning of the line will be
selected. You can also perform the command by manually selecting the check
box. This command is only available if the breakpoint is disabled.
Disable
Disables the breakpoint. The check box at the beginning of the line will be
deselected. You can also perform this command by manually deselecting the
check box. This command is only available if the breakpoint is enabled.
Enable All
Enables all defined breakpoints.
Disable All
Disables all defined breakpoints.
C-SPY® Debugging Guide
118
for STM8
AFE1_AFE2-1:1
Breakpoints
New Breakpoint
Displays a submenu where you can open the breakpoint dialog box for the
available breakpoint types. All breakpoints you define using this dialog box are
preserved between debug sessions.
Breakpoint Usage window
The Breakpoint Usage window is available from the menu specific to the C-SPY driver
you are using.
The Breakpoint Usage window lists all breakpoints currently set in the target system,
both the ones you have defined and the ones used internally by C-SPY. The format of
the items in this dialog box depends on the C-SPY driver you are using.
The window gives a low-level view of all breakpoints, related but not identical to the list
of breakpoints displayed in the Breakpoints window.
C-SPY uses breakpoints when stepping. se the Breakpoint Usage window for:
●
Identifying all breakpoint consumers
●
Checking that the number of active breakpoints is supported by the target system
●
Configuring the debugger to use the available breakpoints in a better way, if
possible.
Requirements
None; this window is always available.
Display area
For each breakpoint in the list, the address and access type are displayed. Each
breakpoint in the list can also be expanded to show its originator.
119
AFE1_AFE2-1:1
Reference information on breakpoints
Advanced breakpoints dialog box
The Advanced Breakpoint dialog box is available from the context menu in the
Breakpoints window.
Use this dialog box to set an advanced breakpoint for which you can choose to use data
values, fetch conditions, and data accesses as breakpoint conditions.
Depending on which breakpoint type you have chosen, different settings are available.
Descriptions of the breakpoint types and their settings follow.
Requirements
●
The C-SPY ST-LINK driver
●
The C-SPY STice driver, using SWIM mode.
Break on data value at a given address
This breakpoint type breaks on the occurrence of a specific value at a specified data
address.
Access mode
Choose between: Write, Read, and Read/Write.
Address
Specify the address where the value is stored.
Data value
Specify the data value at the specified address.
Break on operation code fetch within or outside an address range
These breakpoint types break on the occurrence of any operation code fetch within or
outside of a specified address range, respectively.
First address
Specify the first address of the range.
C-SPY® Debugging Guide
120
for STM8
AFE1_AFE2-1:1
Breakpoints
Last address
Specify the last address of the range.
Break on data access within or outside an address range
These breakpoint types break on the occurrence of a data access within or outside a
specified address range.
Access mode
Choose between: Write, Read, and Read/Write.
First address
Specify the first address of the range.
Last address
Specify the last address of the range.
Break on two sequential operation code fetches
This breakpoint type breaks when two operation code fetches have occurred in
sequence; the occurrence of the first operation code fetch must precede the occurrence
of the second operation code fetch.
First address
Specify the address where the first operation code fetch must occur.
Second address
Specify the address where the second operation code fetch must occur.
Break on data access at one of two addresses
This breakpoint breaks on the occurrence of a data access at either of two addresses.
Access mode
Choose between: Write, Read, and Read/Write.
First address
Specify the first of the two addresses.
Second address
Specify the second of the two addresses.
Break on operation code fetch or data access at given addresses
This breakpoint type breaks either on the occurrence of an operation code fetch at a
specified address, or the occurrence of a data access at a specified address.
121
AFE1_AFE2-1:1
Reference information on breakpoints
Access mode
Choose between: Write, Read, and Read/Write.
Fetch address
Specify the address where the operation code fetch must occur.
Data address
Specify the address where the data access must occur.
Break on stack write or operation code fetch at a given address
This breakpoint type breaks on the occurrence of either a write operation to the stack
below a specified address, or an operation code fetch at a specified address.
Max stack address
Specify the maximum stack address below which the write operation must
occur.
Fetch address
Specify the address where the operation code fetch must occur.
Break on stack write or data access at a given address
This breakpoint type breaks on the occurrence of either a write operation to the stack
below a specified address, or a data access at a specified address.
Access mode
Choose between: Write, Read, and Read/Write.
Data address
Specify the address where the data access must occur.
Max stack address
Specify the maximum stack address below which the write operation must
occur.
C-SPY® Debugging Guide
122
for STM8
AFE1_AFE2-1:1
Breakpoints
Code breakpoints dialog box
The Code breakpoints dialog box is available from the context menu in the editor
window, Breakpoints window, and in the Disassembly window.
This figure reflects the C-SPY simulator.
Use the Code breakpoints dialog box to set a code breakpoint.
Requirements
One of these alternatives:
●
The C-SPY simulator
●
The C-SPY ST-LINK driver
●
The C-SPY STice driver.
Break At
Specify the code location of the breakpoint in the text box. Alternatively, click the Edit
button to open the Enter Location dialog box, see Enter Location dialog box, page 130.
Size
Determines whether there should be a size—in practice, a range—of locations where the
breakpoint will trigger. Each fetch access to the specified memory range will trigger the
breakpoint. Select how to specify the size:
Auto
The size will be set automatically, typically to 1.
Manual
Specify the size of the breakpoint range in the text box.
123
AFE1_AFE2-1:1
Reference information on breakpoints
Action
Specify a valid C-SPY expression, which is evaluated when the breakpoint is triggered
and the condition is true. For more information, see Useful breakpoint hints, page 115.
Conditions
Specify simple or complex conditions:
Expression
Specify a valid C-SPY expression, see C-SPY expressions, page 74.
Condition true
The breakpoint is triggered if the value of the expression is true.
Condition changed
The breakpoint is triggered if the value of the expression has changed since it
was last evaluated.
Skip count
The number of times that the breakpoint condition must be fulfilled before the
breakpoint starts triggering. After that, the breakpoint will trigger every time the
condition is fulfilled.
Log breakpoints dialog box
The Log breakpoints dialog box is available from the context menu in the editor
window, Breakpoints window, and in the Disassembly window.
This figure reflects the C-SPY simulator.
Use the Log breakpoints dialog box to set a log breakpoint.
C-SPY® Debugging Guide
124
for STM8
AFE1_AFE2-1:1
Breakpoints
Requirements
The C-SPY simulator.
Trigger at
Specify the code location of the breakpoint. Alternatively, click the Edit button to open
the Enter Location dialog box, see Enter Location dialog box, page 130.
Message
Specify the message you want to be displayed in the C-SPY Debug Log window. The
message can either be plain text, or—if you also select the option C-SPY macro
"__message" style—a comma-separated list of arguments.
C-SPY macro "__message" style
Select this option to make a comma-separated list of arguments specified in the Message
text box be treated exactly as the arguments to the C-SPY macro language statement
__message, see Formatted output, page 235.
Conditions
Specify simple or complex conditions:
Expression
Specify a valid C-SPY expression, see C-SPY expressions, page 74.
Condition true
The breakpoint is triggered if the value of the expression is true.
Condition changed
The breakpoint is triggered if the value of the expression has changed since it
was last evaluated.
125
AFE1_AFE2-1:1
Reference information on breakpoints
Data breakpoints dialog box
The Data breakpoints dialog box is available from the context menu in the editor
window, Breakpoints window, the Memory window, and in the Disassembly window.
This figure reflects the C-SPY simulator.
Use the Data breakpoints dialog box to set a data breakpoint. Data breakpoints never
stop execution within a single instruction. They are recorded and reported after the
instruction is executed.
Requirements
One of these alternatives:
●
The C-SPY simulator
●
The C-SPY ST-LINK driver.
Break At
Specify the data location of the breakpoint in the text box. Alternatively, click the Edit
button to open the Enter Location dialog box, see Enter Location dialog box, page 130.
Access Type
Selects the type of memory access that triggers the breakpoint:
Read/Write
Reads from or writes to location.
Read
Reads from location.
C-SPY® Debugging Guide
126
for STM8
AFE1_AFE2-1:1
Breakpoints
Write
Writes to location.
Size
Determines whether there should be a size—in practice, a range—of locations where the
breakpoint will trigger. Each fetch access to the specified memory range will trigger the
breakpoint. Select how to specify the size:
Auto
The size will automatically be based on the type of expression the breakpoint is
set on. For example, if you set the breakpoint on a 12-byte structure, the size of
the breakpoint will be 12 bytes.
Manual
Specify the size of the breakpoint range in the text box.
For data breakpoints, this can be useful if you want the breakpoint to be triggered on
accesses to data structures, such as arrays, structs, and unions.
Action
Specify a valid C-SPY expression, which is evaluated when the breakpoint is triggered
and the condition is true. For more information, see Useful breakpoint hints, page 115.
Conditions
Specify simple or complex conditions:
Expression
Specify a valid C-SPY expression, see C-SPY expressions, page 74.
Condition true
The breakpoint is triggered if the value of the expression is true.
Condition changed
The breakpoint is triggered if the value of the expression has changed since it
was last evaluated.
Skip count
The number of times that the breakpoint condition must be fulfilled before the
breakpoint starts triggering. After that, the breakpoint will trigger every time the
condition is fulfilled.
127
AFE1_AFE2-1:1
Reference information on breakpoints
Data Log breakpoints dialog box
The Data Log breakpoints dialog box is available from the context menu in the editor
window, Breakpoints window, the Memory window, and in the Disassembly window.
This figure reflects the C-SPY simulator.
Use the Data Log breakpoints dialog box to set a maximum of four data log breakpoints.
You can set a data log breakpoint on 8- and 16-bit integer variables. Note that it is not
possible to set data log breakpoints on 32-bit integer variables because the microntroller
does not support single-instruction memory access of those.
See also Data Log breakpoints, page 109 and Getting started using data logging, page
79.
Requirements
The C-SPY simulator.
Trigger at
Specify the data location of the breakpoint. Alternatively, click the Edit button to open
the Enter Location dialog box, see Enter Location dialog box, page 130.
Access Type
Selects the type of memory access that triggers the breakpoint:
Read/Write
Reads from or writes to location.
Read
Reads from location.
Write
Writes to location.
C-SPY® Debugging Guide
128
for STM8
AFE1_AFE2-1:1
Breakpoints
Immediate breakpoints dialog box
The Immediate breakpoints dialog box is available from the context menu in the editor
window, Breakpoints window, the Memory window, and in the Disassembly window.
In the C-SPY simulator, use the Immediate breakpoints dialog box to set an immediate
breakpoint. Immediate breakpoints do not stop execution at all; they only suspend it
temporarily.
Requirements
The C-SPY simulator.
Trigger at
Specify the data location of the breakpoint. Alternatively, click the Edit button to open
the Enter Location dialog box, see Enter Location dialog box, page 130.
Access Type
Selects the type of memory access that triggers the breakpoint:
Read
Reads from location.
Write
Writes to location.
Action
Specify a valid C-SPY expression, which is evaluated when the breakpoint is triggered
and the condition is true. For more information, see Useful breakpoint hints, page 115.
129
AFE1_AFE2-1:1
Reference information on breakpoints
Enter Location dialog box
The Enter Location dialog box is available from the breakpoints dialog box, either
when you set a new breakpoint or when you edit a breakpoint.
Use the Enter Location dialog box to specify the location of the breakpoint.
Note: This dialog box looks different depending on the Type you select.
Type
Selects the type of location to be used for the breakpoint, choose between:
Expression
A C-SPY expression, whose value evaluates to a valid code or data location.
A code location, for example the function main, is typically used for code
breakpoints.
A data location is the name of a variable and is typically used for data
breakpoints. For example, my_var refers to the location of the variable my_var,
and arr[3] refers to the location of the fourth element of the array arr. For
static variables declared with the same name in several functions, use the syntax
my_func::my_static_variable to refer to a specific variable.
For more information about C-SPY expressions, see C-SPY expressions, page
74.
Absolute address
An absolute location on the form zone:hexaddress or simply hexaddress
(for example Memory:0x42). zone refers to C-SPY memory zones and
specifies in which memory the address belongs, see C-SPY memory zones, page
134.
Source location
A location in your C source code using the syntax:
{filename}.row.column.
filename specifies the filename and full path.
row specifies the row in which you want the breakpoint.
C-SPY® Debugging Guide
130
for STM8
AFE1_AFE2-1:1
Breakpoints
column specifies the column in which you want the breakpoint.
For example, {C:\src\prog.c}.22.3
sets a breakpoint on the third character position on row 22 in the source file
prog.c. Note that in quoted form, for example in a C-SPY macro, you must
instead write {C:\\src\\prog.c}.22.3.
Note that the Source location type is usually meaningful only for code locations
in code breakpoints.
Resolve Source Ambiguity dialog box
The Resolve Source Ambiguity dialog box appears, for example, when you try to set a
breakpoint on templates and the source location corresponds to more than one function.
To resolve a source ambiguity, perform one of these actions:
●
In the text box, select one or several of the listed locations and click Selected.
●
Click All.
All
The breakpoint will be set on all listed locations.
Selected
The breakpoint will be set on the source locations that you have selected in the text box.
131
AFE1_AFE2-1:1
Reference information on breakpoints
Cancel
No location will be used.
Automatically choose all
Determines that whenever a specified source location corresponds to more than one
function, all locations will be used.
Note that this option can also be specified in the IDE Options dialog box, see Debugger
options in the IDE Project Management and Building Guide.
C-SPY® Debugging Guide
132
for STM8
AFE1_AFE2-1:1
Memory and registers
Memory and registers
●
Introduction to monitoring memory and registers
●
Monitoring memory and registers
●
Reference information on memory and registers
Introduction to monitoring memory and registers
These topics are covered:
●
Briefly about monitoring memory and registers
●
C-SPY memory zones
●
Stack display
●
Memory access checking
BRIEFLY ABOUT MONITORING MEMORY AND REGISTERS
C-SPY provides many windows for monitoring memory and registers, each of them
available from the View menu:
●
The Memory window
Gives an up-to-date display of a specified area of memory—a memory zone—and
allows you to edit it. Different colors are used for indicating data coverage along with
execution of your application. You can fill specified areas with specific values and
you can set breakpoints directly on a memory location or range. You can open several
instances of this window, to monitor different memory areas. The content of the
window can be regularly updated while your application is executing.
●
The Symbolic memory window
Displays how variables with static storage duration are laid out in memory. This can
be useful for better understanding memory usage or for investigating problems
caused by variables being overwritten, for example by buffer overruns.
●
The Stack window
Displays the contents of the stack, including how stack variables are laid out in
memory. In addition, some integrity checks of the stack can be performed to detect
and warn about problems with stack overflow. For example, the Stack window is
useful for determining the optimal size of the stack. You can open up to two instances
of this window, each showing different stacks or different display modes of the same
stack.
133
AFE1_AFE2-1:1
Introduction to monitoring memory and registers
●
The Register window
Gives an up-to-date display of the contents of the processor registers and SFRs, and
allows you to edit them. Because of the large amount of registers—memory-mapped
peripheral unit registers and CPU registers—it is inconvenient to show all registers
concurrently in the Register window. Instead you can divide registers into register
groups. You can choose to load either predefined register groups or define your own
application-specific groups. You can open several instances of this window, each
showing a different register group.
●
The SFR Setup window
Displays the currently defined SFRs that C-SPY has information about. If required,
you can use this window to customize aspects of the SFRs.
To view the memory contents for a specific variable, simply drag the variable to the
Memory window or the Symbolic memory window. The memory area where the
variable is located will appear.
Reading the value of some registers might influence the runtime behavior of your
application. For example, reading the value of a UART status register might reset a
pending bit, which leads to the lack of an interrupt that would have processed a received
byte. To prevent this from happening, make sure that the Register window containing
any such registers is closed when debugging a running application.
C-SPY MEMORY ZONES
In C-SPY, the term zone is used for a named memory area. A memory address, or
location, is a combination of a zone and a numerical offset into that zone. By default,
C-SPY® Debugging Guide
134
for STM8
AFE1_AFE2-1:1
Memory and registers
the STM8 architecture has one zone, Memory, which covers the whole STM8 memory
range.
0x00000000
0xFFFFFFFF
Default zone Memory
Memory zones are used in several contexts, most importantly in the Memory and
Disassembly windows, and in C-SPY macros. In the windows, use the Zone box to
choose which memory zone to display.
Device-specific zones
Memory information for device-specific zones is defined in the device description files.
When you load a device description file, additional zones that adhere to the specific
memory layout become available.
See the device description file for information about available memory zones.
For more information, see Selecting a device description file, page 38 and Modifying a
device description file, page 42.
STACK DISPLAY
The Stack window displays the contents of the stack, overflow warnings, and it has a
graphical stack bar. These can be useful in many contexts. Some examples are:
●
Investigating the stack usage when assembler modules are called from C modules
and vice versa
●
Investigating whether the correct elements are located on the stack
●
Investigating whether the stack is restored properly
●
Determining the optimal stack size
●
Detecting stack overflows.
For microcontrollers with multiple stacks, you can select which stack to view.
135
AFE1_AFE2-1:1
Monitoring memory and registers
Stack usage
When your application is first loaded, and upon each reset, the memory for the stack area
is filled with the dedicated byte value 0xCD before the application starts executing.
Whenever execution stops, the stack memory is searched from the end of the stack until
a byte with a value different from 0xCD is found, which is assumed to be how far the
stack has been used. Although this is a reasonably reliable way to track stack usage,
there is no guarantee that a stack overflow is detected. For example, a stack can
incorrectly grow outside its bounds, and even modify memory outside the stack area,
without actually modifying any of the bytes near the stack range. Likewise, your
application might modify memory within the stack area by mistake.
The Stack window cannot detect a stack overflow when it happens, but can only detect
the signs it leaves behind. However, when the graphical stack bar is enabled, the
functionality needed to detect and warn about stack overflows is also enabled.
Note: The size and location of the stack is retrieved from the definition of the segment
holding the stack, made in the linker configuration file. If you, for some reason, modify
the stack initialization made in the system startup code, cstartup, you should also
change the segment definition in the linker configuration file accordingly; otherwise the
Stack window cannot track the stack usage. For more information about this, see the IAR
C/C++ Development Guide for STM8.
MEMORY ACCESS CHECKING
The C-SPY simulator can simulate various memory access types of the target hardware
and detect illegal accesses, for example a read access to write-only memory. If a memory
access occurs that does not agree with the access type specified for the specific memory
area, C-SPY will regard this as an illegal access. Also, a memory access to memory
which is not defined is regarded as an illegal access. The purpose of memory access
checking is to help you to identify any memory access violations.
The memory areas can either be the zones predefined in the device description file, or
memory areas based on the segment information available in the debug file. In addition
to these, you can define your own memory areas. The access type can be read and write,
read-only, or write-only. You cannot map two different access types to the same memory
area. You can check for access type violation and accesses to unspecified ranges. Any
violations are logged in the Debug Log window. You can also choose to have the
execution halted.
Monitoring memory and registers
These tasks are covered:
●
C-SPY® Debugging Guide
136
for STM8
AFE1_AFE2-1:1
Defining application-specific register groups, page 137.
Memory and registers
DEFINING APPLICATION-SPECIFIC REGISTER GROUPS
Defining application-specific register groups minimizes the amount of registers
displayed in the Register window and speeds up the debugging.
1 Choose Tools>Options>Register Filter during a debug session.
For information about the register filter options, see the IDE Project Management and
Building Guide.
2 Select Use register filter and specify the filename and destination of the filter file for
your new group in the dialog box that appears.
3 Click New Group and specify the name of your group, for example My Timer Group.
4 In the register tree view on the Register Filter page, select a register and click the arrow
button to add it to your group. Repeat this process for all registers that you want to add
to your group.
5 Optionally, select any registers for which you want to change the integer base, and
choose a suitable base.
6 When you are done, click OK. Your new group is now available in the Register
window.
137
AFE1_AFE2-1:1
Reference information on memory and registers
If you want to add more groups to your filter file, repeat this procedure for each group
you want to add.
Note: The registers that appear in the list of registers are retrieved from the ddf file that
is currently used. If a certain SFR that you need does not appear, you can register your
own SFRs. For more information, see SFR Setup window, page 154.
Reference information on memory and registers
Reference information about:
C-SPY® Debugging Guide
138
for STM8
AFE1_AFE2-1:1
●
Memory window, page 139
●
Memory Save dialog box, page 143
●
Memory Restore dialog box, page 144
●
Fill dialog box, page 144
●
Symbolic Memory window, page 146
●
Stack window, page 148
●
Register window, page 152
●
SFR Setup window, page 154
●
Edit SFR dialog box, page 157
●
Memory Access Setup dialog box, page 158
●
Edit Memory Access dialog box, page 160.
Memory and registers
Memory window
The Memory window is available from the View menu.
This window gives an up-to-date display of a specified area of memory—a memory
zone—and allows you to edit it. You can open several instances of this window, which
is very convenient if you want to keep track of several memory or register zones, or
monitor different parts of the memory.
To view the memory corresponding to a variable, you can select it in the editor window
and drag it to the Memory window.
For information about editing in C-SPY windows, see C-SPY Debugger main window,
page 45.
Requirements
None; this window is always available.
Toolbar
The toolbar contains:
Go to
The memory location or symbol you want to view.
Zone
Selects a memory zone, see C-SPY memory zones, page 134.
139
AFE1_AFE2-1:1
Reference information on memory and registers
Context menu button
Displays the context menu.
Update Now
Updates the content of the Memory window while your application is executing.
This button is only enabled if the C-SPY driver you are using has access to the
target system memory while your application is executing.
Live Update
Updates the contents of the Memory window regularly while your application is
executing. This button is only enabled if the C-SPY driver you are using has
access to the target system memory while your application is executing. To set
the update frequency, specify an appropriate frequency in the IDE
Options>Debugger dialog box.
Display area
The display area shows the addresses currently being viewed, the memory contents in
the format you have chosen, and—provided that the display mode is set to
1x Units—the memory contents in ASCII format. You can edit the contents of the
display area, both in the hexadecimal part and the ASCII part of the area.
Data coverage is displayed with these colors:
Yellow
Indicates data that has been read.
Blue
Indicates data that has been written
Green
Indicates data that has been both read and written.
Note: Data coverage is not supported by all C-SPY drivers. Data coverage is supported
by the C-SPY Simulator.
C-SPY® Debugging Guide
140
for STM8
AFE1_AFE2-1:1
Memory and registers
Context menu
This context menu is available:
These commands are available:
Copy, Paste
Standard editing commands.
Zone
Selects a memory zone, see C-SPY memory zones, page 134.
1x Units
Displays the memory contents as single bytes.
2x Units
Displays the memory contents as 2-byte groups.
4x Units
Displays the memory contents as 4-byte groups.
8x Units
Displays the memory contents as 8-byte groups.
Little Endian
Displays the contents in little-endian byte order.
141
AFE1_AFE2-1:1
Reference information on memory and registers
Big Endian
Displays the contents in big-endian byte order.
Data Coverage
Choose between:
Enable toggles data coverage on or off.
Show toggles between showing or hiding data coverage.
Clear clears all data coverage information.
These commands are only available if your C-SPY driver supports data
coverage.
Find
Displays a dialog box where you can search for text within the Memory
window; read about the Find dialog box in the IDE Project Management and
Building Guide.
Replace
Displays a dialog box where you can search for a specified string and replace
each occurrence with another string; read about the Replace dialog box in the
IDE Project Management and Building Guide.
Memory Fill
Displays a dialog box, where you can fill a specified area with a value, see Fill
dialog box, page 144.
Memory Save
Displays a dialog box, where you can save the contents of a specified memory
area to a file, see Memory Save dialog box, page 143.
Memory Restore
Displays a dialog box, where you can load the contents of a file in Intel-hex or
Motorola s-record format to a specified memory zone, see Memory Restore
dialog box, page 144.
Set Data Breakpoint
Sets breakpoints directly in the Memory window. The breakpoint is not
highlighted; you can see, edit, and remove it in the Breakpoints dialog box. The
breakpoints you set in this window will be triggered for both read and write
access. For more information, see Setting a data breakpoint in the Memory
window, page 114.
C-SPY® Debugging Guide
142
for STM8
AFE1_AFE2-1:1
Memory and registers
Memory Save dialog box
The Memory Save dialog box is available by choosing Debug>Memory>Save or from
the context menu in the Memory window.
Use this dialog box to save the contents of a specified memory area to a file.
Requirements
None; this dialog box is always available.
Zone
Selects a memory zone, see C-SPY memory zones, page 134.
Start address
Specify the start address of the memory range to be saved.
End address
Specify the end address of the memory range to be saved.
File format
Selects the file format to be used, which is Intel-extended by default.
Filename
Specify the destination file to be used; a browse button is available for your convenience.
Save
Saves the selected range of the memory zone to the specified file.
143
AFE1_AFE2-1:1
Reference information on memory and registers
Memory Restore dialog box
The Memory Restore dialog box is available by choosing Debug>Memory>Restore
or from the context menu in the Memory window.
Use this dialog box to load the contents of a file in Intel-extended or Motorola S-record
format to a specified memory zone.
Requirements
None; this dialog box is always available.
Zone
Selects a memory zone, see C-SPY memory zones, page 134.
Filename
Specify the file to be read; a browse button is available for your convenience.
Restore
Loads the contents of the specified file to the selected memory zone.
Fill dialog box
The Fill dialog box is available from the context menu in the Memory window.
Use this dialog box to fill a specified area of memory with a value.
C-SPY® Debugging Guide
144
for STM8
AFE1_AFE2-1:1
Memory and registers
Requirements
None; this dialog box is always available.
Start address
Type the start address—in binary, octal, decimal, or hexadecimal notation.
Length
Type the length—in binary, octal, decimal, or hexadecimal notation.
Zone
Selects a memory zone, see C-SPY memory zones, page 134.
Value
Type the 8-bit value to be used for filling each memory location.
Operation
These are the available memory fill operations:
Copy
Value will be copied to the specified memory area.
AND
An AND operation will be performed between Value and the existing contents of
memory before writing the result to memory.
XOR
An XOR operation will be performed between Value and the existing contents of
memory before writing the result to memory.
OR
An OR operation will be performed between Value and the existing contents of
memory before writing the result to memory.
145
AFE1_AFE2-1:1
Reference information on memory and registers
Symbolic Memory window
The Symbolic Memory window is available from the View menu during a debug
session.
This window displays how variables with static storage duration, typically variables
with file scope but also static variables in functions and classes, are laid out in memory.
This can be useful for better understanding memory usage or for investigating problems
caused by variables being overwritten, for example buffer overruns. Other areas of use
are spotting alignment holes or for understanding problems caused by buffers being
overwritten.
To view the memory corresponding to a variable, you can select it in the editor window
and drag it to the Symbolic Memory window.
For information about editing in C-SPY windows, see C-SPY Debugger main window,
page 45.
Requirements
None; this window is always available.
Toolbar
The toolbar contains:
Go to
The memory location or symbol you want to view.
Zone
Selects a memory zone, see C-SPY memory zones, page 134.
Previous
Highlights the previous symbol in the display area.
C-SPY® Debugging Guide
146
for STM8
AFE1_AFE2-1:1
Memory and registers
Next
Highlights the next symbol in the display area.
Display area
This area contains these columns:
Location
The memory address.
Data
The memory contents in hexadecimal format. The data is grouped according to
the size of the symbol. This column is editable.
Variable
The variable name; requires that the variable has a fixed memory location. Local
variables are not displayed.
Value
The value of the variable. This column is editable.
Type
The type of the variable.
There are several different ways to navigate within the memory space:
●
Text that is dropped in the window is interpreted as symbols
●
The scroll bar at the right-side of the window
●
The toolbar buttons Next and Previous
●
The toolbar list box Go to can be used for locating specific locations or symbols.
Note: Rows are marked in red when the corresponding value has changed.
Context menu
This context menu is available:
These commands are available:
Next Symbol
Highlights the next symbol in the display area.
147
AFE1_AFE2-1:1
Reference information on memory and registers
Previous Symbol
Highlights the previous symbol in the display area.
1x Units
Displays the memory contents as single bytes. This applies only to rows which
do not contain a variable.
2x Units
Displays the memory contents as 2-byte groups.
4x Units
Displays the memory contents as 4-byte groups.
Add to Watch Window
Adds the selected symbol to the Watch window.
Stack window
The Stack window is available from the View menu.
This window is a memory window that displays the contents of the stack. In addition,
some integrity checks of the stack can be performed to detect and warn about problems
with stack overflow. For example, the Stack window is useful for determining the
optimal size of the stack.
To view the graphical stack bar:
1 Choose Tools>Options>Stack.
2 Select the option Enable graphical stack display and stack usage.
You can open up to two Stack windows, each showing a different stack—if several
stacks are available—or the same stack with different display settings.
C-SPY® Debugging Guide
148
for STM8
AFE1_AFE2-1:1
Memory and registers
Note: By default, this window uses one physical breakpoint. For more information, see
Breakpoint consumers, page 111.
For information about options specific to the Stack window, see the IDE Project
Management and Building Guide.
Requirements
None; this window is always available.
Toolbar
The toolbar contains:
Stack
Selects which stack to view. This applies to microcontrollers with multiple
stacks.
The graphical stack bar
Displays the state of the stack graphically.
The left end of the stack bar represents the bottom of the stack, in other words, the
position of the stack pointer when the stack is empty. The right end represents the end
of the memory space reserved for the stack. The graphical stack bar turns red when the
stack usage exceeds a threshold that you can specify.
When the stack bar is enabled, the functionality needed to detect and warn about stack
overflows is also enabled.
Place the mouse pointer over the stack bar to get tooltip information about stack usage.
Display area
This area contains these columns:
Location
Displays the location in memory. The addresses are displayed in increasing
order. The address referenced by the stack pointer, in other words the top of the
stack, is highlighted in a green color.
Data
Displays the contents of the memory unit at the given location. From the Stack
window context menu, you can select how the data should be displayed; as a 1-,
2-, or 4-byte group of data.
149
AFE1_AFE2-1:1
Reference information on memory and registers
Variable
Displays the name of a variable, if there is a local variable at the given location.
Variables are only displayed if they are declared locally in a function, and
located on the stack and not in registers.
Value
Displays the value of the variable that is displayed in the Variable column.
Frame
Displays the name of the function that the call frame corresponds to.
Context menu
This context menu is available:
These commands are available:
Show variables
Displays separate columns named Variables, Value, and Frame in the Stack
window. Variables located at memory addresses listed in the Stack window are
displayed in these columns.
Show offsets
Displays locations in the Location column as offsets from the stack pointer.
When deselected, locations are displayed as absolute addresses.
1x Units
Displays the memory contents as single bytes.
2x Units
Displays the memory contents as 2-byte groups.
C-SPY® Debugging Guide
150
for STM8
AFE1_AFE2-1:1
Memory and registers
4x Units
Displays the memory contents as 4-byte groups.
Default Format,
Binary Format,
Octal Format,
Decimal Format,
Hexadecimal Format,
Char Format
Changes the display format of expressions. The display format setting affects
different types of expressions in different ways. Your selection of display format
is saved between debug sessions. These commands are available if a selected
line in the window contains a variable.
The display format setting affects different types of expressions in these ways:
Variables
The display setting affects only the selected variable, not
other variables.
Array elements
The display setting affects the complete array, that is, the
same display format is used for each array element.
Structure fields
All elements with the same definition—the same field
name and C declaration type—are affected by the
display setting.
Options
Opens the IDE Options dialog box where you can set options specific to the
Stack window, see the IDE Project Management and Building Guide.
151
AFE1_AFE2-1:1
Reference information on memory and registers
Register window
The Register window is available from the View menu.
This window gives an up-to-date display of the contents of the processor registers and
special function registers, and allows you to edit the content of some of the registers.
Optionally, you can choose to load either predefined register groups or to define your
own application-specific groups.
You can open several instances of this window, which is very convenient if you want to
keep track of different register groups.
For information about editing in C-SPY windows, see C-SPY Debugger main window,
page 45.
To enable predefined register groups:
1 Select a device description file that suits your device, see Selecting a device description
file, page 38.
2 The register groups appear in the Register window, provided that they are defined in
the device description file. Note that the available register groups are also listed on the
Register Filter page.
To define application-specific register groups:
See Defining application-specific register groups, page 137.
Requirements
None; this window is always available.
C-SPY® Debugging Guide
152
for STM8
AFE1_AFE2-1:1
Memory and registers
Toolbar
The toolbar contains:
CPU Registers
Selects which register group to display, by default CPU Registers. If some of
your SFRs are missing, you can register your own SFRs in a Custom group, see
SFR Setup window, page 154.
Display area
Displays registers and their values. Every time C-SPY stops, a value that has changed
since the last stop is highlighted. Some of the registers are read-only, some of the
registers are write-only (marked with W), and some of the registers are editable. To edit
the contents of an editable register, click it, and modify its value. Press Esc to cancel the
new value.
Some registers are expandable, which means that the register contains interesting bits or
subgroups of bits.
To change the display format, change the Base setting on the Register Filter
page—available by choosing Tools>Options.
153
AFE1_AFE2-1:1
Reference information on memory and registers
For the C-SPY Simulator and the C-SPY hardware debugger drivers, these additional
support registers are available in the CPU Registers group:
CYCLECOUNTER
Cleared when an application is started or reset and is
incremented with the number of used cycles during
execution.
CCSTEP
Shows the number of used cycles during the last performed
C/C++ source or assembler step.
CCTIMER1 and
CCTIMER2
Two trip counts that can be cleared manually at any given
time. They are incremented with the number of used cycles
during execution.
SFR Setup window
The SFR Setup window is available from the Project menu.
This window displays the currently defined SFRs that C-SPY has information about.
You can choose to display only factory-defined or custom-defined SFRs, or both. If
required, you can use this window to customize the aspects of the SFRs. For
factory-defined SFRs (that is, retrieved from the ddf file that is currently used), you can
only customize the access type.
Any custom-defined SFRs are added to a dedicated register group called Custom, which
you can choose to display in the Register window. Your custom-defined SFRs are saved
in projectCustomSFR.sfr.
You can only add or modify SFRs when the C-SPY debugger is not running.
Requirements
None; this window is always available.
C-SPY® Debugging Guide
154
for STM8
AFE1_AFE2-1:1
Memory and registers
Display area
This area contains these columns:
Status
A character that signals the status of the SFR, which can be one of:
blank, a factory-defined SFR.
C, a factory-defined SFR that has been modified.
+, a custom-defined SFR.
?, an SFR that is ignored for some reason. An SFR can be ignored when a
factory-defined SFR has been modified, but the SFR is no longer available, or it
is located somewhere else or with a different size. Typically, this might happen
if you change to another device.
Name
A unique name of the SFR.
Address
The memory address of the SFR.
Zone
Selects a memory zone, see C-SPY memory zones, page 134.
Size
The size of the register, which can be any of 8, 16, 32, or 64.
Access
The access type of the register, which can be one of Read/Write, Read only,
Write only, or None.
You can click a name or an address to change the value. The hexadecimal 0x prefix for
the address can be omitted, the value you enter will still be interpreted as hexadecimal.
For example, if you enter 4567, you will get 0x4567.
You can click a column header to sort the SFRs according to the column property.
Color coding used in the display area:
●
Green, which indicates that the corresponding value has changed
●
Red, which indicates an ignored SFR.
155
AFE1_AFE2-1:1
Reference information on memory and registers
Context menu
This context menu is available:
These commands are available:
Show All
Shows all SFR.
Show Custom SFRs only
Shows all custom-defined SFRs.
Show Factory SFRs only
Shows all factory-defined SFRs retrieved from the ddf file.
Add
Displays the Edit SFR dialog box where you can add a new SFR, see Edit SFR
dialog box, page 157.
Edit
Displays the Edit SFR dialog box where you can edit an SFR, see Edit SFR
dialog box, page 157.
Delete
Deletes an SFR. This command only works on custom-defined SFRs.
Delete/revert All Custom SFRs
Deletes all custom-defined SFRs and reverts all modified factory-defined SFRs
to their factory settings.
C-SPY® Debugging Guide
156
for STM8
AFE1_AFE2-1:1
Memory and registers
Save Custom SFRs
Opens a standard save dialog box to save all custom-defined SFRs.
8|16|32|64 bits
Selects display format for the selected SFR, which can be 8, 16, 32, or 64 bits.
Note that the display format can only be changed for custom-defined SFRs.
Read/Write|Read only|Write only|None
Selects the access type of the selected SFR, which can be Read/Write, Read
only, Write only, or None. Note that for factory-defined SFRs, the default
access type is indicated.
Edit SFR dialog box
The Edit SFR dialog box is available from the SFR Setup window.
Use this dialog box to define the SFRs.
Requirements
None; this dialog box is always available.
Name
Specify the name of the SFR that you want to add or edit.
Address
Specify the address of the SFR that you want to add or edit. The hexadecimal 0x prefix
for the address can be omitted, the value you enter will still be interpreted as
hexadecimal. For example, if you enter 4567, you will get 0x4567.
157
AFE1_AFE2-1:1
Reference information on memory and registers
Zone
Selects the memory zone for the SFR you want to add or edit. The list of zones is
retrieved from the ddf file that is currently used.
Size
Selects the size of the SFR. Choose between 8, 16, 32, or 64 bits. Note that the display
format can only be changed for custom-defined SFRs.
Access
Selects the access type of the SFR. Choose between Read/Write, Read only, Write
only, or None. Note that for factory-defined SFRs, the default access type is indicated.
Memory Access Setup dialog box
The Memory Access Setup dialog box is available from the C-SPY driver menu.
This dialog box lists all defined memory areas, where each column in the list specifies
the properties of the area. In other words, the dialog box displays the memory access
setup that will be used during the simulation.
Note: If you enable both the Use ranges based on and the Use manual ranges option,
memory accesses are checked for all defined ranges.
C-SPY® Debugging Guide
158
for STM8
AFE1_AFE2-1:1
Memory and registers
For information about the columns and the properties displayed, see Edit Memory
Access dialog box, page 160.
Requirements
The C-SPY simulator.
Use ranges based on
Selects any of the predefined alternatives for the memory access setup. Choose between:
Device description file
Loads properties from the device description file.
Debug file segment information
Properties are based on the segment information available in the debug file. This
information is only available while debugging. The advantage of using this
option, is that the simulator can catch memory accesses outside the linked
application.
Use manual ranges
Specify your own ranges manually via the Edit Memory Access dialog box. To open
this dialog box, choose New to specify a new memory range, or select a memory zone
and choose Edit to modify it. For more information, see Edit Memory Access dialog
box, page 160.
The ranges you define manually are saved between debug sessions.
Memory access checking
Check for determines what to check for;
●
Access type violation
●
Access to unspecified ranges.
Action selects the action to be performed if an access violation occurs; choose between:
●
Log violations
●
Log and stop execution.
Any violations are logged in the Debug Log window.
159
AFE1_AFE2-1:1
Reference information on memory and registers
Buttons
These buttons are available:
New
Opens the Edit Memory Access dialog box, where you can specify a new
memory range and attach an access type to it, see Edit Memory Access dialog
box, page 160.
Edit
Opens the Edit Memory Access dialog box, where you can edit the selected
memory area. See Edit Memory Access dialog box, page 160.
Delete
Deletes the selected memory area definition.
Delete All
Deletes all defined memory area definitions.
Note that except for the OK and Cancel buttons, buttons are only available when the
option Use manual ranges is selected.
Edit Memory Access dialog box
The Edit Memory Access dialog box is available from the Memory Access Setup
dialog box.
Use this dialog box to specify the memory ranges, and assign an access type to each
memory range, for which you want to detect illegal accesses during the simulation.
Requirements
The C-SPY simulator.
C-SPY® Debugging Guide
160
for STM8
AFE1_AFE2-1:1
Memory and registers
Memory range
Defines the memory area specific to your device:
Zone
Selects a memory zone, see C-SPY memory zones, page 134.
Start address
Specify the start address for the memory area, in hexadecimal notation.
End address
Specify the end address for the memory area, in hexadecimal notation.
Access type
Selects an access type to the memory range; choose between:
●
Read and write
●
Read only
●
Write only.
161
AFE1_AFE2-1:1
Reference information on memory and registers
C-SPY® Debugging Guide
162
for STM8
AFE1_AFE2-1:1
Part 2. Analyzing your
application
This part of the C-SPY® Debugging Guide for STM8 includes these chapters:
●
Trace
●
Profiling
●
Code coverage
163
164
Trace
Trace
●
Introduction to using trace
●
Collecting and using trace data
●
Reference information on trace
Introduction to using trace
These topics are covered:
●
Reasons for using trace
●
Briefly about trace
●
Requirements for using trace
See also:
●
Getting started using data logging, page 79
●
Getting started using interrupt logging, page 212
●
Profiling, page 189
REASONS FOR USING TRACE
By using trace, you can inspect the program flow up to a specific state, for instance an
application crash, and use the trace data to locate the origin of the problem. Trace data
can be useful for locating programming errors that have irregular symptoms and occur
sporadically.
BRIEFLY ABOUT TRACE
To use trace in C-SPY requires that your target system can generate trace data. Once
generated, C-SPY can collect it and you can visualize and analyze the data in various
windows and dialog boxes.
Trace features in C-SPY
In C-SPY, you can use the trace-related windows Trace, Function Trace, Timeline, and
Find in Trace.
Depending on your C-SPY driver, you:
●
Can set various types of trace breakpoints to control the collection of trace data.
165
AFE1_AFE2-1:1
Collecting and using trace data
●
Have access to windows such as the Interrupt Log, Interrupt Log Summary, Data
Log, and Data Log Summary.
In addition, several other features in C-SPY also use trace data, features such as
Profiling, Code coverage, and Instruction profiling.
REQUIREMENTS FOR USING TRACE
The C-SPY simulator supports trace-related functionality, and there are no specific
requirements.
To use trace in your hardware debugger systems you need:
●
The C-SPY STice driver, not using the SWIM interface.
Note: The specific set of debug components you are using (hardware, a debug probe,
and a C-SPY driver) determine which trace features in C-SPY that are supported.
Collecting and using trace data
These tasks are covered:
●
Getting started with trace
●
Trace data collection using breakpoints
●
Searching in trace data
●
Browsing through trace data.
GETTING STARTED WITH TRACE
1 pen the Trace window—available from the driver-specific menu—and click the
Activate button to enable collecting trace data.
2 Start the execution. When the execution stops, for example because a breakpoint is
triggered, trace data is displayed in the Trace window. For more information about the
window, see Trace window, page 170.
TRACE DATA COLLECTION USING BREAKPOINTS
A convenient way to collect trace data between two execution points is to start and stop
the data collection using dedicated breakpoints. Choose between these alternatives:
C-SPY® Debugging Guide
166
for STM8
AFE1_AFE2-1:1
●
In the editor or Disassembly window, position your insertion point, right-click, and
toggle a Trace Start or Trace Stop breakpoint from the context menu.
●
In the Breakpoints window, choose Trace Start or Trace Stop.
●
The C-SPY system macros __setTraceStartBreak and
__setTraceStopBreak can also be used.
Trace
For more information about these breakpoints, see Trace Start breakpoints dialog box,
page 182 and Trace Stop breakpoints dialog box, page 183, respectively.
Note: Collecting trace data using breakpoints is only supported by the C-SPY simulator.
SEARCHING IN TRACE DATA
When you have collected trace data, you can perform searches in the collected data to
locate the parts of your code or data that you are interested in, for example, a specific
interrupt or accesses of a specific variable.
You specify the search criteria in the Find in Trace dialog box and view the result in the
Find in Trace window.
The Find in Trace window is very similar to the Trace window, showing the same
columns and data, but only those rows that match the specified search criteria.
Double-clicking an item in the Find in Trace window brings up the same item in the
Trace window.
To search in your trace data:
1 On the Trace window toolbar, click the Find button.
2 In the Find in Trace dialog box, specify your search criteria.
Typically, you can choose to search for:
●
A specific piece of text, for which you can apply further search criteria
●
An address range
●
A combination of these, like a specific piece of text within a specific address range.
For more information about the various options, see Find in Trace dialog box, page 185.
3 When you have specified your search criteria, click Find. The Find in Trace window is
displayed, which means you can start analyzing the trace data. For more information,
see Find in Trace window, page 186.
BROWSING THROUGH TRACE DATA
To follow the execution history, simply look and scroll in the Trace window.
Alternatively, you can enter browse mode.
To enter browse mode, double-click an item in the Trace window, or click the Browse
toolbar button.
The selected item turns yellow and the source and disassembly windows will highlight
the corresponding location. You can now move around in the trace data using the up and
down arrow keys, or by scrolling and clicking; the source and Disassembly windows
167
AFE1_AFE2-1:1
Reference information on trace
will be updated to show the corresponding location. This is like stepping backward and
forward through the execution history.
Double-click again to leave browse mode.
Reference information on trace
Reference information about:
●
Trace Settings dialog box, page 168
●
Trace window, page 170
●
Function Trace window, page 174
●
Timeline window, page 174
●
Viewing Range dialog box, page 181
●
Trace Start breakpoints dialog box, page 182
●
Trace Stop breakpoints dialog box, page 183
●
Trace Expressions window, page 184
●
Find in Trace dialog box, page 185
●
Find in Trace window, page 186.
Trace Settings dialog box
The Trace Settings dialog box is available from the STice menu.
Use this dialog box to determine which trace data is displayed in the Trace window.
C-SPY® Debugging Guide
168
for STM8
AFE1_AFE2-1:1
Trace
Requirements
One of these alternatives:
●
The C-SPY Simulator
●
The C-SPY STice driver, not using the SWIM interface.
Trace types
Choose between:
Interrupt handler
Displays interrupt handler entry cycles in the Instruction
event column in the Trace window.
Data read
Displays data memory read cycles in the R event column in
the Trace window.
Data write
Displays data memory write cycles in the W event column in
the Trace window-
Stack read
Displays stack read cycles in the R event column in the Trace
window.
Stack write
Displays stack write cycles in the W event column in the Trace
window.
DMA read
Displays direct memory read cycles in the R event column in
the Trace window.
DMA write
Displays direct memory write cycles in the W event column in
the Trace window.
Time count event
Displays timestamp event cycles in the Time event column in
the Trace window.
Memory access stall
Displays memory access stall cycles in the R event or W event
column in the Trace window.
External input
Displays external input cycles in the Trigger or Al column in
the Trace window.
BEM event
Displays BEM event cycles in the BEM column in the Tarce
window.
Discarded
Displays discarded cycles in the Instruction event column in
the Trace window.
Interrupted
Displays interrupted instruction cycles in the Instruction
event column in the Trace window.
169
AFE1_AFE2-1:1
Reference information on trace
Non-event
Displays cycles with no event. If this option is selected, a
record might be displayed even if it does not contain ny event.
Trace window
The Trace window is available from the C-SPY driver menu.
This window displays the collected trace data.
Requirements
One of these alternatives:
●
The C-SPY Simulator
●
The C-SPY STice driver, not using the SWIM interface.
Trace toolbar
The toolbar in the Trace window and in the Function trace window contains:
Enable/Disable
Enables and disables collecting and viewing trace data in this window. This
button is not available in the Function trace window.
Clear trace data
Clears the trace buffer. Both the Trace window and the Function trace window
are cleared.
Toggle source
Toggles the Trace column between showing only disassembly or disassembly
together with the corresponding source code.
Browse
Toggles browse mode on or off for a selected item in the Trace window, see
Browsing through trace data, page 167.
Find
Displays a dialog box where you can perform a search, see Find in Trace dialog
box, page 185.
Save
Displays a standard Save As dialog box where you can save the collected trace
data to a text file, with tab-separated columns.
Edit Settings
In the C-SPY simulator, this button is not enabled.
C-SPY® Debugging Guide
170
for STM8
AFE1_AFE2-1:1
Trace
For the STice emulator, this button displays the Trace Settings dialog box, see
Trace Settings dialog box, page 168.
Edit Expressions (C-SPY simulator only)
Opens the Trace Expressions window, see Trace Expressions window, page 184.
Display area (in the C-SPY simulator)
This area displays a collected sequence of executed machine instructions. In addition,
the window can display trace data for expressions.
This area contains these columns for the C-SPY simulator:
#
A serial number for each row in the trace buffer. Simplifies the navigation within
the buffer.
Cycles
The number of cycles elapsed to this point.
Trace
The collected sequence of executed machine instructions. Optionally, the
corresponding source code can also be displayed.
Expression
Each expression you have defined to be displayed appears in a separate column.
Each entry in the expression column displays the value after executing the
instruction on the same row. You specify the expressions for which you want to
collect trace data in the Trace Expressions window, see Trace Expressions
window, page 184.
A red-colored row indicates that the previous row and the red row are not consecutive.
This means that there is a gap in the collected trace data, for example because trace data
has been lost due to an overflow.
171
AFE1_AFE2-1:1
Reference information on trace
Display area (in the C-SPY STice driver)
This area contains these columns for the C-SPY STice driver:
Trace
The collected sequence of executed machine instructions. Optionally, the
corresponding source code can also be displayed.
Record
A sequential trace record number.
Instruction event
The type of instruction trace event, one of Decoding start, Interrupt handler,
Discarded, Interrupted, Processing, or Extra record.
PC
The execution address of the trace record.
R addr
The address of a data read event, including locations for instruction decoding.
R value
The data value of a data read event.
R event
Special events during a data read event, one of Data read, DMA read, Stack read,
or Read stall.
W addr
The address of a data write event.
W value
The data value of a data write event.
C-SPY® Debugging Guide
172
for STM8
AFE1_AFE2-1:1
Trace
W event
Special events during a data write event, one of Data write, DMA write, Stack
write, or Write stall.
Time
The timestamp for the event in milliseconds.
Irq
The name of the starting interrupt, for example reset, trap, or irqN.
Time event
An event indicating that the timestamp counter has been affected. When there is
an overflow, Restart is displayed, and when there is a discontinuity,
Discontinuity is displyed.
Trace event
An event indicating a trace discontinuity, for example when the target is started
after a reset.
Trigger*
An event indicating input from an external trigger.
AI*
An event indicating input from the probe analyzer.
BEM*
Indicates that a BEM event has occurred.
* For more information about triggers, probe analyzers, and BEM, see the
documentation from STMicroelectronics.
A red-colored row indicates that the previous row and the red row are not consecutive.
This means that there is a gap in the collected trace data, for example because trace data
has been lost due to an overflow.
173
AFE1_AFE2-1:1
Reference information on trace
Function Trace window
The Function Trace window is available from the C-SPY driver menu during a debug
session.
This window displays a subset of the trace data displayed in the Trace window. Instead
of displaying all rows, the Function Trace window only shows trace data corresponding
to calls to and returns from functions.
Requirements
One of these alternatives:
●
The C-SPY Simulator
●
The C-SPY STice driver, not using the SWIM interface.
Toolbar
For information about the toolbar, see Trace window, page 170.
Display area
For information about the columns in the display area, see Trace window, page 170
Timeline window
The Timeline window is available from the C-SPY driver menu during a debug session.
This window displays trace data in different graphs in relation to a common time axis:
C-SPY® Debugging Guide
174
for STM8
AFE1_AFE2-1:1
●
Call Stack graph
●
Data Log graph
●
Interrupt Log graph
Trace
To display a graph:
1 Choose Timeline from the C-SPY driver menu to open the Timeline window.
2 In the Timeline window, click in the graph area and choose Enable from the context
menu to enable a specific graph.
3 For the Data Log Graph, you need to set a Data Log breakpoint for each variable you
want a graphical representation of in the Timeline window. See Data Log breakpoints
dialog box, page 128.
4 Click Go on the toolbar to start executing your application. The graph appears.
To navigate in the graph, use any of these alternatives:
●
Right-click and from the context menu choose Zoom In or Zoom Out.
Alternatively, use the + and - keys. The graph zooms in or out depending on which
command you used.
●
Right-click in the graph and from the context menu choose Navigate and the
appropriate command to move backwards and forwards on the graph. Alternatively,
use any of the shortcut keys: arrow keys, Home, End, and Ctrl+End.
●
Double-click on a sample of interest and the corresponding source code is
highlighted in the editor window and in the Disassembly window.
●
Click on the graph and drag to select a time interval. Press Enter or right-click and
from the context menu choose Zoom>Zoom to Selection. The selection zooms in.
Point in the selection with the mouse pointer to get detailed tooltip information
about the selected part of the graph:
Point in the graph with the mouse pointer to get detailed tooltip information for that
location.
175
AFE1_AFE2-1:1
Reference information on trace
Requirements
Depending on the abilities in hardware, the debug probe, and the C-SPY driver you are
using, the display area can be populated with different graphs:
Target system
Call Stack
Data Log
Interrupt
Graph
Graph
Log Graph
C-SPY simulator
X
X
X
ST-LINK, and STice using SWIM mode
--
--
--
STice
X
--
--
Table 8: Supported graphs in the Timeline window
For more information about requirements related to trace data, see Requirements for
using trace, page 166.
Display area for the Call Stack Graph
The Call Stack Graph displays the sequence of calls and returns collected by trace.
At the bottom of the graph you will usually find main, and above it, the functions called
from main, and so on. The horizontal bars, which represent invocations of functions, use
four different colors:
●
Medium green for normal C functions with debug information
●
Light green for functions known to the debugger only through an assembler label
●
Medium or light yellow for interrupt handlers, with the same distinctions as for
green.
The numbers represent the number of cycles spent in, or between, the function
invocations.
C-SPY® Debugging Guide
176
for STM8
AFE1_AFE2-1:1
Trace
At the bottom of the window, there is a common time axis that uses seconds as the time
unit.
Display area for the Data Log graph
The Data Log graph displays the data logs generated by trace, for up to four different
variables or address ranges specified as Data Log breakpoints.
Where:
●
The label area at the left end of the graph displays the variable name or the address
for which you have specified the Data Log breakpoint.
●
The graph itself displays how the value of the variable changes over time. The label
area also displays the limits, or range, of the Y-axis for a variable. You can use the
context menu to change these limits. The graph is a graphical representation of the
information in the Data Log window, see Data Log window, page 95.
●
The graph can be displayed either as a thin line between consecutive logs or as a
rectangle for every log (optionally color-filled).
●
A red vertical line indicates overflow, which means that the communication channel
failed to transmit all data logs from the target system. A red question mark indicates
a log without a value.
At the bottom of the window, there is a common time axis that uses seconds as the time
unit.
177
AFE1_AFE2-1:1
Reference information on trace
Display area for the Interrupt Log graph
The Interrupt Log graph displays interrupts reported by the C-SPY simulator. In other
words, the graph provides a graphical view of the interrupt events during the execution
of your application.
Where:
●
The label area at the left end of the graph displays the names of the interrupts.
●
The graph itself shows active interrupts as a thick green horizontal bar where the
white figure indicates the time spent in the interrupt. This graph is a graphical
representation of the information in the Interrupt Log window, see Interrupt Log
window, page 219.
●
If the bar is displayed without horizontal borders, there are two possible causes:
●
The interrupt is reentrant and has interrupted itself. Only the innermost interrupt
will have borders.
●
There are irregularities in the interrupt enter-leave sequence, probably due to
missing logs.
●
If the bar is displayed without a vertical border, the missing border indicates an
approximate time for the log.
●
A red vertical line indicates overflow, which means that the communication channel
failed to transmit all interrupt logs from the target system.
At the bottom of the window, there is a common time axis that uses seconds as the time
unit.
Selection and navigation
Click and drag to select. The selection extends vertically over all graphs, but appears
highlighted in a darker color for the selected graph. You can navigate backward and
forward in the selected graph using the left and right arrow keys. Use the Home and End
C-SPY® Debugging Guide
178
for STM8
AFE1_AFE2-1:1
Trace
keys to move to the first or last relevant point, respectively. Use the navigation keys in
combination with the Shift key to extend the selection.
Context menu
This context menu is available:
Note: The context menu contains some commands that are common to all graphs and
some commands that are specific to each graph. The figure reflects the context menu for
the Call Stack Graph, which means that the menu looks slightly different for the other
graphs.
These commands are available:
Navigate (All graphs)
Commands for navigating over the graph(s); choose between:
Next moves the selection to the next relevant point in the graph. Shortcut key:
right arrow.
Previous moves the selection backward to the previous relevant point in the
graph. Shortcut key: left arrow.
First moves the selection to the first data entry in the graph. Shortcut key:
Home.
Last moves the selection to the last data entry in the graph. Shortcut key: End.
End moves the selection to the last data in any displayed graph, in other words
the end of the time axis. Shortcut key: Ctrl+End.
Auto Scroll (All graphs)
Toggles auto scrolling on or off. When on, the most recently collected data is
automatically displayed if you have executed the command Navigate>End.
Zoom (All graphs)
Commands for zooming the window, in other words, changing the time scale;
choose between:
Zoom to Selection makes the current selection fit the window. Shortcut key:
Return.
179
AFE1_AFE2-1:1
Reference information on trace
Zoom In zooms in on the time scale. Shortcut key: +.
Zoom Out zooms out on the time scale. Shortcut key: -.
10ns, 100ns, 1us, etc makes an interval of 10 nanoseconds, 100 nanoseconds, 1
microsecond, respectively, fit the window.
1ms, 10ms, etc makes an interval of 1 millisecond or 10 milliseconds,
respectively, fit the window.
10m, 1h, etc makes an interval of 10 minutes or 1 hour, respectively, fit the
window.
Data Log (Data Log Graph)
A heading that shows that the Data Log-specific commands below are available.
Call Stack (Call Stack Graph)
A heading that shows that the Call stack-specific commands below are available.
Interrupt (Interrupt Log Graph)
A heading that shows that the Interrupt Log-specific commands below are
available.
Enable (All graphs)
Toggles the display of the graph on or off. If you disable a graph, that graph will
be indicated as OFF in the Timeline window. If no trace data has been collected
for a graph, no data will appear instead of the graph.
Variable (Data Log Graph)
The name of the variable for which the Data Log-specific commands below
apply. This menu command is context-sensitive, which means it reflects the
Data Log Graph you selected in the Timeline window (one of up to four).
Solid Graph (Data Log Graph)
Displays the graph as a color-filled solid graph instead of as a thin line.
Viewing Range (Data Log Graph)
Displays a dialog box, see Viewing Range dialog box, page 181.
Size (Data Log Graph)
Determines the vertical size of the graph; choose between Small, Medium, and
Large.
Show Numerical Value (Data Log Graph)
Shows the numerical value of the variable, in addition to the graph.
Go To Source (Common)
Displays the corresponding source code in an editor window, if applicable.
C-SPY® Debugging Guide
180
for STM8
AFE1_AFE2-1:1
Trace
Sort by (Interrupt Graph)
Sorts the entries according to their ID or name. The selected order is used in the
graph when new interrupts appear.
Select Graphs (Common)
Selects which graphs to be displayed in the Timeline window.
Time Axis Unit (Common)
Selects the unit used in the time axis; choose between Seconds and Cycles.
Profile Selection
Enables profiling time intervals in the Function Profiler window. Note that this
command is only available if the C-SPY driver supports PC Sampling.
Viewing Range dialog box
The Viewing Range dialog box is available from the context menu that appears when
you right-click in the Data Log Graph in the Timeline window.
Use this dialog box to specify the value range, that is, the range for the Y-axis for the
graph.
Requirements
The C-SPY simulator.
181
AFE1_AFE2-1:1
Reference information on trace
Range for ...
Selects the viewing range for the displayed values:
Auto
Uses the range according to the range of the values that are actually collected,
continuously keeping track of minimum or maximum values. The currently
computed range, if any, is displayed in parentheses. The range is rounded to
reasonably even limits.
Factory
For the Data Log Graph: Uses the range according to the value range of the
variable, for example 0–65535 for an unsigned 16-bit integer.
Custom
Use the text boxes to specify an explicit range.
Scale
Selects the scale type of the Y-axis:
●
Linear
●
Logarithmic.
Trace Start breakpoints dialog box
The Trace Start dialog box is available from the context menu that appears when you
right-click in the Breakpoints window.
Use this dialog box to set a Trace Start breakpoint where you want to start collecting
trace data. If you want to collect trace data only for a specific range, you must also set a
Trace Stop breakpoint where you want to stop collecting data.
See also, Trace Stop breakpoints dialog box, page 183.
C-SPY® Debugging Guide
182
for STM8
AFE1_AFE2-1:1
Trace
To set a Trace Start breakpoint:
1 In the editor or Disassembly window, right-click and choose Trace Start from the
context menu.
Alternatively, open the Breakpoints window by choosing View>Breakpoints.
2 In the Breakpoints window, right-click and choose New Breakpoint>Trace Start.
Alternatively, to modify an existing breakpoint, select a breakpoint in the Breakpoints
window and choose Edit on the context menu.
3 In the Trigger At text box, specify an expression, an absolute address, or a source
location. Click OK.
4 When the breakpoint is triggered, the trace data collection starts.
Requirements
The C-SPY simulator.
Trigger at
Specify the code location of the breakpoint. Alternatively, click the Edit button to open
the Enter Location dialog box, see Enter Location dialog box, page 130.
Trace Stop breakpoints dialog box
The Trace Stop dialog box is available from the context menu that appears when you
right-click in the Breakpoints window.
Use this dialog box to set a Trace Stop breakpoint where you want to stop collecting
trace data. If you want to collect trace data only for a specific range, you might also need
to set a Trace Start breakpoint where you want to start collecting data.
See also, Trace Start breakpoints dialog box, page 182.
183
AFE1_AFE2-1:1
Reference information on trace
To set a Trace Stop breakpoint:
1 In the editor or Disassembly window, right-click and choose Trace Stop from the
context menu.
Alternatively, open the Breakpoints window by choosing View>Breakpoints.
2 In the Breakpoints window, right-click and choose New Breakpoint>Trace Stop.
Alternatively, to modify an existing breakpoint, select a breakpoint in the Breakpoints
window and choose Edit on the context menu.
3 In the Trigger At text box, specify an expression, an absolute address, or a source
location. Click OK.
4 When the breakpoint is triggered, the trace data collection stops.
Requirements
The C-SPY simulator.
Trigger at
Specify the code location of the breakpoint. Alternatively, click the Edit button to open
the Enter Location dialog box, see Enter Location dialog box, page 130.
Trace Expressions window
The Trace Expressions window is available from the Trace window toolbar.
Use this window to specify, for example, a specific variable (or an expression) for which
you want to collect trace data.
Requirements
The C-SPY simulator.
C-SPY® Debugging Guide
184
for STM8
AFE1_AFE2-1:1
Trace
Toolbar
The toolbar buttons change the order between the expressions:
Arrow up
Moves the selected row up.
Arrow down
Moves the selected row down.
Display area
Use the display area to specify expressions for which you want to collect trace data:
Expression
Specify any expression that you want to collect data from. You can specify any
expression that can be evaluated, such as variables and registers.
Format
Shows which display format that is used for each expression. Note that you can
change display format via the context menu.
Each row in this area will appear as an extra column in the Trace window.
Find in Trace dialog box
The Find in Trace dialog box is available by clicking the Find button on the Trace
window toolbar or by choosing Edit>Find and Replace>Find.
Note that the Edit>Find and Replace>Find command is context-dependent. It displays
the Find in Trace dialog box if the Trace window is the current window or the Find
dialog box if the editor window is the current window.
Use this dialog box to specify the search criteria for advanced searches in the trace data.
185
AFE1_AFE2-1:1
Reference information on trace
The search results are displayed in the Find in Trace window—available by choosing the
View>Messages command, see Find in Trace window, page 186.
See also Searching in trace data, page 167.
Requirements
One of these alternatives:
●
The C-SPY Simulator
●
The C-SPY STice driver, not using the SWIM interface.
Text search
Specify the string you want to search for. To specify the search criteria, choose between:
Match Case
Searches only for occurrences that exactly match the case of the specified text.
Otherwise int will also find INT and Int and so on.
Match whole word
Searches only for the string when it occurs as a separate word. Otherwise int
will also find print, sprintf and so on.
Only search in one column
Searches only in the column you selected from the drop-down list.
Address Range
Specify the address range you want to display or search. The trace data within the
address range is displayed. If you also have specified a text string in the Text search
field, the text string is searched for within the address range.
Find in Trace window
The Find in Trace window is available from the View>Messages menu. Alternatively, it
is automatically displayed when you perform a search using the Find in Trace dialog
C-SPY® Debugging Guide
186
for STM8
AFE1_AFE2-1:1
Trace
box or perform a search using the Find in Trace command available from the context
menu in the editor window.
This window displays the result of searches in the trace data. Double-click an item in the
Find in Trace window to bring up the same item in the Trace window.
Before you can view any trace data, you must specify the search criteria in the Find in
Trace dialog box, see Find in Trace dialog box, page 185.
For more information, see Searching in trace data, page 167.
Requirements
One of these alternatives:
●
The C-SPY Simulator
●
The C-SPY STice driver, not using the SWIM interface.
Display area
The Find in Trace window looks like the Trace window and shows the same columns
and data, but only those rows that match the specified search criteria.
187
AFE1_AFE2-1:1
Reference information on trace
C-SPY® Debugging Guide
188
for STM8
AFE1_AFE2-1:1
Profiling
Profiling
●
Introduction to the profiler
●
Using the profiler
●
Reference information on the profiler
Introduction to the profiler
These topics are covered:
●
Reasons for using the profiler
●
Briefly about the profiler
●
Requirements for using the profiler
REASONS FOR USING THE PROFILER
Function profiling can help you find the functions in your source code where the most
time is spent during execution. You should focus on those functions when optimizing
your code. A simple method of optimizing a function is to compile it using speed
optimization. Alternatively, you can move the data used by the function into more
efficient memory. For detailed information about efficient memory usage, see the IAR
C/C++ Development Guide for STM8.
Alternatively, you can use filtered profiling, which means that you can exclude, for
example, individual functions from being profiled. To profile only a specific part of your
code, you can select a time interval—using the Timeline window—for which C-SPY
produces profiling information.
Instruction profiling can help you fine-tune your code on a very detailed level, especially
for assembler source code. Instruction profiling can also help you to understand where
your compiled C/C++ source code spends most of its time, and perhaps give insight into
how to rewrite it for better performance.
BRIEFLY ABOUT THE PROFILER
Function profiling information is displayed in the Function Profiler window, that is,
timing information for the functions in an application. Profiling must be turned on
explicitly using a button on the window’s toolbar, and will stay enabled until it is turned
off.
189
AFE1_AFE2-1:1
Introduction to the profiler
Instruction profiling information is displayed in the Disassembly window, that is, the
number of times each instruction has been executed.
Profiling sources
The profiler can use different mechanisms, or sources, to collect profiling information.
Depending on the available trace source features, one or more of the sources can be used
for profiling:
●
Trace (calls)
The full instruction trace is analyzed to determine all function calls and returns.
When the collected instruction sequence is incomplete or discontinuous, the
profiling information is less accurate.
●
Trace (flat)
Each instruction in the full instruction trace or each PC Sample is assigned to a
corresponding function or code fragment, without regard to function calls or returns.
This is most useful when the application does not exhibit normal call/return
sequences, such as when you are using an RTOS, or when you are profiling code
which does not have full debug information.
REQUIREMENTS FOR USING THE PROFILER
The C-SPY simulator support the profiler; there are no specific requirements.
To use the profiler in your hardware debugger system, you need:
●
A device that is supported by STice
●
To enable the options Instruction, Discarded, and Interrupted in the Trace
Settings dialog box. For more information, see Trace Settings dialog box, page 168.
This table lists the C-SPY driver profiling support:
C-SPY driver
Trace (calls)
Trace (flat)
C-SPY simulator
X
X
C-SPY STice driver
X
X
Table 9: C-SPY driver profiling support
STice uses trace for function profiling and built-in STice features for instruction
profiling.
Note:
C-SPY® Debugging Guide
190
for STM8
AFE1_AFE2-1:1
●
Instruction profiling cannot be used at the same time as trace or data coverage.
●
Function profiling cannot be used at the same time as code coverage, data coverage,
or instruction profiling.
Profiling
Using the profiler
These tasks are covered:
●
Getting started using the profiler on function level
●
Analyzing the profiling data
●
Getting started using the profiler on instruction level
GETTING STARTED USING THE PROFILER ON FUNCTION
LEVEL
To display function profiling information in the Function Profiler window:
1 Build your application using these options:
Category
Setting
C/C++ Compiler
Output>Generate debug information
Linker
Output>Include debug information in output
Table 10: Project options for enabling the profiler
2 When you have built your application and started C-SPY, choose C-SPY
Driver>Function Profiler to open the Function Profiler window, and click the Enable
button to turn on the profiler. Alternatively, choose Enable from the context menu that
is available when you right-click in the Function Profiler window.
3 Start executing your application to collect the profiling information.
4 Profiling information is displayed in the Function Profiler window. To sort, click on the
relevant column header.
5 When you start a new sampling, you can click the Clear button—alternatively, use the
context menu—to clear the data.
ANALYZING THE PROFILING DATA
Here follow some examples of how to analyze the data.
The first figure shows the result of profiling using Source: Trace (calls). The profiler
follows the program flow and detects function entries and exits.
●
For the InitFib function, Flat Time 231 is the time spent inside the function itself.
●
For the InitFib function, Acc Time 487 is the time spent inside the function itself,
including all functions InitFib calls.
●
For the InitFib/GetFib function, Acc Time 256 is the time spent inside GetFib (but
only when called from InitFib), including any functions GetFib calls.
191
AFE1_AFE2-1:1
Using the profiler
●
Further down in the data, you can find the GetFib function separately and see all of
its subfunctions (in this case none).
The second figure shows the result of profiling using Source: Trace (flat). In this case,
the profiler does not follow the program flow, instead the profiler only detects whether
the PC address is within the function scope. For incomplete trace data, the data might
contain minor errors.
C-SPY® Debugging Guide
192
for STM8
AFE1_AFE2-1:1
Profiling
For the InitFib function, Flat Time 231 is the time (number of hits) spent inside the
function itself.
To secure valid data when using a debug probe, make sure to use the maximum trace
buffer size and set a breakpoint in your code to stop the execution before the buffer is
full.
GETTING STARTED USING THE PROFILER ON INSTRUCTION
LEVEL
To display instruction profiling information in the Disassembly window:
1 When you have built your application and started C-SPY, choose View>Disassembly
to open the Disassembly window, and choose Instruction Profiling>Enable from the
context menu that is available when you right-click in the left-hand margin of the
Disassembly window.
2 Make sure that the Show command on the context menu is selected, to display the
profiling information.
3 Start executing your application to collect the profiling information.
4 When the execution stops, for instance because the program exit is reached or a
breakpoint is triggered, you can view instruction level profiling information in the
left-hand margin of the window.
193
AFE1_AFE2-1:1
Reference information on the profiler
For each instruction, the number of times it has been executed is displayed.
Reference information on the profiler
Reference information about:
●
Function Profiler window, page 194
See also:
●
Disassembly window, page 62
●
Trace Settings dialog box, page 168
Function Profiler window
The Function Profiler window is available from the C-SPY driver menu.
This window displays function profiling information.
C-SPY® Debugging Guide
194
for STM8
AFE1_AFE2-1:1
Profiling
When Trace(flat) is selected, a checkbox appears on each line in the left-side margin of
the window. Use these checkboxes to include or exclude lines from the profiling.
Excluded lines are dimmed but not removed.
Requirements
One of these alternatives:
●
The C-SPY Simulator
●
An STice emulator. Make sure to use the C-SPY driver for STice, but not with the
SWIM interface.
Toolbar
The toolbar contains:
Enable/Disable
Enables or disables the profiler.
Clear
Clears all profiling data.
Save
Opens a standard Save As dialog box where you can save the contents of the
window to a file, with tab-separated columns. Only non-expanded rows are
included in the list file.
Graphical view
Overlays the values in the percentage columns with a graphical bar.
Progress bar
Displays a backlog of profiling data that is still being processed. If the rate of
incoming data is higher than the rate of the profiler processing the data, a
backlog is accumulated. The progress bar indicates that the profiler is still
processing data, but also approximately how far the profiler has come in the
process. Note that because the profiler consumes data at a certain rate and the
target system supplies data at another rate, the amount of data remaining to be
processed can both increase and decrease. The progress bar can grow and shrink
accordingly.
Display area
The content in the display area depends on which source that is used for the profiling
information:
●
For the Trace (calls) source, the display area contains one line for each function
compiled with debug information enabled. When some profiling information has
195
AFE1_AFE2-1:1
Reference information on the profiler
been collected, it is possible to expand rows of functions that have called other
functions. The child items for a given function list all the functions that have been
called by the parent function and the corresponding statistics.
●
For the Trace (flat) source, the display area contains one line for each C function of
your application, but also lines for sections of code from the runtime library or from
other code without debug information, denoted only by the corresponding
assembler labels. Each executed PC address from trace data is treated as a separate
sample and is associated with the corresponding line in the Profiling window. Each
line contains a count of those samples.
For information about which views that are supported in the C-SPY driver you are using,
see Requirements for using the profiler, page 190.
More specifically, the display area provides information in these columns:
Function (All sources)
The name of the profiled C function.
Calls (Trace (calls))
The number of times the function has been called.
Flat time (Trace (calls))
The time expressed in cycles spent inside the function.
Flat time (%) (Trace (calls))
Flat time expressed as a percentage of the total time.
Acc. time (Trace (calls))
The time expressed in cycles spent inside the function.
Acc. time (%) (Trace (calls))
Accumulated time expressed as a percentage of the total time.
PC Samples (Trace (flat))
The number of PC samples associated with the function.
PC Samples (%) (Trace (flat))
The number of PC samples associated with the function as a percentage of the
total number of samples.
C-SPY® Debugging Guide
196
for STM8
AFE1_AFE2-1:1
Profiling
Context menu
This context menu is available:
The contents of this menu depend on the C-SPY driver you are using.
These commands are available:
Enable
Enables the profiler. The system will collect information also when the window
is closed.
Clear
Clears all profiling data.
Filtering
Selects which part of your code to profile. Choose between:
Check All—Excludes all lines from the profiling.
Uncheck All—Includes all lines in the profiling.
Load—Reads all excluded lines from a saved file.
Save—Saves all excluded lines to a file. Typically, this can be useful if you are
a group of engineers and want to share sets of exclusions.
These commands are only available when using Trace(flat).
Source*
Selects which source to be used for the profiling information. Choose between:
Trace (calls)—the instruction count for instruction profiling is only as complete
as the collected trace data.
Trace (flat)—the instruction count for instruction profiling is only as complete
as the collected trace data.
Save to Log File
Saves all profiling data to a file.
* The available sources depend on the C-SPY driver you are using.
197
AFE1_AFE2-1:1
Reference information on the profiler
C-SPY® Debugging Guide
198
for STM8
AFE1_AFE2-1:1
Code coverage
Code coverage
●
Introduction to code coverage
●
Reference information on code coverage.
Introduction to code coverage
These topics are covered:
●
Reasons for using code coverage
●
Briefly about code coverage
●
Requirements and restrictions for using code coverage.
REASONS FOR USING CODE COVERAGE
The code coverage functionality is useful when you design your test procedure to verify
whether all parts of the code have been executed. It also helps you identify parts of your
code that are not reachable.
BRIEFLY ABOUT CODE COVERAGE
The Code Coverage window reports the status of the current code coverage analysis. For
every program, module, and function, the analysis shows the percentage of code that has
been executed since code coverage was turned on up to the point where the application
has stopped. In addition, all statements that have not been executed are listed. The
analysis will continue until turned off.
REQUIREMENTS AND RESTRICTIONS FOR USING CODE
COVERAGE
Code coverage is supported by the C-SPY Simulator and there are no specific
requirements or restrictions.
To use code coverage in your hardware debugger system, you need the C-SPY STice
driver, not using the SWIM interface.
Reference information on code coverage
Reference information about:
●
Code Coverage window, page 200.
199
AFE1_AFE2-1:1
Reference information on code coverage
See also Single stepping, page 56.
Code Coverage window
The Code Coverage window is available from the View menu.
This window reports the status of the current code coverage analysis. For every program,
module, and function, the analysis shows the percentage of code that has been executed
since code coverage was turned on up to the point where the application has stopped. In
addition, all statements that have not been executed are listed. The analysis will continue
until turned off.
An asterisk (*) in the title bar indicates that C-SPY has continued to execute, and that
the Code Coverage window must be refreshed because the displayed information is no
longer up to date. To update the information, use the Refresh command.
To get started using code coverage:
1 Before using the code coverage functionality you must build your application using
these options:
Category
Setting
C/C++ Compiler
Output>Generate debug information
Linker
Output>Include debug information in output
Debugger
Plugins>Code Coverage
Table 11: Project options for enabling code coverage
2 After you have built your application and started C-SPY, choose View>Code
Coverage to open the Code Coverage window.
3 Click the Activate button, alternatively choose Activate from the context menu, to
switch on code coverage.
C-SPY® Debugging Guide
200
for STM8
AFE1_AFE2-1:1
Code coverage
4 Start the execution. When the execution stops, for instance because the program exit is
reached or a breakpoint is triggered, click the Refresh button to view the code
coverage information.
Requirements
One of these alternatives:
●
The C-SPY Simulator
●
The C-SPY STice driver, not using the SWIM interface.
Display area
The code coverage information is displayed in a tree structure, showing the program,
module, function, and statement levels. The window displays only source code that was
compiled with debug information. Thus, startup code, exit code, and library code is not
displayed in the window. Furthermore, coverage information for statements in inlined
functions is not displayed. Only the statement containing the inlined function call is
marked as executed. The plus sign and minus sign icons allow you to expand and
collapse the structure.
These icons give you an overview of the current status on all levels:
Red diamond
Signifies that 0% of the modules or functions has been
executed.
Green diamond
Signifies that 100% of the modules or functions has been
executed.
Red and green diamond
Signifies that some of the modules or functions have been
executed.
Yellow diamond
Signifies a statement that has not been executed.
The percentage displayed at the end of every program, module, and function line shows
the amount of statements that has been covered so far, that is, the number of executed
statements divided with the total number of statements.
For statements that have not been executed (yellow diamond), the information displayed
is the column number range and the row number of the statement in the source window,
followed by the address of the step point:
<column_start>-<column_end>:row address.
A statement is considered to be executed when one of its instructions has been executed.
When a statement has been executed, it is removed from the window and the percentage
is increased correspondingly.
201
AFE1_AFE2-1:1
Reference information on code coverage
Double-clicking a statement or a function in the Code Coverage window displays that
statement or function as the current position in the source window, which becomes the
active window. Double-clicking a module on the program level expands or collapses the
tree structure.
Context menu
This context menu is available:
These commands are available:
Activate
Switches code coverage on and off during execution.
Clear
Clears the code coverage information. All step points are marked as not
executed.
Refresh
Updates the code coverage information and refreshes the window. All step
points that have been executed since the last refresh are removed from the tree.
Auto-refresh
Toggles the automatic reload of code coverage information on and off. When
turned on, the code coverage information is reloaded automatically when
C-SPY stops at a breakpoint, at a step point, and at program exit.
Save As
Saves the current code coverage result in a text file.
Save session
Saves your code coverage session data to a *.dat file. This is useful if you for
some reason must abort your debug session, but want to continue the session
later on. This command is available on the toolbar. This command might not be
supported by the C-SPY driver you are using.
Restore session
Restores previously saved code coverage session data. This is useful if you for
some reason must abort your debug session, but want to continue the session
later on. This command is available on the toolbar. This command might not be
supported by the C-SPY driver you are using.
C-SPY® Debugging Guide
202
for STM8
AFE1_AFE2-1:1
Part 3. Advanced
debugging
This part of the C-SPY® Debugging Guide for STM8 includes these chapters:
●
Interrupts
●
C-SPY macros
●
The C-SPY command line utility—cspybat
203
204
Interrupts
Interrupts
●
Introduction to interrupts
●
Using the interrupt system
●
Reference information on interrupts
Introduction to interrupts
These topics are covered:
●
Briefly about interrupt logging
●
Briefly about the interrupt simulation system
●
Interrupt characteristics
●
Interrupt simulation states
●
C-SPY system macros for interrupt simulation
●
Target-adapting the interrupt simulation system
See also:
●
Reference information on C-SPY system macros, page 239
●
Breakpoints, page 107
●
The IAR C/C++ Development Guide for STM8
BRIEFLY ABOUT INTERRUPT LOGGING
Interrupt logging provides you with comprehensive information about the interrupt
events. This might be useful for example, to help you locate which interrupts you can
fine-tune to become faster. You can log entrances and exits to and from interrupts. You
can also log internal interrupt status information, such as triggered, expired, etc. The
logs are displayed in the Interrupt Log window and a summary is available in the
Interrupt Log Summary window. The Interrupt Graph in the Timeline window provides
a graphical view of the interrupt events during the execution of your application
program.
Requirements for interrupt logging
Interrupt logging is supported by the C-SPY simulator.
See also Getting started using interrupt logging, page 212.
205
AFE1_AFE2-1:1
Introduction to interrupts
BRIEFLY ABOUT THE INTERRUPT SIMULATION SYSTEM
By simulating interrupts, you can test the logic of your interrupt service routines and
debug the interrupt handling in the target system long before any hardware is available.
If you use simulated interrupts in conjunction with C-SPY macros and breakpoints, you
can compose a complex simulation of, for instance, interrupt-driven peripheral devices.
The C-SPY Simulator includes an interrupt simulation system where you can simulate
the execution of interrupts during debugging. You can configure the interrupt simulation
system so that it resembles your hardware interrupt system.
The interrupt system has the following features:
●
Simulated interrupt support for the STM8 microcontroller
●
Single-occasion or periodical interrupts based on the cycle counter
●
Predefined interrupts for various devices
●
Configuration of hold time, probability, and timing variation
●
State information for locating timing problems
●
Configuration of interrupts using a dialog box or a C-SPY system macro—that is,
one interactive and one automating interface. In addition, you can instantly force an
interrupt.
●
A log window that continuously displays events for each defined interrupt.
●
A status window that shows the current interrupt activities.
All interrupts you define using the Interrupt Setup dialog box are preserved between
debug sessions, unless you remove them. A forced interrupt, on the other hand, exists
only until it has been serviced and is not preserved between sessions.
The interrupt simulation system is activated by default, but if not required, you can turn
off the interrupt simulation system to speed up the simulation. To turn it off, use either
the Interrupt Setup dialog box or a system macro.
C-SPY® Debugging Guide
206
for STM8
AFE1_AFE2-1:1
Interrupts
INTERRUPT CHARACTERISTICS
The simulated interrupts consist of a set of characteristics which lets you fine-tune each
interrupt to make it resemble the real interrupt on your target hardware. You can specify
a first activation time, a repeat interval, a hold time, a variance, and a probability.
The interrupt simulation system uses the cycle counter as a clock to determine when an
interrupt should be raised in the simulator. You specify the first activation time, which
is based on the cycle counter. C-SPY will generate an interrupt when the cycle counter
has passed the specified activation time. However, interrupts can only be raised between
instructions, which means that a full assembler instruction must have been executed
before the interrupt is generated, regardless of how many cycles an instruction takes.
To define the periodicity of the interrupt generation you can specify the repeat interval
which defines the amount of cycles after which a new interrupt should be generated. In
addition to the repeat interval, the periodicity depends on the two options
probability—the probability, in percent, that the interrupt will actually appear in a
period—and variance—a time variation range as a percentage of the repeat interval.
These options make it possible to randomize the interrupt simulation. You can also
specify a hold time which describes how long the interrupt remains pending until
removed if it has not been processed. If the hold time is set to infinite, the corresponding
pending bit will be set until the interrupt is acknowledged or removed.
INTERRUPT SIMULATION STATES
The interrupt simulation system contains status information that you can use for locating
timing problems in your application. The Interrupt Status window displays the available
status information. For an interrupt, these states can be displayed: Idle, Pending,
Executing, or Suspended.
207
AFE1_AFE2-1:1
Introduction to interrupts
Normally, a repeatable interrupt has a specified repeat interval that is longer than the
execution time. In this case, the status information at different times looks like this:
Note: The interrupt activation signal—also known as the pending bit—is automatically
deactivated the moment the interrupt is acknowledged by the interrupt handler.
However, if the interrupt repeat interval is shorter than the execution time, and the
interrupt is reentrant (or non-maskable), the status information at different times looks
like this:
An execution time that is longer than the repeat interval might indicate that you should
rewrite your interrupt handler and make it faster, or that you should specify a longer
repeat interval for the interrupt simulation system.
C-SPY SYSTEM MACROS FOR INTERRUPT SIMULATION
Macros are useful when you already have sorted out the details of the simulated interrupt
so that it fully meets your requirements. If you write a macro function containing
definitions for the simulated interrupts, you can execute the functions automatically
C-SPY® Debugging Guide
208
for STM8
AFE1_AFE2-1:1
Interrupts
when C-SPY starts. Another advantage is that your simulated interrupt definitions will
be documented if you use macro files, and if you are several engineers involved in the
development project you can share the macro files within the group.
The C-SPY Simulator provides these predefined system macros related to interrupts:
__enableInterrupts
__disableInterrupts
__orderInterrupt
__cancelInterrupt
__cancelAllInterrupts
__popSimulatorInterruptExecutingStack
The parameters of the first five macros correspond to the equivalent entries of the
Interrupts dialog box.
For more information about each macro, see Reference information on C-SPY system
macros, page 239.
TARGET-ADAPTING THE INTERRUPT SIMULATION SYSTEM
The interrupt simulation system is easy to use. However, to take full advantage of the
interrupt simulation system you should be familiar with how to adapt it for the processor
you are using.
To simulate device-specific interrupts, the interrupt system must have detailed
information about each available interrupt. This information is provided in the device
description files.
For information about device description files, see Selecting a device description file,
page 38.
Using the interrupt system
These tasks are covered:
●
Simulating a simple interrupt
●
Simulating an interrupt in a multi-task system
●
Getting started using interrupt logging.
See also:
●
Using C-SPY macros, page 227 for details about how to use a setup file to define
simulated interrupts at C-SPY startup
209
AFE1_AFE2-1:1
Using the interrupt system
●
The tutorial Simulating an interrupt in the Information Center.
SIMULATING A SIMPLE INTERRUPT
This example demonstrates the method for simulating a timer interrupt. However, the
procedure can also be used for other types of interrupts.
To simulate and debug an interrupt:
1 Assume this example application which contains an interrupt service routine for a
timer, which increments a tick variable. The main function sets the necessary status
registers. The application exits when 100 interrupts have been generated.
#pragma language = extended
#include "iostm8.h"
#include <intrinsics.h>
volatile int ticks = 0;
void main (void)
{
/* Add your timer setup code here */
__enable_interrupt();
/* Enable interrupts */
while (ticks < 100);
printf("Done\n");
/* Endless loop */
}
/* Timer interrupt service routine */
#pragma vector = TIMER_VECTOR
__interrupt void basic_timer(void)
{
ticks += 1;
}
2 Add your interrupt service routine to your application source code and add the file to
your project.
3 Build your project and start the simulator.
4 Choose Simulator>Interrupt Setup to open the Interrupts Setup dialog box. Select
the Enable interrupt simulation option to enable interrupt simulation. Click New to
open the Edit Interrupt dialog box. For the timer example, verify these settings:
Option
Settings
Interrupt
TIMER_VECTOR
Table 12: Timer interrupt settings
C-SPY® Debugging Guide
210
for STM8
AFE1_AFE2-1:1
Interrupts
Option
Settings
First activation
4000
Repeat interval
2000
Hold time
10
Probability (%)
100
Variance (%)
0
Table 12: Timer interrupt settings (Continued)
Click OK.
5 Execute your application. If you have enabled the interrupt properly in your application
source code, C-SPY will:
●
Generate an interrupt when the cycle counter has passed 4000
●
Continuously repeat the interrupt after approximately 2000 cycles.
6 To watch the interrupt in action, choose Simulator>Interrupt Log to open the
Interrupt Log window.
7 From the context menu, available in the Interrupt Log window, choose Enable to
enable the logging. If you restart program execution, status information about
entrances and exits to and from interrupts will now appear in the Interrupt Log window.
For information about how to get a graphical representation of the interrupts correlated
with a time axis, see Timeline window, page 174.
SIMULATING AN INTERRUPT IN A MULTI-TASK SYSTEM
If you are using interrupts in such a way that the normal instruction used for returning
from an interrupt handler is not used, for example in an operating system with
task-switching, the simulator cannot automatically detect that the interrupt has finished
executing. The interrupt simulation system will work correctly, but the status
information in the Interrupt Setup dialog box might not look as you expect. If too
many interrupts are executing simultaneously, a warning might be issued.
To simulate a normal interrupt exit:
1 Set a code breakpoint on the instruction that returns from the interrupt function.
2 Specify the __popSimulatorInterruptExecutingStack macro as a condition to
the breakpoint.
When the breakpoint is triggered, the macro is executed and then the application
continues to execute automatically.
211
AFE1_AFE2-1:1
Reference information on interrupts
GETTING STARTED USING INTERRUPT LOGGING
1 Choose C-SPY driver>Interrupt Log to open the Interrupt Log window. Optionally,
you can also choose:
●
C-SPY driver>Interrupt Log Summary to open the Interrupt Log Summary
window
●
C-SPY driver>Timeline to open the Timeline window and view the Interrupt graph.
2 From the context menu in the Interrupt Log window, choose Enable to enable the
logging.
3 Start executing your application program to collect the log information.
4 To view the interrupt log information, look in any of the Interrupt Log, Interrupt Log
Summary, or the Interrupt graph in the Timeline window.
5 If you want to save the log or summary to a file, choose Save to log file from the
context menu in the window in question.
6 To disable interrupt logging, from the context menu in the Interrupt Log window,
toggle Enable off.
Reference information on interrupts
Reference information about:
C-SPY® Debugging Guide
212
for STM8
AFE1_AFE2-1:1
●
Interrupt Setup dialog box, page 213
●
Edit Interrupt dialog box, page 214
●
Forced Interrupt window, page 216
●
Interrupt Status window, page 217
●
Interrupt Log window, page 219
●
Interrupt Log Summary window, page 222.
Interrupts
Interrupt Setup dialog box
The Interrupt Setup dialog box is available by choosing Simulator>Interrupt Setup.
This dialog box lists all defined interrupts. Use this dialog box to enable or disable the
interrupt simulation system, as well as to enable or disable individual interrupts.
Requirements
The C-SPY simulator.
Enable interrupt simulation
Enables or disables interrupt simulation. If the interrupt simulation is disabled, the
definitions remain but no interrupts are generated. Note that you can also enable and
disable installed interrupts individually by using the check box to the left of the interrupt
name in the list of installed interrupts.
Display area
This area contains these columns:
Interrupt
Lists all interrupts. Use the checkbox to enable or disable the interrupt.
ID
A unique interrupt identifier.
Type
Shows the type of the interrupt. The type can be one of:
Forced, a single-occasion interrupt defined in the Forced Interrupt Window.
Single, a single-occasion interrupt.
213
AFE1_AFE2-1:1
Reference information on interrupts
Repeat, a periodically occurring interrupt.
If the interrupt has been set from a C-SPY macro, the additional part (macro)
is added, for example: Repeat(macro).
Timing
The timing of the interrupt. For a Single and Forced interrupt, the activation
time is displayed. For a Repeat interrupt, the information has the form:
Activation Time + n*Repeat Time. For example, 2000 + n*2345. This
means that the first time this interrupt is triggered, is at 2000 cycles and after that
with an interval of 2345 cycles.
Buttons
These buttons are available:
New
Opens the Edit Interrupt dialog box, see Edit Interrupt dialog box, page 214.
Edit
Opens the Edit Interrupt dialog box, see Edit Interrupt dialog box, page 214.
Delete
Removes the selected interrupt.
Delete All
Removes all interrupts.
Edit Interrupt dialog box
The Edit Interrupt dialog box is available from the Interrupt Setup dialog box.
Use this dialog box to interactively fine-tune the interrupt parameters. You can add the
parameters and quickly test that the interrupt is generated according to your needs.
C-SPY® Debugging Guide
214
for STM8
AFE1_AFE2-1:1
Interrupts
Note: You can only edit or remove non-forced interrupts.
Requirements
The C-SPY simulator.
Interrupt
Selects the interrupt that you want to edit. The drop-down list contains all available
interrupts. Your selection will automatically update the Description box. The list
ispopulated with entries from the device description file that you have selected.
Description
A description of the selected interrupt, if available. The description is retrieved from the
selected device description file and consists of a string describing the vector address,
request number, enable bit, pending bit, and priority bit, separated by space characters.
For interrupts specified using the system macro __orderInterrupt, the Description
box is empty.
First activation
Specify the value of the cycle counter after which the specified type of interrupt will be
generated.
Repeat interval
Specify the periodicity of the interrupt in cycles.
Variance %
Selects a timing variation range, as a percentage of the repeat interval, in which the
interrupt might occur for a period. For example, if the repeat interval is 100 and the
variance 5%, the interrupt might occur anywhere between T=95 and T=105, to simulate
a variation in the timing.
Hold time
Specify how long, in cycles, the interrupt remains pending until removed if it has not
been processed. If you select Infinite, the corresponding pending bit will be set until the
interrupt is acknowledged or removed.
Probability %
Selects the probability, in percent, that the interrupt will actually occur within the
specified period.
215
AFE1_AFE2-1:1
Reference information on interrupts
Forced Interrupt window
The Forced Interrupt window is available from the C-SPY driver menu.
Use this window to force an interrupt instantly. This is useful when you want to check
your interrupt logic and interrupt routines. Just start typing an interrupt name and focus
shifts to the first line found with that name.
The hold time for a forced interrupt is infinite, and the interrupt exists until it has been
serviced or until a reset of the debug session.
To sort the window contents, click on either the Interrupt or the Description
column header. A second click on the same column header reversers the sort order.
To force an interrupt:
1 Enable the interrupt simulation system, see Interrupt Setup dialog box, page 213.
2 Double-click the interrupt in the Forced Interrupt window, or activate by using the
Force command available on the context menu.
Requirements
The C-SPY simulator.
Display area
This area lists all available interrupts and their definitions. This information is retrieved
from the selected device description file. See this file for a detailed description.
Context menu
This context menu is available:
This command is available:
Force
Triggers the interrupt you selected in the display area.
C-SPY® Debugging Guide
216
for STM8
AFE1_AFE2-1:1
Interrupts
Interrupt Status window
The Interrupt Status window is available from the C-SPY driver menu.
This window shows the status of all the currently active interrupts, in other words
interrupts that are either executing or waiting to be executed.
Requirements
The C-SPY simulator.
Display area
This area contains these columns:
Interrupt
Lists all interrupts.
ID
A unique interrupt identifier.
Type
The type of the interrupt. The type can be one of:
Forced, a single-occasion interrupt defined in the Forced Interrupt window.
Single, a single-occasion interrupt.
Repeat, a periodically occurring interrupt.
If the interrupt has been set from a C-SPY macro, the additional part (macro)
is added, for example: Repeat(macro).
Status
The state of the interrupt:
Idle, the interrupt activation signal is low (deactivated).
Pending, the interrupt activation signal is active, but the interrupt has not been
yet acknowledged by the interrupt handler.
217
AFE1_AFE2-1:1
Reference information on interrupts
Executing, the interrupt is currently being serviced, that is the interrupt handler
function is executing.
Suspended, the interrupt is currently suspended due to execution of an interrupt
with a higher priority.
(deleted) is added to Executing and Suspended if you have deleted a currently
active interrupt. (deleted) is removed when the interrupt has finished executing.
Next Time
The next time an idle interrupt is triggered. Once a repeatable interrupt stats
executing, a copy of the interrupt will appear with the state Idle and the next time
set. For interrupts that do not have a next time—that is pending, executing, or
suspended—the column will show --.
Timing
The timing of the interrupt. For a Single and Forced interrupt, the activation
time is displayed. For a Repeat interrupt, the information has the form:
Activation Time + n*Repeat Time. For example, 2000 + n*2345. This
means that the first time this interrupt is triggered, is at 2000 cycles and after that
with an interval of 2345 cycles.
C-SPY® Debugging Guide
218
for STM8
AFE1_AFE2-1:1
Interrupts
Interrupt Log window
The Interrupt Log window is available from the C-SPY driver menu.
This window logs entrances to and exits from interrupts. The C-SPY simulator also logs
internal state changes.
The information is useful for debugging the interrupt handling in the target system.
When the Interrupt Log window is open, it is updated continuously at runtime.
Note: There is a limit on the number of saved logs. When this limit is exceeded, the
entries in the beginning of the buffer are erased.
For more information, see Getting started using interrupt logging, page 212.
For information about how to get a graphical view of the interrupt events during the
execution of your application, see Timeline window, page 174.
Requirements
The C-SPY simulator.
Display area
This area contains these columns:
Time
The time for the interrupt entrance, based on an internally specified clock
frequency.
219
AFE1_AFE2-1:1
Reference information on interrupts
This column is available when you have selected Show Time from the context
menu.
Cycles
The number of cycles from the start of the execution until the event.
This column is available when you have selected Show Cycles from the context
menu.
Interrupt
The interrupt as defined in the device description file.
Status
Shows the event status of the interrupt:
Triggered, the interrupt has passed its activation time.
Forced, the same as Triggered, but the interrupt was forced from the Forced
Interrupt window.
Enter, the interrupt is currently executing.
Leave, the interrupt has been executed.
Expired, the interrupt hold time has expired without the interrupt being
executed.
Rejected, the interrupt has been rejected because the necessary interrupt
registers were not set up to accept the interrupt.
Program Counter
The value of the program counter when the event occurred.
Execution Time/Cycles
The time spent in the interrupt, calculated using the Enter and Leave
timestamps. This includes time spent in any subroutines or other interrupts that
occurred in the specific interrupt.
C-SPY® Debugging Guide
220
for STM8
AFE1_AFE2-1:1
Interrupts
Context menu
This context menu is available in the Data Log window, the Data Log Summary
window, the Interrupt Log window, and in the Interrupt Log Summary window:
Note: The commands are the same in each window, but they only operate on the specific
window.
These commands are available:
Enable
Enables the logging system. The system will log information also when the
window is closed.
Clear
Deletes the log information. Note that this will happen also when you reset the
debugger.
Save to log file
Displays a standard file selection dialog box where you can select the
destination file for the log information. The entries in the log file are separated
by TAB and LF. An X in the Approx column indicates that the timestamp is an
approximation.
Show Time
Displays the Time column in the Data Log window and in the Interrupt Log
window, respectively.
This menu command might not be available in the C-SPY driver you are using,
which means that the Time column is by default displayed in the Data Log
window.
Show Cycles
Displays the Cycles column in the Data Log window and in the Interrupt Log
window, respectively.
This menu command might not be available in the C-SPY driver you are using,
which means that the Cycles column is not supported.
221
AFE1_AFE2-1:1
Reference information on interrupts
Interrupt Log Summary window
The Interrupt Log Summary window is available from the C-SPY driver menu.
This window displays a summary of logs of entrances to and exits from interrupts.
For more information, see Getting started using interrupt logging, page 212.
For information about how to get a graphical view of the interrupt events during the
execution of your application, see Timeline window, page 174.
Requirements
The C-SPY simulator.
Display area
Each row in this area displays statistics about the specific interrupt based on the log
information in these columns:
Interrupt
The type of interrupt that occurred.
At the bottom of the column,
Count
The number of times the interrupt occurred.
First time
The first time the interrupt was executed.
Total (Time)**
The accumulated time spent in the interrupt.
Total (%)
The time in percent of the current time.
Fastest**
The fastest execution of a single interrupt of this type.
C-SPY® Debugging Guide
222
for STM8
AFE1_AFE2-1:1
Interrupts
Slowest**
The slowest execution of a single interrupt of this type.
Min interval
The shortest time between two interrupts of this type.
The interval is specified as the time interval between the entry time for two
consecutive interrupts.
Max interval
The longest time between two interrupts of this type.
The interval is specified as the time interval between the entry time for two
consecutive interrupts.
** Calculated in the same way as for the Execution time/cycles in the Interrupt Log
window.
Context menu
This context menu is available in the Data Log window, the Data Log Summary
window, the Interrupt Log window, and in the Interrupt Log Summary window:
Note: The commands are the same in each window, but they only operate on the specific
window.
These commands are available:
Enable
Enables the logging system. The system will log information also when the
window is closed.
Clear
Deletes the log information. Note that this will happen also when you reset the
debugger.
Save to log file
Displays a standard file selection dialog box where you can select the
destination file for the log information. The entries in the log file are separated
by TAB and LF. An X in the Approx column indicates that the timestamp is an
approximation.
223
AFE1_AFE2-1:1
Reference information on interrupts
Show Time
Displays the Time column in the Data Log window and in the Interrupt Log
window, respectively.
This menu command might not be available in the C-SPY driver you are using,
which means that the Time column is by default displayed in the Data Log
window.
Show Cycles
Displays the Cycles column in the Data Log window and in the Interrupt Log
window, respectively.
This menu command might not be available in the C-SPY driver you are using,
which means that the Cycles column is not supported.
C-SPY® Debugging Guide
224
for STM8
AFE1_AFE2-1:1
C-SPY macros
C-SPY macros
●
Introduction to C-SPY macros
●
Using C-SPY macros
●
Reference information on the macro language
●
Reference information on reserved setup macro function names
●
Reference information on C-SPY system macros
●
Graphical environment for macros
Introduction to C-SPY macros
These topics are covered:
●
Reasons for using C-SPY macros
●
Briefly about using C-SPY macros
●
Briefly about setup macro functions and files
●
Briefly about the macro language
REASONS FOR USING C-SPY MACROS
You can use C-SPY macros either by themselves or in conjunction with complex
breakpoints and interrupt simulation to perform a wide variety of tasks. Some examples
where macros can be useful:
●
Automating the debug session, for instance with trace printouts, printing values of
variables, and setting breakpoints.
●
Hardware configuring, such as initializing hardware registers.
●
Feeding your application with simulated data during runtime.
●
Simulating peripheral devices, see the chapter Interrupts. This only applies if you
are using the simulator driver.
●
Developing small debug utility functions.
225
AFE1_AFE2-1:1
Introduction to C-SPY macros
BRIEFLY ABOUT USING C-SPY MACROS
To use C-SPY macros, you should:
●
Write your macro variables and functions and collect them in one or several macro
files
●
Register your macros
●
Execute your macros.
For registering and executing macros, there are several methods to choose between.
Which method you choose depends on which level of interaction or automation you
want, and depending on at which stage you want to register or execute your macro.
BRIEFLY ABOUT SETUP MACRO FUNCTIONS AND FILES
There are some reserved setup macro function names that you can use for defining
macro functions which will be called at specific times, such as:
●
Once after communication with the target system has been established but before
downloading the application software
●
Once after your application software has been downloaded
●
Each time the reset command is issued
●
Once when the debug session ends.
To define a macro function to be called at a specific stage, you should define and register
a macro function with one of the reserved names. For instance, if you want to clear a
specific memory area before you load your application software, the macro setup
function execUserPreload should be used. This function is also suitable if you want
to initialize some CPU registers or memory-mapped peripheral units before you load
your application software.
You should define these functions in a setup macro file, which you can load before
C-SPY starts. Your macro functions will then be automatically registered each time you
start C-SPY. This is convenient if you want to automate the initialization of C-SPY, or
if you want to register multiple setup macros.
For more information about each setup macro function, see Reference information on
reserved setup macro function names, page 237.
BRIEFLY ABOUT THE MACRO LANGUAGE
The syntax of the macro language is very similar to the C language. There are:
C-SPY® Debugging Guide
226
for STM8
AFE1_AFE2-1:1
●
Macro statements, which are similar to C statements.
●
Macro functions, which you can define with or without parameters and return
values.
C-SPY macros
●
Predefined built-in system macros, similar to C library functions, which perform
useful tasks such as opening and closing files, setting breakpoints, and defining
simulated interrupts.
●
Macro variables, which can be global or local, and can be used in C-SPY
expressions.
●
Macro strings, which you can manipulate using predefined system macros.
For more information about the macro language components, see Reference information
on the macro language, page 232.
Example
Consider this example of a macro function which illustrates the various components of
the macro language:
__var oldVal;
CheckLatest(val)
{
if (oldVal != val)
{
__message "Message: Changed from ", oldVal, " to ", val, "\n";
oldVal = val;
}
}
Note: Reserved macro words begin with double underscores to prevent name conflicts.
Using C-SPY macros
These tasks are covered:
●
Registering C-SPY macros—an overview
●
Executing C-SPY macros—an overview
●
Registering and executing using setup macros and setup files
●
Executing macros using Quick Watch
●
Executing a macro by connecting it to a breakpoint
●
Aborting a C-SPY macro
For more examples using C-SPY macros, see:
●
The tutorial about simulating an interrupt, which you can find in the Information
Center
●
Initializing target hardware before C-SPY starts, page 42.
227
AFE1_AFE2-1:1
Using C-SPY macros
REGISTERING C-SPY MACROS—AN OVERVIEW
C-SPY must know that you intend to use your defined macro functions, and thus you
must register your macros. There are various ways to register macro functions:
●
You can register macro functions during the C-SPY startup sequence, see
Registering and executing using setup macros and setup files, page 229.
●
You can register macros interactively in the Macro Registration window, see Macro
Registration window, page 272. Registered macros appear in the Debugger macros
window, see Debugger Macros window, page 274.
●
You can register a file containing macro function definitions, using the system
macro __registerMacroFile. This means that you can dynamically select which
macro files to register, depending on the runtime conditions. Using the system
macro also lets you register multiple files at the same moment. For information
about the system macro, see __registerMacroFile, page 257.
Which method you choose depends on which level of interaction or automation you
want, and depending on at which stage you want to register your macro.
EXECUTING C-SPY MACROS—AN OVERVIEW
There are various ways to execute macro functions:
●
You can execute macro functions during the C-SPY startup sequence and at other
predefined stages during the debug session by defining setup macro functions in a
setup macro file, see Registering and executing using setup macros and setup files,
page 229.
●
The Quick Watch window lets you evaluate expressions, and can thus be used for
executing macro functions. For an example, see Executing macros using Quick
Watch, page 229.
●
The Macro Quicklaunch window is similar to the Quick Watch window, but is more
specified on designed for C-SPY macros. See Macro Quicklaunch window, page
276.
●
A macro can be connected to a breakpoint; when the breakpoint is triggered the
macro is executed. For an example, see Executing a macro by connecting it to a
breakpoint, page 230.
Which method you choose depends on which level of interaction or automation you
want, and depending on at which stage you want to execute your macro.
C-SPY® Debugging Guide
228
for STM8
AFE1_AFE2-1:1
C-SPY macros
REGISTERING AND EXECUTING USING SETUP MACROS AND
SETUP FILES
It can be convenient to register a macro file during the C-SPY startup sequence. To do
this, specify a macro file which you load before starting the debug session. Your macro
functions will be automatically registered each time you start the debugger.
If you use the reserved setup macro function names to define the macro functions, you
can define exactly at which stage you want the macro function to be executed.
To define a setup macro function and load it during C-SPY startup:
1 Create a new text file where you can define your macro function.
For example:
execUserSetup()
{
...
_ _registerMacroFile("MyMacroUtils.mac");
_ _registerMacroFile("MyDeviceSimulation.mac");
}
This macro function registers the additional macro files MyMacroUtils.mac and
MyDeviceSimulation.mac. Because the macro function is defined with the function
name execUserSetup, it will be executed directly after your application has been
downloaded.
2 Save the file using the filename extension mac.
3 Before you start C-SPY, choose Project>Options>Debugger>Setup. Select Use
Setup file and choose the macro file you just created.
The macros will now be registered during the C-SPY startup sequence.
EXECUTING MACROS USING QUICK WATCH
The Quick Watch window lets you dynamically choose when to execute a macro
function.
1 Consider this simple macro function that checks the status of a timer enable bit:
TimerStatus()
{
if ((TimerStatreg & 0x01) != 0)/* Checks the status of reg */
return "Timer enabled"; /* C-SPY macro string used */
else
return "Timer disabled"; /* C-SPY macro string used */
}
229
AFE1_AFE2-1:1
Using C-SPY macros
2 Save the macro function using the filename extension mac.
3 To load the macro file, choose View>Macros>Macro Registration. The Macro
Registration window is displayed. Click Add and locate the file using the file browser.
The macro file appears in the list of macros in the Macro Registration window.
4 Select the macro you want to register and your macro will appear in the Debugger
Macros window.
5 Choose View>Quick Watch to open the Quick Watch window, type the macro call
TimerStatus() in the text field and press Return,
Alternatively, in the macro file editor window, select the macro function name
TimerStatus(). Right-click, and choose Quick Watch from the context menu that
appears.
The macro will automatically be displayed in the Quick Watch window.
For more information, see Quick Watch window, page 91.
EXECUTING A MACRO BY CONNECTING IT TO A
BREAKPOINT
You can connect a macro to a breakpoint. The macro will then be executed when the
breakpoint is triggered. The advantage is that you can stop the execution at locations of
particular interest and perform specific actions there.
For instance, you can easily produce log reports containing information such as how the
values of variables, symbols, or registers change. To do this you might set a breakpoint
on a suspicious location and connect a log macro to the breakpoint. After the execution
you can study how the values of the registers have changed.
To create a log macro and connect it to a breakpoint:
1 Assume this skeleton of a C function in your application source code:
int fact(int x)
{
...
}
C-SPY® Debugging Guide
230
for STM8
AFE1_AFE2-1:1
C-SPY macros
2 Create a simple log macro function like this example:
logfact()
{
__message "fact(" ,x, ")";
}
The __message statement will log messages to the Log window.
Save the macro function in a macro file, with the filename extension mac.
3 To register the macro, choose View>Macros>Macro Registration to open the Macro
Registration window and add your macro file to the list. Select the file to register it.
Your macro function will appear in the Debugger Macros window.
4 To set a code breakpoint, click the Toggle Breakpoint button on the first statement
within the function fact in your application source code. Choose View>Breakpoints
to open the Breakpoints window. Select your breakpoint in the list of breakpoints and
choose the Edit command from the context menu.
5 To connect the log macro function to the breakpoint, type the name of the macro
function, logfact(), in the Action field and click Apply. Close the dialog box.
6 Execute your application source code. When the breakpoint is triggered, the macro
function will be executed. You can see the result in the Log window.
●
Note that the expression in the Action field is evaluated only when the breakpoint
causes the execution to really stop. If you want to log a value and then automatically
continue execution, you can either:
●
Use the Condition field instead of the Action field. For an example, see Performing
a task and continuing execution, page 116.
Use a Log breakpoint, see Log breakpoints dialog box, page 124
7 You can easily enhance the log macro function by, for instance, using the __fmessage
statement instead, which will print the log information to a file. For information about
the __fmessage statement, see Formatted output, page 235.
For an example where a serial port input buffer is simulated using the method of
connecting a macro to a breakpoint, see the tutorial Simulating an interrupt in the
Information Center.
ABORTING A C-SPY MACRO
To abort a C-SPY macro:
1 Press Ctrl+Shift+. (period) for a short while.
2 A message that says that the macro has terminated is displayed in the Debug Log
window.
231
AFE1_AFE2-1:1
Reference information on the macro language
This method can be used if you suspect that something is wrong with the execution, for
example because it seems not to terminate in a reasonable time.
Reference information on the macro language
Reference information about:
●
Macro functions, page 232
●
Macro variables, page 232
●
Macro strings, page 233
●
Macro statements, page 234
●
Formatted output, page 235.
MACRO FUNCTIONS
C-SPY macro functions consist of C-SPY variable definitions and macro statements
which are executed when the macro is called. An unlimited number of parameters can
be passed to a macro function, and macro functions can return a value on exit.
A C-SPY macro has this form:
macroName (parameterList)
{
macroBody
}
where parameterList is a list of macro parameters separated by commas, and
macroBody is any series of C-SPY variable definitions and C-SPY statements.
Type checking is neither performed on the values passed to the macro functions nor on
the return value.
MACRO VARIABLES
A macro variable is a variable defined and allocated outside your application. It can then
be used in a C-SPY expression, or you can assign application data—values of the
variables in your application—to it. For more information about C-SPY expressions, see
C-SPY expressions, page 74.
The syntax for defining one or more macro variables is:
__var nameList;
where nameList is a list of C-SPY variable names separated by commas.
C-SPY® Debugging Guide
232
for STM8
AFE1_AFE2-1:1
C-SPY macros
A macro variable defined outside a macro body has global scope, and it exists
throughout the whole debugging session. A macro variable defined within a macro body
is created when its definition is executed and destroyed on return from the macro.
By default, macro variables are treated as signed integers and initialized to 0. When a
C-SPY variable is assigned a value in an expression, it also acquires the type of that
expression. For example:
Expression
What it means
myvar = 3.5;
myvar is now type double, value 3.5.
myvar = (int*)i;
myvar is now type pointer to int, and the value is the same as i.
Table 13: Examples of C-SPY macro variables
In case of a name conflict between a C symbol and a C-SPY macro variable, C-SPY
macro variables have a higher precedence than C variables. Note that macro variables
are allocated on the debugger host and do not affect your application.
MACRO STRINGS
In addition to C types, macro variables can hold values of macro strings. Note that
macro strings differ from C language strings.
When you write a string literal, such as "Hello!", in a C-SPY expression, the value is
a macro string. It is not a C-style character pointer char*, because char* must point to
a sequence of characters in target memory and C-SPY cannot expect any string literal to
actually exist in target memory.
You can manipulate a macro string using a few built-in macro functions, for example
__strFind or __subString. The result can be a new macro string. You can
concatenate macro strings using the + operator, for example str + "tail". You can
also access individual characters using subscription, for example str[3]. You can get the
length of a string using sizeof(str). Note that a macro string is not
NULL-terminated.
The macro function __toString is used for converting from a NULL-terminated C
string in your application (char* or char[]) to a macro string. For example, assume
this definition of a C string in your application:
char const *cstr = "Hello";
233
AFE1_AFE2-1:1
Reference information on the macro language
Then examine these macro examples:
__var str;
/* A macro variable */
str = cstr
/* str is now just a pointer to char */
sizeof str
/* same as sizeof (char*), typically 2 or 4 */
str = __toString(cstr,512) /* str is now a macro string */
sizeof str
/* 5, the length of the string */
str[1]
/* 101, the ASCII code for 'e' */
str += " World!"
/* str is now "Hello World!" */
See also Formatted output, page 235.
MACRO STATEMENTS
Statements are expected to behave in the same way as the corresponding C statements
would do. The following C-SPY macro statements are accepted:
Expressions
expression;
For more information about C-SPY expressions, see C-SPY expressions, page 74.
Conditional statements
if (expression)
statement
if (expression)
statement
else
statement
Loop statements
for (init_expression; cond_expression; update_expression)
statement
while (expression)
statement
do
statement
while (expression);
C-SPY® Debugging Guide
234
for STM8
AFE1_AFE2-1:1
C-SPY macros
Return statements
return;
return expression;
If the return value is not explicitly set, signed int 0 is returned by default.
Blocks
Statements can be grouped in blocks.
{
statement1
statement2
.
.
.
statementN
}
FORMATTED OUTPUT
C-SPY provides various methods for producing formatted output:
__message argList;
Prints the output to the Debug Log window.
__fmessage file, argList; Prints the output to the designated file.
__smessage argList;
Returns a string containing the formatted output.
where argList is a comma-separated list of C-SPY expressions or strings, and file is
the result of the __openFile system macro, see __openFile, page 251.
To produce messages in the Debug Log window:
var1 = 42;
var2 = 37;
__message "This line prints the values ", var1, " and ", var2,
" in the Log window.";
This produces this message in the Log window:
This line prints the values 42 and 37 in the Log window.
To write the output to a designated file:
__fmessage myfile, "Result is ", res, "!\n";
235
AFE1_AFE2-1:1
Reference information on the macro language
To produce strings:
myMacroVar = __smessage 42, " is the answer.";
myMacroVar now contains the string "42 is the answer.".
Specifying display format of arguments
To override the default display format of a scalar argument (number or pointer) in
argList, suffix it with a : followed by a format specifier. Available specifiers are:
%b
for binary scalar arguments
%o
for octal scalar arguments
%d
for decimal scalar arguments
%x
for hexadecimal scalar arguments
%c
for character scalar arguments
These match the formats available in the Watch and Locals windows, but number
prefixes and quotes around strings and characters are not printed. Another example:
__message "The character '", cvar:%c, "' has the decimal value
", cvar;
Depending on the value of the variables, this produces this message:
The character 'A' has the decimal value 65
Note: A character enclosed in single quotes (a character literal) is an integer constant
and is not automatically formatted as a character. For example:
__message 'A', " is the numeric value of the character ",
'A':%c;
would produce:
65 is the numeric value of the character A
Note: The default format for certain types is primarily designed to be useful in the
Watch window and other related windows. For example, a value of type char is
formatted as 'A' (0x41), while a pointer to a character (potentially a C string) is
formatted as 0x8102 "Hello", where the string part shows the beginning of the string
(currently up to 60 characters).
When printing a value of type char*, use the %x format specifier to print just the pointer
value in hexadecimal notation, or use the system macro __toString to get the full
string value.
C-SPY® Debugging Guide
236
for STM8
AFE1_AFE2-1:1
C-SPY macros
Reference information on reserved setup macro function names
There are reserved setup macro function names that you can use for defining your setup
macro functions. By using these reserved names, your function will be executed at
defined stages during execution. For more information, see Briefly about setup macro
functions and files, page 226.
Reference information about:
●
execUserPreload
●
execUserExecutionStarted
●
execUserExecutionStopped
●
execUserSetup
●
execUserPreReset
●
execUserReset
●
execUserExit
execUserPreload
Syntax
execUserPreload
For use with
All C-SPY drivers.
Description
Called after communication with the target system is established but before
downloading the target application.
Implement this macro to initialize memory locations and/or registers which are vital for
loading data properly.
execUserExecutionStarted
Syntax
execUserExecutionStarted
For use with
All C-SPY drivers.
Description
Called when the debugger is about to start or resume execution. The macro is not called
when performing a one-instruction assembler step, in other words, Step or Step Into in
the Disassembly window.
237
AFE1_AFE2-1:1
Reference information on reserved setup macro function names
execUserExecutionStopped
Syntax
execUserExecutionStopped
For use with
All C-SPY drivers.
Description
Called when the debugger has stopped execution. The macro is not called when
performing a one-instruction assembler step, in other words, Step or Step Into in the
Disassembly window.
execUserSetup
Syntax
execUserSetup
For use with
All C-SPY drivers.
Description
Called once after the target application is downloaded.
Implement this macro to set up the memory map, breakpoints, interrupts, register macro
files, etc.
If you define interrupts or breakpoints in a macro file that is executed at system start
(using execUserSetup) we strongly recommend that you also make sure that they are
removed at system shutdown (using execUserExit). An example is available in
SetupSimple.mac, see the tutorials in the Information Center.
The reason for this is that the simulator saves interrupt settings between sessions and if
they are not removed they will get duplicated every time execUserSetup is executed
again. This seriously affects the execution speed.
execUserPreReset
Syntax
execUserPreReset
For use with
All C-SPY drivers.
Description
Called each time just before the reset command is issued.
Implement this macro to set up any required device state.
execUserReset
Syntax
C-SPY® Debugging Guide
238
for STM8
AFE1_AFE2-1:1
execUserReset
C-SPY macros
For use with
All C-SPY drivers.
Description
Called each time just after the reset command is issued.
Implement this macro to set up and restore data.
execUserExit
Syntax
execUserExit
For use with
All C-SPY drivers.
Description
Called once when the debug session ends.
Implement this macro to save status data etc.
Reference information on C-SPY system macros
This section gives reference information about each of the C-SPY system macros.
This table summarizes the pre-defined system macros:
Macro
Description
__cancelAllInterrupts
Cancels all ordered interrupts
__cancelInterrupt
Cancels an interrupt
__clearBreak
Clears a breakpoint
__closeFile
Closes a file that was opened by __openFile
__delay
Delays execution
__disableInterrupts
Disables generation of interrupts
__driverType
Verifies the driver type
__enableInterrupts
Enables generation of interrupts
__evaluate
Interprets the input string as an expression and
evaluates it.
__fillMemory8
Fills a specified memory area with a byte value.
__fillMemory16
Fills a specified memory area with a 2-byte value.
__fillMemory32
Fills a specified memory area with a 4-byte value.
__isBatchMode
Checks if C-SPY is running in batch mode or not.
__loadImage
Loads an image.
Table 14: Summary of system macros
239
AFE1_AFE2-1:1
Reference information on C-SPY system macros
Macro
Description
__memoryRestore
Restores the contents of a file to a specified
memory zone
__memorySave
Saves the contents of a specified memory area to a
file
__messageBoxYesNo
Displays a Yes/No dialog box for user interaction
__openFile
Opens a file for I/O operations
__orderInterrupt
Generates an interrupt
__popSimulatorInterruptExecu Informs the interrupt simulation system that an
tingStack
interrupt handler has finished executing
__readFile
Reads from the specified file
__readFileByte
Reads one byte from the specified file
__readMemory8,
__readMemoryByte
Reads one byte from the specified memory location
__readMemory16
Reads two bytes from the specified memory
location
__readMemory32
Reads four bytes from the specified memory
location
__registerMacroFile
Registers macros from the specified file
__resetFile
Rewinds a file opened by __openFile
__setCodeBreak
Sets a code breakpoint
__setDataBreak
Sets a data breakpoint
__setDataLogBreak
Sets a data log breakpoint
__setLogBreak
Sets a log breakpoint
__setSimBreak
Sets a simulation breakpoint
__setTraceStartBreak
Sets a trace start breakpoint
__setTraceStopBreak
Sets a trace stop breakpoint
__sourcePosition
Returns the file name and source location if the
current execution location corresponds to a source
location
__strFind
Searches a given string for the occurrence of
another string
__subString
Extracts a substring from another string
__targetDebuggerVersion
Returns the version of the target debugger
Table 14: Summary of system macros (Continued)
C-SPY® Debugging Guide
240
for STM8
AFE1_AFE2-1:1
C-SPY macros
Macro
Description
__toLower
Returns a copy of the parameter string where all the
characters have been converted to lower case
__toString
Prints strings
__toUpper
Returns a copy of the parameter string where all the
characters have been converted to upper case
__unloadImage
Unloads a debug image.
__writeFile
Writes to the specified file
__writeFileByte
Writes one byte to the specified file
__writeMemory8,
__writeMemoryByte
Writes one byte to the specified memory location
__writeMemory16
Writes a two-byte word to the specified memory
location
__writeMemory32
Writes a four-byte word to the specified memory
location
Table 14: Summary of system macros (Continued)
__cancelAllInterrupts
Syntax
__cancelAllInterrupts()
Return value
int 0
For use with
The C-SPY Simulator.
Description
Cancels all ordered interrupts.
__cancelInterrupt
Syntax
__cancelInterrupt(interrupt_id)
Parameters
interrupt_id
The value returned by the corresponding __orderInterrupt macro call
(unsigned long).
Return value
Result
Value
Successful
int 0
Table 15: __cancelInterrupt return values
241
AFE1_AFE2-1:1
Reference information on C-SPY system macros
Result
Value
Unsuccessful
Non-zero error number
Table 15: __cancelInterrupt return values
For use with
The C-SPY Simulator.
Description
Cancels the specified interrupt.
__clearBreak
Syntax
__clearBreak(break_id)
Parameters
break_id
The value returned by any of the set breakpoint macros.
Return value
int 0
For use with
All C-SPY drivers.
Description
Clears a user-defined breakpoint.
See also
Breakpoints, page 107.
__closeFile
Syntax
__closeFile(fileHandle)
Parameters
fileHandle
A macro variable used as filehandle by the __openFile macro.
Return value
int 0
For use with
All C-SPY drivers.
Description
Closes a file previously opened by __openFile.
__delay
Syntax
C-SPY® Debugging Guide
242
for STM8
AFE1_AFE2-1:1
__delay(value)
C-SPY macros
Parameters
value
The number of milliseconds to delay execution.
Return value
int 0
For use with
All C-SPY drivers.
Description
Delays execution the specified number of milliseconds.
__disableInterrupts
Syntax
__disableInterrupts()
Return value
Result
Value
Successful
int 0
Unsuccessful
Non-zero error number
Table 16: __disableInterrupts return values
For use with
The C-SPY Simulator.
Description
Disables the generation of interrupts.
__driverType
Syntax
__driverType(driver_id)
Parameters
driver_id
A string corresponding to the driver you want to check for. Choose one of these:
"sim" corresponds to the simulator driver.
"stlink" corresponds to the C-SPY ST-LINK driver.
"stice" corresponds to the C-SPY STice driver.
Return value
Result
Value
Successful
1
Unsuccessful
0
Table 17: __driverType return values
243
AFE1_AFE2-1:1
Reference information on C-SPY system macros
For use with
All C-SPY drivers
Description
Checks to see if the current C-SPY driver is identical to the driver type of the
driver_id parameter.
Example
__driverType("sim")
If the simulator is the current driver, the value 1 is returned. Otherwise 0 is returned.
__enableInterrupts
Syntax
__enableInterrupts()
Return value
Result
Value
Successful
int 0
Unsuccessful
Non-zero error number
Table 18: __enableInterrupts return values
For use with
The C-SPY Simulator.
Description
Enables the generation of interrupts.
__evaluate
Syntax
__evaluate(string, valuePtr)
Parameters
string
Expression string.
valuePtr
Pointer to a macro variable storing the result.
Return value
Result
Value
Successful
int 0
Unsuccessful
int 1
Table 19: __evaluate return values
For use with
C-SPY® Debugging Guide
244
for STM8
AFE1_AFE2-1:1
All C-SPY drivers.
C-SPY macros
Description
This macro interprets the input string as an expression and evaluates it. The result is
stored in a variable pointed to by valuePtr.
Example
This example assumes that the variable i is defined and has the value 5:
__evaluate("i + 3", &myVar)
The macro variable myVar is assigned the value 8.
__fillMemory8
Syntax
__fillMemory8(value, address, zone, length, format)
Parameters
value
An integer that specifies the value.
address
An integer that specifies the memory start address.
zone
A string that specifies the memory zone, see C-SPY memory zones, page 134.
length
An integer that specifies how many bytes are affected.
format
One of these alternatives:
Copy
value will be copied to the specified memory area.
AND
An AND operation will be performed between value and the
existing contents of memory before writing the result to memory.
OR
An OR operation will be performed between value and the
existing contents of memory before writing the result to memory.
XOR
An XOR operation will be performed between value and the
existing contents of memory before writing the result to memory.
Return value
int 0
For use with
All C-SPY drivers.
Description
Fills a specified memory area with a byte value.
245
AFE1_AFE2-1:1
Reference information on C-SPY system macros
Example
__fillMemory8(0x80, 0x700, "", 0x10, "OR");
__fillMemory16
Syntax
__fillMemory16(value, address, zone, length, format)
Parameters
value
An integer that specifies the value.
address
An integer that specifies the memory start address.
zone
A string that specifies the memory zone, see C-SPY memory zones, page 134.
length
An integer that defines how many 2-byte entities to be affected.
format
One of these alternatives:
Copy
value will be copied to the specified memory area.
AND
An AND operation will be performed between value and the
existing contents of memory before writing the result to memory.
OR
An OR operation will be performed between value and the
existing contents of memory before writing the result to memory.
XOR
An XOR operation will be performed between value and the
existing contents of memory before writing the result to memory.
Return value
int 0
For use with
All C-SPY drivers.
Description
Fills a specified memory area with a 2-byte value.
Example
__fillMemory16(0xCDCD, 0x7000, "", 0x200, "Copy");
__fillMemory32
Syntax
C-SPY® Debugging Guide
246
for STM8
AFE1_AFE2-1:1
__fillMemory32(value, address, zone, length, format)
C-SPY macros
Parameters
value
An integer that specifies the value.
address
An integer that specifies the memory start address.
zone
A string that specifies the memory zone, see C-SPY memory zones, page 134.
length
An integer that defines how many 4-byte entities to be affected.
format
One of these alternatives:
Copy
value will be copied to the specified memory area.
AND
An AND operation will be performed between value
and the existing contents of memory before writing
the result to memory.
OR
An OR operation will be performed between value
and the existing contents of memory before writing
the result to memory.
XOR
An XOR operation will be performed between value
and the existing contents of memory before writing
the result to memory.
Return value
int 0
For use with
All C-SPY drivers.
Description
Fills a specified memory area with a 4-byte value.
Example
__fillMemory32(0x0000FFFF, 0x4000, "", 0x1000, "XOR");
__isBatchMode
Syntax
__isBatchMode()
247
AFE1_AFE2-1:1
Reference information on C-SPY system macros
Return value
Result
Value
True
int 1
False
int 0
Table 20: __isBatchMode return values
For use with
All C-SPY drivers.
Description
This macro returns True if the debugger is running in batch mode, otherwise it returns
False.
__loadImage
Syntax
__loadImage(path, offset, debugInfoOnly)
Parameters
path
A string that identifies the path to the image to download. The path must either
be absolute or use argument variables. For information about argument
variables, see the IDE Project Management and Building Guide.
offset
An integer that identifies the offset to the destination address for the downloaded
image.
debugInfoOnly
A non-zero integer value if no code or data should be downloaded to the target
system, which means that C-SPY will only read the debug information from the
debug file. Or, 0 (zero) for download.
Return value
Value
Result
Non-zero integer number
A unique module identification.
int 0
Loading failed.
Table 21: __loadImage return values
For use with
All C-SPY drivers.
Description
Loads an image (debug file).
Note: Flash loading will not be performed; using the Images options you can only
download images to RAM.
C-SPY® Debugging Guide
248
for STM8
AFE1_AFE2-1:1
C-SPY macros
Example 1
Your system consists of a ROM library and an application. The application is your active
project, but you have a debug file corresponding to the library. In this case you can add
this macro call in the execUserSetup macro in a C-SPY macro file, which you
associate with your project:
__loadImage(ROMfile, 0x8000, 1);
This macro call loads the debug information for the ROM library ROMfile without
downloading its contents (because it is presumably already in ROM). Then you can
debug your application together with the library.
Example 2
Your system consists of a ROM library and an application, but your main concern is the
library. The library needs to be programmed into flash memory before a debug session.
While you are developing the library, the library project must be the active project in the
IDE. In this case you can add this macro call in the execUserSetup macro in a C-SPY
macro file, which you associate with your project:
__loadImage(ApplicationFile, 0x8000, 0);
The macro call loads the debug information for the application and downloads its
contents (presumably into RAM). Then you can debug your library together with the
application.
See also
Images, page 295 and Loading multiple images, page 41.
__memoryRestore
Syntax
__memoryRestore(zone, filename)
Parameters
zone
A string that specifies the memory zone, see C-SPY memory zones, page 134.
filename
A string that specifies the file to be read. The filename must include a path,
which must either be absolute or use argument variables. For information about
argument variables, see the IDE Project Management and Building Guide.
Return value
int 0
For use with
All C-SPY drivers.
Description
Reads the contents of a file and saves it to the specified memory zone.
Example
__memoryRestore("", "c:\\temp\\saved_memory.hex");
249
AFE1_AFE2-1:1
Reference information on C-SPY system macros
See also
Memory Restore dialog box, page 144.
__memorySave
Syntax
__memorySave(start, stop, format, filename)
Parameters
start
A string that specifies the first location of the memory area to be saved.
stop
A string that specifies the last location of the memory area to be saved.
format
A string that specifies the format to be used for the saved memory. Choose
between:
intel-extended
motorola
motorola-s19
motorola-s28
motorola-s37.
filename
A string that specifies the file to write to. The filename must include a path,
which must either be absolute or use argument variables. For information about
argument variables, see the IDE Project Management and Building Guide.
Return value
int 0
For use with
All C-SPY drivers.
Description
Saves the contents of a specified memory area to a file.
Example
__memorySave(":0x00", ":0xFF", "intel-extended",
"c:\\temp\\saved_memory.hex");
See also
Memory Save dialog box, page 143.
__messageBoxYesNo
Syntax
C-SPY® Debugging Guide
250
for STM8
AFE1_AFE2-1:1
__messageBoxYesNo(string message, string caption)
C-SPY macros
Parameters
message
A message that will appear in the message box.
caption
The title that will appear in the message box.
Return value
Result
Value
Yes
1
No
0
Table 22: __messageBoxYesNo return values
For use with
All C-SPY drivers.
Description
Displays a Yes/No dialog box when called and returns the user input. Typically, this is
useful for creating macros that require user interaction.
__openFile
Syntax
__openFile(filename, access)
Parameters
filename
The file to be opened. The filename must include a path, which must either be
absolute or use argument variables. For information about argument variables,
see the IDE Project Management and Building Guide.
access
The access type (string).
These are mandatory but mutually exclusive:
"a" append, new data will be appended at the end of the open file
"r" read (by default in text mode; combine with b for binary mode: rb)
"w" write (by default in text mode; combine with b for binary mode: wb)
These are optional and mutually exclusive:
"b" binary, opens the file in binary mode
"t" ASCII text, opens the file in text mode
251
AFE1_AFE2-1:1
Reference information on C-SPY system macros
This access type is optional:
"+" together with r, w, or a; r+ or w+ is read and write, while a+ is read and
append
Return value
Result
Value
Successful
The file handle
Unsuccessful
An invalid file handle, which tests as False
Table 23: __openFile return values
For use with
All C-SPY drivers.
Description
Opens a file for I/O operations. The default base directory of this macro is where the
currently open project file (*.ewp) is located. The argument to __openFile can
specify a location relative to this directory. In addition, you can use argument variables
such as $PROJ_DIR$ and $TOOLKIT_DIR$ in the path argument.
Example
__var myFileHandle;
See also
For information about argument variables, see the IDE Project Management and
Building Guide.
/* The macro variable to contain */
/* the file handle */
myFileHandle = __openFile("$PROJ_DIR$\\Debug\\Exe\\test.tst",
"r");
if (myFileHandle)
{
/* successful opening */
}
__orderInterrupt
Syntax
__orderInterrupt(specification, first_activation,
repeat_interval, variance, infinite_hold_time,
hold_time, probability)
Parameters
specification
The interrupt (string). The specification can either be the full specification used
in the device description file (ddf) or only the name. In the latter case the
interrupt system will automatically get the description from the device
description file.
C-SPY® Debugging Guide
252
for STM8
AFE1_AFE2-1:1
C-SPY macros
first_activation
The first activation time in cycles (integer)
repeat_interval
The periodicity in cycles (integer)
variance
The timing variation range in percent (integer between 0 and 100)
infinite_hold_time
1 if infinite, otherwise 0.
hold_time
The hold time (integer)
probability
The probability in percent (integer between 0 and 100)
Return value
The macro returns an interrupt identifier (unsigned long).
If the syntax of specification is incorrect, it returns -1.
For use with
The C-SPY Simulator.
Description
Generates an interrupt.
Example
This example generates a repeating interrupt using an infinite hold time first activated
after 4000 cycles:
__orderInterrupt( "UART1_R_RXNE", 4000, 2000, 0, 1, 0, 100 );
__popSimulatorInterruptExecutingStack
Syntax
__popSimulatorInterruptExecutingStack(void)
Return value
int 0
For use with
The C-SPY Simulator.
Description
Informs the interrupt simulation system that an interrupt handler has finished executing,
as if the normal instruction used for returning from an interrupt handler was executed.
This is useful if you are using interrupts in such a way that the normal instruction for
returning from an interrupt handler is not used, for example in an operating system with
253
AFE1_AFE2-1:1
Reference information on C-SPY system macros
task-switching. In this case, the interrupt simulation system cannot automatically detect
that the interrupt has finished executing.
See also
Simulating an interrupt in a multi-task system, page 211.
__readFile
Syntax
__readFile(fileHandle, valuePtr)
Parameters
fileHandle
A macro variable used as filehandle by the __openFile macro.
valuePtr
A pointer to a variable.
Return value
Result
Value
Successful
0
Unsuccessful
Non-zero error number
Table 24: __readFile return values
For use with
Description
All C-SPY drivers.
Reads a sequence of hexadecimal digits from the given file and converts them to an
unsigned long which is assigned to the value parameter, which should be a pointer
to a macro variable.
Only printable characters representing hexadecimal digits and white-space characters
are accepted, no other characters are allowed.
Example
__var number;
if (__readFile(myFileHandle, &number) == 0)
{
// Do something with number
}
In this example, if the file pointed to by myFileHandle contains the ASCII characters
1234 abcd 90ef, consecutive reads will assign the values 0x1234 0xabcd 0x90ef
to the variable number.
C-SPY® Debugging Guide
254
for STM8
AFE1_AFE2-1:1
C-SPY macros
__readFileByte
Syntax
__readFileByte(fileHandle)
Parameters
fileHandle
A macro variable used as filehandle by the __openFile macro.
Return value
-1 upon error or end-of-file, otherwise a value between 0 and 255.
For use with
All C-SPY drivers.
Description
Reads one byte from a file.
Example
__var byte;
while ( (byte = __readFileByte(myFileHandle)) != -1 )
{
/* Do something with byte */
}
__readMemory8, __readMemoryByte
Syntax
__readMemory8(address, zone)
__readMemoryByte(address, zone)
Parameters
address
The memory address (integer).
zone
A string that specifies the memory zone, see C-SPY memory zones, page 134.
Return value
The macro returns the value from memory.
For use with
All C-SPY drivers.
Description
Reads one byte from a given memory location.
Example
__readMemory8(0x0108, "");
255
AFE1_AFE2-1:1
Reference information on C-SPY system macros
__readMemory16
Syntax
__readMemory16(address, zone)
Parameters
address
The memory address (integer).
zone
A string that specifies the memory zone, see C-SPY memory zones, page 134.
Return value
The macro returns the value from memory.
For use with
All C-SPY drivers.
Description
Reads a two-byte word from a given memory location.
Example
__readMemory16(0x0108, "");
__readMemory32
Syntax
__readMemory32(address, zone)
Parameters
address
The memory address (integer).
zone
A string that specifies the memory zone, see C-SPY memory zones, page 134.
Return value
The macro returns the value from memory.
For use with
All C-SPY drivers.
Description
Reads a four-byte word from a given memory location.
Example
__readMemory32(0x0108, "");
C-SPY® Debugging Guide
256
for STM8
AFE1_AFE2-1:1
C-SPY macros
__registerMacroFile
Syntax
__registerMacroFile(filename)
Parameters
filename
A file containing the macros to be registered (string). The filename must include
a path, which must either be absolute or use argument variables. For information
about argument variables, see the IDE Project Management and Building
Guide.
Return value
int 0
For use with
All C-SPY drivers.
Description
Registers macros from a setup macro file. With this function you can register multiple
macro files during C-SPY startup.
Example
__registerMacroFile("c:\\testdir\\macro.mac");
See also
Using C-SPY macros, page 227.
__resetFile
Syntax
__resetFile(fileHandle)
Parameters
fileHandle
A macro variable used as filehandle by the __openFile macro.
Return value
int 0
For use with
All C-SPY drivers.
Description
Rewinds a file previously opened by __openFile.
257
AFE1_AFE2-1:1
Reference information on C-SPY system macros
__setCodeBreak
Syntax
__setCodeBreak(location, count, condition, cond_type, action)
Parameters
location
A string that defines the code location of the breakpoint, either a valid C-SPY
expression whose value evaluates to a valid address, an absolute location, or a
source location. For more information about the location types, see Enter
Location dialog box, page 130.
count
The number of times that a breakpoint condition must be fulfilled before a break
occurs (integer).
condition
The breakpoint condition (string).
cond_type
The condition type; either "CHANGED" or "TRUE" (string).
action
An expression, typically a call to a macro, which is evaluated when the
breakpoint is detected.
Return value
Result
Value
Successful
An unsigned integer uniquely identifying the breakpoint. This value
must be used to clear the breakpoint.
Unsuccessful
0
Table 25: __setCodeBreak return values
For use with
The C-SPY hardware debugger drivers.
Description
Sets a code breakpoint, that is, a breakpoint which is triggered just before the processor
fetches an instruction at the specified location.
Examples
__setCodeBreak("{D:\\src\\prog.c}.12.9", 3, "d>16", "TRUE",
"ActionCode()");
This example sets a code breakpoint on the label main in your source:
__setCodeBreak("main", 0, "1", "TRUE", "");
See also
C-SPY® Debugging Guide
258
for STM8
AFE1_AFE2-1:1
Breakpoints, page 107.
C-SPY macros
__setDataBreak
Syntax
__setDataBreak(location, count, condition, cond_type, access,
action)
Parameters
location
A string that defines the data location of the breakpoint, either a valid C-SPY
expression whose value evaluates to a valid address or an absolute location. For
more information about the location types, see Enter Location dialog box, page
130.
count
The number of times that a breakpoint condition must be fulfilled before a break
occurs (integer).
condition
The breakpoint condition (string).
cond_type
The condition type; either "CHANGED" or "TRUE" (string).
access
The memory access type: "R", for read, "W" for write, or "RW" for read/write.
action
An expression, typically a call to a macro, which is evaluated when the
breakpoint is detected.
Return value
Result
Value
Successful
An unsigned integer uniquely identifying the breakpoint. This value
must be used to clear the breakpoint.
Unsuccessful
0
Table 26: __setDataBreak return values
For use with
The C-SPY driver for ST-LINK
The C-SPY driver for STice, using SWIM mode.
Description
Sets a data breakpoint, that is, a breakpoint which is triggered directly after the processor
has read or written data at the specified location.
259
AFE1_AFE2-1:1
Reference information on C-SPY system macros
Example
__var brk;
brk = __setDataBreak(":0x4710", 3, "d>6", "TRUE",
"W", "ActionData()");
...
__clearBreak(brk);
See also
Breakpoints, page 107.
__setDataLogBreak
Syntax
__setDataLogBreak(location, access)
Parameters
location
A string that defines the data location of the breakpoint, either a valid C-SPY
expression whose value evaluates to a valid address or an absolute location. For
more information about the location types, see Enter Location dialog box, page
130.
access
The memory access type: "R", for read, "W" for write, or "RW" for read/write.
Return value
Result
Value
Successful
An unsigned integer uniquely identifying the breakpoint. This value
must be used to clear the breakpoint.
Unsuccessful
0
Table 27: __setDataLogBreak return values
For use with
The C-SPY Simulator.
Description
Sets a data log breakpoint, that is, a breakpoint which is triggered when the processor
reads or writes data at the specified location. Note that a data log breakpoint does not
stop the execution it just generates a data log.
Example
__var brk;
brk = __setDataLogBreak("Memory:0x4710", "R");
...
__clearBreak(brk);
See also
Breakpoints, page 107 and Getting started using data logging, page 79.
C-SPY® Debugging Guide
260
for STM8
AFE1_AFE2-1:1
C-SPY macros
__setLogBreak
Syntax
__setLogBreak(location, message, msg_type, condition,
cond_type)
Parameters
location
A string that defines the code location of the breakpoint, either a valid C-SPY
expression whose value evaluates to a valid address, an absolute location, or a
source location. For more information about the location types, see Enter
Location dialog box, page 130.
message
The message text.
msg_type
The message type; choose between:
TEXT, the message is written word for word.
ARGS, the message is interpreted as a comma-separated list of C-SPY
expressions or strings.
condition
The breakpoint condition (string).
cond_type
The condition type; either "CHANGED" or "TRUE" (string).
Return value
Result
Value
Successful
An unsigned integer uniquely identifying the breakpoint. The same
value must be used when you want to clear the breakpoint.
Unsuccessful
0
Table 28: __setLogBreak return values
For use with
The C-SPY Simulator.
Description
Sets a log breakpoint, that is, a breakpoint which is triggered when an instruction is
fetched from the specified location. If you have set the breakpoint on a specific machine
instruction, the breakpoint will be triggered and the execution will temporarily halt and
print the specified message in the C-SPY Debug Log window.
261
AFE1_AFE2-1:1
Reference information on C-SPY system macros
Example
__var logBp1;
__var logBp2;
logOn()
{
logBp1 = __setLogBreak ("{C:\\temp\\Utilities.c}.23.1",
"\"Entering trace zone at :\", #PC:%X", "ARGS", "1", "TRUE");
logBp2 = __setLogBreak ("{C:\\temp\\Utilities.c}.30.1",
"Leaving trace zone...", "TEXT", "1", "TRUE");
}
logOff()
{
__clearBreak(logBp1);
__clearBreak(logBp2);
}
See also
Formatted output, page 235 and Breakpoints, page 107.
__setSimBreak
Syntax
__setSimBreak(location, access, action)
Parameters
location
A string that defines the data location of the breakpoint, either a valid C-SPY
expression whose value evaluates to a valid address or an absolute location. For
more information about the location types, see Enter Location dialog box, page
130.
access
The memory access type: "R" for read or "W" for write.
action
An expression, typically a call to a macro, which is evaluated when the
breakpoint is detected.
Return value
Result
Value
Successful
An unsigned integer uniquely identifying the breakpoint. This value
must be used to clear the breakpoint.
Unsuccessful
0
Table 29: __setSimBreak return values
For use with
C-SPY® Debugging Guide
262
for STM8
AFE1_AFE2-1:1
The C-SPY Simulator.
C-SPY macros
Description
Use this system macro to set immediate breakpoints, which will halt instruction
execution only temporarily. This allows a C-SPY macro function to be called when the
processor is about to read data from a location or immediately after it has written data.
Instruction execution will resume after the action.
This type of breakpoint is useful for simulating memory-mapped devices of various
kinds (for instance serial ports and timers). When the processor reads at a
memory-mapped location, a C-SPY macro function can intervene and supply the
appropriate data. Conversely, when the processor writes to a memory-mapped location,
a C-SPY macro function can act on the value that was written.
__setTraceStartBreak
Syntax
__setTraceStartBreak(location)
Parameters
location
A string that defines the code location of the breakpoint, either a valid C-SPY
expression whose value evaluates to a valid address, an absolute location, or a
source location. For more information about the location types, see Enter
Location dialog box, page 130.
Return value
Result
Value
Successful
An unsigned integer uniquely identifying the breakpoint. The same
value must be used when you want to clear the breakpoint.
Unsuccessful
0
Table 30: __setTraceStartBreak return values
For use with
The C-SPY Simulator.
Description
Sets a breakpoint at the specified location. When that breakpoint is triggered, the trace
system is started.
263
AFE1_AFE2-1:1
Reference information on C-SPY system macros
Example
__var startTraceBp;
__var stopTraceBp;
traceOn()
{
startTraceBp = __setTraceStartBreak
("{C:\\TEMP\\Utilities.c}.23.1");
stopTraceBp = __setTraceStopBreak
("{C:\\temp\\Utilities.c}.30.1");
}
traceOff()
{
__clearBreak(startTraceBp);
__clearBreak(stopTraceBp);
}
See also
Breakpoints, page 107.
__setTraceStopBreak
Syntax
__setTraceStopBreak(location)
Parameters
location
A string that defines the code location of the breakpoint, either a valid C-SPY
expression whose value evaluates to a valid address, an absolute location, or a
source location. For more information about the location types, see Enter
Location dialog box, page 130.
Return value
Result
Value
Successful
An unsigned integer uniquely identifying the breakpoint. The same
value must be used when you want to clear the breakpoint.
Unsuccessful
int 0
Table 31: __setTraceStopBreak return values
For use with
The C-SPY Simulator.
Description
Sets a breakpoint at the specified location. When that breakpoint is triggered, the trace
system is stopped.
Example
See __setTraceStartBreak, page 263.
C-SPY® Debugging Guide
264
for STM8
AFE1_AFE2-1:1
C-SPY macros
See also
Breakpoints, page 107.
__sourcePosition
Syntax
__sourcePosition(linePtr, colPtr)
Parameters
linePtr
Pointer to the variable storing the line number
colPtr
Pointer to the variable storing the column number
Return value
Result
Value
Successful
Filename string
Unsuccessful
Empty ("") string
Table 32: __sourcePosition return values
For use with
All C-SPY drivers.
Description
If the current execution location corresponds to a source location, this macro returns the
filename as a string. It also sets the value of the variables, pointed to by the parameters,
to the line and column numbers of the source location.
__strFind
Syntax
__strFind(macroString, pattern, position)
Parameters
macroString
A macro string.
pattern
The string pattern to search for
position
The position where to start the search. The first position is 0
Return value
The position where the pattern was found or -1 if the string is not found.
For use with
All C-SPY drivers.
265
AFE1_AFE2-1:1
Reference information on C-SPY system macros
Description
This macro searches a given string (macroString) for the occurrence of another string
(pattern).
Example
__strFind("Compiler", "pile", 0)
__strFind("Compiler", "foo", 0)
See also
Macro strings, page 233.
= 3
= -1
__subString
Syntax
__subString(macroString, position, length)
Parameters
macroString
A macro string.
position
The start position of the substring. The first position is 0.
length
The length of the substring
Return value
A substring extracted from the given macro string.
For use with
All C-SPY drivers.
Description
This macro extracts a substring from another string (macroString).
Example
__subString("Compiler", 0, 2)
The resulting macro string contains Co.
__subString("Compiler", 3, 4)
The resulting macro string contains pile.
See also
Macro strings, page 233.
__targetDebuggerVersion
Syntax
__targetDebuggerVersion()
Return value
A string that represents the version number of the C-SPY debugger processor module.
For use with
All C-SPY drivers.
C-SPY® Debugging Guide
266
for STM8
AFE1_AFE2-1:1
C-SPY macros
Description
This macro returns the version number of the C-SPY debugger processor module.
Example
__var toolVer;
toolVer = __targetDebuggerVersion();
__message "The target debugger version is, ", toolVer;
__toLower
Syntax
__toLower(macroString)
Parameters
macroString
A macro string.
Return value
The converted macro string.
For use with
All C-SPY drivers.
Description
This macro returns a copy of the parameter macroString where all the characters have
been converted to lower case.
Example
__toLower("IAR")
The resulting macro string contains iar.
__toLower("Mix42")
The resulting macro string contains mix42.
See also
Macro strings, page 233.
__toString
Syntax
__toString(C_string, maxlength)
Parameters
C_string
Any null-terminated C string.
maxlength
The maximum length of the returned macro string.
Return value
Macro string.
For use with
All C-SPY drivers.
267
AFE1_AFE2-1:1
Reference information on C-SPY system macros
Description
This macro is used for converting C strings (char* or char[]) into macro strings.
Example
Assuming your application contains this definition:
char const * hptr = "Hello World!";
this macro call:
__toString(hptr, 5)
would return the macro string containing Hello.
See also
Macro strings, page 233.
__toUpper
Syntax
__toUpper(macroString)
Parameters
macroString
A macro string.
Return value
The converted string.
For use with
All C-SPY drivers.
Description
This macro returns a copy of the parameter macroString where all the characters have
been converted to upper case.
Example
__toUpper("string")
The resulting macro string contains STRING.
See also
Macro strings, page 233.
__unloadImage
Syntax
__unloadImage(module_id)
Parameters
module_id
An integer which represents a unique module identification, which is retrieved
as a return value from the corresponding __loadImage C-SPY macro.
C-SPY® Debugging Guide
268
for STM8
AFE1_AFE2-1:1
C-SPY macros
Return value
Value
Result
module_id
A unique module identification (the same as the input
parameter).
int 0
The unloading failed.
Table 33: __unloadImage return values
For use with
All C-SPY drivers.
Description
Unloads debug information from an already downloaded image.
See also
Loading multiple images, page 41 and Images, page 295.
__writeFile
Syntax
__writeFile(fileHandle, value)
Parameters
fileHandle
A macro variable used as filehandle by the __openFile macro.
value
An integer.
Return value
int 0
For use with
All C-SPY drivers.
Description
Prints the integer value in hexadecimal format (with a trailing space) to the file file.
Note: The __fmessage statement can do the same thing. The __writeFile macro is
provided for symmetry with __readFile.
__writeFileByte
Syntax
__writeFileByte(fileHandle, value)
Parameters
fileHandle
A macro variable used as filehandle by the __openFile macro.
value
An integer.
269
AFE1_AFE2-1:1
Reference information on C-SPY system macros
Return value
int 0
For use with
All C-SPY drivers.
Description
Writes one byte to the file fileHandle.
__writeMemory8, __writeMemoryByte
Syntax
__writeMemory8(value, address, zone)
__writeMemoryByte(value, address, zone)
Parameters
value
An integer.
address
The memory address (integer).
zone
A string that specifies the memory zone, see C-SPY memory zones, page 134.
Return value
int 0
For use with
All C-SPY drivers.
Description
Writes one byte to a given memory location.
Example
__writeMemory8(0x2F, 0x8020, "");
__writeMemory16
Syntax
__writeMemory16(value, address, zone)
Parameters
value
An integer.
address
The memory address (integer).
zone
A string that specifies the memory zone, see C-SPY memory zones, page 134.
Return value
C-SPY® Debugging Guide
270
for STM8
AFE1_AFE2-1:1
int 0
C-SPY macros
For use with
All C-SPY drivers.
Description
Writes two bytes to a given memory location.
Example
__writeMemory16(0x2FFF, 0x8020, "");
__writeMemory32
Syntax
__writeMemory32(value, address, zone)
Parameters
value
An integer.
address
The memory address (integer).
zone
A string that specifies the memory zone, see C-SPY memory zones, page 134.
Return value
int 0
For use with
All C-SPY drivers.
Description
Writes four bytes to a given memory location.
Example
__writeMemory32(0x5555FFFF, 0x8020, "");
Graphical environment for macros
Reference information about:
●
Macro Registration window, page 272
●
Debugger Macros window, page 274
●
Macro Quicklaunch window, page 276
271
AFE1_AFE2-1:1
Graphical environment for macros
Macro Registration window
The Macro Registration window is available from the View>Macros submenu during a
debug session.
Use this window to list, register, and edit your debugger macro files.
Double-click a macro file to open it in the editor window and edit it.
Requirements
None; this window is always available.
Display area
This area contains these columns:
File
The name of an available macro file. To register the macro file, select the check
box to the left of the filename. The name of a registered macro file appears in
bold style.
Full path
The path to the location of the added macro file.
C-SPY® Debugging Guide
272
for STM8
AFE1_AFE2-1:1
C-SPY macros
Context menu
This context menu is available:
These commands are available:
Add
Opens a file browser where you can locate the macro file that you want to add
to the list. This menu command is also available as a function button at the top
of the window.
Remove
Removes the selected debugger macro file from the list. This menu command is
also available as a function button at the top of the window.
Remove All
Removes all macro files from the list. This menu command is also available as
a function button at the top of the window.
Reload
Registers the selected macro file. Typically, this is useful when you have edited
a macro file. This menu command is also available as a function button at the
top of the window.
Open File
Opens the selected macro file in the editor window.
Open Debugger Macros Window
Opens the Debugger Macros window.
273
AFE1_AFE2-1:1
Graphical environment for macros
Debugger Macros window
The Debugger Macros window is available from the View>Macro submenu during a
debug session.
Use this window to list all registered debugger macro functions, either predefined
system macros or your own. This window is useful when you edit your own macro
functions and want an overview of all available macros that you can use.
Double-clicking a macro defined in a file opens that file in the editor window.
To open a macro in the Macro Quicklaunch window, drag it from the Debugger Macros
window and drop it in the Macro Quicklaunch window.
Select a macro and press F1 to get online help information for that macro.
Requirements
None; this window is always available.
Display area
This area contains these columns:
Name
The name of the debugger macro.
Parameters
The parameters of the debugger macro.
File
For macros defined in a file, the name of the file is displayed. For predefined
system macros, -System Macro- is displayed.
C-SPY® Debugging Guide
274
for STM8
AFE1_AFE2-1:1
C-SPY macros
Context menu
This context menu is available:
These commands are available:
Open File
Opens the selected debugger macro file in the editor window.
Add to Quicklaunch Window
Adds the selected macro to the Macro Quicklaunch window.
User Macros
Lists only the debugger macros that you have defined yourself.
System Macros
Lists only the predefined system macros.
All Macros
Lists all debugger macros, both predefined system macros and your own.
Open Macro Registration Window
Opens the Macro Registration window.
275
AFE1_AFE2-1:1
Graphical environment for macros
Macro Quicklaunch window
The Macro Quicklaunch window is available from the View menu.
Use this window to evaluate expressions, typically C-SPY macros.
For some devices, there are predefined C-SPY macros available with device support,
typically provided by the chip manufacturer. These macros are useful for performing
certain device-specific tasks. The macros are available in the Macro Quicklaunch
window and are easily identified by their green icon,
The Macro Quicklaunch window is similar to the Quick Watch window, but is primarily
designed for evaluating C-SPY macros. The window gives you precise control over
when to evaluate an expression.
To add an expression:
1 Choose one of these alternatives:
●
Drag the expression to the window
●
In the Expression column, type the expression you want to examine.
If the expression you add and want to evaluate is a C-SPY macro, the macro must first
be registered, see Using C-SPY macros, page 227.
To evaluate an expression:
1 Double-click the Recalculate icon to calculate the value of that expression.
Requirements
None; this window is always available.
C-SPY® Debugging Guide
276
for STM8
AFE1_AFE2-1:1
C-SPY macros
Display area
This area contains these columns:
Recalculate icon
To evaluate the expression, double-click the icon. The latest evaluated
expression appears in bold style.
Expression
One or several expressions that you want to evaluate. Click <click to add>
to add an expression. If the return value has changed since last time, the value
will be displayed in red.
Result
Shows the return value from the expression evaluation.
Context menu
This context menu is available:
These commands are available:
Evaluate Now
Evaluates the selected expression.
Remove
Removes the selected expression.
Remove All
Removes all selected expressions.
277
AFE1_AFE2-1:1
Graphical environment for macros
C-SPY® Debugging Guide
278
for STM8
AFE1_AFE2-1:1
The C-SPY command line utility—cspybat
The C-SPY command line
utility—cspybat
●
Using C-SPY in batch mode
●
Summary of C-SPY command line options
●
Reference information on C-SPY command line options.
Using C-SPY in batch mode
These topics are covered:
●
Starting cspybat
●
Output
●
Invocation syntax
You can execute C-SPY in batch mode if you use the command line utility cspybat,
installed in the directory common\bin.
STARTING CSPYBAT
To start cspybat you must first create a batch file. An easy way to do that is to use one
of the batch files that C-SPY automatically create when you start C-SPY in the IDE.
C-SPY generates a batch file projectname.buildconfiguration.cspy.bat every
time C-SPY is initialized. You can find the files in the directory
$PROJ_DIR$\settings. The batch file contains the same settings as the IDE, and you
can use it from the command line to start cspybat. The files give hints about additional
options that you can use.
OUTPUT
When you run cspybat, these types of output can be produced:
●
Terminal output from cspybat itself
All such terminal output is directed to stderr. Note that if you run cspybat from
the command line without any arguments, the cspybat version number and all
available options including brief descriptions are directed to stdout and displayed
on your screen.
279
AFE1_AFE2-1:1
Summary of C-SPY command line options
●
Terminal output from the application you are debugging
All such terminal output is directed to stdout, provided that you have used the
--plugin option. See --plugin, page 287.
●
Error return codes
cspybat returns status information to the host operating system that can be tested in
a batch file. For successful, the value int 0 is returned, and for unsuccessful the value
int 1 is returned.
INVOCATION SYNTAX
The invocation syntax for cspybat is:
cspybat processor_DLL driver_DLL {debug_file|--debug_file
filename} [cspybat_options] --backend driver_options
Note: In those cases where a filename is required—including the DLL files—you are
recommended to give a full path to the filename.
Parameters
The parameters are:
Parameter
Description
processor_DLL
The processor-specific DLL file; available in stm8\bin.
driver_DLL
The C-SPY driver DLL file; available in stm8\bin.
debug_file
The object file that you want to debug (filename extension dnn).
cspybat_options
The command line options that you want to pass to cspybat. Note
that these options are optional. For information about each option,
see Reference information on C-SPY command line options, page 282.
--backend
Marks the beginning of the parameters to the C-SPY driver; all
options that follow will be sent to the driver. Note that this option is
mandatory.
driver_options
The command line options that you want to pass to the C-SPY driver.
Note that some of these options are mandatory and some are
optional. For information about each option, see Reference information
on C-SPY command line options, page 282.
Table 34: cspybat parameters
Summary of C-SPY command line options
Reference information about:
●
C-SPY® Debugging Guide
280
for STM8
AFE1_AFE2-1:1
General cspybat options
The C-SPY command line utility—cspybat
●
Options available for all C-SPY drivers
●
Options available for the simulator driver
●
Options available for the C-SPY hardware drivers
●
Options available for the C-SPY STice driver
GENERAL CSPYBAT OPTIONS
--backend
Marks the beginning of the parameters to be sent to the
C-SPY driver (mandatory).
--code_coverage_file
Enables the generation of code coverage information and
places it in a specified file.
--cycles
Specifies the maximum number of cycles to run.
--download_only
Downloads a code image without starting a debug session
afterwards.
--leave_running
Starts the execution on the target and then exits but leaves
the target running.
--macro
Specifies a macro file to be used.
--plugin
Specifies a plugin file to be used.
--silent
Omits the sign-on message.
--timeout
Limits the maximum allowed execution time.
OPTIONS AVAILABLE FOR ALL C-SPY DRIVERS
-d
Specifies the C-SPY driver to be used.
-p
Specifies the device description file to be used.
OPTIONS AVAILABLE FOR THE SIMULATOR DRIVER
--disable_interrupts
Disables the interrupt simulation.
--mapu
Activates memory access checking.
OPTIONS AVAILABLE FOR THE C-SPY HARDWARE DRIVERS
--erase_memory
Erases the memory before downloading the code.
281
AFE1_AFE2-1:1
Reference information on C-SPY command line options
--log_file
Creates a log file.
--mcuname
Specifies the name of the MCU used for debugging.
--suppress_download
Suppresses download of the executable image.
--verify_download
Verifies the executable image.
OPTIONS AVAILABLE FOR THE C-SPY STICE DRIVER
--swim
Enables the SWIM interface.
Reference information on C-SPY command line options
This section gives detailed reference information about each cspybat option and each
option available to the C-SPY drivers.
--backend
Syntax
--backend {driver options}
Parameters
driver options
Any option available to the C-SPY driver you are using.
For use with
cspybat (mandatory).
Description
Use this option to send options to the C-SPY driver. All options that follow --backend
will be passed to the C-SPY driver, and will not be processed by cspybat itself.
This option is not available in the IDE.
--code_coverage_file
Syntax
--code_coverage_file file
Note that this option must be placed before the --backend option on the command line.
Parameters
file
The name of the destination file for the code coverage information.
For use with
C-SPY® Debugging Guide
282
for STM8
AFE1_AFE2-1:1
cspybat
The C-SPY command line utility—cspybat
Description
Use this option to enable the generation of code coverage information. The code
coverage information will be generated after the execution has completed and you can
find it in the specified file.
Note that this option requires that the C-SPY driver you are using supports code
coverage. If you try to use this option with a C-SPY driver that does not support code
coverage, an error message will be directed to stderr.
See also
Code coverage, page 199.
To set this option, choose View>Code Coverage, right-click and choose Save As when
the C-SPY debugger is running.
--cycles
Syntax
--cycles cycles
Note that this option must be placed before the --backend option on the command line.
Parameters
cycles
The number of cycles to run.
For use with
cspybat
Description
Use this option to specify the maximum number of cycles to run. If the target program
executes longer than the number of cycles specified, the target program will be aborted.
Using this option requires that the C-SPY driver you are using supports a cycle counter,
and that it can be sampled while executing.
This option is not available in the IDE.
-d
Syntax
-d {sim|stlink|stice}
Parameters
For use with
sim
Specifies the C-SPY simulator driver.
stlink
Specifies the C-SPY ST-LINK driver.
stice
Specifies the C-SPY STice driver.
All C-SPY drivers.
283
AFE1_AFE2-1:1
Reference information on C-SPY command line options
Description
Use this option to specify the driver to be used.
Project>Options>Debugger>Driver
--disable_interrupts
Syntax
--disable_interrupts
For use with
The C-SPY Simulator driver.
Description
Use this option to disable the interrupt simulation.
To set this option, choose Simulator>Interrupt Setup and deselect the Enable
interrupt simulation option.
--download_only
Syntax
--download_only
Note that this option must be placed before the --backend option on the command line.
For use with
cspybat
Description
Use this option to download the code image without starting a debug session afterwards.
To set related option, choose:
Project>Options>Debugger>Setup and deselect Run to.
--erase_memory
Syntax
--erase_memory
For use with
Any C-SPY hardware debugger driver.
Description
Erases the memory (FLASH, EEPROM, and option bytes) before downloading the
code. This is done by first setting the Read-Out Protection option byte and then clearing
it (or the other way around if ROP is already set). During the clearing phase, all memory
areas are erased.
This option is only available for supported devices and when using STice in SWIM
mode or ST-LINK.
C-SPY® Debugging Guide
284
for STM8
AFE1_AFE2-1:1
The C-SPY command line utility—cspybat
Project>Options>Debugger>Driver>Setup>Erase
--leave_running
Syntax
--leave_running
Note that this option must be placed before the --backend option on the command line.
For use with
cspybat
Description
Makes cspybat start the execution on the target and then exits but leaves the target
running.
This option is not available in the IDE.
--log_file
Syntax
--log_file=filename
Parameters
filename
The name of the log file.
For use with
Any C-SPY hardware debugger driver.
Description
Use this option to log the communication between C-SPY and the target system to a file.
To interpret the result, detailed knowledge of the communication protocol is required.
Project>Options>Debugger>Driver>Communication Log
--macro
Syntax
--macro filename
Note that this option must be placed before the --backend option on the command line.
Parameters
filename
The C-SPY macro file to be used (filename extension mac).
For use with
cspybat
285
AFE1_AFE2-1:1
Reference information on C-SPY command line options
Description
Use this option to specify a C-SPY macro file to be loaded before executing the target
application. This option can be used more than once on the command line.
See also
Briefly about using C-SPY macros, page 226.
Project>Options>Debugger>Setup>Setup macros>Use macro file
--mapu
Syntax
--mapu
For use with
The C-SPY simulator driver.
Description
Specify this option to use the segment information in the debug file for memory access
checking. During the execution, the simulator will then check for accesses to
unspecified memory ranges. If any such access is found, the C function call stack and a
message will be printed on stderr and the execution will stop.
See also
Memory access checking, page 136.
To set related options, choose:
Simulator>Memory Access Setup
--mcuname
Syntax
--mcuname name
Parameters
name
The name of the MCU used for debugging, for example STM8S208MB.
For use with
Any C-SPY hardware debugger driver.
Description
Use this option to specify the name of the MCU used for debugging. This option is
mandatory, to be able to communicate with the hardware.
Project>Options>General Options>Target>Device
C-SPY® Debugging Guide
286
for STM8
AFE1_AFE2-1:1
The C-SPY command line utility—cspybat
-p
Syntax
-p filename
Parameters
filename
The device description file to be used.
For use with
All C-SPY drivers.
Description
Use this option to specify the device description file to be used.
See also
Selecting a device description file, page 38.
Project>Options>Debugger>Setup>Device description file
--plugin
Syntax
--plugin filename
Note that this option must be placed before the --backend option on the command line.
Parameters
filename
The plugin file to be used (filename extension dll).
For use with
cspybat
Description
Certain C/C++ standard library functions, for example printf, can be supported by
C-SPY—for example, the C-SPY Terminal I/O window—instead of by real hardware
devices. To enable such support in cspybat, a dedicated plugin module called
stm8bat.dll located in the stm8\bin directory must be used.
Use this option to include this plugin during the debug session. This option can be used
more than once on the command line.
Note: You can use this option to include also other plugin modules, but in that case the
module must be able to work with cspybat specifically. This means that the C-SPY
plugin modules located in the common\plugin directory cannot normally be used with
cspybat.
Project>Options>Debugger>Plugins
287
AFE1_AFE2-1:1
Reference information on C-SPY command line options
--silent
Syntax
--silent
Note that this option must be placed before the --backend option on the command line.
For use with
cspybat
Description
Use this option to omit the sign-on message.
This option is not available in the IDE.
--suppress_download
Syntax
--suppress_download
For use with
Any C-SPY hardware debugger driver.
Description
Use this option to suppress the downloading of the executable image to a non-volatile
type of target memory. The image corresponding to the debugged application must
already exist in the target.
If this option is combined with the option --verify_download, the debugger will read
back the executable image from memory and verify that it is identical to the debugged
application.
Project>Options>Debugger>Setup>Download>Suppress
--swim
Syntax
--swim
For use with
The C-SPY STice driver.
Description
Use this opton to enable the SWIM interface.
Project>Options>Debugger>STice>Setup>Use SWIM interface
C-SPY® Debugging Guide
288
for STM8
AFE1_AFE2-1:1
The C-SPY command line utility—cspybat
--timeout
Syntax
--timeout milliseconds
Note that this option must be placed before the --backend option on the command line.
Parameters
milliseconds
The number of milliseconds before the execution stops.
For use with
cspybat
Description
Use this option to limit the maximum allowed execution time.
This option is not available in the IDE.
--verify_download
Syntax
--verify_download
For use with
Any C-SPY hardware debugger driver.
Description
Use this option to verify that the downloaded code image can be read back from target
memory with the correct contents.
Project>Options>Debugger>C-SPY driver>Verify download
289
AFE1_AFE2-1:1
Reference information on C-SPY command line options
C-SPY® Debugging Guide
290
for STM8
AFE1_AFE2-1:1
Part 4. Additional
reference information
This part of the C-SPY® Debugging Guide for STM8 includes these chapters:
●
Debugger options
●
Additional information on C-SPY drivers
291
292
Debugger options
Debugger options
●
Setting debugger options
●
Reference information on debugger options
●
Reference information on C-SPY hardware debugger driver options
Setting debugger options
Before you start the C-SPY debugger you might need to set some options—both C-SPY
generic options and options required for the target system (C-SPY driver-specific
options). This section gives detailed information about the options in the Debugger
category.
To set debugger options in the IDE:
1 Choose Project>Options to display the Options dialog box.
2 Select Debugger in the Category list.
For more information about the generic options, see Reference information on debugger
options, page 293.
3 On the Setup page, make sure to select the appropriate C-SPY driver from the Driver
drop-down list.
4 To set the driver-specific options, select the appropriate driver from the Category list.
Depending on which C-SPY driver you are using, different options are available.
5 To restore all settings to the default factory settings, click the Factory Settings button.
6 When you have set all the required options, click OK in the Options dialog box.
Reference information on debugger options
Reference information about:
●
Setup
●
Images
●
Extra Options
●
Plugins
293
AFE1_AFE2-1:1
Reference information on debugger options
Setup
The Setup options select the C-SPY driver, the setup macro file, and device description
file to use, and specify which default source code location to run to.
Driver
Selects the C-SPY driver for the target system you have.
Run to
Specifies the location C-SPY runs to when the debugger starts after a reset. By default,
C-SPY runs to the main function.
To override the default location, specify the name of a different location you want
C-SPY to run to. You can specify assembler labels or whatever can be evaluated as such,
for example function names.
If the option is deselected, the program counter will contain the regular hardware reset
address at each reset.
Setup macros
Registers the contents of a setup macro file in the C-SPY startup sequence. Select Use
macro file and specify the path and name of the setup file, for example
SetupSimple.mac. If no extension is specified, the extension mac is assumed. A
browse button is available for your convenience.
Device description file
A default device description file is selected automatically based on your project settings.
To override the default file, select Override default and specify an alternative file. A
browse button is available for your convenience.
C-SPY® Debugging Guide
294
for STM8
AFE1_AFE2-1:1
Debugger options
For information about the device description file, see Modifying a device description
file, page 42.
Device description files for each STM8 device are provided in the directory
stm8\config and have the filename extension ddf.
Images
The Images options control the use of additional debug files to be downloaded.
Note: Flash loading will not be performed; using the Images options you can only
download images to RAM.
Download extra Images
Controls the use of additional debug files to be downloaded:
Path
Specify the debug file to be downloaded. A browse button is available for your
convenience.
Offset
Specify an integer that determines the destination address for the downloaded
debug file.
Debug info only
Makes the debugger download only debug information, and not the complete
debug file.
If you want to download more than three images, use the related C-SPY macro, see
__loadImage, page 248.
For more information, see Loading multiple images, page 41.
295
AFE1_AFE2-1:1
Reference information on debugger options
Plugins
The Plugins options select the C-SPY plugin modules to be loaded and made available
during debug sessions.
Select plugins to load
Selects the plugin modules to be loaded and made available during debug sessions. The
list contains the plugin modules delivered with the product installation.
Description
Describes the plugin module.
Location
Informs about the location of the plugin module.
Generic plugin modules are stored in the common\plugins directory. Target-specific
plugin modules are stored in the stm8\plugins directory.
Originator
Informs about the originator of the plugin module, which can be modules provided by
IAR Systems or by third-party vendors.
Version
Informs about the version number.
C-SPY® Debugging Guide
296
for STM8
AFE1_AFE2-1:1
Debugger options
Extra Options
The Extra Options page provides you with a command line interface to C-SPY.
Use command line options
Specify command line arguments that are not supported by the IDE to be passed to
C-SPY.
Note that it is possible to use the /args option to pass command line arguments to the
debugged application.
Syntax: /args arg0 arg1 ...
Multiple lines with /args are allowed, for example:
/args --logfile log.txt
/args --verbose
If you use /args, these variables must be defined in your application:
/* __argc, the number of arguments in __argv. */
__no_init int __argc;
/* __argv, an array of pointers to strings that holds the
arguments; must be large enough to fit the number of
parameters.*/
__no_init const char * __argv[MAX_ARGS];
/* __argvbuf, a storage area for __argv; must be large enough to
hold all command line parameters. */
__no_init __root char __argvbuf[MAX_ARG_SIZE];
297
AFE1_AFE2-1:1
Reference information on C-SPY hardware debugger driver options
Reference information on C-SPY hardware debugger driver options
This section covers these topics:
●
Setup options for STice and ST-LINK, page 298
Setup options for STice and ST-LINK
The Setup options control the C-SPY STice driver or the C-SPY ST-LINK driver,
respectively.
Download
By default, C-SPY downloads the application to RAM or flash when a debug session
starts. The Download options let you modify the behavior of the download.
Suppress
Disables the downloading of code, while preserving the present content of the
flash. This command is useful if you want to debug an application that already
resides in target memory.
If this option is combined with the Verify option, the debugger will read back
the code image from non-volatile memory and verify that it is identical to the
debugged application.
Erase
Erases the memory (FLASH, EEPROM, and option bytes) before downloading
the code. This is done by first setting the Read-Out Protection option byte and
then clearing it (or the other way around if ROP is already set). During the
clearing phase, all memory areas are erased.
The option is only available for supported devices and when using STice in
SWIM mode or ST-LINK.
C-SPY® Debugging Guide
298
for STM8
AFE1_AFE2-1:1
Debugger options
Verify
Verifies that the downloaded code image can be read back from target memory
with the correct contents.
Use option bytes configuration file
Writes the option bytes settings defined in an option bytes configuration file
(obc) to the device before download. The file is created using the Option bytes
window, see Option Bytes window, page 52.
Communication options
Use SWIM interface
Enables the SWIM interface. Using the SWIM interface makes the STice
emulator behave as ST-LINK.
This option is only available for the C-SPY STice driver.
Communication log
Use communication log file
Logs the communication between C-SPY and the target system to a file. To
interpret the result, detailed knowledge of the interface is required.
299
AFE1_AFE2-1:1
Reference information on C-SPY hardware debugger driver options
C-SPY® Debugging Guide
300
for STM8
AFE1_AFE2-1:1
Additional information on C-SPY drivers
Additional information on
C-SPY drivers
This chapter describes the additional menus and features provided by the
C-SPY® drivers. You will also find some useful hints about resolving problems.
Reference information on C-SPY driver menus
Reference information about:
●
C-SPY driver, page 301
●
Simulator menu, page 302
●
The ST-LINK menu, page 304
●
The STice menu, page 305
C-SPY driver
Before you start the C-SPY debugger, you must first specify a C-SPY driver in the
Options dialog box, using the option Debugger>Setup>Driver.
When you start a debug session, a menu specific to that C-SPY driver will appear on the
menu bar, with commands specific to the driver.
When we in this guide write “choose C-SPY driver>” followed by a menu command,
C-SPY driver refers to the menu. If the feature is supported by the driver, the command
will be on the menu.
301
AFE1_AFE2-1:1
Reference information on C-SPY driver menus
Simulator menu
When you use the simulator driver, the Simulator menu is added to the menu bar.
Menu commands
These commands are available on the menu:
Memory Access Setup
Displays a dialog box to simulate memory access checking by specifying
memory areas with different access types, see Memory Access Setup dialog box,
page 158.
Trace
Opens a window which displays the collected trace data, see Trace window,
page 170.
Function Trace
Opens a window which displays the trace data for function calls and function
returns, see Function Trace window, page 174.
Function Profiler
Opens a window which shows timing information for the functions, see
Function Profiler window, page 194.
Data Log
Opens a window which logs accesses to up to four different memory locations
or areas, see Data Log window, page 95.
C-SPY® Debugging Guide
302
for STM8
AFE1_AFE2-1:1
Additional information on C-SPY drivers
Data Log Summary
Opens a window which displays a summary of data accesses to specific memory
location or areas, see Data Log Summary window, page 97.
Interrupt Log
Opens a window which displays the status of all defined interrupts, see Interrupt
Log window, page 219.
Interrupt Log Summary
Opens a window which displays a summary of the status of all defined
interrupts, see Interrupt Log Summary window, page 222.
Timeline
Opens a window which gives a graphical view of various kinds of information
on a timeline, see Timeline window, page 174.
Simulated Frequency
Opens the Simulated Frequency dialog box where you can specify the
simulator frequency used when the simulator displays time information, for
example in the log windows. Note that this does not affect the speed of the
simulator.
Interrupt Setup
Displays a dialog box where you can configure C-SPY interrupt simulation, see
Interrupt Setup dialog box, page 213.
Forced Interrupts
Opens a window from where you can instantly trigger an interrupt, see Forced
Interrupt window, page 216.
Interrupt Status
Opens a window from where you can instantly trigger an interrupt, see Interrupt
Status window, page 217.
Breakpoint Usage
Displays a window which lists all active breakpoints, see Breakpoint Usage
window, page 119.
303
AFE1_AFE2-1:1
Reference information on C-SPY driver menus
The ST-LINK menu
When you are using the C-SPY driver for ST-LINK, the ST-LINK menu is added to the
menu bar.
Menu commands
These menu commands are available on the menu:
Disable Interrupts When Stepping
Temporarily disables interrupts during hardware single steps. Enabling this
function might be useful in cases where it is impossible to move away from an
instruction with a breakpoint on it, due to pending interrupts.
Option bytes
Opens a window that displays the current state of the option bytes set at the
target STM8 device, see Option Bytes window, page 52.
Data Sample Setup
Opens a window where you can specify variables to sample data for, see Setup
Data Sample window, page 99.
Data Sample
Opens a window where you can view the result of the data sampling, see Data
Sample window, page 100.
Sampled Graphs
Opens a window which gives a graphical view of various kinds of sampled
information, see Sampled Graphs window, page 102.
Breakpoint Usage
Displays a window which lists all active breakpoints, see Breakpoint Usage
window, page 119.
C-SPY® Debugging Guide
304
for STM8
AFE1_AFE2-1:1
Additional information on C-SPY drivers
The STice menu
When you are using the C-SPY driver for STice, the STice menu is added to the menu
bar.
Menu commands
These menu commands are available on the menu:
Disable Interrupts When Stepping
Temporarily disables interrupts during hardware single steps. Enabling this
function might be useful in cases where it is impossible to move away from an
instruction with a breakpoint on it, due to pending interrupts.
Option bytes
Opens a window that displays the current state of the option bytes set at the
target STM8 device, see Option Bytes window, page 52.
Trace Settings
Displays the Trace Settings dialog box, see Trace Settings dialog box, page
168.
Trace
Opens the Trace window, see Trace window, page 170.
Function Trace
Opens the Function Trace window, see Function Trace window, page 174.
Function Profiler
Opens the Function Profiler window, see Function Profiler window, page 194.
305
AFE1_AFE2-1:1
Reference information on the C-SPY simulator
Timeline
Opens a window which gives a graphical view of various kinds of information
on a timeline, see Timeline window, page 174.
Data Sample Setup
Opens a window where you can specify variables to sample data for, see Setup
Data Sample window, page 99.
Data Sample
Opens a window where you can view the result of the data sampling, see Data
Sample window, page 100.
Sampled Graphs
Opens a window which gives a graphical view of various kinds of sampled
information, see Sampled Graphs window, page 102.
Breakpoint Usage
Displays a window which lists all active breakpoints, see Breakpoint Usage
window, page 119.
Reference information on the C-SPY simulator
This section gives additional reference information the C-SPY simulator, reference
information not provided elsewhere in this documentation.
Reference information about:
●
Simulated Frequency dialog box, page 306
Simulated Frequency dialog box
The Simulated Frequency dialog box is available from the C-SPY driver menu.
Use this dialog box to specify the simulator frequency used when the simulator displays
time information.
C-SPY® Debugging Guide
306
for STM8
AFE1_AFE2-1:1
Additional information on C-SPY drivers
Requirements
The C-SPY simulator.
Frequency
Specify the frequency in Hz.
Resolving problems
These topics are covered:
●
Write failure during load
●
No contact with the target hardware
●
Slow stepping speed
Debugging using the C-SPY hardware debugger systems requires interaction between
many systems, independent from each other. For this reason, setting up this debug
system can be a complex task. If something goes wrong, it might be difficult to locate
the cause of the problem.
This section includes suggestions for resolving the most common problems that can
occur when debugging with the C-SPY hardware debugger systems.
For problems concerning the operation of the evaluation board, refer to the
documentation supplied with it, or contact your hardware distributor.
WRITE FAILURE DURING LOAD
There are several possible reasons for write failure during load. The most common is
that your application has been incorrectly linked:
●
Check the contents of your linker configuration file and make sure that your
application has not been linked to the wrong address
●
Check that you are using the correct linker configuration file.
In the IDE, the linker configuration file is automatically selected based on your choice
of device.
To choose a device:
1 Choose Project>Options.
2 Select the General Options category.
3 Click the Target tab.
4 Choose the appropriate device from the Device drop-down list.
307
AFE1_AFE2-1:1
Resolving problems
To override the default linker configuration file:
1 Choose Project>Options.
2 Select the Linker category.
3 Click the Config tab.
4 Choose the appropriate linker configuration file in the Linker configuration file area.
NO CONTACT WITH THE TARGET HARDWARE
There are several possible reasons for C-SPY to fail to establish contact with the target
hardware. Do this:
●
Check the communication devices on your host computer
●
Verify that the cable is properly plugged in and not damaged or of the wrong type
●
Make sure that the evaluation board is supplied with sufficient power
●
Check that the correct options for communication have been specified in the IAR
Embedded Workbench IDE.
Examine the linker configuration file to make sure that the application has not been
linked to the wrong address.
SLOW STEPPING SPEED
If you find that the stepping speed is slow, these troubleshooting tips might speed up
stepping:
●
If you are using a hardware debugger system, keep track of how many hardware
breakpoints that are used and make sure some of them are left for stepping.
Stepping in C-SPY is normally performed using breakpoints. When C-SPY performs
a step command, a breakpoint is set on the next statement and the application
executes until it reaches this breakpoint. If you are using a hardware debugger
system, the number of hardware breakpoints—typically used for setting a stepping
breakpoint in code that is located in flash/ROM memory—is limited. If you, for
example, step into a C switch statement, breakpoints are set on each branch; this
might consume several hardware breakpoints. If the number of available hardware
breakpoints is exceeded, C-SPY switches into single stepping on assembly level,
which can be very slow.
For more information, see Breakpoints in the C-SPY hardware debugger drivers,
page 110 and Breakpoint consumers, page 111.
●
C-SPY® Debugging Guide
308
for STM8
AFE1_AFE2-1:1
Disable trace data collection, using the Enable/Disable button in both the Trace and
the Function Profiling windows. Trace data collection might slow down stepping
because the collected trace data is processed after each step. Note that it is not
sufficient to just close the corresponding windows to disable trace data collection.
Additional information on C-SPY drivers
●
Choose to view only a limited selection of SFR registers. You can choose between
two alternatives. Either type #SFR_name (where SFR_name reflects the name of the
SFR you want to monitor) in the Watch window, or create your own filter for
displaying a limited group of SFRs in the Register window. Displaying many SFR
registers might slow down stepping because all registers must be read from the
hardware after each step. See Defining application-specific register groups, page
137.
●
Close the Memory and Symbolic Memory windows if they are open, because the
visible memory must be read after each step and that might slow down stepping.
●
Close any window that displays expressions such as Watch, Live Watch, Locals,
Statics if it is open, because all these windows read memory after each step and that
might slow down stepping.
●
Close the Stack window if it is open. Choose Tools>Options>Stack and disable the
Enable graphical stack display and stack usage tracking option if it is enabled.
●
If possible, increase the communication speed between C-SPY and the target
board/emulator.
309
AFE1_AFE2-1:1
Resolving problems
C-SPY® Debugging Guide
310
for STM8
AFE1_AFE2-1:1
Index
Index
A
Abort (Report Assert option) . . . . . . . . . . . . . . . . . . . . . . . 72
absolute location, specifying for a breakpoint . . . . . . . . . . 130
Access type (Edit Memory Access option) . . . . . . . . . . . . 161
Access (Edit SFR option) . . . . . . . . . . . . . . . . . . . . . . . . . 158
Add to Watch Window (Symbolic Memory window context
menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
Add (SFR Setup window context menu) . . . . . . . . . . . . . . 156
Address Range (Find in Trace option) . . . . . . . . . . . . . . . 186
Address (Edit SFR option) . . . . . . . . . . . . . . . . . . . . . . . . 157
advanced breakpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
break on data access within or outside an address
range . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
break on data value at a given address . . . . . . . . . . . . . 120
break on opcode fetch or data access at given
addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
break on opcode fetch within or outside an
address range . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
break on stack write or data access at a given address . 122
break on stack write or opcode fetch at a given address 122
break on two sequential opcode fetches . . . . . . . . . . . . 121
data access at one of two addresses . . . . . . . . . . . . . . . 121
Ambiguous symbol (Resolve Symbol Ambiguity option) . . 95
application, built outside the IDE . . . . . . . . . . . . . . . . . . . . 40
assembler labels, viewing . . . . . . . . . . . . . . . . . . . . . . . . . . 78
assembler source code, fine-tuning . . . . . . . . . . . . . . . . . . 189
assembler symbols, using in C-SPY expressions . . . . . . . . 75
assembler variables, viewing. . . . . . . . . . . . . . . . . . . . . . . . 78
assumptions, programming experience . . . . . . . . . . . . . . . . 19
Auto Scroll (Sampled Graphs window context menu) . . . 103
Auto Scroll (Timeline window context menu) . . . . . . . . . 179
Auto window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Autostep settings dialog box . . . . . . . . . . . . . . . . . . . . . . . . 72
Autostep (Debug menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
B
--backend (C-SPY command line option) . . . . . . . . . . . . . 282
backtrace information
generated by compiler . . . . . . . . . . . . . . . . . . . . . . . . . . 60
viewing in Call Stack window . . . . . . . . . . . . . . . . . . . . 66
batch mode, using C-SPY in . . . . . . . . . . . . . . . . . . . . . . . 279
Big Endian (Memory window context menu) . . . . . . . . . . 142
blocks, in C-SPY macros . . . . . . . . . . . . . . . . . . . . . . . . . 235
bold style, in this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Break on Throw (Debug menu). . . . . . . . . . . . . . . . . . . . . . 47
Break on Uncaught Exception (Debug menu) . . . . . . . . . . . 47
Break (Debug menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
breakpoint condition, example . . . . . . . . . . . . . . . . . 115–116
Breakpoint Usage window . . . . . . . . . . . . . . . . . . . . . . . . 119
Breakpoint Usage (Simulator menu) . . . . . . . . . . . . . . . . . 303
Breakpoint usage (STice menu) . . . . . . . . . . . . . . . . . . . . 306
Breakpoint usage (ST-LINK menu) . . . . . . . . . . . . . . . . . 304
breakpoints
code, example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
connecting a C-SPY macro . . . . . . . . . . . . . . . . . . . . . 230
consumers of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 111
data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
data log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
description of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
disabling used by Stack window . . . . . . . . . . . . . . . . . 111
icons for in the IDE . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
in Memory window . . . . . . . . . . . . . . . . . . . . . . . . . . . 114
listing all . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
reasons for using . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107
setting
in memory window . . . . . . . . . . . . . . . . . . . . . . . . . 114
using system macros . . . . . . . . . . . . . . . . . . . . . . . . 114
using the dialog box . . . . . . . . . . . . . . . . . . . . . . . . 112
single-stepping if not available. . . . . . . . . . . . . . . . . . . . 38
toggling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
types of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
useful tips. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
Breakpoints dialog box
Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
Data Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128
311
UCSARM-4:3
Immediate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
Trace Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182
Trace Stop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
Breakpoints window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Browse (Trace toolbar) . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
byte order, setting in Memory window . . . . . . . . . . . . . . . 141
C
C function information, in C-SPY. . . . . . . . . . . . . . . . . . . . 60
C symbols, using in C-SPY expressions . . . . . . . . . . . . . . . 75
C variables, using in C-SPY expressions . . . . . . . . . . . . . . 74
call chain, displaying in C-SPY . . . . . . . . . . . . . . . . . . . . . 60
Call stack information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Call Stack window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
for backtrace information . . . . . . . . . . . . . . . . . . . . . . . . 60
Call Stack (Timeline window context menu) . . . . . . . . . . 180
__cancelAllInterrupts (C-SPY system macro) . . . . . . . . . 241
__cancelInterrupt (C-SPY system macro) . . . . . . . . . . . . . 241
Clear All (Debug Log window context menu) . . . . . . . . . . 71
Clear trace data (Trace toolbar) . . . . . . . . . . . . . . . . . . . . . 170
Clear (Interrupt Log window context menu) . . . . . . . 221, 223
__clearBreak (C-SPY system macro) . . . . . . . . . . . . . . . . 242
__closeFile (C-SPY system macro) . . . . . . . . . . . . . . . . . 242
code breakpoints
overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108
toggling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Code Coverage window . . . . . . . . . . . . . . . . . . . . . . . . . . 200
Code Coverage (Disassembly window context menu) . . . . 65
--code_coverage_file (C-SPY command line option) . . . . 282
code, covering execution of . . . . . . . . . . . . . . . . . . . . . . . 200
command line options . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282
typographic convention . . . . . . . . . . . . . . . . . . . . . . . . . 22
command prompt icon, in this guide . . . . . . . . . . . . . . . . . . 23
Communication log (ST-LINK option) . . . . . . . . . . . . . . . 299
computer style, typographic convention . . . . . . . . . . . . . . . 22
conditional statements, in C-SPY macros . . . . . . . . . . . . . 234
context menu, in windows. . . . . . . . . . . . . . . . . . . . . . . . . . 78
C-SPY® Debugging Guide
312
for ARM
UCSARM-4:3
conventions, used in this guide . . . . . . . . . . . . . . . . . . . . . . 22
Copy Window Contents (Disassembly
window context menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Copy (Debug Log window context menu) . . . . . . . . . . . . . 70
copyright notice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
cspybat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
current position, in C-SPY Disassembly window . . . . . . . . 64
cursor, in C-SPY Disassembly window. . . . . . . . . . . . . . . . 64
--cycles (C-SPY command line option) . . . . . . . . . . . . . . 283
C-SPY
batch mode, using in . . . . . . . . . . . . . . . . . . . . . . . . . . 279
debugger systems, overview of . . . . . . . . . . . . . . . . . . . 31
environment overview . . . . . . . . . . . . . . . . . . . . . . . . . . 27
plugin modules, loading . . . . . . . . . . . . . . . . . . . . . . . . . 39
setting up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37–38
starting the debugger . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
C-SPY drivers
differences between drivers . . . . . . . . . . . . . . . . . . . . . . 33
overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
specifying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
types of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
C-SPY expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
evaluating, using Macro Quicklaunch window. . . . . . . 276
evaluating, using Quick Watch window . . . . . . . . . . . . . 91
in C-SPY macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Tooltip watch, using . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Watch window, using . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
C-SPY macros
blocks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235
conditional statements . . . . . . . . . . . . . . . . . . . . . . . . . 234
C-SPY expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
checking status of register . . . . . . . . . . . . . . . . . . . . 229
creating a log macro . . . . . . . . . . . . . . . . . . . . . . . . 230
executing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
connecting to a breakpoint . . . . . . . . . . . . . . . . . . . 230
using Quick Watch . . . . . . . . . . . . . . . . . . . . . . . . . 229
using setup macro and setup file . . . . . . . . . . . . . . . 229
functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76, 232
loop statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Index
macro statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
setup macro file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
executing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 229
setup macro functions . . . . . . . . . . . . . . . . . . . . . . . . . 226
summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
system macros, summary of . . . . . . . . . . . . . . . . . . . . . 239
using . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76, 232
C-SPY options
Extra Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
Plugins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
C-SPYLink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
C++ terminology. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
D
-d (C-SPY command line option) . . . . . . . . . . . . . . . . . . . 283
data breakpoints, overview . . . . . . . . . . . . . . . . . . . . . . . . 109
Data Coverage (Memory window context menu) . . . . . . . 142
data coverage, in Memory window . . . . . . . . . . . . . . . . . . 140
data log breakpoints, overview . . . . . . . . . . . . . . . . . . . . . 109
Data Log Summary window . . . . . . . . . . . . . . . . . . . . . . . . 97
Data Log window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Data Log (Timeline window context menu) . . . . . . . . . . . 180
Data Sample Setup window . . . . . . . . . . . . . . . . . . . . . . . . 99
Data Sample Setup (STice menu) . . . . . . . . . . . . . . . . . . . 306
Data Sample Setup (ST-LINK menu) . . . . . . . . . . . . . . . . 304
Data Sample window . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
Data Sample (Sampled Graphs window context menu) . . 104
Data Sample (STice menu) . . . . . . . . . . . . . . . . . . . . . . . . 306
Data Sample (ST-LINK menu) . . . . . . . . . . . . . . . . . . . . . 304
ddf (filename extension), selecting a file . . . . . . . . . . . . . . . 39
Debug Log window. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Debug menu (C-SPY main window) . . . . . . . . . . . . . . . . . . 46
Debug (Report Assert option) . . . . . . . . . . . . . . . . . . . . . . . 72
debugger concepts, definitions of . . . . . . . . . . . . . . . . . . . . 30
debugger drivers. See C-SPY drivers
Debugger Macros window . . . . . . . . . . . . . . . . . . . . . . . . 274
debugger system overview . . . . . . . . . . . . . . . . . . . . . . . . . 31
debugging projects
externally built applications . . . . . . . . . . . . . . . . . . . . . . 40
loading multiple images . . . . . . . . . . . . . . . . . . . . . . . . . 41
debugging, RTOS awareness. . . . . . . . . . . . . . . . . . . . . . . . 29
__delay (C-SPY system macro) . . . . . . . . . . . . . . . . . . . . 242
Delay (Autostep Settings option) . . . . . . . . . . . . . . . . . . . . 72
Delete (Breakpoints window context menu) . . . . . . . . . . . 118
Delete (SFR Setup window context menu) . . . . . . . . . . . . 156
Delete/revert All Custom SFRs (SFR Setup window context
menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Description (Edit Interrupt option) . . . . . . . . . . . . . . . . . . 215
description (interrupt property) . . . . . . . . . . . . . . . . . . . . . 215
Device description file (debugger option) . . . . . . . . . . . . . 294
device description files . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
memory zones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
modifying . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
register zone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
specifying interrupts . . . . . . . . . . . . . . . . . . . . . . . . . . 252
Disable All (Breakpoints window context menu) . . . . . . . 118
Disable Interrupts When Stepping (STice menu) . . . . . . . 305
Disable Interrupts When Stepping (ST-LINK menu) . . . . 304
Disable (Breakpoints window context menu) . . . . . . . . . . 118
__disableInterrupts (C-SPY system macro) . . . . . . . . . . . 243
--disable_interrupts (C-SPY command line option) . . . . . 284
Disassembly window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
context menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
disclaimer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
DLIB
naming convention . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
DLIB, documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
do (macro statement) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
document conventions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
documentation
overview of guides . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
overview of this guide . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Download (ST-LINK option) . . . . . . . . . . . . . . . . . . . . . . 298
--download_only (C-SPY command line option) . . . . . . . 284
313
UCSARM-4:3
Driver (debugger option). . . . . . . . . . . . . . . . . . . . . . . . . . 294
__driverType (C-SPY system macro) . . . . . . . . . . . . . . . . 243
E
Edit Expressions (Trace toolbar) . . . . . . . . . . . . . . . . . . . . 171
Edit Interrupt dialog box . . . . . . . . . . . . . . . . . . . . . . . . . . 214
Edit Memory Access dialog box . . . . . . . . . . . . . . . . . . . . 160
Edit Memory Range dialog box . . . . . . . . . . . . . . . . . . . . 157
Edit Settings (Trace toolbar) . . . . . . . . . . . . . . . . . . . . . . . 170
Edit (Breakpoints window context menu) . . . . . . . . . . . . . 118
Edit (SFR Setup window context menu) . . . . . . . . . . . . . . 156
edition, of this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Embedded C++ Technical Committee . . . . . . . . . . . . . . . . 22
Enable All (Breakpoints window context menu) . . . . . . . . 118
Enable interrupt simulation (Interrupt Setup option) . . . . . 213
Enable Log File (Log File option). . . . . . . . . . . . . . . . . . . . 71
Enable (Breakpoints window context menu) . . . . . . . . . . . 118
Enable (Interrupt Log window context menu) . . . . . . 221, 223
Enable (Sampled Graphs window context menu) . . . . . . . 104
Enable (Timeline window context menu) . . . . . . . . . . . . . 180
__enableInterrupts (C-SPY system macro) . . . . . . . . . . . . 244
Enable/Disable Breakpoint (Call
Stack window context menu) . . . . . . . . . . . . . . . . . . . . . . . 68
Enable/Disable Breakpoint (Disassembly window context
menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Enable/Disable (Trace toolbar) . . . . . . . . . . . . . . . . . . . . . 170
endianness. See byte order
Enter Location dialog box . . . . . . . . . . . . . . . . . . . . . . . . . 130
--erase_memory (C-SPY command line option) . . . . . . . . 284
__evaluate (C-SPY system macro) . . . . . . . . . . . . . . . . . . 244
Evaluate Now (Macro Quicklauncher
window context menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
examples
C-SPY macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
interrupts
interrupt logging . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
macros
checking status of register . . . . . . . . . . . . . . . . . . . . 229
C-SPY® Debugging Guide
314
for ARM
UCSARM-4:3
creating a log macro . . . . . . . . . . . . . . . . . . . . . . . . 230
using Quick Watch . . . . . . . . . . . . . . . . . . . . . . . . . 229
performing tasks and continue execution . . . . . . . . . . . 116
tracing incorrect function arguments . . . . . . . . . . . . . . 115
execUserExecutionStarted (C-SPY setup macro) . . . . . . . 237
execUserExecutionStopped (C-SPY setup macro) . . . . . . 238
execUserExit (C-SPY setup macro) . . . . . . . . . . . . . . . . . 239
execUserPreload (C-SPY setup macro). . . . . . . . . . . . . . . 237
execUserPreReset (C-SPY setup macro) . . . . . . . . . . . . . . 238
execUserReset (C-SPY setup macro) . . . . . . . . . . . . . . . . 238
execUserSetup (C-SPY setup macro) . . . . . . . . . . . . . . . . 238
executed code, covering . . . . . . . . . . . . . . . . . . . . . . . . . . 200
execution history, tracing . . . . . . . . . . . . . . . . . . . . . . . . . 167
expressions. See C-SPY expressions
Extra Options, for C-SPY . . . . . . . . . . . . . . . . . . . . . . . . . 297
F
File format (Memory Save option) . . . . . . . . . . . . . . . . . . 143
file types
device description, specifying in IDE . . . . . . . . . . . . . . 39
macro . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38, 294
filename extensions
ddf, selecting device description file . . . . . . . . . . . . . . . 39
mac, using macro file . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Filename (Memory Restore option) . . . . . . . . . . . . . . . . . 144
Filename (Memory Save option) . . . . . . . . . . . . . . . . . . . . 143
Fill dialog box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
__writeMemory8 (C-SPY system macro) . . . . . . . . . . . . . 245
__writeMemory16 (C-SPY system macro) . . . . . . . . . . . . 246
__writeMemory32 (C-SPY system macro) . . . . . . . . . . . . 246
Find in Trace dialog box . . . . . . . . . . . . . . . . . . . . . . . . . . 185
Find in Trace window . . . . . . . . . . . . . . . . . . . . . . . . . . . . 186
Find (Memory window context menu) . . . . . . . . . . . . . . . 142
Find (Trace toolbar) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
first activation time (interrupt property)
definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
First activation (Edit Interrupt option). . . . . . . . . . . . . . . . 215
flash memory, load library module to . . . . . . . . . . . . . . . . 249
Index
for (macro statement) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Forced Interrupt window . . . . . . . . . . . . . . . . . . . . . . . . . . 216
Forced Interrupts (Simulator menu) . . . . . . . . . . . . . . . . . 303
Function Profiler window . . . . . . . . . . . . . . . . . . . . . . . . . 194
Function Profiler (Simulator menu) . . . . . . . . . . . . . . . . . 302
Function profiler (STice menu) . . . . . . . . . . . . . . . . . . . . . 305
Function Trace window. . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Function Trace (Simulator menu) . . . . . . . . . . . . . . . . . . . 302
Function trace (STice menu) . . . . . . . . . . . . . . . . . . . . . . . 305
functions
call stack information for . . . . . . . . . . . . . . . . . . . . . . . . 60
C-SPY running to when starting . . . . . . . . . . . . . . 38, 294
most time spent in, locating . . . . . . . . . . . . . . . . . . . . . 189
G
Go to Source (Breakpoints window context menu) . . . . . . 118
Go to Source (Call Stack window context menu) . . . . . . . . 67
Go To Source (Timeline window context menu) . . . . 180–181
Go (Debug menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46, 59
H
highlighting, in C-SPY . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Hold time (Edit Interrupt option) . . . . . . . . . . . . . . . . . . . 215
hold time (interrupt property), definition of . . . . . . . . . . . 207
I
icons, in this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
if else (macro statement) . . . . . . . . . . . . . . . . . . . . . . . . . . 234
if (macro statement) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
Ignore (Report Assert option) . . . . . . . . . . . . . . . . . . . . . . . 72
illegal memory accesses, checking for . . . . . . . . . . . . . . . 136
Images window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
Images, loading multiple . . . . . . . . . . . . . . . . . . . . . . . . . . 295
immediate breakpoints, overview . . . . . . . . . . . . . . . . . . . 109
Include (Log File option) . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Input Mode dialog box . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
input, special characters in Terminal I/O window . . . . . . . . 69
installation directory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Instruction Profiling (Disassembly window context menu) . 65
Intel-extended, C-SPY output format . . . . . . . . . . . . . . . . . 32
Interrupt Log Summary window . . . . . . . . . . . . . . . . . . . . 222
Interrupt Log Summary (Simulator menu) . . . . . . . . 302–303
Interrupt Log window . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
Interrupt Log (Simulator menu) . . . . . . . . . . . . . . . . . . . . 303
Interrupt Setup dialog box . . . . . . . . . . . . . . . . . . . . . . . . 213
Interrupt Setup (Simulator menu) . . . . . . . . . . . . . . . . . . . 303
Interrupt Status window . . . . . . . . . . . . . . . . . . . . . . . . . . 217
interrupt system, using device description file . . . . . . . . . 209
Interrupt (Edit Interrupt option) . . . . . . . . . . . . . . . . . . . . 215
Interrupt (Timeline window context menu) . . . . . . . . . . . . 180
interrupts
adapting C-SPY system for target hardware . . . . . . . . 209
simulated, introduction to . . . . . . . . . . . . . . . . . . . . . . 205
timer, example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
using system macros . . . . . . . . . . . . . . . . . . . . . . . . . . 208
__isBatchMode (C-SPY system macro) . . . . . . . . . . . . . . 247
italic style, in this guide . . . . . . . . . . . . . . . . . . . . . . . . 22–23
L
labels (assembler), viewing . . . . . . . . . . . . . . . . . . . . . . . . . 78
Length (Fill option). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
library functions
online help for . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
lightbulb icon, in this guide . . . . . . . . . . . . . . . . . . . . . . . . . 23
linker options
typographic convention . . . . . . . . . . . . . . . . . . . . . . . . . 22
Little Endian (Memory window context menu) . . . . . . . . 141
Live Watch window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
__loadImage (C-SPY system macro) . . . . . . . . . . . . . . . . 248
loading multiple debug files, list currently loaded. . . . . . . . 50
loading multiple images . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Locals window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
log breakpoints, overview . . . . . . . . . . . . . . . . . . . . . . . . . 108
Log File dialog box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
315
UCSARM-4:3
Logging>Set Log file (Debug menu) . . . . . . . . . . . . . . . . . 48
Logging>Set Terminal I/O Log file (Debug menu) . . . . . . . 48
--log_file (C-SPY command line option) . . . . . . . . . . . . . 285
loop statements, in C-SPY macros . . . . . . . . . . . . . . . . . . 234
M
mac (filename extension), using a macro file . . . . . . . . . . . 38
--macro (C-SPY command line option) . . . . . . . . . . . . . . 285
macro files, specifying . . . . . . . . . . . . . . . . . . . . . . . . 38, 294
Macro Quicklaunch window . . . . . . . . . . . . . . . . . . . . . . . 276
Macro Registration window . . . . . . . . . . . . . . . . . . . . . . . 272
macro statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 234
macros
executing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227
using . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225
Macros (Debug menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
main function, C-SPY running to when starting . . . . . 38, 294
--mapu (C-SPY command line option) . . . . . . . . . . . . . . . 286
--mcuname (C-SPY command line option) . . . . . . . . . . . . 286
memory access checking. . . . . . . . . . . . . . . . . . . . . . . . . . 136
Memory access checking (Memory Access Setup option) 159
Memory Access Setup dialog box . . . . . . . . . . . . . . . . . . . 158
Memory Access Setup (Simulator menu) . . . . . . . . . . . . . 302
memory accesses, illegal . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Memory Fill (Memory window context menu) . . . . . . . . . 142
memory map . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Memory Restore dialog box . . . . . . . . . . . . . . . . . . . . . . . 144
Memory Restore (Memory window context menu) . . . . . . 142
Memory Save dialog box . . . . . . . . . . . . . . . . . . . . . . . . . 143
Memory Save (Memory window context menu) . . . . . . . . 142
Memory window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
memory zones . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
in device description file . . . . . . . . . . . . . . . . . . . . . . . 135
__memoryRestore (C-SPY system macro) . . . . . . . . . . . . 249
__memorySave (C-SPY system macro) . . . . . . . . . . . . . . 250
Memory>Restore (Debug menu) . . . . . . . . . . . . . . . . . . . . 47
Memory>Save (Debug menu) . . . . . . . . . . . . . . . . . . . . . . . 47
menu bar, C-SPY-specific . . . . . . . . . . . . . . . . . . . . . . . . . . 45
C-SPY® Debugging Guide
316
for ARM
UCSARM-4:3
__messageBoxYesNo (C-SPY system macro) . . . . . . . . . 250
MISRA C, documentation . . . . . . . . . . . . . . . . . . . . . . . . . 21
Mixed Mode (Disassembly window context menu) . . . . . . 66
Motorola, C-SPY output format . . . . . . . . . . . . . . . . . . . . . 32
Move to PC (Disassembly window context menu) . . . . . . . 64
N
Name (Edit SFR option) . . . . . . . . . . . . . . . . . . . . . . . . . . 157
naming conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Navigate (Sampled Graphs window context menu) . . . . . 103
Navigate (Timeline window context menu) . . . . . . . . . . . 179
New Breakpoint (Breakpoints window context menu) . . . 119
Next Statement (Debug menu) . . . . . . . . . . . . . . . . . . . . . . 47
Next Symbol (Symbolic Memory window context menu) 147
O
__openFile (C-SPY system macro) . . . . . . . . . . . . . . . . . . 251
Operation (Fill option) . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
operators, sizeof in C-SPY . . . . . . . . . . . . . . . . . . . . . . . . . 76
optimizations, effects on variables . . . . . . . . . . . . . . . . . . . 76
Option Bytes window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
Option bytes (STice menu) . . . . . . . . . . . . . . . . . . . . . . . . 305
Option bytes (ST-LINK menu) . . . . . . . . . . . . . . . . . . . . . 304
options
on the command line . . . . . . . . . . . . . . . . . . . . . . 282, 297
Options (Stack window context menu) . . . . . . . . . . . . . . . 151
__orderInterrupt (C-SPY system macro). . . . . . . . . . . . . . 252
Originator (debugger option) . . . . . . . . . . . . . . . . . . . . . . 296
P
-p (C-SPY command line option) . . . . . . . . . . . . . . . . . . . 287
parameters
tracing incorrect values of . . . . . . . . . . . . . . . . . . . . . . . 60
typographic convention . . . . . . . . . . . . . . . . . . . . . . . . . 22
part number, of this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Index
peripheral units
device-specific . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
displayed in Register window . . . . . . . . . . . . . . . . . . . 134
in C-SPY expressions . . . . . . . . . . . . . . . . . . . . . . . . . . 75
initializing using setup macros . . . . . . . . . . . . . . . . . . . 226
Please select one symbol
(Resolve Symbol Ambiguity option) . . . . . . . . . . . . . . . . . 95
--plugin (C-SPY command line option) . . . . . . . . . . . . . . 287
plugin modules (C-SPY) . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
loading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Plugins (C-SPY options) . . . . . . . . . . . . . . . . . . . . . . . . . . 296
__popSimulatorInterruptExecutingStack (C-SPY
system macro) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
pop-up menu. See context menu
prerequisites, programming experience. . . . . . . . . . . . . . . . 19
Previous Symbol (Symbolic
Memory window context menu) . . . . . . . . . . . . . . . . . . . . 148
probability (interrupt property) . . . . . . . . . . . . . . . . . . . . . 215
definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207
Probability % (Edit Interrupt option) . . . . . . . . . . . . . . . . 215
Profile Selection (Timeline window context menu) . . . . . 181
profiling
analyzing data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
on function level . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 191
on instruction level . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
profiling information, on functions and instructions . . . . . 189
profiling sources
trace (calls) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190, 195
trace (flat) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190, 196
program execution, in C-SPY . . . . . . . . . . . . . . . . . . . . . . . 55
programming experience. . . . . . . . . . . . . . . . . . . . . . . . . . . 19
program, see also application
projects, for debugging externally built applications . . . . . . 40
publication date, of this guide . . . . . . . . . . . . . . . . . . . . . . . . 2
Q
Quick Watch window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
executing C-SPY macros . . . . . . . . . . . . . . . . . . . . . . . 229
R
Range for (Viewing Range option) . . . . . . . . . . . . . . . . . . 182
__readFile (C-SPY system macro) . . . . . . . . . . . . . . . . . . 254
__readFileByte (C-SPY system macro) . . . . . . . . . . . . . . 255
__readMemoryByte (C-SPY system macro) . . . . . . . . . . . 255
__readMemory8 (C-SPY system macro) . . . . . . . . . . . . . 255
__readMemory16 (C-SPY system macro) . . . . . . . . . . . . 256
__readMemory32 (C-SPY system macro) . . . . . . . . . . . . 256
reference information, typographic convention . . . . . . . . . . 23
Refresh (Debug menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
register groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
predefined, enabling . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
Register window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152
registered trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
__registerMacroFile (C-SPY system macro). . . . . . . . . . . 257
registers, displayed in Register window . . . . . . . . . . . . . . 152
Remove All (Macro Quicklauncher window
context menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277
Remove (Macro Quicklauncher window context menu) . . 277
Repeat interval (Edit Interrupt option) . . . . . . . . . . . . . . . 215
repeat interval (interrupt property), definition of. . . . . . . . 207
Replace (Memory window context menu) . . . . . . . . . . . . 142
Report Assert dialog box . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Reset (Debug menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
__resetFile (C-SPY system macro) . . . . . . . . . . . . . . . . . . 257
Resolve Source Ambiguity dialog box . . . . . . . . . . . . . . . 131
Restore (Memory Restore option) . . . . . . . . . . . . . . . . . . . 144
return (macro statement) . . . . . . . . . . . . . . . . . . . . . . . . . . 235
ROM-monitor, definition of . . . . . . . . . . . . . . . . . . . . . . . . 32
RTOS awareness debugging . . . . . . . . . . . . . . . . . . . . . . . . 29
RTOS awareness (C-SPY plugin module) . . . . . . . . . . . . . . 29
Run to Cursor (Call Stack window context menu) . . . . . . . 67
Run to Cursor (Debug menu) . . . . . . . . . . . . . . . . . . . . . . . 47
Run to Cursor (Disassembly window context menu) . . . . . 65
Run to Cursor, command for executing. . . . . . . . . . . . . . . . 60
Run to (C-SPY option) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Run to (debugger option) . . . . . . . . . . . . . . . . . . . . . . . . . 294
317
UCSARM-4:3
S
Sample Graphs window . . . . . . . . . . . . . . . . . . . . . . . . . . 102
Sampled Graphs (STice menu) . . . . . . . . . . . . . . . . . . . . . 306
Sampled Graphs (ST-LINK menu) . . . . . . . . . . . . . . . . . . 304
Save Custom SFRs (SFR Setup window context menu) . . 157
Save to log file (context menu command) . . . . . . . . . 221, 223
Save (Memory Save option) . . . . . . . . . . . . . . . . . . . . . . . 143
Save (Trace toolbar) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
Scale (Viewing Range option). . . . . . . . . . . . . . . . . . . . . . 182
Select All (Debug Log window context menu) . . . . . . . . . . 70
Select Graphs (Sampled Graphs window context menu) . . 105
Select Graphs (Timeline window context menu) . . . . . . . . 181
Select plugins to load (debugger option) . . . . . . . . . . . . . . 296
Set Data Breakpoint (Memory window context menu) . . . 142
Set Next Statement (Debug menu) . . . . . . . . . . . . . . . . . . . 47
Set Next Statement (Disassembly window context menu) . 66
__setCodeBreak (C-SPY system macro). . . . . . . . . . . . . . 258
__setDataBreak (C-SPY system macro) . . . . . . . . . . . . . . 259
__setDataLogBreak (C-SPY system macro) . . . . . . . . . . . 260
__setLogBreak (C-SPY system macro) . . . . . . . . . . . . . . 261
__setSimBreak (C-SPY system macro) . . . . . . . . . . . . . . 262
__setTraceStartBreak (C-SPY system macro) . . . . . . . . . . 263
__setTraceStopBreak (C-SPY system macro) . . . . . . . . . . 264
setup macro file, registering . . . . . . . . . . . . . . . . . . . . . . . . 38
setup macro functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
reserved names. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
Setup macros (debugger option) . . . . . . . . . . . . . . . . . . . . 294
Setup (C-SPY options) . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
SFR
using as assembler symbols . . . . . . . . . . . . . . . . . . . . . . 75
SFR Setup window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
shortcut menu. See context menu
Show all images (Images window context menu) . . . . . . . . 50
Show All (SFR Setup window context menu) . . . . . . . . . . 156
Show Arguments (Call Stack window context menu) . . . . . 67
Show Custom SFRs only (SFR Setup
window context menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Show Cycles (Interrupt Log window context menu) . 221, 224
C-SPY® Debugging Guide
318
for ARM
UCSARM-4:3
Show Factory SFRs only (SFR Setup
window context menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
Show Numerical Value (Sampled Graphs window context
menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105
Show Numerical Value (Timeline window context menu) 180
Show offsets (Stack window context menu) . . . . . . . . . . . 150
Show only (Image window context menu) . . . . . . . . . . . . . 50
Show Time (Interrupt Log window context menu) . . 221, 224
Show variables (Stack window context menu) . . . . . . . . . 150
--silent (C-SPY command line option) . . . . . . . . . . . . . . . 288
Simulated FrequencyDlg . . . . . . . . . . . . . . . . . . . . . . . . . 306
simulating interrupts, enabling/disabling . . . . . . . . . . . . . 213
Simulator menu. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 302
simulator, introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
Size (Edit SFR option) . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Size (Sampled Graphs window context menu) . . . . . . . . . 105
Size (Timeline window context menu) . . . . . . . . . . . . . . . 180
sizeof . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
software breakpoints, use of . . . . . . . . . . . . . . . . . . . . . . . 110
Solid Graph (Sampled Graphs window context menu) . . . 105
Solid Graph (Timeline window context menu) . . . . . . . . . 180
__sourcePosition (C-SPY system macro) . . . . . . . . . . . . . 265
special function registers (SFR)
using as assembler symbols . . . . . . . . . . . . . . . . . . . . . . 75
stack usage, computing . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
Stack window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
standard C, sizeof operator in C-SPY . . . . . . . . . . . . . . . . . 76
Start address (Fill option) . . . . . . . . . . . . . . . . . . . . . . . . . 145
Start address (Memory Save option) . . . . . . . . . . . . . . . . . 143
Statics window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Step Into (Debug menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Step Into, description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Step Out (Debug menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Step Out, description. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Step Over (Debug menu) . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Step Over, description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
step points, definition of . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
STice (C-SPY driver), hardware installation . . . . . . . . . . . . 35
Stop address (Memory Save option) . . . . . . . . . . . . . . . . . 143
Stop Debugging (Debug menu). . . . . . . . . . . . . . . . . . . . . . 46
Index
__strFind (C-SPY system macro) . . . . . . . . . . . . . . . . . . . 265
ST-LINK (C-SPY driver), hardware installation . . . . . . . . . 35
__subString (C-SPY system macro) . . . . . . . . . . . . . . . . . 266
--suppress_download (C-SPY command line option) . . . . 288
--swim (C-SPY command line option) . . . . . . . . . . . . . . . 288
Symbolic Memory window . . . . . . . . . . . . . . . . . . . . . . . . 146
Symbols window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
symbols, using in C-SPY expressions . . . . . . . . . . . . . . . . . 74
T
target system, definition of . . . . . . . . . . . . . . . . . . . . . . . . . 31
__targetDebuggerVersion (C-SPY system macro) . . . . . . 266
Terminal IO Log Files (Terminal IO Log Files option) . . . . 70
Terminal I/O Log Files dialog box . . . . . . . . . . . . . . . . . . . 69
Terminal I/O window . . . . . . . . . . . . . . . . . . . . . . . . . . 61, 68
terminology. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Text search (Find in Trace option) . . . . . . . . . . . . . . . . . . 186
Time Axis Unit (Timeline window context menu) . . . . . . 181
Timeline window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
Timeline (Simulator menu) . . . . . . . . . . . . . . . . . . . . . . . . 303
Timeline (STice menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
--timeout (C-SPY command line option) . . . . . . . . . . . . . 289
timer interrupt, example . . . . . . . . . . . . . . . . . . . . . . . . . . 210
Toggle Breakpoint (Code) (Call
Stack window context menu) . . . . . . . . . . . . . . . . . . . . . . . 67
Toggle Breakpoint (Code) (Disassembly
window context menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Toggle Breakpoint (Log) (Call
Stack window context menu) . . . . . . . . . . . . . . . . . . . . . . . 67
Toggle Breakpoint (Log) (Disassembly
window context menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Toggle Breakpoint (Trace Start) (Call
Stack window context menu) . . . . . . . . . . . . . . . . . . . . . . . 68
Toggle Breakpoint (Trace Start) (Disassembly
window context menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Toggle Breakpoint (Trace Stop) (Call
Stack window context menu) . . . . . . . . . . . . . . . . . . . . . . . 68
Toggle Breakpoint (Trace Stop) (Disassembly
window context menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Toggle source (Trace toolbar) . . . . . . . . . . . . . . . . . . . . . . 170
__toLower (C-SPY system macro) . . . . . . . . . . . . . . . . . . 267
tools icon, in this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
__toString (C-SPY system macro) . . . . . . . . . . . . . . . . . . 267
__toUpper (C-SPY system macro) . . . . . . . . . . . . . . . . . . 268
Trace Expressions window . . . . . . . . . . . . . . . . . . . . . . . . 184
Trace settings (STice menu) . . . . . . . . . . . . . . . . . . . . . . . 305
trace start and stop breakpoints, overview . . . . . . . . . . . . . 108
Trace Start breakpoints dialog box . . . . . . . . . . . . . . . . . . 182
Trace Stop breakpoints dialog box . . . . . . . . . . . . . . . . . . 183
Trace types (Trace Settings option) . . . . . . . . . . . . . . . . . . 169
Trace window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
trace (calls), profiling source. . . . . . . . . . . . . . . . . . . 190, 195
trace (flat), profiling source. . . . . . . . . . . . . . . . . . . . 190, 196
Trace (Simulator menu) . . . . . . . . . . . . . . . . . . . . . . . . . . 302
Trace (STice menu) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
trace, in Timeline window. . . . . . . . . . . . . . . . . . . . . . . . . 174
trademarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Trigger (Forced Interrupt window context menu) . . . . . . . 216
typographic conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
U
Unavailable, C-SPY message . . . . . . . . . . . . . . . . . . . . . . . 77
__unloadImage(C-SPY system macro) . . . . . . . . . . . . . . . 268
Use command line options (debugger option) . . . . . . . . . . 297
Use Extra Images (debugger option) . . . . . . . . . . . . . . . . . 295
Use manual ranges (Memory Access Setup option) . . . . . 159
Use ranges based on (Memory Access Setup option) . . . . 159
user application, definition of . . . . . . . . . . . . . . . . . . . . . . . 31
V
Value (Fill option) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145
variables
effects of optimizations . . . . . . . . . . . . . . . . . . . . . . . . . 76
information, limitation on . . . . . . . . . . . . . . . . . . . . . . . 76
using in C-SPY expressions . . . . . . . . . . . . . . . . . . . . . . 74
variance (interrupt property), definition of . . . . . . . . . . . . 207
319
UCSARM-4:3
Variance % (Edit Interrupt option) . . . . . . . . . . . . . . . . . . 215
--verify_download (C-SPY command line option) . . . . . . 289
version number
of this guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
Viewing Range dialog box . . . . . . . . . . . . . . . . . . . . . . . . 181
Viewing Range (Sampled Graphs window context menu) 104
Viewing Range (Timeline window context menu) . . . . . . 180
visualSTATE, C-SPY plugin module for . . . . . . . . . . . . . . . 32
W
warnings icon, in this guide . . . . . . . . . . . . . . . . . . . . . . . . 23
Watch window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
using . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
web sites, recommended . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
while (macro statement) . . . . . . . . . . . . . . . . . . . . . . . . . . 234
windows, specific to C-SPY . . . . . . . . . . . . . . . . . . . . . . . . 48
__writeFile (C-SPY system macro) . . . . . . . . . . . . . . . . . 269
__writeFileByte (C-SPY system macro) . . . . . . . . . . . . . . 269
__writeMemoryByte (C-SPY system macro) . . . . . . . . . . 270
__writeMemory8 (C-SPY system macro) . . . . . . . . . . . . . 270
__writeMemory16 (C-SPY system macro) . . . . . . . . . . . . 270
__writeMemory32 (C-SPY system macro) . . . . . . . . . . . . 271
Z
zone
defined in device description file . . . . . . . . . . . . . . . . . 135
in C-SPY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
part of an absolute address . . . . . . . . . . . . . . . . . . . . . . 130
Zone (Edit SFR option). . . . . . . . . . . . . . . . . . . . . . . . . . . 158
Zoom (Sampled Graphs window context menu) . . . . . . . . 104
Zoom (Timeline window context menu) . . . . . . . . . . . . . . 179
Symbols
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
__cancelAllInterrupts (C-SPY system macro) . . . . . . . . . 241
__cancelInterrupt (C-SPY system macro) . . . . . . . . . . . . . 241
C-SPY® Debugging Guide
320
for ARM
UCSARM-4:3
__clearBreak (C-SPY system macro) . . . . . . . . . . . . . . . . 242
__closeFile (C-SPY system macro) . . . . . . . . . . . . . . . . . 242
__delay (C-SPY system macro) . . . . . . . . . . . . . . . . . . . . 242
__disableInterrupts (C-SPY system macro) . . . . . . . . . . . 243
__driverType (C-SPY system macro) . . . . . . . . . . . . . . . . 243
__enableInterrupts (C-SPY system macro) . . . . . . . . . . . . 244
__evaluate (C-SPY system macro) . . . . . . . . . . . . . . . . . . 244
__fillMemory8 (C-SPY system macro). . . . . . . . . . . . . . . 245
__fillMemory16 (C-SPY system macro). . . . . . . . . . . . . . 246
__fillMemory32 (C-SPY system macro). . . . . . . . . . . . . . 246
__fmessage (C-SPY macro statement) . . . . . . . . . . . . . . . 235
__isBatchMode (C-SPY system macro) . . . . . . . . . . . . . . 247
__loadImage (C-SPY system macro) . . . . . . . . . . . . . . . . 248
__memoryRestore (C-SPY system macro) . . . . . . . . . . . . 249
__memorySave (C-SPY system macro) . . . . . . . . . . . . . . 250
__message (C-SPY macro statement) . . . . . . . . . . . . . . . . 235
__messageBoxYesNo (C-SPY system macro) . . . . . . . . . 250
__openFile (C-SPY system macro) . . . . . . . . . . . . . . . . . . 251
__orderInterrupt (C-SPY system macro). . . . . . . . . . . . . . 252
__popSimulatorInterruptExecutingStack (C-SPY
system macro) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
__readFile (C-SPY system macro) . . . . . . . . . . . . . . . . . . 254
__readFileByte (C-SPY system macro) . . . . . . . . . . . . . . 255
__readMemoryByte (C-SPY system macro) . . . . . . . . . . . 255
__readMemory8 (C-SPY system macro) . . . . . . . . . . . . . 255
__readMemory16 (C-SPY system macro) . . . . . . . . . . . . 256
__readMemory32 (C-SPY system macro) . . . . . . . . . . . . 256
__registerMacroFile (C-SPY system macro). . . . . . . . . . . 257
__resetFile (C-SPY system macro) . . . . . . . . . . . . . . . . . . 257
__setCodeBreak (C-SPY system macro). . . . . . . . . . . . . . 258
__setDataBreak (C-SPY system macro) . . . . . . . . . . . . . . 259
__setDataLogBreak (C-SPY system macro) . . . . . . . . . . . 260
__setLogBreak (C-SPY system macro) . . . . . . . . . . . . . . 261
__setSimBreak (C-SPY system macro) . . . . . . . . . . . . . . 262
__setTraceStartBreak (C-SPY system macro). . . . . . . . . . 263
__setTraceStopBreak (C-SPY system macro) . . . . . . . . . . 264
__smessage (C-SPY macro statement) . . . . . . . . . . . . . . . 235
__sourcePosition (C-SPY system macro) . . . . . . . . . . . . . 265
__strFind (C-SPY system macro) . . . . . . . . . . . . . . . . . . . 265
__subString (C-SPY system macro) . . . . . . . . . . . . . . . . . 266
Index
__targetDebuggerVersion (C-SPY system macro) . . . . . . 266
__toLower (C-SPY system macro) . . . . . . . . . . . . . . . . . . 267
__toString (C-SPY system macro) . . . . . . . . . . . . . . . . . . 267
__toUpper (C-SPY system macro) . . . . . . . . . . . . . . . . . . 268
__unloadImage (C-SPY system macro) . . . . . . . . . . . . . . 268
__writeFile (C-SPY system macro) . . . . . . . . . . . . . . . . . 269
__writeFileByte (C-SPY system macro) . . . . . . . . . . . . . . 269
__writeMemoryByte (C-SPY system macro) . . . . . . . . . . 270
__writeMemory8 (C-SPY system macro) . . . . . . . . . . . . . 270
__writeMemory16 (C-SPY system macro) . . . . . . . . . . . . 270
__writeMemory32 (C-SPY system macro) . . . . . . . . . . . . 271
-d (C-SPY command line option) . . . . . . . . . . . . . . . . . . . 283
-p (C-SPY command line option) . . . . . . . . . . . . . . . . . . . 287
--backend (C-SPY command line option) . . . . . . . . . . . . . 282
--code_coverage_file (C-SPY command line option) . . . . 282
--cycles (C-SPY command line option) . . . . . . . . . . . . . . 283
--disable_interrupts (C-SPY command line option) . . . . . 284
--download_only (C-SPY command line option) . . . . . . . 284
--erase_memory (C-SPY command line option) . . . . . . . . 284
--log_file (C-SPY command line option) . . . . . . . . . . . . . 285
--macro (C-SPY command line option) . . . . . . . . . . . . . . 285
--mapu (C-SPY command line option) . . . . . . . . . . . . . . . 286
--mcuname (C-SPY command line option) . . . . . . . . . . . . 286
--plugin (C-SPY command line option) . . . . . . . . . . . . . . 287
--silent (C-SPY command line option) . . . . . . . . . . . . . . . 288
--suppress_download (C-SPY command line option) . . . . 288
--swim (C-SPY command line option) . . . . . . . . . . . . . . . 288
--timeout (C-SPY command line option) . . . . . . . . . . . . . 289
--verify_download (C-SPY command line option) . . . . . . 289
Numerics
1x Units (Memory window context menu) . . . . . . . . . . . . 150
1x Units (Symbolic Memory window context menu) . . . . 148
2x Units (Memory window context menu) . . . . . . . . . . . . 150
4x Units (Memory window context menu) . . . . . . . . . . . . 151
8x Units (Memory window context menu) . . . . . . . . . . . . 141
321
UCSARM-4:3