Add annotations to your code

You can add annotation macros to your code to add various types of visual indicators to your application analysis report, or to break down threads of activity into custom groups and channels.

About this task

Annotations are a useful way to add application-aware semantic information about application execution, which might otherwise not be visible to the profiler.

Note

The CPU overhead of emitting annotations is relatively expensive. Arm recommends that you emit fewer than 10000 annotations per second.

Annotations can be seen in the Timeline and Log views in your analysis report.

Before you begin

Do one of the following:

  • Include the files streamline_annotate.h, streamline_annotate.c, and streamline_annotate_logging.h in your project.

  • Build a libstreamline_annotate library with the Makefile in <install_directory>/sw/streamline/gator/annotate, and include this library in your project.

Procedure

  1. Add the ANNOTATE_SETUP macro to your code.

    This macro must be called before any other annotate macros are called.

  2. Add annotations to your code using the macros defined in streamline_annotate.h. For a list of supported annotations, see Annotate your code.

  3. Build your code.

  4. Ensure gatord is running and run your application. Execute the area of the code that emits the annotations.

Results

These annotations appear in the Timeline view and the Log view.

For a more information about what to expect in each of the Timeline and Log views, see the information per annotation type in View annotations.

Example: Adding annotations to your code

The following examples demonstrate how to use string, visual, or channel and group annotations to your code.

  • Example 1: Add a string annotation to your code

    String annotations write user-defined strings into the Log view and place framing overlays in the details panel in the Timeline view.

    This example uses the ANNOTATE_COLOR string annotation macro to add a colored annotation with a textual string.

    1. Add the ANNOTATE_SETUP macro to your code.

    2. To add a purple annotation with the string "render", use the ANNOTATE_COLOR(ANNOTATE_PURPLE, "render") annotation macro.

      Note

      ANNOTATE_COLOR(color, string) supports color constants that are defined in streamline_annotate.h or ASCII escape codes followed by a 3-byte RGB value.

    3. Use ANNOTATE_END() to clear the annotation message for the thread.

    4. Build your code.

    5. Ensure gatord is running and run your application. Exercise the area of the code that emits the ANNOTATE_COLOR annotation.

    String annotations are displayed as text overlays inside the relevant channels in the details panel of the Timeline view, see inside Channel 0 in the following screenshot:

    String annotation overlays.

    The letter A displays in the process list to indicate the presence of annotations. String annotations are also displayed in the Message column in the Log view.

  • Example 2: Add a visual annotation to your code

    You can add images to the Timeline view and the Log view in your analysis report by adding macros to your code.

    This example records an annotation that includes an image. the example uses the ANNOTATE_VISUAL visual annotation.

    1. Add the ANNOTATE_SETUP macro to your code.

    2. To insert the 'image1' image with the string "My image 1" as a visual annotation to your code, use ANNOTATE_VISUAL(image1, sizeof(image1), "My image 1").

      Where:

      • image1 is the data (your image)

      • sizeof(image1) is the size of the image1 being written to the annotate file

      • My image 1 is an optional descriptive string to be included with image1

    3. Build your code.

    4. Ensure gatord is running and run your application. Exercise the area of the code that emits the annotations.

    The Timeline view now includes a chart that displays 'image1'. In the Log view, any annotation event that includes an image has a camera icon camera in the message field. To see the image, select the row containing the camera icon.

  • Example 3: Add a group or channel annotation to your code

    Group and channel macros enable you to break down threads into multiple channels of activity and assign each channel to a group. A number identifies each group and channel, and each group and channel has a name for display in the Timeline view and the Log view.

    This example uses the ANNOTATE_NAME_GROUP annotation to name a group, and uses the ANNOTATE_NAME_CHANNEL to name a channel and link it to a group.

    1. Add the ANNOTATE_SETUP macro to your code.

    2. To name group '1' as "DEBUG", insert ANNOTATE_NAME_GROUP(1, "DEBUG") macro into your code.

      Note

      Groups can be named after use.

    3. Use ANNOTATE_END() to clear the annotation message for the group.

    4. To name channel '1' as "DisplayImage", and link it to the "DEBUG" group insert the ANNOTATE_NAME_CHANNEL(1, 1, "DisplayImage") macro into your code.

      Note

      • Channels can be named after use

      • A channel can belong to only one group per thread. In other words, channel 1 cannot be part of both group 1 and group 2 on the same thread

    5. Use ANNOTATE_CHANNEL_END(1) to clear the annotation message for the thread.

    6. Build your code.

    7. Ensure gatord is running and run your application. Exercise the area of the code that emits the annotations.

    Timeline view and the Log view show the "DisplayImage" channel, assigned to the "DEBUG" group.