History

ring-buffer: document reader page design

In a private email conversation I explained how the ring buffer page worked by using silly ASCII art. Ingo suggested that I add that to the comments of the code. Here it is.

Steven Rostedt committed 17 years ago

Commit 5cc98541 parent f28e5571 file · +68 −0Browse files

Unified · Split

kernel/trace/ring_buffer.c+68−0
@@ -21,6 +21,74 @@ · 20 unmodified lines
2121
2222 #include "trace.h"
2323
24+/*
25+ * The ring buffer is made up of a list of pages. A separate list of pages is
26+ * allocated for each CPU. A writer may only write to a buffer that is
27+ * associated with the CPU it is currently executing on. A reader may read
28+ * from any per cpu buffer.
29+ *
30+ * The reader is special. For each per cpu buffer, the reader has its own
31+ * reader page. When a reader has read the entire reader page, this reader
32+ * page is swapped with another page in the ring buffer.
33+ *
34+ * Now, as long as the writer is off the reader page, the reader can do what
35+ * ever it wants with that page. The writer will never write to that page
36+ * again (as long as it is out of the ring buffer).
37+ *
38+ * Here's some silly ASCII art.
39+ *
40+ * +------+
41+ * |reader| RING BUFFER
42+ * |page |
43+ * +------+ +---+ +---+ +---+
44+ * | |-->| |-->| |
45+ * +---+ +---+ +---+
46+ * ^ |
47+ * | |
48+ * +---------------+
49+ *
50+ *
51+ * +------+
52+ * |reader| RING BUFFER
53+ * |page |------------------v
54+ * +------+ +---+ +---+ +---+
55+ * | |-->| |-->| |
56+ * +---+ +---+ +---+
57+ * ^ |
58+ * | |
59+ * +---------------+
60+ *
61+ *
62+ * +------+
63+ * |reader| RING BUFFER
64+ * |page |------------------v
65+ * +------+ +---+ +---+ +---+
66+ * ^ | |-->| |-->| |
67+ * | +---+ +---+ +---+
68+ * | |
69+ * | |
70+ * +------------------------------+
71+ *
72+ *
73+ * +------+
74+ * |buffer| RING BUFFER
75+ * |page |------------------v
76+ * +------+ +---+ +---+ +---+
77+ * ^ | | | |-->| |
78+ * | New +---+ +---+ +---+
79+ * | Reader------^ |
80+ * | page |
81+ * +------------------------------+
82+ *
83+ *
84+ * After we make this swap, the reader can hand this page off to the splice
85+ * code and be done with it. It can even allocate a new page if it needs to
86+ * and swap that into the ring buffer.
87+ *
88+ * We will be using cmpxchg soon to make all this lockless.
89+ *
90+ */
91+
2492 /*
2593 * A fast way to enable or disable all ring buffers is to
2694 * call tracing_on or tracing_off. Turning off the ring buffers