COBHAM GRMON3 User Manual

GRMON3

A debug monitor for LEON-based computer systems and SOC designs based on the GRLIB IP library

2019 User's Manual The most important thing we build is trust

GRMON3 User's Manual

GRMON3-UM 1 www.cobham.com/gaisler June 2019, Version 3.1.0

1. Introduction ............................................................................................................................. 5

1.1. Overview ...................................................................................................................... 5

1.2. Supported platforms and system requirements ..................................................................... 5

1.3. Obtaining GRMON ........................................................................................................ 5

1.4. Installation .................................................................................................................... 5

1.5. License ......................................................................................................................... 6

1.6. GRMON Evaluation version ............................................................................................ 6

1.7. Problem reports .............................................................................................................. 6

2. Debugging concept ................................................................................................................... 7

2.1. Overview ...................................................................................................................... 7

2.2. Target initialization ......................................................................................................... 7

2.2.1. LEON2 target initialization .................................................................................... 9

2.2.2. Configuration file target initialization ...................................................................... 9

2.3. Memory register reset values ............................................................................................ 9

3. Operation ............................................................................................................................... 10

3.1. Overview .................................................................................................................... 10

3.2. Starting GRMON ......................................................................................................... 10

3.2.1. Debug link options ............................................................................................. 10

3.2.2. Debug driver options .......................................................................................... 11

3.2.3. General options .................................................................................................. 11

3.3. GRMON command-line interface (CLI) ............................................................................ 12

3.4. Common debug operations ............................................................................................. 13

3.4.1. Examining the hardware configuration ................................................................... 13

3.4.2. Uploading application and data to target memory ..................................................... 14

3.4.3. Running applications .......................................................................................... 15

3.4.4. Inserting breakpoints and watchpoints .................................................................... 16

3.4.5. Displaying processor registers .............................................................................. 16

3.4.6. Backtracing function calls .................................................................................... 16

3.4.7. Displaying memory contents ................................................................................ 17

3.4.8. Instruction disassembly ....................................................................................... 18

3.4.9. Using the trace buffer ......................................................................................... 18

3.4.10. Profiling .......................................................................................................... 20

3.4.11. Attaching to a target system without initialization ................................................... 20

3.4.12. Multi-processor support ..................................................................................... 21

3.4.13. Stack and entry point ........................................................................................ 21

3.4.14. Memory Management Unit (MMU) support .......................................................... 21

3.4.15. CPU cache support ........................................................................................... 22

3.5. Tcl integration .............................................................................................................. 22

3.5.1. Shells ............................................................................................................... 22

3.5.2. Commands ........................................................................................................ 22

3.5.3. API .................................................................................................................. 23

3.6. Symbolic debug information ........................................................................................... 23

3.6.1. Multi-processor symbolic debug information ........................................................... 24

3.7. GDB interface .............................................................................................................. 24

3.7.1. Connecting GDB to GRMON ............................................................................... 24

3.7.2. Executing GRMON commands from GDB ............................................................. 25

3.7.3. Running applications from GDB ........................................................................... 25

3.7.4. Running SMP applications from GDB ................................................................... 26

3.7.5. Running AMP applications from GDB ................................................................... 26

3.7.6. GDB Thread support .......................................................................................... 27

3.7.7. Virtual memory ................................................................................................. 29

3.7.8. Specific GDB optimization .................................................................................. 31

3.7.9. GRMON GUI considerations ............................................................................... 31

3.7.10. Limitations of GDB interface ............................................................................. 31

3.8. Thread support ............................................................................................................. 31

GRMON3-UM June 2019, Version 3.1.0

2 www.cobham.com/gaisler

3.8.1. GRMON thread options ...................................................................................... 32

3.8.2. GRMON thread commands .................................................................................. 32

3.9. Forwarding application console I/O .................................................................................. 33

3.10. EDAC protection ........................................................................................................ 34

3.10.1. Using EDAC protected memory .......................................................................... 34

3.10.2. LEON3-FT error injection .................................................................................. 34

3.11. FLASH programming .................................................................................................. 35

3.11.1. CFI compatible Flash PROM .............................................................................. 35

3.11.2. SPI memory device ........................................................................................... 36

3.12. Automated operation ................................................................................................... 37

3.12.1. Tcl commanding during CPU execution ................................................................ 37

3.12.2. Communication channel between target and monitor ............................................... 37

3.12.3. Test suite driver ............................................................................................... 37

4. Graphical user interface ........................................................................................................... 39

4.1. Overview .................................................................................................................... 39

4.2. Starting GRMON GUI .................................................................................................. 39

4.3. Connect to target .......................................................................................................... 40

4.3.1. Debug link ........................................................................................................ 40

4.3.2. Options ............................................................................................................ 41

4.3.3. Argument contribution ........................................................................................ 41

4.3.4. Configurations ................................................................................................... 41

4.3.5. Connect ............................................................................................................ 41

4.4. Launch configurations ................................................................................................... 41

4.4.1. Target image setup ............................................................................................. 42

4.4.2. Launch properties ............................................................................................... 43

4.5. Views ......................................................................................................................... 44

4.5.1. CPU Registers View ........................................................................................... 44

4.5.2. IO Registers View .............................................................................................. 45

4.5.3. System Information View .................................................................................... 47

4.5.4. Terminals View ................................................................................................. 47

4.5.5. Memory View ................................................................................................... 48

4.5.6. Disassembly View .............................................................................................. 49

4.5.7. Messages View .................................................................................................. 50

4.6. Target communication ................................................................................................... 51

4.6.1. Memory view update .......................................................................................... 51

4.7. C/C++ level debugging .................................................................................................. 51

4.8. Limitations .................................................................................................................. 51

5. Debug link ............................................................................................................................. 52

5.1. UART debug link ......................................................................................................... 52

5.2. Ethernet debug link ....................................................................................................... 53

5.3. JTAG debug link .......................................................................................................... 53

5.3.1. Xilinx parallel cable III/IV ................................................................................... 55

5.3.2. Xilinx Platform USB cable .................................................................................. 55

5.3.3. Altera USB Blaster or Byte Blaster ....................................................................... 57

5.3.4. FTDI FT4232/FT2232 ......................................................................................... 58

5.3.5. Amontec JTAGkey ............................................................................................. 59

5.3.6. Actel FlashPro 3/3x/4/5 ....................................................................................... 59

5.3.7. Digilent HS1 ..................................................................................................... 59

5.4. USB debug link ........................................................................................................... 59

5.5. GRESB debug link ....................................................................................................... 61

5.5.1. AGGA4 SpaceWire debug link ............................................................................. 61

5.6. User defined debug link ................................................................................................. 62

5.6.1. API .................................................................................................................. 62

6. Debug drivers ......................................................................................................................... 64

6.1. AMBA AHB trace buffer driver ...................................................................................... 64

6.2. Clock gating ................................................................................................................ 64

6.2.1. Switches ........................................................................................................... 64

6.3. DSU Debug drivers ....................................................................................................... 64

GRMON3-UM June 2019, Version 3.1.0

3 www.cobham.com/gaisler

6.3.1. Switches ........................................................................................................... 64

6.3.2. Commands ........................................................................................................ 65

6.3.3. Tcl variables ..................................................................................................... 66

6.4. Ethernet controller ........................................................................................................ 66

6.4.1. Commands ........................................................................................................ 66

6.5. GRPWM core .............................................................................................................. 66

6.6. USB Host Controller ..................................................................................................... 67

6.6.1. Switches ........................................................................................................... 67

6.6.2. Commands ........................................................................................................ 67

6.7. I2C ............................................................................................................................. 67

6.8. I/O Memory Management Unit ....................................................................................... 67

6.9. Multi-processor interrupt controller .................................................................................. 68

6.10. L2-Cache Controller .................................................................................................... 68

6.10.1. Switches ......................................................................................................... 68

6.11. Statistics Unit ............................................................................................................. 69

6.12. LEON2 support .......................................................................................................... 71

6.12.1. Switches ......................................................................................................... 71

6.13. On-chip logic analyzer driver ........................................................................................ 71

6.14. Memory controllers ..................................................................................................... 72

6.14.1. Switches ......................................................................................................... 73

6.14.2. Commands ...................................................................................................... 74

6.15. Memory scrubber ........................................................................................................ 74

6.16. MIL-STD-1553B Interface ............................................................................................ 75

6.17. PCI ........................................................................................................................... 76

6.17.1. PCI Trace ....................................................................................................... 80

6.18. SPI ........................................................................................................................... 80

6.19. SpaceWire router ........................................................................................................ 80

6.20. SVGA frame buffer ..................................................................................................... 81

7. Support ................................................................................................................................. 82

A. Command index ..................................................................................................................... 83

B. Command syntax .................................................................................................................... 86

C. Tcl API ............................................................................................................................... 225

D. Fixed target configuration file format ....................................................................................... 234

E. License key installation .......................................................................................................... 236

F. Appending environment variables ............................................................................................ 237

G. Compatibility ....................................................................................................................... 238

G.1. Compatibility notes for GRMON2 ................................................................................. 238

G.2. Compatibility notes for GRMON1 ................................................................................. 238

GRMON3-UM June 2019, Version 3.1.0

4 www.cobham.com/gaisler

1. Introduction

1.1. Overview

GRMON is a general debug monitor for the LEON processor, and for SOC designs based on the GRLIB IP library. GRMON includes the following functions:

• Read/write access to all system registers and memory

• Built-in disassembler and trace buffer management

• Downloading and execution of LEON applications

• Breakpoint and watchpoint management

• Remote connection to GNU debugger (GDB)

• Support for USB, JTAG, UART, Ethernet and SpaceWire debug links

• Tcl interface (scripts, procedures, variables, loops etc.)

• Graphical user interface

1.2. Supported platforms and system requirements

GRMON is currently provided for platforms: Linux (GLIBC >2.10), Windows 7 and Windows 10. To run the GUI Java 8 is required. Both 32-bit and 64-bit versions are supported.

The available debug communication links for each platform vary and they may have additional third-party dependencies that have additional system requirements. See Chapter 5, Debug link for more information.

1.3. Obtaining GRMON

