ARM RealView Debugger User Manual

Download

RealView™ Debugger

Version 1.6

Essentials Guide

ARM DUI 0181B

RealView Debugger

Essentials Guide

Release Information

The following changes have been made to this document.

Change History

Date Issue Change

April 2002 A RealView Debugger 1.5 release.

September 2002 B RealView Debugger v1.6 release.

Proprietary Notice

Words and logos marked with brands and names mentioned herein may be the trademarks of their respective owners.

Neither the whole nor any part of the information contained in, or the product described in, this document may be adapted or reproduced in any material form except with the prior written permission of the copyright holder.

or ™ are registered trademarks or trademarks owned by ARM Limited. Other

The product described in this document is subject to continuous developments and improvements. All particulars of the product and its use contained in this document are given by ARM in good faith. However, all warranties implied or expressed, including but not limited to implied warranties of merchantability, or fitness for purpose, are excluded.

This document is intended only to assist the reader in the use of the product. ARM Limited shall not be liable for any loss or damage arising from the use of any information in this document, or any error or omission in such information, or any incorrect use of the product.

RealView Debugger Essentials Guide

Preface

About this book .............................................................................................. vi

Feedback ....................................................................................................... xi

Chapter 1 About RealView Debugger

1.1 RealView Debugger .................................................................................... 1-2

1.2 About the debugging environment .............................................................. 1-4

1.3 Debugging mode ......................................................................................... 1-6

1.4 Using the documentation suite .................................................................... 1-7

Chapter 2 Features of RealView Debugger

2.1 RealView Debugger v1.6 ............................................................................ 2-2

2.2 Getting more information online .................................................................. 2-5

Chapter 3 Getting Started with RealView Debugger

3.1 Starting RealView Debugger ....................................................................... 3-2

3.2 Connecting to a target ................................................................................. 3-4

3.3 Working with memory .................................................................................. 3-7

3.4 Loading an image ..................................................................................... 3-10

3.5 Debugging an image ................................................................................. 3-14

Contents

Chapter 4 Quick-start Tutorial

4.1 How to use the tutorial ................................................................................ 4-2

4.2 Setting up your first project ......................................................................... 4-3

4.3 Debugging with RealView Debugger ........................................................ 4-13

4.4 Working with custom panes ...................................................................... 4-27

4.5 More about projects .................................................................................. 4-29

4.6 Completing the tutorial .............................................................................. 4-35

Chapter 5 Ending your RealView Debugger Session

5.1 Saving the session ..................................................................................... 5-2

5.2 Disconnecting from a target ........................................................................ 5-5

5.3 Exiting RealView Debugger ........................................................................ 5-7

Chapter 6 RealView Debugger Desktop

6.1 About the desktop ....................................................................................... 6-2

6.2 Finding options on the main menu ........................................................... 6-11

6.3 Working with button toolbars .................................................................... 6-15

6.4 Working in the Code window .................................................................... 6-19

6.5 Editor window ........................................................................................... 6-22

6.6 Resource Viewer window ......................................................................... 6-23

6.7 Analysis window ....................................................................................... 6-26

Appendix A Configuration Files Reference

A.1 Overview ..................................................................................................... A-2

A.2 Files in the etc directory .............................................................................. A-3

A.3 Files in the home directory ......................................................................... A-5

Glossary

Preface

This preface introduces the RealView Debugger Essentials Guide. This guide shows you how to start using RealView Debugger to manage software projects and to debug your application programs. It contains the following sections:

• About this book on page vi

• Feedback on page xi.

Preface

About this book

Intended audience

RealView Debugger provides a powerful tool for debugging and managing software projects. This book contains:

• an introduction to the software components that make up RealView Debugger

• a tutorial to create a project and build an executable image

• a step-by-step guide to getting started, making a connection to a target, and loading an image to start a debugging session

• details about ending a debugging session

• a description of the RealView Debugger desktop

• a glossary of terms for users new to RealView Debugger.

This book is written for developers who are using RealView Debugger to manage ARM-targeted development projects. It assumes that you are an experienced software developer, and that you are familiar with the ARM development tools. It does not assume that you are familiar with RealView Debugger.

Using this book

This book is organized into the following chapters:

Chapter 1 About RealView Debugger

Read this chapter for an introduction to RealView Debugger. This chapter describes the underlying debugger concepts and explains terminology used in the rest of this book and the documentation suite.

Chapter 2 Features of RealView Debugger

Read this chapter for a description of the features of RealView Debugger, including details about those that are new in RealView Debugger v1.6.

Chapter 3 Getting Started with RealView Debugger

This chapter explains how to begin using RealView Debugger for the first time. This describes how to start RealView Debugger, make a connection, and load an image ready to start debugging.

Chapter 4 Quick-start Tutorial

Chapter 5 Ending your RealView Debugger Session

Chapter 6 RealView Debugger Desktop

Glossary An alphabetically arranged glossary defines the special terms used.

Typographical conventions

The following typographical conventions are used in this book:

italic Highlights important notes, introduces special terminology,

Preface

Read this chapter when you have access to a workstation. Follow the step-by-step instructions to gain some experience of using RealView Debugger to manage a project and to debug software.

This chapter describes how to end your RealView Debugger session and exit the debugger.

Read this chapter for a detailed description of the contents of the RealView Debugger desktop.

denotes internal cross-references, and citations.

bold Highlights interface elements, such as menu names. Denotes

ARM processor signal names. Also used for terms in descriptive lists, where appropriate.

monospace

Denotes text that can be entered at the keyboard, such as

commands, file and program names, and source code.

monospace

Denotes a permitted abbreviation for a command or option. The

underlined text can be entered instead of the full command or option name.

monospace italic

Denotes arguments to commands and functions where the

argument is to be replaced by a specific value.

monospace bold

Denotes language keywords when used outside example code.

Feedback

ARM Limited welcomes feedback on both RealView Debugger and its documentation.

Feedback on RealView Debugger

If you have any problems with RealView Debugger, please submit a Software Problem Report:

Preface

Feedback on this book

1. Select Help

→ Send a Problem Report... from the RealView Debugger main

menu.

2. Complete all sections of the Software Problem Report.

3. To get a rapid and useful response, please give:

• a small standalone sample of code that reproduces the problem, if applicable

• a clear explanation of what you expected to happen, and what actually happened

• the commands you used, including any command-line options

• sample output illustrating the problem.

4. Email the report to your supplier.

If you have any comments on this book, please send email to

errata@arm.com

• the document title

• the document number

• the page number(s) to which your comments apply

• a concise explanation of your comments.

General suggestions for additions and improvements are also welcome.

giving:

Preface

Chapter 1

About RealView Debugger

This chapter introduces RealView Debugger. It explains how the debugger provides a development environment for embedded systems applications using the ARM family of processors.

This chapter contains the following sections:

• RealView Debugger on page 1-2

• About the debugging environment on page 1-4

• Debugging mode on page 1-6

• Using the documentation suite on page 1-7.

About RealView Debugger

1.1 RealView Debugger

RealView Debugger enables you to debug your embedded application programs and have complete control over the flow of the program execution so that you can quickly isolate and correct errors.

1.1.1 RealView Debugger concepts and terminology

The following terminology is used throughout the RealView Debugger documentation suite to describe debugging concepts:

Debug target

A piece of hardware or simulator that runs your application program. A hardware debug target might be a single processor, or a development board containing a number of processors.

Connection The link between the debugger program and the debug target.

Single connection access

The base installation of RealView Debugger enables you to carry out debugging tasks in single-processor debugging mode, that is where there is only one target connection.

Multiprocessor access

RealView Debugger has been developed as a fully-featured debugger for working with multiprocessor debug target systems. Multiprocessor access enables you to maintain one or more connections to debug targets. Multiprocessor access is a separately licensed feature of RealView Debugger.

DSP RealView Debugger has been developed to provide full debugging

functions when working with a range of debug target systems including Digital Signal Processors (DSPs). DSP-based debugging is a separately licensed feature of RealView Debugger.

RTOS Operating systems provide software support for application programs

running on a target. Real Time Operating Systems (RTOSs) are operating systems that are designed for systems that interact with real-world activities where time is critical.

Multithreaded operation

RTOS processes can share the memory of the processor so that each can share all the data and code of the others. These are called threads. RealView Debugger enables you to:

• attach Code windows to threads to monitor one or more threads

• select individual threads to display the registers, variables, and code related to that thread

• change the register and variable values for individual threads.

About RealView Debugger

1.2 About the debugging environment

RealView Debugger uses a three-tier environment to debug application programs:

• the debugger software

• the debug interface layer, incorporating the execution vehicles

• the debug target.

RealView Debugger uses connection information to describe:

• how the debugger connects to the debug target

• information required to use that connection

• what kind of processor the target is using.

It might also include cached copies of processor registers or memory.

This approach means that you can switch between debug targets without having to start a second or third instance of the debugger program.

This section describes the RealView Debugger debugging environment:

• Components of RealView Debugger

• Debug target interface on page 1-5

• Persistence information on page 1-5.

1.2.1 Components of RealView Debugger

RealView Debugger comprises:

GUI The Graphical User Interface (GUI) gives access to the main features of

the debugger, command processing, and the Code windows.

Target Vehicle Server (TVS)

RealView Debugger maintains connections through the TVS and plugins that support each combination of target processor and execution vehicle. Using plugins, for example a board file (

*.bcd

files (

), enables RealView Debugger to enumerate advanced

*.brd

), and board-chip definition

information about your target hardware or processor.

The TVS contains the basic debugging functionality and forms most of the software making up RealView Debugger. If you have the appropriate licenses, the TVS provides multiprocessor debugging, supports multithreaded operation under an RTOS, and enables tracing and performance profiling.

RealView Connection Broker

1.2.2 Debug target interface

About RealView Debugger

RealView Connection Broker operates in two modes:

Local Operating as RealView Connection Broker, this runs on your

local workstation and enables you to access local targets.

Remote Operating as RealView Network Broker, this runs on a remote

workstation and makes specified targets on that workstation available to other workstations connected to the same network.

RealView Debugger works with either a hardware or a software debug target. An ARM development board communicating through Multi-ICE debug target system. ARMulator is an example of a software debug target system.

The debug target interface contains the execution vehicles that process requests from the client tools to the target. A debug interface might be a JTAG interface unit such as Multi-ICE, a simulator, or a ROM monitor.

1.2.3 Persistence information

RealView Debugger maintains persistence information to enable you to halt a debugging session and resume at a later date. This means that RealView Debugger can remember your working environment including:

• current target connections

• loaded images

• open projects

• desktop settings, for example pane selections and window positions.

is an example of a hardware

About RealView Debugger

1.3 Debugging mode

The base installation of RealView Debugger enables you to debug your images in single connection mode, that is, where there is only one connection.

If you have the appropriate license, you can also debug multiprocessor applications. RealView Debugger supports such multiprocessor debugging by maintaining connections to multiple debug targets through one or more Code windows. When working in multiprocessor debugging mode, you can use one Code window to cycle through the connected targets, or multiple Code windows to view different targets.

Multiprocessor debugging mode is a separately licensed feature of RealView Debugger and is described in detail in RealView Debugger v1.6 Extensions User Guide.

1.4 Using the documentation suite

The RealView Debugger documentation suite consists of five books:

• RealView Debugger v1.6 Essentials Guide

• RealView Debugger v1.6 User Guide

• RealView Debugger v1.6 Target Configuration Guide

• RealView Debugger v1.6 Command Line Reference Guide

• RealView Debugger v1.6 Extensions User Guide.

At the front of each book is a Preface describing how the contents are organized and how information is presented in the chapters. The following description explains how you might use the books:

