3 COMMAND LANGUAGE

This chapter contains the following sections:

Introduction
CrossView Pro Expressions
Constants
Variables
Formatting Expressions
Operators
Special Expressions
Conditional Evaluation
Functions
Case Sensitivity

3.1 Introduction

The syntax and semantics of CrossView Pro's command language is discussed here. This language is mainly used to enter textual commands in the command edit field of the Command Window. The mouse and menus allow you to access most actions without knowing the command language, although the command language is more powerful. The command language is also used when evaluating expressions and in commands associated with assertions, breakpoints and macros. For information about specific CrossView Pro commands, refer to Chapter 13, Command Reference.

3.2 CrossView Pro Expressions

There are several methods that you can use to input an expression into CrossView Pro:

It is possible to display both monitored and unmonitored expressions in the Data Window. Monitored expressions are updated after every halt in execution. Unmonitored expressions are just one-shot inspections of the expressions value. Refer to section 4.6 , CrossView Pro Windows for a detailed description of the Data Window.

To evaluate a simple expression:

Double click on a variable in the Source window. The result of the expression appears in the data window. Alternatively, depending on the preferences you set in the Data Display Setup dialog, the expression appears in the Evaluate Expression dialog. Click the Add Watch or Add Show button to display the result of the expression in the Data Window. Click the Evaluate button to display the result of the expression in the output field of the Evaluate Expression dialog.

To evaluate a complex expression:

From the Data menu, select Evaluate Expression... and type in any C expression in the Evaluate Expression dialog box. Optionally select a display format. Click the Evaluate button.

Type the expression into the command edit field of the Command Window followed by a return or click the Execute button.

Expressions can be any length in most windows and dialog boxes; CrossView Pro provides a horizontal scroll bar if an expression exceeds the visible length of the entry field.

In CrossView Pro, C expressions may consist of a combination of numeric constants, character constants, strings, variables, register names, C operators, function names, function calls, typecasts and some CrossView Pro-specific symbols. Each of these is described in the next sections.

Evaluation Precision

CrossView Pro evaluates expressions using the same data types and associated precision as used by the target architecture when evaluating the same expression.

3.3 Constants

CrossView Pro, like C, supports integer, floating point and character constants.

Integers

Integers are numbers without decimal points. For example, CrossView Pro will treat the following as integers:

The following number, however, are not treated as integers:

Negative integers, if they appear as the first item on a line, must have parentheses around the number:

This is to prevent confusion with CrossView Pro's own - (minus sign) command.

In addition, CrossView Pro supports standard C octal, hexadecimal and binary notation. You can specify a hexadecimal constant using a leading 0x or a trailing H (or h). The first character must be a decimal digit, so it may be necessary to prefix a hexadecimal number with the '0' character. The hexadecimal representation for decimal 16 is:

For the hexadecimal digits a through f you can use either upper or lower case. The following are all correct hexadecimal representations for decimal 43981:

You can specify a binary constant using a trailing B or Y (or b or y). The following are all binary representations for decimal 5:

You can specify an octal constant using a leading '0'. The octal representation for 8 decimal is:

You can use an L to indicate a long integer constant. For example, CrossView Pro will recognize the following as long integers:

CrossView Pro uses the same ANSI C integral type promotion scheme as the C compiler.

Floating Point

A floating point number requires a decimal point and at least one digit before the decimal point. The following are valid examples of floating point numbers:

Exponential notation, such as 1.234e01, is not allowed. The following are not valid floating point numbers:

As with integers, bracket a negative number with parentheses:

Expressions combining integers and floating point numbers will evaluate to floating point values:

Character

Character constants are single characters or special constants that follow the C syntax for special characters. Examples of valid character constants include:

Character constants must be a single byte and are delimited by '' (single quotation marks). For instance:

Remember not to confuse character constants with strings. A character constant is a single byte, in this example, the ASCII value of m.

Strings

