[PATCH v2] ring-buffer/Documentation: Add documentation on buffer_percent file

[PATCH v2] ring-buffer/Documentation: Add documentation on buffer_percent file

[Steven Rostedt]

From: "Steven Rostedt (Google)" <rostedt@goodmis.org>

When the buffer_percent file was added to the kernel, the documentation
should have been updated to document what that file does.

Fixes: 03329f9939781 ("tracing: Add tracefs file buffer_percentage")
Signed-off-by: Steven Rostedt (Google) <rostedt@goodmis.org>
---
Changes since v1: https://lore.kernel.org/all/20231226123525.71a6d0fb@gandalf.local.home/

- Fixed some grammar issues.

 Documentation/trace/ftrace.rst | 15 +++++++++++++++
 1 file changed, 15 insertions(+)

diff --git a/Documentation/trace/ftrace.rst b/Documentation/trace/ftrace.rst
index 933e7efb9f1b..84b810a6cf76 100644
--- a/Documentation/trace/ftrace.rst
+++ b/Documentation/trace/ftrace.rst
@@ -180,6 +180,21 @@ of ftrace. Here is a list of some of the key files:
 	Only active when the file contains a number greater than 0.
 	(in microseconds)
 
+  buffer_percent:
+
+	This is the water-mark for how much the ring buffer needs to be filled
+	before a waiter is woken up. That is, if an application calls a
+	blocking read syscall on one of the per_cpu trace_pipe_raw files, it
+	will block until the given amount of data specified by buffer_percent
+	is in the ring buffer before it wakes the reader up. This also
+	controls how the splice system calls are blocked on this file.
+
+	0   - means to wake up as soon as there is any data in the ring buffer.
+	50  - means to wake up when roughly half of the ring buffer sub-buffers
+	      are full.
+	100 - means to block until the ring buffer is totally full and is
+	      about to start overwriting the older data.
+
   buffer_size_kb:
 
 	This sets or displays the number of kilobytes each CPU
-- 
2.42.0

Re: [PATCH v2] ring-buffer/Documentation: Add documentation on buffer_percent file

[Randy Dunlap]

On 12/26/23 10:01, Steven Rostedt wrote:
> From: "Steven Rostedt (Google)" <rostedt@goodmis.org>
> 
> When the buffer_percent file was added to the kernel, the documentation
> should have been updated to document what that file does.
> 
> Fixes: 03329f9939781 ("tracing: Add tracefs file buffer_percentage")
> Signed-off-by: Steven Rostedt (Google) <rostedt@goodmis.org>
> ---
> Changes since v1: https://lore.kernel.org/all/20231226123525.71a6d0fb@gandalf.local.home/
> 
> - Fixed some grammar issues.
> 
>  Documentation/trace/ftrace.rst | 15 +++++++++++++++
>  1 file changed, 15 insertions(+)
> 
> diff --git a/Documentation/trace/ftrace.rst b/Documentation/trace/ftrace.rst
> index 933e7efb9f1b..84b810a6cf76 100644
> --- a/Documentation/trace/ftrace.rst
> +++ b/Documentation/trace/ftrace.rst
> @@ -180,6 +180,21 @@ of ftrace. Here is a list of some of the key files:
>  	Only active when the file contains a number greater than 0.
>  	(in microseconds)
>  
> +  buffer_percent:
> +
> +	This is the water-mark for how much the ring buffer needs to be filled

                    watermark
please

> +	before a waiter is woken up. That is, if an application calls a
> +	blocking read syscall on one of the per_cpu trace_pipe_raw files, it
> +	will block until the given amount of data specified by buffer_percent
> +	is in the ring buffer before it wakes the reader up. This also
> +	controls how the splice system calls are blocked on this file.
> +
> +	0   - means to wake up as soon as there is any data in the ring buffer.
> +	50  - means to wake up when roughly half of the ring buffer sub-buffers
> +	      are full.
> +	100 - means to block until the ring buffer is totally full and is
> +	      about to start overwriting the older data.
> +
>    buffer_size_kb:
>  
>  	This sets or displays the number of kilobytes each CPU

