ARM Technical Support Knowledge Articles

How do I use RVD Macros?

Applies to: RealView Development Suite (RVDS)

Answer

This FAQ sets out to introduce the RealView Debugger's (RVD) macro language, and provide examples of how it can be used.  A familiarity with RVD is assumed, and the FAQ should be read in conjunction with the RVD Command Line Reference Guide and User Guide.   It is also recommended that you read the FAQ on RVD Scripting and Automation.

The Macros in this FAQ were tested with RVDS 3.0 and RVDS v3.1 (example 6 - logger.inc, will only work with RVD v3.1 and later).

What can RVD's macro language do?

Similar to RVD scripts, macros are a way of automating the actions of the debugger.  The difference between macros and scripts are the syntax and features.  RVD's macro language implements a 'C like' syntax.  The main advantages it offers over scripting are:

  * Use of local variables (local to the macro)
  * Better control flow through use of "IF {} ELSE IF {} ELSE {}" and "WHILE{}"
  * Ability to attach macros to breakpoints


Basic Structure of a Macro

The basic structure is as follows:

 define int my_macro(parameter)    – definition  (return type, name, parameters)
 int parameter;                                     – setting the types of the parameters
 {
  // Body of macro                                  – body enclosed within {}
 }
 .                                                  –  a '.' denotes the end of the macro definition
 
Comments can either be designated using //, or  /* .... */.  A single comment can not span multiple lines.

 // Acceptable comment
 

 /* Also ok */

 /*
  Not ok
 */

Accessing Global & Local Symbols

Macros can access global symbols (symbols in RVD's symbol table) and local symbols defined within the macro itself.  Local symbols only exist for the duration of the macro's execution.  If you define a local symbol with the same name as a global symbol, the local will be used in preference.

Macros are themselves stored as symbols within the symbol table. This allows a macro to call any other loaded macro as if it were a subroutine. For example:

 define int macro1()
 {
  int number;      
     – Declare a local variable (local symbol)
  number = macro2()     – Call another macro, placing its return value into 'number'
  return number;
 }
 .

Using RVD Commands

Most RVD commands can be issued from within a macro.  To denote them as a debugger command you need to wrap the entire command in $ symbols.  For example:

 $ce @r0$;
 
There are some commands that can NOT be issued from a macro.  These include:

  ADD
  BOARD
  CONNECT
  DEFINE (unless it is the macro definition itself)
  DELETE
  DISCONNECT
  HELP
  HOST
  INCLUDE
  QUIT

Loading and Calling Macros

Macros are normally passed to RVD as a text file.  This can be loaded into RVD either from the command line:

  inc 'c:path omymacro.txt'
 
Or, through

 Tools menu --> Include commands from File...

You can also enter macros directly into RVD by going to:

 Tools menu --> Add/Edit Debugger Macros...

Once loaded, macros can be executed from the Cmd tab of the output pane:

  > inc 'c:CCStart.inc'   –  load the macro by including a script containing the definition
 inc> DEFINE /R int CCStart()
 inc>

 Include file (0) c:CCStart.inc completed.

  > CCStart()              – call macro
  *** Cycles At Start Of Count ***
 Instructions = 0

 Core_Cycles  = 0
 Bus Total    = 0

Attaching Macros to Breakpoints

Macros can be attached to breakpoints, in which case they will be run automatically every time the breakpoint is hit.  How to do this is covered in the RealView Debugger User Guide (available using the link below).

http://www.arm.com/documentation/Software_Development_Tools/index.html

Examples

Accompanying this FAQ are 5 sets of example macros that demonstrate different features of the macro language.  A brief description is given below, more details are given in the readme.txt file provided with each example.

1. CP15 Register Enumeration:
This example uses symbols provided by RVD to give a detailed break down of CP15 register contents. The results are displayed in a GUI window opened by the macro.

2. Function Cycle Counting with RVISS:
This example shows how macros can be used in conjunction with breakpoints. It provides an automated method of counting the cycles between two given points for RVISS targets.

3. ARM1136J(F)-S Virtual to Physical Address Translation:
This example shows how macros can automate a task that would otherwise be very time consuming. It provides a quick method of translating a virtual address to a physical address, using the target's own pagetables.

4. Accessing Coprocessor Registers:
This example shows how macros can extend RVD's functionality. This macro allows users to access coprocessor registers which would otherwise be inaccessible through RVD.

5. Running a batch file on the host OS:
This example demonstrates how you can execute a script (batch file for windows) on the host operating system. We define two macros (GenerateBatch and DisplayTimeDate) and use these to retrieve the system time and date from the host operating system.

6. Macros for demonstrating a new CLI feature available in RVD v3.1 "${  }":
This example demonstrates how you can insert hex values inside a string name using the ${} syntax. This is useful for creating unique filenames when creating a journal in RVD. (This will only work with RVDv3.1 and later).

Zip file icon Macro Examples for RVD

Attachments: macros_v3.zip

Article last edited on: 2008-09-09 15:47:55

Rate this article

[Bad]
|
|
[Good]
Disagree? Move your mouse over the bar and click

Did you find this article helpful? Yes No

How can we improve this article?

Link to this article
Copyright © 2011 ARM Limited. All rights reserved. External (Open), Non-Confidential