ring-buffer: Add documentation on the buffer_subbuf_order file

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.

Link: https://lore.kernel.org/linux-trace-kernel/20231219185631.230636734@goodmis.org
Cc: Masami Hiramatsu <mhiramat@kernel.org>
Cc: Mark Rutland <mark.rutland@arm.com>
Cc: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
Cc: Andrew Morton <akpm@linux-foundation.org>
Cc: Tzvetomir Stoyanov <tz.stoyanov@gmail.com>
Cc: Vincent Donnefort <vdonnefort@google.com>
Cc: Kent Overstreet <kent.overstreet@gmail.com>
Signed-off-by: Steven Rostedt (Google) <rostedt@goodmis.org>

diff --git a/Documentation/trace/ftrace.rst b/Documentation/trace/ftrace.rst
index 23572f6697c0abee8c69d63d2212ca5f0572832f..231d26ceedb05c138bc088d620490b11970369dd 100644 (file)
--- 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