1. You are recommended to read the chapters in this book, RealView Debugger v1.6 Essentials Guide, to start debugging your images and to learn how to use RealView Debugger quickly. This book describes the minimum needed for the new user.

2. For a comprehensive description of the features available in RealView Debugger, see RealView Debugger v1.6 User Guide. This describes, in detail, how to debug your images, how to work with projects, and how to configure RealView Debugger to customize your working environment. This book also contains examples of debugging software and details shortcuts, and tips, for the developer.

About RealView Debugger

3. RealView Debugger v1.6 Target Configuration Guide describes how to connect to targets, how to amend existing targets that are set up in the base installation, and how to customize your own targets.

4. If you want to use the RealView Debugger Command Line Interface (CLI) to control your debugging tasks, RealView Debugger v1.6 Command Line Reference Guide provides a detailed description of every CLI command and includes examples of their use.

5. If you have the appropriate licenses, you can access RealView Debugger extensions, for example multiprocessor debugging mode and Trace. These features are described in RealView Debugger v1.6 Extensions User Guide.

Refer to ARM FLEXlm License Management Guide for details on the license management system that controls the use of ARM applications.

See the installation notes delivered with your product for details on installing RealView Debugger.

About RealView Debugger

Chapter 2

Features of RealView Debugger

This chapter describes the features of RealView Debugger and highlights new functionality in RealView Debugger v1.6. It contains the following sections:

• RealView Debugger v1.6 on page 2-2

• Getting more information online on page 2-5.

Features of RealView Debugger

2.1 RealView Debugger v1.6

RealView Debugger v1.6 provides a range of features for the developer:

• Multi-core debugging

• OS awareness

• Extended Target Visibility (ETV)

• Advanced debugging facilities

• Trace, Analysis, and Profiling on page 2-3

• Project manager on page 2-4

• RealView Debugger downloads on page 2-4.

2.1.1 Multi-core debugging

RealView Debugger v1.6 provides a single debug kernel for mixed ARM and DSP debugging. The debugger provides full support for synchronized start and stop, stepping, and cross triggering of breakpoints.

2.1.2 OS awareness

RealView Debugger v1.6 enables you to:

• use RTOS debug including Halted System Debug (HSD)

• interrogate and display resources after execution has halted

• access semaphores and queues

• view the status of the current thread or other threads

• customize views of application threads.

2.1.3 Extended Target Visibility (ETV)

RealView Debugger v1.6 provides visibility of targets such as boards and SoC. Users can configure targets using board-chip definition files and preconfigured files are available:

• ARM family files provided as part of the installation

• customer/partner board files provided through ARM DevZone

2.1.4 Advanced debugging facilities

RealView Debugger v1.6 provides standard debug views and advanced debugging features:

• RealView Debugger supports variables of 64-bit type ‘long long’ throughout the user interface (new in v1.6).

Features of RealView Debugger

• There is now support for module statics, that is static variables of non-local scope, in the Call Stack pane (new in v1.6).

• RealView Debugger offers a powerful command-line interface and scripting capability that includes macros support, conversion from ARM AXD and armsd, and history lists to record previous actions.

• Users can access a console (headless debugger) driven from the command line or from scripts (new in v1.6).

• RealView Debugger includes an editing control called Tooltip Evaluation that provides hover-style evaluation in different code views (new in v1.6).

• RealView Debugger enables you to position a Memory pane to display a memory region based on the contents of a variable or register in the Register or Watch panes, or in the Src tab (new in v1.6).

• Users now have greater control over panes in the Code window and the debug views displayed. RealView Debugger provides the option of using a single Code window to display a wide range of data views during debugging (new in v1.6).

• Programming Flash modules are available as standard.

• Memory mapping is enabled if required.

• Colored memory views indicate the type of memory according to memory map settings.

2.1.5 Trace, Analysis, and Profiling

New in RealView Debugger v1.6, Trace, Analysis, and Profiling is enabled by a Trace debug license. Trace support is available for:

• ARM ETM v1.0 (ETM7 and ETM9), including On-Chip Trace

• ARM ETM v2.0 (ETM10) (beta)

• ARMulator ETM simulator

• AXYS Oak and TeakLite MaxSim simulators

• DSP Group On-Chip Trace (Oak and TeakLite)

• Motorola 56600 On-Chip Trace

• Intel XScale On-Chip Trace.

Trace and Profiling provides full trace support including simple and complex tracepoints and data filtering:

• viewing raw trace

• viewing code trace

• viewing data trace

Features of RealView Debugger

• viewing disassembly trace

• tracing of function calls

• the profiling of time spent in each function

• the ability to filter captured trace data by field

• the ability to sort captured trace data by field.

You can set tracepoints directly in the source-level view and/or the disassembly-level view. The same functionality is available in the Memory pane so that you can select regions in memory to trace, or trace a specific memory value when it changes.

2.1.6 Project manager

RealView Debugger v1.6 is a fully-featured Integrated Development Environment (IDE) including a project manager and build system.

New in v1.6, the project manager includes a Configuration Summary window to display the switch string passed to the compiler tools for build target configurations in the current project.

2.1.7 RealView Debugger downloads

ARM provides a range of services to support developers using RealView Debugger. Among the downloads available are OS awareness modules to support RTOS developers and enhanced support for different hardware platforms through technical information and board description files. See resources from ARM DevZone.

http://www.arm.com

to access these

2.2 Getting more information online

The full documentation suite is available online as DynaText, XML, and PDF files.

Features of RealView Debugger

Select Start

→ Programs → RealView Debugger v1.6 from the Windows Start

menu. From here:

• select Online Books to view the DynaText files

• select XML Documentation to see the XML version.

You can also access the DynaText files from the Help menu when RealView Debugger is running.

For a Typical installation, the DynaText and XML files are installed in:

C:\Program Files\ARM\Documentation

To access the XML documentation, you must use either:

• Netscape 6.2

• Mozilla 1.0.

The PDF files are installed, as part of the base installation, in

install_directory\PDF

Note

The DynaText, XML, and PDF files contain the same information.

Features of RealView Debugger

Chapter 3

Getting Started with RealView Debugger

This chapter gives step-by-step instructions to get started with RealView Debugger, including making a connection and loading an image for debugging. It also covers the main tasks that you might carry out in a debugging session.

It contains the following sections:

• Starting RealView Debugger on page 3-2

• Connecting to a target on page 3-4

• Working with memory on page 3-7

• Loading an image on page 3-10

• Debugging an image on page 3-14.

Getting Started with RealView Debugger

3.1 Starting RealView Debugger

To start your debugging session, you must complete the following steps:

1. Start RealView Debugger.

2. Connect to your chosen debug target.

3. Load an image for debugging.

This section describes how to start RealView Debugger and display the default Code window. It contains the following sections:

• Starting RealView Debugger

• The Code window.

3.1.1 Starting RealView Debugger

To start RealView Debugger:

1. Select Start

2. Select RealView Debugger from the menu.

The first time you run RealView Debugger after installation, it creates a unique working directory, in your RealView Debugger home directory, for you to store your personal files, debugger settings, and target configuration files. RealView Debugger then creates or copies files into this directory ready for your first debugging session.

If a user ID is not specified then RealView Debugger creates a general-purpose working directory called

3.1.2 The Code window

Starting RealView Debugger immediately after installation displays the default Code window to provide a starting point for all debugging tasks. The Code window is your main debugging and editing window. This is shown in Figure 3-1 on page 3-3.

menu.

→ Programs → RealView Debugger v1.6 from the Windows Start

install_directory\home\owner

Getting Started with RealView Debugger

Color Box Toolbars

Title bar Pane Management

File Editor pane

Pane title bar

Command line

Status line

controls

Output pane

Cursor location field

Build controls

Keyboard status

Processor State

Side pane

Figure 3-1 Code window

The appearance of the Code window depends on your licenses. For example, the base installation enables you to debug your images in single connection mode, that is where there is only one connection. If you are working in this mode, the title bar does not show

[Unattached]

For a full description of the contents of this window, see Chapter 6 RealView Debugger Desktop.

Getting Started with RealView Debugger

3.2 Connecting to a target

The next stage in your debugging session is to connect to your debug target. The base installation of RealView Debugger includes built-in configuration files to enable you to make a connection without having to modify any configuration details.

This section introduces target configuration and how to make a connection:

• Target configuration

• Working with connections

• Making a connection on page 3-5

• Setting connect mode on page 3-6.

3.2.1 Target configuration

RealView Debugger uses a board file to access information about the debugging environment and the debug targets available to you, for example how memory is mapped. See RealView Debugger v1.6 Target Configuration Guide for details of how to customize your targets.

You can start to use RealView Debugger with the default board file installed as part of the base installation without making any further changes.

3.2.2 Working with connections

RealView Debugger makes a distinction between target configuration, and how a target is accessed, that is the connection.

Select File

→ Connection → Connect to Target... from the main menu to display the

Connection Control window ready to make your first connection. This is shown in Figure 3-2 on page 3-5.

Getting Started with RealView Debugger

Check box to make a connection

RDI execution vehicle

Connections available for this vehicle

Execution vehicles

Figure 3-2 Connection Control window

This window dynamically details all your connections during a debugging session.

Note

If you are licensed to use RealView Debugger extensions, the Connection Control window includes tabs, not shown here. For example, in multiprocessor debugging mode, the window includes a Connect tab and a Synch tab.

3.2.3 Making a connection

If you have ADS 1.2 or RVCT 1.2 installed the top-level entry

ARM-A-RR

is the execution vehicle that supports connections to ARM RDI targets, as shown in Figure 3-2. Expand this to show the

ARMulator

connection that uses the ARMulator instruction set simulator.

The default configuration files installed as part of the base installation enable you to connect to an

ARM7TDMI

core using ARMulator on your local workstation. The

Connection Control window shows this default target connection.

Select the

ARM7TDMI

check box so that it is checked to make the connection.

With the connection established, your Code window is updated:

• the Code window title bar is updated with the name of the current connection

• the hyperlink in the File Editor pane changes to enable you to load an image

• the Output pane displays details of the connection

Getting Started with RealView Debugger

• panes are updated with debug information, for example the Register pane shows the core registers for the connected target.

Where you are always debugging code on the same target you can configure RealView Debugger to make the same connection automatically each time it starts. See the chapter describing connecting to targets in RealView Debugger v1.6 Target Configuration Guide for details of how to set this option.

RDI connection details

RealView Debugger displays RDI connection details in different tabs depending on the startup conditions and the Code windows you are using. Because this is the first time you connected to an RDI target from the default Code window, the startup connection details are displayed in the Log tab and the Cmd tab of the Output pane. In future debugging sessions, this information is displayed in the Cmd tab.

3.2.4 Setting connect mode

You can control the way a target processor starts when you connect. This is particularly useful when debugging multiprocessor debug targets and working with multiple threads. In single processor debugging mode, you might want to leave an image executing while RealView Debugger closes down and then restart at a later date.

If you are not connected, you can set connect mode when you make a new connection:

1. Select File

→ Connection → Connect to Target... to display the Connection

Control window.

2. Right-click on the connection entry and select Connect (Defining Mode)... from the Connection context menu.

3. Select the required state from the selection box.

The options listed depend on your execution vehicle.

4. Click OK to make the connection with the processor in the required state.

If you set connect mode from the Connection Control window, this temporarily overrides any setting in your target configuration file. See the chapter describing connecting in RealView Debugger v1.6 Target Configuration Guide for full details on setting connect mode for your debug target.

3.3 Working with memory

Before you load an image, you might have to define memory settings. This depends on the debug target you are using to run your image. For example, if you are using the default ARMulator to simulate an ARM processor, setting the value of top of memory is not appropriate.

