]> git-server-git.apps.pok.os.sepia.ceph.com Git - ceph-client.git/commitdiff
Documentation/rtla: rename common_xxx.rst files to common_xxx.txt
authorGopi Krishna Menon <krishnagopi487@gmail.com>
Mon, 13 Oct 2025 09:27:20 +0000 (16:27 +0700)
committerJonathan Corbet <corbet@lwn.net>
Fri, 17 Oct 2025 20:25:12 +0000 (14:25 -0600)
Sphinx reports htmldocs errors:

Documentation/tools/rtla/common_options.rst:58: ERROR: Undefined substitution referenced: "threshold".
Documentation/tools/rtla/common_options.rst:88: ERROR: Undefined substitution referenced: "tool".
Documentation/tools/rtla/common_options.rst:88: ERROR: Undefined substitution referenced: "thresharg".
Documentation/tools/rtla/common_options.rst:88: ERROR: Undefined substitution referenced: "tracer".
Documentation/tools/rtla/common_options.rst:92: ERROR: Undefined substitution referenced: "tracer".
Documentation/tools/rtla/common_options.rst:98: ERROR: Undefined substitution referenced: "actionsperf".
Documentation/tools/rtla/common_options.rst:113: ERROR: Undefined substitution referenced: "tool".

common_*.rst files are snippets that are intended to be included by rtla
docs (rtla*.rst). common_options.rst in particular contains
substitutions which depend on other common_* includes, so building it
independently as reST source results in above errors.

Rename all common_*.rst files to common_*.txt to prevent Sphinx from
building these snippets as standalone reST source and update all include
references accordingly.

Link: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#substitutions
Suggested-by: Tomas Glozar <tglozar@redhat.com>
Suggested-by: Bagas Sanjaya <bagasdotme@gmail.com>
Signed-off-by: Gopi Krishna Menon <krishnagopi487@gmail.com>
Reviewed-by: Tomas Glozar <tglozar@redhat.com>
Fixes: 05b7e10687c6 ("tools/rtla: Add remaining support for osnoise actions")
Reviewed-by: Bagas Sanjaya <bagasdotme@gmail.com>
Link: https://lore.kernel.org/r/20251008184522.13201-1-krishnagopi487@gmail.com
[Bagas: massage commit message and apply trailers]
Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251013092719.30780-2-bagasdotme@gmail.com>

26 files changed:
Documentation/tools/rtla/common_appendix.rst [deleted file]
Documentation/tools/rtla/common_appendix.txt [new file with mode: 0644]
Documentation/tools/rtla/common_hist_options.rst [deleted file]
Documentation/tools/rtla/common_hist_options.txt [new file with mode: 0644]
Documentation/tools/rtla/common_options.rst [deleted file]
Documentation/tools/rtla/common_options.txt [new file with mode: 0644]
Documentation/tools/rtla/common_osnoise_description.rst [deleted file]
Documentation/tools/rtla/common_osnoise_description.txt [new file with mode: 0644]
Documentation/tools/rtla/common_osnoise_options.rst [deleted file]
Documentation/tools/rtla/common_osnoise_options.txt [new file with mode: 0644]
Documentation/tools/rtla/common_timerlat_aa.rst [deleted file]
Documentation/tools/rtla/common_timerlat_aa.txt [new file with mode: 0644]
Documentation/tools/rtla/common_timerlat_description.rst [deleted file]
Documentation/tools/rtla/common_timerlat_description.txt [new file with mode: 0644]
Documentation/tools/rtla/common_timerlat_options.rst [deleted file]
Documentation/tools/rtla/common_timerlat_options.txt [new file with mode: 0644]
Documentation/tools/rtla/common_top_options.rst [deleted file]
Documentation/tools/rtla/common_top_options.txt [new file with mode: 0644]
Documentation/tools/rtla/rtla-hwnoise.rst
Documentation/tools/rtla/rtla-osnoise-hist.rst
Documentation/tools/rtla/rtla-osnoise-top.rst
Documentation/tools/rtla/rtla-osnoise.rst
Documentation/tools/rtla/rtla-timerlat-hist.rst
Documentation/tools/rtla/rtla-timerlat-top.rst
Documentation/tools/rtla/rtla-timerlat.rst
Documentation/tools/rtla/rtla.rst