The primary site for GRMON is Cobham Gaisler website [http://www.gaisler.com/], where the latest version of GRMON can be ordered and evaluation versions downloaded.

1.4. Installation

Follow these steps to install GRMON. Detailed information can be found futher down.

1. Extract the archive

2. Install the Sentinel LDK Runtime (GRMON Pro version only)

3. Optionally install third-party drivers for the debug interfaces.

4. Optionally setup the path for shared libraries (Linux only)

5. Optionally add GRMON to the environment variable PATH

To install GRMON, extract the archive anywhere on the host computer. The archive contains a directory for each OS that GRMON supports. Each OS-folder contains additional directories as described in the list below. The 32bit and 64-bit version of each OS can be installed in parallel by extracting the archive to the same location.

grmon-pro-3.0.XX/<OS>/bin<BITS> grmon-pro-3.0.XX/<OS>/lib<BITS> grmon-pro-3.0.XX/<OS>/share

The professional version use a Sentinel LDK license key. See Appendix E, License key installation for installation of the Sentinel LDK runtime.

Some debug interfaces requires installation of third-party drivers, see Chapter 5, Debug link for more information.

The bin<BITS> directory contains the executable. For convenience it is recommended to add the bin<BITS> directory of the host OS to the environment variable PATH. See Appendix F, Appending environment variables for instructions on how to append environment variables.

To be able to run the GUI, it is required to install the same bitness version of GRMON as the Java installation. It is still possible to run both bit-versions of GRMON with the GUI. I.e to run GRMON 32-bit with a Java 64bit, install both bit-versions of GRMON.

GRMON3-UM June 2019, Version 3.1.0

5 www.cobham.com/gaisler

The lib<BITS> directory contains some additional libraries that GRMON requires. On the Windows platform the lib<BITS> directory is not available. On the Linux platform, if GRMON fails to start because of some missing libraries that are located in this directory, then add this path to the environment variable LD_LIBRARY_PATH or add it the ld.so.cache (see man pages about ldconfig for more information).

GRMON must find the share directory to work properly. GRMON will try to automatically detect the location of the folder. A warning will be printed when starting GRMON if it fails to find the share folder. If it fails to automatically detect the folder, then the environment variable GRMON_SHARE can be set to point the share/ grmon folder. For example on Windows it could be set to c:\opt\grmon-pro\windows\share\grmon or on Linux it could be set to /opt/grmon-pro/linux/share/grmon.

1.5. License

The GRMON license file can be found in the share folder of the installation. For example on Windows it can be found in c:\opt\grmon-pro\windows\share\grmon or on Linux it could be found in /opt/gr- mon-pro/linux/share/grmon.

1.6. GRMON Evaluation version

The evaluation version of GRMON can be downloaded from Cobham Gaisler website [http://www.gaisler.com/]. The evaluation version may be used during a period of 21 days without purchasing a license. After this period, any commercial use of GRMON is not permitted without a valid license. The following features are not available in the evaluation version:

• GUI

• Support for LEON2, LEON3-FT, LEON4

• FT memory controllers

• SpaceWire drivers

• Custom JTAG configuration

• Profiling

• TCL API (drivers, init scripts, hooks, I/O forward to TCL channel etc)

1.7. Problem reports

Please send bug reports or comments to support@gaisler.com. Customers with a valid support agreement may send questions to support@gaisler.com. Include a GRMON log

when sending questions, please. A log can be obtained by starting GRMON with the command line switch -log filename.

The leon_sparc community at Yahoo may also be a source to find solutions to problems.

GRMON3-UM June 2019, Version 3.1.0

6 www.cobham.com/gaisler

2. Debugging concept

2.1. Overview

The GRMON debug monitor is intended to debug system-on-chip (SOC) designs based on the LEON processor. The monitor connects to a dedicated debug interface on the target hardware, through which it can perform read and write cycles on the on-chip bus (AHB). The debug interface can be of various types: the LEON3/4 processor supports debugging over a serial UART, 32-bit PCI, JTAG, Ethernet and SpaceWire (using the GRESB Ethernet to SpaceWire bridge) debug interfaces. On the target system, all debug interfaces are realized as AHB masters with the Debug protocol implemented in hardware. There is thus no software support necessary to debug a LEON system, and a target system does in fact not even need to have a processor present.

Figure 2.1. GRMON concept overview

GRMON can operate in two modes: command-line mode and GDB mode. In command-line mode, GRMON commands are entered manually through a terminal window. In GDB mode, GRMON acts as a GDB gateway and translates the GDB extended-remote protocol to debug commands on the target system.

GRMON is implemented using three functional layers: command layer, debug driver layer, and debug interface layer. The command layer takes input from the user and parses it in a Tcl Shell. It is also possible to start a GDB server service, which has its own shell, that takes input from GDB. Each shell has it own set of commands and variables. Many commands depends on drivers and will fail if the core is note present in the target system. More information about Tcl integration can be found in the Section 3.5, “Tcl integration”.

The debug driver layer implements drivers that probes and initializes the cores. GRMON will scan the target system at start-up and detect which IP cores are present. The drivers may also provides information to the commands.

The debug interface layer implements the debug link protocol for each supported debug interface. Which interface to use for a debug session is specified through command line options during the start of GRMON. Only interfaces based on JTAG supports 8-/16-bit accesses, all other interfaces access subwords using read-modify-write. 32-bit accesses are supported by all interfaces. More information can be found in Chapter 5, Debug link.

2.2. Target initialization

When GRMON first connects to the target system, it scans the system to detect which IP cores are present. This is done by reading the plug and play information which is normally located at address 0xfffff000 on the AHB bus. A

GRMON3-UM June 2019, Version 3.1.0

7 www.cobham.com/gaisler

debug driver for each recognized IP core is then initialized, and performs a core-specific initialization sequence if required. For a memory controller, the initialization sequence would typically consist of a memory probe operation to detect the amount of attached RAM. For a UART, it could consist of initializing the baud rate generator and flushing the FIFOs. After the initialization is complete, the system configuration is printed:

GRMON3 LEON debug monitor v3.0.0 32-bit professional version

GRLIB build version: 4111 Detected frequency: 40 MHz

Component Vendor LEON3 SPARC V8 Processor Cobham Gaisler AHB Debug UART Cobham Gaisler JTAG Debug Link Cobham Gaisler GRSPW2 SpaceWire Serial Link Cobham Gaisler LEON2 Memory Controller European Space Agency AHB/APB Bridge Cobham Gaisler LEON3 Debug Support Unit Cobham Gaisler Generic UART Cobham Gaisler Multi-processor Interrupt Ctrl. Cobham Gaisler Modular Timer Unit Cobham Gaisler General Purpose I/O port Cobham Gaisler

Use command 'info sys' to print a detailed report of attached cores

grmon3>

More detailed system information can be printed using the ‘info sys’ command as listed below. The detailed system view also provides information about address mapping, interrupt allocation and IP core configuration. Information about which AMBA AHB and APB buses a core is connected to can be seen by adding the -v option. GRMON assigns a unique name to all cores, the core name is printed to the left. See Appendix C, Tcl API for information about Tcl variables and device names.

grmon3> info sys cpu0 Cobham Gaisler LEON3 SPARC V8 Processor AHB Master 0 ahbuart0 Cobham Gaisler AHB Debug UART AHB Master 1 APB: 80000700 - 80000800 Baudrate 115200, AHB frequency 40000000.00 ahbjtag0 Cobham Gaisler JTAG Debug Link AHB Master 2 grspw0 Cobham Gaisler GRSPW2 SpaceWire Serial Link AHB Master 3 APB: 80000A00 - 80000B00 IRQ: 10 Number of ports: 1 mctrl0 European Space Agency LEON2 Memory Controller AHB: 00000000 - 20000000 AHB: 20000000 - 40000000 AHB: 40000000 - 80000000 APB: 80000000 - 80000100 8-bit prom @ 0x00000000 32-bit sdram: 1 * 64 Mbyte @ 0x40000000 col 9, cas 2, ref 7.8 us apbmst0 Cobham Gaisler AHB/APB Bridge AHB: 80000000 - 80100000 dsu0 Cobham Gaisler LEON3 Debug Support Unit AHB: 90000000 - A0000000 AHB trace: 128 lines, 32-bit bus CPU0: win 8, hwbp 2, itrace 128, V8 mul/div, srmmu, lddel 1 stack pointer 0x43fffff0 icache 2 * 4096 kB, 32 B/line lru dcache 1 * 4096 kB, 16 B/line uart0 Cobham Gaisler Generic UART APB: 80000100 - 80000200 IRQ: 2 Baudrate 38461 irqmp0 Cobham Gaisler Multi-processor Interrupt Ctrl. APB: 80000200 - 80000300 gptimer0 Cobham Gaisler Modular Timer Unit APB: 80000300 - 80000400 IRQ: 8 8-bit scalar, 2 * 32-bit timers, divisor 40

GRMON3-UM June 2019, Version 3.1.0

8 www.cobham.com/gaisler

grgpio0 Cobham Gaisler General Purpose I/O port APB: 80000800 - 80000900

2.2.1. LEON2 target initialization

The plug and play information was introduced in the LEON3 processor (GRLIB), and is not available for LEON2 systems. LEON2 is supported by starting GRMON with the -sys leon2 switch or one of the switches that correspond to a known LEON2 device, see Section 6.12, “LEON2 support”.

A LEON2 system has a fixed set of IP cores and address mapping. GRMON will use an internal plug and play table that describes this configuration. The plug and play table used for LEON2 is fixed, and no automatic detection of present cores is attempted. Only those cores that need to be initialized by GRMON are included in the table, so the listing might not correspond to the actual target. It is however possible to load a custom configuration file that describes the target system configuration using see Section 2.2.2, “Configuration file target initialization”

2.2.2. Configuration file target initialization

It is possible to provide GRMON with a configuration file that describes a static configuration by starting GRMON with the switch -cfg filename.

The format of the plug and play configuration file is described in section Appendix D, Fixed target configuration file format. It can be used for both LEON3 and LEON2 systems. An example configuration file is also supplied with the GRMON professional distribution in share/src/cfg/leon3.xml.

2.3. Memory register reset values

To ensure that the memory registers has sane values, GRMON will reset the registers when commands that access the memories are issued, for example run, load commands and similar commands. To modify the reset values, use the commands listed in Section 6.14.2, “Commands”.

GRMON3-UM June 2019, Version 3.1.0

9 www.cobham.com/gaisler

3. Operation

This chapter describes how GRMON can be controlled by the user in a terminal based interactive debug session and how it can be automated with scripts for batch execution. The first sections describe and exemplifies typical operations for interactive use. The later sections describe automation concepts. Most interactive commands are applicable also for automated use.

GRMON graphical user interface is described in Chapter 4, Graphical user interface.

3.1. Overview

An interactive GRMON debug session typically consists of the following steps:

1. Starting GRMON and attaching to the target system

2. Examining the hardware configuration

3. Uploading application program

4. Setup debugging, for example insert breakpoints and watchpoints

5. Executing the application

6. Debugging the application and examining the CPU and hardware state

Step 2 though 6 is performed using the GRMON terminal interface or by attaching GDB and use the standard GDB interface. The GDB section describes how GRMON specific commands are accessed from GDB.

The following sections will give an overview how the various steps are performed.

3.2. Starting GRMON

On a Linux host, GRMON is started by giving the grmon command together with command line options in a terminal window. It can run either the GUI or a commandline interface depending on if a debug link option is provided or not.

On Windows hosts, there are two executable provided. The file grmon.exe is intended to be started in a Windows command prompt (cmd.exe). It can run either the GUI or a commandline interface depending on if a debug link option is provided or not. The executable grmon-gui.exe will always spawn a gui.

Command line options are grouped by function as indicated below.

• The debug link options: setting up a connection to GRLIB target

• General options: debug session behavior options

• Debug driver options: configure the hardware, skip core auto-probing etc.

NOTE: If any debug-link option is given to grmon or grmon.exe, then the GRMON command line interface will be started.

If no debug-link option is given to grmon or grmon.exe, then the GRMON graphical user interface will be started. For more information, see Chapter 4, Graphical user interface.

Below is an example of GRMON connecting to a GR712 evaluation board using the FTDI USB serial interface, tunneling the UART output of APBUART0 to GRMON and specifying three RAM wait states on read and write:

$ grmon -ftdi -u -ramws 3

To connect to a target using the AHBUART debug link, the following example can be used:

$ grmon -uart -u

The -uart option uses the first UART of the host (ttyS0 or COM1) with a baud rate of 115200 baud by default.

3.2.1. Debug link options

GRMON connects to a GRLIB target using one debug link interface, the command line options selects which interface the PC uses to connect to the target and optionally how the debug link is configured. All options are described in Chapter 5, Debug link.

GRMON3-UM June 2019, Version 3.1.0

10 www.cobham.com/gaisler

3.2.2. Debug driver options

The debug drivers provide an interface to view and access AMBA devices during debugging and they offer device specific ways to configure the hardware when connecting and before running the executable. Drivers usually auto-probe their devices for optimal configuration values, however sometimes it is useful to override the auto-probed values. Some options affects multiple drivers. The debug driver options are described in Chapter 6, Debug drivers.

3.2.3. General options

The general options are mostly target independent options configuring the behavior of GRMON. Some of them affects how the target system is accessed both during connection and during the whole debugging session. All general options are described below.

grmon [options]

Options:

-abaud baudrate Set baud-rate for all UARTs in the system, (except the debug-link UART). By default, 38400 baud is used.

-ambamb [maxbuses] Enable auto-detection of AHBCTRL_MB system and (optionally) specifies the maximum number of buses in the system if an argument is given. The optional argument to -ambamb is decoded as below:

0, 1: No Multi-bus (MB) (max one bus)

2..3: Limit MB support to 2 or 3 AMBA PnP buses 4 or no argument: Selects Full MB support

-c filename Run the commands in the batch file at start-up.

-cfg filename Load fixed PnP configuration from a xml-file.

-echo Echo all the commands in the batch file at start-up. Has no effect unless -c is also set.

-edac

Enable EDAC operation in memory controllers that support it.

-freq sysclk Overrides the detected system frequency. The frequency is specified in MHz.

-gdb [port] Listen for GDB connection directly at start-up. Optionally specify the port number for GDB communications. Default port number is 2222.

-gui

Start the GRMON graphical user interface. This option must be combined with an option which specifies the debug-link to use. See Chapter 4, Graphical user interface for more information.

-ioarea address Specify the location of the I/O area. (Default is 0xfff00000).

-log filename Log session to the specified file. If the file already exists the new session is appended. This should be used when requesting support.

-ni

Read plug n' play and detect all system device, but don't do any target initialization. See Section 3.4.11, “Attaching to a target system without initialization” for more information.

-nopnp

Disable the plug n' play scanning. GRMON won't detect any hardware and any hardware dependent functionality won't work.

-u [device] Put UART 1 in FIFO debug mode if hardware supports it, else put it in loop-back mode. Debug mode will enable both reading and writing to the UART from the monitor console. Loop-back mode will only enable reading. See Section 3.9, “Forwarding application console I/O”. The optional device parameter is used to select a specific UART to be put in debug mode. The device parameter is an index starting with 0 for the first UART and then increasing with one in the order they are found in the bus scan. If the device parameter is not used the first UART is selected.

GRMON3-UM June 2019, Version 3.1.0

11 www.cobham.com/gaisler

-udm [device] Put UART 1 in FIFO debug mode if hardware supports it. Debug mode will enable both reading and writing to the UART from the monitor console. See Section 3.9, “Forwarding application console I/O”. The optional device parameter is used to select a specific UART to be put in debug mode. The device parameter is an index starting with 0 for the first UART and then increasing with one in the order they are found in the bus scan. If the device parameter is not used the first UART is selected.

-ulb [device] Put UART 1 in loop-back mode. Loop-back mode will only enable reading from the UART to the monitor console. See Section 3.9, “Forwarding application console I/O”. The optional device parameter is used to select a specific UART to be put in debug mode. The device parameter is an index starting with 0 for the first UART and then increasing with one in the order they are found in the bus scan. If the device parameter is not used the first UART is selected.

-ucmd filename Load script specified by filename into all shells, including the system shell.

-udrv filename Load script specified by filename into system shell.

3.3. GRMON command-line interface (CLI)

The GRMON3 command-line interface features a Tcl 8.6 interpreter which will interpret all entered commands substituting variables etc. before GRMON is actually called. Variables exported by GRMON can also be used to access internal states and hardware registers without going through commands. The GRMON Tcl interface is described in Section 3.5, “Tcl integration”.

GRMON dynamically loads libreadline.so if available on your host system, and uses the readline library to enter and edit commands. Short forms of the commands are allowed, e.g lo, loa, or load, are all interpreted as load. Tab completion is available for commands, Tcl variables, text-symbols, file names, etc. If libreadline.so is not found, the standard input/output routines are used instead (no history, poor editing capabilities and no tabcompletion).

The commands can be separated in to three categories:

• Tcl internal commands and reserved key words

• GRMON built-in commands always available regardless of target

• GRMON commands accessing debug drivers

Tcl internal and GRMON built-in commands are available regardless of target hardware present whereas debug driver commands may only be present on supported systems. The Tcl and driver commands are described in Section 3.5, “Tcl integration” and Chapter 6, Debug drivers respectively. In Table 3.1 is a summary of all GRMON built-in commands. For the full list of commands, see Appendix A, Command index.

Table 3.1. BUILT-IN commands

amem Asynchronous bus read batch Execute batch script bdump Dump memory to a file bload Load a binary file disassemble Disassemble memory dump Dump memory to a file dwarf print or lookup dwarf information eeload Load a file into an EEPROM execsh Run commands in the execution shell exit Exit GRMON gdb Controll the builtin GDB remote server gui Control the graphical user interface help Print all commands or detailed help for a specific command

GRMON3-UM June 2019, Version 3.1.0

12 www.cobham.com/gaisler

info Show information load Load a file or print filenames of uploaded files memb AMBA bus 8-bit memory read access, list a range of addresses memh AMBA bus 16-bit memory read access, list a range of addresses mem AMBA bus 32-bit memory read access, list a range of addresses nolog Suppress stdout of a command quit Quit the GRMON console reset Reset drivers rtg4fddr Print initialization sequence rtg4serdes Print initialization sequence sf2mddr Print initialization sequence sf2serdes Print initialization sequence shell Execute shell process silent Suppress stdout of a command symbols Load, print or lookup symbols usrsh Run commands in threaded user shell verify Verify that a file has been uploaded correctly wash Clear or set memory areas wmemb AMBA bus 8-bit memory write access wmemh AMBA bus 16-bit memory write access wmems Write a string to an AMBA bus memory address wmem AMBA bus 32-bit memory write access

3.4. Common debug operations

This section describes and gives some examples of how GRMON is typically used, the full command reference can be found in Appendix A, Command index.

3.4.1. Examining the hardware configuration

When connecting for the first time it is essential to verify that GRMON has auto-detected all devices and their configuration correctly. At start-up GRMON will print the cores and the frequency detected. From the command line one can examine the system by executing info sys as below:

grmon3> info sys cpu0 Cobham Gaisler LEON3-FT SPARC V8 Processor AHB Master 0 cpu1 Cobham Gaisler LEON3-FT SPARC V8 Processor AHB Master 1 greth0 Cobham Gaisler GR Ethernet MAC AHB Master 3 APB: 80000E00 - 80000F00 IRQ: 14 grspw0 Cobham Gaisler GRSPW2 SpaceWire Serial Link AHB Master 5 APB: 80100800 - 80100900 IRQ: 22 Number of ports: 1 grspw1 Cobham Gaisler GRSPW2 SpaceWire Serial Link AHB Master 6 APB: 80100900 - 80100A00 IRQ: 23 Number of ports: 1 mctrl0 Cobham Gaisler Memory controller with EDAC AHB: 00000000 - 20000000 AHB: 20000000 - 40000000 AHB: 40000000 - 80000000 APB: 80000000 - 80000100 8-bit prom @ 0x00000000 32-bit static ram: 1 * 8192 kbyte @ 0x40000000

GRMON3-UM June 2019, Version 3.1.0

13 www.cobham.com/gaisler

32-bit sdram: 2 * 128 Mbyte @ 0x60000000 col 10, cas 2, ref 7.8 us apbmst0 Cobham Gaisler AHB/APB Bridge AHB: 80000000 - 80100000 dsu0 Cobham Gaisler LEON3 Debug Support Unit AHB: 90000000 - A0000000 AHB trace: 256 lines, 32-bit bus CPU0: win 8, hwbp 2, itrace 256, V8 mul/div, srmmu, lddel 1, GRFPU stack pointer 0x407ffff0 icache 4 * 4096 kB, 32 B/line lru dcache 4 * 4096 kB, 16 B/line lru CPU1: win 8, hwbp 2, itrace 256, V8 mul/div, srmmu, lddel 1, GRFPU stack pointer 0x407ffff0 icache 4 * 4096 kB, 32 B/line lru dcache 4 * 4096 kB, 16 B/line lru uart0 Cobham Gaisler Generic UART APB: 80000100 - 80000200 IRQ: 2 Baudrate 38461, FIFO debug mode irqmp0 Cobham Gaisler Multi-processor Interrupt Ctrl. APB: 80000200 - 80000300 EIRQ: 12 gptimer0 Cobham Gaisler Modular Timer Unit APB: 80000300 - 80000400 IRQ: 8 16-bit scalar, 4 * 32-bit timers, divisor 80 grgpio0 Cobham Gaisler General Purpose I/O port APB: 80000900 - 80000A00 uart1 Cobham Gaisler Generic UART APB: 80100100 - 80100200 IRQ: 17 Baudrate 38461 ...

The memory section for example tells us that GRMON are using the correct amount of memory and memory type. The parameters can be tweaked by passing memory driver specific options on start-up, see Section 3.2, “Starting GRMON”. The current memory settings can be viewed in detail by listing the registers with info reg or by accessing the registers by the Tcl variables exported by GRMON:

grmon3> info sys ... mctrl0 Cobham Gaisler Memory controller with EDAC AHB: 00000000 - 20000000 AHB: 20000000 - 40000000 AHB: 40000000 - 80000000 APB: 80000000 - 80000100 8-bit prom @ 0x00000000 32-bit static ram: 1 * 8192 kbyte @ 0x40000000 32-bit sdram: 2 * 128 Mbyte @ 0x60000000 col 10, cas 2, ref 7.8 us ... grmon3> info reg ... Memory controller with EDAC 0x80000000 Memory config register 1 0x1003c0ff 0x80000004 Memory config register 2 0x9ac05463 0x80000008 Memory config register 3 0x0826e000 ... grmon3> puts [format 0x%08x $mctrl0:: [TAB-COMPLETION] mctrl0::mcfg1 mctrl0::mcfg2 mctrl0::mcfg3 mctrl0::pnp:: mctrl0::mcfg1:: mctrl0::mcfg2:: mctrl0::mcfg3:: grmon3> puts [format 0x%08x $mctrl0::mcfg1] 0x0003c0ff

grmon3> puts [format 0x%08x $mctrl0::mcfg2 :: [TAB-COMPLETION] mctrl0::mcfg2::d64 mctrl0::mcfg2::sdramcmd mctrl0::mcfg2::rambanksz mctrl0::mcfg2::sdramcolsz mctrl0::mcfg2::ramrws mctrl0::mcfg2::sdramrf mctrl0::mcfg2::ramwidth mctrl0::mcfg2::sdramtcas mctrl0::mcfg2::ramwws mctrl0::mcfg2::sdramtrfc mctrl0::mcfg2::rbrdy mctrl0::mcfg2::sdramtrp mctrl0::mcfg2::rmw mctrl0::mcfg2::se mctrl0::mcfg2::sdpb mctrl0::mcfg2::si mctrl0::mcfg2::sdrambanksz grmon3> puts [format %x $mctrl0::mcfg2::ramwidth] 2

3.4.2. Uploading application and data to target memory

A LEON software application can be uploaded to the target system memory using the load command:

GRMON3-UM June 2019, Version 3.1.0

14 www.cobham.com/gaisler

grmon3> load v8/stanford.exe 40000000 .text 54.8kB / 54.8kB [===============>] 100% 4000DB30 .data 2.9kB / 2.9kB [===============>] 100% Total size: 57.66kB (786.00kbit/s) Entry point 0x40000000 Image /home/daniel/examples/v8/stanford.exe loaded

The supported file formats are SPARC ELF-32, ELF-64 (MSB truncated to 32-bit addresses), srecord and a.out binaries. Each section is loaded to its link address. The program entry point of the file is used to set the %PC, %NPC when the application is later started with run. It is also possible to load binary data by specifying file and target address using the bload command.

One can use the verify command to make sure that the file has been loaded correctly to memory as below. Any discrepancies will be reported in the GRMON console.

grmon3> verify v8/stanford.exe 40000000 .text 54.8kB / 54.8kB [===============>] 100% 4000DB30 .data 2.9kB / 2.9kB [===============>] 100% Total size: 57.66kB (726.74kbit/s) Entry point 0x40000000 Image of /home/daniel/examples/v8/stanford.exe verified without errors

NOTE: On-going DMA can be turned off to avoid that hardware overwrites the loaded image by issuing the reset command prior to load. This is important after the CPU has been executing using DMA in for example Ethernet network traffic.

3.4.3. Running applications

After the application has been uploaded to the target with load the run command can be used to start execution. The entry-point taken from the ELF-file during loading will serve as the starting address, the first instruction executed. The run command issues a driver reset, however it may be necessary to perform a reset prior to loading the image to avoid that DMA overwrites the image. See the reset command for details. Applications already located in FLASH can be started by specifying an absolute address. The cont command resumes execution after a temporary stop, e.g. a breakpoint hit. go also affects the CPU execution, the difference compared to run is that the target device hardware is not initialized before starting execution.

grmon3> reset grmon3> load v8/stanford.exe 40000000 .text 54.8kB / 54.8kB [===============>] 100% 4000DB30 .data 2.9kB / 2.9kB [===============>] 100% Total size: 57.66kB (786.00kbit/s) Entry point 0x40000000 Image /home/daniel/examples/v8/stanford.exe loaded

grmon3> run Starting Perm Towers Queens Intmm Mm Puzzle Quick Bubble Tree FFT 34 67 33 117 1117 367 50 50 250 1133

Nonfloating point composite is 144

Floating point composite is 973

CPU 0: Program exited normally. CPU 1: Power down mode

The output from the application normally appears on the LEON UARTs and thus not in the GRMON console. However, if GRMON is started with the -u switch, the UART is put into debug mode and the output is tunneled over the debug-link and finally printed on the console by GRMON. See Section 3.9, “Forwarding application console I/O”. Note that older hardware (GRLIB 1.0.17-b2710 and older) has only partial support for -u, it will not work when the APBUART software driver uses interrupt driven I/O, thus Linux and vxWorks are not supported on older hardware. Instead, a terminal emulator should be connected to UART 1 of the target system.

Since the application changes (at least) the .data segment during run-time the application must be reloaded before it can be executed again. If the application uses the MMU (e.g. Linux) or installs data exception handlers (e.g. eCos), GRMON should be started with -nb to avoid going into break mode on a page-fault or data exception. Likewise, when a software debugger is running on the target (e.g. GDB natively in Linux user-space or WindRiver Workbench debugging a task) soft breakpoints ("TA 0x01" instruction) will result in traps that the OS will handle

GRMON3-UM

15 www.cobham.com/gaisler

June 2019, Version 3.1.0

and tell the native debugger. To prevent GRMON from interpreting it as its own breakpoints and stop the CPU one must use the -nswb switch.

3.4.4. Inserting breakpoints and watchpoints

All breakpoints are inserted with the bp command. The subcommand (soft, hard, watch, bus, data, delete) given to bp determine which type of breakpoint is inserted, if no subcommand is given bp defaults to a software breakpoint.

Instruction breakpoints are inserted using bp soft or bp hard commands. Inserting a software breakpoint will add a (TA 0x1) instruction by modifying the target's memory before starting the CPU, while bp hard will insert a hardware breakpoint using one of the IU watchpoint registers. To debug instruction code in read-only memories or memories which are self-modifying the only option is hardware breakpoints. Note that it's possible to debug any RAM-based code using software breakpoints, even where traps are disabled such as in trap handlers. Since hardware breakpoints triggers on the CPU instruction address one must be aware that when the MMU is turned on, virtual addresses are triggered upon.

CPU data address watchpoints (read-only, write-only or read-write) are inserted using the bp watch command. Watchpoints can be setup to trigger within a range determined by a bit-mask where a one means that the address must match the address pattern and a zero mask indicate don't care. The lowest 2-bits are not available, meaning that 32-bit words are the smallest address that can be watched. Byte accesses can still be watched but accesses to the neighboring three bytes will also be watched.

AMBA-bus watchpoints can be inserted using bp bus or bp data. When a bus watchpoint is hit the trace buffer will freeze. The processor can optionally be put in debug mode when the bus watchpoint is hit. This is controlled by the tmode command:

grmon3> tmode break N

If N = 0, the processor will not be halted when the watchpoint is hit. A value > 0 will break the processor and set the AHB trace buffer delay counter to the same value.

NOTE: For hardware supported break/watchpoints the target must have been configured accordingly, otherwise a failure will be reported. Note also that the number of watchpoints implemented varies between designs.

3.4.5. Displaying processor registers

The current register window of a LEON processor can be displayed using the reg command or by accessing the Tcl cpu namespace that GRMON provides. GRMON exports cpu and cpuN where N selects which CPU's registers are accessed, the cpu namespace points to the active CPU selected by the cpu command.

grmon3> reg INS LOCALS OUTS GLOBALS 0: 00000008 0000000C 00000000 00000000 1: 80000070 00000020 00000000 00000001 2: 00000000 00000000 00000000 00000002 3: 00000000 00000000 00000000 00300003 4: 00000000 00000000 00000000 00040004 5: 00000000 00000000 00000000 00005005 6: 407FFFF0 00000000 407FFFF0 00000606 7: 00000000 00000000 00000000 00000077

psr: F34010E0 wim: 00000002 tbr: 40000060 y: 00000000

pc: 40003E44 be 0x40003FB8 npc: 40003E48 nop grmon3> puts [format %x $::cpu::iu::o6] 407ffff0

Other register windows can be displayed using reg wN, when N denotes the window number. Use the float command to show the FPU registers (if present).

3.4.6. Backtracing function calls

When debugging an application it is often most useful to view how the CPU entered the current function. The bt command analyze the previous stack frames to determine the backtrace. GRMON reads the register windows and then switches to read from the stack depending on the %WIM and %PSR register.

GRMON3-UM June 2019, Version 3.1.0

16 www.cobham.com/gaisler

The backtrace is presented with the caller's program counter (%PC) to return to (below where the CALL instruction was issued) and the stack pointer (%SP) at that time. The first entry (frame #0) indicates the current location of the CPU and the current stack pointer. The right most column print out the %PC address relative the function symbol, i.e. if symbols are present.

grmon3> bt

%pc %sp #0 0x40003e24 0x407ffdb8 <Fft+0x4> #1 0x40005034 0x407ffe28 <main+0xfc4> #2 0x40001064 0x407fff70 <_start+0x64> #3 0x4000cf40 0x407fffb0 <_hardreset_real+0x78>

NOTE: In order to display a correct backtrace for optimized code where optimized leaf functions are present a symbol table must exist.

In a MP system the backtrace of a specific CPU can be printed, either by changing the active CPU with the cpu command or by passing the CPU index to bt.

3.4.7. Displaying memory contents

Any memory location can be displayed and written using the commands listed in the table below. Memory commands that are prefixed with a v access the virtual address space seen by doing MMU address lookups for active CPU.

Table 3.2. Memory access commands

Command

Description

Name

mem AMBA bus 32-bit memory read access, list a range of addresses wmem AMBA bus 32-bit memory write access vmem AMBA bus 32-bit virtual memory read access, list a range of addresses memb AMBA bus 8-bit memory read access, list a range of addresses memh AMBA bus 16-bit memory read access, list a range of addresses vmemb AMBA bus 8-bit virtual memory read access, list a range of addresses vmemh AMBA bus 16-bit virtual memory read access, list a range of addresses vwmemb AMBA bus 8-bit virtual memory write access vwmemh AMBA bus 16-bit virtual memory write access vwmems Write a string to an AMBA bus virtual memory address vwmem AMBA bus 32-bit virtual memory write access wmemb AMBA bus 8-bit memory write access wmemh AMBA bus 16-bit memory write access wmems Write a string to an AMBA bus memory address amem AMBA bus 32-bit asynchronous memory read access

NOTE: Most debug links only support 32-bit accesses, only JTAG links support unaligned access. An unaligned access is when the address or number of bytes are not evenly divided by four. When an unaligned data read request is issued, then GRMON will read some extra bytes to align the data, but only return the requested data. If a write request is issued, then an aligned read-modify-write sequence will occur.

The mem command requires an address and an optional length, if the length is left out 64 bytes are displayed. If a program has been loaded, text symbols can be used instead of a numeric address. The memory content is displayed in hexadecimal-decimal format, grouped in 32-bit words. The ASCII equivalent is printed at the end of the line.

grmon> mem 0x40000000

40000000 a0100000 29100004 81c52000 01000000 ...)..... .....

GRMON3-UM

17 www.cobham.com/gaisler

June 2019, Version 3.1.0

40000010 91d02000 01000000 01000000 01000000 . .............

40000020 91d02000 01000000 01000000 01000000 . .............

40000030 91d02000 01000000 01000000 01000000 . .............

grmon> mem 0x40000000 16

40000000 a0100000 29100004 81c52000 01000000 ...)..... .....

grmon> mem main 48

40003278 9de3bf98 2f100085 31100037 90100000 ..../...1..7....

40003288 d02620c0 d025e178 11100033 40000b4b & .%.x...3@..K

40003298 901223b0 11100033 40000af4 901223c0 ..#....3@.....#.

The memory access commands listed in Table 3.2 are not restricted to memory: they can be used on any bus address accessible by the debug link. However, for access to peripheral control registers, the command info reg can provide a more user-friendly output.

All commands in Table 3.2, , except for amem, return to the caller when the bus access has completed, which means that a sequence of these commands generates a sequence of bus accesses with the same ordering. In situations where the bus accesses order is not critical, the command amem can be used to schedule multiple concurrent read accesses whose results can be retrieved at a later time. This is useful when GRMON is automated using Tcl scripts.

3.4.8. Instruction disassembly

If the memory contents is SPARC machine code, the contents can be displayed in assembly code using the disassemble command:

grmon3> disassemble 0x40000000 10 0x40000000: 88100000 clr %g4 <start+0> 0x40000004: 09100034 sethi %hi(0x4000d000), %g4 <start+4> 0x40000008: 81c12034 jmp %g4 + 0x34 <start+8> 0x4000000c: 01000000 nop <start+12> 0x40000010: a1480000 mov %psr, %l0 <start+16> 0x40000014: a7500000 mov %wim, %l3 <start+20> 0x40000018: 10803401 ba 0x4000d01c <start+24> 0x4000001c: ac102001 mov 1, %l6 <start+28> 0x40000020: 91d02000 ta 0x0 <start+32> 0x40000024: 01000000 nop <start+36>

grmon3> dis main 0x40004070: 9de3beb8 save %sp, -328, %sp <main+0> 0x40004074: 15100035 sethi %hi(0x4000d400), %o2 <main+4> 0x40004078: d102a3f4 ld [%o2 + 0x3f4], %f8 <main+8> 0x4000407c: 13100035 sethi %hi(0x4000d400), %o1 <main+12> 0x40004080: 39100088 sethi %hi(0x40022000), %i4 <main+16> 0x40004084: 3710003a sethi %hi(0x4000e800), %i3 <main+20> 0x40004088: d126e2e0 st %f8, [%i3 + 0x2e0] <main+24> 0x4000408c: d1272398 st %f8, [%i4 + 0x398] <main+28> 0x40004090: 400006a9 call 0x40005b34 <main+32> 0x40004094: 901262f0 or %o1, 0x2f0, %o0 <main+36> 0x40004098: 11100035 sethi %hi(0x4000d400), %o0 <main+40> 0x4000409c: 40000653 call 0x400059e8 <main+44> 0x400040a0: 90122300 or %o0, 0x300, %o0 <main+48> 0x400040a4: 7ffff431 call 0x40001168 <main+52> 0x400040a8: 3510005b sethi %hi(0x40016c00), %i2 <main+56> 0x400040ac: 2510005b sethi %hi(0x40016c00), %l2 <main+60>

3.4.9. Using the trace buffer

The LEON processor and associated debug support unit (DSU) can be configured with trace buffers to store both the latest executed instructions and the latest AHB bus transfers. The trace buffers are automatically enabled by GRMON during start-up , but can also be individually enabled and disabled using tmode command. The command

ahb is used to show the AMBA buffer. The command inst is used to show the instruction buffer. The command hist is used to display the contents of the instruction and the AMBA buffers mixed together. Below is an example

debug session that shows the usage of breakpoints, watchpoints and the trace buffer:

grmon3> lo v8/stanford.exe 40000000 .text 54.8kB / 54.8kB [===============>] 100% 4000DB30 .data 2.9kB / 2.9kB [===============>] 100% Total size: 57.66kB (786.00kbit/s) Entry point 0x40000000 Image /home/daniel/examples/v8/stanford.exe loaded

GRMON3-UM June 2019, Version 3.1.0

18 www.cobham.com/gaisler

grmon3> bp Fft Software breakpoint 1 at <Fft>

grmon3> bp watch 0x4000eae0 Hardware watchpoint 2 at 0x4000eae0

grmon3> bp NUM ADRESS MASK TYPE SYMBOL 1 : 0x40003e20 (soft) Fft+0 2 : 0x4000eae0 0xfffffffc (watch rw) floated+0

grmon3> run

CPU 0: watchpoint 2 hit 0x40001024: c0388003 std %g0, [%g2 + %g3] <_start+36> CPU 1: Power down mode

grmon3> inst TIME ADDRESS INSTRUCTION RESULT 84675 40001024 std %g0, [%g2 + %g3] [4000eaf8 00000000 00000000] 84678 4000101c subcc %g3, 8, %g3 [00000440] 84679 40001020 bge,a 0x4000101c [00000448] 84682 40001024 std %g0, [%g2 + %g3] [4000eaf0 00000000 00000000] 84685 4000101c subcc %g3, 8, %g3 [00000438] 84686 40001020 bge,a 0x4000101c [00000440] 84689 40001024 std %g0, [%g2 + %g3] [4000eae8 00000000 00000000] 84692 4000101c subcc %g3, 8, %g3 [00000430] 84693 40001020 bge,a 0x4000101c [00000438] 84694 40001024 std %g0, [%g2 + %g3] [ TRAP ]

grmon3> ahb TIME ADDRESS TYPE D[31:0] TRANS SIZE BURST MST LOCK RESP HIRQ 84664 4000eb08 write 00000000 2 2 1 0 0 0 0000 84667 4000eb0c write 00000000 3 2 1 0 0 0 0000 84671 4000eb00 write 00000000 2 2 1 0 0 0 0000 84674 4000eb04 write 00000000 3 2 1 0 0 0 0000 84678 4000eaf8 write 00000000 2 2 1 0 0 0 0000 84681 4000eafc write 00000000 3 2 1 0 0 0 0000 84685 4000eaf0 write 00000000 2 2 1 0 0 0 0000 84688 4000eaf4 write 00000000 3 2 1 0 0 0 0000 84692 4000eae8 write 00000000 2 2 1 0 0 0 0000 84695 4000eaec write 00000000 3 2 1 0 0 0 0000

grmon3> reg INS LOCALS OUTS GLOBALS 0: 80000200 00000000 00000000 00000000 1: 80000200 00000000 00000000 00000000 2: 0000000C 00000000 00000000 4000E6B0 3: FFF00000 00000000 00000000 00000430 4: 00000002 00000000 00000000 4000CC00 5: 800FF010 00000000 00000000 4000E680 6: 407FFFB0 00000000 407FFF70 4000CF34 7: 4000CF40 00000000 00000000 00000000

psr: F30010E7 wim: 00000002 tbr: 40000000 y: 00000000

pc: 40001024 std %g0, [%g2 + %g3] npc: 4000101c subcc %g3, 8, %g3

grmon3> bp del 2

grmon3> cont Towers Queens Intmm Mm Puzzle Quick Bubble Tree FFT CPU 0: breakpoint 1 hit 0x40003e24: a0100018 mov %i0, %l0 <Fft+4> CPU 1: Power down mode

grmon3> grmon3> hist TIME ADDRESS INSTRUCTIONS/AHB SIGNALS RESULT/DATA 30046975 40003e20 AHB read mst=0 size=2 [9de3bf90] 30046976 40005030 or %l2, 0x1e0, %o3 [40023de0] 30046980 40003e24 AHB read mst=0 size=2 [91d02001] 30046981 40005034 call 0x40003e20 [40005034] 30046985 40003e28 AHB read mst=0 size=2 [b136201f] 30046990 40003e2c AHB read mst=0 size=2 [f83fbff0] 30046995 40003e30 AHB read mst=0 size=2 [82040018] 30047000 40003e34 AHB read mst=0 size=2 [d11fbff0] 30047005 40003e38 AHB read mst=0 size=2 [9a100019] 30047010 40003e3c AHB read mst=0 size=2 [9610001a]

When printing executed instructions, the value within brackets denotes the instruction result, or in the case of store instructions the store address and store data. The value in the first column displays the relative time, equal

GRMON3-UM

19 www.cobham.com/gaisler

June 2019, Version 3.1.0

to the DSU timer. The time is taken when the instruction completes in the last pipeline stage (write-back) of the processor. In a mixed instruction/AHB display, AHB address and read or write value appears within brackets. The time indicates when the transfer completed, i.e. when HREADY was asserted.

NOTE: As the AHB trace is disabled when a breakpoint is hit, AHB accesses related to instruction cache fetches after the time of break can be missed. The command ahb force can be used enable AHB tracing even when the processor is in debug mode.

NOTE: When switching between tracing modes with tmode the contents of the trace buffer will not be valid until execution has been resumed and the buffer refilled.

3.4.10. Profiling

GRMON supports profiling of LEON applications when run on real hardware. The profiling function collects (statistical) information on the amount of execution time spent in each function. Due to its non-intrusive nature, the profiling data does not take into consideration if the current function is called from within another procedure. Even so, it still provides useful information and can be used for application tuning.

NOTE: To increase the number of samples, use the fastest debug link available on the target system. I.a. do not use I/O forwarding (start GRMON without the -u commandline option)

grmon3> profile on

grmon3> run Starting Perm Towers Queens Intmm Mm Puzzle Quick Bubble Tree FFT

CPU 0: Interrupted! 0x40003ee4: 95a0c8a4 fsubs %f3, %f4, %f10 <Fft+196> CPU 1: Interrupted! 0x40000000: 88100000 clr %g4 <start+0>

grmon3> prof FUNCTION SAMPLES RATIO(%) Trial 0000000096 27.35 __window_overflow_rettseq_ret 0000000060 17.09 main 0000000051 14.52 __window_overflow_slow1 0000000026 7.40 Fft 0000000023 6.55 Insert 0000000016 4.55 Permute 0000000013 3.70 tower 0000000013 3.70 Try 0000000013 3.70 Quicksort 0000000011 3.13 Checktree 0000000007 1.99 _malloc_r 0000000005 1.42 start 0000000004 1.13 outbyte 0000000003 0.85 Towers 0000000002 0.56 __window_overflow_rettseq 0000000002 0.56 ___st_pthread_mutex_lock 0000000002 0.56 _start 0000000001 0.28 Perm 0000000001 0.28 __malloc_lock 0000000001 0.28 ___st_pthread_mutex_trylock 0000000001 0.28

3.4.11. Attaching to a target system without initialization

When GRMON connects to a target system, it probes the configuration and initializes memory and registers. To determine why a target has crashed, or resume debugging without reloading the application, it might be desirable to connect to the target without performing a (destructive) initialization. This can be done by specifying the ni switch during the start-up of GRMON. The system information print-out (info sys) will then however not be able to display the correct memory settings. The use of the -stack option and the go command might also be

GRMON3-UM June 2019, Version 3.1.0

20 www.cobham.com/gaisler

necessary in case the application is later restarted. The run command may not have the intended effect since the debug drivers have not been initialized during start-up.

3.4.12. Multi-processor support

In systems with more than one LEON processor, the cpu command can be used to control the state and debugging focus of the processors. In MP systems, the processors are enumerated with 0..N-1, where N is the number of processors. Each processor can be in two states; enabled or disabled. When enabled, a processor can be started by LEON software or by GRMON. When disabled, the processor will remain halted regardless. One can pause a MP operating system and disable a CPU to debug a hanged CPU for example.

Most per-CPU (DSU) debugging commands such as displaying registers, backtrace or adding breakpoints will be directed to the active processor only. Switching active processor can be done using the 'cpu active N' command, see example below. The Tcl cpu namespace exported by GRMON is also changed to point to the active CPU's namespace, thus accessing cpu will be the same as accessing cpu1 if CPU1 is the currently active CPU.

grmon3> cpu cpu 0: enabled active cpu 1: enabled

grmon3> cpu act 1

grmon3> cpu cpu 0: enabled cpu 1: enabled active

grmon3> cpu act 0

grmon3> cpu dis 1

grmon3> cpu cpu 0: enabled active cpu 1: disabled

grmon3> puts $cpu::fpu::f1

-1.984328031539917

grmon3> puts $cpu0::fpu::f1

-1.984328031539917

grmon3> puts $cpu1::fpu::f1

2.3017966689845248e+18

NOTE: Non-MP software can still run on the first CPU unaffected of the additional CPUs since it is the target software that is responsible for waking other CPUs. All processors are enabled by default.

Note that it is possible to debug MP systems using GDB, but the user are required to change CPU itself. GRMON specific commands can be entered from GDB using the monitor command.

3.4.13. Stack and entry point

The stack pointer is located in %O6 (%SP) register of SPARC CPUs. GRMON sets the stack pointer before starting the CPU with the run command. The address is auto-detected to end of main memory, however it is overridable using the -stack when starting GRMON or by issuing the stack command. Thus stack pointer can be used by software to detect end of main memory.

The entry point (EP) determines at which address the CPU start its first instruction execution. The EP defaults to main memory start and normally overridden by the load command when loading the application. ELF-files has support for storing entry point. The entry point can manually be set with the ep command.

In a MP systems if may be required to set EP and stack pointer individual per CPU, one can use the cpu command in conjunction with ep and stack.

3.4.14. Memory Management Unit (MMU) support

The LEON optionally implements the reference MMU (SRMMU) described in the SPARCv8 specification. GRMON support viewing and changing the MMU registers through the DSU, using the mmu command. GRMON also supports address translation by reading the MMU table from memory similar to the MMU. The walk com-

GRMON3-UM June 2019, Version 3.1.0

21 www.cobham.com/gaisler

mand looks up one address by walking the MMU table printing out every step taken and the result. To simply print out the result of such a translation, use the va command.

The memory commands that are prefixed with a v work with virtual addresses, the addresses given are translated before listing or writing physical memory. If the MMU is not enabled, the vmem command for example is an alias for mem. See Section 3.4.7, “Displaying memory contents” for more information.

NOTE: Many commands are affected by that the MMU is turned on, such as the disassemble command.

3.4.15. CPU cache support

The LEON optionally implements Level-1 instruction-cache and data-cache. GRMON supports the CPU's cache by adopting certain operations depending on if the cache is activated or not. The user may also be able to access the cache directly. This is however not normally needed, but may be useful when debugging or analyzing different cache aspects. By default the L1-cache is turned on by GRMON , the cctrl command can be used to change the cache control register. The commandline switches -nic and -ndc disables instruction and data cache respectively.

With the icache and dcache commands it is possible to view and modify the current content of the cache or check if the cache is consistent with the memory. Both caches can be flushed instantly using the commands cctrl flush. The data cache can be flushed instantly using the commands dcache flush. The instruction cache can be flushed instantly using the commands icache flush.

The GRLIB Level-2 cache is supported using the l2cache command.

3.5. Tcl integration

GRMON has built-in support for Tcl 8.6. All commands lines entered in the terminal will pass through a Tclinterpreter. This enables loops, variables, procedures, scripts, arithmetics and more for the user. I.a. it also provides an API for the user to extend GRMON.

3.5.1. Shells

GRMON creates several independent TCL shells, each with its own set of commands and variables. I.e. changing active CPU in one shell does not affect any other shell. In the commandline version there one shell available for the user by default, the CLI shell, which is accessed from the terminal. In the GUI is possible to create and view multiple shells.

Additional custom user shells for the commandline interface can be created with the command usrsh. Each custom user shell has an associated Tcl interpreter running in a separate execution thread.

When the GDB service is running, a GDB shell is also available from GDB by using the command mon. There is also a system shell and an execution shell running in the background that GRMON uses internally. Some

hooks must be loaded into these shells to work, see Appendix C, Tcl API for more information.

3.5.2. Commands

There are two groups of commands, the native Tcl commands and GRMON's commands. Information about the native Tcl commands and their syntax can be found at the Tcl website [http://www.tcl.tk/]. The GRMON commands' syntax documentation can be found in Appendix B, Command syntax.

The commands have three types of output:

1. Standard output. GRMON's commands prints information to standard output. This information is often

structured in a human readable way and cannot be used by other commands. Most of the GRMON commands print some kind of information to the standard output, while very few of the Tcl commands does that. Setting the variable ::grmon::settings:suppress_output to 1 will stop GRMON commands from printing to the standard output, i.e. the TCL command puts will still print it's output. It is also possible to put the command silent in front of another GRMON command to suppress the output of a single command, e.g. grmon3> puts [expr [silent mem 0x40000000 4] + 4]

GRMON3-UM June 2019, Version 3.1.0

22 www.cobham.com/gaisler

2. Return values. The return value from GRMON is seldom the same as the information that is printed to

standard output, it's often the important data in a raw format. Return values can be used as input to other commands or to be saved in variables. All TCL commands and many GRMON commands have return values. The return values from commands are normally not printed. To print the return value to standard output one can use the Tcl command puts. I.a. if the variable ::grmon::settings:echo_result to 1, then GRMON will always print the result to stdout.

3. Return code. The return code from a command can be accessed by reading the variable errorCode or

by using the Tcl command catch. Both Tcl and GRMON commands will have an error message as return value if it fails, which is also printed to standard output. More about error codes can be read about in the Tcl tutorial or on the Tcler's Wiki [http://wiki.tcl.tk/].

For some of the GRMON commands it is possible to specify which core the commands is operation on. This is implemented differently depending for each command, see the commands' syntax documentation in Appendix B, Command syntax for more details. Some of these commands use a device name to specify which core to interact with, see Appendix C, Tcl API for more information about device names.

3.5.3. API

It is possible to extend GRMON using Tcl. GRMON provides an API that makes it possible do write own device drivers, implement hooks and to write advanced commands. See Appendix C, Tcl API for a detailed description of the API.

3.6. Symbolic debug information

GRMON will automatically extract the symbol information from ELF-files, debug information is never read from ELF-files. The symbols can be used to GRMON commands where an address is expected as below. Symbols are tab completed.

grmon3> load v8/stanford.exe 40000000 .text 54.8kB / 54.8kB [===============>] 100% 4000DB30 .data 2.9kB / 2.9kB [===============>] 100% Image /home/daniel/examples/v8/stanford.exe loaded

grmon3> bp main Software breakpoint 1 at <main>

grmon3> dis strlen 5 0x40005b88: 808a2003 andcc %o0, 0x3, %g0 <strlen+0> 0x40005b8c: 12800012 bne 0x40005BD4 <strlen+4> 0x40005b90: 94100008 mov %o0, %o2 <strlen+8> 0x40005b94: 033fbfbf sethi %hi(0xFEFEFC00), %g1 <strlen+12> 0x40005b98: da020000 ld [%o0], %o5 <strlen+16>

The symbols command can be used to display all symbols, lookup the address of a symbol, or to read in symbols from an alternate (ELF) file:

grmon3> symbols load v8/stanford.exe

grmon3> symbols lookup main Found address 0x40004070

grmon3> symbols list 0x40005ab8 GLOBAL FUNC putchar 0x4000b6ac GLOBAL FUNC _mprec_log10 0x4000d9d0 GLOBAL OBJECT __mprec_tinytens 0x4000bbe8 GLOBAL FUNC cleanup_glue 0x4000abfc GLOBAL FUNC _hi0bits 0x40005ad4 GLOBAL FUNC _puts_r 0x4000c310 GLOBAL FUNC _lseek_r 0x4000eaac GLOBAL OBJECT piecemax 0x40001aac GLOBAL FUNC Try 0x40003c6c GLOBAL FUNC Uniform11 0x400059e8 GLOBAL FUNC printf ...

Reading symbols from alternate files is necessary when debugging self-extracting applications (MKPROM), when switching between virtual and physical address space (Linux) or when debugging a multi-core ASMP system where each CPU has its own symbol table. It is recommended to clear old symbols with symbols clear before switching symbol table, otherwise the new symbols will be added to the old table.

GRMON3-UM

23 www.cobham.com/gaisler

June 2019, Version 3.1.0

3.6.1. Multi-processor symbolic debug information

When loading symbols into GRMON it is possible to associate them with a CPU. When all symbols/images are associated with CPU index 0, then GRMON will assume its a single-core or SMP application and lookup all symbols from the symbols table associated with CPU index 0.

If different CPU indexes are specified (by setting active CPU or adding cpu# argument to the commands) when loading symbols/images, then GRMON will assume its an AMP application that has been loaded. GRMON will use the current active CPU (or cpu# argument) to determine which CPU index to lookup symbols from.

grmon3> cpu active 1

grmon3> symbols ../tests/threads/rtems-mp2 Loaded 1630 symbols

grmon3> bp _Thread_Handler Software breakpoint 1 at <_Thread_Handler>

grmon3> symbols ../tests/threads/rtems-mp1 cpu0 Loaded 1630 symbols

grmon3> bp _Thread_Handler cpu0 Software breakpoint 2 at <_Thread_Handler>

grmon3> bp NUM ADRESS MASK TYPE CPU SYMBOL 1 : 0x40418408 (soft) 1 _Thread_Handler+0 2 : 0x40019408 (soft) 0 _Thread_Handler+0

3.7. GDB interface

This section describes the GDB interface support available in GRMON. GRMON supports GDB version 6.3, 6.4,

6.8 and 8.2. Other tools that communicate over the GDB protocol may also attach to GRMON, some tools such as Eclipse Workbench and DDD communicate with GRMON via GDB.

GDB must be built for the SPARC architecture, a native PC GDB does not work together with GRMON. The toolchains that Cobham Gaisler distributes comes with a patched and tested version of GDB targeting all SPARC LEON development tools.

Please see the GDB documentation available from the official GDB homepage [http://www.gnu.org/software/gdb/].

3.7.1. Connecting GDB to GRMON

GRMON can act as a remote target for GDB, allowing symbolic debugging of target applications. To initiate GDB communications, start the monitor with the -gdb switch or use the GRMON gdb start command:

$ grmon -gdb ... Started GDB service on port 2222. ... grmon3> gdb status GDB Service is waiting for incoming connection Port: 2222

Then, start GDB in a different window and connect to GRMON using the extended-remote protocol. By default, GRMON listens on port 2222 for the GDB connection:

$ sparc-gaisler-elf-gdb /opt/bcc-2.0.7-rc.1-gcc/src/examples/stanford/stanford GNU gdb (GDB) 8.2 Copyright (C) 2018 Free Software Foundation, Inc. License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. Type "show copying" and "show warranty" for details. This GDB was configured as "--host=x86_64-pc-linux-gnu --target=sparc-gaisler-elf". Type "show configuration" for configuration details. For bug reporting instructions, please see: <http://www.gnu.org/software/gdb/bugs/>. Find the GDB manual and other documentation resources online at: <http://www.gnu.org/software/gdb/documentation/>.

GRMON3-UM June 2019, Version 3.1.0

24 www.cobham.com/gaisler

For help, type "help". Type "apropos word" to search for commands related to "word"... Reading symbols from /opt/bcc-2.0.7-rc.1-gcc/src/examples/stanford/stanford...done. (gdb) target extended-remote :2222 Remote debugging using :2222 __bcc_entry_point () at /opt/bcc-2.0.7-rc.1-gcc/src/libbcc/shared/trap/trap_table_mvt.S:81 81 RESET_TRAP(__bcc_trap_reset_mvt); ! 00 reset (gdb)

3.7.2. Executing GRMON commands from GDB

While GDB is attached to GRMON, most GRMON commands can be executed using the GDB monitor command. Output from the GRMON commands is then displayed in the GDB console like below. Some DSU commands are naturally not available since they would conflict with GDB. All commands executed from GDB are executed in a separate Tcl interpreter, thus variables created from GDB will not be available from the GRMON terminal.

(gdb) monitor hist TIME ADDRESS INSTRUCTIONS/AHB SIGNALS RESULT/DATA 30046975 40003e20 AHB read mst=0 size=2 [9de3bf90] 30046976 40005030 or %l2, 0x1e0, %o3 [40023de0] 30046980 40003e24 AHB read mst=0 size=2 [91d02001] 30046981 40005034 call 0x40003e20 [40005034] 30046985 40003e28 AHB read mst=0 size=2 [b136201f] 30046990 40003e2c AHB read mst=0 size=2 [f83fbff0] 30046995 40003e30 AHB read mst=0 size=2 [82040018] 30047000 40003e34 AHB read mst=0 size=2 [d11fbff0] 30047005 40003e38 AHB read mst=0 size=2 [9a100019] 30047010 40003e3c AHB read mst=0 size=2 [9610001a] (gdb)

3.7.3. Running applications from GDB

To load and start an application, use the GDB load and run command.

$ sparc-rtems-gdb v8/stanford.exe (gdb) target extended-remote :2222 Remote debugging using :2222 main () at stanford.c:1033 1033 { (gdb) load Loading section .text, size 0xdb30 lma 0x40000000 Loading section .data, size 0xb78 lma 0x4000db30 Start address 0x40000000, load size 59048 Transfer rate: 18 KB/sec, 757 bytes/write. (gdb) b main Breakpoint 1 at 0x40004074: file stanford.c, line 1033. (gdb) run The program being debugged has been started already. Start it from the beginning? (y or n) y Starting program: /home/daniel/examples/v8/stanford.exe

Breakpoint 1, main () at stanford.c:1033 1033 { (gdb) list 1028 /* Printcomplex( 6, 99, z, 1, 256, 17 ); */ 1029 }; 1030 } /* oscar */ ; 1031 1032 main () 1033 { 1034 int i; 1035 fixed = 0.0; 1036 floated = 0.0; 1037 printf ("Starting \n"); (gdb)

To interrupt execution, Ctrl-C can be typed in GDB terminal (similar to GRMON). The program can be restarted using the GDB run command but the program image needs to be reloaded first using the load command. Software trap 1 (TA 0x1) is used by GDB to insert breakpoints and should not be used by the application.

GRMON translates SPARC traps into (UNIX) signals which are properly communicated to GDB. If the application encounters a fatal trap, execution will be stopped exactly before the failing instruction. The target memory and register values can then be examined in GDB to determine the error cause.

GRMON implements the GDB breakpoint and watchpoint interface and makes sure that memory and cache are synchronized.

GRMON3-UM

25 www.cobham.com/gaisler

June 2019, Version 3.1.0

3.7.4. Running SMP applications from GDB

If GRMON is running on the same computer as GDB, or if the executable is available on the remote computer that is running GRMON, it is recommended to issue the GDB command set remote exec-file <remote-file-path>. After this has been set, GRMON will automatically load the file, and symbols if available, when the GDB command run is issued.

If the executable is not available on the remote computer where GRMON is running, then the GDB command load can be used to load the software to the target system. In addition the entry points for all CPU's, except the first, must be set manually using the GRMON ep before starting the application.

$ sparc-rtems-gdb /opt/rtems-4.11/src/rtems-4.11/testsuites/libtests/ticker/ticker.exe GNU gdb 6.8.0.20090916-cvs Copyright (C) 2008 Free Software Foundation, Inc. License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. Type "show copying" and "show warranty" for details. This GDB was configured as "--host=i686-pc-linux-gnu --target=sparc-rtems"... (gdb) target extended-remote :2222 Remote debugging using :2222 trap_table () at /opt/rtems-4.11/src/rtems-4.11/c/src/lib/libbsp/sparc/leon3/../../sparc/shared/start /start.S:69 69 /opt/rtems-4.11/src/rtems-4.11/c/src/lib/libbsp/sparc/leon3/../../sparc/shared/start/start.S: No such file or directory. in /opt/rtems-4.11/src/rtems-4.11/c/src/lib/libbsp/sparc/leon3/../../sparc/shared/start/start.S Current language: auto; currently asm (gdb) load Loading section .text, size 0x1aed0 lma 0x40000000 Loading section .data, size 0x5b0 lma 0x4001aed0 Start address 0x40000000, load size 111744 Transfer rate: 138 KB/sec, 765 bytes/write. (gdb) mon ep $cpu::iu::pc cpu1 (gdb) mon ep $cpu::iu::pc cpu2 (gdb) mon ep $cpu::iu::pc cpu3 Cpu 1 entry point: 0x40000000 (gdb) run The program being debugged has been started already. Start it from the beginning? (y or n) y Starting program: /opt/rtems-4.11/src/rtems-4.11/testsuites/libtests/ticker/ticker.exe

3.7.5. Running AMP applications from GDB

If GRMON is running on the same computer as GDB, or if the executables are available on the remote computer that is running GRMON, it is recommended to issue the GDB command set remote exec-file <remote-file-path>. When this is set, GRMON will automatically load the file,and symbols if available, when the GDB command run is issued. The second application needs to be loaded into GRMON using the GRMON command load <remote-file-

path> cpu1. In addition the stacks must also be set manually in GRMON using the command stack <address> cpu# for both CPUs.

$ sparc-rtems-gdb /opt/rtems-4.10/src/samples/rtems-mp1 GNU gdb 6.8.0.20090916-cvs Copyright (C) 2008 Free Software Foundation, Inc. License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. Type "show copying" and "show warranty" for details. This GDB was configured as "--host=i686-pc-linux-gnu --target=sparc-rtems"...

GRMON3-UM June 2019, Version 3.1.0

26 www.cobham.com/gaisler

(gdb) target extended-remote :2222 Remote debugging using :2222 (gdb) set remote exec-file /opt/rtems-4.10/src/samples/rtems-mp1 (gdb) mon stack 0x403fff00 cpu0 CPU 0 stack pointer: 0x403fff00 (gdb) mon load /opt/rtems-4.10/src/samples/rtems-mp2 cpu1 Total size: 177.33kB (1.17Mbit/s) Entry point 0x40400000 Image /opt/rtems-4.10/src/samples/rtems-mp2 loaded (gdb) mon stack 0x407fff00 cpu1 CPU 1 stack pointer: 0x407fff00 (gdb) run Starting program: /opt/rtems-4.10/src/samples/rtems-mp1 NODE[0]: is Up! NODE[0]: Waiting for Semaphore A to be created (0x53454d41) NODE[0]: Waiting for Semaphore B to be created (0x53454d42) NODE[0]: Waiting for Task A to be created (0x54534b41) ^C[New Thread 151060481]

Program received signal SIGINT, Interrupt. [Switching to Thread 151060481] pwdloop () at /opt/rtems-4.10/src/rtems-4.10/c/src/lib/libbsp/sparc/leon3/startup/bspidle.S:26 warning: Source file is more recent than executable. 26 retl Current language: auto; currently asm (gdb)

If the executable is not available on the remote computer where GRMON is running, then the GDB command file and load can be used to load the software to the target system. Use the GRMON command cpu act <num> before issuing the GDB command load to specify which CPU is the target for the software being loaded. In addition the stacks must also be set manually in GRMON using the command stack <address> cpu# for both CPUs.

$ sparc-rtems-gdb GNU gdb 6.8.0.20090916-cvs Copyright (C) 2008 Free Software Foundation, Inc. License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. Type "show copying" and "show warranty" for details. This GDB was configured as "--host=i686-pc-linux-gnu --target=sparc-rtems". (gdb) target extended-remote :2222 Remote debugging using :2222 0x40000000 in ?? () (gdb) file /opt/rtems-4.10/src/samples/rtems-mp2 A program is being debugged already. Are you sure you want to change the file? (y or n) y Reading symbols from /opt/rtems-4.10/src/samples/rtems-mp2...done. (gdb) mon cpu act 1 (gdb) load Loading section .text, size 0x2b3e0 lma 0x40400000 Loading section .data, size 0x1170 lma 0x4042b3e0 Loading section .jcr, size 0x4 lma 0x4042c550 Start address 0x40400000, load size 181588 Transfer rate: 115 KB/sec, 759 bytes/write. (gdb) file /opt/rtems-4.10/src/samples/rtems-mp1 A program is being debugged already. Are you sure you want to change the file? (y or n) y

Load new symbol table from "/opt/rtems-4.10/src/samples/rtems-mp1"? (y or n) y Reading symbols from /opt/rtems-4.10/src/samples/rtems-mp1...done. (gdb) mon cpu act 0 (gdb) load Loading section .text, size 0x2b3e0 lma 0x40001000 Loading section .data, size 0x1170 lma 0x4002c3e0 Loading section .jcr, size 0x4 lma 0x4002d550 Start address 0x40001000, load size 181588 Transfer rate: 117 KB/sec, 759 bytes/write. (gdb) mon stack 0x407fff00 cpu1 CPU 1 stack pointer: 0x407fff00 (gdb) mon stack 0x403fff00 cpu0 CPU 0 stack pointer: 0x403fff00 (gdb) run The program being debugged has been started already. Start it from the beginning? (y or n) y Starting program: /opt/rtems-4.10/src/samples/samples/rtems-mp1

3.7.6. GDB Thread support

GDB is capable of listing a operating system's threads, however it relies on GRMON to implement low-level thread access. GDB normally fetches the threading information on every stop, for example after a breakpoint is

GRMON3-UM June 2019, Version 3.1.0

27 www.cobham.com/gaisler

reached or between single-stepping stops. GRMON have to access the memory rather many times to retrieve the information, GRMON. See Section 3.8, “Thread support” for more information.

Start GRMON with the -nothreads switch to disable threads in GRMON and thus in GDB too. Note that GRMON must have access to the symbol table of the operating system so that the thread structures of

the target OS can be found. The symbol table can be loaded from GDB by one must bear in mind that the path is relative to where GRMON has been started. If GDB is connected to GRMON over the network one must make the symbol file available on the remote computer running GRMON.

(gdb) mon puts [pwd] /home/daniel (gdb) pwd Working directory /home/daniel. (gdb) mon sym load /opt/rtems-4.10/src/samples/rtems-hello (gdb) mon sym 0x00016910 GLOBAL FUNC imfs_dir_lseek 0x00021f00 GLOBAL OBJECT Device_drivers 0x0001c6b4 GLOBAL FUNC _mprec_log10 ...

When a program running in GDB stops GRMON reports which thread it is in. The command info threads can be used in GDB to list all known threads, thread N to switch to thread N and bt to list the backtrace of the selected thread.

Program received signal SIGINT, Interrupt. [Switching to Thread 167837703]

0x40001b5c in console_outbyte_polled (port=0, ch=113 `q`) at rtems/.../leon3/console/debugputs.c:38 38 while ((LEON3_Console_Uart[LEON3_Cpu_Index+port]->status & LEON_REG_UART_STATUS_THE) == 0);

(gdb) info threads

8 Thread 167837702 (FTPD Wevnt) 0x4002f760 in _Thread_Dispatch () at rtems/.../threaddispatch.c:109 7 Thread 167837701 (FTPa Wevnt) 0x4002f760 in _Thread_Dispatch () at rtems/.../threaddispatch.c:109 6 Thread 167837700 (DCtx Wevnt) 0x4002f760 in _Thread_Dispatch () at rtems/.../threaddispatch.c:109 5 Thread 167837699 (DCrx Wevnt) 0x4002f760 in _Thread_Dispatch () at rtems/.../threaddispatch.c:109 4 Thread 167837698 (ntwk ready) 0x4002f760 in _Thread_Dispatch () at rtems/.../threaddispatch.c:109 3 Thread 167837697 (UI1 ready) 0x4002f760 in _Thread_Dispatch () at rtems/.../threaddispatch.c:109 2 Thread 151060481 (Int. ready) 0x4002f760 in _Thread_Dispatch () at rtems/.../threaddispatch.c:109 * 1 Thread 167837703 (HTPD ready ) 0x40001b5c in console_outbyte_polled (port=0, ch=113 `q`) at ../../../rtems/c/src/lib/libbsp/sparc/leon3/console/debugputs.c:38 (gdb) thread 8

[Switching to thread 8 (Thread 167837702)]#0 0x4002f760 in _Thread_Dispatch () at rtems/.../threaddispatch.c:109 109 _Context_Switch( &executing->Registers, &heir->Registers ); (gdb) bt

#0 0x4002f760 in _Thread_Dispatch () at rtems/cpukit/score/src/threaddispatch.c:109 #1 0x40013ee0 in rtems_event_receive(event_in=33554432, option_set=0, ticks=0, event_out=0x43fecc14) at ../../../../leon3/lib/include/rtems/score/thread.inl:205 #2 0x4002782c in rtems_bsdnet_event_receive (event_in=33554432, option_set=2, ticks=0, event_out=0x43fecc14) at rtems/cpukit/libnetworking/rtems/rtems_glue.c:641 #3 0x40027548 in soconnsleep (so=0x43f0cd70) at rtems/cpukit/libnetworking/rtems/rtems_glue.c:465 #4 0x40029118 in accept (s=3, name=0x43feccf0, namelen=0x43feccec) at rtems/.../rtems_syscall.c:215 #5 0x40004028 in daemon () at rtems/c/src/libnetworking/rtems_servers/ftpd.c:1925 #6 0x40053388 in _Thread_Handler () at rtems/cpukit/score/src/threadhandler.c:123 #7 0x40053270 in __res_mkquery (op=0, dname=0x0, class=0, type=0, data=0x0, datalen=0, newrr_in=0x0, buf=0x0, buflen=0) at ../rtems/cpukit/libnetworking/libc/res_mkquery.c:199 #8 0x00000008 in ?? () #9 0x00000008 in ?? () Previous frame identical to this frame (corrupt stack?)

In comparison to GRMON the frame command in GDB can be used to select a individual stack frame. One can also step between frames by issuing the up or down commands. The CPU registers can be listed using the info registers command. Note that the info registers command only can see the following registers for an inactive task: g0-g7, l0-l7, i0-i7, o0-o7, PC and PSR. The other registers will be displayed as 0:

gdb) frame 5

#5 0x40004028 in daemon () at rtems/.../rtems_servers/ftpd.c:1925 1925 ss = accept(s, (struct sockaddr *)&addr, &addrLen);

(gdb) info reg

GRMON3-UM

28 www.cobham.com/gaisler

June 2019, Version 3.1.0

g0 0x0 0 g1 0x0 0 g2 0xffffffff -1 g3 0x0 0 g4 0x0 0 g5 0x0 0 g6 0x0 0 g7 0x0 0 o0 0x3 3 o1 0x43feccf0 1140772080 o2 0x43feccec 1140772076 o3 0x0 0 o4 0xf34000e4 -213909276 o5 0x4007cc00 1074252800 sp 0x43fecc88 0x43fecc88 o7 0x40004020 1073758240 l0 0x4007ce88 1074253448 l1 0x4007ce88 1074253448 l2 0x400048fc 1073760508 l3 0x43feccf0 1140772080 l4 0x3 3 l5 0x1 1 l6 0x0 0 l7 0x0 0 i0 0x0 0 i1 0x40003f94 1073758100 i2 0x0 0 i3 0x43ffafc8 1140830152 i4 0x0 0 i5 0x4007cd40 1074253120 fp 0x43fecd08 0x43fecd08 i7 0x40053380 1074082688 y 0x0 0 psr 0xf34000e0 -213909280 wim 0x0 0 tbr 0x0 0 pc 0x40004028 0x40004028 <daemon+148> npc 0x4000402c 0x4000402c <daemon+152> fsr 0x0 0 csr 0x0 0

NOTE: It is not supported to set thread specific breakpoints. All breakpoints are global and stops the execution of all threads. It is not possible to change the value of registers other than those of the current thread.

3.7.7. Virtual memory

There is no way for GRMON to determine if an address sent from GDB is physical or virtual. If an MMU unit is present in the system and it is enabled, then GRMON will assume that all addresses are virtual and try to translate them. When debugging an application that uses the MMU one typically have an image with physical addresses used to load data into the memory and a second image with debug-symbols of virtual addresses. It is therefore important to make sure that the MMU is enabled/disabled when each image is used.

The example below will show a typical case on how to handle virtual and physical addresses when debugging with GDB. The application being debugged is Linux and it consists of two different images created with Linuxbuild. The file image.ram contains physical addresses and a small loader, that among others configures the MMU, while the file image contains all the debug-symbols in virtual address-space.

First start GRMON and start the GDB server.

$ grmon -nb -gdb

Then start GDB in a second shell, load both files into GDB, connect to GRMON and then upload the application into the system. The addresses will be interpreted as physical since the MMU is disabled when GRMON starts.

$ sparc-linux-gdb GNU gdb 6.8.0.20090916-cvs Copyright (C) 2008 Free Software Foundation, Inc. License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html> This is free software: you are free to change and redistribute it. There is NO WARRANTY, to the extent permitted by law. Type "show copying" and "show warranty" for details. This GDB was configured as "--host=i686-pc-linux-gnu --target=sparc-linux". (gdb) file output/images/image.ram Reading symbols from /home/user/linuxbuild-1.0.2/output/images/image.ram...(no d ebugging symbols found)...done.

GRMON3-UM June 2019, Version 3.1.0

29 www.cobham.com/gaisler

(gdb) symbol-file output/images/image Reading symbols from /home/user/linuxbuild-1.0.2/output/images/image...done. (gdb) target extended-remote :2222 Remote debugging using :2222 t_tflt () at /home/user/linuxbuild-1.0.2/linux/linux-2.6-git/arch/sparc/kernel/h ead_32.S:88 88 t_tflt: SPARC_TFAULT /* Inst. Access Exception */ Current language: auto; currently asm (gdb) load Loading section .text, size 0x10b0 lma 0x40000000 Loading section .data, size 0x50 lma 0x400010b0 Loading section .vmlinux, size 0x3f1a60 lma 0x40004000 Loading section .startup_prom, size 0x7ee0 lma 0x403f5a60 Start address 0x40000000, load size 4172352 Transfer rate: 18 KB/sec, 765 bytes/write.

The program must reach a state where the MMU is enabled before any virtual address can be translated. Software breakpoints cannot be used since the MMU is still disabled and GRMON won't translate them into a physical. Hardware breakpoints don't need to be translated into physical addresses, therefore set a hardware assisted breakpoint at 0xf0004000, which is the virtual start address for the Linux kernel.

(gdb) hbreak *0xf0004000 Hardware assisted breakpoint 1 at 0xf0004000: file /home/user/linuxbuild-1.0.2/l inux/linux-2.6-git/arch/sparc/kernel/head_32.S, line 87. (gdb) cont Continuing.

Breakpoint 1, trapbase_cpu0 () at /home/user/linuxbuild-1.0.2/linux/linux-2.6-gi t/arch/sparc/kernel/head_32.S:87 87 t_zero: b gokernel; nop; nop; nop;

At this point the loader has enabled the MMU and both software breakpoints and symbols can be used.

(gdb) break leon_init_timers Breakpoint 2 at 0xf03cff14: file /home/user/linuxbuild-1.0.2/linux/linux-2.6-git /arch/sparc/kernel/leon_kernel.c, line 116.

(gdb) cont Continuing.

Breakpoint 2, leon_init_timers (counter_fn=0xf00180c8 <timer_interrupt>) at /home/user/linuxbuild-1.0.2/linux/linux-2.6-git/arch/sparc/kernel/leon_ke rnel.c:116 116 leondebug_irq_disable = 0; Current language: auto; currently c (gdb) bt #0 leon_init_timers (counter_fn=0xf00180c8 <timer_interrupt>) at /home/user/linuxbuild-1.0.2/linux/linux-2.6-git/arch/sparc/kernel/leon_ke rnel.c:116 #1 0xf03ce944 in time_init () at /home/user/linuxbuild-1.0.2/linux/linux-2.6-gi t/arch/sparc/kernel/time_32.c:227 #2 0xf03cc13c in start_kernel () at /home/user/linuxbuild-1.0.2/linux/linux-2.6

-git/init/main.c:619 #3 0xf03cb804 in sun4c_continue_boot () #4 0xf03cb804 in sun4c_continue_boot () Backtrace stopped: previous frame identical to this frame (corrupt stack?) (gdb) info locals eirq = <value optimized out> rootnp = <value optimized out> np = <value optimized out> pp = <value optimized out> len = 13 ampopts = <value optimized out> (gdb) print len $2 = 13

If the application for some reason need to be reloaded, then the MMU must first be disabled via GRMON. In addition all software breakpoints should be deleted before the application is restarted since the MMU has been disabled and GRMON won't translate virtual addresses anymore.

(gdb) mon mmu mctrl 0 mctrl: 006E0000 ctx: 00000000 ctxptr: 40440800 fsr: 00000000 far: 00000000 (gdb) load Loading section .text, size 0x10b0 lma 0x40000000 Loading section .data, size 0x50 lma 0x400010b0 Loading section .vmlinux, size 0x3f1a60 lma 0x40004000 Loading section .startup_prom, size 0x7ee0 lma 0x403f5a60 Start address 0x40000000, load size 4172352 Transfer rate: 18 KB/sec, 765 bytes/write.

GRMON3-UM

30 www.cobham.com/gaisler

June 2019, Version 3.1.0

+ 209 hidden pages

COBHAM GRMON3 User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

Table of Contents

1. Introduction

1.1. Overview

1.2. Supported platforms and system requirements

1.3. Obtaining GRMON

1.4. Installation

1.5. License

1.6. GRMON Evaluation version

1.7. Problem reports

2. Debugging concept

2.1. Overview

2.2. Target initialization

2.2.1. LEON2 target initialization

2.2.2. Configuration file target initialization

2.3. Memory register reset values

3. Operation

3.1. Overview

3.2. Starting GRMON

3.2.1. Debug link options

3.2.2. Debug driver options

3.2.3. General options

3.3. GRMON command-line interface (CLI)

3.4. Common debug operations

3.4.1. Examining the hardware configuration

3.4.2. Uploading application and data to target memory

3.4.3. Running applications

3.4.4. Inserting breakpoints and watchpoints

3.4.5. Displaying processor registers

3.4.6. Backtracing function calls

3.4.7. Displaying memory contents

3.4.8. Instruction disassembly

3.4.9. Using the trace buffer

3.4.10. Profiling

3.4.11. Attaching to a target system without initialization

3.4.12. Multi-processor support

3.4.13. Stack and entry point

3.4.14. Memory Management Unit (MMU) support

3.4.15. CPU cache support

3.5. Tcl integration

3.5.1. Shells

3.5.2. Commands

3.5.3. API

3.6. Symbolic debug information

3.6.1. Multi-processor symbolic debug information

3.7. GDB interface

3.7.1. Connecting GDB to GRMON

3.7.2. Executing GRMON commands from GDB

3.7.3. Running applications from GDB

3.7.4. Running SMP applications from GDB

3.7.5. Running AMP applications from GDB

3.7.6. GDB Thread support

3.7.7. Virtual memory