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-next>] [day] [month] [year] [list]
Date: Sun, 17 Dec 2023 23:46:06 +0000
From: Yueh-Shun Li <shamrocklee@...teo.net>
To: Jonathan Corbet <corbet@....net>
Cc: linux-doc@...r.kernel.org, linux-kernel@...r.kernel.org
Subject: Irrelevant documentation recommending the use of
 "include/linux/kernel.h"

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.

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
```

or a specific header that contains standalone helper macros?

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

Powered by blists - more mailing lists

Powered by Openwall GNU/*/Linux Powered by OpenVZ