[PATCH 0/9] Documentation/rtla: Cover default options

[PATCH 0/9] Documentation/rtla: Cover default options

[Tomas Glozar]

RTLA has many options that have a default value that is used when
the option is not set associated with them. Those are not covered in
the documentation for the options, which creates confusion among users.

Document the default behavior for all relevant options: -H, -P, -C,
--trace-buffer-size. Some of these are covered in general
descriptions, only missing from the option documentation.

Also, fix a few typos and incorrect naming of tracers.

-----------------------

The patchset contains two parts: fixes (first five commits), and new
additions for default options, which were previously undocumented or
poorly documented (the rest).

The patchset assumes [1] is applied, renaming included files to *.txt
from *.rst, to prevent build error on "make htmldocs".

Note: I am aware that there are more issues with the documentation, just
not everything can (and should) be fixed in one patchset.

[1] https://lore.kernel.org/linux-trace-kernel/20251008184522.13201-1-krishnagopi487@gmail.com/

Tomas Glozar (9):
  Documentation/rtla: Fix typo in common_options.txt
  Documentation/rtla: Fix typo in common_timerlat_options.txt
  Documentation/rtla: Fix typo in rtla-timerlat-top.rst
  Documentation/rtla: Fix typo in common_timerlat_options.txt
  Documentation/rtla: Correct tracer name for common options
  Documentation/rtla: Mention default priority
  Documentation/rtla: Mention default cgroup state
  Documentation/trace: Specify exact priority for timerlat
  Documentation/rtla: Include defaults for tracer options

 Documentation/tools/rtla/common_options.txt      | 16 +++++++++++++---
 .../tools/rtla/common_timerlat_options.txt       |  4 ++--
 Documentation/tools/rtla/rtla-timerlat-top.rst   |  2 +-
 Documentation/trace/timerlat-tracer.rst          | 12 ++++++------
 4 files changed, 22 insertions(+), 12 deletions(-)

-- 
2.51.0

[PATCH 1/9] Documentation/rtla: Fix typo in common_options.txt

[Tomas Glozar]

Fix "unlike" being spelled "nlike" in --on-threshold documentation.

Fixes: 70165c78e31d ("Documentation/rtla: Add actions feature")
Signed-off-by: Tomas Glozar <tglozar@redhat.com>
---
 Documentation/tools/rtla/common_options.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/tools/rtla/common_options.txt b/Documentation/tools/rtla/common_options.txt
index 77ef35d3f831..8ca424ab0faf 100644
--- a/Documentation/tools/rtla/common_options.txt
+++ b/Documentation/tools/rtla/common_options.txt
@@ -67,7 +67,7 @@
         - *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
+          Note that unlike -t/--trace, specifying this multiple times will result in
           the trace being saved multiple times.
 
         - *signal,num=<sig>,pid=<pid>*
-- 
2.51.0

[PATCH 2/9] Documentation/rtla: Fix typo in common_timerlat_options.txt

[Tomas Glozar]

Fix "awakes" being used in place of "awakened" in --users-threads option
documentation.

Fixes: 612738321774 ("Documentation: Add tools/rtla timerlat -u option documentation")
Signed-off-by: Tomas Glozar <tglozar@redhat.com>
---
 Documentation/tools/rtla/common_timerlat_options.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/tools/rtla/common_timerlat_options.txt b/Documentation/tools/rtla/common_timerlat_options.txt
index 1f5d024b53aa..e7074eb36468 100644
--- a/Documentation/tools/rtla/common_timerlat_options.txt
+++ b/Documentation/tools/rtla/common_timerlat_options.txt
@@ -56,7 +56,7 @@
 **-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
+        to wait on the timerlat_fd. Once the workload is awakened, 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**.
 
-- 
2.51.0

[PATCH 3/9] Documentation/rtla: Fix typo in rtla-timerlat-top.rst

[Tomas Glozar]

Fix "seem" in place of intended "seen" in rtla-timerlat-top
documentation.

