linux-kernel - Re: [PATCH v3 1/1] coding-style: recommend split headers instead of kernel.h

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]

Date: Sat, 27 Jan 2024 22:26:40 -0800
From: Randy Dunlap <rdunlap@...radead.org>
To: Yueh-Shun Li <shamrocklee@...teo.net>, Jonathan Corbet <corbet@....net>
Cc: Hu Haowen <src.res.211@...il.com>, Alex Shi <alexs@...nel.org>,
 Yanteng Si <siyanteng@...ngson.cn>, workflows@...r.kernel.org,
 linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org
Subject: Re: [PATCH v3 1/1] coding-style: recommend split headers instead of
 kernel.h



On 1/8/24 12:22, Yueh-Shun Li wrote:
> In section "18) Don't re-invent the kernel macros" in "Linux kernel
> coding style":
> 
> Recommend reusing macros from headers inside include/linux, instead of
> the obsolete include/linux/kernel.h
> 
> Change wording
> 
> - "The header file contains macros" -> "the header files provide macros"
>   Some macros are intended to use inside the header file only, or are
>   considered the implementation detail of other facilities. Developers
>   are expected to determine if a macro is meant to be used outside the
>   header file.
> 
> Signed-off-by: Yueh-Shun Li <shamrocklee@...teo.net>

Acked-by: Randy Dunlap <rdunlap@...radead.org>
Thanks.

> ---
>  Documentation/process/coding-style.rst | 24 +++++++++++++-----------
>  1 file changed, 13 insertions(+), 11 deletions(-)
> 
> diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
> index 6db37a46d305..2a5c4f4c568c 100644
> --- a/Documentation/process/coding-style.rst
> +++ b/Documentation/process/coding-style.rst
> @@ -1048,27 +1048,29 @@ readable alternative if the call-sites have naked true/false constants.
>  Otherwise limited use of bool in structures and arguments can improve
>  readability.
>  
> +
>  18) Don't re-invent the kernel macros
>  -------------------------------------
>  
> -The header file include/linux/kernel.h contains a number of macros that
> -you should use, rather than explicitly coding some variant of them yourself.
> +The header files in the ``include/linux`` directory provide a number of macros
> +that you should use, rather than explicitly coding some variant of them
> +yourself.
> +
>  For example, if you need to calculate the length of an array, take advantage
> -of the macro
> +of the macro ``ARRAY_SIZE()`` from ``include/linux/array_size.h`` by
>  
>  .. code-block:: c
>  
> -	#define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
> +	#include <linux/array_size.h>
> +	ARRAY_SIZE(x) // The size of array x
>  
>  Similarly, if you need to calculate the size of some structure member, use
> +``sizeof_field()`` from ``include/linux/stddef.h``.
>  
> -.. code-block:: c
> -
> -	#define sizeof_field(t, f) (sizeof(((t*)0)->f))
> -
> -There are also min() and max() macros that do strict type checking if you
> -need them.  Feel free to peruse that header file to see what else is already
> -defined that you shouldn't reproduce in your code.
> +There are also ``min()`` and ``max()`` macros in ``include/linux/minmax.h``
> +that do strict type checking if you need them. Feel free to search across and
> +peruse the header files to see what else is already defined that you shouldn't
> +reproduce in your code.
>  
>  
>  19) Editor modelines and other cruft

-- 
#Randy