Where appropriate, defining memory gives you full access to all the memory on your debug target. RealView Debugger enables you to do this in different ways, for example using an include file, or defining the memory map as part of your target configuration settings. These options are described in detail in RealView Debugger v1.6 User Guide.

Note

In the example in this section, you set up memory manually for the current session. Target memory settings defined in this way are only temporary and are lost when you exit RealView Debugger.

This section describes how to set up memory:

• Setting top of memory and stack values

• Setting top of memory for a session on page 3-8.

Getting Started with RealView Debugger

3.3.1 Setting top of memory and stack values

The top of memory variable is used to enable the semihosting mechanism to return the top of stack and heap. If you are not using an ARM-based target, or if your target does not use semihosting, this is ignored.

If you do not set these values, RealView Debugger uses default settings that are dependent on the debug target. For ARM processors the default value used for top of memory is

0x20000

When you first connect to an ARM-based target, RealView Debugger displays a warning message in the Cmd tab:

Warning: No stack/heap or top of memory defined - using defaults.

You can set permanent values for top of memory, stack, and heap, using the Connection Properties window. Configure your debug target and define these settings so that they are used whenever you connect. See the chapter describing configuring custom targets in RealView Debugger v1.6 Target Configuration Guide for an example of how to do this.

Getting Started with RealView Debugger

3.3.2 Setting top of memory for a session

If you are working with an appropriate debug target, you can set the value of top of memory on a temporary basis, that is for the current session, using the register.

Note

If you are using the default ARMulator to simulate an ARM processor, this is not a suitable target for setting top of memory in this way because top of memory is set from an ARMulator configuration file rather than from within RealView Debugger.

@top_of_memory

To set the value of top of memory for an ARM Integrator/AP board and

ARM940T

core,

using Multi-ICE:

1. Select Debug

→ Memory/Register Operations → Set Register... to display the

Interactive Register Setting dialog box.

2. Specify the register to be changed, for example

0x40000

, as shown in Figure 3-3.

@top_of_memory

Figure 3-3 Setting top of memory for session

, and enter the required value,

3. Click Set to update the register contents. The Log display is updated to record the change.

4. Click Close to close the dialog box.

The Debug tab, in the Register pane, displays the updated value, as shown in the example in Figure 3-4 on page 3-9.

Getting Started with RealView Debugger

Figure 3-4 Changed settings in the Register pane

The value of top of memory might be displayed in dark blue to show that it has changed since the last update.

If you set this value too low, loading an image to your target might generate a warning message in the Cmd tab:

Warning: No room for heap - could cause unpredictable behavior.

For full details on setting top of memory for an ARM-based target, see the chapter describing memory mapping in RealView Debugger v1.6 User Guide.

Getting Started with RealView Debugger

3.4 Loading an image

When you have connected to a suitably configured debug target you are ready to load your image for debugging:

• Loading an image

• What is shown in the title bar? on page 3-12

• Reloading an image on page 3-12

• Unloading an image on page 3-13.

3.4.1 Loading an image

In this example, you load the image

dhrystone.axf

installed as part of the base

installation. By default this is located in the ARM examples directory in

install_directory\examples\demo_ARM\dhrystone\Debug.

Select File → Load Image... to load your image. This displays the Load File to Target dialog box where you can locate the required image and specify the way in which it is loaded.

Note

Do not change any default settings in the Load File to Target dialog box.

Your Code window looks like Figure 3-5 on page 3-11.

Getting Started with RealView Debugger

Figure 3-5 Code window with an image loaded

In this Code window Tex t Co l or i n g is enabled by default and line numbering is turned on by selecting Edit

→ Editing Controls → Show Line Numbers.

When you load an image, the debugger:

• inserts the source filename, for the current context, in the File field at the top of the File Editor pane

• highlights the location of the Program Counter (PC) at the entry point with a red box

• moves the text insertion point to the current location of the PC

• updates the Code window panes as appropriate

• updates the Code window title bar to show the name of the project associated with the image

• displays the load line in the Cmd tab in the Output pane.

Getting Started with RealView Debugger

3.4.2 What is shown in the title bar?

The Code window title bar gives details of the connection and any processes running on your debug target. If you connect to a target and load an image, your title bar looks like the one shown in Figure 3-6.

In addition to the application icon, you can see (from left to right):

RVDEBUG Identifies the Code window. This changes to identify each new Code

window that you open, for example

(dhrystone) The project associated with the loaded image.

@ARM... The connection, including the target processor, the connection number,

and the execution vehicle.

[Unattached]

If you are working in multiprocessor debugging mode, this shows the attachment of the window to a specified connection. A Code window is unattached by default, shown by

Figure 3-6 Code window title bar

RVDEBUG_1

[Unattached]

, or

RVDEBUG_2.

If you float a pane, the pane title bar reflects the title bar of the calling Code window.

Note

The contents of your title bar might be different from the one shown in Figure 3-6 depending on your licenses, the current connection (if any), open projects and windows attachment. For a full description of the contents, see Chapter 6 RealView Debugger Desktop.

3.4.3 Reloading an image

During your debugging session you might have to amend your source code and then recompile. Select File

→ Reload Image to Target from the Code window to reload an

image following these changes.

Reloading an image refreshes any window displays and updates debugger resources.

3.4.4 Unloading an image

You do not have to unload an image from a debug target before loading a new image for execution. Display the Load File to Target dialog box and ensure that the Replace Existing File(s) check box is selected ready to load the next image.

However, you might want to unload an image explicitly as part of your debugging session, for example if you correct coding errors and then rebuild outside RealView Debugger. You can do this using the Process Control pane:

Getting Started with RealView Debugger

1. Select View

→ Pane Views → Process Control Pane from the default Code

window main menu.

2. Right-click on the

Image+Symbols

Image

entry, for example

dhrystone.axf

, to display the Image context menu.

, or on the

Load

entry,

3. Select Unload.

You can also unload an image by clicking on the check box associated with the

Load

entry so that it is unselected.

Unloading an image does not affect target memory. It unloads the symbols and removes most of the image details from RealView Debugger. However, the image name is retained.

Note

To remove image details completely, right-click on the

Image

entry in the Process

Control pane and select Delete Entry.

Getting Started with RealView Debugger

3.5 Debugging an image

Chapter 4 Quick-start Tutorial provides details on using the features of RealView Debugger with your images. This section summarizes how to start debugging with RealView Debugger:

• Getting started

• Code views on page 3-15

• Viewing target status on page 3-15.

3.5.1 Getting started

You can start debugging your image when you have completed the following steps:

1. Start RealView Debugger, see Starting RealView Debugger on page 3-2.

2. Connect to your target, see Making a connection on page 3-5.

3. Set top of memory, if appropriate, see Setting top of memory for a session on page 3-8.

4. Load your image, see Loading an image on page 3-10.

To start your debugging session:

1. Select Edit

→ Editing Controls → Show Line Numbers to display line

numbers.

This is not necessary but might help you to follow the examples.

2. Right-click in the first entry in the Memory pane,

, and select Set New

Start Address... from the context menu.

0x8008

3. Enter a value as the start address for the area of interest, for example

4. Click Set to confirm the setting and close the dialog box.

5. Click on the Src tab in the File Editor pane.

6. Set a simple, unconditional breakpoint at line 149 in

dhry_1.c, Proc_5();

, by

double-clicking on the line number.

If the line number is not visible, then double-click inside the gray area at the left of the required statement in the File Editor pane to set the breakpoint.

7. Set a watch by right-clicking on the variable

Int_1_Loc

at line 152 in

dhry_1.c

that it is underlined in red. Select Wat ch from the context menu.

Getting Started with RealView Debugger

8. To start execution either:

• Select Debug → Execution Control → Go (Start Execution) from the

main menu.

• Click the Go button on the Actions toolbar.

9. Enter the required number of runs, for example

10. Monitor execution until the breakpoint is reached.

11. Click Go again and monitor the programas execution continues.

3.5.2 Code views

Use the File Editor pane to view source code during your debugging session. In the example shown in Figure 3-5 on page 3-11, the File Editor pane contains three tabs:

•the Dsm tab enables you to track program execution in the disassembly-level

view

•the Src tab enables you to track program execution in the source-level view

• the file tab non-execution, view.

Click on the relevant tab to toggle between the different code views.

3.5.3 Viewing target status

The State group, on the Actions toolbar, shown in Figure 3-5 on page 3-11, enables you to see the current state of your debug target:

Unknown Shows that the current state of the target is unknown to the debugger. For

50000

dhry_1.c

shows the name of the current source file in the editing, or

example it might have been running when the connection was established or it might be disconnected.

Stopped Shows that the target is connected but any image loaded is not executing.

Running Shows that an image is executing. In this case, a running progress

indicator is also included.

Getting Started with RealView Debugger

Chapter 4

Quick-start Tutorial

This chapter provides a step-by-step tutorial using RealView Debugger to debug your images. All the tasks introduced in this chapter, and the RealView Debugger options used, are described in full in RealView Debugger v1.6 User Guide.

This tutorial contains the following sections:

• How to use the tutorial on page 4-2

• Setting up your first project on page 4-3

• Debugging with RealView Debugger on page 4-13

• Working with custom panes on page 4-27

• More about projects on page 4-29

• Completing the tutorial on page 4-35.

Quick-start Tutorial

4.1 How to use the tutorial

The tutorial starts by setting up a user-defined project to build an image for debugging. A user-defined project in RealView Debugger is not required for debugging, but it can provide a powerful aid to development. A project enables RealView Debugger to save your list of files, understand your build model, and maintain a record of your project-level preferences. In this tutorial, you build source files installed as part of the base installation and then debug the executable.

If you do not set up your own project, you can follow the tutorial using the supplied project, named project comes with a ready-built image, named

install_directory\examples\demo_ARM\dhrystone\Debug

4.1.1 Getting started

Begin by making a copy of the source files provided so that the tutorial is self-contained and the installed example files are untouched:

dhrystone.prj

, installed in the ARM examples directory. This sample

dhrystone.axf

, installed in the directory

1. Create a new directory called

install_directory\Tutorial

. This is the tutorial

project base directory.

2. Copy the required files, directory, that is

dhry.h, dhry_1.c

install_directory\examples\demo_ARM\dhrystone

, and

dhry_2.c

, from the examples

, into the new

tutorial directory.

Start your session so that you can follow the tutorial:

1. Start RealView Debugger, as described in Starting RealView Debugger on page 3-2.

2. Connect to the

ARM7TDMI

core processor using ARMulator, as described in Making

a connection on page 3-5.

You can complete the tutorial using the default files provided in the base installation. It is not necessary to change any of these files or to amend any configuration files.

4.2 Setting up your first project

RealView Debugger enables you to set up different types of user-defined projects:

• Standard project, including Compile/Assemble/Link

• Library project, including Compile/Assemble/Add to library

• Custom project, using your makefile or defining a no-build project to hold only image and properties

• Container project, composed of existing projects

• Copy, created by copying existing projects.

When you create a new project, you can also merge a saved auto-project to create a user-defined project.

For full details on creating different types of project, merging project settings, and accessing the project management features of RealView Debugger, see the chapter describing managing projects in RealView Debugger v1.6 User Guide.

This section takes you through the basic steps to set up a Standard user-defined project based on a set of example source files in the base installation. Follow this section to specify the default behavior for your C, C++, or assembly language programs, and build an image. This section describes:

• Defining your build tools on page 4-4

• Creating a new project on page 4-5

• Defining a Standard Project on page 4-5

• Viewing the project settings on page 4-7

• Setting up compiler options on page 4-7

• Project base directory on page 4-9

