Arm Streamlineを使った注釈(annotate)の方法

適用範囲：DS-5

Streamline Annotateとは
Streamline Annotate機能は、コード内のキーポイントに対し注釈を加えることができます。これはinstrumentationに類似していますが、Streamlineが全ての操作を行います。コンテキストと負荷についてコードに注釈を行い、Streamlineはこのテキストをtimelineビュー上に表示します。

どうやって機能しますか
ユーザスペースアプリケーションがdev/gator/annotateファイルに書き込むと、gatorドライバはタイムスタンプ付きで記録されたannotate-driven出力をマークし、記録データをStreamlineサンプルとトレースキャプチャレポートにまとめます。

注釈が行われたテキストはデータを整頓しておくためのスレッド識別子とともにマークされ、ログの追加を容易にし、ユーザmutexを不要にします。annotateファイルの書き込みは標準Cライブラリ関数によって扱われます。

試してみましょう
アプリケーションコードは仮想annotateファイルに対し、標準Cライブラリ関数を使ってアクセスします：fopen、fwriteおよびfprintf annotate機能を使うには、ターゲットに対し以下を行ってください：

1. /dev/gator/annotateファイルを生成する/gatordが実行していることを確認します
2. 書き込み属性付きで//dev/gator/annotateを開きます
3. なんらかのスレッドから、上記のファイルにnull止めの文字列を書き込みます
4. ASCIIのエスケープコードに続く3-byte RGB値を送ることで、annotationに色をつけることもできます
5. annotateファイルのバッファリングを無効にするか、手動で書き込みごとにファイルの内容を消します
6. 空白文字("")を書き込んでスレッドに対するannotationメッセージをクリアします

ファイルハンドルを使い果たしていなければ、オプションで完了時にannotateファイルをクローズすることもできます。

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('', annotate); }}
#define ANNOTATE_COLOR(setColor, ...) { if (annotate) {color = setColor; 
fwrite((char*)&color, 1, sizeof(color), annotate); 
fprintf(annotate, _VA_ARGS_); 
fputc('', 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_

Example: sum.c

#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 = %lldn", sum, sumr, sumf);
　  return 0;
}

概要
ARM Streamline AnnotateはStreamlineにアプリケーションコンテキストを追加する機能を提供します。アプリケーションからgatorドライバファイルに文字列を書くことで、ターゲットtimelineに対する負荷を可視化することができます。

ARM Streamlineがターゲット情報資源を提供している間、特定のインスタントにおいてターゲットが何をしているかを追加のコンテキストが正確に解明する必要があることがあります。

Streamline Annotate機能はprintfと同じように動作しますが、コンソール出力の変わりに、Streamline timelineビューのすぐ上にannotateステートメントはフレームを表示されます。