Re: [PATCH v2 1/1] docs: Update documentation to avoid mentioning of kernel.h

[Mathieu Poirier <mathieu.poirier@linaro.org>]

On Wed, 26 Nov 2025 at 14:47, Andy Shevchenko
<andriy.shevchenko@linux.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@linux.intel.com>
> Reviewed-by: Randy Dunlap <rdunlap@infradead.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@linaro.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
>