Commit 584528d6 authored by John Ogness's avatar John Ogness Committed by Petr Mladek
Browse files

printk: ringbuffer: Cleanup reader terminology 



With the lockless ringbuffer, it is allowed that multiple
CPUs/contexts write simultaneously into the buffer. This creates
an ambiguity as some writers will finalize sooner.

The documentation for the prb_read functions is not clear as it
refers to "not yet written" and "no data available". Clarify the
return values and language to be in terms of the reader: records
available for reading.

Signed-off-by: default avatarJohn Ogness <john.ogness@linutronix.de>
Reviewed-by: default avatarPetr Mladek <pmladek@suse.com>
Link: https://lore.kernel.org/r/20240207134103.1357162-9-john.ogness@linutronix.de


Signed-off-by: default avatarPetr Mladek <pmladek@suse.com>
parent 36652d0f

kernel/printk/printk_ringbuffer.c

+9 −7
Original line number Diff line number Diff line
@@ -1987,11 +1987,13 @@ u64 prb_first_seq(struct printk_ringbuffer *rb) 
}



/*

 * Non-blocking read of a record. Updates @seq to the last finalized record

 * (which may have no data available).

 * Non-blocking read of a record.

 *

 * See the description of prb_read_valid() and prb_read_valid_info()

 * for details.

 * On success @seq is updated to the record that was read and (if provided)

 * @r and @line_count will contain the read/calculated data.

 *

 * On failure @seq is updated to a record that is not yet available to the

 * reader, but it will be the next record available to the reader.

 */

static bool _prb_read_valid(struct printk_ringbuffer *rb, u64 *seq,

			    struct printk_record *r, unsigned int *line_count)
@@ -2010,7 +2012,7 @@ static bool _prb_read_valid(struct printk_ringbuffer *rb, u64 *seq, 
			*seq = tail_seq;



		} else if (err == -ENOENT) {

			/* Record exists, but no data available. Skip. */

			/* Record exists, but the data was lost. Skip. */

			(*seq)++;



		} else {
@@ -2043,7 +2045,7 @@ static bool _prb_read_valid(struct printk_ringbuffer *rb, u64 *seq, 
 * On success, the reader must check r->info.seq to see which record was

 * actually read. This allows the reader to detect dropped records.

 *

 * Failure means @seq refers to a not yet written record.

 * Failure means @seq refers to a record not yet available to the reader.

 */

bool prb_read_valid(struct printk_ringbuffer *rb, u64 seq,

		    struct printk_record *r)
@@ -2073,7 +2075,7 @@ bool prb_read_valid(struct printk_ringbuffer *rb, u64 seq, 
 * On success, the reader must check info->seq to see which record meta data

 * was actually read. This allows the reader to detect dropped records.

 *

 * Failure means @seq refers to a not yet written record.

 * Failure means @seq refers to a record not yet available to the reader.

 */

bool prb_read_valid_info(struct printk_ringbuffer *rb, u64 seq,

			 struct printk_info *info, unsigned int *line_count)