Fixes: df337d014b57 ("rtla: Add rtla timerlat top documentation")
Signed-off-by: Tomas Glozar <tglozar@redhat.com>
---
 Documentation/tools/rtla/rtla-timerlat-top.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/tools/rtla/rtla-timerlat-top.rst b/Documentation/tools/rtla/rtla-timerlat-top.rst
index 7dbe625d0c42..72d85e36c193 100644
--- a/Documentation/tools/rtla/rtla-timerlat-top.rst
+++ b/Documentation/tools/rtla/rtla-timerlat-top.rst
@@ -21,7 +21,7 @@ DESCRIPTION
 The **rtla timerlat top** displays a summary of the periodic output
 from the *timerlat* tracer. It also provides information for each
 operating system noise via the **osnoise:** tracepoints that can be
-seem with the option **-T**.
+seen with the option **-T**.
 
 OPTIONS
 =======
-- 
2.51.0

[PATCH 4/9] Documentation/rtla: Fix typo in common_timerlat_options.txt

[Tomas Glozar]

Fix spelling error "equilavent" in place of "equivalent".

Fixes: 173a3b014827 ("rtla/timerlat: Add the automatic trace option")
Signed-off-by: Tomas Glozar <tglozar@redhat.com>
---
 Documentation/tools/rtla/common_timerlat_options.txt | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/Documentation/tools/rtla/common_timerlat_options.txt b/Documentation/tools/rtla/common_timerlat_options.txt
index e7074eb36468..33070b264cae 100644
--- a/Documentation/tools/rtla/common_timerlat_options.txt
+++ b/Documentation/tools/rtla/common_timerlat_options.txt
@@ -13,7 +13,7 @@
         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*.
+        thus equivalent to **-P** *f:95*.
 
 **-p**, **--period** *us*
 
-- 
2.51.0

[PATCH 5/9] Documentation/rtla: Correct tracer name for common options

[Tomas Glozar]

Several options in common_options.rst say "osnoise tracer" for both
osnoise and timerlat.

Use |tool| variable so that the correct tool name is used.

Fixes: b1be48307de4 ("rtla: Add rtla osnoise top documentation")
Signed-off-by: Tomas Glozar <tglozar@redhat.com>
---
 Documentation/tools/rtla/common_options.txt | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/Documentation/tools/rtla/common_options.txt b/Documentation/tools/rtla/common_options.txt
index 8ca424ab0faf..a2f9c03810b9 100644
--- a/Documentation/tools/rtla/common_options.txt
+++ b/Documentation/tools/rtla/common_options.txt
@@ -1,6 +1,6 @@
 **-c**, **--cpus** *cpu-list*
 
-        Set the osnoise tracer to run the sample threads in the cpu-list.
+        Set the |tool| tracer to run the sample threads in the cpu-list.
 
 **-H**, **--house-keeping** *cpu-list*
 
@@ -35,7 +35,7 @@
 
 **-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:
+        Set scheduling parameters to the |tool| tracer threads, the format to set the priority are:
 
         - *o:prio* - use SCHED_OTHER with *prio*;
         - *r:prio* - use SCHED_RR with *prio*;
-- 
2.51.0

[PATCH 6/9] Documentation/rtla: Mention default priority

[Tomas Glozar]

RTLA allows the priority of workload threads to be set using the -P
option. This is covered in docs, but the default state for RTLA's own
user workload (implemented in timerlat_u.c) is not mentioned.

Add mention of the default user workload priority as well as a reference
to osnoise and timerlat tracers for kernel workload priority.

Signed-off-by: Tomas Glozar <tglozar@redhat.com>
---
 Documentation/tools/rtla/common_options.txt | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/Documentation/tools/rtla/common_options.txt b/Documentation/tools/rtla/common_options.txt
index a2f9c03810b9..b842f065c8f6 100644
--- a/Documentation/tools/rtla/common_options.txt
+++ b/Documentation/tools/rtla/common_options.txt
@@ -42,6 +42,8 @@
         - *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.
 