diff --git a/Documentation/tools/rtla/common_appendix.rst b/Documentation/tools/rtla/common_appendix.rst
deleted file mode 100644 (file)
index 53cae75..0000000
+++ /dev/null
@@ -1,24 +0,0 @@
-.. SPDX-License-Identifier: GPL-2.0
-
-EXIT STATUS
-===========
-
-::
-
- 0  Passed: the test did not hit the stop tracing condition
- 1  Error: invalid argument
- 2  Failed: the test hit the stop tracing condition
-
-REPORTING BUGS
-==============
-Report bugs to <linux-kernel@vger.kernel.org>
-and <linux-trace-devel@vger.kernel.org>
-
-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).
diff --git a/Documentation/tools/rtla/common_appendix.txt b/Documentation/tools/rtla/common_appendix.txt
new file mode 100644 (file)
index 0000000..53cae75
--- /dev/null
@@ -0,0 +1,24 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+EXIT STATUS
+===========
+
+::
+
+ 0  Passed: the test did not hit the stop tracing condition
+ 1  Error: invalid argument
+ 2  Failed: the test hit the stop tracing condition
+
+REPORTING BUGS
+==============
+Report bugs to <linux-kernel@vger.kernel.org>
+and <linux-trace-devel@vger.kernel.org>
+
+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).
diff --git a/Documentation/tools/rtla/common_hist_options.rst b/Documentation/tools/rtla/common_hist_options.rst
deleted file mode 100644 (file)
index df53ff8..0000000
+++ /dev/null
@@ -1,23 +0,0 @@
-**-b**, **--bucket-size** *N*
-
-        Set the histogram bucket size (default *1*).
-
-**-E**, **--entries** *N*
-
-        Set the number of entries of the histogram (default 256).
-
-**--no-header**
-
-        Do not print header.
-
-**--no-summary**
-
-        Do not print summary.
-
-**--no-index**
-
-        Do not print index.
-
-**--with-zeros**
-
-        Print zero only entries.
diff --git a/Documentation/tools/rtla/common_hist_options.txt b/Documentation/tools/rtla/common_hist_options.txt
new file mode 100644 (file)
index 0000000..df53ff8
--- /dev/null
@@ -0,0 +1,23 @@
+**-b**, **--bucket-size** *N*
+
+        Set the histogram bucket size (default *1*).
+
+**-E**, **--entries** *N*
+
+        Set the number of entries of the histogram (default 256).
+
+**--no-header**
+
+        Do not print header.
+
+**--no-summary**
+
+        Do not print summary.
+
+**--no-index**
+
+        Do not print index.
+
+**--with-zeros**
+
+        Print zero only entries.
diff --git a/Documentation/tools/rtla/common_options.rst b/Documentation/tools/rtla/common_options.rst
deleted file mode 100644 (file)
index 77ef35d..0000000
+++ /dev/null
@@ -1,119 +0,0 @@
-**-c**, **--cpus** *cpu-list*
-
-        Set the osnoise tracer to run the sample threads in the cpu-list.
-
-**-H**, **--house-keeping** *cpu-list*
-
-        Run rtla control threads only on the given cpu-list.
-
-**-d**, **--duration** *time[s|m|h|d]*
-
-        Set the duration of the session.
-
-**-D**, **--debug**
-
-        Print debug info.
-
-**-e**, **--event** *sys:event*
-
-        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.
-
-**--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.
-
-**--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*.
-        For example, the command:
-
-        rtla <command> <mode> -t -e osnoise:irq_noise --trigger="hist:key=desc,duration/1000:sort=desc,duration/1000:vals=hitcount"
-
-        Will automatically save the content of the histogram associated to *osnoise:irq_noise* event in *osnoise_irq_noise_hist.txt*.
-
-        For further information about event trigger see https://www.kernel.org/doc/html/latest/trace/events.html#event-triggers.
-
-**-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.
-
-**-C**, **--cgroup**\[*=cgroup*]
-
-        Set a *cgroup* to the tracer's threads. If the **-C** option is passed without arguments, the tracer's thread will inherit **rtla**'s *cgroup*. Otherwise, the threads will be placed on the *cgroup* passed to the option.
-
-**--warm-up** *s*
-
-        After starting the workload, let it run for *s* seconds before starting collecting the data, allowing the system to warm-up. Statistical data generated during warm-up is discarded.
-
-**--trace-buffer-size** *kB*
-        Set the per-cpu trace buffer size in kB for the tracing output.
-
-**--on-threshold** *action*
-
-        Defines an action to be executed when tracing is stopped on a latency threshold
-        specified by |threshold|.
-
-        Multiple --on-threshold actions may be specified, and they will be executed in
-        the order they are provided. If any action fails, subsequent actions in the list
-        will not be executed.
-
-        Supported actions are:
-
-        - *trace[,file=<filename>]*
-
-          Saves trace output, optionally taking a filename. Alternative to -t/--trace.
-          Note that nlike -t/--trace, specifying this multiple times will result in
-          the trace being saved multiple times.
-
-        - *signal,num=<sig>,pid=<pid>*
-
-          Sends signal to process. "parent" might be specified in place of pid to target
-          the parent process of rtla.
-
-        - *shell,command=<command>*
-
-          Execute shell command.
-
-        - *continue*
-
-          Continue tracing after actions are executed instead of stopping.
-
-        Example:
-
-        $ rtla |tool| |thresharg| 20 --on-threshold trace
-        --on-threshold shell,command="grep ipi_send |tracer|\_trace.txt"
-        --on-threshold signal,num=2,pid=parent
-
-        This will save a trace with the default filename "|tracer|\_trace.txt", print its
-        lines that contain the text "ipi_send" on standard output, and send signal 2
-        (SIGINT) to the parent process.
-
-        Performance Considerations:
-
-        |actionsperf|
-
-**--on-end** *action*
-
-        Defines an action to be executed at the end of tracing.
-
-        Multiple --on-end actions can be specified, and they will be executed in the order
-        they are provided. If any action fails, subsequent actions in the list will not be
-        executed.
-
-        See the documentation for **--on-threshold** for the list of supported actions, with
-        the exception that *continue* has no effect.
-
-        Example:
-
-        $ rtla |tool| -d 5s --on-end trace
-
-        This runs rtla with the default options, and saves trace output at the end.
-
-**-h**, **--help**
-
-        Print help menu.
diff --git a/Documentation/tools/rtla/common_options.txt b/Documentation/tools/rtla/common_options.txt
new file mode 100644 (file)
index 0000000..77ef35d
--- /dev/null
@@ -0,0 +1,119 @@
+**-c**, **--cpus** *cpu-list*
+
+        Set the osnoise tracer to run the sample threads in the cpu-list.
+
+**-H**, **--house-keeping** *cpu-list*
+
+        Run rtla control threads only on the given cpu-list.
+
+**-d**, **--duration** *time[s|m|h|d]*
+
+        Set the duration of the session.
+
+**-D**, **--debug**
+
+        Print debug info.
+
+**-e**, **--event** *sys:event*
+
+        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.
+
+**--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.
+
+**--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*.
+        For example, the command:
+
+        rtla <command> <mode> -t -e osnoise:irq_noise --trigger="hist:key=desc,duration/1000:sort=desc,duration/1000:vals=hitcount"
+
+        Will automatically save the content of the histogram associated to *osnoise:irq_noise* event in *osnoise_irq_noise_hist.txt*.
+
+        For further information about event trigger see https://www.kernel.org/doc/html/latest/trace/events.html#event-triggers.
+
+**-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.
+
+**-C**, **--cgroup**\[*=cgroup*]
+
+        Set a *cgroup* to the tracer's threads. If the **-C** option is passed without arguments, the tracer's thread will inherit **rtla**'s *cgroup*. Otherwise, the threads will be placed on the *cgroup* passed to the option.
+
+**--warm-up** *s*
+
+        After starting the workload, let it run for *s* seconds before starting collecting the data, allowing the system to warm-up. Statistical data generated during warm-up is discarded.
+
+**--trace-buffer-size** *kB*
+        Set the per-cpu trace buffer size in kB for the tracing output.
+
+**--on-threshold** *action*
+
+        Defines an action to be executed when tracing is stopped on a latency threshold
+        specified by |threshold|.
+
+        Multiple --on-threshold actions may be specified, and they will be executed in
+        the order they are provided. If any action fails, subsequent actions in the list
+        will not be executed.
+
+        Supported actions are:
+
+        - *trace[,file=<filename>]*
+
+          Saves trace output, optionally taking a filename. Alternative to -t/--trace.
+          Note that nlike -t/--trace, specifying this multiple times will result in
+          the trace being saved multiple times.
+
+        - *signal,num=<sig>,pid=<pid>*
+
+          Sends signal to process. "parent" might be specified in place of pid to target
+          the parent process of rtla.
+
+        - *shell,command=<command>*
+
+          Execute shell command.
+
+        - *continue*
+
+          Continue tracing after actions are executed instead of stopping.
+
+        Example:
+
+        $ rtla |tool| |thresharg| 20 --on-threshold trace
+        --on-threshold shell,command="grep ipi_send |tracer|\_trace.txt"
+        --on-threshold signal,num=2,pid=parent
+
+        This will save a trace with the default filename "|tracer|\_trace.txt", print its
+        lines that contain the text "ipi_send" on standard output, and send signal 2
+        (SIGINT) to the parent process.
+
+        Performance Considerations:
+
+        |actionsperf|
+
+**--on-end** *action*
+
+        Defines an action to be executed at the end of tracing.
+
+        Multiple --on-end actions can be specified, and they will be executed in the order
+        they are provided. If any action fails, subsequent actions in the list will not be
+        executed.
+
+        See the documentation for **--on-threshold** for the list of supported actions, with
+        the exception that *continue* has no effect.
+
+        Example:
+
+        $ rtla |tool| -d 5s --on-end trace
+
+        This runs rtla with the default options, and saves trace output at the end.
+
+**-h**, **--help**
+
+        Print help menu.
diff --git a/Documentation/tools/rtla/common_osnoise_description.rst b/Documentation/tools/rtla/common_osnoise_description.rst
deleted file mode 100644 (file)
index d5d6161..0000000
+++ /dev/null
@@ -1,8 +0,0 @@
-The **rtla osnoise** 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 operating system noise during its execution.
-The *osnoise*'s tracer threads take note of the delta between each time
-read, along with an interference counter of all sources of interference.
-At the end of each period, the *osnoise* tracer displays a summary of
-the results.
diff --git a/Documentation/tools/rtla/common_osnoise_description.txt b/Documentation/tools/rtla/common_osnoise_description.txt
new file mode 100644 (file)
index 0000000..d5d6161
--- /dev/null
@@ -0,0 +1,8 @@
+The **rtla osnoise** 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 operating system noise during its execution.
+The *osnoise*'s tracer threads take note of the delta between each time
+read, along with an interference counter of all sources of interference.
+At the end of each period, the *osnoise* tracer displays a summary of
+the results.
diff --git a/Documentation/tools/rtla/common_osnoise_options.rst b/Documentation/tools/rtla/common_osnoise_options.rst
deleted file mode 100644 (file)
index bd3c4f4..0000000
+++ /dev/null
@@ -1,39 +0,0 @@
-.. |threshold|  replace:: **-a/--auto**, **-s/--stop**, or **-S/--stop-total**
-.. |thresharg|  replace:: -s
-.. |tracer|     replace:: osnoise
-
-.. |actionsperf| replace::
-        Due to implementational limitations, actions might be delayed
-        up to one second after tracing is stopped.
-
-**-a**, **--auto** *us*
-
-        Set the automatic trace mode. This mode sets some commonly used options
-        while debugging the system. It is equivalent to use **-s** *us* **-T 1 -t**.
-
-**-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.
-
-**-T**, **--threshold** *us*
-
-        Specify the minimum delta between two time reads to be considered noise.
-        The default threshold is *5 us*.
-
-**-t**, **--trace** \[*file*]
-
-        Save the stopped trace to [*file|osnoise_trace.txt*].
diff --git a/Documentation/tools/rtla/common_osnoise_options.txt b/Documentation/tools/rtla/common_osnoise_options.txt
new file mode 100644 (file)
index 0000000..bd3c4f4
--- /dev/null
@@ -0,0 +1,39 @@
+.. |threshold|  replace:: **-a/--auto**, **-s/--stop**, or **-S/--stop-total**
+.. |thresharg|  replace:: -s
+.. |tracer|     replace:: osnoise
+
+.. |actionsperf| replace::
+        Due to implementational limitations, actions might be delayed
+        up to one second after tracing is stopped.
+
+**-a**, **--auto** *us*
+
+        Set the automatic trace mode. This mode sets some commonly used options
+        while debugging the system. It is equivalent to use **-s** *us* **-T 1 -t**.
+
+**-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.
+
+**-T**, **--threshold** *us*
+
+        Specify the minimum delta between two time reads to be considered noise.
+        The default threshold is *5 us*.
+
+**-t**, **--trace** \[*file*]
+
+        Save the stopped trace to [*file|osnoise_trace.txt*].
diff --git a/Documentation/tools/rtla/common_timerlat_aa.rst b/Documentation/tools/rtla/common_timerlat_aa.rst
deleted file mode 100644 (file)
index 077029e..0000000
+++ /dev/null
@@ -1,7 +0,0 @@
-**--dump-tasks**
-
-        prints the task running on all CPUs if stop conditions are met (depends on !--no-aa)
-
-**--no-aa**
-
-        disable auto-analysis, reducing rtla timerlat cpu usage
diff --git a/Documentation/tools/rtla/common_timerlat_aa.txt b/Documentation/tools/rtla/common_timerlat_aa.txt
new file mode 100644 (file)
index 0000000..077029e
--- /dev/null
@@ -0,0 +1,7 @@
+**--dump-tasks**
+
+        prints the task running on all CPUs if stop conditions are met (depends on !--no-aa)
+
+**--no-aa**
+
+        disable auto-analysis, reducing rtla timerlat cpu usage
diff --git a/Documentation/tools/rtla/common_timerlat_description.rst b/Documentation/tools/rtla/common_timerlat_description.rst
deleted file mode 100644 (file)
index 49fcae3..0000000
+++ /dev/null
@@ -1,18 +0,0 @@
-The **rtla timerlat** tool is an interface for the *timerlat* tracer. The
-*timerlat* tracer dispatches a kernel thread per-cpu. These threads
-set a periodic timer to wake themselves up and go back to sleep. After
-the wakeup, they collect and generate useful information for the
-debugging of operating system timer latency.
-
-The *timerlat* tracer outputs information in two ways. It periodically
-prints the timer latency at the timer *IRQ* handler and the *Thread*
-handler. It also enables the trace of the most relevant information via
-**osnoise:** tracepoints.
-
-The **rtla timerlat** tool sets the options of the *timerlat* tracer
-and collects and displays a summary of the results. By default,
-the collection is done synchronously in kernel space using a dedicated
-BPF program attached to the *timerlat* tracer. If either BPF or
-the **osnoise:timerlat_sample** tracepoint it attaches to is
-unavailable, the **rtla timerlat** tool falls back to using tracefs to
-process the data asynchronously in user space.
diff --git a/Documentation/tools/rtla/common_timerlat_description.txt b/Documentation/tools/rtla/common_timerlat_description.txt
new file mode 100644 (file)
index 0000000..49fcae3
--- /dev/null
@@ -0,0 +1,18 @@
+The **rtla timerlat** tool is an interface for the *timerlat* tracer. The
+*timerlat* tracer dispatches a kernel thread per-cpu. These threads
+set a periodic timer to wake themselves up and go back to sleep. After
+the wakeup, they collect and generate useful information for the
+debugging of operating system timer latency.
+
+The *timerlat* tracer outputs information in two ways. It periodically
+prints the timer latency at the timer *IRQ* handler and the *Thread*
+handler. It also enables the trace of the most relevant information via
+**osnoise:** tracepoints.
+
+The **rtla timerlat** tool sets the options of the *timerlat* tracer
+and collects and displays a summary of the results. By default,
+the collection is done synchronously in kernel space using a dedicated
+BPF program attached to the *timerlat* tracer. If either BPF or
+the **osnoise:timerlat_sample** tracepoint it attaches to is
+unavailable, the **rtla timerlat** tool falls back to using tracefs to
+process the data asynchronously in user space.
diff --git a/Documentation/tools/rtla/common_timerlat_options.rst b/Documentation/tools/rtla/common_timerlat_options.rst
deleted file mode 100644 (file)
index 1f5d024..0000000
+++ /dev/null
@@ -1,67 +0,0 @@
-.. |threshold|  replace:: **-a/--auto**, **-i/--irq**, or **-T/--thread**
-.. |thresharg|  replace:: -T
-.. |tracer|     replace:: timerlat
-
-.. |actionsperf| replace::
-        For time-sensitive actions, it is recommended to run **rtla timerlat** with BPF
-        support and RT priority. Note that due to implementational limitations, actions
-        might be delayed up to one second after tracing is stopped if BPF mode is not
-        available or disabled.
-
-**-a**, **--auto** *us*
-
-        Set the automatic trace mode. This mode sets some commonly used options
-        while debugging the system. It is equivalent to use **-T** *us* **-s** *us*
-        **-t**. By default, *timerlat* tracer uses FIFO:95 for *timerlat* threads,
-        thus equilavent to **-P** *f:95*.
-
-**-p**, **--period** *us*
-
-        Set the *timerlat* tracer period in microseconds.
-
-**-i**, **--irq** *us*
-
-        Stop trace if the *IRQ* latency is higher than the argument in us.
-
-**-T**, **--thread** *us*
-
-        Stop trace if the *Thread* latency is higher than the argument in us.
-
-**-s**, **--stack** *us*
-
-        Save the stack trace at the *IRQ* if a *Thread* latency is higher than the
-        argument in us.
-
-**-t**, **--trace** \[*file*]
-
-        Save the stopped trace to [*file|timerlat_trace.txt*].
-
-**--dma-latency** *us*
-        Set the /dev/cpu_dma_latency to *us*, aiming to bound exit from idle latencies.
-        *cyclictest* sets this value to *0* by default, use **--dma-latency** *0* to have
-        similar results.
-
-**--deepest-idle-state** *n*
-        Disable idle states higher than *n* for cpus that are running timerlat threads to
-        reduce exit from idle latencies. If *n* is -1, all idle states are disabled.
-        On exit from timerlat, the idle state setting is restored to its original state
-        before running timerlat.
-
-        Requires rtla to be built with libcpupower.
-
-**-k**, **--kernel-threads**
-
-        Use timerlat kernel-space threads, in contrast of **-u**.
-
-**-u**, **--user-threads**
-
-        Set timerlat to run without a workload, and then dispatches user-space workloads
-        to wait on the timerlat_fd. Once the workload is awakes, it goes to sleep again
-        adding so the measurement for the kernel-to-user and user-to-kernel to the tracer
-        output. **--user-threads** will be used unless the user specify **-k**.
-
-**-U**, **--user-load**
-
-        Set timerlat to run without workload, waiting for the user to dispatch a per-cpu
-        task that waits for a new period on the tracing/osnoise/per_cpu/cpu$ID/timerlat_fd.
-        See linux/tools/rtla/sample/timerlat_load.py for an example of user-load code.
diff --git a/Documentation/tools/rtla/common_timerlat_options.txt b/Documentation/tools/rtla/common_timerlat_options.txt
new file mode 100644 (file)
index 0000000..1f5d024
--- /dev/null
@@ -0,0 +1,67 @@
+.. |threshold|  replace:: **-a/--auto**, **-i/--irq**, or **-T/--thread**
+.. |thresharg|  replace:: -T
+.. |tracer|     replace:: timerlat
+
+.. |actionsperf| replace::
+        For time-sensitive actions, it is recommended to run **rtla timerlat** with BPF
+        support and RT priority. Note that due to implementational limitations, actions
+        might be delayed up to one second after tracing is stopped if BPF mode is not
+        available or disabled.
+
+**-a**, **--auto** *us*
+
+        Set the automatic trace mode. This mode sets some commonly used options
+        while debugging the system. It is equivalent to use **-T** *us* **-s** *us*
+        **-t**. By default, *timerlat* tracer uses FIFO:95 for *timerlat* threads,
+        thus equilavent to **-P** *f:95*.
+
+**-p**, **--period** *us*
+
+        Set the *timerlat* tracer period in microseconds.
+
+**-i**, **--irq** *us*
+
+        Stop trace if the *IRQ* latency is higher than the argument in us.
+
+**-T**, **--thread** *us*
+
+        Stop trace if the *Thread* latency is higher than the argument in us.
+
+**-s**, **--stack** *us*
+
+        Save the stack trace at the *IRQ* if a *Thread* latency is higher than the
+        argument in us.
+
+**-t**, **--trace** \[*file*]
+
+        Save the stopped trace to [*file|timerlat_trace.txt*].
+
+**--dma-latency** *us*
+        Set the /dev/cpu_dma_latency to *us*, aiming to bound exit from idle latencies.
+        *cyclictest* sets this value to *0* by default, use **--dma-latency** *0* to have
+        similar results.
+
+**--deepest-idle-state** *n*
+        Disable idle states higher than *n* for cpus that are running timerlat threads to
+        reduce exit from idle latencies. If *n* is -1, all idle states are disabled.
+        On exit from timerlat, the idle state setting is restored to its original state
+        before running timerlat.
+
+        Requires rtla to be built with libcpupower.
+
+**-k**, **--kernel-threads**
+
+        Use timerlat kernel-space threads, in contrast of **-u**.
+
+**-u**, **--user-threads**
+
+        Set timerlat to run without a workload, and then dispatches user-space workloads
+        to wait on the timerlat_fd. Once the workload is awakes, it goes to sleep again
+        adding so the measurement for the kernel-to-user and user-to-kernel to the tracer
+        output. **--user-threads** will be used unless the user specify **-k**.
+
+**-U**, **--user-load**
+
+        Set timerlat to run without workload, waiting for the user to dispatch a per-cpu
+        task that waits for a new period on the tracing/osnoise/per_cpu/cpu$ID/timerlat_fd.
+        See linux/tools/rtla/sample/timerlat_load.py for an example of user-load code.
diff --git a/Documentation/tools/rtla/common_top_options.rst b/Documentation/tools/rtla/common_top_options.rst
deleted file mode 100644 (file)
index f488789..0000000
+++ /dev/null
@@ -1,3 +0,0 @@
-**-q**, **--quiet**
-
-        Print only a summary at the end of the session.
diff --git a/Documentation/tools/rtla/common_top_options.txt b/Documentation/tools/rtla/common_top_options.txt
new file mode 100644 (file)
index 0000000..f488789
--- /dev/null
@@ -0,0 +1,3 @@
+**-q**, **--quiet**
+
+        Print only a summary at the end of the session.
index 3a7163c02ac8e8f4f462b63a15106022181b65cd..26512b15fe7ba5f4cc5ddd2a42f0952281f2842e 100644 (file)
@@ -29,11 +29,11 @@ collection of the tracer output.
 
 OPTIONS
 =======
