vsprintf.c uses a mix of the `kernel.kptr_restrict` sysctl and the
`hash_pointers` boot param to control pointer hashing. But that wasn't
possible to tell without looking at the source code.
They have a different focus and purpose. To avoid wasting the time of
users trying to use one instead of the other, simply have them reference
each other in the Documentation.
Signed-off-by: Marc Herbert <marc.herbert@linux.intel.com>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260107-doc-hash-ptr-v2-1-cb4c161218d7@linux.intel.com>
Removing :manpage: from non-existing man pages (xyzzy(2), xyzzyat(2),
fxyzzy(3) in adding-syscalls.rst, including translations) prevent
adding link to nonexisting man pages when using manpages_url in next
commit.
While at it, add also missing '(2)' in sp_SP translation.
Reviewed-by: Alejandro Colomar <alx@kernel.org>
Signed-off-by: Petr Vorel <pvorel@suse.cz>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260113113612.315748-2-pvorel@suse.cz>
The driver binding documentation (still) mentions that "When a driver is
attached to a device, the device is inserted into the driver's list of
devices.".
While it is true that the driver-core keeps track of all the devices
that are attached to a driver, this is purely for internal purposes
(i.e. it is an implementation detail) and has no relevance for user
facing documentation.
In fact, it is even misleading, since it could be read as if it were
valid for driver implementations to keep track of all the devices bound
to it.
Instead, drivers operate on a per-device basis, with a separate
per-device instance created when the driver is bound to a device.
Hence, remove the mention of a driver's list of devices and instead add
some documentation of the relationship between drivers and devices.
Signed-off-by: Danilo Krummrich <dakr@kernel.org>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260115215718.6405-1-dakr@kernel.org>
Fix various typos and grammatical errors across documentation files:
- Fix missing preposition 'in' in process/changes.rst
- Correct 'result by' to 'result from' in admin-guide/README.rst
- Fix 'before hand' to 'beforehand' in cgroup-v1/hugetlb.rst
- Correct 'allows to limit' to 'allows limiting' in hugetlb.rst,
cgroup-v2.rst, and kconfig-language.rst
- Fix 'needs precisely know' to 'needs to precisely know'
- Correct 'overcommited' to 'overcommitted' in hugetlb.rst
- Fix subject-verb agreement: 'never causes' to 'never cause'
- Fix 'there is enough' to 'there are enough' in hugetlb.rst
- Fix 'metadatas' to 'metadata' in filesystems/erofs.rst
- Fix 'hardwares' to 'hardware' in scsi/ChangeLog.sym53c8xx
Signed-off-by: Nauman Sabir <officialnaumansabir@gmail.com>
Acked-by: Tejun Heo <tj@kernel.org>
Message-ID: <20260115230110.7734-1-officialnaumansabir@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link to another document does not require 'file:', therefore it was
shown in generated html.
Preformatted text requires just ``...``.
Signed-off-by: Petr Vorel <pvorel@suse.cz>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260111223643.174812-1-pvorel@suse.cz>
When using GNU Make's jobserver feature in kernel builds, a bug in MAKEFLAGS
propagation caused "--jobserver-auth=r,w" to reference an unintended file
descriptor. This led to infinite loops in jobserver-exec's os.read() calls
due to empty token.
My shell opened /etc/passwd for some reason without closing it, and as a
result, all child processes inherited this fd 3.
$ ls -l /proc/self/fd
total 0
lrwx------ 1 changbin changbin 64 Dec 25 13:03 0 -> /dev/pts/1
lrwx------ 1 changbin changbin 64 Dec 25 13:03 1 -> /dev/pts/1
lrwx------ 1 changbin changbin 64 Dec 25 13:03 2 -> /dev/pts/1
lr-x------ 1 changbin changbin 64 Dec 25 13:03 3 -> /etc/passwd
lr-x------ 1 changbin changbin 64 Dec 25 13:03 4 -> /proc/1421383/fd
In this case, the `make` should open a new file descriptor for jobserver
control, but clearly, it did not do so and instead still passed fd 3 as
"--jobserver-auth=3,4" in MAKEFLAGS. (The version of my gnu make is 4.3)
This update ensures robustness against invalid jobserver configurations,
even when `make` incorrectly pass non-pipe file descriptors.
* Rejecting empty reads to prevent infinite loops on EOF.
* Clearing `self.jobs` to avoid writing to incorrect files if invalid tokens
are detected.
* Printing detailed error messages to stderr to inform the user.
Cc: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: Changbin Du <changbin.du@huawei.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260108113836.2976527-1-changbin.du@huawei.com>
Add guidance for AI assistants and developers using AI tools for kernel
contributions, per the consensus reached at the 2025 Maintainers Summit.
Create Documentation/process/coding-assistants.rst with detailed guidance
on licensing, Signed-off-by requirements, and attribution format. The
README points AI tools to this documentation.
This will allow coding assistants to easily parse these instructions and
comply with guidelines set by the community.
Link: https://lwn.net/Articles/1049830/
Signed-off-by: Sasha Levin <sashal@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251223122110.2496946-1-sashal@kernel.org>
The memory-barriers.txt Korean translation is quite outdated. The last
update on the translation was made on 2022-10-10, by commit ee5a86f451
("docs/memory-barriers.txt/kokr: Fix confusing name of 'data dependency
barrier'"). After the date, the original memory-barriers.txt got seven
more changes so far. The most recent one was made on 2025-11-05. But
none of those are applied to the translation.
Maybe I can work again on keeping it updated. But, given the
advancement of translation tools, I think it might not be worth keeping
it at all. Remove the outdated translation.
If it turns out to be worthy to keep the translation and someone willing
to keep it updated steps up, this could be reverted.
This change was inspired from the last kernel summit discussion [1].
[1] https://lpc.events/event/19/contributions/2259/
Cc: Paul E. McKenney <paulmck@kernel.org>
Signed-off-by: SeongJae Park <sj@kernel.org>
Acked-by: Paul E. McKenney <paulmck@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251225014027.15948-1-sj@kernel.org>
For review of patches that revisioned multiple times, patch changelogs
are very useful. Adding actual links to the previous versions can
further help the review. Using such links, reviewers can double check
the changelog by themselves, and find previous discussions. Nowadays
having such links (e.g., lore.kernel.org archive links) is easy and
reliable. Suggest adding such links if available.
Signed-off-by: SeongJae Park <sj@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251225015447.16387-1-sj@kernel.org>
The documentation states that:
make W=n
can be used to verify the documentation format. This is true for .c
files but not for headers [1].
Modify the documentation to specify that headers files are not covered
by make W=n and that these need to be checked separately with
scripts/kernel-doc.
[1] commit 3a025e1d1c ("Add optional check for bad kernel-doc comments")
Link: https://git.kernel.org/torvalds/c/3a025e1d1c2e
Signed-off-by: Vincent Mailhol <mailhol@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251225-doc-format-check-v1-1-dff637a4d275@kernel.org>
While reading the git-format-patch manpages [1], I discovered the existence
of the "Toggle Line Wrap" extension for Thunderbird which I found rather
convenient.
Looking at the history, the ancestor of this extension was added to the
documentation in commit e0e34e977a ("Documentation/email-clients.txt:
update Thunderbird docs with wordwrap plugin") but then removed in commit
f9a0974d3f ("Documentation: update thunderbird email client settings").
Extend the paragraph on Thunderbird's mailnews.wraplength register to
mention the existence of the "Toggle Line Wrap" extension. The goal is not
to create a war on what is the best option so make it clear that this is
just an alternative.
[1] man git-format-patch -- §Thunderbird
Link: https://git-scm.com/docs/git-format-patch#_thunderbird
Signed-off-by: Vincent Mailhol <mailhol@kernel.org>
Reviewed-by: Gal Pressman <gal@nvidia.com>
Acked-by: Sotir Danailov <sndanailov@gmail.com> # As past commit author
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251226-docs_thunderbird-toggle-line-wrap-v2-1-aebb8c60025d@kernel.org>
The recent move of this script from scripts/ to tools/docs/
did not account for the 'cd' directory usage.
Update "cd .." to "cd ../.." to make the script self-correcting.
This also eliminates a shell warning:
./tools/docs/find-unused-docs.sh: line 33: cd: Documentation/: No such file or directory
Fixes: 184414c6a6 ("docs: move find-unused-docs.sh to tools/docs")
Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Fixes: 184414c6a6 (docs: move find-unused-docs.sh to tools/docs)
Signed-off-by: Matthew Wilcox (Oracle) <willy@infradead.org>
Reviewed-by: Matthew Wilcox (Oracle) <willy@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260102200657.1040234-1-rdunlap@infradead.org>
Commit 4843a45ef9fe8 ("entry: Rename "kvm" entry code assets to "virt"
to genericize APIs") renames the config KVM_XFER_TO_GUEST_WORK to
VIRT_XFER_TO_GUEST_WORK.
Adjust the documentation to the current situation, and specifically
refer to the new name of the config.
Signed-off-by: Lukas Bulwahn <lukas.bulwahn@redhat.com>
Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251127154343.292156-3-bigeasy@linutronix.de>
Some thoughts on hardware that is used for real-time workload. Certainly
not complete but should cover some of the import topics such as:
- Main memory, caches and the possiblie control given by the hardware.
- What could happen by putting critical hardware behind USB or VirtIO.
- Allowing real-time tasks to consume the CPU entirely without giving
the system some time to breath.
- Networking with what the kernel provides.
Reviewed-by: Steven Rostedt (Google) <rostedt@goodmis.org>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251127154343.292156-2-bigeasy@linutronix.de>
As the trend of AI-generated reports is growing, the trend of unreadable
reports in gimmicky formats is following, and we cannot request that
developers rely on online viewers to be able to read a security report
full for formatting tags. Let's just insist on the plain text requirement
a bit more.
Signed-off-by: Willy Tarreau <w@1wt.eu>
Signed-off-by: Ingo Molnar <mingo@kernel.org>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251129141741.19046-1-w@1wt.eu>
Update the device tree binding reference from .txt to YAML.
Binding was converted in commit 20b3c9a403 ("dt-bindings: arm: Convert ti,keystone to DT schema")
and moved to Documentation/devicetree/bindings/arm/ti/ti,keystone.yaml.
Signed-off-by: Shubham Sharma <slopixelz@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251207195632.68681-1-slopixelz@gmail.com>
Inline kernel-doc blocks failed to parse tags containing dots (e.g.
creator.process_name in panfrost_gem.h) because the @name regex only
matched word characters. Modify the single-line pattern to match
doc_inline_sect so it includes \. and parses the same as a multi-line
comment.
Signed-off-by: Steven Price <steven.price@arm.com>
Acked-by: Randy Dunlap <rdunlap@infradead.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251211104851.45330-1-steven.price@arm.com>
For several years, and still ongoing, the kernel.h is being split
to smaller and narrow headers to avoid "including everything" approach
which is bad in many ways. Since that, documentation missed a few
required updates to align with that work. Do it here.
Note, language translations are left untouched and if anybody willing
to help, please provide path(es) based on the updated English variant.
Signed-off-by: Andy Shevchenko <andriy.shevchenko@linux.intel.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Reviewed-by: Mathieu Poirier <mathieu.poirier@linaro.org>
Tested-by: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20251126214709.2322314-1-andriy.shevchenko@linux.intel.com>
Mauro says:
As suggested and discussed with Randy, this small series add support
for documenting variables using kernel-doc.
- patch 1: add support for the new feature;
- patch 2: extends to support DEFINE_*;
- patch 3: document two media vars;
- patch 4: fix an issue on kernel-doc.rst markups and automarkup;
- patch 5: document it;
- patch 6: better handle DEFINE_ macros when they don't have static/type;
Since version 5, I'm using "c:macro" to describe variables, as it
avoids Sphinx C domain to try parse the variable. This makes it more
flexible and easier to maintain in long term.
