| 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
| ||
|
Message-ID: <CANLsYkzhvZK4ZhNP=Zc0XxENxGV8efFEMGLBc3RAV626edysiA@mail.gmail.com>
Date: Fri, 5 Dec 2025 08:25:39 -0700
From: Mathieu Poirier <mathieu.poirier@...aro.org>
To: Andy Shevchenko <andriy.shevchenko@...ux.intel.com>
Cc: Randy Dunlap <rdunlap@...radead.org>, "Dr. David Alan Gilbert" <linux@...blig.org>, linux-doc@...r.kernel.org,
linux-kernel@...r.kernel.org, workflows@...r.kernel.org,
linux-remoteproc@...r.kernel.org,
Greg Kroah-Hartman <gregkh@...uxfoundation.org>, "Rafael J. Wysocki" <rafael@...nel.org>,
Danilo Krummrich <dakr@...nel.org>, Jonathan Corbet <corbet@....net>,
Dwaipayan Ray <dwaipayanray1@...il.com>, Lukas Bulwahn <lukas.bulwahn@...il.com>,
Joe Perches <joe@...ches.com>, Bjorn Andersson <andersson@...nel.org>
Subject: Re: [PATCH v2 1/1] docs: Update documentation to avoid mentioning of kernel.h
On Wed, 26 Nov 2025 at 14:47, Andy Shevchenko
<andriy.shevchenko@...ux.intel.com> wrote:
>
> For several years, and still ongoing, the kernel.h is being split
> to smaller and narrow headers to avoid "including everything" approach
> which is bad in many ways. Since that, documentation missed a few
> required updates to align with that work. Do it here.
>
> Note, language translations are left untouched and if anybody willing
> to help, please provide path(es) based on the updated English variant.
>
> Signed-off-by: Andy Shevchenko <andriy.shevchenko@...ux.intel.com>
> Reviewed-by: Randy Dunlap <rdunlap@...radead.org>
> ---
>
> v2: collected tag (Randy), fixed util_macros k-doc (Randy, me), fixed spelling (Randy)
>
> Documentation/core-api/kobject.rst | 2 +-
> Documentation/dev-tools/checkpatch.rst | 2 +-
> Documentation/driver-api/basics.rst | 17 ++++++++++++++++-
> .../driver-api/driver-model/design-patterns.rst | 2 +-
> Documentation/process/coding-style.rst | 10 +++++++---
> Documentation/staging/rpmsg.rst | 7 +++++--
> include/linux/util_macros.h | 2 +-
> 7 files changed, 32 insertions(+), 10 deletions(-)
>
> diff --git a/Documentation/core-api/kobject.rst b/Documentation/core-api/kobject.rst
> index 7310247310a0..5f6c61bc03bf 100644
> --- a/Documentation/core-api/kobject.rst
> +++ b/Documentation/core-api/kobject.rst
> @@ -78,7 +78,7 @@ just a matter of using the kobj member. Code that works with kobjects will
> often have the opposite problem, however: given a struct kobject pointer,
> what is the pointer to the containing structure? You must avoid tricks
> (such as assuming that the kobject is at the beginning of the structure)
> -and, instead, use the container_of() macro, found in ``<linux/kernel.h>``::
> +and, instead, use the container_of() macro, found in ``<linux/container_of.h>``::
>
> container_of(ptr, type, member)
>
> diff --git a/Documentation/dev-tools/checkpatch.rst b/Documentation/dev-tools/checkpatch.rst
> index fa2988dd4657..c1dff8e6bccb 100644
> --- a/Documentation/dev-tools/checkpatch.rst
> +++ b/Documentation/dev-tools/checkpatch.rst
> @@ -753,7 +753,7 @@ Macros, Attributes and Symbols
> sizeof(foo)/sizeof(foo[0]) for finding number of elements in an
> array.
>
> - The macro is defined in include/linux/kernel.h::
> + The macro is defined in include/linux/array_size.h::
>
> #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
>
> diff --git a/Documentation/driver-api/basics.rst b/Documentation/driver-api/basics.rst
> index 5e9f7aee71a7..8b6a5888cb11 100644
> --- a/Documentation/driver-api/basics.rst
> +++ b/Documentation/driver-api/basics.rst
> @@ -114,10 +114,25 @@ Kernel objects manipulation
> Kernel utility functions
> ------------------------
>
> -.. kernel-doc:: include/linux/kernel.h
> +.. kernel-doc:: include/linux/array_size.h
> + :internal:
> +
> +.. kernel-doc:: include/linux/container_of.h
> + :internal:
> +
> +.. kernel-doc:: include/linux/kstrtox.h
> :internal:
> :no-identifiers: kstrtol kstrtoul
>
> +.. kernel-doc:: include/linux/stddef.h
> + :internal:
> +
> +.. kernel-doc:: include/linux/util_macros.h
> + :internal:
> +
> +.. kernel-doc:: include/linux/wordpart.h
> + :internal:
> +
> .. kernel-doc:: kernel/printk/printk.c
> :export:
> :no-identifiers: printk
> diff --git a/Documentation/driver-api/driver-model/design-patterns.rst b/Documentation/driver-api/driver-model/design-patterns.rst
> index 41eb8f41f7dd..965b2b93be6f 100644
> --- a/Documentation/driver-api/driver-model/design-patterns.rst
> +++ b/Documentation/driver-api/driver-model/design-patterns.rst
> @@ -103,7 +103,7 @@ The design pattern is the same for an hrtimer or something similar that will
> return a single argument which is a pointer to a struct member in the
> callback.
>
> -container_of() is a macro defined in <linux/kernel.h>
> +container_of() is a macro defined in <linux/container_of.h>
>
> What container_of() does is to obtain a pointer to the containing struct from
> a pointer to a member by a simple subtraction using the offsetof() macro from
> diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
> index 2969ca378dbb..258158637f65 100644
> --- a/Documentation/process/coding-style.rst
> +++ b/Documentation/process/coding-style.rst
> @@ -1070,7 +1070,7 @@ readability.
> 18) Don't re-invent the kernel macros
> -------------------------------------
>
> -The header file include/linux/kernel.h contains a number of macros that
> +There are many header files in include/linux/ that contain 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
> @@ -1079,14 +1079,18 @@ of the macro
>
> #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))
>
> +which is defined in array_size.h.
> +
> Similarly, if you need to calculate the size of some structure member, use
>
> .. 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
> +which is defined in stddef.h.
> +
> +There are also min() and max() macros defined in minmax.h that do strict type checking
> +if you need them. Feel free to peruse the header files to see what else is already
> defined that you shouldn't reproduce in your code.
>
>
> diff --git a/Documentation/staging/rpmsg.rst b/Documentation/staging/rpmsg.rst
> index 40282cca86ca..42bac1149d9d 100644
> --- a/Documentation/staging/rpmsg.rst
> +++ b/Documentation/staging/rpmsg.rst
> @@ -224,9 +224,12 @@ content to the console.
>
> ::
>
> - #include <linux/kernel.h>
> + #include <linux/dev_printk.h>
> + #include <linux/mod_devicetable.h>
> #include <linux/module.h>
> + #include <linux/printk.h>
> #include <linux/rpmsg.h>
> + #include <linux/types.h>
>
> static void rpmsg_sample_cb(struct rpmsg_channel *rpdev, void *data, int len,
> void *priv, u32 src)
> @@ -244,7 +247,7 @@ content to the console.
> /* send a message on our channel */
> err = rpmsg_send(rpdev->ept, "hello!", 6);
> if (err) {
> - pr_err("rpmsg_send failed: %d\n", err);
> + dev_err(&rpdev->dev, "rpmsg_send failed: %d\n", err);
> return err;
> }
Reviewed-by: Mathieu Poirier <mathieu.poirier@...aro.org>
>
> diff --git a/include/linux/util_macros.h b/include/linux/util_macros.h
> index 2eb528058d0d..71564868b8f6 100644
> --- a/include/linux/util_macros.h
> +++ b/include/linux/util_macros.h
> @@ -119,7 +119,7 @@
> * a fuss about it. This makes the programmer responsible for tagging
> * the functions that can be garbage-collected.
> *
> - * With the macro it is possible to write the following:
> + * With the macro it is possible to write the following::
> *
> * static int foo_suspend(struct device *dev)
> * {
> --
> 2.50.1
>
Powered by blists - more mailing lists