• Building the application on page 4-9

• Project files on page 4-10

• Closing the project on page 4-11.

Quick-start Tutorial

Note

This section introduces the Build-Tool Properties window and the Project Properties window to set up your first development project. There are full descriptions of the general layout and controls of these Settings windows in the RealView Debugger online help topic Changing Settings.

Quick-start Tutorial

4.2.1 Defining your build tools

RealView Debugger provides support for multiple toolchains. The debugger can locate your build tools automatically based on your environment variables or Registry entries. You can use the default build tools in every project you create or to build source files outside a project. However, you can override these settings for specific projects if required.

To see the default toolchain:

1. Select Project

→ Build-Tool Properties... from the Code window main menu.

This displays the Build-Tool Properties window shown in Figure 4-1.

Figure 4-1 Build-Tool Properties for a Typical installation

This shows a Typical installation where the ADS 1.2 toolchain is installed. If you have installed a Custom configuration your window looks different.

When you are working with the Build-Tool Properties window, click on an entry in the left or right pane to see a one-line text explanation in the Description field at the top of the window. Right-click on an entry and select Detailed Description... to see extended online help.

2. Select File

→ Close window to close the Build-Tool Properties window.

The first time you open the Build-Tool Properties window, RealView Debugger copies the file

install_directory\etc\genmake.loc

into your home directory ready for building operations during your debugging sessions. This is updated each time you amend your Build-Tool Properties window settings. You are warned before changes are saved in this file, but you can restore all entries to the installation defaults if required.

This is all that is required to start your first project.

Note

For details on how to change your build tools see Changing build tools on page 4-29.

4.2.2 Creating a new project

To set up the new project:

Quick-start Tutorial

1. Select Project

→ New Project... from the default Code window main menu.

This displays the Create New Project dialog box. The Project Base field might be prefilled with your RealView Debugger installation directory name as defined by your environment variable. You can override this.

2. Enter the project details as shown in Figure 4-2.

2. Click the folder icon and choose <Select Dir>

1. Enter project name

to locate the project base directory

3. Select Standard Project

4. Click OK

Figure 4-2 Creating a new project

RealView Debugger confirms that the specified project base directory exists. If the directory does not exist, you are given the option to create the directory ready for your project files.

4.2.3 Defining a Standard Project

When you close the Create New Project dialog box, RealView Debugger displays the Create Standard Project dialog box where you specify the:

• processor family and toolchain you are using

• source files to include in the build process

Quick-start Tutorial

• image name.

To define the project:

1. Click on the down arrow to specify the Processor Type that you are using to run

your images and the toolchain. In this example, that is

ARM-ADS

2. Click the folder icon to open the project base directory, defined previously, and

specify the source files to use in the build process. This displays the Select source files for Project dialog box where you can highlight one or more files. Use the Shift or Ctrl keys to select the files

dhry_1.c

and

dhry_2.c

3. Click Open and add the required source files to your project.

The Create Standard Project dialog box looks like Figure 4-3.

Figure 4-3 Create Standard Project dialog box

The Executable field contains the image name, that is

tutorial.axf

. Do not

change this so that you can follow the rest of the tutorial.

You do not have to change the project Description field.

4. Click OK to confirm your entries and close the Create Standard Project dialog

box.

Closing the dialog box creates the project settings file in the project base directory and opens the project into the debugger, shown in the Code window title bar.

4.2.4 Viewing the project settings

When you close the Create Standard Project dialog box, RealView Debugger displays the Project Properties window, shown in Figure 4-4.

The Project Properties window enables you to view project settings as defined in the project file. Click on the entry pane of the window. This displays the full path of the project settings file in the Description field at the top of the window. In this new standard project this is identified

install_directory\Tutorial\tutorial.prj

Figure 4-4 Project Properties window

...\tutorial.prj

at the top of the list of entries in the left

Quick-start Tutorial

Most entries in the Project Properties window are filled automatically from the Create Standard Project dialog box. You do not have to change any entries. Select File

→ Close

Window from the menu to close the Project Properties window.

When you examine your project settings and then close the Project Properties window, RealView Debugger regenerates the makefiles. The Build tab in the Output pane displays information about the generation process. You must wait for this to complete before making the next change. See Generated makefiles on page 4-32 for more details.

4.2.5 Setting up compiler options

For this tutorial, you must specify a preprocessor macro that is included as part of the

-D

build model. You have to set the

#if

processes

directives. You must set this to

compiler switch to specify how the compiler

MSC_CLOCK

to specify the C function library

to control how timing measurements are made.

Quick-start Tutorial

To do this you must change a project setting:

1. Select Project

→ Project Properties... from the default Code window main

menu to display the Project Properties window.

2. Click on

3. Double-click on

4. Right-click on

*COMPILE=arm

Preprocessor

Define

in the left pane to see the contents.

in the right pane to see the contents.

in the right pane and select Edit Value from the context

menu.

5. Type

MSC_CLOCK

and press Enter.

An asterisk is placed at the front of the setting to show that it has changed from the default.

6. Select File

→ Save and Close from the menu to close the Project Properties

window.

RealView Debugger regenerates the makefiles, as shown in the Build tab in the Output pane. You must wait for this to complete before making more changes.

Customizing your project

You can also make other changes to the project to specify the build model, for example to suppress compiler warning messages. To do this you must change a project setting:

1. Select Project

→ Project Properties... from the default Code window main

menu to display the Project Properties window.

2. Click on

3. Double-click on

4. Double-click on

5. Right-click on

*COMPILE=arm

in the left pane to see the contents.

Messages

Warning

Suppress_warnings

in the right pane to see the contents.

in the right pane and select enabled from the

context menu.

6. Select File

→ Save and Close from the menu to close the Project Properties

window.

RealView Debugger regenerates the makefiles, as shown in the Build tab in the Output pane. You must wait for this to complete before making more changes.

4.2.6 Project base directory

When the new project setup is complete, your project base directory is updated with the files required to manage your new project. These are the:

Quick-start Tutorial

• project file

• build target configuration directories

• generated makefiles for each build target configuration, for example

tutorial_Debug.mk

Note

The project source files do not have to be in the project base directory, although this is recommended for single-user, self-contained projects.

4.2.7 Building the application

If you have the ARM C compiler installed on your workstation, you can now build the application defined by the example project compiler installed, you can follow the steps to complete the tutorial but you cannot build an executable.

To build the executable for the example project:

1. Select Tools

2. If you have made any changes to the Project Properties, or to the Build-Tool Properties, you are prompted to rebuild all project files.

Click Ye s to confirm the rebuild.

tutorial.prj

Debug, Release

, and

DebugRel

tutorial.prj

. If you do not have the

→ Build... from the default Code window main menu.

The build, or rebuild, completes and RealView Debugger displays the Build tab, in the Output pane, to report successful completion. The Build tab also displays any errors or warnings generated during the build.

Quick-start Tutorial

4.2.8 Project files

The project you have just created is a single-user, self-contained project. This means that the project base directory now contains all the files associated with the tutorial project, as described in Table 4-1.

Table 4-1 Tutorial project files

Project contains

Debug directory

DebugRel directory

Release directory

Source files

Project file

Directory/filename Description

Debug

This area contains the object files and the executable ready for debugging or execution.

By default, configuration for this project. This means that this is the build target configuration that is built and loaded. Change this using the Project Properties window to view, and amend, the

CONFIGURATION

page 4-7.

DebugRel

Release

dhry_1.c

dhry_2.c

dhry.h

tutorial.prj

This area is empty.

The original source files and headers for the project. If any files have been edited, this area also includes the backup files (see Backup files on page 4-11).

The project settings file, using the project name specified when the project was created. This is identified as the first entry in the project settings, shown in Figure 4-4 on page 4-7.

If the project settings have been edited, this area also includes the backup file (see Backup files on page 4-11).

Debug

is specified as the active

group, shown in Figure 4-4 on

makefiles

tutorial_Debug.mk

tutorial_DebugRel.mk

tutorial_Release.mk

The makefiles generated by RealView Debugger for each build target configuration (see Generated makefiles on page 4-32).

The filenames and the rules can be changed in the project settings using the Project Properties

BUILD

window to view, and amend, the

group,

shown in Figure 4-4 on page 4-7.

Executable files

By default, the executable image created in this project is saved in

install_directory\Tutorial\Debug\tutorial.axf.

location or share it with others in your development team. You can load the image to a target processor without opening the project first. However, where you have created a user-defined project, it is recommended that you open the project first to load and debug the associated image. Opening the project enables you to access the project properties, save new settings, or make changes to the build model.

Backup files

If you make any changes to the project during your current session, a backup file is automatically created to enable you to recover from any accidental editing or to restore previous settings. Similarly, changing a source file in the File Editor pane also creates a backup file for safety. These files are given the

dhry_1.c.bak

4.2.9 Closing the project

The default Code window title bar shows the name of your new project:

, and

tutorial.prj.bak

Quick-start Tutorial

You can copy this file to another

.bak

extension by default, for example

, and are located in the project base directory.

RVDEBUG(tutorial) = @ARM7TDMI_0:ARM-A-RR [Unattached]

The project is automatically associated with the connection. This is called project binding. The project name,

tutorial

, is enclosed in round brackets to show that it is

bound to the connection.

Note

If several projects are open, the title bar shows the name of the active project. See the chapter describing managing projects in RealView Debugger v1.6 User Guide for details on controlling projects.

You can keep projects open while you are debugging. This might be useful to add new files to the project or if source files change. It is not necessary to keep the project open to debug the executable you just created.

To close the project, select Project

→ Close Project... from the Code window main

menu. Because there is only one open project, it closes immediately.

Quick-start Tutorial

Note

If you have loaded the image created by your project, RealView Debugger gives you the option to unload the image. Unload the image associated with the project to avoid the creation of an auto-project (see Working with images on page 4-16 for more details).

The Code window title bar shows that the project is no longer open.

Any files displayed in the File Editor pane remain after the parent project closes. To close the file shown on the top tab, either:

• select File

→ Close from the Code window main menu

• right-click on the file tab and select Close from the context menu.

If any file has been edited, you are warned and given the option to save the file before it closes. A backup copy of the previous version is saved by default, unless you have changed this in your workspace.

If you have several files displayed in the File Editor pane, the next tab is brought to the top and you can then close this one in the same way.

In the next part of the tutorial you use the debugging features of RealView Debugger to load an executable image and monitor execution. It is not necessary to exit RealView Debugger at this stage.

4.3 Debugging with RealView Debugger

This section gives you step-by-step instructions to carry out some basic debugging tasks. These examples use the sample project RealView Debugger base installation. If you prefer, you can use the executable built in Setting up your first project on page 4-3 and saved in the tutorial project,

If you are not licensed to use RealView Debugger extensions, your Code window might look different to the one shown in the rest of this tutorial. This does not affect the tutorial.

This section contains the following subsections:

• Getting started

• Basic debugging tasks on page 4-14

• Using breakpoints on page 4-22.

4.3.1 Getting started

Complete these steps so that you can follow the rest of the tutorial:

1. Start RealView Debugger, as described in Starting RealView Debugger on page 3-2.

dhrystone.prj

Quick-start Tutorial

, supplied as part of the

tutorial.prj

2. Connect to the

ARM7TDMI

core processor using ARMulator, as described in Making

a connection on page 3-5.

3. Select Project

install_directory\examples\demo_ARM\dhrystone\dhrystone.prj

→ Open Project... to open the required project, for example

4. Click on the hyperlink in the File Editor pane to load the associated image, for example

install_directory\examples\demo_ARM\dhrystone\Debug\dhrystone.axf

This location has been derived automatically from the project information.

