* Re: [PATCH v6 0/5] kunit: Add support for suppressing warning backtraces
From: Dan Carpenter @ 2026-03-17 10:03 UTC (permalink / raw)
To: Albert Esteve
Cc: Arnd Bergmann, Brendan Higgins, David Gow, Rae Moar,
Maarten Lankhorst, Maxime Ripard, Thomas Zimmermann, David Airlie,
Simona Vetter, Jonathan Corbet, Shuah Khan, linux-kernel,
linux-arch, linux-kselftest, kunit-dev, dri-devel, workflows,
linux-doc, Alessandro Carminati, Guenter Roeck, Kees Cook,
Linux Kernel Functional Testing, Maíra Canal, Simona Vetter
In-Reply-To: <20260317-kunit_add_support-v6-0-dd22aeb3fe5d@redhat.com>
I think this is great to suppress some warnings, and I already ACKed
this patchset. But we're still going to have some warnings where the
warning is the whole point of the test.
It would be great if marked these somehow:
1) At minimum we should mark them so people seeing the warning know it's
intentional. "Intentional Stack Trace". I've sent at least one patch
to add that printk before the stack trace but it was ignored. We could
do this piecemeal.
2) It would be nice if the print was standardized enough so CI systems
could automatically filter it out.
regards,
dan carpenter
^ permalink raw reply
* Re: [PATCH v6 0/5] kunit: Add support for suppressing warning backtraces
From: Vlastimil Babka (SUSE) @ 2026-03-17 11:20 UTC (permalink / raw)
To: Albert Esteve, Arnd Bergmann, Brendan Higgins, David Gow,
Rae Moar, Maarten Lankhorst, Maxime Ripard, Thomas Zimmermann,
David Airlie, Simona Vetter, Jonathan Corbet, Shuah Khan,
Peter Zijlstra
Cc: linux-kernel, linux-arch, linux-kselftest, kunit-dev, dri-devel,
workflows, linux-doc, Alessandro Carminati, Guenter Roeck,
Kees Cook, Linux Kernel Functional Testing, Dan Carpenter,
Maíra Canal, Simona Vetter
In-Reply-To: <20260317-kunit_add_support-v6-0-dd22aeb3fe5d@redhat.com>
On 3/17/26 10:24, Albert Esteve wrote:
> Some unit tests intentionally trigger warning backtraces by passing bad
> parameters to kernel API functions. Such unit tests typically check the
> return value from such calls, not the existence of the warning backtrace.
>
> Such intentionally generated warning backtraces are neither desirable
> nor useful for a number of reasons:
> - They can result in overlooked real problems.
> - A warning that suddenly starts to show up in unit tests needs to be
> investigated and has to be marked to be ignored, for example by
> adjusting filter scripts. Such filters are ad hoc because there is
> no real standard format for warnings. On top of that, such filter
> scripts would require constant maintenance.
>
> One option to address the problem would be to add messages such as
> "expected warning backtraces start/end here" to the kernel log.
> However, that would again require filter scripts, might result in
> missing real problematic warning backtraces triggered while the test
> is running, and the irrelevant backtrace(s) would still clog the
> kernel log.
>
> Solve the problem by providing a means to identify and suppress specific
> warning backtraces while executing test code. Support suppressing multiple
> backtraces while at the same time limiting changes to generic code to the
> absolute minimum.
>
> Overview:
> Patch#1 Introduces the suppression infrastructure.
> Patch#2 Mitigate the impact at WARN*() sites.
> Patch#3 Adds selftests to validate the functionality.
> Patch#4 Demonstrates real-world usage in the DRM subsystem.
> Patch#5 Documents the new API and usage guidelines.
>
> Design Notes:
> The objective is to suppress unwanted WARN*() generated messages.
>
> Although most major architectures share common bug handling via `lib/bug.c`
> and `report_bug()`, some minor or legacy architectures still rely on their
> own platform-specific handling. This divergence must be considered in any
> such feature. Additionally, a key challenge in implementing this feature is
> the fragmentation of `WARN*()` messages emission: specific part in the
> macro, common with BUG*() part in the exception handler.
> As a result, any intervention to suppress the message must occur before the
> illegal instruction.
>
> Lessons from the Previous Attempt
> In earlier iterations, suppression logic was added inside the
> `__report_bug()` function to intercept WARN*() messages not producing
> messages in the macro.
> To implement the check in the bug handler code, two strategies were
> considered:
>
> * Strategy #1: Use `kallsyms` to infer the originating functionid, namely
> a pointer to the function. Since in any case, the user interface relies
> on function names, they must be translated in addresses at suppression-
> time or at check-time.
> Assuming to translate at suppression-time, the `kallsyms` subsystem needs
> to be used to determine the symbol address from the name, and again to
> produce the functionid from `bugaddr`. This approach proved unreliable
> due to compiler-induced transformations such as inlining, cloning, and
> code fragmentation. Attempts to preventing them is also unconvenient
> because several `WARN()` sites are in functions intentionally declared
> as `__always_inline`.
>
> * Strategy #2: Store function name `__func__` in `struct bug_entry` in
> the `__bug_table`. This implementation was used in the previous version.
> However, `__func__` is a compiler-generated symbol, which complicates
> relocation and linking in position-independent code. Workarounds such as
> storing offsets from `.rodata` or embedding string literals directly into
> the table would have significantly either increased complexity or
> increase the __bug_table size.
> Additionally, architectures not using the unified `BUG()` path would
> still require ad-hoc handling. Because current WARN*() message production
> strategy, a few WARN*() macros still need a check to suppress the part of
> the message produced in the macro itself.
>
> As a result, previous version proposed a per-macro solution, which offers
> better control on where the suppression logic is applied.
>
> For this iteration, the `__report_bug()` centralized approach was
> revisited after the discussion in the previous version [1].
Discussion with PeterZ, who is not CC'd here? (did it now for my reply).
> However, again this approach did not work because:
> - Some warning output is generated directly in the macros before calling
> the centralized functions (e.g., `__warn_printk()` in `__WARN_printf()`)
> - Functions in the warning path like `warn_slowpath_fmt()` are marked
> `__always_inline`, making it difficult to intercept early enough
> - So, by the time `__report_bug()` is called, output has already been written
> to the console, making suppression ineffective
>
> Current Proposal: Check Directly in the `WARN()` Macros.
> This avoids the need for function symbol resolution or ELF section
> modification.
> Suppression is implemented directly in the `WARN*()` macros.
So does that bloat every warn/bug site (as Peter objected to) or not?
And is it compatible with x86? I see you modify include/asm-generic/bug.h
but x86 has its own version of e.g. __WARN_printf ?
> A helper function, `__kunit_is_suppressed_warning()`, is used to determine
> whether suppression applies. It is marked as `noinstr`, since some `WARN*()`
> sites reside in non-instrumentable sections. The function uses a static
> branch for the fast path check (which is `noinstr`-safe), and only calls
> the actual suppression check (which uses `strcmp`, and is surrounded by
> instrumentation_begin()/end() calls) when suppressions are active.
> The list of suppressed warnings is protected with RCU (Read-Copy-Update)
> to allow concurrent read access without locks.
>
> To minimize runtime impact when no suppressions are active, static branching
> is used via a static key (`kunit_suppress_warnings_key`). The branch is
> automatically enabled when the first suppression starts and disabled when the
> last suppression ends, tracked via an atomic counter. This keeps the suppression
> check code out-of-line, reducing code bloat at each `WARN*()` site while
> maintaining minimal runtime overhead in the common case (no active suppressions).
>
> This series is based on the RFC patch and subsequent discussion at
> https://patchwork.kernel.org/project/linux-kselftest/patch/02546e59-1afe-4b08-ba81-d94f3b691c9a@moroto.mountain/
> and offers a more comprehensive solution of the problem discussed there.
>
> [1] https://lore.kernel.org/all/CAGegRW76X8Fk_5qqOBw_aqBwAkQTsc8kXKHEuu9ECeXzdJwMSw@mail.gmail.com/
>
> Changes since RFC:
> - Introduced CONFIG_KUNIT_SUPPRESS_BACKTRACE
> - Minor cleanups and bug fixes
> - Added support for all affected architectures
> - Added support for counting suppressed warnings
> - Added unit tests using those counters
> - Added patch to suppress warning backtraces in dev_addr_lists tests
>
> Changes since v1:
> - Rebased to v6.9-rc1
> - Added Tested-by:, Acked-by:, and Reviewed-by: tags
> [I retained those tags since there have been no functional changes]
> - Introduced KUNIT_SUPPRESS_BACKTRACE configuration option, enabled by
> default.
>
> Changes since v2:
> - Rebased to v6.9-rc2
> - Added comments to drm warning suppression explaining why it is needed.
> - Added patch to move conditional code in arch/sh/include/asm/bug.h
> to avoid kerneldoc warning
> - Added architecture maintainers to Cc: for architecture specific patches
> - No functional changes
>
> Changes since v3:
> - Rebased to v6.14-rc6
> - Dropped net: "kunit: Suppress lock warning noise at end of dev_addr_lists tests"
> since 3db3b62955cd6d73afde05a17d7e8e106695c3b9
> - Added __kunit_ and KUNIT_ prefixes.
> - Tested on interessed architectures.
>
> Changes since v4:
> - Rebased to v6.15-rc7
> - Dropped all code in __report_bug()
> - Moved all checks in WARN*() macros.
> - Dropped all architecture specific code.
> - Made __kunit_is_suppressed_warning nice to noinstr functions.
>
> Changes since v5:
> - Rebased to v7.0-rc3
> - Added RCU protection for the suppressed warnings list.
> - Added static key and branching optimization.
> - Removed custom `strcmp` implementation and reworked
> __kunit_is_suppressed_warning() entrypoint function.
>
> Alessandro Carminati (2):
> bug/kunit: Core support for suppressing warning backtraces
> bug/kunit: Suppressing warning backtraces reduced impact on WARN*()
> sites
>
> Guenter Roeck (3):
> Add unit tests to verify that warning backtrace suppression works.
> drm: Suppress intentional warning backtraces in scaling unit tests
> kunit: Add documentation for warning backtrace suppression API
>
> Documentation/dev-tools/kunit/usage.rst | 30 ++++++-
> drivers/gpu/drm/tests/drm_rect_test.c | 16 ++++
> include/asm-generic/bug.h | 48 +++++++----
> include/kunit/bug.h | 62 ++++++++++++++
> include/kunit/test.h | 1 +
> lib/kunit/Kconfig | 9 ++
> lib/kunit/Makefile | 9 +-
> lib/kunit/backtrace-suppression-test.c | 105 ++++++++++++++++++++++++
> lib/kunit/bug.c | 54 ++++++++++++
> 9 files changed, 316 insertions(+), 18 deletions(-)
> create mode 100644 include/kunit/bug.h
> create mode 100644 lib/kunit/backtrace-suppression-test.c
> create mode 100644 lib/kunit/bug.c
>
> --
> 2.34.1
>
> ---
> Alessandro Carminati (2):
> bug/kunit: Core support for suppressing warning backtraces
> bug/kunit: Suppressing warning backtraces reduced impact on WARN*() sites
>
> Guenter Roeck (3):
> Add unit tests to verify that warning backtrace suppression works.
> drm: Suppress intentional warning backtraces in scaling unit tests
> kunit: Add documentation for warning backtrace suppression API
>
> Documentation/dev-tools/kunit/usage.rst | 30 ++++++++-
> drivers/gpu/drm/tests/drm_rect_test.c | 16 +++++
> include/asm-generic/bug.h | 44 ++++++++-----
> include/kunit/bug.h | 61 ++++++++++++++++++
> include/kunit/test.h | 1 +
> lib/kunit/Kconfig | 9 +++
> lib/kunit/Makefile | 9 ++-
> lib/kunit/backtrace-suppression-test.c | 109 ++++++++++++++++++++++++++++++++
> lib/kunit/bug.c | 71 +++++++++++++++++++++
> 9 files changed, 332 insertions(+), 18 deletions(-)
> ---
> base-commit: 80234b5ab240f52fa45d201e899e207b9265ef91
> change-id: 20260312-kunit_add_support-2f35806b19dd
>
> Best regards,
^ permalink raw reply
* Re: [PATCH v6 0/5] kunit: Add support for suppressing warning backtraces
From: Peter Zijlstra @ 2026-03-17 11:30 UTC (permalink / raw)
To: Vlastimil Babka (SUSE)
Cc: Albert Esteve, Arnd Bergmann, Brendan Higgins, David Gow,
Rae Moar, Maarten Lankhorst, Maxime Ripard, Thomas Zimmermann,
David Airlie, Simona Vetter, Jonathan Corbet, Shuah Khan,
linux-kernel, linux-arch, linux-kselftest, kunit-dev, dri-devel,
workflows, linux-doc, Alessandro Carminati, Guenter Roeck,
Kees Cook, Linux Kernel Functional Testing, Dan Carpenter,
Maíra Canal, Simona Vetter
In-Reply-To: <69f4eb09-efbd-4bd1-81b8-963b78e1a3a3@kernel.org>
On Tue, Mar 17, 2026 at 12:20:26PM +0100, Vlastimil Babka (SUSE) wrote:
> > For this iteration, the `__report_bug()` centralized approach was
> > revisited after the discussion in the previous version [1].
>
> Discussion with PeterZ, who is not CC'd here? (did it now for my reply).
>
> > However, again this approach did not work because:
> > - Some warning output is generated directly in the macros before calling
> > the centralized functions (e.g., `__warn_printk()` in `__WARN_printf()`)
> > - Functions in the warning path like `warn_slowpath_fmt()` are marked
> > `__always_inline`, making it difficult to intercept early enough
> > - So, by the time `__report_bug()` is called, output has already been written
> > to the console, making suppression ineffective
> >
> > Current Proposal: Check Directly in the `WARN()` Macros.
> > This avoids the need for function symbol resolution or ELF section
> > modification.
> > Suppression is implemented directly in the `WARN*()` macros.
>
> So does that bloat every warn/bug site (as Peter objected to) or not?
> And is it compatible with x86? I see you modify include/asm-generic/bug.h
> but x86 has its own version of e.g. __WARN_printf ?
Yeah, they done it all wrong again :-(
This should be pushed inside __report_bug() through __WARN_printf with a
new BUGFLAG thing.
So NAK from me on this -- again!
^ permalink raw reply
* Re: [PATCH v6 0/5] kunit: Add support for suppressing warning backtraces
From: Guenter Roeck @ 2026-03-17 14:55 UTC (permalink / raw)
To: Dan Carpenter, Albert Esteve
Cc: Arnd Bergmann, Brendan Higgins, David Gow, Rae Moar,
Maarten Lankhorst, Maxime Ripard, Thomas Zimmermann, David Airlie,
Simona Vetter, Jonathan Corbet, Shuah Khan, linux-kernel,
linux-arch, linux-kselftest, kunit-dev, dri-devel, workflows,
linux-doc, Alessandro Carminati, Kees Cook,
Linux Kernel Functional Testing, Maíra Canal, Simona Vetter
In-Reply-To: <abkm46TIIBBbuuC_@stanley.mountain>
On 3/17/26 03:03, Dan Carpenter wrote:
> I think this is great to suppress some warnings, and I already ACKed
> this patchset. But we're still going to have some warnings where the
> warning is the whole point of the test.
>
Maybe my memory defeats me, but if I recall correctly the original patch
set counted the skipped warnings. I don't see why a to-be-parsed message
would be necessary or add value over that.
Guenter
> It would be great if marked these somehow:
> 1) At minimum we should mark them so people seeing the warning know it's
> intentional. "Intentional Stack Trace". I've sent at least one patch
> to add that printk before the stack trace but it was ignored. We could
> do this piecemeal.
>
> 2) It would be nice if the print was standardized enough so CI systems
> could automatically filter it out.
>
> regards,
> dan carpenter
>
^ permalink raw reply
* Re: [PATCH v6 0/5] kunit: Add support for suppressing warning backtraces
From: Guenter Roeck @ 2026-03-17 15:02 UTC (permalink / raw)
To: Peter Zijlstra, Vlastimil Babka (SUSE)
Cc: Albert Esteve, Arnd Bergmann, Brendan Higgins, David Gow,
Rae Moar, Maarten Lankhorst, Maxime Ripard, Thomas Zimmermann,
David Airlie, Simona Vetter, Jonathan Corbet, Shuah Khan,
linux-kernel, linux-arch, linux-kselftest, kunit-dev, dri-devel,
workflows, linux-doc, Alessandro Carminati, Kees Cook,
Linux Kernel Functional Testing, Dan Carpenter, Maíra Canal,
Simona Vetter
In-Reply-To: <20260317113025.GG2872@noisy.programming.kicks-ass.net>
On 3/17/26 04:30, Peter Zijlstra wrote:
> On Tue, Mar 17, 2026 at 12:20:26PM +0100, Vlastimil Babka (SUSE) wrote:
>>> For this iteration, the `__report_bug()` centralized approach was
>>> revisited after the discussion in the previous version [1].
>>
>> Discussion with PeterZ, who is not CC'd here? (did it now for my reply).
>>
>>> However, again this approach did not work because:
>>> - Some warning output is generated directly in the macros before calling
>>> the centralized functions (e.g., `__warn_printk()` in `__WARN_printf()`)
>>> - Functions in the warning path like `warn_slowpath_fmt()` are marked
>>> `__always_inline`, making it difficult to intercept early enough
>>> - So, by the time `__report_bug()` is called, output has already been written
>>> to the console, making suppression ineffective
>>>
>>> Current Proposal: Check Directly in the `WARN()` Macros.
>>> This avoids the need for function symbol resolution or ELF section
>>> modification.
>>> Suppression is implemented directly in the `WARN*()` macros.
>>
>> So does that bloat every warn/bug site (as Peter objected to) or not?
>> And is it compatible with x86? I see you modify include/asm-generic/bug.h
>> but x86 has its own version of e.g. __WARN_printf ?
>
> Yeah, they done it all wrong again :-(
>
> This should be pushed inside __report_bug() through __WARN_printf with a
> new BUGFLAG thing.
>
That would require another set of WARN macros, and after (or if) accepted
negotiations with each of the owners of the WARNing code to use the new
macros. Trying to do this would just trigger another set of objections.
Given that, but for other reasons,
> So NAK from me on this -- again!
I agree.
Guenter
^ permalink raw reply
* Re: [PATCH v4 1/4] scripts: ver_linux: expand and fix list
From: Jonathan Corbet @ 2026-03-17 15:02 UTC (permalink / raw)
To: Manuel Ebner, Collin Funk, Shuah Khan
Cc: workflows, linux-doc, linux-kernel, Manuel Ebner
In-Reply-To: <20260311165440.183672-2-manuelebner@airmail.cc>
Manuel Ebner <manuelebner@airmail.cc> writes:
> It is a pain in the ass to compare the software versions on the running
> system (scripts/ver_linux) with the minimal required versions.
> Sorting both lists the same way makes side-by-side comparisons a simple task.
OK, we're getting a lot closer. But the above text has nothing to do
with what this patch does - there is no sorting here. What you are
doing is making the names of the tools consistent and adding those that
are missing; that's what your changelog should say.
> fix path to changes.rst
>
> make toolnames uniform with the toolnames in Changes.rst
> make version commands uniform with Changes.rst
>
> Add missing tools in ver_linux
> bash, bc, bindgen, btrfs-progs, Clang, gdb, GNU awk, GNU tar,
> GRUB, GRUB2, gtags, iptables, kmod, mcelog, mkimage, openssl,
> pahole, Python, Rust, Sphinx, squashfs-tools
>
> Signed-off-by: Manuel Ebner <manuelebner@airmail.cc>
> ---
> scripts/ver_linux | 50 ++++++++++++++++++++++++++++++++++-------------
> 1 file changed, 36 insertions(+), 14 deletions(-)
Otherwise I think the patch is good. If this were the only issue, I
would just apply the patch and fix the changelog myself.
Thanks,
jon
^ permalink raw reply
* Re: [PATCH v4 2/4] workflow: process/changes.rst: expand and cleanup list
From: Jonathan Corbet @ 2026-03-17 15:04 UTC (permalink / raw)
To: Manuel Ebner, Collin Funk, Shuah Khan
Cc: workflows, linux-doc, linux-kernel, Manuel Ebner
In-Reply-To: <20260311165612.184288-2-manuelebner@airmail.cc>
Manuel Ebner <manuelebner@airmail.cc> writes:
> It is a pain in the ass to compare the software versions on the running
> system with the minimal required versions (process/changes.rst).
> Sorting both lists the same way makes side-by-side comparisons a simple task.
Again, this text doesn't belong here - describe *this patch.
> add reference to ./scripts/ver_linux
> needn't -> do not need to
That seems like a pointless change, but whtever
> make toolnames uniform with the toolnames in ver_linux
> make version commands uniform with ver_linux
>
> remove footnote for sphinx
> in the paragraph before the list it says:
> "Also, not all tools are necessary on all systems;
> obviously, if you don't have any PC Card hardware, for example,
> you probably needn't concern yourself with pcmciautils."
>
> remove "(optional)" for the same reason as above
Here you have lost some information - now the document doesn't say
*which* tools are optional. That is, I think, not ideal.
> add gdb version 7.2 as mentioned in:
> Documentation/process/debugging/gdb-kernel-debugging.rst
> scripts/gdb/vmlinux-gdb.py
>
> Signed-off-by: Manuel Ebner <manuelebner@airmail.cc>
> ---
> Documentation/process/changes.rst | 28 ++++++++++++++--------------
> 1 file changed, 14 insertions(+), 14 deletions(-)
Thanks,
jon
^ permalink raw reply
* Re: [PATCH v4 3/4] scripts: ver_linux: sort
From: Jonathan Corbet @ 2026-03-17 15:05 UTC (permalink / raw)
To: Manuel Ebner, Collin Funk, Shuah Khan
Cc: workflows, linux-doc, linux-kernel, Manuel Ebner
In-Reply-To: <20260312002535.191111-2-manuelebner@airmail.cc>
Manuel Ebner <manuelebner@airmail.cc> writes:
> It is a pain in the ass to compare the software versions on the running
> system (scripts/ver_linux) with the minimal required versions.
> Sorting both lists the same way makes side-by-side comparisons a simple task.
>
> sort output alphabetically
Sort the output of *what*? Yes, one can figure it out from reading the
patch, but you shouldn't make readers do that.
> Signed-off-by: Manuel Ebner <manuelebner@airmail.cc>
> ---
> scripts/ver_linux | 64 +++++++++++++++++++++++------------------------
> 1 file changed, 32 insertions(+), 32 deletions(-)
Thanks,
jon
^ permalink raw reply
* Re: [PATCH v4 4/4] workflow: process/changes.rst: sort list
From: Jonathan Corbet @ 2026-03-17 15:05 UTC (permalink / raw)
To: Manuel Ebner, Collin Funk, Shuah Khan
Cc: workflows, linux-doc, linux-kernel, Manuel Ebner
In-Reply-To: <20260312002607.191358-2-manuelebner@airmail.cc>
Manuel Ebner <manuelebner@airmail.cc> writes:
> It is a pain in the ass to compare the software versions on the running
> system (scripts/ver_linux) with the minimal required versions.
> Sorting both lists the same way makes side-by-side comparisons a simple task.
>
> sort output alphabetically
Need I say that providing identical changelogs for two different patches
is a sign that something isn't quite right?
The change itself looks fine.
Thanks,
jon
^ permalink raw reply
* Re: [PATCH v4 0/4] workflow, scripts: sort changes.rst and ver_linux
From: Jonathan Corbet @ 2026-03-17 15:08 UTC (permalink / raw)
To: Manuel Ebner, Collin Funk, Shuah Khan
Cc: workflows, linux-doc, linux-kernel, Manuel Ebner
In-Reply-To: <20260311164935.183495-3-manuelebner@airmail.cc>
Manuel Ebner <manuelebner@airmail.cc> writes:
> It is a pain in the ass to compare the software versions on the running
> system (scripts/ver_linux) with the minimal required versions (changes.rst).
> Sorting both lists the same way makes side-by-side comparisons a simple task.
As noted in the individual patches, we're getting closer, but not quite
there yet.
Also, overall, I am still not thrilled about you having send me patches
under a false name. I need you to, at a bare minimum, acknowledge that
this was a violation of the trust that the kernel project depends on,
and that the current name you are using is the real one.
Thanks,
jon
^ permalink raw reply
* Re: [PATCH 1/9] kernel/api: introduce kernel API specification framework
From: Jonathan Corbet @ 2026-03-17 17:49 UTC (permalink / raw)
To: Sasha Levin, linux-api, linux-kernel
Cc: linux-doc, linux-fsdevel, linux-kbuild, linux-kselftest,
workflows, tools, x86, Thomas Gleixner, Paul E. McKenney,
Greg Kroah-Hartman, 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: <20260313150928.2637368-2-sashal@kernel.org>
Sasha Levin <sashal@kernel.org> writes:
> Add a framework for formally documenting kernel APIs with inline
> specifications. This framework provides:
>
> - Structured API documentation with parameter specifications, return
> values, error conditions, and execution context requirements
> - Runtime validation capabilities for debugging (CONFIG_KAPI_RUNTIME_CHECKS)
> - Export of specifications via debugfs for tooling integration
> - Support for both internal kernel APIs and system calls
So I'll confess I have only scanned over the implementation, but I have
some thoughts on the earlier stuff.
[...]
> diff --git a/Documentation/dev-tools/kernel-api-spec.rst b/Documentation/dev-tools/kernel-api-spec.rst
> new file mode 100644
> index 0000000000000..7c0c1694f1f4a
> --- /dev/null
> +++ b/Documentation/dev-tools/kernel-api-spec.rst
> @@ -0,0 +1,482 @@
> +.. SPDX-License-Identifier: GPL-2.0
> +
> +======================================
> +Kernel API Specification Framework
> +======================================
> +
> +:Author: Sasha Levin <sashal@kernel.org>
> +:Date: June 2025
Has it not changed since then?
> +.. contents:: Table of Contents
> + :depth: 3
> + :local:
> +
> +Introduction
> +============
[...]
> +Usage Guide
> +===========
> +
> +Basic API Specification
> +-----------------------
> +
> +API specifications are written as KAPI-annotated kerneldoc comments directly in
> +the source file, immediately preceding the function implementation. The ``kapi``
> +tool extracts these annotations to produce structured specifications.
> +
> +.. code-block:: c
> +
> + /**
> + * kmalloc - allocate kernel memory
> + * @size: Number of bytes to allocate
> + * @flags: Allocation flags (GFP_*)
Given that the text thus far has talked about user-space API validation,
it's a bit surprising to see an internal function used as an example.
Also, maybe it should be kmalloc_obj()? <runs away>
> + * context-flags: KAPI_CTX_PROCESS | KAPI_CTX_SOFTIRQ | KAPI_CTX_HARDIRQ
> + * param-count: 2
param-count is two, but you only document one of them?
> + * param: size
> + * type: KAPI_TYPE_UINT
> + * flags: KAPI_PARAM_IN
> + * constraint-type: KAPI_CONSTRAINT_RANGE
> + * range: 0, KMALLOC_MAX_SIZE
> + *
> + * error: ENOMEM, Out of memory
> + * desc: Insufficient memory available for the requested allocation.
> + */
Honest question: can this be made a bit easier for people to create,
with less shift-key wear? My biggest worry with a system like this is
that people won't take the time to create and maintain the entries, so
anything that would ease the task would help. Is there an impediment to
something like:
contexts: process, softirq, hardirq
param: size
type: uint, input
constraint: range(0, KMALLOC_MAX_SIZE)
See what I'm getting at? ISTM that your DSL could be made a bit less
verbose and shouty while being just as well defined, but perhaps I'm
missing something?
Even better, of course, would be to add a "description" field for each
parameter, and allow that rather than the @param description that
kerneldoc currently uses. That would keep all the information together,
at the minor cost of adding another significant complication to the
kernel-doc script. Mauro won't mind :)
> + void *kmalloc(size_t size, gfp_t flags)
> + {
> + /* Implementation */
> + }
> +
> +Alternatively, specifications can be defined using the ``DEFINE_KERNEL_API_SPEC``
> +macro for compiled-in specs that are stored in the ``.kapi_specs`` ELF section:
> +
> +.. code-block:: c
> +
> + #include <linux/kernel_api_spec.h>
> +
> + DEFINE_KERNEL_API_SPEC(sys_open)
> + KAPI_DESCRIPTION("Open or create a file")
> + KAPI_CONTEXT(KAPI_CTX_PROCESS | KAPI_CTX_SLEEPABLE)
> + /* ... parameter, error, constraint definitions ... */
> + KAPI_END_SPEC
So the reason for two completely separate mechanisms is not entirely
clear to me. The kerneldoc variant is essentially documentation, while
the macro stuff is to be built into the executable? What if you want
both?
It would be nice to only have one way if at all possible; I'm sure that
crossed your mind at some point :) If there have to be two, having both
examples describe the same function would make the parallels more clear.
> +System Call Specification
> +-------------------------
> +
> +System calls are documented inline in the implementation file (e.g., ``fs/open.c``)
> +using KAPI-annotated kerneldoc comments. When ``CONFIG_KAPI_RUNTIME_CHECKS`` is
> +enabled, the ``SYSCALL_DEFINEx`` macros automatically look up the specification
> +and validate parameters before and after the syscall executes.
> +
> +IOCTL Specification
> +-------------------
> +
> +IOCTLs use the same annotation approach with additional structure field
> +specifications
This might be a really good place for an example
[...]
> +Usage Examples
> +--------------
> +
> +Query specific API::
> +
> + $ cat /sys/kernel/debug/kapi/apis/kmalloc/specification
> + API: kmalloc
> + Version: 3.0
> + Description: Allocate kernel memory
> +
> + Parameters:
> + [0] size (size_t, in): Number of bytes to allocate
> + Range: 0 - 4194304
> + [1] flags (flags, in): Allocation flags (GFP_*)
> + Mask: 0x1ffffff
Ah, you do document that second parameter somewhere :)
> + Returns: pointer - Pointer to allocated memory or NULL
> +
> + Errors:
> + ENOMEM: Out of memory
> +
> + Context: process, softirq, hardirq
> +
> + Side Effects:
> + - Allocates memory from kernel heap
That part wasn't in your example
> +Export all specifications::
> +
> + $ cat /sys/kernel/debug/kapi/export/all.json > kernel-apis.json
> +
> +Enable validation for specific API::
> +
> + $ echo 1 > /sys/kernel/debug/kapi/apis/kmalloc/validate
> +
> +Performance Considerations
> +==========================
> +
> +Memory Overhead
> +---------------
> +
> +Each API specification consumes approximately 400-450KB of memory due to the
> +fixed-size arrays in ``struct kernel_api_spec``. With the current 4 syscall
> +specifications, total memory usage is approximately 1.7MB. Consider:
Ouch.
> +Documentation Generation
> +------------------------
> +
> +The framework exports specifications via debugfs that can be used
> +to generate documentation. Tools for automatic documentation generation
> +from specifications are planned for future development.
Documentation always comes last :)
Interesting stuff.
jon
^ permalink raw reply
* Re: [PATCH 5/9] kernel/api: add API specification for sys_open
From: Jonathan Corbet @ 2026-03-17 18:37 UTC (permalink / raw)
To: Sasha Levin, Greg Kroah-Hartman
Cc: linux-api, linux-kernel, linux-doc, linux-fsdevel, linux-kbuild,
linux-kselftest, workflows, tools, x86, Thomas Gleixner,
Paul E. McKenney, 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: <abQ-iIylzpuqlRv3@laps>
Sasha Levin <sashal@kernel.org> writes:
> On Fri, Mar 13, 2026 at 04:33:57PM +0100, Greg Kroah-Hartman wrote:
>>On Fri, Mar 13, 2026 at 11:09:15AM -0400, Sasha Levin wrote:
>>> + * since-version: 1.0
>>
>>I think since older versions :)
>
> Right. I guess that in my mind 1.0 was the first official "release". I'll
> update it to 0.01.
That kind of raises the question of just what since-version means. The
version-0.01 (or 1.0) version of open() surely didn't do everything
described in this specification. So it's saying that some version of
the system call has existed since then?
Thanks,
jon
^ permalink raw reply
* Re: [PATCH 1/9] kernel/api: introduce kernel API specification framework
From: Mauro Carvalho Chehab @ 2026-03-18 6:00 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Sasha Levin, linux-api, linux-kernel, linux-doc, linux-fsdevel,
linux-kbuild, linux-kselftest, workflows, tools, x86,
Thomas Gleixner, Paul E. McKenney, Greg Kroah-Hartman,
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: <87h5qe9wig.fsf@trenco.lwn.net>
On Tue, 17 Mar 2026 11:49:27 -0600
Jonathan Corbet <corbet@lwn.net> wrote:
> Sasha Levin <sashal@kernel.org> writes:
>
> > Add a framework for formally documenting kernel APIs with inline
> > specifications. This framework provides:
> >
> > - Structured API documentation with parameter specifications, return
> > values, error conditions, and execution context requirements
> > - Runtime validation capabilities for debugging (CONFIG_KAPI_RUNTIME_CHECKS)
> > - Export of specifications via debugfs for tooling integration
> > - Support for both internal kernel APIs and system calls
>
> So I'll confess I have only scanned over the implementation, but I have
> some thoughts on the earlier stuff.
>
> [...]
>
> > diff --git a/Documentation/dev-tools/kernel-api-spec.rst b/Documentation/dev-tools/kernel-api-spec.rst
> > new file mode 100644
> > index 0000000000000..7c0c1694f1f4a
> > --- /dev/null
> > +++ b/Documentation/dev-tools/kernel-api-spec.rst
> > @@ -0,0 +1,482 @@
> > +.. SPDX-License-Identifier: GPL-2.0
> > +
> > +======================================
> > +Kernel API Specification Framework
> > +======================================
> > +
> > +:Author: Sasha Levin <sashal@kernel.org>
> > +:Date: June 2025
>
> Has it not changed since then?
>
> > +.. contents:: Table of Contents
> > + :depth: 3
> > + :local:
> > +
> > +Introduction
> > +============
>
> [...]
>
> > +Usage Guide
> > +===========
> > +
> > +Basic API Specification
> > +-----------------------
> > +
> > +API specifications are written as KAPI-annotated kerneldoc comments directly in
> > +the source file, immediately preceding the function implementation. The ``kapi``
> > +tool extracts these annotations to produce structured specifications.
> > +
> > +.. code-block:: c
> > +
> > + /**
> > + * kmalloc - allocate kernel memory
> > + * @size: Number of bytes to allocate
> > + * @flags: Allocation flags (GFP_*)
>
> Given that the text thus far has talked about user-space API validation,
> it's a bit surprising to see an internal function used as an example.
>
> Also, maybe it should be kmalloc_obj()? <runs away>
>
> > + * context-flags: KAPI_CTX_PROCESS | KAPI_CTX_SOFTIRQ | KAPI_CTX_HARDIRQ
> > + * param-count: 2
>
> param-count is two, but you only document one of them?
>
> > + * param: size
> > + * type: KAPI_TYPE_UINT
> > + * flags: KAPI_PARAM_IN
> > + * constraint-type: KAPI_CONSTRAINT_RANGE
> > + * range: 0, KMALLOC_MAX_SIZE
> > + *
> > + * error: ENOMEM, Out of memory
> > + * desc: Insufficient memory available for the requested allocation.
> > + */
>
> Honest question: can this be made a bit easier for people to create,
> with less shift-key wear? My biggest worry with a system like this is
> that people won't take the time to create and maintain the entries, so
> anything that would ease the task would help. Is there an impediment to
> something like:
>
> contexts: process, softirq, hardirq
>
> param: size
> type: uint, input
> constraint: range(0, KMALLOC_MAX_SIZE)
>
> See what I'm getting at? ISTM that your DSL could be made a bit less
> verbose and shouty while being just as well defined, but perhaps I'm
> missing something?
>
> Even better, of course, would be to add a "description" field for each
> parameter, and allow that rather than the @param description that
> kerneldoc currently uses. That would keep all the information together,
> at the minor cost of adding another significant complication to the
> kernel-doc script. Mauro won't mind :)
No, I won't ;-)
It sounds a lot better to use kernel-doc also for kAPI than to have an
independent tool.
It is also very confusing if we end with a kernel-doc-like format
that it is not parsed by kernel-doc.
>
> > + void *kmalloc(size_t size, gfp_t flags)
> > + {
> > + /* Implementation */
> > + }
> > +
> > +Alternatively, specifications can be defined using the ``DEFINE_KERNEL_API_SPEC``
> > +macro for compiled-in specs that are stored in the ``.kapi_specs`` ELF section:
> > +
> > +.. code-block:: c
> > +
> > + #include <linux/kernel_api_spec.h>
> > +
> > + DEFINE_KERNEL_API_SPEC(sys_open)
> > + KAPI_DESCRIPTION("Open or create a file")
> > + KAPI_CONTEXT(KAPI_CTX_PROCESS | KAPI_CTX_SLEEPABLE)
> > + /* ... parameter, error, constraint definitions ... */
> > + KAPI_END_SPEC
>
> So the reason for two completely separate mechanisms is not entirely
> clear to me. The kerneldoc variant is essentially documentation, while
> the macro stuff is to be built into the executable? What if you want
> both?
You can easily add support at kernel-doc to output such macros.
All you need is to create a new class derived from OutputFormat and
make it produce any different output format, including:
#include <linux/kernel_api_spec.h>
DEFINE_KERNEL_API_SPEC(sys_open)
KAPI_DESCRIPTION("Open or create a file")
KAPI_CONTEXT(KAPI_CTX_PROCESS | KAPI_CTX_SLEEPABLE)
/* ... parameter, error, constraint definitions ... */
KAPI_END_SPEC
I'd say that converting from such output to `.kapi_specs`` ELF section
itself and/or to sysfs/debugfs - e.g. something that would require to
compile or be linked with Kernel's compiled binaries should be done by a
separate tool, but we should aim to have a singe tool to process
kernel documentation markups.
It is hard enough to maintain just one tool - and to have people actually
writing documentation. Having a second one to handle it, with a different
format will likely increase a lot the documentation burden.
> It would be nice to only have one way if at all possible; I'm sure that
> crossed your mind at some point :) If there have to be two, having both
> examples describe the same function would make the parallels more clear.
>
> > +System Call Specification
> > +-------------------------
> > +
> > +System calls are documented inline in the implementation file (e.g., ``fs/open.c``)
> > +using KAPI-annotated kerneldoc comments. When ``CONFIG_KAPI_RUNTIME_CHECKS`` is
> > +enabled, the ``SYSCALL_DEFINEx`` macros automatically look up the specification
> > +and validate parameters before and after the syscall executes.
> > +
> > +IOCTL Specification
> > +-------------------
> > +
> > +IOCTLs use the same annotation approach with additional structure field
> > +specifications
>
> This might be a really good place for an example
>
> [...]
>
> > +Usage Examples
> > +--------------
> > +
> > +Query specific API::
> > +
> > + $ cat /sys/kernel/debug/kapi/apis/kmalloc/specification
> > + API: kmalloc
> > + Version: 3.0
> > + Description: Allocate kernel memory
> > +
> > + Parameters:
> > + [0] size (size_t, in): Number of bytes to allocate
> > + Range: 0 - 4194304
> > + [1] flags (flags, in): Allocation flags (GFP_*)
> > + Mask: 0x1ffffff
>
> Ah, you do document that second parameter somewhere :)
>
> > + Returns: pointer - Pointer to allocated memory or NULL
> > +
> > + Errors:
> > + ENOMEM: Out of memory
> > +
> > + Context: process, softirq, hardirq
> > +
> > + Side Effects:
> > + - Allocates memory from kernel heap
>
> That part wasn't in your example
>
> > +Export all specifications::
> > +
> > + $ cat /sys/kernel/debug/kapi/export/all.json > kernel-apis.json
> > +
> > +Enable validation for specific API::
> > +
> > + $ echo 1 > /sys/kernel/debug/kapi/apis/kmalloc/validate
> > +
> > +Performance Considerations
> > +==========================
> > +
> > +Memory Overhead
> > +---------------
> > +
> > +Each API specification consumes approximately 400-450KB of memory due to the
> > +fixed-size arrays in ``struct kernel_api_spec``. With the current 4 syscall
> > +specifications, total memory usage is approximately 1.7MB. Consider:
>
> Ouch.
>
> > +Documentation Generation
> > +------------------------
> > +
> > +The framework exports specifications via debugfs that can be used
> > +to generate documentation. Tools for automatic documentation generation
> > +from specifications are planned for future development.
>
> Documentation always comes last :)
>
> Interesting stuff.
>
> jon
Thanks,
Mauro
^ permalink raw reply
* Re: [PATCH 0/9] Kernel API Specification Framework
From: Mauro Carvalho Chehab @ 2026-03-18 6:24 UTC (permalink / raw)
To: Sasha Levin
Cc: Jakub Kicinski, 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: <abZTg9ZwnE5J4qXa@laps>
On Sun, 15 Mar 2026 02:36:51 -0400
Sasha Levin <sashal@kernel.org> wrote:
> On Sat, Mar 14, 2026 at 11:18:22AM -0700, Jakub Kicinski wrote:
> >On Fri, 13 Mar 2026 11:09:10 -0400 Sasha Levin wrote:
> >> This enables static analysis tools to verify userspace API usage at compile
> >> time, test generation based on formal specifications, consistent error handling
> >> validation, automated documentation generation, and formal verification of
> >> kernel interfaces.
> >
> >Could you give some examples? We have machine readable descriptions for
> >Netlink interfaces, we approached syzbot folks and they did not really
> >seem to care for those.
>
> Once the API is in a machine-readable format, we can write formatters to
> output whatever downstream tools need.
Kernel-doc already does that. The way it works is that it handles
kernel-doc markups on two steps:
- first step: parse kernel-doc markups, function prototypes and data
types for variables, typedefs, structs, unions, enums.
This is done inside tools/lib/python/kdoc/kdoc_parser.py.
The documentation is stored in memory as a list of documentation
entries. Each element there belongs to class KdocItem.
It is trivial to output its content in JSON or YAML format. I
submitted a path series a while ago doing exactly that, aiming to help
writing unittests for first step:
https://lore.kernel.org/linux-doc/7648cb5f5a1b501d9ae9a57b4d8dbeb7273d9097.1770128540.git.mchehab+huawei@kernel.org/
I'm planing to rebase such patch series on the top of my latest
kernel-doc patch series.
- second step: output generation. There is an abstract class named
OutputFormat which contains the following output methods:
def out_doc(self, fname, name, args):
"""Outputs a DOC block."""
def out_function(self, fname, name, args):
"""Outputs a function."""
def out_enum(self, fname, name, args):
"""Outputs an enum."""
def out_var(self, fname, name, args):
"""Outputs a variable."""
def out_typedef(self, fname, name, args):
"""Outputs a typedef."""
def out_struct(self, fname, name, args):
"""Outputs a struct."""
Producing a different output is as easy as doing:
class MyFormat(OutputFormat):
...
def out_var(self, fname, name, args):
self.data =+ f"whatever {name}"
...
Thanks,
Mauro
^ permalink raw reply
* Re: [PATCH v6 0/5] kunit: Add support for suppressing warning backtraces
From: Albert Esteve @ 2026-03-18 9:25 UTC (permalink / raw)
To: Peter Zijlstra
Cc: Vlastimil Babka (SUSE), Arnd Bergmann, Brendan Higgins, David Gow,
Rae Moar, Maarten Lankhorst, Maxime Ripard, Thomas Zimmermann,
David Airlie, Simona Vetter, Jonathan Corbet, Shuah Khan,
linux-kernel, linux-arch, linux-kselftest, kunit-dev, dri-devel,
workflows, linux-doc, Alessandro Carminati, Guenter Roeck,
Kees Cook, Linux Kernel Functional Testing, Dan Carpenter,
Maíra Canal, Simona Vetter
In-Reply-To: <20260317113025.GG2872@noisy.programming.kicks-ass.net>
Hi Peter,
On Tue, Mar 17, 2026 at 12:33 PM Peter Zijlstra <peterz@infradead.org> wrote:
>
> On Tue, Mar 17, 2026 at 12:20:26PM +0100, Vlastimil Babka (SUSE) wrote:
> > > For this iteration, the `__report_bug()` centralized approach was
> > > revisited after the discussion in the previous version [1].
> >
> > Discussion with PeterZ, who is not CC'd here? (did it now for my reply).
(Sorry not to put you on CC, I thought auto-cc would pick you up already)
> >
> > > However, again this approach did not work because:
> > > - Some warning output is generated directly in the macros before calling
> > > the centralized functions (e.g., `__warn_printk()` in `__WARN_printf()`)
> > > - Functions in the warning path like `warn_slowpath_fmt()` are marked
> > > `__always_inline`, making it difficult to intercept early enough
> > > - So, by the time `__report_bug()` is called, output has already been written
> > > to the console, making suppression ineffective
> > >
> > > Current Proposal: Check Directly in the `WARN()` Macros.
> > > This avoids the need for function symbol resolution or ELF section
> > > modification.
> > > Suppression is implemented directly in the `WARN*()` macros.
> >
> > So does that bloat every warn/bug site (as Peter objected to) or not?
> > And is it compatible with x86? I see you modify include/asm-generic/bug.h
> > but x86 has its own version of e.g. __WARN_printf ?
>
> Yeah, they done it all wrong again :-(
>
> This should be pushed inside __report_bug() through __WARN_printf with a
> new BUGFLAG thing.
Thanks for the specific suggestion to use BUGFLAG, but I do not think
this is what we need. These flags seem to be used statically, but the
goal is to enable and disable these warning suppressions dynamically
in the tests. Happy to be corrected if I missed something.
I want to highlight that I did not bluntly ignore your point in the
last version. I thoroughly read the discussions there, and as I
mentioned in the cover letter, I tried to move away from the per-macro
approach. However, while doing that, I encountered the same issues
Alessandro found in the last iteration. I’ll address that below, but I
decided to give this approach one more try and tackle the raised
drawbacks.
The main concern was the increased size of the code emitted by the
WARN*() macros, which was a fair point. I tried to alleviate this with
a static key and branching, and addressed other concerns by using RCU
protection on the list for thread safety. I think it was worth a try,
as all options seemed to have their own tradeoffs. However, if this
option remains unacceptable even after trying to diminish its
drawbacks, I am happy to focus on finding the best solution for the
centralised approach, and keeping the discussion constructive.
So back to my test on this. Alessandro detailed two strategies in the
last version, one of them (storing the function name in `struct
bug_entry`) was already used and discarded in older iterations of this
series. So let's focus on the other strategy, using 'kallsyms`. Let's
assume we still store the function name when registering a new symbol
to suppress. Otherwise, we might need to check address ranges to
ensure bugaddr is within the function's scope, which sounds trickier?
With `kallsyms` we can infer the originating functionid. But this
approach works unreliably with compiler-induced transformations (e.g.,
inlining, cloning, code fragmentation). And we still cannot prevent
all output. Additionally, we would need to prevent prints in
`warn_slowpath_fmt()`. There may be other `printk`s embedded in the
macros, but let's focus on suppressing all warnings as a best effort.
It would already improve the quality of life for testers.
Considering these remaining issues, I managed to create a centralised
proposal. Please find the main changes at the bottom of this message.
But again, even with these, the solution remains unreliable. We can
mitigate this by registering the test name on the suppression list (at
least, I can make the new test in this series pass with that). Not
ideal, but we could mention it in the documentation. Something like
"Suppression is matched by the function where the warning is reported.
If the warning is triggered from a helper (or the compiler inlines it
into the test), that function name may differ. In that case, register
and start suppression for both the test and the helper so the test
passes regardless of inlining."
Would that be a more acceptable solution? Is there a better option I
am not seeing?
BR,
Albert.
diff --git a/kernel/panic.c b/kernel/panic.c
index c78600212b6c1..3cb004a7803f4 100644
--- a/kernel/panic.c
+++ b/kernel/panic.c
@@ -39,6 +39,7 @@
#include <linux/sys_info.h>
#include <trace/events/error_report.h>
#include <asm/sections.h>
+#include <kunit/bug.h>
#define PANIC_TIMER_STEP 100
#define PANIC_BLINK_SPD 18
@@ -1080,9 +1081,14 @@ void __warn(const char *file, int line, void
*caller, unsigned taint,
void warn_slowpath_fmt(const char *file, int line, unsigned taint,
const char *fmt, ...)
{
- bool rcu = warn_rcu_enter();
+ bool rcu;
struct warn_args args;
+ if (__kunit_is_suppressed_warning_at((unsigned
long)__builtin_return_address(0)))
+ return;
+
+ rcu = warn_rcu_enter();
+
pr_warn(CUT_HERE);
if (!fmt) {
diff --git a/lib/bug.c b/lib/bug.c
index 623c467a8b76c..e90b038d9225e 100644
--- a/lib/bug.c
+++ b/lib/bug.c
@@ -48,6 +48,7 @@
#include <linux/rculist.h>
#include <linux/ftrace.h>
#include <linux/context_tracking.h>
+#include <kunit/bug.h>
extern struct bug_entry __start___bug_table[], __stop___bug_table[];
@@ -223,6 +224,9 @@ static enum bug_trap_type __report_bug(struct
bug_entry *bug, unsigned long buga
no_cut = bug->flags & BUGFLAG_NO_CUT_HERE;
has_args = bug->flags & BUGFLAG_ARGS;
+ if (warning && __kunit_is_suppressed_warning_at(bugaddr))
+ return BUG_TRAP_TYPE_WARN;
+
if (warning && once) {
if (done)
return BUG_TRAP_TYPE_WARN;
diff --git a/lib/kunit/bug.c b/lib/kunit/bug.c
index 9c2c4ee013d92..13ffddb044636 100644
--- a/lib/kunit/bug.c
+++ b/lib/kunit/bug.c
@@ -11,6 +11,7 @@
#include <linux/export.h>
#include <linux/instrumentation.h>
#include <linux/jump_label.h>
+#include <linux/kallsyms.h>
#include <linux/rculist.h>
#include <linux/string.h>
@@ -68,4 +69,16 @@ noinstr bool __kunit_is_suppressed_warning(const
char *function)
}
EXPORT_SYMBOL_GPL(__kunit_is_suppressed_warning);
+bool __kunit_is_suppressed_warning_at(unsigned long addr)
+{
+ char buf[KSYM_SYMBOL_LEN];
+
+ if (!static_branch_unlikely(&kunit_suppress_warnings_key))
+ return false;
+ if (sprint_symbol_no_offset(buf, addr) <= 0)
+ return false;
+ return __kunit_check_suppress(buf);
+}
+EXPORT_SYMBOL_GPL(__kunit_is_suppressed_warning_at);
+
#endif /* CONFIG_KUNIT_SUPPRESS_BACKTRACE */
>
> So NAK from me on this -- again!
>
^ permalink raw reply related
* Re: [PATCH v6 0/5] kunit: Add support for suppressing warning backtraces
From: Peter Zijlstra @ 2026-03-18 11:51 UTC (permalink / raw)
To: Albert Esteve
Cc: Vlastimil Babka (SUSE), Arnd Bergmann, Brendan Higgins, David Gow,
Rae Moar, Maarten Lankhorst, Maxime Ripard, Thomas Zimmermann,
David Airlie, Simona Vetter, Jonathan Corbet, Shuah Khan,
linux-kernel, linux-arch, linux-kselftest, kunit-dev, dri-devel,
workflows, linux-doc, Alessandro Carminati, Guenter Roeck,
Kees Cook, Linux Kernel Functional Testing, Dan Carpenter,
Maíra Canal, Simona Vetter
In-Reply-To: <CADSE00Jy=G7HhRkb7vmFSuGFmvpGGt1TQ2NA+7XGLZ4b=g3rxQ@mail.gmail.com>
On Wed, Mar 18, 2026 at 10:25:00AM +0100, Albert Esteve wrote:
> So back to my test on this. Alessandro detailed two strategies in the
> last version, one of them (storing the function name in `struct
> bug_entry`) was already used and discarded in older iterations of this
> series. So let's focus on the other strategy, using 'kallsyms`. Let's
> assume we still store the function name when registering a new symbol
> to suppress. Otherwise, we might need to check address ranges to
> ensure bugaddr is within the function's scope, which sounds trickier?
> With `kallsyms` we can infer the originating functionid. But this
> approach works unreliably with compiler-induced transformations (e.g.,
> inlining, cloning, code fragmentation). And we still cannot prevent
> all output.
> Additionally, we would need to prevent prints in
> `warn_slowpath_fmt()`. There may be other `printk`s embedded in the
> macros, but let's focus on suppressing all warnings as a best effort.
> It would already improve the quality of life for testers.
warn_slowpath_fmt() should be completely unused on x86, s390 and
possibly others. But sure.
> Considering these remaining issues, I managed to create a centralised
> proposal. Please find the main changes at the bottom of this message.
>
> But again, even with these, the solution remains unreliable. We can
> mitigate this by registering the test name on the suppression list (at
> least, I can make the new test in this series pass with that). Not
> ideal, but we could mention it in the documentation. Something like
> "Suppression is matched by the function where the warning is reported.
> If the warning is triggered from a helper (or the compiler inlines it
> into the test), that function name may differ. In that case, register
> and start suppression for both the test and the helper so the test
> passes regardless of inlining."
>
> Would that be a more acceptable solution? Is there a better option I
> am not seeing?
Yes, definitely. This is the sort of thing I was aiming for.
Other option would be the __FILE__ and __LINE__ data, you can match
uniquely against that and not worry about the compiler transforms.
Perhaps less user friendly as a function identifier, but meh, this isn't
aimed at users anyway, but kernel devs.
The kunit userspace could even scrape the __FILE__ and __LINE__ from the
kernel it was compiled against if it so wants. It should be simple
enough to write a tool that takes the source and a function name and
outputs the relevant __FILE__ and __LINE__ thingies. All you need is a
very rudimentary C parser and we've got a ton of those around.
> diff --git a/kernel/panic.c b/kernel/panic.c
> index c78600212b6c1..3cb004a7803f4 100644
> --- a/kernel/panic.c
> +++ b/kernel/panic.c
> @@ -39,6 +39,7 @@
> #include <linux/sys_info.h>
> #include <trace/events/error_report.h>
> #include <asm/sections.h>
> +#include <kunit/bug.h>
>
> #define PANIC_TIMER_STEP 100
> #define PANIC_BLINK_SPD 18
> @@ -1080,9 +1081,14 @@ void __warn(const char *file, int line, void
> *caller, unsigned taint,
> void warn_slowpath_fmt(const char *file, int line, unsigned taint,
> const char *fmt, ...)
> {
> - bool rcu = warn_rcu_enter();
> + bool rcu;
> struct warn_args args;
>
> + if (__kunit_is_suppressed_warning_at((unsigned long)__builtin_return_address(0)))
> + return;
> +
> + rcu = warn_rcu_enter();
> +
> pr_warn(CUT_HERE);
>
> if (!fmt) {
>
> diff --git a/lib/bug.c b/lib/bug.c
> index 623c467a8b76c..e90b038d9225e 100644
> --- a/lib/bug.c
> +++ b/lib/bug.c
> @@ -48,6 +48,7 @@
> #include <linux/rculist.h>
> #include <linux/ftrace.h>
> #include <linux/context_tracking.h>
> +#include <kunit/bug.h>
>
> extern struct bug_entry __start___bug_table[], __stop___bug_table[];
>
> @@ -223,6 +224,9 @@ static enum bug_trap_type __report_bug(struct
> bug_entry *bug, unsigned long buga
> no_cut = bug->flags & BUGFLAG_NO_CUT_HERE;
> has_args = bug->flags & BUGFLAG_ARGS;
>
> + if (warning && __kunit_is_suppressed_warning_at(bugaddr))
> + return BUG_TRAP_TYPE_WARN;
> +
I suppose there's a question here if a suppressed warn counts towards
the once logic below.
> if (warning && once) {
> if (done)
> return BUG_TRAP_TYPE_WARN;
>
> diff --git a/lib/kunit/bug.c b/lib/kunit/bug.c
> index 9c2c4ee013d92..13ffddb044636 100644
> --- a/lib/kunit/bug.c
> +++ b/lib/kunit/bug.c
> @@ -11,6 +11,7 @@
> #include <linux/export.h>
> #include <linux/instrumentation.h>
> #include <linux/jump_label.h>
> +#include <linux/kallsyms.h>
> #include <linux/rculist.h>
> #include <linux/string.h>
>
> @@ -68,4 +69,16 @@ noinstr bool __kunit_is_suppressed_warning(const
> char *function)
> }
> EXPORT_SYMBOL_GPL(__kunit_is_suppressed_warning);
>
> +bool __kunit_is_suppressed_warning_at(unsigned long addr)
> +{
> + char buf[KSYM_SYMBOL_LEN];
> +
> + if (!static_branch_unlikely(&kunit_suppress_warnings_key))
> + return false;
At this point you don't need this to be a static_branch either, both
callers are already in warn slowpaths and nobody cares.
> + if (sprint_symbol_no_offset(buf, addr) <= 0)
> + return false;
> + return __kunit_check_suppress(buf);
> +}
> +EXPORT_SYMBOL_GPL(__kunit_is_suppressed_warning_at);
I don't think you need this export, both callers are definitely
in-kernel.
^ permalink raw reply
* Re: [PATCH 5/9] kernel/api: add API specification for sys_open
From: Sasha Levin @ 2026-03-18 14:12 UTC (permalink / raw)
To: Jonathan Corbet
Cc: Greg Kroah-Hartman, linux-api, linux-kernel, linux-doc,
linux-fsdevel, linux-kbuild, linux-kselftest, workflows, tools,
x86, Thomas Gleixner, Paul E. McKenney, 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: <878qbq9uau.fsf@trenco.lwn.net>
On Tue, Mar 17, 2026 at 12:37:13PM -0600, Jonathan Corbet wrote:
>Sasha Levin <sashal@kernel.org> writes:
>
>> On Fri, Mar 13, 2026 at 04:33:57PM +0100, Greg Kroah-Hartman wrote:
>>>On Fri, Mar 13, 2026 at 11:09:15AM -0400, Sasha Levin wrote:
>
>>>> + * since-version: 1.0
>>>
>>>I think since older versions :)
>>
>> Right. I guess that in my mind 1.0 was the first official "release". I'll
>> update it to 0.01.
>
>That kind of raises the question of just what since-version means. The
>version-0.01 (or 1.0) version of open() surely didn't do everything
>described in this specification. So it's saying that some version of
>the system call has existed since then?
You know, I'm not entierly sure what the definition should be here.
I stole this from man pages where they indicate at which version the API was
introduced in. I'm not sure if it really adds any value.
Any objections to just dropping it?
--
Thanks,
Sasha
^ permalink raw reply
* Re: [PATCH 0/9] Kernel API Specification Framework
From: Sasha Levin @ 2026-03-18 14:14 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Jakub Kicinski, 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: <20260318072410.72618011@foz.lan>
On Wed, Mar 18, 2026 at 07:24:10AM +0100, Mauro Carvalho Chehab wrote:
>On Sun, 15 Mar 2026 02:36:51 -0400
>Sasha Levin <sashal@kernel.org> wrote:
>
>> On Sat, Mar 14, 2026 at 11:18:22AM -0700, Jakub Kicinski wrote:
>> >On Fri, 13 Mar 2026 11:09:10 -0400 Sasha Levin wrote:
>> >> This enables static analysis tools to verify userspace API usage at compile
>> >> time, test generation based on formal specifications, consistent error handling
>> >> validation, automated documentation generation, and formal verification of
>> >> kernel interfaces.
>> >
>> >Could you give some examples? We have machine readable descriptions for
>> >Netlink interfaces, we approached syzbot folks and they did not really
>> >seem to care for those.
>>
>> Once the API is in a machine-readable format, we can write formatters to
>> output whatever downstream tools need.
>
>Kernel-doc already does that. The way it works is that it handles
>kernel-doc markups on two steps:
Cool, I'll take a look. We could throw away the source parser in the kapi tool
and just use the kerneldoc parse.
--
Thanks,
Sasha
^ permalink raw reply
* Re: [PATCH 5/9] kernel/api: add API specification for sys_open
From: Jonathan Corbet @ 2026-03-18 14:16 UTC (permalink / raw)
To: Sasha Levin
Cc: Greg Kroah-Hartman, linux-api, linux-kernel, linux-doc,
linux-fsdevel, linux-kbuild, linux-kselftest, workflows, tools,
x86, Thomas Gleixner, Paul E. McKenney, 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: <abqyv0DiT0LFUU4v@laps>
Sasha Levin <sashal@kernel.org> writes:
> On Tue, Mar 17, 2026 at 12:37:13PM -0600, Jonathan Corbet wrote:
>>Sasha Levin <sashal@kernel.org> writes:
>>
>>> On Fri, Mar 13, 2026 at 04:33:57PM +0100, Greg Kroah-Hartman wrote:
>>>>On Fri, Mar 13, 2026 at 11:09:15AM -0400, Sasha Levin wrote:
>>
>>>>> + * since-version: 1.0
>>>>
>>>>I think since older versions :)
>>>
>>> Right. I guess that in my mind 1.0 was the first official "release". I'll
>>> update it to 0.01.
>>
>>That kind of raises the question of just what since-version means. The
>>version-0.01 (or 1.0) version of open() surely didn't do everything
>>described in this specification. So it's saying that some version of
>>the system call has existed since then?
>
> You know, I'm not entierly sure what the definition should be here.
>
> I stole this from man pages where they indicate at which version the API was
> introduced in. I'm not sure if it really adds any value.
>
> Any objections to just dropping it?
Not here. My general objective with the docs is to describe the kernel
as it is now, without that sort of history unless there's something
specific it can tell current users.
Thanks,
jon
^ permalink raw reply
* Re: [PATCH 1/9] kernel/api: introduce kernel API specification framework
From: Sasha Levin @ 2026-03-18 14:30 UTC (permalink / raw)
To: Jonathan Corbet
Cc: linux-api, linux-kernel, linux-doc, linux-fsdevel, linux-kbuild,
linux-kselftest, workflows, tools, x86, Thomas Gleixner,
Paul E. McKenney, Greg Kroah-Hartman, 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: <87h5qe9wig.fsf@trenco.lwn.net>
On Tue, Mar 17, 2026 at 11:49:27AM -0600, Jonathan Corbet wrote:
>Sasha Levin <sashal@kernel.org> writes:
>
>> Add a framework for formally documenting kernel APIs with inline
>> specifications. This framework provides:
>>
>> - Structured API documentation with parameter specifications, return
>> values, error conditions, and execution context requirements
>> - Runtime validation capabilities for debugging (CONFIG_KAPI_RUNTIME_CHECKS)
>> - Export of specifications via debugfs for tooling integration
>> - Support for both internal kernel APIs and system calls
>
>So I'll confess I have only scanned over the implementation, but I have
>some thoughts on the earlier stuff.
>
>[...]
>
>> diff --git a/Documentation/dev-tools/kernel-api-spec.rst b/Documentation/dev-tools/kernel-api-spec.rst
>> new file mode 100644
>> index 0000000000000..7c0c1694f1f4a
>> --- /dev/null
>> +++ b/Documentation/dev-tools/kernel-api-spec.rst
>> @@ -0,0 +1,482 @@
>> +.. SPDX-License-Identifier: GPL-2.0
>> +
>> +======================================
>> +Kernel API Specification Framework
>> +======================================
>> +
>> +:Author: Sasha Levin <sashal@kernel.org>
>> +:Date: June 2025
>
>Has it not changed since then?
>
>> +.. contents:: Table of Contents
>> + :depth: 3
>> + :local:
>> +
>> +Introduction
>> +============
>
>[...]
>
>> +Usage Guide
>> +===========
>> +
>> +Basic API Specification
>> +-----------------------
>> +
>> +API specifications are written as KAPI-annotated kerneldoc comments directly in
>> +the source file, immediately preceding the function implementation. The ``kapi``
>> +tool extracts these annotations to produce structured specifications.
>> +
>> +.. code-block:: c
>> +
>> + /**
>> + * kmalloc - allocate kernel memory
>> + * @size: Number of bytes to allocate
>> + * @flags: Allocation flags (GFP_*)
>
>Given that the text thus far has talked about user-space API validation,
>it's a bit surprising to see an internal function used as an example.
Indeed :)
I was playing with adding specs to lower level functions as a way to both
simplify the higher level spec blocks, but also to help validate the
correctness of those upper level specs ("you said that this syscall doesn't
allocate memory, but it's calling kmalloc()!").
>Also, maybe it should be kmalloc_obj()? <runs away>
>
>> + * context-flags: KAPI_CTX_PROCESS | KAPI_CTX_SOFTIRQ | KAPI_CTX_HARDIRQ
>> + * param-count: 2
>
>param-count is two, but you only document one of them?
>
>> + * param: size
>> + * type: KAPI_TYPE_UINT
>> + * flags: KAPI_PARAM_IN
>> + * constraint-type: KAPI_CONSTRAINT_RANGE
>> + * range: 0, KMALLOC_MAX_SIZE
>> + *
>> + * error: ENOMEM, Out of memory
>> + * desc: Insufficient memory available for the requested allocation.
>> + */
>
>Honest question: can this be made a bit easier for people to create,
>with less shift-key wear? My biggest worry with a system like this is
>that people won't take the time to create and maintain the entries, so
>anything that would ease the task would help. Is there an impediment to
>something like:
Before answering your actual question, I honestly think that most of these will
be LLM generated, so at least the skeleton of the kernel-doc will be there and
humans will only end up modifying the proposed spec.
> contexts: process, softirq, hardirq
>
> param: size
> type: uint, input
> constraint: range(0, KMALLOC_MAX_SIZE)
>
>See what I'm getting at? ISTM that your DSL could be made a bit less
>verbose and shouty while being just as well defined, but perhaps I'm
>missing something?
Yup, let me look into that.
>Even better, of course, would be to add a "description" field for each
>parameter, and allow that rather than the @param description that
>kerneldoc currently uses. That would keep all the information together,
>at the minor cost of adding another significant complication to the
>kernel-doc script. Mauro won't mind :)
>
>> + void *kmalloc(size_t size, gfp_t flags)
>> + {
>> + /* Implementation */
>> + }
>> +
>> +Alternatively, specifications can be defined using the ``DEFINE_KERNEL_API_SPEC``
>> +macro for compiled-in specs that are stored in the ``.kapi_specs`` ELF section:
>> +
>> +.. code-block:: c
>> +
>> + #include <linux/kernel_api_spec.h>
>> +
>> + DEFINE_KERNEL_API_SPEC(sys_open)
>> + KAPI_DESCRIPTION("Open or create a file")
>> + KAPI_CONTEXT(KAPI_CTX_PROCESS | KAPI_CTX_SLEEPABLE)
>> + /* ... parameter, error, constraint definitions ... */
>> + KAPI_END_SPEC
>
>So the reason for two completely separate mechanisms is not entirely
>clear to me. The kerneldoc variant is essentially documentation, while
>the macro stuff is to be built into the executable? What if you want
>both?
>
>It would be nice to only have one way if at all possible; I'm sure that
>crossed your mind at some point :) If there have to be two, having both
>examples describe the same function would make the parallels more clear.
Under the hood, the
>> +System Call Specification
>> +-------------------------
>> +
>> +System calls are documented inline in the implementation file (e.g., ``fs/open.c``)
>> +using KAPI-annotated kerneldoc comments. When ``CONFIG_KAPI_RUNTIME_CHECKS`` is
>> +enabled, the ``SYSCALL_DEFINEx`` macros automatically look up the specification
>> +and validate parameters before and after the syscall executes.
>> +
>> +IOCTL Specification
>> +-------------------
>> +
>> +IOCTLs use the same annotation approach with additional structure field
>> +specifications
>
>This might be a really good place for an example
I think I'll just drop the IOCTL code for now. I used it in the RFCs to
demonstrate how a similar mechanism could be used throughout different
userspace API, but since I'm not using it in this series it probably makes
sense not to even talk about it.
>[...]
>
>> +Usage Examples
>> +--------------
>> +
>> +Query specific API::
>> +
>> + $ cat /sys/kernel/debug/kapi/apis/kmalloc/specification
>> + API: kmalloc
>> + Version: 3.0
>> + Description: Allocate kernel memory
>> +
>> + Parameters:
>> + [0] size (size_t, in): Number of bytes to allocate
>> + Range: 0 - 4194304
>> + [1] flags (flags, in): Allocation flags (GFP_*)
>> + Mask: 0x1ffffff
>
>Ah, you do document that second parameter somewhere :)
Apparently. I'll update the prior example. Not sure why it's missing :)
>> + Returns: pointer - Pointer to allocated memory or NULL
>> +
>> + Errors:
>> + ENOMEM: Out of memory
>> +
>> + Context: process, softirq, hardirq
>> +
>> + Side Effects:
>> + - Allocates memory from kernel heap
>
>That part wasn't in your example
>
>> +Export all specifications::
>> +
>> + $ cat /sys/kernel/debug/kapi/export/all.json > kernel-apis.json
>> +
>> +Enable validation for specific API::
>> +
>> + $ echo 1 > /sys/kernel/debug/kapi/apis/kmalloc/validate
>> +
>> +Performance Considerations
>> +==========================
>> +
>> +Memory Overhead
>> +---------------
>> +
>> +Each API specification consumes approximately 400-450KB of memory due to the
>> +fixed-size arrays in ``struct kernel_api_spec``. With the current 4 syscall
>> +specifications, total memory usage is approximately 1.7MB. Consider:
>
>Ouch.
It's pretty "dumb" at this point: large static arrays and such, mostly to keep
the code simple to read. If this is a concern for accepting this series, I'm
happy to shrink it down (by a lot).
>> +Documentation Generation
>> +------------------------
>> +
>> +The framework exports specifications via debugfs that can be used
>> +to generate documentation. Tools for automatic documentation generation
>> +from specifications are planned for future development.
>
>Documentation always comes last :)
So this is one thing I wanted to run by the doc maintainers: the kapi tool
already has the capability to export these specs in .rst format. Would it be
interesting to have a manual for kenrel APIs in Documentation/? It can be
automatically generated and updated and would always match the kernel code at
that point.
>Interesting stuff.
Thanks!
--
Thanks,
Sasha
^ permalink raw reply
* Re: [PATCH 1/9] kernel/api: introduce kernel API specification framework
From: Sasha Levin @ 2026-03-18 14:32 UTC (permalink / raw)
To: Jonathan Corbet
Cc: linux-api, linux-kernel, linux-doc, linux-fsdevel, linux-kbuild,
linux-kselftest, workflows, tools, x86, Thomas Gleixner,
Paul E. McKenney, Greg Kroah-Hartman, 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: <87h5qe9wig.fsf@trenco.lwn.net>
On Tue, Mar 17, 2026 at 11:49:27AM -0600, Jonathan Corbet wrote:
>So the reason for two completely separate mechanisms is not entirely
>clear to me. The kerneldoc variant is essentially documentation, while
>the macro stuff is to be built into the executable? What if you want
>both?
>
>It would be nice to only have one way if at all possible; I'm sure that
>crossed your mind at some point :) If there have to be two, having both
>examples describe the same function would make the parallels more clear.
Woops, I forgot to finish writing my reply to this :)
Under the hood, kerneldoc specs are translated into those macros so they could
be part of the build process and embedded into the resulting binary (both for
documentation as well as the runtime validation).
I don't think anyone would use the macro format directly, but as it's there
anyway I figured I'd offer it as an option. Would it make sense to just hide it
behind the scenes?
--
Thanks,
Sasha
^ permalink raw reply
* Re: [PATCH 1/9] kernel/api: introduce kernel API specification framework
From: Sasha Levin @ 2026-03-18 14:53 UTC (permalink / raw)
To: Mauro Carvalho Chehab
Cc: Jonathan Corbet, linux-api, linux-kernel, linux-doc,
linux-fsdevel, linux-kbuild, linux-kselftest, workflows, tools,
x86, Thomas Gleixner, Paul E. McKenney, Greg Kroah-Hartman,
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: <20260318070055.39f1af80@foz.lan>
On Wed, Mar 18, 2026 at 07:00:55AM +0100, Mauro Carvalho Chehab wrote:
>On Tue, 17 Mar 2026 11:49:27 -0600
>Jonathan Corbet <corbet@lwn.net> wrote:
>> So the reason for two completely separate mechanisms is not entirely
>> clear to me. The kerneldoc variant is essentially documentation, while
>> the macro stuff is to be built into the executable? What if you want
>> both?
>
>You can easily add support at kernel-doc to output such macros.
>
>All you need is to create a new class derived from OutputFormat and
>make it produce any different output format, including:
>
> #include <linux/kernel_api_spec.h>
>
> DEFINE_KERNEL_API_SPEC(sys_open)
> KAPI_DESCRIPTION("Open or create a file")
> KAPI_CONTEXT(KAPI_CTX_PROCESS | KAPI_CTX_SLEEPABLE)
> /* ... parameter, error, constraint definitions ... */
> KAPI_END_SPEC
>
>I'd say that converting from such output to `.kapi_specs`` ELF section
>itself and/or to sysfs/debugfs - e.g. something that would require to
>compile or be linked with Kernel's compiled binaries should be done by a
>separate tool, but we should aim to have a singe tool to process
>kernel documentation markups.
>
>It is hard enough to maintain just one tool - and to have people actually
>writing documentation. Having a second one to handle it, with a different
>format will likely increase a lot the documentation burden.
So this is exactly what happens under the hood :) kerneldoc outputs these
macros and they get compiled ito the binary.
I exposed the macros as an option since they're there anyway, but I'm happy to
hide them as internal plumbing too.
--
Thanks,
Sasha
^ permalink raw reply
* Re: [PATCH 1/9] kernel/api: introduce kernel API specification framework
From: Jonathan Corbet @ 2026-03-18 16:50 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, 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: <abq29NMpyXJrqv_7@laps>
Sasha Levin <sashal@kernel.org> writes:
>>> +The framework exports specifications via debugfs that can be used
>>> +to generate documentation. Tools for automatic documentation generation
>>> +from specifications are planned for future development.
>>
>>Documentation always comes last :)
>
> So this is one thing I wanted to run by the doc maintainers: the kapi tool
> already has the capability to export these specs in .rst format. Would it be
> interesting to have a manual for kenrel APIs in Documentation/? It can be
> automatically generated and updated and would always match the kernel code at
> that point.
I suspect we could certainly find a place for it. Maybe as a subsection
of the user-space API manual, at least for the system-call portion of
it.
Thanks,
jon
^ permalink raw reply
* Re: [PATCH 1/9] kernel/api: introduce kernel API specification framework
From: Jonathan Corbet @ 2026-03-18 16:51 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, 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: <abq3f5vdcwRXGJGX@laps>
Sasha Levin <sashal@kernel.org> writes:
> On Tue, Mar 17, 2026 at 11:49:27AM -0600, Jonathan Corbet wrote:
>>So the reason for two completely separate mechanisms is not entirely
>>clear to me. The kerneldoc variant is essentially documentation, while
>>the macro stuff is to be built into the executable? What if you want
>>both?
>>
>>It would be nice to only have one way if at all possible; I'm sure that
>>crossed your mind at some point :) If there have to be two, having both
>>examples describe the same function would make the parallels more clear.
>
> Woops, I forgot to finish writing my reply to this :)
>
> Under the hood, kerneldoc specs are translated into those macros so they could
> be part of the build process and embedded into the resulting binary (both for
> documentation as well as the runtime validation).
>
> I don't think anyone would use the macro format directly, but as it's there
> anyway I figured I'd offer it as an option. Would it make sense to just hide it
> behind the scenes?
If there are two ways of doing it, people will use both ways. My
kneejerk reaction would be to hide the macros as an implementation
detail, but perhaps that's just me.
Thanks,
jon
^ permalink raw reply
* Re: [PATCH v2 00/25] Introduce meminspect
From: Bjorn Andersson @ 2026-03-19 2:55 UTC (permalink / raw)
To: Mukesh Ojha
Cc: Jonathan Corbet, Shuah Khan, Eugen Hristev, Arnd Bergmann,
Dennis Zhou, Tejun Heo, Christoph Lameter, Andrew Morton,
Thomas Gleixner, Peter Zijlstra, Anna-Maria Behnsen,
Frederic Weisbecker, Ingo Molnar, Juri Lelli, Vincent Guittot,
Dietmar Eggemann, Steven Rostedt, Ben Segall, Mel Gorman,
Valentin Schneider, David Hildenbrand, Lorenzo Stoakes,
Liam R. Howlett, Vlastimil Babka, Mike Rapoport,
Suren Baghdasaryan, Michal Hocko, Kees Cook, Brendan Jackman,
Johannes Weiner, Zi Yan, Chris Li, Kairui Song, Kemeng Shi,
Nhat Pham, Baoquan He, Barry Song, Youngjun Park, Petr Mladek,
John Ogness, Sergey Senozhatsky, Mathieu Poirier, Konrad Dybcio,
Rob Herring, Krzysztof Kozlowski, Conor Dooley, Saravana Kannan,
workflows, linux-doc, linux-kernel, linux-arch, linux-mm,
linux-arm-msm, linux-remoteproc, devicetree
In-Reply-To: <20260316181647.m7x4ncmwdjho6yvr@hu-mojha-hyd.qualcomm.com>
On Mon, Mar 16, 2026 at 11:46:47PM +0530, Mukesh Ojha wrote:
> On Sun, Mar 15, 2026 at 09:24:39PM -0500, Bjorn Andersson wrote:
> > On Wed, Mar 11, 2026 at 01:45:44AM +0530, Mukesh Ojha wrote:
[..]
> > >, to get all the regions as
> > > separate files. The tool from the host computer will list the regions
> > > in the order they were downloaded.
> > >
> > > Once you have all the files simply use `cat` to put them all together,
> > > in the order of the indexes. For my kernel config and setup, here is my
> > > cat command : (you can use a script or something, I haven't done that so
> > > far):
> >
> > So these need to be sorted in numerical order, by that number at the end
> > of the file name?
> >
> > Do you manually punch these in? How do we make this user friendly?
>
> Yes, manually.. but I think we can do better. We could make
> this more user‑friendly by using the section header and string table in
> the md_KELF binary both of which existed in the earlier implementation.
> Then, we can write an upstream‑friendly script that reads this KELF
> metadata file, checks whether a binary with the registered name is
> present, and stitches everything together to form a complete ELF that
> the crash tool can consume. Let me know if you have any suggestion..
>
Can we somehow identify that these regions belong to the minidump and
teach QDL to build the ELF for us?
Regards,
Bjorn
^ permalink raw reply
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