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 44. 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:

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

The following code example shows how you can use the annotate function in a simple sum.c program. To use it, you need the example annotate.h header file located in DS-5 install directory/arm/gator/annotate/.

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

// 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
  ANNOTATE_SETUP;
  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;
}