[PATCH] kbuild: document generation of offset header files

[PATCH] kbuild: document generation of offset header files

[Piyush Patle]

Replace the placeholder reference with a description of how Kbuild
generates offset header files such as include/generated/asm-offsets.h.

Remove the corresponding TODO entry now that this is documented.

Signed-off-by: Piyush Patle <piyushpatle228@gmail.com>
---
 Documentation/kbuild/makefiles.rst | 41 ++++++++++++++++++++++++------
 1 file changed, 33 insertions(+), 8 deletions(-)

diff --git a/Documentation/kbuild/makefiles.rst b/Documentation/kbuild/makefiles.rst
index 24a4708d26e8..7521cae7d56f 100644
--- a/Documentation/kbuild/makefiles.rst
+++ b/Documentation/kbuild/makefiles.rst
@@ -1285,8 +1285,39 @@ Example::
 In this example, the file target maketools will be processed
 before descending down in the subdirectories.
 
-See also chapter XXX-TODO that describes how kbuild supports
-generating offset header files.
+Generating offset header files
+------------------------------
+
+The ``include/generated/asm-offsets.h`` header exposes C structure
+member offsets and other compile-time constants to assembly code. It
+is generated from ``arch/$(SRCARCH)/kernel/asm-offsets.c``.
+
+The source file uses ``DEFINE()``, ``OFFSET()``, ``BLANK()`` and
+``COMMENT()`` from ``<linux/kbuild.h>``. These emit marker strings
+through inline asm that Kbuild extracts from the compiled assembly
+output.
+
+Example::
+
+  #include <linux/kbuild.h>
+  #include <linux/sched.h>
+
+  int main(void)
+  {
+          OFFSET(TSK_ACTIVE_MM, task_struct, active_mm);
+          DEFINE(THREAD_SIZE, THREAD_SIZE);
+          BLANK();
+          return 0;
+  }
+
+The rules are defined in the top-level ``Kbuild`` and
+``scripts/Makefile.lib``. The header is built during Kbuild's
+``prepare`` phase, after ``archprepare`` and before descending into
+subdirectories.
+
+The same mechanism generates ``include/generated/bounds.h`` from
+``kernel/bounds.c`` and ``include/generated/rq-offsets.h`` from
+``kernel/sched/rq-offsets.c``.
 
 List directories to visit when descending
 -----------------------------------------
@@ -1690,9 +1721,3 @@ Credits
 - Updates by Kai Germaschewski <kai@tp1.ruhr-uni-bochum.de>
 - Updates by Sam Ravnborg <sam@ravnborg.org>
 - Language QA by Jan Engelhardt <jengelh@gmx.de>
-
-TODO
-====
-
-- Generating offset header files.
-- Add more variables to chapters 7 or 9?
-- 
2.43.0

Re: [PATCH] kbuild: document generation of offset header files

[Piyush Patle]

On Sat, Apr 11, 2026 at 3:43 AM Piyush Patle <piyushpatle228@gmail.com> wrote:
>
> Replace the placeholder reference with a description of how Kbuild
> generates offset header files such as include/generated/asm-offsets.h.
>
> Remove the corresponding TODO entry now that this is documented.
>
> Signed-off-by: Piyush Patle <piyushpatle228@gmail.com>
> ---
>  Documentation/kbuild/makefiles.rst | 41 ++++++++++++++++++++++++------
>  1 file changed, 33 insertions(+), 8 deletions(-)
>
> diff --git a/Documentation/kbuild/makefiles.rst b/Documentation/kbuild/makefiles.rst
> index 24a4708d26e8..7521cae7d56f 100644
> --- a/Documentation/kbuild/makefiles.rst
> +++ b/Documentation/kbuild/makefiles.rst
> @@ -1285,8 +1285,39 @@ Example::
>  In this example, the file target maketools will be processed
>  before descending down in the subdirectories.
>
> -See also chapter XXX-TODO that describes how kbuild supports
> -generating offset header files.
> +Generating offset header files
> +------------------------------
> +
> +The ``include/generated/asm-offsets.h`` header exposes C structure
> +member offsets and other compile-time constants to assembly code. It
> +is generated from ``arch/$(SRCARCH)/kernel/asm-offsets.c``.
> +
> +The source file uses ``DEFINE()``, ``OFFSET()``, ``BLANK()`` and
> +``COMMENT()`` from ``<linux/kbuild.h>``. These emit marker strings
> +through inline asm that Kbuild extracts from the compiled assembly
> +output.
> +
> +Example::
> +
> +  #include <linux/kbuild.h>
> +  #include <linux/sched.h>
> +
> +  int main(void)
> +  {
> +          OFFSET(TSK_ACTIVE_MM, task_struct, active_mm);
> +          DEFINE(THREAD_SIZE, THREAD_SIZE);
> +          BLANK();
> +          return 0;
> +  }
> +
> +The rules are defined in the top-level ``Kbuild`` and
> +``scripts/Makefile.lib``. The header is built during Kbuild's
> +``prepare`` phase, after ``archprepare`` and before descending into
> +subdirectories.
> +
> +The same mechanism generates ``include/generated/bounds.h`` from
> +``kernel/bounds.c`` and ``include/generated/rq-offsets.h`` from
> +``kernel/sched/rq-offsets.c``.
>
>  List directories to visit when descending
>  -----------------------------------------
> @@ -1690,9 +1721,3 @@ Credits
>  - Updates by Kai Germaschewski <kai@tp1.ruhr-uni-bochum.de>
>  - Updates by Sam Ravnborg <sam@ravnborg.org>
>  - Language QA by Jan Engelhardt <jengelh@gmx.de>
> -
> -TODO
> -====
> -
> -- Generating offset header files.
> -- Add more variables to chapters 7 or 9?
> --
> 2.43.0
>

