Documentation/trace/ring-buffer-design.rst

44 	- a pointer to the page that the reader will use next
47 	- a pointer to the page that will be written to next
74 will stop writing to the buffer. This will lose most recent events.
77 before the consumer could free up anything, the producer will
78 overwrite the older data. This will lose the oldest events.
123 it will swap its page with the head_page. The old reader page will
124 become part of the ring buffer and the head_page will be removed.
125 The page after the inserted page (old reader_page) will become the
224 	    - the next page in the ring buffer that will be swapped
228 	    - the page where the next write will take place.
234 writer stack. A writer that preempts another writer will not move the
308 and will not be a full commit until all writes have been committed.
341 and a reader swaps out a page, it will be swapping out the commit page.
364 In this case, the head page will not move when the tail and commit
373 the head page will be pushed ahead one. If the buffer is in producer/consumer
374 mode, the write will fail.
413 Note, the reader page will still point to the previous head page.
414 But when a swap takes place, it will use the most recent head page.
423 each page must be aligned in memory by 4 bytes. This will allow the 2
425 they will always be zero for the address. To get the address,
432 Two flags will be kept by these two bits:
461 When the tail page meets the head pointer, it will use cmpxchg to
483 Any access to the reader will need to take some sort of lock to serialize
484 the readers. But the writers will never take a lock to write to the
489 will also use cmpxchg. If the flag bit in the pointer to the
490 head page does not have the HEADER flag set, the compare will fail
491 and the reader will need to look for the new head page and try again.
575 will always stay in the ring buffer. Traversing the ring buffer via the
599 flag to have the UPDATE flag set. Once this is done, the reader will
600 not be able to swap the head page from the buffer, nor will it be able to
622 The following page will be made into the new head page::
692 This means that the commit will not move while a writer is moving the
696 it will never go back on it unless a reader does another swap with the
714 The above will update the tail page if it is still pointing to the expected
742 been moved forward, the writer will just try again to reserve storage
765 But if a nested writer preempts here, it will see that the next
766 page is a head page, but it is also nested. It will detect that
767 it is nested and will save that information. The detection is the
771 The nested writer will set the new head page pointer::
781 But it will not reset the update back to normal. Only the writer
782 that converted a pointer from HEAD to UPDATE will convert it back
793 After the nested writer finishes, the outermost writer will convert
867 The writer will move the head page forward::
881 will convert it to normal::
895 Then it will move the tail page, and return back to the second writer::
909 The second writer will fail to move the tail page because it was already
910 moved, so it will try again and add its data to the new tail page.
911 It will return to the first writer::
925 while it updates the HEAD page. It will then update the head page to
940 will see it succeeded in updating the pointer from NORMAL to HEAD.