6.18-stable review patch. If anyone has any objections, please let me know.
------------------
From: Gopi Krishna Menon krishnagopi487@gmail.com
commit 96b546c241b11a97ba1247580208c554458e7866 upstream.
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#subs... 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 Signed-off-by: Bagas Sanjaya bagasdotme@gmail.com Signed-off-by: Greg Kroah-Hartman gregkh@linuxfoundation.org --- .../{common_appendix.rst => common_appendix.txt} | 0 ...mmon_hist_options.rst => common_hist_options.txt} | 0 .../rtla/{common_options.rst => common_options.txt} | 0 ...escription.rst => common_osnoise_description.txt} | 0 ...snoise_options.rst => common_osnoise_options.txt} | 0 ...common_timerlat_aa.rst => common_timerlat_aa.txt} | 0 ...scription.rst => common_timerlat_description.txt} | 0 ...erlat_options.rst => common_timerlat_options.txt} | 0 ...common_top_options.rst => common_top_options.txt} | 0 Documentation/tools/rtla/common_appendix.rst | 24 --- Documentation/tools/rtla/common_appendix.txt | 24 +++ Documentation/tools/rtla/common_hist_options.rst | 23 -- Documentation/tools/rtla/common_hist_options.txt | 23 ++ Documentation/tools/rtla/common_options.rst | 119 --------------- Documentation/tools/rtla/common_options.txt | 119 +++++++++++++++ Documentation/tools/rtla/common_osnoise_description.rst | 8 - Documentation/tools/rtla/common_osnoise_description.txt | 8 + Documentation/tools/rtla/common_osnoise_options.rst | 39 ---- Documentation/tools/rtla/common_osnoise_options.txt | 39 ++++ Documentation/tools/rtla/common_timerlat_aa.rst | 7 Documentation/tools/rtla/common_timerlat_aa.txt | 7 Documentation/tools/rtla/common_timerlat_description.rst | 18 -- Documentation/tools/rtla/common_timerlat_description.txt | 18 ++ Documentation/tools/rtla/common_timerlat_options.rst | 67 -------- Documentation/tools/rtla/common_timerlat_options.txt | 67 ++++++++ Documentation/tools/rtla/common_top_options.rst | 3 Documentation/tools/rtla/common_top_options.txt | 3 Documentation/tools/rtla/rtla-hwnoise.rst | 8 - Documentation/tools/rtla/rtla-osnoise-hist.rst | 10 - Documentation/tools/rtla/rtla-osnoise-top.rst | 10 - Documentation/tools/rtla/rtla-osnoise.rst | 4 Documentation/tools/rtla/rtla-timerlat-hist.rst | 12 - Documentation/tools/rtla/rtla-timerlat-top.rst | 12 - Documentation/tools/rtla/rtla-timerlat.rst | 4 Documentation/tools/rtla/rtla.rst | 2 26 files changed, 339 insertions(+), 339 deletions(-) rename Documentation/tools/rtla/{common_appendix.rst => common_appendix.txt} (100%) rename Documentation/tools/rtla/{common_hist_options.rst => common_hist_options.txt} (100%) rename Documentation/tools/rtla/{common_options.rst => common_options.txt} (100%) rename Documentation/tools/rtla/{common_osnoise_description.rst => common_osnoise_description.txt} (100%) rename Documentation/tools/rtla/{common_osnoise_options.rst => common_osnoise_options.txt} (100%) rename Documentation/tools/rtla/{common_timerlat_aa.rst => common_timerlat_aa.txt} (100%) rename Documentation/tools/rtla/{common_timerlat_description.rst => common_timerlat_description.txt} (100%) rename Documentation/tools/rtla/{common_timerlat_options.rst => common_timerlat_options.txt} (100%) rename Documentation/tools/rtla/{common_top_options.rst => common_top_options.txt} (100%)
--- a/Documentation/tools/rtla/common_appendix.rst +++ /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). --- /dev/null +++ b/Documentation/tools/rtla/common_appendix.txt @@ -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). --- a/Documentation/tools/rtla/common_hist_options.rst +++ /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. --- /dev/null +++ b/Documentation/tools/rtla/common_hist_options.txt @@ -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. --- a/Documentation/tools/rtla/common_options.rst +++ /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. --- /dev/null +++ b/Documentation/tools/rtla/common_options.txt @@ -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. --- a/Documentation/tools/rtla/common_osnoise_description.rst +++ /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. --- /dev/null +++ b/Documentation/tools/rtla/common_osnoise_description.txt @@ -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. --- a/Documentation/tools/rtla/common_osnoise_options.rst +++ /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*]. --- /dev/null +++ b/Documentation/tools/rtla/common_osnoise_options.txt @@ -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*]. --- a/Documentation/tools/rtla/common_timerlat_aa.rst +++ /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 --- /dev/null +++ b/Documentation/tools/rtla/common_timerlat_aa.txt @@ -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 --- a/Documentation/tools/rtla/common_timerlat_description.rst +++ /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. --- /dev/null +++ b/Documentation/tools/rtla/common_timerlat_description.txt @@ -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. --- a/Documentation/tools/rtla/common_timerlat_options.rst +++ /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. --- /dev/null +++ b/Documentation/tools/rtla/common_timerlat_options.txt @@ -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. --- a/Documentation/tools/rtla/common_top_options.rst +++ /dev/null @@ -1,3 +0,0 @@ -**-q**, **--quiet** - - Print only a summary at the end of the session. --- /dev/null +++ b/Documentation/tools/rtla/common_top_options.txt @@ -0,0 +1,3 @@ +**-q**, **--quiet** + + Print only a summary at the end of the session. --- a/Documentation/tools/rtla/rtla-hwnoise.rst +++ b/Documentation/tools/rtla/rtla-hwnoise.rst @@ -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 --- a/Documentation/tools/rtla/rtla-osnoise-hist.rst +++ b/Documentation/tools/rtla/rtla-osnoise-hist.rst @@ -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 --- a/Documentation/tools/rtla/rtla-osnoise-top.rst +++ b/Documentation/tools/rtla/rtla-osnoise-top.rst @@ -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 --- a/Documentation/tools/rtla/rtla-osnoise.rst +++ b/Documentation/tools/rtla/rtla-osnoise.rst @@ -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 --- a/Documentation/tools/rtla/rtla-timerlat-hist.rst +++ b/Documentation/tools/rtla/rtla-timerlat-hist.rst @@ -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 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 --- a/Documentation/tools/rtla/rtla-timerlat-top.rst +++ b/Documentation/tools/rtla/rtla-timerlat-top.rst @@ -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 --- a/Documentation/tools/rtla/rtla-timerlat.rst +++ b/Documentation/tools/rtla/rtla-timerlat.rst @@ -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 --- a/Documentation/tools/rtla/rtla.rst +++ b/Documentation/tools/rtla/rtla.rst @@ -45,4 +45,4 @@ AUTHOR ====== Daniel Bristot de Oliveira bristot@kernel.org
-.. include:: common_appendix.rst +.. include:: common_appendix.txt