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:
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:
Ensure
gatordis running.gatordcreates the/dev/gator/annotatefile.Open
/dev/gator/annotatewith write permissionsWrite null-terminated strings to the file from any thread
Optionally set the color of the annotation by sending the ASCII escape code followed by a 3-byte RGB value
Disable buffering on the annotate file, or manually flush the file after each write
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.
For an example of how to use annotate, see the Streamline_annotate example in
the Bare-metal_examples.zip archive, located in .../examples/.
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 add
a color-coded annotate statement to your kernel module code, include annotate_kernel.h and
add the KERNEL_ANNOTATE_COLOR( statement
to your code.color, string)
See also
PDF version