ARM® DS-5 Debugger User Guide

Version 5.20

Table of Contents

About this book
Using this book
Typographic conventions
Other information
1 Getting Started with DS-5 Debugger
1.1 About DS-5 Debugger
1.2 Debugger concepts
1.3 Terminology
1.4 Launching the debugger from Eclipse
1.5 About DS-5 headless command-line debugger
1.6 Headless command-line debugger options
1.7 Specifying a custom configuration database using the headless command-line debugger
1.8 Capturing trace using the headless debugger
1.9 DS-5 Debug perspective keyboard shortcuts
1.10 DS-5 Debugger command-line console keyboard shortcuts
1.11 Standards compliance in DS-5 Debugger
2 Configuring and Connecting to a Target
2.1 Types of target connections
2.2 About Fixed Virtual Platform (FVP) entries in the configuration database
2.3 Configuring a connection to a Linux target using gdbserver
2.4 Configuring a connection to a Fixed Virtual Platform (FVP) for Linux application debug
2.5 Adding a custom model
2.6 Configuring a connection to a Linux Kernel
2.7 About configuring connections to a Linux target using Application Debug with Rewind Support
2.7.1 Connecting to an existing application and application rewind session
2.7.2 Downloading your application and application rewind server on the target system
2.7.3 Starting the application rewind server and debugging the target-resident application
2.8 Configuring a connection to a bare-metal target
2.9 Configuring an Event Viewer connection to a bare-metal target
2.10 About the target configuration import utility
2.11 Adding a new platform
2.12 Adding a new configuration database to DS-5
2.13 Exporting an existing launch configuration
2.14 Importing an existing launch configuration
2.15 Disconnecting from a target
3 Working with the Target Configuration Editor
3.1 About the target configuration editor
3.2 Target configuration editor - Overview tab
3.3 Target configuration editor - Memory tab
3.4 Target configuration editor - Peripherals tab
3.5 Target configuration editor - Registers tab
3.6 Target configuration editor - Group View tab
3.7 Target configuration editor - Enumerations tab
3.8 Target configuration editor - Configurations tab
3.9 Scenario demonstrating how to create a new target configuration file
3.9.1 Creating a memory map
3.9.2 Creating a peripheral
3.9.3 Creating a standalone register
3.9.4 Creating a peripheral register
3.9.5 Creating enumerations for use with a peripheral register
3.9.6 Assigning enumerations to a peripheral register
3.9.7 Creating remapping rules for a control register
3.9.8 Creating a memory region for remapping by a control register
3.9.9 Applying the map rules to the overlapping memory regions
3.10 Creating a power domain for a target
3.11 Creating a Group list
3.12 Importing an existing target configuration file
3.13 Exporting a target configuration file
4 Controlling Execution
4.1 About loading an image on to the target
4.2 About loading debug information into the debugger
4.3 About passing arguments to main()
4.4 Running an image
4.5 Working with breakpoints and watchpoints
4.5.1 Setting or deleting an execution breakpoint
4.5.2 Setting or removing a data watchpoint
4.5.3 Viewing the properties of a data watchpoint
4.5.4 Importing DS-5 breakpoint settings from a file
4.5.5 Exporting DS-5 breakpoint settings to a file
4.6 Working with conditional breakpoints
4.6.1 Assigning conditions to an existing breakpoint
4.7 About pending breakpoints and watchpoints
4.8 Setting a tracepoint
4.9 Setting Streamline start and stop points
4.10 Stepping through an application
4.11 Handling Unix signals
4.12 Handling processor exceptions
4.13 Configuring the debugger path substitution rules
5 Examining the Target
5.1 Examining the target execution environment
5.2 Examining the call stack
5.3 About trace support
5.4 About post-mortem debugging of trace data
6 Debugging Embedded Systems
6.1 About endianness
6.2 About accessing AHB, APB, and AXI buses
6.3 About virtual and physical memory
6.4 About address spaces
6.5 About debugging hypervisors
6.6 About debugging big.LITTLE systems
6.7 About debugging bare-metal symmetric multiprocessing systems
6.8 About debugging multi-threaded applications
6.9 About debugging shared libraries
6.10 About OS awareness
6.10.1 About debugging FreeRTOS ™
6.10.2 About debugging a Linux kernel
6.10.3 About debugging Linux kernel modules
6.10.4 About debugging ThreadX
6.11 About debugging TrustZone enabled targets
6.12 About debugging a Unified Extensible Firmware Interface (UEFI)
6.13 About application rewind
6.14 About debugging MMUs
6.15 About Debug and Trace Services Layer (DTSL)
6.16 About CoreSight™ Target Access Library
6.17 About debugging caches
7 Controlling Runtime Messages
7.1 About semihosting and top of memory
7.2 Working with semihosting
7.3 Enabling automatic semihosting support in the debugger
7.4 Controlling semihosting messages using the command-line console
7.5 Controlling the output of logging messages
7.6 About Log4j configuration files
7.7 Customizing the output of logging messages from the debugger
8 Debugging with Scripts
8.1 Exporting DS-5 Debugger commands generated during a debug session
8.2 Creating a DS-5 Debugger script
8.3 Creating a CMM-style script
8.4 About Jython scripts
8.5 Jython script concepts and interfaces
8.6 Creating Jython projects in Eclipse for DS-5
8.6.1 Creating a new Jython project in Eclipse for DS-5
8.6.2 Configuring an existing project to use the DS-5 Jython interpreter
8.7 Creating a Jython script
8.8 Running a script
9 Working with the Snapshot Viewer
9.1 About the Snapshot Viewer
9.2 Components of a Snapshot Viewer initialization file
9.3 Connecting to the Snapshot Viewer
9.4 Considerations when creating debugger scripts for the Snapshot Viewer
10 DS-5 Debug Perspectives and Views
10.1 App Console view
10.2 ARM Asm Info view
10.3 ARM assembler editor
10.4 Breakpoints view
10.5 C/C++ editor
10.6 Commands view
10.7 Debug Control view
10.8 Disassembly view
10.9 Events view
10.10 Event Viewer Settings dialog box
10.11 Expressions view
10.12 Functions view
10.13 History view
10.14 Memory view
10.15 MMU view
10.16 Modules view
10.17 Registers view
10.18 OS Data view
10.19 Cache Data view
10.20 Screen view
10.21 Scripts view
10.22 Target Console view
10.23 Target view
10.24 Trace view
10.25 Trace Control view
10.26 Variables view
10.27 Timed Auto-Refresh Properties dialog box
10.28 Memory Exporter dialog box
10.29 Memory Importer dialog box
10.30 Fill Memory dialog box
10.31 Export Trace Report dialog box
10.32 Breakpoint Properties dialog box
10.33 Watchpoint Properties dialog box
10.34 Tracepoint Properties dialog box
10.35 Manage Signals dialog box
10.36 Functions Filter dialog box
10.37 Script Parameters dialog box
10.38 Debug Configurations - Connection tab
10.39 Debug Configurations - Files tab
10.40 Debug Configurations - Debugger tab
10.41 Debug Configurations - OS Awareness tab
10.42 Debug Configurations - Arguments tab
10.43 Debug Configurations - Environment tab
10.44 DTSL Configuration Editor dialog box
10.45 Configuration Database panel
10.46 Configuration Perspective
10.46.1 Importing and connecting to a model
10.46.2 Models Configurations Editor - Model Devices and Cluster Configuration
10.46.3 Updating multiple debug hardware units
10.47 About the Remote System Explorer
10.48 Remote Systems view
10.49 Remote System Details view
10.50 Target management terminal for serial and SSH connections
10.51 Remote Scratchpad view
10.52 Remote Systems terminal for SSH connections
10.53 Terminal Settings dialog box
10.54 Debug Hardware Configure IP view
10.55 Debug Hardware Firmware Installer view
10.56 Connection Browser dialog box
10.57 DS-5 Debugger menu and toolbar icons
11 Troubleshooting
11.1 ARM Linux problems and solutions
11.2 Enabling internal logging from the debugger
11.3 Target connection problems and solutions
12 File-based Flash Programming in ARM DS-5
12.1 About file-based flash programming in ARM® DS-5
12.2 Flash programming configuration
12.3 Creating an extension database for flash programming
12.4 About using or extending the supplied ARM® Keil® flash method
12.4.1 Adding flash support to an existing platform using an existing Keil flash algorithm
12.4.2 Adding flash support to an existing target platform using a new Keil flash algorithm
12.5 About creating a new flash method
12.5.1 About using the default implementation FlashMethodv1
12.5.2 About creating the flash method Python script
12.6 About testing the flash configuration
12.7 About flash method parameters
12.8 About getting data to the flash algorithm
12.9 About interacting with the target
13 Writing OS Awareness for DS-5 Debugger
13.1 About Writing operating system awareness for DS-5 Debugger
13.2 Creating an OS awareness extension
13.3 Implementing the OS awareness API
13.4 Enabling the OS awareness
13.5 Implementing thread awareness
13.6 Implementing data views
13.7 Programming advice and noteworthy information
14 Debug and Trace Services Layer (DTSL)
14.1 Additional DTSL documentation and files
14.2 Need for DTSL
14.2.1 SoC design complexity
14.2.2 Debug flexibility
14.2.3 Integrated tool solutions
14.2.4 DS-5 Debugger architecture before DTSL
14.2.5 DS-5 Debugger architecture after DTSL
14.2.6 DS-5 Debugger connection sequence showing where DTSL fits in
14.3 DS-5 configuration database
14.3.1 Modifying DS-5 configdb
14.3.2 Configdb board files
14.3.3 About project_types.xml
14.3.4 About the script
14.3.5 DTSL script
14.4 DTSL as used by DS-5 Debugger
14.4.1 Eclipse debug session launcher dialog
14.4.2 Connecting to DTSL
14.4.3 DTSL access from Debugger Jython scripts
14.5 Main DTSL classes and hierarchy
14.5.1 DTSL configuration objects
14.5.2 DTSL device objects
14.5.3 CoreSight device component register IDs
14.5.4 DTSL trace source objects
14.5.5 DTSL trace capture objects
14.5.6 Memory as seen by a core device
14.5.7 Physical memory access via CoreSight
14.5.8 DTSL MEM-AP support
14.5.9 Linking MEM-AP access to a core device
14.6 DTSL options
14.6.1 DTSL option classes
14.6.2 DTSL option example walk-through
14.6.3 Option names and hierarchy
14.6.4 Dynamic options
14.6.5 Option change notification
14.6.6 Option change notification example walk-through
14.7 DTSL support for SMP and AMP configurations
14.7.1 AMP systems and synchronized execution
14.7.2 Execution synchronization levels
14.7.3 Software synchronization
14.7.4 Tight synchronization
14.7.5 Hardware synchronization
14.7.6 SMP states
14.7.7 Use of CTI for SMP execution synchronization
14.8 DTSL Trace
14.8.1 Platform trace generation
14.8.2 DTSL trace decoding
14.8.3 DTSL decoding stages
14.8.4 DTSL trace client read interface
14.8.5 Supporting multiple trace capture devices
14.8.6 Decoding STM STPv2 output
14.8.7 Example STM reading code
14.8.8 STM objects
14.8.9 DTSL client time-stamp synchronization support
14.9 Extending the DTSL object model
14.9.1 Hooking device reset behavior
14.9.2 Adding a new trace capture device
14.10 Debugging DTSL Jython code within DS-5 Debugger
14.10.1 DTSL Jython syntax errors
14.10.2 Errors reported by the launcher panel
14.10.3 Errors reported at connection time
14.10.4 DTSL Jython functional errors
14.10.5 Walk-through of a DTSL debug session
14.10.6 Starting a second instance of DS-5 for Jython debug
14.10.7 Preparing the DTSL script for debug
14.10.8 Debugging the DTSL code
14.11 DTSL in stand-alone mode
14.11.1 Comparing Java with Jython for DTSL development
14.11.2 DTSL as used by a stand-alone Jython program
14.11.3 Installing the Jython example within Eclipse
14.11.4 Running the Jython program
14.11.5 Invoking the Jython program
14.11.6 About the Jython program
14.11.7 DTSL as used by a stand-alone Java program
14.11.8 Installing the Java example within Eclipse
14.11.9 Running the Java program
14.11.10 Invoking the Java program
14.11.11 About the Java program