Strings are delimited by " " (double quotation marks). In C all strings end with a null (zero) character. Strings are referenced by pointer, not by value. This is standard C practice. In CrossView Pro, you may assign a string literal to a variable which is of type char* (pointer to character):

CrossView Pro supports the standard C character constants shown below:

Code ASCII Hex Function
\b BS 08 Backspace
\f FF 0C Formfeed
\n NL (LF) 0A Newline
\r CR 0D Carriage return
\t HT 09 Horizontal tab
\\ \ 5C Back slash
\? ? 3F Question mark
\' ' 27 Single quote
\" " 22 Double quote
\ooo 3-digit octal number
\xhhh hexadecimal number

Table 3-1: C character codes

Trigraph sequences are not supported.

3.4 Variables

CrossView Pro lets you use variables in the C expressions you type. You may reference two classes of variables: variables defined in the source code and special variables.

Variables defined in your source code fall into two categories: local variables and global variables.

Storage Classes

Variables may be of any C storage class. The size of each class is target dependent. Consult the R8C C Compiler, Assembler, Linker User's Guide for specific sizes.

You may cast variables from one class to another:

Local Variables

You define local variables within a function; their values are maintained on the stack or in registers. When the program exits the function, you lose local variable values. This means that you can only reference local variables when their function is active on the stack.

Local variables of type static retain values between calls. Therefore, you can reference static variables beyond their functions, but only if their function is active on the stack.

CrossView Pro knows whether the compiler has allocated a local variable on the stack or directly in a register and whether the register is currently on the stack. The compiler may move some local variables into registers when optimizing code.

If a part of your source code looks like this:

and you stopped the program after the assignment to x, and set x to another value, this may not prevent the second statement from setting y to 5 due to "constant folding" optimizations performed by the compiler.

Global Variables

Global variables are defined outside every function and are not local to any function. Global (non-static) variables are accessible at any point during program execution, after the system startup code has been executed.

Global variables can be defined static in a module. These variables can only be accessed when a function in this module is active on the stack, or when that file is in the Source Window using the e command.

Specifying Variables in C expressions

The following table specifies how CrossView Pro treats different variables in C expressions. The left column is the variable's syntax in the expression, the right column is the CrossView Pro semantics.

Variable Syntax CrossView Pro Behavior
variable CrossView Pro performs a scope search starting at the current viewing position and proceeding outwards. The debugger first checks locals, local statics and parameters, followed by statics and globals explicitly declared in the current file. Finally, globals in other files are checked.
function#variable CrossView Pro searches for the first instance of function. If found, the debugger uses the frame's address to perform a scope search for variable. Variables are available only if the specified function is active. That is, the stack frame for that function can be found on the run-time stack.
number#variable The frame at stack level number is used by the debugger for the scope search. The current function is always at stack level 0. This format is very useful if you are debugging a recursive function and there are multiple instances of a variable on the stack.
:variable CrossView Pro searches for a global variable named either variable or _variable, in that order.
$variable CrossView Pro searches the list of special variables for $variable.

Table 3-2: Variables in C expressions

Variables and Scoping Rules

A variable is in scope at any point in the program if it is visible to the C source code. For instance, if you have a local variable initval declared in main(), and then step (or move the viewing position) into factorial, initval will be out of scope. You can still find the value of initval by typing:

In this case CrossView Pro will search the stack for the function main(), then look outwards from that function for the first occurrence of initval in scope and report its value. Note that main() must be active, that is, program execution must have passed through main() and not yet returned, in order for initval to have a value.

You can also use the Browse... button in the Expression Evaluation dialog box. This dialog box appears when you click the New Expression button in the toolbar or select Evaluate Expression... from the Data menu.

Special Variables

CrossView Pro maintains a set of variables that are separate from those defined in your program being debugged. These special variables reside in memory on the host computer, not on the target system. They contain the values of the target processor's registers, information about the debugger's status, and user-defined values. Special variables are case insensitive. Use the opt command to display and set these variables (without using the '$'-sign).

