tracing: Expand ftrace documentation
Subsystems (3)
cover tracing: Expand ftrace documentation
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
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 <[email protected]>
Documentation/trace/ftrace.txt +18 -2
@@ -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
In reply to Carsten EmdeAdd an explanation of the trace variabletrace_clock to the ftrace documentation.
Signed-off-by Carsten Emde <[email protected]>
Documentation/trace/ftrace.txt +27 -0
@@ -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