You copied the Doc URL to your clipboard.

Adding images to reports using Visual Annotate

In addition to simple text overlays using Annotate, Streamline supports the annotation of images, providing further application-level context to the Timeline view.

Figure 50. Visual Annotation in the Timeline view

Visual Annotation in the Timeline view

Just like textual annotation, the application writes to /dev/gator/annotate virtual file using standard c-library functions. The gator driver outputs this data with a timestamp to Streamline and integrates it with the trace and sample report.

The mechanics of instrumenting your source code to provide visual annotation is similar to the process of adding standard annotation. For more information on text-only annotation, see Customize reports using Annotate.

To include images in the data sent to the host during a capture session, use the ANNOTATE_VISUAL macro in your source code instead of the ANNOTATE and ANNOTATE_COLOR macros used in standard annotation. ANNOTATE_VISUAL provides a parameter for image data.

Note

You can locate all of the files provided by DS-5 by selecting Help → ARM Extras... from the main menu.

To use visual annotation, you must:

  1. Include the streamline_annotate.h header file located in .../gator/annotate/ in your source code using the following line of code:

    #include "streamline_annotate.h"

    Note

    You can customize the example streamline_annotate.h file provided by DS-5 or create your own. Use it as a template if you want to create your own customized annotate functions.

  2. You must call the following before using the ANNOTATE_VISUAL macro:

    ANNOTATE_DEFINE;

  3. 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, and str with a descriptive string to be included with the image. Including a string is optional.

Figure 51. Visual annotation with optional text

Visual annotation with optional text

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 system performance. Increasing the amount of data sent to the host in this way increases the probe effect for the applications you are profiling

For an example of how to use Visual Annotate, see the annotate.c example source file, located in .../gator/annotate/example/.

Note

To annotate from within the kernel or a module, use the annotate_kernel.h file instead of streamline_annotate.h. The annotate statements in annotate_kernel.h duplicate the functionality of the standard annotate statements defined in streamline_annotate.h, but they are titled differently. Kernel annotate statements all have the KERNEL_ prefix. For example, to annotate your kernel module code to add images to report data, include annotate_kernel.h and add the KERNEL_ANNOTATE_VISUAL(data, length, string) statement to your code.

You can see the effects of visual annotation in the Timeline and Log views of your Streamline Analysis Reports. With visual annotation, the Timeline view data includes a chart that contains the annotated images. For more information about how visual annotation changes the Timeline view and how to interact with it, see Timeline view charts.

Any annotation event that includes an image has an icon in the message field of the Log view. Hover over the icon to see the image.

Was this page helpful? Yes No