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 1: dump_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 2: Setup 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 3: Edit 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 4: Debug 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 5: dump_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 6: Quick Watch window

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

Figure 7: Macro Quicklaunch window

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

Conclusion

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.