List of Figures

1-1 Enable trace in the DTSL options
1-2 Headless debugger connection with DTSL option
2-1 Adding a new configuration database
2-2 Export launch configuration dialog box
2-3 Launch configuration selection panels
2-4 Import launch configuration dialog box
2-5 Launch configuration file selection panels
3-1 Specifying TCF files in the Debug Configurations window
3-2 Target configuration editor - Overview tab
3-3 Target configuration editor - Memory tab
3-4 Target configuration editor - Peripherals tab
3-5 Target configuration editor - Registers tab
3-6 Target configuration editor - Group View tab
3-7 Target configuration editor - Enumerations tab
3-8 Target configuration editor - Configuration tab
3-9 LED register and bitfields
3-10 Core module and LCD control register
3-11 Creating a Memory map
3-12 Creating a peripheral
3-13 Creating a standalone register
3-14 Creating a peripheral register
3-15 Creating enumerations
3-16 Assigning enumerations
3-17 Creating remapping rules
3-18 Creating a memory region for remapping by a control register
3-19 Applying the Remap_RAM_block1 map rule
3-20 Applying the Remap_ROM map rule
3-21 Power Domain Configurations
3-22 Creating a group list
3-23 Selecting an existing target configuration file
3-24 Importing the target configuration file
3-25 Exporting to C header file
3-26 Selecting the files
4-1 Load File dialog box
4-2 Load additional debug information dialog box
4-3 Setting an execution breakpoint
4-4 Setting a data watchpoint
4-5 Viewing the properties of a data watchpoint
4-6 Breakpoint Properties dialog
4-7 Debug Control view
4-8 Managing signal handler settings
4-9 Manage exception handler settings
4-10 Path Substitution dialog box
4-11 Edit Substitute Path dialog box
5-1 Target execution environment
5-2 Debug Control view
6-1 Threading call stacks in the Debug Control view
6-2 Adding individual shared library files
6-3 Modifying the shared library search paths
6-4 Cache Data view (showing L1 TLB cache)
6-5 DTSL Configuration Editor (Cache RAMs configuration tab)
7-1 Typical layout between top of memory, stack, and heap
8-1 Commands generated during a debug session
8-2 PyDev project wizard
8-3 PyDev project settings
8-4 Jython auto-completion and help
8-5 Scripts view
10-1 App Console view
10-2 ARM Asm Info view
10-3 ARM assembler editor
10-4 Breakpoints view
10-5 C/C++ editor
10-6 Show disassembly for selected source line
10-7 Commands view
10-8 Debug Control view
10-9 Disassembly view
10-10 Events view (Shown with all ports enabled for an ETB:ITM trace source)
10-11 Event Viewer Settings (Shown with all Masters and Channels enabled for an ETR:STM trace source)
10-12 Expressions view
10-13 Functions view
10-14 History view
10-15 Memory view
10-16 Memory view with Show Cache
10-17 MMU Translation tab view
10-18 MMU Tables tab view
10-19 Memory Map tab view
10-20 MMU settings
10-21 Modules view showing shared libraries
10-22 Registers view
10-23 OS Data view (showing Keil CMSIS-RTOS RTX Tasks)
10-24 Cache Data view (showing L1 TLB cache)
10-25 Screen buffer parameters
10-26 Screen view
10-27 Scripts view
10-28 Target view
10-29 Trace view with a scale of 100:1
10-30 Trace Control view
10-31 Variables view
10-32 Timed Auto-Refresh Properties dialog box
10-33 Memory Exporter dialog box
10-34 Memory Importer dialog box
10-35 Fill Memory dialog box
10-36 Export Trace Report dialog box
10-37 Breakpoint properties dialog box
10-38 Watchpoint Properties dialog box
10-39 Tracepoint Properties dialog box
10-40 Manage Signals dialog box
10-41 Manage exception handler settings
10-42 Function filter dialog box
10-43 Script Parameters dialog box
10-44 Connection tab (Shown with connection configuration for an FVP with virtual file system support enabled)
10-45 Files tab (Shown with file system configuration for an application on an FVP)
10-46 Debugger tab (Shown with settings for application starting point and search paths)
10-47 OS Awareness tab
10-48 Arguments tab
10-49 New Environment Variable dialog box
10-50 Environment tab (Shown with environment variables configured for an FVP)
10-51 DTSL Configuration Editor (Shown with Trace capture method set to DSTREAM)
10-52 Configuration Database panel
10-53 Configuration Database
10-54 Model Devices and Cluster Configuration tab
10-55 Remote Systems view
10-56 Remote System Details view
10-57 Terminal view
10-58 Remote Scratchpad
10-59 Remote Systems terminal
10-60 Terminal Settings dialog box
10-61 Debug Hardware Configure IP view
10-62 Debug Hardware Firmware Installer
10-63 Connection Browser (Showing a USB connected DSTREAM)
12-1 DS-5 File Flash Architecture
13-1 Eclipse preferences for mydb
13-2 Custom OS awareness displayed in Eclipse Debug Configurations dialog
13-3 myos No OS Support
13-4 myos waiting for target to stop
13-5 myos Enabled
13-6 myos waiting for OS initialization
13-7 myos Debug Control view data
13-8 myos Empty Tasks table
13-9 myos populated Tasks table
14-1 A simple CoreSight Design
14-2 Initial DS-5 Debugger SW Stack
14-3 Post DTSL DS-5 Debugger SW Stack
14-4 DTSL Configuration class hierarchy
14-5 DTSL Device object hierarchy
14-6 DTSL Trace Source class hierarchy
14-7 DTSL Trace Capture Objects
14-8 MEM-AP Access Ports
14-9 MEM-AP Class Hierarchy
14-10 DTSL Option Classes
14-11 DSTREAM Trace Options
14-12 Example use of CTI for H/W execution synchronization
14-13 Trace Generation
14-14 DTSL Trace Decoding Stages for DSTREAM
14-15 DTSL Trace Pipeline Hierarchy
14-16 ETB Trace Decode Pipeline Stages
14-17 Example of Multiple Trace Capture Devices
14-18 STM Object Model
14-19 Launcher panel reporting DTSL Jython script error
14-20 Connection Error Dialog

