[PATCH 0/4] Documentation/rtla: Cover BPF sample collection

[PATCH 0/4] Documentation/rtla: Cover BPF sample collection

[Tomas Glozar]

This is a follow-up to the BPF sample collection patchset [1],
documenting both the feature's build requirements in the readme and
the feature itself in the manpages.

A few fixes affecting the same manpages are also included in
the patchset.

[1] https://lore.kernel.org/linux-trace-kernel/20250218145859.27762-1-tglozar@redhat.com/T/#u

Tomas Glozar (4):
  Documentation/rtla: Fix duplicate text about timerlat tracer
  Documentation/rtla: Fix typo in rtla-timerlat.rst
  Documentation/rtla: Fix typo in common_timerlat_description.rst
  Documentation/rtla: Include BPF sample collection

 .../tools/rtla/common_timerlat_description.rst         | 10 +++++++++-
 Documentation/tools/rtla/rtla-timerlat.rst             |  9 +++------
 tools/tracing/rtla/README.txt                          |  7 +++++++
 3 files changed, 19 insertions(+), 7 deletions(-)

-- 
2.48.1

[PATCH 1/4] Documentation/rtla: Fix duplicate text about timerlat tracer

[Tomas Glozar]

A passage about how the timerlat tracer outputs information is included
in both common_timerlat_description.rst and rtla-timerlat.rst, leading
it to be displayed twice in the rtla-timerlat page.

Remove the duplicate passage from rtla-timerlat.rst.

Fixes: 29380d4055e5 ("rtla: Add rtla timerlat documentation")
Signed-off-by: Tomas Glozar <tglozar@redhat.com>
---
 Documentation/tools/rtla/rtla-timerlat.rst | 3 ---
 1 file changed, 3 deletions(-)

diff --git a/Documentation/tools/rtla/rtla-timerlat.rst b/Documentation/tools/rtla/rtla-timerlat.rst
index 44a49e6f302b..b334fb00ba0e 100644
--- a/Documentation/tools/rtla/rtla-timerlat.rst
+++ b/Documentation/tools/rtla/rtla-timerlat.rst
@@ -16,9 +16,6 @@ DESCRIPTION
 
 .. include:: common_timerlat_description.rst
 
-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 provides information for each noise via the **osnoise:** tracepoints.
 The **rtla timerlat top** mode displays a summary of the periodic output
 from the *timerlat* tracer. The **rtla hist hist** mode displays a histogram
 of each tracer event occurrence. For further details, please refer to the
-- 
2.48.1

[PATCH 2/4] Documentation/rtla: Fix typo in rtla-timerlat.rst

[Tomas Glozar]

The file says "rtla hist hist mode" instead of "rtla timerlat hist
mode".

Fix the typo.

Fixes: 29380d4055e5 ("rtla: Add rtla timerlat documentation")
Signed-off-by: Tomas Glozar <tglozar@redhat.com>
---
 Documentation/tools/rtla/rtla-timerlat.rst | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/Documentation/tools/rtla/rtla-timerlat.rst b/Documentation/tools/rtla/rtla-timerlat.rst
index b334fb00ba0e..20e2d259467f 100644
--- a/Documentation/tools/rtla/rtla-timerlat.rst
+++ b/Documentation/tools/rtla/rtla-timerlat.rst
@@ -17,9 +17,9 @@ DESCRIPTION
 .. include:: common_timerlat_description.rst
 
 The **rtla timerlat top** mode displays a summary of the periodic output
-from the *timerlat* tracer. The **rtla hist hist** mode displays a histogram
-of each tracer event occurrence. For further details, please refer to the
-respective man page.
+from the *timerlat* tracer. The **rtla timerlat hist** mode displays
+a histogram of each tracer event occurrence. For further details, please
+refer to the respective man page.
 
 MODES
 =====
-- 
2.48.1

[PATCH 3/4] Documentation/rtla: Fix typo in common_timerlat_description.rst

[Tomas Glozar]

Fix "it enable" to "it enables".

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

