linux-kernel - Re: [PATCH v2] ring-buffer: fix kernel-doc format to avoid a warning

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <20251020143332.732ae92d@gandalf.local.home>
Date: Mon, 20 Oct 2025 14:33:32 -0400
From: Steven Rostedt <rostedt@...dmis.org>
To: Randy Dunlap <rdunlap@...radead.org>
Cc: linux-kernel@...r.kernel.org, Lai Jiangshan <laijs@...fujitsu.com>,
 Masami Hiramatsu <mhiramat@...nel.org>, Mathieu Desnoyers
 <mathieu.desnoyers@...icios.com>, linux-trace-kernel@...r.kernel.org
Subject: Re: [PATCH v2] ring-buffer: fix kernel-doc format to avoid a
 warning

On Sun, 19 Oct 2025 18:00:37 -0700
Randy Dunlap <rdunlap@...radead.org> wrote:

> Format the kernel-doc for RINGBUF_TYPE_DATA_TYPE_LEN_MAX correctly
> to prevent a kernel-doc warning:
> 
> Warning: include/linux/ring_buffer.h:61 Enum value
>  'RINGBUF_TYPE_DATA_TYPE_LEN_MAX' not described in enum 'ring_buffer_type'
> 
> Fixes: 334d4169a659 ("ring_buffer: compressed event header")
> Signed-off-by: Randy Dunlap <rdunlap@...radead.org>
> ---
> v2: reformat based on comments from Steven;
>     add more enum types to aid with comments;
> 
> Cc: Lai Jiangshan <laijs@...fujitsu.com>
> Cc: Steven Rostedt <rostedt@...dmis.org>
> Cc: Masami Hiramatsu <mhiramat@...nel.org>
> Cc: Mathieu Desnoyers <mathieu.desnoyers@...icios.com>
> Cc: linux-trace-kernel@...r.kernel.org
> ---
>  include/linux/ring_buffer.h |   13 +++++++++----
>  1 file changed, 9 insertions(+), 4 deletions(-)
> 
> --- linux-next-20251016.orig/include/linux/ring_buffer.h
> +++ linux-next-20251016/include/linux/ring_buffer.h
> @@ -43,18 +43,23 @@ struct ring_buffer_event {
>   *				 array[0] = top (28 .. 59) bits
>   *				 size = 8 bytes
>   *
> - * <= @RINGBUF_TYPE_DATA_TYPE_LEN_MAX:
> - *				Data record
> - *				 If type_len is zero:
> + * @RINGBUF_TYPE_DATA:		Data record
>   *				  array[0] holds the actual length
>   *				  array[1..(length+3)/4] holds data
>   *				  size = 4 + length (bytes)
> - *				 else
> + *
> + * @RINGBUF_TYPE_DATA_TYPE_LEN_MIN:
> + * 				Data record with length and data as below
> + * . . .
> + * @RINGBUF_TYPE_DATA_TYPE_LEN_MAX:
> + *				Data record
>   *				  length = type_len << 2
>   *				  array[0..(length+3)/4-1] holds data
>   *				  size = 4 + length (bytes)
>   */
>  enum ring_buffer_type {
> +	RINGBUF_TYPE_DATA = 0,
> +	RINGBUF_TYPE_DATA_TYPE_LEN_MIN = 1,

Adding this just to satisfy kerneldoc seems a bit much.

If this is going to be added, then it should be used in the code.

The RINGBUF_TYPE_DATA should probably be called RINGBUF_TYPE_DATA_LARGE, as
it is zero when it is a large event (bigger than 112 bytes).

>  	RINGBUF_TYPE_DATA_TYPE_LEN_MAX = 28,
>  	RINGBUF_TYPE_PADDING,
>  	RINGBUF_TYPE_TIME_EXTEND,

-- Steve