Jonathan Corbet [Fri, 10 Apr 2026 13:50:40 +0000 (07:50 -0600)]
Merge tag 'Chinese-docs-7.1' of git://git.kernel.org/pub/scm/linux/kernel/git/alexs/linux into tmp
Chinese translation docs for 7.1
This is the Chinese translation subtree for 7.1. It includes
the following changes:
- Add the rust docs translation
- Fix an inconsistent statement in dev-tools/testing-overview
- sync process/2.Process.rst with English version
Ben Guo [Fri, 10 Apr 2026 02:41:13 +0000 (10:41 +0800)]
docs/zh_CN: update rust/index.rst translation
Update the translation of .../rust/index.rst into Chinese.
Update the translation through commit a592a36e4937
("Documentation: use a source-read extension for the index link boilerplate")
Reviewed-by: Dongliang Mu <dzm91@hust.edu.cn> Reviewed-by: Gary Guo <gary@garyguo.net> Signed-off-by: Ben Guo <ben.guo@openatom.club> Signed-off-by: Alex Shi <alexs@kernel.org>
Update the translation of .../rust/quick-start.rst into Chinese.
Update the translation through commit 5935461b4584
("docs: rust: quick-start: add Debian 13 (Trixie)")
Reviewed-by: Dongliang Mu <dzm91@hust.edu.cn> Reviewed-by: Gary Guo <gary@garyguo.net> Signed-off-by: Ben Guo <ben.guo@openatom.club> Acked-by: Gary Guo <gary@garyguo.net> # Rust Signed-off-by: Alex Shi <alexs@kernel.org>
Update the translation of .../rust/coding-guidelines.rst into Chinese.
Update the translation through commit 4a9cb2eecc78
("docs: rust: add section on imports formatting")
Reviewed-by: Dongliang Mu <dzm91@hust.edu.cn> Reviewed-by: Gary Guo <gary@garyguo.net> Signed-off-by: Ben Guo <ben.guo@openatom.club> Signed-off-by: Alex Shi <alexs@kernel.org>
Update the translation of .../rust/arch-support.rst into Chinese.
Update the translation through commit ccb8ce526807
("ARM: 9441/1: rust: Enable Rust support for ARMv7")
Reviewed-by: Dongliang Mu <dzm91@hust.edu.cn> Reviewed-by: Gary Guo <gary@garyguo.net> Signed-off-by: Ben Guo <ben.guo@openatom.club> Signed-off-by: Alex Shi <alexs@kernel.org>
Song Hongyi [Wed, 11 Mar 2026 12:31:03 +0000 (20:31 +0800)]
docs/zh_CN: sync process/2.Process.rst with English version
The Chinese translation of the development process documentation was
outdated. Sync it with the current English version to ensure consistency.
Key changes include:
- Update versioning examples from 5.x to the 9.x placeholder.
- Add footnote [1] to explain the non-semantic versioning scheme.
- Replace the obsolete LTS kernel table with a link to kernel.org.
- Add a cross-reference for the "interleaved replies" section.
Update the translation through commit 5ce70894f6ca
("Doc: correct spelling and wording mistakes")
Signed-off-by: Song Hongyi <szpcq123@gmail.com> Signed-off-by: Alex Shi <alexs@kernel.org>
LIU Haoyang [Thu, 5 Mar 2026 20:10:58 +0000 (04:10 +0800)]
docs/zh_CN: fix an inconsistent statement in dev-tools/testing-overview
This patch fixes an inconsistent describtion in testing-overview.rst,
which should be ``kmalloc`` instead of ``kmalloc_arry`` according to
the original text.
Signed-off-by: LIU Haoyang <tttturtleruss@gmail.com> Reviewed-by: Dongliang Mu <dzm91@hust.edu.cn> Signed-off-by: Alex Shi <alexs@kernel.org>
Steven Rostedt [Mon, 26 Jan 2026 23:17:42 +0000 (18:17 -0500)]
tracing: Documentation: Update histogram-design.rst for fn() handling
The histogram documentation describes the old method of the histogram
triggers using the fn() field of the histogram field structure to process
the field. But due to Spectre mitigation, the function pointer to handle
the fields at runtime caused a noticeable overhead. It was converted over
to a fn_num and hist_fn_call() is now used to call the specific functions
for the fields via a switch statement based on the field's fn_num value.
Update the documentation to reflect this change.
Signed-off-by: Steven Rostedt (Google) <rostedt@goodmis.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260126181742.03e8f0d5@gandalf.local.home>
docs: sysctl: Add documentation for /proc/sys/xen/
Add documentation for the Xen hypervisor sysctl controls in
/proc/sys/xen/balloon/.
Documents the hotplug_unpopulated tunable (available when
CONFIG_XEN_BALLOON_MEMORY_HOTPLUG is enabled) which controls
whether unpopulated memory regions are automatically hotplugged
when the Xen balloon driver needs to reclaim memory.
The documentation is based on source code analysis of
drivers/xen/balloon.c.
Signed-off-by: Shubham Chakraborty <chakrabortyshubham66@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260304150419.16738-1-chakrabortyshubham66@gmail.com>
Randy Dunlap [Sat, 21 Mar 2026 23:09:34 +0000 (16:09 -0700)]
Docs: hid: intel-ish-hid: make long URL usable
The '\' line continuation character in this long URL
doesn't help anything. There is no documentation tooling that
handles the line continuation character to join the 2 lines
to make a usable URL. Web browsers terminate the URL just
before the '\' character so that the second line of the URL
is lost. See:
https://docs.kernel.org/hid/intel-ish-hid.html
Join the 2 lines together so that the URL is usable.
Signed-off-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260321230934.435020-1-rdunlap@infradead.org>
Li RongQing [Mon, 30 Mar 2026 10:59:57 +0000 (06:59 -0400)]
Documentation/kernel-parameters: fix architecture alignment for pt, nopt, and nobypass
Commit ab0e7f20768a ("Documentation: Merge x86-specific boot options doc
into kernel-parameters.txt") introduced a formatting regression where
architecture tags were placed on separate lines with broken indentation.
This caused the 'nopt' [X86] parameter to appear as if it belonged to
the [PPC/POWERNV] section.
Furthermore, since the main 'iommu=' parameter heading already specifies
it is for [X86, EARLY], the subsequent standalone [X86] tags for 'pt',
'nopt', and the AMD GART options are redundant and clutter the
documentation.
Clean up the formatting by removing these redundant tags and properly
attributing the 'nobypass' option to [PPC/POWERNV].
Fixes: ab0e7f20768a ("Documentation: Merge x86-specific boot options doc into kernel-parameters.txt") Acked-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Li RongQing <lirongqing@baidu.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260330105957.2271-1-lirongqing@baidu.com>
sched/doc: Update yield_task description in sched-design-CFS
The yield_task description referenced the long-removed compat_yield
sysctl and described the function as a dequeue/enqueue cycle. Update
it to reflect current behavior: yielding the CPU by moving the
current task's position back in the runqueue.
Sync zh_CN and sp_SP translations.
Signed-off-by: fangqiurong <fangqiurong@kylinos.cn> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260403055806.358921-1-user@fqr-pc>
Costa Shulyupin [Sun, 5 Apr 2026 16:38:45 +0000 (19:38 +0300)]
Documentation/rtla: Convert links to RST format
Web links in the documentation are not properly displayed.
In the man pages web links look like:
Osnoise tracer documentation: < <https://www.kernel.org/doc/html/lat‐
est/trace/osnoise-tracer.html> >
On web pages the URL caption is the URL itself.
Convert tracer documentation links to RST anonymous hyperlink format
for better rendering. Use newer docs.kernel.org instead of
www.kernel.org/doc/html/latest for brevity.
After the change, the links in the man pages look like:
Osnoise tracer <https://docs.kernel.org/trace/osnoise-tracer.html>
On web pages the captions are the titles of the links.
Signed-off-by: Costa Shulyupin <costa.shul@redhat.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260405163847.3337981-1-costa.shul@redhat.com>
Signed-off-by: Manuel Cortez <mdjesuscv@gmail.com> Acked-by: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260406030323.1196-1-mdjesuscv@gmail.com>
Jonathan Corbet [Mon, 30 Mar 2026 22:25:11 +0000 (16:25 -0600)]
docs: add an Assisted-by mention to submitting-patches.rst
We now require disclosure of the use of coding assistants, but our core
submitting-patches document does not mention that. Add a brief mention
with a pointer to Documentation/process/coding-assistants.rst
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <877bqtlzug.fsf@trenco.lwn.net>
Unbeknownst to me, and unremarked upon by the checkpatch maintainer, this
same problem was also solved in the mm tree. Fixing it once is enough, so
this one comes out.
Commit 2e5449f4f21a ("profiling: Remove create_prof_cpu_mask().") said that
no one would create /proc/irq/prof_cpu_mask since commit 1f44a225777e
("s390: convert interrupt handling to use generic hardirq", 2013). Remove
the outdated description.
Akira Yokosawa [Thu, 26 Mar 2026 11:46:37 +0000 (20:46 +0900)]
docs/ja_JP: submitting-patches: Amend "Describe your changes"
To make the translation of "Describe your changes" (into
"変更内容を記述する") easier to follow, do some rewording and
rephrasing, as well as fixing a couple of mistranslations.
Signed-off-by: Akira Yokosawa <akiyks@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260326114637.144601-1-akiyks@gmail.com>
Manuel Ebner [Wed, 25 Mar 2026 19:48:12 +0000 (20:48 +0100)]
docs: changes.rst and ver_linux: sort the lists
Sort the lists of tools in both scripts/ver_linux and
Documentation/process/changes.rst into alphabetical order, facilitating
comparison between the two.
Signed-off-by: Manuel Ebner <manuelebner@mailbox.org>
[jc: rewrote changelog] Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260325194811.78509-2-manuelebner@mailbox.org>
Manuel Ebner [Wed, 25 Mar 2026 19:46:17 +0000 (20:46 +0100)]
docs: changes/ver_linux: fix entries and add several tools
Some of the entries in both Documentation/process/changes.rst and
script/ver_linux were obsolete; update them to reflect the current way of
getting version information.
Many were missing altogether; add the relevant information for:
Florian Fainelli [Thu, 26 Mar 2026 23:32:24 +0000 (16:32 -0700)]
Documentation: Provide hints on how to debug Python GDB scripts
By default GDB does not print a full stack of its integrated Python
interpreter, thus making the debugging of GDB scripts more painful than
it has to be.
Suggested-by: Radu Rendec <radu@rendec.net> Signed-off-by: Florian Fainelli <florian.fainelli@broadcom.com> Reviewed-by: Radu Rendec <radu@rendec.net> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260326233226.2248817-1-florian.fainelli@broadcom.com>
Harry Wentland [Fri, 27 Mar 2026 15:41:57 +0000 (11:41 -0400)]
scripts/checkpatch: add Assisted-by: tag validation
The coding-assistants.rst documentation defines the Assisted-by: tag
format for AI-assisted contributions as:
Assisted-by: AGENT_NAME:MODEL_VERSION [TOOL1] [TOOL2]
This format does not use an email address, so checkpatch currently
reports a false positive about an invalid email when encountering this
tag.
Add Assisted-by: to the recognized signature tags and standard signature
list. When an Assisted-by: tag is found, validate it instead of checking
for an email address.
Examples of passing tags:
- Claude:claude-3-opus coccinelle sparse
- FOO:BAR.baz
- Copilot Github:claude-3-opus
- GitHub Copilot:Claude Opus 4.6
- My Cool Agent:v1.2.3 coccinelle sparse
Examples of tags triggering the new warning:
- Claude coccinelle sparse
- JustAName
- :missing-agent
Cc: Jani Nikula <jani.nikula@linux.intel.com> Assisted-by: Claude:claude-opus-4.6 Co-developed-by: Alex Hung <alex.hung@amd.com> Signed-off-by: Alex Hung <alex.hung@amd.com> Signed-off-by: Harry Wentland <harry.wentland@amd.com> Cc: stable@vger.kernel.org Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260327154157.162962-1-harry.wentland@amd.com>
Akiyoshi Kurita [Mon, 9 Mar 2026 10:50:15 +0000 (19:50 +0900)]
docs: ja_JP: process: translate second half of 'Describe your changes'
Translate the remaining part of the "Describe your changes" section in
Documentation/translations/ja_JP/process/submitting-patches.rst.
Follow review comments on wording and line wrapping, and cover guidance
on self-contained patch descriptions, imperative mood, commit
references, and Link:/Closes:/Fixes: tags.
Daniel Pereira [Mon, 23 Mar 2026 17:11:32 +0000 (14:11 -0300)]
docs: pt_BR: Add translation for KVM x86 maintainer guide
Translate the KVM x86 maintainer guidelines (maintainer-kvm-x86.rst)
into Portuguese (pt_BR). This document covers the specific
workflow, coding style, and testing requirements for the
KVM x86 subsystem.
Signed-off-by: Daniel Pereira <danielmaraboo@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260323171133.88074-3-danielmaraboo@gmail.com>
Daniel Pereira [Mon, 23 Mar 2026 17:11:31 +0000 (14:11 -0300)]
docs: pt_BR: Add translation for process/conclave.rst
Translate the Linux kernel project continuity documentation (conclave.rst)
into Portuguese (pt_BR). Also, update the main pt_BR index to include
the link to the new translation.
Signed-off-by: Daniel Pereira <danielmaraboo@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260323171133.88074-2-danielmaraboo@gmail.com>
docs: kdoc: better handle source when producing YAML output
The current logic was storing symbols source code on a list,
not linked to the actual KdocItem. While this works fine when
kernel-doc markups are OK, on places where there is a "/**"
without a valid kernel-doc markup, it ends that the 1:1 match
between source code and KdocItem doesn't happen, causing
problems to generate the YAML output.
Fix it by storing the source code directly into the KdocItem
structure.
This shouldn't affect performance or memory footprint, except
when --yaml option is used.
While here, add a __repr__() function for KdocItem, as it
helps debugging it.
ReST simple tables use "=" instead of "-". I ended testing it with
a table modified from a complex one, using "--- --- ---", instead
of searching for a real Kernel example.
Only noticed when adding an unit test and seek for an actual
example from kernel-doc markups.
unittests: test_kdoc_parser: add command line arg to read a YAML file
The test_kdoc_parser.py already supports loading dynamic tests
when running unit tests.
Add support to read from a different file. This is useful for:
- regression tests before/afer some changes;
- preparing new unit tests;
- test a different yaml before adding its contents at
tools/unittests/kdoc-test.yaml.
It should be noticed that passing an argument to a unit test
is not too trivial, as unittest core will load itself the
runner with a separate environment. The best (only?) way to
do it is by setting the system environment. This way, when
the class is called by the unit test loader, it can pick
the var from the environment without relying on a global
variable.
The unittest_helper has already provision for it, so let's
use its support.
Rito Rhymes [Mon, 23 Mar 2026 15:24:27 +0000 (11:24 -0400)]
docs: allow long links to wrap per character to prevent page overflow
Some documentation pages contain long link text without natural
break points, which can force page-wide horizontal scroll overflow
on small screens.
Use overflow-wrap: anywhere for anchor text in the docs stylesheet so
links can wrap per character as a fallback when normal word boundaries
are unavailable.
Rito Rhymes [Mon, 23 Mar 2026 15:24:28 +0000 (11:24 -0400)]
docs: allow long table reference links to wrap and prevent overflow
Some documentation pages contain docutils tables with reference links
that use long unbroken strings. Those strings can expand the table
width beyond the content column and cause page-wide horizontal
overflow.
Allow reference links in docutils tables in the main document body to
wrap when needed so the table stays within the content column and does
not break page layout.
Rito Rhymes [Mon, 23 Mar 2026 15:33:42 +0000 (11:33 -0400)]
docs: contain horizontal overflow in C API descriptions
Some documentation pages contain long C API signatures that can exceed
the content width and cause page-wide horizontal scroll overflow.
Apply contained horizontal scrolling to C API description blocks and
keep their signature rows on one line. This preserves signature
formatting while preventing them from breaking page layout.
Contained horizontal scrolling is preferred over wrapping here because
code fidelity is the priority. These blocks are intended to remain
representative of the code itself. Wrapping distorts spacing and line
structure, which affects fidelity, creates misleading renderings, and
reduces readability.
Rito Rhymes [Mon, 23 Mar 2026 15:14:01 +0000 (11:14 -0400)]
docs: allow inline literals in paragraphs to wrap to prevent overflow
Some documentation pages contain long inline literals in paragraph
text that can force page-wide horizontal scroll overflow and break
layout on smaller screens.
Override the default `span.pre` white-space behavior for inline
literals and use `overflow-wrap: anywhere` so they can wrap when
needed. For code used as part of a paragraph, wrapping is appropriate
because it is stylistically part of the surrounding text. Code blocks,
by contrast, are meant to preserve formatting fidelity and are better
served by contained horizontal scrolling.
Jonathan Corbet [Sun, 22 Mar 2026 21:25:08 +0000 (15:25 -0600)]
Merge branch 'mauro' into docs-mw
This series comes after:
https://lore.kernel.org/linux-doc/cover.1773770483.git.mchehab+huawei@kernel.org/
It basically contains patches I submitted before on a 40+ patch series,
but were less relevant, plus a couple of other minor fixes:
- patch 1 improves one of the CTokenizer unit test, fixing some
potential issues on it;
- patches 2 and 3 contain some improvement/fixes for Sphinx
Python autodoc extension. They basically document c_lex.py;
- The remaining patches:
- create a new class for kernel-doc config;
- fix some internal representations of KdocItem;
- add unit tests for KernelDoc() parser class;
- add support to output KdocItem in YAML, which is a
machine-readable output for all documented kAPI.
None of the patches should affect man or html output.
docs: test_kdoc_parser: add support for dynamic test creation
Use the content of kdoc-test.yaml to generate unittests to
verify that kernel-doc internal methods are parsing C code
and generating output the expected way.
Depending on what is written at the parser file at
kdoc-test.yaml, up to 5 tests can be generated from a single
test entry inside the YAML file:
1. from source to kdoc_item: test KernelDoc class;
2. from kdoc_item to man: test ManOutput class;
3. from kdoc_item to rst: test RestOutput class;
4. from source to man without checking expected KdocItem;
5. from source to rst without checking expected KdocItem.
docs: add a simple kdoc-test.yaml together with a validation tool
Create a simple kdoc-test.yaml to be used to create unit tests for
kernel-doc parser and output classes.
For now, all we want is a simple function mapped on a yaml test
using the defined schema.
To be sure that the schema is followed, add an unittest for
the file, which will also validate that the schema is properly
parsed.
It should be noticed that the .TH definition for the man format
contains a timestamp. We'll need to handle that when dealing with
the actual implementation for the ManOutput class unit tests.
docs: unittests: add a parser to test kernel-doc parser logic
Validating that kernel-doc is parsing data properly is tricky.
Add an unittest skeleton that alllows passing a source code
and check if the corresponding values of export_table and
entries returned by the parser are properly filled.
It works by mocking a file input with the contents of a source
string, an comparing if:
- exports set matches;
- expected KernelItem entries match.
Create a new TestSelfValidate meant to check if the logic
inside KdocParser.run_test() does its job of checking for
differences inside KdocItem.
docs: kdoc_item: add support to generate a KdocItem from a dict
When reading the contents on a KdocItem using YAML, the data
will be imported into a dict.
Add a method to create a new KdocItem from a dict to allow
converting such input into a real KdocItem.
While here, address an issue that, if the class is initialized
with an internal parameter outside the 4 initial arguments,
it would end being added inside other_stuff, which breaks
initializing it from a dict.
docs: kdoc_files: move output symbols logic to kdoc_output
When writing unittests for kdoc_output, it became clear that
the logic with handles a series of KdocItem symbols from
a single file belons to kdoc_output, and not to kdoc_files.
Move the code to it.
While here, also ensure that self.config will be placed
together with set.out_style.
Jonathan Corbet [Sun, 22 Mar 2026 21:06:59 +0000 (15:06 -0600)]
Merge branch 'mauro' into docs-mw
Mauro says:
This patch series change how kdoc parser handles macro replacements.
Instead of heavily relying on regular expressions that can sometimes
be very complex, it uses a C lexical tokenizer. This ensures that
BEGIN/END blocks on functions and structs are properly handled,
even when nested.
Checking before/after the patch series, for both man pages and
rst only had:
- whitespace differences;
- struct_group macros now are shown as inner anonimous structs
as it should be.
Also, I didn't notice any relevant change on the documentation build
time. With that regards, right now, every time a CMatch replacement
rule takes in place, it does:
for each transform:
- tokenizes the source code;
- handle CMatch;
- convert tokens back to a string.
A possible optimization would be to do, instead:
- tokenizes source code;
- for each transform handle CMatch;
- convert tokens back to a string.
For now, I opted not do do it, because:
- too much changes on a single row;
- docs build time is taking ~3:30 minutes, which is
about the same time it ws taken before the changes;
- there is a very dirty hack inside function_xforms:
(KernRe(r"_noprof"), ""). This is meant to change
function prototypes instead of function arguments.
So, if ok for you, I would prefer to merge this one first. We can later
optimize kdoc_parser to avoid multiple token <-> string conversions.
-
One important aspect of this series is that it introduces unittests
for kernel-doc. I used it a lot during the development of this series,
to ensure that the changes I was doing were producing the expected
results. Tests are on two separate files that can be executed directly.
Alternatively, there is a run.py script that runs all of them (and
any other python script named tools/unittests/test_*.py"):
$ tools/unittests/run.py
test_cmatch:
TestSearch:
test_search_acquires_multiple: OK
test_search_acquires_nested_paren: OK
test_search_acquires_simple: OK
test_search_must_hold: OK
test_search_must_hold_shared: OK
test_search_no_false_positive: OK
test_search_no_function: OK
test_search_no_macro_remains: OK
TestSubMultipleMacros:
test_acquires_multiple: OK
test_acquires_nested_paren: OK
test_acquires_simple: OK
test_mixed_macros: OK
test_must_hold: OK
test_must_hold_shared: OK
test_no_false_positive: OK
test_no_function: OK
test_no_macro_remains: OK
TestSubSimple:
test_rise_early_greedy: OK
test_rise_multiple_greedy: OK
test_strip_multiple_acquires: OK
test_sub_count_parameter: OK
test_sub_mixed_placeholders: OK
test_sub_multiple_placeholders: OK
test_sub_no_placeholder: OK
test_sub_single_placeholder: OK
test_sub_with_capture: OK
test_sub_zero_placeholder: OK
TestSubWithLocalXforms:
test_functions_with_acquires_and_releases: OK
test_raw_struct_group: OK
test_raw_struct_group_tagged: OK
test_struct_group: OK
test_struct_group_attr: OK
test_struct_group_tagged_with_private: OK
test_struct_kcov: OK
test_vars_stackdepot: OK
test_tokenizer:
TestPublicPrivate:
test_balanced_inner_private: OK
test_balanced_non_greddy_private: OK
test_balanced_private: OK
test_no private: OK
test_unbalanced_inner_private: OK
test_unbalanced_private: OK
test_unbalanced_struct_group_tagged_with_private: OK
test_unbalanced_two_struct_group_tagged_first_with_private: OK
test_unbalanced_without_end_of_line: OK
TestTokenizer:
test_basic_tokens: OK
test_depth_counters: OK
test_mismatch_error: OK
Most of the rules inside CTransforms are of the type CMatch.
Don't re-parse the source code every time.
Doing this doesn't change the output, but makes kdoc almost
as fast as before the tokenizer patches:
# Before tokenizer patches
$ time ./scripts/kernel-doc . -man >original 2>&1
real 0m42.933s
user 0m36.523s
sys 0m1.145s
# After tokenizer patches
$ time ./scripts/kernel-doc . -man >before 2>&1
real 1m29.853s
user 1m23.974s
sys 0m1.237s
# After this patch
$ time ./scripts/kernel-doc . -man >after 2>&1
real 0m48.579s
user 0m45.938s
sys 0m0.988s
$ diff -s before after
Files before and after are identical
Manually checked the differences between original and after
with:
$ diff -U0 -prBw original after|grep -v Warning|grep -v "@@"|less
They're due:
- whitespace fixes;
- struct_group are now better handled;
- several badly-generated man pages from broken inline kernel-doc
markups are now fixed.
docs: kdoc: ensure that comments are dropped before calling split_struct_proto()
Changeset 2b957decdb6c ("docs: kdoc: don't add broken comments inside prototypes")
revealed a hidden bug at split_struct_proto(): some comments there may break
its capability of properly identifying a struct.
Fixing it is as simple as stripping comments before calling it.
The CMatch logic is complex enough to justify tests to ensure
that it is doing its job.
Add unittests to check the functionality provided by CMatch
by replicating expected patterns.
The CMatch class handles with complex macros. Add an unittest
to check if its doing the right thing and detect eventual regressions
as we improve its code.
The initial version was generated using gpt-oss:latest LLM
on my local GPU, as LLMs aren't bad transforming patterns
into unittests.
Yet, the curent version contains only the skeleton of what
LLM produced, as I ended higly changing its content to be
more representative and to have real case scenarios.
The kdoc_xforms test suite contains 3 test groups. Two of
them tests the basic functionality of CMatch to
replace patterns.
The last one (TestRealUsecases) contains real code snippets
from the Kernel with some cleanups to better fit in 80 columns
and uses the same transforms as kernel-doc, thus allowing
to test the logic used inside kdoc_parser to transform
functions, structs and variable patterns.
Its output is like this:
$ tools/unittests/kdoc_xforms.py
Ran 25 tests in 0.003s
OK
test_cmatch:
TestSearch:
test_search_acquires_multiple: OK
test_search_acquires_nested_paren: OK
test_search_acquires_simple: OK
test_search_must_hold: OK
test_search_must_hold_shared: OK
test_search_no_false_positive: OK
test_search_no_function: OK
test_search_no_macro_remains: OK
We'll soon have multiple unit tests, add a runner that will
discover all of them and execute all tests.
It was opted to discover only files that starts with "test",
as this way unittest discover won't try adding libraries or
other stuff that might not contain unittest classes.
docs: kdoc: use tokenizer to handle comments on structs
Better handle comments inside structs. After those changes,
all unittests now pass:
test_private:
TestPublicPrivate:
test balanced_inner_private: OK
test balanced_non_greddy_private: OK
test balanced_private: OK
test no private: OK
test unbalanced_inner_private: OK
test unbalanced_private: OK
test unbalanced_struct_group_tagged_with_private: OK
test unbalanced_two_struct_group_tagged_first_with_private: OK
test unbalanced_without_end_of_line: OK
Ran 9 tests
This also solves a bug when handling STRUCT_GROUP() with a private
comment on it:
@@ -397134,7 +397134,7 @@ basic V4L2 device-level support.
unsigned int max_len;
unsigned int offset;
struct page_pool_params_slow slow;
- STRUCT_GROUP( struct net_device *netdev;
+ struct net_device *netdev;
unsigned int queue_idx;
unsigned int flags;
};
Handling C code purely using regular expressions doesn't work well.
Add a C tokenizer to help doing it the right way.
The tokenizer was written using as basis the Python re documentation
tokenizer example from:
https://docs.python.org/3/library/re.html#writing-a-tokenizer
Parsing a file like drivers/scsi/isci/host.h, which contains
broken kernel-doc markups makes it create a prototype that contains
unmatched end comments.
That causes, for instance, struct sci_power_control to be shown this
this prototype:
struct sci_power_control {
* it is not. */ bool timer_started;
*/ struct sci_timer timer;
* requesters field. */ u8 phys_waiting;
*/ u8 phys_granted_power;
* mapped into requesters via struct sci_phy.phy_index */ struct isci_phy *requesters[SCI_MAX_PHYS];
};
as comments won't start with "/*" anymore.
Fix the logic to detect such cases, and keep adding the comments
inside it.
unittests: add a testbench to check public/private kdoc comments
Add unit tests to check if the public/private and comments strip
is working properly.
Running it shows that, on several cases, public/private is not
doing what it is expected:
test_private:
TestPublicPrivate:
test balanced_inner_private: OK
test balanced_non_greddy_private: OK
test balanced_private: OK
test no private: OK
test unbalanced_inner_private: FAIL
test unbalanced_private: FAIL
test unbalanced_struct_group_tagged_with_private: FAIL
test unbalanced_two_struct_group_tagged_first_with_private: FAIL
test unbalanced_without_end_of_line: FAIL
While python internal libraries have support for unit tests, its
output is not nice. Add a helper module to improve its output.
I wrote this module last year while testing some scripts I used
internally. The initial skeleton was generated with the help of
LLM tools, but it was higly modified to ensure that it will work
as I would expect.
Haoyang LIU [Mon, 9 Mar 2026 07:47:15 +0000 (15:47 +0800)]
tools/docs/checktransupdate.py: fix all issues reported by pylint
This patch fixes all issues reported by pylint, including:
1. Format issue in logging.
2. Variable name style issue.
Fixes: 63e96ce050e5 ("scripts: fix all issues reported by pylint") Signed-off-by: Haoyang LIU <tttturtleruss@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260309074716.10739-1-tttturtleruss@gmail.com>
Daniel Tang [Tue, 10 Mar 2026 01:05:21 +0000 (21:05 -0400)]
docs: path-lookup: fix unrenamed WALK_GET
The symbol WALK_GET does not appears in the codebase as of 0031c06807cfa8aa. It was renamed as of 8f64fb1ccef33107. A previous
documentation update, de9414adafe4, renamed one occurrence in
path-lookup.rst, but forgot to change another occurrence later in the
file.
Fixes: de9414adafe4 ("docs: path-lookup: update WALK_GET, WALK_PUT desc") Signed-off-by: Daniel Tang <danielzgtg.opensource@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <13011949.O9o76ZdvQC@daniel-desktop3>
Julia Lawall [Tue, 10 Mar 2026 12:14:31 +0000 (13:14 +0100)]
coccinelle: update Coccinelle URL
The LIP6 URL no longer functions.
Signed-off-by: Julia Lawall <Julia.Lawall@inria.fr> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260310121431.362091-1-Julia.Lawall@inria.fr>
docs: reporting-issues: create a proper appendix explaining specialties
Merge "Why some bugs remain unfixed and some reports are ignored" with
the closing words while rewriting and extending the text.
The result spends fewer words on explaining things that are normal in
FLOSS -- while outlining where the kernel is different and how that
makes bug reporting more complicated than in other FLOSS projects.
docs: verify-bugs-… and quickly-build-…: improve feedback section
Mention sending patches in the section about feedback. This syncs them
with a section a earlier patch added to reporting-issues.rst, which
was based on these sections and improved during review.
docs: reporting-issues: tweak the reference section intro
Fine tuning to the intro of the reference section:
* Call the step-by-step guide what it is.
* Reorder the links to the guides on bug reporting to first mention the
most modern one.
* Many small changes to streamline the text and slightly shorten it.
docs: reporting-issues: mention text is best viewed rendered
Add a comment before the step-by-step guide explaining that the document
is best viewed in the rendered form, as there the internal links will
work that later patches will add.
Daniel Castro [Tue, 17 Mar 2026 14:01:34 +0000 (11:01 -0300)]
docs: pt_BR: translate process/1.Intro.rst
Add Brazilian Portuguese translation of the development process
introduction (Documentation/process/1.Intro.rst), covering the
executive summary, importance of mainline code, and licensing.
Assisted-by: Claude:claude-opus-4-6 Signed-off-by: Daniel Castro <arantescastro@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260317140136.29256-1-arantescastro@gmail.com>
Daniel Pereira [Thu, 19 Mar 2026 11:54:12 +0000 (08:54 -0300)]
docs/pt_BR: translation of maintainer-soc-clean-dts.rst
Translate Documentation/process/maintainer-soc-clean-dts.rst into Portuguese.
Signed-off-by: Daniel Pereira <danielmaraboo@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260319115416.495020-3-danielmaraboo@gmail.com>
Daniel Pereira [Thu, 19 Mar 2026 11:54:11 +0000 (08:54 -0300)]
docs/pt_BR: translation of maintainer-soc.rst
Translate Documentation/process/maintainer-soc.rst into Portuguese.
This is part of the effort to localize the kernel documentation.
Signed-off-by: Daniel Pereira <danielmaraboo@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260319115416.495020-2-danielmaraboo@gmail.com>
Manuel Ebner [Wed, 11 Mar 2026 16:54:41 +0000 (17:54 +0100)]
scripts: ver_linux: expand and fix list
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.
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>
Message-ID: <20260311165440.183672-2-manuelebner@airmail.cc> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Daniel Pereira [Thu, 12 Mar 2026 12:24:24 +0000 (09:24 -0300)]
docs: pt_BR: add netdev and maintainer handbook translations
Add the Brazilian Portuguese translation for the netdev subsystem
process and update the maintainer handbook to include it.
Signed-off-by: Daniel Pereira <danielmaraboo@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260312122425.19577-1-danielmaraboo@gmail.com>
Kuan-Wei Chiu [Thu, 12 Mar 2026 17:53:41 +0000 (17:53 +0000)]
docs: interconnect: Document consumer APIs and drop outdated text
The documentation currently states that consumer interfaces are not
documented, which is no longer true.
Remove the outdated claim and include the existing kernel-doc from
drivers/interconnect/core.c (filtered for consumer APIs) and
drivers/interconnect/bulk.c.
Signed-off-by: Kuan-Wei Chiu <visitorckw@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260312175341.2944154-3-visitorckw@gmail.com>
Kuan-Wei Chiu [Thu, 12 Mar 2026 17:53:40 +0000 (17:53 +0000)]
docs: interconnect: Add provider APIs to documentation
The "Interconnect providers" section currently only includes data
structures from include/linux/interconnect-provider.h.
Include drivers/interconnect/core.c to extract provider-specific
API documentation. The :functions: directive is used to prevent
mixing with consumer APIs.
Signed-off-by: Kuan-Wei Chiu <visitorckw@gmail.com> Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260312175341.2944154-2-visitorckw@gmail.com>
projects / thirdparty / kernel / linux.git / log