List of Tables

2-1 ETM/PTM versions for each type of processor
3-1 DMA map register SYS_DMAPSR0
3-2 Control bit that remaps an area of memory
7-1 Log4j Components
10-1 Files tab options available for each Debug operation
10-2 DS-5 Debugger icons
10-3 Perspective icons
10-4 View icons
10-5 View markers
10-6 Miscellaneous icons
14-1 CTI Signal Connections

Release Information

Document History
Issue Date Confidentiality Change
A 30 June 2010 Non-Confidential First release
B 30 September 2010 Non-Confidential Update for DS-5 version 5.2
C 30 November 2010 Non-Confidential Update for DS-5 version 5.3
D 30 January 2011 Non-Confidential Update for DS-5 version 5.4
E 30 May 2011 Non-Confidential Update for DS-5 version 5.5
F 30 July 2011 Non-Confidential Update for DS-5 version 5.6
G 30 September 2011 Non-Confidential Update for DS-5 version 5.7
H 30 November 2012 Non-Confidential Update for DS-5 version 5.8
I 28 February 2012 Non-Confidential Update for DS-5 version 5.9
J 30 May 2012 Non-Confidential Update for DS-5 version 5.10
K 30 July 2012 Non-Confidential Update for DS-5 version 5.11
L 30 October 2012 Non-Confidential Update for DS-5 version 5.12
M 15 December 2012 Non-Confidential Update for DS-5 version 5.13
N 15 March 2013 Non-Confidential Update for DS-5 version 5.14
O 14 June 2013 Non-Confidential Update for DS-5 version 5.15
P 13 September 2013 Non-Confidential Update for DS-5 version 5.16
Q 13 December 2013 Non-Confidential Update for DS-5 version 5.17
R 14 March 2014 Non-Confidential Update for DS-5 version 5.18
S 27 June 2014 Non-Confidential Update for DS-5 version 5.19
T 17 October 2014 Non-Confidential Update for DS-5 version 5.20

