You copied the Doc URL to your clipboard.

Customize reports using Annotate

While ARM Streamline provides a wealth 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 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:

  1. Ensure gatord is running. gatord creates the /dev/gator/annotate file.

  2. Open /dev/gator/annotate with write permissions

  3. Write null-terminated strings to the file from any thread

  4. Optionally set the color of the annotation by sending the ASCII escape code followed by a 3-byte RGB value

  5. Disable buffering on the annotate file, or manually flush the file after each write

  6. 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.

The following code examples show how you can build an annotate.h header file and use the annotate function in the simple sum.c program.

Code example: annotate.h

#ifndef _ANNOTATE_
#define _ANNOTATE_

#include <stdio.h>
extern FILE *annotate;
extern int color;

#define ANNOTATE_DEFINE FILE *annotate; int color;
#define ANNOTATE_SETUP { annotate = fopen("/dev/gator/annotate", "wb"); \
if (annotate) {setvbuf(annotate, (char *)NULL, _IONBF, 0); }}
#define ANNOTATE(...) { if (annotate) {fprintf(annotate, _VA_ARGS_); \
fputc('\0', annotate); }}
#define ANNOTATE_COLOR(setColor, ...) { if (annotate) {color = setColor; \
fwrite((char*)&color, 1, sizeof(color), annotate); \
fprintf(annotate, _VA_ARGS_); \
fputc('\0', annotate); }}

// ESC character, hex RGB (little endian)

int ANNOTATE_RED = 0x0000ff1b;
int ANNOTATE_BLUE = 0xff00001b;
int ANNOTATE_GREEN = 0x00ff001b;
int ANNOTATE_PURPLE = 0xff00ff1b;
int ANNOTATE_YELLOW = 0x00ffff1b;
int ANNOTATE_CYAN = 0xffff001b;

int ANNOTATE_WHITE = 0xffffff1b;
int ANNOTATE_LTGRAY = 0xbbbbbb1b;
int ANNOTATE_DKGRAY = 0x5555551b;
int ANNOTATE_BLACK = 0x0000001b;

#endif // _ANNOTATE_

Code example: sum.c

This simple sum.c program shows how annotate can be added to your code:

#include <stdlib.h>
#include "annotate.h"
// instantiated once per program

// caution: unintended stack use may cause a segfault
unsigned long long sum_recursive(int x) {
  if (x <= 0) return x;
  return x + sum_recursive(x - 1);

unsigned long long sum_loop(int x) {
  unsigned long long sum = 0;
  while (x > 0) sum += x--;
  return sum;

unsigned long long sum_fast(int x) {
  if (x <= 0) return x;
  return (((unsigned long long)x+1) * (unsigned long long)x >> 1);

int main(int argc, char** argv) {
  // called once per program
  if (argc != 2) {
    printf("usage: sum <num>\n");
    return 0;

  int value = atoi(argv[1]);
  ANNOTATE("Sum of Numbers (%d)", value);
  unsigned long long sum = sum_loop(value);
  ANNOTATE_COLOR(ANNOTATE_PURPLE, "Sum of Numbers Recursive");
  unsigned long long sumr = sum_recursive(value);
  ANNOTATE("Sum of Numbers Fast");
  unsigned long long sumf = sum_fast(value);
  ANNOTATE(""); // End annotation

  printf("sum = %lld, sumr = %lld, sumf = %lld\n", sum, sumr, sumf);
  return 0;
Was this page helpful? Yes No