Hi,
Gentle ping on this patch.

I’d appreciate any feedback whenever you get time, or let me know if I
should resend/rework anything.

Regards,
Piyush

Re: [PATCH] kbuild: document generation of offset header files

[Nathan Chancellor]

Hi Piyush,

On Sat, Apr 18, 2026 at 07:08:33PM +0530, Piyush Patle wrote:
> On Sat, Apr 11, 2026 at 3:43 AM Piyush Patle <piyushpatle228@gmail.com> wrote:
> >
> > Replace the placeholder reference with a description of how Kbuild
> > generates offset header files such as include/generated/asm-offsets.h.
> >
> > Remove the corresponding TODO entry now that this is documented.
> >
> > Signed-off-by: Piyush Patle <piyushpatle228@gmail.com>
...
> Gentle ping on this patch.
> 
> I’d appreciate any feedback whenever you get time, or let me know if I
> should resend/rework anything.

Thanks for the ping. This is still in my review/handling queue but given
that we are in the merge window for 7.1, I am not looking at 7.2
material until 7.1-rc1 is out.

Cheers,
Nathan

Re: [PATCH] kbuild: document generation of offset header files

[Nicolas Schier]

On Sat, Apr 11, 2026 at 03:42:54AM +0530, Piyush Patle wrote:
> Replace the placeholder reference with a description of how Kbuild
> generates offset header files such as include/generated/asm-offsets.h.
> 
> Remove the corresponding TODO entry now that this is documented.
> 
> Signed-off-by: Piyush Patle <piyushpatle228@gmail.com>
> ---
>  Documentation/kbuild/makefiles.rst | 41 ++++++++++++++++++++++++------
>  1 file changed, 33 insertions(+), 8 deletions(-)

Looks good to me, thanks!

Reviewed-by: Nicolas Schier <nsc@kernel.org>

Re: [PATCH] kbuild: document generation of offset header files

[Nathan Chancellor]

On Sat, 11 Apr 2026 03:42:54 +0530, Piyush Patle <piyushpatle228@gmail.com> wrote:

Hi Piyush,

> Replace the placeholder reference with a description of how Kbuild
> generates offset header files such as include/generated/asm-offsets.h.
> 
> Remove the corresponding TODO entry now that this is documented.
> 
> Signed-off-by: Piyush Patle <piyushpatle228@gmail.com>

Thanks, this seems generally good to me. I had wondered if it was worth
adding a "lay person's explanation" of the example but I think it is
fairly easy to understand.

>
>
> diff --git a/Documentation/kbuild/makefiles.rst b/Documentation/kbuild/makefiles.rst
> index 24a4708d26e8..7521cae7d56f 100644
> --- a/Documentation/kbuild/makefiles.rst
> +++ b/Documentation/kbuild/makefiles.rst
> @@ -1690,9 +1721,3 @@ Credits
>  - Updates by Kai Germaschewski <kai@tp1.ruhr-uni-bochum.de>
>  - Updates by Sam Ravnborg <sam@ravnborg.org>
>  - Language QA by Jan Engelhardt <jengelh@gmx.de>
> -
> -TODO
> -====
> -
> -- Generating offset header files.
> -- Add more variables to chapters 7 or 9?

Sashiko notes that you also removed the TODO around variables:

  https://sashiko.dev/#/message/20260410221257.191517-1-piyushpatle228@gmail.com

I don't think it is a big enough deal to warrant a respin but just
something to be aware of for the future.

-- 
Cheers,
Nathan

Re: [PATCH] kbuild: document generation of offset header files

[Nathan Chancellor]

On Sat, 11 Apr 2026 03:42:54 +0530, Piyush Patle wrote:
> Replace the placeholder reference with a description of how Kbuild
> generates offset header files such as include/generated/asm-offsets.h.
> 
> Remove the corresponding TODO entry now that this is documented.

Applied to

  https://git.kernel.org/pub/scm/linux/kernel/git/kbuild/linux.git kbuild-next-unstable

Thanks!

[1/1] kbuild: document generation of offset header files
      https://git.kernel.org/kbuild/c/a0d7be4ab3ece

Please look out for regression or issue reports or other follow up
comments, as they may result in the patch/series getting dropped or
reverted. Patches applied to an "unstable" branch are accepted pending
wider testing in -next and any post-commit review; they will generally
be moved to the main branch in a week if no issues are found.

Best regards,
-- 
Cheers,
Nathan