From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.0 (2014-02-07) on aws-us-west-2-korg-lkml-1.web.codeaurora.org Received: from kanga.kvack.org (kanga.kvack.org [205.233.56.17]) by smtp.lore.kernel.org (Postfix) with ESMTP id DB4E0C369C2 for ; Sat, 26 Apr 2025 00:07:17 +0000 (UTC) Received: by kanga.kvack.org (Postfix) id 71DDB6B0008; Fri, 25 Apr 2025 20:07:15 -0400 (EDT) Received: by kanga.kvack.org (Postfix, from userid 40) id 6CB706B000A; Fri, 25 Apr 2025 20:07:15 -0400 (EDT) X-Delivered-To: int-list-linux-mm@kvack.org Received: by kanga.kvack.org (Postfix, from userid 63042) id 5B9B06B000C; Fri, 25 Apr 2025 20:07:15 -0400 (EDT) X-Delivered-To: linux-mm@kvack.org Received: from relay.hostedemail.com (smtprelay0017.hostedemail.com [216.40.44.17]) by kanga.kvack.org (Postfix) with ESMTP id 3C1C96B0008 for ; Fri, 25 Apr 2025 20:07:15 -0400 (EDT) Received: from smtpin20.hostedemail.com (a10.router.float.18 [10.200.18.1]) by unirelay02.hostedemail.com (Postfix) with ESMTP id 7D7F4120DA8 for ; Sat, 26 Apr 2025 00:07:16 +0000 (UTC) X-FDA: 83374255272.20.FD6897A Received: from sea.source.kernel.org (sea.source.kernel.org [172.234.252.31]) by imf24.hostedemail.com (Postfix) with ESMTP id A9598180007 for ; Sat, 26 Apr 2025 00:07:14 +0000 (UTC) Authentication-Results: imf24.hostedemail.com; dkim=pass header.d=kernel.org header.s=k20201202 header.b=LyxhD+pD; dmarc=pass (policy=quarantine) header.from=kernel.org; spf=pass (imf24.hostedemail.com: domain of kees@kernel.org designates 172.234.252.31 as permitted sender) smtp.mailfrom=kees@kernel.org ARC-Seal: i=1; s=arc-20220608; d=hostedemail.com; t=1745626034; a=rsa-sha256; cv=none; b=xMWk8ZnSRC1jV88PBaG8JtMHqz0Xq9IGbAVX1SxUyuDmN8cGGNaLCtj69XtttRDVHgq6Uk 7TqQ9L+QA5QsdMH2l4DsrjiE1pIgnl7LPIXeOKAK04mlRw/0Pjyvbhnr2ijvuBpTAxkXwC 8JVndC3ggDx8MDBMApoYqtoqnvX0dyQ= ARC-Authentication-Results: i=1; imf24.hostedemail.com; dkim=pass header.d=kernel.org header.s=k20201202 header.b=LyxhD+pD; dmarc=pass (policy=quarantine) header.from=kernel.org; spf=pass (imf24.hostedemail.com: domain of kees@kernel.org designates 172.234.252.31 as permitted sender) smtp.mailfrom=kees@kernel.org ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=hostedemail.com; s=arc-20220608; t=1745626034; h=from:from:sender:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-type:content-transfer-encoding:content-transfer-encoding: in-reply-to:references:dkim-signature; bh=px+dfjeUQf1kyiyqiSHVYo2IX7u/x8JnSP+Y8gqDPqg=; b=RxjGPGTetH8RLKeFZCZtdb0oo3cosxhJFKEQS49bEZBJU7ACimC/qbZ0BzfdP4ZutCTB1l 1JlRghMBfi14jWoBmC5GBL2WYLsn2d/87EX8uuAzFRSOm8iaeWrOOwrPIC/swQxUBuEoB6 VtT7mkvF5KnSno623nOu2SmRk+QZXcI= Received: from smtp.kernel.org (transwarp.subspace.kernel.org [100.75.92.58]) by sea.source.kernel.org (Postfix) with ESMTP id 7EA4543883; Sat, 26 Apr 2025 00:07:11 +0000 (UTC) Received: by smtp.kernel.org (Postfix) with ESMTPSA id 08D51C4CEE4; Sat, 26 Apr 2025 00:07:13 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/simple; d=kernel.org; s=k20201202; t=1745626033; bh=UoxqykoSJQYy0HuyseAsAhDvn5nbQ6gFG5I+BwMHNN4=; h=From:To:Cc:Subject:Date:From; b=LyxhD+pDYH3mjbUMG//m/KUkrdANKLMw3grgt8i8YT5xwkE94n8Z2aiuf6XSevq2g cUHMR3b4atIiGWOAU3grWRCvFXXF0fcDQR09BX2ocOaaXlzO20JvFbpdLb030pXKxc iHdfSnyN+dCNzw4+GhYAxntVXppGpPrjCp0BG6a/GFkaJpRxyquZDQ14mKf65j2Sp6 sygJeHT2VQPsZqXKH6uEHk75BD4CbiM1iIusPGtx9gatYZqOfJNEnMV4tOfBGZaR5I +nP5iiDOGtLZbU/uGNGP0nbT5COPK3Pp2Kkwx0/y0M6IG0h+FhlyjUZCHSUI1UE/40 +hOxdd4ba+ONw== From: Kees Cook To: Jonathan Corbet Cc: Kees Cook , Andrew Morton , Randy Dunlap , Bagas Sanjaya , Mike Rapoport , Arnd Bergmann , linux-doc@vger.kernel.org, linux-mm@kvack.org, Maxime Ripard , Tejun Heo , Natalie Vock , Xavier , Samuel Holland , Maarten Lankhorst , Dan Williams , Michael Kelley , Kuan-Wei Chiu , Christian Brauner , linux-kernel@vger.kernel.org, linux-hardening@vger.kernel.org Subject: [PATCH] kernel-doc: Add initial binfmt docs Date: Fri, 25 Apr 2025 17:07:09 -0700 Message-Id: <20250426000704.work.637-kees@kernel.org> X-Mailer: git-send-email 2.34.1 MIME-Version: 1.0 X-Developer-Signature: v=1; a=openpgp-sha256; l=3675; i=kees@kernel.org; h=from:subject:message-id; bh=UoxqykoSJQYy0HuyseAsAhDvn5nbQ6gFG5I+BwMHNN4=; b=owGbwMvMwCVmps19z/KJym7G02pJDBk8ymv+MN5+cXzSpIM+axNt1BPnLo44Hs5T8Nn678GH0 zgkD3m96ihlYRDjYpAVU2QJsnOPc/F42x7uPlcRZg4rE8gQBi5OAZjIp90M//StpQIm+71lj3ER dbGc5rC16sK9oG6B8NT7/3J2Vvzfb8Hwv+6MpNf2ra1yyxmT2X/2xpx7+Wv5E7U1EYcuf26KLZ2 iygQA X-Developer-Key: i=kees@kernel.org; a=openpgp; fpr=A5C3F68F229DD60F723E6E138972F4DFDC6DC026 Content-Transfer-Encoding: 8bit X-Rspamd-Queue-Id: A9598180007 X-Stat-Signature: db6paco87ihdmjkbajeq4r5o74e8q11c X-Rspam-User: X-Rspamd-Server: rspam08 X-HE-Tag: 1745626034-770430 X-HE-Meta: U2FsdGVkX1+WTxRE4VckwhrXWvZAgv4ZNxho1UJPVZh2yFkAoAeu9ZPR4ODRzc9h6oKeVKQ1CDp3e+Glc270aLJVCbzRCKTZas7LtT+CHgHEXkyuun3bi4g87tYnGu29mwGLpjEY+0RhBxYk3DrWykQL9Mk6gWMi9i+Cw2cnsYuye72QNG8BBHqvVWBekLR8BxnEzpeyuxD6iBldvT21DkrOmduVNkY4S5BYiQZQ4T1yzA9WTWcYUaykY9zhwhJWNcq6RLPt+Dc6ylz8MFRO8X7srz2HvgubDNVg8vz/iu6dT6wFxyQ77rc3jFYebync6YeOE6T3aNZFTw88i5y+PfL6LxYAWU7CxvbfzHpAc6d60X37W2JpYNmtR/y0AC7QZzubK8nPXlz6rXkrJtgrlOPzXZJo5xwakqLS9t4Kw9pY9Wevkx7bM5j4xJbgztwtccEBCsKSxtsQp6ALWAD44UdRPAjTuk57KbdZqSy68wKpwWuE6F74TRZslGsFOd0KPy5mYMryiHZX/dNtWJz0rKRsgLZUPbpcGo4qSRnFxn6D4Eui2bd6/iN4VOzsPKvT1xw4xO0Q8hbFA3xjKduqku5iHbgJQBKGGu1dI831aYVcQAxZNi+UYYW9Ik/rJtMcPt7XEZfZFNhgPL3YX7nVhEFzEo85/oIr3VSbIAJHM3pQ9luJOYBzMd1U+iQFEl5x8BTIDGY340O57+jFomZGK6Sp5kaatCkO3XhLy8euL1R9OnKUFw4Zql3IrIYWw2nPGIXi+85Li2NZFiIIoeDoey5B/cujYg0PV4kVelrYwLKO84Hthufg2bwuSbkLxV2F2vig63phcgbvxaNzVd6wv2FnsWyOJNPXX8tZWvAgZ0FK/7M/VQJfsM4y9XAKfb0P5cpUZy4vc2oF0u96WhwoJSARYoc2YB8J25WMjA+1M9rD6rMwBgfZRIwPwsIwhbYmj0SswbrQKmBgKMftcuy p+0VmeeY 2WPuMTprvNkJdHDWaJK1BO74BsGNbXHwTcVO3g/RVCF2sm1neT4ucz62QO95+g/eOSEeXsI2aRLRSFZR2qiuFevb7jKH2ZLSD28gTFGFPX4lfYjd7krLa68tjTmruTSlAV/bWUYaVODZmWyAfhcLD/fmgC/4obT1F4yhJAWDriP2kEc3CLxGRhsOAw/u2/pbiaptVO2M9k2rvKwh0nm7XwEMmIkY11YiRmvpNq4fwUtsZXULpSvoDKfbCW4QA7sseR5oFbbtfQOBd0gxhWsR4kz+RjBEmhgeBXQENpEc06QbhA8eN1cW08ihcuLJtmP63ea7r3kOtTFKX5E4xvip+R6oMiThEJcdLEhZOaU1TZ7Pv8zPPcsAwyWUiZv6sM+eDlhYAOV+P2jOd9EPx50ZZiTF0kJw5ybBIJzDjmxhqSMfYmysA2gFvAvu8DxhuxhkieciYjNLOpfcX2xvmCjQ95qugltsbEtvA+7XO8crdWSdXP5YaKi1gRXYMug== X-Bogosity: Ham, tests=bogofilter, spamicity=0.000000, version=1.2.4 Sender: owner-linux-mm@kvack.org Precedence: bulk X-Loop: owner-majordomo@kvack.org List-ID: List-Subscribe: List-Unsubscribe: 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 --- Cc: Jonathan Corbet Cc: Andrew Morton Cc: Randy Dunlap Cc: Bagas Sanjaya Cc: Mike Rapoport Cc: Arnd Bergmann Cc: Cc: --- 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 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 () { - while (!/^ \*/ && s/\\\s*$//) { + while (!/^\s* \*/ && s/\\\s*$//) { $_ .= ; } # Replace tabs by spaces -- 2.34.1