[13/14] ring-buffer: Add documentation on the buffer_subbuf_order file

Commit Message

Steven Rostedt Dec. 10, 2023, 3:54 a.m. UTC

From: "Steven Rostedt (Google)" <[e-mail]>

Add to the documentation how to use the buffer_subbuf_order file to change
the size and how it affects what events can be added to the ring buffer.

Signed-off-by: Steven Rostedt (Google) <[e-mail]>
---
 Documentation/trace/ftrace.rst | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

Comments

Mathieu Desnoyers Dec. 10, 2023, 2:28 p.m. UTC | #1

On 2023-12-09 22:54, Steven Rostedt wrote:
[...]
> +  buffer_subbuf_order:
> +
> +	This sets or displays the sub buffer page size order. The ring buffer
> +	is broken up into several same size "sub buffers". An event can not be
> +	bigger than the size of the sub buffer. Normally, the sub buffer is
> +	the size of the architecture's page (4K on x86). The sub buffer also
> +	contains meta data at the start which also limits the size of an event.
> +	That means when the sub buffer is a page size, no event can be larger
> +	than the page size minus the sub buffer meta data.

The fact that the user ABI documentation for this tracer parameter needs
to dig into details about architecture page size is a good indicator
that this ABI is not at the abstraction level it should be (pages vs
bytes).

Thanks,

Mathieu

> +
> +	The buffer_subbuf_order allows the user to change the size of the sub
> +	buffer. As the sub buffer is a set of pages by the power of 2, thus
> +	the sub buffer total size is defined by the order:
> +
> +	order		size
> +	----		----
> +	0		PAGE_SIZE
> +	1		PAGE_SIZE * 2
> +	2		PAGE_SIZE * 4
> +	3		PAGE_SIZE * 8
> +
> +	Changing the order will change the sub buffer size allowing for events
> +	to be larger than the page size.
> +
> +	Note: When changing the order, tracing is stopped and any data in the
> +	ring buffer and the snapshot buffer will be discarded.
> +
>     free_buffer:
>   
>   	If a process is performing tracing, and the ring buffer	should be

Patch

diff --git a/Documentation/trace/ftrace.rst b/Documentation/trace/ftrace.rst
index 23572f6697c0..231d26ceedb0 100644
--- a/Documentation/trace/ftrace.rst
+++ b/Documentation/trace/ftrace.rst
@@ -203,6 +203,33 @@  of ftrace. Here is a list of some of the key files:
 
 	This displays the total combined size of all the trace buffers.
 
+  buffer_subbuf_order:
+
+	This sets or displays the sub buffer page size order. The ring buffer
+	is broken up into several same size "sub buffers". An event can not be
+	bigger than the size of the sub buffer. Normally, the sub buffer is
+	the size of the architecture's page (4K on x86). The sub buffer also
+	contains meta data at the start which also limits the size of an event.
+	That means when the sub buffer is a page size, no event can be larger
+	than the page size minus the sub buffer meta data.
+
+	The buffer_subbuf_order allows the user to change the size of the sub
+	buffer. As the sub buffer is a set of pages by the power of 2, thus
+	the sub buffer total size is defined by the order:
+
+	order		size
+	----		----
+	0		PAGE_SIZE
+	1		PAGE_SIZE * 2
+	2		PAGE_SIZE * 4
+	3		PAGE_SIZE * 8
+
+	Changing the order will change the sub buffer size allowing for events
+	to be larger than the page size.
+
+	Note: When changing the order, tracing is stopped and any data in the
+	ring buffer and the snapshot buffer will be discarded.
+
   free_buffer:
 
 	If a process is performing tracing, and the ring buffer	should be