-.. include:: common_osnoise_options.rst
+.. include:: common_osnoise_options.txt
 
-.. include:: common_top_options.rst
+.. include:: common_top_options.txt
 
-.. include:: common_options.rst
+.. include:: common_options.txt
 
 EXAMPLE
 =======
@@ -106,4 +106,4 @@ AUTHOR
 ======
 Written by Daniel Bristot de Oliveira <bristot@kernel.org>
 
-.. include:: common_appendix.rst
+.. include:: common_appendix.txt
index 1fc60ef2610677f71bc663693e85a75be9c16308..007521c865d97e4bd7e8bbd0a6187668ecac9cee 100644 (file)
@@ -15,7 +15,7 @@ SYNOPSIS
 
 DESCRIPTION
 ===========
-.. include:: common_osnoise_description.rst
+.. include:: common_osnoise_description.txt
 
 The **rtla osnoise hist** tool collects all **osnoise:sample_threshold**
 occurrence in a histogram, displaying the results in a user-friendly way.
@@ -24,11 +24,11 @@ collection of the tracer output.
 
 OPTIONS
 =======
-.. include:: common_osnoise_options.rst
+.. include:: common_osnoise_options.txt
 
-.. include:: common_hist_options.rst
+.. include:: common_hist_options.txt
 