+        If not set, tracer threads keep their default priority. For rtla user threads, it is set to SCHED_FIFO with priority 95. For kernel threads, see *osnoise* and *timerlat* tracer documentation for the running kernel version.
+
 **-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.
-- 
2.51.0

[PATCH 7/9] Documentation/rtla: Mention default cgroup state

[Tomas Glozar]

The RTLA option -C/--cgroup is used to set a cgroup for workload
threads. This is either a specific cgroup, if passed an argument, or
rtla's cgroup, if no argument is given.

Expand the documentation of the -C option to also include the
information about the cgroup settings when the option is not specified.

Signed-off-by: Tomas Glozar <tglozar@redhat.com>
---
 Documentation/tools/rtla/common_options.txt | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/Documentation/tools/rtla/common_options.txt b/Documentation/tools/rtla/common_options.txt
index b842f065c8f6..26e94d291a70 100644
--- a/Documentation/tools/rtla/common_options.txt
+++ b/Documentation/tools/rtla/common_options.txt
@@ -48,6 +48,8 @@
 
         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.
 
+        If not set, the behavior differs between workload types. User workloads created by rtla will inherit rtla's cgroup. Kernel workloads are assigned the root cgroup.
+
 **--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.
-- 
2.51.0

[PATCH 8/9] Documentation/trace: Specify exact priority for timerlat

[Tomas Glozar]

The timerlat tracer documentation mentions that threads are created with
real-time priority, but does not mention which priority and scheduling
class is used.

Add the information so that users do not have to look it up in
trace_osnoise.c.

Signed-off-by: Tomas Glozar <tglozar@redhat.com>
---
 Documentation/trace/timerlat-tracer.rst | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/Documentation/trace/timerlat-tracer.rst b/Documentation/trace/timerlat-tracer.rst
index 53a56823e903..68d429d454a5 100644
--- a/Documentation/trace/timerlat-tracer.rst
+++ b/Documentation/trace/timerlat-tracer.rst
@@ -43,12 +43,12 @@ It is possible to follow the trace by reading the trace file::
            <...>-868     [001] ....    54.030347: #2     context thread timer_latency      4351 ns
 
 
