ARM RealView Debugger User Manual

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.

+ 100 hidden pages

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