ARM® DS-5 Using ARM Streamlineinfocenter.arm.com/.../DUI0482Q_using_arm_streamline.pdf ·...

ARM® DS-5™

Version 5.19

Using ARM Streamline™

Copyright © 2010-2014 ARM. All rights reserved.ARM DUI0482Q

ARM® DS-5™

Using ARM® Streamline™

Copyright © 2010-2014 ARM. All rights reserved.

Release Information

Document History

Issue Date Confidentiality Change

A 19 October 2010 Non-Confidential ARM Streamline Performance Analyzer 1.0

B 19 January 2011 Non-Confidential Version 5.4

C 19 April 2011 Non-Confidential Version 5.5

D 19 July 2011 Non-Confidential Version 5.6

E 19 September 2011 Non-Confidential Version 5.7

F 19 November 2011 Non-Confidential Version 5.8

G 19 February 2012 Non-Confidential Version 5.9

H 19 May 2012 Non-Confidential Version 5.10

I 19 July 2012 Non-Confidential Version 5.11

J 19 October 2012 Non-Confidential Version 5.12

K 19 December 2012 Non-Confidential Version 5.13

L 15 March 2013 Non-Confidential Version 5.14

M 14 June 2013 Non-Confidential Version 5.15

N 13 September 2013 Non-Confidential Version 5.16

O 13 December 2013 Non-Confidential Version 5.17

P 14 March 2014 Non-Confidential Version 5.18

Q 27 June 2014 Non-Confidential Version 5.19

Non-Confidential Proprietary Notice

This document is protected by copyright and other related rights and the practice or implementation of the information contained inthis document may be protected by one or more patents or pending patent applications. No part of this document may bereproduced in any form by any means without the express prior written permission of ARM. No license, express or implied, byestoppel 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 usethe 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 OFMERCHANTABILITY, SATISFACTORY QUALITY, NON-INFRINGEMENT OR FITNESS FOR A PARTICULARPURPOSE 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, orother rights.

This document may include technical inaccuracies or typographical errors.

TO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENT WILL ARM BE LIABLE FOR ANY DAMAGES,INCLUDING WITHOUT LIMITATION ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL, PUNITIVE, ORCONSEQUENTIAL DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, ARISINGOUT OF ANY USE OF THIS DOCUMENT, EVEN IF ARM HAS BEEN ADVISED OF THE POSSIBILITY OF SUCHDAMAGES.

This document consists solely of commercial items. You shall be responsible for ensuring that any use, duplication or disclosure ofthis document complies fully with any relevant export laws and regulations to assure that this document or any portion thereof isnot exported, directly or indirectly, in violation of such export laws. Use of the word “partner” in reference to ARM’s customers is

ARM® DS-5™

ARM DUI0482Q Copyright © 2010-2014 ARM. All rights reserved. 2Non-Confidential

not intended to create or refer to any partnership relationship with any other company. ARM may make changes to this document atany 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 thisdocument 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 theEnglish version of this document and any translation, the terms of the English version of the Agreement shall prevail.

Words and logos marked with ® or ™ are registered trademarks or trademarks of ARM Limited or its affiliates in the EU and/orelsewhere. All rights reserved. Other brands and names mentioned in this document may be the trademarks of their respectiveowners. Please follow ARM’s trademark usage guidelines at http://www.arm.com/about/trademark-usage-guidelines.php

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.

LES-PRE-20349

Confidentiality Status

This document is Non-Confidential. The right to use, copy and disclose this document may be subject to license restrictions inaccordance 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

http://www.arm.com

ARM® DS-5™


http://www.arm.com/about/trademark-usage-guidelines.php

http://www.arm.com

ContentsARM® DS-5™ Using ARM Streamline™

PrefaceAbout this book ..................................................... ..................................................... 12

Chapter 1 Target Setup1.1 Features of Streamline™ Ultimate, Professional, and Community Editions ...... ...... 1-161.2 Standards compliance in Streamline™ .................................. .................................. 1-171.3 Streamline™ prerequisites ........................................................................................ 1-181.4 Preparing and building your Linux kernel ................................ ................................ 1-191.5 Required kernel configuration menu options ............................. ............................. 1-201.6 Building the gator daemon ........................................... ........................................... 1-211.7 Building the gator module ........................................................................................ 1-231.8 Running the gator daemon on your target ............................... ............................... 1-251.9 Connecting to an Android target using Ethernet ...................................................... 1-271.10 Starting a capture session ........................................... ........................................... 1-281.11 Stopping the gator daemon .......................................... .......................................... 1-291.12 gatord command line options ......................................... ......................................... 1-301.13 Setting up Streamline™ to support an ARM® Mali™-based device .............. .............. 1-311.14 Connecting to a Cortex®-M device using DSTREAM™ ............................................ 1-331.15 Recommended compiler options ...................................... ...................................... 1-34

Chapter 2 The Streamline Data View2.1 Opening the Streamline Data view .......................................................................... 2-362.2 Streamline™ Data view toolbar options .................................. .................................. 2-372.3 Capture color-coding ............................................... ............................................... 2-39


2.4 The Connection Browser dialog box ........................................................................ 2-402.5 Analysis Data Locations dialog box options .............................. .............................. 2-412.6 Duplicating a capture ............................................... ............................................... 2-42

Chapter 3 Capture and Analysis Options3.1 Opening the Capture & Analysis Options dialog box ....................... ....................... 3-443.2 Capture & Analysis Options dialog box settings ...................................................... 3-45

Chapter 4 Counter Configuration4.1 Counter Configuration dialog box structure .............................. .............................. 4-524.2 Opening the Counter Configuration dialog box ........................... ........................... 4-544.3 Adding new events to the Events to Collect list ........................... ........................... 4-554.4 Removing events from the Events to Collect list .......................... .......................... 4-574.5 Counter Configuration toolbar options .................................. .................................. 4-584.6 Events specific to ARM® Mali™ technology ............................... ............................... 4-594.7 Events-based sampling ............................................. ............................................. 4-604.8 Setting up events-based sampling ..................................... ..................................... 4-61

Chapter 5 The Live View5.1 Live view overview ................................................. ................................................. 5-645.2 Live view toolbar options ............................................ ............................................ 5-66

Chapter 6 The Timeline View6.1 Timeline view overview ............................................................................................ 6-696.2 The Cross Section Marker ........................................... ........................................... 6-716.3 Timeline view charts ................................................................................................ 6-736.4 Timeline view details panel overview ................................... ................................... 6-776.5 Heat Map mode ................................................... ................................................... 6-796.6 Core Map and Cluster Map modes .......................................................................... 6-816.7 Processes mode ...................................................................................................... 6-836.8 Exceptions mode .................................................. .................................................. 6-846.9 OpenCL mode .................................................... .................................................... 6-856.10 Timeline view toolbar ............................................... ............................................... 6-896.11 Timeline view contextual menu options ................................. ................................. 6-916.12 Timeline view keyboard shortcuts ..................................... ..................................... 6-926.13 The Timeline view Samples HUD ............................................................................ 6-946.14 Filtering using the caliper controls ..................................... ..................................... 6-956.15 Adding bookmarks to the Timeline view .................................................................. 6-976.16 Timeline view charts specific to ARM® Mali™-based targets .................. .................. 6-986.17 The Warnings tag ................................................. ................................................. 6-1006.18 Changing the quality of graphics in the Timeline view ..................... ..................... 6-1016.19 Timeline view chart configuration ..................................... ..................................... 6-1026.20 Chart configuration toolbar options ........................................................................ 6-1036.21 Chart configuration series options .................................... .................................... 6-1076.22 Snippet menu .................................................... .................................................... 6-1116.23 Adding an existing chart using the Snippets menu ................................................ 6-1136.24 Adding a new chart to the Timeline view using the Snippets menu ........... ........... 6-1146.25 Snippet menu contextual menu options ................................ ................................ 6-1156.26 Snippet menu buttons ............................................................................................ 6-1166.27 Visual Annotation in the Timeline view .................................................................. 6-117


Chapter 7 The Table Views: Call Paths, Functions, and Stack7.1 Table view toolbar options .......................................... .......................................... 7-1207.2 Table view contextual menu options .................................. .................................. 7-1217.3 Table view keyboard shortcuts .............................................................................. 7-1227.4 Sorting table reports ............................................... ............................................... 7-1237.5 Call Paths view column headers ..................................... ..................................... 7-1257.6 Functions view column headers ...................................... ...................................... 7-1267.7 The Maximum Stack Depth by Thread chart ............................ ............................ 7-1277.8 Stack view column headers ......................................... ......................................... 7-128

Chapter 8 The Code View8.1 Code view basics ................................................. ................................................. 8-1308.2 Selecting rows in the Code view ............................................................................ 8-1318.3 Path prefix substitution in the Code view ............................... ............................... 8-1328.4 Using the find command in the Code view .............................. .............................. 8-1348.5 Code view toolbar options .......................................... .......................................... 8-1358.6 Code view keyboard shortcuts ....................................... ....................................... 8-136

Chapter 9 The Call Graph View9.1 Call Graph view overview ...................................................................................... 9-1389.2 How the Call Graph view hierarchy is built ............................................................ 9-1409.3 Using the mini-map to navigate the Call Graph view ...................... ...................... 9-1419.4 Call Graph view function contextual menu options ................................................ 9-1429.5 Call Graph view whitespace contextual menu options ..................... ..................... 9-1439.6 Call Graph view toolbar options ...................................... ...................................... 9-1449.7 Call Graph view keyboard shortcuts ...................................................................... 9-145

Chapter 10 Streamline Annotate10.1 Annotate overview ............................................... ............................................... 10-14710.2 Adding Streamline Annotate to your code ............................. ............................. 10-14810.3 Visual Annotate overview .......................................... .......................................... 10-14910.4 Adding Visual Annotate to your code ................................. ................................. 10-15110.5 Kernel annotation ................................................ ................................................ 10-15210.6 Annotate macros ................................................ ................................................ 10-15310.7 Importing the Streamline_annotate example ........................... ........................... 10-155

Chapter 11 The Log View11.1 Log view column headers .................................................................................... 11-15711.2 Log view search fields ............................................ ............................................ 11-15911.3 Log view contextual menu options ................................... ................................... 11-16011.4 Log view totals panel ............................................. ............................................. 11-161

Chapter 12 Capturing Energy Data12.1 Energy Probe overview ........................................... ........................................... 12-16312.2 Energy Probe requirements ........................................ ........................................ 12-16512.3 Shunt resistor selection for Energy Probe ............................. ............................. 12-16612.4 Setting up Energy Probe .......................................... .......................................... 12-16712.5 Adding the caiman application to Streamline™ .......................... .......................... 12-16912.6 Updating your firmware ........................................... ........................................... 12-17012.7 Energy Probe data in Streamline .................................... .................................... 12-171


12.8 Applying manual offsets to align energy data ...................................................... 12-17312.9 Setting up National Instrument Multifunction Data Acquisition devices (NI-DAQ) to

capture energy data .............................................. .............................................. 12-174

Chapter 13 Advanced Customizations13.1 Capturing data on your target .............................................................................. 13-17713.2 Capturing energy data locally and importing it to a capture ................ ................ 13-17813.3 Using the gator_events_mmapped.c custom counters example ............ ............ 13-17913.4 Creating custom performance counters ............................... ............................... 13-18013.5 gator_events functions ............................................ ............................................ 13-18113.6 Category and event parameters for custom counters in events.xml ......... ......... 13-18213.7 Getting L2C-310 memory-mapped peripherals working with Streamline ...... ...... 13-18413.8 Profiling the Linux kernel .......................................... .......................................... 13-18513.9 Re-analyzing Stored Streamline Capture Data ......................... ......................... 13-18613.10 Streamline™ preferences ...................................................................................... 13-188

Chapter 14 Troubleshooting Common Streamline™ Issues14.1 Troubleshooting target connection issues ............................. ............................. 14-19014.2 Troubleshooting report issues ...................................... ...................................... 14-191

Chapter 15 Using Streamline™ on the Command Line15.1 Opening a Streamline™-enabled command prompt or shell ................ ................ 15-19315.2 Streamline™ command-line options .................................. .................................. 15-19415.3 Outputting command line data to a file ................................................................ 15-197


List of FiguresARM® DS-5™ Using ARM Streamline™

Figure 1-1 The Start Capture button ....................................................................................................... 1-28Figure 2-1 The Streamline Data view ..................................................................................................... 2-36Figure 2-2 Duplicating a capture ............................................................................................................. 2-42Figure 3-1 The Capture & Analysis Options button ................................................................................ 3-44Figure 3-2 The Capture & Analysis Options dialog box .......................................................................... 3-45Figure 3-3 The Stop button in the Live view with Discard Data option enabled ...................................... 3-47Figure 3-4 Symbols loaded icon ............................................................................................................. 3-49Figure 4-1 The Counter Configuration dialog box ................................................................................... 4-52Figure 4-2 The Streamline data view - Counter Configuration ................................................................ 4-54Figure 4-3 Adding a counter to the Events to Collect list ........................................................................ 4-55Figure 4-4 The Interface drop-down menu ............................................................................................. 4-56Figure 4-5 Setting up events-based sampling ........................................................................................ 4-62Figure 5-1 The Live view ......................................................................................................................... 5-64Figure 6-1 The Timeline view .................................................................................................................. 6-69Figure 6-2 A Cross Section Marker fuzzy line ......................................................................................... 6-72Figure 6-3 A bar chart with an active selection in the processes section ............................................... 6-74Figure 6-4 The Processes Focus button ................................................................................................. 6-74Figure 6-5 The Quick Access tooltip ....................................................................................................... 6-74Figure 6-6 Moving a chart using the handle control ................................................................................ 6-75Figure 6-7 Re-sizing a chart .................................................................................................................... 6-75Figure 6-8 Using the chart disclosure control to show per cluster data .................................................. 6-76Figure 6-9 Process bars in Heat Map mode ........................................................................................... 6-79Figure 6-10 CPU contention dashes in the Timeline view ........................................................................ 6-80


Figure 6-11 Filter button ............................................................................................................................ 6-80Figure 6-12 Core Map mode with two cores ............................................................................................. 6-81Figure 6-13 OpenCL mode in the Timeline view ....................................................................................... 6-85Figure 6-14 A gap between commands in OpenCL mode ........................................................................ 6-86Figure 6-15 A selected command in OpenCL mode ................................................................................. 6-86Figure 6-16 Zooming out in OpenCL mode .............................................................................................. 6-87Figure 6-17 OpenCL mode tooltip ............................................................................................................. 6-87Figure 6-18 Filtering in OpenCL mode ...................................................................................................... 6-88Figure 6-19 Events-based sampling tag on the Timeline toolbar .............................................................. 6-89Figure 6-20 Warnings tag ......................................................................................................................... 6-89Figure 6-21 Community Edition tag .......................................................................................................... 6-89Figure 6-22 The zoom level drop-down menu .......................................................................................... 6-90Figure 6-23 Timeline view Samples HUD ................................................................................................. 6-94Figure 6-24 Using the calipers to filter ...................................................................................................... 6-95Figure 6-25 Adding a bookmark ................................................................................................................ 6-97Figure 6-26 The bookmark in the timeline overview ................................................................................. 6-97Figure 6-27 Charts in the Timeline view specific to Mali-based targets .................................................... 6-98Figure 6-28 The Warnings tag ................................................................................................................ 6-100Figure 6-29 The Timeline view with the Use highest quality graphics option disabled ........................... 6-101Figure 6-30 The Chart Configuration button ........................................................................................... 6-102Figure 6-31 The Chart Configuration panel and Cache chart ................................................................. 6-102Figure 6-32 A bar chart example ............................................................................................................ 6-103Figure 6-33 A stacked chart example ..................................................................................................... 6-103Figure 6-34 Data from series A obstructed by data from series B .......................................................... 6-104Figure 6-35 Logarithmic scale ................................................................................................................. 6-105Figure 6-36 Series options ...................................................................................................................... 6-107Figure 6-37 The Color dialog box on Windows ....................................................................................... 6-108Figure 6-38 The Snippets menu ............................................................................................................. 6-111Figure 6-39 Changing categories ............................................................................................................ 6-112Figure 6-40 Visual annotation in the Timeline view ................................................................................ 6-117Figure 6-41 Hovering over an image in the Timeline view ...................................................................... 6-117Figure 7-1 A multi-level sort .................................................................................................................. 7-123Figure 7-2 The Maximum Stack Depth by Thread chart ....................................................................... 7-127Figure 8-1 The Code View .................................................................................................................... 8-130Figure 8-2 The Totals panel .................................................................................................................. 8-130Figure 8-3 Missing source file ............................................................................................................... 8-132Figure 8-4 The Path Prefix Substitutions dialog box ............................................................................. 8-133Figure 8-5 The Find field ....................................................................................................................... 8-134Figure 9-1 A selected function in the Call Graph view .......................................................................... 9-139Figure 9-2 A simple hierarchy ............................................................................................................... 9-140Figure 9-3 Call Hierarchy with Multiple Calls ........................................................................................ 9-140Figure 9-4 The Call Graph view mini-map ............................................................................................ 9-141Figure 10-1 Annotation overlays ........................................................................................................... 10-147Figure 10-2 Visual Annotation in the Timeline view .............................................................................. 10-149Figure 11-1 Visual annotation in the Log view ...................................................................................... 11-157Figure 12-1 Energy Probe schematic ................................................................................................... 12-163Figure 12-2 Energy Probe electrical connection example .................................................................... 12-163Figure 12-3 Connection to target .......................................................................................................... 12-167Figure 12-4 The populated Tool Path field ........................................................................................... 12-169Figure 12-5 Energy Probe data in the Timeline view ............................................................................ 12-171


Figure 12-6 The Energy Offset menu ................................................................................................... 12-173Figure 12-7 Connections for NI USB-621x ........................................................................................... 12-175Figure 13-1 The Sine counter in the Timeline view ............................................................................... 13-179Figure 13-2 The Analyze dialog box ..................................................................................................... 13-186Figure 15-1 A functions report generated using report mode ............................................................... 15-194Figure 15-2 The Timeline view in a text file .......................................................................................... 15-198


Preface

This preface introduces the ARM® DS-5™ Using ARM Streamline™.

It contains the following:

• About this book on page 12.


About this bookARM DS-5 Using ARM Streamline. Provides instructional documentation for real-time, non-intrusiveanalysis of applications. Available as a PDF.

Using this book

This book is organized into the following chapters:

Chapter 1 Target Setup

ARM® Streamline™ Performance Analyzer is a system-wide visualizer and profiler for targets runningARM Linux, Android, or Chrome OS, and for Cortex®-M targets running CMSIS-RTX. To get startedusing it, you must set up your target, then build and configure gator, the mechanism that Streamlineuses to communicate with your target.

Chapter 2 The Streamline Data View

The Streamline Data view enables you to set target connection settings, start and stop capture sessions,and create new Streamline Analysis Reports from stored capture sessions.

Chapter 3 Capture and Analysis Options

The Capture & Analysis Options dialog box enables you to change capture session settings such asduration, sample rate, and buffer size.

Chapter 4 Counter Configuration

ARM Streamline provides a Counter Configuration dialog box that enables you to modify what data iscollected at runtime.

Chapter 5 The Live View

The Live view provides capture data in real-time, updating charts as long as the capture session is active.

Chapter 6 The Timeline View

The Timeline view charts data over the course of the execution and provides a details panel with furtherinformation. The contents of the details panel is dependent on the currently selected mode.

Chapter 7 The Table Views: Call Paths, Functions, and Stack

Although the information contained in the Call Paths, Functions, and Stack views differ, their basicfunctionality is similar. Each one is a table report, with rows for each function and columns for eachstatistical category.

Chapter 8 The Code View

The Code view provides the highest level of detail in ARM Streamline. It breaks statistics down byindividual lines of code and by disassembly.

Chapter 9 The Call Graph View

The Call Graph view displays your code as a visual call hierarchy and color codes functions to highlightsbottlenecks.

Chapter 10 Streamline Annotate

This feature enables you to add annotations to your code that are propagated into the Timeline and Logviews. Color coded, timestamped annotations present efficient visualization of significant events in yourcode.

Chapter 11 The Log View

Preface About this book


The Log view lists every message generated by the ANNOTATE, ANNOTATE_COLOR and ANNOTATE_VISUALstatements in your code along with information related to the message.

Chapter 12 Capturing Energy Data

To capture energy data for Streamline you must have either an ARM Energy Probe or a supported NI-DAQ device. The ARM Energy Probe is a compact probe designed for application and system softwaredevelopers to measure any combination of power, voltage, and current in up to three channels. Thecombination of ARM Streamline and an energy capture device enable the visualization of power metricsagainst the software behavior of your target hardware. It provides a better understanding of the static anddynamic behavior of your target system for the purposes of debugging, profiling, and analysis.

Chapter 13 Advanced Customizations

Learn how to customize the more advanced collection and reporting features of ARM Streamline.

Chapter 14 Troubleshooting Common Streamline™ Issues

These topics describe how to troubleshoot common Streamline issues.

Chapter 15 Using Streamline™ on the Command Line

Much of the functionality of Streamline is available on the command line using the streamlinecommand. You can initiate capture sessions, produce Analysis Reports from existing Captures, andoutput report data, all without opening the user interface.

Glossary

The ARM Glossary is a list of terms used in ARM documentation, together with definitions for thoseterms. The ARM Glossary does not contain terms that are industry standard unless the ARM meaningdiffers from the generally accepted meaning.

See the ARM Glossary for more information.

Typographic conventions

italicIntroduces special terminology, denotes cross-references, and citations.

boldHighlights interface elements, such as menu names. Denotes signal names. Also used for termsin descriptive lists, where appropriate.

monospaceDenotes text that you can enter at the keyboard, such as commands, file and program names,and source code.

monospaceDenotes a permitted abbreviation for a command or option. You can enter the underlined textinstead of the full command or option name.

monospace italicDenotes arguments to monospace text where the argument is to be replaced by a specific value.

monospace boldDenotes language keywords when used outside example code.

<and>Encloses replaceable terms for assembler syntax where they appear in code or code fragments.For example:

MRC p15, 0 <Rd>, <CRn>, <CRm>, <Opcode_2>

SMALL CAPITALS

Used in body text for a few terms that have specific technical meanings, that are defined in theARM glossary. For example, IMPLEMENTATION DEFINED, IMPLEMENTATION SPECIFIC, UNKNOWN, andUNPREDICTABLE.



http://infocenter.arm.com/help/topic/com.arm.doc.aeg0014-/index.html

Feedback

Feedback on this product

If you have any comments or suggestions about this product, contact your supplier and give:

• The product name.• The product revision or version.• An explanation with as much information as you can provide. Include symptoms and diagnostic

procedures if appropriate.

Feedback on content

If you have comments on content then send an e-mail to [email protected]. Give:

• The title.• The number ARM DUI0482Q.• The page number(s) to which your comments refer.• A concise explanation of your comments.

ARM also welcomes general suggestions for additions and improvements.

Note

ARM tests the PDF only in Adobe Acrobat and Acrobat Reader, and cannot guarantee the quality of therepresented document when used with any other PDF reader.

Other information

• ARM Information Center.• ARM Technical Support Knowledge Articles.• Support and Maintenance.• ARM Glossary.



mailto:[email protected]

http://infocenter.arm.com/help/index.jsp

http://infocenter.arm.com/help/topic/com.arm.doc.faqs

http://www.arm.com/support/services/support-maintenance.php

http://infocenter.arm.com/help/topic/com.arm.doc.aeg0014-/index.html

Chapter 1Target Setup

ARM® Streamline™ Performance Analyzer is a system-wide visualizer and profiler for targets runningARM Linux, Android, or Chrome OS, and for Cortex®-M targets running CMSIS-RTX. To get startedusing it, you must set up your target, then build and configure gator, the mechanism that Streamlineuses to communicate with your target.It contains the following sections:

• 1.1 Features of Streamline™ Ultimate, Professional, and Community Editions on page 1-16.• 1.2 Standards compliance in Streamline™ on page 1-17.• 1.3 Streamline™ prerequisites on page 1-18.• 1.4 Preparing and building your Linux kernel on page 1-19.• 1.5 Required kernel configuration menu options on page 1-20.• 1.6 Building the gator daemon on page 1-21.• 1.7 Building the gator module on page 1-23.• 1.8 Running the gator daemon on your target on page 1-25.• 1.9 Connecting to an Android target using Ethernet on page 1-27.• 1.10 Starting a capture session on page 1-28.• 1.11 Stopping the gator daemon on page 1-29.• 1.12 gatord command line options on page 1-30.• 1.13 Setting up Streamline™ to support an ARM® Mali™-based device on page 1-31.• 1.14 Connecting to a Cortex®-M device using DSTREAM™ on page 1-33.• 1.15 Recommended compiler options on page 1-34.

ARM DUI0482Q Copyright © 2010-2014 ARM. All rights reserved. 1-15Non-Confidential

1.1 Features of Streamline™ Ultimate, Professional, and Community EditionsIf you open Streamline and are not connected to a valid license, Streamline Community Edition opensinstead of the more fully featured Ultimate or Professional Editions.

Community Edition is specifically tagged and the only views available are the Timeline and Functionsviews. All other views are only available in the Ultimate and Professional Editions.

For an up-to-date chart of Community, Professional and Ultimate Edition features, visit the DS-5™

website: http://ds.arm.com/ds-5/optimize/streamline-features/

Note

Only Ultimate Edition supports ARMv8 targets. If you open a capture generated on an ARMv8 targetand do not have a valid license for ARMv8 features, Streamline opens a Community Edition version ofthe report for that capture.

1 Target Setup1.1 Features of Streamline™ Ultimate, Professional, and Community Editions


http://ds.arm.com/ds-5/optimize/streamline-features/

1.2 Standards compliance in Streamline™

Lists the levels of compliance that Streamline conforms to.

ELFStreamline can read executable images in ELF format.

DWARFStreamline can read debug information from ELF images in the DWARF 2, DWARF 3, andDWARF 4 formats.

Note

The DWARF 2 and DWARF 3 standards are ambiguous in some areas such as debug framedata. This means that there is no guarantee that the debugger can consume the DWARFproduced by all third-party tools.

