RealView Debugger Command Line Reference

RealView Debugger Command Line Reference
RealView Debugger
®
Version 3.0
Command Line Reference Guide
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger
Command Line Reference Guide
Copyright © 2002-2006 ARM Limited. All rights reserved.
Release Information
The following changes have been made to this document.
Change History
Date
Issue
Change
April 2002
A
RealView Debugger v1.5 release
September 2002
B
RealView Debugger v1.6 release
February 2003
C
RealView Debugger v1.6.1 release
September 2003
D
RealView Debugger v1.6.1 release for RVDS v2.0
January 2004
E
RealView Debugger v1.7 release for RVDS v2.1
December 2004
F
RealView Debugger v1.8 release for RVDS v2.2
May 2005
G
RealView Debugger v1.8 SP1 release for RVDS v2.2 SP1
March 2006
H
RealView Debugger 3.0 release for RVDS v3.0
Proprietary Notice
Words and logos marked with ® or ™ are registered trademarks or trademarks owned by ARM Limited. Other
brands and names mentioned herein may be the trademarks of their respective owners.
Neither the whole nor any part of the information contained in, or the product described in, this document
may be adapted or reproduced in any material form except with the prior written permission of the copyright
holder.
The product described in this document is subject to continuous developments and improvements. All
particulars of the product and its use contained in this document are given by ARM in good faith. However,
all warranties implied or expressed, including but not limited to implied warranties of merchantability, or
fitness for purpose, are excluded.
This document is intended only to assist the reader in the use of the product. ARM Limited shall not be liable
for any loss or damage arising from the use of any information in this document, or any error or omission in
such information, or any incorrect use of the product.
Confidentiality Status
This document is Non-Confidential. The right to use, copy and disclose this document may be subject to
license restrictions in accordance with the terms of the agreement entered into by ARM and the party that
ARM delivered this document to.
ii
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
Product Status
The information in this document is final, that is for a developed product.
Web Address
http://www.arm.com
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
iii
iv
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
Contents
RealView Debugger Command Line Reference
Guide
Preface
About this book ............................................................................................ viii
Feedback ....................................................................................................... xi
Chapter 1
Working with the CLI
1.1
1.2
1.3
1.4
1.5
1.6
1.7
1.8
1.9
Chapter 2
RealView Debugger Commands
2.1
2.2
2.3
ARM DUI 0175H
General command language syntax ........................................................... 1-2
Window and file numbers ............................................................................ 1-5
Using expressions and statements ............................................................. 1-6
Command scripts ........................................................................................ 1-7
Macro language ........................................................................................ 1-10
Types of RealView Debugger expressions ............................................... 1-15
Constructing expressions .......................................................................... 1-16
Using variables in the debugger ............................................................... 1-33
Source patching with macros .................................................................... 1-41
Command syntax definition ......................................................................... 2-2
Debugger commands listed by function ...................................................... 2-3
Alphabetical command reference .............................................................. 2-13
Copyright © 2002-2006 ARM Limited. All rights reserved.
v
Chapter 3
RealView Debugger Predefined Macros
3.1
3.2
Chapter 4
RealView Debugger Keywords
4.1
4.2
vi
Predefined macros listed by function .......................................................... 3-2
Alphabetical predefined macro reference ................................................... 3-6
Keywords listed by function ........................................................................ 4-2
Alphabetical keyword reference ................................................................. 4-4
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
Preface
This preface introduces the RealView® Debugger v3.0 Command Line Reference Guide.
It contains the following sections:
•
About this book on page viii
•
Feedback on page xi.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
vii
Preface
About this book
You can control the RealView Debugger by using either its Graphical User Interface
(GUI) or its Command-Line Interface (CLI). This book describes the RealView
Debugger CLI.
Intended audience
This book has been written for developers who are using RealView Debugger to debug
software written to run on ARM® architecture-based target systems. It assumes that you
are a software developer who is familiar with command-line tools. It does not assume
that you are familiar with RealView Debugger.
Using this book
This book is organized into the following parts and chapters:
Chapter 1 Working with the CLI
Read this chapter for an introduction to the RealView Debugger CLI.
Chapter 2 RealView Debugger Commands
Read this chapter for a detailed description of the RealView Debugger
CLI commands.
Chapter 3 RealView Debugger Predefined Macros
Read this chapter for a detailed description of the RealView Debugger
predefined macros.
Chapter 4 RealView Debugger Keywords
Read this chapter for a detailed description of the RealView Debugger
keywords.
Typographical conventions
The following typographical conventions are used in this book:
viii
italic
Highlights important notes, introduces special terminology,
denotes internal cross-references, and citations.
bold
Highlights interface elements, such as menu names. Denotes
ARM processor signal names. Also used for terms in descriptive
lists, where appropriate.
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
Preface
monospace
Denotes text that can be entered at the keyboard, such as
commands, file and program names, and source code.
monospace
Denotes a permitted abbreviation for a command or option. The
underlined text can be entered instead of the full command or
option name.
monospace italic
Denotes arguments to commands and functions where the
argument is to be replaced by a specific value.
monospace bold
Denotes language keywords when used outside example code.
Further reading
This section lists publications from both ARM Limited and third parties that provide
additional information on developing code for the ARM family of processors.
ARM periodically provides updates and corrections to its documentation. See the
Documentation area of http://www.arm.com for current errata sheets, addenda, and the
ARM Frequently Asked Questions list.
ARM publications
This book is part of the RealView Debugger documentation suite. Other books in this
suite include:
•
RealView Debugger v3.0 Essentials Guide (ARM DUI 0181)
•
RealView Debugger v3.0 User Guide (ARM DUI 0153)
•
RealView Debugger v3.0 Trace User Guide (ARM DUI 0322)
•
RealView Debugger v3.0 RTOS Guide (ARM DUI 0323)
•
RealView Debugger v3.0 Target Configuration Guide (ARM DUI 0182).
For details on using the RealView Compilation Tools (RVCT), see the books in the
RVCT documentation suite.
For details on using RealView ARMulator® ISS, see the following documentation:
•
RealView ARMulator ISS User Guide (ARM DUI 0207).
For general information on software interfaces and standards supported by ARM, see
install_directory\Documentation\Specifications\....
See the following documentation for information relating to the ARM debug interfaces
suitable for use with RealView Debugger:
•
RealView ICE and RealView Trace User Guide (ARM DUI 0155)
•
Multi-ICE® User Guide (ARM DUI 0048)
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
ix
Preface
•
ARM MultiTrace™ User Guide (ARM DUI 0150).
See the datasheet or Technical Reference Manual for your hardware.
Other publications
For a comprehensive introduction to ARM architecture see:
Steve Furber, ARM System-on-Chip Architecture, Second Edition, 2000, Addison
Wesley, ISBN 0-201-67519-6.
For a detailed introduction to regular expressions, as used in the RealView Debugger
search and pattern matching tools, see:
Jeffrey E. F. Friedl, Mastering Regular Expressions, Powerful Techniques for Perl and
Other Tools, 1997, O'Reilly & Associates, Inc. ISBN 1-56592-257-3.
For the definitive guide to the C programming language, on which the RealView
Debugger macro and expression language is based, see:
Brian W. Kernighan, Dennis M. Ritchie, The C Programming Language, second
edition, 1989, Prentice-Hall, ISBN 0-13-110362-8.
For more information about IEEE Std. 1149.1 (JTAG), see:
IEEE Standard Test Access Port and Boundary Scan Architecture (IEEE Std. 1149.1),
available from the IEEE (www.ieee.org).
For more information about CEVA-Oak, CEVA-TeakLite, and CEVA-Teak processors
from CEVA, Inc. see http://www.ceva-dsp.com.
For more information about the ZSP400 and ZSP500 processors from the ZSP division
of LSI Logic see http://www.zsp.com.
x
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
Preface
Feedback
ARM Limited welcomes feedback on both RealView Debugger and its documentation.
Feedback on RealView Debugger
If you have any problems with RealView Debugger, submit a Software Problem Report:
1.
Select Help → Send a Problem Report... from the RealView Debugger main
menu.
2.
Complete all sections of the Software Problem Report.
3.
To get a rapid and useful response, give:
4.
•
a small standalone sample of code that reproduces the problem, if
applicable
•
a clear explanation of what you expected to happen, and what actually
happened
•
the commands you used, including any command-line options
•
sample output illustrating the problem.
Email the report to your supplier.
Feedback on this book
If you have any comments on this book, send email to [email protected] giving:
•
the document title
•
the document number
•
the page number(s) to which your comments apply
•
a concise explanation of your comments.
General suggestions for additions and improvements are welcome.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
xi
Preface
xii
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
Chapter 1
Working with the CLI
This chapter introduces the RealView® Debugger Command-Line Interface (CLI). It
contains the following sections:
•
General command language syntax on page 1-2
•
Window and file numbers on page 1-5
•
Using expressions and statements on page 1-6
•
Command scripts on page 1-7
•
Macro language on page 1-10
•
Types of RealView Debugger expressions on page 1-15
•
Constructing expressions on page 1-16
•
Using variables in the debugger on page 1-33
•
Source patching with macros on page 1-41.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
1-1
Working with the CLI
1.1
General command language syntax
This section describes the general syntax conventions that are supported by the
RealView Debugger CLI:
•
General syntax rules
•
Command qualifiers and flags
•
Command parameters on page 1-3
•
Abbreviations on page 1-4.
1.1.1
General syntax rules
The commands you submit to the debugger must conform to the following rules:
1.1.2
•
Each command line can contain only one debugger command.
•
If you refer to a symbol, then you must use the same case that the symbol has in
the symbol table. Therefore, variables you create with the ADD command and
user-defined macros you create are case sensitive.
•
A command line can be up to 4095 characters in length.
Command qualifiers and flags
Many commands accept flags, qualifiers, and parameters, using the following syntax:
COMMAND [,qualifier | /flag] [parameter]...
If a command qualifier is present, it must appear after the command name and before
any command parameters.
Qualifiers
You introduce each command qualifier with a punctuation character, as follows:
,qualifier
A comma introduces a qualifier that provides the debugger with
additional information on how to execute a command. For example, the
command:
DHELP,FULL =command_name
displays the full version instead of the summary version of its help text.
Other comma qualifiers are included in the command descriptions
described in Chapter 2 RealView Debugger Commands.
1-2
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
Working with the CLI
Flags
You introduce each command flag with a forward slash character, as follows:
A flag is either one or two letters that acts as a switch.
/flag
For example, some commands accept a size flag. Valid size flags are:
/B
8 bits. Sets the size of some value or values to a byte.
/H
16 bits. Sets the size of some value or values to a halfword.
/W
32 bits. Sets the size of some value or values to a word.
For an example of a command that accepts these qualifiers, see FILL on
page 2-173.
Where a command supports flags, the flags are described as part of the
command syntax (see Chapter 2 RealView Debugger Commands).
1.1.3
Command parameters
As described in Command qualifiers and flags on page 1-2, commands accept flags,
qualifiers, and parameters.
Command parameters are typically expressions that represent values or addresses to be
used by a command. Parameters must be separated from each other with some form of
punctuation. However, punctuation for the first parameter might be optional:
=text
An equals sign introduces a text string when you have multiple
parameters. It is not required for the first parameter. Depending on the
command, this might specify:
•
a resource
•
a thread or process name
•
a number or string expression
•
an address or offset
•
a description
•
an instance
•
a location
•
a configuration.
;windowid | ;fileid
A semicolon introduces a specification of where any output produced by
the command is to be sent. If you supply a ;windowid or ;fileid
parameter, it must be the final parameter of the command. See Window
and file numbers on page 1-5 for details.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
1-3
Working with the CLI
;macro-call
A semicolon also introduces a specification of a macro to be called by the
command. If you supply a ;macro-call parameter, it must be the final
parameter of the command. You cannot use a ;windowid or ;fileid
parameter with a ;macro-call parameter. If you want to send the output
from the macro to a window or file, use the VMACRO command (see
VMACRO on page 2-365).
Rules for specifying command parameters
The parameters you supply to a RealView Debugger command must conform to the
following rules:
1.1.4
•
One or more spaces must separate command parameters from a command when
there is no punctuation (for example, a /, ,, or =).
•
If a parameter, for example a filename, includes spaces or other special characters,
you must enclose it in double quotes ("..."), or single quotes ('...').
•
In high-level mode, code addresses must be referenced by line numbers, labels,
and function names, or casted values.
Abbreviations
You can enter many debugger commands in an abbreviated form. The debugger requires
enough letters to uniquely identify the command you enter.
Many commands also have aliases. An alias is a different name that you can use instead
of the listed name (see ALIAS on page 2-23). If you can use a short form of an alias, the
underlined characters show the shortest acceptable form, for example:
BREAKI
Is an acceptable short form of BREAKINSTRUCTION.
BINSTRUCTION Is an alias of BREAKINSTRUCTION.
BI
Is the shortest form of BREAKINSTRUCTION.
DCOM
Is an acceptable short form of DCOMMANDS.
DHELP
Is an alias of DCOMMANDS.
To see if a particular CLI command has an acceptable short form or alias, see its
description in Chapter 2 RealView Debugger Commands.
1-4
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
Working with the CLI
1.2
Window and file numbers
Many commands and macros enable you to specify a window number (windowid) or file
number (fileid). The number identifies a window or file to which any output is sent.
You must use a number in the range 50 to 1024. For more information see:
•
FOPEN on page 2-179
•
VOPEN on page 2-367
•
fopen on page 3-15.
Note
When a user-defined number is in use for a window or a file, that number cannot be
reused until you close the associated window or file. Either:
•
use the VCLOSE command to close both windows and files at the command line (see
VCLOSE on page 2-361)
•
use the fclose predefined macro to close a file in a macro (see fclose on
page 3-11).
To see what windows and files you have opened, use the WINDOW command (see WINDOW
on page 2-375).
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
1-5
Working with the CLI
1.3
Using expressions and statements
The basic components of the RealView Debugger command-line language can be
classified as either expressions or statements, or a combination of both, where
statements are typically contained in include files (see the chapter that describes
debugging with command scripts in the RealView Debugger v3.0 User Guide).
This section describes:
•
Expressions
•
Keywords
•
Predefined macros.
1.3.1
Expressions
There are many types of expressions accepted by the RealView Debugger CLI, enabling
you to extend the operation of a command from the CLI. Expressions can be, for
example, binary mathematical expressions, references to module names, or calls to
functions. For an example of these and other types of expressions, see Types of RealView
Debugger expressions on page 1-15.
1.3.2
Keywords
The RealView Debugger keywords are statements that can be used in a macro
definition. These keywords are the same as the C language keywords, and they cannot
be redefined or used in any other context. For a detailed description of these keywords,
see Chapter 4 RealView Debugger Keywords.
1.3.3
Predefined macros
RealView Debugger also provides predefined macros. Predefined macros can be used:
•
in macros that you define
•
directly at the command line
•
with the CEXPRESSION command, if the macro returns a value.
For a detailed description of the predefined macros available in RealView Debugger, see
Chapter 3 RealView Debugger Predefined Macros.
For details on creating macros and using them with RealView Debugger, see the chapter
that describes using macros for debugging in the RealView Debugger v3.0 User Guide.
1-6
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
Working with the CLI
1.4
Command scripts
You can automate a debugging session by running command scripts. A command script
is a text file, which can contain:
•
CLI commands (see Chapter 2 RealView Debugger Commands)
•
predefined macros (see Chapter 3 RealView Debugger Predefined Macros).
•
user-defined macros (see Macro language on page 1-10).
You can also include comments in your command scripts (see Command script
comments).
1.4.1
Considerations when using command scripts
Each command must be on a separate line, and must not be split across multiple lines.
You do not have to be connected to a target to run a command script. However, some
commands require that you have:
•
established a connection to a target (such as the LOAD command)
•
an image loaded (such as the BREAKINSTRUCTION command).
You can connect to a target and load an image either:
•
manually before running your command script
•
within the command script.
See the chapter that describes debugging with command scripts in the RealView
Debugger v3.0 User Guide for full details on creating and using command scripts.
1.4.2
Command script comments
You can use comments in your command scripts. Any characters identified as belonging
to a comment are ignored by RealView Debugger. The following rules apply to
comments in command scripts:
•
C style comments begin with a slash followed by an asterisk (/*) and end with an
asterisk followed by a slash (*/). Also the comment text and the delimiters must
be on a single line:
—
valid comment
/* comment */
—
invalid comment
/*
another comment
*/
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
1-7
Working with the CLI
•
C++ style comments begin with two slashes (//) and end when the end of the line
is reached, for example:
// This is a line comment
// Copyright (c) ARM Limited
•
Comments that begin with //, but are not placed after a command, do not appear
in any log and journal files.
•
Comments can begin with a semicolon (;), for example:
; A comment
•
Comments can begin with //# and end when the end of the line is reached.
•
Comments that begin with //#, but are not placed after a command, appear only
in a journal file. Also, the //# prefix is replaced with ; in the that file.
•
Only // or //# comments can be placed at the end of a command, for example:
ADD int value
•
// integer value
Comments cannot be nested.
See Macro comments on page 1-13 for the rules that apply when placing comments in
macros.
1.4.3
Example command script
Example 1-1 shows a command script that:
•
connects to a target
•
loads an image
•
defines a user-defined macro to display the value of a variable in the image (see
Macro language on page 1-10 for more details about macros)
•
sets a breakpoint that runs the user-defined macro to display the value of a
variable when the breakpoint is activated.
Example 1-1 Sample command script
ERROR=ABORT
WAIT=ON
// Abort if error occurs when processing the script
// Wait for each command to finish
// Log the output from the image
STDIOLOG ON='c:\myprojects\project1\stdoutput.txt'
1-8
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
Working with the CLI
/* Connect to the ARM_Cortex-A8 model with ISSM */
CONNECT @[email protected]
/* Load the project1.axf image from myprojects directory */
LOAD 'c:\myprojects\project1\Debug\project1.axf'
/* Define macro to print a value (must be defined after image load) */
define /R int printval(thisVal)
int thisVal;
{
/* Print the value of the myvar variable when the
breakpoint is activated */
$PRINTVALUE thisVal$;
return 1; // continue execution after breakpoint is activated
}
.
// Scope to main() so that we can set a
// breakpoint using a line number
SCOPE main
/* Set a breakpoint at line 149 in project1.c */
BREAKINSTRUCTION \PROJECT1\#149:1 ; printval(myvar)
GO
// Run the image
STDIOLOG OFF
// Close the log file
UNLOAD 1
// Unload the image
DELFILE 1
// Remove the symbol definitions
DISCONNECT @[email protected]
// Disconnect from the target
WAIT=OFF
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
1-9
Working with the CLI
1.5
Macro language
Macros are constructed in a Kernighan and Ritchie C-like scripting language that is
interpreted on the host. You can create your own or use one of the available predefined
run-time macros (see Chapter 3 RealView Debugger Predefined Macros).
This section covers:
•
Macro definition
•
Macro body on page 1-11
•
Macro terminator on page 1-12
•
Macro comments on page 1-13
•
Macro local symbols on page 1-14.
See the chapter that describes using macros for debugging in the RealView Debugger
v3.0 User Guide for full details on creating and using macros.
1.5.1
Macro definition
A macro definition must contain:
•
the DEFINE command (see DEFINE on page 2-121)
•
the macro name, which is case sensitive
•
the macro body
•
a terminating full stop or period (.) as the first and only character on the last line.
The syntax of a macro definition is as follows:
DEFINE [/R] [return_type] macro_name([parameter_list])
[param_definitions]
{
macro_body
}
.
where:
The new macro can replace an existing user-defined macro with
the same name. If any symbol other than a user-defined macro has
the same name as the new macro, then the following error is
displayed:
/R
Error: E004D: Symbol with this name already exists.
return_type
1-10
The return type for the macro and is an optional component of the
macro definition. The type can be any legal C or C++ data type,
except const. The default type is int.
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
Working with the CLI
Note
One use of a macro return value is to control what action
RealView Debugger takes when a breakpoint is activated (see the
macro_call argument to BREAKINSTRUCTION on page 2-67).
parameter_list
A parameter list for the macro and is an optional component of the
macro definition. You specify a parameter list in the same way that
you specify arguments for a C function. If parameter_list is
defined then the type must also be specified or else type int is
assumed. The following example illustrates the use of a
parameter_list:
define int scpy(target, source)
char *target;
char *source;
The declaration defines arguments for the macro scpy(). The type
of both the target and the source are declared to be pointers to a
char.
Note
For full details on the DEFINE command, see DEFINE on page 2-121.
1.5.2
Macro body
The macro body consists of the source lines of the macro and optional formal
arguments. You can have multiple statements on a single line, but a single statement
must not be split across multiple lines.
The syntax of a macro body is as follows:
[local_definitions]
macro_statement;[macro_statement;]...
where:
local_definitions
defines variables used locally in the macro body.
Formal arguments can be used throughout the macro body. These arguments are later
replaced by the values of the actual arguments in the macro call.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
1-11
Working with the CLI
Using CLI commands in a macro
You can use debugger commands in the macro body. If used, you must enclose the
command with dollar signs ($) and end in a semi-colon (;), and the command must not
be split across multiple lines, for example:
last_time = @cycle;
value = base[offset];
base[offset] = 0;
$printf "base offset value=%d\n",value$;
You can also use macro arguments and local variables in RealView Debugger
commands.
You cannot use the following commands inside a macro:
ADD
•
•
BOARD
•
CONNECT
•
DEFINE (unless it is the macro definition itself)
•
DELETE
•
DISCONNECT
•
HELP
•
HOST
•
INCLUDE
•
QUIT.
Also you cannot used execution-type commands (for example, STEP) in a macro if you
attach the macro to another entity, such as a breakpoint. See the chapter that describes
using macros for debugging in the RealView Debugger v3.0 User Guide.
1.5.3
Macro terminator
A macro terminator is used as the last character of the macro definition. This is a
full-stop or period (.) and must be the first and only character on the line.
1-12
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
Working with the CLI
1.5.4
Macro comments
You can use comments in your macros to document your code. Any characters
identified as belonging to a comment are ignored by RealView Debugger. The
following rules apply to comments in macros:
•
C style comments begin with a slash followed by an asterisk (/*) and end with an
asterisk followed by a slash (*/), for example:
/* comment */
/*
This is another
comment
*/
•
C++ style comments begin with two slashes (//) and end when the end of the line
is reached, for example:
// This is a line comment
// Copyright (c) ARM Limited
•
Only // comments can be placed at the end of a macro statement, for example:
macro_statement;
•
// comment
Only // comments can be nested within a /* */ comment, for example:
/*
This is a comment
// This is another comment
*/
See Command script comments on page 1-7 for the rules that apply when placing
comments outside of macro definitions in a command script.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
1-13
Working with the CLI
1.5.5
Macro local symbols
You can create symbols in a macro that are local to the macro. You must declare a type
for macro local symbols. The type can be any legal C or C++ data type, except const.
For example:
define /R int sqrValue(value)
int value;
{
int squared;
squared = value * value;
return squared;
}
.
All symbols declared within a macro exist only during the execution of the macro, that
is the static keyword is not recognized.
To create the equivalent of a global static variable, use the ADD command (see ADD on
page 2-18) to create the symbol before defining the macro that references the symbol.
For example:
add int cnt
define /R counter()
{
cnt = cnt + 1;
}
.
1-14
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
Working with the CLI
1.6
Types of RealView Debugger expressions
As described in General command language syntax on page 1-2, the CLI requires that
you enter commands in a form acceptable to the debugger. The components of these
commands are expressions and statements. For more details on statements, see Using
expressions and statements on page 1-6.
Table 1-1 shows the types of expressions that are accepted by the CLI. For each type,
there is a cross-reference to a command in Chapter 2 RealView Debugger Commands
where the expression type might be used. However, the use is not limited to these
commands.
Table 1-1 Types of CLI expressions
Type
Pattern/example
Usage cross-reference
Arithmetical operation (value or address)
x+(y*5)
FILL on page 2-173
Array element reference (value or address)
argv[1]
ARGUMENTS on page 2-32
Conditional expression
c==3
BREAKINSTRUCTION on page 2-67
Floating-point expression
3.14
FPRINTF on page 2-182
Function name reference (code address)
main
LIST on page 2-200
Line reference (code address)
#line_number
SCOPE on page 2-268
Macro call
macro()
ALIAS on page 2-23
Memory address
&address
BREAKINSTRUCTION on page 2-67
Memory address
(type *) expression
PRINTVALUE on page 2-247
Memory location
0x8000
BREAKREAD on page 2-74
Memory range expression
0x100..0x200
BREAKREAD on page 2-74
Qualified line (specifying source module)
MODULE1\#12
SCOPE on page 2-268
Stack level reference
stack_level
SCOPE on page 2-268
String expression
"string"
FILL on page 2-173
Symbol reference (value or address)
symbol_name
ADD on page 2-18
Target connection reference
targetname
CONNECT on page 2-108
Target program function
function()
BREAKINSTRUCTION on page 2-67
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
1-15
Working with the CLI
1.7
Constructing expressions
The debugger groups expressions into two classes:
•
C source language expressions, used in assembled or compiled source mode
•
assembly language expressions, used in assembly source or disassembly mode.
Most valid C expressions are also valid in the debugger (see Using expressions and
statements on page 1-6). However, if you are an assembly language user, you do not
have to know how to program in C to use the debugger. Simple C expressions are the
same as standard algebraic expressions.
The types of expression elements accepted by the CLI are described in Types of
RealView Debugger expressions on page 1-15. This section introduces the basic
elements of the CLI, and how to construct expressions based on these elements. It
contains the following sections:
•
Permitted symbol names
•
Program symbols on page 1-17
•
Debugger variable symbols on page 1-18
•
Macro symbols on page 1-19
•
Reserved symbols on page 1-19
•
Addresses on page 1-30
•
Expression strings on page 1-31
•
Target functions on page 1-32.
1.7.1
Permitted symbol names
A symbol (also called an identifier) is a name that identifies something, for example
program and debugger variables, macros, keywords, and registers.
Symbols can be up to 1024 characters in length. The first character in a symbol must be
alphabetic, an underscore _, or the at sign @. The valid characters in a symbol include
upper- and lower-case alphabetic characters, numeric characters, the dollar sign $, at
sign @, and underscore _. Other symbolic characters cannot be used in symbols. The
debugger distinguishes between uppercase and lowercase characters in a symbol. A
symbol is therefore matched by the following regular expression:
[[email protected]][[email protected]$0-9]{0,1023}
Regular expressions are described in Mastering Regular Expressions (see Other
publications on page x).
1-16
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
Working with the CLI
If your compiler or assembler creates symbols that contain characters that are invalid in
RealView Debugger symbols, prefix the symbol name with an @ and enclose the rest of
the name in double quotes " to reference it, for example @"!parser". You cannot access
a symbol including a double quote character in its name.
1.7.2
Program symbols
Program symbols are identifiers associated with a source program. They include
variables, function names, and, depending on the compiler, macro names. Symbols
defined in the source of the application can normally be passed to the debugger. When
a program is loaded for debugging, program symbols are normally loaded into a symbol
table associated with the target connection.
Some compilers insert a leading underscore _ to all program source symbols so that
program symbol names are distinguished from other names. The debugger strips the
first leading underscore from such program symbols when an application file is read so
references to program symbols are as originally written.
Some compilers pass C and C++ preprocessor macros to the debugger. These are also
usable in expressions. The debugger shows the expansion in the output.
Listing Symbols
You can list all symbols currently defined in RealView Debugger. To do this, enter:
printsymbols /w *
For more details on using this command, see PRINTSYMBOLS on page 2-242.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
1-17
Working with the CLI
Referencing symbols
References to symbols or source-level line numbers can be unqualified or qualified. An
unqualified reference includes only the symbol or line number itself. A qualified
reference includes the symbol or line number preceded by a root (defined in the
following section), module and/or function name. Root, module, and function names
are separated from the symbol or line number by a backslash \. Module names must be
in uppercase. Table 1-2 summarizes examples of qualified symbols.
Table 1-2 Qualified symbol references
1.7.3
Form
Example
Comment
@root\\
@tst\\TS1ROOT
References module TS1ROOT in root @tst.
(Usually from file loaded as tst.x or tst.out.)
\global ::global
\x ::x
References global variable x in current root.
function\local
main\x
References local variable x in function main.
MODULE\function
SIEVE\main
References function main in module sieve.
MODULE\static
SIEVE\y
References static variable y in module sieve.
MODULE\line_number
ENTRY\#18
References line number 18 in module entry.
MODULE\function\local
ENTRY\main\x
References local variable x in function main in
module entry.
LINE\local
#20\x
References local variable x in an unnamed
block at line 20.
Debugger variable symbols
Debugger variables are created during a debugging session with the ADD CLI command,
and all have global scope. When a debugger symbol is created you can assign it a data
type (for example char, int, or long) and an initial value, but cannot assign initial values
to struct, union, or class type symbols.
Debugger variables can be stored in either:
•
Debugger memory. The debugger allocates memory for the variable for you.
•
Target memory. You must specify a target memory address for the variable.
1-18
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
Working with the CLI
1.7.4
Macro symbols
A RealView Debugger macro is similar to a C function. It has a name, a return type, and
optional arguments. You can also define macro-local variables, and the macro itself is a
sequence of statements. Symbols are used in macros in two ways:
Macro name
Local variables
This identifies the macro. Macro names are case sensitive. You
must avoid using the following when creating your own macros:
•
names of the predefined macros (see Chapter 3 RealView
Debugger Predefined Macros)
•
keywords (see Chapter 4 RealView Debugger Keywords)
•
debugger commands (see Chapter 2 RealView Debugger
Commands)
•
aliases you have defined using the ALIAS command (see
ALIAS on page 2-23).
Local variables can be defined within a macro as working storage
while the macro executes. A macro local variable can only be
accessed by the macro in which it is defined. It is created when the
macro is executed and has an undefined initial value.
Macros can call other macros, but not recursively. If your macro calls another
user-defined macro, then the called macro must be defined in the command script before
the macro that calls it.
See the chapter that describes using macros for debugging in the RealView Debugger
v3.0 User Guide for more information on creating and using macros.
1.7.5
Reserved symbols
Reserved symbols are reserved words that represent registers, status bits, and debugger
control variables. These symbols are always recognized by the debugger and can be
used at any time during a debugging session. Because reserved symbols have special
meanings within the debugger command language, they cannot be defined and used for
other purposes. To avoid conflict with other symbols, the names of all reserved symbols
are preceded by an at sign @. See Table 1-3 on page 1-21 for a list of reserved symbols
and their descriptions.
This section contains:
•
Displaying a list of currently defined symbols on page 1-20
•
Referencing reserved symbols on page 1-21
•
Printing reserved symbols on page 1-22
•
Symbols for referencing the common processor core registers on page 1-25
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
1-19
Working with the CLI
•
•
Symbols for referencing the extended CPSR and SPSR registers on page 1-26
Symbols for referencing internal variables and board-specific registers on
page 1-28.
Displaying a list of currently defined symbols
You can display a list of the symbols that are currently defined in RealView Debugger.
To do this, use the PRINTSYMBOLS command (see PRINTSYMBOLS on page 2-242):
printsymbols *
This command lists:
1-20
•
RealView Debugger reserved symbols. These include symbols defined for the
target associated with the current connection.
•
RealView Debugger predefined macros.
•
If you have an image loaded for the current connection, then the symbols defined
for that image are listed.
•
If you have defined any macros, then any arguments and local symbols defined
for those macros are listed.
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
Working with the CLI
Referencing reserved symbols
The RealView Debugger defines several symbols, known as reserved symbols, that
retain specific information for you to access. Table 1-3 shows these reserved symbols
with a short description. Reserved symbol names always begin with an at sign @ and can
be all uppercase or all lowercase.
Table 1-3 Reserved symbols
Symbol
Description
@register
References the named register. For more details see:
•
Symbols for referencing the common processor core registers on
page 1-25
•
Symbols for referencing internal variables and board-specific registers
on page 1-28.
@entry
Used to form a function pseudo-label, function\@entry, that identifies the first
location in the function after the code that sets up the function parameters. In
general, function\@entry refers to either:
•
the first executable line of code in that function
•
the first auto local that is initialized in that function.
In either case, function\@entry is beyond the function prologue, to ensure that
the function parameters can be accessed. This enables you to set a breakpoint
on a function without having to scope to the function in the File Editor pane,
or without having to know an address.
If no lines exist that set up any parameters for the function (for example, an
embedded assembler function), then the following error message is displayed:
Error: E0039: Line number not found.
As an example, if you have a function func_1(value) you might want to set a
breakpoint that triggers only when the argument value has a specific value on
entry to the function:
bi,when:{value==2} func_1\@entry
ARM DUI 0175H
@hlpc
Indicates your current high-level source code line. @hlpc is valid only if the
Program Counter (PC) is in a module that has high-level line information (that
is, a C, C++, or assembler source module compiled with debug turned on).
@hlpc contains the line number at the current PC only if located in source code.
Otherwise, it is zero.
@last_host_output
The last line of output that was generated by the HOST command.
@line_range
Contains the line range of the source code associated with the PC.
@module
Indicates the name of the current module as determined by the location of the
PC.
Copyright © 2002-2006 ARM Limited. All rights reserved.
1-21
Working with the CLI
Table 1-3 Reserved symbols (continued)
Symbol
Description
@procedure
Indicates the name of the current function as determined by the location of the
PC.
@file
Indicates the name of the current file as determined by the location of the PC.
@root
Indicates the current root name.
Printing reserved symbols
To print the reserved symbols, use the FPRINTF or PRINTF command with the appropriate
format specifier. Alternatively, use the PRINTVALUE command to print the contents of a
numerical reserved symbol, for example @hlpc. You can also use the PRINTSYMBOLS/F
command with no arguments, and the command displays all roots. For more details on
these commands, see:
•
FPRINTF on page 2-182
•
PRINTF on page 2-238
•
PRINTSYMBOLS on page 2-242
•
PRINTVALUE on page 2-247.
Also, see Reserved symbols on page 1-19.
Table 1-4 shows the format specifiers to use when printing reserved symbols.
Table 1-4 Format specifiers for printing reserved symbols
1-22
Format
specifier
Information to print
Symbol to use
Register contents, see:
•
Symbols for referencing the common processor core
registers on page 1-25
•
Symbols for referencing internal variables and
board-specific registers on page 1-28.
@register
This must match
the type of the
register.
Current instruction
@pc
%m
Current line number
@hlpc
%d
Current source line as text
@hlpc
%h
Last line output by the HOST command
@last_host_output
%s
Line range of the source code identified by the PC
@line_range
%s
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
Working with the CLI
Table 1-4 Format specifiers for printing reserved symbols (continued)
Information to print
Symbol to use
Format
specifier
Current module name
@module
%s
Current procedure name
@procedure
%s
Current file name determined by the PC
@file
%s
Current root name
@root
%s
Example
The following example shows how to use these symbols:
1.
Create an include file, for example symbols.inc, containing the following
command and macro definition (see Macro language on page 1-10):
add int windowOpened=0
define /R int rsvdSymbols(outputID)
int outputID;
{
if (outputID > 49) && (outputID <=1024) {
if (windowOpened != outputID)
$vopen outputID$;
$fprintf outputID, "****************************\n"$;
$fprintf outputID, "root:
%s\n", @root$;
$fprintf outputID, "hlpc:
%d\n", @hlpc$;
$fprintf outputID, "code line:
%h\n", @hlpc$;
$fprintf outputID, "instruction: %m", @pc$;
$fprintf outputID, "file:
%s\n", @file$;
$fprintf outputID, "line_range:
%s\n", @line_range$;
$fprintf outputID, "module:
%s\n", @module$;
$fprintf outputID, "procedure:
%s\n", @procedure$;
windowOpened=outputID;
}
else {
error(3,"Invalid window ID %d.\nValid range 50 to 1024.",outputID);
windowOpened=0;
}
// return 0 to stop at the breakpoint
return (0);
}
.
2.
Connect to RVISS (see CONNECT on page 2-108), for example:
connect "@localhost"
connect "@new_arm"
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
1-23
Working with the CLI
3.
Load the Dhrystone image from the main examples directory (see LOAD on
page 2-202):
load/r 'main_examples_directory\dhrystone\Debug\dhrystone.axf'
4.
Include the file you created in step 1 to define the macro (see INCLUDE on
page 2-194). If this is in the directory c:\myscripts, then enter:
include 'c:\myscripts\symbols.inc'
5.
Run the macro, with an outputID of 50 (see Window and file numbers on
page 1-5):
macro rsvdSymbols(50)
The following details are displayed:
root:
@dhrystone
hlpc:
0
code line:
<invalid line>
instruction: $00008000 EAFFFFFF B
file:
../../angel/startup.s
line_range:
module:
STARTUP_S
procedure: __main
$L0x8004 $
~<S0x8004>
Here the high-level source code line is zero, and no code line can be displayed.
This is because the PC is at a location in a library module that was compiled
without debug turned on, and the source file is not available.
6.
Set a breakpoint at the first executable line of code in function main, that also runs
the rsvdSymbols() macro when the breakpoint is reached (see BREAKINSTRUCTION on
page 2-67):
breakinstruction,macro:{rsvdSymbols(50)} main\@entry
7.
Run the Dhrystone application (see GO on page 2-186):
go
When the breakpoint is reached, the rsvdSymbols() macro runs, and the following
details are displayed:
root:
@dhrystone
hlpc:
91
code line:
Next_Ptr_Glob = (Rec_Pointer) malloc (sizeof (Rec_Type));
instruction: 000084D0 E3A00030 MOV
r0,#0x30
file:
c:\program files\arm\rvd\examples\1.7\5\windows\dhrystone\
dhry_1.c
line_range: 91..91
module:
DHRY_1
procedure: main
1-24
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
Working with the CLI
8.
Reload the Dhrystone application and clear the previous breakpoint (see RELOAD
on page 2-257 and CLEARBREAK on page 2-104):
reload
clear
9.
Set the breakpoint again, but specify the module and line:
breakinstruction,macro:{rsvdSymbols(50)} \DHRY_1\#149:1
10.
Run the Dhrystone application:
go
The listing shown in step 7 is displayed, but the line_range is now shown as
79..91.
Symbols for referencing the common processor core registers
Table 1-5 shows the symbols to use if you want to reference the processor core registers.
These are the registers shown in the Core tab of the Registers pane, and they are
common to all ARM architectures. You can also perform operations on these registers,
see Operations on symbols and registers on page 1-29.
Table 1-5 Common processor core register symbols
ARM DUI 0175H
Register symbol
Description
@Rn
Use this symbol to reference registers r1 to r12.
@R13 or @SP
References the SP register.
@R14 or @LR
References the LR register.
@R15 or @PC
References the PC register.
@CPSR
References the CPSR register.
@CPSR_C
References the Carry flag of the CPSR NZCV flags.
@CPSR_F
References the FIQ register of the CPSR.
@CPSR_FLG
A bitmap referencing the NZCV flags of the CPSR.
@CPSR_I
References the IRQ register of the CPSR.
@CPSR_MODE
References the MODE register of the CPSR.
@CPSR_N
References the Negative flag of the CPSR NZCV flags.
@CPSR_T
References the T flag of the CPSR STATE register.
Copyright © 2002-2006 ARM Limited. All rights reserved.
1-25
Working with the CLI
Table 1-5 Common processor core register symbols (continued)
Register symbol
Description
@CPSR_V
References the Overflow flag of the CPSR NZCV flags.
@CPSR_Z
References the Zero flag of the CPSR NZCV flags.
@R8_bank
References registers R8, R9, R10, R11, and R12 in register bank bank.
These are used only in register banks USR and FIQ.
For example, @R9_USR.
@R9_bank
@R10_bank
@R11_bank
@R12_bank
@R13_bank
References the SP register in register bank bank.
For example, @R13_IRQ.
@R14_bank
References the LR register in register bank bank.
For example, @R14_SVC.
@SPSR_bank
References the SPSR registers in a register bank. regs is one of the
following (see the equivalent CPSR symbols for details):
@SPSR_bank_regs
C
FLG
F
I
MODE
N
T
V
Z
Carry flag of the NZCV flags
NZCV flags
FIQ register
IRQ register
MODE register
Negative flag of the NZCV flags
T State flag of the STATE register
Overflow flag of the NZCV flags
Zero flag of the NZCV flags
Note
There is no SPSR register in the USR bank.
For example, @SPSR_IRQ_T references the processor STATE register in the
IRQ register bank.
Symbols for referencing the extended CPSR and SPSR registers
Table 1-6 on page 1-27 shows the CPSR and SPSR register symbols that are available
on processors cores that support the extended ARM architectures. These symbols are in
addition to those listed in Table 1-5 on page 1-25.
1-26
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
Working with the CLI
Table 1-6 Extended CPSR and SPSR processor core register symbols
Register symbol
Description
Earliest
architecture
supported
@CPSR_A
References the Imprecise Data Abort (IDA) Control flag of the CPSR.
ARMv6 or later
@CPSR_E
References the Endianness Control flag of the CPSR.
ARMv6 or later
@CPSR_FLGE
A bitmap referencing the NZCVQ flags of the CPSR.
ARMv5TE and
ARMv6 or later
@CPSR_GE
A bitmap referencing the Greater than or Equal flags GE[3:0] of the
CPSR.
ARMv6 or later
@CPSR_IT
References the If Then register of the CPSR.
ARMv6T2 or later
@CPSR_J
References the J State flag of the CPSR STATE register.
Jazelle®-capable
@CPSR_JT
References the J and T State flags of the CPSR STATE register. Set to
the following values:
0
To clear both flags (ARM state)
0x00000020
To set the T flag (Thumb state)
0x01000000
To set the J flag (Jazelle bytecode state)
0x01000020
To set both the T and J flags (Thumb-2EE state)
Thumb®-capable or
Jazelle-capable
@CPSR_Q
References the Unsaturated flag of the CPSR NZCVQ flags.
ARMv5TE and
ARMv6 or later
@SPSR_bank
References the SPSR registers in a register bank. regs is one of the
following (see the equivalent CPSR symbols for details):
@SPSR_bank_regs
A
FLGE
E
GE
IT
J
JT
Q
IDA Control flag
NZCVQ flags
Endianness Control flag
Greater than or Equal flags
IF Then register
J State flag of the STATE register
J and T State flags of the STATE register
Unsaturated flag of the NZCVQ flags
Note
There is no SPSR register in the USR bank.
For example, @SPSR_IRQ_T references the processor STATE register in the
IRQ register bank.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
1-27
Working with the CLI
Symbols for referencing internal variables and board-specific registers
You can also reference internal debugger variables and board-specific registers:
•
Internal debugger variables are displayed in extra tabs of the Registers pane, and
depend on your target connection. For example, the Debug tab is available when
connecting to RealView ICE.
•
Board-specific registers are displayed in other tabs of the Registers pane.
Note
You can also perform operations on the internal debugger variables and board-specific
registers, see Operations on symbols and registers on page 1-29.
To find the symbol names for the internal debugger variables, you must use the
RealView Debugger GUI. To find the symbol names for board-specific registers, you
can use either the RealView Debugger GUI, or look in the related board/chip definition
file (.bcd) in the RealView Debugger program_directory\etc directory.
To find the name of a board-specific (memory mapped) register or internal debugger
variable using the RealView Debugger GUI:
1.
2.
Select the required tab, for example, Debug.
Right-click on the register or variable that you want to reference, for example,
semihost_enabled.
3.
Select Properties from the context menu.
This displays an Information dialog. The Register: field shows the symbol name.
For semihost_enabled, the symbol name is @SEMIHOST_ENABLED.
To find the name of a board-specific (memory mapped) register from the related
board/chip definition file:
1.
Find the file in the RealView Debugger program_directory\etc directory that has
the same name as the board/chip definition. For example, the names for the
Integrator AP board are defined in the file AP.bcd.
2.
Open the file with a text editor.
Note
Do not make changes to this file directly. Use the Connection Properties window
in the GUI to make any changes. See the chapter that describes configuring
custom targets in the RealView Debugger v3.0 Target Configuration Guide.
1-28
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
Working with the CLI
3.
1.7.6
Search for lines containing Register.regname, where regname is the name of the
register, for example Register.G_SC_PCI.
Operations on symbols and registers
You can perform operations on symbols, on the registers listed in Table 1-5 on
page 1-25, the internal debugger variables, and board-specific registers. The operations
you can perform are listed in Table 1-7.
Table 1-7 Register operations
Operation
Description
Examples
@var = value
Assign a value to the symbol.
@PC = 0x8000
@var++, @var--
Increment or decrement the value in the symbol.
@R6++
@var = @var + value
Add a value to, or subtract a value from, the symbol.
@R12 = @R11+2
Multiply or divide the value in the symbol by a
specified value. Dividing by zero gives an error
message.
@R7 = @R7*2
@var &= [~]mask
AND the mask value with the contents of the symbol.
~ indicates the inverse of the mask value.
@FLG &= 3
@FLG &= ~3
@var |= [~]mask
OR the mask value with the contents of the symbol. ~
indicates the inverse of the mask value.
@FLG |= 3
@var ^= [~]mask
Exclusive OR the mask value with the contents of the
symbol. ~ indicates the inverse of the mask value.
@FLG ^= 3
@var = @var - value
@var = @var * value
@var = @var / value
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
1-29
Working with the CLI
1.7.7
Addresses
An address can be represented by most C expressions that evaluate to a single value. In
source-level mode, expressions that evaluate to a code address cannot contain numeric
constants or operators, unless you use a cast.
Data address and assembly-level code address expressions can also be represented by
most legal C expressions. For details on legal C expressions, see the C language
Reference Manual. There are no restrictions involving constants or operators. Table 1-8
summarizes the special addressing types supported by the RealView Debugger.
Table 1-8 Address expressions
Addressing type
Indicator
Example
Indirect addresses
[ ]
PRINTVALUE (H W) [23]
Line numbers
#
BREAKINSTRUCTION #10
Address ranges
..
DUMP 0x2200..0x2214
DUMP 0x2200..+14
Multistatement reference
:
BREAKINSTRUCTION #21:32 (refers to the
statement on line 21 that contains column 32)
.
BREAKINSTRUCTION #21.2 (refers to the second
statement on line 21)
Address of non-label symbol.
The symbol cannot be that of
a register or a constant.
1-30
&
BREAKREAD &var
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
Working with the CLI
1.7.8
Expression strings
An expression string is a list of values separated by commas. The expression string can
contain expressions and ASCII character strings enclosed in quotation marks. For
several commands, each value in an expression string can be changed to the size
specified by the size qualifiers. If the size is changed, padding is added to elements that
do not fit.
Examples of expression strings are shown in Table 1-9.
Table 1-9 Examples of expression strings
String
Results
1,2,"abc"
Values 1 and 2, and ASCII values of abc.
3+4, count, foo()
Value 7, value of count, results of calling foo.
'1xyz123'
ASCII values of 1, x, y, z, 1, 2, and 3.
You can cast values to arrays, so that for example you can access the second byte of a
32 bit word by casting the word to a byte array.
Note
If you enter a command line that starts with an open-bracket (, or an asterisk *, the
debugger interprets this as if you had entered a CEXPRESSION command with that text as
its argument (see CEXPRESSION on page 2-101). For example:
> *(char*)0x8000 = 0
is equivalent to:
> CE *(char*)0x8000 = 0
As with the normal CEXPRESSION command, you can use this to view or modify program
variables and memory. CE is the abbreviation for CEXPRESSION.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
1-31
Working with the CLI
1.7.9
Target functions
Target functions can be called within a debugger expression. Depending on the
processor, the data type of the return value determines the type that the function call
takes. Public labels, like runtime routines, are assumed to return an integer. Passing
structures by returning a pointer is not supported.
A target function called from a debugger expression behaves the same way as if it were
called from a user program. Target functions can invoke I/O operations or error
messages in addition to activating breakpoints and associated macros. If a breakpoint is
hit that stops execution, the registers are restored and the call ends with an error.
Arguments are copied to the stack below the current function. The return address is the
entry point of the application where a breakpoint is placed.
Macros take higher precedence than target functions. If a target function and a macro
have the same name, the macro is executed unless the target function is qualified. For
example, strcpy is a predefined debugger macro, while PROG\strcpy is a function within
the module PROG. The predefined macro is referenced as strcpy(t,s), while
PROG\strcpy(t,s) refers to the function within PROG. A target function must be called
within a debugger expression that is used within a command. It cannot be directly
executed as a command, but a macro can.
Example 1-2 Calling a target function
CEXPRESSION PROG\strcpy(t,s)
1-32
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
Working with the CLI
1.8
Using variables in the debugger
It is important to understand how to access variables that are stored in memory. This
section describes symbol storage classes and data types. It describes how to qualify a
symbolic reference with a module or function name, how to specify fully referenced
variables, and how to make stack references. It contains the following sections:
•
Scope
•
Data types on page 1-34
•
Root names on page 1-36
•
Module names on page 1-37
•
Variable references on page 1-38
•
Stack references on page 1-39.
1.8.1
Scope
All variables and functions in a C or C++ source program have a storage class that
defines how the variable or function is created and accessed. C preprocessor symbols
might not be available to the debugger.
Global (extern)
In the debugger, global variables can be referred to from any module.
However, if a symbol of the same name exists in the local scope, this
variable must be qualified by a root name, by \ (current root), or with ::.
ARM DUI 0175H
Static
In the debugger, static functions can be referred to from the same module
without qualification. Static functions in other modules must be qualified
with the module name if the name is ambiguous or the module has not
been used yet (not loaded).
Local
A local variable is accessible when it is local to the current function, local
to the current unnamed block, or when its function is on the stack. It can
be qualified by function, line, or stack level.
Register
Register variables might not be available from all lines in the function,
because hardware registers can be shared by more than one local register
variable. A register variable is accessible when it is local to the current
function or when its function is on the stack. It can be qualified by
function or stack level.
Copyright © 2002-2006 ARM Limited. All rights reserved.
1-33
Working with the CLI
Scoping rules
References to symbols follow the standard scoping rules of C and C++. If a symbol is
referenced, the debugger searches its symbol table using the following priority:
1.8.2
1.
Any symbol local to the current macro.
2.
Any symbol local to the current line.
3.
Any symbol local to the current function.
4.
Any symbol local to the class of the current function.
5.
Any symbol static to the current module.
6.
Any global symbol not necessarily in the current module.
7.
A static symbol in another module.
8.
A global symbol in another root (that is, a different loaded file).
Data types
All symbols and expressions have an associated data type:
•
Source language modules can contain any valid C or C++ language data type.
•
Assembly language modules can contain variables with the types shown in
Table 1-10. Some assemblers might have other types such as fixed-point. In
addition, each symbol has an attribute that indicates whether a variable was
defined in a code or data area. Also, the assembler can create arrays of these types
in addition to structures (check with the assembler manufacturer for details).
Table 1-10 Equivalent RealView Debugger data types for ARM assembler
1-34
ARM assembler data type
Equivalent data type in
RealView Debugger
Size
(bytes)
byte
unsigned char
1
word
unsigned short int
2
long
unsigned long
4
8-byte long
long long
8
single-precision floating point
float
4
double-precision floating point
double
8
label
label
1
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
Working with the CLI
You can access a specific number of bytes in memory using the following predefined
macros:
•
byte() to return an unsigned char (see byte on page 3-7)
•
word() to return an unsigned short int (see word on page 3-61)
•
dword() to return an unsigned long (see dword on page 3-8).
Type conversion
The RealView Debugger performs data-type conversions under the following
circumstances:
•
when two or more operands of different types appear in an expression, data type
conversion is performed according to the rules of C or C++
•
when arguments are passed to a macro or target function, the types of the passed
arguments are converted to the types given in the macro function definition
•
when the data type of an operand is forced by user-specified type casting, it is
converted
•
when a specific type is required by a command, the value is converted according
to the rules of C/C++.
Type casting
Type casting forces the conversion of an expression to the specified data type. The
contents of any variables that are referenced are not altered. Debugger expressions can
be cast into different types using the following syntax:
(type_name) expression
Example 1-3 Casting symbols and expressions into different types
(char) prime
(float) 12
(int) sin(0.2)
(int) ptr_char
/*
/*
/*
/*
/*
prime is cast to type char */
value is 12.0. (integer 12 in floating point) */
value is 0, sin(0.2) is 0.198, truncates to 0 */
the variable expression ptr_char is */
cast to type int */
The debugger can cast some expression types to an array type. Example 1-4 on
page 1-36 casts the constant expression 7 to an array of three characters starting at
location 0x0007.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
1-35
Working with the CLI
Example 1-4 Casting to an array
(char[3]) 7
/* address is 0x0007 */
This type of casting to an array can be used with the PRINTVALUE command (see
page 2-247). Assembly language structures can be displayed in a more meaningful form
by using this technique. Table 1-11 lists additional special casting types. Arrays of
hexadecimal types and pointers to hexadecimal types can also be used.
Table 1-11 Special casting types
1.8.3
Cast
Commands
Meaning
(QUOTED STRING) or (Q S)
PRINTVALUE
Show as "string."
(INSTRUCTION ADDRESS) or (I A)
All
Convert into a legal source-level
address.
(UNKNOWN TYPE) or (U T)
All
Convert into a single byte.
(HEX BYTE) or (H B)
All
Show in hex bytes.
(HEX WORD) or (H W)
All
Show in 16 bit hex.
(HEX DOUBLE WORD) or (H D)
All
Show in 32 bit hex.
Root names
Root names indicate the top level in a qualified path name. Each time the debugger is
invoked, it automatically creates a base root. This root is assigned the name \\ and
contains all debugger variables, macros, and most user-defined symbols. The only
user-defined symbols that are not in the base root are those created with the ADD
command. The remainder are built-in (see ADD on page 2-18).
When an executable program is loaded, the debugger automatically creates a second
root for that program. The name of this root is the name of the program with an at sign
@ prepended to it. For example, when the debugger loads the proga program, it creates
the root @PROGA. An alternative root name can be specified with the LOAD command (see
LOAD on page 2-202).
If two programs have the same name, the debugger appends an underscore followed by
a number (that is, @NAME_1, @NAME_2) to the second (and any subsequent) program.
To specify which root a module belongs to, use @ROOT\\MODULE where ROOT is the root
name and MODULE is the module name. The \\ specifies that the preceding symbol is a
root name. Use \\ to specify the base root, which contains built-in type, macro, and
1-36
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
Working with the CLI
reserved word information. In the PRINTSYMBOLS command, the root can be specified
directly. The reserved symbol @ROOT points to the current root name. For more
information about debugger reserved symbols, see Reserved symbols on page 1-19.
Example 1-5 Using root names
ps \
ps/t \\
ps/m @sieve\\
ps/f
/*
/*
/*
/*
Shows
Shows
Shows
Shows
all symbols in current root */
types in base root */
all modules in root @sieve */
all roots */
The debugger considers the context to help determine the current root. If the context is
within a module, the root of that module is the current context. The use of a backslash
\ refers to the current root, as specified by the context.
1.8.4
Module names
Module names qualify symbolic references. The module name is usually the source
filename without the extension. If the extension is not one of .*c, .*cp, .*c++, .*cpp,
.cxx, or .ixx, then the extension is preserved and the dot (.) is replaced with an
underscore (_). This convention avoids a conflict with the C period operator (.), that
indicates a structure reference.
Therefore, module names are changed as follows:
•
SIEVE.C becomes SIEVE
•
SIEVE.H becomes SIEVE_H
•
PORT.ASG becomes PORT_ASG
You might have to use module names when referencing symbols, for example:
•
SIEVE\main
•
SIEVE_H\#4
•
PORT_ASG\x
All module names are converted to uppercase by the debugger. To avoid confusion, it is
recommended that function names are not all uppercase. If two or more modules have
the same name, the debugger appends an underscore followed by a number to the
second, and any subsequent, module (for example, PROGA_1, PROGA_2, and PROGA_3). To
see the current module and function that is in scope, use the CONTEXT command (see
CONTEXT on page 2-113).
See Printing reserved symbols on page 1-22 for details on how to print the current
module and functions names.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
1-37
Working with the CLI
1.8.5
Variable references
In C, using a variable in an expression can result in a value or an address:
•
a fully referenced variable results in a value
•
a partially referenced variable results in an address.
Some legal assembly language variables can conflict with C operators, such as dot (.)
and question mark (?). These characters are replaced with an underscore (_).
Examples of variable references are provided in Table 1-12, including an indication of
what type of reference is being made.
Table 1-12 Examples of references to variables
Variable reference
Reference type
int A;
A is fully referenced.
A = 5;
long temp;
temp is fully referenced.
temp = 9;
int arr[10], *LABEL;
arr is not fully referenced so its address is used.
LABEL = arr;
arr[3] is fully referenced.
arr[3] = 8;
int AB[10][10], *LABX;
AB is not fully referenced so its address is used.
LABX = AB[5];
LABX = LABEL;
LABEL is fully referenced so its value is used (the address it
points to).
char *p,c;
p is fully referenced. c is not fully referenced.
p = &c;
c = *LABEL;
1-38
LABEL is dereferenced so the value of its address is used.
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
Working with the CLI
When you refer to a variable in a C/C++ expression that is not fully referenced, you are
referring to the address of that variable, not the value. For this reason, the variable is
considered unreferenced. The normal C operators are implemented to modify
references, as shown in Table 1-13.
Table 1-13 C operators for referencing and dereferencing variables
Operator
Scalar
Pointer
Array
Structure
Union
*
-
Ref
Ref
-
-
&
Deref
Deref
-
Deref
Deref
->
-
Refa
-
-
-
.
-
-
-
Ref
Ref
[ ]
-
Ref
Ref
-
-
a. Must be a pointer to a structure or union. The right side must be a member of that structure or
union. Otherwise, it is illegal.
These operators let you reference, or get the value of, and dereference, or get the address
of, variables. The concept of referenced and dereferenced variables also applies to
breakpoints. For example:
BREAKACCESS arrayname
This command sets an access breakpoint at the start address of the array arrayname
because arrayname is not fully referenced.
The following form of the command sets a breakpoint at the value stored in
arrayname[3] and not the address of arrayname[3], because it is now fully referenced:
BREAKACCESS arrayname[3]
By including the special operator &, the following command enables you to set a
breakpoint at the address of the array element arrayname[3]:
BREAKACCESS &arrayname[3]
1.8.6
Stack references
When a function is invoked in C/C++, space is allocated on the stack for most local
variables. Typically, space is also allocated for a return address for returning to the
calling routine. If a function calls another function, all information is saved on the stack
to continue execution when the called function returns. The function is now nested.
You can reference variables and functions nested on the stack implicitly or explicitly.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
1-39
Working with the CLI
Implicit stack references
Within the debugger, you can implicitly reference variables on the stack as follows:
•
To refer to variables on the stack in the current function, specify the name of the
variable, for example x.
•
To refer to a local variable in a nested function, specify the function name
followed by a backslash and the name of the local variable (main\i for example).
If the nested function is recursive, the last occurrence of that function is used. An
explicit reference enables any occurrence to be selected.
Explicit stack references
A function is allocated storage for its variables on the stack when it is currently
executing. To refer to variables on the stack explicitly, you must specify the nesting level
of the function preceded by an at sign @. The Call Stack window in source-level mode
displays nesting level information. The current function is @0, its caller is @1.
You can reference functions on the stack as follows:
•
To refer to the address where some function on the stack returns, specify the
function nesting level preceded by an at sign @. For example, GO @1 executes the
program until the debugger reaches the address that corresponds to the location
where the current function returns to its caller (the instruction after the call). The
LIST and DISASSEMBLE commands can be used to show the code at the return
address (LI @2 for example).
In nonrecursive programs, the command GO @1 corresponds to setting a breakpoint
when the current function returns to its caller. In recursive programs, the address
alone might not be enough to specify the instance that you want. A command such
as [email protected]; until(depth == 4) can be used to specify the instance of the address that
you want (assuming depth is a local variable in your recursive function that
determines the instance you are executing).
1-40
•
To explicitly refer to a local variable in a nested function, specify the function
nesting level followed by a backslash and the name of the variable. For example,
PRINTVALUE @3\str references the local variable str of the function at nesting level
3.
•
To see all available information about a function, specify the EXPAND command
followed by the function nesting level. For example, EXPAND @7 displays all
information about the function at the specified level for that particular invocation.
This information includes the name of the function, the address that is returned
to, and all local variables in the function and their values.
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
Working with the CLI
1.9
Source patching with macros
When debugging your application program, sometimes errors can be temporarily
patched with source statements. It is often unnecessary to edit the source code, and
recompile and link. Instead, you can use a temporary patch by using macros with
breakpoints.
To insert a few lines of source code in your program:
1.
Define a macro containing the statements that you want to insert.
2.
Start a debugging session and set a breakpoint on the source line following the
point where you want to insert the new lines.
3.
Attach your macro to this breakpoint. See Chapter 2 RealView Debugger
Commands for details explaining how to do this using the breakpoint commands.
Alternatively, see the RealView Debugger v3.0 User Guide for details explaining
how to do this in the GUI.
4.
Run the program until execution stops at the breakpoint.
5.
The source statements in your macro are interpreted and executed. The macro
completes.
6.
Program execution continues normally.
Note
Using a macro in this way might cause problems with compiler optimizations, for
example the ordering of instructions might have been altered by the compiler.
You can also use a similar approach to jump over or skip lines of source code:
ARM DUI 0175H
1.
Define a macro to set the PC to a point beyond the lines that are not executed.
2.
Start a debugging session and set a breakpoint on the first line to be skipped.
3.
Attach your macro to this breakpoint.
4.
Run the program until execution stops at the breakpoint.
5.
The source statements in your macro are interpreted and executed. The macro
completes.
6.
Program execution continues normally from the new position of the PC.
Copyright © 2002-2006 ARM Limited. All rights reserved.
1-41
Working with the CLI
You can also use the JUMP command for looping and skipping over commands, shown
in the fragment in Example 1-6. The JUMP command takes a label and an expression. If
the expression evaluates to True then control jumps to the specified label. If the label is
positioned earlier in the file, this loops. If the label is positioned later in the file, all
intermediate commands are skipped.
The expression can test:
•
symbols, using the isalive() keyword (see isalive on page 4-12)
•
results
•
local symbols, created with ADD
•
file tests, using macros.
Example 1-6 Using the JUMP command
add int cnt = 20
initialize
:repeat
/* loop 20 times */
some_commands
jump repeat,cnt
/* repeat until cnt==0 */
;
; define some local vars if not defined.
;
jump nodefine,isalive(cnt)==1
some_commands
:nodefine
For more information on the ADD and JUMP commands, see ADD on page 2-18 and JUMP on
page 2-199.
1-42
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
Working with the CLI
1.9.1
Patching example to re-implement a loop
The source code being debugged contains the following lines:
24
25
26
27
28
29
30
31
32
count = 5;
for (i=0; i < MAXNUM; i++)
{
array[i]=1;
count=count+2;
k=count*i;
}
To jump over or skip lines 29 and 30, and to insert a new line temporarily, which
increments count by 1:
1.
Define a macro that contains statements to increment count and move the PC over
the two lines:
DEFINE patch_29()
{
count++;
/* increment count by 1 */
$SETREG @PC = #31$; /* reset program counter so skipping 29 & 30 */
return(1);
/* return 1 to continue normal execution */
}
.
ARM DUI 0175H
2.
Start a debugging session and set an instruction breakpoint on line 29. See
Execution control on page 2-4 for a list of the commands you can use to set
breakpoints. Alternatively, see the RealView Debugger v3.0 User Guide for
details on how to set breakpoints using the GUI interface.
3.
Attach your macro to this breakpoint.
4.
Run the program until execution stops at the breakpoint.
5.
The source statements in your macro are interpreted and executed. The macro
completes.
6.
Program execution continues normally.
Copyright © 2002-2006 ARM Limited. All rights reserved.
1-43
Working with the CLI
1.9.2
Patching example to emulate a serial port
To emulate a serial port in your source code:
1.
Define a macro that emulates a serial port:
add unsigned long last_time;
/* create local symbol */
define int ser_port(offset,base)
/* macro definition */
int offset;
/* offset of device register */
unsigned short *base;
/* base of port */
{
unsigned short value;
if (offset == 0)
{
/* control register */
if (last_time && @cycle-last_time < 20)
{
error (0, "ser_port: access less than
allowed time: %d", @cycle-last_time);
return (0);
}
last_time = @cycle;
value = base[offset]; /* cache written value */
base[offset] = 0;
/* reset */
if (value == 0x20)
{
/* want to read */
...
}
...
}
...
$SETREG @PC = #line_num$; /* reset PC to skip the patched lines */
}
.
2.
Start a debugging session and set a breakpoint on the source code to stop
execution immediately before it accesses the serial port, for example at line 20 of
module_name.c, and attach your macro to this breakpoint:
BREAKINSTRUCTION \MODULE_NAME\#20 ;ser_port(0,&ser_port)
3.
Continue debugging using the newly-inserted serial port emulation.
As with the previous example, this is only a temporary patch so the source code must
be edited and then recompiled. Be careful, however, when using such a patch in
optimized code.
1-44
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
Working with the CLI
1.9.3
Other ways to use macros
This section describes other ways that you can use macros. It includes:
•
Using macros to interact with files and windows
•
Using macros with commands on page 1-46
•
Sending debug information to the Output pane on page 1-47
•
Interacting with a user on page 1-47.
Using macros to interact with files and windows
During your debugging session, you can use macros to read from or write to a file, or to
write to a window. The macros to do this are listed in Table 1-14.
Table 1-14 Macros for interacting with files and windows
ARM DUI 0175H
Macro
Acts on
See
fclose()
Files
fclose on page 3-11
fopen()
Files
fopen on page 3-15
fgetc()
Files
fgetc on page 3-12
fputc()
Files
fputc on page 3-17
fread()
Files
fread on page 3-19
fwrite()
Files and
windows
fwrite on page 3-21
Copyright © 2002-2006 ARM Limited. All rights reserved.
1-45
Working with the CLI
Using macros with commands
You can use macros with the commands listed in Table 1-15. For these commands, the
macro is executed automatically when an event occurs, such as the activation of a
breakpoint. The return value from the macro can also determine the subsequent
execution (for example, see the macro_call argument to BREAKINSTRUCTION on
page 2-67).
Table 1-15 Commands that run macros automatically
Command
See
BGLOBAL
BGLOBAL on page 2-36
BREAKACCESS
BREAKACCESS on page 2-45
BREAKEXECUTION
BREAKEXECUTION on page 2-56
BREAKINSTRUCTION
BREAKINSTRUCTION on page 2-67
BREAKREAD
BREAKREAD on page 2-74
BREAKWRITE
BREAKWRITE on page 2-85
GO
GO on page 2-186
GOSTEP
GOSTEP on page 2-188
Table 1-16 lists the commands that you can use to manage macros.
Table 1-16 Commands that enable you to manage macros
1-46
Command
See
CEXPRESSION
CEXPRESSION on page 2-101
DEFINE
DEFINE on page 2-121
DELETE
DELETE on page 2-125
MACRO
MACRO on page 2-208
SHOW
SHOW on page 2-284
VMACRO
VMACRO on page 2-365
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
Working with the CLI
Sending debug information to the Output pane
You can send debugging information to the Output pane in the GUI with the error()
predefined macro (see error on page 3-9).
Interacting with a user
A number of macros are provided that enable a user to interact with your script and then
continue execution based on the decision, or data, entered. See the following sections:
•
prompt_file on page 3-32
•
prompt_list on page 3-34
•
prompt_text on page 3-36
•
prompt_yesno on page 3-38
•
prompt_yesno_cancel on page 3-40.
You can also use these predefined macros with other macros and include files. If using
these predefined macros with the MACRO command (see MACRO on page 2-208) in include
files, use the JUMP command (see JUMP on page 2-199) to implement the user’s decision.
The following example shows how you can use these predefined macros with the MACRO
command:
Example 1-7 Using the prompt macros with JUMP
add int val
add char buff[15]
strcpy(buff, "one\ntwo\nthree")
// Implement user’s choice
define /R void choice(option)
int option;
{
if (choice > 0) {
if (choice == 1)
$printf "Item one selected.\n"$;
else if (choice == 2)
$printf "Item two selected.\n"$;
else
$printf "Item three selected.\n"$;
}
}
.
// Choose an option
:repeat
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
1-47
Working with the CLI
macro val = prompt_list("Choose one:", buff)
choice(val)
jump repeat, val>0
// Repeat until user clicks Cancel
1-48
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
Chapter 2
RealView Debugger Commands
This chapter describes available RealView® Debugger commands. It contains the
following sections:
•
Command syntax definition on page 2-2
•
Debugger commands listed by function on page 2-3
•
Alphabetical command reference on page 2-13.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-1
RealView Debugger Commands
2.1
Command syntax definition
Many commands have alternative names, or aliases, that you might find easier to
remember. Command names and aliases can be abbreviated. For example, ADDBOARD can
be abbreviated to ADDBO. The syntax definition for each command shows how it can be
shortened by underlining the abbreviation, that is ADDBOARD.
In the syntax definition of each command:
•
square brackets [...] enclose optional parameters
•
words enclosed in braces {} separated by a vertical bar | indicate alternatives from
which you choose one
•
parameters that can be repeated are followed by an ellipsis ....
Do not type square brackets, braces, or the vertical bar. Replace parameters in italics
with the value you want. When you supply more than one parameter, use a comma or a
space or a semicolon as a separator, as shown in the syntax definition for the command.
If a parameter is a name that includes spaces, enclose it in double quotation marks.
2.1.1
Specifying address ranges
Many commands enable you to specify a range of addresses. You specify an address
range using either of the following formats:
start_addr..end_addr
Start address and an absolute end address, for example:
memmap,define 0x10000..0x20000
start_addr..+length
Start address and length of the address region, for example:
memmap,define 0x10000..+0x10000
In both cases, the start and end values are inclusive.
You can also use symbol names such as macros, function names, and variables as the
start address:
printdsm mymacro()..+1000
printdsm main..+1000
fill Arr_2_Glob..+64=0xFF
2-2
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.2
Debugger commands listed by function
This section lists the commands according to their general function:
•
Board file access
•
Execution control on page 2-4
•
Examining source files on page 2-5
•
Program image management on page 2-5
•
Target registers and memory on page 2-6
•
Status enquiries on page 2-7
•
Macros and aliases on page 2-8
•
CLI on page 2-8
•
Program symbol manipulation on page 2-9
•
Creating and writing to files and windows on page 2-9
•
Processor tracing on page 2-10
•
OS-aware debugging on page 2-11
•
Miscellaneous on page 2-12.
This section does not include command aliases. See Alphabetical command reference
on page 2-13 for a full, alphabetical list of commands.
2.2.1
Board file access
Table 2-1 shows the commands that operate on boards, that is target processors,
development systems and their subcomponents.
Table 2-1 Board file access commands
ARM DUI 0175H
Description
Command
Select a particular target definition
BOARD on page 2-41
Connect the debugger to a target
CONNECT on page 2-108
Remove target definition
DELBOARD on page 2-124
Disconnect the debugger from a target
DISCONNECT on page 2-136
List board descriptions
DTBOARD on page 2-146
Write board memory map as linker file
DUMPMAP on page 2-155
Edit current board definition
EDITBOARDFILE on page 2-158
Read, or reread, a board file
READBOARDFILE on page 2-252
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-3
RealView Debugger Commands
2.2.2
Execution control
Table 2-2 shows the commands that control target execution, including instruction and
data breakpoints.
Table 2-2 Execution control commands
Description
Command
Initialize or reset the processor
EMURESET on page 2-160
RELOAD on page 2-257
RESET on page 2-259
RESTART on page 2-263
Start executing from current state
GO on page 2-186
RUN on page 2-266
Set a data or instruction breakpoint
BREAKACCESS on page 2-45
BREAKEXECUTION on page 2-56
BREAKINSTRUCTION on page 2-67
BREAKREAD on page 2-74
BREAKWRITE on page 2-85
Clear, enable or disable a breakpoint
CLEARBREAK on page 2-104
DISABLEBREAK on page 2-131
ENABLEBREAK on page 2-162
RESETBREAKS on page 2-261
Stop execution at current point
HALT on page 2-190
STOP on page 2-301
Set or change processor exceptions
BGLOBAL on page 2-36
Step by instruction
STEPINSTR on page 2-291
STEPOINSTR on page 2-296
Step by source line
STEPLINE on page 2-293
STEPO on page 2-298
Step invoking a macro at each step
GOSTEP on page 2-188
Synchronize execution
SYNCHEXEC on page 2-303
XTRIGGER on page 2-379
Do something when execution starts or stops
2-4
ONSTATE on page 2-222
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.2.3
Examining source files
Table 2-3 shows the commands that let you examine the program source files.
Table 2-3 Examining source file commands
Description
Command
Display a specific source file
LIST on page 2-200
Display execution context
CONTEXT on page 2-113
DOWN on page 2-143
UP on page 2-359
WHERE on page 2-373
2.2.4
Display locals of an execution context
EXPAND on page 2-169
Select source or assembly display
MODE on page 2-216
Move the display location within program
SCOPE on page 2-268
Display program source files
DTFILE on page 2-149
Program image management
Table 2-4 shows the commands that manipulate image (executable) files.
Table 2-4 Program image management commands
Description
Command
Reload or restart current executable
RELOAD on page 2-257
RESTART on page 2-263
ARM DUI 0175H
Add or remove executable file from loaded
files list
ADDFILE on page 2-21
Load target with one or more executable
files
LOAD on page 2-202
Unload an executable file or process
UNLOAD on page 2-357
Write to FLASH memory
FLASH on page 2-176
Translate host filesystem pathnames
(These commands are deprecated.)
NAMETRANSLATE on page 2-219
Define program (argc, argv)
ARGUMENTS on page 2-32
DELFILE on page 2-127
RELOAD on page 2-257
PATHTRANSLATE on page 2-233
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-5
RealView Debugger Commands
Table 2-4 Program image management commands (continued)
2.2.5
Description
Command
Define run mode
RUN on page 2-266
Disassemble target memory
DISASSEMBLE on page 2-133
Print disassembled target memory
PRINTDSM on page 2-236
Verify data or image file against memory
VERIFYFILE on page 2-362
Display more information about load errors
DLOADERR on page 2-139
Do something when execution starts or stops
ONSTATE on page 2-222
Target registers and memory
Table 2-5 shows the commands that manipulate target registers and memory.
Table 2-5 Target register and memory access commands
Description
Command
Enable and change target memory layout
MEMMAP on page 2-210
Fill target memory with value or values
FILL on page 2-173
SETMEM on page 2-273
CEXPRESSION on page 2-101
Copy or compare target memory areas
COPY on page 2-115
COMPARE on page 2-106
Change target registers
SETREG on page 2-275
Display memory in window
MEMWINDOW on page 2-214
LIST on page 2-200
2-6
Disassemble target memory
DISASSEMBLE on page 2-133
Search for value or values in memory
SEARCH on page 2-270
Write to FLASH memory
FLASH on page 2-176
Write memory map to linker file
DUMPMAP on page 2-155
Write host file into target memory
READFILE on page 2-253
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
Table 2-5 Target register and memory access commands (continued)
Description
Command
Write target memory to screen
DUMP on page 2-153
Write target memory to host file
WRITEFILE on page 2-376
Compare host file with target memory
TEST on page 2-305
VERIFYFILE on page 2-362
2.2.6
Status enquiries
Table 2-6 shows the commands that display information about the current debugger
session.
Table 2-6 Status enquiry commands
Description
Command
Display current image file information
DTFILE on page 2-149
Display more information about load errors
DLOADERR on page 2-139
Display execution context
CONTEXT on page 2-113
WHERE on page 2-373
Display currently set breakpoints and
tracepoints
DTBREAK on page 2-147
Display trace status
DTRACE on page 2-151
Display board descriptions
DTBOARD on page 2-146
Display the contents of a macro
SHOW on page 2-284
Display simulator instruction pipeline
DPIPEVIEW on page 2-145
Display and define user preferences
OPTION on page 2-224
SETTINGS on page 2-279
Displays RVISS bus and processor cycles.
ARM DUI 0175H
STATS on page 2-286
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-7
RealView Debugger Commands
2.2.7
Macros and aliases
Table 2-7 shows the commands that define and display command aliases and macros.
More information about macros can be found in Chapter 1 Working with the CLI and
also in the RealView Debugger v3.0 User Guide.
Table 2-7 Macro and alias commands
2.2.8
Description
Command
Define a command macro
DEFINE on page 2-121
Invoke a command macro
MACRO on page 2-208
Step invoking a macro at each step
GOSTEP on page 2-188
Define, list, delete command alias
ALIAS on page 2-23
Attach macro to window with auto-update
VMACRO on page 2-365
Display the contents of a macro
SHOW on page 2-284
CLI
Table 2-8 shows the functions that manipulate the command line itself.
Table 2-8 CLI commands
Description
Command
Run script file
INCLUDE on page 2-194
Define error action for script file
ERROR on page 2-164
Cause an abnormal error for script file
FAILINC on page 2-172
Interrupt current asynchronous command
CANCEL on page 2-99
INTRPT on page 2-196
Jump (go to) another point in the script
JUMP on page 2-199
Log CLI actions to file
JOURNAL on page 2-197
LOG on page 2-206
Log STDIO messages to a file
2-8
STDIOLOG on page 2-289
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.2.9
Program symbol manipulation
Table 2-9 shows the commands that display and change symbols the debugger symbol
table.
Table 2-9 Program symbol manipulation commands
Description
Command
Create symbols referencing target memory
ADD on page 2-18
Create host-debugger symbols
ADD on page 2-18
Delete symbols
DELETE on page 2-125
Browse C++ class structure
BROWSE on page 2-97
Load only the symbols for a program
LOAD on page 2-202
Display symbols in the symbol table
PRINTSYMBOLS on page 2-242
Display variable type details
PRINTTYPE on page 2-245
Evaluate expressions involving symbols
CEXPRESSION on page 2-101
PRINTVALUE on page 2-247
Display value of symbol every time
debugger stops target
2.2.10
MONITOR on page 2-217
NOMONITOR on page 2-221
Creating and writing to files and windows
Table 2-10 shows the commands that manipulate windows.
Table 2-10 Creating files and text writing commands
ARM DUI 0175H
Description
Command
Opening a file
FOPEN on page 2-179
Creating a new window
VOPEN on page 2-367
Clearing a window
VCLEAR on page 2-360
Setting the cursor position within a window
VSETC on page 2-369
Deleting a window
VCLOSE on page 2-361
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-9
RealView Debugger Commands
Table 2-10 Creating files and text writing commands (continued)
Description
Command
Attaching a macro to a window
VMACRO on page 2-365
Display list of open files and windows
WINDOW on page 2-375
Writing text to a file or window
FPRINTF on page 2-182
PRINTF on page 2-238
Commands that support the ;windowid or
;fileid parameter.
2.2.11
Processor tracing
Table 2-11 shows the processor instruction tracing functions.
Table 2-11 Processor tracing commands
Description
Command
Enable and disable tracing
TRACE on page 2-309
Configure the trace capture logic
ANALYZER on page 2-26
ETM_CONFIG on page 2-165
Display status information
DTRACE on page 2-151
Set tracepoints in the program
TRACE on page 2-309
TRACEDATAACCESS on page 2-323
TRACEDATAREAD on page 2-329
TRACEDATAWRITE on page 2-335
TRACEEXTCOND on page 2-341
TRACEINSTREXEC on page 2-346
TRACEINSTRFETCH on page 2-352
Displaying, saving, and loading captured
trace information
2-10
TRACEBUFFER on page 2-312
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.2.12
OS-aware debugging
Table 2-12 shows the commands that are specific to OS-aware connections.
Table 2-12 OS-aware specific debugging commands
Description
Command
Control OS-aware debugging
OSCTRL on page 2-230
OS-aware action commands
AOS_resource-list on page 2-30
OS-aware resource commands
DOS_resource-list on page 2-141
Select thread in OS-aware thread group
THREAD on page 2-307
Table 2-13 shows those commands that provide arguments or have specific behavior for
OS-aware connections.
Table 2-13 Debugging commands with OS-aware related features
Description
Command
Set an instruction breakpoint for a specific
thread
BREAKINSTRUCTION on page 2-67
Stop execution
HALT on page 2-190
STOP on page 2-301
Reset processor and cleanup thread states
and other OS issues
RESET on page 2-259
Other commands can be used with OS-aware connections, such as those for stepping,
accessing memory and registers, and setting hardware breakpoints.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-11
RealView Debugger Commands
2.2.13
Miscellaneous
Table 2-14 shows the remaining functions.
Table 2-14 Miscellaneous commands
Description
Command
Open and close the Connection Control
window
CCTRL on page 2-100
Get help on command
HELP on page 2-191
DHELP on page 2-130
DCOMMANDS on page 2-118
Run a command on the host operating
system
HOST on page 2-192
Define user preferences
OPTION on page 2-224
SETTINGS on page 2-279
2-12
Force debugger to wait for a specified
number of seconds
PAUSE on page 2-235
Force debugger to wait, or not to wait, for
command to complete
WAIT on page 2-370
Quit debugger
QUIT on page 2-251
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3
Alphabetical command reference
This section lists in alphabetical order all the commands that you can issue to RealView
Debugger using the CLI. It also lists all aliases and includes cross references, where
appropriate.
The following sections describe the available commands:
•
ADD on page 2-18
•
ADDFILE on page 2-21
•
ALIAS on page 2-23
•
ANALYZER on page 2-26
•
AOS_resource-list on page 2-30
•
ARGUMENTS on page 2-32
•
BACCESS on page 2-35
•
BEXECUTION on page 2-35
•
BGLOBAL on page 2-36
•
BINSTRUCTION on page 2-40
•
BOARD on page 2-41
•
BREAD on page 2-44
•
BREAK on page 2-44
•
BREAKACCESS on page 2-45
•
BREAKEXECUTION on page 2-56
•
BREAKINSTRUCTION on page 2-67
•
BREAKREAD on page 2-74
•
BREAKWRITE on page 2-85
•
BROWSE on page 2-97
•
BWRITE on page 2-98
•
CANCEL on page 2-99
•
CCTRL on page 2-100
•
CEXPRESSION on page 2-101
•
CLEARBREAK on page 2-104
•
COMPARE on page 2-106
•
CONNECT on page 2-108
•
CONTEXT on page 2-113
•
COPY on page 2-115
•
DBOARD on page 2-117
•
DBREAK on page 2-117
•
DCOMMANDS on page 2-118
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-13
RealView Debugger Commands
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
2-14
DEFINE on page 2-121
DELBOARD on page 2-124
DELETE on page 2-125
DELFILE on page 2-127
DHELP on page 2-130
DISABLEBREAK on page 2-131
DISASSEMBLE on page 2-133
DISCONNECT on page 2-136
DLOADERR on page 2-139
DMAP on page 2-140
DOS_resource-list on page 2-141
DOWN on page 2-143
DPIPEVIEW on page 2-145
DTBOARD on page 2-146
DTBREAK on page 2-147
DTFILE on page 2-149
DTRACE on page 2-151
DUMP on page 2-153
DUMPMAP on page 2-155
DVFILE on page 2-157
EDITBOARDFILE on page 2-158
EMURESET on page 2-160
EMURST on page 2-161
ENABLEBREAK on page 2-162
ERROR on page 2-164
ETM_CONFIG on page 2-165
EXPAND on page 2-169
FAILINC on page 2-172
FILL on page 2-173
FLASH on page 2-176
FOPEN on page 2-179
FPRINTF on page 2-182
GO on page 2-186
GOSTEP on page 2-188
HALT on page 2-190
HELP on page 2-191
HOST on page 2-192
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
ARM DUI 0175H
HWRESET on page 2-193
INCLUDE on page 2-194
INTRPT on page 2-196
JOURNAL on page 2-197
JUMP on page 2-199
LIST on page 2-200
LOAD on page 2-202
LOG on page 2-206
MACRO on page 2-208
MEMMAP on page 2-210
MEMWINDOW on page 2-214
MMAP on page 2-215
MODE on page 2-216
MONITOR on page 2-217
NAMETRANSLATE on page 2-219
NOMONITOR on page 2-221
ONSTATE on page 2-222
OPTION on page 2-224
OS action commands on page 2-228
OS resource commands on page 2-229
OSCTRL on page 2-230
PATHTRANSLATE on page 2-233
PAUSE on page 2-235
PRINTDSM on page 2-236
PRINTF on page 2-238
PRINTSYMBOLS on page 2-242
PRINTTYPE on page 2-245
PRINTVALUE on page 2-247
PROPERTIES on page 2-250
PS on page 2-250
PT on page 2-250
QUIT on page 2-251
READBOARDFILE on page 2-252
READFILE on page 2-253
REEXEC on page 2-256
RELOAD on page 2-257
RESET on page 2-259
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-15
RealView Debugger Commands
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
2-16
RESETBREAKS on page 2-261
RESTART on page 2-263
RSTBREAKS on page 2-265
RUN on page 2-266
SCOPE on page 2-268
SEARCH on page 2-270
SETFLAGS on page 2-272
SETMEM on page 2-273
SETREG on page 2-275
SETTINGS on page 2-279
SHOW on page 2-284
SINSTR on page 2-285
SM on page 2-285
SOINSTR on page 2-285
SOVERLINE on page 2-285
SR on page 2-285
STATS on page 2-286
STDIOLOG on page 2-289
STEPINSTR on page 2-291
STEPLINE on page 2-293
STEPOINSTR on page 2-296
STEPO on page 2-298
STOP on page 2-301
SYNCHEXEC on page 2-303
TEST on page 2-305
THREAD on page 2-307
TRACE on page 2-309
TRACEBUFFER on page 2-312
TRACEDATAACCESS on page 2-323
TRACEDATAREAD on page 2-329
TRACEDATAWRITE on page 2-335
TRACEEXTCOND on page 2-341
TRACEINSTREXEC on page 2-346
TRACEINSTRFETCH on page 2-352
UNLOAD on page 2-357
UP on page 2-359
VCLEAR on page 2-360
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
•
•
•
•
•
•
•
•
•
•
•
ARM DUI 0175H
VCLOSE on page 2-361
VERIFYFILE on page 2-362
VMACRO on page 2-365
VOPEN on page 2-367
VSETC on page 2-369
WAIT on page 2-370
WARMSTART on page 2-372
WHERE on page 2-373
WINDOW on page 2-375
WRITEFILE on page 2-376
XTRIGGER on page 2-379.
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-17
RealView Debugger Commands
2.3.1
ADD
The ADD command creates a symbol and adds it to the debugger symbol table.
Syntax
ADD [type] symbol_name [&address] [=value [,value]...]
where:
One of the following data types:
type
int
The symbol represents a location holding a four byte signed
integer value. This is the default type of symbols.
char
The symbol represents a location holding a one byte value.
short
The symbol represents a location holding a two byte value.
long
The symbol represents a location holding a four byte value.
long long The symbol represents a location holding an 8-byte value.
You can use these types together with * and [] to indicate pointer and
array variables, using the C language syntax.
You can also create symbols with type float or double, but you cannot
initialize them with a value in the ADD statement.
You can create references to existing instances of the following types:
struct
The symbol is an instance of, or a pointer to, a C structure.
enum
The symbol is an instance of, or a pointer to, a C enumeration.
union
The symbol is an instance of, or a pointer to, a C union.
You cannot create new enumerations, structures, or unions. You cannot
initialize complete structures at once, although you can individually
assign values to the members with CEXPRESSION.
If the symbol is an array, then the array size must be specified after to the
symbol name within in square brackets. You can define multidimensional
arrays by appending several bracketed array dimensions.
2-18
symbol_name
Is the name of the symbol being added. The name must start with an
alphabetic character or an underscore, optionally followed by alphabetic
or numeric characters or underscores. The symbol name must not already
exist (when appropriate, use DELETE on page 2-125 to remove a symbol).
address
Is the address in target memory that is referred to by this debugger
symbol. If you do not specify an address, the new debugger symbol refers
to a location in debugger memory, and is not available to code running on
the target.
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
Is the initial value of the added symbol. You can use:
value
•
integer values corresponding to the C types int, char, short, long or
long long
•
pointers to integers in target memory
•
strings in double quotes, matching the character array type, char[n],
but not char *
•
a list of values separated by a comma.
If the symbol type is a pointer, an assigned value must be the address of
the value on the target.
You can initialize array symbols using multiple value arguments. For
example:
add char names[3][2] ="aa", "bb"
print names[1]
"bb...
The ... after bb indicates that there is no terminating NUL for the string, in
this case because each element of the array is only 2 characters in size.
The value is loaded into the memory location referred to by the symbol.
If value is not specified, the symbol is set to zero in debugger memory but
is not given a value in target memory.
Floating-point values are not recognized.
Description
The ADD command adds a symbol to the debugger symbol table for the current
connection. You cannot add a symbol without a connection, but you do not have to have
loaded an executable image file. The symbol survives an executable image being
reloaded (File → Reload Image to Target) but is destroyed if the target is disconnected
and then reconnected or another, different, image is loaded.
You can remove a symbol defined using ADD by using the DELETE command, and you can
modify its value using CEXPRESSION.
Rules
The following rules apply to the use of the ADD command:
ARM DUI 0175H
•
ADD runs asynchronously unless in a macro.
•
The specified symbol must not exist at the time it is added.
•
To change the symbol type, delete the symbol and then add it again.
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-19
RealView Debugger Commands
•
When initializing symbols, the size of the symbol is used, not the size of the type
of value supplied. In particular, the size of a char array is not determined by the
string used to initialize it.
•
If a char array is created, for example using ADD char namearray[n], it is filled with
the initial value.
•
If there is a runtime error in the initial value, the symbol is still created. You can
then assign the correct value with the CEXPRESSION command, or you can delete the
symbol and add it again with a legal initial value.
Examples
The following examples show how to use ADD:
add mysymbol =3
Adds a new symbol called mysymbol of type int to the debugger
symbol table.
add char *xyz
Adds a new symbol called xyz to the debugger symbol table. The
new symbol is of character pointer type and has an initial value of
zero.
See also
The following commands provide similar or related functionality:
•
CEXPRESSION on page 2-101
•
DELETE on page 2-125.
2-20
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.2
ADDFILE
The ADDFILE command adds the named file to the executable image file list but does not
load it. You can optionally empty the list before adding the new filename.
Syntax
ADDFILE [,auto] =filename [=string,...]
where:
auto
Specifies that only one added file is permitted for each process or
processor. Any previously added file is removed when the specified file
is added.
filename
The name of the file to be added. You must use double quotes around the
filename if it contains any spaces.
You can include one of more environment variables in the filename. For
example, if MYPATH defines the location C:\Myimages, you can specify:
adsfile ="$MYPATH\\myimage.axf"
string
The target pathname, for example, an OS loader.
Description
The RealView Debugger executable file list contains the names of the files containing
the target code for your application. Normally this contains a single linker output file,
for example dhry.axf and, in this case, you use the LOAD and RELOAD commands as
required.
However, when the application is more complex it is sometimes easier to create it as
several files, for example one file for the Operating System (OS) and one for each major
process. In these cases, you use the ADDFILE and RELOAD, or the ADDFILE and LOAD/A
commands, to manipulate the files that are loaded onto the target.
To load the files on the file list use RELOAD, described on page 2-257.
Examples
The following example removes any existing files from the executable file list and loads
dhry.axf into it. The reload command then transfers the executable contents of dhry.axf
to the target and sets the processor PC to the image entry point:
addfile,auto =c:\source\debug\dhry.axf
reload
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-21
RealView Debugger Commands
This is the same as:
load c:\source\debug\dhry.axf
This example loads the file dhry.axf into the file list, removing any existing files. It then
adds the file kernel.axf to the file list. The reload command transfers the executable
contents of both files to the target and sets the PC to the entry address of the last
executable loaded, in this case that of kernel.axf.
addfile,auto =c:\source\dhry\debug\dhry.axf
addfile =c:\source\OS\debug\kernel.axf
reload
See also
The following commands provide similar or related functionality:
•
DELFILE on page 2-127
•
DTFILE on page 2-149
•
LOAD on page 2-202
•
RELOAD on page 2-257
•
UNLOAD on page 2-357.
2-22
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.3
ALIAS
The ALIAS command is used to manipulate command aliases. Aliases are new debugger
commands constructed from (optionally, parts of) existing debugger commands or
macros.
Syntax
ALIAS [alias_name [=[definition]]]
where:
alias_name
Names your new debugger command. This name is accepted as a legal
debugger command name.
An optional asterisk * embedded in the name indicates that the parts of
the name that follow are not required, so your command can be
abbreviated.
definition
Defines the replacement string that is substituted in place of alias_name
whenever alias_name is invoked.
The definition normally contains macro invocations or debugger internal
commands, or parts of such commands. However, any string of legal
debugger characters is accepted.
Using $* within a definition inserts the command-line parameters to the
alias in the expansion. By default, parameters are appended to the alias
when command expansion occurs.
Description
The ALIAS command can create, list, or delete new debugger commands. The building
blocks are existing debugger commands and macros and, optionally, specific
parameters. You can use ALIAS to define either:
•
a new name (for example, one that is shorter or easier to remember) for an existing
command
•
a command that defines fixed parameters for an existing command.
ALIAS can only substitute one command for another. If you require a multiple command
alias, use the MACRO command instead.
Enter ALIAS without parameters to display a list of the defined alias commands in the
order in which they were added.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-23
RealView Debugger Commands
You can name your alias using almost any sequence of letters or numbers. However,
when a command is entered the debugger searches for internal debugger commands
before it searches for aliases. Therefore, you must ensure that you do not use an alias
name that is the same as an internal debugger command. The name priorities are as
follows:
1.
Debugger internal command, or defined abbreviation of command
2.
Defined alias names, and the defined abbreviations of alias names
3.
Macro names.
You can place alias command arguments in a specific position in the expanded debugger
command by inserting the sequence $* where the parameters to the command alias must
appear.
Rules
The following rules apply to the use of the ALIAS command:
•
ALIAS runs asynchronously unless it is called within a macro.
•
alias_name must not exist at the time it is added. To change the definition of an
alias, first define the alias equal to the nothing (alias nm=) to delete it and then
add it again.
•
If a debugger command has the same name as an alias, the debugger command is
the one that is executed.
•
Alias names are always matched before macros names.
•
If two alias abbreviations or an alias and an abbreviation match, the first alias
added during the current session is always used.
•
An alias definition must be defined in terms of predefined debugger commands
or macro names.
•
An alias definition can reference debugger commands and macros.
Examples
The following examples show how to use ALIAS:
alias showf*ile =dtfile ;99
Defines a command called SHOWFILE that can be abbreviated to SHOWF, that
is equivalent to the DTFILE command with its output directed to window
number 99.
2-24
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
alias dub =dump /b
Defines a command called DUB, with no abbreviation, that expands to the
DUMP command in byte mode (/b).
dub 0x20
Calls the alias dub to print out memory in bytes from address 0x20. This
alias invocation is exactly the same as typing:
dump /b 0x20
alias bpc =breakexecution,continue,message:{Break} $* ;DoCheck()
Defines a command called BPC, with no abbreviation, that expands to the
breakexecution command with specific parameters and trigger macro
DoCheck(). It must be invoked with the address to break at as a parameter:
bpc \MAIN_C\#15
This is equivalent to typing the command:
breakexecution,continue,message:{Break} \MAIN_C\#15 ;DoCheck()
See also
The following commands provide similar or related functionality:
•
BREAKEXECUTION on page 2-560
•
DEFINE on page 2-121
•
DTFILE on page 2-149
•
MACRO on page 2-208.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-25
RealView Debugger Commands
2.3.4
ANALYZER
The ANALYZER command controls the configuration of the trace logic analyzer.
Syntax
ANALYZER {[,disable]|[,enable]}
ANALYZER
{[edit_properties]|[,map_log_phys]|[,triggers]|[,connect]|[,set_size]}
ANALYZER {[,clear]|[,clear_triggers]}
ANALYZER
{[,before]|[,around]|[,after]|[,stop_on_trigger]|[,continue_on_trigger]}
ANALYZER {,full_stop|,full_ignore|,full_ring}
ANALYZER {,collect_all|,collect_flow}
ANALYZER {,dataonly|,addronly|,fulltrace}
ANALYZER {,disconnect}
ANALYZER {,auto_off|,auto_instronly|,auto_dataonly|,auto_both}
ANALYZER {,mode_continuous|,mode_trigger}
where:
disable
Disable tracing.
enable
Enable tracing.
edit_properties
When connecting to a target device other than an ARM® processor
with Embedded Trace Macrocell™ (ETM), this is the equivalent of
the Edit → Configure Analyzer Properties... option on the
Analysis window main menu. (Deprecated)
Note
To configure an ETM use ETM_CONFIG.
2-26
map_log_phys
The equivalent of the Edit → Physical to Logical Address
Mapping... option on the Analysis window main menu. Not
available with an ARM ETM-enabled processor.
triggers
The equivalent of the Edit → Set/Edit Event Triggers option on
the Analysis window main menu. Not available with an ARM
ETM-enabled processor.
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
connect
The equivalent of the Edit → Connect Analyzer option on the
Analysis window main menu. Not available with an ARM
ETM-enabled processor because an ARM ETM is automatically
connected.
set_size=(n)
Enables you to set the trace buffer size.The equivalent of the
Edit → Set Trace Buffer Size... option on the Analysis window
main menu. If the value is specified in the command it is used,
otherwise display the Set Trace Buffer Size dialog and set the
value from that.
clear
Clear the captured trace buffer.
clear_triggers
Clear any triggers set using an ANALYZER,triggers command. Not
available with an ARM ETM-enabled processor.
before
Capture data before the trigger, that is, 100% before, 0% after.
around
Capture data around the trigger, that is, 50% before, 50% after.
after
Capture data after the trigger, that is, 0% before, 100% after.
stop_on_trigger
Stop the processor when a trigger point is reached. This option is
only applicable to the ARM ETM.
continue_on_trigger
Continue program execution across trigger points. This option is
only applicable to the ARM ETM.
ARM DUI 0175H
full_stop
Stop the processor and put it into debug state when the trace buffer
is full. Not available with an ARM ETM-enabled processor.
full_ignore
Stop collecting trace information when the trace buffer is full, but
let the processor continue running. Not available with an ARM
ETM-enabled processor.
full_ring
Continue collecting trace information when the trace buffer fills
by discarding the oldest trace information, treating the buffer as a
ring. This is the only option available for the ARM ETM.
collect_all
Store all trace the information generated. Not available with an
ARM ETM-enabled processor.
collect_flow
Store only flow-control trace information. Cannot be changed for
an ARM ETM-enabled processor because normal ETM operation
is a variant of this that includes some additional synchronization
points.
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-27
RealView Debugger Commands
dataonly
Trace only data bus transfers.
addronly
Trace only address bus transfers.
fulltrace
Trace both data and address bus transfers.
disconnect
Disconnects the Analysis window.
auto_off
Disables automatic tracing.
auto_instronly
When no tracepoints are set, captures trace information only for
executed instructions.
auto_dataonly
When no tracepoints are set, captures trace information only for
data accesses. This is supported only by ETM v3.
auto_both
When no tracepoints are set, captures trace information for both
executed instructions and data accesses.
Description
The ANALYZER command, and the ETM_CONFIG command, enables you to control the
configuration of your trace capture analyzer.
Note
Because trace analyzer capabilities and implementations vary, some of the qualifiers
provided by the ANALYZER command are not available on some of the trace targets
supported by RealView Debugger. Operation of the ARM ETM is controlled in more
depth with the ETM_CONFIG command.
For more information analysis and tracing, see the Embedded Trace Macrocell
Specification and the chapter that describes tracing in the RealView Debugger v3.0
Trace User Guide.
The options are split into several groups:
•
Options config, edit_properties, map_log_phys, triggers, and set_size display a
GUI dialog that enables you to configure the associated trace component.
Note
These options are not available when running in command line mode.
•
2-28
The clear option acts on the trace capture buffer. See also the TRACEBUFFER
command.
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
•
Options before, around, after, clear_triggers, stop_on_trigger, and
continue_on_trigger enable you to control the relative location of the trace trigger
within the trace buffer and the effect of the trigger. See the TRACE, TRACEINSTREXEC,
TRACEDATAACCESS and similar commands for control of tracepoint location in target
memory.
•
Options full_stop, full_ignore, and full_ring enable control over the behavior
of the trace buffer when it becomes full.
•
Options collect_all and collect_flow enable control of the trace data collection
strategy. Collecting all bus transactions provides the benefit of following
everything that is happening without recourse to external information, but
conversely requires a very high bandwidth trace port. Collecting only bus
transactions that change the flow of control provides most of the important
information if you also have access to an accurate memory image.
Examples
The following examples show how to use ANALYZER:
ANALYZER,set_size=500
Set the trace buffer size to 500 records, if this action is supported
by the logic analyzer you are using.
ANALYZER,full_ring,around
Set the logic analyzer to capture trace information around the
defined trigger point, using the trace buffer in ring mode so that it
cannot overflow.
See also
The following commands provide similar or related functionality:
•
DTBREAK on page 2-147
•
DTRACE on page 2-151
•
ETM_CONFIG on page 2-165
•
TRACE on page 2-309
•
TRACEBUFFER on page 2-312
•
TRACEDATAACCESS on page 2-323
•
TRACEDATAREAD on page 2-329
•
TRACEDATAWRITE on page 2-335
•
TRACEINSTREXEC on page 2-346
•
TRACEINSTRFETCH on page 2-352.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-29
RealView Debugger Commands
2.3.5
AOS_resource-list
Performs an action on an object chosen from the OS resource list.
Syntax
AOS_resource-list ,qualifier [=value]
where:
resource-list
Specifies the resource list.
qualifier
Specifies the action, that is action-name[:value].
value
Identifies an object in the specified resource list.
Description
The AOS_resource-list command performs an action on an object chosen from the OS
resource list. The resource-list and qualifier depend on the OS you are using.
You can get a list of these commands using the DCOMMANDS command, for example:
dcommands all
You can also determine the commands from the Resource Viewer pane:
•
resource-list is determined by the tab you select in the Resource List, with the
exception of the Conn tab
•
qualifier is determined by right clicking on an object in the selected tab of the
Resource List.
You might want to log your use of the Resource Viewer pane to determine the CLI
commands you can use with your OS. See LOG on page 2-206 for details. You can then
modify the log file, and use it as a command script, see INCLUDE on page 2-194.
See the RealView Debugger v3.0 RTOS Guide for details on using the Resource Viewer
pane, and the interaction of OS actions and RealView Debugger.
Examples
The following examples show how to use AOS_resource-list:
aos_thread_list,suspend = 0x39d8
Suspends the thread 0x39d8.
2-30
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
aos_timer_list,set:100 = 0x15260
Sets the value of the timer 0x15260 to 100.
aos_timer_list,deactivate = timer_1
Deactivates the timer timer_1.
See also
The following commands provide similar or related functionality:
•
DOS_resource-list on page 2-141
•
OSCTRL on page 2-230
•
THREAD on page 2-307.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-31
RealView Debugger Commands
2.3.6
ARGUMENTS
The ARGUMENTS command enables you to specify the command-line arguments for the
application. These are used for each subsequent run on this connection.
Note
You can also specify arguments as part of the LOAD command.
Syntax
ARGUMENTS [{,delete | ,prompt}]
ARGUMENTS [,default] string
where:
delete
Delete the currently set ARGUMENTS list, so the argv list for the next run of
a program is only the program filename.
default
Make the defined arguments the default, so they apply to new
connections created in this session.
prompt
Display a dialog to prompt you for the arguments when the ARGUMENTS
command is executed.
string
Defines the command line that the application sees when it inspects the
argv[] array, or equivalent.
Description
The ARGUMENTS command enables you to specify arguments that the target application
might require when it starts execution. The specified string is made available to the
application running on the target through the semihosting mechanism. Any previous
argument definition is overwritten.
If a literal double-quote character is required in the arguments, you must escape it using
the backslash character and embed it in single quotes, for example:
ARGUMENTS "-f '\"my file.c\"'"
If you enter this command without any parameters, the current argument definition is
displayed.
2-32
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
About using the ARGUMENTS command
You must issue the ARGUMENTS command after loading and reloading an image:
•
This sequence works:
LOAD .....
ARGUMENTS "hello"
•
This sequence does not work:
ARGUMENTS "hello"
LOAD
•
This sequence works initially, but the argument setttings are lost after the reload:
LOAD
AGRUMENTS "hello"
GO
RELOAD
After reloading the image, enter this command again to specify the arguments
before running the image.
Examples
The following examples show how to use ARGUMENTS:
ARGUMENTS "-f file.c -o file.o"
Sets the command line so that, if the line is parsed in the normal
way by _main(), the argv[] array contains:
argv[0]
target program filename, for example: com.axf
argv[1]
-f
argv[2]
file.c
argv[3]
-o
argv[4]
file.o
argv[5]
NULL
ARGUMENTS "-f '\"my file.c\"' -o '\"my file.o\"'"
Sets the command line so that, if the line is parsed in the normal
way by _main(), the argv[] array contains:
ARM DUI 0175H
argv[0]
target program filename, for example: "com.axf"
argv[1]
-f
argv[2]
"my file.c"
argv[3]
-o
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-33
RealView Debugger Commands
argv[4]
"my file.o"
argv[5]
NULL
load /pd/r 'com.axf;;-f file.c -o file.o'
go
arguments "-f '\"my file.c\"' -o '\"my file.o\"'"
restart
go
Changes the arguments without unloading the image. Table 2-15
shows the argument assignments in the original LOAD command,
and the new assignments specified by the ARGUMENTS command.
Table 2-15 Changed argument assignments
Argument
Original value
New value
argv[0]
com.axf
com.axf
argv[1]
-f
-f
argv[2]
file.c
"my file.c"
argv[3]
-o
-o
argv[4]
file.o
"my file.o"
argv[5]
NULL
NULL
See also
The following commands provide similar or related functionality:
•
GO on page 2-186
•
LOAD on page 2-202
•
RESTART on page 2-263.
2-34
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.7
BACCESS
BACCESS is an alias of BREAKACCESS (see page 2-45).
2.3.8
BEXECUTION
BEXECUTION is an alias of BREAKEXECUTION (see page 2-56).
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-35
RealView Debugger Commands
2.3.9
BGLOBAL
The BGLOBAL command enables or disables global breakpoints, also called processor
exceptions.
Note
This command overrides the settings in the Connection Properties of the current
connection. However, if you disconnect and reconnect then the settings in the
Connection Properties are applied to the connection.
Syntax
BGLOBAL {,enable | ,disable} name [;macro-call]
BGLOBAL ,gui [;macro-call]
where:
request
If specified, must be one of the following:
enable
Enable the specified global breakpoint.
disable
Disable the specified global breakpoint.
gui
Display a list box that enables you to select a global breakpoint
to enable or disable.
Note
This qualifier has no effect when running in command line
mode.
name
Identifies the global breakpoint to be enabled or disabled. See
Compatibility on page 2-37 for a list of supported names.
macro-call
Specifies a macro and any parameters it requires. This macro is run when
a global breakpoint is triggered.
If the macro returns a nonzero value, execution continues. If the macro
returns a zero value, or if you do not specify a macro, target execution
stops and the debugger waits in command mode.
Description
The BGLOBAL command enables or disables global breaks. A global breakpoint is a
processor event that can cause execution to halt in any application using this connection.
For example, taking an undefined instruction trap might be a global breakpoint. The list
2-36
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
of possible global breakpoint events is defined by a combination of the target processor
and the Target Access. For more information on the meaning of the processor
exceptions see the processor architecture manual.
Some simulators, including RealView ARMulator® ISS (RVISS), can extend the list of
possible breakpoint events beyond that defined for the processor. These extensions are
normally defined by peripheral or memory models included in the simulator. For
example, a memory model might define a DMA transfer event.
Each extra event is named by the model that implements it, and these names are
displayed with the standard names in the GUI. You can set and modify global
breakpoints for these events using the bglobal command by specifying the event name
as name in the command. If the name includes spaces, you must enclose it in double
quotes.
Compatibility
The supported events are determined in part by the currently connected processor type:
RealView ICE connections to ARM processors
The possible events are the exception types supported by the processors
on RealView ICE connections. The supported names are:
reset
The RESET exception.
undef
The undefined instruction exception.
SWI
The software interrupt (SWI) exception.
prefetch abort
The prefetch abort (instruction memory read abort)
exception. You must use double quotes to specify
this name, for example:
bglobal,enable "prefetch abort"
data abort
The data abort (data memory read or write abort)
exception. You must use double quotes to specify
this name, for example:
bglobal,enable "data abort"
IRQ
The interrupt request exception.
FIQ
The fast interrupt request exception.
RealView Simulator Broker connections to ARM processors
The possible events are the exception types supported by processors on
RealView Simulator Broker connections. The supported names are:
ARM DUI 0175H
Reset
The RESET exception.
Undefined
The undefined instruction exception.
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-37
RealView Debugger Commands
SWI
The software interrupt (SWI) exception.
P_Abort
The prefetch abort (instruction memory read abort)
exception.
D_Abort
The data abort (data memory read or write abort)
exception.
Address
The address exception. Used only by the now
obsolete 26-bit ARM processor architectures.
IRQ
The interrupt request exception.
FIQ
The fast interrupt request exception.
Error
The error exception.
CEVA-Oak and CEVA-TeakLite processors
The events supported are:
ILL
The illegal access break.
BKR
The block repeat break.
TBF
The trace buffer full break.
INT
The interrupt break.
BRE
The branch break.
EXR
The external register read break.
EXW
The external register write break.
Examples
The following example disables debugger interception of the ARM architecture
software interrupt (SWI) exception, so that an application can process SWI exceptions
itself:
bglobal,disable SWI
This example enables debugger interception of the ARM architecture UNDEF exception,
so that if the application starts executing data literals (the usual reason for
unintentionally executing an undefined instruction) you can find out why:
bglobal,enable undefined
Some processor exceptions interact with other debugger functions. For example, the
ARM SWI exception is used by the ARM Semihosting interface, and the CEVA-Oak
processor trace buffer full break is used by the CEVA-Oak trace configuration mode.
2-38
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
See also
The following command provides similar or related functionality:
•
BREAKACCESS on page 2-45
•
BREAKEXECUTION on page 2-56
•
BREAKINSTRUCTION on page 2-67
•
BREAKREAD on page 2-74
•
BREAKWRITE on page 2-85
•
GO on page 2-186.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-39
RealView Debugger Commands
2.3.10
BINSTRUCTION
BINSTRUCTION is an alias of BREAKINSTRUCTION (see page 2-67).
2-40
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.11
BOARD
The BOARD command changes the current board, also known as the current connection.
By default, all actions apply to the current connection.
Note
The BOARD command is only available when RealView Debugger is licensed for multiple
processor use.
Syntax
BOARD [{,next | ,default | [=]resource}]
where:
next
Connects the debugger to the next connection listed in the connection list.
default
Connects the debugger to the connection that is listed first in the
connection list.
resource
Identifies the connection that is to become the current connection. The =
in this parameter is optional.
The connection information is specified in the same format as it is
displayed in the Code window title bar. You can specify this using one of
the following:
@connection:manufacturer
"connection:manufacturer"
where:
•
connection is the connection name for the target device, for
example ARM966E-S_0
•
manufacturer is the manufacturer ID (for example ARM-ARM-NW),
which you can determine from the board file or from the
connection properties.
Note
If you have created multiple RVISS connections using the ARM-A-SW
manufacturer type (see the RealView Debugger v3.0 Target
Configuration Guide for details), then you cannot use the
connection:manufacturer resource name to change the connection. You
must use the board,next command to cycle through the connections.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-41
RealView Debugger Commands
Description
With no parameters, the BOARD command displays the name of the current board. The
displayed information has the following format:
Current Board is connection:manufacturer targetname - TargetAccess_description
where targetname is the name of the target processor, and TargetAccess_description is
the description of the Target Access that is displayed in the Connection Control window.
With one of the qualifiers or the resource argument, the command connects the
debugger to either:
•
the specified board
•
the next board in the board list
•
the default board.
The newly selected board becomes the current target connection. RealView Debugger
uses the term board because a target connection is defined by more than a processor
device. The memory map and the available peripherals are normally defined by the
target as a whole, and so it is more appropriate to refer to boards than to processors.
You can display the boards that you can cycle through using board,next by clicking the
connection drop-down list from the toolbar.
Using ADDBOARD, you can add a board to the list of boards that can be selected when
creating a new connection, for the duration of the current session. You can remove an
unconnected board from the list using DELBOARD. To add or remove a board from the
board list permanently, you must edit the board file using EDITBOARDFILE.
Note
If you enter the BOARD command in a Code window that is attached to a connetion, then
no connection information is displayed.
Examples
The following examples show how to use BOARD:
•
To change the current board to the next defined board from the board list:
board,next
New Current Board is Simarm_0:Sim ARM1176JZF-S - Simulator Broker (P1)
•
To change the current board to the named board in the board list:
board ="ARM966E-S_0:ARM-A-NW"
New Current Board is ARM966E-S_0:ARM-ARM-NW ARM966E-S - ARM966E-S on
Integrator/AP (RVI-USB) (P1)
2-42
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
The name of the current board is displayed in the titlebar of an unattached Code
Window and in the output of the board command when specified without
arguments, for example:
board
Current Board is ARM966E-S_1:ARM-ARM-NW ARM966E-S - ARM966E-S on
Integrator/AP (RVI-USB) (P1)
See also
The following commands provide similar or related functionality:
•
CONNECT on page 2-108
•
DELBOARD on page 2-124
•
DISCONNECT on page 2-136
•
EDITBOARDFILE on page 2-158
•
THREAD on page 2-307.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-43
RealView Debugger Commands
2.3.12
BREAD
BREAD is an alias of BREAKREAD (see page 2-74).
2.3.13
BREAK
BREAK is an alias of BREAKINSTRUCTION (see page 2-67).
2-44
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.14
BREAKACCESS
The BREAKACCESS command sets a hardware breakpoint that activates when specified
memory locations are accessed, either by a memory read or a memory write.
See the chapter that describes setting breakpoints in the RealView Debugger v3.0 User
Guide for full details on the use of breakpoints in RealView Debugger.
Syntax
BREAKACCESS [,qualifier...] {address | address-range} [;macro-call]
where:
qualifier
Is a list of zero or more qualifiers. The possible qualifiers are described
in List of qualifiers on page 2-48.
address | address-range
Specifies a single address in target memory, or an address range. The
address can also be a memory mapped register (see Memory mapped
registers on page 2-46). For details on how to specify an address range,
see Specifying address ranges on page 2-2.
macro-call
Specifies a macro and any parameters it requires. This macro runs when
the access breakpoint is hit. The macro is treated as being specified last
in the qualifier list.
If the macro returns a nonzero value, or you specified continue in the
qualifiers, execution continues. If the macro returns a zero value, or if you
do not specify a macro, target execution stops and the debugger waits in
command mode.
The macro argument symbols are interpreted when the breakpoint is
specified and so they must be in scope at that point, or you must explicitly
qualify them.
Description
BREAKACCESS is used to set or modify memory access breakpoints. Access breakpoints
activate when one or more specified memory addresses are read from or written to. If
the command has no arguments, it behaves like DTBREAK on page 2-147, listing the
current breakpoints (see List of qualifiers on page 2-48).
Hardware address breakpoints can use other hardware tests in association with the
address test, such as trigger inputs and outputs, hardware pass counters, and and-then,
or chained, tests (see Qualifiers that define hardware tests on page 2-48).
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-45
RealView Debugger Commands
All breakpoints can have conditions, for example expressions, macros, C++ object tests,
and pass counters. All address breakpoints can include actions including: counters,
timing (with hardware assist), update of specified windows, enabling or disabling other
breakpoints, and the starting and stopping of other processors or threads.
When a hardware data access breakpoint is hit on the target, the following sequence of
events occurs:
1.
The debugger or the hardware associates the event with a specific debugger
breakpoint ID.
2.
If the breakpoint has a software pass count associated with it, the count is updated.
3.
The conditions for this breakpoint, if any, are tested in the order specified on the
command line (see Qualifiers that define conditional breakpoints on page 2-48).
If any condition is False, target execution resumes with the instruction at the
breakpointed location. Macros specified with the macro: qualifier or the
;macro-call argument are run in this phase.
4.
If the breakpoint has actions associated with it (for example, using message
displays a user-specified message) these actions are run, in the order specified on
the command line (see Qualifiers that define conditional breakpoints on
page 2-48).
5.
If the qualifiers include continue, target execution resumes with the instruction at
the breakpointed location. If not, the debugger updates the state of the GUI and
waits for a command, leaving the application halted.
If you are debugging multiprocessor applications, and you have set up synchronization
and cross-triggering, then you can specify how each processor is affected when a
breakpoint activates. For full details, see the chapter that describes debugging multiple
targets in the RealView Debugger v3.0 User Guide.
Memory mapped registers
You can set a breakpoint that activates when a memory-mapped registers is accessed in
any way. To specify a memory mapped register, enter the following expression for the
address:
register:expression
The register is identified by expression. For example:
BREAKACCESS register:PR1
or
BREAKACCESS register:@PR1
2-46
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
For more details about memory mapped registers, see the RealView Debugger v3.0
Target Configuration Guide.
Note
You can only specify memory mapped registers that are defined in either the
connection-level settings or a Board/Chip Definition (.bcd) file that you have assigned
to the connection. You cannot set breakpoints on core registers.
Combining hardware and software pass counts
You can combine hardware and software pass counts to achieve higher count values. If
you define both hardware and software pass counts:
1.
2.
When the hardware pass count reaches zero, the software pass count is
decremented. What happens next depends on your hardware:
•
For RVISS, the hardware count remains at zero, so that
total count = hw_passcount + passcount
•
Other processors, such as DSPs, might exhibit the RVISS behaviour, or
might reset the hardware pass count to the initial value, so that:
total count = (hw_passcount +1) * passcount + hw_passcount
When the software pass count reaches zero, the breakpoint activates.
The breakpoint list index number
RealView Debugger assigns a breakpoint list index number to each breakpoint. This
number is assigned consecutively. However, if you delete a breakpoint, then the
numbering might no longer be consecutive.
To determine the breakpoint list index of an existing breakpoint:
1.
Start RealView Debugger in GUI mode.
2.
Select View → Break/Tracepoints to display the Break/Tracepoint pane.
3.
Click the checkbox for the chosen breakpoint to disable it.
4.
Click the Cmd tab in the Output pane.
The breakpoint list index (number) for the breakpoint is shown in the command:
disable,h number
5.
ARM DUI 0175H
Click the checkbox for the chosen breakpoint to enable it.
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-47
RealView Debugger Commands
Qualifiers that define conditional breakpoints
To set up a conditional breakpoint, use one or more of the following condition
qualifiers:
•
macro (or ;macro-call)
•
obj
•
passcount
•
when
•
when_not.
Qualifiers that define breakpoint actions
To specify actions to be performed when a breakpoint activates, use the following action
qualifiers:
•
continue
•
message
•
update.
Qualifiers that define hardware tests
To specify hardware tests for data access breakpoints, use the following qualifiers:
•
data_only
•
hw_ahigh
•
hw_amask
•
hw_and
•
hw_dhigh
•
hw_dmask
•
hw_dvalue
•
hw_in
•
hw_not
•
hw_passcount.
List of qualifiers
The list of qualifiers depends on the processor and Target Access, and so the GUI does
not present things that do not make sense. The command handler generates an error if a
specific combination is invalid for a specific processor or Target Access, but this is
determined when you issue the command.
2-48
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
The possible qualifiers are:
append:(n)
Instead of creating a new breakpoint, append the qualifiers
specified with this command to an existing breakpoint with
breakpoint list index number n (see The breakpoint list index
number on page 2-47).
Note
You cannot use append to change the breakpoint address or to
create chained breakpoints.
continue
Execution continues when the breakpoint activates and no
breakpoint details are displayed. Any specified action qualifiers
are still performed, depending on the results of any condition
qualifiers.
data_only
The breakpoint activates if a data value, specified using hw_dvalue,
is detected by the debug hardware on the processor data bus.
hw_ahigh:(n)
Specifies the high address for an address-range breakpoint. The
low address is specified by the standard breakpoint address.
This facility is not supported by ARM EmbeddedICE®
macrocells. For example, this command sets a breakpoint that
activates for any address between 0x1000-0x1200:
BREAKACCESS,hw_ahigh:0x1200 0x1000
This is equivalent to the command:
BREAKACCESS 0x1000..0x1200
hw_amask:(n)
Specifies the address mask value for an address-range breakpoint.
Addresses that match the standard breakpoint address when
masked with this value cause the breakpoint to activate.
This facility is supported by ARM EmbeddedICE macrocells. For
example, this command sets a breakpoint that activates for any
address between 0x1FA00-0x1FA0F:
BREAKACCESS,hw_amask:0xFFFF0 0x1FA00
This is equivalent to the command:
BREAKACCESS 0x1FA00..0x1FA0F
hw_and:{[then-]id} Perform an and or an and-then conjunction with another
breakpoint, to create a chain of breakpoints. Each breakpoint in
the chain is called a breakpoint unit.You specify the breakpoint
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-49
RealView Debugger Commands
units in the reverse order that RealView Debugger processes them.
The position of the breakpoint unit in the chain is identified by id,
which is one of the following:
next
Indicates that this breakpoint unit is to be linked to
another breakpoint unit specified for this connection.
You must set a breakpoint unit with the ID next before
you set any other breakpoint units for the chain. When
used with then-, this breakpoint unit is the last one
processed in the chain.
prev
Indicates that this breakpoint unit is to be linked to an
existing breakpoint unit specified for this connection.
Make sure the existing breakpoint has been set with a
next, prev, or index_number ID, and is a hardware
breakpoint.
Note
When using the prev ID, you must finish defining the
complete breakpoint chain before you create any
non-chained breakpoints.
index_number
The breakpoint list index number of an existing
breakpoint unit (see The breakpoint list index number
on page 2-47). Make sure the existing breakpoint has
been set with a next, prev, or index_number ID, and is a
hardware breakpoint.
How RealView Debugger processes the breakpoint units depends
on the conjunction you have used:
•
In the and form, the conditions associated with both
breakpoint units are chained together, so that the action
associated with the second breakpoint unit is performed
only when both conditions simultaneously match.
For example:
BREAKACCESS,hw_and:next,hw_dvalue:1
@copyfns\\COPYFNS\mycpy\append
BREAKEXECUTION,hw_and:prev @copyfns\\COPYFNS\mycpy\
•
2-50
In the and-then form, RealView Debugger examines the
breakpoint units starting with the last one you specified.
When the condition for the last breakpoint unit (breakpoint
unit N) is met, the associated actions are performed and the
previous breakpoint is enabled (breakpoint unit N-1).
RealView Debugger continues processing all remaining
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
breakpoints in the chain, until the condition in the first one
you specified is met (breakpoint unit 1). At this point, unless
the continue qualifier is specified in that breakpoint,
execution stops.
For example, you might have three breakpoint units in a
chain, which you specify in the following order:
BREAKACCESS,hw_and:{then-next},continue 0x1001B (BPU1)
BREAKACCESS,hw_and:{then-prev} 0x10018 (BPU2)
BREAKACCESS,hw_and:{then-prev} 0x10014 (BPU3)
In this case, RealView Debugger first checks for a data
access at address 0x10014 (BPU3), then at address 0x10018
(BPU2), and finally at adress 0x1001B (BPU1). When all
conditions are met, processing continues as instructed by
BPU1.
If you clear BPU1, then all breakpoints in the chain are cleared.
If you clear any other breakpoint unit, then that breakpoint unit
and the following ones are cleared. The previous breakpoint units
remain set. For example, clearing BPU2, clears both BPU2 and
BPU3, but not BPU1.
hw_dhigh:(n)
Specifies the high data value for a data-range breakpoint. The low
data value is specified by the hw_dvalue qualifier.
This facility is not supported by ARM EmbeddedICE macrocells.
For example, this command sets a breakpoint that activates for any
data value between 0x00-0x18:
BREAKACCESS,hw_dvalue:0x0,hw_dhigh:0x18 0x1000
hw_dmask:(n)
Specifies the data value mask value for a data-range breakpoint.
Data values that match the value specified by the hw_dvalue
qualifier when masked with this value cause the breakpoint to
activate.
This facility is supported by ARM EmbeddedICE macrocells. For
example, this command sets a breakpoint that activates for any
data value between 0x400-0x4FF:
BREAKACCESS,hw_dvalue:0x400,hw_dmask:0xF00 0x1FA00
hw_dvalue:(n)
Specifies a data value to be compared to values transmitted on the
processor data bus.
This facility is supported by ARM EmbeddedICE macrocells. For
example, this command sets a breakpoint that activates for the
data value 0x400:
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-51
RealView Debugger Commands
BREAKACCESS,hw_dvalue:0x400
hw_in:{s}
Input trigger tests. The string that follows matches
hardware-supported input tests as a list of names or a value. The
available tests depends on the Target Access and the target
processor.
Table 2-16 shows the possible strings for an ARM940T™
processor.
Table 2-16 Example hw_in test strings for an ARM940T
Input test string
Meaning
No "Ext=level" string
Ignore external
trigger level
Ext=0x00000001
Low
Ext=0x00000002
High
No "Mode=mode" string
Any mode
Mode=0x00000004
Privileged
Mode=0x00000008
User
No "AccessSize=size"
string
Default access
size
AccessSize=0x00000100
8-bit
AccessSize=0x00000200
16-bit
AccessSize=0x00000300
32-bit
AccessSize=0x00000400
8/16-bit
AccessSize=0x00000500
8/32-bit
For example, you might have a connection to an ARM940T
processor through the RealView-ICE Target Access. For this
processor, to test for a low external trigger level and 32-bit data
accesses in User mode at address 0x10014, enter:
BREAKACCESS,hw_in:"Ext=0x00000002",hw_in:"Mode=0x00000008",h
w_in:"AccessSize=0x00000300" 0x10014
2-52
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
hw_not:{s}
Use this qualifier to invert the sense of an address, data, or hw_and
term specified in the same command. The argument s can be set
to:
addr
Invert the breakpoint address value.
data
Invert the breakpoint value.
then
Invert an associated hw_and:{then} condition.
For example, to break when a data value does not match a mask,
you can write:
BREAKACCESS,hw_not:data,hw_dmask:0x00FF ...
The break commands require an address value, and the addr
variant of hw_not uses this address.
BREAKACCESS,hw_not:addr 0x10040
This means to break at any address other than 0x10040. This
example is probably not useful.
The hw_not:then variant of the command is used in conjunction
with hw_and to form or and nand-then conditions.
This facility is not supported by ARM EmbeddedICE macrocells.
hw_out:{s}
Not supported in this release.
hw_passcount:(n)
Specifies the number of times that the break condition is ignored
before the breakpoint activates. The default value is 0. This
qualifier differs from passcount only in that it is implemented in
hardware. n is limited to a 32-bit value by the debugger, but might
be much more limited by the target hardware, for example to 8 or
16 bits.
You can combine the hardware and software pass counts to
achieve higher count values. However, the behavior depends on
your processor (see Combining hardware and software pass
counts on page 2-47).
macro:{MacroCall(arg1,arg2)}
When the breakpoint is hit, the specified macro is executed. Any
program variables or functions must be in scope at the time the
breakpoint request is entered, or the names must be fully qualified.
You must include the braces { and }.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-53
RealView Debugger Commands
message:{"$windowid | fileid$message"}
Activation of the breakpoint results in message being output.
Prefixing message with $windowid | fileid$ enables you to write
the message text to a user-defined window or file. See Window
and file numbers on page 1-5 for details. For example:
BREAKACCESS,message:{"$100$this is a message"}
modify:(n)
Instead of creating a new breakpoint, modify the breakpoint with
breakpoint list index number n (see The breakpoint list index
number on page 2-47). The address expression and the qualifiers
of the existing breakpoint are replaced by those specified in this
command.
obj:(n)
This condition is True if the argument n matches the C++ object
pointer, normally called this.
passcount:(n)
Specifies the number of times that the break condition is ignored
before the breakpoint activates. The default value is 0. If you
specify this in the middle of a sequence of break conditions, those
specified before the pass count are processed whether or not the
count reaches zero. The conditions specified afterwards are run
only when the count reaches zero.
There is a hardware pass count qualifier available, hw_passcount,
for debug hardware that supports it. You can combine the
hardware and software pass counts to achieve higher count values.
However, the behavior depends on your processor (see Combining
hardware and software pass counts on page 2-47).
Note
If a breakpoint uses a passcount, the counting is performed on the
host, and so program execution stops briefly every time the
breakpoint is hit, even when the count has not been reached.
size:n
Set the size of the breakpoint to either 16 or 32 bits. For example:
BREAKACCESS,size:32 0x10040
Use this qualifier if no debug information is available for your
image. By default, RealView Debugger sets a 32-bit breakpoint.
update:{"name"}
2-54
Update the named windows, or all windows, by reading the
memory and processor state when the breakpoint activates. You
can use the name all to refresh all windows, or a name specified
in the title bar of the window.
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
This qualifier enables you to get an overview of the process state
at a particular point, without having to manually restart the
process at each break. The update still takes a significant period of
time, and so this method is unsuitable as a non-intrusive
debugging tool.
when:{condition}
The breakpoint activates whenever condition, a debugger
expression, evaluates to True.
Note
Using a macro as an argument to when, reverses the sense of the
return value from the macro.
when_not:{condition}
The breakpoint activates whenever condition, a debugger
expression, evaluates to False.
Alias
BACCESS is an alias of BREAKACCESS.
See also
The following commands provide similar or related functionality:
•
BREAKEXECUTION on page 2-56
•
BREAKINSTRUCTION on page 2-67
•
BREAKREAD on page 2-74
•
BREAKWRITE on page 2-85
•
CLEARBREAK on page 2-104
•
DTBREAK on page 2-147
•
ENABLEBREAK on page 2-162
•
VMACRO on page 2-365.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-55
RealView Debugger Commands
2.3.15
BREAKEXECUTION
The BREAKEXECUTION command sets an execution breakpoint that enables ROM-based
breakpoints by using the hardware breakpoint facilities of the target.
See the chapter that describes setting breakpoints in the RealView Debugger v3.0 User
Guide for full details on the use of breakpoints in RealView Debugger.
Syntax
BREAKEXECUTION [,qualifier...] expression [;macro-call]
where:
qualifier
Is an ordered list of zero or more qualifiers. The possible qualifiers are
described in List of qualifiers on page 2-59.
expression
Specifies the address at which the breakpoint is placed. By default, this is
the address where program execution stops.
macro-call
Specifies a macro and any parameters it requires. The macro runs when
the breakpoint is hit and before the instruction at the breakpoint is
executed. The macro is treated as being specified last in the qualifier list.
If the macro returns a nonzero value, or you specified continue in the
qualifiers, execution continues. If the macro returns a zero value, or if you
do not specify a macro, target execution stops and the debugger waits in
command mode.
The macro argument symbols are interpreted when the breakpoint is
specified and so they must be in scope at that point, or you must explicitly
qualify them.
Description
This command is used to set or modify an execution address breakpoint. An execution
breakpoint identifies the location of an instruction that, if executed, causes the
breakpoint to be hit. When the breakpoint is hit, RealView Debugger determines when
the breakpoint is activated. Activation depends on whether or not any condition
qualifiers are assigned to the breakpoint (see Qualifiers that define conditional
breakpoints on page 2-58):
2-56
•
If no condition qualifiers are assigned, then the breakpoint activates immediately.
•
If condition qualifiers are assigned, then activation is be delayed until all the
conditions are met.
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
When the breakpoint activates, any action qualifiers that are assigned to the breakpoint
are performed (see Qualifiers that define breakpoint actions on page 2-58). If no action
qualifiers are assigned, the default action is to stop execution.
When a hardware breakpoint instruction is hit on the target, the following sequence of
events occurs:
1.
The debugger or the hardware associates the event with a specific debugger
breakpoint ID.
2.
If the breakpoint has a software pass count associated with it, the count is updated.
3.
The conditions for this breakpoint, if any, are tested in the order specified on the
command line (see Qualifiers that define conditional breakpoints on page 2-58).
If any condition is False, target execution resumes with the instruction at the
breakpointed location. Macros specified with the macro: qualifier or the
;macro-call argument are run in this phase.
4.
If the breakpoint has actions associated with it (for example, using timed to note
the time the breakpoint occurred) these actions are run, in the order specified on
the command line (see Qualifiers that define breakpoint actions on page 2-58).
5.
If the qualifiers include continue, target execution resumes with the instruction at
the breakpointed location. If not, the debugger updates the state of the GUI and
waits for a command, leaving the application halted.
If the command has no arguments, it behaves like DTBREAK on page 2-147, listing the
current breakpoints.
Execution breakpoints can also use various hardware tests (see Qualifiers that define
hardware tests on page 2-59), such as trigger inputs, hardware pass counters, and
and-then, or chained, tests.
If you are debugging multiprocessor applications, and you have set up synchronization
and cross-triggering, then you can specify how each processor is affected when a
breakpoint activates. For full details, see the chapter that describes debugging multiple
targets in the RealView Debugger v3.0 User Guide.
Combining hardware and software pass counts
You can combine hardware and software pass counts to achieve higher count values. If
you define both hardware and software pass counts:
1.
When the hardware pass count reaches zero, the software pass count is
decremented. What happens next depends on your hardware:
•
ARM DUI 0175H
For RVISS, the hardware count remains at zero, so that
total count = hw_passcount + passcount
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-57
RealView Debugger Commands
•
2.
Other processors, such as DSPs, might exhibit the RVISS behaviour, or
might reset the hardware pass count to the initial value, so that:
total count = (hw_passcount +1) * passcount + hw_passcount
When the software pass count reaches zero, the breakpoint activates.
The breakpoint list index number
RealView Debugger assigns a breakpoint list index number to each breakpoint. This
number is assigned consecutively. However, if you delete a breakpoint, then the
numbering might no longer be consecutive.
To determine the breakpoint list index of an existing breakpoint:
1.
Start RealView Debugger in GUI mode.
2.
Select View → Break/Tracepoints to display the Break/Tracepoint pane.
3.
Click the checkbox for the chosen breakpoint to disable it.
4.
Click the Cmd tab in the Output pane.
The breakpoint list index (number) for the breakpoint is shown in the command:
disable,h number
5.
Click the checkbox for the chosen breakpoint to enable it.
Qualifiers that define conditional breakpoints
To set up a conditional breakpoint, use one or more of the following condition
qualifiers:
•
macro (or ;macro-call)
•
obj
•
passcount
•
when
•
when_not.
Qualifiers that define breakpoint actions
To specify actions to be performed when a breakpoint activates, use the following action
qualifiers:
•
continue
•
message
•
update.
2-58
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
Qualifiers that define hardware tests
To specify hardware tests for execution breakpoints, use the following qualifiers:
•
hw_ahigh
•
hw_amask
•
hw_and
•
hw_in
•
hw_not
•
hw_passcount.
List of qualifiers
The list of qualifiers is dependent on the processor and Target Access, and so the GUI
does not present things that do not make sense. The command handler generates an error
if a specific combination is invalid for a specific processor or Target Access, but this is
determined when you issue the command.
The possible qualifiers are:
append:(n)
Instead of creating a new breakpoint, append the qualifiers
specified with this command to an existing breakpoint with
breakpoint list index number n (see The breakpoint list index
number on page 2-58).
Note
You cannot use append to change the breakpoint address or to
create chained breakpoints.
continue
Execution continues when the breakpoint activates and no
breakpoint details are displayed. Any specified action qualifiers
are still performed, depending on the results of any condition
qualifiers.
hw_ahigh:(n)
Specifies the high address for an address-range breakpoint. The
low address is specified by the standard breakpoint address.
This facility is not supported by ARM EmbeddedICE macrocells.
For example, this command sets a breakpoint that activates for any
address between 0x1000-0x1200:
BREAKEXECUTION,hw_ahigh:0x1200 0x1000
This is equivalent to the command:
BREAKEXECUTION 0x1000..0x1200
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-59
RealView Debugger Commands
hw_amask:(n)
Specifies the address mask value for an address-range breakpoint.
Addresses that match the standard breakpoint address when
masked with this value cause the breakpoint to activate.
This facility is supported by ARM EmbeddedICE macrocells. For
example, this command sets a breakpoint that activates for any
address between 0x1FA00-0x1FA0F:
BREAKEXECUTION,hw_amask:0xFFFF0 0x1FA00
This is equivalent to the command:
BREAKEXECUTION 0x1FA00..0x1FA0F
hw_and:{[then-]id} Perform an and or an and-then conjunction with another
breakpoint, to create a chain of breakpoints. Each breakpoint in
the chain is called a breakpoint unit.You specify the breakpoint
units in the reverse order that RealView Debugger processes them.
The position of the breakpoint unit in the chain is identified by id,
which is one of the following:
next
Indicates that this breakpoint unit is to be linked to
another breakpoint unit specified for this connection.
You must set a breakpoint unit with the ID next before
you set any other breakpoint units for the chain. When
used with then-, this breakpoint unit is the last one
processed in the chain.
prev
Indicates that this breakpoint unit is to be linked to an
existing breakpoint unit specified for this connection.
Make sure the existing breakpoint has been set with a
next, prev, or index_number ID, and is a hardware
breakpoint.
Note
When using the prev ID, you must finish defining the
complete breakpoint chain before you create any
non-chained breakpoints.
index_number
The breakpoint list index number of an existing
breakpoint unit (see The breakpoint list index number
on page 2-58). Make sure the existing breakpoint has
been set with a next, prev, or index_number ID, and is a
hardware breakpoint.
2-60
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
How RealView Debugger processes the breakpoint units depends
on the conjunction you have used:
•
In the and form, the conditions associated with both
breakpoint units are chained together, so that the action
associated with the second breakpoint unit is performed
only when both conditions simultaneously match.
For example:
BREAKACCESS,hw_and:next,hw_dvalue:1
@copyfns\\COPYFNS\mycpy\append
BREAKEXECUTION,hw_and:prev @copyfns\\COPYFNS\mycpy\
•
In the and-then form, RealView Debugger examines the
breakpoint units starting with the last one you specified.
When the condition for the last breakpoint unit (breakpoint
unit N) is met, the associated actions are performed and the
previous breakpoint is enabled (breakpoint unit N-1).
RealView Debugger continues processing all remaining
breakpoints in the chain, until the condition in the first one
you specified is met (breakpoint unit 1). At this point, unless
the continue qualifier is specified in that breakpoint,
execution stops.
For example, you might have three breakpoint units in a
chain, which you specify in the following order:
BREAKEXECUTION,hw_and:{then-next},continue
DHRY_2\Proc_7 (BPU1)
BREAKEXECUTION,hw_and:{then-prev} DHRY_1\Proc_4 (BPU2)
BREAKEXECUTION,hw_and:{then-prev} DHRY_1\Proc_5 (BPU3)
In this case, RealView Debugger first checks for the
execution of the procedure Proc_5 in the source dhry_1.c
(BPU3), then the procedure Proc_4 in the source dhry_1.c
(BPU2), and finally the procedure Proc_7 in the source
dhry_2.c (BPU1). When all conditions are met, processing
continues as instructed by the first brakpoint in the chain.
If you clear BPU1, then all breakpoints in the chain are cleared.
If you clear any other breakpoint unit, then that breakpoint unit
and the following ones are cleared. The previous breakpoint units
remain set. For example, clearing BPU2, clears both BPU2 and
BPU3, but not BPU1.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-61
RealView Debugger Commands
hw_in:{s}
Input trigger tests. The string that follows matches
hardware-supported input tests as a list of names or a value. The
available tests depends on the Target Access and the target
processor.
Table 2-17 shows the possible strings for an ARM940T processor.
Table 2-17 Example hw_in test strings for an ARM940T
Input test string
Meaning
No "Ext=level" string
Ignore external
trigger level
Ext=0x00000001
Low
Ext=0x00000002
High
No "Mode=mode" string
Any mode
Mode=0x00000004
Privileged
Mode=0x00000008
User
No "AccessSize=size"
string
Default access
size
AccessSize=0x00000100
8-bit
AccessSize=0x00000200
16-bit
AccessSize=0x00000300
32-bit
AccessSize=0x00000400
8/16-bit
AccessSize=0x00000500
8/32-bit
For example, you might have a connection to an ARM940T
processor through the RealView-ICE Target Access. For this
processor, to test for a Privileged mode access from at line 149 in
dhry_1.c, enter:
BREAKEXECUTION,hw_in:"Mode=0x00000004" \DHRY_1\#149:1
hw_not:{s}
2-62
Use this qualifier to invert the sense of an address, data, or hw_and
term specified in the same command. The argument s can be set
to:
addr
Invert the breakpoint address value.
data
Invert the breakpoint value.
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
then
Invert an associated hw_and:{then} condition.
For example, to break when a data value does not match a mask,
you can write:
BREAKEXECUTION,hw_not:data,hw_dmask:0x00FF ...
The break commands require an address value, and the addr
variant of hw_not uses this address.
BREAKEXECUTION,hw_not:addr 0x10040
This means to break at any address other than 0x10040. This
example is probably not useful.
The hw_not:then variant of the command is used in conjunction
with hw_and to form nand and nand-then conditions.
This facility is not supported by ARM EmbeddedICE macrocells.
hw_out:{s}
Not supported in this release.
hw_passcount:(n)
Specifies the number of times that the break condition is ignored
before it activates. The default value is 0. This qualifier differs
from passcount only in that it is implemented in hardware. n is
limited to a 32-bit value by the debugger, but might be much more
limited by the target hardware, for example to 8 or 16 bits.
You can combine the hardware and software pass counts to
achieve higher count values. However, the behavior depends on
your processor (see Combining hardware and software pass
counts on page 2-57).
macro:{MacroCall(arg1,arg2)}
When the breakpoint is hit, the specified macro is executed. Any
program variables or functions must be in scope at the time the
breakpoint request is entered, or the names must be fully qualified.
You must include the braces { and }.
message:{"$windowid | fileid$message"}
Activation of the breakpoint results in message being output.
Prefixing message with $windowid | fileid$ enables you to write
the message text to a user-defined window or file. See Window
and file numbers on page 1-5 for details. For example:
BREAKEXECUTION,message:{"$100$this is a message"}
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-63
RealView Debugger Commands
modify:(n)
Instead of creating a new breakpoint, modify the breakpoint with
breakpoint list index number n (see The breakpoint list index
number on page 2-58). The address expression and the qualifiers
of the existing breakpoint are replaced by those specified in this
command.
obj:(n)
This condition is True if the argument n matches the C++ object
pointer, normally called this.
passcount:(n)
Specifies the number of times that the break condition is ignored
before it activates. The default value is 0. If you specify this in the
middle of a sequence of break conditions, those specified before
the pass count are processed whether or not the count reaches
zero. The conditions specified afterwards are run only when the
count reaches zero.
There is a hardware pass count qualifier available, hw_passcount,
for debug hardware that supports it. You can combine the
hardware and software pass counts to achieve higher count values.
However, the behavior depends on your processor (see Combining
hardware and software pass counts on page 2-57).
Note
If a breakpoint uses a passcount, the counting is performed on the
host, and so program execution stops briefly every time the
breakpoint is hit, even when the count has not been reached.
size:n
Set the size of the breakpoint to either 16 or 32 bits. For example:
BREAKEXECUTION,size:32 0x10040
Use this qualifier if no debug information is available for your
image. By default, RealView Debugger sets a 32-bit breakpoint.
update:{"name"}
Update the named windows, or all windows, by reading the
memory and processor state when the breakpoint activates. You
can use the name all to refresh all windows, or a name specified
in the title bar of the window.
This qualifier enables you to get an overview of the process state
at a particular point, without having to manually restart the
process at each break. The update still takes a significant period of
time, and so this method is unsuitable as a non-intrusive
debugging tool.
when:{condition}
2-64
The breakpoint activates whenever condition, a debugger
expression, evaluates to True.
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
Note
Using a macro as an argument to when, reverses the sense of the
return value from the macro.
when_not:{condition}
The breakpoint activates whenever condition, a debugger
expression, evaluates to False.
Examples
The following examples show how to use BREAKEXECUTION:
BREAKEXECUTION 0x8000
Set a hardware breakpoint at address 0x8000.
BREAKEXECUTION \MATH_1\#449:22
Set a hardware breakpoint at line 449, column 22 in the file math.c.
BREAKEXECUTION,append:(1),continue,update:{all}
Given an already set breakpoint at position 1 in the breakpoint list,
add a request to update all windows in the code window for this
connection and continue execution each time the breakpoint
activates.
BREAKEXECUTION,hw_pass:(5) \MAIN_1\#49
Set a hardware breakpoint using a hardware counter to stop at the
fifth time that execution reaches line 49 of main.c.
BREAKEXECUTION \MAIN_1\MAIN_C\#33 ;CheckStruct()
Set a hardware breakpoint that calls a debugger macro
CheckStruct each time it reaches line 33 of main.c. If CheckStruct
returns a nonzero value, the debugger continues application
execution.
BREAKEXECUTION,when:{check_struct()} \MAIN_1\#33
Set a hardware breakpoint that calls a target program function
check_struct() each time it reaches line 33 of main.c. If this
function returns a zero value, the debugger continues application
execution.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-65
RealView Debugger Commands
Alias
BEXECUTION is an alias of BREAKEXECUTION.
See also
The following commands provide similar or related functionality:
•
BREAKACCESS on page 2-45
•
BREAKINSTRUCTION on page 2-67
•
BREAKREAD on page 2-74
•
BREAKWRITE on page 2-85
•
ENABLEBREAK on page 2-162
•
VMACRO on page 2-365.
2-66
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.16
BREAKINSTRUCTION
The BREAKINSTRUCTION command sets a software instruction breakpoint at the specified
memory location. Software breakpoints are implemented by writing a special
instruction at the break address, and so cannot be set in ROM.
See the chapter that describes setting breakpoints in the RealView Debugger v3.0 User
Guide for full details on the use of breakpoints in RealView Debugger.
Syntax
BREAKINSTRUCTION [,qualifier...] expression [=threads,...] [;macro-call]
where:
qualifier
Is an ordered list of zero or more qualifiers. The possible qualifiers are
described in List of qualifiers on page 2-69.
expression
Specifies the address at which the breakpoint is placed. By default, this is
the address where program execution stops.
threads
The list of threads that make up the break trigger group.
Only available for OS-aware RSD connections.
macro-call
Specifies a macro and any parameters it requires. The macro runs when
the breakpoint activates and before the instruction at the breakpoint is
executed. The macro is treated as being specified last in the qualifier list.
If the macro returns a nonzero value, or you specified continue in the
qualifiers, execution continues. If the macro returns a zero value, or if you
do not specify a macro, target execution stops and the debugger waits in
command mode.
The macro argument symbols are interpreted when the breakpoint is
specified and so they must be in scope at that point, or you must explicitly
qualify them.
Description
BREAKINSTRUCTION is used to set or modify software address breakpoints. Software
address breakpoints include breakpoints set by patching special instructions into the
program and hardware that tests the address and data values. If the command has no
arguments, it behaves like DTBREAK on page 2-147, listing the current breakpoints.
If you try to set a software breakpoint at a location in ROM or Flash, then RealView
Debugger attempts to set a hardware breakpoint instead. The attempt fails if insufficient
hardware facilities are available.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-67
RealView Debugger Commands
You can use qualifiers evaluated in the debugger, such as expressions, macros, C++
object tests, and software pass counters. You can also define actions to occur when the
breakpoint is triggered (hit), including updating counters or windows, and the enabling
or disabling of other breakpoints (see List of qualifiers on page 2-69).
When a software breakpoint instruction is hit on the target, the following sequence of
events occurs:
1.
The debugger associates the address with a specific breakpoint ID. A memory
address can only be associated with one user breakpoint at a time.
2.
If the breakpoint has a pass count associated with it, the count is updated.
3.
The conditions for this breakpoint, if any, are tested in the order specified on the
command line (see Qualifiers that define conditional breakpoints on page 2-69).
If any condition is False, target execution resumes with the instruction at the
breakpointed location. Macros specified with the macro: qualifier or the
;macro-call argument are run in this phase.
4.
If the breakpoint has actions associated with it (for example, using timed to note
the time the breakpoint occurred) these actions are run, in the order specified on
the command line (see Qualifiers that define breakpoint actions on page 2-69).
5.
If the qualifiers include continue, target execution resumes with the instruction at
the breakpointed location. If not, the debugger updates the state of the GUI and
waits for a command, leaving the application halted.
If you are debugging multiprocessor applications, and you have set up synchronization
and cross-triggering, then you can specify how each processor is affected when a
breakpoint activates. For full details, see the chapter that describes debugging multiple
targets in the RealView Debugger v3.0 User Guide.
The breakpoint list index number
RealView Debugger assigns a breakpoint list index number to each breakpoint. This
number is assigned consecutively. However, if you delete a breakpoint, then the
numbering might no longer be consecutive.
To determine the breakpoint list index of an existing breakpoint:
2-68
1.
Start RealView Debugger in GUI mode.
2.
Select View → Break/Tracepoints to display the Break/Tracepoint pane.
3.
Click the checkbox for the chosen breakpoint to disable it.
4.
Click the Cmd tab in the Output pane.
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
The breakpoint list index (number) for the breakpoint is shown in the command:
disable,h number
5.
Click the checkbox for the chosen breakpoint to enable it.
Qualifiers that define conditional breakpoints
To set up a conditional breakpoint, use one or more of the following condition
qualifiers:
•
macro (or ;macro-call)
•
obj
•
passcount
•
when
•
when_not.
Qualifiers that define breakpoint actions
To specify actions to be performed when a breakpoint activates, use the following action
qualifiers:
•
continue
•
message
•
update.
List of qualifiers
The list of qualifiers is dependent on the processor and Target Access, and so the GUI
does not present things that do not make sense. The command handler generates an error
if a specific combination is invalid for a specific processor or Target Access, but this is
determined when you issue the command.
The possible qualifiers are:
ARM DUI 0175H
append:(n)
Instead of creating a new breakpoint, append the qualifiers
specified with this command to an existing breakpoint with
breakpoint list index number n (see The breakpoint list index
number on page 2-68). You cannot change the breakpoint address.
continue
Execution continues when the breakpoint activates and no
breakpoint details are displayed. Any specified action qualifiers
are still performed, depending on the results of any condition
qualifiers.
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-69
RealView Debugger Commands
macro:{MacroCall(arg1,arg2)}
When the breakpoint is hit, the specified macro is executed. Any
program variables or functions must be in scope at the time the
breakpoint request is entered, or the names must be fully qualified.
A macro call specified here is treated in the same way as a macro
specified after a ;. You must include the braces { and }.
message:{"$windowid | fileid$message"}
Activation of the breakpoint results in message being output.
Prefixing message with $windowid | fileid$ enables you to write
the message text to a user-defined window or file. See Window
and file numbers on page 1-5 for details. For example:
BREAKINSTRUCTION,message:{"$100$this is a message"}
modify:(n)
Instead of creating a new breakpoint, modify the breakpoint with
breakpoint list index number n (see The breakpoint list index
number on page 2-68). The address expression and the qualifiers
of the existing breakpoint are replaced by those specified in this
command.
obj:(n)
This condition is True if the argument n matches the C++ object
pointer, normally called this.
passcount:(n)
Specifies the number of times that the break condition is ignored
before the breakpoint activates. The default value is 0. If you
specify this in the middle of a sequence of break conditions, those
specified before the passcount are processed whether or not the
count reaches zero. The conditions specified afterwards are run
only when the count reaches zero.
rtos:type
Sets a breakpoint for OS-aware connections, where type is one of:
hsd
Sets a Halted System Debug (HSD) breakpoint for
debugging your OS-aware image.
process
Not supported in this release.
system
Sets a system breakpoint for debugging images running
in Running System Debug (RSD) mode.
thread
Sets a thread breakpoint for debugging images running
in RSD mode.
For more details about these types of breakpoint, see the chapter
that describes OS support in the RealView Debugger v3.0 RTOS
Guide.
size:n
2-70
Set the size of the breakpoint to either 16 or 32 bits. For example:
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
BREAKINSTRUCTION,size:32 0x10040
Use this qualifier if no debug information is available for your
image. By default, RealView Debugger sets a 32-bit breakpoint.
update:{"name"}
Update the named windows, or all windows, by reading the
memory and processor state when the breakpoint activates. You
can use the name all to refresh all windows, or a name specified
in the title bar of the window.
This qualifier enables you to get an overview of the process state
at a particular point, without having to manually restart the
process at each break. The update still takes a significant period of
time, and so this method is unsuitable as a non-intrusive
debugging tool.
when:{condition}
The breakpoint activatesactivates whenever condition, a debugger
expression, evaluates to True.
Note
Using a macro as an argument to when, reverses the sense of the
return value from the macro.
when_not:{condition}
The breakpoint activates whenever condition, a debugger
expression, evaluates to False.
Rules
The following rules apply to the use of the BREAKINSTRUCTION command:
•
Breakpoints are specific to the board, process, or task active in the window at the
time they are set.
•
If synchronous breakpoints are set on two or more threads on the same board, the
debugger stops the threads as close to the same time as the architecture of the
board permits.
Examples
The following examples show how to use BREAKINSTRUCTION:
BREAKINSTRUCTION 0x8000
Set a breakpoint at address 0x8000.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-71
RealView Debugger Commands
BREAKINSTRUCTION \MATH_1\MATH_C\#449:22
Set a breakpoint at line 449, column 22 in the file math.c.
BREAKINSTRUCTION,append:(1),continue,update:{all}
Given an already set breakpoint at position 1 in the breakpoint list,
add a request to update all windows in the code window for this
connection and continue execution each time the breakpoint
activates.
BREAKINSTRUCTION,pass:(5) \MAIN_1\MAIN_C\#49
Set a breakpoint using a hardware counter to stop at the fifth time
that execution reaches line 49 of main.c.
BREAKINSTRUCTION \MAIN_1\MAIN_C\#33 ;CheckStruct()
Set a breakpoint that calls a debugger macro CheckStruct each
time it reaches line 33 of main.c. If CheckStruct returns a nonzero
value, the debugger continues application execution.
BREAKINSTRUCTION,when:{count<4 || err==5} \MAIN_1\SUBFN_C\#33
Set a breakpoint that activates when the expression count<4 ||
err==5 is True when execution reaches line 33 of subfn.c.
BREAKINSTRUCTION,when:{check_struct()} \MAIN_1\MAIN_C\#33
Set a breakpoint that calls a target program function
check_struct() each time it reaches line 33 of main.c. If this
function returns a zero value, the debugger continues application
execution.
BREAKINSTRUCTION, rtos:hsd \DEMO\#201
Set a HSD breakpoint at line 201 in demo.c.
BREAKINSTRUCTION,rtos:system \DEMO\#154
Set a system breakpoint at line 154 in demo.c.
BREAKINSTRUCTION,rtos:thread \DEMO\#154 = 0x39d8, 0x3a68
Set a thread breakpoint using a break trigger group consisting of
two threads, defined by the addresses of the thread control blocks.
BREAKINSTRUCTION,rtos:thread \DEMO\#180 = thread_2, thread_6, thread_8
Set a thread breakpoint using a break trigger group consisting of
three threads, defined by the thread names.
2-72
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
BREAKINSTRUCTION,modify:2,rtos:system
Modify breakpoint number 2, a thread breakpoint, to be a system
breakpoint.
BREAKINSTRUCTION,modify:3,rtos:thread = 0x1395c, 0x13bac
Modify breakpoint number 3, a thread breakpoint, to specify a
different break trigger group, shown in Figure 2-1.
Figure 2-1 Changing the break trigger group
Alias
BINSTRUCTION and BREAK are aliases of BREAKINSTRUCTION.
See also
The following commands provide similar or related functionality:
•
AOS_resource-list on page 2-30
•
BREAKACCESS on page 2-45
•
BREAKEXECUTION on page 2-56
•
BREAKREAD on page 2-74
•
BREAKWRITE on page 2-85
•
CLEARBREAK on page 2-104
•
DOS_resource-list on page 2-141
•
ENABLEBREAK on page 2-162
•
OSCTRL on page 2-230
•
STOP on page 2-301
•
VMACRO on page 2-365.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-73
RealView Debugger Commands
2.3.17
BREAKREAD
The BREAKREAD command sets a hardware breakpoint that activates when a read
operation is performed on any of the specified memory locations.
See the chapter that describes setting breakpoints in the RealView Debugger v3.0 User
Guide for full details on the use of breakpoints in RealView Debugger.
Syntax
BREAKREAD [,qualifier...] {address | address-range} [;macro-call]
where:
qualifier
Is an ordered list of zero or more qualifiers. The possible qualifiers are
described in List of qualifiers on page 2-77.
address | address-range
Specifies a single address in target memory, or an address range. The
address can also be a memory mapped register (see Memory mapped
registers on page 2-75). For details on how to specify an address range,
see Specifying address ranges on page 2-2.
macro-call
Specifies a macro and any parameters it requires. The macro runs when
the breakpoint is hit and before the instruction at the breakpoint is
executed. The macro is treated as being specified last in the qualifier list.
If the macro returns a nonzero value, or you specified continue in the
qualifiers, execution continues. If the macro returns a zero value, or if you
do not specify a macro, target execution stops and the debugger waits in
command mode.
The macro argument symbols are interpreted when the breakpoint is
specified and so they must be in scope at that point, or you must explicitly
qualify them.
Description
BREAKREAD is used to set or modify data read breakpoints. Data read breakpoints activate
when data that matches a condition is read from memory at a particular address or
address range. If the command has no arguments, it behaves like DTBREAK on page 2-147,
listing the current breakpoints.
Hardware address breakpoints can use other hardware tests in association with the
address test, such as trigger inputs and outputs, hardware pass counters, and and-then,
or chained, tests (see Qualifiers that define hardware tests on page 2-77).
2-74
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
You can use qualifiers evaluated in the debugger, such as expressions, macros, C++
object tests, and software pass counters. You can also define actions to occur when the
breakpoint is triggered (hit), including updating counters or windows, and the enabling
or disabling of other breakpoints (see List of qualifiers on page 2-77).
If you do not specify an address, the read breakpoint is set at the address defined by the
current value of the PC. The breakpoint is triggered if the target program reads data
from any specified target memory area.
When a hardware data read breakpoint is hit on the target, the following sequence of
events occurs:
1.
The debugger or the hardware associates the event with a specific debugger
breakpoint ID.
2.
If the breakpoint has a software pass count associated with it, the count is updated.
3.
The conditions for this breakpoint, if any, are tested in the order specified on the
command line (see Qualifiers that define conditional breakpoints on page 2-77).
If any condition is False, target execution resumes with the instruction at the
breakpointed location. Macros specified with the macro: qualifier or the
;macro-call argument are run in this phase.
4.
If the breakpoint has actions associated with it (for example, using timed to note
the time the breakpoint occurred) these actions are run, in the order specified on
the command line (see Qualifiers that define breakpoint actions on page 2-77).
5.
If the qualifiers include continue, target execution resumes with the instruction at
the breakpointed location. If not, the debugger updates the state of the GUI and
waits for a command, leaving the application halted.
If you are debugging multiprocessor applications, and you have set up synchronization
and cross-triggering, then you can specify how each processor is affected when a
breakpoint activates. For full details, see the chapter that describes debugging multiple
targets in the RealView Debugger v3.0 User Guide.
Memory mapped registers
You can set a breakpoint that activates on a read from a memory-mapped register. To
specify a memory mapped register, enter the following expression for the address:
register:expression
The register is identified by expression. For example:
BREAKREAD register:PR1
or
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-75
RealView Debugger Commands
BREAKREAD register:@PR1
For more details about memory mapped registers, see the RealView Debugger v3.0
Target Configuration Guide.
Note
You can only specify memory mapped registers that are defined in either the
connection-level settings or a Board/Chip Definition (.bcd) file that you have assigned
to the connection. You cannot set breakpoints on core registers.
Combining hardware and software pass counts
You can combine hardware and software pass counts to achieve higher count values. If
you define both hardware and software pass counts:
1.
2.
When the hardware pass count reaches zero, the software pass count is
decremented. What happens next depends on your hardware:
•
For RVISS, the hardware count remains at zero, so that
total count = hw_passcount + passcount
•
Other processors, such as DSPs, might exhibit the RVISS behaviour, or
might reset the hardware pass count to the initial value, so that:
total count = (hw_passcount +1) * passcount + hw_passcount
When the software pass count reaches zero, the breakpoint activates.
The breakpoint list index number
RealView Debugger assigns a breakpoint list index number to each breakpoint. This
number is assigned consecutively. However, if you delete a breakpoint, then the
numbering might no longer be consecutive.
To determine the breakpoint list index of an existing breakpoint:
1.
Start RealView Debugger in GUI mode.
2.
Select View → Break/Tracepoints to display the Break/Tracepoint pane.
3.
Click the checkbox for the chosen breakpoint to disable it.
4.
Click the Cmd tab in the Output pane.
The breakpoint list index (number) for the breakpoint is shown in the command:
disable,h number
5.
2-76
Click the checkbox for the chosen breakpoint to enable it.
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
Qualifiers that define conditional breakpoints
To set up a conditional breakpoint, use one or more of the following condition
qualifiers:
•
macro (or ;macro-call)
•
obj
•
passcount
•
when
•
when_not.
Qualifiers that define breakpoint actions
To specify actions to be performed when a breakpoint activates, use the following action
qualifiers:
•
continue
•
message
•
update.
Qualifiers that define hardware tests
To specify hardware tests for data read breakpoints, use the following qualifiers:
•
data_only
•
hw_ahigh
•
hw_amask
•
hw_and
•
hw_dhigh
•
hw_dmask
•
hw_dvalue
•
hw_in
•
hw_not
•
hw_passcount.
List of qualifiers
The list of qualifiers is dependent on the processor and Target Access, and so the GUI
does not present things that do not make sense. The command handler generates an error
if a specific combination is invalid for a specific processor or Target Access, but this is
determined when you issue the command.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-77
RealView Debugger Commands
The possible qualifiers are:
append:(n)
Instead of creating a new breakpoint, append the qualifiers
specified with this command to an existing breakpoint with
breakpoint list index number n (see The breakpoint list index
number on page 2-76).
Note
You cannot use append to change the breakpoint address or to
create chained breakpoints.
continue
data_only
Execution continues when the breakpoint activates and no
breakpoint details are displayed. Any specified action qualifiers
are still performed, depending on the results of any condition
qualifiers.
The breakpoint is triggered if a data value, specified using
hw_dvalue, is detected by the debug hardware on the processor data
bus.
hw_ahigh:(n)
Specifies the high address for an address-range breakpoint. The
low address is specified by the standard breakpoint address.
This facility is not supported by ARM EmbeddedICE macrocells.
For example, this command sets a breakpoint that activates for any
address between 0x1000-0x1200:
BREAKREAD,hw_ahigh:0x1200 0x1000
This is equivalent to the command:
BREAKREAD 0x1000..0x1200
hw_amask:(n)
Specifies the address mask value for an address-range breakpoint.
Addresses that match the standard breakpoint address when
masked with this value cause the breakpoint to activate.
This facility is supported by ARM EmbeddedICE macrocells. For
example, this command sets a breakpoint that activates for any
address between 0x1FA00-0x1FA0F:
BREAKREAD,hw_amask:0xFFFF0 0x1FA00
This is equivalent to the command:
BREAKREAD 0x1FA00..0x1FA0F
hw_and:{[then-]id} Perform an and or an and-then conjunction with another
breakpoint, to create a chain of breakpoints. Each breakpoint in
the chain is called a breakpoint unit.You specify the breakpoint
2-78
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
units in the reverse order that RealView Debugger processes them.
The position of the breakpoint unit in the chain is identified by id,
which is one of the following:
next
Indicates that this breakpoint unit is to be linked to
another breakpoint unit specified for this connection.
You must set a breakpoint unit with the ID next before
you set any other breakpoint units for the chain. When
used with then-, this breakpoint unit is the last one
processed in the chain.
prev
Indicates that this breakpoint unit is to be linked to an
existing breakpoint unit specified for this connection.
Make sure the existing breakpoint has been set with a
next, prev, or index_number ID, and is a hardware
breakpoint.
Note
When using the prev ID, you must finish defining the
complete breakpoint chain before you create any
non-chained breakpoints.
index_number
The breakpoint list index number of an existing
breakpoint unit (see The breakpoint list index number
on page 2-76). Make sure the existing breakpoint has
been set with a next, prev, or index_number ID, and is a
hardware breakpoint.
How RealView Debugger processes the breakpoint units depends
on the conjunction you have used:
•
In the and form, the conditions associated with both
breakpoint units are chained together, so that the action
associated with the second breakpoint unit is performed
only when both conditions simultaneously match.
For example:
BREAKREAD,hw_and:next,hw_dvalue:1
@copyfns\\COPYFNS\mycpy\append
BREAKEXECUTION,hw_and:prev @copyfns\\COPYFNS\mycpy\
•
ARM DUI 0175H
In the and-then form, RealView Debugger examines the
breakpoint units starting with the last one you specified.
When the condition for the last breakpoint unit (breakpoint
unit N) is met, the associated actions are performed and the
previous breakpoint is enabled (breakpoint unit N-1).
RealView Debugger continues processing all remaining
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-79
RealView Debugger Commands
breakpoints in the chain, until the condition in the first one
you specified is met (breakpoint unit 1). At this point, unless
the continue qualifier is specified in that breakpoint,
execution stops.
For example, you might have three breakpoint units in a
chain, which you specify in the following order:
BREAKREAD,hw_and:{then-next},continue 0x10014 (BPU1)
BREAKREAD,hw_and:{then-prev} 0x10018 (BPU2)
BREAKREAD,hw_and:{then-prev} 0x1001B (BPU3)
In this case, RealView Debugger first checks for a data read
at address 0x1001B (BPU3), then at address 0x10018 (BPU2),
and finally at adress 0x10014 (BPU1). When all conditions
are met, processing continues as instructed by the first
brakpoint in the chain.
If you clear BPU1, then all breakpoints in the chain are cleared.
If you clear any other breakpoint unit, then that breakpoint unit
and the following ones are cleared. The previous breakpoint units
remain set. For example, clearing BPU2, clears both BPU2 and
BPU3, but not BPU1.
hw_dhigh:(n)
Specifies the high data value for a data-range breakpoint. The low
data value is specified by the hw_dvalue qualifier.
This facility is not supported by ARM EmbeddedICE macrocells.
For example, this command sets a breakpoint that activates for any
data value between 0x00-0x18:
BREAKREAD,hw_dvalue:0x0,hw_dhigh:0x18 0x1000
hw_dmask:(n)
Specifies the data value mask value for a data-range breakpoint.
Data values that match the value specified by the hw_dvalue
qualifier when masked with this value cause the breakpoint to
activate.
This facility is supported by ARM EmbeddedICE macrocells. For
example, this command sets a breakpoint that activates for any
data value between 0x400-0x4FF:
BREAKREAD,hw_dvalue:0x400,hw_dmask:0xF00 0x1FA00
hw_dvalue:(n)
Specifies a data value to be compared to values transmitted on the
processor data bus.
This facility is supported by ARM EmbeddedICE macrocells. For
example, this command sets a breakpoint that activates for the
data value 0x400:
2-80
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
BREAKREAD,hw_dvalue:0x400 0x1FA00
hw_in:{s}
Input trigger tests. The string that follows matches
hardware-supported input tests as a list of names or a value. The
available tests depends on the Target Access and the target
processor.
Table 2-18 shows the possible strings for an ARM940T processor.
Table 2-18 Example hw_in test strings for an ARM940T
Input test string
Meaning
No "Ext=level" string
Ignore external
trigger level
Ext=0x00000001
Low
Ext=0x00000002
High
No "Mode=mode" string
Any mode
Mode=0x00000004
Privileged
Mode=0x00000008
User
No "AccessSize=size"
string
Default access
size
AccessSize=0x00000100
8-bit
AccessSize=0x00000200
16-bit
AccessSize=0x00000300
32-bit
AccessSize=0x00000400
8/16-bit
AccessSize=0x00000500
8/32-bit
For example, you might have a connection to an ARM940T
processor through the RealView-ICE Target Access. For this
processor, to test for a low external trigger level and a 32-bit data
read in User mode from address 0x10014, enter:
BREAKREAD,hw_in:"Ext=0x00000002",hw_in:"Mode=0x00000008",hw_
in:"AccessSize=0x00000300" 0x10014
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-81
RealView Debugger Commands
hw_not:{s}
Use this qualifier to invert the sense of an address, data, or hw_and
term specified in the same command. The argument s can be set
to:
addr
Invert the breakpoint address value.
data
Invert the breakpoint value.
then
Invert an associated hw_and:{then} condition.
For example, to break when a data value does not match a mask,
you can write:
BREAKREAD,hw_not:data,hw_dmask:0x00FF ...
The break commands require an address value, and the addr
variant of hw_not uses this address.
BREAKREAD,hw_not:addr 0x10040
This means to break at any address other than 0x10040. This
example is probably not useful.
The hw_not:then variant of the command is used in conjunction
with hw_and to form nand and nand-then conditions.
This facility is not supported by ARM EmbeddedICE macrocells.
hw_out:{s}
Not supported in this release.
hw_passcount:(n)
Specifies the number of times that the break condition is ignored
before the breakpoint activates. The default value is 0. This
qualifier differs from passcount only in that it is implemented in
hardware. Although n is limited to a 32-bit value by the debugger,
it might be much more limited by the target hardware, for example
to 8 or 16 bits.
You can combine the hardware and software pass counts to
achieve higher count values. However, the behavior depends on
your processor (see Combining hardware and software pass
counts on page 2-76).
macro:{MacroCall(arg1,arg2)}
When the breakpoint is hit, the specified macro is executed. Any
program variables or functions must be in scope at the time the
breakpoint request is entered, or the names must be fully qualified.
You must include the braces { and }.
2-82
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
message:{"$windowid | fileid$message"}
Activation of the breakpoint results in message being output.
Prefixing message with $windowid | fileid$ enables you to write
the message text to a user-defined window or file. See Window
and file numbers on page 1-5 for details. For example:
breakread,message:{"$100$this is a message"}
modify:(n)
Instead of creating a new breakpoint, modify the breakpoint with
breakpoint list index number n (see The breakpoint list index
number on page 2-76). The address expression and the qualifiers
of the existing breakpoint are replaced by those specified in this
command.
obj:(n)
This condition is True if the argument n matches the C++ object
pointer, normally called this.
passcount:(n)
Specifies the number of times that the break condition is ignored
before the breakpoint activates. The default value is 0. If you
specify this in the middle of a sequence of break conditions, those
specified before the pass count are processed whether or not the
count reaches zero. The conditions specified afterwards are run
only when the count reaches zero.
There is a hardware pass count qualifier available, hw_passcount,
for debug hardware that supports it. You can combine the
hardware and software pass counts to achieve higher count values.
However, the behavior depends on your processor (see Combining
hardware and software pass counts on page 2-76).
Note
If a hardware breakpoint uses a passcount, the counting is
performed on the host, and so program execution stops briefly
every time the breakpoint is hit, even when the count has not been
reached.
size:n
Set the size of the breakpoint to either 16 or 32 bits. For example:
BREAKREAD,size:32 0x10040
Use this qualifier if no debug information is available for your
image. By default, RealView Debugger sets a 32-bit breakpoint.
update:{"name"}
ARM DUI 0175H
Update the named windows, or all windows, by reading the
memory and processor state when the breakpoint activates. You
can use the name all to refresh all windows, or a name specified
in the title bar of the window.
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-83
RealView Debugger Commands
This qualifier enables you to get an overview of the process state
at a particular point, without having to manually restart the
process at each break. The update still takes a significant period of
time, and so this method is unsuitable as a non-intrusive
debugging tool.
when:{condition}
The breakpoint activates whenever condition, a debugger
expression, evaluates to True.
Note
Using a macro as an argument to when, reverses the sense of the
return value from the macro.
when_not:{condition}
The breakpoint activates whenever condition, a debugger
expression, evaluates to False.
Examples
The following examples show how to use BREAKREAD:
BREAKREAD 0x8000
Stop program execution if a read occurs at location 0x8000.
BREAKREAD 0x100..0x200
Stop program execution if a read occurs in the 257 bytes from
0x100-0x200 (inclusive).
Alias
BREAD is an alias of BREAKREAD.
See also
The following commands provide similar or related functionality:
•
BREAKACCESS on page 2-45
•
BREAKEXECUTION on page 2-56
•
BREAKINSTRUCTION on page 2-67
•
BREAKWRITE on page 2-85
•
CLEARBREAK on page 2-104
•
DTBREAK on page 2-147
•
ENABLEBREAK on page 2-162
•
VMACRO on page 2-365.
2-84
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.18
BREAKWRITE
The BREAKWRITE command sets a hardware breakpoint that activates when a write
operation is performed on any of the specified memory locations.
See the chapter that describes setting breakpoints in the RealView Debugger v3.0 User
Guide for full details on the use of breakpoints in RealView Debugger.
Syntax
BREAKWRITE [,qualifier...] {address | address-range} [; macro-call]
where:
qualifier
Is an ordered list of zero or more qualifiers. The possible qualifiers are
described in List of qualifiers on page 2-88.
address | address-range
Specifies a single address in target memory, or an address range. The
address can also be a memory mapped register (see Memory mapped
registers on page 2-86). For details on how to specify an address range,
see Specifying address ranges on page 2-2.
macro-call
Specifies a macro and any parameters it requires. The macro runs when
the breakpoint is hit and before the instruction at the breakpoint is
executed. The macro is treated as being specified last in the qualifier list.
If the macro returns a nonzero value, or you specified continue in the
qualifiers, execution continues. If the macro returns a zero value, or if you
do not specify a macro, target execution stops and the debugger waits in
command mode.
The macro argument symbols are interpreted when the breakpoint is
specified and so they must be in scope at that point, or you must explicitly
qualify them.
Description
BREAKWRITE is used to set or modify data write breakpoints. Data write breakpoints
activate when data that matches a condition is written to memory at a particular address
or address range. If the command has no arguments, it behaves like DTBREAK on
page 2-147, listing the current breakpoints.
Hardware address breakpoints can use other hardware tests in association with the
address test, such as trigger inputs and outputs, hardware pass counters, and and-then,
or chained, tests (see Qualifiers that define hardware tests on page 2-88).
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-85
RealView Debugger Commands
You can use qualifiers evaluated in the debugger, such as expressions, macros, C++
object tests, and software pass counters. You can also define actions to occur when the
breakpoint activates, including updating counters or windows, and the enabling or
disabling of other breakpoints (see List of qualifiers on page 2-88).
If you do not specify an address, the write breakpoint is set at the address defined by the
current value of the PC. The breakpoint is hit if the target program writes data to any
part of the specified target memory area.
When a hardware data write breakpoint is hit on the target, the following sequence of
events occurs:
1.
The debugger or the hardware associates the event with a specific debugger
breakpoint ID.
2.
If the breakpoint has a software pass count associated with it, the count is updated.
3.
The conditions for this breakpoint, if any, are tested in the order specified on the
command line (see Qualifiers that define conditional breakpoints on page 2-88).
If any condition is False, target execution resumes with the instruction at the
breakpointed location. Macros specified with the macro: qualifier or the
;macro-call argument are run in this phase.
4.
If the breakpoint has actions associated with it (for example, using timed to note
the time the breakpoint occurred) these actions are run, in the order specified on
the command line (see Qualifiers that define breakpoint actions on page 2-88).
5.
If the qualifiers include continue, target execution resumes with the instruction at
the breakpointed location. If not, the debugger updates the state of the GUI and
waits for a command, leaving the application halted.
If you are debugging multiprocessor applications, and you have set up synchronization
and cross-triggering, then you can specify how each processor is affected when a
breakpoint activates. For full details, see the chapter that describes debugging multiple
targets in the RealView Debugger v3.0 User Guide.
Memory mapped registers
You can set a breakpoint that activates on a write to a memory-mapped register. To
specify a memory mapped register, enter the following expression for the address:
register:expression
The register is identified by expression. For example:
BREAKWRITE register:PR1
or
2-86
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
BREAKWRITE register:@PR1
For more details about memory mapped registers, see the RealView Debugger v3.0
Target Configuration Guide.
Note
You can only specify memory mapped registers that are defined in either the
connection-level settings or a Board/Chip Definition (.bcd) file that you have assigned
to the connection. You cannot set breakpoints on core registers.
Combining hardware and software pass counts
You can combine hardware and software pass counts to achieve higher count values. If
you define both hardware and software pass counts:
1.
2.
When the hardware pass count reaches zero, the software pass count is
decremented. What happens next depends on your hardware:
•
For RVISS, the hardware count remains at zero, so that
total count = hw_passcount + passcount
•
Other processors, such as DSPs, might exhibit the RVISS behaviour, or
might reset the hardware pass count to the initial value, so that:
total count = (hw_passcount +1) * passcount + hw_passcount
When the software pass count reaches zero, the breakpoint activates.
The breakpoint list index number
RealView Debugger assigns a breakpoint list index number to each breakpoint. This
number is assigned consecutively. However, if you delete a breakpoint, then the
numbering might no longer be consecutive.
To determine the breakpoint list index of an existing breakpoint:
1.
Start RealView Debugger in GUI mode.
2.
Select View → Break/Tracepoints to display the Break/Tracepoint pane.
3.
Click the checkbox for the chosen breakpoint to disable it.
4.
Click the Cmd tab in the Output pane.
The breakpoint list index (number) for the breakpoint is shown in the command:
disable,h number
5.
ARM DUI 0175H
Click the checkbox for the chosen breakpoint to enable it.
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-87
RealView Debugger Commands
Qualifiers that define conditional breakpoints
To set up a conditional breakpoint, use one or more of the following condition
qualifiers:
•
macro (or ;macro-call)
•
obj
•
passcount
•
when
•
when_not.
Qualifiers that define breakpoint actions
To specify actions to be performed when a breakpoint activates, use the following action
qualifiers:
•
continue
•
message
•
update.
Qualifiers that define hardware tests
To specify hardware tests for data write breakpoints, use the following qualifiers:
•
data_only
•
hw_ahigh
•
hw_amask
•
hw_and
•
hw_dhigh
•
hw_dmask
•
hw_dvalue
•
hw_in
•
hw_not
•
hw_passcount.
List of qualifiers
The list of qualifiers depends on the processor and Target Access, and so the GUI does
not present things that do not make sense. The command handler generates an error if a
specific combination is invalid for a specific processor or Target Access, but this is
determined when you issue the command.
2-88
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
The possible qualifiers are:
append:(n)
Instead of creating a new breakpoint, append the qualifiers
specified with this command to an existing breakpoint with
breakpoint list index number n (see The breakpoint list index
number on page 2-87).
Note
You cannot use append to change the breakpoint address or to
create chained breakpoints.
continue
Execution continues when the breakpoint activates and no
breakpoint details are displayed. Any specified action qualifiers
are still performed, depending on the results of any condition
qualifiers.
data_only
The breakpoint activates if a data value, specified using hw_dvalue,
is detected by the debug hardware on the processor data bus.
hw_ahigh:(n)
Specifies the high address for an address-range breakpoint. The
low address is specified by the standard breakpoint address.
This facility is not supported by ARM EmbeddedICE macrocells.
For example, this command sets a breakpoint that activates for any
address between 0x1000-0x1200:
BREAKWRITE,hw_ahigh:0x1200 0x1000
This is equivalent to the command:
BREAKWRITE 0x1000..0x1200
hw_amask:(n)
Specifies the address mask value for an address-range breakpoint.
Addresses that match the standard breakpoint address when
masked with this value cause the breakpoint to activate.
This facility is supported by ARM EmbeddedICE macrocells. For
example, this command sets a breakpoint that activates for any
address between 0x1FA00-0x1FA0F:
BREAKWRITE,hw_amask:0xFFFF0 0x1FA00
This is equivalent to the command:
BREAKWRITE 0x1FA00..0x1FA0F
hw_and:{[then-]id} Perform an and or an and-then conjunction with another
breakpoint, to create a chain of breakpoints. Each breakpoint in
the chain is called a breakpoint unit.You specify the breakpoint
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-89
RealView Debugger Commands
units in the reverse order that RealView Debugger processes them.
The position of the breakpoint unit in the chain is identified by id,
which is one of the following:
next
Indicates that this breakpoint unit is to be linked to
another breakpoint unit specified for this connection.
You must set a breakpoint unit with the ID next before
you set any other breakpoint units for the chain. When
used with then-, this breakpoint unit is the last one
processed in the chain.
prev
Indicates that this breakpoint unit is to be linked to an
existing breakpoint unit specified for this connection.
Make sure the existing breakpoint has been set with a
next, prev, or index_number ID, and is a hardware
breakpoint.
Note
When using the prev ID, you must finish defining the
complete breakpoint chain before you create any
non-chained breakpoints.
index_number
The breakpoint list index number of an existing
breakpoint unit (see The breakpoint list index number
on page 2-47). Make sure the existing breakpoint has
been set with a next, prev, or index_number ID, and is a
hardware breakpoint.
How RealView Debugger processes the breakpoint units depends
on the conjunction you have used:
•
In the and form, the conditions associated with both
breakpoint units are chained together, so that the action
associated with the second breakpoint unit is performed
only when both conditions simultaneously match.
For example:
BREAKWRITE,hw_and:next,hw_dvalue:1
@copyfns\\COPYFNS\mycpy\append
BREAKEXECUTION,hw_and:prev @copyfns\\COPYFNS\mycpy\
•
2-90
In the and-then form, RealView Debugger examines the
breakpoint units starting with the last one you specified.
When the condition for the last breakpoint unit (breakpoint
unit N) is met, the associated actions are performed and the
previous breakpoint is enabled (breakpoint unit N-1).
RealView Debugger continues processing all remaining
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
breakpoints in the chain, until the condition in the first one
you specified is met (breakpoint unit 1). At this point, unless
the continue qualifier is specified in that breakpoint,
execution stops.
For example, you might have three breakpoint units in a
chain, which you specify in the following order:
BREAKWRITE,hw_and:{then-next},continue 0x10014 (BPU1)
BREAKWRITE,hw_and:{then-prev} 0x10018 (BPU2)
BREAKWRITE,hw_and:{then-prev} 0x1001B (BPU3)
In this case, RealView Debugger first checks for a data write
at address 0x1001B (BPU3), then at address 0x10018 (BPU2),
and finally at adress 0x10014 (BPU1). When all conditions
are met, processing continues as instructed by the first
brakpoint in the chain.
If you clear BPU1, then all breakpoints in the chain are cleared.
If you clear any other breakpoint unit, then that breakpoint unit
and the following ones are cleared. The previous breakpoint units
remain set. For example, clearing BPU2, clears both BPU2 and
BPU3, but not BPU1.
hw_dhigh:(n)
Specifies the high data value for a data-range breakpoint. The low
data value is specified by the hw_dvalue qualifier.
This facility is not supported by ARM EmbeddedICE macrocells.
For example, this command sets a breakpoint that activates for any
data value between 0x00-0x18:
BREAKWRITE,hw_dvalue:0x0,hw_dhigh:0x18 0x1000
hw_dmask:(n)
Specifies the data value mask value for a data-range breakpoint.
Data values that match the value specified by the hw_dvalue
qualifier when masked with this value cause the breakpoint to
activate.
This facility is supported by ARM EmbeddedICE macrocells. For
example, this command sets a breakpoint that activates for any
data value between 0x400-0x4FF:
BREAKWRITE,hw_dvalue:0x400,hw_dmask:0xF00 0x1FA00
hw_dvalue:(n)
Specifies a data value to be compared to values transmitted on the
processor data bus.
This facility is supported by ARM EmbeddedICE macrocells. For
example, this command sets a breakpoint that activates for the
data value 0x400:
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-91
RealView Debugger Commands
BREAKWRITE,hw_dvalue:0x400 0x1FA00
hw_in:{s}
Input trigger tests. The string that follows matches
hardware-supported input tests as a list of names or a value. The
available tests depends on the Target Access and the target
processor.
Table 2-19 shows the possible strings for an ARM940T processor.
Table 2-19 Example hw_in test strings for an ARM940T
Input test string
Meaning
No "Ext=level" string
Ignore external
trigger level
Ext=0x00000001
Low
Ext=0x00000002
High
No "Mode=mode" string
Any mode
Mode=0x00000004
Privileged
Mode=0x00000008
User
No "AccessSize=size"
string
Default access
size
AccessSize=0x00000100
8-bit
AccessSize=0x00000200
16-bit
AccessSize=0x00000300
32-bit
AccessSize=0x00000400
8/16-bit
AccessSize=0x00000500
8/32-bit
For example, you might have a connection to an ARM940T
processor through the RealView-ICE Target Access. For this
processor, to test for a low external trigger level and a 32-bit data
write in User mode to address 0x10014, enter:
BREAKWRITE,hw_in:"Ext=0x00000002",hw_in:"Mode=0x00000008",hw
_in:"AccessSize=0x00000300" 0x10014
2-92
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
hw_not:{s}
Use this qualifier to invert the sense of an address, data, or hw_and
term specified in the same command. The argument s can be set
to:
addr
Invert the breakpoint address value.
data
Invert the breakpoint value.
then
Invert an associated hw_and:{then} condition.
For example, to break when a data value does not match a mask,
you can write:
BREAKWRITE,hw_not:data,hw_dmask:0x00FF ...
The break commands require an address value, and the addr
variant of hw_not uses this address.
BREAKWRITE,hw_not:addr 0x10040
This means to break at any address other than 0x10040. This
example is probably not useful.
The hw_not:then variant of the command is used in conjunction
with hw_and to form nand and nand-then conditions.
This facility is not supported by ARM EmbeddedICE macrocells.
hw_out:{s}
Not supported in this release.
hw_passcount:(n)
Specifies the number of times that the break condition is ignored
before the breakpoint activates. The default value is 0. This
qualifier differs from passcount only in that it is implemented in
hardware. n is limited to a 32-bit value by the debugger, but might
be much more limited by the target hardware, for example to 8 or
16 bits.
You can combine the hardware and software pass counts to
achieve higher count values. However, the behavior depends on
your processor (see Combining hardware and software pass
counts on page 2-87).
macro:{MacroCall(arg1,arg2)}
When the breakpoint is hit, the specified macro is executed. Any
program variables or functions must be in scope at the time the
breakpoint request is entered, or the names must be fully qualified.
You must include the braces { and }.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-93
RealView Debugger Commands
message:{"$windowid | fileid$message"}
Activation of the breakpoint results in message being output.
Prefixing message with $windowid | fileid$ enables you to write
the message text to a user-defined window or file. See Window
and file numbers on page 1-5 for details. For example:
BREAKWRITE,message:{"$100$this is a message"}
modify:(n)
Instead of creating a new breakpoint, modify the breakpoint with
breakpoint list index number n (see The breakpoint list index
number on page 2-87). The address expression and the qualifiers
of the existing breakpoint are replaced by those specified in this
command.
obj:(n)
This condition is True if the argument n matches the C++ object
pointer, normally called this.
passcount:(n)
Specifies the number of times that the break condition is ignored
before the breakpoint activates. The default value is 0. If you
specify this in the middle of a sequence of break conditions, those
specified before the pass count are processed whether or not the
count reaches zero. The conditions specified afterwards are run
only when the count reaches zero.
There is a hardware pass count qualifier available, hw_passcount,
for debug hardware that supports it. You can combine the
hardware and software pass counts to achieve higher count values.
However, the behavior depends on your processor (see Combining
hardware and software pass counts on page 2-87).
Note
If a hardware breakpoint uses a passcount, the counting is
performed on the host, and so program execution stops briefly
every time the breakpoint is hit, even when the count has not been
reached.
size:n
Set the size of the breakpoint to either 16 or 32 bits. For example:
BREAKWRITE,size:32 0x10040
Use this qualifier if no debug information is available for your
image. By default, RealView Debugger sets a 32-bit breakpoint.
update:{"name"}
2-94
Update the named windows, or all windows, by reading the
memory and processor state when the breakpoint activates. You
can use the name all to refresh all windows, or a name specified
in the title bar of the window.
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
This qualifier enables you to get an overview of the process state
at a particular point, without having to manually restart the
process at each break. The update still takes a significant period of
time, and so this method is unsuitable as a non-intrusive
debugging tool.
when:{condition}
The breakpoint activates whenever condition, a debugger
expression, evaluates to True.
Note
Using a macro as an argument to when, reverses the sense of the
return value from the macro.
when_not:{condition}
The breakpoint activates whenever condition, a debugger
expression, evaluates to False.
Examples
The following examples show how to use BREAKWRITE:
BREAKWRITE 0x8000
Stop program execution if the program writes to location 0x8000.
BREAKWRITE 0x1100..0x1200
Stop program execution if the program writes to the 257 bytes
from 0x1100-0x1200 (inclusive).
BREAKWRITE 0x1100..0x1200 ; CheckMem(0x100)
Stop program execution if the program writes to the 257 bytes
from 0x1100-0x1200 (inclusive) and calls the macro CheckMem with
the base address 0x100.
Alias
BWRITE is an alias of BREAKWRITE.
See also
The following commands provide similar or related functionality:
•
BREAKACCESS on page 2-45
•
BREAKEXECUTION on page 2-56
•
BREAKINSTRUCTION on page 2-67
•
BREAKREAD on page 2-74
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-95
RealView Debugger Commands
•
•
•
•
2-96
CLEARBREAK on page 2-104
DTBREAK on page 2-147
ENABLEBREAK on page 2-162
VMACRO on page 2-365.
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.19
BROWSE
The BROWSE command invokes the C++ class browser interface
Syntax
BROWSE symbol
where:
symbol
Specifies a C++ class or structure to be browsed.
Description
Displays the parent class or classes and any child classes for the class you specify. You
can specify the class as either a variable name or the class name.
Examples
The following example shows how to use BROWSE:
browse Shakespeare
Shakespeare
parents
|
children
____________________|____________________
/
\
| baseclass
See also
There are no other commands that provide similar or related functionality.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-97
RealView Debugger Commands
2.3.20
BWRITE
BWRITE is an alias of BREAKWRITE (see page 2-85).
2-98
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.21
CANCEL
The CANCEL command cancels, or interrupts, the execution of commands.
Syntax
CANCEL
Description
The CANCEL command enables you to interrupt, or cancel, an asynchronous command
that the is still executing. It is equivalent to the Cancel toolbar icon. If the target is
running, only commands that can definitely be run with a running target are executed.
Other commands are held in a queue for execution when the target stops. This is called
pending the command. Use the CANCEL command to clear pending commands from the
list, to stop them being executed.
You cannot use this command to halt target execution. Use HALT to do this.
Note
Synchronous commands can only be run when target program execution has stopped.
Asynchronous commands can be run at all times.
See also
The following commands provide similar or related functionality:
•
HALT on page 2-190
•
INTRPT on page 2-196
•
WAIT on page 2-370.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-99
RealView Debugger Commands
2.3.22
CCTRL
The CCTRL command opens and closes the Connection Control window.
Note
This command has no effect when running in command line mode.
Syntax
CCTRL
Description
The CCTRL command enables you to open and close the Connection Control window. If
the Connection Control window is open, then the command closes the window. If the
Connection Control window is closed, then the command opens the window.
2-100
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.23
CEXPRESSION
The CEXPRESSION command calculates and displays the value of an expression. You can
also modify variables using the assignment operator.
Syntax
CEXPRESSION [/R] expression
where:
/R
Suppresses printing of the result, that is the line beginning with the text
Result is:.
expression
A valid debugger expression.
Description
The CEXPRESSION command calculates the value of an expression or assigns a value to a
variable. Debugger expressions are described in more detail in Chapter 1 Working with
the CLI but include target function and procedure calls, debugger macro invocation, and
scalar C languages expressions. You cannot manipulate values larger than 4 bytes, other
than double values, in an expression.
If you use CEXPRESSION to run a target function, it is called using the target resources,
including stack and heap space. The debugger ensures that the core processor registers
are saved before calling the debugger function and restored afterwards. The following
issues must be remembered when calling target application functions:
•
Target function calls must be supported for your processor.
•
You must ensure that the target has initialized those resources that the called
function, and any function it calls, requires.
This normally requires at least that the C runtime code has completed execution
so that the stack and heap are set up.
•
ARM DUI 0175H
If the target function has side effects, for example changing global variables, the
side effects might not be reflected in the original application straight away,
because the compiler might have stored elements of that global state in registers,
or even indirectly in the PC. It is likely that programs compiled with optimization
enabled are more prone to this issue.
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-101
RealView Debugger Commands
Rules
The following rules apply to the use of the CEXPRESSION command:
•
CEXPRESSION runs synchronously if the expression uses target registers, including
the stack pointer, or if it uses target memory and background memory access is
not available.
Use the WAIT command to force it to run synchronously.
•
You must have a valid target execution context before you can run target functions
correctly.
•
Macros take higher precedence than target functions. If a target function and a
macro have the same name, the macro is the one that is executed unless the target
function is qualified.
•
Results are displayed in either floating-point format, address format, or in
decimal, hexadecimal, or ASCII format depending on the type of variables used
in the expression.
•
The ASCII representation is displayed if the expression value is a printable ASCII
character.
•
Floating-point numbers are shown as double by default (14 decimal digits of
precision). They can be cast to float to display 6 decimal digits of precision.
Examples
The following examples show how to use CEXPRESSION:
CEXPRESSION Run_Index
Displays the current value of the variable named Run_Index.
CE /R Run_Index=50 Assigns a value of 50 to the variable named Run_Index, and
suppresses the printing of the result.
CE sin(0.2)
Displays the value of the application function sin(), passing in the
value (double)0.2.
CE @R0 =20h
Writes 0x20 to target register R0. For more details on operations
with registers, see Referencing reserved symbols on page 1-21.
See also
The following commands provide similar or related functionality:
•
ADD on page 2-18
2-102
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
•
•
•
•
•
•
ARM DUI 0175H
DEFINE on page 2-121
DUMP on page 2-153
MACRO on page 2-208
PRINTVALUE on page 2-247
SETMEM on page 2-273
SETREG on page 2-275.
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-103
RealView Debugger Commands
2.3.24
CLEARBREAK
The CLEARBREAK command deletes one or more breakpoints.
Syntax
CLEARBREAK [{breakpoint_number | breakpoint_number_range}]
where:
breakpoint_number
Specifies the breakpoint number to be cleared.
breakpoint_number_range
Specifies a range of breakpoint numbers as two integers separated by the
range operator (..).
Description
This command clears (deletes) the breakpoints you specify, using the position of the
breakpoint in a list of breakpoints to identify the breakpoints to clear.
You can display a list of the currently defined breakpoints using the command DTBREAK
(see page 2-147), and also by displaying the Break/Tracepoints pane in the Code
window.
When specifying a range of breakpoints, you can either specify the end of the range as
an absolute position, or you can specify the number of breakpoints to delete by typing
a plus sign followed by the number of breakpoints. For example: +3 indicates three
breakpoints.
To delete all breakpoints, use CLEARBREAK with no parameters.
CLEARBREAK runs synchronously.
Note
You can disable a breakpoint, so that the breakpoint is unset but remembered by the
debugger, using the DISABLEBREAK command. You can enable breakpoints that you have
disabled, so setting them on the target again, using the ENABLEBREAK command.
Examples
2-104
CL
Clears every breakpoint.
CL 5
Clears the breakpoint listed fifth in the current list of breakpoints.
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
CL 5..7
Clears the fifth, sixth, and seventh breakpoints in the current list.
CL 5..+3
Clears the fifth, sixth, and seventh breakpoints in the current list.
See also
The following commands provide similar or related functionality:
•
BREAKACCESS on page 2-45
•
BREAKEXECUTION on page 2-56
•
BREAKINSTRUCTION on page 2-67
•
BREAKREAD on page 2-74
•
BREAKWRITE on page 2-85
•
DISABLEBREAK on page 2-131
•
DTBREAK on page 2-147
•
ENABLEBREAK on page 2-162.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-105
RealView Debugger Commands
2.3.25
COMPARE
The COMPARE command compares two blocks of memory and displays the differences.
Syntax
COMPARE [/R] [address-range, address]
where:
Instructs the debugger to continue comparing and displaying mismatches
until either the end of the block is reached or you press CTRL-Break to
abort the operation.
/R
address-range
Specifies the address range to be compared using two addresses separated
by the range operator (..). See Specifying address ranges on page 2-2 for
details on how to specify an address range.
address
Specifies the starting address of the block of memory to use as a
comparison.
Description
A specified block of memory is compared to a block of the same size starting at a
specified location.
Mismatched addresses and values are displayed. If you are using the GUI, then they are
displayed in the Output pane. Entering the command again at this point without
parameters continues the process starting with the first byte after the mismatch.
If the contents of the two blocks of memory are the same, the debugger displays the
message:
Memory blocks are the same.
COMPARE runs synchronously unless background access to target memory is supported.
Use the WAIT command to force it to run synchronously.
2-106
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
Examples
The following examples show how to use COMPARE:
com 0x8100..0x82FF,0x8700
Compares the contents of memory from 0x8100 to 0x82FF with the
contents of memory from 0x8700 to 088FF, stopping at the first
mismatch.
com/r 0x8100..0x81FF,0x8700
Compares the contents of memory from 0x8100 to 0x81FF with the
contents of memory from 0x8700 to 087FF, displaying all the
differences found.
com/r 0x8100..+512,0x8700
Compares the contents of memory from 0x8100 to 0x81FF with the
contents of memory from 0x8700 to 088FF, displaying all the
differences found.
See also
The following commands provide similar or related functionality:
•
COPY on page 2-115
•
FILL on page 2-173
•
MEMWINDOW on page 2-214
•
TEST on page 2-305
•
VERIFYFILE on page 2-362.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-107
RealView Debugger Commands
2.3.26
CONNECT
The CONNECT command is used to connect the debugger to a specified target.
Syntax
CONNECT [{,reset|,noreset}] [{,halt|,nohalt}] [=] @targetname
CONNECT [,gui] [=] @targetname
where:
reset
Reset the target before connecting to it.
noreset
Do not reset the target on connecting to it.
halt
Stop the target on connecting to it.
nohalt
Do not stop the target on connecting to it.
targetname
Specifies the required Target Access or target device. See:
•
Opening the Target Access on page 2-110
•
Connecting to the target device on page 2-110
•
Making connections with a single command on page 2-111
•
RealView Simulator Broker connections on page 2-111.
gui
Enables you to choose the connect mode from a dialog or prompt:
•
If you use this option when running in GUI mode, it displays a
dialog.
•
If you use this option when running in command line mode, it
displays a prompt.
The connect specifies what state you want the debugger to leave the target
in after the connection. See Connect modes on page 2-109 for more
details.
Description
The CONNECT command creates a new target connection. The details of the connection
are specified using the board file. To connect to a target you indicate which target in the
board file you want to connect to, using the identifier string.
Using the CONNECT command means that you do not use the Connection Control window
(shown in Figure 2-2 on page 2-109). However, it is helpful to think of that window
when considering the operation of the CONNECT command.
2-108
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
Figure 2-2 Connection Control window
Note
If you set the connect mode in the board (.BRD) file of the target the target connects using
that mode. If you specify prompt for the connect mode, then the CONNECT command acts
as though you specified the ,gui qualifier. See the RealView Debugger v3.0 Target
Configuration Guide for more details. The reset, noreset, halt, and nohalt qualifiers
override the connect mode setting in the board file.
Connect modes
When you connect to a target, the connect mode determines what happens to the target:
No Reset and Stop (,noreset,halt)
Connect to the target, but do not reset it. If the target is running, stop it.
This is the default.
No Reset and No Stop (,noreset,nohalt)
Connect to the target, but do not reset it. The running state of the target is
unchanged.
Reset and Stop (,reset,halt)
Connect to the target, and reset it. If the target is running after the reset,
stop it.
Reset and No Stop (,reset,nohalt)
Connect to the target, and reset it. The running state of the target is
unchanged.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-109
RealView Debugger Commands
Note
The connect modes available depend on the Target Access you are using.
Opening the Target Access
To open a Target Access, you enter the Target Access name with an @ prefix, for
example:
connect @RealView-ICE
This command opens the Target Access and expands it in the Connection Control
window. (Entering the same command again closes the Target Access and collapses it.)
Specify the Target Access name as defined in the board file, that is as it appears in the
Connection Control window, as shown in these examples:
connect @RealView-ICE
connect @Remote_A
connect @localhost
Note
If you specify a target that has not been configured, you are prompted to configure the
target before the Target Access can be opened (see the RealView Debugger v3.0 Target
Configuration Guide for more details).
Connecting to the target device
After you have opened the Target Access you can connect to the target target using the
command:
connect @target_device
For example:
connect @ARM940T_0
The target name includes a numerical suffix. If there is more than one target configured
for a Target Access, then the number reflects the order on the JTAG scan chain for
hardware targets.
If you have opened more than one Target Access, and both provide access to targets with
the same name (for example, ARM940T_0), then the debugger connects to the target for the
first Target Access that you opened.
2-110
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
Making connections with a single command
You can use connect to a target where the Target Access is not currently opened using
a single command:
connect @[email protected]
For example:
connect @[email protected]
This command connects to the ARM940T_0 device, expecting this to be available when the
RealView-ICE Target Access is opened. If the Target Access, in this case RealView-ICE,
has not been configured with an ARM940T_0, the connection fails with the message Types
of objects in list do not match. You must correctly configure the Target Access before
you connect to the target device.
RealView Simulator Broker connections
A RealView Simulator Broker connection enables you to connect multiple simulated
target. For example, new_arm enables you to connect to RVISS. When you connect to a
RealView Simulator Broker connection, a new target connection is created.
If you connect to new_arm, a Simarm_n connection is created, where n is a number to
ensure the new target connection name is unique, and starts at zero. For example, create
two connections using new_arm:
connect @new_arm
connect @new_arm
The connection Simarm_0 and Simarm_1 are created.
To disconnect from these connections, you can use the commands:
disconnect @Simarm_0
disconnect @Simarm_1
If you disconnect a Simarm_n connection, then create a new Simarm_n connection in the
same debugging session, then the next highest number is assigned to the new
connection. For example, connect and disconnect using the following command
sequence:
connect @new_arm
connect @new_arm
disconnect @Simarm_0
disconnect @Simarm_1
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-111
RealView Debugger Commands
The next connection you make is given the name Simarm_2. When you exit RealView
Debugger, the next time you start RealView Debugger it begins numbering the
connections from zero.
See also
The following commands provide similar or related functionality:
•
BOARD on page 2-41
•
DISCONNECT on page 2-136
•
EDITBOARDFILE on page 2-158
•
RESTART on page 2-263
•
RUN on page 2-266
•
SYNCHEXEC on page 2-303
•
XTRIGGER on page 2-379.
2-112
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.27
CONTEXT
The CONTEXT command displays the current context.
Syntax
CONTEXT [/F]
where:
Displays all contexts (roots).
/F
Description
The CONTEXT command displays the current context. If you are using the GUI, then the
context is displayed in the Output pane. The context includes the current root, module,
procedure, and line. The context must be in a module with high-level debug information
for the line number to be displayed.
If the context is at the PC, then the text At the PC: is displayed.
If you have changed scope to a location other than that pointed to by the PC, then the
text Scoped to: is displayed.
CONTEXT runs asynchronously unless it is run in a macro.
Examples
The following example shows how to use CONTEXT using the dhrystone application:
> context
At the PC: (0x00008000): ENTRY\__main
Source view: DHRY_1\main Line 78
This demonstrates the case where the PC and the current source view do not correspond.
In this case, the editor is displaying the beginning of the function main() at line 78, while
the pc is at location 0x8000 in the __main(), the routine that calls main().
The following example sets a breakpoint in main() and runs to that breakpoint:
> bi \DHRY_1\#98:0
> go
Stopped at 0x000084D0 due to SW Instruction Breakpoint
Stopped at 0x000084D0: DHRY_1\main Line 98
> con
At the PC: (0x000084D0): DHRY_1\main Line 98
Now the PC and the source view are synchronized, the form of the message changes.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-113
RealView Debugger Commands
Finally, the /F form, of CONTEXT displays the Root: specification shown in the following
example (see Chapter 1 Working with the CLI for more information on root context
specifications):
> CONTEXT/F
At the PC: (0x000084D0): DHRY_1_1\DHRY_1_C\main Line 98
Root: @dhrystone\\ [SCOPE]
See also
The following commands provide similar or related functionality:
•
DOWN on page 2-143
•
PRINTSYMBOLS on page 2-242
•
SCOPE on page 2-268
•
SETREG on page 2-275
•
UP on page 2-359.
2-114
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.28
COPY
The COPY command copies a region of memory.
Syntax
COPY addressrange, targetaddr
where:
addressrange Specifies the address range to be copied.
targetaddr
Specifies the starting address where the copied memory is placed.
Description
The COPY command copies the contents of a specified block of memory to a block of the
same size starting at a specified location.
The command copies data from low address to high addresses, without taking account
of overlapping source and destination memory regions. You must not rely on this
behavior in future versions of the debugger.
COPY runs synchronously unless background access to target memory is supported. Use
the WAIT command to force it to run synchronously.
Examples
The following examples show how to use COPY:
copy 0x8100..0x81FF,0x8700
Copies the contents of memory at 0x8100 to 0x81FF to memory at 0x8700
to 087FF.
copy 0x8100..+128,0x8700
Copies the contents of memory at 0x8100 to 0x817F to memory at 0x8700
to 0877F.
See also
The following commands provide similar or related functionality:
•
COMPARE on page 2-106
•
FILL on page 2-173
•
LOAD on page 2-202
•
READFILE on page 2-253
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-115
RealView Debugger Commands
•
•
2-116
TEST on page 2-305
SETMEM on page 2-273.
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.29
DBOARD
DBOARD is an alias of DTBOARD (see page 2-146).
2.3.30
DBREAK
DBREAK is an alias of DTBREAK (see page 2-147).
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-117
RealView Debugger Commands
2.3.31
DCOMMANDS
The DCOMMANDS command lists the commands available based on the Target Access,
target processor, and type of connection.
Syntax
DCOMMANDS [{,full | ,alias}] [,cmd_class...] [{;windowid | ;fileid}]
DCOMMANDS [{,full | ,alias}] =specific_cmd [{;windowid | ;fileid}]
where:
cmd_class
Specifies a class of commands to have details displayed, and can be any
of the following:
status or display
to list status and display commands
setstatus or ss
to list setstatus commands
breakcomplex or bc
to list breakcomplex commands
If no command class is specified, all of the commands known to
DCOMMANDS are described.
alias
Show a summary of names and aliases for the specified command class.
full
Show more detailed information on the specified command class.
specific_cmd Specifies a particular command to display, or all to display all commands
known to DCOMMANDS.
;windowid | ;fileid
Identifies the window or file where the command is to send the output.
See Window and file numbers on page 1-5 for details.
If you do not supply a ;windowid or ;fileid parameter, output is displayed
on the screen. If you are using the GUI, then the output is displayed in the
Output pane.
Description
The DCOMMANDS command displays the list of commands supported by the current target.
The optional command class qualifier enables you to display one or more specific
classes of commands. The specific_cmd argument shows a specified command. The
full qualifier provides extended detail on the command.
2-118
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
Note
Some commands are not listed in the DCOMMANDS command list, and DCOMMANDS reports
that these commands are unknown if you request help with the specific_cmd argument.
This is a limitation of the current implementation of the help system and does not
indicate a fault in the operation of the commands.
Examples
The following examples show the use of DCOMMANDS. The first command displays a
summary of all status commands that are available on the current target:
> dcom,status =all
dcommands [{,cmd_classes...}] [=specific_cmd] [;viewport]
or dhelp
[{,cmd_classes...}] [=specific_cmd] [;viewport]
dtboard [={resource,...}] [;viewport]
or dboard
[={resource,...}] [;viewport]
dtprocess [={task,...}] [;viewport]
or dvprocess [={task,...}] [;viewport]
dtfile
[={value,...}] [;viewport]
or dvfile
[={value,...}] [;viewport]
or dmap
[={value,...}] [;viewport]
dtbreak [={threads,...}] [;viewport]
or dbreak
[={threads,...}] [;viewport]
Note
;viewport in the command syntax can be either ;windowid or ;fileid.
This command displays a more complete summary of the XTRIGGER command:
> dcom,full xtrig
xtrigger [{,qualifier...}] [={boards,...}]
Qualifiers:
in_disable
in_enabl
eout_disable
out_enable
onhost
This command is used to set the cross-triggering state of the selected
boards. This can be used to control what happens when any board stops. It
will be implemented using hardware when possible but can be forced to use
software (on host) methods.
Alias
DHELP is an alias of DCOMMANDS.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-119
RealView Debugger Commands
See also
The following commands provide similar or related functionality:
•
HELP on page 2-191
•
SHOW on page 2-284.
2-120
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.32
DEFINE
The DEFINE command creates a macro for use by other RealView Debugger components.
Note
Because a macro definition requires multiple lines, you cannot use the DEFINE command
from the RealView Debugger command prompt. Instead, you must either:
•
Use the macro command GUI. See the macros chapter in the RealView Debugger
v3.0 User Guide for more information.
•
Write your macro definition in a text file and load it into RealView Debugger
using the INCLUDE command (see Macro language on page 1-10).
Syntax
DEFINE [/R] [return_type] macro_name ([parameters])[parameter_definitions] {
macro_body} .
where:
/R
The new macro can replace an existing symbol with the same name.
return_type
Specifies the return type of the macro. If a type is not specified,
return_type defaults to type int.
macro_name
Specifies the name of the macro.
parameters
Lists parameters (comma-separated list within parentheses). These
parameters can be used throughout the macro definition and are later
replaced with the values of the actual parameters in the macro call.
param_definitions
Defines the types of the variables in parameter_list. If types are not
specified, the default type int is assumed.
macro_body
Represents the contents of the macro, and is split over many lines. The
syntax for macro_body is:
[local_definitions]
macro_statement;[macro_statement;] ...
local_definitions are the variables used within the macro_body.
A macro_statement is any legal C statement except switch and goto
statements, or a debugger command. If macro_statement is a debugger
command, it must start with a dollar sign ($) and end with a dollar sign
and a semicolon ($;). All statements are terminated by a semicolon.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-121
RealView Debugger Commands
The macro_body ends with a line containing only a period (full stop).
Description
The definition contains a macro name, the parameters passed to the macro, the source
lines of the macro, and a terminating period as the first and only character on the last
line.
After a macro has been loaded into RealView Debugger, the definition is stored in the
symbol table. If the symbol table is recreated, for example when an image is loaded with
symbols, any macros are automatically deleted. The number of macros that can be
defined is limited only by the available memory on your workstation.
Macros can be invoked by name on the command line where the name does not conflict
with other commands or aliases and the return value is not required. You can also invoke
a macro on the command line using the MACRO command, and in expressions, for
example using the CEXPRESSION command.
Macros can also be invoked as actions associated with:
•
a window, for example VMACRO
•
the GO and GOSTEP commands
•
a breakpoint, for example BREAKEXECUTION
•
deferred commands, for example BGLOBAL.
Note
Macros invoked as associated actions cannot execute GO, or GOSTEP, or any of the
stepping commands, for example STEPINSTR.
If you require a breakpoint that, when the condition is met, does something and then
continues program execution, you must use the breakpoint continue qualifier, or return
1 from the macro call, instead of the GO command. See the breakpoint command
descriptions for more details.
Examples
The following examples show how to use DEFINE:
define float square(f)
float f;
{
return (f*f);
}
.
2-122
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
define show_i()
{
int i;
i = 10;
$printf "value of i = %d\n", i$;
return (1);
}
.
define /R int userPrompt()
{
char userPromptBuffer[100];
int retval;
retval = prompt_text( "Please enter text", userPromptBuffer );
if (retval == 0) {
$printf "Clicked OK\n"$;
$printf "%s\n", userPromptBuffer$;
} else
$printf "Clicked Cancel\n"$;
return 1;
}
.
See also
The following commands provide similar or related functionality:
•
ALIAS on page 2-23
•
BGLOBAL on page 2-36
•
BREAKEXECUTION on page 2-56
•
CEXPRESSION on page 2-101
•
GO on page 2-186
•
GOSTEP on page 2-188
•
INCLUDE on page 2-194
•
MACRO on page 2-208.
•
SHOW on page 2-284
•
VMACRO on page 2-365.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-123
RealView Debugger Commands
2.3.33
DELBOARD
The DELBOARD command deletes a board entry from the displayed list.
Syntax
DELBOARD [=resource,...]
where:
resource
Identifies the board that is to have its entry deleted from the list.
Description
Use this command to delete a specified non-connected board entry. If you do not specify
a board, all non-connected board entries are deleted. You supply the number or name of
the board, or 0 for all. This does not affect the file stored on disk, only what is shown.
Example
The following example shows how to use DELBOARD:
delboard =6
This command deletes the connection definition numbered 6, that must be unconnected
when the command is issued. See CONNECT on page 2-108 for more information
about connection numbers. The deleted connection definition becomes available again
when a READBOARDFILE command is issued or the debugger is restarted.
See also
The following commands provide similar or related functionality:
•
BOARD on page 2-41
•
CONNECT on page 2-108
•
EDITBOARDFILE on page 2-158.
2-124
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.34
DELETE
The DELETE command deletes macros or one or more symbols from the symbol table.
Syntax
DELETE {symbol_name | \\ | \ | macroname} [,y]
where:
symbol_name
Specifies the symbol to be removed from the symbol table.
symbol_name\ Deletes the specified symbol and all symbols it owns (its child symbols).
root\\
Deletes all symbols of the specified root.
\\
Deletes all user-defined symbols of the base root.
\
Deletes all symbols of the current root.
macroname
Deletes the specified macro.
y
Specifies that DELETE can delete child symbols if the specified symbol has
them. If this is not done, DELETE prompts for confirmation before deleting
child symbols.
Description
The DELETE command deletes symbols from the symbol table associated with the current
connection. Symbols are entered into the symbol table when an executable file
containing them is loaded onto the connection using LOAD or RELOAD, and when you use
the ADD command.
Deleting a symbol or group of symbols is useful if the program has changed, perhaps as
a result of runtime patching of the executable. To change the memory location of a
symbol such as an address label, you must first delete it and then add it again at the new
location.
You can also use the DELETE command to delete debugger macros that you have created
using the MACRO command.
You cannot use DELETE to delete debugger command aliases. Instead, define the alias to
be nothing:
alias name=
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-125
RealView Debugger Commands
Rules
The following rules apply to the use of the DELETE command:
•
The DELETE command runs asynchronously unless in a macro.
•
All debugging information for that symbol is deleted, but program execution is
unchanged.
Note
If you delete a symbol that is defined by your image, then you cannot perform
various debugging tasks on that symbol, such as setting a breakpoint on that
symbol. You must do a full load of the image to recover the debugging symbols.
•
Only program symbols, macros, and user-defined debugger symbols can be
deleted from the symbol table. Predefined symbols, such as register names,
cannot be deleted.
•
If more than one symbol exists with the same name, then RealView Debugger
displays the error:
Error: E0098: Cannot delete: more than one symbol with this name.
You must specify the full symbol reference to delete it.
For example, if you load a macro called sqr, and you have a function in your
image called sqr, then to delete the macro you must enter:
delete \\sqr
Note
To see all the definitions that exist for a symbol name, use the PRINTSYMBOLS (see
PRINTSYMBOLS on page 2-242) command, for example:
printsymbols sqr
•
If the specified symbol or macro has local symbols, confirmation is requested that
you want to delete all the local symbols. Entering the ,y parameter provides this
confirmation automatically.
See also
The following commands provide similar or related functionality:
•
ADD on page 2-18
•
ALIAS on page 2-23
•
PRINTSYMBOLS on page 2-242
•
DEFINE on page 2-121.
2-126
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.35
DELFILE
The DELFILE command removes filenames from the executable file list, provided the
specified file is not loaded onto the target.
Syntax
DELFILE [,auto] {filename | file_num}
where:
Causes the command to remove unloaded files from the file list that were
added as a result of the ADDFILE,auto command.
auto
filename|file_num
Identifies a file to be removed from the executable file list.
You can include one of more environment variables in the filename. For
example, if MYPATH defines the location C:\Myfiles, you can specify:
delfile "$MYPATH\\myimage.axf"
Description
The ADDFILE and the DELFILE commands are used to manipulate the executable image file
list. This list is in most cases only one file, the executable you load onto the target using
LOAD. There are circumstances where you must load more than one file onto the target at
once. In these cases you use ADDFILE to set up the files to load, and RELOAD or LOAD/A to
load them onto the target.
You use DELFILE to remove unloaded files that you have added to the executable file list.
There are several ways to specify the files to delete:
•
by complete filename, for example C:\Source\dhry\Debug\dhry.axf
•
by short filename, for example dhry.axf
•
by file number, for example 2
•
as the currently unloaded files that were added to the list by ADDFILE,auto
•
as all currently unloaded files.
DELFILE with no arguments deletes all currently unloaded files, and DELFILE,auto deletes
any currently unloaded files added as a result of an ADDFILE,auto.
Use DTFILE to display the current file list, including the defined short filenames, file
numbers and whether the file is loaded or not.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-127
RealView Debugger Commands
•
Note
If you use the full filename you must enclose it in double quotes. You do not have
to quote the short filename in quotes, although you can.
•
You cannot delete multiple named or numbered files in a single command. Use
multiple DELFILE commands, or delete all files and then use ADDFILE as required.
•
An executable file must be unloaded from the target before its name can be
removed from the file list. Use the UNLOAD command to unload a file that is no
longer being used by the target.
Examples
The following examples show how to use ADDFILE and DELFILE:
> addfile ="C:\Source\helloworld\Debug\helloworld.axf"
> dtfile
File 1 with modid <not loaded>: Symbols not Loaded. 0 Sections.
'helloworld.axf' As 'C:\Source\helloworld\Debug\helloworld.axf'
1,1/* ARM7TDMI PC=0x00008000
!"C:\Source\helloworld\Debug\helloworld.axf"
A file is added to the executable list, using ADDFILE, and DTFILE shows that it is on the
list and has file number, or id, of 1 (the File 1 part of the output from DTFILE).
Because the file has not been loaded, the debugger has not read the symbol table to
determine the code, data and Base Stack Segment (BSS) section sizes that a DTFILE
following a LOAD displays. See DTFILE on page 2-149 for more information.
To delete this file, you can use the file ID, reported in the first line of DTFILE output, as
follows:
> delfile 1
> dtfile
No files for this process.
The DTFILE output tells you that the deletion was successful. In this particular case, the
file id is not required, because a DELFILE with no parameters deletes all unloadable files.
For example:
> addfile ="C:\Source\helloworld\Debug\helloworld.axf"
> delfile
> dtfile
No files for this process.
You can name the file to delete, using either the full name of the file or the short name
listed in the DTFILE result:
2-128
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
> addfile ="C:\Source\helloworld\Debug\helloworld.axf"
> delfile helloworld.axf
> dtfile
No files for this process.
> addfile ="C:\Source\helloworld\Debug\helloworld.axf"
> delfile "C:\Source\helloworld\Debug\helloworld.axf"
> dtfile
No files for this process.
See also
The following commands provide similar or related functionality:
•
ADDFILE on page 2-21
•
DTFILE on page 2-149
•
LOAD on page 2-202
•
RELOAD on page 2-257
•
UNLOAD on page 2-357.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-129
RealView Debugger Commands
2.3.36
DHELP
DHELP is an alias of DCOMMANDS (see page 2-118).
2-130
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.37
DISABLEBREAK
The DISABLEBREAK command disables one or more specified breakpoints.
Syntax
DISABLEBREAK [,h] [break_num,...]
where:
break_num
Specifies one or more breakpoints to disable, separated by commas.
You identify breakpoints by their position in the list displayed by the
DTBREAK command (see page 2-147).
Do not use this qualifier. It is for debugger internal use only.
h
Description
The DISABLEBREAK command disables one or more breakpoints. A disabled breakpoint is
removed from the target as if the breakpoint were deleted, but the debugger keeps a
record of it. You can then enable it again by referring to the breakpoint number when
required, rather than having to recreate it from scratch.
If you issue the command with no parameters then all breakpoints for this connection
are disabled. Disabling a breakpoint that is already disabled has no effect.
Examples
The following examples show how to use DISABLEBREAK:
disablebreak 4,6,8
Disables the fourth, sixth, and eighth breakpoints in the current list of
breakpoints.
disablebreak Disables all the current breakpoints.
See also
The following commands provide similar or related functionality:
•
BREAKACCESS on page 2-45
•
BREAKEXECUTION on page 2-56
•
BREAKINSTRUCTION on page 2-67
•
BREAKREAD on page 2-74
•
BREAKWRITE on page 2-85
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-131
RealView Debugger Commands
•
•
•
•
2-132
CLEARBREAK on page 2-104
DTBREAK on page 2-147
CLEARBREAK on page 2-104
ENABLEBREAK on page 2-162.
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.38
DISASSEMBLE
The DISASSEMBLE command displays memory addresses and corresponding assembly
code on the Dsm tab page of the Code window.
Syntax
DISASSEMBLE [{/D|/S|/A|/B|/E}] [{address | @stack_level}]
where:
Attempt to auto-detect the disassembly mode.
/D
For ARM architecture processors, select from ARM, Thumb®, Jazelle®
bytecodes, or Thumb-2 Execution Environment (Thumb-2EE) using
information from the image file where available.
Disassemble using the standard instruction disassembly mode.
/S
For ARM architecture processors, select ARM state (32-bit) instructions.
Disassemble using the alternate instruction disassembly mode.
/A
For ARM architecture processors, select Thumb state (16-bit)
instructions.
/B
Disassemble using Jazelle bytecode assembly instructions. This is
available only for ARM processors.
/E
Disassemble using Thumb-2EE assembly instructions. This is available
only for ARM processors.
address
Specifies the starting address for disassembly. This can be a literal
address or a debugger expression.
stack_level
Enables you to specify the starting point without knowing its address.
Stack level 0 is the current address in the current procedure, stack level 1
is the code address from which the current procedure was called.
Description
The DISASSEMBLE command displays memory addresses in hexadecimal and assembly
code on the Dsm tab page of the Code window, starting at the specified memory
location and using the assembler mnemonics and register names associated with the
processor type of this connection.
Where multiple assembler mnemonics exist for the same processor type (for example,
with the ARM and the GNU assemblers for ARM processors) the debugger can only
use one of them. There is no way to select the alternate form.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-133
RealView Debugger Commands
Note
Different target connections can be connected to different processor types and so have
differing register names and assembler mnemonics.
If the specified address falls in the middle of an instruction, the whole instruction is
displayed. Memory is displayed starting at the address held in the PC if you do not
supply an address. The current execution context and variable scope of the program
remains unchanged even if you select an alternate stack level.
If you issue the OPTION command with the LINES=ON option, source code is intermixed
with the assembly language code. If you issue the OPTION command with the SYMBOLS=ON
option, symbol references are displayed with the assembly language symbols and
labels.
The DISASSEMBLE command runs synchronously unless background access to target
memory is supported. Use the WAIT command to force it to run synchronously.
Examples
The following examples show how to use DISASSEMBLE:
DISASSEMBLE /S @1
Disassemble, using the standard instruction format (for ARM processors,
the ARM state format), the instructions that are executed when the
current function returns, displaying the result in the Dsm tab in the File
Editor pane.
DISASSEMBLE 0x80200
Disassemble, using an instruction format selected using symbol table
information, the instructions starting at address 0x80200, displaying the
result in the Dsm tab in the File Editor pane.
See also
The following commands provide similar or related functionality:
•
DUMPMAP on page 2-155
•
DUMP on page 2-153
•
LOAD on page 2-202
•
MEMWINDOW on page 2-214
•
MODE on page 2-216
•
PRINTDSM on page 2-236
•
SETTINGS on page 2-279
2-134
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
•
ARM DUI 0175H
WHERE on page 2-373.
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-135
RealView Debugger Commands
2.3.39
DISCONNECT
The DISCONNECT command disconnects the debugger from a target.
Syntax
DISCONNECT [,all | ,gui] [{,debug|,nodebug}] [=][@targetname]
where:
all
Disconnects all connections.
gui
Enables you to choose the disconnect mode from a dialog or prompt:
•
If you use this option when running in GUI mode, it displays a
dialog.
•
If you use this option when running in command line mode, it
displays a prompt.
The disconnect specifies what state you want the debugger to leave the
target in after the disconnection. See Disconnect modes on page 2-137 for
more details.
debug
Disconnects using the As-is with Debug mode (see Disconnect modes on
page 2-137).
nodebug
Disconnects using the As-is without Debug mode (see Disconnect modes
on page 2-137).
targetname
Specifies the required target name as it appears in the GUI.
Description
The DISCONNECT command disconnects the debugger from a target, undoing the action of
a previous CONNECT. You can specify the target as outlined for the CONNECT command.
Note
If you set the disconnect mode in the board (.BRD) file of the target, the target
disconnects using that mode. If you specify prompt for the disconnect mode, then the
DISCONNECT command acts as though you specified the ,gui qualifier. See the RealView
Debugger v3.0 User Guide for more details.
The DISCONNECT command runs asynchronously.
2-136
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
Disconnect modes
When you disconnect from a target, the disconnect mode determines what happens to
the target:
As-is with Debug
Leave the target in the current run state and the current debug
state. That is:
•
If the target is running now, leave it running. If the target is
stopped in debug state now, leave it stopped.
•
Current debug state intact, for example, breakpoints remain
set.
As-is without Debug
Leave the target in the current run state but without the current
debug state. That is:
•
If the target is running now, leave it running. If the target is
stopped in debug state now, leave it stopped.
•
Current debug state lost, for example, breakpoints are
removed.
Note
The disconnect modes available depend on the Target Access you are using.
See the RealView Debugger v3.0 User Guide for details on disconnect mode.
Implications for OS-aware connections
If you disconnect from an OS-aware connection, RealView Debugger sends a command
to the Debug Agent, which might resume all stopped threads depending on how the
Debug Agent is implemented.
Examples
The following examples show how to use DISCONNECT:
disconnect,all
Disconnect all currently connected connections.
disconnect
Disconnect the current target:
In the GUI, this is the target shown in the title bar of the Code
window where you enter the command. Therefore, if you enter the
command in a Code window that is attached to a connection, then
the connection to which the Code window is attached is
disconnected.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-137
RealView Debugger Commands
Note
You can determine the current connection using the BOARD
command (see BOARD on page 2-41), for example:
> board
Current Board is ARM940T_0:ARM-ARM-NW (P1)
disconnect,gui @[email protected]
Display the Disconnect Mode selection box to disconnect the
target @[email protected]
disconnect @[email protected]
Disconnect the named RVISS target. The @localhost is optional
where there is no ambiguity.
Note
Target names must be entered as they appear in the Connection Control window.
See also
The following commands provide similar or related functionality:
•
BOARD on page 2-41
•
CONNECT on page 2-108
•
RESTART on page 2-263.
2-138
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.40
DLOADERR
The DLOADERR command displays possible reasons for the last load error.
Syntax
dloaderr [{,gui | ;windowid | ;fileid}]
where:
This qualifier causes the results to be displayed in a dialog.
gui
Note
This qualifier has no effect when running in command line mode.
;windowid | ;fileid
Identifies the window or file where the command is to send the output.
See Window and file numbers on page 1-5 for details.
Description
The DLOADERR command displays possible reasons for the most recent program
executable load error, and suggests actions you might take.
If you issue the command with no qualifier or parameter, then its output is displayed on
the screen. If you are using the GUI, then the output is displayed in the Output pane. For
more information on redirecting message output see VOPEN on page 2-367.
See also
The following commands provide similar or related functionality:
•
LOAD on page 2-202
•
RELOAD on page 2-257.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-139
RealView Debugger Commands
2.3.41
DMAP
DMAP is an alias of DTFILE (see page 2-149).
2-140
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.42
DOS_resource-list
Displays an OS resource list or shows details of one element in that list.
Syntax
DOS_resource-list ,qualifier [=value] [{;windowid | ;fileid}]
where:
resource-list
Specifies the resource list.
qualifier
Specifies what to display, that is all or detail. detail is the default if you
specify a value. If you do not specify a value, you must use all.
value
Identifies an object in the specified resource list.
;windowid | ;fileid
Identifies the window or file where the command is to send the output.
See Window and file numbers on page 1-5 for details.
Description
The DOS_resource-list command displays an OS resource list or shows details of one
element in that list. If you are using the GUI, then these are displayed in the Output
pane. It displays the information as shown in the Details area of the Resource Viewer
pane. The resource-list and qualifier depend on the OS you are using.
You can get a list of these commands using the DCOMMANDS command, for example:
dcommands all
You can also determine these from the Resource Viewer pane:
•
resource-list is determined by the tab you select in the Resource List, with the
exception of the Conn tab
•
qualifier is determined by right clicking on an object in the selected tab of the
Resource List.
You might want to log your use of the Resource Viewer pane to determine the CLI
commands you can use with your OS. See LOG on page 2-206 for details. You can then
modify the log file, and use it as a command script, see INCLUDE on page 2-194.
See the RealView Debugger v3.0 RTOS Guide for details on using the Resource Viewer
pane.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-141
RealView Debugger Commands
Examples
The following examples show how to use DOS_resource-list:
fopen 100,'c:\myfiles\threads.txt'
dos_thread_list,all ;100
vclose 100
Copies the details of all thread resources to the file
c:\myfiles\threads.txt.
dos_thread_list,detail = thread_4
dos_thread_list,detail = 0x39d8
Displays details about the thread named thread_4 and the thread with ID
0x39d8.
dos_timer_list,detail = 0x39d8
Displays details about the specified timer.
See also
The following commands provide similar or related functionality:
•
AOS_resource-list on page 2-30
•
BREAKINSTRUCTION on page 2-67
•
GO on page 2-186
•
HALT on page 2-190
•
OSCTRL on page 2-230
•
STOP on page 2-301
•
THREAD on page 2-307.
2-142
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.43
DOWN
The DOWN command moves the variable scope and source location down the stack (that
is, away from the program entry point, towards the current PC).
Syntax
DOWN [levels]
where:
levels
Specifies the number of stack levels to move down. This must be a
positive number.
Description
This command moves the current variable scope, and source or disassembly view
location down the stack by the specified number of levels. The debugger modifies the
local variable scope to display the variables in the new location, and potentially hiding
those at the previous level.
If you are already at the lowest level (nearest to the program entry point), a message
reminds you that you cannot move down any more. You must have used an UP command
or a SCOPE command before a DOWN command becomes meaningful. You can move down
one level by using the command without parameters.
The DOWN command runs synchronously unless background access to target memory is
supported. Use the WAIT command to force it to run synchronously.
Example
The following example shows how to use DOWN. The UP command moves the context up
the stack to the enclosing function, so that a variable index is in scope. The value of the
variable is displayed, and it is decided to discover that another variable, count, by
looking at the preceding function. When count is displayed, the DOWN 2 command is used
to return down the stack two levels, to the scope of the initial function
> up
> ce index
index = 3
> up
> ce count
count = 55
> down 2
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-143
RealView Debugger Commands
See also
The following commands provide similar or related functionality:
•
CEXPRESSION on page 2-101
•
CONTEXT on page 2-113
•
EXPAND on page 2-169
•
SCOPE on page 2-268
•
UP on page 2-359
•
WHERE on page 2-373.
2-144
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.44
DPIPEVIEW
The DPIPEVIEW command shows details of the processor execution pipe-line.
Note
This command is only supported by some types of simulator. See your simulator
documentation for more information.
Syntax
DPIPEVIEW [=value] [{;windowid | ;fileid}]
where:
A pipe level or position index which, if specified, provides more detail
about the instruction at that point.
value
;windowid | ;fileid
Identifies the window or file where the command is to send the output.
See Window and file numbers on page 1-5 for details.
If you do not supply a ;windowid or ;fileid parameter, output is displayed
on the screen. If you are using the GUI, then the output is displayed in the
Output pane.
Description
The command shows details of the processor execution pipe-line. It is normally used
with cycle-accurate simulators. The pipe list contains the main pipe-line state.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-145
RealView Debugger Commands
2.3.45
DTBOARD
The DTBOARD command displays information about the current or a specified connection.
Syntax
DTBOARD [="resource",...] [{;windowid | ;fileid }]
where:
resource
Identifies the connection that is to have its details displayed. You must
specify each name in double quotes, for example:
dtboard ="Simarm_1","Simarm_2"
windowid | fileid
Identifies the window or file where the command is to send the output.
See Window and file numbers on page 1-5 for details.
Description
The DTBOARD command displays information about the current or a specified connection.
If you do not specify a connection, the command displays information about the current
connection. If you do not supply a ;windowid parameter, the output is displayed on the
screen. If you are using the GUI, then the output is displayed in the Output pane. For
more information see VOPEN on page 2-367.
Example
The following example shows how to use DTBOARD.
> dtboard
Connected Board 'Simarm_1' Port 0: Server supporting Single Tasking.
Port string: localhost
Entry of router/broker localhost
Alias
DBOARD is an alias of DTBOARD.
See also
The following commands provide similar or related functionality:
•
BOARD on page 2-41
•
CONNECT on page 2-108
•
DTFILE on page 2-149.
2-146
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.46
DTBREAK
The DTBREAK command displays information on all breakpoints and tracepoints set.
Syntax
DTBREAK [=thread,...] [{;windowid | ;fileid}]
where:
thread
Not supported in this release.
windowid | fileid
Identifies the window or file where the command is to send the output.
See Window and file numbers on page 1-5 for details.
If you do not supply a windowid or fileid parameter, the output is
displayed on the screen. If you are using the GUI, then the output is
displayed in the Output pane.
Description
The DTBREAK command displays information about the currently defined breakpoints and
tracepoints.
The output includes the following fields:
S
Indicates the enabled and disabled state of the breakpoint or tracepoint:
•
a blank entry indicates enabled
•
D indicated disabled.
Type
The type of breakpoint or tracepoint.
Address
The address associated with the breakpoint or tracepoint.
For a data only breakpoint, this field displays the text Data-Value.
Count
The number of times a breakpoint has been activated.
If a pass count is assigned, then this field does not begin incrementing
until the pass count has reached zero.
Miscellaneous
Shows the current value of any software pass count condition that is
assigned to the breakpoint.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-147
RealView Debugger Commands
Example
The following is an example of the output from DTBREAK:
> dtbreak
S Type
Address
Count
Miscellaneous
- -------------------------Instr
0x24000408
0
Pass=10
Read
0x24000434
0
Trace InstrExec
0x000085A8
0
Alias
DBREAK is an alias of DTBREAK.
See also
The following commands provide similar or related functionality:
•
BREAKACCESS on page 2-45
•
BREAKEXECUTION on page 2-56
•
BREAKINSTRUCTION on page 2-67
•
BREAKREAD on page 2-74
•
BREAKWRITE on page 2-85
•
CLEARBREAK on page 2-104
•
DISABLEBREAK on page 2-131
•
DTRACE on page 2-151
•
ENABLEBREAK on page 2-162
•
TRACEBUFFER on page 2-312
•
TRACEDATAACCESS on page 2-323
•
TRACEDATAREAD on page 2-329
•
TRACEDATAWRITE on page 2-335
•
TRACEEXTCOND on page 2-341
•
TRACEINSTREXEC on page 2-346
•
TRACEINSTRFETCH on page 2-352.
2-148
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.47
DTFILE
The DTFILE command displays information about one or more specified files or all files
of the current process.
Syntax
DTFILE [=file_num,...][{;windowid | ;fileid}]
where:
file_num
One or more integer numbers that identify the file or files about which
you want to see information. If you do not supply this parameter, details
of all the currently loaded files are displayed.
windowid | fileid
Identifies the window or file where the command is to send the output.
See Window and file numbers on page 1-5 for details.
If you do not supply a windowid or fileid parameter, output is displayed
on the screen. If you are using the GUI, then the output is displayed in the
Output pane.
Description
The DTFILE command displays information about the currently loaded executable file.
The file numbers are the same as those used in the ADDFILE and DELFILE commands. The
information displayed varies:
•
if the file has been loaded onto the target, then the information contains details
about the code and data section sizes and the load addresses
•
if the file has not been loaded, the debugger has not yet determined the code and
data sizes and so does not display them.
The first line of the output includes the following information:
File file_num
Used by the ADDFILE, DELFILE, RELOAD and UNLOAD commands to refer to the
file.
modid num An internal number.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-149
RealView Debugger Commands
Symbols Loaded
This item tells you whether the executable file has program debug
symbols and whether they have been loaded. In most cases you require
debug symbols to make sense of the program instructions.
n sections
This item tells you how many program sections there are in the file. Each
loaded program section is normally listed with any associated
information.
The second line of output contains first the shortname and then the file path name of the
file. The short name is an abbreviation of the name, normally the filename with no
directory specification. The file path name includes the full directory path name for the
file. You must normally specify the file path name enclosed in double quotes when
entering it in commands.
If a file was built with separate load regions defined, these load regions are also shown
in the output.
Example
The following example illustrates the output of DTFILE, displaying information about a
loaded executable called shapes.axf.
> dtfile =1
File 1 with modid
'shapes.axf' As
Code section of
BSS section of
1: Symbols Loaded. 2 Sections.
'c:\src\cpp\shapes_Data\Debug\shapes.axf'
size 10732 at 0x00008000: ER_RO
size
356 at 0x0000A9EC: ER_ZI
Alias
DMAP and DVFILE are aliases of DTFILE.
See also
The following commands provide similar or related functionality:
•
ADDFILE on page 2-21
•
LOAD on page 2-202
•
MEMMAP on page 2-210
•
RELOAD on page 2-257
•
UNLOAD on page 2-357.
2-150
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.48
DTRACE
The DTRACE command shows information on trace.
Syntax
dtrace [{;windowid | ;fileid}]
where:
windowid | fileid
Identifies the window or file where the command is to send the output.
See Window and file numbers on page 1-5 for details.
If you do not supply a windowid or fileid parameter, output is displayed
on the screen. If you are using the GUI, then the output is displayed in the
Output pane.
Description
The DTRACE command displays information about the trace analyzer you are using and
the triggers that are defined.
Example
The following example illustrates the output of DTRACE:
> dtrace
ARM Analyzer: ARM Embedded Trace Macrocell. Version 1.0.
2 Tracepoints defined.
Trigger On at Code 0x846C.
Trigger On at Code 0x8540.
Buffer collected Before Trigger.
(Before/Around/AfterSupported).
See also
The following commands provide similar or related functionality:
•
ANALYZER on page 2-26
•
ETM_CONFIG on page 2-165
•
TRACE on page 2-309
•
TRACEBUFFER on page 2-312
•
TRACEDATAACCESS on page 2-323
•
TRACEDATAREAD on page 2-329
•
TRACEDATAWRITE on page 2-335
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-151
RealView Debugger Commands
•
•
•
2-152
TRACEEXTCOND on page 2-341
TRACEINSTREXEC on page 2-346
TRACEINSTRFETCH on page 2-352.
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.49
DUMP
The DUMP command displays memory contents in hexadecimal or ASCII format.
Syntax
DUMP [{/B|/H|/W|/8|/16|/32}] [{address | address-range}]
where:
/B, , /8
Sets the display format to byte (8 bits).
If the processor naturally addresses bytes (for example, ARM7TDMI®)
then this is the default setting. However, CEVA and ZSP DSPs address
words of 16 bits, so /H is the default for CEVA and ZSP DSPs.
/H, , /16
Sets the display format to halfword (16 bits).
/W, , /32
Sets the display format to word (32 bits).
address
Specifies a memory address at which to begin the display of contents. The
remainder of that 16-byte line and the whole of the following 16-byte line
are displayed.
address-range
Specifies a range of memory addresses whose contents are to be
displayed. See Specifying address ranges on page 2-2 for details on how
to specify an address range.
Description
The DUMP command displays memory contents in bytes, words or long words as
hexadecimal and ASCII characters on the screen. If you are using the GUI, then they
are displayed in the Output pane.
If you do not specify any parameters, the next five lines of data after the previously
dumped address range are displayed. In the character output format, nonprintable
characters (such as a carriage return) are represented by a period (.).
The DUMP command runs synchronously unless background access to target memory is
supported. Use the WAIT command to force it to run synchronously.
Example
The following example illustrates the output of DUMP. The first example displays two
rows of memory from 0x8000.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-153
RealView Debugger Commands
> dump 0x8000
0x00008000 00 00 00 EA 24 06 00 EA
0x00008010 0C A0 8A E0 01 70 4A E2
28 C0 8F E2 00 0C 9C E8 ....$...(.......
0C B0 8B E0 0B 00 5A E1 .....pJ.......Z.
Executing DUMP again displays a page of memory from 0x8020.
> dump
0x00008020
0x00008030
0x00008040
0x00008050
0x00008060
00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F
-----------------------------------------------1D 06 00 0A 0F 00 BA E8 14 E0 4F E2 01 00 13 E3
03 F0 47 10 03 F0 A0 E1 6C 6B 00 00 7C 6B 00 00
00 40 A0 E3 00 50 A0 E3 00 60 A0 E3 00 C0 A0 E3
10 20 52 E2 70 10 A1 28 FC FF FF 8A 82 2E B0 E1
30 00 A1 28 00 C0 81 45 0E F0 A0 E1 04 30 9F E5
..........O.....
..G.....lk..|k..
[email protected]...`......
. R.p..(........
0..(...E.....0..
Requesting a DUMP of words of memory, and specifying a range of addresses produces
the following result:
dump /h 0x9004..0x9012
0x00009000
0x00009010 0000 E350
0001
E1A0
1004
E28D
0780
EB00
............
..P.
See also
The following commands provide similar or related functionality:
•
CEXPRESSION on page 2-101
•
FILL on page 2-173
•
MEMWINDOW on page 2-214
•
WRITEFILE on page 2-376.
2-154
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.50
DUMPMAP
The DUMPMAP command writes the current memory map out as a file, using the native
linker format.
Note
Although you can save the memory map for an ARM target, the linker command file
cannot be used when building images for ARM architecture-based processors.
Syntax
DUMPMAP filename
where:
filename
Specifies the filename or file pathname to which the map is written. It
must be enclosed in double quotes if a pathname is specified, and the
pathname must already exist on your system.
You can include one of more environment variables in the filename. For
example, if MYPATH defines the location C:\Myfiles, you can specify:
dumpmap '$MYPATH\ld.map'
Description
The DUMPMAP command writes a linker map file in the format associated with the current
processor to the named file.
If the filename is a file path name, it must be enclosed in double quotes. If it is not an
absolute path name, it is written relative to the current directory of RealView Debugger,
which on Windows is normally your desktop.
If the file already exists, RealView Debugger only replaces the information between the
RVDEBUG: generated data block and the RVDEBUG: generated data above comments.
The command runs synchronously.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-155
RealView Debugger Commands
Example
The following command saves the memory map for a DSP processor to the file
c:\source\ld.map:
dumpmap "c:\source\ld.map"
Example 2-1 shows an example of a generated linker command file, in DSP format.
This example shows a combination of internal memory based on current register
settings (@YYYY) in addition to external memory as defined by the loading of a program.
Example 2-1 DSP format command file
/* Linker Command file for the DSPxx processor */
/* This file was generated by RVDEBUG. You can edit everything
outside the MEMORY block defined by RVDEBUG. Updates by
RVDEBUG will only effect that block. */
/* RVDEBUG: generated data block. Updated Fri Apr 04 15:10:41 2003
Do not modify this block. Do not put MEMORY lines above
this line, put below end of this block. */
MEMORY
{
/* Register @YYYY has (masked) value 0068 */
PAGE 0: PDaRam: org=0x0080, len=0x177F /* internal 'Dual-Access' */
PAGE 0: P_RAM: org=0x8000, len=0x032D /* external 'Sect .text' */
PAGE 1: DMapReg: org=0x0000, len=0x005F /* internal 'Registers (mapped)' */
PAGE 1: DScrDaRam: org=0x0060, len=0x001F /* internal 'Scratch Dual-Access' */
PAGE 1: DLDaRam: org=0x0080, len=0x177F /* internal 'Dual-Access' */
PAGE 1: D_RAM: org=0x8000, len=0x0085 /* external 'Sect .bss,.stack' */
PAGE 1: DHRom(R): org=0xC000, len=0x3EFF /* internal 'Internal program-ROM' */
}
/* RVDEBUG: generated data above */
See also
The following command provides similar or related functionality:
•
MEMMAP on page 2-210.
2-156
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.51
DVFILE
DVFILE is an alias of DTFILE (see page 2-149).
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-157
RealView Debugger Commands
2.3.52
EDITBOARDFILE
The EDITBOARDFILE command enables you to edit a specified board file.
Note
This command is not available when running in command line mode.
Syntax
EDITBOARDFILE [,configure] [="boardfilename","routeID"...]
where:
configure
Opens the configuration dialog for the debug target.
boardfilename
Identifies the board file that you want to edit. This must be in double
quotes, for example, "myboard.brd".
You can include one of more environment variables in the filename. For
example, if MYPATH defines the location C:\Myfiles, you can specify:
editboardfile ="$MYPATH\\myboard.brd"
routeID
Identifies the route ID for the target associated with the board file that you
want to edit. This must be in double quotes, for example, "3".
Description
The EDITBOARDFILE command displays the Connection Properties window to edit the
specified board file. If you do not specify a board file, the settings of the current board
file are displayed for you to edit.
Note
If you specify a routeID, you must also specify a blank boardfilename, for example:
editboardfile,configure "","3"
You can specify one or more boardfilename/routeID combinations.
If you make any changes to a board file, the updated file is reread when you close the
Connection Properties window.
The command runs asynchronously.
2-158
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
Example
The following example shows how to use EDITBOARDFILE to edit the Connection
Properties dialog:
editboardfile
The following example shows how to use EDITBOARDFILE to edit the board file for a
specific connection:
editboardfile,configure "","4"
If you specify a board that does not have a device-specific configuration, then the
Connection Properties dialog is displayed.
See also
The following commands provide similar or related functionality:
•
DELBOARD on page 2-124
•
DTBOARD on page 2-146
•
READBOARDFILE on page 2-252.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-159
RealView Debugger Commands
2.3.53
EMURESET
The EMURESET command tests and resets a hardware emulator.
Syntax
EMURESET [,test] id
where:
test
Runs an emulation test on the connection identified by id. This can
involve JTAG testing or self checks.
id
Connection identity.
Description
The EMURESET command resets a hardware emulator or monitor. This is not the same as
RESET which resets the target processor or board. The emulation reset is used to set the
communications up properly or to prepare the board for debugging.
The EMURESET command is not supported for ARM RDI targets. The command runs
synchronously, and is not accepted when the debugger is connected to this hardware.
Example
The following example shows how to reset the hardware on the connection with an ID
of 4.
emureset 4
Alias
EMURST and HWRESET are aliases of EMURESET.
See also
The following commands provide similar or related functionality:
•
RESET on page 2-259
•
RESTART on page 2-263
•
WARMSTART on page 2-372.
2-160
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.54
EMURST
EMURST is an alias of EMURESET (see page 2-160).
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-161
RealView Debugger Commands
2.3.55
ENABLEBREAK
The ENABLEBREAK command enables one or more specified breakpoints.
Syntax
ENABLEBREAK [,h] [break_num,...]
where:
break_num
Specifies one or more breakpoints to enable, separated by commas.
You identify breakpoints by their position in the list displayed by the
DTBREAK command (see page 2-147).
Do not use this qualifier. It is for debugger internal use only.
h
Description
The ENABLEBREAK command enables one or more breakpoints that have been disabled. A
disabled breakpoint is removed from the target as if the breakpoint were deleted, but the
debugger keeps a record of it. You can enable it again, using this command, by referring
to the breakpoint number, avoiding then having to recreate it from scratch.
If you issue the command with no parameters then all breakpoints are enabled. Enabling
a breakpoint that is already enabled has no effect.
The command runs synchronously.
Example
The following examples show how to use ENABLEBREAK:
enablebreak 4,6,8
Enables the fourth, sixth, and eighth breakpoints in the current list
of breakpoints.
enablebreak
Enables all the current breakpoints.
See also
The following commands provide similar or related functionality:
•
BREAKEXECUTION on page 2-56
•
BREAKINSTRUCTION on page 2-67
•
BREAKREAD on page 2-74
•
BREAKWRITE on page 2-85
•
CLEARBREAK on page 2-104
2-162
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
•
•
•
ARM DUI 0175H
DISABLEBREAK on page 2-131
DTBREAK on page 2-147
RESETBREAKS on page 2-261.
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-163
RealView Debugger Commands
2.3.56
ERROR
The ERROR command specifies what happens if an error occurs in processing an INCLUDE
file.
Note
This command has no effect when running in command line mode.
Syntax
ERROR = {quit | abort | continue}
where:
quit
Instructs the debugger to quit the session and exit to the operating system.
abort
Instructs the debugger to return to command mode and wait for keyboard
input.
continue
Instructs the debugger to abandon the command that produced the error,
and to execute the next command in the include file.
Description
The ERROR command specifies the action the debugger takes if an error occurs while
processing an include file. If you issue the ERROR command without parameters, program
execution terminates.
The ERROR command runs asynchronously unless in a macro.
Example
The following example shows how to use ERROR:
error = abort
If an error occurs, abort reading the include file and return to the
command prompt.
See also
The following commands provide similar or related functionality:
•
INCLUDE on page 2-194
•
QUIT on page 2-251.
2-164
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.57
ETM_CONFIG
The ETM_CONFIG command provides control over the ARM Embedded Trace Macrocell™
(ETM).
Syntax
ETM_CONFIG [,qualifier...]
where:
qualifier
Is a list of qualifiers. The possible qualifiers are described in List of
qualifiers.
Description
The ETM_CONFIG command provides control over the ARM ETM. The arguments to a
single invocation of the command specify a configuration of the ETM, so the presence
or absence of qualifiers is relevant.
For more information on the terms used by the ETM and options it provides, see the
Embedded Trace Macrocell Specification and the chapter that describes tracing in the
RealView Debugger v3.0 Trace User Guide.
List of qualifiers
The list of qualifiers depends on the processor and Target Access. The command
handler generates an error if a specific combination is invalid for a specific processor or
Target Access, but this is determined when you issue the command. The possible
qualifiers are:
ARM DUI 0175H
addronly
Trace only address bus transfers. (Deprecated)
coprocessor
Enable coprocessor tracing. To disable, issue the command
without this qualifier.
cycle_accurate
Enable cycle-accurate tracing, if the ETM supports it. To disable,
issue the command without this qualifier.
demultiplex
Select the demultiplexed trace port transmission mode.
dataonly
Trace only data bus transfers.
datasuppression
Enables ETM v3 data suppression on FIFO full. This is supported
only by ETM v3.
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-165
RealView Debugger Commands
disableport
Disable the ETM trace port. To enable, issue the command
without this qualifier.
extinN:value
External extended input selector register parts:
extin1:n External extended input 1.
extin2:n External extended input 2.
extin3:n External extended input 3.
extin4:n External extended input 4.
The value n of each part can be a value in the range 0 to 255,
inclusive. However, the number of inputs, the range of values
supported, and the default value of each input depends on the
ETM you are using. For example, the ARM1136JF-S™ has two
extended external inputs with values in the range zero to 20 and
default values of zero.
Use the TRACEEXTCOND command to specify which input to test.
These inputs are supported only by ETM v3.1, and later.
2-166
FIFO_hw:n
Set the FIFO high-water mark to n.
filtercoprocessor
Enables filtering of CPRTs when data trace is enabled. This is
supported only by ETMv3.
fulltrace
Trace both data and address bus transfers. (Deprecated)
half_rate
Enable half-rate clocking of the trace port by the ETM. For
full-rate, issue the command without this qualifier.
mmap_decode:n
Set the ETM memory map value to n. This is an
implementation-dependent value that varies depending on the
memory map decode logic present in your system.
multiplex
Select the multiplexed trace port transmission mode.
nomultiplex
Select the normal (not multiplexed or demultiplexed) trace port
transmission mode.
packauto
Selects the automatic packing mode for the TPA.
packnormal
Selects the normal packing mode for the TPA.
packdouble
Selects the double packing mode for the TPA.
packquad
Selects the quad packing mode for the TPA.
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
portratio:n
port_width:n
Enables ETM v3 port speed to ETM clock speed ratios to be set.
This is supported only by ETM v3. Appropriate values for n are:
0
Use a 1:1 ratio.
1
Use a 1:2 ratio.
2
Use a 1:3 ratio.
3
Use a 1:4 ratio.
4
Use a 2:1 ratio.
5
Use dynamic ratio modes for on-chip trace.
6
Use the implementation-defined mode, if implemented
by the ASIC designer.
Set the ETM port width, where n is one of:
0
4-bit port.
1
8-bit port.
2
16-bit port.
3
24-bit port.
4
32-bit port.
The 24-bit and 32-bit settings are supported only for ETB11™
connections using RealView ICE.
size:n
Set the ETM trace buffer size to n records.
stall_full
Enable processor stalling if the FIFO becomes full, if the ETM
and processor support it. To disable, issue the command without
this qualifier.
suppressdata
Suppress data tracing if the FIFO becomes full. To leave data
tracing enabled, issue the command without this qualifier.
syncfrequency:n
For ETMv2, and later, a synchronization frequency register is
used to define the time between synchronization points in the trace
data. That is, the points where the trace tools start decompressing
the trace output.
The synchronization frequency n can be a value in the range 100
to 4095, inclusive, with the default being 1024:
•
for ETMv2 and ETM v3.0, the value is in cycles
•
for ETMv3.1 and later, the value is in bytes.
time_stamps
ARM DUI 0175H
Enable time stamping if the ETM and trace capture hardware
support it. To disable, issue the command without this qualifier.
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-167
RealView Debugger Commands
twin
Selects the connection that the current connection is connected
(twinned) with. This is supported only by DCP/TCM hardware.
twinmaster
Selects the processor that is to be the DCP master. This is
supported only by DCP/TCM hardware.
Examples
The following examples show how to use ETM_CONFIG:
ETM_CONFIG,port_width:0,coprocessor,fulltrace,size:10240
Set up the ETM for a 4-bit, full-rate, nonmultiplexed trace port, no
stalling or timestamps, 10K trace records, address and data
tracing, and in non cycle-accurate mode.
ETM_CONFIG,port_width:1,stall_full,multiplex,fulltrace,suppressdata,size:1024
Set up the ETM for an 8-bit, full-rate, multiplexed trace port,
processor stalling and data suppression on FIFO full, no
timestamps, 1024 trace records, address and data tracing, and in
non cycle-accurate mode.
See also
The following commands provide similar or related functionality:
•
ANALYZER on page 2-26
•
DTBREAK on page 2-147
•
DTRACE on page 2-151
•
TRACE on page 2-309
•
TRACEBUFFER on page 2-312
•
TRACEDATAREAD on page 2-329
•
TRACEDATAACCESS on page 2-323
•
TRACEDATAWRITE on page 2-335
•
TRACEINSTREXEC on page 2-346
•
TRACEINSTRFETCH on page 2-352.
2-168
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.58
EXPAND
The EXPAND command displays the values of parameters to a procedure and any local
variables that have been set up.
Syntax
EXPAND [@stack_level [{,windowid | ,fileid}]]
Where:
@stack_level Specifies a stack level if you want to see only a single level expanded. For
example, you can specify @3 to expand stack level 3 only.
,windowid | ,fileid
Identifies the window or file where the command is to send the output.
See Window and file numbers on page 1-5 for details. You can specify a
window or file ID only if you specify a stack level.
Description
The EXPAND command displays the values of parameters to a procedure and any local
variables that have been set up. You can expand any procedure in a directly called chain
from the main program to the current procedure. Other procedures are not accessible.
If no stack level is specified, all procedures nested on the stack are displayed. Stack
levels are numbered starting with the current procedure equaling 0, the caller of this
procedure is 1, the caller of that procedure is 2.
The EXPAND command runs synchronously.
Messages that can be output by the EXPAND command have the following meanings:
<Bad float>
Invalid floating-point value, cannot be converted.
<bad size>
Type size invalid.
<UNKNOWN: xx>
Invalid enum value, where xx = value.
<INFINITY>
Floating-point value is infinity.
<Invalid value (x)>
Error number (x) occurred.
<NAN>
ARM DUI 0175H
Not a number (for a floating-point value).
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-169
RealView Debugger Commands
<not a source procedure. Address is ...>
Routine is not defined as a function in the object file.
<not alive>
Local register variable no longer exists.
<Not in procedure> PC located before first executable line.
<unknown type>
Type is not recognized by the debugger.
Example
The following example illustrates the EXPAND command executed during a run of the
dhrystone program. You can see three of the messages in use: an UNKNOWN enum value, a
variable that is not alive, and a procedure that has no source or debug information
available.
> go
> expand
00. Proc_1: at line 309.
Ptr_Val_Par07FFFF60 = (record *)0x01000260
Next_Record00000005 = (record *)0x0100C274
01. main: at line 170.
Int_1_Loc 07FFFF60 = 16777824
Int_2_Loc 07FFFF60 = 16777824
Int_3_Loc 07FFFF5C = 134217624
Ch_Index 'C'
Enum_Loc 07FFFF58 = <UNKNOWN: 255>
Str_1_Loc 07FFFF38 = "\xFF\xFF\xFF\xFFx\x1E"
Str_2_Loc 07FFFF18 = ""
Run_Index 07FFFF64 = 16827048
Number_Of_Runs100000
n
<not alive>
02. <not a source procedure. Address is 01001DF0>
The program was halted in Proc_1 at line 309. The output shows that Proc_1 was called
from main line 170, and main was called by unnamed code at address 0x01001DF0, which
is part of the C runtime library.
Because main is called from the C runtime library, no source and no debug information
is available for the procedure that called main, so EXPAND reports the pc address from
which the call to main is made.
See also
The following commands provide similar or related functionality:
•
CEXPRESSION on page 2-101
•
JOURNAL on page 2-197
2-170
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
•
•
ARM DUI 0175H
PRINTVALUE on page 2-247
WHERE on page 2-373.
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-171
RealView Debugger Commands
2.3.59
FAILINC
The FAILINC command causes an abnormal exit from processing an include file.
Syntax
FAILINC "string"
where:
string
A string to display that explains the reason for aborting the include file.
Description
The FAILINC command enables you to abort processing an include file. You might do this
when checks of the target or debugger environment have failed to find resources the
include file requires.
Use the string parameter to explain the abort.
Example
The following example shows how to use the FAILINC command in a macro:
if ( *((char*)(0xffe00)) != 0 )
$failinc "Peripheral not initialized. Aborting$";
The following example shows how to use the FAILINC command in an include file:
jump nofail,( *((char*)(0xffe00)) == 0 )
failinc "Peripheral not initialized. Aborting"
:nofail
These two examples test a memory address, expecting to read a 0 from some peripheral
register. If it does not read 0, it aborts include file processing.
See also
The following commands provide similar or related functionality:
•
ERROR on page 2-164
•
INCLUDE on page 2-194
•
JUMP on page 2-199.
2-172
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.60
FILL
The FILL command fills a memory block with values.
Syntax
FILL [{/B|/H|/W|/8|/16|/32}] [/NW]
addressrange ={expression | expressionlist}
where:
/B, , /8
Sets the fill size to byte (8 bits).
If the processor naturally addresses bytes (for example, ARM7TDMI)
then this is the default setting. However, CEVA and ZSP DSPs address
words of 16 bits, so /H is the default for CEVA and ZSP DSPs.
/H, , /16
Sets the fill size to halfword (16 bits).
/W, , /32
Sets the fill size to word (32 bits).
/NW,
Suppresses the warning prompt when filling a large area of memory.
addressrange Specifies the range of addresses that identify the memory contents to be
filled with the pattern. The start and the end of the range is included in the
range. For example a byte fill from 0x400..0x500 writes to 0x400 and to
0x500. See Specifying address ranges on page 2-2 for more details on
address ranges.
expression
Specifies the pattern used to fill memory. The expression can be:
•
a decimal or hexadecimal number
•
a debugger expression, for example a math calculation
•
a string enclosed in quotation marks.
If you use a quoted string:
•
each character of the string is treated as a byte value in an
expressionlist
•
no C-style zero terminator byte is written to memory.
expressionlist
Specifies the pattern used to fill memory. An expressionlist is a sequence
of values separated by commas, for example:
0x20,0x40,0x20
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-173
RealView Debugger Commands
Note
All expressions in an expression string are padded or truncated to the size
specified by the size qualifiers if they do not fit the specified size evenly.
This also applies to each character of a string.
Description
The FILL command fills a memory block with values obtained from evaluating an
expression or list of expressions. The size qualifier is used to determine the size of each
element of expressionlist.
If the number of values in expressionlist is less than the number of bytes in the
specified address range, the debugger repeatedly writes the list to memory until all of
the designated memory locations are filled.
If more values than can be contained in the specified address range are given, the last
repetition is completed before the process stops, so up to (length(expressionlist)-1)
bytes, halfwords or words might be written beyond the range end address.
If you specify an address range with equal start and end addresses, the memory at that
address is modified. If an expression is not specified, the debugger acts as if =0 had been
specified as the expression.
The FILL command runs synchronously unless background access to target memory is
supported. Use the WAIT command to force it to run synchronously.
Examples
The following examples show how to use FILL:
fill 0x1000..0x1004="hello"
Writes hello in the locations 0x1000...0x1004.
fill 0x1000..0x1001="hello"
Writes hello in the locations 0x1000...0x1004.
fill 0x1000..0x1013
Writes as bytes the value 0 to locations 0x1000...0x1013.
fill /h 0x1000..0x1014
Writes the 16-bit value 0 to locations 0x1000...0x1014.
2-174
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
fill 0x1000..0x1013="hello"
Writes hellohellohellohello in the locations 0x1000...0x1013.
fill /w 0x2032..0x2053=0xDEADC0DE
For a little-endian memory system, writes 0xDE to 0x2032, 0xC0 to 0x2033,
0xAD to 0x2034, 0xDE to 0x2035 and on to: 0xDE to 0x2052, 0xC0 to 0x2053,
0xAD to 0x2054, and 0xDE to 0x2055.
fill 0x3000..0x4756 =0xEA000000/2
Writes 0x00 to 0x3000..0x4576. The value of 0xEA000000/2 is calculated as
0x75000000. Because fill defaults to a byte expression width, this is then
truncated to 0x00 and written.
fill /32 0x3000..0x4756 =0xEA000000
Writes 1373 ARM processor NOP instructions to memory, changing
locations 0x3000..0x4578, and so writing 2 bytes more than the specified
range.
See also
The following commands provide similar or related functionality:
•
CEXPRESSION on page 2-101
•
MEMWINDOW on page 2-214
•
READFILE on page 2-253
•
SETMEM on page 2-273.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-175
RealView Debugger Commands
2.3.61
FLASH
The FLASH command enables you to write, verify, or erase Flash blocks.
Syntax
flash [,qualifier...] [={addressrange | address, ...}]
where:
qualifier
If specified, must be one or more of the following:
cancel
Discard the patched or downloaded changes.
clk:(frequency)
If required by your Flash device, specify the clock frequency
as a positive integer, reperesenting the clock frequency in Hz.
For example, enter 14175000 to specify a frequency of 14.175
MHz.
erase
Erase the specified blocks. This normally sets every byte in the
block to 0xFF or 0x00, depending on the type of Flash memory
used. You can identify the Flash block using a handle, an
address or an address range.
write
Write data to the specified blocks of Flash memory. If you do
not specify a block or address, then the write begins at the start
of the first block.
verify
If you specify this qualifier the data written to the Flash blocks
is verified against the data source.
handle=blocknum,...
Identifies one or more Flash blocks to be operated on.
To list the Flash blocks, use the FLASH command with no
arguments (see Examples on page 2-177).
The block numbers are also shown in the Open Flash Blocks
list of the Flash Memory Control dialog box. See the RealView
Debugger v3.0 User Guide for details.
Note
Do not use an address or address range with this qualifier.
2-176
useorig
This qualifier specifies that the original contents of the
memory is used wherever it is not explicitly modified.
scratch
This qualifier specifies that the original contents of the target
memory buffer is not saved first. This might save you some
time if the buffer is large.
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
By default the target memory buffer is saved first, and restored
afterwards.
addressrange Multiple Flash blocks can be specified using a range of addresses. The
start and the end of the range is included in the range. For example,
0x24000000..0x24FFFFFF specifies the blocks in the address range
0x24000000 to 0x24FFFFFF. See Specifying address ranges on page 2-2 for
more details.
If you use the handle qualifier, then do not specify an address range.
address
The Flash block can be specified by address.
If you use the handle qualifier, then do not specify an address.
Note
If you use the address or addressrange qualifiers, then those blocks that are touched by
the address or addressrange are written to completely. For example, if you specify an
address range that starts at block zero, and finishes part way into block three, then the
whole of blocks one, two and three are written to.
Description
This command is used to manage Flash memory. This command enables you to:
•
write and verify Flash blocks, which require that the blocks be opened first
•
erase Flash blocks, which does not require the blocks to be open.
The Flash block is specified by address. You cannot program more than one target
device at a time.
If this command is used with no arguments, it reports the currently open blocks.
Examples
The following examples show how to use the FLASH command:
•
To display information for the currently loaded Flash image, enter:
> flash
Flash opened on ARM920T_0:ARM-ARM-NW for 'Intel DT28F320S3 2Mx16 x2 x4' at
'0x24000000'
Block 0: +0x0000..+2644
•
To erase the Flash in the range 0x24000000 to 0x24FFFFFF inclusive, enter:
flash,erase =0x24000000..0x24FFFFFF
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-177
RealView Debugger Commands
See also
The following command provides similar or related functionality:
•
MEMMAP on page 2-210.
2-178
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.62
FOPEN
The FOPEN command opens a file and assigns to it a specified file number.
Syntax
FOPEN [/A] [/R] fileid, filename
where:
/A
Appends new data to an existing file. You cannot read or write the
existing information, and the existing information is retained.
/R
Opens a file as read-only. You must use this qualifier if you want to read
the file with the fgetc() macro (see fgetc on page 3-12).
fileid
Specifies the identity of the file to be opened. This must be a user-defined
fileid. See Window and file numbers on page 1-5 for details.
filename
Specifies the file being opened. Quotation marks are optional, but see
Rules for specifying filenames on page 2-180 for details on how to
specify filenames that include a path.
Description
This command enables you to read or write a file on the host filesystem by associating
it with a RealView Debugger custom file number.
The file is opened for writes only by default, but you can specify append or read-only
modes instead. You write to the file using the FPRINTF command, the fputc or fwrite
macros, or by redirecting output from those commands that accept the fileid specifier.
You read the file using either the fgetc or fread macros. You close the file using the
VCLOSE command.
Note
Be aware of the following:
ARM DUI 0175H
•
The FOPEN command runs asynchronously unless it is used in a macro.
•
If you open a new or existing file for writing, no data is written to the file until the
output buffer is flushed. This happens when you close the file with the VCLOSE
command, but it might happen at other times because the buffered I/O behavior is
the same as in C.
•
If you specify a filename with a path that does not exist, then an error message is
displayed. RealView Debugger does not create the non-existent path.
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-179
RealView Debugger Commands
Rules for specifying filenames
Follow these rules when specifying a filename:
•
If the filename consists of only alphanumeric characters, slashes, or a period, but
the filename does not start with a slash, then you do not have to use quotes. For
example, includes/file.
•
Filenames with a leading slash must be in double quotes, for example "/file".
•
Filenames containing a backslash must be in single quotes. For example '\file'
or 'c:\myfiles\file'.
Alternatively, you can escape each backslash and use double quotes. For example,
"c:\\myfiles\\file".
•
You can use environment variables to specify paths to a file. For example, if
PATHROOT=C:\MYFILES and PATHTEST=TEST1:
'$PATHROOT\$PATHTEST\test1.c'
You can include:
—
—
the filename as part of the second environment variable, and then specify
'$PATHROOT\$PATHTEST'.
the path separator in the environment variable, and then specify
'$PATHROOT$PATHTEST'.
Examples
The following examples show how to use FOPEN:
fopen 50, 'c:\temp\file.txt'
fprintf 50, "Start of function\n"
Open a file and write some text to it.
fopen /r 50, 'c:\temp\file.txt'
ce fgetc(50)
Open a file and read the first character of the file.
See also
The following commands provide similar or related functionality:
•
FPRINTF on page 2-182
•
VCLOSE on page 2-361
•
VMACRO on page 2-365
•
VOPEN on page 2-367
2-180
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
•
WINDOW on page 2-375.
The following macros provide similar or related functionality:
•
fclose on page 3-11
•
fgetc on page 3-12
•
fopen on page 3-15
•
fputc on page 3-17
•
fread on page 3-19
•
fwrite on page 3-21.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-181
RealView Debugger Commands
2.3.63
FPRINTF
The FPRINTF command displays formatted text to a specified file or window.
Syntax
FPRINTF {windowid | fileid}, "format_string" [,argument...]
where:
windowid | fileid
Identifies the window or file where the command is to send the output.
See Window and file numbers on page 1-5 for details.
format_string
Is a format specification conforming to C/C++ rules with extensions. It
might be a text message, or it can describe how one or more arguments
are to be presented. See Format string syntax for details.
argument
The value or values to be written.
Description
The command is similar to the C run-time fprintf function. You select the windowid or
fileid to use from the range 50..1024. For output to a file, the file must be opened using
the FOPEN command. For output to a user window, the window must be opened using the
VOPEN command.
Format string syntax
The text in format_string is defines what is displayed. If there are no % characters in the
string, the text is written out and any other arguments to FPRINTF are ignored. The %
symbol is used to indicate the start of an argument conversion specification. The syntax
of the specification is:
%[flag][fieldwidth][precision][lenmod]convspec
where:
2-182
flag
An optional conversion modification flag -. If specified, the result is
left-justified within the field width. If not specified, the result is
right-justified.
fieldwidth
An optional minimum field width specified in decimal.
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
precision
An optional precision specified in decimal, with a preceding . (period
character) to identify it.
lenmod
An optional argument length specifier:
convspec
h
a 16-bit value
l
a 32-bit value
ll
a 64-bit value
The possible conversion specifier characters, <convspec>, are:
%
A literal % character.
m
The mnemonic for the processor instruction in memory
pointed to by the argument. The expansion includes a newline
character. The information that is printed includes:
•
the memory address in hexadecimal
•
the memory contents in hexadecimal
•
the instruction mnemonic and arguments
•
an ASCII representation of the memory contents, if
printable.
H
A line from the current source file, where the argument is the
line number.
h
A line from the current source file, where the argument is the
source line address (as opposed to a target memory address).
d, i, or u An integer argument printed in decimal. d and i are equivalent,
and indicate a signed integer. u is used for unsigned integers.
x or X
An integer argument printed in unsigned hexadecimal. x
indicates that the letters a to f are used for the extra digits, and
X indicates that the letters A to F are used.
c
A single character argument.
s
A string argument. The string itself can be stored on the host
or on the target.
p
A pointer argument. The value of the pointer is printed in
hexadecimal.
e, E, f, g, or G
A floating point argument, printed in scientific notation, fixed
point notation, or the shorter of the two. The capital letter
forms use a capital E in scientific notation rather than an e.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-183
RealView Debugger Commands
Output is formatted beginning at the left of the format string and is copied to the screen.
If you are using the GUI, then the string is copied to the Output pane. Whenever a
conversion specification is encountered, the next argument is converted according to the
specification, and the result is copied to the screen.
Rules
The following rules apply to the use of the FPRINTF command:
•
FPRINTF runs synchronously
•
windowid must identify a user-defined window that you have previously opened
with the VOPEN command
•
fileid must identify a file that you have previously opened in write mode, for
example:
FOPEN 100, "c:\myfiles\file.txt"
•
if there are too many arguments, some of those that do not correspond with a
format specifier are not printed
•
if there are too few arguments (that is, there are more conversion specifiers in the
format string than there are arguments after the format string), the string <invalid
value> is output instead
•
if the argument type does not correspond to its conversion field specification,
arguments are converted incorrectly.
Example
The following examples show how to use FPRINTF:
fprintf 50,"Syntax error\n"
Writes the string Syntax error to the window or file.
fprintf 50, "Execution time: %d seconds\n", tend-tstart
Prints the result of the calculation to the window or file, in the format:
Execution time: 20 seconds
fprintf 50, "Value is %d\n"
Prints the following to the window or file:
Value=<invalid value>
2-184
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
See also
The following commands provide similar or related functionality:
•
CEXPRESSION on page 2-101
•
FOPEN on page 2-179
•
PRINTF on page 2-238
•
PRINTVALUE on page 2-247
•
VOPEN on page 2-367
•
VCLOSE on page 2-361.
The following macros provide similar or related functionality:
•
fclose on page 3-11
•
fopen on page 3-15
•
fputc on page 3-17
•
fread on page 3-19.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-185
RealView Debugger Commands
2.3.64
GO
The GO command executes the target program starting from the current PC or from a
specified address.
Syntax
GO [=start_address[,]] [ {temp_break [%%passcount][,] }... [;macro-call]]
where:
start_address
Specifies an address at which execution is to begin.
temp_break
Acts as a temporary instruction breakpoint, which is automatically
cleared when program execution is suspended.
passcount
Specifies the number of times the temp_break address is executed before
the command actually halts.
macro_name
Invokes a macro if a temporary break occurs. The macro return value
determines whether execution continues or not. If there is an attached
macro, execution continues when the macro returns a non-zero value. If
the macro returns a zero, execution halts.
Description
This command executes the target program starting from the current PC or from a
specified address. The command also causes program execution to resume after it has
been suspended. Execution continues until a permanent or temporary breakpoint, an
error, or a halt instruction is encountered. You can also use the HALT and STOP commands
to halt execution.
RealView Debugger continues to accept commands after GO has been entered.
Commands that cannot be completed while the target is running (synchronous
commands) are delayed until the target is next stopped. For more information about the
limitations the Target Access imposes while the target is running, see your target
documentation.
You can specify a temporary instruction breakpoint with the GO command, providing
similar functionality to the Go to Cursor GUI command. The temporary breakpoint is
removed as soon as the target stops, whether the breakpoint was hit or not. You can also
associate a macro to be run that can also determine whether the target remains stopped
at the breakpoint.
The GO command runs synchronously.
2-186
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
If you are working with OS-aware images, and the current connection is running in RSD
mode, then the GO command starts the current thread. See the RealView Debugger v3.0
RTOS Guide and the chapter that describes debugging multiple targets in the RealView
Debugger v3.0 User Guide.
Note
When specifying a start address you must be careful to make sure that the processor
stack has been set up and remains balanced.
Examples
The following examples show how to use GO:
GO
Start or resume executing the target program from the current PC.
GO @1
Resume executing the target program from the current PC, stopping when
the current function returns to its caller.
GO write_io; until (x==2)
Resume executing the target program from the current PC, and stop when
x has the value 2.
See also
The following commands provide similar or related functionality:
•
BREAKEXECUTION on page 2-56
•
BREAKINSTRUCTION on page 2-67
•
HALT on page 2-190
•
GOSTEP on page 2-188
•
RUN on page 2-266
•
STEPINSTR on page 2-291
•
STEPLINE on page 2-293
•
STOP on page 2-301.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-187
RealView Debugger Commands
2.3.65
GOSTEP
The GOSTEP command single-steps through the program, invoking a named macro at
every step.
Syntax
GOSTEP macro_name
where:
macro_name
Specifies the name of the macro that is invoked after each instruction.
The macro return value determines whether execution continues or not.
Execution continues when the macro returns a non-zero value.
Description
The GOSTEP command single-steps through the program, invoking a named macro at
every step. Execution starts at the current PC, and continues until you click Stop to halt
execution, the macro returns zero, or a breakpoint is hit. Single-stepping is by source
line for high-level source code and by processor instruction for assembly language
code.
The GOSTEP command runs synchronously.
•
•
Note
Using the command significantly slows target execution speed.
Using the command might cause target program execution errors because of
timing issues.
Example
The following examples show how to use GOSTEP:
GOSTEP checkvariable
Start or resume executing the target program from the current PC. At each
step, invoke a macro called checkvariable. A step is an instruction or a
statement, depending on the source display MODE.
GOSTEP until (y>100)
Resume executing the target program, stopping when the program
variable y exceeds 100. until is a predefined macro (see until on
page 3-57).
2-188
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
See also
The following commands provide similar or related functionality:
•
BREAKEXECUTION on page 2-56
•
BREAKINSTRUCTION on page 2-67
•
HALT on page 2-190
•
GO on page 2-186
•
MODE on page 2-216
•
RUN on page 2-266
•
STEPINSTR on page 2-291
•
STEPLINE on page 2-293
•
STOP on page 2-301.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-189
RealView Debugger Commands
2.3.66
HALT
The HALT command stops target program execution.
Syntax
HALT
Description
The effect of the HALT command depends on the current state of the target:
•
If no OS support is enabled, or HSD support is enabled, this stops the processor.
•
If RSD is enabled, this stops the currently running thread, or the thread attached
to the Code window.
If you are working with OS-aware images, see the RealView Debugger v3.0 RTOS
Guide and the chapter that describes debugging multiple targets in the RealView
Debugger v3.0 User Guide.
•
If RealMonitor support is enabled, then only the application thread stops. The
RealMonitor thread continues running.
See the RealView Debugger v3.0 Target Configuration Guide for details on
configuring and using RealMonitor.
See also
The following commands provide similar or related functionality:
•
AOS_resource-list on page 2-30
•
BREAKINSTRUCTION on page 2-67
•
DOS_resource-list on page 2-141
•
GO on page 2-186
•
GOSTEP on page 2-188
•
OSCTRL on page 2-230
•
RUN on page 2-266
•
STEPINSTR on page 2-291
•
STOP on page 2-301.
2-190
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.67
HELP
The HELP command displays RealView Debugger online help. To do this type:
HELP
The topic Welcome to RealView Debugger Help includes more information about
using online help in RealView Debugger.
Note
This command has no effect when running in command line mode. Use the DHELP or
DCOMMANDS instead. See DHELP on page 2-130 and DCOMMANDS on page 2-118.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-191
RealView Debugger Commands
2.3.68
HOST
The HOST command enables you to run a command on your host operating system.
Syntax
HOST command
where:
command
The command that you want to run on your host operating system. This
can be a DOS command on a Windows system, a Sun Solaris command,
or Red Hat Linux command.
Description
The HOST command enables you to run a command on your host operating system
(Windows, Sun Solaris, or Red Hat Linux).
Note
You cannot use the HOST command to change the current directory pointed to by
RealView Debugger. For example, host cd "c:\my sources" has no effect.
Examples
The following examples show how to use HOST on Windows system:
host dir "c:\my sources"
Lists the contents of directory c:\my sources. This must be in quotes
because there is a space in the path name.
host cd
2-192
Displays the current directory pointed to by RealView Debugger.
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.69
HWRESET
HWRESET is an alias of EMURESET (see page 2-160).
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-193
RealView Debugger Commands
2.3.70
INCLUDE
The INCLUDE command executes commands stored in the specified file.
Syntax
INCLUDE [/S] filename
where:
/S
Stops the commands in the include file being echoed to the display.
However, the commands are still added to the command history list.
filename
Specifies the command file to be read. Quotation marks are optional, but
see Rules for specifying filenames on page 2-180 for details on how to
specify filenames that include a path.
Description
The INCLUDE command executes a group of commands stored in the specified file as
though they were entered from the keyboard. Commands in the file are executed until
the end of the file is reached or an error occurs. If an error occurs, the debugger behaves
as specified by the ERROR command. If a filename extension is not specified, the
debugger automatically appends the extension .inc.
Note
If you want to include a batch file when a target is running, you must first enter the
wait=off command, then include the batch file:
> wait=off
> include myfile.inc
Your batch file can still include the wait=on command, if required.
The INCLUDE command is normally used to perform repetitive or complex initializations,
such as:
•
loading and running programs, setting up breakpoints and initial variable
definitions
•
creating debugger aliases and macros, perhaps for use in later debugging
Note
The DEFINE command, used to create macros, can only be used in an INCLUDE file.
2-194
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
•
running test suites.
You can configure the debugger to load a given include file automatically when a target
connection is made using the Commands setting of the Advanced_Information block for
your target. See the RealView Debugger v3.0 Target Configuration Guide for more
information.
You can also run script files using the -inc argument to RealView Debugger itself. See
the chapter that describes debugging with command scripts in the RealView Debugger
v3.0 User Guide for more information.
The INCLUDE command runs asynchronously unless in a macro.
Example
The following example shows how to use INCLUDE:
INCLUDE "startup.inc"
Read the file startup.inc in the current directory and interpret the
contents as RealView Debugger commands. The file startup.inc might
contain:
; startup.inc 12/12/00
; Author: J.Doe
;
alias sf*ile =dtfile ;99
alias dub =dump /b
vopen 99
See also
The following commands provide similar or related functionality:
•
ALIAS on page 2-23
•
DEFINE on page 2-121
•
ERROR on page 2-164
•
FAILINC on page 2-172
•
JUMP on page 2-199
•
MACRO on page 2-208
•
WAIT on page 2-370.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-195
RealView Debugger Commands
2.3.71
INTRPT
The INTRPT command interrupts the execution of commands.
Syntax
INTRPT
Description
The INTRPT command enables you to interrupt an asynchronous command that the target
is still executing. Commands are held in a queue for execution when the target stops.
This is called pending the command.
Use the CANCEL command to clear pending commands from the list, to stop them being
executed.
You cannot use this command to halt target execution. Use HALT to do this.
Note
Synchronous commands can only be run when target program execution has stopped.
Asynchronous commands can be run at all times.
See also
The following commands provide similar or related functionality:
•
CANCEL on page 2-99
•
HALT on page 2-190
•
WAIT on page 2-370.
2-196
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.72
JOURNAL
The JOURNAL command controls the logging of commands and output.
Syntax
JOURNAL [/A] [{OFF | ON="filename"}]
where:
/A
Appends information to an existing file.
OFF
Closes the journal file and stops collecting information. This is the
default setting.
ON
Starts writing information to the journal file.
filename
Specifies the journal filename. If you do not specify a filename extension,
the extension .jou is used. Quotation marks are optional, but see Rules for
specifying filenames on page 2-180 for details on how to specify
filenames that include a path.
Description
The JOURNAL command starts or stops saving, in a specified file:
•
the commands that you enter
•
any output that is generated by a command
•
error messages
•
text specifically sent to the journal file.
If you are using the GUI, then the log file contains the same information that is
displayed in the Cmd tab of the Output pane.
Note
If the specified file exists and you do not specify the /A parameter, the existing contents
of the file are overwritten and lost.
The JOURNAL command runs asynchronously unless it is in a macro.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-197
RealView Debugger Commands
Example
The following examples show how to use JOURNAL:
JOURNAL ON='c:\temp\log.txt'
Start logging output to the file c:\temp\log.txt, overwriting any existing
file of that name.
JOURNAL /A ON="log"
Start logging output to the file log.jou in the current directory of the
debugger, appending the new log text to the file if it already exists.
JOURNAL OFF
Stop logging output.
See also
The following commands provide similar or related functionality:
•
LOG on page 2-206
•
STDIOLOG on page 2-289
•
VOPEN on page 2-367.
2-198
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.73
JUMP
The JUMP command goes to a label in an include file.
Syntax
JUMP label [,condition]
where:
label
Is the string that identifies the target line in the include file to which you
want control to jump. The first character of the target label must be a
colon :, and it must be followed by a label string.
condition
Is an optional expression that can be evaluated as True or False. The jump
to the specified label takes place only if the condition is True, otherwise
control passes to the next command in the include file.
Description
The JUMP command can only be used in an include file. If you specify a condition, then
the jump takes place only if the condition is True. Otherwise control passes to the next
line in the include file.
You cannot use the JUMP command inside a macro, nor place a target label inside a
macro. However, you can provide similar functionality by using the if, for, while and
do-while flow control constructs in macros (see Chapter 4 RealView Debugger
Keywords).
Example
The following fragment of an include file shows the use of labels and jumps:
initialize
:retry
jump skip_setup,x==1 // variable x is 1 when setup is complete
some_commands
jump retry
// keep trying to initialize
:skip_setup
See also
The following commands provide similar or related functionality:
•
DEFINE on page 2-121
•
FAILINC on page 2-172
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-199
RealView Debugger Commands
2.3.74
LIST
The LIST command displays source code in the Code window.
Syntax
LIST [{#line_number | function_name | @stack_level}]
where:
line_number
Specifies the number of the first line to be displayed.
function_name
Specifies a function that is to have its source code displayed.
@stack_level Displays the line that is returned to after the specified nesting level. For
example, @1 represents the instruction after the call to the current
procedure.
Description
The LIST command displays the source code in the Code window beginning at the
specified line number, stack level, or function name.
You can qualify line number or procedure names by preceding them with a module
name. If you do not specify a parameter for the LIST command, the line pointed to by
the PC is displayed.
The LIST command runs asynchronously unless in a macro.
Example
The following examples show how to use LIST:
list
List the text of the current source file from the current PC location, if that
refers to a source file with debugging information.
list #44
List the text of the current source file from line 44.
list @1
List the text of the source file containing the call to the current procedure,
starting from the statement after the call.
See also
The following commands provide similar or related functionality:
•
CONTEXT on page 2-113
2-200
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
•
•
•
•
•
•
ARM DUI 0175H
DISASSEMBLE on page 2-133
DOWN on page 2-143
EXPAND on page 2-169
SCOPE on page 2-268
UP on page 2-359
WHERE on page 2-373.
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-201
RealView Debugger Commands
2.3.75
LOAD
The LOAD command loads the specified executable file onto the target.
Syntax
LOAD [/A] [/C] [/NI] [{/NP|/SP}] [/NS] [/PD] [/R] absolute_filename[,root]
[;section [,section]...] [;arg1 ...] [&base_address]
where:
/A
This loads and appends another executable image without deleting any
existing one. If the new image file overlaps the addresses of the existing
object modules, the load terminates and displays an error message. If you
want to replace the current image with a new one, use /R.
This option might be the default option if you are running an operating
system extension to RealView Debugger. For more information, consult
the manual provided with the extension.
/C
Converts all symbols to lowercase as they are read by the absolute file
reader.
/NI
Loads only the symbol table. Overlap of addresses is checked if /A is also
used. Does not load the program image code or the data.
/NP
Prevents the command changing the value of the PC.
/NS
Prevents the command loading debug information into the symbol table.
Only the program image is loaded. No check for overlapping addresses is
made. The /NS option can be used to reload the current program image
without affecting the symbol table.
/PD
Pop dialog. Display a dialog for errors and warnings, rather than dumping
them to the log.
/R
Replaces the existing program with the program being loaded.
/SP
Sets the PC to the start address specified in the object module. This is the
default behavior when symbols are loaded, the image file specifies an
entry address and the /A flag is not also specified.
absolute_filename
Specifies the name of the absolute object file to be loaded. Quotation
marks are optional, but see Rules for specifying filenames on page 2-180
for details on how to specify filenames that include a path. Also, see
Rules on page 2-204.
2-202
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
root
Specifies the root associated with the symbols in the program being
loaded. The default root is the filename without an extension. See Rules
on page 2-204 for details on how to specify a root.
section
Lists sections to load when an image is being loaded. The default is to
load all sections. This option is commonly used to reload the initialized
data area when starting a program.
The section names that are available for a specific image can be listed
using the ARM development tools command fromelf or the GNU
development tools command objdump. See Rules on page 2-204 for details
on how to specify sections.
args
Specifies an optional, space-separated, list of arguments to the image.
Note
You can also specify arguments using the ARGUMENTS command. For
example, you can might want to modify the arguments without unloading
the image.
The case of arguments is preserved. See Rules on page 2-204 for details
on how to specify arguments.
base_address Specifies an address offset to be added to all sections when computing the
load addresses.
For this option to work correctly with position-independent code and
data, your program must have been compiled with Position-Independent
Code (PIC) and Position-Independent Data (PID).
For TrustZone® applications, be aware of the following:
•
An image is loaded into the Secure world by default.
•
To load an image into the Normal world, then prefix the address
with &N:. For example:
—
the following command loads an image at the image entry
point:
load ‘C:\myproject\myimage.axf’ &N:0
—
the following command loads a position-independent image:
load ‘C:\myproject\myimage.axf’ &N:0x1000
Note
You can also prefix the address with &S:, if you want to explicitly identify
a Secure world address.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-203
RealView Debugger Commands
Description
The LOAD command loads the specified executable file into the debug target. The file
specified must be a format supported by the RealView Debugger.
To reset the initialized values of program variables after entering a RESET or a RESTART
command, you must reload your program using the LOAD command. The RELOAD
command checks the file date to determine whether program symbols have changed and
therefore whether they must be reloaded.
If a load is performed that includes the symbol table, any breakpoints or macros
referring to symbols in the previous root are invalidated.
The LOAD command runs synchronously.
Rules
Follow these rules when using LOAD:
•
absolute_filename, root, section, and args must all be placed in the same set of
quotes. For example, on Windows:
load /pd/r 'c:\source\demofile.axf ;ER_RO,ER_ZI ;12345' &0x8A00
•
If you want to specify arguments, but not a section, you must specify an empty
section. All sections are loaded in this case. For example:
load /pd/r 'c:\source\myfile.axf;;arg1 arg2 arg3'
•
Where an argument includes spaces, additional quotes must be used. Use single
quotes around arguments if the outer quotes are double quotes. Use double quotes
around arguments if outer quotes are single quotes. For example:
load /pd/r "myimage.axf ;;12345 'Argument Two'" &0x8A00
•
base_address must be placed outside the quotes, and must be the last parameter
specified.
Examples
The following examples show how to use LOAD:
load 'c:\source\myfile.axf'
Load the executable file myfile.axf to the target.
2-204
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
load /ni/sp 'c:\source\rtos.axf'
Load the symbol table for an image rtos.axf that is also in target ROM,
setting the PC to the program start address so that a subsequent GO runs
the program.
load /np 'c:\source\mp3.axf'
Load the executable library mp3.axf onto the target so that the preloaded
executable can use it. The PC is not modified. Symbol table entries in
mp3.axf are added to the existing symbol table.
Note
Ensure that executables you load in this way occupy distinct memory
regions. No relocation is performed by RealView Debugger unless you
specify a base offset.
load /pd/r 'c:\source\demofile.axf ;ER_RO,ER_ZI' &0x8A00
Load the executable file demofile.axf to the default target. Specify an
offset added to all sections to compute the load addresses. Load only the
specified sections ER_RO and ER_ZI.
load /pd/r 'c:\source\myfile.axf;;arg1 arg2 arg3'
Load the executable file myfile.axf to the default target using an
arguments list. An empty section list is given so all sections are loaded.
See also
The following commands provide similar or related functionality:
•
ADDFILE on page 2-21
•
ARGUMENTS on page 2-32
•
DTFILE on page 2-149
•
GO on page 2-186
•
RELOAD on page 2-257
•
RESET on page 2-259
•
RESTART on page 2-263
•
RUN on page 2-266
•
UNLOAD on page 2-357.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-205
RealView Debugger Commands
2.3.76
LOG
The LOG command records user input and places it in a specified file.
Syntax
LOG [/A] [{OFF | ON="filename"}]
where:
/A
Specifies that new records are to be added to any that already exist in the
specified file.
OFF
Closes the log file and stops collecting information. This is the default.
ON
Starts writing information to the log file.
filename
Specifies the name of the log file. Quotation marks are optional, but see
Rules for specifying filenames on page 2-180 for details on how to
specify filenames that include a path.
Description
This command records user input and places it in a specified file. Commands that are
issued but not successfully completed are written to the log file as comments along with
the associated error codes. All successful commands are written to the log file, so the
file can be used as an include file.
Note
If you want to use the log file as an include file, first remove the log command that
appears at the start of the file.
If the specified file exists and you do not specify the /A parameter, the existing contents
of the file are overwritten and lost. A window number (28) is associated with the log file
so that text can be written to it using FPRINTF. See Window and file numbers on page 1-5
for details.
Using LOG with no parameters shows the current log file, if any. User input is recorded
in the log file until the LOG OFF command is issued.
The LOG command runs asynchronously unless in a macro.
2-206
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
Example
The following examples show how to use LOG:
LOG ON='c:\temp\log.txt'
Start logging output to the file c:\temp\log.txt, overwriting any existing
file of that name.
LOG /A ON="log"
Start logging output to the file log.log in the current directory of the
debugger, appending the new log text to the file if it already exists.
LOG OFF
Stop logging output.
See also
The following commands provide similar or related functionality:
•
JOURNAL on page 2-197
•
STDIOLOG on page 2-289
•
VOPEN on page 2-367.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-207
RealView Debugger Commands
2.3.77
MACRO
The MACRO command enables you to run a predefined or user-defined macro.
Syntax
MACRO macroname(parameters...)
where:
macroname
Specifies that name of the macro.
parameters
The actual values of parameters required by the macro.
Description
The MACRO command runs a macro. You can run macros in these ways:
•
as part of the expression in a CE command
•
as the argument to the MACRO command
•
as a command on its own.
The CE command enables you to see the result of the macro, as set with the RETURN
statement. If the macro does not explicitly return information, or you do not have to
know the return value, you can use the macro name as a command. However, in this case
the macro is only run if the name does not match any other debugger command or any
alias defined with ALIAS. You can therefore use the MACRO command to ensure that the
command that is run is the macro, and not a debugger command or an alias.
Note
It is recommended that, if you call macros in an include file and they do not return a
value, that you use MACRO to make the call. This ensures that the future operation of the
include file is not changed if new commands are added to the debugger, for example
using ALIAS.
Macros can also be invoked as actions associated with:
•
a window, for example VMACRO
•
a breakpoint, for example BREAKEXECUTION
•
deferred commands, for example BGLOBAL.
Note
Macros that are not directly invoked from the command line cannot execute GO, or
GOSTEP, or any of the stepping commands, for example STEPINSTR.
2-208
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
Example
The following example shows how to use MACRO:
macro fgetc(50)
Read a character from the file associated with the file number 50 and
throw it away, with the side effect of advancing the file pointer to the next
character.
See also
The following commands provide similar or related functionality:
•
ALIAS on page 2-23
•
CEXPRESSION on page 2-101
•
DEFINE on page 2-121
•
INCLUDE on page 2-194
•
PRINTSYMBOLS on page 2-242.
•
SHOW on page 2-284
•
VMACRO on page 2-365.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-209
RealView Debugger Commands
2.3.78
MEMMAP
The MEMMAP command enables you to define and control memory mapping.
Syntax
MEMMAP [,qualifier...] [={address|address-range}]
where:
qualifier
One of the following:
enable
Turns on memory mapping control. This is the
default.
The debugger only accesses the target memory in
regions that are defined in the map, and uses the
access method to determine the operations that are
permitted.
disable
Turns off memory mapping control. The debugger
assumes that all memory is RAM.
delete
Deletes memory map entries:
•
if you supply a memory map entry start
address in address, delete that entry
•
if you supply no arguments, delete all
memory maps.
autosection
When loading an image, create memory mappings
automatically from the sections of the image. This
is default behavior.
updateautomap
Update the memory map based on the information
provided in the board file. This is automatically
done when:
•
the debugger starts up
•
the target program stops
•
the registers that control the map are changed
by you.
This qualifier enables you to manually request a
map update.
define
2-210
Creates a new memory region using the address
range in address. You can specify additional
information about the region with the type, access,
and description qualifiers.
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
description:text
Set the name of this memory map region to text.
This is used to label the entry for your own
reference.
access:text
Set the memory access type to text, which must be
one of the predefined strings:
asize:size
type:text
ARM DUI 0175H
RAM
memory can be read and written with no
specific provision.
ROM
memory can only be read.
WOM
memory can only be written.
NOM
there is no memory in this region.
Flash
there is Flash memory in this region. It
can always be read, and it can be written
as required using the Flash memory
procedure if this is defined.
Auto
There is memory in this region but the
type is inferred by the image that is
loaded. Memory in regions not defined
by the image are assumed to be absent
(equivalent to NOM).
Prompt
There is memory in this region but you
set the type by responding to a prompt
when loading an image to it. The default
is there is no memory.
The size of memory accesses, where size is one of:
1
1-byte accesses
2
2-byte accesses
4
4-byte accesses
8
8-byte accesses
Set the memory type to text, which must be one of
the defined memory type strings for the processor
architecture:
•
For ARM processors, the only available type
is Any.
•
For CEVA, Inc. CEVA-Oak,
CEVA-TeakLite, and CEVA-Teak
processors, and LSI Logic ZSP processors,
the types are:
— Program
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-211
RealView Debugger Commands
—
—
fme:filename
address
Data
IO.
For Flash memory, the Flash programming method
file (*.fme) that is to be used. You must enter the full
path and file name, enclosed in double quotes.
The memory region, specified as a single address (delete).
address-range
The memory region, specified as an address range (define). The start and
the end of the range is included in the range. See Specifying address
ranges on page 2-2 for details on how to specify an address range.
Description
The MEMMAP command enables you to:
•
Enable and disable memory mapping.
•
Define new memory regions based on type and access rights. The list of valid
access rights and types is defined by the Target Access and processor.
•
Delete memory map entries.
Any memory map settings in a BCD file assigned to the connection are not changed. If
you disable and enable memory mapping, any changes you make to the memory map
with MEMMAP are preserved. However, the changes are lost when you disconnect. When
you next connect to the target, the original memory map from the assigned BCD file is
restored.
For more details about memory mapping, see the chapter that describes mapping target
memory in the RealView Debugger v3.0 User Guide.
Examples
The following examples show how to use MEMMAP:
memmap,define 0x10000..0x20000
Creates a memory map region from 0x10000 to 0x20000, inclusive. The
length of the region is 0x10001 bytes.
memmap,define 0x10000..+0x10000
Creates a memory map region from 0x10000 to 0x1FFFF, inclusive. The
length of the region is 0x10000 bytes.
2-212
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
mmap,def,access:Flash,type:Any,asize:4,descr:"Intel",fme:"C:\myflash\IntegratorA
P\flash_IntegratorAP.fme"=0x24000000..0x25FFFFFF
Define a Flash memory region called Intel, using 4-byte memory
accesses, and using the Flash programming method file located in
C:\myflash\IntegratorAP\flash_IntegratorAP.fme.
mmap,def,access:RAM,type:Any,description:"Data space"=0x0000..0x7FFF
Define a read/write memory region called Data space in the first 32KB of
memory.
mmap,def,access:ROM,type:Any,descr:"Bootrom"=0x10000..+0xFFFF
Define the 64KB region starting at 0x10000 as a read-only region called
Bootrom.
mmap,delete =0x10000
Delete the memory map entry that starts at 0x10000, resetting the map for
that area to the Auto map.
mmap,delete
Delete all memory map entries, resetting the map to the default Auto map
over the whole address space.
mmap,disable Disable memory mapping.
Alias
MMAP is an alias of MEMMAP.
See also
The following commands provide similar or related functionality:
•
DUMPMAP on page 2-155
•
FLASH on page 2-176
•
MEMWINDOW on page 2-214
•
SETMEM on page 2-273.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-213
RealView Debugger Commands
2.3.79
MEMWINDOW
The MEMWINDOW command sets the base address of the memory pane.
Note
This command is not available when running in command line mode.
Syntax
MEMWINDOW [{/B|/H|/W|/8|/16|/32}] address
where:
/B, , /8
Sets the display format to byte (8 bits).
If the processor naturally addresses bytes (for example, ARM7TDMI)
then this is the default setting. However, CEVA and ZSP DSPs have a
natural addressing of a word (16 bits), so /H is the default for CEVA and
ZSP DSPs.
/H, , /16
Sets the display format to halfword (16 bits).
/W, , /32
Sets the display format to word (32 bits).
address
The base address for the memory pane.
Description
The MEMWINDOW command sets the base address of the memory pane. You can specify the
size of each printed value using the qualifiers. If you do not specify a size, the previous
size is retained.
Example
The following example shows how to use MEMWINDOW:
memw /b 0x200
Display in the memory pane bytes from address 0x200.
See also
The following command provides similar or related functionality:
•
SETMEM on page 2-273.
2-214
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.80
MMAP
MMAP is an alias of MEMMAP (see page 2-210).
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-215
RealView Debugger Commands
2.3.81
MODE
The MODE command switches the code window between disassembly and source view.
Note
This command has no effect when running in command line mode.
Syntax
MODE [{HIGHLEVEL | ASSEMBLY}]
where:
HIGHLEVEL
Set the code window to the source view.
ASSEMBLY
Set the code window to the disassembly view.
Description
The MODE command enables you to toggle between disassembly and source modes of the
Code view, and along with this, the stepping mode of the GOSTEP command. Without an
argument, the current mode is toggled. With an argument, the current view mode is set
to the indicated mode.
See also
The following commands provide similar or related functionality:
•
CONTEXT on page 2-113.
•
DISASSEMBLE on page 2-133.
•
GOSTEP on page 2-188
•
LIST on page 2-200.
2-216
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.82
MONITOR
The MONITOR command adds the named variable to the list of monitored, or watched,
variables, displayed in the Watch pane.
Note
This command is not available when running in command line mode.
Syntax
MONITOR variable_name
where:
variable_name
The name of a variable or expression in the current context, or a
path name, using the \\module\proc\variable syntax, for a
variable that you are monitoring.
Description
The MONITOR command adds a variable to the list of watched variables displayed in the
Watch pane of the debugger. This list displays the values of each variable every time the
debugger stops, for example at a breakpoint. If the variable is out of scope when the
debugger stops, the value is printed as Symbol not found without qualification.
You can add pointer and structure variables to this list. If you do, the values of members
and referenced variables can be displayed using the icon next to the pointer name in
the watch pane.
Note
•
MONITOR is equivalent to display, found in some other debuggers.
•
You can print the value of a variable using the CEXPRESSION or PRINTVALUE
command.
Examples
The following examples show how to use MONITOR:
monitor count
Monitor the value of the variable count, displaying the value as an integer.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-217
RealView Debugger Commands
moni this
Monitor the members of the current C++ class, through the C++ class
pointer this.
moni \\MAIN_1\ALLOC\maxalloc
Monitor the global variable maxalloc from the file main.c.
See also
The following commands provide similar or related functionality:
•
CEXPRESSION on page 2-101
•
CONTEXT on page 2-113
•
DUMP on page 2-153.
•
NOMONITOR on page 2-221
•
PRINTVALUE on page 2-247.
2-218
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.83
NAMETRANSLATE
The NAMETRANSLATE command manipulates the host/target name translation list.
Note
This command is deprecated.
Syntax
NAMETRANSLATE [,qualifier] [=name-translation, ...]
where:
qualifier
If specified, must be one of the following:
replace
The current name translation list is to be replaced by the list
specified in this command.
delete
The current name translation list is to be deleted.
If you do not supply a qualifier, the name translation list specified in this
command is appended to the current name translation list.
name_translation
A list of name translations. The format is:
"hname=tname"
where hname is the filename on the host and tname is the filename on the
target. Both hname and tname can be a comma-separated list.
Each translation must be enclosed in double quotes.
Description
The NAMETRANSLATE command extends, replaces, or deletes the name translation list.
Name translation enables a host filename to be different from a target filename.
If you supply no arguments, the NAMETRANSLATE command prompts you to enter a name
translation for the current board:
•
If you enter this command in the Cmd tab when running in GUI mode, a prompt
dialog is displayed and shows any existing translation.
•
If you enter this command when running in command line mode, you can press
Enter to show the current name translation.
If translating from host name to target name, the first target name in the list is used. If
translating from target name to host name, the first host name in the list is used.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-219
RealView Debugger Commands
Examples
The following examples show how to use NAMETRANSLATE:
nametranslate "hostfile1=targetfile1","hostfile2=targetfile2"
nametranslate "hostfile1,hostfile2,hostfile3=targetfile1,targetfile2"
See also
The following commands provide similar or related functionality:
•
LOAD on page 2-202
•
PATHTRANSLATE on page 2-233.
2-220
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.84
NOMONITOR
The NOMONITOR command deletes variables from the Watch pane.
Note
This command is not available when running in command line mode.
Syntax
NOMONITOR [{linenum | linenum..linenum}]
where:
linenum
A line number or a line number range for the items to delete.
Description
This NOMONITOR command deletes variables added to the Watch pane by MONITOR, using a
line number in the pane to identify the item to delete.
Line numbers start at 1 for the first line and increment by one for each top-level variable.
A structure or array variable that has been expanded using the icon to the left of the
variable name, , counts as only one line. If you reference a line that is not present, the
command is ignored.
You can delete several consecutive elements from the Watch pane using a line number
range, separating the first and last line numbers with a double-dot (..). If the end of a
line range is not present, only the lines that are present are deleted.
If you do not specify a line number or line number range, all lines are deleted from the
Watch pane.
Examples
The following examples show how to use NOMONITOR:
nomonitor 2
Delete the variable on line 2 of the Watch pane.
nomonitor 2..4
Delete the variables on lines 2, 3, and 4 of the Watch pane.
See also
The following command provides similar or related functionality:
•
MONITOR on page 2-217.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-221
RealView Debugger Commands
2.3.85
ONSTATE
The ONSTATE command executes the associated command when a particular event
occurs.
Syntax
ONSTATE [,event] [,timer] [,replace] [command]
where:
Specifies the event to trigger on from the following list:
event
start
Execute the command immediately before program execution
starts.
stop
Execute the command immediately after program execution
stops.
starttimed
Execute the command immediately before program execution
starts and at the specified interval thereafter until the program
stops running. The target must support execution of
commands on a running target.
tstart
An alias of starttimed.
stoptimed
Execute the command immediately after program execution
stops and at the specified interval thereafter, until the debugger
starts the program again or the target is disconnected. Specify
the time interval using the ,timer qualifier, with the interval in
milliseconds.
tstop
An alias of stoptimed.
reset
If target reset is detected by the debugger, execute the
command.
timer
A qualifier used to specify the time interval used with timed events. The
minimum interval is 10ms.
replace
A qualifier used to specify that this ONSTATE command replaces all
previous ONSTATE commands for the same event.
If this qualifier is not specified, new commands for an event are added to
the end of a list of commands to execute when the event happens.
command
2-222
The debugger command to execute. It can be more than one word.
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
Description
The ONSTATE command executes a given debugger command when a specified event
occurs. If no arguments are provided, ONSTATE lists out the currently registered
commands for each type of event.
Examples
The following examples show how to use ONSTATE:
onstate,tstop,timer:5000 ce 0x8000
While the debugger has the target stopped at a five-second interval,
execute the command ce 0x8000.
onstate,stop,replace
Delete the event commands associated with the stop event.
onstate
List the current event commands in the following format:
On Start:
<no commands registered>On Stop:
<no commands registered>On Start Timed (every 0 msecs):
<no commands registered>On Stop Timed (every 5000 msecs):
ce 0x8000On Reset:
<no commands registered>
See also
The following command provides similar or related functionality:
•
BGLOBAL on page 2-36.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-223
RealView Debugger Commands
2.3.86
OPTION
The OPTION command enables you to change the settings of debugger options for this
session, or to display their current settings.
Syntax
OPTION [option = value]
where:
option
Specifies a setting from the list:
RADIX
The number base used for numeric input and output. The value
must be one of:
DECIMAL
The default input number base is decimal, base 10,
using the digits 0..9. You can also suffix a decimal
number with t. This is the default setting.
HEXADECIMAL
The default input number base is hexadecimal, base
16, using the digits 0..9 and a..f, or 0..9 and A..F.
You can also prefix a hexadecimal number with 0x
or suffix it with h.
Note
It is suggested that you use either the 0x prefix or h
suffix for every hexadecimal number. This ensures
that the value is valid if you change the radix to
decimal. For example, 0x80FF is always valid, but
80FF is invalid for a decimal radix.
Also, if you use the h suffix, it is suggested that you
prefix the hexadecimal number with a zero digit to
avoid confusion with symbol names, for example,
0FADEh.
OUTDEC
The output number base is decimal, base 10, using
the digits 0..9. This is the default setting.
The output number base is hexadecimal, base 16, is
prefixed with 0x and uses the digits 0..9 and A..F.
The number base for a particular session can also be set in the
workspace options.
OUTHEX
2-224
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
DEMANDLOAD
A flag that controls when the debugger symbol table is loaded.
The value must be one of:
ON
The debug sections of the executable file are loaded
into the debugger symbol table as required,
speeding up the target load time. This is the default
setting.
OFF
The whole symbol table is loaded from the file
when the LOAD or RELOAD commands are issued.
ENDIANITY
A flag that indicates the endianness of the target. The value
must be one of:
LITTLE
The least significant byte of data is in the lowest
address in memory, or appears first in a word in a
data stream.
BIG
The most significant byte of data is in the lowest
address in memory, or appears last in a word in a
data stream.
Note
The option changes how the debugger sends and receives data
from the target. It cannot be used to change the endianness of
the target itself. You must set this value, or the equivalent
board file setting, to reflect the target, or the debugger might
not work with your target.
FRAMESTOP
A flag that controls the behavior of the call stack algorithm.
The value must be one of:
ON
The call stack stops when a stack frame is
encountered that does not have associated debug
information.
OFF
The call stack stops when the end of stack is
reached or when the stack frame no longer makes
sense.
STEPPING A flag that controls the high-level stepping behavior in the
disassembly view (that is, in the Dsm tab of the File Editor
pane). Lines of interleaved source in the disassembly view are
prefixed by either >>> or ---. This flag determines whether
lines prefixed with --- are stepped to or stepped over.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-225
RealView Debugger Commands
The value must be one of:
ALL
Step to the first instruction of the next line of source
prefixed with >>> or ---.
STATEMENT Step to the first instruction of the next line of source
prefixed by >>>. That is, step over any lines of
source prefixed with ---. This is the default.
Defines the value that you want to assign to the specified option.
value
Description
The OPTION command enables you to change the settings of debugger options for this
session, or to display their current settings. If you supply no parameters, the command
displays the current settings of various options.
Examples
option
Displays the current option settings, for example:
DEMANDLOAD = ON
ENDIANITY = LITTLE
FRAMESTOP = OFF
RADIX = DECIMAL, OUTHEX
STEPPING=STATEMENT
option radix=hex
The numerical input base is hexadecimal. The following are valid
numbers when the default number base is hexadecimal:
•
0xAB (AB hex, 171 decimal)
•
0AB (AB hex, 171 decimal)
•
45 (45 hex, 69 decimal)
•
45t (45 decimal)
•
45H (45 hex, 69 decimal).
and the following are not valid:
•
AB (does not start with a digit)
•
0t45 (t must be at the end).
The following example opens a user-defined window with the name User80 followed by
a window named User50:
>option radix=hex
>vopen 50
>option radix=dec
>vopen 50
2-226
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
See also
The following commands provide similar or related functionality:
•
CEXPRESSION on page 2-101
•
LOAD on page 2-202
•
PRINTVALUE on page 2-247
•
SETTINGS on page 2-279
•
STEPLINE on page 2-293
•
STEPO on page 2-298.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-227
RealView Debugger Commands
2.3.87
OS action commands
OS action commands. See AOS_resource-list on page 2-30 for details.
2-228
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.88
OS resource commands
OS resource commands. See DOS_resource-list on page 2-141 for details.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-229
RealView Debugger Commands
2.3.89
OSCTRL
The OSCTRL command controls debugging of OS-aware targets.
Syntax
OSCTRL ,qualifier
where:
qualifier
Specifies the action, and can be one of:
addfilter="filter;process;module"
For OS plugins that support event debugging, adds a filter to
control selective loading of the debug symbols, where:
filter
The name of the filter. This can be any name that
uniquely identifies the filter. It must not include a
comma (,) or semicolon (;).
process
The process name that this filter is to match against.
Specify * (asterisk) to match any process name.
The module name that this filter is to match against.
Specify * (asterisk) to match any module name.
If you want to add multiple filters, then enter an
osctrl,addfilter command for each filter.
module
clearfilter
For OS plugins that support event debugging, clears all debug
symbol filters set with addfilter.
enableeventcapture
Enables the capture of target operating system events under
OS plugins that support event debugging. Use the setevents
qualifier to specify the events to be filtered.
enable_rsd
Enable RSD.
disable_rsd
Disable RSD.
properties_rsd
Report the current RSD properties on the screen.
2-230
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
setevents=events
For OS plugins that support event debugging, a bitmap
representing the events that are filtered (bit zero represents the
first event). The events that you can filter depend on the OS
plugin you are using.
These events are the same as the fields in the Connection
Properties Events group. See the appendix that describes the
configuration settings in the RealView Debugger v3.0 Target
Configuration Guide for more details.
Description
The OSCTRL command enables you to control debugging of OS-aware targets. You can:
•
Set debug symbol file filtering.
•
Enable capture of specific events.
•
Enable or disable RSD.
•
Display the current RSD properties, such as:
—
the status of the RSD module
—
settings as specified in your board file (or .bcd file where available)
—
RSD breakpoints.
If you are using the GUI, then the properties are displayed in the Output pane.
The filters are stored in the workspace file. However, you can only modify the filters
using either the OSCTRL command or the Debug Symbols - File Filter dialog box (see the
RealView Debugger v3.0 RTOS Guide for more details).
Examples
The following examples shows how to use OSCTRL:
osctrl,enable_rsd
Enables RSD for the current target connection.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-231
RealView Debugger Commands
osctrl,enableeventcapture
osctrl,setevents=3
osctrl,addfilter="Filter 1;dhry;*"
Enables the capturing of events, and specifies that the first two events
only are to be captured (the setevents value is interpreted as a bitmap).
Also, a filter is defined (Filter 1). This filter causes RealView Debugger
to prompt you to load symbols when any module is in scope for a process
that has the text dhry in the name.
See also
The following commands provide similar or related functionality:
•
AOS_resource-list on page 2-30
•
BREAKINSTRUCTION on page 2-67
•
DOS_resource-list on page 2-141
•
HALT on page 2-190
•
STOP on page 2-301
•
THREAD on page 2-307.
2-232
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.90
PATHTRANSLATE
The PATHTRANSLATE command manipulates the host/target name translation list.
Note
This command is deprecated.
Syntax
PATHTRANSLATE [,qualifier] [=path-translation, ...]
where:
qualifier
If specified, must be one of the following:
replace
The current path translation list is to be replaced by the list
specified in this command.
default
The current path translation list is to be deleted.
delete
The current path translation list is to be deleted.
If you do not supply a qualifier, the path translation list specified in this
command is appended to the current path translation list.
path_translation
A list of path translations, that must be enclosed in quotes ("). The format
is:
"hpath=tpath"
where hpath is the path on the host and tpath is the path on the target.
Both hpath and tpath can be a comma-separated list.
Target can be '-' which means a grab of a process with no path prepends
the host path.
Description
The PATHTRANSLATE command extends, replaces, or deletes the path translation for a
board. Path translation enables the paths on a host computer to be different from those
on a remote target.
If you do not provide a path translation in the command, you are prompted to enter a
path translation for the current board:
•
ARM DUI 0175H
If you enter this command in the Cmd tab when running in GUI mode, a prompt
dialog is displayed and shows any existing translation.
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-233
RealView Debugger Commands
•
If you enter this command when running in command line mode, you can press
Enter to show the current translation.
If translating from host name to target name, the first target name in the list is used. If
translating from target name to host name, the first host name in the list is used.
Examples
The following examples show how to use PATHTRANSLATE:
pathtranslate "hostpath1=targetpath1","hostpath2=targetpath2"
pathtranslate "hostpath1,hostpath2,hostpath3=targetpath1,targetpath2"
See also
The following commands provide similar or related functionality:
•
LOAD on page 2-202
•
NAMETRANSLATE on page 2-219.
2-234
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.91
PAUSE
The PAUSE command waits for a specified number of seconds.
Syntax
PAUSE [n]
where:
Specifies a period of time, in seconds.
n
Description
The PAUSE command pauses command file reading. It stops execution of commands
from the include file for a specified time, or until you indicate that execution can
continue.
If you do not supply a parameter, or supply a value of zero, the command waits
indefinitely. Execution continues when you press Return, Enter, or Cancel.
If you supply a positive integer, a countdown of seconds from that number to zero is
displayed. Execution continues when zero is reached, or earlier if you press Return,
Enter, or Cancel.
Note
This command requires that RealView Debugger is connected to a debug target.
Examples
The following examples show how to use PAUSE:
pause 5
Wait for 5 seconds, or for you to press Return, Enter, or Cancel, and then
continue.
pause
Wait for you to press Return, Enter, or Cancel.
See also
The following command provides similar or related functionality:
•
WAIT on page 2-370.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-235
RealView Debugger Commands
2.3.92
PRINTDSM
The PRINTDSM command prints disassembled target memory at a specified address or
between a range of addresses.
Syntax
PRINTDSM { address | addressrange }
where:
address
The address containing the line of code to be disassembled. For example,
0x8000.
addressrange The start and end addresses containing the code to be disassembled. For
example, 0x8000..0x8FFF specifies addresses in the address range 0x8000
to 0x8FFF. See Specifying address ranges on page 2-2 for more details.
Description
The PRINTDSM command prints disassembled target memory at the specified address, or
in the specified address range:
•
if you are using the GUI, then output is sent to the Cmd tab of the output pane
•
if you have a journal file open, the disassembly is also sent to that file.
The output is in the same format as the disassmbly in the Dsm tab of the File Editor
pane.
Note
This command requires that RealView Debugger is connected to a debug target.
Examples
The following examples use the dhrystone image to show how to use PRINTDSM:
printdsm 0x8000..0x800F
Prints a disassembled version of the code from 0x8000 to 0x800F, for
example:
__main:
RW:00008000 EA000000
RW:00008004 EA00069C
__scatterload_rt2:
RW:00008008 E28F0028
RW:0000800C E8900C00
2-236
B
B
__scatterload_rt2
__rt_entry
ADR
LDM
r0,{pc}+0x30 ; 0x8038
r0,{r10,r11}
Copyright © 2002-2006 ARM Limited. All rights reserved.
<0x8008>
<0x9a7c>
ARM DUI 0175H
RealView Debugger Commands
printdsm main..+16
Prints a disassembled version of the 16 bytes of code starting from the
address of function main, for example:
main:
RW:00008200
RW:00008204
RW:00008208
RW:0000820C
E92D47F0
E24DD070
E3A00030
EB00040E
PUSH
SUB
MOV
BL
{r4-r10,r14}
r13,r13,#0x70
r0,#0x30
malloc
<0x924c>
See also
The following commands provide similar or related functionality:
•
DISASSEMBLE on page 2-133
•
DUMPMAP on page 2-155
•
DUMP on page 2-153
•
SETTINGS on page 2-279.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-237
RealView Debugger Commands
2.3.93
PRINTF
The PRINTF command prints formatted text on the screen.
Syntax
PRINTF "format_string" [,argument]...
where:
format_string
Is a format specification conforming to C/C++ rules with extensions. It
might be a text message, or it can describe how one or more arguments
are to be presented. See Format string syntax for details.
Note
Only the first 256 characters of the string are displayed, even after
formatting is applied.
argument
Is a list of values that you want displayed in the way described by the
specified format.
Description
The PRINTF command uses a special format string to write text and numbers to the
screen. If you are using the GUI, then they are displayed in the Output pane. It works in
a similar way to the ANSI C standard library function printf(), with a number of
extensions to better support the debugger environment.
Format string syntax
The message in format_string is a string. If there are no % characters in the string, the
message is written out and any arguments are ignored. The % symbol is used to indicate
the start of an argument conversion specification. The syntax of the specification is:
%[flag][fieldwidth][precision][lenmod]convspec
where:
2-238
flag
An optional conversion modification flag -. If specified, the result is
left-justified within the field width. If not specified, the result is
right-justified.
fieldwidth
An optional minimum field width specified in decimal.
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
precision
An optional precision specified in decimal, with a preceding . (period
character) to identify it.
lenmod
An optional argument length specifier:
convspec
h
a 16-bit value
l
a 32-bit value
ll
a 64-bit value
The possible conversion specifier characters are:
%
A literal % character.
m
The mnemonic for the processor instruction in memory
pointed to by the argument. The expansion includes a newline
character. The information that is printed includes:
•
the memory address in hexadecimal
•
the memory contents in hexadecimal
•
the instruction mnemonic and arguments
•
an ASCII representation of the memory contents, if
printable.
H
A line from the current source file, where the argument is the
line number.
h
A line from the current source file, where the argument is a
target memory address.
d, i, or u An integer argument printed in decimal. d and i are equivalent,
and indicate a signed integer. u is used for unsigned integers.
x or X
An integer argument printed in unsigned hexadecimal. x
indicates that the letters a to f are used for the extra digits, and
X indicates that the letters A to F are used.
c
A single character argument.
s
A string argument. The string itself can be stored on the host
or on the target.
p
A pointer argument. The value of the pointer is printed in
hexadecimal.
e, E, f, g, or G
A floating point argument, printed in scientific notation, fixed
point notation, or the shorter of the two. The capital letter
forms use a capital E in scientific notation rather than an e.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-239
RealView Debugger Commands
Rules
The following rules apply to the use of the FPRINTF command:
•
if there are too many arguments, some of them are not printed
•
if there are too few arguments (that is, there are more conversion specifiers in the
format string than there are arguments after the format string), the string <invalid
value> is output instead
•
if the argument type does not correspond to its conversion field specification,
arguments are converted incorrectly.
Examples
The following examples show how to use PRINTF:
printf "Found %d errors\n", ecount
Print out a message, substituting the value of ecount. So, if ecount had the
value 5, the message is:
Found 5 errors
printf "Completion %%\n", runs
Print out a message that includes a single percent symbol. The argument
runs is ignored, so the message is:
Completion %
printf "%h\n", #82
Print out a source file line 82. For example:
REG
char
Ch_Index;
printf "Var is %hd.\n", short_var
Print out the variable short short_var. For example:
Var is 22.
printf "Instruction1 %m\nInstruction2 %m", 0x100, 0x104
Print out the disassembly of the contents of location 0x100, two newlines
and the contents of location 0x104. For example, it might print:
2-240
Instruction1 000000100 20011410
ANDCS
r1,r1,r0,LSL r4
Instruction2 000000104 20011412
ANDCS
r1,r1,r2,LSL r4
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
printf "Average execution time %f secs\n", totaltime / (double)20
Print out a message, substituting the value of the expression. So, if
totaltime had the value 523.3, the message is:
Average execution time 26.165 secs
See also
The following commands provide similar or related functionality:
•
CEXPRESSION on page 2-101
•
FPRINTF on page 2-182
•
PRINTTYPE on page 2-245
•
PRINTVALUE on page 2-247.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-241
RealView Debugger Commands
2.3.94
PRINTSYMBOLS
The PRINTSYMBOLS command displays information about the specified symbol including
its name, data type, storage class, and memory location.
Syntax
PRINTSYMBOLS [{/C|/D|/E|/F|/M|/R|/T|/W}] [name[*]] [{\|\\|*}]
where:
/C
Displays functions and labels.
/D
Displays data and macros.
/E
Displays any symbol declaration conflicts.
Mismatch errors occur when global variables are declared with different
types in different modules or global functions are declared with different
return types or argument counts in different modules.
/F
Displays symbols in all roots (all contexts). All matching names in all
roots are shown.
/M
Displays modules and module names.
/R
Displays reserved symbols, registers, internal variables, and any memory
mapped registers.
/T
Displays types.
/W
Displays symbols in wide format (names only).
name
Specifies the symbolic unit.
The wildcard character (*) can be used to match the first zero or more
letters of a name. The * must be the last character in the partial name.
2-242
*
An asterisk as the only parameter displays all symbols in the current
context.
\
Displays information about all modules.
\\
Displays information about debugger symbols.
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
Description
The PRINTSYMBOLS command displays information about the specified symbol including
its name, data type, storage class, and memory location. If you want to see all modules
in your current root, use only \ and \\. If you want to see all symbols in a particular
function or module, append \ to the module name.
PRINTSYMBOLS with no options specified acts the same as the CONTEXT command. Also,
PRINTSYMBOLS /F acts the same as CONTEXT /F.
Note
The symbol name must be specified in the correct case, even when a wildcard is used.
Examples
The following examples show how to use PRINTSYMBOLS:
printsymbols funct1\
Prints the names of all symbols within funct1, for example, all local
variables.
printsymbols /m *
Prints the names of all modules in the image. For example, for the
dhrystone image this command prints:
@dhrystone\\DHRY_H
@dhrystone\\TIME_H
@dhrystone\\DHRY_1
: Codeless Include File.
: Codeless Include File.
: High level module.
Code section = 0x00008278
Code section = 0x0000D8BC
@dhrystone\\DHRY_2
: NON-LOADED module.
Code section = 0x0000807C
@dhrystone\\STARTUP_S : Assembly level module.
Code section = 0x00008000
@dhrystone\\SCATTER_S : Assembly level module.
Code section = 0x00008008
@dhrystone\\SYSAPP
: Assembly level module.
Code section = 0x00008FB4
Code section = 0x0000AE20
Code section = 0x0000D07C
@dhrystone\\HEAPALLOC : Assembly level module.
Code section = 0x00008FF4
Code section = 0x000098E4
Code section = 0x0000AF14
...
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
to 0x00008FB3
to 0x0000D8BF
to 0x0000826F
to 0x00008007
to 0x0000807B
to 0x00008FF3
to 0x0000AEE7
to 0x0000D093
to 0x000090EF
to 0x000098EB
to 0x0000AF33
2-243
RealView Debugger Commands
Alias
PS is an alias of PRINTSYMBOLS.
See also
The following command provides similar or related functionality:
•
CONTEXT on page 2-113.
•
PRINTTYPE on page 2-245.
2-244
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.95
PRINTTYPE
The PRINTTYPE command displays language type information for a symbol.
Syntax
PRINTTYPE {symbol_name | expression}
where:
symbol_name
Specifies the name of a symbol.
expression
Specifies a debugger expression.
Description
The PRINTTYPE command displays language type information for a symbol or debugger
expression. The information is displayed in a style similar to the source language.
Note
The symbol name must be specified in the correct case, even if a wildcard is used for
part of the name.
Examples
The following examples show how to use PRINTTYPE:
printtype Enumeration
Shows details of the enum type Enumeration, defined by the dhrystone
image:
typedef enum Enumeration
{
, Ident_1:0 Ident_2:1, Ident_3:2, Ident_4:3, Ident_5:4
} Enumeration;
-- Defined within module DHRY_H
printtype ptr->databuf
Shows type details of a field referenced by the pointer databuf.
Alias
PT is an alias of PRINTTYPE.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-245
RealView Debugger Commands
See also
The following commands provide similar or related functionality:
•
ADD on page 2-18
•
BROWSE on page 2-97
•
DELETE on page 2-125
•
PRINTF on page 2-238
•
PRINTSYMBOLS on page 2-242.
2-246
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.96
PRINTVALUE
The PRINTVALUE command prints the value of a variable or expression.
Syntax
PRINTVALUE [{/H|/MB|/R|/S|/T}] {expression | expression_range}
where:
/T
Displays the value in decimal format.
/H
Displays the value in hexadecimal format.
/MB
Displays multibyte characters using the current encoding, for example
UTF-8. You must use the GUI to set up the character encoding. For
instructions on how to do this, see the description on how to localize the
RealView Debugger interface in the RealView Debugger v3.0 Essentials
Guide.
/R
Suppresses the display of the address when you specify a variable in an
image.
/S
Suppresses the display of characters in the string, but displays the
character pointer.
expression
Specifies an expression to be displayed. If you are using the GUI, then the
expression is displayed in the Output pane.
expression_range
Specifies an expression range to be displayed. If you are using the GUI,
the expressions range is displayed in the Output pane.
Description
The PRINTVALUE command prints to the screen the value of a variable or expression using
its natural type for formatting. It can display all of aggregate types, such as structures,
and expressions can be type cast to display it in a different format. All values that make
up a complex type are printed. If you are using the GUI, then they are displayed in the
Output pane.
Each value within an expression_range is displayed according to the base type if one
exists. All expressions printed with this command are displayed according to their type.
If the type of the expression is unknown, it defaults to type byte.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-247
RealView Debugger Commands
The PRINTVALUE command runs synchronously unless access to target memory is
required and background access is not possible. Use the WAIT command to force it to run
synchronously.
The following messages can be displayed by the PRINTVALUE command:
<ENUM: xx>
Invalid enum value, xx = value.
<INFINITY>
Floating-point value is infinity.
<NAN>
Not a number. A floating-point error.
Examples
The following examples show how to use PRINTVALUE:
printvalue /mb pchUTF8
Prints the multibyte character variable pchUTF8, encoded in UTF-8, as
multibyte characters. Without the /mb switch the characters are displayed
as escaped characters.
printvalue *Ptr_Glob
The command can be used to print the full contents of a record, for
example this instance from a run of dhrystone:
printv *Ptr_Glob
0x00011540 = {Ptr_Comp=(record *)0x00011508,Discr=Ident_1,variant={var_1=
{Enum_Comp=Ident_3,Int_Comp=17,Str_Comp="DHRYSTONE PROG
RAM, SOME STRING"},var_2={E_Comp_2=Ident_3,Str_2_Comp="C
\x02\xC7\x11"},var_3={Ch_1_Comp='\x02',Ch_2_Comp='C'}}}
Note
For the same expression, CEXPRESSION prints the address, not the full
value:
> ce *Ptr_Glob
Result is: data address 0x00011540
p Ptr_Glob
Printing the value of the pointer tells you the address of the pointer, its
type and the value stored there:
0x0000EBBC = (record *)0x00011540
Note
For the same expression, CEXPRESSION prints the value of the pointer, but
not its type and address:
2-248
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
> ce Ptr_Glob
Result is: data address 0x00011540
See also
The following commands provide similar or related functionality:
•
CEXPRESSION on page 2-101
•
MONITOR on page 2-217.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-249
RealView Debugger Commands
2.3.97
PROPERTIES
PROPERTIES is an alias of SETTINGS (see page 2-279).
2.3.98
PS
PS is an alias of PRINTSYMBOLS (see page 2-242).
2.3.99
PT
PT is an alias of PRINTTYPE (see page 2-245).
2-250
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.100 QUIT
The QUIT command causes the debugger to exit.
Syntax
QUIT [Y]
where:
Exits the debugger without displaying a confirmation dialog. Include this
when using the QUIT command in a batch file.
Y
Description
The QUIT command exits the debugger. It displays a dialog box where you can confirm
the operation.
If you have any unsaved changes, you are prompted to save these before the debugger
exits.
Examples
The following examples show how to use QUIT:
ARM DUI 0175H
quit
Exits the debugger. Displays a dialog box where you can choose to
confirm or abort the operation. If you choose to exit, the debugger warns
of any unsaved changes.
quit y
Exits the debugger without additional confirmation. However, the
debugger warns of any unsaved changes.
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-251
RealView Debugger Commands
2.3.101 READBOARDFILE
The READBOARDFILE command reads the specified board file.
Syntax
READBOARDFILE [,auto] [=board-filename]
where:
Is an optional qualifier. If you specify auto the command does not read
the specified board file if it is the same as the last one read.
auto
board-filename
Specifies the name of the board file to read. It must be enclosed in double
quotes.
You can include one of more environment variables in the filename. For
example, if MYPATH defines the location C:\Myfiles, you can specify:
readboardfile ="$MYPATH\\gizmo.brd"
Description
The READBOARDFILE command reads the specified board file. If you do not specify a board
file, the command rereads the current board file. If you do not specify a board file and
no board file has been read, the command reads the default rvdebug.brd.
The READBOARDFILE command runs synchronously.
Examples
The following example shows how to use READBOARDFILE:
readboardfile ="c:\sources\gizmo.brd"
Read the file gizmo.brd into memory, replacing the current file.
See also
The following commands provide similar or related functionality:
•
BOARD on page 2-41
•
DELBOARD on page 2-124
•
EDITBOARDFILE on page 2-158.
2-252
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.102 READFILE
The READFILE command reads a file into target memory.
Syntax
READFILE ,{obj|raw|raw8|raw16|raw32|rawb|rawhw|ascii[,opts]} [,nowarn] filename
[=address|offset]
where:
obj
The file is an executable file in the standard target format. For ARM
targets, this is ARM-ELF.
There are no opts supported for this file type.
raw
Read the file as raw data, using the most efficient access size for the
target.
There are no opts supported for this file type.
You must specify an address with this qualifier.
raw8
Read the file as raw data, one byte for each byte of memory.
There are no opts supported for this file type.
You must specify an address with this qualifier.
raw16
Read the file as raw data, 16 bits for each 16 bits of memory.
There are no opts supported for this file type.
You must specify an address with this qualifier.
raw32
Read the file as raw data, 32 bits for each 32 bits of memory.
There are no opts supported for this file type.
You must specify an address with this qualifier.
ARM DUI 0175H
rawb
Deprecated. Use raw8 instead.
rawhw
Deprecated. Use raw16 instead.
ascii
The file is a stream of ASCII digits separated by whitespace. The
interpretation of the digits is specified by other qualifiers (see the opts
qualifier). The starting address of the file must be specified in a one line
header in one of the following ways:
[start]
The start address.
[start,end]
The start address, a comma, and the end address.
[start,+len]
The start address, a comma, and the length.
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-253
RealView Debugger Commands
[start,end,size]
The start address, a comma, the end address, a
comma, and a character indicating the size of each
value, where b is 8 bits, h is 16 bits and l is 32 bits.
This is the format used by the WRITEFILE command.
If the size of the items in the file is not specified, the debugger determines
the size by examining the number of white-space separated significant
digits in the first data value. For example, if the first data value was
0x00A0, the size is set to 16-bits.
Optional qualifiers available for use with the ascii qualifier:
opts
nowarn
byte
The file is a stream of 8-bit values that are written to target
memory without extra interpretation.
half
The file is a stream of 16-bit values.
long
The file is a stream of 32-bit values.
Suppress the display of the large file warning messages, such as:
Downloading n bytes can take a long time. (Hint: Choosing a larger
access size may reduce this time) Do it anyway?
filename
The name of the file to be read. This can be a file that you have written
with the WRITEFILE command.
You can include one of more environment variables in the filename. For
example, if MYPATH defines the location C:\Myfiles, you can specify:
readfile,raw "$MYPATH\\myfile.dat" 0x8000..0x8100
address|offset
Specifies the starting address in target memory for the load:
•
For an ascii file type, specify a signed offset value. This is the
offset from the start location that is stored in the ASCII file.
•
For any other type of file, specify a start address or range of
addresses to be loaded.
Description
The READFILE command reads a file, performs a format conversion if necessary on its
contents, and loads the resulting information into target memory.
The types of file and file formats supported depend on the target processor and any
loaded DLLs. The type of memory assumed depends on the target processor. For
example, ARM processors have byte addressable memory and CEVA-Oak processors
have word addressable memory.
2-254
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
Examples
The following examples show how to use READFILE:
readfile ,obj "c:\temp\file.exe"
Reads the contents of the named executable file into memory at its
specified start address.
readfile ,ascii,long "c:\temp\file.txt" =0x2000
Reads the contents of the named text file into memory, writing values as
words using the target endianness to translate values in the file into bytes
in target memory. The file is written starting at address 0xA000, because
the file contains a start address and an offset is specified. The file contents
can look, for example, like this:
[0x8000,0x9000,l]
E28F8090 E898000F E0800008 E0811008
E0822008 E0833008 E240B001 E242C001
E1500001 0A00000E E8B00070 E1540005
...
See also
The following commands provide similar or related functionality:
•
FILL on page 2-173
•
FLASH on page 2-176
•
LOAD on page 2-202
•
SETMEM on page 2-273
•
VERIFYFILE on page 2-362
•
WRITEFILE on page 2-376.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-255
RealView Debugger Commands
2.3.103 REEXEC
REEXEC is an alias of RESTART (see page 2-263).
2-256
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.104 RELOAD
The RELOAD command loads a linked program image containing program code and data.
Syntax
RELOAD [{,qualifier...}] [{filename | file_num}] [=task]
where:
qualifier
If specified, qualifier must be one of the following:
all
Loads all the files in the file list.
symbols_only
Reloads the symbols only, not the executable
image.
image_only
Reloads the executable image only, not the
symbols.
force
Forces the load to proceed even if it might be
aborted because, for example, the file being loaded
overlaps a file already loaded.
filename | file_num
Specifies a file to be reloaded. If you do not specify a file, the whole
process is reloaded.
Use the DTFILE command to list details of the file or files that are
associated with the current connection (see DTFILE on page 2-149). The
details include:
•
the file number, which is shown at the start of the output for each
file listed by the text File file_num
•
the filename and path.
Specifies the task that is to start. This parameter is required only when the
target is running multiple tasks.
task
Description
The RELOAD command loads or reloads an absolute file image containing program code
and data. You can load a specified file, or one or more files from the file list. The PC is
reset to the start location.
If any file being reloaded is already loaded, it is unloaded before being loaded again. If
the symbols for a given file are already loaded, they are not reloaded unless the file
modification date has changed.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-257
RealView Debugger Commands
You can reload symbols only, or the image only. For details see the descriptions of the
command qualifiers.
The effect of reloading the system file is defined by the Target Access.
Note
If you reload an image that requires arguments, you must use the ARGUMENTS command
to specify them before running the image. Alternatively, use the LOAD command and
specify the arguments as part of that command.
See also
The following commands provide similar or related functionality:
•
ADDFILE on page 2-21
•
ARGUMENTS on page 2-32
•
DTFILE on page 2-149
•
LOAD on page 2-202
•
READFILE on page 2-253
•
UNLOAD on page 2-357.
2-258
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.105 RESET
The RESET command performs or simulates a target processor reset.
Syntax
RESET [,cleanup] [=resource]
where:
cleanup
Use this command qualifier only with operating systems that support it.
Its purpose is to cleanup thread states and other OS issues.
resource
Specifies the target processor that is to be reset, for example,
@[email protected]
You must specify @RealView-ICE only if the target identifier is not unique.
For example, you might have another @ARM966E-S_0 target on a Multi-ICE
connection.
Description
This command is used to reset the target processor and peripherals on the board. If an
actual hardware reset is not possible, the command places the processor in a state that
is as close as possible to the hardware reset state. The actual behavior varies from one
processor type to another and from one Target Access type to another. Check with the
manufacturer for details. Variables are not reset to their original values, because
memory is not re-initialized
The RESET command runs synchronously.
Alias
WARMSTART is an alias of RESET.
Examples
The following examples show how to use RESET:
reset @[email protected]
Resets the ARM966E-S™ processor on the RealView-ICE connection.
reset,cleanup @ARM966E-S_0
Resets the ARM966E-S processor, and cleans up the thread states and
any other OS issues on the processor.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-259
RealView Debugger Commands
See also
The following command provides similar or related functionality:
•
RESTART on page 2-263.
2-260
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.106 RESETBREAKS
The RESETBREAKS command resets breakpoint pass counters and and-then conditions.
Syntax
resetbreaks [,h] [break_num,...] [=thread,...]
where:
h
Do not use this qualifier. It is for debugger internal use only.
break_num
Specifies one or more breakpoints to have their pass counters reset to
zero.
You identify breakpoints by their position in the list displayed by the
DTBREAK command (see page 2-147).
thread
Specifies one or more threads to which this command applies. Other
threads remain unaffected. If you do not supply this parameter, then
breakpoints on all threads are reset.
You do not have to supply this parameter if the processor has only a single
execution thread or the OS extension is not enabled.
Description
The RESETBREAKS command resets breakpoints pass counters. The pass counters are the
counts of the number of times breakpoints have been triggered, as shown by the DTBREAK
command (see page 2-147). It also resets the and and and-then condition state so that
the first breakpoint is again required before the second can trigger. For more
information on and and and-then conditions see BREAKEXECUTION on page 2-56.
If you issue a RESETBREAKS command without specifying a breakpoint number, the pass
counter, and and and-then conditions for all the current pass counters are reset to zero.
You might typically issue a RESETBREAKS command after a RELOAD command, so that the
counts all begin again from zero when you restart execution.
Examples
The following examples show how to use RESETBREAKS:
ARM DUI 0175H
resetbreaks 4,6,8
Resets the pass counters and conditions of the fourth, sixth, and
eighth breakpoints in the current list of breakpoints.
resetbreaks =2
Resets all the pass counters and conditions in thread 2.
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-261
RealView Debugger Commands
Alias
RSTBREAKS is an alias of RESETBREAKS.
See also
The following commands provide similar or related functionality:
•
BREAKEXECUTION on page 2-56
•
BREAKINSTRUCTION on page 2-67
•
BREAKREAD on page 2-74
•
BREAKWRITE on page 2-85
•
CLEARBREAK on page 2-104
•
DTBREAK on page 2-147
•
RELOAD on page 2-257.
2-262
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.107 RESTART
The RESTART command resets the PC to the program starting address.
Syntax
RESTART [=task]
where:
Specifies the task that is to start. This parameter is required when the
target is running multiple tasks and the OS extension is enabled.
task
Note
This is not avalaible in this release.
Description
The RESTART command resets the PC to the program starting address, so that the next GO,
STEP or GOSTEP command restarts execution at the beginning of the program. The RESTART
command does not reset the values of variables, the stack pointer is not reset and
breakpoints are not cleared. If required, RESTART can be configured to reload the image
using the SETTINGS command. All declared I/O ports are unaffected. You can use the
ARGUMENTS command (see page 2-26) to change the arguments passed to the process for
a restart.
Note
If the program relies on the initial values of variables in initialized data areas, and
those variables are modified during program execution, then using RESTART to
rerun the program fails.
•
The RESTART command might behave differently if you are using the OS extension
to RealView Debugger. See the instructions for the specific OS extension for
more details.
•
The RESTART command runs synchronously.
Alias
REEXEC is an alias of RESTART.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-263
RealView Debugger Commands
See also
The following commands provide similar or related functionality:
•
GO on page 2-186
•
RELOAD on page 2-257.
2-264
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.108 RSTBREAKS
RSTBREAKS is an alias of RESETBREAKS (see page 2-261).
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-265
RealView Debugger Commands
2.3.109 RUN
The RUN command starts execution using a specific mode, or sets the default mode used
by the GO command.
Syntax
RUN
RUN ,setdefault
RUN [,setdefault],{debug|normal}
RUN [,setdefault],{clock|benchmark}
RUN [,setdefault],{free|user}
where:
setdefault
Set the default mode for the GO command to the mode specified by this
command, but do not start execution.
If no mode is specified, then the default mode (debug or normal) is set.
debug | normal
Run with breakpoints active. This is the default mode.
clock | benchmark
Run with breakpoint timing hardware enabled. This mode is only
available on some targets.
free | user
Run at full speed, with breakpoints disabled. Depending on the target,
hardware, this might not be any faster than normal mode.
Description
If supported by the target, the RUN command starts execution using a specific mode, or
sets the default mode used by the GO command.
If you supply no parameters, RUN displays the current mode.
Examples
The following examples show how to use RUN:
run,setdefault,normal
Set the default run mode to normal, so that the next GO command for this
connection runs the target in the normal way.
2-266
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
run,free
Run the target with breakpoints disabled.
See also
The following command provides similar or related functionality:
•
GO on page 2-186
•
HALT on page 2-190
•
STOP on page 2-301.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-267
RealView Debugger Commands
2.3.110 SCOPE
The SCOPE command specifies the current module and procedure scope.
Syntax
SCOPE /F
SCOPE root_name\\
SCOPE [root_name\\] module_name
SCOPE [[root_name\\] module_name\] {function_name | (expression) | @stack_level
| #line_number}]
where:
/F
Selects the first module of the next root.
root_name
Specifies the name of a root (for example, @sieve).
module_name
Specifies the name of a module (for example, SIEVE).
function_name
Specifies the name of a function (for example, proc1).
expression
Specifies an expression specifying the location of a calling
function.
stack_level
Specifies a stack level.
line_number
Specifies a high-level line number.
Description
The SCOPE command specifies the current module and procedure scope. This determines
the current context. The current context determines how local variables are accessed and
what symbol qualification is required. The following context types are supported:
•
the current PC
•
a specific module, function, or source file line
•
a stack frame position
•
auto-set, used when the debugger is in source mode and the PC is not in a source
view context, for example when the program is at the entry point.
The SCOPE command can change the default root, module, procedure, line number, or
stack level, but it does not change the PC.
To return the scope to display source at the current PC location, use SCOPE with no
parameters. To display the current scope, use the CONTEXT command.
2-268
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
The current root and module is the default when line numbers and local symbols are
referenced without a module or procedure qualifier. For example, if line number 3 is
entered on the command line as #3, it is interpreted as default_module\#3. The new
source file or disassembly is shown in the Code window.
The SCOPE command runs asynchronously. Use the WAIT command to force it to run
synchronously.
Examples
The following examples show how to use SCOPE:
scope #155
Set the current context to line 155 in the current module (file).
Scoped to: (0x01000560): DHRY_1\main Line 155
sc \\DHRY_1
Set the current context to the start of the file dhry_1.c.
Scoped to: (0x010002BC): DHRY_1\main Line 78
sc @1
Set the scope to the stack frame of the calling function.
sc
Return the current context to the execution point.
At the PC: (0x01000544): DHRY_1\main Line 152
See also
The following commands provide similar or related functionality:
•
CONTEXT on page 2-113
•
PRINTVALUE on page 2-247
•
WHERE on page 2-373.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-269
RealView Debugger Commands
2.3.111 SEARCH
The SEARCH command searches memory for a specified value or pattern.
Syntax
SEARCH [{/B|/H|/W|/8|/16|/32}] [/R] [address-range [={expression |
expression_string}]]
where:
/B, , /8
Sets the display format to byte (8 bits).
If the processor naturally addresses bytes (for example, ARM7TDMI)
then this is the default setting. However, CEVA and ZSP DSPs have a
natural addressing of a word (16 bits), so /H is the default for CEVA and
ZSP DSPs.
/H, , /16
Sets the display format to halfword (16 bits).
/W, , /32
Sets the display format to word (32 bits).
/R
Continues to search for the specified expression displaying each match
until the end of the block or until the STOP button is used.
address-range
Specifies the range of addresses to be searched. See Specifying address
ranges on page 2-2 for details on how to specify an address range.
expression
Specifies the value to search for.
expression_string
Specifies the pattern to search for.
Description
The SEARCH command searches a memory area for the specified value or pattern string.
When it is found, the debugger stops searching and displays the address where the
expression was found.
If they do not fit the specified size evenly, all expressions in an expression string are
padded or truncated to the size specified by the size qualifiers. If you do not specify an
expression or expression string, the debugger searches the memory area for zeros. If you
issue a SEARCH command without parameters, the debugger continues searching through
the originally specified address range starting from where the last match was found.
The SEARCH command runs synchronously.
2-270
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
Examples
The following examples show how to use SEARCH:
search 0x1000..0x2000 =122
Search for the first occurrence of the byte value 122 (ASCII z), in the 4KB
block of memory starting at 0x1000.
search /r 0x1000..0x2000 =163
Display all occurrences of the byte value 163 (ASCII £) in the 4KB block
of memory starting at 0x1000.
search 0x1000..0x2000 ="-help"
Search for the first occurrence of the string -help in the 4KB block of
memory starting at 0x1000.
See also
The following commands provide similar or related functionality:
•
MEMWINDOW on page 2-214
•
SETMEM on page 2-273.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-271
RealView Debugger Commands
2.3.112 SETFLAGS
The SETFLAGS command is reserved for internal use by the RealView Debugger.
2-272
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.113 SETMEM
The SETMEM command changes the contents of memory to a specified value.
Syntax
SETMEM [{/B|/H|/W|/8|/16|/32}] address [={expression | expression_string}]
where:
/B, , /8
Sets the access size to byte (8 bits). This is the default setting.
/H, , /16
Sets the access size to halfword (16 bits).
/W, , /32
Sets the access size to word (32 bits).
address
Specifies the memory address where the contents are to be changed.
expression
Specifies an expression to be evaluated to a value and placed into the
specified memory address.
expression_string
Specifies the string pattern to be placed into the specified memory
address.
Description
The SETMEM command changes the contents of the specified memory location to the
value or values defined by expression or expression_string. SETMEM is used to set
assembly-level memory. For example, you can use it to work around a section of code
that is producing incorrect results by changing variables to the correct values. If you do
not specify a value then the interactive setting dialog is displayed.
An expression string is a list of values separated by commas. ASCII characters enclosed
in quotation marks are treated as an array of characters, and with the /H and /W qualifiers
are each expanded to 2 or 4 bytes. All expressions in an expression string are padded or
truncated to the size specified by the size qualifiers (/B, /H, /W).
Note
The SETMEM command does not recognize variable typing, so you must ensure the
expression size qualifier is compatible with the variable type.
The SETMEM command runs synchronously unless background access to target memory
is supported. Use the WAIT command to force it to run synchronously.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-273
RealView Debugger Commands
Examples
Assuming the following definitions:
int count=2, buf[8];
int *ptr = buf;
And the following memory map:
0x10200 : 0x00000002
0x10204 : 0x00000000
0x10224 : 0x00010204
count
buf
ptr
The following two statements both set the value of count to 5:
setmem /32 &count=5
setmem /32 0x10200=5
The following two statements both set the value of buf[0] to 0x40:
sm /W 0x10204 =0x40
sm /W ptr
=0x40
Note
The command SM count=5 sets the memory location addressed by the value of count to
5, leaving the contents of count unchanged.
Alias
SM is an alias of SETMEM.
See also
The following commands provide similar or related functionality:
•
CEXPRESSION on page 2-101
•
FILL on page 2-173
•
READFILE on page 2-253.
2-274
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.114 SETREG
The SETREG command changes the contents of a register, status flag, or a special target
variable such as the cycle count.
Syntax
SETREG [@register_name [=value]]
where:
register_name
Specifies a register. Register names begin with an at sign (@).
Defines the value to be placed in the register.
value
Description
This command changes the contents of a register, status flag, or a special target variable
such as the cycle count. For more details, see Referencing reserved symbols on
page 1-21.
Note
If you use this command when running in command line mode, you must supply a
register_name. Otherwise, the command has no effect.
Register names
You can set the value of any register, or register bit-field, that is defined by an active
.bcd file. To link a relevant definition file to the current connection, use Connection
Properties window to set the BoardChip name for the connection.
You can view the currently defined registers using the PRINTSYMBOLS command (see
PRINTSYMBOLS on page 2-242), for example:
PRINTSYMBOLS /r *
This also displays any reserved symbols and internal variables that are currently
defined.
By defining new registers in a .bcd file, you can extend the register list to, for example,
include peripheral control registers for your target.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-275
RealView Debugger Commands
Note
Some processors and peripherals have some read-only registers. These cannot be
written to with SETREG.
Command line usage
You can set the value of registers defined in a board chip file or by the processor model,
by prefixing the register name with the @ symbol and assigning it a value. The value
can include program and debugger symbols and debugger expressions.
Note
Change the values of processor and device registers with care. Compilers and operating
systems do not always use registers in the expected manner.
Fully Interactive register setting
In the GUI, if you supply no parameters, the SETREG command displays the Interactive
Register Setting dialog where you can specify a register and a value, shown in
Figure 2-3. The Register drop-down list contains the names of recently used registers.
To select other register names, click either Next Reg or Prev Reg. The current value of
the register is displayed in the Value field, in both unsigned hexadecimal and in signed
decimal.
Figure 2-3 Interactive Register Setting dialog
Enter a new value in the combo-box beneath Enter New Value and then click Set. The
Log tab displays the changes you have made.
2-276
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
Select Clear New to clear the Enter New Value field after setting a register with Set.
If Clear New is unchecked, the value you enter remains in the field and you can set
multiple registers with repeated clicks on Set.
Click Auto Inc Reg or Auto Dec Reg to select whether, after clicking Set, the next
higher or next lower numbered register is selected.
Partly Interactive register setting
If you supply only a register name, the SETREG command displays a prompt, shown in
Figure 2-4, enabling you to enter a new value for that register.
Figure 2-4 Register value prompt
Enter the value in the text field and click Set to change the register, or click Cancel to
abort the command.
Alias
SR is an alias of SETREG.
Examples
The following examples show how to use SETREG:
setreg @r3=0x50
Write the value 0x50 to processor register R3.
setreg @spsr_svc
Display a prompt, shown in Figure 2-4, containing the current value of
ARM processor register SPSR_SVC (saved program status register,
Supervisor mode). Use the text box to enter a new value.
setreg @v=1
Set the ALU overflow flag in the current program status register.
setreg
ARM DUI 0175H
Invoke the Interactive Register Setting dialog shown in Figure 2-3 on
page 2-276.
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-277
RealView Debugger Commands
See also
The following commands provide similar or related functionality:
•
ADD on page 2-18
•
CEXPRESSION on page 2-101
•
PRINTSYMBOLS on page 2-242.
2-278
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.115 SETTINGS
The SETTINGS command enables you to define target settings.
Syntax
SETTINGS [{default | option_list}]
where:
default
Causes all settings to revert to their default values.
option_list
A list of option names and values. Each option-value pair consists of a
setting name, an equals sign, and a value. The available option names and
values are described in List of options on page 2-280.
You can specify multiple options in the list by separating each
option-value pair with a colon.
Description
The SETTINGS command enables you to define settings (properties) for target support.
Some of these options have equivalent settings in the Workspace of the GUI. See the
individual option description in List of options on page 2-280 for the equivalent GUI
setting.
Note
If you want to change other Workspace settings, you must use the GUI. See the
RealView Debugger v3.0 User Guide for more details.
If the only parameter is the default qualifier, then all the settings revert to their default
values. If you supply no parameters, the command displays the current values of
settings for which a default value is defined.
Each setting is defined in the form of name=value, and multiple settings can be changed
using a colon (:) as a separator.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-279
RealView Debugger Commands
List of options
The standard option names are:
loadact={default|noimask|reset|pre_reset}
Action on load:
default
Normal load image behavior. For ARM processors, the
processor is placed in ARM state and supervisor mode with
interrupts disabled.
noimask
Do not change the processor status register. For example, on
ARM processors, the default modification of CPSR is not
performed.
reset
Reset the processor after the load, to perform a start from reset.
pre_reset Reset the processor before the load.
restart={set_pc|reload|reload_data}
Defines the action of the RESTART command. The possible values are:
set_pc
Set the PC to the entry point of the image.
reload
Reload the image as for RELOAD. The options relating to RELOAD,
that is loadact and pcset, also apply.
reload_data
Reload only the initialized data of the image. The option
relating to RELOAD, that is loadact, also applies.
restart_reset={True|False}
Reset on restart:
True
Reset the processor on RESTART, in addition to any other
actions.
False
Do not reset the processor on RESTART.
fillstack=value
Define a value to fill stack memory with before the program starts. This
is not used for ARM processor image files.
fillheap=value
Define a value to fill memory defined as heap. This is not used for ARM
processor image files.
2-280
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
fillundefined=value
Define a value to fill unused words of memory, such as words between
each section of the image in memory. This is not used for ARM processor
image files.
imagecache_enabled={True|False}
The image cache stores debug information from the image rather than
from physical memory. This enables RealView Debugger to access the
debug information if it cannot access the physical memory, for example,
when the target is running. This is especially important when tracing, so
that you do not have to stop the target for RealView Debugger to collect
or decompress trace information.
However, you might want to disable image caching if, for example, you
have self-modifying code, which can lead to incorrect information being
displayed.
Also, if the image cache is disabled, you cannot view the disassembly of
your image when the target is running.
Enables and disables the image cache:
True
Enables the image cache.
False
Disables the image cache. This is the default.
Note
Image caching is enabled by default.
disasm={default|standard|alternate|bytecode|extended}
Set the disassembly mode. This affects the disassembly in the Dsm tab,
and the output from the PRINTDSM command.
The possible values are:
default
Attempt to auto-detect the disassembly mode.
For ARM architecture processors, select from ARM, Thumb,
Jazelle bytecodes, or Thumb-2EE, using information from the
image file where available.
standard Select the standard instruction disassembly mode.
For ARM architecture processors, select ARM state (32-bit)
instructions.
alternate Select the alternate instruction disassembly mode.
For ARM architecture processors, select Thumb state (16-bit)
instructions.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-281
RealView Debugger Commands
bytecode Select the Jazelle bytecode disassembly mode. This is
available only for ARM processors.
extended Select the Thumb-2EE disassembly mode. This is available
only for ARM processors.
Equivalent Workspace setting: DEBUGGER, Disassembler, Format.
dsmvalue={True|False}
Selects whether the instruction code is displayed in disassembly listings.
The possible values are:
True
Disassembly listings include the instruction opcode, along
with the instruction memory address and mnemonics.
False
Disassembly listings do not include the instruction opcode.
Equivalent Workspace setting: DEBUGGER, Disassembler, Instr_value.
Additional options might be implemented for a particular Target Access. See the
documentation of your Target Access for more information.
Alias
PROPERTIES is an alias of SETTINGS.
Examples
The following examples show how to use SETTINGS:
settings loadact=reset
After an image is loaded or reloaded, reset the processor (in hardware).
This is useful when the image has been constructed to run from target
reset.
settings disasm=standard:dsmvalue=true
Specifies that disassembly is to be displayed using the standard format for
the target, and that the instruction code is to be hidden from the
disassembly listings.
See also
The following commands provide similar or related functionality:
•
DISASSEMBLE on page 2-133
•
LOAD on page 2-202
•
RELOAD on page 2-257
2-282
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
•
•
•
•
ARM DUI 0175H
OPTION on page 2-224
PRINTDSM on page 2-236
RESET on page 2-259
RESTART on page 2-263.
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-283
RealView Debugger Commands
2.3.116 SHOW
The SHOW command displays the source code of a specified debugger macro.
Syntax
SHOW macro_name [{,windowid | ,fileid}]
where:
macro_name
Specifies the name of the macro to be displayed.
,windowid | ,fileid
Identifies the window or file where the command is to send the output.
See Window and file numbers on page 1-5 for details.
If you do not supply a ,windowid or ,fileid parameter, or there is no
window or file associated with the ID, the macro is displayed on the
screen. If you are using the GUI, then the macro is displayed in the
Output pane.
Description
The SHOW command displays the source code of a specified macro. See the macros
chapter in the RealView Debugger v3.0 User Guide for more information.
Example
The following example shows how to use SHOW:
show mac ,50
Display the contents of a macro called mac in window number 50.
See also
The following commands provide similar or related functionality:
•
DEFINE on page 2-121
•
INCLUDE on page 2-194
•
MACRO on page 2-208.
2-284
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.117 SINSTR
SINSTR is an alias of STEPINSTR (see page 2-291).
2.3.118 SM
SM is an alias of SETMEM (see page 2-273).
2.3.119 SOINSTR
SOINSTR is an alias of STEPOINSTR (see page 2-296).
2.3.120 SOVERLINE
SOVERLINE is an alias of STEPO (see page 2-298).
2.3.121 SR
SR is an alias of SETREG (see page 2-275).
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-285
RealView Debugger Commands
2.3.122 STATS
The STATS command displays bus and processor cycles for RVISS targets. You can
specify user-defined reference points to show the counts from specific points in the
execution.
Syntax
STATS [[=]ref_name]
STATS {,setref | ,clearref} [[=]ref_name]
STATS ,reset [=]ref_name
STATS ,clearall
where:
clearall
Removes all user-defined reference points.
clearref
Removes the specified user-defined reference point.
If no reference point is specified, the last reference point in the list is
deleted, if any.
reset
Resets the specified user-defined reference point.
setref
Creates a specified user-defined reference point.
If no reference point is specified, a reference point is created, which has
the the default name:
Ref_nn
where nn is a numerical identifier starting at 01. This is incremented with
each new reference point you create.
ref_name
The name of a user-defined reference point, which can have a maximum
of nine characters. The name can include alphanumeric characters and
the underscore (_), colon (:), and space characters. You cannot specify
the default reference point name Ref_Cur (see Default reference point on
page 2-287).
For example, i10_a:1.
Note
If you include a space character, then delimit the name with double
quotes, for example "a1 loop".
2-286
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
Description
This command enables you to:
•
display values of statistics counters
•
create one or more reference point for those counters
•
reset an existing reference point
•
delete an existing reference point or all reference points.
Note
The statistics counters are the values returned by the RVISS $statistics structure (see
the RealView ARMulator ISS User Guide for details).
Statistics counters
The statistics counters displayed depends on the type of processor:
•
uncached von Neuman cores, such as the ARM7TDMI, display:
Instructions, Core_Cycles, S_Cycles, N_Cycles, I_Cycles, and C_Cycles
•
Harvard cores, such as the ARM9TDMI® display:
Instructions, Core_Cycles, ID_Cycles, IBus_Cycles, Idle_Cycles, and Dbus_Cycles
•
cores with AMBA® ASB interfaces, such as the ARM940T, display:
Instructions, Core_Cycles, S_Cycles, N_Cycles, A_Cycles, and C_Cycles
•
cores with AMBA AHB interfaces, such as the ARM946E-S™, display:
Instructions, Core_Cyles, SEQ, NON-SEQ, IDLE, and BUSY.
For all types a total count is also displayed.
Default reference point
A default reference point exists, called Ref_Cur, which shows the total counts for the
target. You cannot delete or reset the values for this reference point. These default
reference point counts are also shown in the CycleCount tab of the Register pane.
You can access the individual statistics count values for the default reference point using
debugger symbols. To find the symbol name for a statistics counter, enter the command:
PRINTSYMBOL @stats_*
User-defined reference points
A user-defined reference point shows the counts only from the point at which it is
created.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-287
RealView Debugger Commands
If you enter the command without a qualifier or reference name, then the statistics
counters for all reference points are displayed.
If you enter the command with a reference name only, then the statistics counters are
displayed only for that reference point.
Note
When you disconnect from the target, the user-defined reference points are deleted and
the Ref_Cur counts are reset to zero.
Example
For example, you might want to view the counts from the point at which a breakpoint
is hit. To do this, you might set a breakpoint that is activated after 10 passes, then create
a reference point to show the counts from this point onwards. The following example
uses the dhrystone image to demonstrate this:
1.
Connect to an RVISS target on the localhost Target Access.
2.
Load the example dhrystone image ...\Debug\dhrystone.axf.
3.
Enter the following command to set a breakpoint:
BREAKINSTRUCTION,passcount:10 \DHRY_1\#149:1
4.
Start execution.
5.
Enter 1000 when prompted for the number of runs.
6.
When the breakpoint is activated, create your reference point (iter:10):
STATS,setref iter:10
7.
View the current values:
> STATS
Ref_Point Instructions Core_Cycles _S_Cycles _N_Cycles _A_Cycles C_Cycles Total
Ref_Cur
00007cb1
0000c703
0000e4b6 00000000 00031279 00000000 0003f72f
iter:10
00000000
00000000
00000000 00000000 00000000 00000000 00000000
8.
Restart execution.
9.
View the current values:
> STATS
Ref_Point Instructions Core_Cycles _S_Cycles _N_Cycles _A_Cycles C_Cycles Total
Ref_Cur
00007e97
0000ca13
0000e800 00000000 00031e87 00000000 00040687
iter:10
000001e6
00000310
0000034a 00000000 00000c0e 00000000 00000f58
10.
2-288
You can create additional reference points as required.
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.123 STDIOLOG
The STDIOLOG command records the messages that are sent to STDIO.
Syntax
STDIOLOG [/A] [{OFF | ON="filename"}]
where:
/A
Specifies that new records are to be added to any that already exist in the
specified file.
OFF
Closes the log file and stops collecting information. This is the default.
ON
Starts writing information to the log file.
filename
Specifies the name of the log file. Quotation marks are optional, but see
Rules for specifying filenames on page 2-180 for details on how to
specify filenames that include a path.
Description
This command records the messages that are sent to STDIO. It does not record any
responses you give to prompts.
Note
If you use this command in the Cmd tab of the Output pane, the messages are the same
as those displayed in the StdIO tab of the Output pane.
If the specified file exists and you do not specify the /A parameter, the existing contents
of the file are overwritten and lost. A window number (20) is associated with the STDIO
so that text can be written to it using the commands and macros that support window
numbers. See Window and file numbers on page 1-5 for details.
Using STDIOLOG with no parameters shows the current log file, if any. STDIO output is
recorded in the log file until the STDIOLOG OFF command is issued.
The STDIOLOG command runs asynchronously unless in a macro.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-289
RealView Debugger Commands
Example
The following examples show how to use STDIOLOG:
STDIOLOG ON='c:\temp\stdiolog.txt'
Start logging output to the file c:\temp\stdiolog.txt, overwriting any
existing file of that name.
STIOLOG /A ON="stdiolog"
Start logging output to the file stdiolog.log in the current directory of the
debugger, appending the new log text to the file if it already exists.
STDIOLOG OFF Stop logging output.
See also
The following commands provide similar or related functionality:
•
JOURNAL on page 2-197
•
LOG on page 2-206
•
VOPEN on page 2-367.
2-290
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.124 STEPINSTR
The STEPINSTR command executes a specified number of processor instructions
(low-level step).
Note
If a breakpoint is set on an instruction that is encompassed by the STEPINSTR command,
then the breakpoint is actioned. The breakpoint behavior depends on any condition
qualifiers that are assigned. If you do not want the breakpoint to be actioned, then either
disable or clear the breakpoint (see DISABLEBREAK on page 2-131 or CLEARBREAK
on page 2-104) before stepping.
Syntax
STEPINSTR [value]
STEPINSTR =starting_address [,value]
where:
starting_address
Specifies where execution is to begin. If you do not supply this parameter
execution continues from the current PC.
Note
Specifying an address is equivalent to directly modifying the PC. Do not
specify a starting address unless you are sure of the consequences to the
processor and program state.
Specifies the number of instructions to be executed.
value
If you do not supply this parameter a single instruction is executed. All
instructions, including instructions that fail a conditional execution test,
count towards the number of instructions executed.
Description
The STEPINSTR command executes a specified number of instructions. If the instructions
include procedure calls, these are stepped into.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-291
RealView Debugger Commands
Note
For some procedure call standards there is code inserted between the call site and the
destination of the call by the linker, and this might not have debug information or source
code available. If this is the case for your code, a STEPINSTR call that stops in this code
causes the source window to be blanked.
It is normal to use this instruction in conjunction with the disassembly mode of the
source window, selected using the MODE command.
Examples
The following examples show how to use STEPINSTR:
stepinstr
Step the program by one instruction.
si 5
Step the program five instructions.
si =0x8000,5
Starting at address 0x8000, step the program five instructions.
Alias
SINSTR is an alias of STEPINSTR.
See also
The following commands provide similar or related functionality:
•
BEXECUTION on page 2-35
•
DISASSEMBLE on page 2-133
•
GO on page 2-186
•
GOSTEP on page 2-188
•
MODE on page 2-216
•
STEPLINE on page 2-293
•
STEPOINSTR on page 2-296
•
STEPO on page 2-298.
2-292
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.125 STEPLINE
The STEPLINE command executes one or more program statements (high-level step), and
steps into procedure and function calls.
Note
If you perform a high-level step in code for which there is no source available, RealView
Debugger attempts to step up the call stack until a location is reached that has source
available.
Syntax
STEPLINE [value]
STEPLINE =starting_address [,value]
where:
starting_address
Specifies where execution is to begin. If you do not supply this parameter
execution continues from the current PC.
Note
Specifying an address is equivalent to directly modifying the PC. Do not
specify a starting address unless you are sure of the consequences to the
processor and program state.
Specifies the number of lines of source code to be executed.
value
If you do not supply this parameter a single statement or source line is
executed. All lines that contain executable code, including those in called
functions, count towards the number of lines executed.
Description
The STEPLINE command executes one or more source program units. If the debug
information in the executable:
ARM DUI 0175H
•
describes the boundaries of program statements, then STEPLINE steps by program
statement
•
describes the source file line for each machine instruction, then STEPLINE steps by
source line
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-293
RealView Debugger Commands
•
describes only the external functions in the code, then STEPLINE steps by machine
instruction.
STEPLINE steps into procedure or function calls. When line or statement debug
information is available, the transition from the call site to the first executable statement
of the called code counts as one step. If source debug information is available for some
but not all of the functions in the program, STEPLINE steps to the next source line,
whether this is within a called function, for example, from program entry-point to
main(), or outside of the current function, for example from an assembler library routine
PC to an enclosing source function.
If the step starts in the middle of a statement (for example, because you have used
STEPINSTR) a single step takes you to the start of the next statement.
If you compile high level language code with debug information and with optimization
enabled, for example using armcc -g -O1, it is possible that:
•
source code is not executed in the order it appears in the source file
•
some source program statements are not executed because the optimizer has
deduced they are redundant
•
some source program statements appear to be not executed because the optimizer
has indivisibly combined them with other statements
•
statements are executed fewer times than you expect
•
it might not be possible to breakpoint or step some statements, because the
machine instructions are shared with other source code.
These, and other effects, are the normal consequences of compiler optimization.
For assembler source files assembled with debug information, a single assembly
statement consists of;
•
an explicitly written assembly instruction
•
an assembler pseudo-operation resulting in machine instructions, even if several
instructions are generated, for example an ARM ADR instruction
•
a call of an assembler macro that generates machine instructions.
It is normal to use this instruction in conjunction with the disassembly mode of the
source window, selected using the MODE command.
2-294
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
Examples
The following examples show how to use STEPLINE:
stepline
Step the program by one statement.
stepline 5
Step the program five statements.
s =0x8000,5
Starting at address 0x8000, step the program five statements.
See also
The following commands provide similar or related functionality:
•
BEXECUTION on page 2-35
•
DISASSEMBLE on page 2-133
•
GO on page 2-186
•
GOSTEP on page 2-188
•
MODE on page 2-216
•
OPTION on page 2-224
•
STEPINSTR on page 2-291
•
STEPOINSTR on page 2-296
•
STEPO on page 2-298.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-295
RealView Debugger Commands
2.3.126 STEPOINSTR
The STEPOINSTR command executes a specified number of instructions (low-level step),
and completely executes program calls.
Note
If a breakpoint is set on an instruction that is encompassed by the STEPOINSTR command,
then the breakpoint is actioned. The breakpoint behavior depends on any condition
qualifiers that are assigned. If you do not want the breakpoint to be actioned, then either
disable or clear the breakpoint (see DISABLEBREAK on page 2-131 or CLEARBREAK
on page 2-104) before stepping.
Syntax
STEPOINSTR [value]
STEPOINSTR =starting_address [,value]
where:
starting_address
Specifies where execution is to begin. If you do not supply this parameter
execution continues from the current PC.
Note
Specifying an address is equivalent to directly modifying the PC. Do not
specify a starting address unless you are sure of the consequences to the
processor and program state.
Specifies the number of instructions to be executed.
value
If you do not supply this parameter a single instruction is executed. All
instructions in the current function, including instructions that fail a
conditional execution test, count towards the number of instructions
executed. Function calls count as one instruction.
Description
The STEPOINSTR command executes a specified number of instructions. If the
instructions include procedure calls, these are stepped over, counting as only one
instruction.
It is normal to use this instruction in conjunction with the disassembly mode of the
source window, selected using the MODE command.
2-296
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
Examples
The following examples show how to use STEPOINSTR:
stepoinstr
Step the program by one instruction.
stepoinstr 5
Step the program five instructions.
soi =0x8000,5
Starting at address 0x8000, step the program five instructions, counting a
subroutine call as one instruction.
Alias
SOINSTR is an alias of STEPOINSTR.
See also
The following commands provide similar or related functionality:
•
BEXECUTION on page 2-35
•
DISASSEMBLE on page 2-133
•
GO on page 2-186
•
GOSTEP on page 2-188
•
MODE on page 2-216
•
STEPINSTR on page 2-291
•
STEPLINE on page 2-293
•
STEPO on page 2-298.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-297
RealView Debugger Commands
2.3.127 STEPO
The STEPO command executes a specified number of lines (high-level step), and
completely executes functions.
Note
If you perform a high-level step in code for which there is no source available, RealView
Debugger attempts to step up the call stack until a location is reached that has source
available.
Syntax
STEPO [={starting_address [,value] | value}]
where:
starting_address
Specifies where execution is to begin. If you do not supply this parameter
execution begins at the address currently defined by the PC.
Specifies the number of lines of source code to be executed. If you do not
supply this parameter a single line is executed. All lines in the current
program count towards the number of lines executed. A call to a function
causes the whole of the function to be executed, and counts as one line.
value
Description
The STEPO command executes one or more source program units. If the debug
information in the executable:
•
describes the boundaries of program statements, then STEPO steps by program
statement
•
describes the source file line for each machine instruction, then STEPO steps by
source line
•
describes only the function entry points in the code, then STEPO steps by machine
instruction.
If a statement calls one or more procedures or functions, they are all executed to
completion as part of the execution of the statement.
If the step starts in the middle of a statement (for example, because you have used
STEPINSTR) a single step takes you to the start of the next statement.
2-298
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
If you compile high level language code with debug information and with optimization
enabled, for example using armcc -g -O1, it is possible that:
•
source code is not executed in the order it appears in the source file
•
some source program statements are not executed because the optimizer has
deduced they are redundant
•
some source program statements appear to be not executed because the optimizer
has indivisibly combined them with other statements
•
statements are executed fewer times than you expect
•
it might not be possible to breakpoint or step some statements, because the
machine instructions are shared with other source code.
These, and other effects, are the normal consequences of compiler optimization.
For assembler source files assembled with debug information, a single assembly
statement consists of;
•
an explicitly written assembly instruction
•
an assembler pseudo-operation resulting in machine instructions, even if several
instructions are generated, for example an ARM ADR instruction
•
a call of an assembler macro that generates machine instructions.
It is normal to use this instruction in conjunction with the disassembly mode of the
source window, selected using the MODE command.
Alias
SO is an alias of STEPO.
Examples
The following examples show how to use STEPO:
ARM DUI 0175H
stepo
Step the program by one statement.
so 5
Step the program five statements.
so =0x8000,5
Starting at address 0x8000, step the program five statements.
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-299
RealView Debugger Commands
See also
The following commands provide similar or related functionality:
•
BEXECUTION on page 2-35
•
DISASSEMBLE on page 2-133
•
GO on page 2-186
•
GOSTEP on page 2-188
•
MODE on page 2-216
•
OPTION on page 2-224
•
STEPINSTR on page 2-291
•
STEPLINE on page 2-293
•
STEPOINSTR on page 2-296.
2-300
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.128 STOP
The STOP command stops target program execution, or a specified thread when the
processor is running in RSD mode.
Syntax
STOP [=value]
where:
Identifies the thread.
value
Description
The behavior of the STOP command depends on the whether your program is running on
a non OS-aware or OS-aware connection.
Using the STOP command on non OS-aware connections
The STOP command stops the whole processor.
Using the STOP command on OS-aware connections
The behavior of the STOP command depends on whether the processor is running in HSD
or RSD mode:
•
If the processor is running in HSD mode, the command stops the whole processor.
•
If the processor is running in RSD mode, and you use the STOP command without
specifying a thread, RealView Debugger attempts to stop the processor. The
behavior depends on the OS System_Stop setting in the Advanced_Information
block for the connection (see the RealView Debugger v3.0 RTOS Guide). If it is
set to Prompt, you are prompted to continue with the request:
— Yes stops the processor, and the processor falls back to HSD mode.
— No cancels the stop request, and the processor continues to run.
For an unattached Code window, the STOP command acts on the current thread. If
the Code window is attached to a thread, then the STOP command stops that thread.
•
If the processor is running in RSD mode, and you use the STOP command with a
thread identifier, the identified thread is stopped.
The stopping of threads is accomplished by the Debug Agent using the associated
OS service.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-301
RealView Debugger Commands
If you are working with OS-aware images, see the RealView Debugger v3.0 RTOS
Guide and the chapter that describes debugging multiple targets in the RealView
Debugger v3.0 User Guide.
Using the STOP command on connections running RealMonitor
If RealMonitor support is enabled, then only the application thread stops. The
RealMonitor thread continues running.
See the RealView Debugger v3.0 Target Configuration Guide for details on configuring
and using RealMonitor.
Examples
The following examples show how to use STOP:
Stops the processor.
stop
stop = thread_4
Stops the specified thread in RSD.
stop = 0x39d8
Stops the thread specified by the TCB address in RSD.
See also
The following commands provide similar or related functionality:
•
AOS_resource-list on page 2-30
•
BREAKINSTRUCTION on page 2-67
•
DOS_resource-list on page 2-141
•
GO on page 2-186
•
HALT on page 2-190
•
OSCTRL on page 2-230.
2-302
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.129 SYNCHEXEC
The SYNCHEXEC command controls how connections and threads run, step, and stop
together.
Note
Debugging more than one processor at a time is a separately licensed feature. See the
RealView Debugger v3.0 User Guide for more information about the multiprocessing
features of RealView Debugger.
Syntax
SYNCHEXEC [,run] [,step] [,stop] [{,all | [=]connections}]
SYNCHEXEC,remove [{,all | [=]connections}]
where:
run, , step, , stop
Qualifiers that you can specify in any combination to define the actions
to synchronize. If you do not supply a qualifier, all actions are used
together.
remove
Remove the connections from the synchronized group instead of adding
them to it.
all
Indicates all existing connections.
connections
A comma-separated list of connection identifiers, of the form:
connection-id [,connection-id,...]
where:
connection-id
The name of the target connection (see CONNECT
on page 2-108). If the connections have unique
names, then you have only to use the connection
name. Otherwise, you must also specify the Target
Access name
Description
The SYNCHEXEC command controls how RealView Debugger controls multiple target
processors. The initial state is that every target processor is controlled independently.
Therefore, stopping or starting a program on one processor only affects other processors
if there is a link between the processors.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-303
RealView Debugger Commands
If you require RealView Debugger to stop or start several target processors together, you
use this command to link them into a synchronized execution group. You can choose
whether this group applies to single stepping, to free-running, or to stopping (in the
sense of a user-initiated halt), independently.
Examples
The following examples show how to use SYNCHEXEC:
synchexec,rem,all
Unsynchronize all processors.
synchexec,step,run,stop @[email protected],@[email protected]_1,@ARM940T_0
Synchronize the following target connections on step, stop and run:
ARM_Cortex-A8, available on the ISSM Target Access
ARM_Cortex-A8, available on the ISSM_1 Target Access
ARM940T_0 (no Target Access is specified, because no other connection
exists with this name)
synchexec,all
Synchronizes all available target connections on step, stop and run.
See also
The following commands provide similar or related functionality:
•
BEXECUTION on page 2-35
•
CONNECT on page 2-108
•
GO on page 2-186
•
HALT on page 2-190
•
STEPINSTR on page 2-291
•
STOP on page 2-301
•
XTRIGGER on page 2-379.
2-304
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.130 TEST
The TEST command reads target memory to verify that specified values exist throughout
the specified memory area.
Syntax
TEST [{/B|/H|/W|/8|/16|/32}] [/R] address-range [={expression | stringexpr}]
where:
/B, , /8
Sets the expression size to byte (8 bits). This is the default setting.
/H, , /16
Sets the expression size to halfword (16 bits).
/W, , /32
Sets the expression size to word (32 bits).
/R
Continues to test for the specified expression, displaying each match until
the end of the block or until the stop button Cancel is pressed.
address-range
Specifies the range of addresses to be tested. See Specifying address
ranges on page 2-2 for details on how to specify an address range.
expression
Specifies a value to check against the contents of memory.
stringexpr
Specifies a string pattern to check against the contents of memory. The
debugger tests the memory area to verify that it is filled with those values
in the pattern of the string.
An expression string is a list of values separated by commas and can
include ASCII characters enclosed in quotation marks. All expressions in
an expression string are padded or truncated to the size specified by the
size qualifiers if they do not fit the specified size evenly.
Description
The TEST command examines target memory to verify that specified values exist
throughout the specified memory area. Unless you use the /R qualifier, Testing stops
when a mismatch is found. The debugger always displays any mismatched address and
value.
Subsequent TEST commands issued without parameters cause the debugger to continue
testing through the address range originally specified, beginning with the last address
that did not match.
The TEST command runs synchronously.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-305
RealView Debugger Commands
Examples
The following examples show how to use TEST:
test/8 0x8000..0x9000 =0
Find the address of the first non-zero byte in the 4KB page from 0x8000.
test/r/16 0x10000..0x20000 =0xFFFF
Find and display the addresses of any half-word in the address range that
is not 0xFFFF. This might be useful to find out which regions of a Flash
memory device are programmed.
See also
The following command provides similar or related functionality:
•
SETMEM on page 2-273.
2-306
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.131 THREAD
The THREAD command sets the specified thread to be the current thread.
Note
See the RealView Debugger v3.0 User Guide for more information about debugging
multiple processors and the RealView Debugger v3.0 RTOS Guide for OS debugging.
Debugging more than one processor at a time is a separately licensed feature.
Syntax
THREAD [{,next|,default}]
THREAD [=thread]
where:
next
Change the current thread to be the next one in the list of threads.
default
Ensures that there is a valid current thread.
thread
Define the thread that is to become the current thread. You can use the
thread name or the thread ID.
Description
The THREAD command sets the specified thread to be the current thread.
The current thread is normally set by whichever thread stops last. This command
enables you to specify a thread that is to be the current thread. By default, all actions
apply to the current board, process, and thread.
Examples
The following examples show how to use THREAD:
thread,next
Change the current thread to the next thread.
thread =thread_2
Change the current thread to the thread named thread_2.
thread =0x13dac
Change the current thread to the thread with an ID of 0x13dac.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-307
RealView Debugger Commands
See also
The following commands provide similar or related functionality:
•
BOARD on page 2-41
•
OSCTRL on page 2-230
•
RUN on page 2-266.
2-308
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.132 TRACE
The TRACE command provides a quick method of enabling or disabling tracing during
program execution. The tracepoints you set with this command are unconditional.
Syntax
TRACE location
TRACE [{{,endpoint}|{,prompt}|{,trigger}}] location
TRACE ,range startlocation..endlocation
TRACE ,data startlocation..endlocation
where:
location
A program source location, specified symbolically or numerically.
startlocation
The start of a program source range, which must be at a lower
address than that specified by endlocation.
endlocation
The end of a program source range, which must be at a higher
address than that specified by startlocation.
Description
The TRACE command enables you to set trace trigger, start points, and end points in the
program. This enables you to switch tracing on or off at specific addresses during
program execution (see Trace control during program execution). The tracepoints you
set are unconditional tracepoints. To set more complex tracepoints, use the
TRACEDATAACCESS, TRACEDATAREAD, TRACEDATAWRITE, TRACEEXTCOND, TRACEINSTREXEC, or
TRACEINSTRFETCH command as appropriate.
Trace operation is described in detail in the RealView Debugger v3.0 Trace User Guide.
Trace control during program execution
The endpoint, range, data, prompt, and trigger qualifiers are used to control tracing
during program execution. With no qualifier, the TRACE command sets a trace start point.
To use these commands, you must specify a program source location, for example a
memory address within the program image, or a source module and line number.
The commands are as follows:
TRACE location
Set a trace start point in the program at address location.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-309
RealView Debugger Commands
trace ,endpoint location
Set a trace end point in the program at address location.
trace ,trigger location
Set a trace trigger in the program at address location.
trace ,prompt location
Set an unconditional tracepoint in the program at address location, where
the type of tracepoint is selected from a list of supported types presented
in a dialog box. See the chapter that describes setting unconditional
tracepoints in the RealView Debugger v3.0 Trace User Guide for more
details.
Note
The prompt qualifier is not available when running in command line
mode.
trace ,range startlocation..endlocation
Set a trace range in the program from address startlocation to
endlocation, so that instructions at addresses between these points are
traced.
trace ,data startlocation..endlocation
Set a trace range in the program from address startlocation to
endlocation, so that data at addresses between these points are traced.
trace ,range ,data startlocation..endlocation
Set a trace range in the program from address startlocation to
endlocation, so that instructions executed and data accessed at addresses
between these points are traced.
Note
ARM program code often includes literal pools, constants required by the
program that cannot be easily included in the instruction opcodes. Literal
pool accesses shows up on data tracing, and might quickly fill up the
ETM FIFO buffer quickly, depending on the program.
2-310
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
Examples
The following examples show how to use TRACE:
TRACE,prompt \DHRY_1\#78
Prompts you with a selection of tracepoints that you can set.
TRACE,range,data 0x80200..0x80400
Set tracepoints so that data and code accesses between
0x80200-0x80400 are traced, but not accesses at other addresses.
See also
The following commands provide similar or related functionality:
•
ANALYZER on page 2-26
•
DTBREAK on page 2-147
•
DTRACE on page 2-151
•
ETM_CONFIG on page 2-165
•
TRACEBUFFER on page 2-312
•
TRACEDATAACCESS on page 2-323
•
TRACEDATAREAD on page 2-329
•
TRACEDATAWRITE on page 2-335
•
TRACEEXTCOND on page 2-341
•
TRACEINSTREXEC on page 2-346
•
TRACEINSTRFETCH on page 2-352.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-311
RealView Debugger Commands
2.3.133 TRACEBUFFER
The TRACEBUFFER command manipulates the contents and display of the program
execution trace buffer.
Syntax
TRACEBUFFER ,subcommand [,qualifier] ="text"
TRACEBUFFER ,subcommand =value
TRACEBUFFER ,subcommand
where:
subcommand
The possible commands are described in Description.
qualifier
The possible qualifiers are described in Description.
text
The name of a file or program symbol.
value
A numeric value or range, for example 4 or 5..8.
Description
The TRACEBUFFER command manipulates the program execution and data trace buffer
associated with a trace analyzer, enabling you to save, load, find, and filter the data. The
actions are differentiated using the subcommand, and are described in the section
Subcommands.
Trace operation is described in detail in the RealView Debugger v3.0 Trace User Guide.
Subcommands
The possible subcommands listed in the syntax are described in the following sections:
•
Loadfile on page 2-313
•
Savefile on page 2-313
•
Closefile on page 2-314
•
Amount on page 2-314
•
Scaletime on page 2-315
•
Speed on page 2-315
•
Find_trigger on page 2-316
•
Find_position on page 2-316
•
Find_time on page 2-316
•
Find_address on page 2-316
2-312
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
Find_data on page 2-317
Find_name on page 2-317
Posfilter on page 2-317
Timefilter on page 2-317
Addressfilter on page 2-318
Namefilter on page 2-318
Percentfilter on page 2-318
Datavaluefilter on page 2-319
Accesstypefilter on page 2-319
Clearfilter on page 2-319
Or_filter on page 2-319
And_filter on page 2-320
Invert_filter on page 2-320
Normal_filter on page 2-320
Pos_relative on page 2-320
Pos_absolute on page 2-320
Refresh on page 2-321
Gui on page 2-321.
Loadfile
TRACEBUFFER ,loadfile ="filename"
Load a file into the trace buffer for extra analysis. filename is the name of the file to load,
and must be quoted.
You can include one of more environment variables in the filename. For example, if
MYPATH defines the location C:\Myfiles, you can specify:
TRACEBUFFER,loadfile '$MYPATH\mytrace.dat'
Note
The file must have been saved using the savefile subcommand with the qualifier full,
minimal, or profile, or the GUI equivalent.
Savefile
TRACEBUFFER ,savefile [,ascii|,full|,minimal|,profile] [,append] [,filtered]
="filename"
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-313
RealView Debugger Commands
Save the trace buffer to a file, where:
ascii
Save lines of text as displayed in the current tab of the Analysis window.
This format cannot be loaded into the RealView Debugger analysis
window.
full
Save the whole trace buffer as a binary file in an RealView Debugger
internal format.
minimal
Save only timing, address, and access type data from the trace buffer as a
binary file in a RealView Debugger internal format. The files created are
much smaller than the full format, but some information is lost.
profile
Save only execution profile data from the trace buffer as a binary file in a
RealView Debugger internal format. The files created are smaller than
the minimal format, but only include enough information to display
execution profiles.
append
Append the new trace data to an existing file. Do not append data in one
format to files in a different format.
filtered
Apply the selected display filters when saving trace data. If not specified,
the entire trace buffer is saved, regardless of selected display filters.
filename
The name of the file to write the data to. If the full argument is specified,
the filename extension is ignored. If the full argument is not specified,
then the filename must use a known extension (.trc, .trm, .trp, or .txt).
You can include one of more environment variables in the filename. For
example, if MYPATH defines the location C:\Myfiles, you can specify:
TRACEBUFFER,savefile '$MYPATH\mytrace.dat'
Closefile
TRACEBUFFER ,closefile
Unload the data from the last file loaded with loadfile and clear the Analysis window.
Amount
TRACEBUFFER ,amount
=size
This subcommand is deprecated. Specify the number of captured trace records to read
from the trace buffer. There is a default value that normally corresponds to the entire
trace buffer. Set this if you do not require analysis of all of the captured trace buffer.
2-314
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
The value of size is one of:
0
The default buffer size. Normally this is the whole buffer, but see your
analyzer documentation for full details.
n
The maximum number of records to read.
n..m
The range of records to read, with 0 being the trigger record, if any, and
the start of the buffer point if not triggered. If you have a trigger record,
you can use negative values to reference records before the trigger.
For example, if a trigger is specified then 10..200 means read 190 records
starting 10 records after the analyzer triggered.
If no trigger is specified, the same string, 10..200, means to read the 190
records starting 10 records into the buffer.
To read the records around the trigger position in the buffer, you can
specify -20..20.
Scaletime
TRACEBUFFER ,scaletime =scale
Set the units for time values displayed in the Analysis window, where scale is:
0
The default units
1
Picoseconds (10-12 seconds)
2
Nanoseconds (10-9 seconds)
3
Microseconds (10-6 seconds)
4
Milliseconds (10-3 seconds)
5
Seconds
6
Cycles.
For ARM ETM, the default units are nanoseconds, and you cannot use scale 6, cycles.
Speed
TRACEBUFFER ,speed =mhz
Set the speed of the target processor clock for use in cycle-to-time conversions, where
mhz is the clock frequency in MHz. The default value is 20MHz. For example:
TRACEBUFFER,speed=40
sets the speed to 40MHz, so that a period of 400 cycles is considered to take 400/40E6
seconds, or 10 microseconds.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-315
RealView Debugger Commands
Find_trigger
TRACEBUFFER ,find_trigger
Searches for the trigger position in the trace buffer. If found, the item is selected and the
Analysis window display is centered on it. There are no arguments.
Find_position
TRACEBUFFER ,find_position =position
Searches for the indicated position or set of positions in the trace buffer, where position
is an integer or range:
n
The position to find.
n..m
Find the first in a range of positions from n to m inclusive.
n..+o
Find the first in a range of positions from n to n+o inclusive.
The values n and m can be negative if a trigger is defined. If any of the positions is found,
the first is selected and the Analysis window display is centered on it.
Find_time
TRACEBUFFER ,find_time =time
Searches for the indicated time or range of times in the trace buffer, where time is an
integer or range:
n
The time to find.
n..m
Find the first in a range of times from n to m inclusive.
n..+o
Find the first in a range of times from n to n+o inclusive.
The values n and m can be negative if a trigger is defined. If any of the times are found,
the first is selected and the Analysis window display is centered on it.
Find_address
TRACEBUFFER ,find_address =address
Searches for the indicated address or set of positions in the trace buffer, where address
is an integer or range:
n
The address to find.
n..m
Find the first in a range of addresses from n to m inclusive.
n..+o
Find the first in a range of addresses from n to n+o inclusive.
If any of the addresses are found, the first is selected and the Analysis window display
is centered on it.
2-316
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
Find_data
TRACEBUFFER ,find_data =dbval
Searches for the indicated data bus value or set of values in the trace buffer, where dbval
is an integer or range:
n
The data bus value to find.
n..m
Find the first in a range of data bus values from n to m inclusive.
n..+o
Find the first in a range of data bus values from n to n+o inclusive.
The values n and m can be negative. If any of the values are found, the first is selected
and the Analysis window display is centered on it.
Find_name
TRACEBUFFER ,find_name ="text"
Searches for the supplied text. The search is based on a textual search of the
information in the Symbolic column of the analysis window. If found, the record is
selected and the Analysis window display is centered on it.
Posfilter
TRACEBUFFER ,posfilter =position
Restricts the trace buffer information displayed in the Analysis window based on a
positions or set of positions, where position is an integer or range:
n
The position to display.
n..m
Display the range of positions from n to m inclusive. n can be negative.
n..+o
Display the range of positions from n to n+o inclusive.
The values n and m can be negative if a trigger is defined. Positions are displayed in the
Elem column of the Analysis window.
Applying a filter to the trace buffer does not lose information unless you save the trace
with the filtered qualifier. See Savefile on page 2-313 for more information.
Timefilter
TRACEBUFFER ,timefilter =time
Restricts the trace buffer information displayed in the Analysis window based on a time
or range of times in the current time scale units, where time is an integer or range:
n
The time to display.
n..m
Display the range of times from n to m inclusive.
n..+o
Display the range of times from n to n+o inclusive.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-317
RealView Debugger Commands
The values n and m can be negative if a trigger is defined. You can use cycle numbers
instead of time values. Applying a filter to the trace buffer does not lose information
unless you save the trace with the filtered qualifier. See Savefile on page 2-313 for
more information.
Addressfilter
TRACEBUFFER ,addrfilter =address
TRACEBUFFER ,addressfilter =address
Restricts the trace buffer information displayed in the Analysis window based on an
address or range of addresses, where address is an integer or range:
n
The address to display.
n..m
Display the range of addresses from n to m inclusive.
n..+o
Display the range of addresses from n to n+o inclusive.
You cannot specify addresses symbolically with addressfilter. Use namefilter instead.
Applying a filter to the trace buffer does not lose information unless you save the trace
with the filtered qualifier. See Savefile on page 2-313 for more information.
Namefilter
TRACEBUFFER ,namefilter ="name"
Restricts the trace buffer information displayed in the Analysis window based on a
symbolic name, where name is a single string. The symbol names used by this filter are
displayed in the Symbolic column of the Analysis window.
Applying a filter to the trace buffer does not lose information unless you save the trace
with the filtered qualifier. See Savefile on page 2-313 for more information.
Percentfilter
TRACEBUFFER ,percentfilter =percent
Restricts the trace buffer information displayed in the Analysis window based on an
percentage of the buffer, where percent is an integer or range:
n
The percentage to display.
n..m
Display the range of percentages from n to m inclusive.
n..+o
Display the range of percentages from n to n+o inclusive.
Applying a filter to the trace buffer does not lose information unless you save the trace
with the filtered qualifier. See Savefile on page 2-313 for more information.
2-318
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
Datavaluefilter
TRACEBUFFER ,dvalfilter =value
TRACEBUFFER ,datavaluefilter =value
Restricts the trace buffer information displayed in the Analysis window based on an
data value or range of values, where value is an integer or range:
n
The value to display.
n..m
Display the range of value from n to m inclusive.
n..+o
Display the range of value from n to n+o inclusive.
Applying a filter to the trace buffer does not lose information unless you save the trace
with the filtered qualifier. See Savefile on page 2-313 for more information.
Accesstypefilter
TRACEBUFFER ,typefilter =mask
TRACEBUFFER ,accesstypefilter =mask
Restricts the trace buffer information displayed in the Analysis window based on an
access type, where mask is a bitwise-OR of the following values:
0x001
Code access.
0x002
Data access.
0x004
Instruction prefetch.
0x008
DMA.
0x010
Interrupt.
0x020
Bus transaction.
0x040
Probe collection.
0x080
Pin or signal change.
0x100
Non-trace error.
Applying a filter to the trace buffer does not lose information unless you save the trace
with the filtered qualifier. See Savefile on page 2-313 for more information.
Clearfilter
TRACEBUFFER ,clearfilter
Remove any and all of the filters applied to the trace buffer, so that the Analysis window
displays all the collected trace information.
Or_filter
TRACEBUFFER ,or_filter
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-319
RealView Debugger Commands
Specifies that, if multiple filter conditions are applied to the trace buffer, the trace data
is displayed if any of the filters display it. That is, the display is the union of all the
filters. This is the initial state and you can change it using and_filter. Specifying
or_filter overrides a previously active and_filter setting, and the change is applied to
the Analysis window immediately.
And_filter
TRACEBUFFER ,and_filter
Specifies that, if multiple filter conditions are applied to the trace buffer, the trace data
is displayed only if all of the filters display it. That is, the display is the intersection of
all the filters. Specifying and_filter overrides a previously active or_filter setting and
the change is applied to the Analysis window immediately.
Invert_filter
TRACEBUFFER ,invert_filter
Invert the sense of the specified filter conditions.
For example, if you specify posfilter and Datavaluefilter, then:
•
with and_filter specified, the filtering process returns trace information for the
areas of execution except where both the position and data value match criteria
you have entered are satisfied
•
for or_filter specified, the filtering process returns trace information for the
areas of execution except where either the position or data value match criterion
you have entered is satisfied.
Normal_filter
TRACEBUFFER ,normal_filter
Revert back to non-inverted filtering (the default).
Pos_relative
TRACEBUFFER ,pos_relative
Specifies that the element (position) numbering used in the Elem column of the Analysis
window is relative to the trigger position, so that the trigger record is numbered 0, the
record before (in time) the trigger is -1, and the record after is 1.
Pos_absolute
TRACEBUFFER ,pos_absolute
2-320
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
Specifies that the element (position) numbering used in the Elem column of the Analysis
window is absolute, so that the record captured first is numbered 0, and records captured
later are numbered in increasing sequence.
You cannot use this mode with the ARM ETM because records are always relative to a
trigger.
Refresh
TRACEBUFFER ,refresh
This option refreshes the trace display.
Gui
TRACEBUFFER ,gui
This option modifies the action of the other commands. It specifies that the TRACEBUFFER
command was initiated from the GUI, and that messages must be displayed using
dialogs rather than text in the command window.
Note
This option has no effect when running in command line mode.
Examples
The following examples show how to use TRACEBUFFER:
TRACEBUFFER,timefilter 49.9..50.1
Set a filter that displays in the Analysis window only trace records
captured 0.1 time unit before and after 50 time units. You set time
units with scaletime.
TRACEBUFFER,savefile,full ="tracerun.trc"
Save the whole of the current trace buffer, because no filtering is
applied, to a file in the current directory called tracerun.trc.
TRACEBUFFER,find_name ="main"
Search through the Analysis window for the first occurrence of the
text main, and display it.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-321
RealView Debugger Commands
See also
The following commands provide similar or related functionality:
•
ANALYZER on page 2-26
•
DTBREAK on page 2-147
•
DTRACE on page 2-151
•
ETM_CONFIG on page 2-165
•
TRACE on page 2-309
•
TRACEDATAACCESS on page 2-323
•
TRACEDATAREAD on page 2-329
•
TRACEDATAWRITE on page 2-335
•
TRACEEXTCOND on page 2-341
•
TRACEINSTREXEC on page 2-346
•
TRACEINSTRFETCH on page 2-352.
2-322
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.134 TRACEDATAACCESS
The TRACEDATAACCESS command sets a trace point on data accesses, that is, either reads
or writes.
Note
This command is valid only for ETM-based hardware targets.
Syntax
TRACEDATAACCESS [,qualifier...] {address | address-range}
where:
qualifier
Is an ordered list of zero or more qualifiers. The possible qualifiers are
described in List of qualifiers.
address
Specifies the address at which the tracepoint is placed.
address-range
Specifies the address range for the tracepoint. See Specifying address
ranges on page 2-2 for details on how to specify an address range.
Description
This command sets a tracepoint at the address or address range you specify that triggers
when an instruction access at the indicated address accesses data from memory.
The tracepoint type is by default to trigger, that is, start collecting trace information into
the trace buffer. You can modify the action using the hw_out: qualifier to, for example,
stop tracing.
For more information about tracepoints and the way you access the ETM, see the
Embedded Trace Macrocell Specification and the chapters that describe setting
unconditional and conditional tracepoints in the RealView Debugger v3.0 Trace User
Guide.
List of qualifiers
The command qualifiers are as follows, but not all qualifiers are available for all of the
supported trace targets:
hw_ahigh:(n)
ARM DUI 0175H
Specifies the high address for an address-range tracepoint. The
low address is specified by the standard tracepoint address.
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-323
RealView Debugger Commands
For example, this command sets a tracepoint that triggers when a
data access is made by any instruction in the address range from
0x1000 to 0x1200:
TRACEDATAACCESS,hw_ahigh:0x1200 0x1000
hw_dvalue:(n)
Specifies a data value to be compared to values transmitted on the
processor data bus.
For example, this command sets a tracepoint that triggers for a
data read or a data write of the data value 0x400 at an instruction at
address 0x1FA00:
TRACEDATAACCESS,hw_dvalue:0x400 0x1FA00
hw_dhigh:(n)
Specifies the high data value for a data-range tracepoint. The low
data value is specified by the hw_dvalue qualifier.
For example, this command sets a tracepoint that triggers for any
data read or a data write of the data value between 0x00-0x18 at an
instruction at address 0x1000:
TRACEDATAACCESS,hw_dvalue:0x0,hw_dhigh:0x18 0x1000
hw_dmask:(n)
Specifies the data value mask value used for in comparisons with
a data-value tracepoint. Data values that match the value specified
by the hw_dvalue qualifier when masked with this value cause the
tracepoint to trigger.
For example, this command sets a tracepoint that triggers for any
data read or a data write of the data value between 0x400-0x4FF at
an instruction at address 0x1000:
TRACEDATAACCESS,hw_dvalue:0x400,hw_dmask:0xF00 0x1000
hw_passcount:(n)
Specifies the number of times that the specified condition has to
occur to trigger the tracepoint.
You can use this option to set up and use the ARM ETM counter
hardware, if the ETM has counters and there is one available for
use. ETM counters are 32 bits.
hw_and:{[then-]id} Perform an and or an and-then conjunction with an existing
tracepoint identifed by id, which is one of:
•
•
•
2-324
next for the next breakpoint specified for this connection
prev for the last breakpoint specified for this connection
the breakpoint list index of an existing breakpoint.
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
Tracepoints set in this way are called chained tracepoints. How
RealView Debugger processes the tracepoints depends on the
conjunction you have used:
•
In the and form, the conditions associated with both
tracepoints are chained together, so that trace capture starts
only when both conditions simultaneously match.
For example:
TRACEDATAACCESS,hw_and:next \MODIFY\#582
TRACEDATAACCESS,hw_and:prev \ACCESS\#379
•
In the and-then form, RealView Debugger examines the
chained tracepoints starting with the last one you specified.
When the condition for the last tracepoint is met, the
previous tracepoint is enabled. However, trace capture starts
only when this tracepoint condition is met. RealView
Debugger continues processing all tracepoints in the chain,
until the condition in first one you specified is met. At this
point, trace capture starts.
For example, you might have three tracepoints in a chain:
TRACEDATAACCESS,hw_and:{then-next} 0x10014
TRACEDATAACCESS,hw_and:{then-prev} 0x10018
TRACEDATAACCESS,hw_and:{then-prev} 0x1001B
In this case, RealView Debugger first checks for a data
access at address 0x1001B, then at address 0x10018, and
finally at adress 0x10014. When all conditions are met, trace
capture starts.
If you clear a tracepoint that has the ID next, then all tracepoints
in the chain are cleared.
If you clear a tracepoint that has the ID prev, then that tracepoint
and the following ones are cleared. The previous breakpoints in
the chain remain set.
hw_in:{s}
Input trigger tests. The string s is specific to the trace connection
being used. For the ARM ETM, the following case-sensitive
forms are available:
Ignore Security Level=Yes|No
Enables Secure and Normal mode data comparisons for
processors that implement the TrustZone architecture:
Yes
ARM DUI 0175H
Match when the processor is in any mode.
This is the default.
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-325
RealView Debugger Commands
Match only when the processor is in the
mode specified by the address suffix:
•
S:address indicates Secure mode.
•
N:address indicates Normal mode.
For example, the command to set a tracepoint for a
Secure mode address is:
No
TRACEDATAACCESS,hw_in:{Ignore Security Level=No}
S:0x8100.
"Size of Data Access=s"
This determines the following:
•
for data accesses, the size of the data transfer
•
for instruction accesses, the size of the
instruction accessed.
The size s is one of:
Any
Depends on the implementation:
•
halfword for Thumb code
•
word for ARM code.
This is the default.
Halfword 16-bit accesses (Thumb code).
32-bit accesses (ARM code).
For example, this command sets a tracepoint that
triggers for any 32-bit data read or a write that occurs
in the program code between 0x1E000-0x1FF00:
Word
TRACEDATAACCESS,hw_in:"Size of Data Access=Word"
0x1E00..0x1FF00
hw_out:{s}
Output trigger tests. The string s is specific to the trace connection
being used. For the ARM ETM, the following case-sensitive form
is defined:
"Tracepoint Type=s"
Specify the trace action for this command, where s is:
2-326
Trigger
Sets a trigger point.
Start Tracing
Sets a trace start point.
Stop Tracing
Sets a trace stop point.
Trace Instr
Sets an instruction-only trace
range.
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
Trace Instr and Data
Sets an instruction and data trace
range.
For example, this command sets a tracepoint that traces all
instructions executed between program code addresses
0x1E000-0x1FF00, but does not trace instructions outside this range:
TRACEDATAACCESS,hw_out:"Tracepoint Type=Trace Instr"
0x1E00..0x1FF00
hw_not:{s}
Use this qualifier to invert the sense of an address, data, or hw_and
term specified in the same command. The argument s can be set
to:
addr
Invert the tracepoint address value.
data
Invert the tracepoint value.
then
Invert an associated hw_and:{then} condition.
For example, to trace when a data value does not match a mask,
you can write:
TRACEDATAACCESS,hw_not:data,hw_dmask:0x00FF ...
The trace commands require an address value, and the addr variant
of hw_not uses this address.
TRACEDATAACCESS,hw_not:addr 0x10040..0x10060
This means to trace execution at addresses other than the range
0x10040-0x10060, that is, exclude this region from the trace.
The hw_not:then variant of the command is used in conjunction
with hw_and to form or and nand-then conditions.
modify:(n)
Instead of creating a new tracepoint, modify the tracepoint with
tracepoint ID number n by replacing the address expression and
the qualifiers of the existing tracepoint to those specified in this
command.
Note
You cannot use this qualifier with the hw_and qualifier to change a
non-chained tracepoint to a chained tracepoint. However, you can
modify a chained tracepoint with any other qualifier and also
change the address expression.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-327
RealView Debugger Commands
Examples
The following examples show how to use TRACEDATAACCESS:
TRACEDATAACCESS \MATH_1\#449.3
Set a trace trigger at statement 3 of line 449 in the file math.c.
TRACEDATAACCESS \MAIN_1\#35..\MAIN_1\#63
Start tracing instructions when a data access in the code between
line 35-63 of main.c occurs.
TRACEDATAACCESS,hw_pass:5,hw_out:"Tracepoint Type=Start Tracing" \MAIN_1\#35
Start tracing when a data access at line 35 of main.c occurs.
TRACEDATAACCESS,hw_out:"Tracepoint Type=Stop Tracing" \GUI_1\#35..\GUI_1\#78
Stop tracing when any instruction between line 35-78 of gui.c
accesses data.
Alias
TRCDACCES is an alias of TRACEDATAACCESS.
See also
The following commands provide similar or related functionality:
•
ANALYZER on page 2-26
•
DTBREAK on page 2-147
•
DTRACE on page 2-151
•
ETM_CONFIG on page 2-165
•
TRACE on page 2-309
•
TRACEBUFFER on page 2-312
•
TRACEDATAREAD on page 2-329
•
TRACEDATAWRITE on page 2-335
•
TRACEEXTCOND on page 2-341
•
TRACEINSTREXEC on page 2-346
•
TRACEINSTRFETCH on page 2-352.
2-328
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.135 TRACEDATAREAD
The TRACEDATAREAD command enables you to set a tracepoint on data reads.
Note
This command is valid only for ETM-based hardware targets.
Syntax
TRACEDATAREAD [,qualifier...] {address | address-range}
where:
qualifier
Is an ordered list of zero or more qualifiers. The possible qualifiers are
described in List of qualifiers.
address
Specifies the address at which the tracepoint is placed.
address-range
Specifies the address range at which the tracepoint is placed. See
Specifying address ranges on page 2-2 for details on how to specify an
address range.
Description
This command sets a tracepoint at the address or address range you specify that triggers
when an instruction access at the indicated address reads data from memory.
The tracepoint type is by default to trigger, that is, start collecting trace information into
the trace buffer. You can modify the action using the hw_out: qualifier to, for example,
stop tracing.
For more information about tracepoints and the way you access the ETM, see the
Embedded Trace Macrocell Specification and the chapters that describe setting
unconditional and conditional tracepoints in the RealView Debugger v3.0 Trace User
Guide.
List of qualifiers
The command qualifiers are as follows, but not all qualifiers are available for all of the
supported trace targets:
hw_ahigh:(n)
ARM DUI 0175H
Specifies the high address for an address-range tracepoint. The
low address is specified by the standard tracepoint address.
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-329
RealView Debugger Commands
For example, this command sets a tracepoint that triggers when a
data read is made by any instruction in the address range from
0x1000 to 0x1200:
TRACEDATAREAD,hw_ahigh:0x1200 0x1000
This is equivalent to the command:
TRACEDATAREAD 0x1000..0x1200
hw_dvalue:(n)
Specifies a data value to be compared to values transmitted on the
processor data bus.
For example, this command sets a tracepoint that triggers for a
data read of the data value 0x400 at an instruction at address
0x1FA00:
TRACEDATAREAD,hw_dvalue:0x400 0x1FA00
hw_dhigh:(n)
Specifies the high data value for a data-range tracepoint. The low
data value is specified by the hw_dvalue qualifier.
For example, this command sets a tracepoint that triggers for any
data read of the data value between 0x00-0x18 at an instruction at
address 0x1000:
TRACEDATAREAD,hw_dvalue:0x0,hw_dhigh:0x18 0x1000
hw_dmask:(n)
Specifies the data value mask value used for in comparisons with
a data-value tracepoint. Data values that match the value specified
by the hw_dvalue qualifier when masked with this value cause the
tracepoint to trigger.
For example, this command sets a tracepoint that triggers for any
data read of the data value between 0x400-0x4FF at an instruction
at address 0x1000:
TRACEDATAREAD,hw_dvalue:0x400,hw_dmask:0xF00 0x1000
hw_passcount:(n)
Specifies the number of times that the specified condition has to
occur to trigger the tracepoint.
You can use this option to set up and use the ARM ETM counter
hardware, if the ETM has counters and there is one available for
use. ETM counters are 32 bits.
hw_and:{[then-]id} Perform an and or an and-then conjunction with an existing
tracepoint identifed by id, which is one of:
•
•
•
2-330
next for the next breakpoint specified for this connection
prev for the last breakpoint specified for this connection
the breakpoint list index of an existing breakpoint.
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
Tracepoints set in this way are called chained tracepoints. How
RealView Debugger processes the tracepoints depends on the
conjunction you have used:
•
In the and form, the conditions associated with both
tracepoints are chained together, so that trace capture starts
only when both conditions simultaneously match.
For example:
TRACEDATAREAD,hw_and:next \MODIFY\#582
TRACEDATAREAD,hw_and:prev \ACCESS\#379
•
In the and-then form, RealView Debugger examines the
chained tracepoints starting with the last one you specified.
When the condition for the last tracepoint is met, the
previous tracepoint is enabled. However, trace capture starts
only when this tracepoint condition is met. RealView
Debugger continues processing all tracepoints in the chain,
until the condition in first one you specified is met. At this
point, trace capture starts.
For example, you might have three tracepoints in a chain:
TRACEDATAREAD,hw_and:{then-next} 0x10014
TRACEDATAREAD,hw_and:{then-prev} 0x10018
TRACEDATAREAD,hw_and:{then-prev} 0x1001B
In this case, RealView Debugger first checks for a data read
at address 0x1001B, then at address 0x10018, and finally at
adress 0x10014. When all conditions are met, trace capture
starts.
If you clear a tracepoint that has the ID next, then all tracepoints
in the chain are cleared.
If you clear a tracepoint that has the ID prev, then that tracepoint
and the following ones are cleared. The previous breakpoints in
the chain remain set.
hw_in:{s}
Input trigger tests. The string s is specific to the trace connection
being used. For the ARM ETM, the following case-sensitive
forms are defined:
Ignore Security Level=Yes|No
Enables Secure and Normal mode data comparisons for
processors that implement the TrustZone architecture:
Yes
ARM DUI 0175H
Match when the processor is in any mode.
This is the default.
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-331
RealView Debugger Commands
Match only when the processor is in the
mode specified by the address suffix:
•
S:address indicates Secure mode.
•
N:address indicates Normal mode.
For example, the command to set a tracepoint for a
Secure mode address is:
No
TRACEDATAREAD,hw_in:{Ignore Security Level=No}
S:0x8100.
"Size of Data Access=s"
This determines the following:
•
for data accesses, the size of the data transfer
•
for instruction accesses, the size of the
instruction accessed.
The size s is one of:
Any
Depends on the implementation:
•
halfword for Thumb code
•
word for ARM code.
This is the default.
Halfword 16-bit accesses (Thumb code).
32-bit accesses (ARM code).
For example, this command sets a tracepoint that
triggers for any 32-bit data read or a write that occurs
in the program code between 0x1E000-0x1FF00:
Word
TRACEDATAREAD,hw_in:"Size of Data Access=Word"
0x1E00..0x1FF00
hw_out:{s}
Output trigger tests. The string s is specific to the trace connection
being used. For the ARM ETM, the following case-sensitive form
is defined:
"Tracepoint Type=s"
Specify the trace action for this command, where s is:
2-332
Trigger
Sets a trigger point.
Start Tracing
Sets a trace start point.
Stop Tracing
Sets a trace stop point.
Trace Instr
Sets an instruction-only trace
range.
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
Trace Instr and Data
Sets an instruction and data trace
range.
For example, this command sets a tracepoint that traces all
instructions executed between program code addresses
0x1E000-0x1FF00, but does not trace instructions outside this range:
TRACEDATAREAD,hw_out:"Tracepoint Type=Trace Instr"
0x1E00..0x1FF00
hw_not:{s}
Use this qualifier to invert the sense of an address, data, or hw_and
term specified in the same command. The argument s can be set
to:
addr
Invert the tracepoint address value.
data
Invert the tracepoint value.
then
Invert an associated hw_and:{then} condition.
For example, to trace when a data value does not match a mask,
you can write:
TRACEDATAREAD,hw_not:data,hw_dmask:0x00FF ...
The trace commands require an address value, and the addr variant
of hw_not uses this address.
TRACEDATAREAD,hw_not:addr 0x10040..0x10060
This means to trace execution at addresses other than the range
0x10040 to 0x10060, that is, exclude this region from the trace.
The hw_not:then variant of the command is used in conjunction
with hw_and to form or and nand-then conditions.
modify:(n)
Instead of creating a new tracepoint, modify the tracepoint with
tracepoint ID number n by replacing the address expression and
the qualifiers of the existing tracepoint to those specified in this
command.
Note
You cannot use this qualifier with the hw_and qualifier to change a
non-chained tracepoint to a chained tracepoint. However, you can
modify a chained tracepoint with any other qualifier and also
change the address expression.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-333
RealView Debugger Commands
Examples
The following examples show how to use TRACEDATAREAD:
TRACEDATAREAD \COMMAND_1\#132
Set a trace data read trigger at line 132 in the file command.c.
TRACEDATAREAD \MAIN_1\#35..\MAIN_1\#63
Start tracing instructions when a data read occurs in the code
between line 35-63 of main.c.
TRACEDATAREAD,hw_pass:5,hw_out:"Tracepoint Type=Start Tracing" \MAIN_1\#35
Start tracing when a data read occurs at line 35 of main.c.
TRACEDATAREAD,hw_out:"Tracepoint Type=Stop Tracing" \GUI_1\#35..\GUI_1\#78
Stop tracing when any instruction between line 35-78 of gui.c
reads data.
Alias
TRCDREAD is an alias of TRACEDATAREAD.
See also
The following commands provide similar or related functionality:
•
ANALYZER on page 2-26
•
DTBREAK on page 2-147
•
DTRACE on page 2-151
•
ETM_CONFIG on page 2-165
•
TRACE on page 2-309
•
TRACEBUFFER on page 2-312
•
TRACEDATAACCESS on page 2-323
•
TRACEDATAWRITE on page 2-335
•
TRACEEXTCOND on page 2-341
•
TRACEINSTREXEC on page 2-346
•
TRACEINSTRFETCH on page 2-352.
2-334
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.136 TRACEDATAWRITE
The TRACEDATAWRITE command enables you to set a tracepoint on data reads.
Note
This command is valid only for ETM-based hardware targets.
Syntax
TRACEDATAWRITE [,qualifier...] {address | address-range}
where:
qualifier
Is an ordered list of zero or more qualifiers. The possible qualifiers are
described in List of qualifiers.
address
Specifies the address at which the tracepoint is placed.
address-range
Specifies the address range at which the tracepoint is placed. See
Specifying address ranges on page 2-2 for details on how to specify an
address range.
Description
This command sets a tracepoint at the address or address range you specify that triggers
when an instruction access at the indicated address writes data to memory.
The tracepoint type is by default to trigger, that is, start collecting trace information into
the trace buffer. You can modify the action using the hw_out: qualifier to, for example,
stop tracing.
For more information about tracepoints and the way you access the ETM, see the
Embedded Trace Macrocell Specification and the chapters that describe setting
unconditional and conditional tracepoints in the RealView Debugger v3.0 Trace User
Guide.
List of qualifiers
The command qualifiers are as follows, but not all qualifiers are available for all of the
supported trace targets:
hw_ahigh:(n)
ARM DUI 0175H
Specifies the high address for an address-range tracepoint. The
low address is specified by the standard tracepoint address.
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-335
RealView Debugger Commands
For example, this command sets a tracepoint that triggers when
data is written by any instruction in the address range from 0x1000
to 0x1200:
TRACEDATAWRITE,hw_ahigh:0x1200 0x1000
This is equivalent to the command:
TRACEDATAWRITE 0x1000..0x1200
hw_dvalue:(n)
Specifies a data value to be compared to values transmitted on the
processor data bus.
For example, this command sets a tracepoint that triggers when
data value 0x400 is written by an instruction at address 0x1FA00:
TRACEDATAWRITE,hw_dvalue:0x400 0x1FA00
hw_dhigh:(n)
Specifies the high data value for a data-range tracepoint. The low
data value is specified by the hw_dvalue qualifier.
For example, this command sets a tracepoint that triggers when
data value between 0x00-0x18 is written by an instruction at
address 0x1000:
TRACEDATAWRITE,hw_dvalue:0x0,hw_dhigh:0x18 0x1000
hw_dmask:(n)
Specifies the data value mask value used for in comparisons with
a data-value tracepoint. Data values that match the value specified
by the hw_dvalue qualifier when masked with this value cause the
tracepoint to trigger.
For example, this command sets a tracepoint that triggers when
data value between 0x400-0x4FF is written by an instruction at
address 0x1000:
TRACEDATAWRITE,hw_dvalue:0x400,hw_dmask:0xF00 0x1000
hw_passcount:(n)
Specifies the number of times that the specified condition has to
occur to trigger the tracepoint.
You can use this option to set up and use the ARM ETM counter
hardware, if the ETM has counters and there is one available for
use. ETM counters are 32 bits.
hw_and:{[then-]id} Perform an and or an and-then conjunction with an existing
tracepoint identifed by id, which is one of:
•
•
•
2-336
next for the next breakpoint specified for this connection
prev for the last breakpoint specified for this connection
the breakpoint list index of an existing breakpoint.
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
Tracepoints set in this way are called chained tracepoints. How
RealView Debugger processes the tracepoints depends on the
conjunction you have used:
•
In the and form, the conditions associated with both
tracepoints are chained together, so that trace capture starts
only when both conditions simultaneously match.
For example:
TRACEDATAWRITE,hw_and:next \MODIFY\#582
TRACEDATAWRITE,hw_and:prev \ACCESS\#379
•
In the and-then form, RealView Debugger examines the
chained tracepoints starting with the last one you specified.
When the condition for the last tracepoint is met, the
previous tracepoint is enabled. However, trace capture starts
only when this tracepoint condition is met. RealView
Debugger continues processing all tracepoints in the chain,
until the condition in first one you specified is met. At this
point, trace capture starts.
For example, you might have three tracepoints in a chain:
TRACEDATAWRITE,hw_and:{then-next} 0x10014
TRACEDATAWRITE,hw_and:{then-prev} 0x10018
TRACEDATAWRITE,hw_and:{then-prev} 0x1001B
In this case, RealView Debugger first checks for a data write
at address 0x1001B, then at address 0x10018, and finally at
adress 0x10014. When all conditions are met, trace capture
starts.
If you clear a tracepoint that has the ID next, then all tracepoints
in the chain are cleared.
If you clear a tracepoint that has the ID prev, then that tracepoint
and the following ones are cleared. The previous breakpoints in
the chain remain set.
hw_in:{s}
Input trigger tests. The string s is specific to the trace connection
being used. For the ARM ETM, the following case-sensitive
forms are defined:
Ignore Security Level=Yes|No
Enables Secure and Normal mode data comparisons for
processors that implement the TrustZone architecture:
Yes
ARM DUI 0175H
Match when the processor is in any mode.
This is the default.
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-337
RealView Debugger Commands
Match only when the processor is in the
mode specified by the address suffix:
•
S:address indicates Secure mode.
•
N:address indicates Normal mode.
For example, the command to set a tracepoint for a
Secure mode address is:
No
TRACEDATAWRITE,hw_in:{Ignore Security Level=No}
S:0x8100.
"Size of Data Access=s"
This determines the following:
•
for data accesses, the size of the data transfer
•
for instruction accesses, the size of the
instruction accessed.
The size s is one of:
Any
Depends on the implementation:
•
halfword for Thumb code
•
word for ARM code.
This is the default.
Halfword 16-bit accesses (Thumb code).
32-bit accesses (ARM code).
For example, this command sets a tracepoint that
triggers for any 32-bit data read or a write that occurs
in the program code between 0x1E000-0x1FF00:
Word
TRACEDATAWRITE,hw_in:"Size of Data Access=Word"
0x1E00..0x1FF00
hw_out:{s}
Output trigger tests. The string s is specific to the trace connection
being used. For the ARM ETM, the following case-sensitive form
is defined:
"Tracepoint Type=s"
Specify the trace action for this command, where s is:
2-338
Trigger
Sets a trigger point.
Start Tracing
Sets a trace start point.
Stop Tracing
Sets a trace stop point.
Trace Instr
Sets an instruction-only trace
range.
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
Trace Instr and Data
Sets an instruction and data trace
range.
For example, this command sets a tracepoint that traces all
instructions executed between program code addresses
0x1E000-0x1FF00, but does not trace instructions outside this range:
TRACEDATAWRITE,hw_out:"Tracepoint Type=Trace Instr"
0x1E00..0x1FF00
hw_not:{s}
Use this qualifier to invert the sense of an address, data, or hw_and
term specified in the same command. The argument s can be set
to:
addr
Invert the tracepoint address value.
data
Invert the tracepoint value.
then
Invert an associated hw_and:{then} condition.
For example, to trace when a data value does not match a mask,
you can write:
TRACEDATAWRITE,hw_not:data,hw_dmask:0x00FF ...
The trace commands require an address value, and the addr variant
of hw_not uses this address.
TRACEDATAWRITE,hw_not:addr 0x10040..0x10060
This means to trace execution at addresses other than the range
0x10040 to 0x10060, that is, exclude this region from the trace.
The hw_not:then variant of the command is used in conjunction
with hw_and to form or and nand-then conditions.
modify:(n)
Instead of creating a new tracepoint, modify the tracepoint with
tracepoint ID number n by replacing the address expression and
the qualifiers of the existing tracepoint to those specified in this
command.
Note
You cannot use this qualifier with the hw_and qualifier to change a
non-chained tracepoint to a chained tracepoint. However, you can
modify a chained tracepoint with any other qualifier and also
change the address expression.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-339
RealView Debugger Commands
Examples
The following example shows how to use TRACEDATAWRITE:
TRACEDATAWRITE \MATH_1\#449.3
Set a trace data write trigger at statement 3 of line 449 in the file
math.c.
Alias
TRCDWRITE is an alias of TRACEDATAWRITE.
See also
The following commands provide similar or related functionality:
•
ANALYZER on page 2-26
•
DTBREAK on page 2-147
•
DTRACE on page 2-151
•
ETM_CONFIG on page 2-165
•
TRACE on page 2-309
•
TRACEBUFFER on page 2-312
•
TRACEDATAACCESS on page 2-323
•
TRACEDATAREAD on page 2-329
•
TRACEEXTCOND on page 2-341
•
TRACEINSTREXEC on page 2-346
•
TRACEINSTRFETCH on page 2-352.
2-340
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.137 TRACEEXTCOND
The TRACEEXTCOND command enables you to set a tracepoint that triggers when a
specified external condition is enabled.
Note
This command is valid only for ETM-based hardware targets.
Syntax
TRACEEXTCOND [,qualifier...] {address | address-range}
where:
qualifier
Is an ordered list of zero or more qualifiers. The possible qualifiers are
described in List of qualifiers on page 2-342.
address
Specifies the address at which the tracepoint is placed.
address-range
Specifies the address range at which the tracepoint is placed. See
Specifying address ranges on page 2-2 for details on how to specify an
address range.
Description
This command sets a tracepoint at the address or address range you specify. The
tracepoint triggers when an instruction in the specified address range is executed. By
default, the tracepoint type is Trigger, that is start collecting trace information into the
trace buffer. You can modify the action using the hw_out: qualifiers to, for example, stop
tracing.
For more information about tracepoints and the way you access the ETM, see the
Embedded Trace Macrocell Specification and the chapters that describe setting
unconditional and conditional tracepoints in the RealView Debugger v3.0 Trace User
Guide.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-341
RealView Debugger Commands
List of qualifiers
The command qualifiers are as follows, but not all qualifiers are available for all of the
supported trace targets:
hw_passcount:(n)
Specifies the number of times that the specified condition has to
occur to trigger the tracepoint. You can use this option to set up
and use the ARM ETM counter hardware, if the ETM has counters
and there is one available for use. ETM counters are 32 bits.
hw_and:{[then-]id} Perform an and or an and-then conjunction with an existing
tracepoint identifed by id, which is one of:
•
•
•
next for the next breakpoint specified for this connection
prev for the last breakpoint specified for this connection
the breakpoint list index of an existing breakpoint.
Tracepoints set in this way are called chained tracepoints. How
RealView Debugger processes the tracepoints depends on the
conjunction you have used:
•
In the and form, the conditions associated with both
tracepoints are chained together, so that trace capture starts
only when both conditions simultaneously match.
•
In the and-then form, RealView Debugger examines the
chained tracepoints starting with the last one you specified.
When the condition for the last tracepoint is met, the
previous tracepoint is enabled. However, trace capture starts
only when this tracepoint condition is met. RealView
Debugger continues processing all tracepoints in the chain,
until the condition in first one you specified is met. At this
point, trace capture starts.
If you clear a tracepoint that has the ID next, then all tracepoints
in the chain are cleared.
If you clear a tracepoint that has the ID prev, then that tracepoint
and the following ones are cleared. The previous breakpoints in
the chain remain set.
2-342
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
hw_in:{s}
Input trigger to test for external condition events. The string s is
specific to the trace connection being used. For the ARM ETM,
the following case-sensitive forms are defined:
"External Condition=s"
The tracepoint is activated on the events shown in
Table 2-20.
Table 2-20 External condition events
Event
String setting
External inputs 1-4
ExternalIn1
ExternalIn2
ExternalIn3
ExternalIn4
Extended external inputs 1-4
(ETMv3.1 and later)a
The number of inputs available
depends on the ETM.
Extended
Extended
Extended
Extended
EmbeddedICE watchpoints 1-2
Watchpoint1
Watchpoint2
Access to ASIC memory maps 1-16
ASIC Memmap 1
...
ASIC Memmap 16
ExternalIn1
ExternalIn2
ExternalIn3
ExternalIn4
a. You must also use the ETM_CONFIG command to specify the
number of the external input to test.
Up to four signals are available. The ASIC
manufacturer determines the availability and usage of
these output signals. See your ASIC documentation for
details.
hw_out:{s}
Output trigger tests. The string s is specific to the trace connection
being used. For the ARM ETM, the following case-sensitive
forms are defined:
"Tracepoint Type=s"
Specify the trace action for this command, where s is:
ARM DUI 0175H
Trigger
Sets a trigger point.
Start Tracing
Sets a trace start point.
Stop Tracing
Sets a trace stop point.
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-343
RealView Debugger Commands
Trace Instr
Sets an instruction-only trace
range.
Trace Instr and Data
Sets an instruction and data trace
range.
hw_not:{s}
Use this qualifier to invert the sense of an address, data, or hw_and
term specified in the same command. The argument s can be set
to:
addr
Invert the tracepoint address value.
data
Invert the tracepoint value.
then
Invert an associated hw_and:{then} condition.
For example, to trace when a data value does not match a mask,
you can write:
TRACEEXTCOND,hw_not:data,hw_dmask:0x00FF ...
The trace commands require an address value, and the addr variant
of hw_not uses this address.
TRACEEXTCOND,hw_not:addr 0x10040..0x10060
This means to trace execution at addresses other than the range
0x10040 to 0x10060, that is, exclude this region from the trace.
The hw_not:then variant of the command is used in conjunction
with hw_and to form or and nand-then conditions.
modify:(n)
Instead of creating a new tracepoint, modify the tracepoint with
tracepoint ID number n by replacing the address expression and
the qualifiers of the existing tracepoint to those specified in this
command.
Note
You cannot use this qualifier with the hw_and qualifier to change a
non-chained tracepoint to a chained tracepoint. However, you can
modify a chained tracepoint with any other qualifier and also
change the address expression.
Examples
The following examples show how to use TRACEEXTCOND:
TRACEEXTCOND \MATH_1\#449.3
Set a hardware tracepoint at statement 3 of line 449 in the file
math.c.
2-344
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
TRACEEXTCOND,hw_pass:(5) \MAIN_1\#35
Set a hardware tracepoint using an ETM counter to enable tracing
the fifth time that execution reaches line 35 of main.c.
Alias
TRCEEXTC is an alias of TRACEEXTCOND.
See also
The following commands provide similar or related functionality:
•
ANALYZER on page 2-26
•
DTBREAK on page 2-147
•
DTRACE on page 2-151
•
ETM_CONFIG on page 2-165
•
TRACE on page 2-309
•
TRACEBUFFER on page 2-312
•
TRACEDATAACCESS on page 2-323
•
TRACEDATAREAD on page 2-329
•
TRACEDATAWRITE on page 2-335
•
TRACEINSTREXEC on page 2-346
•
TRACEINSTRFETCH on page 2-352.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-345
RealView Debugger Commands
2.3.138 TRACEINSTREXEC
The TRACEINSTREXEC command enables you to set a tracepoint on instruction execution.
Syntax
TRACEINSTREXEC [,qualifier...] {address | address-range}
where:
qualifier
Is an ordered list of zero or more qualifiers. The possible qualifiers are
described in List of qualifiers.
address
Specifies the address at which the tracepoint is placed.
address-range
Specifies the address range at which the tracepoint is placed. See
Specifying address ranges on page 2-2 for details on how to specify an
address range.
Description
This command sets a tracepoint at the address or address range you specify that triggers
when an instruction is executed in the indicated address range.
The tracepoint type is by default to trigger, that is, start collecting trace information into
the trace buffer. You can modify the action using the hw_out: qualifier to, for example,
stop tracing.
For more information about tracepoints and the way you access the ETM, see the
Embedded Trace Macrocell Specification and the chapters that describe setting
unconditional and conditional tracepoints in the RealView Debugger v3.0 Trace User
Guide.
List of qualifiers
The command qualifiers are as follows, but not all qualifiers are available for all of the
supported trace targets:
hw_ahigh:(n)
Specifies the high address for an address-range tracepoint. The
low address is specified by the standard tracepoint address.
For example, this command sets a tracepoint that triggers for any
address between 0x1000-0x1200:
TRACEINSTREXEC,hw_ahigh:0x1200 0x1000
This is equivalent to the command:
2-346
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
TRACEINSTREXEC 0x1000..0x1200
hw_dvalue:(n)
Specifies a data value to be compared to values transmitted on the
processor data bus.
For example, this command sets a tracepoint that triggers when
the instruction opcode 0xEA000040 is executed in code between
0x1FA00-0x1FAFF:
TRACEINSTREXEC,hw_dvalue:0xEA000040 0x1FA00..0x1FAFF
hw_dhigh:(n)
Specifies the high data value for a data-range tracepoint. The low
data value is specified by the hw_dvalue qualifier.
For example, this command sets a tracepoint that triggers when
the instruction opcode between 0xEA000040-0xEA00004F is executed
in code between 0x1FA00-0x1FAFF:
TRACEINSTREXEC,hw_dvalue:0xEA000040,hw_dhigh:0xEA00004F
0x1FA00..0x1FAFF
hw_dmask:(n)
Specifies the data value mask value for a data-range tracepoint.
Data values that match the value specified by the hw_dvalue
qualifier when masked with this value cause the tracepoint to
trigger.
For example, this command sets a tracepoint that triggers when
the an instruction with basic opcode 0xEA000040 but with any value
in bits [15:8] is executed in code between 0x1FA00-0x1FAFF:
TRACEINSTREXEC,hw_dvalue:0xEA000040,hw_dmask:0xFFFF00FF
0x1FA00..0x1FAFF
hw_passcount:(n)
Specifies the number of times that the specified condition has to
occur to trigger the tracepoint. You can use this option to set up
and use the ARM ETM counter hardware, if the ETM has counters
and there is one available for use. ETM counters are 32 bits.
hw_and:{[then-]id} Perform an and or an and-then conjunction with an existing
tracepoint identifed by id, which is one of:
•
•
•
next for the next breakpoint specified for this connection
prev for the last breakpoint specified for this connection
the breakpoint list index of an existing breakpoint.
Tracepoints set in this way are called chained tracepoints. How
RealView Debugger processes the tracepoints depends on the
conjunction you have used:
•
ARM DUI 0175H
In the and form, the conditions associated with both
tracepoints are chained together, so that trace capture starts
only when both conditions simultaneously match.
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-347
RealView Debugger Commands
•
In the and-then form, RealView Debugger examines the
chained tracepoints starting with the last one you specified.
When the condition for the last tracepoint is met, the
previous tracepoint is enabled. However, trace capture starts
only when this tracepoint condition is met. RealView
Debugger continues processing all tracepoints in the chain,
until the condition in first one you specified is met. At this
point, trace capture starts.
If you clear a tracepoint that has the ID next, then all tracepoints
in the chain are cleared.
If you clear a tracepoint that has the ID prev, then that tracepoint
and the following ones are cleared. The previous breakpoints in
the chain remain set.
hw_in:{s}
Input trigger tests. The string s is specific to the trace connection
being used. For the ARM ETM, the following case-sensitive
forms are defined:
"Check Condition Code=s"
For instruction tracepoints, comparisons, check the
instruction condition code against the specified value,
and return True if it matches, where s is:
Pass
Trace only instructions that are executed.
Fail
Trace only instructions that are not executed.
Ignore Security Level=Yes|No
Enables Secure and Normal mode data comparisons for
processors that implement the TrustZone architecture:
Yes
Match when the processor is in any mode.
This is the default.
Match only when the processor is in the
mode specified by the address suffix:
•
S:address indicates Secure mode.
•
N:address indicates Normal mode.
For example, the command to set a tracepoint for a
Secure mode address is:
No
TRACEINSTREXEC,hw_in:{Ignore Security Level=No}
S:0x8000.
Size of Data Access=s
This determines the following:
•
for data accesses, the size of the data transfer
2-348
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
•
for instruction accesses, the size of the
instruction accessed.
The size s is one of:
Depends on the implementation:
•
halfword for Thumb code
•
word for ARM code.
This is the default.
Any
Halfword 16-bit accesses (Thumb code).
32-bit accesses (ARM code).
Word
hw_out:{s}
Output trigger tests. The string s is specific to the trace connection
being used. For the ARM ETM, the following case-sensitive
forms are defined:
"Tracepoint Type=s"
Specify the trace action for this command, where s
depends on the target connection:
•
For an ETM-based hardware target s is:
Trigger
Sets a trigger point.
Start Tracing
Sets a trace start point.
Stop Tracing
Sets a trace stop point.
Trace Instr
Sets an instruction-only
trace range.
Trace Instr and Data
Sets an instruction and data
trace range.
•
For a RealView Simulator Broker target, such as
RVISS, s is:
Trigger
Sets a trigger point.
Trace Start Point (Instruction Only)
Sets an instruction-only
trace start point.
Trace Start Point (Instruction and Data)
Sets an instruction and data
trace start point.
Trace End Point
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
Sets a trace stop point.
2-349
RealView Debugger Commands
hw_not:{s}
Use this qualifier to invert the sense of an address, data, or hw_and
term specified in the same command. The argument s can be set
to:
addr
Invert the tracepoint address value.
data
Invert the tracepoint value.
then
Invert an associated hw_and:{then} condition.
For example, to trace when a data value does not match a mask,
you can write:
TRACEINSTREXEC,hw_not:data,hw_dmask:0x00FF ...
The trace commands require an address value, and the addr variant
of hw_not uses this address.
TRACEINSTREXEC,hw_not:addr 0x10040..0x10060
This means to trace execution at addresses other than the range
0x10040 to 0x10060, that is, exclude this region from the trace.
The hw_not:then variant of the command is used in conjunction
with hw_and to form or and nand-then conditions.
modify:(n)
Instead of creating a new tracepoint, modify the tracepoint with
tracepoint ID number n by replacing the address expression and
the qualifiers of the existing tracepoint to those specified in this
command.
Note
You cannot use this qualifier with the hw_and qualifier to change a
non-chained tracepoint to a chained tracepoint. However, you can
modify a chained tracepoint with any other qualifier and also
change the address expression.
Examples
The following examples show how to use TRACEINSTREXEC:
TRACEINSTREXEC \MATH_1\#449.3
Set a hardware tracepoint at statement 3 of line 449 in the file
math.c.
TRACEINSTREXEC,hw_pass:(5) \MAIN_1\#35
Set a hardware tracepoint using an ETM counter to enable tracing
the fifth time that execution reaches line 35 of main.c.
2-350
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
Alias
TRCIEXEC is an alias of TRACEINSTREXEC.
See also
The following commands provide similar or related functionality:
•
ANALYZER on page 2-26
•
DTBREAK on page 2-147
•
DTRACE on page 2-151
•
ETM_CONFIG on page 2-165
•
TRACE on page 2-309
•
TRACEBUFFER on page 2-312
•
TRACEDATAACCESS on page 2-323
•
TRACEDATAREAD on page 2-329
•
TRACEDATAWRITE on page 2-335
•
TRACEEXTCOND on page 2-341
•
TRACEINSTRFETCH on page 2-352.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-351
RealView Debugger Commands
2.3.139 TRACEINSTRFETCH
The TRACEINSTRFETCH command enables you to set a tracepoint on instruction fetch from
memory.
Note
This command is valid only for ETM-based hardware targets.
Syntax
TRACEINSTRFETCH [,qualifier...] {address | address-range}
where:
qualifier
Is an ordered list of zero or more qualifiers. The possible qualifiers are
described in List of qualifiers on page 2-353.
address
Specifies the address at which the tracepoint is placed.
address-range
Specifies the address range at which the tracepoint is placed. See
Specifying address ranges on page 2-2 for details on how to specify an
address range.
Description
This command sets a tracepoint at the address or address range you specify that triggers
when an instruction opcode is fetched from memory in the indicated address range.
Note
Use this type of tracepoint with care, because not all instructions that are fetched are
executed, and because the fetch from memory occurs several cycles before execution
and possibly not in execution order.
The tracepoint type is by default to trigger, that is, start collecting trace information into
the trace buffer. You can modify the action using the hw_out: qualifier to, for example,
stop tracing.
For more information about tracepoints and the way you access the ETM, see the
Embedded Trace Macrocell Specification and the chapters that describe setting
unconditional and conditional tracepoints in the RealView Debugger v3.0 Trace User
Guide.
2-352
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
List of qualifiers
The command qualifiers are as follows, but not all qualifiers are available for all of the
supported trace targets:
hw_ahigh:(n)
Specifies the high address for an address-range tracepoint. The
low address is specified by the standard tracepoint address.
For example, this command sets a tracepoint that triggers for any
address between 0x1000-0x1200:
TRACEINSTRFETCH,hw_ahigh:0x1200 0x1000
This is equivalent to the command:
TRACEINSTRFETCH 0x1000..0x1200
hw_dvalue:(n)
Specifies a data value to be compared to values transmitted on the
processor data bus.
For example, this command sets a tracepoint that triggers when
the instruction opcode 0xEA000040 is fetched in code between
0x1FA00-0x1FAFF:
TRACEINSTRFETCH,hw_dvalue:0xEA000040 0x1FA00..0x1FAFF
hw_dhigh:(n)
Specifies the high data value for a data-range tracepoint. The low
data value is specified by the hw_dvalue qualifier.
For example, this command sets a tracepoint that triggers when
the instruction opcode between 0xEA000040-0xEA00004F is fetched
in code between 0x1FA00-0x1FAFF:
TRACEINSTRFETCH,hw_dvalue:0xEA000040,hw_dhigh:0xEA00004F
0x1FA00..0x1FAFF
hw_dmask:(n)
Specifies the data value mask value for a data-range tracepoint.
Data values that match the value specified by the hw_dvalue
qualifier when masked with this value cause the tracepoint to
trigger.
For example, this command sets a tracepoint that triggers when
the an instruction with basic opcode 0x0xEA000040 but with any
value in bits 8-15 is fetched in code between 0x1FA00-0x1FAFF:
TRACEINSTRFETCH,hw_dvalue:0xEA000040,hw_dmask:0xFFFF00FF
0x1FA00..0x1FAFF
hw_passcount:(n)
ARM DUI 0175H
Specifies the number of times that the specified condition has to
occur to trigger the tracepoint. You can use this option to set up
and use the ARM ETM counter hardware, if the ETM has counters
and there is one available for use. ETM counters are 32 bits.
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-353
RealView Debugger Commands
hw_and:{[then-]id} Perform an and or an and-then conjunction with an existing
tracepoint. For example, hw_and:2, or hw_and:"then-2", where 2 is
the tracepoint ID of another tracepoint.
In the and form, the conditions associated with both tracepoints
are chained together, so that the action associated with the second
tracepoint is performed only when both conditions match at the
same time.
In the and-then form, when the condition for the first tracepoint is
met, the second tracepoint is enabled. When the second tracepoint
condition is matched, even if the first condition no longer matches,
the actions associated are performed.
Theid is one of:
hw_in:{s}
•
the tracepoint list index of an existing of tracepoint
•
prev for the last tracepoint specified for this connection
•
next for the target of this condition.
Input trigger tests. The string s is specific to the trace connection
being used. For the ARM ETM, the following case-sensitive
forms are defined:
Ignore Security Level=Yes|No
Enables Secure and Normal mode data comparisons for
processors that implement the TrustZone architecture:
Yes
Match when the processor is in any mode.
This is the default.
Match only when the processor is in the
mode specified by the address suffix:
•
S:address indicates Secure mode.
•
N:address indicates Normal mode.
For example, the command to set a tracepoint for a
Secure mode address is:
No
TRACEINSTRFETCH,hw_in:{Ignore Security Level=No}
S:0x8000.
Size of Data Access=s
This determines the following:
•
for data accesses, the size of the data transfer
•
for instruction accesses, the size of the
instruction accessed.
2-354
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
The size s is one of:
Any
Depends on the implementation:
•
halfword for Thumb code
•
word for ARM code.
This is the default.
Halfword 16-bit accesses (Thumb code).
Word
hw_out:{s}
32-bit accesses (ARM code).
Output trigger tests. The string s is specific to the trace connection
being used. For the ARM ETM, the following case-sensitive
forms are defined:
"Tracepoint Type=s"
Specify the trace action for this command, where s is:
Trigger
Sets a trigger point.
Start Tracing
Sets a trace start point.
Stop Tracing
Sets a trace stop point.
Trace Instr
Sets an instruction-only trace
range.
Trace Instr and Data
Sets an instruction and data trace
range.
hw_not:{s}
Use this qualifier to invert the sense of an address, data, or hw_and
term specified in the same command. The argument s can be set
to:
addr
Invert the tracepoint address value.
data
Invert the tracepoint value.
then
Invert an associated hw_and:{then} condition.
For example, to trace when a data value does not match a mask,
you can write:
TRACEINSTRFETCH,hw_not:data,hw_dmask:0x00FF ...
The trace commands require an address value, and the addr variant
of hw_not uses this address.
TRACEINSTRFETCH,hw_not:addr 0x10040..0x10060
This means to trace execution at addresses other than the range
0x10040 to 0x10060, that is, exclude this region from the trace.
The hw_not:then variant of the command is used in conjunction
with hw_and to form or and nand-then conditions.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-355
RealView Debugger Commands
modify:(n)
Instead of creating a new tracepoint, modify the tracepoint with
tracepoint ID number n by replacing the address expression and
the qualifiers of the existing tracepoint to those specified in this
command.
Note
You cannot use this qualifier with the hw_and qualifier to change a
non-chained tracepoint to a chained tracepoint. However, you can
modify a chained tracepoint with any other qualifier and also
change the address expression.
Alias
TRCIFETCH is an alias of TRACEINSTRFETCH.
See also
The following commands provide similar or related functionality:
•
ANALYZER on page 2-26
•
DTRACE on page 2-151
•
ETM_CONFIG on page 2-165
•
TRACE on page 2-309
•
TRACEBUFFER on page 2-312
•
TRACEDATAACCESS on page 2-323
•
TRACEDATAREAD on page 2-329
•
TRACEDATAWRITE on page 2-335
•
TRACEEXTCOND on page 2-341
•
TRACEINSTREXEC on page 2-346.
2-356
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.140 UNLOAD
The UNLOAD command unloads a specified file.
Syntax
UNLOAD [,qualifier] [{filename | file_num}] [=task]
where:
qualifier
If specified, qualifier must be one of the following:
Unloads all the files in the file list.
all
symbols_only
Unloads the symbols only, not the executable image.
image_only
Unloads the executable image only, not the symbols.
filename | file_num
Specifies a file to be unloaded.
Use the DTFILE command to list details of the file or files that are
associated with the current connection (see DTFILE on page 2-149). The
details include:
•
the file number, which is shown at the start of the output by the text
File file_num
•
the filename and path.
Applicable only to OS-aware images, this specifies a task to be unloaded.
Use this form of the command if you are running multiple tasks and want
to unload only one of them.
task
Description
The UNLOAD command unloads a specified file. If you do not specify a file then all files
are unloaded. If you specify a file, using either a filename or a file number, then only
that file is unloaded. Any unloaded files remain in the file list and can be reloaded.
The effect of unloading the system file is defined by the Target Access. You can unload
only symbols or only the image.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-357
RealView Debugger Commands
Note
If you have specified any arguments for the image, these are lost when you unload the
image. If you specified the arguments as part of the LOAD command, you must specify
the arguments again when you load the image. Alternatively, after loading the image
again, use the ARGUMENTS command to specify the arguments.
You do not have to unload an image to run it again. Use the RESTART command to reset
the PC to the entry point, the use the GO command to run the image.
Examples
The following examples show how to use UNLOAD:
unload dhrystone.axf
Unload the symbols (and macros, if any) for the dhrystone program from
debugger.
See also
The following commands provide similar or related functionality:
•
ADDFILE on page 2-21
•
DELFILE on page 2-127
•
DTFILE on page 2-149
•
LOAD on page 2-202
•
RELOAD on page 2-257
•
RESTART on page 2-263.
2-358
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.141 UP
The UP command moves up stack levels.
Syntax
UP [levels]
where:
levels
Specifies the number of levels to climb. If you do not supply a parameter,
you move up one level.
Description
The UP command moves up stack levels
Each time you move up one level you can see the source line to which you return when
you complete execution of your current function or subroutine. At each level you can
examine the values of variables and registers that are in scope.
If you are already at the top level a message reminds you that you cannot move up any
more. When you have moved up one or more levels, you can use the DOWN command (see
page 2-143) to move down. When you have moved up one or more levels, any STEPLINE
or STEPINSTR command you issue is effective at the lowest level, not at the level currently
in view.
See also
The following commands provide similar or related functionality:
•
DOWN on page 2-143
•
CONTEXT on page 2-113
•
DTFILE on page 2-149.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-359
RealView Debugger Commands
2.3.142 VCLEAR
The VCLEAR command clears a user-defined window and sets the cursor to home.
Syntax
VCLEAR windowid
where:
windowid
Specifies the window to be cleared. This must be a user-defined windowid.
See Window and file numbers on page 1-5 for details.
Description
The VCLEAR command clears a user-defined window and sets the cursor to home.
Examples
The following example shows how to use VCLEAR:
vclear 50
Clear window number 50.
See also
The following commands provide similar or related functionality:
•
PRINTF on page 2-238
•
VCLOSE on page 2-361
•
VOPEN on page 2-367
•
VSETC on page 2-369.
2-360
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.143 VCLOSE
The VCLOSE command removes and closes a user-defined window or file.
Syntax
VCLOSE {windowid | fileid}
where:
windowid | fileid
Specifies the window or file to be closed. This must be a user-defined
windowid or fileid. See Window and file numbers on page 1-5 for details.
Description
The VCLOSE command removes and closes a user-defined window opened with VOPEN, or
closes a user-defined file opened with FOPEN.
Examples
The following example shows how to use VCLOSE:
vclose 50
Close window number 50.
See also
The following commands provide similar or related functionality:
•
FOPEN on page 2-179
•
PRINTF on page 2-238
•
VCLEAR on page 2-360
•
VOPEN on page 2-367
•
VSETC on page 2-369.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-361
RealView Debugger Commands
2.3.144 VERIFYFILE
The VERIFYFILE command compares the contents of a specified file with the contents of
target memory.
Syntax
VERIFYFILE [,{obj|raw|raw8|raw16|raw32|rawb|rawhw|ascii[,opts]}] filename
[=address|offset]
where:
obj
The file is an executable file in the standard target format. For ARM
targets, this is ARM-ELF.
There are no opts supported for this file type.
raw
Compare as raw data, using the most efficient access size for the target.
There are no opts supported for this file type.
You must specify an address with this qualifier.
raw8
Compare as raw data, one byte for each byte of memory.
There are no opts supported for this file type.
You must specify an address with this qualifier.
raw16
Compare as raw data, 16 bits for each 16 bits of memory.
There are no opts supported for this file type.
You must specify an address with this qualifier.
raw32
Compare as raw data, 32 bits for each 32 bits of memory.
There are no opts supported for this file type.
You must specify an address with this qualifier.
2-362
rawb
Deprecated. Use raw8 instead.
rawhw
Deprecated. Use raw16 instead.
ascii
The file is a stream of ASCII digits separated by whitespace. The
interpretation of the digits is specified by other qualifiers (see the opts
qualifier). The starting address of the file must be specified in a one line
header in one of the following ways:
[start]
The start address.
[start,end]
The start address, a comma, and the end address.
[start,+len]
The start address, a comma, and the length.
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
[start,end,size]
The start address, a comma, the end address, a
comma, and a character indicating the size of each
value, where b is 8 bits, h is 16 bits and l is 32 bits.
If the size of the items in the file is not specified, the debugger determines
the size by examining the number of white-space separated significant
digits in the first data value. For example, if the first data value was
0x00A0, the size is set to 16-bits.
Optional qualifiers available for use with the ascii qualifier:
opts
filename
byte
The file is a stream of 8-bit values that are written to target
memory without extra interpretation.
half
The file is a stream of 16-bit values.
long
The file is a stream of 32-bit values.
Specifies the name of the file to be read.
You can include one of more environment variables in the filename. For
example, if MYPATH defines the location C:\Myimages, you can specify:
verifyfile,raw "$MYPATH\\myimage.axf" 0x8000...0x8100
address|offset
Specifies the starting address in target memory for the comparison:
•
For an ascii file type, specify a signed offset value. This is the
offset from the start location that is stored in the ASCII file.
•
For any other type of file, specify a start address or range of
addresses to be compared.
Description
The VERIFYFILE command compares the contents of a specified file with the contents of
target memory.
Data might be stored in a file in a variety of formats. You can specify the format by
specifying the file type. The command then converts the data read from the file before
performing the comparison.
The types of file and file formats supported depend on the target processor and any
loaded DLLs. The type of memory assumed depends on the target processor. For
example, ARM processors have byte addressable memory and CEVA-Oak processors
have word addressable memory.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-363
RealView Debugger Commands
Examples
The following example shows how to use VERIFYFILE:
verifyfile,raw8 'c:\images\rom.dat' =0x8000
Verify that the ROM image file in rom.dat matches target memory
starting at location 0x8000.
See also
The following commands provide similar or related functionality:
•
READFILE on page 2-253
•
TEST on page 2-305
•
WRITEFILE on page 2-376.
2-364
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.145 VMACRO
The VMACRO command attaches a macro to a user-defined window or file. Any output that
is normally sent to the Cmd tab of the Output pane is redirected to the specified window
or file.
Syntax
VMACRO {windowid | fileid} [,macro_name(args)]
where:
windowid | fileid
Specifies the window of file to be associated with the macro. This must
be a user-defined windowid or fileid. See Window and file numbers on
page 1-5 for details.
macro_name
Specifies the name and call arguments of the macro that is to send its
output to the specified window or file. This happens whenever the macro
runs, either directly from the CLI or a command script, or by a breakpoint
being hit to which the macro is attached.
Description
The VMACRO command attaches a specified macro to a specified user-defined window or
file. Any output that is normally sent to the Cmd tab of the Output pane is redirected to
the specified window or file whenever the macro is called.
Note
If the attached macro contains any commands or predefined macros that use a different
windowid or fileid, then they are not affected by the VMACRO command.
If you do not supply a macro name, the window or file is disassociated from any macro.
The VMACRO command runs asynchronously.
Examples
The following examples show how to use VMACRO:
vmacro 50,showmyvars()
Use the macro showmyvars() to write formatted variables to window 50.
vmacro 50
Unbind all macros from user window 50.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-365
RealView Debugger Commands
fopen 100,'c:\myfiles\messages.txt'
vmacro 100,showmyvars()
showmyvars()
vmacro 100
vclose 100
Use the macro showmyvars() to write formatted variables to the file
messages.txt, unbind the macro from the file, and finally close the file.
See also
The following commands provide similar or related functionality:
•
BREAKACCESS on page 2-45
•
BREAKEXECUTION on page 2-56
•
BREAKINSTRUCTION on page 2-67
•
BREAKREAD on page 2-74
•
BREAKWRITE on page 2-85
•
DEFINE on page 2-121
•
FOPEN on page 2-179
•
FPRINTF on page 2-182
•
MONITOR on page 2-217
•
PRINTVALUE on page 2-247
•
VOPEN on page 2-367
•
VSETC on page 2-369.
The following macros provide similar or related functionality:
•
fclose on page 3-11
•
fopen on page 3-15
•
fputc on page 3-17
•
fwrite on page 3-21.
2-366
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.146 VOPEN
The VOPEN command creates a user-defined window that you can use with commands
that have a ;windowid parameter.
Syntax
VOPEN windowid [,screen_num,loc_top,loc_left,loc_bottom,loc_right]
where:
windowid
Specifies a number to identify the new window. This must be a
user-defined windowid. See Window and file numbers on page 1-5 for
details.
If a window already exists with the specified number the command fails.
Use this value for the windowid parameter in commands that you want to
display their output in this window.
screen_num
This parameter is maintained for backward compatibility but is no longer
used. If you want to specify the position and size of the new window, you
must enter a screen_num value for the command to parse correctly.
loc_top
Specifies the number of characters the upper edge of the window is
positioned from the top of the screen.
loc_left
Specifies the number of characters the left side of the window is
positioned from the left side of the screen.
loc_bottom
Specifies the number of characters the bottom row of the window is
positioned from the top of the screen.
loc_right
Specifies the number of characters the right side of the window is
positioned from the left side of the screen.
Description
The VOPEN command creates a user-defined window. When you have created a window
you can direct the output from various other commands to it. The commands that can
have their output redirected are those that have an optional windowid parameter.
If you supply only the windowid parameter, a window is opened with default position and
size of 10 rows of 33 characters. The size of a character is determined by the currently
selected font so the size and placement of the window might appear to vary between
machines and between sessions.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-367
RealView Debugger Commands
After opening a window you can move and resize it as required.
If the error message Bad size specification for window is displayed, check that:
•
loc_top is smaller than loc_bottom
•
loc_left is smaller than loc_right
•
loc_bottom and loc_right are smaller than the screen size.
Examples
The following examples show how to use VOPEN:
vopen 50
Open window number 50 at the default size of 10 rows of 33 characters.
vopen 50,0,5,5,50,40
Open window number 50 at position (5,5) and 45 rows of 35 characters.
See also
The following commands provide similar or related functionality:
•
FOPEN on page 2-179
•
FPRINTF on page 2-182
•
VCLOSE on page 2-361
•
VMACRO on page 2-365
•
WINDOW on page 2-375.
2-368
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.147 VSETC
The VSETC command positions the cursor in the specified user-defined window.
Syntax
VSETC windowid ,row ,column
where:
windowid
Identifies the window that is to have its cursor positioned. This must be a
user-defined windowid. See Window and file numbers on page 1-5 for
details.
row
Specifies the row number in the window, counting from 0, the number of
the top row.
column
Specifies the column number in the window, counting from 0, the number
of the leftmost column.
Description
The VSETC command positions the cursor in the specified user-defined window. This
defines where the next output to be directed to that window appears.
Example
The following example shows how to use VSETC:
vsetc 50,2,5
fprintf 50,"Status: %d", status
Write Status: to window 50, starting from the third column of the sixth row.
See also
The following commands provide similar or related functionality:
•
FOPEN on page 2-179
•
FPRINTF on page 2-182
•
VCLOSE on page 2-361.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-369
RealView Debugger Commands
2.3.148 WAIT
The WAIT command tells the debugger whether to wait for a command to complete
before permitting another command to be issued.
Syntax
WAIT = [{ON | OFF}]
where:
ON
specifies that all following commands are to run synchronously.
OFF
specifies that following commands run according to their default
behavior. This is the default.
Description
The WAIT command makes commands run synchronously. If WAIT is not used, commands
use their default behavior.
All commands run from a macro run synchronously unless WAIT is set OFF.
Note
This command requires that RealView Debugger is connected to a debug target.
Examples
The following examples show how to use WAIT:
•
The following commands cause the debugger to fill memory synchronously,
forcing you to wait until the fill is complete before accepting another command:
wait on
fill/b 0x8000..0x9FFF =0
wait off
•
In the following example, the CEXPRESSION command runs when the target next
stops running (for example, if the breakpoint is hit):
load /pd/r dhrystone.axf
breakexecution main
wait on
go
wait off
cexpression @r0
2-370
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
See also
The following command provides similar or related functionality:
•
PAUSE on page 2-235.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-371
RealView Debugger Commands
2.3.149 WARMSTART
WARMSTART is an alias of RESET (see page 2-259).
2-372
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.150 WHERE
The WHERE command displays a call stack.
Syntax
WHERE [number_of_levels]
where:
number_of_levels
Specifies the number of levels you want to examine. If you do not supply
this parameter, all levels are displayed.
Description
The WHERE command displays a call stack. This shows you the function that you are in,
and the function that called that, and the function that called that, until the debugger
cannot continue. A call stack is not a history of every function call in the life of the
process.
The call stack requires debug information for every procedure called. If debug
information is not available, the call stack stops. The call stack might also stop
prematurely because the stack frames read by the debugger do not conform to the
expected structure, for example if memory corruption has occurred, or if a scheduler has
created new stack frames.
Examples
The following example shows how to use WHERE:
> where
#0: (0x24000148) DHRY_2_1\\Proc_7 Line 79. File='C:\Program
Files\ARM\ADSv1_2\Examples\dhry\dhry_2.c'
#1: (0x24000674) DHRY_1_1\\main Line 164. File='C:\Program
Files\ARM\ADSv1_2\Examples\dhry\dhry_1.c'
This shows a request for a full stack trace of the dhrystone program. The program was
stopped at line 79 of procedure Proc_7(). The call stack tells you that this call of
Proc_7() was made by code at line 164 of main().
The call stack does not tell you what called main(). Normally, there is bootstrap code in
__main() that calls main, but because this code is not normally compiled with debug
symbols included, this procedure is not shown in the call stack.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-373
RealView Debugger Commands
> where 1
#0: (0x240002B8) DHRY_1_1\\Proc_3 Line 355. File='C:\Program
Files\ARM\ADSv1_2\Examples\dhry\dhry_1.c'
This shows a request for a single level stack trace of the dhrystone program. The
program was stopped at line 355 of procedure Proc_3(). Compare this to the output of
CONTEXT at the same location:
At the PC: (0x240002B8): DHRY_1_1\Proc_3 Line 355
See also
The following commands provide similar or related functionality:
•
CONTEXT on page 2-113
•
SCOPE on page 2-268
•
SETREG on page 2-275.
2-374
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.151 WINDOW
The WINDOW command displays a list of open user-defined windows and files.
Syntax
WINDOW [{windowid | fileid | name}]
where
windowid | fileid
The user-defined windowid or fileid. See Window and file numbers on
page 1-5 for details.
The name of the window or file.
name
Description
The WINDOW command displays a list of the user-defined windows that you have opened
with the VOPEN command, and a list of the user-defined files that you have opened with
the FOPEN command.
Example
The following command shows a list of files and user-defined windows that are open:
> fopen 98,'c:\myfiles\myfile.txt'
> vopen 99
> window
Num
Type
Name
98
Files
myfile.txt
99
User
User99
Available Terminal Window types: File, User
See also
The following commands provide similar or related functionality:
•
FOPEN on page 2-179
•
VCLEAR on page 2-360
•
VCLOSE on page 2-361
•
VOPEN on page 2-367.
•
VSETC on page 2-369.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-375
RealView Debugger Commands
2.3.152 WRITEFILE
The WRITEFILE command writes the contents of memory to a file, performing a format
conversion if necessary.
Syntax
WRITEFILE ,{obj|raw|raw8|raw16|raw32|rawb|rawhw|ascii[,opts]} [,nowarn] filename
=addressrange
where:
obj
Write the file in the standard executable target format. For ARM targets,
this is ARM-ELF.
There are no opts supported for this file type.
raw
Write the file as raw data, using the most efficient access size for the
target.
There are no opts supported for this file type.
You must specify an address with this qualifier.
raw8
Write the file as raw data, one byte for each byte of memory.
There are no opts supported for this file type.
You must specify an address with this qualifier.
raw16
Write the file as raw data, 16 bits for each 16 bits of memory.
There are no opts supported for this file type.
You must specify an address with this qualifier.
raw32
Write the file as raw data, 32 bits for each 32 bits of memory.
There are no opts supported for this file type.
You must specify an address with this qualifier.
rawb
Deprecated. Use raw8 instead.
rawhw
Deprecated. Use raw16 instead.
ascii
Write the file as a stream of ASCII digits separated by whitespace. The
exact format is specified by other qualifiers (see the opts qualifier). The
file has a one line header that is compatible with READFILE and VERIFYFILE.
This header has the following format:
[start,end,size]
2-376
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
start and end specifies the address range that is written. size is a
character that indicates the size of each value, where b is 8 bits, h is 16
bits and l is 32 bits.
Optional qualifiers available for use with the ascii qualifier:
opts
nowarn
byte
The file is a stream of 8-bit hexadecimal values that are written
to the file without extra interpretation.
half
The file is a stream of 16-bit hexadecimal values.
long
The file is a stream of 32-bit hexadecimal values.
Suppress the display of the large file warning messages, such as:
Downloading n bytes can take a long time. (Hint: Choosing a larger
access size may reduce this time) Do it anyway?
This also suppresses the warning if the file you are writing to already
exists. In this case, the existing file is overwritten.
filename
The name of the file to be written.
You can include one of more environment variables in the filename. For
example, if MYPATH defines the location C:\Myfiles, you can specify:
writefile,raw "$MYPATH\\myfile.dat" 0x8000..0x8100
addressrange The address range in target memory to write to the file. Specify an
address range as start_addr..end_addr, for example 0x8000..0x9000.
Description
The WRITEFILE command writes the contents of memory to a file, performing a format
conversion if necessary.
The type of memory assumed depends on the target processor. For example, ARM
processors have byte addressable memory and CEVA-Oak processors have word
addressable memory.
Examples
The following examples show how to use WRITEFILE:
writefile ,raw "c:\temp\file.dat" =0x8000..0x9000
Write the contents of the 4KB memory page at 0x8000 to the file
c:\temp\file.dat, storing the data in raw, uninterpreted, form.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-377
RealView Debugger Commands
writefile ,ascii,long "c:\temp\file.txt" =0x8000..0x9000
Write the contents of the 4KB memory page at 0x8000 to the file
c:\temp\file.dat, storing it as 32-bit values in target memory endianess.
For example, the file might look similar to this:
[0x8000,0x9000,l]
E28F8090 E898000F E0800008 E0811008
E0822008 E0833008 E240B001 E242C001
E1500001 0A00000E E8B00070 E1540005
...
Note
By writing a file as longs and reading it back as longs on a different target,
you can convert the endianness of the data in the file.
See also
The following commands provide similar or related functionality:
•
FILL on page 2-173
•
LOAD on page 2-202
•
SETMEM on page 2-273
•
READFILE on page 2-253
•
VERIFYFILE on page 2-362.
2-378
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Commands
2.3.153 XTRIGGER
The XTRIGGER command controls whether stopping execution of one processor stops
execution of other processors.
Syntax
XTRIGGER [,in_disable][,in_enable][,out_disable][,out_enable][,onhost]
[[=]connections]
where:
in_disable
Disable input triggering.
in_enable
Enable input triggering.
out_disable
Disable output triggering.
out_enable
Enable output triggering.
onhost
Implement in software. Use this if hardware support is possible, but you
require software implementation nevertheless.
connections
A comma-separated list of connection identifiers, of the form:
connection-id [,connection-id,...]
where:
connection-id
The name of the target connection (see CONNECT
on page 2-108). If the connections have unique
names, then you have only to use the connection
name. Otherwise, you must also specify the Target
Access name
Description
The XTRIGGER command controls the cross-triggering of processor stops. Use it to
specify whether stopping execution of one processor stops execution of other
processors.
For tight synchronization, the target must support hardware cross triggering. If
hardware cross triggering is not available, the debugger simulates cross triggering in
software, but this is slower, and there might be a large delay between one processor
stopping, and the debugger causing the other processors to stop.
If you issue the command with no arguments, it displays the cross-triggering state of all
connections, for example:
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
2-379
RealView Debugger Commands
> xtrigger
ARM940T_0: Input=Enabled OnHost. Output=Disabled OnHost
Simarm_0: Input=Disabled OnHost. Output=Enabled OnHost
If you issue the command with qualifiers, you have to specify a list of one or more
connections to act on. Input triggering means that the processor is stopped by others.
Output triggering means that when the processor stops it stops others.
Example
The following example shows how to use XTRIGGER:
xtrigger,in_enable @[email protected],@[email protected]_1
xtrigger,out_enable @ARM940T_0
Stop both ARM Cortex™-A8 targets when the ARM940T processor stops
(no Target Access is specified, because no other connection exists with
this name).
See also
The following commands provide similar or related functionality:
•
CONNECT on page 2-108
•
SYNCHEXEC on page 2-303.
2-380
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
Chapter 3
RealView Debugger Predefined Macros
This chapter describes available RealView® Debugger predefined macros. It contains
the following sections:
•
Predefined macros listed by function on page 3-2
•
Alphabetical predefined macro reference on page 3-6.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
3-1
RealView Debugger Predefined Macros
3.1
Predefined macros listed by function
This section lists the commands according to their general function:
•
Access data values at an address
•
Flow control statements
•
File and window access on page 3-3
•
String manipulation on page 3-3
•
Memory manipulation on page 3-4
•
Miscellaneous on page 3-4
•
User interaction macros on page 3-5.
3.1.1
Access data values at an address
Table 3-1 contains a summary of the predefined macros that return a data value at a
given address.
Table 3-1 Access data value macros
3.1.2
Description
Macro
Returns a byte value from the specified
address.
byte on page 3-7
Returns a long value from the specified
address.
dword on page 3-8
Returns a word value at the specified
address.
word on page 3-61
Flow control statements
Table 3-2 contains a summary of the conditional statement macros.
Table 3-2 Flow control statements
3-2
Description
Macro
Breaks when an expression evaluates to
True.
until on page 3-57
Breaks when an expression evaluates to
True.
when on page 3-59
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Predefined Macros
3.1.3
File and window access
Table 3-3 contains a summary of the file and window access macros.
Table 3-3 File and window access macros
3.1.4
Description
Macro
Closes a specified file.
fclose on page 3-11
Returns a byte from file or window.
fgetc on page 3-12
Opens a file for reading, writing, or both.
fopen on page 3-15
Writes the contents of next byte to a file.
fputc on page 3-17
Reads a file into a buffer.
fread on page 3-19
Writes a buffer to a file.
fwrite on page 3-21
String manipulation
Table 3-4 contains a summary of the string manipulation macros.
Table 3-4 String manipulation
ARM DUI 0175H
Description
Macro
Concatenates two strings.
strcat on page 3-43
Locates the first occurrence of a character in
a string.
strchr on page 3-45
Compares two strings.
strcmp on page 3-47
Copies a string.
strcpy on page 3-49
Performs string comparison without case
distinction.
stricmp on page 3-51
Returns string length.
strlen on page 3-53
Performs limited comparison of two strings.
strncmp on page 3-55
Copyright © 2002-2006 ARM Limited. All rights reserved.
3-3
RealView Debugger Predefined Macros
3.1.5
Memory manipulation
Table 3-5 contains a summary of the memory manipulation macros.
Table 3-5 Memory Manipulation macros
3.1.6
Description
Macro
Searches for a character in memory.
memchr on page 3-24
Clears memory values.
memclr on page 3-26
Copies characters from memory.
memcpy on page 3-28
Sets the value of characters in memory.
memset on page 3-30
Miscellaneous
Table 3-6 contains a summary of other predefined macros.
Table 3-6 Miscellaneous macros
3-4
Description
Macro
Processes error message returned from
macro.
error on page 3-9
Returns a local string from an address.
getsym on page 3-23
Returns the value of a specified register.
reg_str on page 3-42
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Predefined Macros
3.1.7
User interaction macros
RealView Debugger provides several predefined macros that enable you to get user
input or prompt the user to take action. User interaction macros can be used in
expressions on the command line and can be called from macros that you create
yourself.
Note
Be careful when using these macros as part of test scripts. For example, if you attach
the prompt_text macro to a breakpoint that is triggered frequently in your program,
without testing the return value, it is possible that the debugger displays the prompt
message repeatedly in an endless loop.
Table 3-7 contains a summary of the predefined user interaction macros.
Table 3-7 User interaction macros
Description
Macro
Displays a file containing message text.
prompt_file on
page 3-32
ARM DUI 0175H
Displays a dialog box containing message
text and a choice list.
prompt_list on
Displays a dialog box containing message
text and buttons (Ok and Cancel).
prompt_text on
page 3-34
page 3-36
Displays a dialog box containing question
text and buttons (Yes and No).
page 3-38
Displays a dialog box containing question
text and buttons (Yes, No and Cancel).
on page 3-40
Copyright © 2002-2006 ARM Limited. All rights reserved.
prompt_yesno() on
prompt_yesno_cancel()
3-5
RealView Debugger Predefined Macros
3.2
Alphabetical predefined macro reference
This section lists in alphabetical order all the commands that you can issue to RealView
Debugger using the CLI.
The following sections describe the available predefined macros:
•
byte on page 3-7
•
dword on page 3-8
•
error on page 3-9
•
fclose on page 3-11
•
fgetc on page 3-12
•
fopen on page 3-15
•
fputc on page 3-17
•
fread on page 3-19
•
fwrite on page 3-21
•
getsym on page 3-23
•
memchr on page 3-24
•
memclr on page 3-26
•
memcpy on page 3-28
•
memset on page 3-30
•
prompt_file on page 3-32
•
prompt_list on page 3-34
•
prompt_text on page 3-36
•
prompt_yesno on page 3-38
•
prompt_yesnocancel on page 3-40
•
reg_str on page 3-42
•
strcat on page 3-43
•
strchr on page 3-45
•
strcmp on page 3-47
•
strcpy on page 3-49
•
stricmp on page 3-51
•
strlen on page 3-53
•
strncmp on page 3-55
•
until on page 3-57
•
when on page 3-59
•
word on page 3-61.
3-6
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Predefined Macros
3.2.1
byte
Returns a byte value from the specified address.
Syntax:
unsigned char byte (addr)
void *addr;
where:
The address containing the value to be returned.
addr
Description
This macro returns a value between 0 and 255, corresponding to the memory contents
at the location specified by addr. The byte macro uses the indirection operator to obtain
the value.
Return Value
unsigned char
The byte value located at the specified address.
Rules
The argument default type is specified by using the OPTION command (see OPTION on
page 2-224):
OPTION radix = [ decimal | hex ]
Example
To display the contents of the hexadecimal address 0x8338, enter the following on the
command line:
PRINTVALUE byte(0x8338)
See also
The following macros provide similar or related functionality:
•
dword on page 3-8
•
word on page 3-61.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
3-7
RealView Debugger Predefined Macros
3.2.2
dword
Returns an unsigned long value from a specified address.
Syntax:
unsigned long dword (addr)
void *addr;
where:
The address containing the value to be returned.
addr
Description
This macro returns an unsigned long value, contained within four bytes of memory,
corresponding to the memory contents at the location specified by addr. The dword
macro uses the indirection operator to obtain the value.
Return Value
unsigned long
The four byte value located at the specified address.
Rules
The argument default type is specified by using the OPTION command (see OPTION on
page 2-224):
OPTION radix = [ decimal | hex ]
Example
To display the contents of the hexadecimal address 0x8338, enter the following on the
command line:
PRINTVALUE dword(0x8338)
See also
The following macros provide similar or related functionality:
•
byte on page 3-7
•
word on page 3-61.
3-8
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Predefined Macros
3.2.3
error
Processes an error message returned from a macro.
Syntax:
int error (type, message, value)
int type;
char *message;
long value;
where:
Specifies the error class, indicated by one of the predefined error codes
listed in Table 3-8.
type
Table 3-8 Error classes
Type
Class
Description
1
note
message appears as a line with no prefix.
In the GUI, the message appears in the Output
pane.
2
warning code
message appears with the Warning: prefix.
In the GUI, the message appears in the Output
pane and is also highlighted.
3
message
error code
In the headless debugger message appears with the
Error: prefix.
In the GUI, message appears in an Error dialog
without the prefix.
Pointer to char. Points to the first character in a character string for the
corresponding error message.
The string can contain a single instance of the format specifier %d. In this
case, value is printed in the string. If no format specifier is included in the
string, value is ignored.
Variable of type long.
value
Description
This macro processes an error messages returned from a macro. The error macro
generates a call to the error processing function (_error). It handles messages from both
predefined and user-specified macros.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
3-9
RealView Debugger Predefined Macros
The message and value parameters are formatted in standard PRINTF formats (see PRINTF
on page 2-238).
Return Value
Indicates the error message that is displayed in the Cmd tab of the Code
window.
int
Rules
See the PRINTF command on page 2-238 for value formats.
Example
Do the following:
1.
Define the following macro in an include file, and load the include file:
DEFINE /R int odd(n)
int n;
{
if ((n & 0x1)==1) // check if number is odd, using
// a bitwise AND, and checking for
// nonzero result
return (0);
// zero is returned from this branch,
// indicating: Yes, number is odd.
else
// no - number is even, not odd
error (2, "number specified (%d) is not odd\n", n);
// text msg displayed, %d in format
// specifier used for int display,
// as in printf()
return (1);
// 1 is returned when exiting this
// branch
}
.
2.
Enter the command:
odd(6)
The following error message appears:
Warning: number specified (6) is not odd
3-10
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Predefined Macros
3.2.4
fclose
Closes a specified user-defined file.
Syntax
int fclose (fileid)
int fileid;
where:
fileid
The ID of an open file. This must be a user-defined fileid. See Window
and file numbers on page 1-5 for details.
Description
This macro closes a file that has been opened with the fopen macro.
Example
The example on page 3-13 also shows you how to use fclose in a macro.
See also
The following macros provide similar or related functionality:
•
fgetc on page 3-12
•
fopen on page 3-15
•
fputc on page 3-17
•
fread on page 3-19
•
fwrite on page 3-21.
The following commands provide similar or related functionality:
•
FOPEN on page 2-179
•
FPRINTF on page 2-182
•
VCLOSE on page 2-361
•
VMACRO on page 2-365
•
WINDOW on page 2-375.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
3-11
RealView Debugger Predefined Macros
3.2.5
fgetc
Reads a byte from a file.
Syntax
int fgetc (fileid)
int fileid;
where:
fileid
The ID of the file containing the next byte to be read. This must be a
user-defined fileid. See Window and file numbers on page 1-5 for
details.
Description
This macro returns the contents of the next byte from a file. The fgetc macro name is
short for [file getc() ], where file indicates that the macro operates on a file, and getc
is the standard function for getting a character from a user defined file. This is distinct
from the getchar function, which can only retrieve a character from the standard input,
and is typically the keyboard.
fgetc returns the contents of the next memory location byte from the specified file. You
define the identity of the file with the fopen macro (see fopen on page 3-15), or the FOPEN
command (see FOPEN on page 2-179). Any file used to read, or get, the contents of the
next byte, must be opened in read mode.
Return value
Returns the contents of the next byte of memory from a user specified file
or window. Returns the value -1 if either an end-of-file mark (EOF) or an
error is encountered.
int
Rules
The file read from must be opened in read mode, for example:
fopen(100,"c:\\myfiles\\data_in.txt","r")
3-12
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Predefined Macros
Example
This example shows how to use fgetc, together with fopen, fputc, and fclose:
define /R void copyFile()
{
int retval;
int ch;
// Create data file to read
retval = fopen(100,"c:\\myfiles\\data_in.txt","w");
if (retval < 0)
error(2,"Cannot open file for writing!\n",101);
else {
retval = fwrite("1234567890\n1234567890\n1234567890", 1, 32, 100);
fclose(100);
fopen(100,"c:\\myfiles\\data_in.txt","r");
// open for read-only
if (retval < 0)
error(2,"Source file not opened!\n",101);
else
fopen(200,"c:\\myfiles\data_out.txt","w");
// open for writing
if (retval < 0)
error(2,"Destination file not opened!\n",101);
else
do {
ch = fgetc(100);
// fgetc()
if (ch < 0)
$printf "Finished copying the file!"$;
else
fputc(ch,200);
// fputc()
} while (ch > 0);
}
fclose(100);
fclose(200);
}
}
.
See also
The following macros provide similar or related functionality:
•
fclose on page 3-11
•
fopen on page 3-15
•
fputc on page 3-17
•
fread on page 3-19
•
fwrite on page 3-21.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
3-13
RealView Debugger Predefined Macros
The following commands provide similar or related functionality:
•
FOPEN on page 2-179
•
FPRINTF on page 2-182
•
VCLOSE on page 2-361
•
WINDOW on page 2-375.
3-14
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Predefined Macros
3.2.6
fopen
Opens a file for reading, writing, or both.
Syntax
int fopen (fileid, file_name, mode)
int fileid;
char *file_name;
char *mode;
where:
fileid
An ID number for the file that is opened. This must be a user-defined
fileid. See Window and file numbers on page 1-5 for details.
file_name
A string pointer identifying the name of the file you want to open. If you
specify a hardcoded filename you must enclose it in double quotes. See
Rules for specifying filenames for details on how to specify filenames that
include a path.
mode
Standard C-style file mode.
Description
This macro opens a file for reading, writing, or both.
Return value
One of the following:
int
-1
Failure
fileid
Success, the ID number of the opened file is returned.
Rules for specifying filenames
Follow these rules when specifying a filename:
•
Filenames must be in double quotes, for example "myfiles/file".
•
Filenames containing a backslash must be in double quotes, with each backslash
escaped. For example, "c:\\myfiles\\file".
Example
The example on page 3-13 also shows you how to use fopen in a macro.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
3-15
RealView Debugger Predefined Macros
See also
The following macros provide similar or related functionality:
fclose on page 3-11
•
•
fgetc on page 3-12
•
fputc on page 3-17
•
fread on page 3-19
•
fwrite on page 3-21.
The following commands provide similar or related functionality:
•
FOPEN on page 2-179
•
FPRINTF on page 2-182
•
VCLOSE on page 2-361
•
VMACRO on page 2-365
•
WINDOW on page 2-375.
3-16
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Predefined Macros
3.2.7
fputc
Writes a byte to a file.
Syntax
int fputc (byte,fileid)
int byte;
int fileid;
where:
byte
The byte to be written.
fileid
The ID number of the file where the next byte is to be written. This must
be a user-defined fileid. See Window and file numbers on page 1-5 for
details.
Description
This macro writes the contents of the next byte to a file. You must define the identity of
the file with either the fopen macro (see fopen on page 3-15) or the FOPEN command (see
FOPEN on page 2-179).
Return value
Not used.
int
Rules
The file written to must be opened in write mode, for example:
fopen(100,"c:\\myfiles\\data_out.txt","w").
Example
The example on page 3-13 also shows you how to use fputc in a macro.
See also
The following macros provide similar or related functionality:
•
fclose on page 3-11
•
fgetc on page 3-12
•
fopen on page 3-15
•
fread on page 3-19
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
3-17
RealView Debugger Predefined Macros
•
fwrite on page 3-21.
The following commands provide similar or related functionality:
FOPEN on page 2-179
•
•
FPRINTF on page 2-182
•
VCLOSE on page 2-361
•
WINDOW on page 2-375.
3-18
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Predefined Macros
3.2.8
fread
Reads the contents of a file into a buffer.
Syntax
unsigned long fread (buffer, count, size, fileid)
void *buffer;
unsigned count;
unsigned size;
int fileid;
where:
buffer
Specifies the start of the area into which the data is written.
count
Specifies the number of elements.
size
Specifies the size of each element in bytes.
fileid
The ID number of the file containing the data to be read. This must be a
user-defined fileid. See Window and file numbers on page 1-5 for
details.
Description
This macro reads the contents of a file into a buffer. You must define the identity of the
file with either the fopen macro (see fopen on page 3-15) or the FOPEN command (see
FOPEN on page 2-179).
Return value
unsigned long
The size of the data that is read, and is the same as size * count. However,
it returns the value -1 if an end-of-file (EOF) or error has occurred.
Rules
None
Example
This example shows how to use fread in a macro:
1.
ARM DUI 0175H
Create an include file containing the following macro, for example,
c:\myincludes\myfile.inc:
Copyright © 2002-2006 ARM Limited. All rights reserved.
3-19
RealView Debugger Predefined Macros
define /R void readFile(nElements)
int nElements;
{
char buffer[37];
int nbytes;
int recLen;
recLen = 6;
if (nElements > recLen)
error(2,"Enter a number from 1 to %d.\n",recLen);
else {
strcpy(buffer,"One \nTwo \nThree\nFour \nFive \nSix
fopen(100,"c:\\myfiles\\data.txt","w");
nbytes = fwrite(buffer, nElements, recLen, 100);
$printf "%d bytes written\n",nbytes$;
fclose(100);
fopen(100,"c:\\myfiles\\data.txt","r");
memset(buffer,0,37);
nbytes = fread(buffer, nElements, recLen, 100);
$printf "%d bytes read\n",nbytes$;
$printf "Strings:\n%s",buffer$;
fclose(100);
}
}
.
2.
\n");
At the command line, include the file you created in step 1:
include 'c:\myincludes\myfile.inc'
3.
Run the macro, specifying a value from 1 to 6:
readFile(4)
See also
The following macros provide similar or related functionality:
•
fclose on page 3-11
•
fgetc on page 3-12
•
fopen on page 3-15
•
fputc on page 3-17
•
fwrite on page 3-21.
The following commands provide similar or related functionality:
•
FOPEN on page 2-179
•
FPRINTF on page 2-182
•
VCLOSE on page 2-361
•
WINDOW on page 2-375.
3-20
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Predefined Macros
3.2.9
fwrite
Writes the contents of a buffer to a file or window.
Syntax
unsigned long fwrite (buffer, count, size, outputid)
void *buffer;
unsigned count;
unsigned size;
int outputid;
where:
buffer
Specifies the start of the area from which the data is read.
count
Specifies the number of elements.
size
Specifies the size of each element in bytes.
outputid
The ID number of a window or file where the data is to be written. This
must be a user-defined windowid or fileid. See Window and file numbers
on page 1-5 for details.
Description
This macro writes the contents of a buffer to a file or window. You must define the
identity of the file with either the fopen macro (see fopen on page 3-15) or the FOPEN
command (see FOPEN on page 2-179).
Return value
unsigned long
The size of the data that is written, and is the same as size * count.
Rules
If you are writing to a file, it must be opened in write mode, for example:
fopen(100,"c:\\myfiles\\data_out.txt","w").
Example
The example on page 3-19 also shows you how to use fwrite in a macro.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
3-21
RealView Debugger Predefined Macros
See Also
The following macros provide similar or related functionality:
fclose on page 3-11
•
•
fgetc on page 3-12
•
fopen on page 3-15
•
fputc on page 3-17
•
fread on page 3-19.
The following commands provide similar or related functionality:
•
FOPEN on page 2-179
•
FPRINTF on page 2-182
•
VCLOSE on page 2-361
•
WINDOW on page 2-375.
3-22
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Predefined Macros
3.2.10
getsym
Returns a debugger symbol at a specified address.
Syntax
char *getsym (addr)
void *addr;
where:
The address for which the associated symbol is to be returned.
addr
Description
This macro returns a debugger symbol from a specified address. If no symbol exists at
the address, a null string is returned
Return value
char *
A debugger symbol.
Rules
None
Example
This example shows how to use getsym on the command line:
add char x[20]
strcpy(x,getsym(@pc))
pr x
"__main"
strcpy(x,getsym(0x8010))
pr x
""
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
3-23
RealView Debugger Predefined Macros
3.2.11
memchr
Searches for a character in memory.
Syntax
char *memchr (str1, byte_value, count)
char *str1;
char byte_value;
int count;
where:
str1
A character pointer to the memory location of the first character byte in a
string of characters contained in a file.
byte_value
A character variable used to copy the memory contents of the character
occupying a specific position in a character string.
count
An integer variable that specifies the number of characters in str that are
to be searched for the character specified by byte_value.
Description
This macro searches for a character in memory. The memchr macro locates the first
occurrence of the character byte_value, that is contained in the first count bytes of
memory area that begins with the memory location pointed to by the start variable, str1.
Return value
char *
Points to the instance of the character being searched for, called
byte_value, if one is found. If no instance of the character being searched
for is found, then a NULL pointer is returned.
Rules
For debugger variables only, a -1 value (0xFFFFFFFF) is returned when byte_value does
not occur in the memory searched on by memchr.
Example
This example shows how to use memchr:
define /R void memoryChr()
{
char buff[37];
3-24
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Predefined Macros
char *posn;
strcpy(buff,"1234567890abcdefghijklmnopqrstuvwxyz");
posn = memchr(buff,'d',20);
$printf "%s\n",posn$;
}
.
See Also
The following macros provide similar or related functionality:
•
memclr on page 3-26
•
memcpy on page 3-28
•
memset on page 3-30.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
3-25
RealView Debugger Predefined Macros
3.2.12
memclr
Clears memory contents in a specified range.
Syntax
char *memclr (str1, count)
char *str1;
int count;
where:
str1
A character pointer to the memory location of the first character byte in a
string of characters that is replaced by the NUL character.
count
A variable of integer type, used to specify the number of consecutive
bytes of memory in a character string that are to be replaced by the NUL
character.
Description
This macro replaces the specified number of characters in str1 with the NUL character
'\0' starting at the beginning of str1. If count is less than the length of str1, the macro
returns a pointer that points to the address of the character following the area that is
cleared.
Return value
char *
Points to the first character byte after the string of characters overwritten
with the NUL character. This enables continuation of the writing process
with perfect alignment of bytes for file erasure.
Rules
None
Example
This example shows how to use memclr:
define /R void memoryClr()
{
char buff[37];
char *posn;
strcpy(buff,"1234567890abcdefghijklmnopqrstuvwxyz");
posn = memclr(buff,20);
3-26
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Predefined Macros
$printf "%s\n",posn$;
}
.
See Also
The following macros provide similar or related functionality:
•
memchr on page 3-24
•
memcpy on page 3-28
•
memset on page 3-30.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
3-27
RealView Debugger Predefined Macros
3.2.13
memcpy
Copies a specified number of characters from a source memory area to a destination
memory area.
Syntax
char *memcpy (dest, src, count)
char *dest;
char *src;
int count;
where:
dest
A character pointer that specifies the starting address for the destination
memory area, to begin writing characters to.
src
A character pointer that specifies the starting address for the source
memory area, to begin copying characters from.
count
An integer variable specifying the number of characters (bytes) to be
copied, from the source location, to the destination location of memory.
Description
Copies count characters from the source memory area, pointed to by src, and writes this
character string to a destination memory area, pointed to by dest.
Return value
Points to the destination location that is one byte beyond the last byte
written to. This enables continuation of the writing process with perfect
alignment of bytes for string concatenation of memory blocks.
char*
Rules
None
Example
This example shows how to use memcpy:
define /R void memoryCpy()
{
char buff1[37];
char buff2[37];
3-28
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Predefined Macros
char *posn;
strcpy(buff1,"1234567890abcdefghijklmnopqrstuvwxyz");
posn = memcpy(buff2,buff1,20);
$printf "%s\n",buff2$;
}
.
See Also
The following macros provide similar or related functionality:
•
memchr on page 3-24
•
memclr on page 3-26
•
memset on page 3-30.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
3-29
RealView Debugger Predefined Macros
3.2.14
memset
Fills a specified area of memory with a character.
Syntax
char *memset (dest, byte_value, count)
char *dest;
char byte_value;
int count;
where:
dest
A character pointer to the memory location where the memset macro is to
write a string of repeating characters.
byte_value
A character variable used to specify the number of times that a character
is written consecutively, beginning at the *dest address.
count
An integer variable used to specify the number of times a particular
character is to be written consecutively, beginning with the byte whose
address is *dest.
Description
This macro writes a character in memory multiple times. The memset macro writes the
character byte_value into the contents of the first count bytes in memory, beginning with
the byte pointed to by dest. For example, write character 'X' consecutively, one hundred
times, beginning at address 0x8f51fff4.
Return value
char *
Points to the destination location that is one byte beyond the last byte
written to. This enables continuation of the writing process with perfect
alignment of bytes for string concatenation of memory blocks.
Rules
None
Example
This example shows how to use memset:
3-30
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Predefined Macros
define /R void memorySet()
{
char buff[37];
char *posn;
posn = memset(buff,'@',20);
$printf "%s\n",buff$;
}
.
See Also
The following macros provide similar or related functionality:
•
memchr on page 3-24
•
memclr on page 3-26
•
memcpy on page 3-28.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
3-31
RealView Debugger Predefined Macros
3.2.15
prompt_file
Displays an Open File dialog.
Note
This macro is not available in the headless debugger.
Syntax
int prompt_file(title, buff)
char *title;
char *buff;
where:
title
The text that appears in the title bar of the Open File dialog.
buff
The filename that appears in the File name text box of the dialog. Assign
an empty string to leave the File name text box blank.
Contains the chosen path and filename of the opened file when the Open
button is clicked.
Description
This macro displays an Open File dialog.
Assign an empty string to buff to leave the File name text box of the dialog blank.
Assign a filename, without a path, to buff before executing this macro, the filename
appears in the File name text box of the dialog.
When you click Open, buff contains the chosen path and filename.
Return value
One of the following:
int
0
File opened.
1
Cancel.
Rules
None
3-32
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Predefined Macros
Example
This example shows how to use prompt_file in a macro:
define /R void openFile()
{
char filename[100];
int retval;
retval = prompt_file("Open File", filename);
if (retval == 1)
$printf "Open file cancelled!\n"$;
else
retval = fopen(100,filename,"r");
if (retval < 0)
$printf "Could not open file: %s\n", filename$;
else
$printf "Opened file: %s\n", filename$;
}
.
See Also
The following macros provide similar or related functionality:
•
prompt_list on page 3-34
•
prompt_text on page 3-36
•
prompt_yesno on page 3-38
•
prompt_yesnocancel on page 3-40.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
3-33
RealView Debugger Predefined Macros
3.2.16
prompt_list
Displays a dialog containing message text, a list of choices, and Ok, Cancel and Help
buttons.
Note
This macro is not available in the headless debugger.
Syntax
int prompt_list (message, buff)
char *message;
char *buff;
where:
message
The message text that appears at the top of the dialog.
buff
Initially, the list of choices that appear for selection in the dialog,
separated by \n.
Description
This macro displays a dialog containing message text and a list of choices.
Return value
One of the following:
int
0
Cancel
n
Index number of the chosen list item. The first item in the list
has an index of 1.
Rules
None
Example
This example shows how to use prompt_list on the command line:
add char buff[15]
strcpy(buff, "one\ntwo\nthree")
ce prompt_list("Choose one:", buff)Result is: 3 0x03
3-34
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Predefined Macros
See Also
The following macros provide similar or related functionality:
prompt_file on page 3-32
•
•
prompt_text on page 3-36
•
prompt_yesno on page 3-38
•
prompt_yesnocancel on page 3-40.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
3-35
RealView Debugger Predefined Macros
3.2.17
prompt_text
Displays a dialog containing message text, and Ok and Cancel buttons.
Note
This macro is not available in the headless debugger.
Syntax
int prompt_text (message, buff)
char *message;
char *buff;
where:
message
The message text that appears at the top of the dialog.
buff
The buffer that is to contain the user response.
Description
This macro displays a dialog containing message text, and Ok and Cancel buttons. The
user response is entered into the buffer (local or target).
Return value
One of the following:
int
0
OK
1
Cancel
Rules
None
Example
This example shows how to use prompt_text in a macro:
define /R int usrPrompt()
{
char userPromptBuffer[100];
int retval;
retval = prompt_text( "Please enter text", userPromptBuffer );
if (retval == 0) {
$printf "Pressed OK\n"$;
3-36
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Predefined Macros
$printf "%s\n", userPromptBuffer$;
} else
$printf "Pressed Cancel\n"$;
return retval;
}
.
See Also
The following macros provide similar or related functionality:
•
prompt_file on page 3-32
•
prompt_list on page 3-34
•
prompt_yesno on page 3-38
•
prompt_yesnocancel on page 3-40.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
3-37
RealView Debugger Predefined Macros
3.2.18
prompt_yesno
Displays a dialog containing question text, and Yes and No buttons.
Note
This macro is not available in the headless debugger.
Syntax
int prompt_yesno (message)
char *message;
where:
message
The text that you want to appear as a question on the dialog.
Description
This macro displays a dialog containing question text and two buttons (Yes and No) for
the user reply.
Return value
One of the following:
int
0
Yes
2
No
Rules
None
Example
This example shows how to use prompt_yesno on the command line:
ce prompt_yesno("Is everything OK?")Result is: 0 0x00
See Also
The following macros provide similar or related functionality:
•
prompt_file on page 3-32
•
prompt_list on page 3-34
•
prompt_text on page 3-36
3-38
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Predefined Macros
•
ARM DUI 0175H
prompt_yesnocancel on page 3-40.
Copyright © 2002-2006 ARM Limited. All rights reserved.
3-39
RealView Debugger Predefined Macros
3.2.19
prompt_yesno_cancel
Displays a dialog containing question text, and Yes, No and Cancel buttons.
Note
This macro is not available in the headless debugger.
Syntax
int prompt_yesno_cancel (message)
char *message;
where:
message
The text that you want to appear as a question on the dialog.
Description
This macro displays a dialog containing question text and buttons (Yes, No and Cancel)
for the user reply.
Return value
One of the following:
int
0
Yes
1
Cancel
2
No
Rules
None
Example
This example shows how to use prompt_yesno_cancel on the command line:
ce prompt_yesno_cancel("Is everything OK?")Result is: 1 0x01
See Also
The following macros provide similar or related functionality:
•
prompt_file on page 3-32
•
prompt_list on page 3-34
3-40
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Predefined Macros
•
•
ARM DUI 0175H
prompt_text on page 3-36
prompt_yesno on page 3-38.
Copyright © 2002-2006 ARM Limited. All rights reserved.
3-41
RealView Debugger Predefined Macros
3.2.20
reg_str
Returns the value of a specified register.
Syntax
unsigned long reg_str (name)
char *name;
where:
The register name.
name
Description
This macro takes a register name from a string and returns the value for the register.
Return value
unsigned long
The value for the register.
Rules
You must be connected to a target.
Example
This example shows how to use reg_str on the command line:
ce reg_str("@CPSR")
Result is: 211 0xD3
3-42
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Predefined Macros
3.2.21
strcat
Concatenates two strings.
Syntax
char *strcat (dest, src)
char *dest;
char *src;
where:
dest
A character pointer, that specifies the starting address for the destination
memory area. Characters from the src string are appended to the end of
this string, starting where the NUL character previously terminated the
string.
src
A character pointer that specifies the starting address for the source
memory area, to begin copying characters from, when appending to the
end of the *dest string.
Description
This macro appends the src string to the end of the dest string, and then returns a pointer
to the dest string. This macro behaves like the strcat function in the ANSI C string
library.
Return value
char *
Points to the first byte in the dest string.
Rules
This macro does not check to see whether the second string can fit in the first array,
unless it is a debugger array. Failure to allot enough space for the first array causes
excess characters to overflow into adjacent memory locations. Consider using the
strlen macro first to confirm that there is enough length in dest, for the original dest
and src together.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
3-43
RealView Debugger Predefined Macros
Example
This example shows how to use strcat on the command line:
add char buff[15]
ce strcpy(buff,"12345")
ce strcat(buff,"67890")
printf "%s\n",buff
1234567890
See Also
The following macros provide similar or related functionality:
•
strchr on page 3-45
•
strcmp on page 3-47
•
strcpy on page 3-49
•
stricmp on page 3-51
•
strlen on page 3-53
•
strncmp on page 3-55.
3-44
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Predefined Macros
3.2.22
strchr
Locates the first occurrence of a character in a string.
Syntax
char *strchr (str1, byte_value)
char *str1;
char byte_value;
where:
str1
This is a character pointer to the memory location of the first character
byte in a string of characters.
byte_value
This is a variable of character type, used to specify the character that the
strchr macro must search for. The terminating NUL character '\0' is part of
the string, so it can be searched for.
Description
This macro locates the first occurrence of a character in a string.
Return value
char *
Points to the first memory location of the first occurrence of the character
byte_value byte. If no instance of the character being searched for is
found, then a NULL pointer is returned.
Rules
For debugger variables only, a -1 value (0xFFFFFFFF) is returned, when byte_value does
not occur in the string searched on by strchr.
Example
This example shows how to use strchr in a macro:
define /R void substr(character)
char character;
{
char *pos;
pos = strchr("This is a string",character);
$printf "position: %s\n",pos$;
}
.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
3-45
RealView Debugger Predefined Macros
See Also
The following macros provide similar or related functionality:
strcat on page 3-43
•
•
strcmp on page 3-47
•
strcpy on page 3-49
•
stricmp on page 3-51
•
strlen on page 3-53
•
strncmp on page 3-55.
3-46
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Predefined Macros
3.2.23
strcmp
Compares two strings.
Syntax
unsigned long strcmp (str1, str2)
char *str1;
char *str2;
where:
str1
Variable of type pointer to char. Specifies the location in memory of the
first byte of a character string.
str2
Variable of type pointer to char. Specifies the location in memory of the
first byte of a character string.
Description
This macro compares two strings based on the internal machine representation of the
characters.
For example, ASCII A has the value 41 in hexadecimal notation and ASCII B has the
value 42 in hexadecimal notation. Therefore, A is less than B.
This macro behaves like the strcmp function in the ANSI C string library.
Return value
int
One of the following:
<0
Indicates that the second argument string value comes after the
first argument string value in the machine collating sequences,
str1 < str2.
0
Indicates that the two strings are identical in content.
>0
Indicates that the first argument string value comes after the
second argument string value in the machine collating
sequences, str2 < str1.
Rules
•
Strings are assumed to be NULL terminated or to fit within the array boundaries.
•
Comparisons are always signed, regardless of how the string is declared.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
3-47
RealView Debugger Predefined Macros
Example
This example shows how to use strcmp on the command line:
ce strcmp("string1","string2")
Result is: 4294967295 0xFFFFFFFF
See Also
The following macros provide similar or related functionality:
•
strcat on page 3-43
•
strchr on page 3-45
•
strcpy on page 3-49
•
stricmp on page 3-51
•
strlen on page 3-53
•
strncmp on page 3-55.
3-48
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Predefined Macros
3.2.24
strcpy
Copies a source string into a destination string.
Syntax
char *strcpy (dest, src)
char *dest;
char *src;
where:
dest
A character pointer, that specifies the starting address for the destination
character string. Characters from the src string are copied to the dest
string location.
src
A character pointer that specifies the starting address for the source
character string. This string is copied to the dest character string address.
Description
This macro writes the src string directly to the dest string address beginning at the first
byte pointed to by dest. It writes until encountering a NUL character '\0', which
designates the end of the src string. It returns a pointer to the dest string.
This macro behaves like the strcpy function in the ANSI C string library.
Return value
char *
Points to the first byte in the string dest.
Rules
If the destination string is a debugger array, the macro checks the size of the array before
copying. Otherwise this macro does not check to see whether the second string can fit
in the first array. Failure to allocate enough space for the first array causes excess
characters to overflow into adjacent memory locations. Consider using the strlen
macro first to confirm that there is enough length in dest, for the src string.
Example
This example shows how to use strcpy on the command line:
add char buff[50]
ce strcpy(buff,"source string")
printf "%s\n",buff
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
3-49
RealView Debugger Predefined Macros
See Also
The following macros provide similar or related functionality:
strcat on page 3-43
•
•
strchr on page 3-45
•
strcmp on page 3-47
•
stricmp on page 3-51
•
strlen on page 3-53
•
strncmp on page 3-55.
3-50
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Predefined Macros
3.2.25
stricmp
Compares two strings without case distinction.
Syntax
int stricmp (str1, str2)
char *str1;
char *str2;
where:
str1
Variable of type pointer to char. Specifies the location in memory of the
first byte of a character string.
str2
Variable of type pointer to char. Specifies the location in memory of the
first byte of a character string.
Description
This macro performs string comparison without case distinction. The stricmp macro
compares strings in ASCII sequence, ignoring case.
Return value
int
One of the following:
<0
Indicates that the second argument string value comes after the
first argument string value in the machine collating sequences,
independent of case distinction, str1 < str2.
0
Indicates that the two strings are identical in content,
independent of case distinction.
>0
Indicates that the first argument string value comes after the
second argument string value in the machine collating
sequences, independent of case distinction, str2 < str1.
Rules
•
Strings are assumed to be NULL terminated or to fit within the array boundaries.
•
Comparisons are always signed, regardless of how the string is declared.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
3-51
RealView Debugger Predefined Macros
Example
This example shows how to use stricmp on the command line:
ce stricmp("abcDEF","ABCdef")
Result is: 0 0x00000000
See Also
The following macros provide similar or related functionality:
•
strcat on page 3-43
•
strchr on page 3-45
•
strcmp on page 3-47
•
strcpy on page 3-49
•
strlen on page 3-53
•
strncmp on page 3-55.
3-52
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Predefined Macros
3.2.26
strlen
Returns the length or the specified string.
Syntax
unsigned long strlen (str1)
char *str1;
where:
Variable of type pointer to char. Specifies the location in memory of the
first byte of a character string.
str1
Description
This macro returns the string length. The strlen macro counts the number of characters
in a string up to but not including the NUL terminating character.
This macro behaves like the strlen function in the ANSI C string library.
Return value
unsigned long
Return value is equal to the number of characters in the string pointed to
by str1, not including the terminating NUL character.
Rules
•
Strings are assumed to be NUL terminated.
•
If str1 is not properly terminated by a NUL character, the length returned is invalid.
Example
This example shows how to use strlen on the command line:
ce strlen("1234567890")
Result is: 10 0x0A
See Also
The following macros provide similar or related functionality:
•
strcat on page 3-43
•
strchr on page 3-45
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
3-53
RealView Debugger Predefined Macros
•
•
•
•
3-54
strcmp on page 3-47
strcpy on page 3-49
stricmp on page 3-51
strncmp on page 3-55.
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Predefined Macros
3.2.27
strncmp
Performs a limited comparison of two strings.
Syntax
int strncmp (str1, str2, count)
char *str1;
char *str2;
int count;
where:
str1
Variable of type pointer to char. Specifies the location in memory of the
first byte of a character string.
str2
Variable of type pointer to char. Specifies the location in memory of the
first byte of a character string.
count
Variable of integer type. Specifies the length of characters in each string
to compare, unless the NUL character is encountered in either string first.
Description
This macro performs limited comparison of two strings. The strncmp macro is used to
compare strings in ASCII sequence, except that the comparison stops after count
characters, or when the first NUL character is encountered, whichever comes first.
This macro behaves like the strncmp function in the ANSI C string library.
Return value
One of the following:
int
<0
Indicates that the second argument string value comes after the
first argument string value in the machine collating sequences,
str1 < str2.
0
Indicates that the two strings are identical in content.
>0
Indicates that the first argument string value comes after the
second argument string value in the machine collating
sequences, str2 < str1.
Rules
•
ARM DUI 0175H
Strings do not have to be NULL terminated or fit within the array boundaries
because the comparison is limited to the number of stated characters.
Copyright © 2002-2006 ARM Limited. All rights reserved.
3-55
RealView Debugger Predefined Macros
•
Less than count characters are compared if one of the strings is smaller than count
characters.
•
The comparison is always signed, regardless of how the string is declared.
Example
This example shows how to use strncmp in a macro:
define /R void checkfile(filename)
char *filename;
{
int retval;
retval = strncmp(filename, "dhrystone", 4);
if (retval == 0)
$printf "%s belongs to the Dhrystone project\n",filename$;
else
$printf "%s belongs to another project\n",filename$;
}
.
See Also
The following macros provide similar or related functionality:
•
strcat on page 3-43
•
strchr on page 3-45
•
strcmp on page 3-47
•
strcpy on page 3-49
•
stricmp on page 3-51
•
strlen on page 3-53.
3-56
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Predefined Macros
3.2.28
until
Breaks when a given expression evaluates to True.
Syntax
int until (expression)
int expression;
where:
expression
An expression that is evaluated to test if the result is nonzero.
Description
This macro causes execution to break when expression is True. The until macro
evaluates its argument, expression, to determine if it is True (nonzero) or False (zero).
This macro can only be used with the GO command (see GO on page 2-186) and the GOSTEP
command (see GOSTEP on page 2-188) to:
•
halt execution when the expression passed is True
•
continue execution when the expression passed is False.
Return value
One of the following:
int
0
Indicates that expression is False (zero).
1
Indicates that expression is True (nonzero).
Rules
Any C expression resulting in a value can be used as the argument, expression.
Example
Set temporary breakpoints at line numbers 3 and 17 in the current module, and at the
entry point to the function printf. When any of these locations are encountered by the
executing program, the debugger stops then checks the until conditional statements. If
the variable i is equal to 3 or the variable x is less than y, a break occurs. Otherwise,
program execution continues.
GO #3,#17,printf;until(i==3||x<y)
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
3-57
RealView Debugger Predefined Macros
See also
The following macros provide similar or related functionality:
when on page 3-59
•
3-58
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Predefined Macros
3.2.29
when
Breaks when an expression evaluates to True.
Syntax
int when (expression)
int expression;
where:
expression
An expression that is evaluated to test if the result is nonzero.
Description
This macro causes execution to break when expression is True. The when macro
evaluates its argument, expression, to determine if it is True (nonzero) or False (zero).
This macro is designed to be used with any breakpoint commands. When used with
these commands, program execution halts when the stated expression is True and
continues when the stated expression is False.
Note
RealView Debugger creates a conditional breakpoint, and assigns the when condition
using the ,macro:{when(expression)} qualifier. See the description of the breakpoint
commands in Chapter 2 RealView Debugger Commands for more details.
Return value
One of the following:
int
0
Indicates that expression is True (nonzero).
1
Indicates that expression is False (zero).
Rules
Any C expression resulting in a value can be used as the argument, expression.
Example
Set a breakpoint at the entry point of the routine strcpy. Each time strcpy is
encountered, the breakpoint is hit, and the macro when is executed. The macro causes the
breakpoint to be activated (program execution stops) when its argument, in this case the
byte pointed to by *str, is zero.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
3-59
RealView Debugger Predefined Macros
BREAKINSTRUCTION strcpy\@entry;when(*str == 0)
See also
The following macros provide similar or related functionality:
•
until on page 3-57
3-60
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Predefined Macros
3.2.30
word
Returns a word value at the specified address.
Syntax
unsigned short int word (addr)
void *addr;
where:
The address containing the value to be returned.
addr
Description
This macro returns a word value at the specified address. The word macro returns an
unsigned short integer value (a two byte word of memory value) for the contents of
memory pointed to by the argument addr.
Return value
unsigned short int
The two byte value located at the specified address.
Rules
The argument default type is specified by using the OPTION command (see OPTION on
page 2-224):
OPTION radix = [ decimal | hex ]
Example
To display the contents of the hexadecimal address 0x8338, enter the following on the
command line:
PRINTVALUE word(0x8338)
See also
The following macros provide similar or related functionality:
•
byte on page 3-7
•
dword on page 3-8.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
3-61
RealView Debugger Predefined Macros
3-62
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
Chapter 4
RealView Debugger Keywords
This chapter describes the available RealView® Debugger keywords. It contains the
following sections:
•
Keywords listed by function on page 4-2
•
Alphabetical keyword reference on page 4-4.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
4-1
RealView Debugger Keywords
4.1
Keywords listed by function
This section lists the keywords according to their general function:
•
Data type keywords
•
Conditional statement keywords
•
Flow control keywords on page 4-3
•
Miscellaneous keywords on page 4-3.
4.1.1
Data type keywords
Table 4-1 contains a summary of the data type keywords.
Table 4-1 Data type keywords
Description
Keyword
Character variable
char
Double floating variable
double
Floating variable
float
Integer variable
int
Long variable
long
Long long variable
long long
Short variable
short
Unsigned variable, defaults to
unsigned
unsigned int
4.1.2
Conditional statement keywords
Table 4-2 contains a summary of the conditional statement keywords.
Table 4-2 Conditional statement keywords
4-2
Description
Keyword
Simplest form of a conditional statement.
if on page 4-10
Specify an alternative statement to execute if
the if statement evaluates to False.
if-else on page 4-11
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Keywords
4.1.3
Flow control keywords
Table 4-3 contains a summary of the conditional statement keywords.
Table 4-3 Flow control keywords
4.1.4
Description
Keyword
Exits from the current loop.
break on page 4-5
Ignores the remaining statements in the
current loop and executes the next iteration
of the loop.
continue on page 4-6
Executes a given statement one or more
times until an expression evaluates to False.
do-while on page 4-7
Executes a statement a given number of
times.
for on page 4-8
Evaluates an expression and executes the
following statement or statements until the
expression evaluates to False.
while on page 4-16
Miscellaneous keywords
Table 4-4 contains a summary of other keywords.
Table 4-4 Miscellaneous keywords
Description
Keyword
Verifies that a symbol is currently active.
isalive on page 4-12
Returns the size of a data type.
sizeof on page 4-15
You can also use these keywords on the command line by prefixing them with the
CEXPRESSION command (see CEXPRESSION on page 2-101). For example:
cexpression sizeof(int)
Result is: 4 0x04
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
4-3
RealView Debugger Keywords
4.2
Alphabetical keyword reference
This section lists in alphabetical order the keywords that you can use in macros.
The following sections describe the available keywords:
•
break on page 4-5
•
continue on page 4-6
•
do-while on page 4-7
•
for on page 4-8
•
if on page 4-10
•
if-else on page 4-11
•
isalive on page 4-12
•
return on page 4-14
•
sizeof on page 4-15
•
while on page 4-16.
4-4
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Keywords
4.2.1
break
Exits the current loop immediately.
Syntax:
break;
Description
The break statement causes the innermost for, do-while, or while loop to be exited
immediately.
Return Value
None
Rules
None
Example
See the example on page 4-9 to see how to use break in a for loop.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
4-5
RealView Debugger Keywords
4.2.2
continue
Causes the next iteration of a loop to be executed, ignoring any remaining commands
in the loop.
Syntax:
continue;
Description
The continue statement causes the remainder of the for, do-while, or while loop to be
ignored and the next iteration of the loop to execute.
Return Value
None
Rules
None
Example
See the example on page 4-9 to see how to use continue in a for loop.
4-6
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Keywords
4.2.3
do-while
Executes one or more statements until an expression is False.
Syntax:
do {
statement;
[statement;]...
} while (expression);
/* execute this statement */
/* additional statements */
/* while this expression is True */
where:
expression
The expression to be evaluated at the end of each iteration of the loop.
Description
The do-while statement executes a given statement one or more times until an
expression evaluates to False.
If you have more than one statement in the do-while loop these must be enclosed in curly
braces ({}).
Return Value
None
Rules
None
Example
This example shows how to use do-while in a macro:
define /R void doloop()
{
int i;
i = 1;
do {
$printf "Iteration: %d\n", i$;
i++;
} while (i < 11);
}
.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
4-7
RealView Debugger Keywords
4.2.4
for
Executes one or more statements a given number of times.
Syntax:
for
(expression_1;
expression_2;
expression_3)
/* evaluate only once */
/* evaluate before each iteration */
/* evaluate after each iteration */
statement;
/* execute this statement */
/* while expression_2 is True */
/* additional statements */
{
[statement;]...
}
Description
The for statement is useful for executing a statement a given number of times. It
evaluates expression_1 and then evaluates expression_2 to see if it is True, that is
nonzero, or False, that is zero. If expression_2 evaluates to True, all statements are
executed once.
Next expression_3 is evaluated, and expression_2 is evaluated again to see if it is True
or False. If expression_2 is True, all statements are executed again and the cycle
continues. If expression_2 is False, all statements are bypassed and execution continues
at the next statement outside the for loop.
Where you have more than one statement in the for loop these must be enclosed by
curly braces ({}).
The term expression_1 can be used to initialize a variable to be used in the loop. It is
evaluated once, before the first iteration of the loop. The term expression_2 determines
whether to execute or terminate the loop and is evaluated before each iteration. If the
term expression_2 evaluates to True, that is nonzero, the loop is executed. If
expression_2 is False, that is zero, the loop is terminated. The term expression_3 can be
used to increment a loop counter, and is evaluated after each iteration.
Return Value
None
Rules
None
4-8
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Keywords
Example
This example shows how to use the for statement in a macro:
define /R void forloop()
{
int i;
for (i=0; i<11; i++) {
if (i > 10) {
$printf "
Done!\n"$;
break;
} else if (i==5) {
$printf "
Halfway there...\n"$;
continue;
}
$printf "Iteration: %d\n", i$;
}
}
.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
4-9
RealView Debugger Keywords
4.2.5
if
The simplest form of a macro conditional statement.
Syntax:
if (expression)
{
statement;
[statement;]...
}
/* If this expression is True */
/* execute this statement */
/* additional statements */
Description
The if statement is the simplest form of a macro conditional statement. It is always
followed by an expression enclosed in parentheses. If the expression evaluates to zero,
that is False, the statement following the expression is bypassed. If the expression
evaluates to a value other than zero, that is True, the statement following the expression
is executed. If you have more than one statement in the if statement these must be
enclosed in curly braces ({}).
Return Value
None
Rules
None
Example
This example shows how to use if in a macro:
if (n==0)
strcpy(number,"zero");
4-10
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Keywords
4.2.6
if-else
Provides a way to specify an alternative statement to execute if the if statement
evaluates to False.
Syntax:
if (expression)
{
statement_1;
[statement;]...
}else
{
statement_2;
[statement;]...
}
/* If expression is True */
/* execute statement_1 */
/* and these additional statements */
/* If expression is False */
/* execute statement_2 */
/* and these additional statements */
Description
The if-else statement provides a way to specify an alternative statement to execute if
the if statement evaluates to False. If the expression evaluates to True, that is nonzero,
statement_1 and any following statements are executed, but statement_2 and any
following statements are not executed. If the expression evaluates to False, that is zero,
statement_2 and any following statements are executed, but statement_1 and any
following statements are not executed. If you have more than one statement in the if
section or in the else section these must be enclosed in curly braces ({}).
Return Value
None
Rules
None
Example
This example shows how to use if-else in a macro:
if (n==0)
strcpy(number,"zero");
else
strcpy(number,"nonzero");
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
4-11
RealView Debugger Keywords
4.2.7
isalive
Tests the status of the specified symbol.
Syntax
int isalive (symbol_name)
symbol_name;
where:
symbol_name
The variable name used for the symbol that isalive tests the scope of.
Description
The isalive keyword tests whether the specified symbol is in scope. It checks the status
of the argument symbol_name, to see whether that variable is in scope, and whether it can
be referenced. The value returned by isalive specifies whether the variable does not
exist, is not in scope, is in scope inside the current active function, or is an external
(global) variable, or a static variable on the stack but out of scope.
Return value
One of the following values
int
-1
Symbol does not exist.
0
Symbol not currently active. It cannot be referenced because it
is out of scope.
1
Symbol currently active. It is part of the local procedure, also
called an automatic variable.
2
Available on the stack. The symbol is not part of local
procedure, and is also called an external (active), global
(active), or static automatic variable (inactive, but containing
stored memory contents).
Rules
The argument of isalive must be a variable that has no return value. The argument
cannot be a function.
Example
You can use the following syntax for the isalive keyword when checking the status of
a variable used in its argument.
4-12
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Keywords
CEXPRESSION isalive(xxx)
/* Returns -1 if the symbol xxx does not exist. */
ADD var1
CE isalive(var1)
/* Returns 1 since var1 is defined and active. */
Note
The keywords CEXPRESSION and CE are equivalent.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
4-13
RealView Debugger Keywords
4.2.8
return
Returns a value from a macro.
Syntax:
return [(]expression[)];
Description
The return statement is used to return a value from a macro. The expression is
evaluated, and the resulting value is returned to the caller. If a breakpoint macro returns
a value of True, that is nonzero, program execution continues. If it returns a value of
False, that is zero, program execution is halted. If a macro never returns a value, the
macro_type must be declared as void when it is defined.
Return Value
None
Rules
None
Example
This example shows how to use return in a macro:
define /R int value(x)
int x;
{
if (x > 0)
return (x);
else
return(-1);
}
.
4-14
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Keywords
4.2.9
sizeof
Returns the data type size in bytes.
Syntax
int sizeof(type_name)
where:
type_name
The data type or variable for which the data size is to be determined.
Description
The sizeof keyword returns the data type size in bytes of a given variable or data type.
Return value
The size of the data type in bytes.
int
Rules
None
Example
This example shows how to use sizeof in a macro:
define /R void saveData()
{
char buffer[37];
int retval;
strcpy(buffer,"One \nTwo \nThree\nFour \nFive \nSix
fopen(100,"c:\\myfiles\\data.txt","w");
retval = fwrite(buffer, 1, sizeof(buffer)-1, 100);
$printf "%d bytes written\n",retval$;
$vclose 100$;
}
.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
\n");
4-15
RealView Debugger Keywords
4.2.10
while
Evaluates an expression and executes one or more statements until the expression
evaluates to False.
Syntax:
while (expression)
{
statement;
[statement;]...
}
/* while this expression is True */
/* execute this statement */
/* and these additional statements */
where:
expression
The expression to be evaluated at the start of each loop.
Description
The while statement evaluates an expression and executes the following statement or
statements until the expression evaluates to False.
The while statement must be followed by an expression in parentheses. As long as the
expression evaluates to True, all following statements are repeatedly executed. When
the expression evaluates to False, all statements are bypassed and execution continues
at the next statement outside the while loop. If you have more than one statement in the
loop these must be enclosed in curly braces ({}).
Return Value
None
Rules
None
Example
This example shows how to use while in a macro:
define /R void whileloop()
{
int x;
x = 1;
while (1) {
$printf "Iteration: %d\n", x$;
4-16
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
RealView Debugger Keywords
if (x > 10) {
$printf "Done!\n"$;
break;
} else if (x==5) {
$printf "Halfway there...\n"$;
}
x++;
}
}
.
ARM DUI 0175H
Copyright © 2002-2006 ARM Limited. All rights reserved.
4-17
RealView Debugger Keywords
4-18
Copyright © 2002-2006 ARM Limited. All rights reserved.
ARM DUI 0175H
Was this manual useful for you? yes no
Thank you for your participation!

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project

Download PDF

advertisement