diff --git a/Documentation/tools/rtla/common_timerlat_description.rst b/Documentation/tools/rtla/common_timerlat_description.rst
index 321201cb8597..8cd3e717baa8 100644
--- a/Documentation/tools/rtla/common_timerlat_description.rst
+++ b/Documentation/tools/rtla/common_timerlat_description.rst
@@ -6,5 +6,5 @@ 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 enable the trace of the most relevant information via
+handler. It also enables the trace of the most relevant information via
 **osnoise:** tracepoints.
-- 
2.48.1

[PATCH 4/4] Documentation/rtla: Include BPF sample collection

[Tomas Glozar]

Add dependencies needed to build rtla with BPF sample collection support
to README, and document both ways of sample collection in the manpages.

Signed-off-by: Tomas Glozar <tglozar@redhat.com>
---
 Documentation/tools/rtla/common_timerlat_description.rst | 8 ++++++++
 tools/tracing/rtla/README.txt                            | 7 +++++++
 2 files changed, 15 insertions(+)

diff --git a/Documentation/tools/rtla/common_timerlat_description.rst b/Documentation/tools/rtla/common_timerlat_description.rst
index 8cd3e717baa8..49fcae3ffdec 100644
--- a/Documentation/tools/rtla/common_timerlat_description.rst
+++ b/Documentation/tools/rtla/common_timerlat_description.rst
@@ -8,3 +8,11 @@ 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/tools/tracing/rtla/README.txt b/tools/tracing/rtla/README.txt
index dd5621038c55..43e98311d10f 100644
--- a/tools/tracing/rtla/README.txt
+++ b/tools/tracing/rtla/README.txt
@@ -13,6 +13,13 @@ RTLA depends on the following libraries and tools:
  - libtraceevent
  - libcpupower (optional, for --deepest-idle-state)
 
+For BPF sample collection support, the following extra dependencies are
+required:
+
+ - libbpf 1.0.0 or later
+ - bpftool with skeleton support
+ - clang with BPF CO-RE support
+
 It also depends on python3-docutils to compile man pages.
 
 For development, we suggest the following steps for compiling rtla:
-- 
2.48.1

Re: [PATCH 4/4] Documentation/rtla: Include BPF sample collection

[Luis Claudio R. Goncalves]

On Tue, Mar 11, 2025 at 12:49:36PM +0100, Tomas Glozar wrote:
> Add dependencies needed to build rtla with BPF sample collection support
> to README, and document both ways of sample collection in the manpages.
> 
> Signed-off-by: Tomas Glozar <tglozar@redhat.com>
> ---
>  Documentation/tools/rtla/common_timerlat_description.rst | 8 ++++++++
>  tools/tracing/rtla/README.txt                            | 7 +++++++
>  2 files changed, 15 insertions(+)
> 
> diff --git a/Documentation/tools/rtla/common_timerlat_description.rst b/Documentation/tools/rtla/common_timerlat_description.rst
> index 8cd3e717baa8..49fcae3ffdec 100644
> --- a/Documentation/tools/rtla/common_timerlat_description.rst
> +++ b/Documentation/tools/rtla/common_timerlat_description.rst
> @@ -8,3 +8,11 @@ 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

In the last phrase, s/is/are/. So that "If either... or... are unavailable".

Luis

> +unavailable, the **rtla timerlat** tool falls back to using tracefs to
> +process the data asynchronously in user space.
> diff --git a/tools/tracing/rtla/README.txt b/tools/tracing/rtla/README.txt
> index dd5621038c55..43e98311d10f 100644
> --- a/tools/tracing/rtla/README.txt
> +++ b/tools/tracing/rtla/README.txt
> @@ -13,6 +13,13 @@ RTLA depends on the following libraries and tools:
>   - libtraceevent
>   - libcpupower (optional, for --deepest-idle-state)
>  
> +For BPF sample collection support, the following extra dependencies are
> +required:
> +
> + - libbpf 1.0.0 or later
> + - bpftool with skeleton support
> + - clang with BPF CO-RE support
> +
>  It also depends on python3-docutils to compile man pages.
>  
>  For development, we suggest the following steps for compiling rtla:
> -- 
> 2.48.1
> 
---end quoted text---

