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

SymbolDescription
@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_outputThe last line of output that was generated by the HOST command.
@line_rangeContains the line range of the source code associated with the PC.
@moduleIndicates the name of the current module as determined by the location of the PC.
@procedureIndicates the name of the current function as determined by the location of the PC.
@fileIndicates the name of the current file as determined by the location of the PC.
@rootIndicates 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 printSymbol to useFormat 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:

  1. 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);
    }
    .
    
  2. Connect to RealView ARMulator® ISS (RVISS), for example:

    connect "@ARM7TDMI@RVISS"
    
  3. Load the Dhrystone image from the main examples directory:

    load/r 'main_examples_directory\dhrystone\Debug\dhrystone.axf'
    
  4. 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'
    
  5. 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.

  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:

    breakinstruction,macro:{rsvdSymbols(50)} main\@entry
    
  7. 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
    
  8. Reload the Dhrystone application and clear the previous breakpoint:

    reload
    clearbreak
    
  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 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 symbolDescription
@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 symbolDescriptionEarliest 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:

  1. Select the required tab, for example, Debug.

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

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

  3. Search for lines containing Register.regname, where regname is the name of the register, for example Register.G_SC_PCI.

See also

Copyright © 2002-2011 ARM. All rights reserved.ARM DUI 0175N
Non-ConfidentialID052111