The default Code window title bar shows the name of your open project:

RVDEBUG(dhrystone) = @ARM7TDMI_0:ARM-A-RR [Unattached]

Note

If you are using the supplied source files, RealView Debugger might warn that the source is more recent than the executable. This message can be ignored.

Quick-start Tutorial

4.3.2 Basic debugging tasks

In your debugging session RealView Debugger enables you to examine registers, memory contents, and variables:

• Displaying register contents

• Changing register contents on page 4-15

• Process control on page 4-16

• Displaying memory contents on page 4-17

• Displaying variables on page 4-19

• Tooltip evaluation on page 4-19

• Using the call stack on page 4-20

• Using browsers and lists on page 4-21

• Setting watches on page 4-21.

Displaying register contents

To display register contents for the loaded image:

1. Select View

→ Pane Views → Registers from the default Code window to

display the Register pane. It looks like the example in Figure 4-5.

Pane Menu, click here to work with pane data

Select a tab to view target details

Pane Content menu, click here to change the pane view

Figure 4-5 Register pane

Quick-start Tutorial

The Register pane displays tabs appropriate to the target processor running your image and the target vehicle used to make the connection. For the

ARM7TDMI

core

using ARMulator, the pane includes the Core tab, showing the base registers for the connected target processor, and the Debug tab, showing internal debugger variables. For full details on the contents of this tab see the chapter describing monitoring execution in RealView Debugger v1.6 User Guide.

2. Click the Pane menu and select Show Enumerations as Values from the available options. This displays the register contents as values rather than enumerated strings. The Register pane is refreshed.

3. Click the Pane menu and unselect Show Enumerations as Values.

Changing register contents

To change the contents of registers:

1. Click on the Core tab in the Register pane.

2. Right-click in the Mode field of the Current Program Status Register (CPSR) register (

SVC

) to display the context menu shown in Figure 4-6.

Figure 4-6 Changing register contents

3. Select Set Enumeration.... This opens a selection box where you can specify the

context-sensitive value to modify the selected register entry.

4. Select

FIQ

from the list of available options and click OK to change the Mode

field of the CPSR from ARM banked registers,

SVC (0013 R8

) to

R14

, shown in the pane. Similarly, if you are in

mode and you change the contents of

) change to match.

(

FIQ (0011

R13

in the

). This updates the contents of the

SVC

bank (SP), the contents of

R13

Quick-start Tutorial

In this example, the value can also be changed by selecting FIQ from the list of values from the context menu shown in Figure 4-6 on page 4-15.

Process control

To display the Process Control pane:

1. Select View

→ Pane Views → Process Control Pane from the default Code

window. It looks like the example in Figure 4-7.

Figure 4-7 Process Control pane

The Process tab shows details about your current process. If you are debugging a single process application, this is the same as viewing the processor details. In this example, you can identify the target processor and see details about your project and the loaded image.

2. Right-click on an entry in this pane, for example

dhrystone.axf

, and select

Properties from the context menu. This displays a text box giving more information on the chosen item.

Working with images

Where you have created a user-defined project, it is recommended that you open this first to load and debug the associated image, or images. This enables you to access the project properties, save new settings, or make changes to the build model. In this example, the user-defined project is open so project settings have been used to populate entries in the Process tab.

When an image is loaded directly to a debug target, RealView Debugger checks to see if an auto-project exists for that image in the same location. Where no auto-project exists, RealView Debugger creates an in-memory project to use in the current session.

Quick-start Tutorial

An auto-project is a custom, image control, project that holds project settings where the build model is unknown. You can view these settings using the Project Properties window. Using an auto-project enables you to amend and save image load parameters where you do not have a user-defined project or where you have no control over the build model. You also have the option to use the saved auto-project as the basis of a user-defined project.

Note

If you load an image built as part of a user-defined project without opening the project you cannot access all the project properties because these are unknown to RealView Debugger. In this case, RealView Debugger creates an in-memory project, or uses the saved auto-project file.

See the chapter on working with images in RealView Debugger v1.6 User Guide for details on using auto-projects in RealView Debugger.

Displaying memory contents

To display an area of memory:

1. Select View → Pane Views → Memory from the default Code window to display the Memory pane.

2. Right-click on an entry

to display the context menu shown in Figure 4-8.

Figure 4-8 Memory address menu

3. Select Set New Start Address... to display the address prompt box.

4. Enter

0x8000

as the new start address and click Set to confirm your choice and

close the prompt.

5. Click on the Memory pane Pane menu and select Show ASCII to display the updated memory contents, shown in Figure 4-9 on page 4-18.

Quick-start Tutorial

Figure 4-9 Updated memory contents

Click on the Pane menu again and select Set Number of Columns to show... to

choose how many columns are used in the memory display, for example

. If you do not specify the number used (or specify zero), RealView Debugger displays as many columns as it can fit into the pane.

6. Click the Go button on the Actions toolbar to execute the image. Enter a large

50000

number of runs, for example

7. Click Stop Execution to stop the program before it finishes and view the updated

memory contents, shown in dark blue in the Memory pane.

At the next update, memory contents might be colored light blue. This shows that they changed at the previous update. Seeing the update depends on the memory contents that you can see and where execution stops.

8. Click on the file tab for the source file

9. Double-click on

scanf

so that it is highlighted and then drag it to the Memory

dhry_1.c

and locate

scanf

at line 124.

pane where you can drop it into the display. This is a quick way to display a chosen location in the Memory pane,

Use the Pane menu, or right-click in an address entry in the Memory pane, to select the display format and modify the address range of the memory area that you want to see.

You can change memory contents displayed in the Memory pane using in-place editing.

Displaying variables

To display the value of a variable from your source code:

Quick-start Tutorial

1. Select File

→ Reload Image to Target to reload the image.

2. Click the Go button on the toolbar to execute the image for a number of runs, for

5000

example

3. Select the required variable in the current context, for example click on the file tab for the source file

Ptr_Glob

structassign (*Ptr_Val_Par->Ptr_Comp, *Ptr_Glob);

in the expression:

dhry_1.c

and move to line 301. Highlight the variable

4. Right-click to display the Source Variable Name menu, shown in Figure 4-10.

Figure 4-10 Source Variable Name menu

5. Select Print to view the value of the chosen variable in the current context. This is displayed in the Cmd tab of the Output pane.

6. Select View Memory At Value to display the memory view at this location.

Tooltip evaluation

Use Tooltip Evaluation to see hover-style evaluation when you hold your mouse pointer, for two seconds, over a variable in the Src tab, or a register in the Dsm tab.

This option is enabled by default. Select Edit

→ Editing Controls → To ol ti p

Evaluation to disable this for the current Code window.

Quick-start Tutorial

Using the call stack

The Call Stack pane enables you to follow the flow of your program by examining the current status of functions and variables. This pane shows you the path that leads from the main entry point to the currently executing function.

To monitor your execution path:

1. Select View

→ Pane Views → Call Stack from the default Code window to

display the Call Stack pane.

2. Select File

→ Reload Image to Target to reload the image.

3. Click the Go button on the Actions toolbar to execute the image. Enter a large

number of runs, for example

50000

4. Click Stop Execution to stop the program before it finishes.

The Call Stack tab, in the Call Stack pane, displays details of the functions currently on the stack and awaiting execution.

5. Right-click on an entry in the Call Stack pane, to see the Function context menu.

This menu enables you to carry out operations on the chosen function in the stack, for example to scope to that function.

6. Click on the Locals tab in the Call Stack pane. This displays a list of the variables

that are local to the current function, shown in the example in Figure 4-11.

Figure 4-11 Local variables in the Call Stack pane

If a variable is a structure or an array, a plus sign is added to the entry in the Call Stack pane. You can click on this to expand the variable to see all elements of the structure or array.

7. Right-click on an entry in the Locals tab, to see the Va ri ab l es context menu.

8. Click on the Statics tab, to see non-local variables, that is module statics.

Quick-start Tutorial

Using browsers and lists

RealView Debugger provides lists browsers and lists to help with debugging tasks. These enable you to search through your source files to look for specific structures and to monitor their status during program execution. Browsers are available for:

• project modules and files

• functions

• variables

• C++ classes.

To access the browsers:

1. Select Find from the default Code window main menu to display the Find menu.

The list of available lists is at the bottom of the menu.

2. Select Function List... to display the Function List.

3. Highlight the required function in the list.

4. Use the controls in the dialog box to:

• view details about the function

• perform actions, for example scoping to the function or setting a breakpoint

• display the source-level view or the disassembly-level view.

5. Click Close to close the Function List.

See the chapter describing working with browsers in RealView Debugger v1.6 User Guide for full details on using browsers and lists.

Setting watches

Watches monitor variables during execution of your image.

To set a series of watches and to monitor their value during execution of the image:

1. Select File

→ Reload Image to Target to reload the image.

2. Click the Go button on the Actions toolbar to execute the image. Enter a large number of runs, for example

50000

3. Click Stop Execution to stop the program before it finishes.

4. Select View

→ Pane Views → Watch from the default Code window to display

the Watch pane.

5. Highlight the required variable in the current context.

Quick-start Tutorial

6. Right-click to display the Source Variable Name menu, shown in Figure 4-10 on

7. Select Watc h from the menu. This adds the chosen variable to the Watch pane and

8. Click the Go button on the toolbar to execute the image.

9. Click the Stop Execution button to stop the program before it finishes.

4.3.3 Using breakpoints

Breakpoints are specified locations where execution should stop. The breakpoint is triggered either by:

• execution reaching the specified address

page 4-19.

displays the current value, if known.

With the processor halted, monitor changes in the variables in the Watch pane. Depending on where you halted execution, values that changed at the last pane update are displayed in dark blue. Values that changed at a previous pane update are displayed in light blue.

You can remove variables from the Watch pane. Highlight the entry and press Delete. The values list is refreshed after the entry has been removed.

• data values at the specified location, in the current context, changing or becoming equal to a particular value.

Breakpoints let you suspend program execution when the program accesses specific memory locations, variables, or functions. You can define conditions that are tested or qualify the breakpoint to define when execution stops. This section describes:

• Breakpoint types

• Actions and qualifiers on page 4-23

• Managing breakpoints on page 4-25.

Breakpoint types

RealView Debugger enables you to use different types of breakpoint when you are debugging your image. Breakpoint types are dependent on the hardware support provided by your debug target:

Simple These breakpoints enable you to test address-specific data values. These

breakpoints can be either hardware or software breakpoints.

Simple breakpoints are supported by all ARM processors.

Quick-start Tutorial

Complex These breakpoints use advanced hardware support on your target

processor, or as implemented by your simulator software.

Check your hardware characteristics, and your vendor-supplied documentation, to determine the level of support for complex breakpoints.

RealView Debugger provides the Set Address/Data Break/Tracepoint dialog box that enables you to specify your breakpoint details and to define how execution continues after the breakpoint triggers. This is described in full in the chapter describing working with breakpoints in RealView Debugger v1.6 User Guide.

Viewing your hardware characteristics

To see your hardware support for complex breakpoints select Debug → Complex Breakpoints

→ Show Break Capabilities of HW... from the default Code window

main menu. This displays an information box describing the support available for your target processor.

Note

If you are using the default ARMulator to simulate an ARM processor, this does not support the use of complex breakpoints.

Actions and qualifiers

Breakpoints are also classified depending on the action taken by RealView Debugger to trigger the breakpoint:

Unconditional

The program stops if execution reaches the specified location.

Conditional The program stops if execution reaches the specified location and one or

more predefined conditions are met. The conditions that must be satisfied can be defined based on data values or on counters.

Setting conditional breakpoints

Use the Set Address/Data Break/Tracepoint dialog box to set a simple, conditional breakpoint:

1. Select File

2. Select File

→ Reload Image to Target to reload the image.

→ Open... and open the source file

dhry_2.c

so that it is displayed in

the File Editor pane.

3. Scroll through the source file

dhry_2.c

and locate the line:

Quick-start Tutorial

81 }/* Proc_7 */

