* [PATCH v3 03/12] docs: maintainers: add SPDX license to the file
From: Mauro Carvalho Chehab @ 2026-04-27 13:00 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Shuah Khan
In-Reply-To: <cover.1777294623.git.mchehab+huawei@kernel.org>
While this file is really trivial, add a SPDX license line on it.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
---
Documentation/process/maintainers.rst | 2 ++
1 file changed, 2 insertions(+)
diff --git a/Documentation/process/maintainers.rst b/Documentation/process/maintainers.rst
index 6174cfb4138f..5d1b1464c3ae 100644
--- a/Documentation/process/maintainers.rst
+++ b/Documentation/process/maintainers.rst
@@ -1 +1,3 @@
+.. SPDX-License-Identifier: GPL-2.0
+
.. maintainers-include::
--
2.53.0
^ permalink raw reply related
* [PATCH v3 04/12] docs: maintainers_include: auto-generate maintainer profile TOC
From: Mauro Carvalho Chehab @ 2026-04-27 13:00 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List, Mauro Carvalho Chehab
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Shuah Khan, Dan Williams
In-Reply-To: <cover.1777294623.git.mchehab+huawei@kernel.org>
Add a feature to allow auto-generating media entry profiles from the
corresponding field inside MAINTAINERS file(s).
Suggested-by: Dan Williams <djbw@kernel.org>
Closes: https://lore.kernel.org/linux-doc/69dd6299440be_147c801005b@djbw-dev.notmuch/
Acked-by: Dan Williams <djbw@kernel.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Message-ID: <4e9512a3d05942c98361d06d60a118d7c78762b6.1776176108.git.mchehab+huawei@kernel.org>
---
Documentation/sphinx/maintainers_include.py | 93 +++++++++++++++++----
1 file changed, 76 insertions(+), 17 deletions(-)
diff --git a/Documentation/sphinx/maintainers_include.py b/Documentation/sphinx/maintainers_include.py
index 519ad18685b2..1dac83bf1a65 100755
--- a/Documentation/sphinx/maintainers_include.py
+++ b/Documentation/sphinx/maintainers_include.py
@@ -21,6 +21,8 @@ import sys
import re
import os.path
+from textwrap import indent
+
from docutils import statemachine
from docutils.parsers.rst import Directive
from docutils.parsers.rst.directives.misc import Include
@@ -30,20 +32,11 @@ def ErrorString(exc): # Shamelessly stolen from docutils
__version__ = '1.0'
-def setup(app):
- app.add_directive("maintainers-include", MaintainersInclude)
- return dict(
- version = __version__,
- parallel_read_safe = True,
- parallel_write_safe = True
- )
+class MaintainersParser:
+ """Parse MAINTAINERS file(s) content"""
-class MaintainersInclude(Include):
- """MaintainersInclude (``maintainers-include``) directive"""
- required_arguments = 0
-
- def parse_maintainers(self, path):
- """Parse all the MAINTAINERS lines into ReST for human-readability"""
+ def __init__(self, base_path, path):
+ self.profiles = list()
result = list()
result.append(".. _maintainers:")
@@ -78,6 +71,12 @@ class MaintainersInclude(Include):
# Drop needless input whitespace.
line = line.rstrip()
+ match = re.match(r"P:\s*(Documentation/\S+)\.rst", line)
+ if match:
+ fname = os.path.relpath(match.group(1), base_path)
+ if fname not in self.profiles:
+ self.profiles.append(fname)
+
# Linkify all non-wildcard refs to ReST files in Documentation/.
pat = r'(Documentation/([^\s\?\*]*)\.rst)'
m = re.search(pat, line)
@@ -165,12 +164,23 @@ class MaintainersInclude(Include):
for separated in field_content.split('\n'):
result.append(separated)
- output = "\n".join(result)
+ self.output = "\n".join(result)
+
+ # Create a TOC class
+
+class MaintainersInclude(Include):
+ """MaintainersInclude (``maintainers-include``) directive"""
+ required_arguments = 0
+
+ def emit(self, base_path, path):
+ """Parse all the MAINTAINERS lines into ReST for human-readability"""
+
+ output = MaintainersParser(base_path, path).output
+
# For debugging the pre-rendered results...
#print(output, file=open("/tmp/MAINTAINERS.rst", "w"))
- self.state_machine.insert_input(
- statemachine.string2lines(output), path)
+ self.state_machine.insert_input(statemachine.string2lines(output), path)
def run(self):
"""Include the MAINTAINERS file as part of this reST file."""
@@ -186,12 +196,61 @@ class MaintainersInclude(Include):
# Append "MAINTAINERS"
path = os.path.join(path, "MAINTAINERS")
+ base_path = os.path.dirname(self.state.document.document.current_source)
try:
self.state.document.settings.record_dependencies.add(path)
- lines = self.parse_maintainers(path)
+ lines = self.emit(base_path, path)
except IOError as error:
raise self.severe('Problems with "%s" directive path:\n%s.' %
(self.name, ErrorString(error)))
return []
+
+class MaintainersProfile(Include):
+ required_arguments = 0
+
+ def emit(self, base_path, path):
+ """Parse all the MAINTAINERS lines looking for profile entries"""
+
+ profiles = MaintainersParser(base_path, path).profiles
+
+ output = ".. toctree::\n"
+ output += " :maxdepth: 2\n\n"
+ output += indent("\n".join(profiles), " ")
+
+ self.state_machine.insert_input(statemachine.string2lines(output), path)
+
+ def run(self):
+ """Include the MAINTAINERS file as part of this reST file."""
+ if not self.state.document.settings.file_insertion_enabled:
+ raise self.warning('"%s" directive disabled.' % self.name)
+
+ # Walk up source path directories to find Documentation/../
+ path = self.state_machine.document.attributes['source']
+ path = os.path.realpath(path)
+ tail = path
+ while tail != "Documentation" and tail != "":
+ (path, tail) = os.path.split(path)
+
+ # Append "MAINTAINERS"
+ path = os.path.join(path, "MAINTAINERS")
+ base_path = os.path.dirname(self.state.document.document.current_source)
+
+ try:
+ self.state.document.settings.record_dependencies.add(path)
+ lines = self.emit(base_path, path)
+ except IOError as error:
+ raise self.severe('Problems with "%s" directive path:\n%s.' %
+ (self.name, ErrorString(error)))
+
+ return []
+
+def setup(app):
+ app.add_directive("maintainers-include", MaintainersInclude)
+ app.add_directive("maintainers-profile-toc", MaintainersProfile)
+ return dict(
+ version = __version__,
+ parallel_read_safe = True,
+ parallel_write_safe = True
+ )
--
2.53.0
^ permalink raw reply related
* [PATCH v3 01/12] MAINTAINERS: add an entry for media maintainers profile
From: Mauro Carvalho Chehab @ 2026-04-27 13:00 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Randy Dunlap
In-Reply-To: <cover.1777294623.git.mchehab+huawei@kernel.org>
The media subsystem has a maintainers entry profile, but its entry
is missing at MAINTAINERS.
Add it.
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Message-ID: <5af4aa6a716228eea4d59dc26b97d642e1e7d419.1776176108.git.mchehab+huawei@kernel.org>
---
MAINTAINERS | 1 +
1 file changed, 1 insertion(+)
diff --git a/MAINTAINERS b/MAINTAINERS
index 2fb1c75afd16..f52ec50f6d10 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -16223,6 +16223,7 @@ P: Documentation/driver-api/media/maintainer-entry-profile.rst
W: https://linuxtv.org
Q: https://patchwork.linuxtv.org/project/linux-media/list/
T: git git://linuxtv.org/media.git
+P: Documentation/driver-api/media/maintainer-entry-profile.rst
F: Documentation/admin-guide/media/
F: Documentation/devicetree/bindings/media/
F: Documentation/driver-api/media/
--
2.53.0
^ permalink raw reply related
* [PATCH v3 00/12] Auto-generate maintainer profile entries
From: Mauro Carvalho Chehab @ 2026-04-27 13:00 UTC (permalink / raw)
To: Albert Ou, Jonathan Corbet, Mauro Carvalho Chehab, Palmer Dabbelt,
Paul Walmsley
Cc: Mauro Carvalho Chehab, linux-doc, linux-kernel, linux-riscv,
workflows, Alexandre Ghiti, Shuah Khan, Randy Dunlap,
Dan Williams
Hi Jon,
This is basically the same patch series I sent during the merge
window, rebased on the top of post 7.1-rc1 docs-next branch.
It is tested both with and without O=DOCS.
It contains just one extra trivial patch adding a missing SPDX
header.
This patch series change the way maintainer entry profile links
are added to the documentation. Instead of having an entry for
each of them at an ReST file, get them from MAINTAINERS content.
That should likely make easier to maintain, as there will be a single
point to place all such profiles.
The output is a per-subsystem sorted (*) series of links shown as a
list like this:
- Arm And Arm64 Soc Sub-Architectures (Common Parts)
- Arm/Samsung S3C, S5P And Exynos Arm Architectures
- Arm/Tesla Fsd Soc Support
...
- Xfs Filesystem
Please notice that the series is doing one logical change per patch.
I could have merged some changes altogether, but I opted doing it
in small steps to help reviews. If you prefer, feel free to merge
maintainers_include changes on merge.
There is one interesting side effect of this series: there is no
need to add rst files containing profiles inside a TOC tree: Just
creating the file anywhere inside Documentation and adding a P entry
is enough. Adding them to a TOC won't hurt.
Reported-by: Randy Dunlap <rdunlap@infradead.org>
Suggested-by: Dan Williams <djbw@kernel.org>
Closes: https://lore.kernel.org/linux-doc/69dd6299440be_147c801005b@djbw-dev.notmuch/
(*) At the end, I opted to use sorted(), just to ensure it, even
knowing that MAINTAINER entries are supposed to be sorted, as
the cost of sorting ~20 already-sorted entries is negligible.
---
v3:
- Added SPDX entry to process/maintainers.rst file;
- rebased after 7.1-rc1 release.
v2:
- I placed the to MAINTAINERS changes at the beginning.
- fix a bug when O=DOCS is used;
- proper handle glob "P" entries (just in case, no profiles use it ATM);
- when SPHINXDIRS=process, instead of producing warnings, point to
entries at https://docs.kernel.org;
- MAINTAINERS parsing now happens just once;
- The output won't be numered for entries inside numered TOC trees;
- TOC tree is now hidden;
- instead of display a TOC tree, it shows a list of profiles,
ordered and named after file system name taken from MAINTAINERS file;
- At the output list, both https and file profiles are shown the same
way.
Mauro Carvalho Chehab (12):
MAINTAINERS: add an entry for media maintainers profile
MAINTAINERS: add maintainer-tip.rst to X86
docs: maintainers: add SPDX license to the file
docs: maintainers_include: auto-generate maintainer profile TOC
docs: auto-generate maintainer entry profile links
docs: maintainers_include: use a better title for profiles
docs: maintainers_include: add external profile URLs
docs: maintainers_include: preserve names for files under process/
docs: maintainers_include: Only show main entry for profiles
docs: maintainers_include: improve its output
docs: maintainers_include: fix support for O=dir
docs: maintainers_include: parse MAINTAINERS just once
.../maintainer/maintainer-entry-profile.rst | 24 +--
.../process/maintainer-handbooks.rst | 17 +-
Documentation/process/maintainers.rst | 2 +
Documentation/sphinx/maintainers_include.py | 161 +++++++++++++++---
MAINTAINERS | 2 +
5 files changed, 152 insertions(+), 54 deletions(-)
--
2.53.0
^ permalink raw reply
* [PATCH v3 02/12] MAINTAINERS: add maintainer-tip.rst to X86
From: Mauro Carvalho Chehab @ 2026-04-27 13:00 UTC (permalink / raw)
To: Jonathan Corbet, Linux Doc Mailing List
Cc: Mauro Carvalho Chehab, linux-kernel, linux-riscv, workflows,
Randy Dunlap, Dan Williams
In-Reply-To: <cover.1777294623.git.mchehab+huawei@kernel.org>
The X86 subsystem has a maintainers entry profile, but its entry
is missing at MAINTAINERS.
Add it.
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Acked-by: Dan Williams <djbw@kernel.org>
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Message-ID: <970434c647aa1e1e9a81c87b4d5fed934d4018a7.1776176108.git.mchehab+huawei@kernel.org>
---
MAINTAINERS | 1 +
1 file changed, 1 insertion(+)
diff --git a/MAINTAINERS b/MAINTAINERS
index f52ec50f6d10..a00d4ba61c2a 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -28808,6 +28808,7 @@ M: Ingo Molnar <mingo@redhat.com>
M: Borislav Petkov <bp@alien8.de>
M: Dave Hansen <dave.hansen@linux.intel.com>
M: x86@kernel.org
+P: Documentation/process/maintainer-tip.rst
R: "H. Peter Anvin" <hpa@zytor.com>
L: linux-kernel@vger.kernel.org
S: Maintained
--
2.53.0
^ permalink raw reply related
* Re: [PATCH v3 3/3] Documentation: deprecated.rst: kmalloc-family: mark argument as optional
From: Jonathan Corbet @ 2026-04-27 9:51 UTC (permalink / raw)
To: Manuel Ebner, Shuah Khan, linux-doc, Kees Cook, linux-kernel
Cc: workflows, linux-mm, Geert Uytterhoeven, Manuel Ebner
In-Reply-To: <20260424175740.258522-2-manuelebner@mailbox.org>
Manuel Ebner <manuelebner@mailbox.org> writes:
> put the optional argument (gfp) in square brackets
> add whitespace for readability
>
> eg. ptr = kmalloc_obj(*ptr, gfp);
> -> ptr = kmalloc_obj(*ptr [, gfp] );
>
> Signed-off-by: Manuel Ebner <manuelebner@mailbox.org>
> ---
> Documentation/process/deprecated.rst | 12 ++++++------
> 1 file changed, 6 insertions(+), 6 deletions(-)
>
> diff --git a/Documentation/process/deprecated.rst b/Documentation/process/deprecated.rst
> index fed56864d036..b431993fd08e 100644
> --- a/Documentation/process/deprecated.rst
> +++ b/Documentation/process/deprecated.rst
> @@ -392,12 +392,12 @@ allocations. For example, these open coded assignments::
>
> become, respectively::
>
> - ptr = kmalloc_obj(*ptr, gfp);
> - ptr = kzalloc_obj(*ptr, gfp);
> - ptr = kmalloc_objs(*ptr, count, gfp);
> - ptr = kzalloc_objs(*ptr, count, gfp);
> - ptr = kmalloc_flex(*ptr, flex_member, count, gfp);
> - __auto_type ptr = kmalloc_obj(struct foo, gfp);
> + ptr = kmalloc_obj(*ptr [, gfp] );
> + ptr = kzalloc_obj(*ptr [, gfp] );
> + ptr = kmalloc_objs(*ptr, count [, gfp] );
> + ptr = kzalloc_objs(*ptr, count [, gfp] );
> + ptr = kmalloc_flex(*ptr, flex_member, count [, gfp] );
> + __auto_type ptr = kmalloc_obj(struct foo [, gfp] );
>
Marking the GFP argument as optional is fine, but the documentation
should surely say what the default is.
There are, of course, other kmalloc()-related entries in that file that
could use an update, but that is a job for another time, I guess.
Thanks,
jon
^ permalink raw reply
* Re: [PATCH v3 1/9] kernel/api: introduce kernel API specification framework
From: Nathan Chancellor @ 2026-04-27 3:37 UTC (permalink / raw)
To: Sasha Levin
Cc: linux-api, linux-kernel, linux-doc, linux-fsdevel, linux-kbuild,
linux-kselftest, workflows, tools, x86, Thomas Gleixner,
Paul E . McKenney, Greg Kroah-Hartman, Jonathan Corbet,
Dmitry Vyukov, Randy Dunlap, Cyril Hrubis, Kees Cook, Jake Edge,
David Laight, Askar Safin, Gabriele Paoloni,
Mauro Carvalho Chehab, Christian Brauner, Alexander Viro,
Andrew Morton, Masahiro Yamada, Shuah Khan, Ingo Molnar,
Arnd Bergmann
In-Reply-To: <20260424165130.2306833-2-sashal@kernel.org>
On Fri, 24 Apr 2026 12:51:21 -0400, Sasha Levin <sashal@kernel.org> wrote:
> diff --git a/kernel/Makefile b/kernel/Makefile
> index 6785982013dc..564315153643 100644
> --- a/kernel/Makefile
> +++ b/kernel/Makefile
> @@ -59,6 +59,9 @@ obj-y += dma/
> obj-y += entry/
> obj-y += unwind/
> obj-$(CONFIG_MODULES) += module/
> +obj-$(CONFIG_KAPI_SPEC) += api/
> +# Ensure api/ is always cleaned even when CONFIG_KAPI_SPEC is not set
> +obj- += api/
If $(CONFIG_KAPI_SPEC) is not set, shouldn't
obj-$(CONFIG_KAPI_SPEC) += api/
evaluate to
obj- += api/
anyways? Why the duplication? This is the only place in the kernel where
this would be needed?
>
> diff --git a/kernel/api/.gitignore b/kernel/api/.gitignore
> new file mode 100644
> index 000000000000..ca2f632621cf
> --- /dev/null
> +++ b/kernel/api/.gitignore
> @@ -0,0 +1,2 @@
> +# SPDX-License-Identifier: GPL-2.0-only
> +/generated_api_specs.c
This appears unused?
>
> diff --git a/kernel/api/Kconfig b/kernel/api/Kconfig
> new file mode 100644
> index 000000000000..d1072728742a
> --- /dev/null
> +++ b/kernel/api/Kconfig
> @@ -0,0 +1,77 @@
> +# SPDX-License-Identifier: GPL-2.0-only
> +#
> +# Kernel API Specification Framework Configuration
> +#
> +
> +config KAPI_SPEC
> + bool "Kernel API Specification Framework"
> + default n
I think 'default n' is tautological since 'n' is the default for all
bool symbols. Consider dropping it on all symbols throughtout this file.
--
Nathan Chancellor <nathan@kernel.org>
^ permalink raw reply
* Re: [PATCH 3/3] Documentation: security-bugs: clarify requirements for AI-assisted reports
From: Willy Tarreau @ 2026-04-27 2:22 UTC (permalink / raw)
To: Randy Dunlap
Cc: greg, leon, security, Jonathan Corbet, skhan, workflows,
linux-doc, linux-kernel, Greg KH
In-Reply-To: <133e96b7-251d-4af2-8084-2adca3e547e4@infradead.org>
On Sun, Apr 26, 2026 at 12:36:28PM -0700, Randy Dunlap wrote:
>
>
> On 4/26/26 9:39 AM, Willy Tarreau wrote:
> > +Use common sense when evaluating the report. If the affected file has not been
> > +touched for more than one year and is maintained by a single individual, it is
> > +likely that usage has declined and exposed users are virtually non-existent
> > +(e.g., drivers for very old hardware, obsolte filesystems). In such cases,
>
> obsolete
(...)
Thank you Randy for your reviews! I'll apply the fixes and resend in a
few days if there are no more comments.
Willy
^ permalink raw reply
* Re: [PATCH 3/3] Documentation: security-bugs: clarify requirements for AI-assisted reports
From: Randy Dunlap @ 2026-04-26 19:36 UTC (permalink / raw)
To: Willy Tarreau, greg
Cc: leon, security, Jonathan Corbet, skhan, workflows, linux-doc,
linux-kernel, Greg KH
In-Reply-To: <20260426163914.19449-4-w@1wt.eu>
On 4/26/26 9:39 AM, Willy Tarreau wrote:
> +Use common sense when evaluating the report. If the affected file has not been
> +touched for more than one year and is maintained by a single individual, it is
> +likely that usage has declined and exposed users are virtually non-existent
> +(e.g., drivers for very old hardware, obsolte filesystems). In such cases,
obsolete
> +there is no need to consume a maintainer's time with an unimportant report. If
> +the issue is clearly trivial and publicly discoverable, you should report it
> +directly to the public mailing lists.
--
~Randy
^ permalink raw reply
* Re: [PATCH 2/3] Documentation: security-bugs: explain what is and is not a security bug
From: Randy Dunlap @ 2026-04-26 19:33 UTC (permalink / raw)
To: Willy Tarreau, greg
Cc: leon, security, Jonathan Corbet, skhan, workflows, linux-doc,
linux-kernel, Greg KH
In-Reply-To: <20260426163914.19449-3-w@1wt.eu>
On 4/26/26 9:39 AM, Willy Tarreau wrote:
> The use of automated tools to find bugs in random locations of the kernel
> induces a raise of security reports even if most of them should just be
> reported as regular bugs. This patch is an attempt at drawing a line
> between what qualifies as a security bug and what does not, hoping to
> improve the situation.
>
> Cc: Greg KH <gregkh@linuxfoundation.org>
> Cc: Leon Romanovsky <leon@kernel.org>
> Suggested-by: Leon Romanovsky <leon@kernel.org>
> Signed-off-by: Willy Tarreau <w@1wt.eu>
> ---
>
> Leon, while we started this list before our discussion, I reused most of
> your proposal which was more comprehensive, and merged our initial work
> into it. I added you in Suggested-by: but I think that Co-developed-by:
> would be more suitable. If so, for this you'll have to also sign-off the
> patch. It's as you prefer, I personally don't care.
>
> ---
> Documentation/process/security-bugs.rst | 50 +++++++++++++++++++++++++
> 1 file changed, 50 insertions(+)
>
> diff --git a/Documentation/process/security-bugs.rst b/Documentation/process/security-bugs.rst
> index a8a8fc724e8c8..7cc3a1970ca00 100644
> --- a/Documentation/process/security-bugs.rst
> +++ b/Documentation/process/security-bugs.rst
> @@ -66,6 +66,56 @@ In addition, the following information are highly desirable:
> the issue appear. It is useful to share them, as they can be helpful to
> keep end users protected during the time it takes them to apply the fix.
>
> +What qualifies as a security bug
> +--------------------------------
> +
> +It is important that most bugs are handled publicly so as to involve the widest
> +possible audience and find the best solution. By nature, bugs that are handled
> +in closed discussions between a small set of participants are less likely to
> +produce the best possible fix (e.g., risk of missing valid use cases, limited
> +testing abilities).
> +
> +It turns out that the majority of the bugs reported to the security team are
> +just regular bugs that have been improperly qualified as security bugs due to a
> +misunderstanding of the Linux kernel's threat model, and ought to have been
> +sent through the normal channels described in
> +'Documentation/admin-guide/reporting-issues.rst'.
Remove the <'> marks and let automarkup handle the filename.
--
~Randy
^ permalink raw reply
* [PATCH 2/3] Documentation: security-bugs: explain what is and is not a security bug
From: Willy Tarreau @ 2026-04-26 16:39 UTC (permalink / raw)
To: greg
Cc: leon, security, Jonathan Corbet, skhan, workflows, linux-doc,
linux-kernel, Willy Tarreau, Greg KH
In-Reply-To: <20260426163914.19449-1-w@1wt.eu>
The use of automated tools to find bugs in random locations of the kernel
induces a raise of security reports even if most of them should just be
reported as regular bugs. This patch is an attempt at drawing a line
between what qualifies as a security bug and what does not, hoping to
improve the situation.
Cc: Greg KH <gregkh@linuxfoundation.org>
Cc: Leon Romanovsky <leon@kernel.org>
Suggested-by: Leon Romanovsky <leon@kernel.org>
Signed-off-by: Willy Tarreau <w@1wt.eu>
---
Leon, while we started this list before our discussion, I reused most of
your proposal which was more comprehensive, and merged our initial work
into it. I added you in Suggested-by: but I think that Co-developed-by:
would be more suitable. If so, for this you'll have to also sign-off the
patch. It's as you prefer, I personally don't care.
---
Documentation/process/security-bugs.rst | 50 +++++++++++++++++++++++++
1 file changed, 50 insertions(+)
diff --git a/Documentation/process/security-bugs.rst b/Documentation/process/security-bugs.rst
index a8a8fc724e8c8..7cc3a1970ca00 100644
--- a/Documentation/process/security-bugs.rst
+++ b/Documentation/process/security-bugs.rst
@@ -66,6 +66,56 @@ In addition, the following information are highly desirable:
the issue appear. It is useful to share them, as they can be helpful to
keep end users protected during the time it takes them to apply the fix.
+What qualifies as a security bug
+--------------------------------
+
+It is important that most bugs are handled publicly so as to involve the widest
+possible audience and find the best solution. By nature, bugs that are handled
+in closed discussions between a small set of participants are less likely to
+produce the best possible fix (e.g., risk of missing valid use cases, limited
+testing abilities).
+
+It turns out that the majority of the bugs reported to the security team are
+just regular bugs that have been improperly qualified as security bugs due to a
+misunderstanding of the Linux kernel's threat model, and ought to have been
+sent through the normal channels described in
+'Documentation/admin-guide/reporting-issues.rst'.
+
+The security list exists for urgent bugs that grant an attacker a capability
+they are not supposed to have on a correctly configured production system, and
+can be easily exploited, representing an imminent threat to many users. Before
+reporting, consider whether the issue actually crosses a trust boundary on such
+a system.
+
+In the Linux kernel's threat model, an issue is **not** a security bug, and
+should not be reported to the security list, when triggering it requires the
+reporter to first undermine the system they are attacking. This includes, but
+is not limited to, behavior that only manifests after the administrator has
+explicitly enabled it (loading a module, setting a sysctl, writing to a debugfs
+knob, or otherwise using an interface documented as privileged or unsafe); bugs
+reachable only through root or CAP_SYS_ADMIN or CAP_NET_ADMIN on a machine the
+actor already fully controls, with no further privilege boundary being crossed;
+prediction of random numbers that only works in a totally silent environment
+(such as IP ID, TCP ports or sequence numbers that can only be guessed in a
+lab), issues that appear only in debug, lockdep, KASAN, fault-injection,
+CONFIG_NOMMU, or other developer-oriented kernel builds that are not intended
+for production use; problems seen only under development simulators, emulators,
+or fuzzing harnesses that present hardware or input states which cannot occur
+on real systems; bugs that require modified or emulated hardware; missing
+hardening or defence-in-depth suggestions with no demonstrable exploit path
+(including local ASLR bypass); mounting file systems that would be fixed or
+rejected by fsck; and bugs in out-of-tree modules or vendor forks, which should
+be reported to the relevant vendor. Functional and performance regressions,
+and disagreements with documented kernel policy (for example, "root can load
+modules"), are likewise ordinary bugs or feature requests rather than security
+issues, and should be reported via the usual channels.
+
+If you are unsure whether an issue qualifies, err on the side of reporting
+privately: the security team would rather triage a borderline report than miss
+a real vulnerability. Reporting ordinary bugs to the security list, however,
+does not make them move faster and consumes triage capacity that other reports
+need.
+
Identifying contacts
--------------------
--
2.52.0
^ permalink raw reply related
* [PATCH 0/3] Documentation: security-bugs: new updates covering triage and AI
From: Willy Tarreau @ 2026-04-26 16:39 UTC (permalink / raw)
To: greg
Cc: leon, security, Jonathan Corbet, skhan, workflows, linux-doc,
linux-kernel, Willy Tarreau
This series tries to translate recent discussions on the security list
on how to better handle reports. It details:
- when not to Cc: the security list
- what classes of bugs do not need to be handled privately
- minimum requirements for AI-assisted reports
As usual, this is probably perfectible but can already help in the short
term as we can point it to reporters, so barring any strong disagreement,
better continue to proceed in small incremental improvements and observe
the effects.
Thanks!
Willy
---
Willy Tarreau (3):
Documentation: security-bugs: do not systematically Cc the security
team
Documentation: security-bugs: explain what is and is not a security
bug
Documentation: security-bugs: clarify requirements for AI-assisted
reports
Documentation/process/security-bugs.rst | 131 ++++++++++++++++++++++--
1 file changed, 120 insertions(+), 11 deletions(-)
--
2.52.0
^ permalink raw reply
* [PATCH 3/3] Documentation: security-bugs: clarify requirements for AI-assisted reports
From: Willy Tarreau @ 2026-04-26 16:39 UTC (permalink / raw)
To: greg
Cc: leon, security, Jonathan Corbet, skhan, workflows, linux-doc,
linux-kernel, Willy Tarreau, Greg KH
In-Reply-To: <20260426163914.19449-1-w@1wt.eu>
AI tools are increasingly used to assist in bug discovery. While these
tools can identify valid issues, reports that are submitted without
manual verification often lack context, contain speculative impact
assessments, or include unnecessary formatting. Such reports increase
triage effort, waste maintainers' time and may be ignored.
Reports where the reporter has verified the issue and the proposed fix
typically meet quality standards. This documentation outlines specific
requirements for length, formatting, and impact evaluation to reduce
the effort needed to deal with these reports.
Cc: Greg KH <gregkh@linuxfoundation.org>
Signed-off-by: Willy Tarreau <w@1wt.eu>
---
Documentation/process/security-bugs.rst | 55 +++++++++++++++++++++++++
1 file changed, 55 insertions(+)
diff --git a/Documentation/process/security-bugs.rst b/Documentation/process/security-bugs.rst
index 7cc3a1970ca00..803d8819694e7 100644
--- a/Documentation/process/security-bugs.rst
+++ b/Documentation/process/security-bugs.rst
@@ -180,6 +180,61 @@ the Linux kernel security team only. Your message will be triaged, and you
will receive instructions about whom to contact, if needed. Your message may
equally be forwarded as-is to the relevant maintainers.
+Responsible use of AI to find bugs
+----------------------------------
+
+A significant fraction of bug reports submitted to the security team are
+actually the result of code reviews assisted by AI tools. While this can be an
+efficient means to find bugs in rarely explored areas, it causes an overload on
+maintainers, who are sometimes forced to ignore such reports due to their poor
+quality or accuracy. As such, reporters must be particularly cautious about a
+number of points which tend to make these reports needlessly difficult to
+handle:
+
+ * **Length**: AI-generated reports tend to be excessively long, containing
+ multiple sections and excessive detail. This makes it difficult to spot
+ important information such as affected files, versions, and impact. Please
+ ensure that a clear summary of the problem and all critical details are
+ presented first. Do not require triage engineers to scan multiple pages of
+ text. Configure your tools to produce concise, human-style reports.
+
+ * **Formatting**: Most AI-generated reports are littered with Markdown tags.
+ These decorations complicate the search for important information and do
+ not survive the quoting processes involved in forwarding or replying.
+ Please **always convert your report to plain text** without any formatting
+ decorations before sending it.
+
+ * **Impact Evaluation**: Many AI-generated reports lack an understanding of
+ the kernel's threat model and go to great lengths inventing theoretical
+ consequences. This adds noise and complicates triage. Please stick to
+ verifiable facts (e.g., "this bug permits any user to gain CAP_NET_ADMIN")
+ without enumerating speculative implications. Have your tool read this
+ documentation as part of the evaluation process.
+
+ * **Reproducer**: AI-based tools are often capable of generating reproducers.
+ Please always ensure your tool provides one and **test it thoroughly**. If
+ the reproducer does not work, or if the tool cannot produce one, the
+ validity of the report should be seriously questioned.
+
+ * **Propose a Fix**: Many AI tools are actually better at writing code than
+ evaluating it. Please ask your tool to propose a fix and **test it** before
+ reporting the problem. If the fix cannot be tested because it relies on
+ rare hardware or almost extinct network protocols, the issue is likely not
+ a security bug. In any case, if a fix is proposed, it must adhere to
+ Documentation/process/submitting-patches.rst and include a 'Fixes:' tag
+ designating the commit that introduced the bug.
+
+Failure to consider these points exposes your report to the risk of being
+ignored.
+
+Use common sense when evaluating the report. If the affected file has not been
+touched for more than one year and is maintained by a single individual, it is
+likely that usage has declined and exposed users are virtually non-existent
+(e.g., drivers for very old hardware, obsolte filesystems). In such cases,
+there is no need to consume a maintainer's time with an unimportant report. If
+the issue is clearly trivial and publicly discoverable, you should report it
+directly to the public mailing lists.
+
Sending the report
------------------
--
2.52.0
^ permalink raw reply related
* [PATCH 1/3] Documentation: security-bugs: do not systematically Cc the security team
From: Willy Tarreau @ 2026-04-26 16:39 UTC (permalink / raw)
To: greg
Cc: leon, security, Jonathan Corbet, skhan, workflows, linux-doc,
linux-kernel, Willy Tarreau, Greg KH
In-Reply-To: <20260426163914.19449-1-w@1wt.eu>
With the increase of automated reports, the security team is dealing
with way more messages than really needed. The reporting process works
well with most teams so there is no need to systematically involve the
security team in reports.
Let's suggest to keep it for small lists of recipients, to cover the
risk of lost messages (spam, vacation etc) but to avoid it for larger
teams.
Cc: Greg KH <gregkh@linuxfoundation.org>
Cc: Leon Romanovsky <leon@kernel.org>
Signed-off-by: Willy Tarreau <w@1wt.eu>
---
Documentation/process/security-bugs.rst | 26 ++++++++++++++-----------
1 file changed, 15 insertions(+), 11 deletions(-)
diff --git a/Documentation/process/security-bugs.rst b/Documentation/process/security-bugs.rst
index 27b028e858610..a8a8fc724e8c8 100644
--- a/Documentation/process/security-bugs.rst
+++ b/Documentation/process/security-bugs.rst
@@ -70,11 +70,10 @@ Identifying contacts
--------------------
The most effective way to report a security bug is to send it directly to the
-affected subsystem's maintainers and Cc: the Linux kernel security team. Do
-not send it to a public list at this stage, unless you have good reasons to
-consider the issue as being public or trivial to discover (e.g. result of a
-widely available automated vulnerability scanning tool that can be repeated by
-anyone).
+affected subsystem's maintainers. Do not send it to a public list at this
+stage, unless you have good reasons to consider the issue as being public or
+trivial to discover (e.g. result of a widely available automated vulnerability
+scanning tool that can be repeated by anyone).
If you're sending a report for issues affecting multiple parts in the kernel,
even if they're fairly similar issues, please send individual messages (think
@@ -148,12 +147,17 @@ run additional tests. Reports where the reporter does not respond promptly
or cannot effectively discuss their findings may be abandoned if the
communication does not quickly improve.
-The report must be sent to maintainers, with the security team in ``Cc:``.
-The Linux kernel security team can be contacted by email at
-<security@kernel.org>. This is a private list of security officers
-who will help verify the bug report and assist developers working on a fix.
-It is possible that the security team will bring in extra help from area
-maintainers to understand and fix the security vulnerability.
+The report must be sent to maintainers. If there are two or fewer recipients
+in your message, and only in this case, you can also Cc: the Linux kernel
+security team who will ensure the message is delivered to the proper people,
+and will be able to assist small maintainers teams with a process they are not
+necessarily familiar with. For larger teams, please do not Cc: the Linux
+kernel security team, unless you're seeking specific help (e.g. when resending
+a message which got no response within a week). The Linux kernel security team
+can be contacted by email at <security@kernel.org>. This is a private list of
+security officers who will help verify the bug report and assist developers
+working on a fix. It is possible that the security team will bring in extra
+help from area maintainers to understand and fix the security vulnerability.
Please send **plain text** emails without attachments where possible.
It is much harder to have a context-quoted discussion about a complex
--
2.52.0
^ permalink raw reply related
* Re: [PATCH v3] checkpatch: add --json output mode
From: Sasha Levin @ 2026-04-26 11:23 UTC (permalink / raw)
To: Joe Perches
Cc: dwaipayanray1, lukas.bulwahn, mricon, corbet, skhan, apw,
workflows, linux-doc, linux-kernel
In-Reply-To: <1f8e71e117fbe7ff43723a863fd598c0568c4938.camel@perches.com>
On Sat, Apr 25, 2026 at 06:12:13PM -0700, Joe Perches wrote:
>On Sat, 2026-04-25 at 20:07 -0400, Sasha Levin wrote:
>> On Sat, Apr 25, 2026 at 02:52:35PM -0700, Joe Perches wrote:
>> On 2026-04-25 13:04, Sasha Levin wrote:
>> Add a --json flag to checkpatch.pl that emits structured JSON output,
>> > > making results machine-parseable for CI systems, IDE integrations, and
>> > > AI-assisted code review tools.
>> > []
>> > > A separate --json-pretty flag emits the same JSON in a pretty-printed
>> > > (indented, multi-line) form for human reading
>> > Why not just always use pretty?
>> > Would a script care?
>>
>> Who's the intended consumer for the --json-pretty?
>>
>> I my mind, --json is there to make it easier for tooling to process the output.
>
>Agree, but does the pretty output make it harder for tooling?
For real JSON parsers, no - they handle either form fine.
The one issue is multi-file invocations: --json emits one compact document per
file per line (NDJSON), which lets plain-shell consumers do `while read line;
do ...` or pipe through grep/awk/head. Pretty mode loses that property because
each document spans multiple lines, so consumers need a
streaming JSON parser.
--
Thanks,
Sasha
^ permalink raw reply
* Re: [PATCH v3] checkpatch: add --json output mode
From: Joe Perches @ 2026-04-26 9:47 UTC (permalink / raw)
To: Sasha Levin, dwaipayanray1, lukas.bulwahn
Cc: mricon, corbet, skhan, apw, workflows, linux-doc, linux-kernel
In-Reply-To: <20260425200431.4088895-1-sashal@kernel.org>
On Sat, 2026-04-25 at 16:04 -0400, Sasha Levin wrote:
> diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
[]
> @@ -2403,6 +2426,24 @@ sub report_dump {
> our @report;
> }
>
> +sub json_print_result {
> + my ($filename, $total_errors, $total_warnings, $total_checks,
> + $total_lines, $issues, $used_types, $ignored_types) = @_;
> + my %result = (
> + filename => $filename,
> + total_errors => $total_errors,
> + total_warnings => $total_warnings,
> + total_checks => $total_checks,
> + total_lines => $total_lines,
> + issues => $issues,
> + );
> + $result{used_types} = $used_types if (defined $used_types);
> + $result{ignored_types} = $ignored_types if (defined $ignored_types);
> + my $json_encoder = JSON::PP->new->canonical->utf8;
Maybe canonical isn't great as it outputs keys in alphabetic order.
The output may be more sensible in the defined order.
^ permalink raw reply
* Re: [PATCH v3] checkpatch: add --json output mode
From: Joe Perches @ 2026-04-26 1:12 UTC (permalink / raw)
To: Sasha Levin
Cc: dwaipayanray1, lukas.bulwahn, mricon, corbet, skhan, apw,
workflows, linux-doc, linux-kernel
In-Reply-To: <ae1XUFURKgdG6lGh@laps>
On Sat, 2026-04-25 at 20:07 -0400, Sasha Levin wrote:
> On Sat, Apr 25, 2026 at 02:52:35PM -0700, Joe Perches wrote:
> On 2026-04-25 13:04, Sasha Levin wrote:
> Add a --json flag to checkpatch.pl that emits structured JSON output,
> > > making results machine-parseable for CI systems, IDE integrations, and
> > > AI-assisted code review tools.
> > []
> > > A separate --json-pretty flag emits the same JSON in a pretty-printed
> > > (indented, multi-line) form for human reading
> > Why not just always use pretty?
> > Would a script care?
>
> Who's the intended consumer for the --json-pretty?
>
> I my mind, --json is there to make it easier for tooling to process the output.
Agree, but does the pretty output make it harder for tooling?
^ permalink raw reply
* Re: [PATCH v3] checkpatch: add --json output mode
From: Sasha Levin @ 2026-04-26 0:07 UTC (permalink / raw)
To: Joe Perches
Cc: dwaipayanray1, lukas.bulwahn, mricon, corbet, skhan, apw,
workflows, linux-doc, linux-kernel
In-Reply-To: <c8722587377c3bc4be03f7d04bd45912@perches.com>
On Sat, Apr 25, 2026 at 02:52:35PM -0700, Joe Perches wrote:
>On 2026-04-25 13:04, Sasha Levin wrote:
>>Add a --json flag to checkpatch.pl that emits structured JSON output,
>>making results machine-parseable for CI systems, IDE integrations, and
>>AI-assisted code review tools.
>[]
>>A separate --json-pretty flag emits the same JSON in a pretty-printed
>>(indented, multi-line) form for human reading
>
>Why not just always use pretty?
>Would a script care?
Who's the intended consumer for the --json-pretty?
I my mind, --json is there to make it easier for tooling to process the output.
A user can already achieve the same result by piping the json output through jq
or other similar tools:
$ ./scripts/checkpatch.pl --json 0001-checkpatch-add-json-output-mode.patch
{"filename":"0001-checkpatch-add-json-output-mode.patch","ignored_types":[],"issues":[],"total_checks":0,"total_errors":0,"total_lines":189,"total_warnings":0,"used_types":[]}
$ ./scripts/checkpatch.pl --json 0001-checkpatch-add-json-output-mode.patch | jq
{
"filename": "0001-checkpatch-add-json-output-mode.patch",
"ignored_types": [],
"issues": [],
"total_checks": 0,
"total_errors": 0,
"total_lines": 189,
"total_warnings": 0,
"used_types": []
}
--
Thanks,
Sasha
^ permalink raw reply
* Re: [PATCH v3] checkpatch: add --json output mode
From: Joe Perches @ 2026-04-25 21:52 UTC (permalink / raw)
To: Sasha Levin
Cc: dwaipayanray1, lukas.bulwahn, mricon, corbet, skhan, apw,
workflows, linux-doc, linux-kernel
In-Reply-To: <20260425200431.4088895-1-sashal@kernel.org>
On 2026-04-25 13:04, Sasha Levin wrote:
> Add a --json flag to checkpatch.pl that emits structured JSON output,
> making results machine-parseable for CI systems, IDE integrations, and
> AI-assisted code review tools.
[]
> A separate --json-pretty flag emits the same JSON in a pretty-printed
> (indented, multi-line) form for human reading
Why not just always use pretty?
Would a script care?
^ permalink raw reply
* [PATCH v3] checkpatch: add --json output mode
From: Sasha Levin @ 2026-04-25 20:04 UTC (permalink / raw)
To: dwaipayanray1, lukas.bulwahn
Cc: joe, mricon, corbet, skhan, apw, workflows, linux-doc,
linux-kernel, Sasha Levin
In-Reply-To: <20260408172435.1268067-1-sashal@kernel.org>
Add a --json flag to checkpatch.pl that emits structured JSON output,
making results machine-parseable for CI systems, IDE integrations, and
AI-assisted code review tools.
The JSON output includes per-file totals (errors, warnings, checks,
lines) and an array of individual issues with structured fields for
level, type, message, file path, and line number.
A separate --json-pretty flag emits the same JSON in a pretty-printed
(indented, multi-line) form for human reading.
The --json (and --json-pretty) flags are mutually exclusive with
--terse and --emacs. Normal text output behaviour is completely
unchanged when --json is not specified.
Assisted-by: Claude:claude-opus-4-7
Signed-off-by: Sasha Levin <sashal@kernel.org>
---
v3:
- Report the same line numbers text mode prints (matches --emacs
and --showfile). Fixes wrong locations on commit-message issues.
- Drop redundant defined() checks and `+ 0` coercions in the JSON
code; the values are already numeric and always defined.
- Add --json-pretty for indented output.
- Add parens around print() arguments.
- Consolidate the three empty-result early exits into one block.
- Return at the JSON branch instead of wrapping the rest of
process() in an else, so multi-file runs emit one document per
file and the indentation is no longer misleading.
v2: https://lore.kernel.org/all/20260408172435.1268067-1-sashal@kernel.org/
v1: https://lore.kernel.org/all/20260406170039.4034716-1-sashal@kernel.org/
Documentation/dev-tools/checkpatch.rst | 13 ++++
scripts/checkpatch.pl | 86 +++++++++++++++++++-------
2 files changed, 78 insertions(+), 21 deletions(-)
diff --git a/Documentation/dev-tools/checkpatch.rst b/Documentation/dev-tools/checkpatch.rst
index dccede68698ca..8a7c7742b23fa 100644
--- a/Documentation/dev-tools/checkpatch.rst
+++ b/Documentation/dev-tools/checkpatch.rst
@@ -64,6 +64,19 @@ Available options:
Output only one line per report.
+ - --json
+
+ Output results as a JSON object. The object includes total error,
+ warning, and check counts, plus an array of individual issues with
+ structured fields for level, type, message, file, and line number.
+ Output is one compact JSON document per input file, suitable for CI
+ and scripted post-processing. Cannot be used with --terse or --emacs.
+
+ - --json-pretty
+
+ Like --json, but emit pretty-printed (indented, multi-line) JSON for
+ human reading.
+
- --showfile
Show the diffed file position instead of the input file position.
diff --git a/scripts/checkpatch.pl b/scripts/checkpatch.pl
index 0492d6afc9a1f..181bd10b046b7 100755
--- a/scripts/checkpatch.pl
+++ b/scripts/checkpatch.pl
@@ -14,6 +14,7 @@ use File::Basename;
use Cwd 'abs_path';
use Term::ANSIColor qw(:constants);
use Encode qw(decode encode);
+use JSON::PP;
my $P = $0;
my $D = dirname(abs_path($P));
@@ -33,6 +34,8 @@ my $chk_patch = 1;
my $tst_only;
my $emacs = 0;
my $terse = 0;
+my $json = 0;
+my $json_pretty = 0;
my $showfile = 0;
my $file = 0;
my $git = 0;
@@ -93,6 +96,8 @@ Options:
--patch treat FILE as patchfile (default)
--emacs emacs compile window format
--terse one line per report
+ --json output results as JSON
+ --json-pretty like --json, but pretty-printed
--showfile emit diffed file position, not input file position
-g, --git treat FILE as a single commit or git revision range
single git commit with:
@@ -320,6 +325,8 @@ GetOptions(
'patch!' => \$chk_patch,
'emacs!' => \$emacs,
'terse!' => \$terse,
+ 'json!' => \$json,
+ 'json-pretty!' => \$json_pretty,
'showfile!' => \$showfile,
'f|file!' => \$file,
'g|git!' => \$git,
@@ -380,6 +387,9 @@ help($help - 1) if ($help);
die "$P: --git cannot be used with --file or --fix\n" if ($git && ($file || $fix));
die "$P: --verbose cannot be used with --terse\n" if ($verbose && $terse);
+$json = 1 if ($json_pretty);
+die "$P: --json cannot be used with --terse or --emacs\n" if ($json && ($terse || $emacs));
+
if ($color =~ /^[01]$/) {
$color = !$color;
} elsif ($color =~ /^always$/i) {
@@ -1352,7 +1362,7 @@ for my $filename (@ARGV) {
}
close($FILE);
- if ($#ARGV > 0 && $quiet == 0) {
+ if (!$json && $#ARGV > 0 && $quiet == 0) {
print '-' x length($vname) . "\n";
print "$vname\n";
print '-' x length($vname) . "\n";
@@ -1373,7 +1383,7 @@ for my $filename (@ARGV) {
$file = $oldfile if ($is_git_file);
}
-if (!$quiet) {
+if (!$quiet && !$json) {
hash_show_words(\%use_type, "Used");
hash_show_words(\%ignore_type, "Ignored");
@@ -2396,6 +2406,19 @@ sub report {
push(our @report, $output);
+ if ($json) {
+ our ($realfile, $realline, $linenr);
+ my $line = ($file || $showfile) ? $realline : $linenr;
+ my %issue = (
+ level => $level,
+ type => $type,
+ message => $msg,
+ );
+ $issue{file} = $realfile if ($realfile ne '');
+ $issue{line} = $line if ($line);
+ push(our @json_issues, \%issue);
+ }
+
return 1;
}
@@ -2403,6 +2426,24 @@ sub report_dump {
our @report;
}
+sub json_print_result {
+ my ($filename, $total_errors, $total_warnings, $total_checks,
+ $total_lines, $issues, $used_types, $ignored_types) = @_;
+ my %result = (
+ filename => $filename,
+ total_errors => $total_errors,
+ total_warnings => $total_warnings,
+ total_checks => $total_checks,
+ total_lines => $total_lines,
+ issues => $issues,
+ );
+ $result{used_types} = $used_types if (defined $used_types);
+ $result{ignored_types} = $ignored_types if (defined $ignored_types);
+ my $json_encoder = JSON::PP->new->canonical->utf8;
+ $json_encoder->pretty if ($json_pretty);
+ print($json_encoder->encode(\%result), "\n");
+}
+
sub fixup_current_range {
my ($lineRef, $offset, $length) = @_;
@@ -2653,7 +2694,7 @@ sub is_userspace {
sub process {
my $filename = shift;
- my $linenr=0;
+ our $linenr=0;
my $prevline="";
my $prevrawline="";
my $stashline="";
@@ -2691,14 +2732,15 @@ sub process {
my $last_coalesced_string_linenr = -1;
our @report = ();
+ our @json_issues = ();
our $cnt_lines = 0;
our $cnt_error = 0;
our $cnt_warn = 0;
our $cnt_chk = 0;
# Trace the real file/line as we go.
- my $realfile = '';
- my $realline = 0;
+ our $realfile = '';
+ our $realline = 0;
my $realcnt = 0;
my $here = '';
my $context_function; #undef'd unless there's a known function
@@ -7806,21 +7848,14 @@ sub process {
}
}
- # If we have no input at all, then there is nothing to report on
- # so just keep quiet.
- if ($#rawlines == -1) {
- exit(0);
- }
-
- # In mailback mode only produce a report in the negative, for
- # things that appear to be patches.
- if ($mailback && ($clean == 1 || !$is_patch)) {
- exit(0);
- }
-
- # This is not a patch, and we are in 'no-patch' mode so
- # just keep quiet.
- if (!$chk_patch && !$is_patch) {
+ # Bail out early without producing a normal report when there is no
+ # input at all, when we are in mailback mode and either the patch is
+ # clean or the input does not appear to be a patch, or when the input
+ # is not a patch and we are in 'no-patch' mode.
+ if ($#rawlines == -1 ||
+ ($mailback && ($clean == 1 || !$is_patch)) ||
+ (!$chk_patch && !$is_patch)) {
+ json_print_result($filename, 0, 0, 0, 0, []) if ($json);
exit(0);
}
@@ -7868,7 +7903,16 @@ sub process {
}
}
- print report_dump();
+ if ($json) {
+ my @used = sort keys %use_type;
+ my @ignored = sort keys %ignore_type;
+ json_print_result($filename, $cnt_error, $cnt_warn,
+ $cnt_chk, $cnt_lines, \@json_issues,
+ \@used, \@ignored);
+ return $clean;
+ }
+
+ print(report_dump());
if ($summary && !($clean == 1 && $quiet == 1)) {
print "$filename " if ($summary_file);
print "total: $cnt_error errors, $cnt_warn warnings, " .
--
2.53.0
^ permalink raw reply related
* [PATCH v3 3/3] Documentation: deprecated.rst: kmalloc-family: mark argument as optional
From: Manuel Ebner @ 2026-04-24 17:57 UTC (permalink / raw)
To: Jonathan Corbet, Shuah Khan, linux-doc, Kees Cook, linux-kernel
Cc: workflows, linux-mm, Geert Uytterhoeven, Manuel Ebner
In-Reply-To: <20260424174743.257951-2-manuelebner@mailbox.org>
put the optional argument (gfp) in square brackets
add whitespace for readability
eg. ptr = kmalloc_obj(*ptr, gfp);
-> ptr = kmalloc_obj(*ptr [, gfp] );
Signed-off-by: Manuel Ebner <manuelebner@mailbox.org>
---
Documentation/process/deprecated.rst | 12 ++++++------
1 file changed, 6 insertions(+), 6 deletions(-)
diff --git a/Documentation/process/deprecated.rst b/Documentation/process/deprecated.rst
index fed56864d036..b431993fd08e 100644
--- a/Documentation/process/deprecated.rst
+++ b/Documentation/process/deprecated.rst
@@ -392,12 +392,12 @@ allocations. For example, these open coded assignments::
become, respectively::
- ptr = kmalloc_obj(*ptr, gfp);
- ptr = kzalloc_obj(*ptr, gfp);
- ptr = kmalloc_objs(*ptr, count, gfp);
- ptr = kzalloc_objs(*ptr, count, gfp);
- ptr = kmalloc_flex(*ptr, flex_member, count, gfp);
- __auto_type ptr = kmalloc_obj(struct foo, gfp);
+ ptr = kmalloc_obj(*ptr [, gfp] );
+ ptr = kzalloc_obj(*ptr [, gfp] );
+ ptr = kmalloc_objs(*ptr, count [, gfp] );
+ ptr = kzalloc_objs(*ptr, count [, gfp] );
+ ptr = kmalloc_flex(*ptr, flex_member, count [, gfp] );
+ __auto_type ptr = kmalloc_obj(struct foo [, gfp] );
If `ptr->flex_member` is annotated with __counted_by(), the allocation
will automatically fail if `count` is larger than the maximum
--
2.53.0
^ permalink raw reply related
* [PATCH v3 1/3] Documentation: adopt new coding style of type-aware kmalloc-family
From: Manuel Ebner @ 2026-04-24 17:51 UTC (permalink / raw)
To: Jonathan Corbet, Shuah Khan, linux-doc
Cc: Kees Cook, linux-kernel, workflows, linux-sound, linux-media,
linux-mm, Manuel Ebner
In-Reply-To: <20260424174743.257951-2-manuelebner@mailbox.org>
Update the documentation to reflect new type-aware kmalloc-family as
suggested in commit 2932ba8d9c99 ("slab: Introduce kmalloc_obj()
and family")
ptr = kmalloc(sizeof(*ptr), gfp);
-> ptr = kmalloc_obj(*ptr);
ptr = kmalloc(sizeof(struct some_obj_name), gfp);
-> ptr = kmalloc_obj(*ptr);
ptr = kzalloc(sizeof(*ptr), gfp);
-> ptr = kzalloc_obj(*ptr);
ptr = kmalloc_array(count, sizeof(*ptr), gfp);
-> ptr = kmalloc_objs(*ptr, count);
ptr = kcalloc(count, sizeof(*ptr), gfp);
-> ptr = kzalloc_objs(*ptr, count);
Signed-off-by: Manuel Ebner <manuelebner@mailbox.org>
---
Documentation/core-api/kref.rst | 4 ++--
Documentation/core-api/list.rst | 4 ++--
Documentation/driver-api/mailbox.rst | 4 ++--
Documentation/driver-api/media/v4l2-fh.rst | 2 +-
Documentation/kernel-hacking/locking.rst | 4 ++--
Documentation/locking/locktypes.rst | 4 ++--
Documentation/process/coding-style.rst | 8 ++++----
.../sound/kernel-api/writing-an-alsa-driver.rst | 12 ++++++------
Documentation/spi/spi-summary.rst | 4 ++--
.../translations/it_IT/kernel-hacking/locking.rst | 4 ++--
.../translations/it_IT/locking/locktypes.rst | 4 ++--
.../translations/it_IT/process/coding-style.rst | 2 +-
.../translations/sp_SP/process/coding-style.rst | 2 +-
Documentation/translations/zh_CN/core-api/kref.rst | 4 ++--
.../translations/zh_CN/process/coding-style.rst | 2 +-
.../zh_CN/video4linux/v4l2-framework.txt | 2 +-
.../translations/zh_TW/process/coding-style.rst | 2 +-
18 files changed, 36 insertions(+), 36 deletions(-)
diff --git a/Documentation/core-api/kref.rst b/Documentation/core-api/kref.rst
index 8db9ff03d952..1c14c036699d 100644
--- a/Documentation/core-api/kref.rst
+++ b/Documentation/core-api/kref.rst
@@ -40,7 +40,7 @@ kref_init as so::
struct my_data *data;
- data = kmalloc(sizeof(*data), GFP_KERNEL);
+ data = kmalloc_obj(*data);
if (!data)
return -ENOMEM;
kref_init(&data->refcount);
@@ -100,7 +100,7 @@ thread to process::
int rv = 0;
struct my_data *data;
struct task_struct *task;
- data = kmalloc(sizeof(*data), GFP_KERNEL);
+ data = kmalloc_obj(*data);
if (!data)
return -ENOMEM;
kref_init(&data->refcount);
diff --git a/Documentation/core-api/list.rst b/Documentation/core-api/list.rst
index 241464ca0549..86cd0a1b77ea 100644
--- a/Documentation/core-api/list.rst
+++ b/Documentation/core-api/list.rst
@@ -112,7 +112,7 @@ list:
/* State 1 */
- grock = kzalloc(sizeof(*grock), GFP_KERNEL);
+ grock = kzalloc_obj(*grock);
if (!grock)
return -ENOMEM;
grock->name = "Grock";
@@ -123,7 +123,7 @@ list:
/* State 2 */
- dimitri = kzalloc(sizeof(*dimitri), GFP_KERNEL);
+ dimitri = kzalloc_obj(*dimitri);
if (!dimitri)
return -ENOMEM;
dimitri->name = "Dimitri";
diff --git a/Documentation/driver-api/mailbox.rst b/Documentation/driver-api/mailbox.rst
index 463dd032b96c..4bcd73a99115 100644
--- a/Documentation/driver-api/mailbox.rst
+++ b/Documentation/driver-api/mailbox.rst
@@ -87,8 +87,8 @@ a message and a callback function to the API and return immediately).
struct async_pkt ap;
struct sync_pkt sp;
- dc_sync = kzalloc(sizeof(*dc_sync), GFP_KERNEL);
- dc_async = kzalloc(sizeof(*dc_async), GFP_KERNEL);
+ dc_sync = kzalloc_obj(*dc_sync);
+ dc_async = kzalloc_obj(*dc_async);
/* Populate non-blocking mode client */
dc_async->cl.dev = &pdev->dev;
diff --git a/Documentation/driver-api/media/v4l2-fh.rst b/Documentation/driver-api/media/v4l2-fh.rst
index a934caa483a4..38319130ebf5 100644
--- a/Documentation/driver-api/media/v4l2-fh.rst
+++ b/Documentation/driver-api/media/v4l2-fh.rst
@@ -42,7 +42,7 @@ Example:
...
- my_fh = kzalloc(sizeof(*my_fh), GFP_KERNEL);
+ my_fh = kzalloc_obj(*my_fh);
...
diff --git a/Documentation/kernel-hacking/locking.rst b/Documentation/kernel-hacking/locking.rst
index dff0646a717b..d02e62367c4f 100644
--- a/Documentation/kernel-hacking/locking.rst
+++ b/Documentation/kernel-hacking/locking.rst
@@ -442,7 +442,7 @@ to protect the cache and all the objects within it. Here's the code::
{
struct object *obj;
- if ((obj = kmalloc(sizeof(*obj), GFP_KERNEL)) == NULL)
+ if ((obj = kmalloc_obj(*obj)) == NULL)
return -ENOMEM;
strscpy(obj->name, name, sizeof(obj->name));
@@ -517,7 +517,7 @@ which are taken away, and the ``+`` are lines which are added.
struct object *obj;
+ unsigned long flags;
- if ((obj = kmalloc(sizeof(*obj), GFP_KERNEL)) == NULL)
+ if ((obj = kmalloc_obj(*obj)) == NULL)
return -ENOMEM;
@@ -63,30 +64,33 @@
obj->id = id;
diff --git a/Documentation/locking/locktypes.rst b/Documentation/locking/locktypes.rst
index 37b6a5670c2f..ac1ad722a9e7 100644
--- a/Documentation/locking/locktypes.rst
+++ b/Documentation/locking/locktypes.rst
@@ -498,7 +498,7 @@ allocating memory. Thus, on a non-PREEMPT_RT kernel the following code
works perfectly::
raw_spin_lock(&lock);
- p = kmalloc(sizeof(*p), GFP_ATOMIC);
+ p = kmalloc_obj(*p, GFP_ATOMIC);
But this code fails on PREEMPT_RT kernels because the memory allocator is
fully preemptible and therefore cannot be invoked from truly atomic
@@ -507,7 +507,7 @@ while holding normal non-raw spinlocks because they do not disable
preemption on PREEMPT_RT kernels::
spin_lock(&lock);
- p = kmalloc(sizeof(*p), GFP_ATOMIC);
+ p = kmalloc_obj(*p, GFP_ATOMIC);
bit spinlocks
diff --git a/Documentation/process/coding-style.rst b/Documentation/process/coding-style.rst
index 35b381230f6e..a3bf75dc7c88 100644
--- a/Documentation/process/coding-style.rst
+++ b/Documentation/process/coding-style.rst
@@ -936,7 +936,7 @@ used.
---------------------
The kernel provides the following general purpose memory allocators:
-kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), and
+kmalloc(), kzalloc(), kmalloc_objs(), kzalloc_objs(), vmalloc(), and
vzalloc(). Please refer to the API documentation for further information
about them. :ref:`Documentation/core-api/memory-allocation.rst
<memory_allocation>`
@@ -945,7 +945,7 @@ The preferred form for passing a size of a struct is the following:
.. code-block:: c
- p = kmalloc(sizeof(*p), ...);
+ p = kmalloc_obj(*p, ...);
The alternative form where struct name is spelled out hurts readability and
introduces an opportunity for a bug when the pointer variable type is changed
@@ -959,13 +959,13 @@ The preferred form for allocating an array is the following:
.. code-block:: c
- p = kmalloc_array(n, sizeof(...), ...);
+ p = kmalloc_objs(*ptr, n, ...);
The preferred form for allocating a zeroed array is the following:
.. code-block:: c
- p = kcalloc(n, sizeof(...), ...);
+ p = kzalloc_objs(*ptr, n, ...);
Both forms check for overflow on the allocation size n * sizeof(...),
and return NULL if that occurred.
diff --git a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
index 895752cbcedd..12433612aa9c 100644
--- a/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
+++ b/Documentation/sound/kernel-api/writing-an-alsa-driver.rst
@@ -266,7 +266,7 @@ to details explained in the following section.
....
/* allocate a chip-specific data with zero filled */
- chip = kzalloc(sizeof(*chip), GFP_KERNEL);
+ chip = kzalloc_obj(*chip);
if (chip == NULL)
return -ENOMEM;
@@ -628,7 +628,7 @@ After allocating a card instance via :c:func:`snd_card_new()`
err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
0, &card);
.....
- chip = kzalloc(sizeof(*chip), GFP_KERNEL);
+ chip = kzalloc_obj(*chip);
The chip record should have the field to hold the card pointer at least,
@@ -747,7 +747,7 @@ destructor and PCI entries. Example code is shown first, below::
return -ENXIO;
}
- chip = kzalloc(sizeof(*chip), GFP_KERNEL);
+ chip = kzalloc_obj(*chip);
if (chip == NULL) {
pci_disable_device(pci);
return -ENOMEM;
@@ -1737,7 +1737,7 @@ callback::
{
struct my_pcm_data *data;
....
- data = kmalloc(sizeof(*data), GFP_KERNEL);
+ data = kmalloc_obj(*data);
substream->runtime->private_data = data;
....
}
@@ -3301,7 +3301,7 @@ You can then pass any pointer value to the ``private_data``. If you
assign private data, you should define a destructor, too. The
destructor function is set in the ``private_free`` field::
- struct mydata *p = kmalloc(sizeof(*p), GFP_KERNEL);
+ struct mydata *p = kmalloc_obj(*p);
hw->private_data = p;
hw->private_free = mydata_free;
@@ -3833,7 +3833,7 @@ chip data individually::
err = snd_card_new(&pci->dev, index[dev], id[dev], THIS_MODULE,
0, &card);
....
- chip = kzalloc(sizeof(*chip), GFP_KERNEL);
+ chip = kzalloc_obj(*chip);
....
card->private_data = chip;
....
diff --git a/Documentation/spi/spi-summary.rst b/Documentation/spi/spi-summary.rst
index 6e21e6f86912..7ad6af76c247 100644
--- a/Documentation/spi/spi-summary.rst
+++ b/Documentation/spi/spi-summary.rst
@@ -249,7 +249,7 @@ And SOC-specific utility code might look something like::
{
struct mysoc_spi_data *pdata2;
- pdata2 = kmalloc(sizeof *pdata2, GFP_KERNEL);
+ pdata2 = kmalloc_obj(*pdata2);
*pdata2 = pdata;
...
if (n == 2) {
@@ -373,7 +373,7 @@ a bus (appearing under /sys/class/spi_master).
return -ENODEV;
/* get memory for driver's per-chip state */
- chip = kzalloc(sizeof *chip, GFP_KERNEL);
+ chip = kzalloc(*chip);
if (!chip)
return -ENOMEM;
spi_set_drvdata(spi, chip);
diff --git a/Documentation/translations/it_IT/kernel-hacking/locking.rst b/Documentation/translations/it_IT/kernel-hacking/locking.rst
index 4c21cf60f775..acca89a3743a 100644
--- a/Documentation/translations/it_IT/kernel-hacking/locking.rst
+++ b/Documentation/translations/it_IT/kernel-hacking/locking.rst
@@ -462,7 +462,7 @@ e tutti gli oggetti che contiene. Ecco il codice::
{
struct object *obj;
- if ((obj = kmalloc(sizeof(*obj), GFP_KERNEL)) == NULL)
+ if ((obj = kmalloc_obj(*obj)) == NULL)
return -ENOMEM;
strscpy(obj->name, name, sizeof(obj->name));
@@ -537,7 +537,7 @@ sono quelle rimosse, mentre quelle ``+`` sono quelle aggiunte.
struct object *obj;
+ unsigned long flags;
- if ((obj = kmalloc(sizeof(*obj), GFP_KERNEL)) == NULL)
+ if ((obj = kmalloc_obj(*obj)) == NULL)
return -ENOMEM;
@@ -63,30 +64,33 @@
obj->id = id;
diff --git a/Documentation/translations/it_IT/locking/locktypes.rst b/Documentation/translations/it_IT/locking/locktypes.rst
index 1c7056283b9d..d5fa36aa05cc 100644
--- a/Documentation/translations/it_IT/locking/locktypes.rst
+++ b/Documentation/translations/it_IT/locking/locktypes.rst
@@ -488,7 +488,7 @@ o rwlock_t. Per esempio, la sezione critica non deve fare allocazioni di
memoria. Su un kernel non-PREEMPT_RT il seguente codice funziona perfettamente::
raw_spin_lock(&lock);
- p = kmalloc(sizeof(*p), GFP_ATOMIC);
+ p = kmalloc_obj(*p, GFP_ATOMIC);
Ma lo stesso codice non funziona su un kernel PREEMPT_RT perché l'allocatore di
memoria può essere oggetto di prelazione e quindi non può essere chiamato in un
@@ -497,7 +497,7 @@ trattiene un blocco *non-raw* perché non disabilitano la prelazione sui kernel
PREEMPT_RT::
spin_lock(&lock);
- p = kmalloc(sizeof(*p), GFP_ATOMIC);
+ p = kmalloc_obj(*p, GFP_ATOMIC);
bit spinlocks
diff --git a/Documentation/translations/it_IT/process/coding-style.rst b/Documentation/translations/it_IT/process/coding-style.rst
index c0dc786b8474..2a499412a2e3 100644
--- a/Documentation/translations/it_IT/process/coding-style.rst
+++ b/Documentation/translations/it_IT/process/coding-style.rst
@@ -943,7 +943,7 @@ Il modo preferito per passare la dimensione di una struttura è il seguente:
.. code-block:: c
- p = kmalloc(sizeof(*p), ...);
+ p = kmalloc_obj(*p, ...);
La forma alternativa, dove il nome della struttura viene scritto interamente,
peggiora la leggibilità e introduce possibili bachi quando il tipo di
diff --git a/Documentation/translations/sp_SP/process/coding-style.rst b/Documentation/translations/sp_SP/process/coding-style.rst
index 7d63aa8426e6..44c93d5f6beb 100644
--- a/Documentation/translations/sp_SP/process/coding-style.rst
+++ b/Documentation/translations/sp_SP/process/coding-style.rst
@@ -955,7 +955,7 @@ La forma preferida para pasar el tamaño de una estructura es la siguiente:
.. code-block:: c
- p = kmalloc(sizeof(*p), ...);
+ p = kmalloc_obj(*p, ...);
La forma alternativa donde se deletrea el nombre de la estructura perjudica
la legibilidad, y presenta una oportunidad para un error cuando se cambia
diff --git a/Documentation/translations/zh_CN/core-api/kref.rst b/Documentation/translations/zh_CN/core-api/kref.rst
index b9902af310c5..fcff01e99852 100644
--- a/Documentation/translations/zh_CN/core-api/kref.rst
+++ b/Documentation/translations/zh_CN/core-api/kref.rst
@@ -52,7 +52,7 @@ kref可以出现在数据结构体中的任何地方。
struct my_data *data;
- data = kmalloc(sizeof(*data), GFP_KERNEL);
+ data = kmalloc_obj(*data);
if (!data)
return -ENOMEM;
kref_init(&data->refcount);
@@ -106,7 +106,7 @@ Kref规则
int rv = 0;
struct my_data *data;
struct task_struct *task;
- data = kmalloc(sizeof(*data), GFP_KERNEL);
+ data = kmalloc_obj(*data);
if (!data)
return -ENOMEM;
kref_init(&data->refcount);
diff --git a/Documentation/translations/zh_CN/process/coding-style.rst b/Documentation/translations/zh_CN/process/coding-style.rst
index 5a342a024c01..55d5da974d89 100644
--- a/Documentation/translations/zh_CN/process/coding-style.rst
+++ b/Documentation/translations/zh_CN/process/coding-style.rst
@@ -813,7 +813,7 @@ Documentation/translations/zh_CN/core-api/memory-allocation.rst 。
.. code-block:: c
- p = kmalloc(sizeof(*p), ...);
+ p = kmalloc_obj(*p, ...);
另外一种传递方式中，sizeof 的操作数是结构体的名字，这样会降低可读性，并且可能
会引入 bug。有可能指针变量类型被改变时，而对应的传递给内存分配函数的 sizeof
diff --git a/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt b/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt
index f0be21a60a0f..ba43c5c4797c 100644
--- a/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt
+++ b/Documentation/translations/zh_CN/video4linux/v4l2-framework.txt
@@ -799,7 +799,7 @@ int my_open(struct file *file)
...
- my_fh = kzalloc(sizeof(*my_fh), GFP_KERNEL);
+ my_fh = kzalloc_obj(*my_fh);
...
diff --git a/Documentation/translations/zh_TW/process/coding-style.rst b/Documentation/translations/zh_TW/process/coding-style.rst
index e2ba97b3d8bb..63c78982a1af 100644
--- a/Documentation/translations/zh_TW/process/coding-style.rst
+++ b/Documentation/translations/zh_TW/process/coding-style.rst
@@ -827,7 +827,7 @@ Documentation/translations/zh_CN/core-api/memory-allocation.rst 。
.. code-block:: c
- p = kmalloc(sizeof(*p), ...);
+ p = kmalloc_obj(*p, ...);
另外一種傳遞方式中，sizeof 的操作數是結構體的名字，這樣會降低可讀性，並且可能
會引入 bug。有可能指針變量類型被改變時，而對應的傳遞給內存分配函數的 sizeof
--
2.53.0
^ permalink raw reply related
* [PATCH v3 0/3] Documentation: adopt new coding style of type-aware kmalloc-family
From: Manuel Ebner @ 2026-04-24 17:47 UTC (permalink / raw)
To: Jonathan Corbet, Shuah Khan, linux-doc, Kees Cook
Cc: linux-kernel, workflows, linux-sound, rcu, linux-media, linux-mm,
Manuel Ebner
Update the documentation to reflect new type-aware kmalloc-family as
suggested in commit 2932ba8d9c99 ("slab: Introduce kmalloc_obj()
and family")
On Tue, 2026-04-21 at 19:55 +0200, Manuel Ebner wrote:
> I have also thought about adding a few cases to checkpatch.pl, but this
> will take me more time, and i want to get this series finished.
I can't do it, i don't have the knowledge in Perl and Regex.
[v2] -> [v3]:
remove obvious wrong replacements in [1/3]
add Acked-by: Paul E. McKenney in [2/3]
change how to mark the optional argument in [3/3]
add recipants
--cc="linux-mm@kvack.org"
--to="Kees Cook"
--cc="Geert Uytterhoeven"
[v1] -> [v2]:
put RCU/* in a seperate patch [Patch 2/3]
Omit optional argument (GFP_KERNEL) as suggested by https://lwn.net/Articles/1062856/
deprecated.rst: change the argument gfp to optional [Patch 3/3]
Signed-off-by: Manuel Ebner <manuelebner@mailbox.org>
^ permalink raw reply
* [PATCH v3 9/9] kernel/api: add runtime verification selftest
From: Sasha Levin @ 2026-04-24 16:51 UTC (permalink / raw)
To: linux-api, linux-kernel
Cc: linux-doc, linux-fsdevel, linux-kbuild, linux-kselftest,
workflows, tools, x86, Thomas Gleixner, Paul E . McKenney,
Greg Kroah-Hartman, Jonathan Corbet, Dmitry Vyukov, Randy Dunlap,
Cyril Hrubis, Kees Cook, Jake Edge, David Laight, Askar Safin,
Gabriele Paoloni, Mauro Carvalho Chehab, Christian Brauner,
Alexander Viro, Andrew Morton, Masahiro Yamada, Shuah Khan,
Ingo Molnar, Arnd Bergmann, Sasha Levin
In-Reply-To: <20260424165130.2306833-1-sashal@kernel.org>
Add a selftest for CONFIG_KAPI_RUNTIME_CHECKS that exercises
sys_open/sys_read/sys_write/sys_close through raw syscall() and
verifies KAPI pre-validation catches invalid parameters while
allowing valid operations through.
Test cases (TAP output):
1-4: Valid open/read/write/close succeed
5-7: Invalid flags, mode bits, NULL path rejected with EINVAL
8: dmesg contains expected KAPI warning strings
Signed-off-by: Sasha Levin <sashal@kernel.org>
---
MAINTAINERS | 1 +
tools/testing/selftests/Makefile | 1 +
tools/testing/selftests/kapi/Makefile | 7 +
tools/testing/selftests/kapi/kapi_test_util.h | 33 +
tools/testing/selftests/kapi/test_kapi.c | 1096 +++++++++++++++++
5 files changed, 1138 insertions(+)
create mode 100644 tools/testing/selftests/kapi/Makefile
create mode 100644 tools/testing/selftests/kapi/kapi_test_util.h
create mode 100644 tools/testing/selftests/kapi/test_kapi.c
diff --git a/MAINTAINERS b/MAINTAINERS
index 0d14205077908..ddfd9cad98916 100644
--- a/MAINTAINERS
+++ b/MAINTAINERS
@@ -13826,6 +13826,7 @@ F: include/linux/kernel_api_spec.h
F: kernel/api/
F: tools/kapi/
F: tools/lib/python/kdoc/kdoc_apispec.py
+F: tools/testing/selftests/kapi/
KERNEL AUTOMOUNTER
M: Ian Kent <raven@themaw.net>
diff --git a/tools/testing/selftests/Makefile b/tools/testing/selftests/Makefile
index 450f13ba4cca9..7881bec5aafe1 100644
--- a/tools/testing/selftests/Makefile
+++ b/tools/testing/selftests/Makefile
@@ -48,6 +48,7 @@ TARGETS += intel_pstate
TARGETS += iommu
TARGETS += ipc
TARGETS += ir
+TARGETS += kapi
TARGETS += kcmp
TARGETS += kexec
TARGETS += kselftest_harness
diff --git a/tools/testing/selftests/kapi/Makefile b/tools/testing/selftests/kapi/Makefile
new file mode 100644
index 0000000000000..32a750901b111
--- /dev/null
+++ b/tools/testing/selftests/kapi/Makefile
@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: GPL-2.0
+
+TEST_GEN_PROGS := test_kapi
+
+CFLAGS += -static -Wall -Wextra -Werror -O2 $(KHDR_INCLUDES)
+
+include ../lib.mk
diff --git a/tools/testing/selftests/kapi/kapi_test_util.h b/tools/testing/selftests/kapi/kapi_test_util.h
new file mode 100644
index 0000000000000..e097c370542ad
--- /dev/null
+++ b/tools/testing/selftests/kapi/kapi_test_util.h
@@ -0,0 +1,33 @@
+/* SPDX-License-Identifier: GPL-2.0 */
+/*
+ * Copyright (C) 2026 Sasha Levin <sashal@kernel.org>
+ *
+ * Compatibility helpers for KAPI selftests.
+ *
+ * __NR_open is not defined on aarch64 and riscv64 (only __NR_openat exists).
+ * Provide a wrapper that uses __NR_openat with AT_FDCWD to achieve the same
+ * behavior as __NR_open on architectures that lack it.
+ */
+#ifndef KAPI_TEST_UTIL_H
+#define KAPI_TEST_UTIL_H
+
+#include <fcntl.h>
+#include <sys/syscall.h>
+
+#ifndef __NR_open
+/*
+ * On architectures without __NR_open (e.g., aarch64, riscv64),
+ * use openat(AT_FDCWD, ...) which is equivalent.
+ */
+static inline long kapi_sys_open(const char *pathname, int flags, int mode)
+{
+ return syscall(__NR_openat, AT_FDCWD, pathname, flags, mode);
+}
+#else
+static inline long kapi_sys_open(const char *pathname, int flags, int mode)
+{
+ return syscall(__NR_open, pathname, flags, mode);
+}
+#endif
+
+#endif /* KAPI_TEST_UTIL_H */
diff --git a/tools/testing/selftests/kapi/test_kapi.c b/tools/testing/selftests/kapi/test_kapi.c
new file mode 100644
index 0000000000000..a6b7576f95c3e
--- /dev/null
+++ b/tools/testing/selftests/kapi/test_kapi.c
@@ -0,0 +1,1096 @@
+// SPDX-License-Identifier: GPL-2.0
+/*
+ * Copyright (C) 2026 Sasha Levin <sashal@kernel.org>
+ *
+ * Userspace selftest for KAPI runtime verification of syscall parameters.
+ *
+ * Exercises sys_open, sys_read, sys_write, and sys_close through raw
+ * syscall() to ensure KAPI pre-validation wrappers interact correctly
+ * with normal kernel error handling.
+ *
+ * Requires CONFIG_KAPI_RUNTIME_CHECKS=y for full coverage; many tests
+ * also pass without it.
+ *
+ * TAP output format.
+ */
+
+#define _GNU_SOURCE
+#include <stdbool.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <unistd.h>
+#include <fcntl.h>
+#include <errno.h>
+#include <signal.h>
+#include <sys/syscall.h>
+#include <sys/stat.h>
+#include <linux/limits.h>
+#include "../kselftest.h"
+#include "kapi_test_util.h"
+
+#define NUM_TESTS 29
+
+/*
+ * Set from the SIGPIPE handler. `volatile sig_atomic_t` is the POSIX-
+ * mandated type for flags touched by async-signal-safe handlers;
+ * checkpatch's generic "volatile considered harmful" warning targets
+ * kernel code and does not apply here.
+ */
+static volatile sig_atomic_t got_sigpipe;
+
+/*
+ * The tap_* helpers are thin wrappers around ksft_test_result_* so the
+ * rest of this file reads like the original author wrote it, while the
+ * output goes through the shared kselftest harness.
+ */
+static void tap_ok(const char *desc)
+{
+ ksft_test_result_pass("%s\n", desc);
+}
+
+static void tap_fail(const char *desc, const char *reason)
+{
+ ksft_test_result_fail("%s: %s\n", desc, reason);
+}
+
+static void tap_skip(const char *desc, const char *reason)
+{
+ ksft_test_result_skip("%s: %s\n", desc, reason);
+}
+
+/*
+ * Return true when the kernel provides the kapi runtime-check surface.
+ * Tests that rely on KAPI rejecting bad parameters pre-call should be
+ * skipped on kernels without it, not reported as failures.
+ */
+static bool kapi_runtime_checks_active(void)
+{
+ struct stat st;
+
+ return stat("/sys/kernel/debug/kapi", &st) == 0 && S_ISDIR(st.st_mode);
+}
+
+static void sigpipe_handler(int sig)
+{
+ (void)sig;
+ got_sigpipe = 1;
+}
+
+/* ---- Valid operation tests ---- */
+
+/*
+ * Test 1: open a readable file
+ * Returns fd on success.
+ */
+static int test_open_valid(void)
+{
+ errno = 0;
+ long fd = kapi_sys_open("/etc/hostname", O_RDONLY, 0);
+
+ if (fd >= 0) {
+ tap_ok("open valid file");
+ } else {
+ /* /etc/hostname might not exist; try /etc/passwd */
+ errno = 0;
+ fd = kapi_sys_open("/etc/passwd", O_RDONLY, 0);
+ if (fd >= 0)
+ tap_ok("open valid file (fallback /etc/passwd)");
+ else
+ tap_fail("open valid file", strerror(errno));
+ }
+ return (int)fd;
+}
+
+/*
+ * Test 2: read from fd
+ */
+static void test_read_valid(int fd)
+{
+ char buf[256];
+
+ errno = 0;
+ long ret = syscall(__NR_read, fd, buf, sizeof(buf));
+
+ if (ret > 0)
+ tap_ok("read from valid fd");
+ else if (ret == 0)
+ tap_ok("read from valid fd (EOF)");
+ else
+ tap_fail("read from valid fd", strerror(errno));
+}
+
+/*
+ * Test 3: write to /dev/null
+ */
+static void test_write_valid(void)
+{
+ errno = 0;
+ long devnull = kapi_sys_open("/dev/null", O_WRONLY, 0);
+
+ if (devnull < 0) {
+ tap_fail("write to /dev/null (open failed)", strerror(errno));
+ return;
+ }
+
+ errno = 0;
+ long ret = syscall(__NR_write, (int)devnull, "hello", 5);
+
+ if (ret == 5)
+ tap_ok("write to /dev/null");
+ else
+ tap_fail("write to /dev/null",
+ ret < 0 ? strerror(errno) : "short write");
+
+ syscall(__NR_close, (int)devnull);
+}
+
+/*
+ * Test 4: close fd
+ */
+static void test_close_valid(int fd)
+{
+ errno = 0;
+ long ret = syscall(__NR_close, fd);
+
+ if (ret == 0)
+ tap_ok("close valid fd");
+ else
+ tap_fail("close valid fd", strerror(errno));
+}
+
+/* ---- KAPI parameter rejection tests ---- */
+
+/*
+ * Test 5: open with invalid flag bits
+ * 0x10000000 is outside the valid O_* mask, KAPI should reject.
+ */
+static void test_open_invalid_flags(void)
+{
+ long ret;
+
+ if (!kapi_runtime_checks_active()) {
+ tap_skip("open with invalid flags",
+ "CONFIG_KAPI_RUNTIME_CHECKS not enabled");
+ return;
+ }
+
+ errno = 0;
+ /*
+ * Use /dev/null (always present on any sane rootfs) so KAPI's flag
+ * validation is reached before a path-lookup ENOENT can mask it.
+ * 0x10000000 is outside the valid O_* mask.
+ */
+ ret = kapi_sys_open("/dev/null", 0x10000000, 0);
+
+ if (ret == -1 && errno == EINVAL) {
+ tap_ok("open with invalid flags returns EINVAL");
+ } else if (ret >= 0) {
+ tap_fail("open with invalid flags", "expected EINVAL, got success");
+ syscall(__NR_close, (int)ret);
+ } else {
+ char msg[64];
+
+ snprintf(msg, sizeof(msg), "expected EINVAL, got %s",
+ strerror(errno));
+ tap_fail("open with invalid flags", msg);
+ }
+}
+
+/*
+ * Test 6: open with invalid mode bits
+ * 0xFFFF has bits outside S_IALLUGO (07777), KAPI should reject.
+ */
+static void test_open_invalid_mode(void)
+{
+ long ret;
+
+ if (!kapi_runtime_checks_active()) {
+ tap_skip("open with invalid mode",
+ "CONFIG_KAPI_RUNTIME_CHECKS not enabled");
+ return;
+ }
+
+ errno = 0;
+ ret = kapi_sys_open("/tmp/kapi_test_mode",
+ O_CREAT | O_WRONLY | O_EXCL, 0xFFFF);
+
+ if (ret == -1 && errno == EINVAL) {
+ tap_ok("open with invalid mode returns EINVAL");
+ } else if (ret >= 0) {
+ tap_fail("open with invalid mode", "expected EINVAL, got success");
+ syscall(__NR_close, (int)ret);
+ unlink("/tmp/kapi_test_mode");
+ } else {
+ char msg[64];
+
+ snprintf(msg, sizeof(msg), "expected EINVAL, got %s",
+ strerror(errno));
+ tap_fail("open with invalid mode", msg);
+ }
+}
+
+/*
+ * Test 7: open with NULL path
+ * KAPI USER_PATH constraint should reject NULL.
+ */
+static void test_open_null_path(void)
+{
+ errno = 0;
+ long ret = kapi_sys_open(NULL, O_RDONLY, 0);
+
+ if (ret == -1 && errno == EINVAL) {
+ tap_ok("open with NULL path returns EINVAL");
+ } else if (ret == -1 && errno == EFAULT) {
+ /* Kernel may catch this as EFAULT before KAPI */
+ tap_ok("open with NULL path returns EFAULT (acceptable)");
+ } else if (ret >= 0) {
+ tap_fail("open with NULL path", "expected error, got success");
+ syscall(__NR_close, (int)ret);
+ } else {
+ char msg[64];
+
+ snprintf(msg, sizeof(msg), "got %s", strerror(errno));
+ tap_fail("open with NULL path", msg);
+ }
+}
+
+/*
+ * Test 8: open with flag bit 30 set (0x40000000)
+ * This bit is outside the valid O_* mask, KAPI should reject with EINVAL.
+ */
+static void test_open_flag_bit30(void)
+{
+ long ret;
+
+ if (!kapi_runtime_checks_active()) {
+ tap_skip("open with flag bit 30 (0x40000000) returns EINVAL",
+ "CONFIG_KAPI_RUNTIME_CHECKS not enabled");
+ return;
+ }
+
+ errno = 0;
+ ret = kapi_sys_open("/dev/null", 0x40000000, 0);
+
+ if (ret == -1 && errno == EINVAL) {
+ tap_ok("open with flag bit 30 (0x40000000) returns EINVAL");
+ } else if (ret >= 0) {
+ tap_fail("open with flag bit 30 (0x40000000) returns EINVAL",
+ "expected EINVAL, got success");
+ syscall(__NR_close, (int)ret);
+ } else {
+ char msg[64];
+
+ snprintf(msg, sizeof(msg), "expected EINVAL, got %s",
+ strerror(errno));
+ tap_fail("open with flag bit 30 (0x40000000) returns EINVAL",
+ msg);
+ }
+}
+
+/* ---- Boundary condition and error path tests ---- */
+
+/*
+ * Test 9: read with fd=-1 should return an error.
+ * With CONFIG_KAPI_RUNTIME_CHECKS=y, KAPI validates the fd first and
+ * rejects negative fds (other than AT_FDCWD) with EINVAL. Without
+ * KAPI, the kernel returns EBADF. Accept either.
+ */
+static void test_read_bad_fd(void)
+{
+ char buf[16];
+
+ errno = 0;
+ long ret = syscall(__NR_read, -1, buf, sizeof(buf));
+
+ if (ret == -1 && (errno == EBADF || errno == EINVAL)) {
+ tap_ok("read with fd=-1 returns error");
+ } else {
+ char msg[64];
+
+ snprintf(msg, sizeof(msg), "expected EBADF/EINVAL, got %s",
+ ret >= 0 ? "success" : strerror(errno));
+ tap_fail("read with fd=-1 returns error", msg);
+ }
+}
+
+/*
+ * Test 10: read with count=0 should return 0
+ */
+static void test_read_zero_count(void)
+{
+ char buf[1];
+ long fd;
+
+ errno = 0;
+ fd = kapi_sys_open("/dev/null", O_RDONLY, 0);
+ if (fd < 0) {
+ tap_fail("read with count=0 returns 0",
+ "cannot open /dev/null");
+ return;
+ }
+
+ errno = 0;
+ long ret = syscall(__NR_read, (int)fd, buf, 0);
+
+ if (ret == 0) {
+ tap_ok("read with count=0 returns 0");
+ } else {
+ char msg[64];
+
+ snprintf(msg, sizeof(msg), "expected 0, got %ld (errno=%s)",
+ ret, strerror(errno));
+ tap_fail("read with count=0 returns 0", msg);
+ }
+
+ syscall(__NR_close, (int)fd);
+}
+
+/*
+ * Test 11: write with count=0 should return 0
+ */
+static void test_write_zero_count(void)
+{
+ long fd;
+
+ errno = 0;
+ fd = kapi_sys_open("/dev/null", O_WRONLY, 0);
+ if (fd < 0) {
+ tap_fail("write with count=0 returns 0",
+ "cannot open /dev/null");
+ return;
+ }
+
+ errno = 0;
+ long ret = syscall(__NR_write, (int)fd, "x", 0);
+
+ if (ret == 0) {
+ tap_ok("write with count=0 returns 0");
+ } else {
+ char msg[64];
+
+ snprintf(msg, sizeof(msg), "expected 0, got %ld (errno=%s)",
+ ret, strerror(errno));
+ tap_fail("write with count=0 returns 0", msg);
+ }
+
+ syscall(__NR_close, (int)fd);
+}
+
+/*
+ * Test 12: open with a path longer than PATH_MAX should fail
+ * Expect ENAMETOOLONG or EINVAL.
+ */
+static void test_open_long_path(void)
+{
+ char *longpath;
+ size_t len = PATH_MAX + 256;
+
+ longpath = malloc(len);
+ if (!longpath) {
+ tap_fail("open with path > PATH_MAX", "malloc failed");
+ return;
+ }
+
+ memset(longpath, 'A', len - 1);
+ longpath[0] = '/';
+ longpath[len - 1] = '\0';
+
+ errno = 0;
+ long ret = kapi_sys_open(longpath, O_RDONLY, 0);
+
+ if (ret == -1 && (errno == ENAMETOOLONG || errno == EINVAL)) {
+ tap_ok("open with path > PATH_MAX returns ENAMETOOLONG/EINVAL");
+ } else if (ret >= 0) {
+ tap_fail("open with path > PATH_MAX",
+ "expected error, got success");
+ syscall(__NR_close, (int)ret);
+ } else {
+ char msg[64];
+
+ snprintf(msg, sizeof(msg),
+ "expected ENAMETOOLONG/EINVAL, got %s",
+ strerror(errno));
+ tap_fail("open with path > PATH_MAX", msg);
+ }
+
+ free(longpath);
+}
+
+/*
+ * Test 13: read with unmapped user pointer should return EFAULT or EINVAL.
+ * Use a pipe with data so the kernel actually tries to copy to the buffer.
+ */
+static void test_read_unmapped_buf(void)
+{
+ int pipefd[2];
+
+ if (pipe(pipefd) < 0) {
+ tap_fail("read with unmapped buffer returns EFAULT/EINVAL",
+ "pipe() failed");
+ return;
+ }
+
+ /* Write some data so read has something to copy */
+ (void)write(pipefd[1], "hello", 5);
+
+ errno = 0;
+ long ret = syscall(__NR_read, pipefd[0], (void *)0xDEAD0000, 16);
+
+ if (ret == -1 && (errno == EFAULT || errno == EINVAL)) {
+ tap_ok("read with unmapped buffer returns EFAULT/EINVAL");
+ } else {
+ char msg[64];
+
+ snprintf(msg, sizeof(msg),
+ "expected EFAULT/EINVAL, got %s",
+ ret >= 0 ? "success" : strerror(errno));
+ tap_fail("read with unmapped buffer returns EFAULT/EINVAL",
+ msg);
+ }
+
+ close(pipefd[0]);
+ close(pipefd[1]);
+}
+
+/*
+ * Test 14: write with unmapped user pointer should return EFAULT or EINVAL.
+ * Use a pipe so the kernel actually tries to copy from the buffer.
+ */
+static void test_write_unmapped_buf(void)
+{
+ int pipefd[2];
+
+ if (pipe(pipefd) < 0) {
+ tap_fail("write with unmapped buffer returns EFAULT/EINVAL",
+ "pipe() failed");
+ return;
+ }
+
+ errno = 0;
+ long ret = syscall(__NR_write, pipefd[1], (void *)0xDEAD0000, 16);
+
+ if (ret == -1 && (errno == EFAULT || errno == EINVAL)) {
+ tap_ok("write with unmapped buffer returns EFAULT/EINVAL");
+ } else {
+ char msg[64];
+
+ snprintf(msg, sizeof(msg),
+ "expected EFAULT/EINVAL, got %s",
+ ret >= 0 ? "success" : strerror(errno));
+ tap_fail("write with unmapped buffer returns EFAULT/EINVAL",
+ msg);
+ }
+
+ close(pipefd[0]);
+ close(pipefd[1]);
+}
+
+/*
+ * Test 15: close an already-closed fd should return EBADF
+ */
+static void test_close_already_closed(void)
+{
+ long fd;
+
+ errno = 0;
+ fd = kapi_sys_open("/dev/null", O_RDONLY, 0);
+ if (fd < 0) {
+ tap_fail("close already-closed fd returns EBADF",
+ "cannot open /dev/null");
+ return;
+ }
+
+ /* Close it once - should succeed */
+ syscall(__NR_close, (int)fd);
+
+ /* Close it again - should fail with EBADF */
+ errno = 0;
+ long ret = syscall(__NR_close, (int)fd);
+
+ if (ret == -1 && errno == EBADF) {
+ tap_ok("close already-closed fd returns EBADF");
+ } else {
+ char msg[64];
+
+ snprintf(msg, sizeof(msg), "expected EBADF, got %s",
+ ret == 0 ? "success" : strerror(errno));
+ tap_fail("close already-closed fd returns EBADF", msg);
+ }
+}
+
+/*
+ * Test 16: open /dev/null with O_RDONLY|O_CLOEXEC should succeed
+ */
+static void test_open_valid_cloexec(void)
+{
+ errno = 0;
+ long fd = kapi_sys_open("/dev/null", O_RDONLY | O_CLOEXEC, 0);
+
+ if (fd >= 0) {
+ tap_ok("open /dev/null with O_RDONLY|O_CLOEXEC succeeds");
+ syscall(__NR_close, (int)fd);
+ } else {
+ char msg[64];
+
+ snprintf(msg, sizeof(msg), "expected success, got %s",
+ strerror(errno));
+ tap_fail("open /dev/null with O_RDONLY|O_CLOEXEC succeeds",
+ msg);
+ }
+}
+
+/*
+ * Test 17: write 0 bytes to /dev/null should return 0
+ */
+static void test_write_zero_devnull(void)
+{
+ long fd;
+
+ errno = 0;
+ fd = kapi_sys_open("/dev/null", O_WRONLY, 0);
+ if (fd < 0) {
+ tap_fail("write 0 bytes to /dev/null returns 0",
+ "cannot open /dev/null");
+ return;
+ }
+
+ errno = 0;
+ long ret = syscall(__NR_write, (int)fd, "", 0);
+
+ if (ret == 0) {
+ tap_ok("write 0 bytes to /dev/null returns 0");
+ } else {
+ char msg[64];
+
+ snprintf(msg, sizeof(msg), "expected 0, got %ld (errno=%s)",
+ ret, strerror(errno));
+ tap_fail("write 0 bytes to /dev/null returns 0", msg);
+ }
+
+ syscall(__NR_close, (int)fd);
+}
+
+/*
+ * Test 18: read from a write-only fd should return EBADF
+ */
+static void test_read_writeonly_fd(void)
+{
+ long fd;
+
+ errno = 0;
+ fd = kapi_sys_open("/dev/null", O_WRONLY, 0);
+ if (fd < 0) {
+ tap_fail("read from write-only fd returns EBADF",
+ "cannot open /dev/null");
+ return;
+ }
+
+ char buf[16];
+
+ errno = 0;
+ long ret = syscall(__NR_read, (int)fd, buf, sizeof(buf));
+
+ if (ret == -1 && errno == EBADF) {
+ tap_ok("read from write-only fd returns EBADF");
+ } else {
+ char msg[64];
+
+ snprintf(msg, sizeof(msg), "expected EBADF, got %s",
+ ret >= 0 ? "success" : strerror(errno));
+ tap_fail("read from write-only fd returns EBADF", msg);
+ }
+
+ syscall(__NR_close, (int)fd);
+}
+
+/*
+ * Test 19: write to a read-only fd should return EBADF
+ */
+static void test_write_readonly_fd(void)
+{
+ long fd;
+
+ errno = 0;
+ fd = kapi_sys_open("/dev/null", O_RDONLY, 0);
+ if (fd < 0) {
+ tap_fail("write to read-only fd returns EBADF",
+ "cannot open /dev/null");
+ return;
+ }
+
+ errno = 0;
+ long ret = syscall(__NR_write, (int)fd, "hello", 5);
+
+ if (ret == -1 && errno == EBADF) {
+ tap_ok("write to read-only fd returns EBADF");
+ } else {
+ char msg[64];
+
+ snprintf(msg, sizeof(msg), "expected EBADF, got %s",
+ ret >= 0 ? "success" : strerror(errno));
+ tap_fail("write to read-only fd returns EBADF", msg);
+ }
+
+ syscall(__NR_close, (int)fd);
+}
+
+/*
+ * Test 20: close fd 9999 (likely invalid) should return EBADF
+ */
+static void test_close_fd_9999(void)
+{
+ errno = 0;
+ long ret = syscall(__NR_close, 9999);
+
+ if (ret == -1 && errno == EBADF) {
+ tap_ok("close fd 9999 returns EBADF");
+ } else {
+ char msg[64];
+
+ snprintf(msg, sizeof(msg), "expected EBADF, got %s",
+ ret == 0 ? "success" : strerror(errno));
+ tap_fail("close fd 9999 returns EBADF", msg);
+ }
+}
+
+/*
+ * Test 21: read from pipe after write end is closed returns 0 (EOF)
+ */
+static void test_read_closed_pipe(void)
+{
+ int pipefd[2];
+
+ if (pipe(pipefd) < 0) {
+ tap_fail("read from closed pipe returns 0 (EOF)",
+ "pipe() failed");
+ return;
+ }
+
+ /* Close write end */
+ close(pipefd[1]);
+
+ char buf[16];
+
+ errno = 0;
+ long ret = syscall(__NR_read, pipefd[0], buf, sizeof(buf));
+
+ if (ret == 0) {
+ tap_ok("read from closed pipe returns 0 (EOF)");
+ } else {
+ char msg[64];
+
+ snprintf(msg, sizeof(msg), "expected 0, got %ld (errno=%s)",
+ ret, ret < 0 ? strerror(errno) : "n/a");
+ tap_fail("read from closed pipe returns 0 (EOF)", msg);
+ }
+
+ close(pipefd[0]);
+}
+
+/*
+ * Test 22: write to pipe after read end is closed returns EPIPE + SIGPIPE
+ */
+static void test_write_closed_pipe(void)
+{
+ int pipefd[2];
+ struct sigaction sa, old_sa;
+
+ if (pipe(pipefd) < 0) {
+ tap_fail("write to closed pipe returns EPIPE + SIGPIPE",
+ "pipe() failed");
+ return;
+ }
+
+ /* Install SIGPIPE handler */
+ memset(&sa, 0, sizeof(sa));
+ sa.sa_handler = sigpipe_handler;
+ sigemptyset(&sa.sa_mask);
+ sigaction(SIGPIPE, &sa, &old_sa);
+
+ got_sigpipe = 0;
+
+ /* Close read end */
+ close(pipefd[0]);
+
+ errno = 0;
+ long ret = syscall(__NR_write, pipefd[1], "hello", 5);
+
+ if (ret == -1 && errno == EPIPE && got_sigpipe) {
+ tap_ok("write to closed pipe returns EPIPE + SIGPIPE");
+ } else if (ret == -1 && errno == EPIPE) {
+ tap_ok("write to closed pipe returns EPIPE (SIGPIPE not caught)");
+ } else {
+ char msg[128];
+
+ snprintf(msg, sizeof(msg),
+ "expected EPIPE, got %s (sigpipe=%d)",
+ ret >= 0 ? "success" : strerror(errno),
+ (int)got_sigpipe);
+ tap_fail("write to closed pipe returns EPIPE + SIGPIPE", msg);
+ }
+
+ /* Restore SIGPIPE handler */
+ sigaction(SIGPIPE, &old_sa, NULL);
+ close(pipefd[1]);
+}
+
+/*
+ * Test 23: open with O_DIRECTORY on a regular file returns ENOTDIR
+ */
+static void test_open_directory_on_file(void)
+{
+ errno = 0;
+ long ret = kapi_sys_open("/dev/null", O_RDONLY | O_DIRECTORY, 0);
+
+ if (ret == -1 && errno == ENOTDIR) {
+ tap_ok("open O_DIRECTORY on regular file returns ENOTDIR");
+ } else if (ret >= 0) {
+ tap_fail("open O_DIRECTORY on regular file",
+ "expected ENOTDIR, got success");
+ syscall(__NR_close, (int)ret);
+ } else {
+ char msg[64];
+
+ snprintf(msg, sizeof(msg), "expected ENOTDIR, got %s",
+ strerror(errno));
+ tap_fail("open O_DIRECTORY on regular file", msg);
+ }
+}
+
+/*
+ * Test 24: open nonexistent file without O_CREAT returns ENOENT
+ */
+static void test_open_nonexistent(void)
+{
+ errno = 0;
+ long ret = kapi_sys_open("/tmp/kapi_nonexistent_file_12345",
+ O_RDONLY, 0);
+
+ if (ret == -1 && errno == ENOENT) {
+ tap_ok("open nonexistent file without O_CREAT returns ENOENT");
+ } else if (ret >= 0) {
+ tap_fail("open nonexistent file",
+ "expected ENOENT, got success (file exists?)");
+ syscall(__NR_close, (int)ret);
+ } else {
+ char msg[64];
+
+ snprintf(msg, sizeof(msg), "expected ENOENT, got %s",
+ strerror(errno));
+ tap_fail("open nonexistent file", msg);
+ }
+}
+
+/*
+ * Test 25: close stdin (fd 0) should succeed
+ * We dup it first so we can restore it.
+ */
+static void test_close_stdin(void)
+{
+ int saved_stdin = dup(0);
+
+ if (saved_stdin < 0) {
+ tap_fail("close stdin succeeds", "cannot dup stdin");
+ return;
+ }
+
+ errno = 0;
+ long ret = syscall(__NR_close, 0);
+
+ if (ret == 0) {
+ tap_ok("close stdin (fd 0) succeeds");
+ } else {
+ char msg[64];
+
+ snprintf(msg, sizeof(msg), "expected success, got %s",
+ strerror(errno));
+ tap_fail("close stdin (fd 0) succeeds", msg);
+ }
+
+ /* Restore stdin */
+ dup2(saved_stdin, 0);
+ close(saved_stdin);
+}
+
+/*
+ * Test 26: read after close returns EBADF
+ */
+static void test_read_after_close(void)
+{
+ long fd;
+
+ errno = 0;
+ fd = kapi_sys_open("/dev/null", O_RDONLY, 0);
+ if (fd < 0) {
+ tap_fail("read after close returns EBADF",
+ "cannot open /dev/null");
+ return;
+ }
+
+ syscall(__NR_close, (int)fd);
+
+ char buf[16];
+
+ errno = 0;
+ long ret = syscall(__NR_read, (int)fd, buf, sizeof(buf));
+
+ if (ret == -1 && errno == EBADF) {
+ tap_ok("read after close returns EBADF");
+ } else {
+ char msg[64];
+
+ snprintf(msg, sizeof(msg), "expected EBADF, got %s",
+ ret >= 0 ? "success" : strerror(errno));
+ tap_fail("read after close returns EBADF", msg);
+ }
+}
+
+/*
+ * Test 27: write with large count
+ * Without KAPI: the kernel clamps count to MAX_RW_COUNT and succeeds.
+ * With KAPI: KAPI validates the buffer against the count and may
+ * return EFAULT/EINVAL since the buffer is smaller than count.
+ * Accept either success or EFAULT/EINVAL.
+ */
+static void test_write_large_count(void)
+{
+ long fd;
+ char buf[64] = "test data";
+
+ errno = 0;
+ fd = kapi_sys_open("/dev/null", O_WRONLY, 0);
+ if (fd < 0) {
+ tap_fail("write with large count handled correctly",
+ "cannot open /dev/null");
+ return;
+ }
+
+ errno = 0;
+ long ret = syscall(__NR_write, (int)fd, buf, (size_t)0x7ffff000UL);
+
+ if (ret > 0) {
+ tap_ok("write with large count succeeds (clamped, no KAPI)");
+ } else if (ret == -1 && (errno == EFAULT || errno == EINVAL)) {
+ tap_ok("write with large count returns EFAULT/EINVAL (KAPI validates buffer)");
+ } else {
+ char msg[64];
+
+ snprintf(msg, sizeof(msg), "expected success or EFAULT, got %s",
+ ret == 0 ? "zero" : strerror(errno));
+ tap_fail("write with large count handled correctly", msg);
+ }
+
+ syscall(__NR_close, (int)fd);
+}
+
+/* ---- Integration tests ---- */
+
+/*
+ * Test 28: full normal syscall path - open, read, write, close
+ * Verify KAPI does not interfere with normal operations.
+ */
+static void test_normal_path(void)
+{
+ long rd_fd, wr_fd;
+ char buf[128];
+ int ok = 1;
+ char reason[128] = "";
+
+ /* Open a readable file */
+ errno = 0;
+ rd_fd = kapi_sys_open("/etc/hostname", O_RDONLY, 0);
+ if (rd_fd < 0) {
+ errno = 0;
+ rd_fd = kapi_sys_open("/etc/passwd", O_RDONLY, 0);
+ }
+ if (rd_fd < 0) {
+ snprintf(reason, sizeof(reason), "open readable file: %s",
+ strerror(errno));
+ ok = 0;
+ }
+
+ /* Read from it */
+ if (ok) {
+ errno = 0;
+ long n = syscall(__NR_read, (int)rd_fd, buf, sizeof(buf));
+
+ if (n < 0) {
+ snprintf(reason, sizeof(reason), "read: %s",
+ strerror(errno));
+ ok = 0;
+ }
+ }
+
+ /* Open /dev/null for writing */
+ wr_fd = -1;
+ if (ok) {
+ errno = 0;
+ wr_fd = kapi_sys_open("/dev/null", O_WRONLY, 0);
+ if (wr_fd < 0) {
+ snprintf(reason, sizeof(reason),
+ "open /dev/null: %s", strerror(errno));
+ ok = 0;
+ }
+ }
+
+ /* Write to /dev/null */
+ if (ok) {
+ errno = 0;
+ long n = syscall(__NR_write, (int)wr_fd, "test", 4);
+
+ if (n != 4) {
+ snprintf(reason, sizeof(reason), "write: %s",
+ n < 0 ? strerror(errno) : "short write");
+ ok = 0;
+ }
+ }
+
+ /* Close both fds */
+ if (rd_fd >= 0) {
+ errno = 0;
+ if (syscall(__NR_close, (int)rd_fd) != 0 && ok) {
+ snprintf(reason, sizeof(reason), "close read fd: %s",
+ strerror(errno));
+ ok = 0;
+ }
+ }
+
+ if (wr_fd >= 0) {
+ errno = 0;
+ if (syscall(__NR_close, (int)wr_fd) != 0 && ok) {
+ snprintf(reason, sizeof(reason), "close write fd: %s",
+ strerror(errno));
+ ok = 0;
+ }
+ }
+
+ if (ok)
+ tap_ok("normal syscall path (open/read/write/close) works");
+ else
+ tap_fail("normal syscall path (open/read/write/close) works",
+ reason);
+}
+
+/*
+ * Test 29: verify dmesg contains KAPI warnings for the invalid tests
+ */
+static void test_dmesg_warnings(void)
+{
+ int kmsg_fd = open("/dev/kmsg", O_RDONLY | O_NONBLOCK);
+
+ if (kmsg_fd < 0) {
+ tap_skip("dmesg contains expected KAPI warnings",
+ "cannot open /dev/kmsg");
+ return;
+ }
+
+ /*
+ * Rewind to the start of kmsg. SEEK_DATA on /dev/kmsg is the
+ * documented way to skip to the first entry still in the ring
+ * buffer. Older kernels (or CONFIG_PRINTK=n builds) may reject
+ * the seek with -EINVAL; in that case we can't reliably audit
+ * past warnings, so skip the test rather than fail it.
+ */
+ if (lseek(kmsg_fd, 0, SEEK_DATA) == (off_t)-1) {
+ tap_skip("dmesg contains expected KAPI warnings",
+ "lseek(SEEK_DATA) not supported on /dev/kmsg");
+ close(kmsg_fd);
+ return;
+ }
+
+ char line[4096];
+ int found_invalid_bits = 0;
+ int found_null = 0;
+ ssize_t n;
+
+ for (;;) {
+ n = read(kmsg_fd, line, sizeof(line) - 1);
+ if (n > 0) {
+ line[n] = '\0';
+ if (strstr(line, "contains invalid bits"))
+ found_invalid_bits++;
+ if (strstr(line, "NULL") && strstr(line, "not allowed"))
+ found_null++;
+ } else if (n == -1 && errno == EPIPE) {
+ /* Ring buffer wrapped, continue reading */
+ continue;
+ } else {
+ /* EAGAIN (no more messages) or other error */
+ break;
+ }
+ }
+
+ close(kmsg_fd);
+
+ if (found_invalid_bits >= 2 && found_null >= 1) {
+ tap_ok("dmesg contains expected KAPI warnings");
+ } else if (found_invalid_bits >= 1 || found_null >= 1) {
+ char msg[128];
+
+ snprintf(msg, sizeof(msg),
+ "partial: invalid_bits=%d null=%d",
+ found_invalid_bits, found_null);
+ tap_ok(msg);
+ } else {
+ tap_fail("dmesg KAPI warnings",
+ "no KAPI warnings found in dmesg");
+ }
+}
+
+int main(void)
+{
+ ksft_print_header();
+ ksft_set_plan(NUM_TESTS);
+
+ /* Valid operations (1-4) */
+ int fd = test_open_valid();
+
+ if (fd >= 0)
+ test_read_valid(fd);
+ else
+ tap_fail("read from valid fd", "no fd from open");
+
+ test_write_valid();
+
+ if (fd >= 0)
+ test_close_valid(fd);
+ else
+ tap_fail("close valid fd", "no fd from open");
+
+ /* KAPI parameter rejection (5-8) */
+ test_open_invalid_flags();
+ test_open_invalid_mode();
+ test_open_null_path();
+ test_open_flag_bit30();
+
+ /* Boundary conditions and error paths (9-20) */
+ test_read_bad_fd();
+ test_read_zero_count();
+ test_write_zero_count();
+ test_open_long_path();
+ test_read_unmapped_buf();
+ test_write_unmapped_buf();
+ test_close_already_closed();
+ test_open_valid_cloexec();
+ test_write_zero_devnull();
+ test_read_writeonly_fd();
+ test_write_readonly_fd();
+ test_close_fd_9999();
+
+ /* Pipe and lifecycle tests (21-27) */
+ test_read_closed_pipe();
+ test_write_closed_pipe();
+ test_open_directory_on_file();
+ test_open_nonexistent();
+ test_close_stdin();
+ test_read_after_close();
+ test_write_large_count();
+
+ /* Integration (28-29) */
+ test_normal_path();
+ test_dmesg_warnings();
+
+ ksft_finished();
+ return 0;
+}
--
2.53.0
^ permalink raw reply related
* [PATCH v3 8/9] kernel/api: add API specification for sys_write
From: Sasha Levin @ 2026-04-24 16:51 UTC (permalink / raw)
To: linux-api, linux-kernel
Cc: linux-doc, linux-fsdevel, linux-kbuild, linux-kselftest,
workflows, tools, x86, Thomas Gleixner, Paul E . McKenney,
Greg Kroah-Hartman, Jonathan Corbet, Dmitry Vyukov, Randy Dunlap,
Cyril Hrubis, Kees Cook, Jake Edge, David Laight, Askar Safin,
Gabriele Paoloni, Mauro Carvalho Chehab, Christian Brauner,
Alexander Viro, Andrew Morton, Masahiro Yamada, Shuah Khan,
Ingo Molnar, Arnd Bergmann, Sasha Levin
In-Reply-To: <20260424165130.2306833-1-sashal@kernel.org>
Add KAPI-annotated kerneldoc for the sys_write system call in
fs/read_write.c.
The specification documents parameter constraints (fd, user buffer,
count), error conditions, locking requirements, signal handling
behavior, and short write semantics.
Signed-off-by: Sasha Levin <sashal@kernel.org>
---
fs/read_write.c | 391 ++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 391 insertions(+)
diff --git a/fs/read_write.c b/fs/read_write.c
index 258efd5b5793b..28312311df875 100644
--- a/fs/read_write.c
+++ b/fs/read_write.c
@@ -1046,6 +1046,397 @@ ssize_t ksys_write(unsigned int fd, const char __user *buf, size_t count)
return ret;
}
+/**
+ * sys_write - Write data to a file descriptor
+ * @fd: File descriptor to write to
+ * @buf: User-space buffer containing data to write
+ * @count: Maximum number of bytes to write
+ *
+ * long-desc: Attempts to write up to count bytes from the buffer starting at
+ * buf to the file referred to by the file descriptor fd. For seekable files
+ * (regular files, block devices), the write begins at the current file offset,
+ * and the file offset is advanced by the number of bytes written. If the file
+ * was opened with O_APPEND, the file offset is first set to the end of the
+ * file before writing. For non-seekable files (pipes, FIFOs, sockets, character
+ * devices), the file offset is not used and writing occurs at the current
+ * position as defined by the device.
+ *
+ * The number of bytes written may be less than count if, for example, there is
+ * insufficient space on the underlying physical medium, or the RLIMIT_FSIZE
+ * resource limit is encountered, or the call was interrupted by a signal
+ * handler after having written less than count bytes. In the event of a
+ * successful partial write, the caller should make another write() call to
+ * transfer the remaining bytes. This behavior is called a "short write."
+ *
+ * On Linux, write() transfers at most MAX_RW_COUNT (0x7ffff000, approximately
+ * 2GB minus one page) bytes per call, regardless of whether the file or
+ * filesystem would allow more. This prevents signed arithmetic overflow.
+ *
+ * For regular files, a successful write() does not guarantee that data has been
+ * committed to disk. Use fsync(2) or fdatasync(2) if durability is required.
+ * For O_SYNC or O_DSYNC files, the kernel automatically syncs data on write.
+ *
+ * POSIX permits writes that are interrupted after partial writes to either
+ * return -1 with errno=EINTR, or to return the count of bytes already written.
+ * Linux implements the latter behavior: if some data has been written before
+ * a signal arrives, write() returns the number of bytes written rather than
+ * failing with EINTR.
+ *
+ * contexts: process, sleepable
+ *
+ * param: fd
+ * type: fd, input
+ * constraint-type: range(0, INT_MAX)
+ * cdesc: Must be a valid, open file descriptor with write permission.
+ * The file must have been opened with O_WRONLY or O_RDWR. File descriptors
+ * opened with O_RDONLY, O_PATH, or that have been closed return EBADF.
+ * Standard file descriptors 0 (stdin), 1 (stdout), 2 (stderr) are valid if
+ * open and writable. AT_FDCWD and other special values are not valid.
+ *
+ * param: buf
+ * type: user_ptr, input
+ * constraint-type: buffer(2)
+ * cdesc: Must point to a valid, readable user-space memory region of at
+ * least count bytes. The buffer is validated via access_ok() before any
+ * write operation. NULL is invalid and returns EFAULT. For O_DIRECT writes,
+ * the buffer may need to be aligned to the filesystem's block size (varies
+ * by filesystem; query with statx() using STATX_DIOALIGN on Linux 6.1+).
+ *
+ * param: count
+ * type: uint, input
+ * constraint-type: range(0, SIZE_MAX)
+ * cdesc: Maximum number of bytes to write. Clamped internally to
+ * MAX_RW_COUNT (INT_MAX & PAGE_MASK, approximately 0x7ffff000 bytes) to
+ * prevent signed overflow. A count of 0 is passed through to the underlying
+ * file operation and typically returns 0, but may trigger filesystem
+ * or driver-specific side effects. Cast to ssize_t must not be negative.
+ *
+ * return:
+ * type: int
+ * check-type: range
+ * success: >= 0
+ * desc: On success, returns the number of bytes written (non-negative). Zero
+ * indicates that nothing was written (count was 0, or no space available
+ * for non-blocking writes). The return value may be less than count due to
+ * resource limits, signal interruption, or device constraints (short write).
+ * On error, returns a negative error code.
+ *
+ * error: EBADF, Bad file descriptor
+ * desc: fd is not a valid file descriptor, or fd was not opened for writing.
+ * This includes file descriptors opened with O_RDONLY, O_PATH, or file
+ * descriptors that have been closed. Also returned if the file structure
+ * does not have FMODE_WRITE set.
+ *
+ * error: EFAULT, Bad address
+ * desc: buf points outside the accessible address space. The buffer address
+ * failed access_ok() validation. Can also occur if a fault happens during
+ * copy_from_user() when reading data from user space.
+ *
+ * error: EINVAL, Invalid argument
+ * desc: Returned in several cases: (1) The file descriptor refers to an
+ * object that is not suitable for writing (no write or write_iter method).
+ * (2) The file was opened with O_DIRECT and the buffer alignment, offset,
+ * or count does not meet the filesystem's alignment requirements. (3) The
+ * count argument, when cast to ssize_t, is negative. Also returned if the
+ * file lacks the FMODE_CAN_WRITE flag.
+ *
+ * error: EAGAIN, Resource temporarily unavailable
+ * desc: fd refers to a file (pipe, socket, device) that is marked non-blocking
+ * (O_NONBLOCK) and the write would block because the buffer is full.
+ * Equivalent to EWOULDBLOCK. The application should retry later or use
+ * select/poll/epoll to wait for writability.
+ *
+ * error: EWOULDBLOCK, Operation would block
+ * desc: Alias of EAGAIN on Linux (identical errno value). POSIX permits
+ * implementations to distinguish the two; Linux does not. Listed here
+ * for completeness so tooling that consults the spec does not treat
+ * EWOULDBLOCK-returning call sites as undocumented. See EAGAIN above
+ * for the conditions that trigger it.
+ *
+ * error: EINTR, Interrupted system call
+ * desc: The call was interrupted by a signal before any data was written. This
+ * only occurs if no data has been transferred; if some data was written
+ * before the signal, the call returns the number of bytes written. The
+ * caller should typically restart the write.
+ *
+ * error: EPIPE, Broken pipe
+ * desc: fd refers to a pipe or socket whose reading end has been closed.
+ * When this condition occurs, the calling process also receives a SIGPIPE
+ * signal. If the signal is caught or ignored, EPIPE is still returned.
+ * For sockets, MSG_NOSIGNAL (via send()) suppresses the signal. For
+ * pwritev2(), the RWF_NOSIGNAL flag suppresses it.
+ *
+ * error: EFBIG, File too large
+ * desc: An attempt was made to write a file that exceeds the implementation-
+ * defined maximum file size or the file size limit (RLIMIT_FSIZE) of the
+ * process. When RLIMIT_FSIZE is exceeded, the process also receives SIGXFSZ.
+ * For files not opened with O_LARGEFILE on 32-bit systems, the limit is 2GB.
+ *
+ * error: ENOSPC, No space left on device
+ * desc: The device containing the file has no room for the data. This can
+ * occur mid-write resulting in a short write followed by ENOSPC on retry.
+ *
+ * error: EDQUOT, Disk quota exceeded
+ * desc: The user's quota of disk blocks on the filesystem has been exhausted.
+ * Like ENOSPC, this can result in a short write.
+ *
+ * error: EIO, Input/output error
+ * desc: A low-level I/O error occurred while modifying the inode or writing
+ * data. This typically indicates hardware failure, filesystem corruption,
+ * or network filesystem timeout. Some data may have been written.
+ *
+ * error: EPERM, Operation not permitted
+ * desc: The operation was prevented: (1) by a file seal (F_SEAL_WRITE or
+ * F_SEAL_FUTURE_WRITE on memfd/shmem), (2) writing to an immutable inode
+ * (IS_IMMUTABLE), (3) by an LSM hook denying the operation, or (4) by a
+ * fanotify permission event denying the write.
+ *
+ * error: EOVERFLOW, Value too large for defined data type
+ * desc: The file position plus count would exceed LLONG_MAX. Also returned
+ * when the offset would exceed filesystem limits after the write.
+ *
+ * error: EDESTADDRREQ, Destination address required
+ * desc: fd is a datagram socket for which no peer address has been set using
+ * connect(2). Use sendto(2) to specify the destination address.
+ *
+ * error: ETXTBSY, Text file busy
+ * desc: The file is being used as a swap file (IS_SWAPFILE). Note: unlike
+ * the traditional Unix meaning, Linux does not return ETXTBSY when writing
+ * to an executing binary; that only blocks open() with O_WRONLY/O_RDWR.
+ *
+ * error: EXDEV, Cross-device link
+ * desc: When writing to a pipe that has been configured as a watch queue
+ * (CONFIG_WATCH_QUEUE), direct write() calls are not supported.
+ *
+ * error: ENOMEM, Out of memory
+ * desc: Insufficient kernel memory was available for the write operation.
+ * For pipes, this occurs when allocating pages for the pipe buffer.
+ *
+ * error: ERESTARTSYS, Restart system call (internal)
+ * desc: Internal error code indicating the syscall should be restarted. This
+ * is converted to EINTR if SA_RESTART is not set on the signal handler, or
+ * the syscall is transparently restarted if SA_RESTART is set. User space
+ * should not see this error code directly.
+ *
+ * error: EACCES, Permission denied
+ * desc: The security subsystem (LSM such as SELinux or AppArmor) denied the
+ * write operation via security_file_permission(). This can occur even if
+ * the file was successfully opened.
+ *
+ * lock: file->f_pos_lock
+ * type: mutex
+ * acquired: conditional
+ * released: true
+ * desc: For regular files that require atomic position updates (FMODE_ATOMIC_POS),
+ * the f_pos_lock mutex is acquired by fdget_pos() at syscall entry and released
+ * by fdput_pos() at syscall exit. This serializes concurrent writes sharing
+ * the same file description. Not acquired for stream files (FMODE_STREAM like
+ * pipes and sockets) or when the file is not shared.
+ *
+ * lock: sb->s_writers (freeze protection)
+ * type: custom
+ * acquired: conditional
+ * released: true
+ * desc: For regular files, file_start_write() acquires freeze protection on
+ * the superblock via sb_start_write() before the write, and file_end_write()
+ * releases it after. This prevents writes during filesystem freeze. Not
+ * acquired for non-regular files (pipes, sockets, devices).
+ *
+ * lock: inode->i_rwsem
+ * type: rwlock
+ * acquired: conditional
+ * released: true
+ * desc: For regular files using generic_file_write_iter(), the inode's i_rwsem
+ * is acquired in write mode before modifying file data. This is internal to
+ * the filesystem and released before return. Not all filesystems use this
+ * pattern.
+ *
+ * lock: pipe->mutex
+ * type: mutex
+ * acquired: conditional
+ * released: true
+ * desc: For pipes and FIFOs, the pipe's mutex is held while modifying pipe
+ * buffers. Released temporarily while waiting for space, then reacquired.
+ *
+ * lock: RCU read-side
+ * type: rcu
+ * acquired: conditional
+ * released: true
+ * desc: Held transiently during file descriptor table lookup within fdget().
+ * The RCU read lock is acquired and released internally by the fd lookup
+ * path, not held across the entire syscall. fdput() releases the file
+ * reference count, not the RCU lock.
+ *
+ * signal: SIGPIPE
+ * direction: send
+ * action: terminate
+ * condition: Writing to a pipe or socket with no readers
+ * desc: When writing to a pipe whose read end is closed, or a socket whose
+ * peer has closed, SIGPIPE is sent to the calling process. The default
+ * action terminates the process. Use signal(SIGPIPE, SIG_IGN) to suppress
+ * for write(). EPIPE is returned regardless of signal disposition.
+ * timing: during
+ *
+ * signal: SIGXFSZ
+ * direction: send
+ * action: coredump
+ * condition: Writing exceeds RLIMIT_FSIZE
+ * desc: When a write would exceed the soft file size limit (RLIMIT_FSIZE),
+ * SIGXFSZ is sent. The default action terminates with a core dump. The
+ * write returns EFBIG. If RLIMIT_FSIZE is RLIM_INFINITY, no signal is sent.
+ * timing: during
+ *
+ * signal: Any signal
+ * direction: receive
+ * action: return
+ * condition: While blocked waiting for space (pipes, sockets)
+ * desc: The syscall may be interrupted by signals while waiting for buffer
+ * space to become available. If interrupted before any data is written,
+ * returns -EINTR or -ERESTARTSYS. If data was already written, returns the
+ * byte count. Restartable if SA_RESTART is set and no data was written.
+ * errno: -EINTR
+ * timing: during
+ * restartable: yes
+ *
+ * side-effect: file_position
+ * target: file->f_pos
+ * condition: For seekable files when write succeeds (returns > 0)
+ * desc: The file offset (f_pos) is advanced by the number of bytes written.
+ * For files opened with O_APPEND, f_pos is first set to file size. For
+ * stream files (FMODE_STREAM such as pipes and sockets), the offset is not
+ * used or modified. Position updates are protected by f_pos_lock when
+ * shared.
+ * reversible: no
+ *
+ * side-effect: modify_state
+ * target: inode timestamps (mtime, ctime)
+ * condition: When write succeeds (returns > 0)
+ * desc: Updates the file's modification time (mtime) and change time (ctime)
+ * via file_update_time(). The update precision depends on filesystem mount
+ * options (fine-grained timestamps for multigrain inodes).
+ * reversible: no
+ *
+ * side-effect: modify_state
+ * target: SUID/SGID bits (mode)
+ * condition: When writing to a setuid/setgid file
+ * desc: The SUID bit is cleared when a non-root user writes to a file with
+ * the bit set. The SGID bit may also be cleared. This is a security feature
+ * to prevent privilege escalation via modified setuid binaries. Done via
+ * file_remove_privs().
+ * reversible: no
+ *
+ * side-effect: modify_state
+ * target: file data
+ * condition: When write succeeds (returns > 0)
+ * desc: Modifies the file's data content. For regular files, data is written
+ * to the page cache (buffered I/O) or directly to storage (O_DIRECT).
+ * Data may not be persistent until fsync() is called or the file is closed.
+ * reversible: no
+ *
+ * side-effect: modify_state
+ * target: task I/O accounting
+ * condition: Always
+ * desc: Updates the current task's I/O accounting statistics. The wchar field
+ * (write characters) is incremented by bytes written via add_wchar() only on
+ * successful writes (ret > 0). The syscw field (syscall write count) is
+ * incremented via inc_syscw() when the write operation is attempted
+ * (after passing initial validation checks). These statistics are visible
+ * in /proc/[pid]/io.
+ * reversible: no
+ *
+ * side-effect: modify_state
+ * target: fsnotify events
+ * condition: When write returns > 0
+ * desc: Generates an FS_MODIFY fsnotify event via fsnotify_modify(), allowing
+ * inotify, fanotify, and dnotify watchers to be notified of the write.
+ *
+ * capability: CAP_DAC_OVERRIDE
+ * type: bypass_check
+ * allows: Bypass discretionary access control on write permission
+ * without: Standard DAC checks are enforced
+ * condition: Checked at open time via inode_permission(), not during read()
+ *
+ * capability: CAP_FSETID
+ * type: bypass_check
+ * allows: Bypass ownership checks for SUID/SGID clearing
+ * without: SUID/SGID bits are cleared on write by non-owner
+ * condition: Checked during file_remove_privs()
+ *
+ * constraint: MAX_RW_COUNT
+ * desc: The count parameter is silently clamped to MAX_RW_COUNT (INT_MAX &
+ * PAGE_MASK, approximately 2GB minus one page) to prevent integer overflow
+ * in internal calculations. This is transparent to the caller.
+ * expr: actual_count = min(count, MAX_RW_COUNT)
+ *
+ * constraint: File must be open for writing
+ * desc: The file descriptor must have been opened with O_WRONLY or O_RDWR.
+ * Files opened with O_RDONLY or O_PATH cannot be written and return EBADF.
+ * The file must have both FMODE_WRITE and FMODE_CAN_WRITE flags set.
+ * expr: (file->f_mode & FMODE_WRITE) && (file->f_mode & FMODE_CAN_WRITE)
+ *
+ * constraint: RLIMIT_FSIZE
+ * desc: The size of data written is constrained by the RLIMIT_FSIZE resource
+ * limit. If writing would exceed this limit, SIGXFSZ is sent and EFBIG is
+ * returned. The limit does not apply to files beyond the limit - only to
+ * writes that would cross it.
+ * expr: pos + count <= rlimit(RLIMIT_FSIZE) || rlimit(RLIMIT_FSIZE) == RLIM_INFINITY
+ *
+ * constraint: File seals
+ * desc: For memfd or shmem files with F_SEAL_WRITE or F_SEAL_FUTURE_WRITE
+ * seals applied, all write operations fail with EPERM. With F_SEAL_GROW,
+ * writes that would extend file size fail with EPERM.
+ *
+ * examples: n = write(fd, buf, sizeof(buf)); // Basic write
+ * n = write(STDOUT_FILENO, msg, strlen(msg)); // Write to stdout
+ * // Handle short writes:
+ * while (total < len) {
+ * n = write(fd, buf + total, len - total);
+ * if (n < 0) break;
+ * total += n;
+ * }
+ * // Pipe error handling:
+ * if (write(pipefd[1], &byte, 1) < 0 && errno == EPIPE)
+ * handle_broken_pipe();
+ *
+ * notes: The behavior of write() varies significantly depending on the type of
+ * file descriptor:
+ *
+ * - Regular files: Writes to the page cache (buffered) or directly to storage
+ * (O_DIRECT). Short writes are rare except near RLIMIT_FSIZE or disk full.
+ * O_APPEND is atomic for determining write position.
+ *
+ * - Pipes and FIFOs: Blocking by default. Writes up to PIPE_BUF (4096 bytes
+ * on Linux) are guaranteed atomic. Larger writes may be interleaved with
+ * writes from other processes. Blocks if pipe is full; returns EAGAIN with
+ * O_NONBLOCK. SIGPIPE/EPIPE if no readers.
+ *
+ * - Sockets: Behavior depends on socket type and protocol. Stream sockets
+ * (TCP) may return partial writes. Datagram sockets (UDP) typically write
+ * complete messages or fail. SIGPIPE/EPIPE for broken connections (unless
+ * MSG_NOSIGNAL). EDESTADDRREQ for unconnected datagram sockets.
+ *
+ * - Terminals: May block on flow control. Canonical vs raw mode affects
+ * behavior. Special characters may be interpreted.
+ *
+ * - Device special files: Behavior is device-specific. Block devices behave
+ * similarly to regular files. Character device behavior varies.
+ *
+ * Race condition considerations: Concurrent writes from threads sharing a
+ * file description race on the file position. Linux 3.14+ provides atomic
+ * position updates via f_pos_lock for regular files (FMODE_ATOMIC_POS), but
+ * for maximum safety, use pwrite() for concurrent positioned writes.
+ *
+ * O_DIRECT writes bypass the page cache and typically require buffer and
+ * offset alignment to filesystem block size. Query requirements via statx()
+ * with STATX_DIOALIGN (Linux 6.1+). Unaligned O_DIRECT writes return EINVAL
+ * on most filesystems.
+ *
+ * For zero-copy writes, consider using splice(2), sendfile(2), or vmsplice(2)
+ * instead of copying data through user-space buffers with write().
+ *
+ * Partial writes (short writes) must be handled by application code.
+ * Applications should loop until all data is written or an error occurs.
+ */
SYSCALL_DEFINE3(write, unsigned int, fd, const char __user *, buf,
size_t, count)
{
--
2.53.0
^ permalink raw reply related
page: next (older) | prev (newer) | latest
- recent:[subjects (threaded)|topics (new)|topics (active)]
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox