[PATCH] rtla: clarify trace option syntax in documentation and usage help

[PATCH] rtla: clarify trace option syntax in documentation and usage help

[Ivan Pravdin]

When using `rtla timerlat {top,hist}`, the `-t/--trace` option is
optional. However, when providing a filename, the long option requires
an equal sign (`=`), i.e., `--trace=<file>`. This is because the
command-line parser treats `--trace` without `=` as a flag with no
value, leading to unexpected behavior.

Valid usage:
    - `-t[file]`
    - `-t=[file]`
    - `--trace=[file]`

Invalid usage:
    - `-t [file]`
    - `--trace [file]`

Clarify valid usage in documentation and help message.

Signed-off-by: Ivan Pravdin <ipravdin.official@gmail.com>
---
 Documentation/tools/rtla/common_osnoise_options.rst  | 2 +-
 Documentation/tools/rtla/common_timerlat_options.rst | 2 +-
 tools/tracing/rtla/src/timerlat_hist.c               | 2 +-
 tools/tracing/rtla/src/timerlat_top.c                | 2 +-
 4 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/tools/rtla/common_osnoise_options.rst b/Documentation/tools/rtla/common_osnoise_options.rst
index d73de2d58f5f..0b73a55f1d1f 100644
--- a/Documentation/tools/rtla/common_osnoise_options.rst
+++ b/Documentation/tools/rtla/common_osnoise_options.rst
@@ -26,6 +26,6 @@
         Specify the minimum delta between two time reads to be considered noise.
         The default threshold is *5 us*.
 
-**-t**, **--trace** \[*file*]
+**-t**, **--trace**=\[*file*]
 
         Save the stopped trace to [*file|osnoise_trace.txt*].
diff --git a/Documentation/tools/rtla/common_timerlat_options.rst b/Documentation/tools/rtla/common_timerlat_options.rst
index 10dc802f8d65..8d55b590c7d0 100644
--- a/Documentation/tools/rtla/common_timerlat_options.rst
+++ b/Documentation/tools/rtla/common_timerlat_options.rst
@@ -22,7 +22,7 @@
         Save the stack trace at the *IRQ* if a *Thread* latency is higher than the
         argument in us.
 
-**-t**, **--trace** \[*file*]
+**-t**, **--trace**=\[*file*]
 
         Save the stopped trace to [*file|timerlat_trace.txt*].
 
diff --git a/tools/tracing/rtla/src/timerlat_hist.c b/tools/tracing/rtla/src/timerlat_hist.c
index 36d2294c963d..b6e1275b0e71 100644
--- a/tools/tracing/rtla/src/timerlat_hist.c
+++ b/tools/tracing/rtla/src/timerlat_hist.c
@@ -730,7 +730,7 @@ static void timerlat_hist_usage(char *usage)
 		"	  -d/--duration time[m|h|d]: duration of the session in seconds",
 		"	     --dump-tasks: prints the task running on all CPUs if stop conditions are met (depends on !--no-aa)",
 		"	  -D/--debug: print debug info",
-		"	  -t/--trace[file]: save the stopped trace to [file|timerlat_trace.txt]",
+		"	  -t/--trace=[file]: save the stopped trace to [file|timerlat_trace.txt]",
 		"	  -e/--event <sys:event>: enable the <sys:event> in the trace instance, multiple -e are allowed",
 		"	     --filter <filter>: enable a trace event filter to the previous -e event",
 		"	     --trigger <trigger>: enable a trace event trigger to the previous -e event",
diff --git a/tools/tracing/rtla/src/timerlat_top.c b/tools/tracing/rtla/src/timerlat_top.c
index 7365e08fe986..19ee98456e3f 100644
--- a/tools/tracing/rtla/src/timerlat_top.c
+++ b/tools/tracing/rtla/src/timerlat_top.c
@@ -496,7 +496,7 @@ static void timerlat_top_usage(char *usage)
 		"	  -d/--duration time[s|m|h|d]: duration of the session",
 		"	  -D/--debug: print debug info",
 		"	     --dump-tasks: prints the task running on all CPUs if stop conditions are met (depends on !--no-aa)",
-		"	  -t/--trace[file]: save the stopped trace to [file|timerlat_trace.txt]",
+		"	  -t/--trace=[file]: save the stopped trace to [file|timerlat_trace.txt]",
 		"	  -e/--event <sys:event>: enable the <sys:event> in the trace instance, multiple -e are allowed",
 		"	     --filter <command>: enable a trace event filter to the previous -e event",
 		"	     --trigger <command>: enable a trace event trigger to the previous -e event",
-- 
2.45.2

Re: [PATCH] rtla: clarify trace option syntax in documentation and usage help

[Steven Rostedt]

On Tue, 22 Jul 2025 21:52:33 -0400
Ivan Pravdin <ipravdin.official@gmail.com> wrote:

> When using `rtla timerlat {top,hist}`, the `-t/--trace` option is
> optional. However, when providing a filename, the long option requires
> an equal sign (`=`), i.e., `--trace=<file>`. This is because the
> command-line parser treats `--trace` without `=` as a flag with no
> value, leading to unexpected behavior.
> 
> Valid usage:
>     - `-t[file]`
>     - `-t=[file]`
>     - `--trace=[file]`
> 
> Invalid usage:
>     - `-t [file]`
>     - `--trace [file]`

I wonder if the better fix would be to make the above valid?

-- Steve


> 
> Clarify valid usage in documentation and help message.
> 
> Signed-off-by: Ivan Pravdin <ipravdin.official@gmail.com>

Re: [PATCH] rtla: clarify trace option syntax in documentation and usage help

[Tomas Glozar]

čt 24. 7. 2025 v 15:59 odesílatel Steven Rostedt <rostedt@goodmis.org> napsal:
>
> On Tue, 22 Jul 2025 21:52:33 -0400
> Ivan Pravdin <ipravdin.official@gmail.com> wrote:
> > Valid usage:
> >     - `-t[file]`
> >     - `-t=[file]`
> >     - `--trace=[file]`
> >
> > Invalid usage:
> >     - `-t [file]`
> >     - `--trace [file]`
>
> I wonder if the better fix would be to make the above valid?
>

Definitely. There is also another case where only = syntax is
accepted,  C/--cgroup. In my opinion, both are confusing, and both
should accept = as well as space. I even had some trouble with the
latter as it fails to parse silently and looks like the cgroup setting
code is not working.

Tomas