Introduction to C-SPY macros

In this section:

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, seeInterrupts. This only applies if you are using the simulator driver.
Developing small debug utility functions.

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.

Briefly about the macro language

The syntax of the macro language is very similar to the C language. There are:

Macro statements, which are similar to C statements.
Macro functions, which you can define with or without parameters and return values.
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.

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.

IAR Embedded Workbench for RL78 5.20