-.. include:: common_options.rst
+.. include:: common_options.txt
 
 EXAMPLE
 =======
@@ -65,4 +65,4 @@ AUTHOR
 ======
 Written by Daniel Bristot de Oliveira <bristot@kernel.org>
 
-.. include:: common_appendix.rst
+.. include:: common_appendix.txt
index b1cbd7bcd4aed2c6483016c675f0b9b28acc4747..6ccadae38945706f864b12636107160c1194fd45 100644 (file)
@@ -15,7 +15,7 @@ SYNOPSIS
 
 DESCRIPTION
 ===========
-.. include:: common_osnoise_description.rst
+.. include:: common_osnoise_description.txt
 
 **rtla osnoise top** collects the periodic summary from the *osnoise* tracer,
 including the counters of the occurrence of the interference source,
@@ -26,11 +26,11 @@ collection of the tracer output.
 
 OPTIONS
 =======
-.. include:: common_osnoise_options.rst
+.. include:: common_osnoise_options.txt
 
-.. include:: common_top_options.rst
+.. include:: common_top_options.txt
 
-.. include:: common_options.rst
+.. include:: common_options.txt
 
 EXAMPLE
 =======
@@ -60,4 +60,4 @@ AUTHOR
 ======
 Written by Daniel Bristot de Oliveira <bristot@kernel.org>
 
