Using C-SPY macros

How to dump variables and register values with C-SPY macros

IAR Embedded Workbench is an integrated development environment which supports a wide range of microcontrollers. C-SPY, the debugger of IAR Embedded Workbench, includes an extensive macro system that can be used to make the testing process more efficient.

C-SPY macro language components

These are the four C-SPY macro language components:

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.

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.

Macro strings

In addition to C types, macro variables can hold values of macro strings. You should note that macro strings differ from C language strings. When you write a string literal 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.

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
  • Conditional statements
  • Loop statements
  • Return statements
  • Blocks

For more details about the macro language components, see the debugger user guide.

Example 1: Dump C variables at a selected location

C variables that have assigned addresses can be dumped using C-SPY macros. Other variables might be eliminated due to code optimizations. To ensure C variables are assigned an address, the volatile keyword can be used.

To create a C-SPY macro for dumping variables, we can create a macro function called “dump_values()”:

dump_values () {
  __var t1, t2; 
  t1 = callCount;
  t2 = fib;
   __message t1, ",", t2:%x, "\n";

Figure 1dump_values C-SPY macro function

We can save this text file as “dump.mac” and browse to the file from [Project] => [Options…] => [Debugger] => [Setup].


Figure 2Setup macros option settings

Set a code breakpoint where you wish to dump the values. Select [View] → [Breakpoints] to open the [Breakpoint] window. Right-click the breakpoint and select [Edit…].

Input dump_values() at the “Action” field. Then, when the code stops at the breakpoint, dump_values() will be executed.


Figure 3Edit the Breakpoint settings, specifying the C-SPY macro function at Action

Each time the code is stopped at the breakpoint, the debug log will display the dumped variables:


Figure 4Debug Log window, the result of dump_values() is shown

Example 2: Dump processor registers

Below is a C-SPY macro function that outputs processor core registers to the debug log. You can access core registers by putting # before the register name.

dump_reg () {
  __message "R0, R1, R2, R3 =", # R0:% x, ",", # R1:% x, ",", # R2:% x, ",", # R3:% x;
  __message "R4, R5, R6, R7 =", # R4:% x, ",", # R5:% x, ",", # R6:% x, ",", # R7:% x;
  __message "R8, R9, R10, R11 =", # R8:% x, ",", # R9:% x, ",", # R10:% x, ",", # R11:% x;
  __message "R12, R13, R14, R15 =", # R12:% x, ",", # R13:% x, ",", # R14:% x, ",", # R15:% x;
  __message "PSR =", # xPSR:% x;

Figure 5dump_reg C-SPY macro function

It can be convenient to add this and other macros to the same .mac file.

Manually executing C-SPY macros

Select [View] => [Quick Watch] to show the “Quick Watch” window.

By inputting “dump_reg()” and pressing “Enter”, or by clicking the button , you execute the dump_reg() function. The result is outputted to the debug log window.


Figure 6Quick Watch window

You can also use the “Macro Quicklaunch” window from [View] => [Macro Quicklaunch] to execute the macro and output the result:

Macro_Quicklaunch_windowFigure 7Macro Quicklaunch window


Figure 8Debug Log window showing the result of dump_reg()


In this article, we have showed a few examples specifically on how to output C variables and register contents to the “Debug log” window. By using C-SPY macros, you can automate debugging and verification tasks, but you can also perform a wide variety of other tasks such as hardware configuration, simulation of peripheral drivers and feeding of the application with simulated data during runtime. C-SPY macros can be used by themselves or combined with complex breakpoints and interrupt simulations, which gives you a wide variety of possibilities.

© IAR Systems 1995-2016 - All rights reserved.