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] 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 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 <[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 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