Re: [PATCH 0/4] Documentation/rtla: Cover BPF sample collection

[Luis Claudio R. Goncalves]

On Tue, Mar 11, 2025 at 12:49:32PM +0100, Tomas Glozar wrote:
> This is a follow-up to the BPF sample collection patchset [1],
> documenting both the feature's build requirements in the readme and
> the feature itself in the manpages.
> 
> A few fixes affecting the same manpages are also included in
> the patchset.
> 
> [1] https://lore.kernel.org/linux-trace-kernel/20250218145859.27762-1-tglozar@redhat.com/T/#u

LGTM.

Reviewed-by: Luis Claudio R. Goncalves <lgoncalv@redhat.com>

 
> Tomas Glozar (4):
>   Documentation/rtla: Fix duplicate text about timerlat tracer
>   Documentation/rtla: Fix typo in rtla-timerlat.rst
>   Documentation/rtla: Fix typo in common_timerlat_description.rst
>   Documentation/rtla: Include BPF sample collection
> 
>  .../tools/rtla/common_timerlat_description.rst         | 10 +++++++++-
>  Documentation/tools/rtla/rtla-timerlat.rst             |  9 +++------
>  tools/tracing/rtla/README.txt                          |  7 +++++++
>  3 files changed, 19 insertions(+), 7 deletions(-)
> 
> -- 
> 2.48.1
> 
---end quoted text---

Re: [PATCH 4/4] Documentation/rtla: Include BPF sample collection

[Tomas Glozar]

út 11. 3. 2025 v 14:07 odesílatel Luis Claudio R. Goncalves
<lgoncalv@redhat.com> napsal:
>
> In the last phrase, s/is/are/. So that "If either... or... are unavailable".
>
> Luis
>

All references I found on this topic say the verb should be singular
(since both "BPF" and "the osnoise:timerlat_sample tracepoint" are
singular). Search for "either or subject verb agreement", e.g. [1].

[1] https://www.englishgrammar.org/subjectverb-agreement-2/

Tomas

Re: [PATCH 4/4] Documentation/rtla: Include BPF sample collection

[Jonathan Corbet]

Tomas Glozar <tglozar@redhat.com> writes:

> út 11. 3. 2025 v 14:07 odesílatel Luis Claudio R. Goncalves
> <lgoncalv@redhat.com> napsal:
>>
>> In the last phrase, s/is/are/. So that "If either... or... are unavailable".
>>
>> Luis
>>
>
> All references I found on this topic say the verb should be singular
> (since both "BPF" and "the osnoise:timerlat_sample tracepoint" are
> singular). Search for "either or subject verb agreement", e.g. [1].
>
> [1] https://www.englishgrammar.org/subjectverb-agreement-2/

I concur with that reasoning, FWIW.

What is the intended path to get this one upstream; should I take it?

Thanks,

jon

Re: [PATCH 4/4] Documentation/rtla: Include BPF sample collection

[Steven Rostedt]

On Mon, 17 Mar 2025 16:47:41 -0600
Jonathan Corbet <corbet@lwn.net> wrote:

> What is the intended path to get this one upstream; should I take it?

Hi Jon,

Yes, can you take this through your tree?

You can add:

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


Thanks!

-- Steve

Re: [PATCH 4/4] Documentation/rtla: Include BPF sample collection

[Jonathan Corbet]

Steven Rostedt <rostedt@goodmis.org> writes:

> On Mon, 17 Mar 2025 16:47:41 -0600
> Jonathan Corbet <corbet@lwn.net> wrote:
>
>> What is the intended path to get this one upstream; should I take it?
>
> Hi Jon,
>
> Yes, can you take this through your tree?
>
> You can add:
>
>  Acked-by: Steven Rostedt (Google) <rostedt@goodmis.org>

...and I have finally done that ...

Thanks,

jon