Streamline Annotations example

Purpose and scope

This document describes how to build, run and analyze the Streamline annotation example provided with Arm DS IDE.

This example illustrates the use of Streamline annotations by way of simple instrumented C code. Some different types of annotation - bookmark, text, visual, group and channel annotations - are shown.

This example is intended to be run and analyzed on an Arm Linux hardware target that supports Streamline, though it can also be run only (not analyzed) on a software model such as the FVP model.

The ready-made Streamline capture for this example can be viewed in Streamline using the Import Streamline Sample Captures wizard. To view the ready-made Streamline capture, first launch the Streamline application, then import the capture for this example by selecting , Import Streamline Sample Captures, then selecting from the list of sample captures. The capture is added to the Streamline Data view. Double-click on the capture to generate and view an Analysis Report.

Click on the Timeline tab to view the annotations generated by the example:

On Timeline (around 0.5s) appears a coloured bookmark with the text "End of splash image, start rendering bmp images". The example uses the macro ANNOTATE_MARKER_COLOR_STR(setColor, data) to create the bookmark with a title and a color.
Click on the (annotate) process to view the purple coloured text annotations ("render 0", "render 1", ...). The example uses the macro ANNOTATE_COLOR(setColor, data) to add simple text overlays.

This example also illustrates the use of group and channel annotations to track some of the functions. These use the ANNOTATE_NAME_GROUP, ANNOTATE_NAME_CHANNEL and ANNOTATE_CHANNEL_COLOR macros. Click on the Log tab to list every message generated by the ANNOTATE statements in the code along with information related to the message.

The master sources for the Streamline annotation C source and header files streamline_annotate.c/.h are provided in install_directory\sw\streamline\gator\annotate\.

Terminology

This document refers to 'host' and 'target' systems. The 'host' system is the Linux or Windows desktop computer that you use for most of your work. The 'target' system is some Arm-based hardware (or model of such hardware) on which the example Arm Linux distribution is running.

Hardware and software requirements

A host workstation (Linux or Windows) is required to build the example, communicate with the target, and run Arm DS IDE Debugger.
An Arm Linux hardware target, configured for Streamline (with gator driver and daemon).
A serial terminal emulator such as the Terminal view in Arm DS IDE, TeraTerm for Windows (TeraTerm Website) or minicom for Linux, connected via a serial cable to your platform. This may be needed when running the example on real target hardware, to monitor the Arm Linux boot process and provide a terminal interface to Arm Linux. This is not needed if using a software model as that provides its own terminal. To open the Terminal view in Arm DS IDE, select Window → Show View → Other... to open the Show View dialog box, then expand the Terminal group and select Terminal, and click OK. To configure the terminal settings, click on Settings in the Terminal view, then select the required connection type (for example, Serial), then enter the required settings (for example, 38400 baud, 8 bits, no parity, 1 stop bit) and click OK.
A secure copy program such as scp to allow files to be copied from host to target. Windows versions of this Linux command are available, such as pscp as provided with PuTTY. Alternatively, use Arm DS IDE Debugger Debug Configurations dialog or Remote System Explorer to transfer files from host to target.

Building this example

A pre-built executable is provided for aarch64 Linux systems.

Building on the command-line

To build on the command-line with the supplied make utility:

On Windows, open a Arm DS IDE Command Prompt from the Start menu, run the select_toolchain utility, and select GCC 4.8.3 [arm-linux-gnueabihf] from the list
On Linux, run the suite_exec utility with the --toolchain option to select the compiler and start a shell configured for the suite environment, for example: ~/Arm_ds/bin/suite_exec --toolchain "GCC 4.8.3 [arm-linux-gnueabihf]" bash

Then navigate to ...\Streamline_annotate then type:

make

The usual make rules: clean, all and rebuild are provided in the Makefile.

Building with Eclipse

In the Project Explorer view, select the project you want to build.
Select Project → Build Project.

The supplied Streamline_annotate Eclipse (makefile builder) project is used to build this example.

Running/Debugging the example on a hardware target