The following is a list of the reserved special variables for CrossView Pro:

Reserved Variable Description
$ARG(n) Contains the value of the nth int-sized argument of the current function. Allows access to arguments of variable argument list functions without knowing the name of the argument.
$FILE Contains the name of the file that holds the current viewing position.
$IN(function) Contains the value 1 if the current pc is inside the specified function, otherwise 0.
$LINE Contains the line number of the current viewing position. This variable is often used in assertions to monitor program flow.
$PROCEDURE Contains the name of the procedure at the current viewing position.
$ASMHEX Contains a string "ON" or "OFF". The value "ON" specifies that the disassembled code as displayed in the assembly window will display hexadecimal opcodes. Default is "OFF".
$AUTOSRC Contains a string "ON" or "OFF". The value "ON" specifies that the debugger will automatically switch between the source window and the assembly window display depending on the presence of symbolic debug information at the current location. The value "OFF" prevents the automatic window switching. Default is "OFF".
$CPU Contains a string indicating the current CPU type.
$FP Contains the value of the frame pointer.
$MIXEDASM Contains a string "ON" or "OFF". The value "ON" specifies that the disassembled code as displayed in the assembly window will be intermixed with the corresponding source lines. The value "OFF" suppresses this intermixing. Default is "ON".
$MORE Contains a string "ON" or "OFF". The value "ON" specifies that the more output pager is enabled. The value "OFF" disables the more output pager. Default is "ON".
$PC Contains the value of the program counter.
$PIPELINE Contains a string "ON" or "OFF". The value "ON" specifies that the pipeline should be displayed in the assembly window. Default is "OFF".
$register Contains the value of the specified register.
$SP Contains the value of the stack pointer.
$SYMBOLS Contains a string "ON" or "OFF" indicating if local symbols and symbolic addresses (e.g. main:56+0x4) or absolute addresses are present in disassembly. Default is "ON".
$SRCLINENRS Contains a string "ON" or "OFF". The value "ON" specifies that line numbers should be printed in the source window. The value "OFF" suppresses printing of line numbers. Default is "OFF".
$SRCMERGELIMIT Contains the value for the source merge limit in the assembly window, the number of source lines to be intermixed in the assembly window. Value 0 indicates that there is no limit. Default is 0.
$USE_MDF_FILE Contains a string "ON" or "OFF". The value "ON" specifies that an application specific memory definition file must be processed before a new file is loaded and/or downloaded to the target. The value "OFF" suppresses processing of a memory definition file. Default is "OFF".

Table 3-3: Reserved special variables

Registers

For CrossView Pro, a fixed set of registers is always available. You can add additional R8C derivative specific SFRs in a .sfr file. See the C Compiler, Assembler, Linker User's Guide for more information.

You can configure which (and in which order) registers must appear in the register window in the Register Window Setup dialog (Settings | Register Window Setup...).

It is possible to request the address of an SFR by using the address operator &.

In addition to the standard register special variables, CrossView Pro supplies the special variables: $sp (the stack pointer), $pc (the program counter) and $fp (the current frame pointer).

The values of Reserved special variables cannot be changed interactively (i.e., on the CrossView Pro command line).

User-defined Special Variables

During a debugging session, you may need some new variables for your own debugging purposes, such as counting the number of times you encounter a breakpoint. CrossView Pro allows you to create and use your own special variables for this purpose. CrossView Pro does not allocate space for these variables in target memory; it maintains them on the host computer.

The names of these variables, which must begin with a $ (dollar sign), are defined when they are first used. For instance:

defines a variable named $count of type int with a value of 5. Special variables are of the same type as the last expression they were assigned. For example:

then:

creates a special variable $name of type (char *). The second statement creates a special symbol $name and assigns it the value of 12 of type int.

