Kernel annotations are for annotating kernel code or kernel modules, and allow you to profile any system calls. Streamline supports string, marker, and custom counter kernel annotations. For more information about how to use kernel annotations, see README.md and the annotation examples located in <install_directory>/sw/streamline/gator/trace/events:
example_standalone, where annotations are added in the same module
example_shared, where annotations are exported from a different module
Warning
gator_annotate.h and and gator_annotate.c are intended for use in a development environment. Arm does not recommend including these files in a released product without performing a security audit of the source code first.
Note
Arm® Development Studio has examples of annotations in <install_directory>/sw/streamline/examples/annotations/. See the readme file in the same directory for further information.
Use the following macros to send annotations to gatord from a kernel context, using Linux ftrace as the transport mechanism. They are defined in <install_directory>/sw/streamline/gator/trace/event/gator_annotate.h.
The following macros indicate that an event is associated with the whole kernel:
GATOR_KERNEL_WIDE_PIDFor bookmark and counter TRACE_EVENTS only. To indicate that the event is associqted with the whole kernel rather than a specific tid, you can pass this value as the tid. Annotation texts must have a tid of at least zero. tid == 0 is the idle process. This value can used only for bookmark and counter TRACE_EVENTS.
The following macros create and configure gator bookmark annotations:
GATOR_BOOKMARK(label)Add a bookmark with a label.
GATOR_BOOKMARK_COLOR(color, label)Add a bookmark with a color and a label.
The following macros start (START) and stop (STOP) kernel space function annotations:
Note
START and STOP macros enable you to call the same function but offer a distinction between when the text annotation is intended to be the start of a text annotation, or the end.
GATOR_TEXT_START(tid, channel, label)Start a text annotation.
GATOR_TEXT_START_COLOR(tid, color, channel, label)Start a text annotation with a color.
GATOR_TEXT_STOP(tid, channel)End a text annotation. This macro sends an empty string as the label, which Streamline recognizes as the end of a text annotation with the given channel and tid.
The following macros output counter values:
GATOR_DELTA_COUNTER_VALUE(title, name, units, value)Output delta counter values.
GATOR_ABSOLUTE_COUNTER_VALUE(title, name, units, value)Output absolute counter values.