RealView® Developer Kit Command Line Reference Guide 1.6.5. Reserved symbols

1.6.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 for a list of reserved symbols and their descriptions.

This section contains:

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 PRINTSYMBOLS):

printsymbols *

This command lists:

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 the symbols defined for those macros are listed.

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 processor core registers Symbols for referencing internal variables and board-specific registers.
`@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
`@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.
`@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.
`@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 FPRINTF
PRINTF on PRINTF
PRINTSYMBOLS on PRINTSYMBOLS
PRINTVALUE on PRINTVALUE.

Also, see Reserved symbols.

Table 1.4 shows the format specifiers to use when printing reserved symbols.

Table 1.4. Format specifiers for printing reserved symbols

Information to print	Symbol to use	Format specifier
Register contents, see: Symbols for referencing processor core registers Symbols for referencing internal variables and board-specific registers.	`@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`
Line range of the source code identified by the PC	`@line_range`	`%s`
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:

Create an include file, for example symbols.inc, containing the following command and macro definition (see Macro language):

add int windowOpened=0
define /R int rsvdSymbols(outputID)
int outputID;
{
  if (windowOpened = 0)
    if (outputID > 49) {
      $vopen outputID$;
      windowOpened=1;
    }
  $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$;
  // return 0 to stop at the breakpoint
  // return 1 to continue after the breakpoint
  return (0);
}
.

Connect to RVI-ME (see CONNECT on CONNECT)
Load the Dhrystone image from the main examples directory (see LOAD on LOAD):
```
load/r ’main_examples_directory\dhrystone\Debug\dhrystone.axf’
```
Include the file you created in step 1 to define the macro (see INCLUDE on INCLUDE). If this is in the directory c:\myscripts, then enter:
```
include ’c:\myscripts\symbols.inc’
```
Run the macro, with an outputID of 20, the Standard I/O window (see Window and file numbers):
```
macro rsvdSymbols(20)
```
The following details are displayed:
```
root:       @dhrystone
hlpc:        0
code line:   <invalid line>
instruction: $00008000 EAFFFFFF  B        $L0x8004 $      ~<S0x8004>
file:       ../../angel/startup.s
line_range:
module:     STARTUP_S
procedure:  __main
```
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.
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 BREAKINSTRUCTION):
```
breakinstruction,macro:{rsvdSymbols(20)} main\@entry
```

Run the Dhrystone application (see GO on GO):

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

Reload the Dhrystone application and clear the previous breakpoint (see RELOAD on RELOAD and CLEARBREAK on CLEARBREAK):
```
reload
clear
```
Set the breakpoint again, but specify the module and line:
```
breakinstruction,macro:{rsvdSymbols(20)} \DHRY_1\#91:1
```
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 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 Register pane. You can also perform operations on these registers, see Operations on symbols and registers.

Table 1.5. Processor core register symbols

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_FLG`	References the NZCV flags of the CPSR.
`@CPSR_F`	References the FIQ register of the CPSR.
`@CPSR_I`	References the IRQ register of the CPSR.
`@CPSR_T`	References the STATE register of the CPSR.
`@CPSR_MODE`	References the MODE register of the CPSR.
`@R8_bank` `@R9_bank` `@R10_bank` `@R11_bank` `@R12_bank`	References register `R8`, `R9`, `R10`, `R11`, and `R12` in register banks `bank`. These are used only in register banks `USR` and `FIQ`. For example, `@R9_USR`.
`@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` `@SPSR_bank_regs`	References the SPSR registers in a register `bank`. `regs` is one of the following:
	`FLG` `F` `I` `T` `MODE`	`NZCV` flags `FIQ` register `IRQ` register `STATE` register `MODE` register.
	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 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 Register 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 Register pane.

Note

You can also perform operations on the internal debugger variables and board-specific registers, see Operations on symbols and registers.

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 register or internal debugger variable using the RealView Debugger GUI:

Select the required tab, for example, Debug.
Right-click on the register or variable that you want to reference, for example, semihost_enabled.
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 register from the related board/chip definition file:

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.
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 RealView Developer Kit v2.2 Debugger User Guide.
Search for the line containing Register_Window.boardname, where boardname is the name of the board, for example Register_Window.AP. The lines following this entry contain the register names.

Copyright © 2005, 2006 ARM Limited. All rights reserved.	ARM DUI 0284C
Non-Confidential
PDF version