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

From: Steven Rostedt
Date: Sat Dec 09 2023 - 23:05:10 EST


From: "Steven Rostedt (Google)" <rostedt@xxxxxxxxxxx>

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) <rostedt@xxxxxxxxxxx>
---
Documentation/trace/ftrace.rst | 27 +++++++++++++++++++++++++++
1 file changed, 27 insertions(+)

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
--
2.42.0