-.. include:: common_appendix.rst
+.. include:: common_appendix.txt
index c129b206ce34844b89c348fc65bbccdf5eed6ba5..540d2bf6c1524782b61340b60887dd7a0760fded 100644 (file)
@@ -14,7 +14,7 @@ SYNOPSIS
 DESCRIPTION
 ===========
 
-.. include:: common_osnoise_description.rst
+.. include:: common_osnoise_description.txt
 
 The *osnoise* tracer outputs information in two ways. It periodically prints
 a summary of the noise of the operating system, including the counters of
@@ -56,4 +56,4 @@ AUTHOR
 ======
 Written by Daniel Bristot de Oliveira <bristot@kernel.org>
 
-.. include:: common_appendix.rst
+.. include:: common_appendix.txt
index 4923a362129bbddf431fecbae919aec409858a80..f56fe546411bd4cad65e9b49e9453c46580c5d5f 100644 (file)
@@ -16,7 +16,7 @@ SYNOPSIS
 DESCRIPTION
 ===========
 
-.. include:: common_timerlat_description.rst
+.. include:: common_timerlat_description.txt
 
 The **rtla timerlat hist** displays a histogram of each tracer event
 occurrence. This tool uses the periodic information, and the
@@ -25,13 +25,13 @@ occurrence. This tool uses the periodic information, and the
 OPTIONS
 =======
 