This example can be run and debugged on a hardware target by using the supplied Streamline_annotate-gdbserver debug configuration.

If you have not done so already, boot Arm Linux on your target and log-in as root.
Create a Linux/ssh Remote System Explorer connection for your target
Select Run → Debug Configurations..., then selecting the Streamline_annotate-gdbserver under the Arm DS IDE Debugger configuration type, and press Debug. This is pre-configured to download the stripped annotate executable to the target, start gdbserver on the target, load the debug information from the debug/unstripped version of the image into Arm DS IDE Debugger, then start executing annotate, stopping at main().

Loading the example onto the hardware target manually

Instead of using the supplied Streamline_annotate-gdbserver debug configuration, the example stripped executable annotate can be manually downloaded onto the target, before the example can be run/debugged. To load this file onto the target, you can either:

use Run → Debug Configurations... - see Configuring a connection to a Linux application using gdbserver in Arm DS IDE Debugger User Guide for more information on how to load the image
use Remote System Explorer to drag and drop this file from the host to target file system, then set execute permissions on the copied executable on the target with Remote System Explorer's Properties → Permissions option
perform the manual copy steps as follows:
1. On the target, obtain the IP address of the target with:
  
  ifconfig
  
  to give, for example, 10.1.204.172
2. To load the example onto the target, navigate to the ...\Streamline_annotate\stripped directory, then copy the generated stripped files from the host to your home directory on the target.
  
  If logged-in as root, copy to a writable directory in its home directory with, for example, these commands on a Linux host:
  
  scp annotate root@10.1.204.172:/writeable
  
  Windows users might need to use pscp from PuTTY instead of scp.
3. Set execute permissions on the copied executable on the target with chmod +x annotate on the target console

Running the example manually

Instead of using the supplied Streamline_annotate-gdbserver debug configuration, annotate can be run directly from the target's command-line.

First, navigate to the directory on the target where annotate is located, then execute the following command on the target:

./annotate

Preparing to debug the example with gdbserver manually

Instead of using the supplied Streamline_annotate-gdbserver debug configurations, you can prepare to debug annotate with gdbserver manually.

First, navigate to the directory on the target where annotate is located, then execute the following command on the target:

gdbserver :5000 ./annotate &

Connect from Arm DS IDE Debugger to gdbserver, as described in Configuring a connection to a Linux application using gdbserver in Arm DS IDE Debugger User Guide.

Capturing data and annotations

Assuming the stripped annotation executable has already been loaded to the target, it can now be analyzed with Streamline.

First prepare the Streamline capture configuration in the Streamline Data view: Click on Capture & analysis options and enter a name for the capture session. In the Address field, enter the host name or IP address of the target. Select an Output path to where to save the data. Add the name of the program image to capture - for this example, Streamline must load the debug information from the debug/unstripped version of the image at ${workspace_loc}\Streamline_annotate\annotate. Click Save to return to Streamline Data.
Press Start capture. If the capture configuration is correct, a new analysis file appears in the Streamline Data, with a Stop button within it.
Start the example from the command line with: ./annotate.
After the example finishes, press Stop in Streamline Data. The collected data is then processed for viewing.
When the analysis completes, Streamline automatically opens the Analysis Report. To analyze the captured data again with other settings, click on the Options gear-wheel icon on the right-hand side of the Streamline_annotate Capture Data.

For more information, see Streamline User Guide.

Known issues and troubleshooting

The Linux target will report: # Cannot exec ./annotate: Permission denied.

if you have not set execute permissions on the application. Use, for example, chmod +x annotate.
The Linux target will report: Connection Failed: Failed to delete file /writable/(app): Permission denied.

if you don't have permissions to write in the root folder. Modify your Debug Configuration, and set, in Files Tab, a writeable folder in Target download directory:.
Breakpoints are not being hit in an application or shared library:

Ensure the application and any shared libraries on your target match the ones on the host. The code/data layout must be identical, though the application/shared library on your target does not need to contain debug symbols, i.e. these can be stripped to reduce image size. Try copying the application/shared library across from host to target again.

Streamline Annotations example - Arm Development Suite