4. Right-click on the line number and select Set Break... from the context menu to display the Set Address/Data Break/Tracepoint dialog box shown in Figure 4-12.

If the line number is not visible, then right-click inside the gray area at the left of the required statement or on the line of code to display the context menu.

Figure 4-12 Set Address/Data Break/Tracepoint dialog box

Because you are using ARMulator to simulate an

ARM7TDMI

processor, the breakpoint types available are limited. A software instruction breakpoint is highlighted and the Location field is prefilled.

Depending on the Break/Tracepoint Type you select, the Location or the Value Match field might be unavailable. In this case, the field is grayed out.

5. Click New to specify the Qualifiers or conditions for the new breakpoint. This displays the New Qualifiers menu.

6. Select When Expression True... from the menu.

7. Enter the condition

Int_Glob==5

in the prompt.

8. Click Set to confirm the entry and close the prompt box.

The breakpoint condition is shown in the Qualifiers group display.

Quick-start Tutorial

9. Click OK to close the Set Address/Data Break/Tracepoint dialog box. The code

view is updated and a yellow disc appears to show that a conditional breakpoint has been set. The Cmd tab, in the Output pane, shows the RealView Debugger command used to set the breakpoint.

10. Click the Go button on the toolbar to execute the image. When the breakpoint is reached, execution stops and RealView Debugger displays a message in the Cmd tab of the Output pane to identify the point in the source code where the program stopped.

11. Click Go again to complete execution.

If you try to set a breakpoint on a non-executable line, RealView Debugger looks for the first executable line immediately following and places the breakpoint there. If the lines preceding the breakpointed instruction are comments, declarations, or other non-executable code, they are marked with black, downward pointing arrows. Lines marked in this way are regarded as part of the breakpoint. You cannot place two unconditional breakpoints on the same line, or on lines marked by the downward pointing arrows.

Managing breakpoints

To display the current breakpoint details:

1. Select View

→ Pane Views → Break/Tracepoints Pane from the default Code

window to display the Break/Tracepoints pane, shown in Figure 4-13.

Figure 4-13 Break/Tracepoints pane

This shows the conditional breakpoint you set previously, the address, and the RealView Debugger command used to create it. The check box is selected to show that the breakpoint is enabled.

2. Right-click anywhere on the breakpoint entry, in the Break/Tracepoints pane, to display the Break/Tracepoints menu.

From here, you can examine the breakpoint, edit or copy it, or disable it so that it is ignored the next time the program runs.

Quick-start Tutorial

You can remove entries from the Break/Tracepoints pane. Highlight the entry and select Clear from the Break/Tracepoint menu. The breakpoints list is refreshed after the entry has been removed.

4.4 Working with custom panes

If you are working in single-processor debugging mode, the default Code window gives you full access to your code views and all debugging operations. However, you might want to display multiple memory views for your debug target, or to view multiple panes at the same time. You can customize your desktop to get the views you want.

See Chapter 6 RealView Debugger Desktop for:

• details on the contents of the Code window

• full details on working with panes

• a description of the controls used in the rest of this section.

This section describes:

• Customizing your debug views

• Hiding panes on page 4-28.

4.4.1 Customizing your debug views

To set up the default Code window and customize the panes:

Quick-start Tutorial

1. Select View

→ Pane Views → Registers to view the Register pane, Core tab.

2. Click the Pane Content menu in the Register pane and select Switch Side to reposition the pane.

3. Select View

→ Pane Views → Call Stack to view the Call Stack pane, Call

Stack tab.

4. Click the Pane Content menu in the Call Stack pane and select Process Control to change the debug view.

Your default Code window looks like the example shown in Figure 4-14 on page 4-28.

Quick-start Tutorial

Figure 4-14 Example Code window

In Figure 4-14, line numbering is turned on by selecting Edit → Editing Controls → Show Line Numbers.

4.4.2 Hiding panes

You can use the Pane Management controls, on the Actions toolbar, to define which panes are visible in your Code windows, for example click Hide Bottom Pane from the Pane Management controls to hide the Output pane in the Code window shown in Figure 4-14.

4.5 More about projects

This section gives more detail on how to manage your projects in RealView Debugger and enables you to make more changes to the tutorial project, if required. It contains the following sections:

• Changing build tools

• Viewing build settings on page 4-30

• Adding files to your project on page 4-31

• Generated makefiles on page 4-32

• Building an application on page 4-33

• Finding build errors on page 4-33.

4.5.1 Changing build tools

You can specify the location of a default toolchain to use when building applications and images. You can set up a tools location at any time but it is recommended that you do this before creating your first project.

To set up a different build tools location:

Quick-start Tutorial

1. Select Project

→ Build-Tool Properties... from the Code window main menu.

This displays the Build-Tool Properties window shown in Figure 4-15.

Figure 4-15 Setting the build tools location for a Custom installation

2. Double-click on a group, in the left pane, to specify the toolchain to use. This displays the contents in the right pane. This is shown in the example in Figure 4-15.

Quick-start Tutorial

3. Right-click on the

Tool_dir

entry and select Edit as Directory Name from the

context menu. This displays the Enter New Directory dialog box where you can specify the location of the toolchain you want to use. This forms the base directory for the executable tools for this family of processors.

4. Select File

→ Save and Close to save your changes and close the Build-Tool

Properties window.

If you have a common linker command file or your own runtime libraries, for example kernel, ASIC (Application Specific Integrated Circuit), and peripheral drivers, you can specify them for all projects at this stage. To make the changes:

1. Select Project

2. Double-click on the

3. Double-click on

4. Right-click on

→ Build-Tool Properties... from the Code window main menu.

*PROC=ARM_ADS

C_code

in the right pane.

Def_cmd_file

group in the left pane to expand the tree.

and select Edit as Filename from the context menu.

This displays the Enter New Filename dialog box where you can specify the location of the linker command file.

5. Right-click on

Def_lib_cmd_file

and select Edit as Filename from the context

menu. This displays the Enter New Filename dialog box where you can specify the location of the librarian command file.

6. Select File

→ Save and Close to save your changes and close the Build-Tool

Properties window.

4.5.2 Viewing build settings

The Project Properties window includes another window that enables you to see a summary of the compiler, assembler, and linker command lines generated by the current project settings. This window provides a read-only display of the command-line switches for each of the current build target configurations.

To view your current compiler settings:

1. Select Project

install_directory\examples\demo_ARM\dhrystone\dhrystone.prj

2. Select Project

3. Click on ARM C compiler (

4. Select View

→ Open Project... to open the required project, for example

→ Project Properties... to display the Project Properties window.

*COMPILE=arm

in the left pane of the Project Properties window to see the

armcc

) command line.

→ Configuration Summary to display the Configuration Summary

window, shown in Figure 4-16 on page 4-31.

Quick-start Tutorial

Figure 4-16 Configuration Summary window

This window contains one tab for each of the build target configurations specified for the chosen group, that is

Debug, Release

, and

DebugRel

If you change a compiler setting, the Configuration Summary window updates automatically.

5. Click on

*ASSEMBLE=arm

ARM assembler (

6. Select File → Close Window from the menu to close the Project Properties

window without making any changes.

If you select an entry in the left pane that does not contain compiler, assembler, or linker settings, for example message:

NO COMPILE, ASSEMBLE or BUILD group is selected.

If you close the Project Properties window without closing the Configuration Summary window first, RealView Debugger displays both windows automatically when you next open the Project Properties window in this session.

4.5.3 Adding files to your project

You can change your project properties at any time after creation, for example you can add source files, add object files, delete files, or exclude files from the build.

Adding source files to a project

With a project open, you can add source files and so update the project properties automatically. There are two ways to do this, depending on the location of the file you want to add:

in the left pane of the Project Properties window to see the

armasm

) command line in the Configuration Summary window.

*CONFIGURATION

, the Configuration Summary window displays the

• Select Project

→ Add This File to Project to add the file currently displayed in

the topmost tab in the File Editor pane to the list of project sources.

• Select Project

→ Add Files to Project... to display the Select File(s) to Add

dialog box where one or more files can be added to the project.

Quick-start Tutorial

Make sure that the Project Properties window is not open when adding source files from the Project menu. Also ensure that any rebuild is complete.

Adding object files to a project

If you want to add object files to your project you must use the Project Properties window, shown in Figure 4-4 on page 4-7. For full details of how to do this, see the chapter describing managing projects in RealView Debugger v1.6 User Guide.

4.5.4 Generated makefiles

Note

RealView Debugger uses the template

***

The

is replaced depending on your default processor family and toolchain. In this

gen_***.mk

tutorial project, RealView Debugger uses the template directory

install_directory\etc

to generate makefiles for all projects.

gen_arx.mk

located in the

The makefiles are generated when you do any of the following:

• create a new project

• edit and save an existing project

• edit and close the Build-Tool Properties window

• update the Project Properties window, for example doing an edit and save.

Details about the makefile generation process are given in the Build tab of the Output pane.

Note

You can also force the makefiles to be regenerated if necessary. This is explained in the chapter describing managing projects in RealView Debugger v1.6 User Guide.

Viewing the makefile

You can view the makefile that is generated using RealView Debugger, for example either:

• Select File

→ Open... from the default Code window main menu to display the

Select File to Open dialog box where you can locate the makefile and open it in the File Editor pane for viewing.

• Open Windows Explorer and navigate to the project base directory. Drag the makefile and drop it into the File Editor pane where it opens for viewing.

Do not make any changes to the generated makefiles as these are overridden when the files are next generated. It is recommended that you always use the Project Properties window to set up your preferences.

4.5.5 Building an application

To build the executable for a project:

Quick-start Tutorial

1. Select Project

2. Select Tools

→ Open Project... to open the required project.

→ Build... from the default Code window main menu.

3. If you have made any changes to the Project Properties, or to the Build-Tool Properties, you are prompted to rebuild all project files.

Click Ye s to confirm the rebuild.

The build, or rebuild, completes and RealView Debugger displays the Build tab, in the Output pane, to report successful completion. If the build process fails, the Build tab reports any errors.

In the build process:

• RealView Debugger builds the executable as a background task. This is shown by an exclamation mark in the Build tab. You can still submit commands or use RealView Debugger during the build.

•The

Debug

build target configuration is built by default.

-f

flag forces the

make

utility to read the specified file,

tutorial_Debug.mk

, as

a makefile.

•The

all

flag forces a rebuild of all project files.

You can click the Stop Build button on the Actions toolbar to halt a build.

4.5.6 Finding build errors

Errors in your source code always result in a failed build and the executable is not built. In these cases, you must locate and correct these errors. RealView Debugger includes features to help locate errors in the source files when the build process fails.

Build error reporting

The error reporting system:

• highlights the error text in the Output pane Build tab

• scrolls the file in the File Editor pane to the location of the error

Quick-start Tutorial

• places a blue pointer at the error

• places the flashing text cursor in the source file after the error.

If RealView Debugger finds more than one error, it highlights the first error. Select

To ol s

→ Next Line/Error to move through the error list after correcting an error.

Alternatively, you can go directly to an error by double-clicking on the line number, shown in the Output pane Build tab.

4.6 Completing the tutorial

Because the tutorial project is self-contained, follow these steps if you want to tidy up

install_directory\Tutorial

the

4.6.1 Removing tutorial project files

