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

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [day] [month] [year] [list]

Message-Id: <20250426000704.work.637-kees@kernel.org>
Date: Fri, 25 Apr 2025 17:07:09 -0700
From: Kees Cook <kees@...nel.org>
To: Jonathan Corbet <corbet@....net>
Cc: Kees Cook <kees@...nel.org>,
	Andrew Morton <akpm@...ux-foundation.org>,
	Randy Dunlap <rdunlap@...radead.org>,
	Bagas Sanjaya <bagasdotme@...il.com>,
	Mike Rapoport <rppt@...nel.org>,
	Arnd Bergmann <arnd@...db.de>,
	linux-doc@...r.kernel.org,
	linux-mm@...ck.org,
	Maxime Ripard <mripard@...nel.org>,
	Tejun Heo <tj@...nel.org>,
	Natalie Vock <natalie.vock@....de>,
	Xavier <xavier_qy@....com>,
	Samuel Holland <samuel.holland@...ive.com>,
	Maarten Lankhorst <dev@...khorst.se>,
	Dan Williams <dan.j.williams@...el.com>,
	Michael Kelley <mhklinux@...look.com>,
	Kuan-Wei Chiu <visitorckw@...il.com>,
	Christian Brauner <brauner@...nel.org>,
	linux-kernel@...r.kernel.org,
	linux-hardening@...r.kernel.org
Subject: [PATCH] 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/20250425224502.work.520-kees@kernel.org/ [1]
Signed-off-by: Kees Cook <kees@...nel.org>
---
Cc: Jonathan Corbet <corbet@....net>
Cc: Andrew Morton <akpm@...ux-foundation.org>
Cc: Randy Dunlap <rdunlap@...radead.org>
Cc: Bagas Sanjaya <bagasdotme@...il.com>
Cc: Mike Rapoport <rppt@...nel.org>
Cc: Arnd Bergmann <arnd@...db.de>
Cc: <linux-doc@...r.kernel.org>
Cc: <linux-mm@...ck.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@...nel.org>
 L:	linux-mm@...ck.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