linux-kernel - Re: [PATCH v3 1/2] include/linux/watch

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: <2121105.1673359772@warthog.procyon.org.uk>
Date:   Tue, 10 Jan 2023 14:09:32 +0000
From:   David Howells <dhowells@...hat.com>
To:     Siddh Raman Pant <code@...dh.me>
Cc:     dhowells@...hat.com, Mauro Carvalho Chehab <mchehab@...nel.org>,
        Randy Dunlap <rdunlap@...radead.org>,
        Jonathan Corbet <corbet@....net>,
        "Fabio M. De Francesco" <fmdefrancesco@...il.com>,
        Eric Dumazet <edumazet@...gle.com>,
        Christophe JAILLET <christophe.jaillet@...adoo.fr>,
        Eric Biggers <ebiggers@...nel.org>,
        keyrings <keyrings@...r.kernel.org>,
        linux-security-module <linux-security-module@...r.kernel.org>,
        linux-fsdevel <linux-fsdevel@...r.kernel.org>,
        linux-kernel <linux-kernel@...r.kernel.org>
Subject: Re: [PATCH v3 1/2] include/linux/watch_queue: Improve documentation

Siddh Raman Pant <code@...dh.me> wrote:

> +/**
> + * struct watch_type_filter - Filter on watch type
> + *
> + * @type: Type of watch_notification
> + * @subtype_filter: Bitmask of subtypes to filter on
> + * @info_filter: Filter on watch_notification::info
> + * @info_mask: Mask of relevant bits in info_filter
> + */
>  struct watch_type_filter {
>  	enum watch_notification_type type;
> -	__u32		subtype_filter[1];	/* Bitmask of subtypes to filter on */
> -	__u32		info_filter;		/* Filter on watch_notification::info */
> -	__u32		info_mask;		/* Mask of relevant bits in info_filter */
> +	__u32		subtype_filter[1];
> +	__u32		info_filter;
> +	__u32		info_mask;
>  };

Please don't.

The structure is documented fully here:

	Documentation/core-api/watch_queue.rst

See:

	https://docs.kernel.org/core-api/watch_queue.html#event-filtering

The three column approach is much more readable in the code as it doesn't
separate the descriptions from the things described.  Putting things in
columns has been around for around 6000 years.

David