[PATCH 4/4] Documentation/rtla: Document unsetting options

[Tomas Glozar]

Add an appendix documenting how to unset options in RTLA. For options
where unsetting is currently not supported, add a note into the
respective section.

An additional note is added for --on-threshold trace. As it is
considered distinct from --trace, it is not reverted by --no-trace.

Signed-off-by: Tomas Glozar <tglozar@xxxxxxxxxx>
---
 Documentation/tools/rtla/common_appendix.txt    | 17 +++++++++++++++++
 Documentation/tools/rtla/common_options.txt     | 13 ++++++++++++-
 .../tools/rtla/common_osnoise_options.txt       |  4 ++++
 .../tools/rtla/common_timerlat_options.txt      |  4 ++++
 4 files changed, 37 insertions(+), 1 deletion(-)

diff --git a/Documentation/tools/rtla/common_appendix.txt b/Documentation/tools/rtla/common_appendix.txt
index 68cb15840d3a9..ad610ed02a240 100644
--- a/Documentation/tools/rtla/common_appendix.txt
+++ b/Documentation/tools/rtla/common_appendix.txt
@@ -1,5 +1,22 @@
 .. SPDX-License-Identifier: GPL-2.0
 
+UNSETTING OPTIONS
+=================
+
+The effect of most command line options can be reverted by prepending "no-" to
+the long variant of the option, for example:
+
+$ rtla timerlat top -p 100 --no-period
+
+resets the period back to the default value of 1000 us.
+
+If a command line option sets multiple RTLA parameters at once, the inverted
+option will revert all of them, even if they were not set by the particular
+option. For example, since using "--auto" implies "--trace", specifying
+"--trace --no-auto" will also disable trace output, just like if "--no-trace"
+was specified.
+
+
 SIGINT BEHAVIOR
 ===============
 
diff --git a/Documentation/tools/rtla/common_options.txt b/Documentation/tools/rtla/common_options.txt
index 6caa51d029347..38da1cf443a48 100644
--- a/Documentation/tools/rtla/common_options.txt
+++ b/Documentation/tools/rtla/common_options.txt
@@ -22,10 +22,14 @@
 
         Enable an event in the trace (**-t**) session. The argument can be a specific event, e.g., **-e** *sched:sched_switch*, or all events of a system group, e.g., **-e** *sched*. Multiple **-e** are allowed. It is only active when **-t** or **-a** are set.
 
+        This option cannot be unset.
+
 **--filter** *<filter>*
 
         Filter the previous **-e** *sys:event* event with *<filter>*. For further information about event filtering see https://www.kernel.org/doc/html/latest/trace/events.html#event-filtering.
 
+        This option cannot be unset.
+
 **--trigger** *<trigger>*
         Enable a trace event trigger to the previous **-e** *sys:event*.
         If the *hist:* trigger is activated, the output histogram will be automatically saved to a file named *system_event_hist.txt*.
@@ -37,6 +41,8 @@
 
         For further information about event trigger see https://www.kernel.org/doc/html/latest/trace/events.html#event-triggers.
 
+        This option cannot be unset.
+
 **-P**, **--priority** *o:prio|r:prio|f:prio|d:runtime:period*
 
         Set scheduling parameters to the |tool| tracer threads, the format to set the priority are:
@@ -78,7 +84,8 @@
 
           Saves trace output, optionally taking a filename. Alternative to -t/--trace.
           Note that unlike -t/--trace, specifying this multiple times will result in
-          the trace being saved multiple times.
+          the trace being saved multiple times, and --no-trace will not disable trace
+          output when enabled through this option.
 
         - *signal,num=<sig>,pid=<pid>*
 
@@ -107,6 +114,8 @@
 
         |actionsperf|
 
+        This option cannot be unset.
+
 **--on-end** *action*
 
         Defines an action to be executed at the end of tracing.
@@ -124,6 +133,8 @@
 
         This runs rtla with the default options, and saves trace output at the end.
 
+        This option cannot be unset.
+
 **-h**, **--help**
 
         Print help menu.
diff --git a/Documentation/tools/rtla/common_osnoise_options.txt b/Documentation/tools/rtla/common_osnoise_options.txt
index bd3c4f4991939..5fc70c0016158 100644
--- a/Documentation/tools/rtla/common_osnoise_options.txt
+++ b/Documentation/tools/rtla/common_osnoise_options.txt
@@ -24,11 +24,15 @@
         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.
 
+        This option cannot be unset.
+
 **-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.
 
+        This option cannot be unset.
+
 **-T**, **--threshold** *us*
 
         Specify the minimum delta between two time reads to be considered noise.
diff --git a/Documentation/tools/rtla/common_timerlat_options.txt b/Documentation/tools/rtla/common_timerlat_options.txt
index 100840f4c0ed0..e36898438a0b0 100644
--- a/Documentation/tools/rtla/common_timerlat_options.txt
+++ b/Documentation/tools/rtla/common_timerlat_options.txt
@@ -23,10 +23,14 @@
 
         Stop trace if the *IRQ* latency is higher than the argument in us.
 
+        This option cannot be unset.
+
 **-T**, **--thread** *us*
 
         Stop trace if the *Thread* latency is higher than the argument in us.
 
+        This option cannot be unset.
+
 **-s**, **--stack** *us*
 
         Save the stack trace at the *IRQ* if a *Thread* latency is higher than the
-- 
2.54.0