-- 
#Randy
https://people.kernel.org/tglx/notes-about-netiquette
https://subspace.kernel.org/etiquette.html

Re: [PATCH v2] ring-buffer/Documentation: Add documentation on buffer_percent file

[Jonathan Corbet]

Steven Rostedt <rostedt@goodmis.org> writes:

> From: "Steven Rostedt (Google)" <rostedt@goodmis.org>
>
> When the buffer_percent file was added to the kernel, the documentation
> should have been updated to document what that file does.
>
> Fixes: 03329f9939781 ("tracing: Add tracefs file buffer_percentage")
> Signed-off-by: Steven Rostedt (Google) <rostedt@goodmis.org>
> ---
> Changes since v1: https://lore.kernel.org/all/20231226123525.71a6d0fb@gandalf.local.home/
>
> - Fixed some grammar issues.
>
>  Documentation/trace/ftrace.rst | 15 +++++++++++++++
>  1 file changed, 15 insertions(+)

Are you planning on shipping this one upstream, or would you like me to
pick it up?

Thanks,

jon

Re: [PATCH v2] ring-buffer/Documentation: Add documentation on buffer_percent file

[Steven Rostedt]

On Wed, 03 Jan 2024 14:15:30 -0700
Jonathan Corbet <corbet@lwn.net> wrote:

> Steven Rostedt <rostedt@goodmis.org> writes:
> 
> > From: "Steven Rostedt (Google)" <rostedt@goodmis.org>
> >
> > When the buffer_percent file was added to the kernel, the documentation
> > should have been updated to document what that file does.
> >
> > Fixes: 03329f9939781 ("tracing: Add tracefs file buffer_percentage")
> > Signed-off-by: Steven Rostedt (Google) <rostedt@goodmis.org>
> > ---
> > Changes since v1: https://lore.kernel.org/all/20231226123525.71a6d0fb@gandalf.local.home/
> >
> > - Fixed some grammar issues.
> >
> >  Documentation/trace/ftrace.rst | 15 +++++++++++++++
> >  1 file changed, 15 insertions(+)  
> 
> Are you planning on shipping this one upstream, or would you like me to
> pick it up?

I was hoping you can take it, but please take v3.

  https://lore.kernel.org/all/20231229122402.537eb252@gandalf.local.home/

Thanks!

-- Steve

Re: [PATCH v2] ring-buffer/Documentation: Add documentation on buffer_percent file

[Jonathan Corbet]

Steven Rostedt <rostedt@goodmis.org> writes:

> On Wed, 03 Jan 2024 14:15:30 -0700
> Jonathan Corbet <corbet@lwn.net> wrote:
>
>> Steven Rostedt <rostedt@goodmis.org> writes:
>> 
>> > From: "Steven Rostedt (Google)" <rostedt@goodmis.org>
>> >
>> > When the buffer_percent file was added to the kernel, the documentation
>> > should have been updated to document what that file does.
>> >
>> > Fixes: 03329f9939781 ("tracing: Add tracefs file buffer_percentage")
>> > Signed-off-by: Steven Rostedt (Google) <rostedt@goodmis.org>
>> > ---
>> > Changes since v1: https://lore.kernel.org/all/20231226123525.71a6d0fb@gandalf.local.home/
>> >
>> > - Fixed some grammar issues.
>> >
>> >  Documentation/trace/ftrace.rst | 15 +++++++++++++++
>> >  1 file changed, 15 insertions(+)  
>> 
>> Are you planning on shipping this one upstream, or would you like me to
>> pick it up?
>
> I was hoping you can take it, but please take v3.
>
>   https://lore.kernel.org/all/20231229122402.537eb252@gandalf.local.home/

Yep, will do.

Thanks,

jon