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

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

[Andy Shevchenko]

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;
 	}
 
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

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

[Randy Dunlap]

On 11/26/25 1:46 PM, Andy Shevchenko 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>

Tested-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(-)
> 

-- 
~Randy

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

[Joe Perches]

On Wed, 2025-11-26 at 22:46 +0100, Andy Shevchenko 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.

And I still think precompiled headers can be beneficial to
standardize using kernel.h to reduce overall compilation time.

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

[Andy Shevchenko]

On Thu, Nov 27, 2025 at 09:34:51AM -0800, Joe Perches wrote:
> On Wed, 2025-11-26 at 22:46 +0100, Andy Shevchenko 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.
> 
> And I still think precompiled headers can be beneficial to
> standardize using kernel.h to reduce overall compilation time.

Same Q, why don't we have just a single header? Why do we have a concept of
(modular) headers to begin with? And Ingo's approach shows that the problem
can be solved properly by dividing headers to be more logical smaller pieces.
So, I have a strong disagreement for using kernel.h. At least not in this form,
It needs to be cleaned up and some sanity given to that train wreck. When it's
done, we can think of precompiled headers.

-- 
With Best Regards,
Andy Shevchenko

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

[Andy Shevchenko]

On Wed, Nov 26, 2025 at 04:26:04PM -0800, Randy Dunlap wrote:
> On 11/26/25 1:46 PM, Andy Shevchenko 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>
> 
> Tested-by: Randy Dunlap <rdunlap@infradead.org>

Thanks, Randy!

Jonathan, please apply this change. Independently on the opinions about
kernel.h the documentation has to be updated as it's currently misleading.

-- 
With Best Regards,
Andy Shevchenko

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

[Jonathan Corbet]

Andy Shevchenko <andriy.shevchenko@linux.intel.com> writes:

> On Wed, Nov 26, 2025 at 04:26:04PM -0800, Randy Dunlap wrote:
>> On 11/26/25 1:46 PM, Andy Shevchenko 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>
>> 
>> Tested-by: Randy Dunlap <rdunlap@infradead.org>
>
> Thanks, Randy!
>
> Jonathan, please apply this change. Independently on the opinions about
> kernel.h the documentation has to be updated as it's currently misleading.

I will but not right away...I'm really trying to stabilize things,
already too late, for the merge window.

jon

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

[Andy Shevchenko]

On Sat, Nov 29, 2025 at 08:54:48AM -0700, Jonathan Corbet wrote:
> Andy Shevchenko <andriy.shevchenko@linux.intel.com> writes:
> > On Wed, Nov 26, 2025 at 04:26:04PM -0800, Randy Dunlap wrote:
> >> On 11/26/25 1:46 PM, Andy Shevchenko 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>
> >> 
> >> Tested-by: Randy Dunlap <rdunlap@infradead.org>
> >
> > Thanks, Randy!
> >
> > Jonathan, please apply this change. Independently on the opinions about
> > kernel.h the documentation has to be updated as it's currently misleading.
> 
> I will but not right away...I'm really trying to stabilize things,
> already too late, for the merge window.

Noted, thanks for explanation!

-- 
With Best Regards,
Andy Shevchenko

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

[Mathieu Poirier]

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
>

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

[Jonathan Corbet]

Andy Shevchenko <andriy.shevchenko@linux.intel.com> writes:

> 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(-)

Applied (finally) thanks.

jon

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

[Andy Shevchenko]

On Mon, Dec 22, 2025 at 03:00:24PM -0700, Jonathan Corbet wrote:
> Andy Shevchenko <andriy.shevchenko@linux.intel.com> writes:
> 
> > 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(-)
> 
> Applied (finally) thanks.

Thank you! I leave the translations to the respective maintainers and native
speakers to decide.

-- 
With Best Regards,
Andy Shevchenko