Customize reports using Annotate

While ARM Streamline provides a large variety of target information, sometimes you require extra context to decipher exactly what the target is doing at certain instances. 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 Timeline view:

Figure 63. Annotate overlays

Annotate overlays

When the user space application writes to the /dev/gator/annotate file, the gator driver marks the recorded annotate-driven output with a timestamp and integrates the recorded data into the Streamline sample and trace capture report.

The annotated text is marked with a thread identifier that keeps the data uncluttered and eliminates the necessity 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 fprintf. To start using the annotate feature, do the following:

  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.

  5. Write null-terminated strings to the file from any thread using the ANNOTATE macro:

    ANNOTATE(string)
    
  6. Optionally set the color of the annotation using the ANNOTATE_COLOR macro and by either choosing a color constant from those defined in streamline_annotate.h or by sending the ASCII escape code followed by a 3-byte RGB value:

    ANNOTATE_COLOR(color, string)
    
  7. Write an empty string to clear the annotation message for the thread

Unless you are running out of file handles, closing the annotate file on completion is optional.

Note

You can locate all of the files provided by DS-5 by selecting Help → ARM Extras... from the main menu. See the streamline_annotate.h located here for a better understanding of how to call each annotate macro.

Show/hideSee also

Copyright © 2010-2012 ARM. All rights reserved.ARM DUI 0482J
Non-ConfidentialID100912