Special variables are just like any other variables, except you cannot meaningfully take the address of them. CrossView Pro allows as a default 26 user-defined special variables. You can change this limit with the -s option at startup, or by selecting the Options... menu item from the File menu and choosing the Initialization tab.

See the startup options in Chapter 4, Using CrossView Pro.

3.5 Formatting Expressions

By default, CrossView Pro displays the value of an expression using the appropriate format for the type of expression. CrossView Pro follows several simple rules for displaying variables:

You can determine in which format a variable is displayed. Once the format has been selected, however, you must enter values or change values in the appropriate format. When editing is finished, the debugger interprets all values in terms of the currently selected formats.

You may, however, tell CrossView Pro to display an expression in a particular format other than the default format. The format code follows the variable, in one of two ways:

The simplest method of specifying display formats is from the Evaluate Expression dialog box. To access this dialog box:

In the Command Window, you can use several format codes shown in the next table to specify the variable display. The format codes can be entered as:

to display the variable in format format, or:

to display the variable's address in format format.

The structure of the formatting code is:

Count is the number of times to apply the format style style. Size indicates the number of bytes to be formatted. Both count and size must be numbers, although you may use c (char), s (short), i (int), and l (long) as shorthand for size. Legal integer format sizes are 1, 2, and 4; legal float format sizes are 4 and 8.

Be sure not to confuse CrossView Pro format codes with C character codes, e.g. \a. CrossView Pro uses a forward slash / not a backward slash \.

Style Description
a Print the specified number of characters of the character array; any positive size is OK. Use the expression's value as the address of the first byte.
c Print a character; any positive size is OK; default size is sizeof(char).
D Print in decimal; needs NO size specifier; size is sizeof(long).
d Print in decimal; can have a size specifier; default size is sizeof(expression).
E Print in "e" floating point notation; needs NO size specifier; default size is sizeof(double).
e Print in "e" floating point notation; the size specifier can be sizeof(float) or sizeof(double); default size is sizeof(expression).
F Print in "f" floating point notation; needs NO size specifier; default size is sizeof(double).
f Print in "f" floating point notation; the size specifier can be sizeof(float) or sizeof(double); default size is sizeof(expression).
G Print in "g" floating point notation; needs NO size specifier; default size is sizeof(double).
g Print in "g" floating point notation; the size specifier can be sizeof(float) or sizeof(double); default size is sizeof(expression).
I Print the function, source line, and disassembled instruction at the address.
i Print the disassembled instruction at address.
n Print in the "natural" format, based on type; use it for printing variables that have the same name as an CrossView Pro command.
O Print in octal; needs NO size specifier; size is sizeof(long).
o Print in octal; can have a size specifier; default size is sizeof(expression).
P Print the name of the function at the address.
p Print the names of the file, function, and source line at the address.
s Print the specified number of characters of the string, using the expression's value as the address of a pointer to the first byte. Equivalent to *expression/a. If no size is specified the entire string, pointed to by expression, is printed (till nil-character).
t Display the type of the indicated variable or function.
U Print in unsigned decimal; needs NO size specifier; size is sizeof(long).
u Print in unsigned decimal; can have a size specifier; default size is sizeof(expression).
X Print in hexadecimal; needs NO size specifier; size is sizeof(long).
x Print in hexadecimal; can have a size specifier; default size is sizeof(expression).

Table 3-4: Format style codes

For example, typing:

displays four, hexadecimal two-byte memory locations starting at the address of initval.

The following piece of C-code can be accessed in CrossView Pro using the string format codes:

With format codes, you may view the contents of memory addresses on the screen. For instance, to dump the contents of an absolute memory address range, you must think of the address being a pointer. To show (dump) the memory contents you use the C language indirection operator '*'. Example:

This command displays in hexadecimal two long words at memory location 0x4000 and beyond. Instead of using the size specifier in the display format, you can force the address to be a pointer to unsigned long by casting the value:

