Skip to contentSkip to conversation

kernel-doc: Add initial binfmt docs

PATCH In review Kees Cook 2 participants 3 messages Apr 26, 2025 – Apr 29, 2025

Subsystems (3)
Memory management Documentation exec and binfmt
lore
Share & tools
lore

Kees Cook

author maintainer
#0 lore raw

PATCH 1/1 kernel-doc: Add initial binfmt docs

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/[email protected]/ [1] open here
Signed-off-by Kees Cook <[email protected]>

---
Cc: Jonathan Corbet <[email protected]>
Cc: Andrew Morton <[email protected]>
Cc: Randy Dunlap <[email protected]>
Cc: Bagas Sanjaya <[email protected]>
Cc: Mike Rapoport <[email protected]>
Cc: Arnd Bergmann <[email protected]>
Cc: <[email protected]>
Cc: <[email protected]>

---
 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
Documentation/core-api/exec-binfmt.rst new file +30 -0
new file mode 100644
index 000000000000..7e9b515a8107
@@ -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:
Documentation/core-api/index.rst +1 -0
index e9789bd381d8..e44b9b2e60ef 100644
@@ -62,6 +62,7 @@ Low level entry and exit
    :maxdepth: 1
 
    entry
+   exec-binfmt
 
 Concurrency primitives
 ======================
MAINTAINERS +1 -0
index fa1e04e87d1d..0dca4c2cbbff 100644
@@ -8820,6 +8820,7 @@ M:	Kees Cook <[email protected]>
 L:	[email protected]
 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
scripts/kernel-doc +2 -2
index af6cf408b96d..a2af8ac5acff 100755
@@ -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
Signature · 1 line
2.34.1
maintainer
#1 lore raw
Quoted 5 lines · 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].

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

author maintainer
#2 lore raw
Quoted 8 lines · Jonathan Corbet
Quoted 5 lines · 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].

Quoted 6 lines

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

Signature · 1 line
Kees Cook