From 9978cc8481a64f0f2ae2802ab84896c02f67f680 Mon Sep 17 00:00:00 2001
From: Juri Lelli <juri.lelli@arm.com>
Date: Fri, 14 Jul 2017 15:52:35 +0200
Subject: [PATCH] tutorial: add info about bref event

Add information in the tutorial and an example about how bref event can
be used to measure end-to-end latency of pipelines of tasks.

Signed-off-by: Juri Lelli <juri.lelli@arm.com>
---
 doc/examples/tutorial/example9.json | 59 +++++++++++++++++++++++++++++
 doc/tutorial.txt                    | 25 +++++++-----
 2 files changed, 75 insertions(+), 9 deletions(-)
 create mode 100644 doc/examples/tutorial/example9.json

diff --git a/doc/examples/tutorial/example9.json b/doc/examples/tutorial/example9.json
new file mode 100644
index 00000000..e020a375
--- /dev/null
+++ b/doc/examples/tutorial/example9.json
@@ -0,0 +1,59 @@
+{
+	/*
+	 * Latency associated with a pipeline of tasks.
+	 * Task tick start the pipeline every 24ms.
+	 * Task task1 gets a time reference (bref) and wakes task2 up (after
+	 * executing for a while). task2 wakes task3 up.
+	 * Eitherr task1 or task3 (extremes of the pipeline), depending on
+	 * who arrives last, will use bref to compute end-to-end latency
+	 * (pipe_latency) in the log.
+	 */
+	"tasks" : {
+		"tick" : {
+			"loop" : -1,
+			"cpus" : [0],
+			"phases" : {
+				"p1" : {
+					"loop" : 1,
+					"resume" : "task1",
+					"timer" :  { "ref" : "tick", "period": 6000 }
+				},
+				"p2" : {
+					"loop" : 3,
+					"timer" :  { "ref" : "tick", "period": 6000 }
+				}
+			}
+		},
+		"task1" : {
+			"loop" : -1,
+			"bref" : "pipeline",
+			"run1" : 300,
+			"resume" : "task2",
+			"run2" : 4000,
+			"barrier" : "pipeline",
+			"suspend" : "task1"
+		},
+		"task2" : {
+			"loop" : -1,
+			"suspend" : "task2",
+			"run" :  1000,
+			"resume" : "task3"
+		},
+		"task3" : {
+			"loop" : -1,
+			"suspend" : "task3",
+			"run" :  1000,
+			"barrier" : "pipeline"
+		}
+	},
+	"global" : {
+		"default_policy" : "SCHED_OTHER",
+		"duration" : 6,
+		"ftrace" : true,
+		"gnuplot" : false,
+		"lock_pages" : false,
+		"logdir" : "./",
+		"log_basename" : "example9",
+		"calibration" : "CPU0"
+	}
+}
diff --git a/doc/tutorial.txt b/doc/tutorial.txt
index 5a612133..827c6a0b 100644
--- a/doc/tutorial.txt
+++ b/doc/tutorial.txt
@@ -521,6 +521,12 @@ generates the following sequence:
     "unlock" : "SyncPointA" (internal mutex)
 }
 
+* bref : String. Time reference for a pipeline of tasks. It has to match a
+barrier (see above). The task at the beginning of the pipeline calls this
+event to get such a reference; the last task at the other end of the pipeline
+(the one that broadcasts and wakes everybody else up) will compute the delta.
+See doc/examples/tutorial/example9.json for more information.
+
 * suspend : String. Block the calling thread until another thread wakes it up
 with resume. The String can be let empty as it will be filled by workgen with
 the right thread's name before starting the use case.
@@ -626,19 +632,20 @@ metrics are:
 - c_duration: sum of the configured duration of run/runtime events
 - c_period: sum of the timer(s) period(s)
 - wu_lat: sum of wakeup latencies after timer events
+- pipe_lat: end-to-end latency of a pipeline of tasks (0 if no pipeline exists)
 
 Below is an extract of a log:
 
 # Policy : SCHED_OTHER priority : 0
-#idx     perf      run   period           start             end          rel_st      slack c_duration   c_period     wu_lat
-   0    92164    19935    98965    504549567051    504549666016            2443      78701      20000     100000        266
-   0    92164    19408    99952    504549666063    504549766015          101455      80217      20000     100000        265
-   0    92164    19428    99952    504549766062    504549866014          201454      80199      20000     100000        264
-   0    92164    19438    99955    504549866060    504549966015          301452      80190      20000     100000        265
-   0    92164    19446    99952    504549966061    504550066013          401453      80093      20000     100000        264
-   0    92164    19415    99953    504550066060    504550166013          501452      80215      20000     100000        263
-   0    92164    19388    99954    504550166059    504550266013          601451      80242      20000     100000        264
-   0    92164    19444    99956    504550266060    504550366015          701452      80185      20000     100000        265
+#idx     perf      run   period           start             end          rel_st      slack c_duration   c_period     wu_lat   pipe_lat
+   0    92164    19935    98965    504549567051    504549666016            2443      78701      20000     100000        266          0
+   0    92164    19408    99952    504549666063    504549766015          101455      80217      20000     100000        265          0
+   0    92164    19428    99952    504549766062    504549866014          201454      80199      20000     100000        264          0
+   0    92164    19438    99955    504549866060    504549966015          301452      80190      20000     100000        265          0
+   0    92164    19446    99952    504549966061    504550066013          401453      80093      20000     100000        264          0
+   0    92164    19415    99953    504550066060    504550166013          501452      80215      20000     100000        263          0
+   0    92164    19388    99954    504550166059    504550266013          601451      80242      20000     100000        264          0
+   0    92164    19444    99956    504550266060    504550366015          701452      80185      20000     100000        265          0
 
 Some gnuplot files are also created to generate charts based on the log files 
 for each thread and for each kind of metrics. The format of the chart that