linux-kernel - Re: Irrelevant documentation recommending the use of "include/linux/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]

Message-ID: <107b6b5e-ca14-4b2b-ba2e-38ecd74c0ad3@infradead.org>
Date: Fri, 5 Jan 2024 14:49:14 -0800
From: Randy Dunlap <rdunlap@...radead.org>
To: Yueh-Shun Li <shamrocklee@...teo.net>, Jonathan Corbet <corbet@....net>
Cc: linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org
Subject: Re: Irrelevant documentation recommending the use of
 "include/linux/kernel.h"

Hi,

On 12/17/23 15:46, Yueh-Shun Li wrote:
> Dear Maintainer,
> 
> The section "18) Don't re-invent the kernel macros" in
> "Linux kernel coding style" (Documentation/process/coding-style.rst)
> recommends re-using the macros defined in "include/linux/kernel.h"
> instead of the improvised ones locally.
> 
> However, There's a note in the comment block added by commit 40cbf09f060c
> ("kernel.h: include a note to discourage people from including it in headers")
> two years ago, saying that there's an in-progress splitting of kernel.h
> and inclusion in headers under include/ is discouraged.
> 
> Considering that the section was added 17 years ago by commit 58637ec90b7c
> ("Add a new section to CodingStyle, promoting include/linux/kernel.h"),
> the section about kernel.h in the "Linux kernel coding style" documentation seems outdated.
> 

Yes.

> Reproduction steps:
> 
> ```sh
> # cd to the kernel source tree
> cd path/to/source/linux
> # Show the git blame of the documentation section added in 2006
> git blame -L 1051,1071 Documentation/process/coding-style.rst
> # Show the comment note on top of include/linux/kernel.h added in 2022
> git blame -L 2,10 include/linux/kernel.h
> ```
> 
> Should we change
> 
> ```
> The header file include/linux/kernel.h
> ```
> 
> to something like
> 
> ```
> The header files under the include/linux/ directory
> ```

the necessary header files in the include/linux/ directory.


> 
> or a specific header that contains standalone helper macros?
> 

No. That would just end up as another catchall file that
gets too large (bloated) and contain many headers that are not
needed for some or many source files.

> It might be out of scope here,
> but such a header that collects standalone helping macros
> seems non-existent so far.

I think that we don't want another one.

> It would be great to have one that contains things like
> "STRINGIFY", "CONCATENATE" (or "PASTE"), "UNIQUE_ID"
> and other helper macros without external dependencies.
> There's one called "include/linux/util_macros.h", but it depends on "include/linux/math.h".
> 
> It's the first time for me to report an issue in LKML.
> Please kindly point out anything
> that I should fix or could improve.
> 
> Best regards,
> 
> Shamrock
> 

Thanks.
-- 
#Randy