Commit ea70a962 authored by Petr Pavlu's avatar Petr Pavlu Committed by Steven Rostedt (Google)
Browse files

ring-buffer: Correct stale comments related to non-consuming readers 

Adjust the following code documentation:

* Kernel-doc comments for ring_buffer_read_prepare() and
  ring_buffer_read_finish() mention that recording to the ring buffer is
  disabled when the read is active. Remove mention of this restriction
  because it was already lifted in commit 1039221c ("ring-buffer: Do
  not disable recording when there is an iterator").

* Function ring_buffer_read_finish() performs a self-check of the
  ring-buffer by locking cpu_buffer->reader_lock and then calling
  rb_check_pages(). The preceding comment explains that the lock is
  needed because rb_check_pages() clears the HEAD flag required by
  readers which might be running in parallel. Remove this explanation
  because commit 8843e06f ("ring-buffer: Handle race between
  rb_move_tail and rb_check_pages") simplified the function so it no
  longer resets the mentioned flag. Nonetheless, the lock is still
  needed because a reader swapping a page into the ring buffer can make
  the underlying doubly-linked list temporarily inconsistent.

This is a non-functional change.

Link: https://lore.kernel.org/linux-trace-kernel/20240517134008.24529-2-petr.pavlu@suse.com



Cc: Masami Hiramatsu <mhiramat@kernel.org>
Cc: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
Signed-off-by: default avatarPetr Pavlu <petr.pavlu@suse.com>
Signed-off-by: default avatarSteven Rostedt (Google) <rostedt@goodmis.org>
parent fa3889d9

kernel/trace/ring_buffer.c

+3 −13
Original line number Diff line number Diff line
@@ -5046,13 +5046,9 @@ EXPORT_SYMBOL_GPL(ring_buffer_consume); 
 * @flags: gfp flags to use for memory allocation

 *

 * This performs the initial preparations necessary to iterate

 * through the buffer.  Memory is allocated, buffer recording

 * through the buffer.  Memory is allocated, buffer resizing

 * is disabled, and the iterator pointer is returned to the caller.

 *

 * Disabling buffer recording prevents the reading from being

 * corrupted. This is not a consuming read, so a producer is not

 * expected.

 *

 * After a sequence of ring_buffer_read_prepare calls, the user is

 * expected to make at least one call to ring_buffer_read_prepare_sync.

 * Afterwards, ring_buffer_read_start is invoked to get things going
@@ -5139,8 +5135,7 @@ EXPORT_SYMBOL_GPL(ring_buffer_read_start); 
 * ring_buffer_read_finish - finish reading the iterator of the buffer

 * @iter: The iterator retrieved by ring_buffer_start

 *

 * This re-enables the recording to the buffer, and frees the

 * iterator.

 * This re-enables resizing of the buffer, and frees the iterator.

 */

void

ring_buffer_read_finish(struct ring_buffer_iter *iter)
@@ -5148,12 +5143,7 @@ ring_buffer_read_finish(struct ring_buffer_iter *iter) 
	struct ring_buffer_per_cpu *cpu_buffer = iter->cpu_buffer;

	unsigned long flags;



	/*

	 * Ring buffer is disabled from recording, here's a good place

	 * to check the integrity of the ring buffer.

	 * Must prevent readers from trying to read, as the check

	 * clears the HEAD page and readers require it.

	 */

	/* Use this opportunity to check the integrity of the ring buffer. */

	raw_spin_lock_irqsave(&cpu_buffer->reader_lock, flags);

	rb_check_pages(cpu_buffer);

	raw_spin_unlock_irqrestore(&cpu_buffer->reader_lock, flags);