-.. include:: common_timerlat_options.rst
+.. include:: common_timerlat_options.txt
 
-.. include:: common_hist_options.rst
+.. include:: common_hist_options.txt
 
-.. include:: common_options.rst
+.. include:: common_options.txt
 
-.. include:: common_timerlat_aa.rst
+.. include:: common_timerlat_aa.txt
 
 EXAMPLE
 =======
@@ -110,4 +110,4 @@ AUTHOR
 ======
 Written by Daniel Bristot de Oliveira <bristot@kernel.org>
 
-.. include:: common_appendix.rst
+.. include:: common_appendix.txt
index 50968cdd2095a1a5547f24d258007a68504c1ede..7dbe625d0c42437cb814bcc543166b3f88a09a8c 100644 (file)
@@ -16,7 +16,7 @@ SYNOPSIS
 DESCRIPTION
 ===========
 
-.. include:: common_timerlat_description.rst
+.. include:: common_timerlat_description.txt
 
 The **rtla timerlat top** displays a summary of the periodic output
 from the *timerlat* tracer. It also provides information for each
@@ -26,13 +26,13 @@ seem with the option **-T**.
 OPTIONS
 =======
 
-.. include:: common_timerlat_options.rst
+.. include:: common_timerlat_options.txt
 
-.. include:: common_top_options.rst
+.. include:: common_top_options.txt
 
