You copied the Doc URL to your clipboard.

Annotate overview

While ARM Streamline provides a large variety of target information, sometimes you might require extra context. Streamline Annotate lets you instrument your source code by adding annotations to it.

When the user space application writes to the gator annotate socket, the gator driver integrates the recorded annotate-driven output into the Streamline sample and trace capture report. The annotated text is marked with a thread identifier, which keeps the data uncluttered and eliminates the need for user mutexes.

You can add the following types of annotations:

String

String annotations work in a similar way to printf() statements, but instead of console output, they populate the Log view and place framing overlays directly in the Streamline Timeline view. Specify the string content using ANNOTATE(), ANNOTATE_COLOR(), ANNOTATE_CHANNEL(), or ANNOTATE_CHANNEL_COLOR() macros.

Visual

Visual annotations add images to the visual annotation chart in the Timeline view. The images are also displayed in the Log view. Specify the image data using the ANNOTATE_VISUAL() macro.

Marker

Marker annotations add bookmarks to the Timeline view, optionally with a title, to identify time points of interest. Specify markers using the ANNOTATE_MARKER() and related macros.

Custom counters

These are counters that you dynamically define in user space code. After you have run a capture session, the Timeline view displays a chart for each custom counter you have created, showing the numeric values plotted over time. Specify custom counters using the ANNOTATE_DELTA_COUNTER() or ANNOTATE_ABSOLUTE_COUNTER() macros. Assign a unique identifier to each counter and specify a chart title and a series name for the data. Assign delta or absolute values using the ANNOTATE_COUNTER_VALUE() macro.

Groups and channels

This set of macros enables you to break down threads into multiple channels of activity and assign each channel to a group. Identify each group and channel by a number and give it a name for display in the Timeline and Log views. Groups and channels are defined per thread, so although each channel number must be unique within the thread, channels in different threads can have the same number.

The ANNOTATE_NAME_GROUP() macro defines a group and ANNOTATE_NAME_CHANNEL() defines a channel and assigns it to a group. Specify the beginning of a channel using ANNOTATE_CHANNEL() or ANNOTATE_CHANNEL_COLOR() and the end of the channel using ANNOTATE_CHANNEL_END().

Custom activity maps

Allow you to define and visualize a complex dependency chain of jobs. Define a custom activity map (CAM) view using CAM_VIEW_NAME(), then add tracks to it using CAM_TRACK(). Add jobs without any dependencies on other jobs to a track using CAM_JOB(), or jobs with a single dependency using CAM_JOB_DEP(), or jobs with multiple dependencies using CAM_JOB_DEPS(). The following screenshot shows some CAM views, tracks, and jobs:

Figure 9-1 Custom Activity Maps

Custom Activity Maps

The annotation macros are defined in streamline_annotate.h. StreamlineAnnotate.java provides equivalent methods for string, visual, and marker annotations, and for groups and channels.

Example code for string, visual, and marker annotations, and groups and channels is provided in the Streamline_annotate example. This is a simple Linux application written in C, located in <DS-5_install_directory>/examples/Linux_examples.zip. To use the example, import the Linux application example projects into DS-5 Eclipse and refer to readme.html for more details.

Example code for custom counters and Custom Activity Map annotations is provided in delta.c, absolute.c, and cam.c, located in the <DS-5_install_directory>/arm/gator/example/ directory.

Note

In DS-5 version 5.20 and later, applications that use user space gator, in addition to those that use kernel space gator, can emit annotations. Applications built using the annotation implementation in earlier versions of DS-5 will continue to work in version 5.20 and later, but only with kernel space gator. If they use user space gator, you must re-build them using the new annotation implementation.

Related reference