Android application package file (APK)Streamline can read all valid ELF executable images from an APK file.

Note

Streamline scans APK archives for ELF images. It extracts the ELF images and includes themas Program Images for analysis.

1 Target Setup1.2 Standards compliance in Streamline™


1.3 Streamline™ prerequisitesTo run Streamline, your hardware must meet certain specifications, and you must have certain toolsinstalled to build the gator daemon and kernel. Review this list of prerequisites before trying to set upyour target.

To run Streamline, you must have:

• An ARM-powered hardware target.• The Linux kernel source code for the target platform. Streamline supports only Linux kernel versions

2.6.32 and above.

Note

You only need the Linux kernel source code if you want a complete set of available features from thegator driver, gator.ko. You do not need the source code if you use the user space only version ofgator, although this does not support all Streamline features and is only supported for Linux kernel3.4 and later.

• The cross compiler for building the Linux kernel or GCC. You can obtain GCC at the Linaro website:http://www.linaro.org

To run Streamline with a Cortex-M3 target, you must also have:

• A DSTREAM™ device.• A platform with an ETM trace port.

Related tasks1.4 Preparing and building your Linux kernel on page 1-19.1.6 Building the gator daemon on page 1-21.1.7 Building the gator module on page 1-23.1.8 Running the gator daemon on your target on page 1-25.1.10 Starting a capture session on page 1-28.

1 Target Setup1.3 Streamline™ prerequisites


http://www.linaro.org

1.4 Preparing and building your Linux kernelStreamline requires that you build your Linux kernel with certain options enabled. These instructions arespecific to building a Linux kernel. Ignore these steps if you are running Android.

To prepare your kernel for use with Streamline, follow these steps:

Procedure

1. Download one of the supported versions of the Linux kernel and configure it.For instructions on how to do this and the required kernel code, visit http://www.kernel.org.

Note

You can build and configure the gator driver gator.ko by unpacking gator-driver.tar.gz directlyinto the Linux kernel source tree. On Linux, this file is located in the directory /usr/local/DS-5/arm/gator/driver-src. For more information, see the topic Building the gator module.

2. Enter the following command in your shell to export the cross compiler:export CROSS_COMPILE=${CROSS_TOOLS}/bin/arm-linux-gnueabihf-

3. To specify that this build is for an ARM architecture, enter the following command in your shell:export ARCH=arm

4. Enter the following to build the configuration file specific to your platform:make platform_defconfig

Replace platform_defconfig in the command with one of the configuration files located in theyour_kernel/arch/arm/configs directory appropriate for your platform or with a configuration fileprovided by a vendor.

5. To build the command-line kernel configuration tool, enter the following in your shell:make menuconfig

6. Set the required kernel configuration menu options. These options are described in the Requiredkernel configuration menu options reference topic.

7. Use the following command to build the image:make -j5 uImage

The uImage should be installed and booted before moving on to the next step.8. Verify all of your kernel options on a running system using /proc/config.gz, if it exists on your

system. For example, to confirm that CONFIG_PROFILING is enabled, enter:zcat /proc/config.gz | grep CONFIG_PROFILING

Related tasks1.6 Building the gator daemon on page 1-21.1.7 Building the gator module on page 1-23.1.8 Running the gator daemon on your target on page 1-25.1.10 Starting a capture session on page 1-28.

Related references1.3 Streamline™ prerequisites on page 1-18.1.5 Required kernel configuration menu options on page 1-20.

1 Target Setup1.4 Preparing and building your Linux kernel


http://www.kernel.org

1.5 Required kernel configuration menu optionsWhether you are running Linux or Android on your target, you must enable certain kernel configurationoptions to run Streamline.

The following menus have options that are required for Streamline:

Note

If these options are not set correctly, you must change them and rebuild your kernel. If they are setcorrectly, you are ready to build and install the gator driver.

Note

The location of these options might change between releases. If so, use the search option in menuconfigto find them.

General SetupEnable the Profiling Support option, CONFIG_PROFILING and the Kernel performance eventand counters option, CONFIG_PERF_EVENTS.

Kernel FeaturesEnable the High Resolution Timer Support option, CONFIG_HIGH_RES_TIMERS and the Enablehardware performance counter support option, CONFIG_HW_PERF_EVENTS. Enable the Uselocal timer interrupts option, CONFIG_LOCAL_TIMERS, if you are using a SymmetricMultiProcessing (SMP). The CONFIG_LOCAL_TIMERS option is not necessary if you are runningon Linux version 3.12 or later.

CPU Power ManagementTo enable the CPU Freq Timeline view chart, gator requires kernel version 2.6.38 or greaterand that you define the CPU Frequency scaling > CPU Frequency scaling option,CONFIG_CPU_FREQ.

Note

The Trace context switches and events option, CONFIG_ENABLE_DEFAULT_TRACERS, is not visibleif you have other Tracers configuration options enabled. Enabling other Tracers configurationoptions is sufficient to turn on context switches and events and run Streamline.CONFIG_GENERIC_TRACER or CONFIG_TRACING also work to enable tracing. The Trace processcontext switches and events option may not be visible in menuconfig as an option if other traceconfigurations are enabled. Enabling one of these other trace configurations works fine to turnon tracing.

Related tasks1.4 Preparing and building your Linux kernel on page 1-19.

1 Target Setup1.5 Required kernel configuration menu options


1.6 Building the gator daemonWhen you have built the gator daemon and loaded it on your target, Streamline uses it to communicatewith your device.

Note

It is not possible to build the gator daemon or driver on a Windows host.

Note

Your DS-5 installation includes a pre-built gatord binary, which you can install onto your target.Alternatively, you can build gatord yourself following the steps outlined in this topic. For fullfunctionality, gatord requires an accompanying gator driver, gator.ko. gatord can run withoutgator.ko on Linux or Android 3.4 or later, but is restricted to using user space APIs and does notsupport all Streamline features. For more information, see the readme included in the gator directory.

To build the gator daemon, follow these steps:

Procedure

1. Enter the following command to extract the archive that contains the gator daemon source:tar xzf <DS_install_directory>/arm/gator/daemon-src/gator-daemon.tar.gz

Note

Make sure you extract this file into a directory in which you have write privileges.

2. Change directory to the newly created gator-daemon. This step varies depending on whether you arerunning Linux or Android.

• For Linux, enter:

cd gator-daemon

• For Android, enter:

mv gator-daemon jni

3. Issue the commands to build gatord.

• To build gatord for a Linux target, enter:

make CROSS_COMPILE=${CROSS_TOOLS}/bin/arm-linux-gnueabihf-

Note

To do this, you must have a g++-enabled build host toolchain. If the target is g++-enabled, youcan build directly on it. On a Linaro Ubuntu target, you must enter the following command toinstall g++:

sudo apt-get install g++

• To build gatord for Android, enter:

<NDK_install_directory>/ndk-build

Note

Before you do this, you must have installed the Android NDK. For information, see the AndroidNDK website, http://developer.android.com/sdk/ndk.

1 Target Setup1.6 Building the gator daemon


http://developer.android.com/sdk/ndk

4. If you did not build the gator daemon on the target, transfer gatord to the target and then move it tothe appropriate directory. Which directory is appropriate is dependent on the target.

5. Make gatord executable by entering the following command:chmod +x gatord

Related tasks1.4 Preparing and building your Linux kernel on page 1-19.1.7 Building the gator module on page 1-23.1.8 Running the gator daemon on your target on page 1-25.1.10 Starting a capture session on page 1-28.

Related references1.3 Streamline™ prerequisites on page 1-18.

1 Target Setup1.6 Building the gator daemon


1.7 Building the gator moduleTo get the full functionality of Streamline, you must build the gator driver, gator.ko, and place it in thetarget file system.

If you do not build the gator.ko driver, Streamline uses a user space only version of gatord whichprovides a subset of the functionality that it provides when supported by the gator.ko module. Thisrequires Linux 3.4 or later. For more information, see the readme included in the gator directory.

DS-5 provides the source code for gator.ko in an archive called gator-driver.tar.gz.

Procedure

Assuming that you have extracted the archive and that you have all of the required tools for buildingkernel modules, you can build gator.ko either by using a build command or by integrating it into thekernel build system. The build command to use depends on whether you are building on a Linux hostor a target.Use one of the following ways to build gator.ko:

• On a Linux host, use the following build command:

make -C <kernel_build_dir> M=`pwd` ARCH=arm CROSS_COMPILE=${CROSS_TOOLS}/bin/arm-linux-gnueabihf- modules

Note

You must remove the comment hashtag from the following line in the makefile of the gatormodule to enable kernel stack unwinding:

# EXTRA_CFLAGS += -DGATOR_KERNEL_STACK_UNWINDING

• On a target, use the following build command:

make -C <kernel_build_dir> M=`pwd`

• To integrate gator.ko into the kernel build system, use the following instructions:

cd <kernel_build_dir>cd driversmkdir gatorcp -r <path_to_gator_driver_src>/* gator

Add the following line to the end of Makefile in the kernel drivers folder:

obj-$(CONFIG_GATOR) += gator/

Add the following line before the last endmenu in Kconfig in the kernel drivers folder:

source "drivers/gator/Kconfig"

This enables you to select and rebuild gator when using menuconfig to configure the kernel.

To add support for an ARM Mali™-based processor, you must specify some additional options whenbuilding the gator module.

Related tasks1.4 Preparing and building your Linux kernel on page 1-19.1.6 Building the gator daemon on page 1-21.1.8 Running the gator daemon on your target on page 1-25.1.10 Starting a capture session on page 1-28.1.13 Setting up Streamline™ to support an ARM® Mali™-based device on page 1-31.13.7 Getting L2C-310 memory-mapped peripherals working with Streamline on page 13-184.13.8 Profiling the Linux kernel on page 13-185.

1 Target Setup1.7 Building the gator module


Related references1.3 Streamline™ prerequisites on page 1-18.

1 Target Setup1.7 Building the gator module


1.8 Running the gator daemon on your targetWhen all of the necessary files are in place, you can start the gator daemon. gatord needs to be activelyrunning for Streamline to initiate a capture session over Ethernet or USB. This setup task applies to bothLinux and Android targets.

To run gatord, follow these steps:

Procedure

1. Copy gatord and gator.ko into the file system on the target. On Android, you can do this on yourhost using adb push.

2. To ensure gatord has execute permission, enter the following command:chmod +x gatord

On Android, you can execute this command using adb shell.3. Optional: If gatord is in a different directory to gator.ko on the target, you must do one of the

following:

• Insert the gator.ko module manually using the following command:

insmod gator.ko

• Include the path to gator.ko using the -m option to gatord. For example:

./gatord -m /home/gator/gator.ko &

If gatord does not exist in the same directory as gator.ko and you do not either manually insertgator.ko or include a path to it when running gatord, a user space only version of gatord runswhen the command is executed. This user space version of gatord has most, but not all of thefunctionality of the standard version of gatord running with the gator.ko module.

For more information, see the readme included in the gator directory.4. After making sure that you have root privileges, enter the following to execute the gator daemon:

./gatord &

By default, gatord uses port 8080 for communication with the host, but you can adjust this bylaunching gatord with the port number as a parameter. For example:

./gatord -p 5050 &

Additionally, specify the port number using the Capture & Analysis Options dialog box byappending a colon followed by the port number to the IP address in the address field. For example, ifthe address is 10.99.28.54 and the port is 5050 you enter 10.99.28.54:5050. If you do not provide aport number, the default port is used.

gatord requires the libstdc++.so.6 library. This file is usually supplied with the Linux distributionon your target. A copy of libstdc++.so.6 is available in the DS-5 Linux example distribution.If you use Security-Enhanced Linux (SELinux), you might see one of the following errors whenrunning gatord:

• Unable to mount the gator filesystem needed for profiling.

• Unable to load (insmod) gator.ko driver: >>> gator.ko must be built against the current kernel version & configuration >>> See dmesg for more details

If you see one of these error messages, enter the dmesg command for more details.

If the output from dmesg contains the text SELinux: initialized (dev gatorfs, typegatorfs), not configured for labeling, enter the following command to disable SELinux:

setenforce 0

After gatord has started, you can re-enable SELinux by using the following command:

1 Target Setup1.8 Running the gator daemon on your target


setenforce 1

Related tasks1.4 Preparing and building your Linux kernel on page 1-19.1.6 Building the gator daemon on page 1-21.1.7 Building the gator module on page 1-23.1.10 Starting a capture session on page 1-28.1.11 Stopping the gator daemon on page 1-29.

Related references1.3 Streamline™ prerequisites on page 1-18.1.15 Recommended compiler options on page 1-34.

1 Target Setup1.8 Running the gator daemon on your target


1.9 Connecting to an Android target using EthernetStreamline supports connecting to your Android target using Ethernet. Using the Android Debug Bridge(ADB) utility that is part of the Android SDK, it is possible to forward a TCP port from the target to yourlocal host over a USB or Ethernet connection. ADB can also be configured to work over Ethernet.

Note

For more information about the Android SDK and ADB setup, see the Android website: http://developer.android.com/tools/help/adb.html

When you have successfully set up ADB, follow this step to forward the Streamline port to yourlocalhost:

Procedure

Enter the following command:adb forward tcp:8080 tcp:8080

Related tasks1.10 Starting a capture session on page 1-28.

1 Target Setup1.9 Connecting to an Android target using Ethernet


http://developer.android.com/tools/help/adb.html

http://developer.android.com/tools/help/adb.html

1.10 Starting a capture sessionOnce you have the gator driver and daemon up and running, you are ready to run a capture session usingthe Streamline Data view in Eclipse for DS-5.

To initiate a capture session in Eclipse for DS-5, follow these steps:

Procedure

1. Open the Streamline Data view. To do so, select Window > Show View > Other...2. Expand the DS-5 group.3. Select Streamline Data.4. Enter an IP address in the Address field at the top of the Streamline Data view.

If you have an Android target and use the ADB to forward the port, enter localhost in the Addressfield.

5. Click the Start Capture button.

Figure 1-1 The Start Capture button

If an up-to-date version of gator is running on your Streamline-compatible target, this triggers the start ofthe Live view, which plots capture data on the bar graphs in real time.

Related tasks1.4 Preparing and building your Linux kernel on page 1-19.1.6 Building the gator daemon on page 1-21.1.7 Building the gator module on page 1-23.1.8 Running the gator daemon on your target on page 1-25.1.9 Connecting to an Android target using Ethernet on page 1-27.

Related references1.3 Streamline™ prerequisites on page 1-18.14.1 Troubleshooting target connection issues on page 14-190.3.2 Capture & Analysis Options dialog box settings on page 3-45.

1 Target Setup1.10 Starting a capture session


1.11 Stopping the gator daemonYou might want to shut down the gator daemon, for example when updating it with a newer version.

To stop the gator daemon, follow these steps:

Procedure

1. Determine the process id of gatord using the following command:ps ax | grep gatord

2. Kill the identified process using the following command:kill process_id

Replace process_id with the process identification number obtained in the previous step.

Note

When you remove the gator daemon from the target, you must also unload the gator module so that theupdated gator daemon matches the gator driver version. To check if the gator module is running, enterthe following on the command line of your target:

lsmod | grep gator

If the gator module is loaded, unload it using the following command:

rmmod gator

You must be logged in as root to do this.

1 Target Setup1.11 Stopping the gator daemon


1.12 gatord command line optionsWhen you start gatord on the command line, you can pass any number of options to it, including optionsthat define the location of the gator.ko module and the configurable xml files it uses to define theparameters of the capture session.

You can use the following options with gatord:

-cSets the location of the configuration.xml file that defines the capture options. Include thedirectory location and the file name. This option is useful when the directory containing gatordis not writable.

-eDefines the location of the events.xml file to use with gatord. events.xml defines the countersthat Streamline collects during the capture session. Include the directory location and the filename.

-hLists all of the available gatord command-line options.

-mIf gator.ko is located in a different directory to gatord, use the -m option to define the locationof gator.ko.

-pSets the port number that gatord uses to communicate with the host.

-sDefines the location of the session.xml file. Include the directory location and the file name.This option is most useful when performing a local capture.

-oUseful when performing a local capture, use this option to define the location of the APCdirectory.

-vDisplays the version information for gatord.

1 Target Setup1.12 gatord command line options


1.13 Setting up Streamline™ to support an ARM® Mali™-based deviceStreamline enables you to gather GPU-specific profiling data on a Mali-400, Mali-450, or Mali-T6xxbased device, adding a significant amount of data about the graphical performance of your target to theAnalysis Reports.

To use Streamline with a Mali-based device, you must have the following:

• A Mali-4xx, or Mali-T6xx based device.• A sufficiently recent version of the mali.ko driver. The driver must be capable of generating the

tracepoints needed by the gator.ko driver. Consult your supplier to see if this version of the driver isavailable for your device. For more information, see the Mali Developer site, http://www.malideveloper.com

Follow normal installation and setup instructions for Streamline and the gator daemon. You also need tobuild the gator driver, gator.ko with support for Mali technology. For best results, build it in-tree, at<kernel_build_dir>/drivers/gator and configure it using menuconfig options. The followinginstructions describe what these options mean and how to build gator.ko for a Mali-based device out-of-tree.

Procedure

1. Streamline only supports one type of GPU (and driver version) at once, and you choose this at buildtime.

• For a Mali-4xx GPU, specify the following options to your gator.ko make command:

GATOR_WITH_MALI_SUPPORT=MALI_4xx # Set by CONFIG_GATOR_MALI_4XXMP

# gator source needs to #include "linux/mali_linux_trace.h"CONFIG_GATOR_MALI_PATH=".../<path_to_Mali_DDK_kernel_files>/src/devicedrv/mali"

GATOR_MALI_INTERFACE_STYLE=<3|4> # 3=Mali-400 DDK >= r3p0-04rel0 and < r3p2-01rel3 # 4=Mali-400 DDK >= r3p2-01rel3 # A default of 4 is set in gator-driver/gator_events_mali_4xx.c

To add the corresponding support to Mali technology, Userspace needs the following:

— MALI_TIMELINE_PROFILING_ENABLED=1— MALI_FRAMEBUFFER_DUMP_ENABLED=1— MALI_SW_COUNTERS_ENABLED=1

The Kernel driver needs USING_PROFILING=1 # Sets CONFIG_MALI400_PROFILING=y

These settings are the defaults in later driver versions. See the DDK integration guide for moredetails.

• For a Mali-T6xx GPU, specify the following options to your gator.ko make command:

GATOR_WITH_MALI_SUPPORT=MALI_T6xx # Set by CONFIG_GATOR_MALI_T6XX

# gator source needs access to headers under .../kernel/drivers/gpu/arm/... # a default of . is suitable for in-tree buildsDDK_DIR=".../<path_to_Mali_DDK_kernel_files>"

Add the streamline_annotate=1 option if you want visual annotations.

To add the corresponding support to Mali technology, Userspace (scons) needs gator=1.

The Kernel driver needs CONFIG_MALI_GATOR_SUPPORT=y.

See the DDK integration guide for more details.2. Insert the gator module as normal:

insmod gator.ko

3. Verify that you built the module successfully:

1 Target Setup1.13 Setting up Streamline™ to support an ARM® Mali™-based device


http://www.malideveloper.com


ls -l /dev/gator/events/ARM_Mali_Device_Type

Replace Mali_Device_Type in the command with either Mali-4xx* or Mali-T6xx*. This commandshould produce a list of counters.

If you have successfully built the gator module with support for Mali technology, you can run a capturesession on a Mali-based target. Follow the normal instructions for setting capture options and triggering acapture session.

1 Target Setup1.13 Setting up Streamline™ to support an ARM® Mali™-based device


1.14 Connecting to a Cortex®-M device using DSTREAM™

You can capture data for Streamline on a Cortex-M device by connecting a DSTREAM unit to theInstrumentation Trace Macrocell (ITM) Stimulus Port on the target and making minor changes toproject_types.xml file for your board.

To connect Streamline to a Cortex-M target:

Procedure

1. Build the RTX library with debug info and the preprocessor define DBG_MSG. ITM instrumentationrequires this.

2. Connect a DSTREAM unit to the ITM port on your target.3. Make sure your target is connected to your host.

Note

For Streamline to be compatible with a target, there must already be a DSTREAM connection for thatboard in the configdb that supports debug and trace.

4. Add the following lines of code to the project_types.xml for your board at the end of the activityXML node that corresponds to the DSTREAM debug and trace connection:

<streamline_setup_script><name>CDB://../../../Scripts/streamline_setup_script_m3.py</name><arguments></arguments></streamline_setup_script>

Note

The projects_types.xml file for a target is located in <DS-5_install_directory>/sw/debugger/configdb/Boards/<Your_Board_Type>/<Your_Board>/.

Open this file and add the above lines to the DSTREAM activity node. If your target is notavailable in the default Debug Configuration, then you may need to create a custom DebugConfiguration in a separate folder. For example, /home/user/configdb.

This process is explained in more detail here:

http://infocenter.arm.com/help/topic/com.arm.doc.faqs/ka15562.html

5. Reset the target after a capture starts in order to enable RTX to output the ITM task switchinformation.Task names are only emitted over ITM at the time of the task creation.

Your target appears in the Connection Browser of the Streamline Data view.

1 Target Setup1.14 Connecting to a Cortex®-M device using DSTREAM™


http://infocenter.arm.com/help/topic/com.arm.doc.faqs/ka15562.html

1.15 Recommended compiler optionsWhen building executables for profiling using Streamline, it is best practice to use the GCC compileroptions listed in this topic.

-gTurns on the debug symbols necessary for quality Analysis Reports. Compile using this optionto create the ELF files for your host. Use the Capture & Analysis Options dialog box tospecify the ELF files to use in a Streamline session.

-fno-inlineDisables inlining and substantially improves the call path quality.

-fno-omit-frame-pointerCompiles your EABI images and libraries with frame pointers. This enables Streamline torecord the call stack with each sample taken.

-marmThis option is required if GCC is compiled with the --with-mode=thumb option enabled.Using the --with-mode=thumb option without -marm breaks call stack unwinding in Streamline.

Note

Call stack unwinding is not supported for Thumb code or output from armcc.

Related tasks1.8 Running the gator daemon on your target on page 1-25.

1 Target Setup1.15 Recommended compiler options


Chapter 2The Streamline Data View

The Streamline Data view enables you to set target connection settings, start and stop capture sessions,and create new Streamline Analysis Reports from stored capture sessions.It contains the following sections:

• 2.1 Opening the Streamline Data view on page 2-36.• 2.2 Streamline™ Data view toolbar options on page 2-37.• 2.3 Capture color-coding on page 2-39.• 2.4 The Connection Browser dialog box on page 2-40.• 2.5 Analysis Data Locations dialog box options on page 2-41.• 2.6 Duplicating a capture on page 2-42.


2.1 Opening the Streamline Data viewThe Streamline Data view is your command center for much of the functionality of Streamline. Usingthis view, you can change capture options, edit counter configurations, manage your existing Streamlinecaptures, and start new capture sessions.

To open the Streamline Data view:

Procedure

1. Select Window > Show View > Other...2. Expand the DS-5 group.3. Select Streamline Data.

Figure 2-1 The Streamline Data view

Note

As of version 5.17, Streamline no longer produces a separate .apd Analysis Report. It now embeds thereport data in the capture. Use the Analyze button to generate new report data from an existing capture.It will overwrite the existing capture. Use the Duplicate contextual menu if you want to preserve theoriginal capture.

Related tasks13.9 Re-analyzing Stored Streamline Capture Data on page 13-186.

Related references2.2 Streamline™ Data view toolbar options on page 2-37.2.2 Streamline™ Data view toolbar options on page 2-37.3.2 Capture & Analysis Options dialog box settings on page 3-45.

2 The Streamline Data View2.1 Opening the Streamline Data view


2.2 Streamline™ Data view toolbar optionsThe toolbar of the Streamline Data view enables you to change capture options, edit counterconfigurations, start new capture sessions, and manage your existing Streamline captures.

The following controls are available in the toolbar of the Streamline Data view:

Show HelpOpens a list of help topics for the Streamline Data view in a Help view.

Collapse allCollapses all captures in the Streamline Data view, hiding the detailed information for everycapture. This option is disabled if all captures are already collapsed.

Expand allExpands all captures in the Streamline Data view, exposing detailed information for each. Thisoption is disabled if all captures are already expanded.

DeleteDeletes a stored capture from the file system.

RefreshRefreshes the contents of the Streamline Data view. If you have added Streamline files to any ofyour defined locations outside of Eclipse, use Refresh to sync this view.

Edit Locations...Opens the Analysis Data Locations dialog box, which enables you to define the folders on yourfile system that contain Streamline data.

Export Capture File(s)...Opens a dialog box that enables you to save the currently selected .apc directories as ziparchives that you can later import into Streamline using the Import Capture File(s)... option.

Import Capture File(s)...Opens a File System dialog box. To import a capture, navigate to a .zip archive that contains avalid .apc directory, select it, then click Open. The newly imported capture now appears in thelist of captures and in the Streamline Data view.

Start CaptureStarts a capture session. Streamline uses your settings from the Capture & Analysis Optionsdialog box. If you have not defined settings using the Capture & Analysis Options dialog box,Streamline connects to the target at the address that you entered in the Address field usingdefault values for each of the capture options. Once clicked, a dialog box appears that promptsyou to enter a title for the capture.Streamline adds the parent directory of the capture to the Analysis Data Locations list if it isnot already there. When the capture session stops, Streamline generates report data based on thesettings in the Capture & Analysis Options dialog box. You can use this dialog box to set acapture session length. If you want to control the length of the session yourself, you can use theStreamline data view to terminate it manually. To do so, click the either the Stop button thatappears on the left in the new capture entry or the Stop button in the Live view.

Counter configurationOpens the Counter Configuration dialog box. Use it to modify the performance counterstracked during your capture session.

Capture & Analysis OptionsOpens the Capture & Analysis Options dialog box. Use it to set the parameters of any futurecapture sessions.

Connection fieldEnter the network name or IP address of your target. Click the Browse for a target button toopen the Connection Browser dialog box where you can select a target from a list of availabletargets on your network. Select one, then click the Select button. The Connection field updatesto show the newly selected target.

2 The Streamline Data View2.2 Streamline™ Data view toolbar options


Filter fieldEnter a string in this field to display only the captures whose name contains this string.

Analyze...The Analyze... button appears if you use the disclosure control to show more information aboutan individual capture. Use this button, or the Analyze... option from the Streamline Data viewcontextual menu to produce a new report based on the capture session data.

Related tasks2.1 Opening the Streamline Data view on page 2-36.13.9 Re-analyzing Stored Streamline Capture Data on page 13-186.2.1 Opening the Streamline Data view on page 2-36.

Related references2.4 The Connection Browser dialog box on page 2-40.

2 The Streamline Data View2.2 Streamline™ Data view toolbar options


2.3 Capture color-codingEach of the captures in the Streamline Data view has a color-coded bar to its left. The color of the bartells you the status of the capture and dictates what happens when you double-click on it.

The following colors can appear next to a capture:

BlueBlue indicates a working capture that contains a report compatible with the current version ofStreamline. Double-click on a blue capture to open its report in the Editor section of Eclipse forDS-5.

AmberAmber indicates a capture that needs to be re-analyzed, as its report is missing or incompatiblewith the current version of Streamline. Generate a new capture by either clicking the Analyzebutton or by double-clicking on the capture.

RedThis capture does not have valid report data and it can not be re-analyzed. You must run anothercapture session on your target. This is most common in captures produced by a much earlierversion of Streamline.

2 The Streamline Data View2.3 Capture color-coding


2.4 The Connection Browser dialog boxThe Connection Browser dialog box, opened from the Streamline Data view, enables you to find yourdesired target and select it without having to look up its name or IP address.

When you click the Browse for a target button in the Connection field of the Streamline Data view,Streamline searches your network and provides a selectable list of possible targets. The ConnectionBrowser sorts the targets by type:

DSTREAMLists all DSTREAM targets available on the network. If you select a DSTREAM unit from thislist, you must also specify the type of hardware the DSTREAM unit is connected to, using theTarget Type Browser in the Capture & Analysis Options dialog box.

Note

Streamline does not support all target types connected through a DSTREAM unit. The list thatappears in the Target Type Browser is a list of all currently supported DSTREAM -connectedtargets.

Streamline AgentLists all targets connected directly to the network that have gator installed and running. Theseare the most common targets for Streamline. If you select one of these targets, the Target Type,shown in the Capture & Analysis Options dialog box, is set to Streamline Agent. Keep thisvalue when using a board not connected to a debug device.

Related references3.2 Capture & Analysis Options dialog box settings on page 3-45.2.2 Streamline™ Data view toolbar options on page 2-37.

2 The Streamline Data View2.4 The Connection Browser dialog box


2.5 Analysis Data Locations dialog box optionsUse the Analysis Data Location dialog box to define locations on your file system that containStreamline analysis data. The analysis data can be capture data or Streamline Analysis Reports.

The following buttons are included in the Analysis Data Locations dialog box:

AddOpens another dialog box that enables you to search your file system to add a new folder to thelist.

Note

There is a sample Streamline capture in the xaos sample directory if you have not alreadycreated one of your own. Use the Add button and choose the xaos project directory to make theexample capture appear in the Streamline Data view.

RemoveDeletes a folder from the list.

OKCloses the dialog box. All captures in the newly defined folders appear in the Streamline Dataview.

CancelDiscards any current changes to the list of locations and exits the dialog box.

ResetReturns the defined folders to the default list. The default folder depends on your OS:

• On Windows, it is C:\Users\<user_name>\Documents\Streamline.• On Linux, it is ~/Documents/Streamline.

2 The Streamline Data View2.5 Analysis Data Locations dialog box options


2.6 Duplicating a captureYou can duplicate any existing capture in the Streamline data view using the contextual menu. This canbe advantageous in cases where you want to re-analyze a capture with new options while maintaining theoriginal capture.

To duplicate a capture:

Procedure

1. Right-click on the capture.2. Choose Duplicate from the resulting contextual menu.3. In the New Name dialog box, give the Duplicate Streamline Document a new name.

Figure 2-2 Duplicating a capture

2 The Streamline Data View2.6 Duplicating a capture


Chapter 3Capture and Analysis Options

The Capture & Analysis Options dialog box enables you to change capture session settings such asduration, sample rate, and buffer size.It contains the following sections:

• 3.1 Opening the Capture & Analysis Options dialog box on page 3-44.• 3.2 Capture & Analysis Options dialog box settings on page 3-45.


3.1 Opening the Capture & Analysis Options dialog boxUse the Capture & Analysis Options dialog box to set up the parameters for your capture session.

To open it:

Procedure

1. Open the Streamline Data view if it is not already open. Select Window > Show View > Other andchoose Streamline Data from the DS-5 folder.

2. Click the Capture & Analysis Options button.

Figure 3-1 The Capture & Analysis Options button

3 Capture and Analysis Options3.1 Opening the Capture & Analysis Options dialog box


3.2 Capture & Analysis Options dialog box settingsThe Capture & Analysis Options dialog box enables you to change the capture session settings,including address, duration, sample rate, and buffer size.

It contains several sections, each providing a set of options.

Figure 3-2 The Capture & Analysis Options dialog box

Connection settings

The Connection section contains the following settings:

AddressThe network address of the target. You can alternatively enter the network name of your target.The value given in this field overwrites the value in the Address field of the Streamline Dataview, if one has been given. The reverse is also true. If you enter a new address in the Addressfield of the Streamline Data view, it replaces the value entered here.

3 Capture and Analysis Options3.2 Capture & Analysis Options dialog box settings


Browse for a target buttonUse the Browse for a target button on the right side of the Address field to open theConnection Browser. Streamline searches your network and produces a list of possibletargets. Selecting one populates the Address field.

Target TypeClick on the Target Type button to open the Target Type browser. If you are connected directlyto your gator-enabled target, select Streamline Agent from the list. If you are connected to atarget through a DSTREAM unit, select your hardware from the list.

Note

By default, Streamline uses port 8080 to connect to a target. To use a different port, specify one here byentering a colon and a port number after the IP address. For example, enter Your_IP_address:1010 touse port 1010 to connect to the target.

Note

If you use the port forwarding of Android ADB with USB, enter localhost in the Address field.

Capture settings

The Capture section contains the following options:

Sample RateThe target generates periodic measurement interrupts according to the following settings:Normal=1kHz, Low=100Hz, and None=0Hz. The Normal setting works well for mostinstances. Low is recommended if you have a slow target, or if the target is heavily loaded, asthe Low setting means less intrusion by Streamline. The Low setting does necessitate a longercapture to collect representative data. If you set Sample Rate to None, Streamline does not forcethe target to generate any periodic measurement interrupts. This ensures that Streamline has thelowest level of intrusion on your code, but also means that resulting reports show only zeroes inany report columns that rely on sampling.

Buffer ModeThe default setting is Streaming, which enables unbounded streaming of target data directly toyour host using a 1MB buffer. You can also use one of the following store-and-forward buffers:

Mode Buffer size

Large 16MB

Medium 4MB

Small 1MB

If you select one of these sizes, the capture ends when the buffer is full. This prevents theintrusion caused by streaming data from the target to the host.

Note

You must set the Buffer Mode to Streaming to enable Live view. If you select one of the buffersizes, the Live view does not display real-time data during the capture session.



Call stack unwindingSelect this checkbox to ensure that Streamline records call stacks. This greatly improves thevisibility of the behavior of the target, but increases the amount of raw data Streamline sendsfrom the target to the host. Make sure you compile your EABI images and libraries with framepointers enabled using the -fno-omit-frame-pointer compilation option. If GCC is compiledwith the --with-mode=thumb option, you must also use the -marm option.

Note

Streamline supports call stack unwinding for ARM binaries created using GCC, provided youcompile them with frame pointers enabled. Streamline does not support output from armcc.

Discard DataIf this option is enabled, Streamline discards all data when you terminate the capture. Use thisoption if you only want to see the data that streams during a capture session and do not want togenerate a capture.

If you use this option, a red x appears over the Terminate Capture button in the Live view.

Figure 3-3 The Stop button in the Live view with Discard Data option enabled

DurationThe length of the capture session, in minutes and seconds. For example, enter 1:05 for 1 minuteand 5 seconds. If you do not provide a value here, the capture session continues until you stop itmanually, or the buffer is full.

Energy Capture settings

The following settings define your Energy Capture device:

Energy Capture drop-down menuThis menu has three options. Select No Energy Data Collection to turn Energy Capture off.When you enable this option, all other Energy Capture options are disabled. Select ARMEnergy Probe or National Instruments DAQ to match your energy capture hardware.

DeviceUse this field to give Streamline the name of your target energy capture device. Streamlineattempts to auto-detect your device if this field is left blank.

Note

When using ARM Energy Probe on Linux, enter /dev/ttyACM0 in the Device field, if required.When using NI-DAQ, the device name is usually Dev1.

PortThe port Streamline uses to communicate with your chosen energy capture device. The defaultport is 8081.



Tool PathUse this field to define the path to the caiman.exe executable, which is required to use eitherthe ARM Energy Probe or a NI-DAQ device to gather power output statistics. The button to theright of this field enables you to search your file system.

In addition to the settings that define your capture device, the Energy Probe section has configurationoptions that apply to each channel:

PowerWhen enabled, Streamline collects power data on this channel.

VoltageWhen enabled, Streamline collects voltage data on this channel.

CurrentWhen enabled, Streamline collects current information for this channel.

ResistanceUse this field to define the value, in milliohms, of the shunt resistor that connects to each of theavailable channels. The default setting is 20 milliohms.

Analysis settings

The Analysis section contains the following controls:

Process Debug Information (when available) checkboxIf you enable this option, Streamline processes DWARF debug information and line numbers.This provides a higher level of detail in your captures, but results in higher memory usage. Thisoption does not affect the data collected during the capture session. It only affects the report dataautomatically generated after the termination of the capture session. This option can be changedwhen you re-analyze the stored Capture.

Note

You must have built the image using the -g compiler option in order to enable this feature.

Note

If you disable this feature, the source section of the Code view does not display the source codeor source code statistics. The disassembly is still available with this option disabled, but thesource section shows only a No source available message.

High Resolution Timeline checkboxIf you select this checkbox, Streamline processes more data, enabling you to zoom in further inthe Timeline view. By default, the highest resolution in the Timeline view is milliseconds, butwith this option enabled, you can zoom in to microsecond bin sizes.

This option does not affect the data collected during the capture session. It only affects thereport data automatically generated after the termination of the capture session. This option canbe changed when you re-analyze the stored capture data.

Program Images section

Use this area to explore your file system and define all of the images and libraries that you want toprofile.

The images defined here do not affect the data collected during the capture session. They only affect thereport data automatically generated after the termination of the capture session. These images can bechanged when you re-analyze the stored capture.



Note

When compiling images on your host, make sure you set the -g compilation option to enable debugsymbols.

Note

Disabling inlining with the -fno-inline compiler setting substantially improves the call path quality.

The following buttons are included in the Program Images section of the Capture & Analysis Optionsdialog box:

Add ELF Image...Opens a file system dialog box that you can use to choose images to add. Select the image,executable, or Android Package File (APK) and click Open to add the file to the list.

Add ELF Image from Workspace...Opens a file from your Eclipse workspace.

Toggle Symbol LoadingActivates or deactivates symbol loading for the selected image, executable, or APK. An eyeappears next to any entry in the list with symbol loading turned on.

Figure 3-4 Symbols loaded icon

Using this option instead of removing an entry from the list makes it easy to toggle an entry onand off over multiple runs, as it does not remove it from the Program Images list.

RemoveRemoves the selected entries.

ImportUse the resulting file system dialog box to find an existing session.xml file and import itssettings to the Capture & Analysis Options dialog box.

ExportSaves the current settings as an xml file.

SaveSaves the settings and exits.

CancelDiscards all changes and exits.

Related tasks12.9 Setting up National Instrument Multifunction Data Acquisition devices (NI-DAQ) to capture energydata on page 12-174.13.9 Re-analyzing Stored Streamline Capture Data on page 13-186.2.1 Opening the Streamline Data view on page 2-36.1.10 Starting a capture session on page 1-28.

Related references2.4 The Connection Browser dialog box on page 2-40.14.1 Troubleshooting target connection issues on page 14-190.



14.2 Troubleshooting report issues on page 14-191.7.5 Call Paths view column headers on page 7-125.



Chapter 4Counter Configuration

ARM Streamline provides a Counter Configuration dialog box that enables you to modify what data iscollected at runtime.It contains the following sections:

• 4.1 Counter Configuration dialog box structure on page 4-52.• 4.2 Opening the Counter Configuration dialog box on page 4-54.• 4.3 Adding new events to the Events to Collect list on page 4-55.• 4.4 Removing events from the Events to Collect list on page 4-57.• 4.5 Counter Configuration toolbar options on page 4-58.• 4.6 Events specific to ARM® Mali™ technology on page 4-59.• 4.7 Events-based sampling on page 4-60.• 4.8 Setting up events-based sampling on page 4-61.


4.1 Counter Configuration dialog box structureThe Counter Configuration dialog box contains two main areas, Available Events and Events toCollect. Use the list in Available Events to populate the Events to Collect list with your desiredcounters.

Figure 4-1 The Counter Configuration dialog box

The dialog box contains the following two areas:

4 Counter Configuration4.1 Counter Configuration dialog box structure


Available EventsThe Available Events list contains categorized events offered for each core on your currenttarget as well as a list of OS-specific events. The events contained in the processor lists dependson the type of processor as does the number of events that you can add. Events that appear ingray are already in the Events to Collect list.

Note

As of version 5.14, Streamline supports hardware monitoring counters, if they are available onyour target hardware.

The maximum number of available events and the amount remaining are in the upper right handcorner of the Available Events list. When you have reached this maximum, all entries in thecategory list are grayed out and you cannot add any additional events to the Events to Collectlist.

Note

These available events that appear in this list are based on the PMU counters of the core.

Events to CollectThis list of categories and events is what the Timeline view uses for its line graphs. Each eventlisted here is available for display in the Timeline view using the Chart Configuration view.

Related tasks4.2 Opening the Counter Configuration dialog box on page 4-54.4.3 Adding new events to the Events to Collect list on page 4-55.4.4 Removing events from the Events to Collect list on page 4-57.4.8 Setting up events-based sampling on page 4-61.

Related references4.5 Counter Configuration toolbar options on page 4-58.

4 Counter Configuration4.1 Counter Configuration dialog box structure


4.2 Opening the Counter Configuration dialog boxARM Streamline uses a default best-fit set of hardware performance counters to aid in the analysis ofyour applications, but you can modify them using the Counter Configuration dialog box, accessedthrough the Streamline Data view.

To open the Counter Configuration dialog box:

Procedure

1. Make sure that you have the Streamline Data view open.

Note

To open the Streamline Data view, select Window > Show View > Other.., and choose it from theDS-5 folder.

2. Enter an IP address for a valid target in the target field of the Streamline Data view or choose a targetusing the Connection Browser button.

3. Click Counter Configuration, in the Streamline Data view.

Figure 4-2 The Streamline data view - Counter Configuration

To open the Counter Configuration dialog box, you must be able to connect to the target with thegator daemon running so that Streamline can determine which counters are available for your specifichardware. Clicking Counter Configuration without properly specifying a target produces an errormessage.

Related concepts4.7 Events-based sampling on page 4-60.


4 Counter Configuration4.2 Opening the Counter Configuration dialog box


4.3 Adding new events to the Events to Collect listStreamline uses the list of counters in the Events to Collect list to determine what data to collect duringa capture session. If an event you want does not appear on the list, you can add it using the CounterConfiguration dialog box.

To add events to the list:

Procedure

1. Open the Counter Configuration dialog box using the button in the Streamline Data view.2. Select and drag events from the Available Events list and drop them in the Events to Collect area.

Figure 4-3 Adding a counter to the Events to Collect list

The added events appears in the Events to Collect list under its category name.

Note

Streamline creates charts for all counters in the Events to Collect list unless a counter is used by aSticky Snippet. In this case, Streamline generates a chart from the Sticky Snippet.

4 Counter Configuration4.3 Adding new events to the Events to Collect list


3. In cases where a counter can be collected on one of a number of different cores or interfaces, a drop-down menu appears next to the counter in the Events to Collect list. Use this menu to select aspecific core or interface.The ARM Versatile Express TC2 hardware, featuring CCI-400 coherent interconnect, enables you tocollect counters over a number of different interfaces. The interface drop-down menu in the Eventsto Collect list is specific to this hardware.

Figure 4-4 The Interface drop-down menu

Related concepts4.7 Events-based sampling on page 4-60.6.22 Snippet menu on page 6-111.


4 Counter Configuration4.3 Adding new events to the Events to Collect list


4.4 Removing events from the Events to Collect listYou are limited in the number of hardware-specific events that you can collect during a capture session.Removing unwanted counters from the Events to Collect list frees up room to add the counters that youdo want.

To remove events from the Events to Collect list:

Procedure

1. Click the button in the Streamline Data view to open the Counter Configuration dialog box.2. Select any number of events or event categories from the Events to Collect list.3. Press Delete to remove that category and all of the events it contains from the Events to Collect list.



4 Counter Configuration4.4 Removing events from the Events to Collect list


4.5 Counter Configuration toolbar optionsThe toolbar of the Counter Configuration dialog box provides options that provide help resources andenable you to manage your configuration settings.

The Counter Configuration dialog box contains the following buttons:

HelpOpens Counter Configuration help in the dialog box.

Load DefaultsReturns the Events to Collect list to the Streamline defaults.

Import...Opens a dialog that enables you to search for an XML file that you previously generated.

Export...Exports the current counters configuration to an XML file. You can create the xml file andmanually add as an option when running gatord on the target, if you choose to capture datalocally.

SaveSaves your current counter configurations and exits the dialog box. The counter configurationfile is saved to your target.

CancelExits the Counters Configuration dialog box without saving the defined settings.

DeleteRemoves the selected counter from the Events to Collect list.

Toggle Events-Based SamplingThis button turns Events-based sampling on for the selected counter. Use the Threshold field todefine how many hits for the counter before a sample is recorded.



4 Counter Configuration4.5 Counter Configuration toolbar options


4.6 Events specific to ARM® Mali™ technologyIf you build the gator driver with support for Mali technology and connect to either a Mali-4xx or Mali-T6xx based target, there are many additional events in the Available Events list that are specific to Mali-based targets.

For information about the meaning of each of the Mali-specific counters and how to interpret theprofiling data, see the Mali GPU Application Optimization Guide, available on the Mali developer site,http://www.malideveloper.com.

When choosing which Mali events to add to the Events to Collect list, consider the following:

• The Mali-4xx GPUs contains two counters per block, each of which can count one of many events.You can add either or both to the Events to Collect list. You can add any number of the manyavailable Mali-T6xx counters as the Mali-T6xx hardware reports its hardware events through a blockof shared memory rather than through dedicated hardware registers.

• Vertex and fragment processor counters are delivered as a single total at the end of each phase ofactivity.

• L2 counters report continuously because the cache is shared by the vertex and fragment processorsand cannot easily be attributed to a single operation.

• Some Mali counters support multiple interfaces. Choose an interface for each counter using the dropdown menu next to the counter in the Events to Collect list.

Related tasks4.3 Adding new events to the Events to Collect list on page 4-55.4.2 Opening the Counter Configuration dialog box on page 4-54.

4 Counter Configuration4.6 Events specific to ARM® Mali™ technology



4.7 Events-based samplingBy default, Streamline records samples at an interval determined by the Sample Rate drop-down menu inthe Capture & Analysis Options dialog box. You can override this behavior and set Streamline to doevents-based sampling, enabling you to customize which inefficiencies you want to highlight with thesampling data.

With events-based sampling, Streamline samples only when the selected event is triggered a number oftimes equal to the value in the Threshold field of the Counter Configuration dialog box, and does so foreach core on your target. For example, to trigger a sample every time a core causes 500 L2 cache misses,select L2 miss from the Events to Collect list and enter 500 in the Threshold field. Given an adequatecapture session, the Samples statistic contained in many of the Streamline reports indicates whichprocesses and functions are the potential cause of inefficient caching.

Note

Events-based sampling is only possible when the PMU on the target hardware can generate interrupts.



4 Counter Configuration4.7 Events-based sampling


4.8 Setting up events-based samplingIn Streamline, you can override the default interval sampling with events-based sampling using theCounter Configuration dialog box.

To enable events-based sampling, follow these steps:

Procedure

1. Open the Counter Configuration dialog box using the button in the Streamline data view.2. Select an event from the Events to Collect list.3. Click the Toggle events-based sampling button on the right side of the dialog box.

If the Toggle events-based sampling button is not selectable after you have selected an event, thenthat event does not support events-based sampling.

4. Enter a value in the newly activated Threshold field.Avoid setting a very low threshold for high frequency events. If you enter a threshold value thatgenerates too many samples, Streamline could fail, and you might have to restart your target. To findan appropriate value to enter in the Threshold field, turn off events-based sampling to run a standard,time-based profile with the event counter that you want to use enabled. Look at the resulting Timelineview and note the peak per-second value in the chart for your counter. Your target for the Thresholdfield is 1000 samples per second, so if the peak for that event is 2000000, a good value to insert in theThreshold field is 2000.

4 Counter Configuration4.8 Setting up events-based sampling


Figure 4-5 Setting up events-based sampling



4 Counter Configuration4.8 Setting up events-based sampling


Chapter 5The Live View

The Live view provides capture data in real-time, updating charts as long as the capture session is active.It contains the following sections:

• 5.1 Live view overview on page 5-64.• 5.2 Live view toolbar options on page 5-66.


5.1 Live view overviewWhen you trigger a capture session in Eclipse for DS-5, the Live view opens automatically. It chartscapture data and provides a list of processes alongside usage data.

Figure 5-1 The Live view

You can use the chart handles to reorder the charts in Live view, and you can use the bottom of thehandle to re-size the height of a chart. Disclosure controls enable you to view data on a per-core or per-cluster basis for charts that support this.

Note

To have active charts in the Live view, you must set Buffer Mode to Streaming in the Capture &Analysis Options dialog box. If Streaming is not active during a capture session, Live view stillappears, but without any data populating the charts.

Below the charts is a report that lists all of the processes and provides an id and usage statistics for eachof them. This list updates continuously as long as the capture session is running.

The Live view is intended to give feedback during a capture session. The additional functionality anddata provided by the various views of Streamline are only available once you have stopped your capturesession and Streamline has processed the data in the capture.

5 The Live View5.1 Live view overview


The toolbar of the Live view contains an activity monitor that shows you whether or not there is anylatency in the data passing from the target. If there is no latency and Streamline is plotting live data in thecharts of the Live view, the activity cursor that moves left and right is blue. If there is latency, theactivity monitor is red. In the case of latency, the Live view halts scrolling until the data can catch up.

If you selected the Discard Data option in the Capture & Analysis Options dialog box, an x appears inthe toolbar display, letting you know Streamline is to discard data upon termination of the capturesession.

5 The Live View5.1 Live view overview


5.2 Live view toolbar optionsThe Live view provides options that enable you to stop the current capture session and navigate throughthe Live view history.

The Live view contains the following toolbar options:

Stop data captureStops the capture session. The resulting report data replaces the Live view in the editor sectionof Eclipse for DS-5. It has the same effect as clicking the Stop data capture button in theStreamline Data view. To the right of the Stop data capture button there is a drop down menuthat contains two options:

Stop capture and analyzeThis option has the same effect as clicking the Stop data capture button. It stops thecapture and keeps data based on the settings in the Capture & Analysis Optionsdialog box.

Stop capture and discardChoose this option to terminate the current capture session and discard all data. If youchoose this option, Streamline does not create an APC report.

Go to beginningMoves the scrollbar to the beginning of the charts in the Live view and holds focus there.

Halt scrollingCauses the Live view to stop scrolling so that you can focus on the chart data currently in view.The charts of the Live view continue to expand as the capture session continues, but the Liveview only moves if you move the horizontal scrollbar.

Go to live positionClicking Go to live position returns the Live view to the default scrolling behavior. The viewmoves with the growing charts and the live streaming data remains in focus.

5 The Live View5.2 Live view toolbar options


Chapter 6The Timeline View

The Timeline view charts data over the course of the execution and provides a details panel with furtherinformation. The contents of the details panel is dependent on the currently selected mode.It contains the following sections:

• 6.1 Timeline view overview on page 6-69.• 6.2 The Cross Section Marker on page 6-71.• 6.3 Timeline view charts on page 6-73.• 6.4 Timeline view details panel overview on page 6-77.• 6.5 Heat Map mode on page 6-79.• 6.6 Core Map and Cluster Map modes on page 6-81.• 6.7 Processes mode on page 6-83.• 6.8 Exceptions mode on page 6-84.• 6.9 OpenCL mode on page 6-85.• 6.10 Timeline view toolbar on page 6-89.• 6.11 Timeline view contextual menu options on page 6-91.• 6.12 Timeline view keyboard shortcuts on page 6-92.• 6.13 The Timeline view Samples HUD on page 6-94.• 6.14 Filtering using the caliper controls on page 6-95.• 6.15 Adding bookmarks to the Timeline view on page 6-97.• 6.16 Timeline view charts specific to ARM® Mali™-based targets on page 6-98.• 6.17 The Warnings tag on page 6-100.• 6.18 Changing the quality of graphics in the Timeline view on page 6-101.• 6.19 Timeline view chart configuration on page 6-102.• 6.20 Chart configuration toolbar options on page 6-103.


• 6.21 Chart configuration series options on page 6-107.• 6.22 Snippet menu on page 6-111.• 6.23 Adding an existing chart using the Snippets menu on page 6-113.• 6.24 Adding a new chart to the Timeline view using the Snippets menu on page 6-114.• 6.25 Snippet menu contextual menu options on page 6-115.• 6.26 Snippet menu buttons on page 6-116.• 6.27 Visual Annotation in the Timeline view on page 6-117.

6 The Timeline View


6.1 Timeline view overviewThe Timeline view is the first view that you see when Streamline opens a report. It provides you withhigh level information about the performance of your target during a capture session.

After you have successfully generated a report, Streamline opens it automatically and displays theTimeline view.

Figure 6-1 The Timeline view

The Timeline view has two main sections: The charts that appear in the upper half and the details panelthat appears in the lower. The information in the details panel is dependent on the current selection in themode menu, located in the lower left of the Timeline view.

The Timeline view breaks up its data into bins, a unit of time defined by the unit drop down menu at thetop of the view. For example, if the unit is set to 100ms, every color-coded bin in the processes sectionrepresents trace data captured during a 100ms window.

Related concepts6.3 Timeline view charts on page 6-73.6.4 Timeline view details panel overview on page 6-77.6.19 Timeline view chart configuration on page 6-102.6.27 Visual Annotation in the Timeline view on page 6-117.

Related tasks6.14 Filtering using the caliper controls on page 6-95.6.15 Adding bookmarks to the Timeline view on page 6-97.

6 The Timeline View6.1 Timeline view overview


Related references6.10 Timeline view toolbar on page 6-89.6.11 Timeline view contextual menu options on page 6-91.6.12 Timeline view keyboard shortcuts on page 6-92.

6 The Timeline View6.1 Timeline view overview


6.2 The Cross Section MarkerThe Cross Section Marker is a versatile tool for looking at specific ranges of data in the Timeline view. Itstarts one bin wide but can be re-sized using the handles on both sides or moved left and right using themiddle of the marker. An overlay shows you data pertinent to the current range of the Cross SectionMarker.

By default, the Cross Section Marker is inactive. To activate or move the Cross Section Marker, clickanywhere in charts or anywhere in the map modes of the details panel. The Cross Section Markerappears where you clicked and provides data specific to the bin where you placed it.

You can also stretch the Cross Section Marker using the handle that is located above the charts in theTimeline view. Click and drag on either that right or the left side of the handle to expand it. Onceexpanded, you can move the Cross Section Marker left and right by clicking and dragging it. Theinformation contained in the samples HUD relates only to the window of time defined by the currentCross Section Marker.

Note

Unlike the filter controls, moving and expanding the Cross Section Marker does not have an effect on thedata in the other report views. It does affect the data in the details panel if Processes mode is currentlyactive.

In cases where you set a Cross Section Marker border, then change to a higher level of magnificationwhere the Cross Section Marker border would not sit precisely, the border is displayed as a blurred line.This thicker, fuzzy border line indicates that the offset of the Cross Section Marker is not perfectlyaligned with the bin at the current magnification level, but is fractionally within it. For example, if youzoom in the 100ms level and set an edge of the Cross Section Marker to 26.6 seconds, then zoom backout to the 1s level, the edge of the Cross Section Marker appears as a blurred line.

6 The Timeline View6.2 The Cross Section Marker


Figure 6-2 A Cross Section Marker fuzzy line

Related concepts6.13 The Timeline view Samples HUD on page 6-94.

Related references6.11 Timeline view contextual menu options on page 6-91.6.12 Timeline view keyboard shortcuts on page 6-92.

6 The Timeline View6.2 The Cross Section Marker


6.3 Timeline view chartsThe top half of the Timeline view contains a series of charts. The type of charts it displays is dependenton the counters you have defined using the Counter Configuration dialog box and any customizationsyou have made to the charts using the chart configuration controls.

Streamline collects data for the charts from hardware and software performance counter resources. Thedata is dependent on how you have configured your counters and the type of system you use. For SMPsystems, the chart disclosure control enables you to expand the data to show collection either per core orper big.LITTLE™ cluster.

Here are some of the default charts in the Timeline view:

CPU ActivityThe percentage of the CPU time spent in system or user code, the remainder being idle time.The CPU activity chart is not user configurable.

CPU Wait - ContentionMeasures the amount of times the core was forced to wait due to contention as a percentage.This is a binary indicator. When the task is waiting, this value is 100%, otherwise it is 0%.

CPU Wait - I/OMeasures how often waiting on I/O caused a task to stop running.

ClockThe number of cycles used by each core.

CoreThe total number of instructions executed by each core.

FrequencyThe frequency of the ARM core. Can be broken down per core on a multi-core system.

CacheThe number of cache coherency hits and misses. A cache coherency miss occurs every time aprocessor tries to read from or write to the cache when it is in incoherent state. This is morecommon in SMP systems where multiple processors share resources. A coherency hit occurswhen a processor reads from or writes to a cache that is in a valid state.

InterruptsMaps the amount of both soft IRQs and standard, hardware IRQs. Soft IRQs are similar toIRQs, but are handled in software. Soft IRQs are usually delivered at a time that is relativelyconvenient for the kernel code.

Disk IOMeasures the number of times reads and writes to disk were triggered.

MemoryCharts the available system memory over the time of the execution.

If you are using a target with more than one core, some graphs in the Timeline view have a disclosurecontrol. Use this to break each graph into multiple sections, one for each core in your system.

Unlike the other charts in the Timeline view, the current selection in the Heat Map of the details panelaffects how the CPU Activity, CPU Wait, GPU Vertex, GPU Fragments, and Memory charts aredisplayed. When there is an active selection in the Heat Map, the green bars change to reflect CPUactivity caused by the selected processes. Streamline still displays the total activity in dark gray so thatyou can visually compare the selected processes CPU Activity values to the total.

6 The Timeline View6.3 Timeline view charts


Figure 6-3 A bar chart with an active selection in the processes section

Like the CPU Activity chart, the GPU Vertex and Fragment bar charts display only activity initiated bythe selected processes. This allows you to differentiate between GPU activity caused by your applicationand activity resulting from other applications or system services.

Process Focus Buttons

Some of the charts in the Timeline view also have a button on the left side of the chart handle thatenables you to select that chart as the current focus of the Heat Map in the details panel. By default, thisis set to the CPU activity chart.

Figure 6-4 The Processes Focus button

If you click a Processes Focus button on one of the bar charts, the Heat Map in the details panel updatesto show a heat map of processes that contributed to activity in the newly selected bar chart. For example,if you click the Processes Focus button on the GPU Vertex chart, the Heat Map updates to show activityfor the GPU vertex processor only. The GPU charts are only available if you have captured data on anARM Mali-based target and built the gator module to support Mali technology.

Quick access tooltips

Hover over any of the charts in the Timeline view and a tooltip appears, displaying values and key colorsspecific to that chart.

Figure 6-5 The Quick Access tooltip

Clicking on a chart moves the Cross Section Marker, which shows values and key colors for each of thecharts of the Timeline view.



Moving and re-sizing charts

Each chart and process has a rounded box on the left that contains the title, and in the case of charts, acolor-coded key. You can also use these rounded bars, called handles, to drag and drop individual chartsand processes into a preferred order.

Figure 6-6 Moving a chart using the handle control

To re-order a chart or process, click and drag the handle control, then release it where you want it placed.To hide a chart, drag it to the bottom of the charts and drag the divider bar up until it is hidden.

You can also re-size any chart in the Timeline view using a control on the bottom edge of the charthandle control.

Figure 6-7 Re-sizing a chart

All series expand to fill the new height. Increasing the size of a chart provides a higher level of graphicaldetail, highlighting the variance in values.

You can also customize the width of the chart handle. To do so, click and drag the right edge of anyhandle to your desired width.

The chart disclosure control

The chart disclosure control appears in the upper left corner of a chart where per core data is present. Ifyou click on the disclosure control and there are no core clusters on your target, the disclosure arrowpoints straight down and the chart expands to show a separate chart for every core on your target.

If you do have clusters on your target hardware, the disclosure control behaves differently. Click onceand the arrow moves down forty-five degrees and the Timeline view shows charts for each cluster onyour system.



Figure 6-8 Using the chart disclosure control to show per cluster data

Click the button a second time and the arrow moves straight down and the Timeline view shows a chartfor every core in your system. Click a third time and the chart returns to its default state.

Chart type overlay

The letter displayed in the chart handle tells you whether the Y-axis data in the chart is displayed asLogarithmic, Overlay, or Stack. Hover over the letter for a tooltip that describes how the data indisplayed.

Related concepts6.1 Timeline view overview on page 6-69.6.4 Timeline view details panel overview on page 6-77.6.19 Timeline view chart configuration on page 6-102.6.27 Visual Annotation in the Timeline view on page 6-117.

Related tasks6.14 Filtering using the caliper controls on page 6-95.6.15 Adding bookmarks to the Timeline view on page 6-97.12.8 Applying manual offsets to align energy data on page 12-173.




6.4 Timeline view details panel overviewThe details panel of the Timeline view enables you to switch between different modes using the modemenu in its bottom left. Each mode provides a different set of data to supplement the charts.

The details panel has the following modes:

Heat Map modeThe Heat Map shows you a list of processes that were active during the capture session in eachtime bin alongside a color-coded heat map. Colors range from white to red, and the darker thecolor, the more activity caused by the process in that bin.

Core Map modeThe Core Map mode is similar to Heat Map mode. It shows a list of processes, but instead of acolor-coded heat map, it provides you a colored activity map based on which core wasresponsible for the majority of the activity for each process. This mode is not available forsingle core hardware targets.

Cluster Map modeIdentical to Core Map mode, except that Cluster Map mode provides a color-coded activitymap based on cluster. This mode is only available for targets that have multiple core clusters.

Processes modeProcesses mode provides a list of all processes alongside a process number, the percentage ofCPU used and the amount of memory used. Unlike the other modes, the data here is dependenton the current selection of the cross-section marker.

Exception modeThis mode, only available if you are using a target that has a Cortex-M class core, displays eachof the types of exceptions that occurred during execution along with counts and Time In andTime Out numbers.

OpenCL modeThis mode displays the OpenCL commands being executed on each thread over the course of acapture session and shows dependencies between commands. It is only available for MaliT6/7xx targets.

Summary Table modeThis mode is only available if summary information exists. It displays the information in tabularform, with optional links to the Code view. If multiple summary tables exist, you can switchbetween them using the table names menu displayed at the bottom of the Timeline view.

Each mode except the Summary Table mode has a filtering field, which appears at the bottom of theTimeline view. Enter a regular expression in the field to filter the processes in the details panel. Forexample, if you enter a standard string consisting only of letters, the maps in the details panel update toinclude only [idle], [kernel], and any processes that contain the entered string. Regular expression stringsare not case sensitive. The charts in the Timeline view update to display only activity from the remainingprocesses.

Entries in the filtering field in the Heat, Core, or Cluster Map affect the other map modes, but not theOpenCL, Processes or Exception modes. Filtering data entered in Processes or Exception modes affectthe data in both of these mode types, but does not affect the data in any of the map modes.

Related concepts6.1 Timeline view overview on page 6-69.6.3 Timeline view charts on page 6-73.6.19 Timeline view chart configuration on page 6-102.6.27 Visual Annotation in the Timeline view on page 6-117.


6 The Timeline View6.4 Timeline view details panel overview



6 The Timeline View6.4 Timeline view details panel overview


6.5 Heat Map modeThe Heat Map shows you a list of processes that were active during the capture session. The entries arederived from process and thread trace data from the Linux kernel scheduler. Weighted colors reflect thenumber of samples in each process or thread.

Open Heat Map mode using the mode menu in the bottom left of the Timeline view.

Figure 6-9 Process bars in Heat Map mode

Here is what each of the colored bins in the Heat Map represent:

WhiteThe process is not running.

GrayThe process has started, but is dormant. It could be sleeping, waiting on user input, or waitingfor some other process to finish.

Yellow to RedThe process is responsible for some percentage of total instructions during this bin. Redindicates a higher percentage.

Note

The [idle] process is color-coded differently to the other processes in the Timeline view. When thesystem is fully idle, it is bright blue. When it is partially idle it is a lighter shade of blue, and when thesystem is fully active, it appears white.

6 The Timeline View6.5 Heat Map mode


Blue DashesCPU contention caused a delay. This can happen if there are too many processes and not enoughcores to handle them.

Figure 6-10 CPU contention dashes in the Timeline view

Red DashesAn I/O operation caused a delay. The process stopped while a read or a write to disk occurred.

If you select any number of processes or threads, all the charts in the Timeline view update to reflectonly activity caused by the selected processes and threads. All charts that do not contain the necessaryprocess information are blanked out.

Each of the multi-threaded or annotated processes in the list have a disclosure control. Use the control toshow each of the threads and annotations for that process. Annotations shown here can be hierarchical,with annotation groups each containing a set of channels, as defined by the macros inserted in your code.

Note

Selecting a process or thread in the Heat Map affects the CPU Activity, CPU Wait, GPU Vertex, andGPU Fragments charts. All of these charts update to reflect usage based on the current selection in theHeat Map.

If you activate the disclosure control to show threads and annotations for that process, a filter buttonappears to the right of the process title. Use this to filter threads within that process.

Figure 6-11 Filter button

6 The Timeline View6.5 Heat Map mode


6.6 Core Map and Cluster Map modesThe Core Map and Cluster Map modes change the details panel of the Timeline view to a mode thathighlights core or cluster affinity. In these modes, the bars show the mapping of software threads toprocessor cores or clusters to show you on which cores your bottleneck functions are running.

Figure 6-12 Core Map mode with two cores

The colors in Core Map mode are:

BlueFirst core.

TurquoiseSecond core.

PurpleThird core.

AmberFourth core.

WhiteFifth core.

The colors in the Cluster Map mode are:

RedFirst cluster.

YellowSecond cluster.

GreenThird cluster.

BlueFourth cluster.

Hovering the mouse cursor over a color-coded bin shows you which core or cluster the color identifies.There is a key in the bottom of the details panel that shows you each of the colors and which core orcluster that color represents.

6 The Timeline View6.6 Core Map and Cluster Map modes


Note

Core Map mode is supported for captures using SMP systems and Cluster Map mode is only supportedby hardware targets where there is more than one cluster of cores. These modes do not appear in themode menu in captures where they are not supported.

6 The Timeline View6.6 Core Map and Cluster Map modes


6.7 Processes modeProcesses mode provides a set of data similar to what you would get if you entered the top command inyour Linux shell. For every time bin in the Timeline view, it provides you a list of processes along withusage information.

The details panel has the following columns when it is in Processes mode:

IDThe unique identifier assigned to the thread.

NameThe name of the process or thread.

% CPUThe percentage of the CPU activity this process used for the time bins currently selected bycross-section marker.

MemoryThe amount of memory used by the process. Like the % CPU column, this value is dependenton the current position of the cross-section marker.

Note

The memory column only appears if the capture used memory counters.

You can sort by any of the columns in Processes mode. Click once for a descending sort and twice for anascending sort.

6 The Timeline View6.7 Processes mode


6.8 Exceptions modeWhile in Exceptions mode, the details panel lists all of the exception types that occurred during thecapture session, in addition to counts and the minimum and maximum time in and out. Exceptions modeis only available for Cortex-M targets connected using DSTREAM.

Exceptions mode has the following columns:

IRQThe IRQ line used by the interrupt type.

NameThe name of the interrupt type.

CountThe number of times an interrupt of this type occurred during the whole capture session.

Total TimeThe total amount of time spent in this exception across the whole capture session.

Min. Time InThe shortest amount of time in during a single instance of this exception.

Max. Time InThe longest amount of time in during a single instance of this exception.

Min. Time OutThe shortest amount of time outside this exception.

Max. Time OutThe longest amount of time outside this exception.

Like Processes mode, you can sort by any of the columns in Exceptions mode. Click once for adescending sort and twice for an ascending sort.

6 The Timeline View6.8 Exceptions mode


6.9 OpenCL modeOpenCL mode provides a visual representation of OpenCL code. It shows which command is being runon each thread over the course of the capture session and provides mechanisms to explore commanddependencies.

Note

Streamline can display an OpenCL timeline showing kernel dependencies and execution usinginformation from Mali T6/7xx devices. This is an early access feature available to Mali licensees only.Contact your support team for more information.

The Open Computing Language, or OpenCL is a framework for parallel execution of jobs or kernelsusing task-based and data-based parallelism. To help you visualize the behavior of OpenCL code,Streamline provides the OpenCL mode in the Timeline view.

Figure 6-13 OpenCL mode in the Timeline view

In OpenCL, commands are added to queues, then executed in parallel on one of the available hardwaredevices, usually a CPU, GPGPU, or DSP. Commands in a queue execute in series, but commands canalso be dependent on the completion of commands in other queues.

Command names are shown inside colored areas, representing the duration of their execution. If there aretwo or more commands in a bin, and there is enough room, the number of commands in the bin is shownin light gray. Dependencies between commands are shown using connecting lines. These have circles ateach end to indicate the direction of the dependency. A command shown with a closed circle isdependent on a command shown with an open circle.

Gaps might appear between the execution of commands in a queue. In the following figure, a gap occursalthough six commands are queued. To find out why commands are not executing, Streamline allowsyou to click on a command to give it focus, hide any non-relevant information, and show its dependencyconnections.

6 The Timeline View6.9 OpenCL mode


Figure 6-14 A gap between commands in OpenCL mode

The following figure shows the selected command highlighted with a yellow border and connecting lineslinking it to the commands it depends on. This shows that the reason for the gap is the selected commandis waiting for the completion of a command in a different queue, on a different device.

Figure 6-15 A selected command in OpenCL mode

All of the data in OpenCL mode is presented as a tabbed hierarchy. Click on any of the tabs on the left ofthe OpenCL mode to select that tab and each of its subordinates. For example, if you click on a specificdevice, Streamline highlights each queue for that device and the Execution, Sync., and Memory rowsfor each of those queues.

Zooming out or scrolling reveals the point at which the selected command was enqueued. Yellow linesshow where selected commands enter and exit a queue.



Figure 6-16 Zooming out in OpenCL mode

Hovering over a command in OpenCL mode displays a tooltip that shows the command name, the timethat it was initiated, the time it took the command to start after it was initiated, and its duration.

Figure 6-17 OpenCL mode tooltip

At the bottom of the chart in OpenCL mode is a search and filter field. Enter a string in the field andOpenCL mode updates to show only the commands that contain that string.

When the Show all dependencies option is selected, dependencies are displayed for all commands,whether or not they are selected.



Figure 6-18 Filtering in OpenCL mode



6.10 Timeline view toolbarARM Streamline provides easy ways to navigate and modify the Timeline view using the toolbar.

The toolbar controls in the Timeline view are:

TagsOne or more tags appear on the left hand side of the toolbar if a special condition applies to thereport. A tag appears if one of the following conditions applies:

• Events-based sampling was used during the capture session.

Figure 6-19 Events-based sampling tag on the Timeline toolbar• The user-space version of gatord was used during the capture session.• One or more warnings apply to the report.

Figure 6-20 Warnings tag• You are currently using DS-5 Community Edition.

Figure 6-21 Community Edition tag

When you hover over a tag, a tooltip appears, giving you more detailed information about whatthe tag signifies.

HelpBrings up contextual help in Eclipse.

Toggle bookmark markersActivates or deactivates the bookmark markers in the Timeline view. If selected, Streamlineplaces vertical lines that stretch across the charts under each of your bookmarks.

Toggle HUD DisplayToggles the Samples HUD on and off.

Reset filteringResets the calipers. The calipers are the blue arrow controls at the top of the Timeline view thatyou can use to filter the statistics in the reports to an area of interest.

Select Annotation log...Opens the Log view and selects the closest Annotation-generated message to the currentposition of the Cross Section Marker. This option is not applicable if you did not includeANNOTATION statements in your code.

6 The Timeline View6.10 Timeline view toolbar


Zoom levelEnables you to cycle through the levels of zoom. Use the plus and minus buttons to increase ordecrease the units of time used to represent one bin in the Timeline view.

Figure 6-22 The zoom level drop-down menu

Time index markerShows the time index of the current location of the mouse cursor. The time index markercontains a drop down menu that enables you to specify the level of zoom for the Timeline view.

Export Timeline view to a text fileOpens the Export dialog box, enabling you to export the data from the Timeline view. Valuescan be separated by spaces, commas, or tab delimiters, making it easy to save data as a separatefile or to open it in your favorite spreadsheet application.

Related concepts6.1 Timeline view overview on page 6-69.6.3 Timeline view charts on page 6-73.6.4 Timeline view details panel overview on page 6-77.6.19 Timeline view chart configuration on page 6-102.6.27 Visual Annotation in the Timeline view on page 6-117.



6 The Timeline View6.10 Timeline view toolbar


6.11 Timeline view contextual menu optionsRight-click anywhere in the charts or the map modes of the details panel of the Timeline view to open acontextual help menu that enables you to change the current position of the caliper filtering controls.

The basic contextual menu options are:

Set left caliperSets the left caliper control to the current location. Streamline filters all data before the leftcaliper from all views.

Set right caliperSets the right caliper control to the current location. Streamline filters all data after the rightcaliper location from all views.

Reset calipersResets calipers to their default locations. The left caliper returns to the start of the capturesession and the right caliper to the end.

Set Cross Section Marker start indexSets the left-hand boundary of the Cross Section Marker. This extends the Cross SectionMarker if it already is in the Timeline view. If it is currently parked, the Cross SectionMarker is moved to the current location. The selected location must be to the left of the currentlocation of the Cross Section Marker.

Set Cross Section Marker end indexSets the right-hand boundary of the Cross Section Marker.

Park the Cross Section MarkerResets the Cross Section Marker to its default location. To bring the Cross Section Markerback after parking it, click anywhere in the charts or map modes or drag the Cross SectionMarker from its parked position in the far left of the divider.

If you right-click on a bookmark to open a contextual menu, there are two additional options:

Rename bookmarkOpens the small interface that enables you to change the title and color of your bookmark.

Delete bookmarkRemoves the bookmark from the Timeline view.

Related concepts6.1 Timeline view overview on page 6-69.6.3 Timeline view charts on page 6-73.6.4 Timeline view details panel overview on page 6-77.6.19 Timeline view chart configuration on page 6-102.6.27 Visual Annotation in the Timeline view on page 6-117.6.2 The Cross Section Marker on page 6-71.6.13 The Timeline view Samples HUD on page 6-94.


Related references6.10 Timeline view toolbar on page 6-89.6.12 Timeline view keyboard shortcuts on page 6-92.

6 The Timeline View6.11 Timeline view contextual menu options


6.12 Timeline view keyboard shortcutsWhile you can navigate every report in Streamline using the mouse, keyboard shortcuts are often a fasterway to accomplish common tasks.

The keyboard shortcuts available for the Timeline view are:

Left arrowMoves the Cross Section Marker one bin to the left.

Right arrowMoves the Cross Section Marker one bin to the right.

Shift + left arrowContracts the width of the Cross Section Marker if it is wider than one bin.

Shift + right arrowExpands the width of the Cross Section Marker.

BToggles the vertical markers for bookmarks on and off.

CSwitches the details panel to Core Map mode.

HSwitches the details panel to Heat Map mode.

ESwitches the details panel to Exceptions mode, if that mode is available for the current report.

LOpens the Log tab and highlights the annotation indicated by the Cross Section Marker.

OSwitches the details panel to OpenCL mode.

PSwitches the details panel to Processes mode.

SReveals or hides the Samples HUD.

TSwitches the details panel to Summary Table mode, if that mode is available for the currentreport.

USwitches the details panel to Cluster Map mode, if that mode is available for the current report.

+Zooms the Timeline view in one level.

-Zooms the Timeline view out one level.

Ctrl+ZTriggers the undo command. It steps back one change to the filtering in the Timeline View.

Ctrl+YTriggers the redo command. It steps forward one change to the filtering in the Timeline view, ifyou have previously used undo.

Related concepts6.1 Timeline view overview on page 6-69.6.3 Timeline view charts on page 6-73.6.4 Timeline view details panel overview on page 6-77.6.19 Timeline view chart configuration on page 6-102.6.27 Visual Annotation in the Timeline view on page 6-117.6.2 The Cross Section Marker on page 6-71.6.13 The Timeline view Samples HUD on page 6-94.

6 The Timeline View6.12 Timeline view keyboard shortcuts



Related references6.10 Timeline view toolbar on page 6-89.6.11 Timeline view contextual menu options on page 6-91.

6 The Timeline View6.12 Timeline view keyboard shortcuts


6.13 The Timeline view Samples HUDThe Samples HUD shows the functions with the most samples in the currently selected cross-section.

Selecting a bar jumps you into the relevant context in the Call Paths view. Use the Analyze button onthe capture to load more applications and decrease the number of bracketed entries in this list.

Figure 6-23 Timeline view Samples HUD

The Samples HUD can be turned on and off using the Samples HUD button in the toolbar.

Related concepts6.2 The Cross Section Marker on page 6-71.


6 The Timeline View6.13 The Timeline view Samples HUD


6.14 Filtering using the caliper controlsThe Timeline view contains calipers that you can use to set the specific window of time on which youwant to focus. Streamline updates each of the report views based on where the left and right calipers areset.

To set filtering using the caliper controls, follow these steps:

Procedure

1. Set the left caliper using one of the following ways:

• Drag the left caliper control to a location. The caliper control is blue and is located in theTimeline ruler.

• Right-click anywhere in the Timeline view and select Set left caliper from the contextual menu.2. Repeat the process for the right caliper.

The caliper controls narrow the focus of the report. Only data relevant to this interval appears in the otherviews, so the Call Paths, Functions, Code, Call Graph and Stack views update when you move thecalipers.

Figure 6-24 Using the calipers to filter

Related concepts6.1 Timeline view overview on page 6-69.6.3 Timeline view charts on page 6-73.6.4 Timeline view details panel overview on page 6-77.

6 The Timeline View6.14 Filtering using the caliper controls


6.19 Timeline view chart configuration on page 6-102.6.27 Visual Annotation in the Timeline view on page 6-117.


6 The Timeline View6.14 Filtering using the caliper controls


6.15 Adding bookmarks to the Timeline viewYou can create bookmarks in the Timeline view, enabling you to label and quickly return to criticalpoints in the Timeline view.

To create a bookmark, follow these steps:

Procedure

1. Double-click in the timeline rule.2. Give the new bookmark a name in the resulting field.

Figure 6-25 Adding a bookmark3. Optionally, to give the new bookmark a color:

a) Click on the color selector to the right of the bookmark entry field.b) Select a color from the dialog box.c) Click OK in the dialog box.

Your bookmark appears as a small mark in the Timeline overview. You can use this mark to quicklyreturn to your bookmark.

Figure 6-26 The bookmark in the timeline overview

Note

Hover over your bookmark to produce an overlay that shows you the title of the bookmark and twobuttons. Use the Edit Bookmark button to change the title or color of your bookmark and the Deletebookmark button to remove the bookmark from the Timeline.

Related concepts6.1 Timeline view overview on page 6-69.6.3 Timeline view charts on page 6-73.6.4 Timeline view details panel overview on page 6-77.6.19 Timeline view chart configuration on page 6-102.6.27 Visual Annotation in the Timeline view on page 6-117.


6 The Timeline View6.15 Adding bookmarks to the Timeline view


6.16 Timeline view charts specific to ARM® Mali™-based targetsIf you have a Mali-based target, and have followed the steps to build a version of gator compatible withit, the Timeline view provides GPU charts unique to Mali-based targets.

Figure 6-27 Charts in the Timeline view specific to Mali-based targets

If you have built gator.ko to support Mali technology and have run a capture session on either aMali-400 or Mali-450 based target, the following charts are added to the default set of Timeline viewcharts:

GPU Vertex chartStreamline reports whether the status of the Mali vertex processor is idle or active. The load onthe vertex processor is proportional to the number of vertices and the complexity of the shaderused to transform their coordinates.

6 The Timeline View6.16 Timeline view charts specific to ARM® Mali™-based targets


GPU Fragment chartStreamline reports whether the status of the Mali fragment processor is idle or active. The loadon the fragment processor is proportional to the number of pixels to be rendered and thecomplexity of the shader used to determine the final pixel color. Pixels rendered include on andoff screen pixels and the additional pixels required for super sampling.

If you have built gator.ko to support Mali technology and have run a capture session on a Mali-T6xxbased target, Streamline includes the following MaliT-6xx-specific chart types:

GPU Job Slot 0Streamline reports whether Job Slot 0 is occupied or idle. Job Slot 0 activity generallycorresponds to fragment shader work, though this is not exclusively the case.

GPU Job Slot 1Reports whether Job Slot 1 is occupied or idle. Job Slot 1 activity generally, corresponds tovertex shader work, though this is not exclusively the case.

GPU Job Slot 2Reports whether Job Slot 2 is occupied or idle. Job Slot 2 activity generally corresponds to GPUcompute work.

Note

Refer to the Mali documentation for more details on the GPU Job Slots.

6 The Timeline View6.16 Timeline view charts specific to ARM® Mali™-based targets


6.17 The Warnings tagThe Warnings tag appears in the Timeline view if there is a problem with the reports. Clicking on the tagproduces a list of applicable errors, alerting you to the type and severity of problems.

The Warnings tag only appears if there is an issue.

Figure 6-28 The Warnings tag

All of the warnings are sorted by type and each is given a color-coded warning icon that tells you theseverity of the issue:

RedThe issue is critical. For example, a connection timeout caused the termination of the capture,leaving you with incomplete data.

YellowThe issue is mid-level. For example, Streamline was unable to successfully correlate power datafrom the Energy Probe.

WhiteThe issue is minor. For example, a chart exists in the report when there is no counter data fromthe capture session to populate it.

6 The Timeline View6.17 The Warnings tag


6.18 Changing the quality of graphics in the Timeline viewIf you find the Timeline view to be slow and unresponsive, you can turn off the high quality graphics inthe preferences of DS-5.

To change the quality of the graphics in Streamline, follow these steps:

Procedure

1. Select Window > Preferences.2. Use the disclosure control to open the DS-5 group.3. Select Streamline from the list under DS-5.4. Deselect the Use highest quality graphics checkbox.

By default, the Use highest quality graphics option is active.5. Click OK.

Figure 6-29 The Timeline view with the Use highest quality graphics option disabled

6 The Timeline View6.18 Changing the quality of graphics in the Timeline view


6.19 Timeline view chart configurationYou can use the chart customization panel to change all aspects of a chart, from the color to the data setsthat the chart uses, giving you the option to display the data you want in the manner you want itpresented.

Many of the charts in the Timeline view have a button, located near the top right of the chart handle,which opens a Chart Configuration panel.

Figure 6-30 The Chart Configuration button

The Chart Configuration panel is broken down into two sections:

• A toolbar section, which contains controls that apply to the chart as a whole.• A series section, which contains one or more series controls.

For example, the Cache chart contains two series, Data access and Data refill.

Figure 6-31 The Chart Configuration panel and Cache chart

The Data access series uses data from the $CacheDataAccess counter, while Data refill uses$CacheDataRefill.

In the toolbar, the Cache chart is defined as Stacked and Fill chart, so the Timeline view draws it as twostacked fill graphs.

Related concepts6.22 Snippet menu on page 6-111.

Related tasks6.23 Adding an existing chart using the Snippets menu on page 6-113.6.24 Adding a new chart to the Timeline view using the Snippets menu on page 6-114.

Related references6.20 Chart configuration toolbar options on page 6-103.6.21 Chart configuration series options on page 6-107.6.26 Snippet menu buttons on page 6-116.6.25 Snippet menu contextual menu options on page 6-115.

6 The Timeline View6.19 Timeline view chart configuration


6.20 Chart configuration toolbar optionsThe toolbar of the Chart Configuration panel defines chart options that apply to all series in a chart.

It has the following options:

Range modifierUse the slider to limit the range of values for the chart. The upper slider defines the upper limitand the lower slider adjusts the floor. As you move these two sliders, the chart re-scales basedon the newly defined range.

Chart TypeUse the Type buttons on the left side of the toolbar to choose between one of the following charttypes:

BarIn a bar style chart, each bin in the chart is represented by a colored bar. Like the stackview, values from higher series are stacked on top of values from lower series and thetotal bar height represents the aggregate.

Figure 6-32 A bar chart example

Y-axis modifierUse the drop-down menu to select one of the following options:

StackedIn a stacked style chart, filled line charts are stacked on top of each other. The Timelineview stacks a filled line graph representing the series at the top of the chart control ontop of the series that appear beneath it. So, the highest point of the graphs in a stackedchart is an aggregate of data from all of the series contained in the chart control. Forexample, if the first value of series A is three and the first value of series B is five, thefirst data point in the stack chart that contains these series is eight.

Figure 6-33 A stacked chart example

Stacked charts are appropriate when the events are counted in exactly one of the seriesin a chart. For example, this is useful in a case where a chart contains both Data ReadHits and Data Read Misses.

6 The Timeline View6.20 Chart configuration toolbar options


OverlayAn overlay chart contains a line for each series defined in the chart control. The areabelow the line is filled with the color defined in the series control for each data set.Series higher in the chart control appear behind series that are lower in the chartcontrol. So if series A is the first series in a chart control and has a value of three andseries B appears second in the chart control and has a value of five, this value fromseries A is obstructed from view by the larger value of series B. For this reason, it isimportant to place higher value series higher in the chart control when using an overlaychart. Drag and drop series controls to reorder them.

Figure 6-34 Data from series A obstructed by data from series B

Overlay charts are appropriate when some of the events are counted in more than moreseries in the same chart. Data Read Requests and Data Read Hits are a good example ofthis.



LogarithmicShows all data points on a log10(y) scale where y is each Y-axis data point in the chart.This Y-axis modifier is useful when there is a huge difference between the minimumand maximum values in a chart. In charts with these huge deltas, it can be hard todifferentiate between the lower value data points in the chart. Setting the Y-axismodifier to Logarithmic can give you a better visual representation of your data in thesecases. A logarithmic chart displays with a series of horizontal lines in Streamline, eachline represents an increase in value by a power of ten, so that if data point A sits exactlyone line higher than data point B, A is ten times higher than B.

Note

If the actual value of a data point in a Streamline logarithmic chart is less than one, itappears in the Streamline chart like a zero value. This is because the logarithmic valueof such a data point would be a negative number.

Figure 6-35 Logarithmic scale

TitleUse this field to give the chart a title. The title appears at the top of the handle for the chart inthe Timeline view.

Average SelectionWhen you have this option checked, any selection you make using the Cross Section Markershows the average value of all bins included in the selection. If unchecked the overlay is a totalvalue of all bins.

Average CoresWhen you have this option checked, values in a multi-core chart are the average of theindividual cores when you have not used the multi-core disclosure control to show per core data.If you have not checked this chart control option, the multi-core chart shows the totals from allcores.



PercentageIn a percentage style chart, values are plotted as percentages between 0 and 100.

Save as SnippetSaves the current chart as a Snippet. After it has been saved, you can use the Snippet menu,located in the bottom left of the Timeline view to add this chart as it is currently configured.

Remove ChartRemoves the current chart from the Timeline view. If you have saved the chart as a Snippet, youcan add it back to the Timeline view later using the Snippet menu.

Related concepts6.19 Timeline view chart configuration on page 6-102.6.22 Snippet menu on page 6-111.


Related references6.21 Chart configuration series options on page 6-107.6.26 Snippet menu buttons on page 6-116.6.25 Snippet menu contextual menu options on page 6-115.



6.21 Chart configuration series optionsEach chart in the Timeline view contains one or more series or sets of data to use in its charts. Eachseries has a set of options, specific to that series that enable you to customize both the data it uses to plotthe chart and the look and feel.

Figure 6-36 Series options

You can use the handle on the left side of each series control to reorder the series in a chart, or to moveor copy the series to another chart. To move the series, drag and drop it. To copy the series, hold downthe Ctrl key while dragging it. When moving the series to a new chart, make sure chart configuration isopen for the destination chart.

Each series in a chart contains the following options:

6 The Timeline View6.21 Chart configuration series options


ColorTo change the color of a series in the Timeline view, click on the color box in its series control.This opens the Color dialog box:

Figure 6-37 The Color dialog box on Windows

Note

The type of Color dialog box that appears depends on your operating system.

Pick a new color for the series from the existing options or define a custom color. Streamlineuses this defined color for the series in the Timeline view.

NameEnter a name for the series. This name appears next to the chart color in the chart key.

TooltipEnter a description for the series in this field. When you hover over the series title or color in theTimeline view, a tooltip appears, containing the description defined here.

ExpressionUse this field to define the data set that the series uses. Press Ctrl + Space or the $ symbol toactivate a drop-menu that shows you a list of counters. You can select a counter in this ContentAssist list to see its description. Click on a counter to add it to the Expression field. You cancreate an expression using more than one counter by using a combination of counter names andany of the following operators: >, <, >=, <=, ==, !=, ||, !, &&, %, *, /, +, -. Youcan use parentheticals to define the order of operation. In addition to the mathematical andcomparative operators, you can use the following expressions in the Expression field:

ifEvaluates whether a condition is true or false before applying an effect. Usage: if(x,y, z), where x is the expression to be analyzed. The result is y if x is non-zero or z if xis zero. Only one of y or z is evaluated.

absReturns the absolute value of the numeric expression specified as the parameter. Usage:abs(x), where x is a numeric expression.

ceilReturns the smallest integer that is greater than or equal to the numeric expressiongiven as a parameter. Usage: ceil(x), where x is a numeric expression.



floorReturns the largest integer that is less than or equal to a numeric expression given as aparameter. Usage: floor(x), where x is a numeric expression.

maxCompares the arguments and returns the greater value. Usage: max(x,y), where x and yare numeric expressions.

minCompares the arguments and returns the lesser value. Usage: min(x,y), where x and yare numeric expressions.

roundReturns a numerical value rounded to an integer. Usage: round(x), where x is anumeric expression.

For standard, non-EBS captures, Streamline samples counters on every context switch and at thefrequency corresponding to the Sample Rate drop-down menu in the Capture & AnalysisOptions dialog box. For EBS captures, Streamline samples counters on context switches andwhen the specified counter reaches its threshold.

Functions drop-down menuYou can select one of the following functions to apply to all the values in the series using thedrop-down menu in the series options panel:

accumulateReturns the accumulated value of all the samples in the time bin.

minimumReturns the minimum values for the counter for each time bin in the current zoom levelin the Timeline view. So, if the current zoom level of the Timeline view is one second,minimum provides you the lowest value recorded for any millisecond within thatsecond.

Note

In most cases, minimum provides the lowest value for each millisecond within any timebin. If you have High Resolution Timeline enabled, minimum provides the lowestvalue per microsecond, if the given counter provides that level of detail.

maximumWorks the same way as minimum, except that it provides a maximum value for eachtime bin.

averageWorks the same way as minimum, except that it provides an average value for each timebin.

hertzConverts the counter to a rate. It takes the value for each time bin and divides it by theunit of time represented by the time bin, then converts it up to seconds. You can use itto convert a cycles count into cycles per second.

There are three basic types of counters in Streamline and the type of counter is important whenchoosing one of the available functions:

Absolute countersAbsolute counters like Memory: Free report the current, absolute value. Use average,maximum, and minimum with these counter types.

Delta countersDelta counters Clock: Cycles provide the change in value since the last measurement.Use accumulate and hertz with delta counters.

Activity countersActivity counters like Contention: Wait report when the CPU/GPU changes from oneactivity or state to another. Use the average function with activity counters.



Note

When used independently from source data, entering constants in the Expression field can yieldinconsistent results.

If more than one sample is received at the smallest time bin, a single value is calculated basedon the above logic for the time bin. Even in a high-resolution report, 1ms is the smallest time binfor counters. When there is more than one sample in the smallest time bin, Streamline useslinear interpolation to calculate a value for accumulate and hertz. For average, maximum, andminimum, the actual samples are used without interpolation. If no samples are received, thenaverage, maximum, and minimum are zero.

UnitEnter the unit type for the series. The value you enter in this field appears when you use theCross Section Marker to select one or more bins.

-Removes the current series from the chart.

+Adds a new series to the chart. The new series appears immediately in the Timeline when youadd valid entries in the Expression and Name fields. You can have up to eight series in a singlechart.



Related references6.20 Chart configuration toolbar options on page 6-103.6.26 Snippet menu buttons on page 6-116.6.25 Snippet menu contextual menu options on page 6-115.



6.22 Snippet menuLocated on the left hand side of the Timeline view, between the charts and the details panel, the Snippetsmenu enables you to manage your saved chart templates and create new charts. The default charts andthe charts that you have saved using the Save as Snippet button in the Chart Configuration panel are allcategorized in the menu, so that you can easily find them and add them to the Timeline view.

Figure 6-38 The Snippets menu

On the left side of the Snippet menu is the Categories section, and on the right a Sticky Snippets section.Click on any category in the Categories to see all of the charts assigned to it. Add snippets to StickySnippets list to define a set of charts that the Timeline view uses in every new Capture. Drag and dropany snippet from the left side of the Snippets menu to the Sticky Snippets side to create a new StickySnippet.

All snippets have an associated symbol:

AddThis chart is available to be added. Click on the Add button to add the chart to the Timelineview.

CheckmarkA chart in the Timeline has a configuration that precisely matches the snippet.

CautionA caution symbol appears next to the snippet if the counters necessary for the chart were notcaptured during the capture session. Hover the mouse cursor over a snippet with a cautionsymbol to display a tooltip detailing which counters in the snippet were not captured in thereport data. Try re-configuring your counters using the Counter Configuration dialog box andrun another capture session to add these charts populated with data.

Auto-generated charts appear in orange in the Snippets view. When Streamline creates the report data ina capture, it generates charts for all of the available counters assigned in the Counter Configurationdialog box. If you make changes, or remove any of these auto-generated charts, you can restore themusing the auto-generated chart in the Snippets menu.

6 The Timeline View6.22 Snippet menu


To move snippets in the Snippets menu, drag and drop them into a new location. To re-order a snippet,move it up and down in the list. To move a snippet from one category to another, drag the snippet to thecategory header and hover for a second.

Figure 6-39 Changing categories

The snippet moves one level up in the hierarchy. Move the snippet over a category and hover to openthat category. Place the snippet in any location within the category.

Related concepts6.19 Timeline view chart configuration on page 6-102.

Related tasks4.3 Adding new events to the Events to Collect list on page 4-55.6.23 Adding an existing chart using the Snippets menu on page 6-113.6.24 Adding a new chart to the Timeline view using the Snippets menu on page 6-114.


6 The Timeline View6.22 Snippet menu


6.23 Adding an existing chart using the Snippets menuThe Snippets menu contains many different chart types that you can add to the Timeline view.

To add a chart from the saved snippets, follow these steps:

Procedure

1. Click on the Snippets menu to open it.2. Click any of the available categories to open a list of snippets available in that category.3. Click the blue plus symbol to use the snippet to add a chart to the Timeline view.



6 The Timeline View6.23 Adding an existing chart using the Snippets menu


6.24 Adding a new chart to the Timeline view using the Snippets menuAlthough most charts in the Timeline view are configurable, there may be times when you need to createa chart from scratch and define your own data points. Use the Snippets menu to create a new chart in theTimeline view.

To add a new blank chart, follow these steps:

Procedure

1. Click on the Snippets menu to open it.2. Click Add Blank Chart



6 The Timeline View6.24 Adding a new chart to the Timeline view using the Snippets menu


6.25 Snippet menu contextual menu optionsLike most of the Streamline user interface, the Snippet menu provides contextual options if you right-click on any snippet or category.

The following contextual menu options are available if you right-click on a snippet:

Rename SnippetChoose this option and the snippet title changes to a field that enables you to rename the snippet.

Delete snippetRemoves the snippet from the Snippet menu.

The following options are available if you right-click on a category:

Rename CategoryThis option enables you to change the name of the selected category. The category namechanges to a field that enables you to rename the snippet category.

Delete CategoryThis option only works if the category has no subordinate snippets. If the category is empty andyou select this contextual menu option, a dialog box appears, asking you to confirm the action.Click OK to delete the category.



Related references6.20 Chart configuration toolbar options on page 6-103.6.21 Chart configuration series options on page 6-107.6.26 Snippet menu buttons on page 6-116.

6 The Timeline View6.25 Snippet menu contextual menu options


6.26 Snippet menu buttonsAlong the bottom of the Snippets menu are a series of buttons that enable you to add a blank chart, resetall snippets, export the current Snippet configuration, or import a previously generated template.

The Snippet menu contains the following items:

Add Blank ChartAdds a new unpopulated chart to the Timeline view. Use the Chart Configuration panel to adddata and customize the new chart.

Reset SnippetsResets all snippets to their factory default values. This action is not reversible.

Import a snippet configurationUse the import dialog to find a snippets.xml on your file system to import.

Export the snippet configuration to a fileCreates a snippets.xml file in the location defined in the Export dialog box. This option is usefulif you want to carry over your saved snippets to another Eclipse installation.



Related references6.20 Chart configuration toolbar options on page 6-103.6.21 Chart configuration series options on page 6-107.6.25 Snippet menu contextual menu options on page 6-115.

6 The Timeline View6.26 Snippet menu buttons


6.27 Visual Annotation in the Timeline viewIf you used the Visual Annotate feature to add images to the capture data, those images appear as a chartin the Timeline view so that you track the visuals of your application with the chart data.

Figure 6-40 Visual annotation in the Timeline view

Rows in the charts view that contain images can be re-ordered in the same way as the other charts. Butrows containing images have a few unique properties:

• Hovering your mouse over the images in a visual annotation chart shows you the image for thecurrent position of the mouse. If there is more than one image in the twenty bin range covered byeach thumbnail pictured in a visual annotation chart, Streamline uses the first image from the range.Moving the mouse over that thumbnail reveals the other annotated images in that twenty bin range.Up to five images can be shown per bin if the data is dense enough. This means that an image sectioncan contain as many as 100 images as you mouse over it.

• Hover over an image in the Timeline view and two red markers appear above and below the image.The red markers show you in which bin your code produced the current image. Move the mouse rightand left and these markers move each time you move to a new image. Press SPACE while hoveringover an image to see a full size version of that image.

Figure 6-41 Hovering over an image in the Timeline view• Blue markers above and below images mark images annotated with text. Hover over a blue marker

and the text associated with that image appears above the upper marker.

6 The Timeline View6.27 Visual Annotation in the Timeline view


Related concepts10.3 Visual Annotate overview on page 10-149.

Related references10.6 Annotate macros on page 10-153.

6 The Timeline View6.27 Visual Annotation in the Timeline view


Chapter 7The Table Views: Call Paths, Functions, and Stack

Although the information contained in the Call Paths, Functions, and Stack views differ, their basicfunctionality is similar. Each one is a table report, with rows for each function and columns for eachstatistical category.

It contains the following sections:

• 7.1 Table view toolbar options on page 7-120.• 7.2 Table view contextual menu options on page 7-121.• 7.3 Table view keyboard shortcuts on page 7-122.• 7.4 Sorting table reports on page 7-123.• 7.5 Call Paths view column headers on page 7-125.• 7.6 Functions view column headers on page 7-126.• 7.7 The Maximum Stack Depth by Thread chart on page 7-127.• 7.8 Stack view column headers on page 7-128.


7.1 Table view toolbar optionsThe toolbar in the table reports provides options for help, export, and opening source files. The toolbar inthe Call Paths view adds a few unique options.

The following options are available from the toolbar:

HelpOpens contextual help in Eclipse.

Export table to a text fileOpens the export dialog box, enabling you to export the data from the table view. Values can beseparated by spaces, commas, or tab delimiters, making it easy to save data as a separate file orto open it in your favorite spreadsheet application.

Edit SourceOpens the source file in your preferred editor. Without any rows selected in the table view, theEdit Source option is disabled.

Fully expand all rows - Call Paths view onlyShows the entire hierarchy. It has the effect of opening disclosure controls to reveal allprocesses, thread, and functions.

Fully collapse all rows - Call Paths view onlyHides all children in the entire hierarchy. It has the effect of closing all disclosure controls.

Related tasks7.4 Sorting table reports on page 7-123.

Related references7.3 Table view keyboard shortcuts on page 7-122.7.2 Table view contextual menu options on page 7-121.7.5 Call Paths view column headers on page 7-125.7.6 Functions view column headers on page 7-126.7.8 Stack view column headers on page 7-128.

7 The Table Views: Call Paths, Functions, and Stack7.1 Table view toolbar options


7.2 Table view contextual menu optionsStreamline provides contextual menu options that help you navigate between the available report types.Right-click on any row in a table report to open a contextual menu.

The following options are available from contextual menus in the table views:

Select Process/Thread in TimelineOpens the Timeline view with the currently selected processes, threads, and functions selectedin the Processes section. Handles for selected processes in the Timeline view appear partiallyblue.

Select in FunctionsOpens the Functions view. All functions related to the selection in the current report are selectedin the Functions view.

Select in CodeOpens the Code view. All lines of code for the current selection are selected in the Code view.

Select in Call GraphOpens the Call Graph view. Any function in the current selection is selected in the Call Graphview.

Select in StackOpens the Stack view. All functions related to the selection in the current report are selected inthe Stack view.

Edit SourceOpens the file that contains the process, thread, or function in your default code editor.

Fully Expand Rows - Call Paths view onlyOpens the hierarchy to reveal every descendent of the selected functions.

Expand Selection to All Matching Functions - Call Paths view onlyUpdates the current selection to include every instance of the selected functions, wherever theyexist in the hierarchy. It expands the hierarchy to expose currently hidden instances of thefunction.

Collapse Unselected Rows - Call Paths view onlyCollapses every row in the hierarchy that is not part of the current selection.


Related references7.3 Table view keyboard shortcuts on page 7-122.7.1 Table view toolbar options on page 7-120.7.5 Call Paths view column headers on page 7-125.7.6 Functions view column headers on page 7-126.7.8 Stack view column headers on page 7-128.

7 The Table Views: Call Paths, Functions, and Stack7.2 Table view contextual menu options


7.3 Table view keyboard shortcutsWhile you can navigate every table report in ARM Streamline using the mouse, you can use keyboardshortcuts to perform common tasks quickly.

The following keyboard shortcuts are available for the table views:

Up arrowMoves the current selection up one row.

Shift + Up ArrowAdds the previous row to the current selection.

Down arrowMoves the current selection down one row.

Shift + Down ArrowAdds the next row to the current selection.

HomeSelects the first row in the active table report.

EndSelects the last row in the active table report.

Page UpMoves up in the current report one page. A page is defined by the range of rows currentlydisplayed in the table report.

Page DownMoves down one page.

Right Arrow - Call Paths view onlyDiscloses the subordinate rows for the currently selected process, thread, or function. Has thesame effect as clicking on the disclosure control to the left of the process, thread, or function'stitle.

Left Arrow - Call Paths view onlyHides the subordinate rows for the currently selected process, thread, or functions.

Shift + Right Arrow - Call Paths view onlyDiscloses all of the subordinate rows for the currently selected process, thread, or functions. Theentire hierarchy below the selected links is revealed.

Shift + Left Arrow - Call Paths view onlyHides all of the subordinate call chain links. On the surface, it has the same effect as pressingthe left arrow by itself, but when the subordinate process, thread, and functions are againrevealed, this command ensures that only their immediate subordinates appear.


Related references7.2 Table view contextual menu options on page 7-121.7.1 Table view toolbar options on page 7-120.7.5 Call Paths view column headers on page 7-125.7.6 Functions view column headers on page 7-126.7.8 Stack view column headers on page 7-128.

7 The Table Views: Call Paths, Functions, and Stack7.3 Table view keyboard shortcuts


7.4 Sorting table reportsStreamline supports multi-level search in all of the table reports, enabling you to bring functions to thetop of table reports based on your specifications.

To perform a multi-level sort in any table report, follow these steps:

Procedure

1. Click once or twice on any of the column headers.The data in the table views is reordered based on the data contained in that column. Repeat clickstoggle the sort order between ascending and descending. The default numerical and alphabeticalsorting behavior varies from column to column, but an upwards arrow in the column header alwaysindicates an ascending sort, while a downward arrow indicates a descending sort.

Note

If an element is selected in the table, a re-sort attempts to keep the selected element in view.

2. Hold down the shift key and click once or twice on a different column header.This provides a secondary sort. This can be repeated on any number of columns to provide multiplelevels of sorting.

Figure 7-1 A multi-level sort

Note

The dots in the lower right of the column headers indicate ordering, with the number of dotsindicating the position of the column in the sort hierarchy. For example, one dot means the markedcolumn is the primary sort column, while two dots indicates it is the secondary sort.

7 The Table Views: Call Paths, Functions, and Stack7.4 Sorting table reports


Related references7.3 Table view keyboard shortcuts on page 7-122.7.2 Table view contextual menu options on page 7-121.7.1 Table view toolbar options on page 7-120.7.5 Call Paths view column headers on page 7-125.7.6 Functions view column headers on page 7-126.7.8 Stack view column headers on page 7-128.

7 The Table Views: Call Paths, Functions, and Stack7.4 Sorting table reports


7.5 Call Paths view column headersThe Call Paths view presents its data hierarchically, showing called functions and threads as subordinatein the hierarchy to their calling function, thread, or process. Every function, thread, or process that calledanother has a disclosure control that you can use to see more of the hierarchy.

The Call Paths view has the following column headers:

SelfSelf time is a measure of time spent in a function or process. It does not include time spent indescendant functions. It reports these amounts here as a total number of samples.

% SelfThe number of samples caused by this function or process as a percentage of the total number ofsamples, capture-wide.

ProcessThe total time spent executing this function, including time spent executing descendantfunctions.

% ProcessThe total time spent executing this function measured against the time spent executing theprocess as a whole.

TotalThe amount of time used by the function and all of the functions it calls.

StackThe number of bytes used by the stack in this function. A question mark is presented if the stackusage of the function is unknown.

Process/Thread/CodeThe name of the process, thread, or function. Every [process] appears in the list enclosed insquare brackets, while {threads} are enclosed in braces.

Note

If you disabled call stack unwinding in the Capture & Analysis Options dialog box, thesampled functions all appear directly under the threads in the Call Paths view.

LocationThis column reports the location of the function, listing both the file name and line of thedeclaration.

Note

All data in the Call Paths view is dependent on the filtering selection in the Timeline view. If you haveused the caliper controls to filter data in the Timeline view, the data in the Call Paths reflects thisselection.


Related references7.3 Table view keyboard shortcuts on page 7-122.7.2 Table view contextual menu options on page 7-121.7.1 Table view toolbar options on page 7-120.7.6 Functions view column headers on page 7-126.7.8 Stack view column headers on page 7-128.14.2 Troubleshooting report issues on page 14-191.3.2 Capture & Analysis Options dialog box settings on page 3-45.

7 The Table Views: Call Paths, Functions, and Stack7.5 Call Paths view column headers


7.6 Functions view column headersThe functions view provides of list of all functions called during the capture session alongside usagedata.

The Functions view has the following column headers:

SelfSelf time is a measure of time spent in a function, without including time spent in descendantfunctions. It reports amounts in this column as a total of samples.

% SelfThe number of samples caused by this function as a percentage of the total number of samples,capture-wide.

InstancesThe number of times the functions appears in the Call Paths view.

Function nameThe name of the function.

LocationThis column reports the location of the function, listing both the file name and line of thedeclaration.

ImageThe image file that contains the function.

Note

All data in the Functions view is dependent on the filtering selection in the Timeline view. If you haveused the caliper controls to filter data in the Timeline view, the data in the Functions view reflects thisselection.


Related references7.3 Table view keyboard shortcuts on page 7-122.7.2 Table view contextual menu options on page 7-121.7.1 Table view toolbar options on page 7-120.7.5 Call Paths view column headers on page 7-125.7.8 Stack view column headers on page 7-128.

7 The Table Views: Call Paths, Functions, and Stack7.6 Functions view column headers


7.7 The Maximum Stack Depth by Thread chartAt the top of the Stack view is a chart titled Maximum Stack Depth by Thread that lists the bestcandidates for stack optimization for each thread.

Beside each bar is the name of the process that called the function, then the thread, then finally thefunction itself. This function exists in the call path with the highest stack depth for the thread, and, out ofall the functions that exist in this call path, it used the most bytes.

Figure 7-2 The Maximum Stack Depth by Thread chart

Clicking on one of the bars bar filters the stack view to feature only functions that contributed to the peakstack for that thread. Click the Show All button to return the Stack view to its default state.

Related references7.8 Stack view column headers on page 7-128.

7 The Table Views: Call Paths, Functions, and Stack7.7 The Maximum Stack Depth by Thread chart


7.8 Stack view column headersThe Stack view ranks functions according to their contribution to the maximum stack depth, providingyou with the best targets for stack optimization.

The Stack view has the following column headers:

StackThe number of bytes used by the stack in this function. A question mark appears next to the totalif the stack usage of the function is unknown.

SizeThe total size of the function, in bytes.

Function NameThe name of the function, as specified in the source code.

LocationThe location of the function, listing both the file name and line of the declaration.

Note

The Stack view depends on successful call stack unwinding. Enable the Call Stack Unwinding option inthe Capture & Analysis Options dialog box.

Related concepts7.7 The Maximum Stack Depth by Thread chart on page 7-127.


Related references7.3 Table view keyboard shortcuts on page 7-122.7.2 Table view contextual menu options on page 7-121.7.1 Table view toolbar options on page 7-120.7.5 Call Paths view column headers on page 7-125.7.6 Functions view column headers on page 7-126.

7 The Table Views: Call Paths, Functions, and Stack7.8 Stack view column headers


Chapter 8The Code View

The Code view provides the highest level of detail in ARM Streamline. It breaks statistics down byindividual lines of code and by disassembly.It contains the following sections:

• 8.1 Code view basics on page 8-130.• 8.2 Selecting rows in the Code view on page 8-131.• 8.3 Path prefix substitution in the Code view on page 8-132.• 8.4 Using the find command in the Code view on page 8-134.• 8.5 Code view toolbar options on page 8-135.• 8.6 Code view keyboard shortcuts on page 8-136.


8.1 Code view basicsThe Code view helps with the discovery of function-level hot spots. It flattens statistics and displaysthem at the source and disassembly levels.

By default, the code view shows the source code next to color-coded statistics. To see both code anddisassembly instructions, click the Disassembly view button to display the Disassembly view.

Figure 8-1 The Code View

The Code view presents the percentage each source line or disassembly entry contributed to the totalsamples collected for the function.

Figure 8-2 The Totals panel

Note

All of the sampling data in the Code view is dependent on the filtering selection in the Timeline view. Ifyou have used the caliper controls to filter data in the Timeline view, the sampling data in the Code viewreflects this selection.

Related tasks8.3 Path prefix substitution in the Code view on page 8-132.8.4 Using the find command in the Code view on page 8-134.

Related references8.5 Code view toolbar options on page 8-135.8.6 Code view keyboard shortcuts on page 8-136.

8 The Code View8.1 Code view basics


8.2 Selecting rows in the Code viewTo select a single row of code in the Code view, simply click on it. If you want the selection to span arange of code lines, you have a few options.

To select multiple rows in the Code view, follow these steps:

Procedure

1. Click on the code row that is the start of your range.2. There are multiple ways to define the range:

• Hold the mouse after clicking on the first row and drag it across a range of rows.• Hold down the shift key and select the last row of the series to select the entire sequence of rows.• Hold down the control key if you want to select additional rows without selecting all of the rows

in between.

Selecting code in the Code view highlights related instructions in the disassembly panel.

Note

The selection behavior in the disassembly section is slightly different than that of the source codesection. Selecting a single line of disassembly selects all of the instructions that relate to a single lineof source code, and you can use function tags to highlight all instruction lines associated with a singlefunction.

Note

If selected source code lines or disassembly instructions contain too many rows to fit in the bounds ofthe current window, small selection indicators appears on the right hand side of the Code view. Ifthere are more selected rows than can fit in the view, the indicators show you how many more arepresent off screen. Click on the More indicator to see additional selected rows.

8 The Code View8.2 Selecting rows in the Code view


8.3 Path prefix substitution in the Code viewARM Streamline automatically locates and displays the source code in the source view. If, however, thesource files are not located in the same directory they were in during compilation, the source view is notpopulated and you must set up path substitutions so that Streamline can find the code.

In cases where Streamline cannot locate the source, it displays a missing source file message in thesource section of the Code view.

Figure 8-3 Missing source file

Follow these steps to set up path prefix substitutions:

Procedure

1. There are two ways to start:

• Click the link under the missing file message.• Click the Set Path Prefix Substitutions button in the toolbar.

Either method opens the Path Prefix Substitutions dialog box.

8 The Code View8.3 Path prefix substitution in the Code view


Figure 8-4 The Path Prefix Substitutions dialog box2. Click the plus symbol to add a new path prefix substitution.3. Enter valid paths in the Prefix and Replacement fields.4. Click the Apply button.

If the path given in the Replacement field contains code that lines up with the code used in thecapture, Streamline populates the view with your source code and the statistical overlay.

Related concepts8.1 Code view basics on page 8-130.

8 The Code View8.3 Path prefix substitution in the Code view


8.4 Using the find command in the Code viewTo search your code and instructions for a function name or an instruction address, use the Find field,located just below the toolbar in the Code view.

Figure 8-5 The Find field

To find a specific function or hexadecimal instruction address, follow these steps:

Procedure

1. Enter a string in the Find field.The box to the right of the Find field updates to show any current matches.

2. Press the Enter key to go to the first match in the code.3. Press the Enter key again to cycle through all available matches.


Related tasks8.3 Path prefix substitution in the Code view on page 8-132.

Related references8.5 Code view toolbar options on page 8-135.8.6 Code view keyboard shortcuts on page 8-136.

8 The Code View8.4 Using the find command in the Code view


8.5 Code view toolbar optionsThe toolbar of the Code view is essential to its functionality. The disassembly button is the most critical,as it opens the disassembly section. Opening this section splits the view and provides a list allinstructions associated with the current source file.

The toolbar of the Code view contains the following buttons:

HelpOpens contextual help in Eclipse.

Disassembly ViewOpens the disassembly panel. The disassembly panel takes up the bottom section of the Codeview and shows the instructions associated with the source code.

Recently Selected FunctionsOpens a drop-down menu that enables you to choose a recently selected function from a list.This selects the function in the code view.

Edit SourceOpens the source file in your preferred editor.

FindOpens a dialog box that enables you to search your file system to find the source file thatmatches the source code used during profiling. Use this button if the source file is missing oryou have previously selected an out of sync source file.



Related references8.6 Code view keyboard shortcuts on page 8-136.

8 The Code View8.5 Code view toolbar options


8.6 Code view keyboard shortcutsThe keyboard shortcuts in the Code view help you to quickly navigate through your source code anddisassembly instructions.

The keyboard shortcuts available for the table views are:

Up arrowMoves the current selection up one row.

Shift + Up ArrowAdds the previous row to the current selection.

Down arrowMoves the current selection down one row.

Shift + Down ArrowAdds the next row to the current selection.

HomeThe home key takes you to the top of the function that contains the currently selected row. If aline of code is selected in the source view that does not have any instructions associated with it,the home key takes you top of the source file.

EndThe end key takes you to the bottom of the function that contains the currently selected row.Like the home key, if the selected line of source does not have any instructions associated withit, the end key takes you to the bottom of the file.

Page UpMoves up one page. A page is defined by the range of rows currently displayed in either thesource or disassembly view.

Page DownMoves down one page.



Related references8.5 Code view toolbar options on page 8-135.

8 The Code View8.6 Code view keyboard shortcuts


Chapter 9The Call Graph View

The Call Graph view displays your code as a visual call hierarchy and color codes functions to highlightsbottlenecks.It contains the following sections:

• 9.1 Call Graph view overview on page 9-138.• 9.2 How the Call Graph view hierarchy is built on page 9-140.• 9.3 Using the mini-map to navigate the Call Graph view on page 9-141.• 9.4 Call Graph view function contextual menu options on page 9-142.• 9.5 Call Graph view whitespace contextual menu options on page 9-143.• 9.6 Call Graph view toolbar options on page 9-144.• 9.7 Call Graph view keyboard shortcuts on page 9-145.


9.1 Call Graph view overviewThe Call Graph view provides you with a visual representation of your code hierarchy, laying out eachfunction according to where it is called and using arrows to connect calling functions. You can use it toquickly identify hotspots in your hierarchy.

The Call Graph view is made up of the following elements:

Function boxesThe Call Graph view draws a function box for each function in your call hierarchy. The CallGraph view color codes the functions according to total samples so the critical functions arequickly identifiable in the Call Graph view. These colors range from bright red to light yellow,red being the highest value, light yellow the lowest. These colors are easily identifiable in themini-map so you can scroll quickly to the critical functions.

Call ArrowsThe direction of the arrow indicates which function was the calling function. An arrow pointingto a function tells you that function is the callee and the function from which the line originatesis the calling function.

Caller and Callee bulletsIn cases where the calling function is in the same column or in a column to the left or right ofthe called function, a call arrow is drawn from the caller to the callee. If, however, the calledfunction appears in a column more than one column to the left of the calling function, a bullet isadded to the left of the calling function and to the right of the called function. The numbercontained in the bullet represents how many calling or called functions the bullet represents.Right-click on a caller or callee bullet to see all of the functions contained in it. Choose afunction in the contextual menu to select and center that function in the Call Graph view.

The mini-mapIn the bottom left hand corner of the Call Graph view is a mini-map that can be used to easilynavigate around the Call Graph view when the hierarchy is too large to fit in the editor sectionof Eclipse.

Click on any function in the hierarchy to select it. In addition to coloring the rectangle dark blue, arrowsare highlighted to show you the connections to the selected function.

9 The Call Graph View9.1 Call Graph view overview


Figure 9-1 A selected function in the Call Graph view

Selecting a function also changes any connected caller or callee bullets from gray to black.

Related concepts9.2 How the Call Graph view hierarchy is built on page 9-140.

Related tasks9.3 Using the mini-map to navigate the Call Graph view on page 9-141.

Related references9.4 Call Graph view function contextual menu options on page 9-142.9.5 Call Graph view whitespace contextual menu options on page 9-143.9.6 Call Graph view toolbar options on page 9-144.9.7 Call Graph view keyboard shortcuts on page 9-145.3.2 Capture & Analysis Options dialog box settings on page 3-45.

9 The Call Graph View9.1 Call Graph view overview


9.2 How the Call Graph view hierarchy is builtThe hierarchy of functions, as presented in the Call Graph view, is built based on the call chains sampledduring execution. An understanding of how Streamline displays this hierarchy helps you to maximize theutility of the view.

Note

The Call Graph view depends on call stack unwinding, an option you can set using the Capture &Analysis Options dialog box.

The originating function is placed in the far left column and functions it calls are placed in the column toits right. Functions that these functions call are placed in a column to the right of that and so on down theline, until all of the functions have been placed. There is a caveat to this placing behavior. If a function iscalled at multiple levels of the hierarchy, it is placed as far left as possible in the Call Graph view.

To illustrate, if the function main calls function a which in turn calls function b, it looks like this:

Figure 9-2 A simple hierarchy

If, in addition to function a, main also calls function b, function b is put in a higher place in thehierarchy, nearer to main, it might look like this:

Figure 9-3 Call Hierarchy with Multiple Calls

The Call Graph view presents a simple call hierarchy, but real-world algorithms describe hierarchies farmore complex than those shown in the figures. Rather than present the Call Graph view with all of theseconnections visually represented as a spider web of call arrows, the Call Graph view uses a simplemethod to determine whether or not to draw a call line.

Related concepts9.1 Call Graph view overview on page 9-138.


Related references9.4 Call Graph view function contextual menu options on page 9-142.9.5 Call Graph view whitespace contextual menu options on page 9-143.9.6 Call Graph view toolbar options on page 9-144.9.7 Call Graph view keyboard shortcuts on page 9-145.

9 The Call Graph View9.2 How the Call Graph view hierarchy is built


9.3 Using the mini-map to navigate the Call Graph viewThe mini-map, located in the lower left of the Call Graph view, helps you quickly navigate large callhierarchies.

To move to new location in the call graph, place the cursor in the call graph and click on a location in themini-map. To pan the viewable area using the mini-map, follow these steps:

Figure 9-4 The Call Graph view mini-map

Procedure

1. Hover over the draggable area box within the mini-map.The cursor changes into a hand when you do so.

2. Click and drag the area box to move the viewable area.The objects in the mini-map have the same color coding as the functions in the Call Graph viewitself. The bright red function in the hierarchy appears as bright red in the mini-map so that you canuse the mini-map to quickly zoom to a bottleneck. Selected functions appear dark blue in the mini-map.

Related concepts9.1 Call Graph view overview on page 9-138.9.2 How the Call Graph view hierarchy is built on page 9-140.

Related references9.4 Call Graph view function contextual menu options on page 9-142.9.5 Call Graph view whitespace contextual menu options on page 9-143.9.6 Call Graph view toolbar options on page 9-144.9.7 Call Graph view keyboard shortcuts on page 9-145.

9 The Call Graph View9.3 Using the mini-map to navigate the Call Graph view


9.4 Call Graph view function contextual menu optionsRight-click on any function in the call graph to open a contextual menu, which presents you with a list ofselection and navigation options so that you have easy access to the calling and called functions of theselected function, in addition to detailed statistics for that function via the table reports.

The contextual menu options for functions in the Call Graph view are:

CallersUse the arrow to the right of this contextual menu option for a complete list of all of thefunctions that called the selected function. Choosing a function from this list selects it in thehierarchy. If the function is the root function, the Call Graph view grays out this menu option.

CalleesThis menu option works identically to the Callers menu option, only it contains a selectable listof functions that are called by the selected function. If the selected function does not call anyfunctions, the Call Graph view grays out this menu option.

Select CallersSelects every function that called the selected functions.

Select Caller TreeSelects the chain of functions that led to the call of the selected functions.

Select Callers and CalleesSelects any function that called or was called by the selected functions.

Select Caller Tree and Callee TreeSelects the chain of functions that led to call of the selected functions and every descendent ofthe selected functions.

Select in...There are four Select in... contextual menu options. Each opens a report view with the currentfunction selected in the new view.

Edit SourceOpens the file that contains the selected function in your default code editor.



Related references9.5 Call Graph view whitespace contextual menu options on page 9-143.9.6 Call Graph view toolbar options on page 9-144.9.7 Call Graph view keyboard shortcuts on page 9-145.

9 The Call Graph View9.4 Call Graph view function contextual menu options


9.5 Call Graph view whitespace contextual menu optionsRight-clicking on an empty area in the Call Graph view produces contextual menu options that enableyou to show or hide specific functions from the call hierarchy.

The contextual menu options for the whitespace in the Call Graph view are:

Toggle System FunctionsStreamline classifies all functions that begin with either an underscore or std:: as systemfunctions, and hides them by default. You can, however, show them by choosing the ShowSystem Functions contextual menu option. All orphaned functions that are no longer connectedto the tree when the system functions are hidden are shown as unconnected boxes at the bottomof the Call Graph view. If this option is active, the contextual menu option changes to HideSystem Functions.

Toggle Uncalled FunctionsThis option works in much the same way as the Show/Hide System Functions option. SelectShow Uncalled Functions and all of the functions contained in your code that were not calledduring the captured execution appear as disconnected boxes in the bottom of the hierarchy.



Related references9.4 Call Graph view function contextual menu options on page 9-142.9.6 Call Graph view toolbar options on page 9-144.9.7 Call Graph view keyboard shortcuts on page 9-145.

9 The Call Graph View9.5 Call Graph view whitespace contextual menu options


9.6 Call Graph view toolbar optionsThe toolbar of the Call Graph view contains a series of options that enable you to access help andperform common operations.

The toolbar buttons available in the Call Graph view are:

Show HelpOpens the help view with a list of topics relevant to the Call Graph view.

Toggle System FunctionsStreamline classifies all functions that begin with either an underscore or std:: as systemfunctions, and hides them by default. You can, however, show them by choosing the ShowSystem Functions drop-down menu option. All orphaned functions that are no longer connectedto the tree when the system functions are hidden are shown as unconnected boxes at the bottomof the Call Graph view. If this option is active, the contextual menu option changes to HideSystem Functions. This button is highlighted if system function visibility is currently off.

Toggle Uncalled FunctionsThis option works in much the same way as the Show/Hide System Functions option. SelectShow Uncalled Functions and all of the functions contained in your code that were not calledduring the captured execution appear as disconnected boxes in the bottom of the hierarchy.

Toggle Mini-mapToggle mini-map visibility on and off.

Edit SourceEdit the source file that contains the selected function.



Related references9.4 Call Graph view function contextual menu options on page 9-142.9.5 Call Graph view whitespace contextual menu options on page 9-143.9.7 Call Graph view keyboard shortcuts on page 9-145.

9 The Call Graph View9.6 Call Graph view toolbar options


9.7 Call Graph view keyboard shortcutsThe Call Graph view provides keyboard shortcuts to enable you to quickly traverse the call hierarchy.

Use the following keyboard shortcuts to navigate the Call Graph view:

Up arrowMoves the current selection up one function box.

Down arrowMoves the current selection down one function box. The down arrow does not move theselection to the uncalled and disconnected functions. These must be selected using the mouse.

Right arrowMoves the current selection to the right. If no function is to the immediate right of the currentfunction box, ARM Streamline chooses the closest available function in the row to the right ofthe currently selected function.

Left arrowMoves the current selection to a function box to the left of the currently selected function.Works in the same manner as the right arrow command.

HomeSelects the top function box in the current Call Graph view row.

EndSelects the bottom function box in the current Call Graph view row.

SPACEBARHolding down the spacebar turns the mouse cursor into a hand and enables you to click and dragthe viewable area.

TABCycles the selection to the next highest self time value.

Shift + TABCycles the selection to the function one above the current selection in terms of its self timevalue. For example, if the function with the third highest self time value is selected, pressingSHIFT + TAB selects the second highest function.



Related references9.4 Call Graph view function contextual menu options on page 9-142.9.5 Call Graph view whitespace contextual menu options on page 9-143.9.6 Call Graph view toolbar options on page 9-144.

9 The Call Graph View9.7 Call Graph view keyboard shortcuts


Chapter 10Streamline Annotate

This feature enables you to add annotations to your code that are propagated into the Timeline and Logviews. Color coded, timestamped annotations present efficient visualization of significant events in yourcode.It contains the following sections:

• 10.1 Annotate overview on page 10-147.• 10.2 Adding Streamline Annotate to your code on page 10-148.• 10.3 Visual Annotate overview on page 10-149.• 10.4 Adding Visual Annotate to your code on page 10-151.• 10.5 Kernel annotation on page 10-152.• 10.6 Annotate macros on page 10-153.• 10.7 Importing the Streamline_annotate example on page 10-155.


10.1 Annotate overviewWhile ARM Streamline provides a large variety of target information, sometimes you might requireextra context. Streamline Annotate provides a facility for you to add this context to Streamline.

The Streamline Annotate feature works in a similar way to printf(), but instead of console output,annotate statements populate the Log view and place framing overlays right in the Streamline Timelineview.

Note

The user space only mode of gator does not support annotations.

Figure 10-1 Annotation overlays

When the user space application writes to the /dev/gator/annotate file, the gator driver marks therecorded annotate-driven output with a timestamp and integrates the recorded data into the Streamlinesample and trace capture report.

The annotated text is marked with a thread identifier that keeps the data uncluttered and eliminates thenecessity of user mutexes. Writing to the annotate file is handled by the standard C library functions.

The application code accesses the virtual annotate file using the standard C library functions: fopen(),fwrite(), and fflush().

Annotation groups and channels

You can use the ANNOTATE_NAME_CHANNEL and ANNOTATE_NAME_GROUP to define channels and groups tobetter organize your Annotations. A defined Annotation channel appears under the thread in theProcesses section of the Timeline. Channels can be further sorted by groups, with multiple channelsappearing under a group title that you define using the ANNOTATE_NAME_GROUP macro.

Related tasks10.2 Adding Streamline Annotate to your code on page 10-148.10.7 Importing the Streamline_annotate example on page 10-155.


10 Streamline Annotate10.1 Annotate overview


10.2 Adding Streamline Annotate to your codeStreamline provides a set of macros that enable you to send customized output to your generatedAnalysis Reports. This feature, called Annotate, is much more versatile than printf() statements, andyou can use them to add overlays or automatic bookmarks to the Timeline view.

Note

If you use the -pthread option when linking, you must also use it with GCC at compile time forAnnotate to work correctly.

To start using the Annotate feature, follow these steps:

Procedure

1. Ensure gatord is running. gatord creates the /dev/gator/annotate file.2. Include the streamline_annotate.h header file by adding the following include statement to your

code: #include "streamline_annotate.h"If are you working in Java, StreamlineAnnotate.java provides the same functionality as themacros in streamline_annotate.h.

3. Add the ANNOTATE_SETUP macro to your code. It must be called before any other annotate macros arecalled.

4. Add one ANNOTATE_DEFINE macro to your code.5. Write null-terminated strings to the file from any thread using the ANNOTATE macro:

ANNOTATE(string)

6. Optional: Set the color of the annotation using the ANNOTATE_COLOR macro and either choosing acolor constant from those defined in streamline_annotate.h or sending the ASCII escape codefollowed by a 3-byte RGB value: ANNOTATE_COLOR(color, string)

7. Optional: Use ANNOTATE_END to clear the annotation message for the thread.

Related concepts10.1 Annotate overview on page 10-147.

Related tasks10.7 Importing the Streamline_annotate example on page 10-155.


10 Streamline Annotate10.2 Adding Streamline Annotate to your code


10.3 Visual Annotate overviewIn addition to simple text overlays using Annotate, Streamline supports the annotation of images,providing further application-level context to the Timeline view.

Just like textual annotation, the application writes to /dev/gator/annotate virtual file using standard Clibrary functions. The gator driver outputs this data with a timestamp to Streamline and integrates it withthe trace and sample report.

Figure 10-2 Visual Annotation in the Timeline view

To include images in the data sent to the host during a capture session, use the ANNOTATE_VISUAL macroin your source code instead of the ANNOTATE and ANNOTATE_COLOR macros used in standard annotation.ANNOTATE_VISUAL provides a parameter for image data.

Note

Visual Annotation supports images in the following formats: GIF, PNG, JPEG, TIFF, ICO, and BMP+RLE. There is no limit to the image size but the larger the image, the greater impact on the systemperformance. Increasing the amount of data sent to the host in this way increases the probe effect for theapplications you are profiling.

The following example function is from the Streamline_annotate example project, included in theLinux_examples archive in the examples directory of your DS-5 installation:

void displayImage() { char filename[32]; char* image; unsigned int size;

// Supported formats include gif, png, jpeg, tiff, ico, bmp (+rle) strcpy(filename, "splash.bmp"); image = readFromDisk(filename, &size); if (image == NULL) { printf("error loading image %s\n", filename); exit(1);

10 Streamline Annotate10.3 Visual Annotate overview


}

// Add text along with the image annotation ANNOTATE_VISUAL(image, size, filename); free(image);}

You can see the effects of visual annotation in the Timeline and Log views of your Streamline AnalysisReports. With visual annotations, the Timeline view data includes a chart that contains the annotatedimages. In the Log view, any annotation event that includes an image has an icon in the message field.Hover over the icon to see the image.

Related concepts6.27 Visual Annotation in the Timeline view on page 6-117.


10 Streamline Annotate10.3 Visual Annotate overview


10.4 Adding Visual Annotate to your codeStreamline provides a set of macros that enable you to send images to your generated Analysis Reports.Use them to add images to Timeline and Log views.

To use the Visual Annotate feature to add images to the Timeline and Log views, follow these steps:

Procedure

1. Ensure gatord is running. gatord creates the /dev/gator/annotate file.2. Include the streamline_annotate.h header file by adding the following include statement to your

code: #include "streamline_annotate.h"3. Add the ANNOTATE_SETUP macro to your code. It must be called before any other annotate macros are

called.4. Add one ANNOTATE_DEFINE macro to your code. You must call the following before using the

ANNOTATE_VISUAL macro.5. Insert the ANNOTATE_VISUAL macro into your code: ANNOTATE_VISUAL(data, length, str);

Replace data with your image, length with the size of the data being written to the annotate file, andstr with a descriptive string to be included with the image. Including a string is optional.

10 Streamline Annotate10.4 Adding Visual Annotate to your code


10.5 Kernel annotationYou can insert the Annotate macros of Streamline in either user-space or kernel code. There are a fewimportant considerations when using Annotate with kernel code.

Note

As the Annotate macros may block, do not add them to kernel code in an interrupt context.

Insert Annotation macro codes in kernel code in the same way you would user space code, with thefollowing exceptions:

• Do not call ANNOTATE_SETUP in kernel code. This macro is a prerequisite to other Annotate macros inuser space code, but not in kernel code.

• ANNOTATE_DEFINE is also unnecessary. You do not need to add an instance of ANNOTATE_DEFINE inkernel code.

Related tasks10.7 Importing the Streamline_annotate example on page 10-155.


10 Streamline Annotate10.5 Kernel annotation


10.6 Annotate macrosStreamline provides a variety of macros to mark up your code, whether you want color markup, macrosthat include channel information, or macros that insert automatic bookmarks in the Timeline view.

Insert the following macros in your source code to enable Streamline Annotate:

Note

You must add the file streamline_annotate.h, located in .../gator/annotate/, to your list ofincludes to use these macros.

Mode Description

ANNOTATE_SETUP() Call this macro before any other annotate macros to setup annotation.

Note

When you annotate from within the kernel or a module, you do not need to useANNOTATE_DEFINE and ANNOTATE_SETUP. Kernel annotations are not supportedin interrupt context.

ANNOTATE_DEFINE() Like ANNOTATE_SETUP(), you must insert a single instance ofANNOTATE_DEFINE() in your code for annotation to work. UnlikeANNOTATE_SETUP(), it does not matter where ANNOTATE_DEFINE() is called.

ANNOTATE(string) This functions adds a string annotation. Because the ANNOTATE macro does notdefine a specific channel, the annotation is added to channel 0 by default.

ANNOTATE_CHANNEL(channel, string) Adds a string annotation to a channel defined by the numeric identifier passedto the channel variable.

Note

Annotation channels and groups are used to organize annotations within thethreads shown in the processes section of the Timeline view. Each annotationchannel appears on its own line under the thread. Channels may also be sortedby groups and displayed under a group name that you define using theANNOTATE_NAME_GROUP macro.

ANNOTATE_COLOR(color, string) Works the in the same way as the basic ANNOTATE macro, only use the colorvariable to define an interface display color for the annotation string.

ANNOTATE_CHANNEL_COLOR(channel,color, string)

Use this macro to define an annotation string, give it an color for display in theinterface, and assign it to a channel by passing a channel identifier to thechannel variable.

ANNOTATE_END() This command terminates the annotation. Because the ANNOTATE_END macrodoes not define a specific channel, it defaults to channel 0.

ANNOTATE_CHANNEL_END(channel) Terminates the annotation for the given channel.

ANNOTATE_NAME_CHANNEL(channel,group, string)

Use this command to name a channel and attach it to a group. Enter a numberfor the channel variable, the identifier of a valid group for group, and yourown channel title for the string variable.

ANNOTATE_NAME_GROUP(group,string)

Use this command to give an annotation group a title. Pass a group identifierto the group variable and a name for the group to the string variable.

ANNOTATE_MARKER() Use this function to add a red bookmark to the Timeline view without a title. Ithas no parameters.

10 Streamline Annotate10.6 Annotate macros


(continued)

Mode Description

ANNOTATE_MARKER_STR(string) This function adds a marker to the Timeline view with a title. Pass a string as aparameter to ANNOTATE_MARKER_STR(...) and the Timeline view displays itwhen you hover over the bookmark.

ANNOTATE_MARKER_COLOR(color) This functions adds a bookmark and assigns it a color. Pass a color through asa parameter to automatically assign it to the bookmark.

ANNOTATE_MARKER_COLOR_STR(color,string)

This function creates a bookmark with a title, and a color. Set the color and thetitle string using the function parameters and the created bookmark appears inthe Timeline view with the defined properties.

ANNOTATE_VISUAL(data, length,str)

Insert in your code to record an annotation that includes an image in one of thefollowing formats: GIF, PNG, JPEG, TIFF, ICO, and BMP +RLE. Replacedata with your image, length with the size of the data being written to theannotate file, and str with a descriptive string to be included with the image.Including a string is optional.

Note

You can locate all of the files provided by DS-5 Debugger by selecting Help > ARM Extras... from themain menu. See the streamline_annotate.h located here for a better understanding of how to call eachannotate macro.

Related concepts10.1 Annotate overview on page 10-147.10.5 Kernel annotation on page 10-152.

Related tasks10.2 Adding Streamline Annotate to your code on page 10-148.10.7 Importing the Streamline_annotate example on page 10-155.10.7 Importing the Streamline_annotate example on page 10-155.

10 Streamline Annotate10.6 Annotate macros


10.7 Importing the Streamline_annotate exampleThe best way to get started with Streamline Annotate is to import the Streamline_annotate example. Itcontains examples of how to use standard, visual, and bookmark annotations.

To import the Streamline_annotate example, follow these steps.

Procedure

1. In Eclipse for DS-5, select File > Import...2. In the Import dialog box, use the Disclosure control to open the General Tab.3. Select Existing Projects into Workspace.4. Click Next.5. Use the radio button to activate the Select archive file field.6. Click the Browse button next to the Select archive file field.7. Navigate to ../examples in your DS-5 installation directory.8. Select the Linux_examples archive.9. Click Open.10. Make sure the Streamline_annotate example is checked. Select any other projects you want to import.11. Click Finish.

When completed, the Streamline_annotate example appears in your Project Explorer view alongwith any other examples you imported.


Related tasks10.2 Adding Streamline Annotate to your code on page 10-148.


10 Streamline Annotate10.7 Importing the Streamline_annotate example


Chapter 11The Log View

The Log view lists every message generated by the ANNOTATE, ANNOTATE_COLOR and ANNOTATE_VISUALstatements in your code along with information related to the message.It contains the following sections:

• 11.1 Log view column headers on page 11-157.• 11.2 Log view search fields on page 11-159.• 11.3 Log view contextual menu options on page 11-160.• 11.4 Log view totals panel on page 11-161.


11.1 Log view column headersThe Log view lists every annotation generated during your capture session alongside when it occurredand what code created it.

Note

To populate the Log view, insert ANNOTATE statements in your code. Absent ANNOTATE statements in thesource, the view is empty.

The Log view contains the following column headers:

WhenThis value, given in seconds, tells you when message was generated during the capturedexecution. All messages appear in the Log view in chronological order.

DurationThe length of time the annotation lasted.

MessageThe contents of the message generated by ANNOTATE. If an annotation message contains animage, a camera icon appears in the Message column. Select a row with a camera icon to see theimage.

Figure 11-1 Visual annotation in the Log view

GroupYou assign any channel to a group using the ANNOTATE_NAME_CHANNEL macro. to create a group.The title created using the ANNOTATE_NAME_GROUP macro is used in this column.

ChannelIf you assigned a macro to a channel using either the ANNOTATE_CHANNEL orANNOTATE_CHANNEL_COLOR macros, the channel name is listed here.

CoreThe core that generated the message.

WhereThe process and thread that generated the message.

Note

Unlike the other table reports in Streamline, you cannot sort the data in the Log view.


Related references11.2 Log view search fields on page 11-159.

11 The Log View11.1 Log view column headers


11.3 Log view contextual menu options on page 11-160.11.4 Log view totals panel on page 11-161.

11 The Log View11.1 Log view column headers


11.2 Log view search fieldsThe Log view provides three search fields above the table data that enable you to find particularmessages.

The regular expression that you enter in any of the search fields acts as a filter. Only messages thatcontain the matching pattern appear in the list, sorted in the chronological order. The log view containsthe following search fields:

WhenUse this search field to filter the Log view based on when Streamline captured the annotation.To define a range, enter a number for the lower limit of the range, a dash, and a second numberthat defines the upper limit. For example, 4-5 filters the Log view so it only shows annotationscaptured between seconds 4 and 5. To define a range up to a certain number, input a dash andthen a single number. To define a range that includes a number and everything above it, enter anumber followed by a dash. For example, to filter for annotations that occurred after the thirtysecond mark of the capture, enter 30-.

GroupFind all messages that belong to the given group.

MessageSearch the message field for a string. Only messages that match the given pattern appear in thelog view until the search is modified or cleared. Regular expression strings are case sensitiveunless you include (?i) in front of your search expression.

DurationFilter the Log view based on the duration field. As with the When field, you can enter a numberor a range of numbers.

ChannelFind all messages assigned to the given channel.

CoreFind messages called by a particular core. Enter a core number here and the Log view displaysonly messages triggered by that core.

WhereSearch based on the location that triggered the annotate message. To narrow down messages tothose called by a particular function, enter that function name in the Where field.


Related references11.1 Log view column headers on page 11-157.11.3 Log view contextual menu options on page 11-160.11.4 Log view totals panel on page 11-161.

11 The Log View11.2 Log view search fields


11.3 Log view contextual menu optionsRight-click anywhere in the table to open a contextual menu that provides you with options that enableyou to navigate to selected annotations in either the Timeline view or the Call Paths table report.

The menu contains the following options:

Select Time Range in TimelineOpens the Timeline view with the Cross Section Marker set to include all of the selected entries.

Select Process/Thread in TimelineOpens the Timeline view with the Cross Section Marker moved to the location of the selectedannotation message.

Select in Call PathsOpens the Call paths view. All functions related to the selection in the Log view are selected inthe Call paths view.


Related references11.1 Log view column headers on page 11-157.11.2 Log view search fields on page 11-159.11.4 Log view totals panel on page 11-161.

11 The Log View11.3 Log view contextual menu options


11.4 Log view totals panelThe totals panel provides additional information when you select multiple messages in the Log view.

The total panel contains the following fields:

Log EntriesThe total number of messages you have selected in the Log view.

DeltaThe total difference in time between the function called first and the function called last amongstthe selected functions. Use the totals panel to easily see the time gap between two messages byclicking on one and holding Ctrl and clicking on a second. The value in the Totals Panel Deltafield updates to show you the time difference between the two selected messages.


Related references11.1 Log view column headers on page 11-157.11.2 Log view search fields on page 11-159.11.3 Log view contextual menu options on page 11-160.

11 The Log View11.4 Log view totals panel


Chapter 12Capturing Energy Data

To capture energy data for Streamline you must have either an ARM Energy Probe or a supported NI-DAQ device. The ARM Energy Probe is a compact probe designed for application and system softwaredevelopers to measure any combination of power, voltage, and current in up to three channels. Thecombination of ARM Streamline and an energy capture device enable the visualization of power metricsagainst the software behavior of your target hardware. It provides a better understanding of the static anddynamic behavior of your target system for the purposes of debugging, profiling, and analysis.It contains the following sections:

• 12.1 Energy Probe overview on page 12-163.• 12.2 Energy Probe requirements on page 12-165.• 12.3 Shunt resistor selection for Energy Probe on page 12-166.• 12.4 Setting up Energy Probe on page 12-167.• 12.5 Adding the caiman application to Streamline™ on page 12-169.• 12.6 Updating your firmware on page 12-170.• 12.7 Energy Probe data in Streamline on page 12-171.• 12.8 Applying manual offsets to align energy data on page 12-173.• 12.9 Setting up National Instrument Multifunction Data Acquisition devices (NI-DAQ) to capture

energy data on page 12-174.


12.1 Energy Probe overviewThe Energy Probe is designed to be a low impact, inexpensive solution to give you quick feedback on theimpact of your code on the system energy footprint. It is not intended to be a high-precision dataacquisition instrument for power benchmarking.

The Energy Probe has three power connectors, each of which is designed to connect to a 2-pin header formeasuring the power. This allows the energy probe to provide three independent power, current, orvoltage measurements.

Figure 12-1 Energy Probe schematic

In addition to the three power connectors, the Energy Probe has a single pin GND connector that must beconnected to ground on your target board. It provides a ground connection for the Energy Probe.

Each of the three power connectors measures:

• The current flow through a shunt resistor of a known value on your target system• The voltage at the positive terminals of the Energy Probe.

Figure 12-2 Energy Probe electrical connection example

Caution

The Energy Probe has flying leads and must be carefully connected to your target. Do not plug the greenground wire into anything but the target ground. This includes I/O pins and power pins. Doing so couldcause damage to your Energy Probe or the power supply of your target.

Related concepts12.7 Energy Probe data in Streamline on page 12-171.

Related tasks12.4 Setting up Energy Probe on page 12-167.12.5 Adding the caiman application to Streamline™ on page 12-169.

12 Capturing Energy Data12.1 Energy Probe overview


Related references12.2 Energy Probe requirements on page 12-165.

12 Capturing Energy Data12.1 Energy Probe overview


12.2 Energy Probe requirementsUsing the Energy Probe with Streamline requires the Energy Probe hardware, a DS-5 installation, and atarget with a shunt resistor that meets the specifications required by the Energy Probe.

The Energy Probe has the following requirements:

• An installation of ARM DS-5 Basic or Professional Edition, version 5.9 or later.• A suitable DS-5 license.• A Streamline-enabled target. For Linux and Android targets, this requires the gator driver and

daemon to be installed on the target.• An Energy Probe Unit.• A USB extension cable.• USB drivers for the Energy Probe.• A target that has 2-pin IDC 0.1" power measurement headers. The target also requires a shunt resistor

with a supply voltage less than 15V and rated at least 0.5W. The shunt resistor needs a 1-pin IDCground terminal and must not drop more than 165mV.

Note

You can tell if your target has the right power management headers by visual inspection. For moreinformation about whether or not your target meets the other requirements for Energy Probe, see thedocumentation for your target.

Related concepts12.1 Energy Probe overview on page 12-163.12.7 Energy Probe data in Streamline on page 12-171.


12 Capturing Energy Data12.2 Energy Probe requirements


12.3 Shunt resistor selection for Energy ProbeWith 20x amplification, Energy Probe requires the correct selection of a shunt resistor to provide the bestpossible dynamic range in power measurement, while avoiding saturation of the input of Energy Probe.

A shunt resistor with a value too low reduces measurement dynamic range, resulting in less resolution inthe power data. A shunt resistor with a value too high can cause the input stage of the Energy Probe tosaturate, which causes a flat line in the charts related to Energy Probe in the Streamline Timeline view.

To avoid input saturation, the drop across the Rshunt resistor must never be more than 165mV. You canalso use the following equation to determine if your shunt resistor is appropriate:

RShunt(max) = 165 x Vsupply / ( 1000 x Power )

Vsupply is the input/core voltage. Power(max) is the maximum power that the Energy Probe measures.Rshunt(max) is the maximum value of the shunt resistor. A shunt resistor value greater thanRshunt(max) might cause input saturation.

This equation provides the absolute maximum value for Rshunt. Use a value that is more than fivepercent lower than this value to allow for component tolerances.

Note

When connecting the Energy Probe, consider the following:

• The black and white probe closest to the green wire is Channel 0.• For best results, attach Channel 0 to the power source which best represents the CPU load. Streamline

aligns the power data with the software activity by maximizing the correlation of Channel 0 with theCPU load.

• The probe white wire is V+. The black wire is V-.

Examples

• 5V power supply, 8W(max), Rshunt(max) = 100 milliohms.• 1V core voltage, 2.5W(max), Rshunt(max) = 50 milliohms.• 1.5V core voltage, 0.4W(max), Rshunt(max) = 500 milliohms.

12 Capturing Energy Data12.3 Shunt resistor selection for Energy Probe


12.4 Setting up Energy ProbeIt is critical that you set up your Energy Probe correctly. Failure to do so can result in missing power datain Streamline, and, in some cases, damage to your target.

Figure 12-3 Connection to target

To set up Energy Probe, follow these steps:

Procedure

1. Connect your target to your host through a USB port.2. If necessary, install drivers using the standard Windows driver installation.

When first plugging in the Energy Probe on Windows, the LED flashes RED at approximately onesecond intervals. This indicates the USB enumeration has failed and that you must install the driver.

3. If prompted to locate the driver file, select the ARM_EnergyProbe.inf configuration file, located ininstall_directory/sw/energy probe/

4. To setup on Linux Ubuntu, enter the following command: sudo apt-get install libudev-dev5. On Linux Ubuntu, you must either change the permissions of the tty device or add yourself to the

dialout group for Energy Probe to successfully use the device. To change the permissions of the ttydevice, either:

• Use the following command: chmod 777 tty_location

12 Capturing Energy Data12.4 Setting up Energy Probe


• Add yourself to the same group as the tty device. To do so, enter the following command:usermod -a -G Group_Name User_Name

dialout is the usual name of the group for the tty device.When you have installed the driver and it is operating correctly, the LED remains green. If you attacha probe to the target with the channel wire connector the wrong way around, this causes the LED toturn red and blink. This does not damage your target or the Energy Probe but it does not provideuseful data. If this happens, disconnect all Energy Probes and wait until the LED changes to green,then reattach them one by one and make sure you reverse any probe that caused the LED to change tored. When you have attached the Energy Probe correctly, the LED remains green.

Note

In case of low consumption, it is possible that the LED remains red even if the connection is right.This might happen if the target device is idle.

6. If your target has headers available for power or energy metering, attach the ground wire, then attachthe probes.

7. Attach the probes.Make sure the probe polarity is correct by observing if the LED changes from green to red. The probewhite wire is V+. The black wire is V-.


Related tasks12.5 Adding the caiman application to Streamline™ on page 12-169.12.6 Updating your firmware on page 12-170.


12 Capturing Energy Data12.4 Setting up Energy Probe


12.5 Adding the caiman application to Streamline™

For Streamline to communicate with the Energy Probe, you must point it to the caiman application usingthe Tool Path field in the Capture & Analysis Options dialog box.

To configure Energy Probe in DS-5 for Eclipse, follow these steps

Procedure

1. Select the ARM Energy Probe option from the Energy Capture drop-down menu.2. Click the Choose from the file system... button next to the Tool Path field.3. Locate caiman.exe in your DS-5 installation directory and select it.4. Click Open.

Figure 12-4 The populated Tool Path field

Note

It might be necessary to specify the tty device when using the ARM Energy Probe on Linux. To doso, enter the following in the Device field: /dev/ttyACM0. When using NI-DAQ, the device name isusually Dev1.

Note

On Windows, you can leave the Device field empty. Streamline auto-detects your energy probe.


Related tasks12.4 Setting up Energy Probe on page 12-167.


12 Capturing Energy Data12.5 Adding the caiman application to Streamline™


12.6 Updating your firmwareNecessary updates occasionally become available for the Energy Probe firmware.

Follow these instructions to update your software:

Procedure

1. Detach the Energy Probe probes and ground from the target.2. Copy the file eprobe_firmware.bin to a local folder on your Windows machine.

Because of a limitation with the USB bootloader from the MCU vendor, updating firmware on Linuxis not supported.

3. Plug the Energy Probe into a USB port.4. To enable firmware programming mode, insert a paperclip into the little hole on the top near the

LED.5. Press and hold down the button for three seconds.6. Wait for LED to turn red, and then off. Firmware programming mode is now active.7. When the drive folder has opened, delete the firmware.bin file. This file is a placeholder.8. Drag and drop the new eprobe_firmware.bin file onto the drive folder.9. Safely remove the Energy Probe drive from the machine using the Windows Safely Remove driver

icon.10. Unplug the Energy Probe from the machine.11. Wait for one second and plug it back in.

Related tasks12.4 Setting up Energy Probe on page 12-167.

12 Capturing Energy Data12.6 Updating your firmware


12.7 Energy Probe data in StreamlineAfter you have successfully setting up the Energy Probe and have run a capture session, you can see theEnergy Probe data aligned to the software activity in the Timeline view of Streamline

If your target meets the requirements, and you have attached a power probe point that closely resemblesthe activity of the CPU cores using Channel 0, the Streamline correlation algorithm aligns the data foryou. Notes that appear when you click the warnings tag on the left side of the toolbar communicate anylimitations or failures in this area.

When you have set up everything correctly, run a standard report capture and analysis. A large variancebetween idle and activity ensures that the correlation algorithm has something to lock onto, so set yourworkloads accordingly. If you have connected and configured your Energy Probe correctly, a powerchart now appears in the Timeline view.

Figure 12-5 Energy Probe data in the Timeline view

Related concepts12.1 Energy Probe overview on page 12-163.


12 Capturing Energy Data12.7 Energy Probe data in Streamline



12 Capturing Energy Data12.7 Energy Probe data in Streamline


12.8 Applying manual offsets to align energy dataChart data related to power can be offset manually using the Energy Offset menu, located in the bottomleft of the Timeline view.

To manually offset the energy data in the Timeline view, follow these steps:

Procedure

1. Click on the Energy Offset menu, located next to the Snippets menu in the bottom left on theTimeline view.

Figure 12-6 The Energy Offset menu2. Use the left and right arrows to move the power data left and right until it lines up appropriately with

the other data in the Timeline view.You can use the Reset button, located between the left and right arrows, to returns the power data toits original position.The Energy Offset menu is disabled if there are no energy counters displayed in the Timeline viewcharts.

Related concepts6.3 Timeline view charts on page 6-73.

12 Capturing Energy Data12.8 Applying manual offsets to align energy data


12.9 Setting up National Instrument Multifunction Data Acquisition devices (NI-DAQ) to capture energy data

In addition to the Energy Probe, you can also use NI-DAQ devices to gather energy data from your targetand view the results in Streamline.

To collect power statistics using a NI-DAQ device, you must have the following:

• NI-DAQ hardware.

• NI-DAQmx software installed on your host machine. This software package includes drivers for theNI-DAQ device.

Note

If you are running on Linux, you must use the NI-DAQmx Base software. Currently, Red Hat Linuxis the only type of Linux that the NI-DAQ device is supported on. Also, caiman must be built fromsource with Linux. Edit CMakeLists.txt and set SUPPORT_DAQ to 1, set NI_RUNTIME_LINK to 0 andverify the NI-DAQ install paths within CMakeLists.txt. See README_caiman.txt in the DS-5install directory for details.

Note

All necessary software is available on the National Instruments website, http://www.ni.com.

To set up your NI-DAQ device, follow these steps:

Procedure

1. Connect the Ai1 connections on the NI-DAQ device to go across the shunt resistor on your target.2. Connect Ai0 negative to ground.3. Also connect Ai GND to ground.4. Loop Ai0 positive to Ai1 negative.

The Ai0 connectors is measured across the load, which is used to derive the voltage.

12 Capturing Energy Data12.9 Setting up National Instrument Multifunction Data Acquisition devices (NI-DAQ) to capture energy data


http://www.ni.com

Figure 12-7 Connections for NI USB-621x5. Repeat steps 1 through 3 using the other connectors on the NI-DAQ device to measure additional

channels.6. In the Streamline Data view of DS-5 for Eclipse, click Capture & Analysis Options.7. Select the NI-DAQ option from the Energy Capture drop-down menu.8. Enter a valid system name in the Device field.

To get the system name of your National Instruments device, you must run the NI-DAQmx Base ListDevices application, installed as part of the NI-DAQmx software package.

9. Click the Choose from the file system... button next to the Tool Path field.10. Locate caiman.exe in your DS-5 installation directory and select it.11. Click Open.

Related references3.2 Capture & Analysis Options dialog box settings on page 3-45.

12 Capturing Energy Data12.9 Setting up National Instrument Multifunction Data Acquisition devices (NI-DAQ) to capture energy data


Chapter 13Advanced Customizations

Learn how to customize the more advanced collection and reporting features of ARM Streamline.It contains the following sections:

• 13.1 Capturing data on your target on page 13-177.• 13.2 Capturing energy data locally and importing it to a capture on page 13-178.• 13.3 Using the gator_events_mmapped.c custom counters example on page 13-179.• 13.4 Creating custom performance counters on page 13-180.• 13.5 gator_events functions on page 13-181.• 13.6 Category and event parameters for custom counters in events.xml on page 13-182.• 13.7 Getting L2C-310 memory-mapped peripherals working with Streamline on page 13-184.• 13.8 Profiling the Linux kernel on page 13-185.• 13.9 Re-analyzing Stored Streamline Capture Data on page 13-186.• 13.10 Streamline™ preferences on page 13-188.


13.1 Capturing data on your targetTypically, ARM Streamline uses an active network connection to send captured data from the target tothe host. If this is not possible because of limitations with your target, you can save the data to localtarget storage for a later manual transfer to your host.

To capture data locally, follow these steps:

Procedure

1. Create a session.xml file. To do so, use the Capture & Analysis Options dialog box to set yourcapture options, then click the Export... button to save the new session.xml file.Alternatively, you can copy a session.xml file from an existing capture.

2. Create a configuration.xml file. To do so, define your target in the Connection field, then open theCounter Configuration dialog box from the Streamline Data view. Set up the counters you want tocollect, then click Save. A new configuration.xml file is created in the directory where gatord isrunning. This file is automatically used when you run gatord. To define a specific configuration file,use the -c option when you run gatord.If your target is not TCP/IP capable, you must create a configuration.xml file and manuallytransfer it to your target. For instructions on how to do this, see http://community.arm.com/thread/4568

3. Enter the following command:./gatord -s session.xml -o <YourFileName>.apc &

The -s option defines the location of session.xml and the -o option defines the name and locationof the resulting .apc output file.

4. Stop the capture session. You can do so in a number of different ways:

• Specify a duration using the duration attribute in session.xml.• In the Capture & Analysis dialog box, set the value of Buffer Mode to something other than

streaming. Use one of the following values: Large, Normal, or Small. A Large store-and-forward buffer is 16MB, while Normal is 4MB, and Small is 1MB. The profiling sessionterminates automatically when it reaches the set buffer size.

• Press Ctrl+C on the console to interrupt the gator daemon. The daemon must be running in theforeground.

• Determine the process id of gatord and enter the kill command: kill process_ID.

When the capture stops, Streamline creates an .apc directory on the target with the data and .xmlfiles.

5. Transfer the newly created .apc directory to your host.6. Open Eclipse for DS-5.7. If the Streamline Data view is not already open, select Window > Show View > Other > DS-5 >

Streamline Data.8. Click the Edit Locations... button in the upper right of the Streamline Data View.9. Choose the directory that contains the .apc directory that you transferred from your target.10. If you want to define image files for better data in the report views, double-click on the .apc

directory in the Streamline Data view to open the Analyze dialog box.11. Define your image files using the Analyze dialog box. Image files must match the images that you

ran on your target during the local capture session.12. Click Analyze.

Related tasks13.9 Re-analyzing Stored Streamline Capture Data on page 13-186.

13 Advanced Customizations13.1 Capturing data on your target


http://community.arm.com/thread/4568

http://community.arm.com/thread/4568

13.2 Capturing energy data locally and importing it to a captureIf you want to run a capture session locally and want the resulting report to include energy data, it ispossible to run caiman and gatord simultaneously and then merge the data from the two captures into asingle report.

To import energy data into a capture, follow these steps:

Procedure

1. Open the Capture & Analysis Options dialog box.2. Enable energy capture by selecting ARM Energy Probe or NI-DAQ from the Energy Capture drop-

down menu, then enter the settings for each channel.3. Enter all other options as normal.4. Export a session.xml file using the Export... option.5. On the host, start a caiman local capture where the channel/resistance pairs match what you

configured in the exported session.xml. For example:caiman -l -r 0:20 -r 1:30

6. At the same time, trigger a gator local capture using the session.xml previously exported:gatord -s session.xml -o <YourFileName>.apc

7. When ready, stop the gator capture.8. Immediately stop the caiman capture.9. On your host machine, create a sub-folder in the .apc folder of the gator capture. Name the new folder

energy.10. Copy the following caiman local capture files to the newly created energy folder: 0000000000,

captured.xml, and, if it exists, warnings.xml.11. In the Streamline Data view, right-click on the merged capture and select Analyze... from the

contextual menu.12. Use the Manual Energy Offset button in the Timeline view to match the energy data with other

capture data.

13 Advanced Customizations13.2 Capturing energy data locally and importing it to a capture


13.3 Using the gator_events_mmapped.c custom counters exampleIn the gator-driver.tar.gz archive distributed with your copy of Streamline is a gator source filecalled gator_events_mmapped.c. This file is provided as an example of how to add custom counters.Incorporating the simulated examples from gator_events_mmapped.c into gator is a good way tofamiliarize yourself with the process of adding your own counters.

Note

You can locate all of the files provided by DS-5 by selecting Help > ARM Extras... from the mainmenu.

To add a custom counter using gator_events_mmapped.c, follow these steps:

Procedure

1. Open the gator_events_mmapped.c sample file in the editor of your choice.2. Copy the XML from the comments section of gator_events_mmapped.c.3. Create a new text file in the same directory as the gator daemon source code, and call it events-

mmap.xml.4. Add the copied XML from the comments section of gator_events_mmapped.c to events-

mmap.xml.5. Remove any * comment markers from the copied XML.6. Save events-mmap.xml.7. Rebuild gatord and copy it to the target.8. Kill the old gatord process if it is already running, then enter ./gatord & on the command line of

your target to launch the newly built gatord.9. Open the Counter Configuration dialog using the button in the Streamline Data view.

A new category, mmapped, appears in the Counter Configuration dialog box with the Sine,Triangle, and PWM simulated counters.

10. Add Sine to list of counters.11. Run a capture session.

If successful, the waveform generated by the simulated Sine counter appears in the charts section ofthe Timeline view.

Figure 13-1 The Sine counter in the Timeline view

Related references13.5 gator_events functions on page 13-181.13.6 Category and event parameters for custom counters in events.xml on page 13-182.

13 Advanced Customizations13.3 Using the gator_events_mmapped.c custom counters example


13.4 Creating custom performance countersIn addition to the hardware-specific and Linux performance counters that you can configure using theCounter Configuration dialog box, the gator daemon and driver provide hooks that enable you tocustomize counters.

Streamline derives its default set of counters from the performance monitoring unit, linux hooks, andmemory-mapped peripherals. You can add your own counters to this list if there is a hardware metric thatyou want to track which Streamline does not provide by default.

Note

To create your own counters, mimic the methods used in the gator_events_mmapped.c or any of theother gator_events_x files included with the gator source. You can locate all of the files provided byDS-5 by selecting Help > ARM Extras... from the main menu.

Follow these steps to ensure that gatord interacts with your custom source:

Procedure

1. Create an empty gator_events_your_custom.c file or duplicate gator_events_mmapped.c.2. Update the makefile to build the new gator_events_your_custom.c file.3. Add the preprocessor directive #include "gator.h" if you do not use gator_events_mmapped.c as

a template.4. Implement the following functions in your new source file: gator_events_your_custom_init,

gator_events_your_custom_interface, gator_events_your_custom_create_files,gator_events_your_custom_start, gator_events_your_custom_read, andgator_events_your_custom_stop.

5. Add gator_events_your_custom_init to GATOR_EVENTS_LIST in gator_main.c.6. All of your new counters must be added to the events list. To do this:

a) Create a new XML file in the same directory as the makefile before building gatord. The makefilepulls in any file that begins with events-, so create an XML file called events-YourCustom.xml.

b) Define how many counters exist in your custom set using the <counter_setname="counter_name" count="x"> tag. Give your counter a unique, descriptive name and enterhow many counters are available for the count attribute. For example: <counter_setname="ARM_Cortex-A9_cnt" count="6"/>

c) For each counter set, you must list each of the possible events. Define the event category usingthe <category> tag.

d) Define the individual events for each event category, including all of the necessary attributes.A basic event example:

<event event="0x01" title="Cache" name="Instruction refill" description="Instruction fetch that causes a refill of at least the level of instruction or unified cache closest to the processor"/>

A fixed event example:

<event counter="ARM_Cortex-A9_ccnt" title="Clock" name="Cycles" display="hertz" units="Hz" average_selection="yes" description="The number of core clock cycles"/>

7. Re-build gatord after you create your new XML file.

Related references13.5 gator_events functions on page 13-181.13.6 Category and event parameters for custom counters in events.xml on page 13-182.

13 Advanced Customizations13.4 Creating custom performance counters


13.5 gator_events functionsTo create your own custom counters, you must add gator functions to your source code.

This table gives a brief description of each of the gator events functions:

Gator events function Description

gator_events_your_custom_init gator calls this function at startup.

gator_events_your_custom_interface Tells gator what triggers calls to your custom events file.

gator_events_your_custom_create_files Adds custom directories and enabled, event, and key filesto /dev/gator/events.

gator_events_your_custom_start gator calls this at the start of execution.

gator_events_your_custom_read gator calls this at every sample.

gator_events_your_custom_stop gator calls this at the termination of a capture session.

Related tasks13.3 Using the gator_events_mmapped.c custom counters example on page 13-179.13.4 Creating custom performance counters on page 13-180.

13 Advanced Customizations13.5 gator_events functions


13.6 Category and event parameters for custom counters in events.xmlIn addition to adding gator functions to your code so that gator can collect data for your customcounters, you also must provide descriptions of your counters in the events.xml file.

Note

Additional details are available in the gator protocol documentation, located in DS-5/arm/gator/protocol.

The category node has the following attributes:

Mode Description

name A name for this category of counters. This names the header the counter appearsunder in the Counter Configuration dialog box.

counter_set Defines the counter set to be used.

per_cpu Defines whether or not Streamline collects data on a per cpu basis. Set this valueto yes and Streamline collects data from each cpu separately for these counters.

supports_event_based_sampling Use yes or no to define whether or not the counters in this category can be usedfor event-based sampling. The default value is no.

For example: <category name="Cortex-A9" counter_set="ARM_Cortex-A9_cnt" per_cpu="yes" supports_event_based_sampling="yes">

Use the option_set node when the same event applies to multiple devices. It has the followingattributes:

Mode Description

event_delta The hex integer offset to add to the applicable event to get the event number.

name The name of the device. The value of name is appended to the event name.

description A description of the device option. This description is appended to the eventdescription.

Use the following attributes in the event elements:

Mode Description

counter Every event element must have either the counter or event attribute defined.Use the counter attribute for fixed counter types, like cycle count. Use theevent attribute for all other events.

event Architecture specific or implementation-specific event number, in hexadecimal,determined from either the architecture specification document or the TechnicalReference Manual of the processor. This attribute is required if the element doesnot have a counter attribute.

option_set Defines the option_set to use.

title The title of the chart that Streamline displays. Counters with matching titlesstack in the charts.

name The name that Streamline displays after the title.

per_cpu Defines whether or not Streamline collects data on a per cpu basis. Set this valueto yes and Streamline collects data from each cpu separately for this event.

13 Advanced Customizations13.6 Category and event parameters for custom counters in events.xml


(continued)

Mode Description

supports_event_based_sampling Use yes or no to define whether or not the event can be used for event basedsampling. This value defaults to the category value if the attribute is not presentin the event.

class Use either delta, absolute, or activity as the value for the class attribute. Usedelta for values that increment or are accumulated over time such as hardwareperformance counters. Use absolute for singular or impulse values such assystem memory used. Use activity in conjunction with scheduler trace datasuch as CPU activity. The default value is delta. The class attribute is optional.

display Use one of the following values with the display attribute: average, maximum,minimum, hertz, or accumulate. This is the same as adding .avg, .max, .minor .hz to the counter name in the chart configuration Expression field ofStreamline. The default value is accumulate.

units Defines the unit type to display in Streamline.

modifier Gives the number to divide read numbers by for fixed point math. This attributeis optional.

derived Defines whether or not the data is derived from the data of another chart.

series_composition Defines how to arrange the data in the Timeline view. Enter either overlay,stacked, or logarithmic as the value for this attribute. This attribute is optionaland the default value is stacked.

rendering_type The type of chart to render for the Timeline view in Streamline. This attribute isoptional and can be set to either bar, fill, or line. The default value is fill.

average_selection Enter yes to have the values of the Cross Section Marker in the Timeline viewdisplay as average. Enter no to have them display as a total.

average_cores Sets whether or not Streamline averages the values of multiple cores whenviewing the aggregate data of a per-cpu chart. Enter yes or no as the value forthis attribute. The average_cores attribute is optional.

percentage Sets whether or not the Timeline view displays data as a percentage of themaximum value in the chart. Enter yes or no as the value for this attribute. Thepercentage attribute is optional.

description Use this attribute to define a description to show in Streamline. The value of thisattribute is used as the tooltip for the counter.

Related tasks13.3 Using the gator_events_mmapped.c custom counters example on page 13-179.13.4 Creating custom performance counters on page 13-180.

13 Advanced Customizations13.6 Category and event parameters for custom counters in events.xml


13.7 Getting L2C-310 memory-mapped peripherals working with StreamlineStreamline provides a file, gator_events_l2c-310.c, that you must make a small modification to andinclude in the build of gator, to get L2C-310 memory mapped peripherals working with Streamline.

Follow these steps to modify and add gator_events_l2c-310.c:

Procedure

1. Open the gator_events_l2c-310.c file located in the archive in .../gator/driver-src2. Find the gator_events_l2c310_probe function in gator_events_l2c-310.c3. Add the following #if statement to the existing #if statements in the gator_events_l2c310_probe

function:

#if defined(Your_Architecture) L2C_310_Address,#endif

Note

Replace Your_Architecture with the name of your architecture and L2C_310_Address with thephysical address of your L2C-310 in hexadecimal.

4. Rebuild the gator driver.5. Connect to your target.

Related tasks1.7 Building the gator module on page 1-23.

13 Advanced Customizations13.7 Getting L2C-310 memory-mapped peripherals working with Streamline


13.8 Profiling the Linux kernelIf you do not include the kernel in the images in the Capture & Analysis Options dialog box, thestatistics generated by the kernel are not aligned with source code in the Analysis Reports. Before youcan include the Linux kernel in the Program Images section of the Capture & Analysis Options dialog,you must build a version of vmlinux with kernel debug information enabled.

To profile the Linux kernel, follow these steps:

Procedure

1. Enter the following command to change a menu setting: make ARCH=arm CROSS_COMPILE=${CROSS_TOOLS}/bin/arm-linux-gnueabihf- menuconfig

2. In the Kernel Hacking menu, select the Compile the kernel with debug info option. This enablesCONFIG_DEBUG_INFO.

3. Enter the following command to build the image: make -j5 ARCH=arm CROSS_COMPILE=${CROSS_TOOLS}/bin/arm-linux-gnueabihf- uImageThis creates a new vmlinux image.

Note

You can profile drivers using this method. Statically link the driver into the kernel image or add themodule as an image in the Capture & Analysis Options dialog box.

4. Optional: Rebuild gator.ko.This step is only required if you previously built gator.ko with kernel stack unwinding turned off.To turn kernel stack unwinding on, remove the comment tags that surroundGATOR_KERNEL_STACK_UNWINDING in the Makefile and rebuild gator.ko. If you previously builtgator.ko with kernel stack unwinding turned on, you do not need to rebuild it.

Note

Enabling kernel stack unwinding might trigger errors that appear at millisecond intervals during thecapture session. If you experience this behavior, disable kernel stack unwinding.

5. Open the Streamline Data view if it is not already open. Select Window > Show View > Other... andchoose Streamline Data from the list of views.

6. Open the Capture & Analysis Options dialog box.7. Click the Add ELF image... button in the Program Images section.8. Navigate to your vmlinux file and select it.9. Click OK10. Start a new capture session.

Related tasks1.7 Building the gator module on page 1-23.

13 Advanced Customizations13.8 Profiling the Linux kernel


13.9 Re-analyzing Stored Streamline Capture DataAnalyzing an existing Capture creates new report data, replacing the report data that already exists in theCapture.

There are a number of reasons why you might want to do this, for example:

• You might want to change your Analysis options.• Your sources might not have been available when the data was captured.• A new version of Streamline might be incompatible with the existing report data.

To analyze a Streamline Capture:

Procedure

1. Open the Streamline Data view.2. Use the disclosure control to open up the details of a Capture, then click the Analyze button in the

lower right of the Capture.3. In the resulting dialog box, make the required changes to the settings.

Figure 13-2 The Analyze dialog box

Note

The options here are a subset of the options available in the Capture & Analysis Options dialog boxand they work the same way. Use the checkboxes of the Analysis section to toggle the HighResolution Timeline and Process Debug Information on and off. Use the Program Images sectionto add or remove any number of images, executables, and APK archives.

4. Click Analyze.

Related tasks13.1 Capturing data on your target on page 13-177.2.1 Opening the Streamline Data view on page 2-36.

13 Advanced Customizations13.9 Re-analyzing Stored Streamline Capture Data


Related references2.2 Streamline™ Data view toolbar options on page 2-37.3.2 Capture & Analysis Options dialog box settings on page 3-45.

13 Advanced Customizations13.9 Re-analyzing Stored Streamline Capture Data


13.10 Streamline™ preferencesIn the DS-5 preferences dialog box, there a few options available that enable you to change the look andbehavior of the Streamline views.

The following options are available under DS-5 > Streamline in the Eclipse Preferences dialog box:

Prompt before deleting Streamline data filesIf this option is enabled, Streamline always prompts you to confirm before deleting a capturefrom your file system. Disable to keep Streamline from prompting you whenever you delete afile.

Use highest quality graphicsDisable this option to reduce the graphics quality in the Timeline view and provide a slightboost to the performance of Streamline.

13 Advanced Customizations13.10 Streamline™ preferences


Chapter 14Troubleshooting Common Streamline™ Issues

These topics describe how to troubleshoot common Streamline issues.It contains the following sections:

• 14.1 Troubleshooting target connection issues on page 14-190.• 14.2 Troubleshooting report issues on page 14-191.


14.1 Troubleshooting target connection issuesEach of the error messages provided by Streamline on a connection failure indicates a different issue.Use the provided solutions to fix your these connection issues.

Use these solutions to solve common target connection issues:

Problem Solution

Error message generated: Unable to connect tothe gator daemon at your_target_address.Please verify you have installed the gatordaemon on your target and it is running.Installation instructions can be foundin: .../README_Streamline.txt

Make sure the gator daemon is running on your target. Enter thefollowing command in the shell of your target:

ps ax | grep gatord

If this command returns no results, gatord is not active. Start it bynavigating to the directory that contains gatord and entering thefollowing command:

sudo ./gatord &

Try connecting to the target again.

If gatord is active and you still receive this error message, trydisabling any firewalls on your host machine that might beinterfering with communication between it and the target.

Error message generated: Unknown host Make sure that you have correctly entered the name or IP addressof the target in Address field. If you have entered a name, try an IPaddress instead.

Error message generated: Unable to launch.Only one instance of Streamline may berunning on this machine. Please close allinstances of Eclipse and try again.

Stop any other running Streamline session and try connecting tothe target again. If you cannot find another session, try closingEclipse for DS-5, then re-starting it.

When using event-based sampling, Streamline failsto find the PMU.

The PMU on your hardware might not be correctly configured toallow the processor interrupts necessary for Streamline to useevent-based sampling. Test on alternate hardware or disable event-based sampling in the Counter Configuration dialog box.

Related tasks1.10 Starting a capture session on page 1-28.

Related references3.2 Capture & Analysis Options dialog box settings on page 3-45.14.2 Troubleshooting report issues on page 14-191.

14 Troubleshooting Common Streamline™ Issues14.1 Troubleshooting target connection issues


14.2 Troubleshooting report issuesIf you successfully complete a capture session but have a problem with the resulting report data, consultthis list of common issues.

Each common problem is listed with a possible solution:

Problem Solution

Streamline does not show any source code in theCode view.

Make sure that you use the -g option during compilation. Streamlinemust have debug symbols turned on to match instructions to sourcecode.

Streamline does not show source code for sharedlibraries.

Add the libraries using the Capture & Analysis Options dialogbox. Click Add ELF Image... in the Program Images section,navigate to your shared library, and then add it.

The data in the Call Paths view is flat. Thepresented table is a list rather than a hierarchy.

Use the -fno-omit-frame-pointer and -marm options duringcompilation and check the Call Stack Unwinding option in theCapture & Analysis Options dialog box.

Note

Streamline does not walk the stack for kernels, loadable kernelmodules, or statically linked drivers. These generate flat data in thecall paths view.

Functions that you know are highly used aremissing from the reports. Other functions mightseem artificially large.

This can be because of code inlining done by the compiler. To turninlining off, add -fno-inline as an option during compilation.

A newly-generated capture has no data. If you experience this and the profiling session had event-basedsampling enabled, the PMU on your target might not have triggeredthe interrupts correctly. Test on alternate hardware or disable event-based sampling in the Counter configuration dialog box.

Related references14.1 Troubleshooting target connection issues on page 14-190.7.5 Call Paths view column headers on page 7-125.3.2 Capture & Analysis Options dialog box settings on page 3-45.

14 Troubleshooting Common Streamline™ Issues14.2 Troubleshooting report issues


Chapter 15Using Streamline™ on the Command Line

Much of the functionality of Streamline is available on the command line using the streamlinecommand. You can initiate capture sessions, produce Analysis Reports from existing Captures, andoutput report data, all without opening the user interface.It contains the following sections:

• 15.1 Opening a Streamline™-enabled command prompt or shell on page 15-193.• 15.2 Streamline™ command-line options on page 15-194.• 15.3 Outputting command line data to a file on page 15-197.


15.1 Opening a Streamline™-enabled command prompt or shellUsing Streamline outside of the user interface enables you to perform automated captures and generatetext-based reports that you can export into your favorite spreadsheet application. To do so, you mustopen a Streamline-enabled command prompt or shell.

To open a Streamline-enabled command prompt, follow these steps:

Procedure

The method to open a shell is dependent on your operating system:

• On Windows, select Start > All Programs > ARM DS-5 > DS-5 Command Prompt.• On Linux, add the .../bin location to your PATH environment variable then open a UNIX bash

shell.

Related tasks15.3 Outputting command line data to a file on page 15-197.

Related references15.2 Streamline™ command-line options on page 15-194.

15 Using Streamline™ on the Command Line15.1 Opening a Streamline™-enabled command prompt or shell


15.2 Streamline™ command-line optionsThe streamline command has different modes that enable you to use most features of Streamlineoutside of the DS-5 for Eclipse user interface.

Streamline™ command-line modes

The streamline command is called in a Streamline-enabled shell using the following syntax:

streamline <mode> [options] <file...>

Use any of the following modes directly after streamline on the command line:

Mode Description

-capture This mode initiates a capture session. You must enter a valid session.xml filewith the capture mode declaration. The session.xml file defines your targethardware and the parameters of the capture session. For example:

streamline -capture session.xml

To create a session.xml file, enter your settings and then use the Export...option in the Capture & Analysis Options dialog box within DS-5 forEclipse.

-report This mode reads data from a capture and outputs it your console. You can useoptions to define how that data appears in the console or define an output fileto store the data to disk. You must enter a valid .apc file after the declaration ofreport mode. For example:

streamline -report threads_001.apc

Figure 15-1 A functions report generated using report mode

Options common to every mode

Enter any option between the mode and file. The following options are available in any mode:

15 Using Streamline™ on the Command Line15.2 Streamline™ command-line options


Mode Description

-h, -?, -help Outputs help information to the console, listing each mode and option as wellas the required syntax.

-v, -version Displays the program version information.

-o, -output, <output> In capture mode, defines the name of the capture file.

Capture mode option

The following option is available only in capture mode:

Mode Description

-duration <seconds> Use the duration option with capture mode to set a maximum length for thecapture session. Enter the option with a the number of seconds that you wantthe capture to last. The capture automatically terminates when it reaches thatlength. For example, the following command triggers a 60 second capturesession:

streamline -capture -duration 60 session.xml

Report mode options

The following options are unique to report mode:

Mode Description

-all Outputs the contents of the Timeline, Call Paths, Functions, Stack, and Logviews. This is the default option.

-callpath Outputs the contents of the table data of the Call Paths view. Subordinatefunctions are indented.

-function Outputs the contents of the Functions view.

-stack Outputs the contents of the Stack view.

-log Outputs the contents of the Log view.

-timeline Outputs the contents of the Timeline view.

-opencl Outputs the contents of the OpenCL table.

Note

To export OpenCL data, the report must contain OpenCL annotations.

-bookmarks Outputs all bookmarks stored in a capture, listing the time index location ofthe bookmark and its text.

-template Use this option with the location of a valid chart configuration file to list yourcustomized charts on the command line. Use the Export snippetconfiguration to a file button in the Snippet menu of the Timeline view tocreate a valid configuration, then use that file with the -template option.

-per_cluster When used with the -timeline option, this option forces Streamline to outputper-cluster data. By default, it outputs aggregated data.

-per_core Outputs per-core data when used with the -timeline option.

-start <seconds> Filters output data to start at the specified time within the timeline. Forexample if you enter 0.005 with the start option, all data before the 5millisecond mark is not included in the output.



(continued)

Mode Description

-stop <seconds> Filters output data to stop at the specified time within the timeline.

-bstart <name> Filter the data to start at the first bookmark with the provided name. Forexample, if you enter -bstart redflag, all data before the first the firstinstance of the bookmark title redflag is filtered from the output.

-bstop <seconds> Filter the data to end at the first bookmark with the provided name.

-format <space|tab|csv> Use this option to specify the format of the output. Format the tables usingspaces, tabs or comma-separated values. This can be useful if you want toeasily convert output text files to your favorite spreadsheet program. Thedefault format is spaces, making the tables easy to read when printed on thecommand line.

You can define multiple reports types using these options. For example, enter streamline -report -callpath -function thread_001.apc to output only the Call Paths and Functions data from thethread_001.apc capture.

Related tasks15.1 Opening a Streamline™-enabled command prompt or shell on page 15-193.15.3 Outputting command line data to a file on page 15-197.



15.3 Outputting command line data to a fileBecause the reports generated by Streamline can be very large, it can be useful to output the data to anoutput file. You can then import data from this .txt file to your favorite spreadsheet application.

You can add an output file to the streamline command to send the large quantities of data to a .txt file.

Procedure

Add > output.txt to the end of a valid streamline command. For example: streamline -report-timeline capture_001.apc > output.txt

This creates a file with the given name, if it does not already exist, and outputs the data to the new fileinstead of the command window.

15 Using Streamline™ on the Command Line15.3 Outputting command line data to a file


Figure 15-2 The Timeline view in a text file

Related tasks15.1 Opening a Streamline™-enabled command prompt or shell on page 15-193.

Related references15.2 Streamline™ command-line options on page 15-194.

15 Using Streamline™ on the Command Line15.3 Outputting command line data to a file


ARM® DS-5 Using ARM Streamlineinfocenter.arm.com/.../DUI0482Q_using_arm_streamline.pdf ·...

Documents

Transcript of ARM® DS-5 Using ARM Streamlineinfocenter.arm.com/.../DUI0482Q_using_arm_streamline.pdf ·...