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@xxxxxxxxxx/ [1] Signed-off-by: Kees Cook <kees@xxxxxxxxxx> --- Cc: Jonathan Corbet <corbet@xxxxxxx> Cc: Andrew Morton <akpm@xxxxxxxxxxxxxxxxxxxx> Cc: Randy Dunlap <rdunlap@xxxxxxxxxxxxx> Cc: Bagas Sanjaya <bagasdotme@xxxxxxxxx> Cc: Mike Rapoport <rppt@xxxxxxxxxx> Cc: Arnd Bergmann <arnd@xxxxxxxx> Cc: <linux-doc@xxxxxxxxxxxxxxx> Cc: <linux-mm@xxxxxxxxx> --- 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@xxxxxxxxxx> L: linux-mm@xxxxxxxxx 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
