[PATCH 0/2] tracing: Expand ftrace documentation

[PATCH 0/2] tracing: Expand ftrace documentation

[Carsten Emde]

The meaning of the tracing_max_latency variable
was not entirely clear from the documentation.
The variable trace_clock was not explained in
the documentation.

[PATCH 1/2] add-tracing_max_latency-may-not-be-worst-case-system-latency-to-ftrace-docs.patch

[Carsten Emde]

[-- Attachment #1: add-tracing_max_latency-may-not-be-worst-case-system-latency-to-ftrace-docs.patch --]
[-- Type: text/plain, Size: 1739 bytes --]

Explain the background of the trace variable
tracing_max_latency in the context of the
wakeup and the wakeup_rt tracer and why it
does not necessarily measure the worst-case
latency of the system.

Signed-off-by: Carsten Emde <C.Emde@osadl.org>

Index: linux-2.6.33-rc2/Documentation/trace/ftrace.txt
===================================================================
--- linux-2.6.33-rc2.orig/Documentation/trace/ftrace.txt
+++ linux-2.6.33-rc2/Documentation/trace/ftrace.txt
@@ -117,9 +117,25 @@ of ftrace. Here is a list of some of the
 	For example, the time interrupts are disabled.
 	This time is saved in this file. The max trace
 	will also be stored, and displayed by "trace".
-	A new max trace will only be recorded if the
+	A new max trace will only be recorded, if the
 	latency is greater than the value in this
-	file. (in microseconds)
+	file (in microseconds). NOTE: The max latency
+	recorded by the wakeup and the wakeup_rt tracer
+	do not necessarily reflect the worst-case latency
+	of the system. If two or more processes share the
+	highest priority of the system and may be woken
+	up shortly after each other, the max latency
+	recorded by the wakeup and the wakeup_rt tracers
+	equal the worst-case latency of the system *plus*
+	the longest possible runtime duration of all tasks
+	that share the same priority. An exact measurement
+	of the worst-case wakeup latency of the system can
+	be achieved using the wakekup latency histograms
+	that are part of the PREEMPT_RT patches. These
+	histograms separately determine the wakeup latency
+	of a task that exclusively uses the highest
+	priority of the system and of tasks that share the
+	highest priority of the system with other tasks.
 
   buffer_size_kb:
 

[PATCH 2/2] add-trace_clock-to-ftrace-docs.patch

[Carsten Emde]

[-- Attachment #1: add-trace_clock-to-ftrace-docs.patch --]
[-- Type: text/plain, Size: 1706 bytes --]

Add an explanation of the trace variable
trace_clock to the ftrace documentation.

Signed-off-by: Carsten Emde <C.Emde@osadl.org>

Index: linux-2.6.33-rc2/Documentation/trace/ftrace.txt
===================================================================
--- linux-2.6.33-rc2.orig/Documentation/trace/ftrace.txt
+++ linux-2.6.33-rc2/Documentation/trace/ftrace.txt
@@ -91,6 +91,33 @@ of ftrace. Here is a list of some of the
 	This file holds the output of the trace in a human
 	readable format (described below).
 
+  trace_clock:
+
+	Three different clocks are available for the tracer
+	timestamps, "local", "medium" and "global". For the
+	time being, however, the "medium" clock is disabled
+	in the source code and requires the line
+		{ trace_clock,		"medium" },
+	to be inserted in kernel/trace/trace.c between
+		{ trace_clock_local,	"local" },
+	and
+		{ trace_clock_global,	"global" },
+	- The "local" clock is the simplest and least coherent
+	tracing clock. It is useful for tracing that does not
+	cross to other CPUs nor does it go through idle events.
+	- The "medium" clock is a scalable global clock with
+	some jitter. It is not completely serialized, but not
+	completely incorrect when crossing CPUs either.
+	- The "global" clock is a globally monotonic, serialized
+	clock. It has a higher overhead than the "local" and the
+	"medium" trace clock but is still an order of magnitude
+	faster than a hardware clock based on the gettimeofday()
+	function would be.
+
+	The content of trace_clock displays the available tracer
+	clocks, the name of the currently selected clock is
+	surrounded by square brackets.
+
   trace_pipe:
 
 	The output is the same as the "trace" file but this