To remove the files associated with the project:

Quick-start Tutorial

directory after you close down RealView Debugger.

1. Delete the project file

2. Delete the build target configuration directories, for example:

install_directory\Tutorial\Debug

3. Delete the target generated makefiles, for example:

install_directory\Tutorial\tutorial_Debug.mk

4. Delete any backup files with the

The project is now deleted from your workstation.

4.6.2 Removing the tutorial project

If you do not want to keep the files copied at the start, or the executable image, you can delete the entire tutorial project base directory, that is

install_directory\Tutorial\tutorial.prj

.bak

extension.

install_directory\Tutorial

Quick-start Tutorial

Chapter 5

Ending your RealView Debugger Session

This chapter describes how to end your debugging session and how to exit RealView Debugger. It contains the following sections:

• Saving the session on page 5-2

• Disconnecting from a target on page 5-5

• Exiting RealView Debugger on page 5-7.

Ending your RealView Debugger Session

5.1 Saving the session

RealView Debugger stores session details by default when you end your debugging session. Saving the session enables you to start your next session using the same working environment, connecting automatically to a specified target, and opening projects.

RealView Debugger stores session details using your:

• Workspace

• Startup file on page 5-3

• History file on page 5-3

• Settings options on page 5-4.

5.1.1 Workspace

The RealView Debugger workspace is used for visualization and control of default values, and storing persistence information. It includes:

• user-defined options and settings

• connection details

• details about open windows and, in some cases, their contents

• user-defined projects or auto-projects to open on startup.

The first time that you run RealView Debugger, the default workspace settings file

rvdebug.aws

is created in your home directory. Each time you start RealView Debugger after this, it loads this workspace automatically, but you can change the defaults or create a new workspace of your own.

To change your workspace, select File

→ Workspace from the main menu to display

the Worksp ace menu shown in Figure 5-1.

Figure 5-1 Workspace menu

Alternatively, you can run RealView Debugger from the command line without loading a workspace, for example:

"C:\Program Files\ARM\RealView Debugger v1_6\bin\rvdebug.exe" -aws=-

5.1.2 Startup file

Ending your RealView Debugger Session

For full details on amending your workspace settings to define how session details are saved and where, see the chapter describing configuring workspaces in RealView Debugger v1.6 User Guide.

The startup file contains a record of your last debugging session including:

• images and files loaded into RealView Debugger

• the list of all recently loaded files, for example source files

• the recent workspaces list

• the workspace to be used on startup, if specified

• workspace save and restart settings

• user-defined menu settings, for example pane format options

• the recent projects list.

5.1.3 History file

By default, this file is called

rvdebug.sav

. The first time you close down RealView Debugger after performing an operation in the default Code window a startup file is created in your home directory. From this point on, every time you close down RealView Debugger and exit, this startup file is updated. You can specify a different startup file, or none at all, by changing your workspace settings.

The history file contains a record of:

• commands submitted during a debugging session, for example, changing

directory, loading source files, loading an image for execution, or setting breakpoints

• data entries examined in the Code window during debugging

• the Set Directory and Set File lists used in Open dialog boxes, for example Select

File to Open, or Select File to Include Commands from

• personal favorites such as variables, data values, watches, and breakpoints.

The first time you run RealView Debugger, carry out an operation, and then exit, a history file is created in your home directory. By default, this is called

exphist.sav

and

is updated at the end of all subsequent debugging sessions.

Ending your RealView Debugger Session

5.1.4 Settings options

By default, RealView Debugger writes your current settings to your startup file ready for re-use, saves your current workspace, and reloads this workspace at the next start-up.

To change these defaults, select File

→ Wor kspac e from the main menu to display the

Workspa ce menu shown in Figure 5-1 on page 5-2.

At the bottom of this menu are your current settings options. Enable or disable the required options to decide how your next RealView Debugger session starts. For example, if Same Workspace on Startup is unselected, RealView Debugger does not use the current workspace at the next start-up. This means that, unless another workspace is specified on the command line, RealView Debugger opens the default workspace.

These options are saved in your startup file when you exit RealView Debugger.

5.2 Disconnecting from a target

You can disconnect from the current target quickly, depending on your current debugging mode. Either:

Ending your RealView Debugger Session

• Select File

This immediately disconnects the connection.

• Select File

menu to display the Connection Control window, and unselect the check box to disconnect the connection.

RealView Debugger Code windows do not close when you disconnect from a target. However, if you have an image loaded, disconnecting removes all the debug information from RealView Debugger and this clears pane contents.

Disconnecting does not close any open projects.

Note

It is not necessary to disconnect from a target before you close down RealView Debugger, see Exiting RealView Debugger on page 5-7 for more details.

5.2.1 Setting disconnect mode

You can control the way a target processor is left after you disconnect. This is particularly useful when debugging multiprocessor debug targets and working with multiple threads. In single processor debugging mode, you might want to leave an image executing but close down RealView Debugger.

If you are connected, you can set disconnect mode:

→ Connection → Disconnect from the Code window main menu.

→ Connection → Connect to Target... from the Code window main

1. Select File

→ Connection → Connect to Target... to display the Connection

Control window.

2. Right-click on the connection entry and select Disconnect (Defining Mode)...

from the Connection context menu.

3. Select the required state from the selection box.

The options listed depend on your execution vehicle.

4. Click OK to disconnect and leave the processor in the required state.

Ending your RealView Debugger Session

If you set disconnect mode from the Connection Control window, this temporarily overrides any setting in your target configuration file. See the chapter describing connecting (and disconnecting) in RealView Debugger v1.6 Target Configuration Guide for full details on setting disconnect mode for your debug target.

5.3 Exiting RealView Debugger

This section describes the options available when you exit RealView Debugger:

• Closing down without a connection

• Closing down with a connection

• Reconnecting to a target on page 5-8.

5.3.1 Closing down without a connection

Disconnect from your target, as described in Disconnecting from a target on page 5-5, and select File

Click Ye s to close the Exit dialog box and close down RealView Debugger.

5.3.2 Closing down with a connection

→ Exit to display the Exit dialog box.

Ending your RealView Debugger Session

If you are connected to your target and you select File

→ Exit, the Exit dialog box

includes the Disconnect Connection check box, shown in Figure 5-2.

Figure 5-2 Exit dialog box, connected

Use the check box to specify your disconnect options:

• Maintaining the connection

• Terminating the connection on page 5-8.

Maintaining the connection

To close down and maintain the connection:

1. Unselect the Disconnect Connection check box shown in Figure 5-2.

2. Click Ye s to close the Exit dialog box and close down RealView Debugger.

RealView Debugger exits but the connection is maintained for future sessions, that is the Target Vehicle Server (TVS) is left running. If you are connected to a remote debug target and you close down this way, the remote RealView Debugger Connection Broker is also left running.

Ending your RealView Debugger Session

Terminating the connection

To close down and terminate the connection:

1. Leave the Disconnect Connection check box, shown in Figure 5-2 on page 5-7,

so that it is selected.

2. Click Ye s to close the Exit dialog box and close down RealView Debugger.

RealView Debugger exits and terminates any connections to debug targets, that is TVS stops. If you are connected to a remote debug target and you close down this way, you must stop the remote RealView Debugger Connection Broker manually.

Note

See Components of RealView Debugger on page 1-4 for details on TVS and RealView Debugger Connection Broker.

5.3.3 Reconnecting to a target

RealView Debugger saves all open connections in the current workspace if you close down without disconnecting first. This default behavior is independent of the status of the Disconnect Connection check box shown in Figure 5-2 on page 5-7.

If you exit a session when still connected to a debug target, RealView Debugger tries to reconnect when you next open the workspace. However, this might fail if the connection or vehicle status has changed, for example if your Multi-ICE server has stopped.

If RealView Debugger reconnects successfully, the connection mode specified in the target configuration file is used by default. See the chapter describing connecting in RealView Debugger v1.6 Target Configuration Guide for full details on defining the connect mode for your debug target.

Note

Use your settings options to change the way RealView Debugger closes down, see Settings options on page 5-4 for details.

Chapter 6

RealView Debugger Desktop

This chapter describes, in detail, the RealView Debugger desktop. It describes the contents of the default Code window, and explains how to change them. This chapter describes items and options available from the main menu and the toolbars.

It contains the following sections:

• About the desktop on page 6-2

• Finding options on the main menu on page 6-11

• Working with button toolbars on page 6-15

• Working in the Code window on page 6-19

• Editor window on page 6-22

• Resource Viewer window on page 6-23

• Analysis window on page 6-26.

RealView Debugger Desktop

6.1 About the desktop

This section describes the default Windows desktop that you see when you run RealView Debugger for the first time after installation and highlights any key features that might be different. It contains the following sections:

• Splash screen

• Code window

• Default windows and panes on page 6-5

• Pane controls on page 6-8

• Button toolbars on page 6-8

• Color Box on page 6-9

• Other window elements on page 6-10.

6.1.1 Splash screen

Run the debugger from the Windows Start menu to display the RealView Debugger splash screen. During this time, the debugger is checking your environment and creating (or updating) configuration files and a working directory.

6.1.2 Code window

Use the

-nologo

flag to run RealView Debugger from the command line without a

splash screen.

The Windows splash screen is replaced by the default Code window when you run RealView Debugger for the first time after installation, shown in Figure 6-1 on page 6-3.

RealView Debugger Desktop

Color Box Toolbars

Title bar Pane Management

File Editor pane

Pane title bar

Command line

Status line

controls

Output pane

Cursor location field

Build controls

Keyboard status

Processor State

Side pane

Figure 6-1 Default Code window

The Code window is your main debugging and editing window. The contents of this window change as you:

• connect to targets

• load and unload application programs or files

• configure and customize your working environment.

The toolbar buttons displayed, and the options available from window and pane menus also change depending on the licenses you have.

Title bar

RealView Debugger Desktop

Figure 6-2 Title bar

In addition to the application icon, the title bar contains (from left to right):

RVDEBUG Identifies the Code window. This changes as you open new windows, for

example

RVDEBUG_1

, or

RVDEBUG_2.

(dhrystone) The project associated with the image that you loaded.

In RealView Debugger, a project can be associated with a connection, that is it is bound to that connection, shown in Figure 6-2.

Where a project is not associated with a particular connection, it is unbound. In this case, the project name is enclosed in angled brackets, for example

<my_project>

See the chapter describing managing projects in RealView Debugger v1.6 User Guide for details on project binding.

@ARM... The connection, including the target processor, the connection number,

and the execution vehicle.

[Unattached]

The attachment of the window to a specified connection.

If you are working in multiprocessor mode, the default Code window is unattached. You can attach a Code window to a specified connection, shown by

[Board]

. See the chapter describing working with multiple

targets in RealView Debugger v1.6 Extensions User Guide for details.

If you are using an RTOS, you can attach a Code window to a thread to display debug information for that thread. This is shown by

[Thread]

. See the chapter describing RTOS support in RealView Debugger v1.6 Extensions User Guide for details.

If you are working in single processor debugging mode, the option to attach windows to your connection is not available.

If you float a pane, the pane title bar reflects the title bar of the calling Code window.

Note

The contents of your title bar might be different from the one shown in Figure 6-2 depending on your connection (if any), open projects, and windows attachment.

6.1.3 Default windows and panes

RealView Debugger provides a range of debug views:

• Registers

• Stack

• Process Control

•Symbol Browser

• Watch

• Call Stack and Locals

• Memory and Memory Map

• Threads (with the appropriate RTOS support package)

• Break/Tracepoints.

The default Code window, shown in Figure 6-1 on page 6-3, contains:

File Editor pane

The File Editor pane is always visible when working with RealView Debugger.