-The tracer creates a per-cpu kernel thread with real-time priority that
-prints two lines at every activation. The first is the *timer latency*
-observed at the *hardirq* context before the activation of the thread.
-The second is the *timer latency* observed by the thread. The ACTIVATION
-ID field serves to relate the *irq* execution to its respective *thread*
-execution.
+The tracer creates a per-cpu kernel thread with real-time priority
+SCHED_FIFO:95 that prints two lines at every activation. The first is
+the *timer latency* observed at the *hardirq* context before the activation
+of the thread. The second is the *timer latency* observed by the thread.
+The ACTIVATION ID field serves to relate the *irq* execution to its
+respective *thread* execution.
 
 The *irq*/*thread* splitting is important to clarify in which context
 the unexpected high value is coming from. The *irq* context can be
-- 
2.51.0

[PATCH 9/9] Documentation/rtla: Include defaults for tracer options

[Tomas Glozar]

Commit 0122938a7ab4 ("rtla: Always set all tracer options") changed the
behavior of RTLA to always set all osnoise and timerlat tracer options
to default values taken from the tracers whenever an RTLA measurement
is started. The change was done to make RTLA results consistent on
subsequent runs of the same command.

Include the default values for tracer options also in documentation
where appropriate.

Signed-off-by: Tomas Glozar <tglozar@redhat.com>
---
 Documentation/tools/rtla/common_options.txt | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/tools/rtla/common_options.txt b/Documentation/tools/rtla/common_options.txt
index 26e94d291a70..1c4f3e663cf5 100644
--- a/Documentation/tools/rtla/common_options.txt
+++ b/Documentation/tools/rtla/common_options.txt
@@ -2,10 +2,14 @@
 
         Set the |tool| tracer to run the sample threads in the cpu-list.
 
+        By default, the |tool| tracer runs the sample threads on all CPUs.
+
 **-H**, **--house-keeping** *cpu-list*
 
         Run rtla control threads only on the given cpu-list.
 
+        If omitted, rtla will attempt to auto-migrate its main thread to any CPU that is not running any workload threads.
+
 **-d**, **--duration** *time[s|m|h|d]*
 
         Set the duration of the session.
@@ -57,6 +61,8 @@
 **--trace-buffer-size** *kB*
         Set the per-cpu trace buffer size in kB for the tracing output.
 
+        If not set, the default tracefs buffer size is used.
+
 **--on-threshold** *action*
 
         Defines an action to be executed when tracing is stopped on a latency threshold
-- 
2.51.0

Re: [PATCH 0/9] Documentation/rtla: Cover default options

[Jonathan Corbet]

Tomas Glozar <tglozar@redhat.com> writes:

> RTLA has many options that have a default value that is used when
> the option is not set associated with them. Those are not covered in
> the documentation for the options, which creates confusion among users.
>
> Document the default behavior for all relevant options: -H, -P, -C,
> --trace-buffer-size. Some of these are covered in general
> descriptions, only missing from the option documentation.
>
> Also, fix a few typos and incorrect naming of tracers.

So I see that this series is still unapplied...should I take it through
docs?

Thanks,

jon

Re: [PATCH 0/9] Documentation/rtla: Cover default options

[Steven Rostedt]

On Mon, 03 Nov 2025 16:35:32 -0700
Jonathan Corbet <corbet@lwn.net> wrote:

> Tomas Glozar <tglozar@redhat.com> writes:
> 
> > RTLA has many options that have a default value that is used when
> > the option is not set associated with them. Those are not covered in
> > the documentation for the options, which creates confusion among users.
> >
> > Document the default behavior for all relevant options: -H, -P, -C,
> > --trace-buffer-size. Some of these are covered in general
> > descriptions, only missing from the option documentation.
> >
> > Also, fix a few typos and incorrect naming of tracers.  
> 
> So I see that this series is still unapplied...should I take it through
> docs?

Yes please!

Acked-by: Steven Rostedt (Google) <rostedt@goodmis.org>

Thanks,

-- Steve

Re: [PATCH 0/9] Documentation/rtla: Cover default options

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 820 bytes --]

On Mon, Nov 03, 2025 at 04:35:32PM -0700, Jonathan Corbet wrote:
> Tomas Glozar <tglozar@redhat.com> writes:
> 
> > RTLA has many options that have a default value that is used when
> > the option is not set associated with them. Those are not covered in
> > the documentation for the options, which creates confusion among users.
> >
> > Document the default behavior for all relevant options: -H, -P, -C,
> > --trace-buffer-size. Some of these are covered in general
> > descriptions, only missing from the option documentation.
> >
> > Also, fix a few typos and incorrect naming of tracers.
> 
> So I see that this series is still unapplied...should I take it through
> docs?

Of course!

Acked-by: Bagas Sanjaya <bagasdotme@gmail.com>

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH 0/9] Documentation/rtla: Cover default options

[Jonathan Corbet]

Steven Rostedt <rostedt@goodmis.org> writes:

> On Mon, 03 Nov 2025 16:35:32 -0700
> Jonathan Corbet <corbet@lwn.net> wrote:
>
>> Tomas Glozar <tglozar@redhat.com> writes:
>> 
>> > RTLA has many options that have a default value that is used when
>> > the option is not set associated with them. Those are not covered in
>> > the documentation for the options, which creates confusion among users.
>> >
>> > Document the default behavior for all relevant options: -H, -P, -C,
>> > --trace-buffer-size. Some of these are covered in general
>> > descriptions, only missing from the option documentation.
>> >
>> > Also, fix a few typos and incorrect naming of tracers.  
>> 
>> So I see that this series is still unapplied...should I take it through
>> docs?
>
> Yes please!
>
> Acked-by: Steven Rostedt (Google) <rostedt@goodmis.org>

OK, I have done that.

Thanks,

jon