RealView Debugger Command Line Reference Guide: 1.6.6. Reserved symbols

1.6.6. 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.

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:

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 any arguments and local 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 example, `@R0`. Use this symbol to reference register `r0`.
`@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 locate to the function in the source or disassembly view, 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.
`@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.
`@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.

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	`@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`
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:

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);
}
.

Connect to RealView ARMulator^® ISS (RVISS), for example:
```
connect "@ARM7TDMI@RVISS"
```

Load the Dhrystone image from the main examples directory:

load/r 'main_examples_directory\dhrystone\Debug\dhrystone.axf'

Include the file you created in step 1 to define the macro. If this is in the directory c:\myscripts, then enter:
```
include 'c:\myscripts\symbols.inc'
```
Run the macro, with an outputID of 50:
```
macro rsvdSymbols(50)
```
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:
```
breakinstruction,macro:{rsvdSymbols(50)} main\@entry
```

Run the Dhrystone application (see 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\rvds\examples\...\...\...\...\main\dhrystone\
dhry_1.c
line_range: 91..91
module:     DHRY_1
procedure:  main

Reload the Dhrystone application and clear the previous breakpoint:
```
reload
clearbreak
```
Set the breakpoint again, but specify the module and line:
```
breakinstruction,macro:{rsvdSymbols(50)} \DHRY_1\#149:1
```
Run the Dhrystone application:
```
go
```
The listing shown in step 7 is displayed, but the line_range has changed to 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 view, and they are common to all ARM architectures. You can also perform operations on these registers.

Table 1.5. Common 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_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.
`@CPSR_V`	References the Overflow flag of the CPSR NZCV flags.
`@CPSR_Z`	References the Zero flag of the CPSR NZCV flags.
`@R8_bank` `@R9_bank` `@R10_bank` `@R11_bank` `@R12_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`.
`@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 (see the equivalent CPSR symbols for details):
	`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 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.

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` `@SPSR_bank_regs`	References the SPSR registers in a register `bank`. `regs` is one of the following (see the equivalent CPSR symbols for details):
	`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.

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 view, and depend on your target connection. For example, the Debug tab is available when connecting to a target through an ARM DSTREAM™ or RealView ICE debug unit.
Board-specific registers are displayed in other tabs of the Registers view.

Note

You can also perform operations on the internal debugger variables and board-specific 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 your default settings directory identified by the RVDEBUG_SHADOW_DIR_ETC environment variable.

To find the name of a board-specific (memory mapped) 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 (memory mapped) register from the related board/chip definition file:

Find the file in your default settings 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 dialog box in the GUI to make any changes.
Search for lines containing Register.regname, where regname is the name of the register, for example Register.G_SC_PCI.

Copyright © 2002-2011 ARM. All rights reserved.	ARM DUI 0175N
Non-Confidential	ID052111
PDF version

1.6.6. Reserved symbols

Displaying a list of currently defined symbols

Referencing reserved symbols

Printing reserved symbols

Example

Symbols for referencing the common processor core registers

Note

Symbols for referencing the extended CPSR and SPSR registers

Note

Symbols for referencing internal variables and board-specific registers

Note

Note

See also