-.. include:: common_options.rst
+.. include:: common_options.txt
 
-.. include:: common_timerlat_aa.rst
+.. include:: common_timerlat_aa.txt
 
 **--aa-only** *us*
 
@@ -133,4 +133,4 @@ AUTHOR
 ------
 Written by Daniel Bristot de Oliveira <bristot@kernel.org>
 
-.. include:: common_appendix.rst
+.. include:: common_appendix.txt
index 20e2d259467fd03ba2c1b7ade6cc0a62cf25fb95..ce9f57e038c37fb5133ca0ebe2f565a5f2d1e3d9 100644 (file)
@@ -14,7 +14,7 @@ SYNOPSIS
 DESCRIPTION
 ===========
 
-.. include:: common_timerlat_description.rst
+.. include:: common_timerlat_description.txt
 
 The **rtla timerlat top** mode displays a summary of the periodic output
 from the *timerlat* tracer. The **rtla timerlat hist** mode displays
@@ -51,4 +51,4 @@ AUTHOR
 ======
 Written by Daniel Bristot de Oliveira <bristot@kernel.org>
 
-.. include:: common_appendix.rst
+.. include:: common_appendix.txt
index fc0d233efcd5dff61a5fbbc43b492cef4bbe4dad..2a5fb7004ad448d36df35de33417fef82ce3269f 100644 (file)
@@ -45,4 +45,4 @@ AUTHOR
 ======
 Daniel Bristot de Oliveira <bristot@kernel.org>
 
-.. include:: common_appendix.rst
+.. include:: common_appendix.txt