Added basic usage information for Tracing framework

diff --git a/doc/008-tracing/Tracing.tex b/doc/008-tracing/Tracing.tex
index 9aba762..f90ffd1 100644 (file)
--- a/doc/008-tracing/Tracing.tex
+++ b/doc/008-tracing/Tracing.tex
@@ -4,7 +4,7 @@
 %
 % This file is distributed under the terms in the attached LICENSE file.
 % If you do not find this file, copies can be found by writing to:
-% ETH Zurich D-INFK, Haldeneggsteig 4, CH-8092 Zurich. Attn: Systems Group.
+% ETH Zurich D-INFK, Universitaetstr. 6, CH-8092 Zurich. Attn: Systems Group.
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \documentclass[a4paper,11pt,twoside]{report}
@@ -15,6 +15,13 @@
 \usepackage{pifont}
 \usepackage{textcomp}
 \usepackage{amsmath}
+\usepackage{hyperref}
+
+% Disable ugly boxes
+\hypersetup{
+    colorlinks=false,
+    pdfborder={0 0 0},
+}
 
 % Include the listings-package
 \usepackage{listings}
@@ -22,8 +29,8 @@
        basicstyle=\footnotesize\ttfamily,
        framexbottommargin=4pt,
        frame=single,
-       basicstyle=\footnotesize, 
-       captionpos=b
+       captionpos=b,
+        language=c
 }
 
 \usepackage{float}
@@ -682,6 +689,52 @@ part of the trace log data, that is interesting to you.
        \label{fig:aquarium-filters}
 \end{figure}
 
+\chapter{Usage}
+
+This chapter describes how to use the Tracing framework in Barrelfish.
+
+\begin{itemize}
+\item Add trace events to \lstinline{trace_definitions/trace_defs.pleco}
+\item Enable tracing in \lstinline{hake/Config.hs}
+\item Add \lstinline{addLibraries = [ ``trace'' ],} to your Hakefile
+\item Modify the source code of your programs as described in
+  Listing~\ref{lst:app_example}
+\item Download and compile Aquarium2 as described in the README as
+  part of the source code
+\end{itemize}
+
+\begin{code}
+\begin{lstlisting}[frame=single, caption={Enable tracing for an application}, label={lst:app_example}]
+#include <trace/trace.h>
+
+int main(..) {
+
+  // initialize the trace framework
+  trace_reset_all();
+  trace_prepare(..); // do clock synchronization
+
+  // tell the framework when to start recording
+  err = trace_control(TRACE_EVENT_XXX_AAA, TRACE_EVENT_XXX_BBB, _duration);
+
+  // enable the subsystems that should be traced
+  trace_set_subsys_enabled(TRACE_SUBSYS_XXX, true);
+  // or activate for all:
+  trace_set_all_subsys_enabled(true);
+
+  // fire the event that triggers start of recording
+  trace_event(TRACE_SUBSYS_XXX, TRACE_EVENT_XXX_AAA, _payload);
+
+  execute_something_useful();
+  
+  // fire the event that triggers end of recording
+  trace_event(TRACE_SUBSYS_XXX, TRACE_EVENT_XXX_BBB, _payload);
+
+  // Flush the buffer
+  trace_flush(MKCLOSURE(..));
+}  
+\end{lstlisting}
+\end{code}
+
 \chapter{Performance Analysis}
 
 \section{Introduction}