To view the first four elements of the array table from the demo.c program, type:

This command displays in decimal the first four 2-byte values beginning at the address of the array table.

3.6 Operators

Standard C Operators

CrossView Pro supports the standard C operators in the ANSI defined order of precedence. The order of precedence determines which operators execute first.

The semicolon character (;) separates commands on the same line. In this way, you may type multiple commands on a single line. Comments delimited by /* and */ are allowed; CrossView Pro simply ignores them.

Order of Precedence
(in descending order)
() [] -> .
! ~ ++ -- + - * & (type) sizeof
* // %
+ -
<< >>
< <= > >=
== !=
&
^
|
&&
||
?: = += -= *= /= %= &= ^= |= <<= >>=

Table 3-5: Order of precedence of standard C operators

The *, - and + operators appear twice since they exist as both unary and binary operators and unary operators have higher precedence than binary.

Division is represented by // (two slashes) not / (one slash). This is to avoid confusion with CrossView Pro's format specifier syntax.

Using Addresses

To specify an address, you may use the & operator. To determine the address of initval, type:

If you try to use the & operator on a local variable in a register, CrossView Pro issues an error message and tells you which register holds the variable.

3.7 Special Expressions

String Commands

Whenever CrossView Pro encounters an expression consisting solely of a string by itself, it simply echoes the string. For example:

Use this technique to place helpful debugging messages on breakpoints. For example, setting the following breakpoint:

this cause CrossView Pro to echo the message now in for loop, to display the value of sum in the Command Window, and to continue when line 60 is encountered. You can also enter this breakpoint and the associated commands via the Breakpoints dialog box, which you can open by selecting the Breakpoints... menu item from the Breakpoints menu.

The Period Operand

As a shorthand, CrossView Pro supports a special operand, period `.', that stands for the value of the last expression CrossView Pro calculated. For instance, in the following example, the period in the second command equals the value 11, which is the result of the previous expression:

The period operand assumes the same size and format implied by the specifier used to view the previous item. Thus if you look at a long as a char, a subsequent `.' is considered to be one byte. Use this technique to alter specified pieces of a larger data item, such as the second highest byte of a long, without altering the rest of the long. The period operand may be used in any context valid for other variables.

`.' is the name of a location. When you use it, it is dereferenced like any other name. If you want the address of something that is 30 bytes farther on in memory, do not type .+30 as this takes the contents of dot and adds 30 to it. Type instead &.+30 which adds 30 to the address of the period operand.

3.8 Conditional Evaluation

CrossView Pro supports the if construct. Use this construct in breakpoints and assertions to alter program flow conditionally. For example, if you reset the following breakpoint:

CrossView Pro compares the value of sum with 5931 when the program stops at line 60. If sum is less than or equal to 5931, CrossView Pro continues. Otherwise, CrossView Pro displays the value of sum with 5931 when the program stops at line 60.

You can also use the exp1 ? exp2 : exp3 C ternary operator for conditional expressions. For example:

assigns the value 1 to myvar.

3.9 Functions

In CrossView Pro expressions, you can include functions defined in the program's code.

Command line function calls are not supported for the R8C .

You can call functions through the Call a Function dialog box. Note that only the results of the function call are shown. You cannot enter expressions in this field. If you want to use the results of the function call in an expression, then type the expression into the Evaluate Expression dialog box or type in the command into the Command Window (described in the keyboard method below).

The Command Window receives the results of the function call.

Type in the expression containing a function call directly into the Command Window.

To execute a function on the target type the function name and the arguments as you would do in your C program. For example,

3.10 Case Sensitivity

The absolute file supplies the case sensitivity information for variable names. It is initially case sensitive for the C language. You may toggle case sensitivity by:

From the Edit menu, select Search String... to view the Search String dialog box. This dialog contains the Case Sensitive check box.

Typing the (capital) Z command in the Command Window.


Copyright © 2003 Altium BV