Man page for rtla osnoise top mode.
Cc: Steven Rostedt <rostedt@xxxxxxxxxxx>
Cc: Ingo Molnar <mingo@xxxxxxxxxx>
Cc: Tom Zanussi <zanussi@xxxxxxxxxx>
Cc: Masami Hiramatsu <mhiramat@xxxxxxxxxx>
Cc: Juri Lelli <juri.lelli@xxxxxxxxxx>
Cc: Clark Williams <williams@xxxxxxxxxx>
Cc: Peter Zijlstra <peterz@xxxxxxxxxxxxx>
Cc: Thomas Gleixner <tglx@xxxxxxxxxxxxx>
Cc: Sebastian Andrzej Siewior <bigeasy@xxxxxxxxxxxxx>
Cc: Daniel Bristot de Oliveira <bristot@xxxxxxxxxx>
Cc: linux-rt-users@xxxxxxxxxxxxxxx
Cc: linux-trace-devel@xxxxxxxxxxxxxxx
Cc: linux-kernel@xxxxxxxxxxxxxxx
Signed-off-by: Daniel Bristot de Oliveira <bristot@xxxxxxxxxx>
---
.../rtla/Documentation/rtla-osnoise-top.txt | 98 +++++++++++++++++++
1 file changed, 98 insertions(+)
create mode 100644 tools/tracing/rtla/Documentation/rtla-osnoise-top.txt
diff --git a/tools/tracing/rtla/Documentation/rtla-osnoise-top.txt b/tools/tracing/rtla/Documentation/rtla-osnoise-top.txt
new file mode 100644
index 000000000000..c7c0e7983c6f
--- /dev/null
+++ b/tools/tracing/rtla/Documentation/rtla-osnoise-top.txt
@@ -0,0 +1,98 @@
+rtla-osnoise-top(1)
+===================
+
+NAME
+----
+rtla-osnoise-top - Display a summary of the operating system noise
+
+SYNOPSIS
+--------
+*rtla osnoise top* ['OPTIONS']
+
+DESCRIPTION
+-----------
+The rtla-osnoise-top(1) tool is an interface for the osnoise tracer. The
+osnoise tracer dispatches a kernel thread per-cpu. These threads read the
+time in a loop while with preemption, softirq and IRQs enabled, thus
+allowing all the sources of osnoise during its execution. The osnoise's
+tracer threads take note of the delta between each time read, along with
+an interference counter for each source of interference. At the end of
+each period, the osnoise tracer displays a summary of the results.
+
+*rtla osnoise top* collects the periodic summary from the osnoise tracer,
+including the counters of the occurrence of the interference source,
+displaying the results in a user-friendly format.
+
+The tool also allows many configurations of the osnoise tracer and the
+collection of the tracer output.
+
+OPTIONS
+-------
+*-h*, *--help*::
+Print help menu.
+*-p*, *--period* 'us'::
+Set the osnoise tracer period in microseconds.
+*-r*, *--runtime* 'us'::
+Set the osnoise tracer runtime in microseconds.
+*-s*, *--stop* 'us'::
+Stop the trace if a single sample is higher than the argument in microseconds.
+If -T is set, it will also save the trace to the output.
+*-S*, *--stop-total* 'us'::
+Stop the trace if the total sample is higher than the argument in microseconds.
+If -T is set, it will also save the trace to the output.
+*-c*, *--cpus* 'cpu-list'::
+Set the osnoise tracer to run the sample threads in the cpu-list.
+*-d*, *--duration* 'time[s|m|h|d]'::
+Set the duration of the session.
+*-t*, *--trace*['=file']::
+Save the stopped trace to ['file|osnoise_trace.txt'].
+*-q*, *--quiet*::
+Print only a summary at the end of the session.
+*-P*, *--priority* 'o:prio|r:prio|f:prio|d:runtime:period'::
+Set scheduling parameters to the osnoise tracer threads, the format to set the priority are:
+ - 'o:prio' - use SCHED_OTHER with 'prio';
+ - 'r:prio' - use SCHED_RR with 'prio';
+ - 'f:prio' - use SCHED_FIFO with 'prio';
+ - 'd:runtime[us|ms|s]:period[us|ms|s]' - use SCHED_DEADLINE with 'runtime' and 'period' in nanoseconds.
+
+EXAMPLE
+-------
+In the example below, the rtla osnoise top tool is set to run with a
+real-time priority 'FIFO:1', on CPUs '0-3', for '900ms' at each period
+('1s' by default). The reason for reducing the runtime is to avoid starving
+the rtla tool. The tool is also set to run for 'one minute' and to display
+a summary of the report at the end of the session.
+
+-------------------------------------------------------
+[root@f34 ~]# rtla osnoise top -P F:1 -c 0-3 -r 900000 -d 1M -q
+ Operating System Noise
+duration: 0 00:01:00 | time is in us
+CPU Period Runtime Noise % CPU Aval Max Noise Max Single HW NMI IRQ Softirq Thread
+ 0 #59 53100000 304896 99.42580 6978 56 549 0 53111 1590 13
+ 1 #59 53100000 338339 99.36282 8092 24 399 0 53130 1448 31
+ 2 #59 53100000 290842 99.45227 6582 39 855 0 53110 1406 12
+ 3 #59 53100000 204935 99.61405 6251 33 290 0 53156 1460 12
+-------------------------------------------------------
+
+SEE ALSO
+--------
+_rtla-osnoise(1)_, _rtla-osnoise-hist_(1)
+
+Osnoise tracer documentation: <https://www.kernel.org/doc/html/latest/trace/osnoise-tracer.html>
+
+AUTHOR
+------
+Written by Daniel Bristot de Oliveira <bristot@xxxxxxxxxx>
+
+REPORTING BUGS
+--------------
+Report bugs to <lkml@xxxxxxxxxxxxxxx>
+
+LICENSE
+-------
+rtla is Free Software licensed under the GNU GPLv2
+
+COPYING
+-------
+Copyright \(C) 2021 Red Hat, Inc. Free use of this software is granted under
+the terms of the GNU Public License (GPL).
--
2.31.1