Non-Confidential Proprietary Notice

This document is protected by copyright and other related rights and the practice or implementation of the information contained in this document may be protected by one or more patents or pending patent applications. No part of this document may be reproduced in any form by any means without the express prior written permission of ARM. No license, express or implied, by estoppel or otherwise to any intellectual property rights is granted by this document unless specifically stated.
Your access to the information in this document is conditional upon your acceptance that you will not use or permit others to use the information for the purposes of determining whether implementations infringe any third party patents.
THIS DOCUMENT IS PROVIDED “AS IS”. ARM PROVIDES NO REPRESENTATIONS AND NO WARRANTIES, EXPRESS, IMPLIED OR STATUTORY, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTABILITY, SATISFACTORY QUALITY, NON-INFRINGEMENT OR FITNESS FOR A PARTICULAR PURPOSE WITH RESPECT TO THE DOCUMENT. For the avoidance of doubt, ARM makes no representation with respect to, and has undertaken no analysis to identify or understand the scope and content of, third party patents, copyrights, trade secrets, or other rights.
This document may include technical inaccuracies or typographical errors.
This document consists solely of commercial items. You shall be responsible for ensuring that any use, duplication or disclosure of this document complies fully with any relevant export laws and regulations to assure that this document or any portion thereof is not exported, directly or indirectly, in violation of such export laws. Use of the word “partner” in reference to ARM’s customers is not intended to create or refer to any partnership relationship with any other company. ARM may make changes to this document at any time and without notice.
If any of the provisions contained in these terms conflict with any of the provisions of any signed written agreement covering this document with ARM, then the signed written agreement prevails over and supersedes the conflicting provisions of these terms. This document may be translated into other languages for convenience, and you agree that if there is any conflict between the English version of this document and any translation, the terms of the English version of the Agreement shall prevail.
Copyright © [2010-2014], ARM Limited or its affiliates. All rights reserved.
ARM Limited. Company 02557590 registered in England.
110 Fulbourn Road, Cambridge, England CB1 9NJ.

Confidentiality Status

This document is Non-Confidential. The right to use, copy and disclose this document may be subject to license restrictions in accordance with the terms of the agreement entered into by ARM and the party that ARM delivered this document to.
Unrestricted Access is an ARM internal classification.

Product Status

The information in this document is Final, that is for a developed product.

Web Address

Non-ConfidentialPDF file icon PDF versionARM DUI0446T
Copyright © 2010-2014 ARM. All rights reserved.