[PATCH] kernel-doc: Add initial binfmt docs

[PATCH] kernel-doc: Add initial binfmt docs

[Kees Cook]

Adds a framework to hold the initial exec.c and binfmt_elf.c
kernel-docs. Updates scripts/kernel-doc to allow leading whitespace so
that embedded "DOC:" tags can be found that aren't at the start of a
line so that in-function documentation can be found, like that recently
marked up in binfmt_elf.c[1].

Link: https://lore.kernel.org/lkml/20250425224502.work.520-kees@kernel.org/ [1]
Signed-off-by: Kees Cook <kees@kernel.org>
---
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Andrew Morton <akpm@linux-foundation.org>
Cc: Randy Dunlap <rdunlap@infradead.org>
Cc: Bagas Sanjaya <bagasdotme@gmail.com>
Cc: Mike Rapoport <rppt@kernel.org>
Cc: Arnd Bergmann <arnd@arndb.de>
Cc: <linux-doc@vger.kernel.org>
Cc: <linux-mm@kvack.org>
---
 Documentation/core-api/exec-binfmt.rst | 30 ++++++++++++++++++++++++++
 Documentation/core-api/index.rst       |  1 +
 MAINTAINERS                            |  1 +
 scripts/kernel-doc                     |  4 ++--
 4 files changed, 34 insertions(+), 2 deletions(-)
 create mode 100644 Documentation/core-api/exec-binfmt.rst

diff --git a/Documentation/core-api/exec-binfmt.rst b/Documentation/core-api/exec-binfmt.rst
new file mode 100644
index 000000000000..7e9b515a8107
--- /dev/null
+++ b/Documentation/core-api/exec-binfmt.rst
@@ -0,0 +1,30 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+======================================
+execve(2) internals and Binary Formats
+======================================
+
+Overview
+========
+To perform execve(), the kernel loads the header of a file from disk,
+searches through all binary handlers to find a match, and then builds a
+new process memory layout with the resulting binfmt, before transferring
+userspace execution control to it.
+
+ELF PIE Handling Notes
+======================
+.. kernel-doc:: fs/binfmt_elf.c
+   :doc: PIE handling
+
+brk handling
+============
+.. kernel-doc:: fs/binfmt_elf.c
+   :doc: "brk" handling
+
+Functions and structures
+========================
+.. kernel-doc:: fs/exec.c
+   :identifiers:
+
+.. kernel-doc:: fs/binfmt_elf.c
+   :identifiers:
diff --git a/Documentation/core-api/index.rst b/Documentation/core-api/index.rst
index e9789bd381d8..e44b9b2e60ef 100644
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -62,6 +62,7 @@ Low level entry and exit
    :maxdepth: 1
 
    entry
+   exec-binfmt
 
 Concurrency primitives
 ======================
diff --git a/MAINTAINERS b/MAINTAINERS
index fa1e04e87d1d..0dca4c2cbbff 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -8820,6 +8820,7 @@ M:	Kees Cook <kees@kernel.org>
 L:	linux-mm@kvack.org
 S:	Supported
 T:	git git://git.kernel.org/pub/scm/linux/kernel/git/kees/linux.git for-next/execve
+F:	Documentation/core-api/exec-binfmt.rst
 F:	Documentation/userspace-api/ELF.rst
 F:	fs/*binfmt_*.c
 F:	fs/Kconfig.binfmt
diff --git a/scripts/kernel-doc b/scripts/kernel-doc
index af6cf408b96d..a2af8ac5acff 100755
--- a/scripts/kernel-doc
+++ b/scripts/kernel-doc
@@ -243,7 +243,7 @@ my $decl_type;
 # Name of the kernel-doc identifier for non-DOC markups
 my $identifier;
 
-my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.
+my $doc_start = '^\s*/\*\*\s*$'; # Allow whitespace at end of comment start.
 my $doc_end = '\*/';
 my $doc_com = '\s*\*\s*';
 my $doc_com_body = '\s*\* ?';
@@ -2261,7 +2261,7 @@ sub process_file($) {
 
     $section_counter = 0;
     while (<IN_FILE>) {
-        while (!/^ \*/ && s/\\\s*$//) {
+        while (!/^\s* \*/ && s/\\\s*$//) {
             $_ .= <IN_FILE>;
         }
         # Replace tabs by spaces
-- 
2.34.1

Re: [PATCH] kernel-doc: Add initial binfmt docs

[Jonathan Corbet]

Kees Cook <kees@kernel.org> writes:

> Adds a framework to hold the initial exec.c and binfmt_elf.c
> kernel-docs. Updates scripts/kernel-doc to allow leading whitespace so
> that embedded "DOC:" tags can be found that aren't at the start of a
> line so that in-function documentation can be found, like that recently
> marked up in binfmt_elf.c[1].

Just one tiny little problem ... when you weren't looking, Mauro snuck
in and replaced scripts/kernel-doc with a shiny new Python
implementation.  So that part of the patch won't apply to docs-next; if
you apply it somewhere else, the change will get lost.

I figured we were going to run into at least one of these ... sorry ...

jon

Re: [PATCH] kernel-doc: Add initial binfmt docs

[Kees Cook]

On Mon, Apr 28, 2025 at 05:27:15PM -0600, Jonathan Corbet wrote:
> Kees Cook <kees@kernel.org> writes:
> 
> > Adds a framework to hold the initial exec.c and binfmt_elf.c
> > kernel-docs. Updates scripts/kernel-doc to allow leading whitespace so
> > that embedded "DOC:" tags can be found that aren't at the start of a
> > line so that in-function documentation can be found, like that recently
> > marked up in binfmt_elf.c[1].
> 
> Just one tiny little problem ... when you weren't looking, Mauro snuck
> in and replaced scripts/kernel-doc with a shiny new Python
> implementation.  So that part of the patch won't apply to docs-next; if
> you apply it somewhere else, the change will get lost.
> 
> I figured we were going to run into at least one of these ... sorry ...

Oh duh, yeah, I will go re-do this with -next.

-Kees

-- 
Kees Cook