Use this area of the Code window to:

• use a shortcut to connect to a target or load an image

• enter text to create project files

• open source files for editing and resaving

•view disassembly

• set breakpoints to control execution

• use the available menu options to search for specific text as part of

• follow execution through a sequence of source-level and

The File Editor pane contains a hyperlink to make your first connection to a debug target. When a connection is made, this link changes to give you a quick way to load an image.

When RealView Debugger first starts, the File Editor pane contains tabs to track program execution:

•the Src tab shows the current context in the source view

•the Dsm tab displays disassembled code with intermixed C/C++

RealView Debugger Desktop

debugging

disassembly-level views.

source lines.

RealView Debugger Desktop

If you load an image, or when you are working with source files, more tabs are displayed, for example

dhry_1.c

. In this case, click on the Src tab

to see the location of the PC.

Side pane By default, this contains the Register pane view that displays grouped

processor registers for the current target processor. When you first run RealView Debugger, this pane is positioned to the right of the File Editor pane but you can switch this pane to the left, using the Switch Side option from the Pane Content menu.

The Register pane displays different tabs depending on the target processor and the connection mechanism. For example, if you are using ARMulator to simulate an ARM processor, the Debug tab displays debugger internals. However, if the target processor is a DSP, a Status tab is available displaying details of the status flags.

Middle pane row

The middle pane row can contain one, two, or three pane views, but you can specify which panes are visible. By default this row contains:

Call Stack pane

Use this pane to:

• display the procedure calling chain from the entry point to the current procedure

• monitor local variables.

The Call Stack pane contains tabs:

Call Stack

Displays the stack functions call chain.

Locals Shows variables local to the current function.

Statics Displays a list of static variables local to the current

module.

This Shows objects located by the C++ specific

this

pointer.

Watch pane

Use this pane to:

• set up variables or expressions to watch

• display current watches

• modify watches already set

• delete existing watches.

The Watch pane contains tabs to display sets of watched values. The first tab, Watc h1, is selected by default.

Bottom pane

RealView Debugger Desktop

Memory pane

Use this pane to:

• display the contents of a range of memory locations on the target

• edit the values stored by the application.

The bottom pane of the Code window always contains the Output pane. Select the different tabs to:

• enter commands during a debugging session (Cmd)

• handle I/O with your application (StdIO)

• see the progress of builds (Build)

• see the results of Find in Files operations (FileFind)

• see the results of operations using your version control tool

(SrcCtrl)

• view the results of commands and track events during debugging

(Log).

The command line is located at the bottom of the Output pane. This shows the status of the current process, for example, process). You can also enter debugger commands at the

Stop, Run

prompt.

, or

None

(no

During your debugging session, you can use the Pane Content menu to define which view is displayed in a chosen pane (see Pane controls on page 6-8 for details). At the end of your first session, you can configure RealView Debugger to start next time with a different set of panes or views if required by saving the customized setup in your workspace.

Changing panes

Select View

→ Pane Views to change what is displayed in a pane view or to restore the

default views. You can also use this menu to display any window or pane that is hidden, without changing the view it displays. If a pane is hidden and you use the Pane Views menu to change the pane contents, it is automatically displayed to show the new view.

Formatting pane views

The contents of the File Editor pane and the Output pane cannot be changed. However, you can define how the view is formatted, for example change the size of text displayed in the File Editor pane or the number of lines displayed in the Output pane. See the chapter describing configuring workspaces in RealView Debugger v1.6 User Guide for details of how to do this.

RealView Debugger Desktop

6.1.4 Pane controls

Each configurable pane in the Code window, shown in Figure 6-1 on page 6-3, includes a title bar and pane controls. In the side pane, the pane title bar is displayed horizontally at the top of the pane. In the middle and bottom panes, the title bar is displayed vertically at the left side of the pane.

If you float a pane, the title bar is displayed horizontally at the top of the window.

A pane contains the controls:

Pane Content

Click this button to display the Pane Content menu where you can change the debug view in the pane.

The selected option in the menu indicates the current view.

Visual controls

The visual controls are at the bottom of the Pane Content menu. Use these to float or hide the pane.

In the side pane, use the option Switch Side to move the pane from the right side of the Code window so that it is positioned to the left of the code view.

Expand/Collapse Pane

Click this button to collapse the currently selected view. Other panes are expanded to fill the empty area.

Click the Expand Pane button to restore the view.

There is no option to collapse, or expand, a floating pane.

Pane Menu Click this button to display the Pane menu.

Use this to:

• change the display format

• change how pane contents are updated

• extract data from the pane.

The options available from this menu depend on the pane.

6.1.5 Button toolbars

There are two toolbars, below the Code window main menu, that provide quick access to many of the features available from menu options:

• Actions toolbar, shown in Figure 6-3 on page 6-9

• Editing toolbar, shown in Figure 6-4 on page 6-9.

RealView Debugger Desktop

Figure 6-3 Actions toolbar

Figure 6-4 Editing toolbar

To disable a toolbar, select View → To ol ba rs from the main menu. This displays the To ol ba rs menu where you can specify which toolbars are visible.

You can move a toolbar from the default position in the Code window so that it floats on your desktop. To restore the floating toolbar, double-click anywhere on the toolbar title bar.

Note

Repositioning a toolbar in this way applies only to the calling Code window. If you create a new Code window the toolbars are in the default positions on opening.

See Working with button toolbars on page 6-15 for details on the buttons available from the Actions toolbar and the Editing toolbar, and how to customize toolbar groups.

6.1.6 Color Box

Code windows in RealView Debugger are color-coded to help with navigation. This is particularly useful when debugging multiprocessor debug targets and working with multiple threads.

When connected to a single target processor, the Color Box identifies the connection associated with the window. This is located on the main menu toolbar next to File, shown in Figure 6-5.

Color Box

Figure 6-5 Color Box

RealView Debugger Desktop

When you first start RealView Debugger the Code window is not associated with any target or process. The Color Box changes when you make your first connection. As you create new Code windows, these are also color-coded. Closing your connection changes the Color Box to show that there is no connection associated with the window. Any other Code windows attached to that connection are also updated to match. Notice that:

• connection-independent windows, or controls, do not contain a Color Box

• floating panes contain a Color Box that matches the calling window.

6.1.7 Other window elements

There are status display areas at the bottom of the Code window:

Status line As you move through menu options, or when you view button tooltips,

Cursor location field

LOG Shows that output is being written to a log file.

this line shows a more detailed explanation of the option or button under the cursor.

As you move through files within the File Editor pane, the current location of the text insertion point is displayed in the Cursor location field at the bottom right of the Code window.

JOU Shows that output is being written to a journal file.

STDIOlog Shows that output is being written to an STDIOlog file.

NUM Shows that you can use the numeric keypad to enter numbers.

CAP Shows that Caps Lock is selected.

6.2 Finding options on the main menu

This section provides a summary of the main menu options available from the Code window that enable you to:

• open and close files within the File Editor pane

• manage target images, projects, and workspaces

• navigate, search, and edit source files

• manage new windows and change pane contents

• work with projects and build images

• debug your images

• access the online help system.

The submenus available from the main menu bar are:

File Displays the File menu shown in Figure 6-6.

RealView Debugger Desktop

Figure 6-6 File menu

Note

The menu option Close Window is not enabled when the default Code

window is the only window. This is the main debugging and editing window, and it must be open throughout your debugging session. Close the Code window to close down RealView Debugger.

RealView Debugger Desktop

Edit Displays the Edit menu shown in Figure 6-7. This menu enables you to

work with source files as you develop your application. It includes options to define how source code is displayed in the File Editor pane.

Figure 6-7 Edit menu

Find Displays the Find menu shown in Figure 6-8. This menu enables you to

work with source files and to perform searches on those files as you debug your image. This also gives access to the browsers in RealView Debugger.

Figure 6-8 Find menu

View Displays the View menu shown in Figure 6-9. This menu enables you to

set up new windows and panes as you are working with target connections. It also includes options to customize toolbar groups.

Figure 6-9 View menu

RealView Debugger Desktop

Note

Custom windows are not available in this release.

Project Displays the Project menu shown in Figure 6-10. This menu enables you

to work with projects so that you can organize your source files, model your build process, and share files with other developers. This can be used in conjunction with the Too ls menu to rebuild images.

Figure 6-10 Project menu

To ol s Displays the To ol s menu shown in Figure 6-11.

Figure 6-11 Tools menu

This menu enables you to build files, or groups of files, to create your image ready for loading to a target. It also enables you to examine, and change, your workspace settings and global configuration options.

If you have the appropriate licenses, you can access RealView Debugger extensions for Trace, Analysis, and Profiling. These features are described fully in RealView Debugger v1.6 Extensions User Guide.

Note

Supported by selected simulators from the DSP Group, the Simulation

Control option is not available in this release.

RealView Debugger Desktop

Debug Displays the Debug menu shown in Figure 6-12.

Figure 6-12 Debug menu

This menu includes the main facilities you use during a debugging session.

Help Displays the Help menu shown in Figure 6-13.

Figure 6-13 Help menu

This menu gives you access to the RealView Debugger online help, to web downloads pages, and displays details of your version of RealView Debugger. You can also use this menu to create and submit a Software Problem Report (SPR).

ARM RealView Debugger User Manual

Specifications and Main Features

Frequently Asked Questions

User Manual

Contents

Preface

About this book

Intended audience

Using this book

Further reading

Feedback

Feedback on this book

About RealView Debugger

1.1 RealView Debugger

1.1.1 RealView Debugger concepts and terminology

1.2 About the debugging environment

1.2.1 Components of RealView Debugger

1.2.2 Debug target interface

1.2.3 Persistence information

1.3 Debugging mode

1.4 Using the documentation suite

Features of RealView Debugger

2.1 RealView Debugger v1.6

2.1.1 Multi-core debugging

2.1.2 OS awareness

2.1.3 Extended Target Visibility (ETV)

2.1.4 Advanced debugging facilities

2.1.5 Trace, Analysis, and Profiling

2.1.6 Project manager

2.1.7 RealView Debugger downloads

2.2 Getting more information online

Getting Started with RealView Debugger

3.1 Starting RealView Debugger

3.1.1 Starting RealView Debugger

3.1.2 The Code window

3.2 Connecting to a target

3.2.1 Target configuration

3.2.2 Working with connections

3.2.3 Making a connection

3.2.4 Setting connect mode

3.3 Working with memory

3.3.1 Setting top of memory and stack values

3.3.2 Setting top of memory for a session

3.4 Loading an image

3.4.1 Loading an image

3.4.2 What is shown in the title bar?

3.4.3 Reloading an image

3.4.4 Unloading an image

3.5 Debugging an image

3.5.1 Getting started

3.5.2 Code views

3.5.3 Viewing target status

Quick-start Tutorial

4.1 How to use the tutorial

4.1.1 Getting started

4.2 Setting up your first project

4.2.1 Defining your build tools

4.2.2 Creating a new project

4.2.3 Defining a Standard Project

4.2.4 Viewing the project settings

4.2.5 Setting up compiler options

4.2.6 Project base directory

4.2.7 Building the application

4.2.8 Project files

4.2.9 Closing the project

4.3 Debugging with RealView Debugger

4.3.1 Getting started

4.3.2 Basic debugging tasks

4.3.3 Using breakpoints

4.4 Working with custom panes

4.4.1 Customizing your debug views

4.4.2 Hiding panes

4.5 More about projects

4.5.1 Changing build tools

4.5.2 Viewing build settings

4.5.3 Adding files to your project

4.5.4 Generated makefiles

4.5.5 Building an application

4.5.6 Finding build errors

4.6 Completing the tutorial