linux-stable.git/Documentation/locking, branch master Linux kernel stable tree Merge tag 'docs-7.2' of git://git.kernel.org/pub/scm/linux/kernel/git/docs/linux 2026-06-16T03:05:59+00:00 Linus Torvalds torvalds@linux-foundation.org 2026-06-16T03:05:59+00:00 a87bbc4578fd686d535fbd62e8bc73fc6c7c5415 Pull documentation updates from Jonathan Corbet: "Things have calmed down a bit on the docs front, with no earthshaking changes this time around: - Ongoing work on the Japanese and Portuguese translations - Better integration of the MAINTAINERS file into the rendered documents, including a search interface - A seemingly infinite supply of fixes for typos, minor grammatical issues, and related problems that LLMs find with abandon" * tag 'docs-7.2' of git://git.kernel.org/pub/scm/linux/kernel/git/docs/linux: (93 commits) docs: pt_BR: Translate 3.Early-stage.rst into Portuguese docs: pt_BR: update "Purpose of Defconfigs" section in maintainer-soc.rst Documentation: bug-hunting.rst: fix grammar docs/ja_JP: translate submitting-patches.rst (interleaved-replies) docs: Fix minor grammatical error docs/{it_it,sp_SP,zh_CN,zh_TW}: update references to removed CONFIG_DEBUG_SLAB Documentation: process: fix brackets Documentation: arch: fix brackets docs/dyndbg: explain flags parse 1st docs/dyndbg: update examples \012 to \n docs: kernel-parameters: Fix stale sticore file paths docs: real-time: Fix duplicated sched(7) text docs: kgdb: Fix stale source file paths docs: sonypi: Fix stale header file path docs: kernel-parameters: Remove sa1100ir IrDA parameter iommu: Documentation: rearrange, update kernel-parameters docs: md: fix grammar in speed_limit description docs: changes.rst: restore pahole 1.26 minimum (regressed by sort) Documentation: Fix syntax of kmalloc_objs example in coding style doc docs: pt_BR: update maintainer-handbooks ... 
Pull documentation updates from Jonathan Corbet:
 "Things have calmed down a bit on the docs front, with no earthshaking
  changes this time around:

   - Ongoing work on the Japanese and Portuguese translations

   - Better integration of the MAINTAINERS file into the rendered
     documents, including a search interface

   - A seemingly infinite supply of fixes for typos, minor grammatical
     issues, and related problems that LLMs find with abandon"

* tag 'docs-7.2' of git://git.kernel.org/pub/scm/linux/kernel/git/docs/linux: (93 commits)
  docs: pt_BR: Translate 3.Early-stage.rst into Portuguese
  docs: pt_BR: update "Purpose of Defconfigs" section in maintainer-soc.rst
  Documentation: bug-hunting.rst: fix grammar
  docs/ja_JP: translate submitting-patches.rst (interleaved-replies)
  docs: Fix minor grammatical error
  docs/{it_it,sp_SP,zh_CN,zh_TW}: update references to removed CONFIG_DEBUG_SLAB
  Documentation: process: fix brackets
  Documentation: arch: fix brackets
  docs/dyndbg: explain flags parse 1st
  docs/dyndbg: update examples \012 to \n
  docs: kernel-parameters: Fix stale sticore file paths
  docs: real-time: Fix duplicated sched(7) text
  docs: kgdb: Fix stale source file paths
  docs: sonypi: Fix stale header file path
  docs: kernel-parameters: Remove sa1100ir IrDA parameter
  iommu: Documentation: rearrange, update kernel-parameters
  docs: md: fix grammar in speed_limit description
  docs: changes.rst: restore pahole 1.26 minimum (regressed by sort)
  Documentation: Fix syntax of kmalloc_objs example in coding style doc
  docs: pt_BR: update maintainer-handbooks
  ...
Documentation: futex: Add a note about robust list race condition 2026-06-03T09:38:52+00:00 André Almeida andrealmeid@igalia.com 2026-06-02T09:10:16+00:00 3f63e2545978abda58f2cf7ff0d7a2942965e8cb Add a note to the documentation giving a brief explanation why doing a robust futex release in userspace is racy, what should be done to avoid it and provide links to read more. [ tglx: Fixed a few typos ] Signed-off-by: André Almeida <andrealmeid@igalia.com> Signed-off-by: Thomas Gleixner <tglx@kernel.org> Signed-off-by: Peter Zijlstra (Intel) <peterz@infradead.org> Link: https://patch.msgid.link/20260329-tonyk-vdso_test-v2-1-b7db810e44a1@igalia.com Link: https://patch.msgid.link/20260602090535.936286833@kernel.org 
Add a note to the documentation giving a brief explanation why doing a
robust futex release in userspace is racy, what should be done to avoid
it and provide links to read more.

[ tglx: Fixed a few typos ]

Signed-off-by: André Almeida <andrealmeid@igalia.com>
Signed-off-by: Thomas Gleixner <tglx@kernel.org>
Signed-off-by: Peter Zijlstra (Intel) <peterz@infradead.org>
Link: https://patch.msgid.link/20260329-tonyk-vdso_test-v2-1-b7db810e44a1@igalia.com
Link: https://patch.msgid.link/20260602090535.936286833@kernel.org
futex: Move futex task related data into a struct 2026-06-03T09:38:49+00:00 Thomas Gleixner tglx@kernel.org 2026-06-02T09:09:25+00:00 c1ffc9c6e4f8a13dd68e97920c9a24d095c6e41a Having all these members in task_struct along with the required #ifdeffery is annoying, does not allow efficient initializing of the data with memset() and makes extending it tedious. Move it into a data structure and fix up all usage sites. Signed-off-by: Thomas Gleixner <tglx@kernel.org> Signed-off-by: Peter Zijlstra (Intel) <peterz@infradead.org> Reviewed-by: Mathieu Desnoyers <mathieu.desnoyers@efficios.com> Reviewed-by: André Almeida <andrealmeid@igalia.com> Link: https://patch.msgid.link/20260602090535.308220888@kernel.org 
Having all these members in task_struct along with the required #ifdeffery
is annoying, does not allow efficient initializing of the data with
memset() and makes extending it tedious.

Move it into a data structure and fix up all usage sites.

Signed-off-by: Thomas Gleixner <tglx@kernel.org>
Signed-off-by: Peter Zijlstra (Intel) <peterz@infradead.org>
Reviewed-by: Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
Reviewed-by: André Almeida <andrealmeid@igalia.com>
Link: https://patch.msgid.link/20260602090535.308220888@kernel.org
Documentation: adopt new coding style of type-aware kmalloc-family 2026-05-03T14:54:21+00:00 Manuel Ebner manuelebner@mailbox.org 2026-04-29T07:14:44+00:00 7c6d969d5349c40348276d5c301b2d200afa623d Update the documentation to reflect new type-aware kmalloc-family as suggested in commit 2932ba8d9c99 ("slab: Introduce kmalloc_obj() and family") ptr = kmalloc(sizeof(*ptr), gfp); -> ptr = kmalloc_obj(*ptr, gfp); ptr = kmalloc(sizeof(struct some_obj_name), gfp); -> ptr = kmalloc_obj(*ptr, gfp); ptr = kzalloc(sizeof(*ptr), gfp); -> ptr = kzalloc_obj(*ptr, gfp); ptr = kmalloc_array(count, sizeof(*ptr), gfp); -> ptr = kmalloc_objs(*ptr, count, gfp); ptr = kcalloc(count, sizeof(*ptr), gfp); -> ptr = kzalloc_objs(*ptr, count, gfp); Signed-off-by: Manuel Ebner <manuelebner@mailbox.org> Acked-by: SeongJae Park <sj@kernel.org> Acked-by: Vlastimil Babka (SUSE) <vbabka@kernel.org> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <20260429071445.309733-2-manuelebner@mailbox.org> 
Update the documentation to reflect new type-aware kmalloc-family as
suggested in commit 2932ba8d9c99 ("slab: Introduce kmalloc_obj()
and family")

ptr = kmalloc(sizeof(*ptr), gfp);
 -> ptr = kmalloc_obj(*ptr, gfp);
ptr = kmalloc(sizeof(struct some_obj_name), gfp);
 -> ptr = kmalloc_obj(*ptr, gfp);
ptr = kzalloc(sizeof(*ptr), gfp);
 -> ptr = kzalloc_obj(*ptr, gfp);
ptr = kmalloc_array(count, sizeof(*ptr), gfp);
 -> ptr = kmalloc_objs(*ptr, count, gfp);
ptr = kcalloc(count, sizeof(*ptr), gfp);
 -> ptr = kzalloc_objs(*ptr, count, gfp);

Signed-off-by: Manuel Ebner <manuelebner@mailbox.org>
Acked-by: SeongJae Park <sj@kernel.org>
Acked-by: Vlastimil Babka (SUSE) <vbabka@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260429071445.309733-2-manuelebner@mailbox.org>
Documentation: use a source-read extension for the index link boilerplate 2026-01-23T18:59:34+00:00 Jani Nikula jani.nikula@intel.com 2026-01-23T14:31:49+00:00 a592a36e49372172d7c7551ec19ed18184c935e1 The root document usually has a special :ref:`genindex` link to the generated index. This is also the case for Documentation/index.rst. The other index.rst files deeper in the directory hierarchy usually don't. For SPHINXDIRS builds, the root document isn't Documentation/index.rst, but some other index.rst in the hierarchy. Currently they have a ".. only::" block to add the index link when doing SPHINXDIRS html builds. This is obviously very tedious and repetitive. The link is also added to all index.rst files in the hierarchy for SPHINXDIRS builds, not just the root document. Put the boilerplate in a sphinx-includes/subproject-index.rst file, and include it at the end of the root document for subproject builds in an ad-hoc source-read extension defined in conf.py. For now, keep having the boilerplate in translations, because this approach currently doesn't cover translated index link headers. Cc: Jonathan Corbet <corbet@lwn.net> Cc: Mauro Carvalho Chehab <mchehab@kernel.org> Cc: Randy Dunlap <rdunlap@infradead.org> Signed-off-by: Jani Nikula <jani.nikula@intel.com> Tested-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org> [jc: did s/doctree/kern_doc_dir/ ] Signed-off-by: Jonathan Corbet <corbet@lwn.net> Message-ID: <20260123143149.2024303-1-jani.nikula@intel.com> 
The root document usually has a special :ref:`genindex` link to the
generated index. This is also the case for Documentation/index.rst. The
other index.rst files deeper in the directory hierarchy usually don't.

For SPHINXDIRS builds, the root document isn't Documentation/index.rst,
but some other index.rst in the hierarchy. Currently they have a
".. only::" block to add the index link when doing SPHINXDIRS html
builds.

This is obviously very tedious and repetitive. The link is also added to
all index.rst files in the hierarchy for SPHINXDIRS builds, not just the
root document.

Put the boilerplate in a sphinx-includes/subproject-index.rst file, and
include it at the end of the root document for subproject builds in an
ad-hoc source-read extension defined in conf.py.

For now, keep having the boilerplate in translations, because this
approach currently doesn't cover translated index link headers.

Cc: Jonathan Corbet <corbet@lwn.net>
Cc: Mauro Carvalho Chehab <mchehab@kernel.org>
Cc: Randy Dunlap <rdunlap@infradead.org>
Signed-off-by: Jani Nikula <jani.nikula@intel.com>
Tested-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
[jc: did s/doctree/kern_doc_dir/ ]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <20260123143149.2024303-1-jani.nikula@intel.com>
documentation: seqlock: fix the wrong documentation of read_seqbegin_or_lock/need_seqretry 2025-10-21T10:31:56+00:00 Oleg Nesterov oleg@redhat.com 2025-09-28T16:20:29+00:00 28a0ee311960baad97bf85e1e995aed4a71e22a2 The comments and pseudo code in Documentation/locking/seqlock.rst are wrong: int seq = 0; do { read_seqbegin_or_lock(&foo_seqlock, &seq); /* ... [[read-side critical section]] ... */ } while (need_seqretry(&foo_seqlock, seq)); read_seqbegin_or_lock() always returns with an even "seq" and need_seqretry() doesn't change this counter. This means that seq is always even and thus the locking pass is simply impossible. IOW, "_or_lock" has no effect and this code doesn't differ from do { seq = read_seqbegin(&foo_seqlock); /* ... [[read-side critical section]] ... */ } while (read_seqretry(&foo_seqlock, seq)); Signed-off-by: Oleg Nesterov <oleg@redhat.com> Signed-off-by: Peter Zijlstra (Intel) <peterz@infradead.org> 
The comments and pseudo code in Documentation/locking/seqlock.rst are wrong:

	int seq = 0;
	do {
		read_seqbegin_or_lock(&foo_seqlock, &seq);

		/* ... [[read-side critical section]] ... */

	} while (need_seqretry(&foo_seqlock, seq));

read_seqbegin_or_lock() always returns with an even "seq" and need_seqretry()
doesn't change this counter. This means that seq is always even and thus the
locking pass is simply impossible.

IOW, "_or_lock" has no effect and this code doesn't differ from

	do {
		seq = read_seqbegin(&foo_seqlock);

		/* ... [[read-side critical section]] ... */

	} while (read_seqretry(&foo_seqlock, seq));

Signed-off-by: Oleg Nesterov <oleg@redhat.com>
Signed-off-by: Peter Zijlstra (Intel) <peterz@infradead.org>
Documentation: locking: Add local_lock_nested_bh() to locktypes 2025-08-21T18:52:20+00:00 Sebastian Andrzej Siewior bigeasy@linutronix.de 2025-08-15T09:38:56+00:00 f41c808c43883d3d7b46e7742a93127acb81d60b local_lock_nested_bh() is used within networking where applicable. Document why it is used and how it behaves. Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20250815093858.930751-3-bigeasy@linutronix.de 
local_lock_nested_bh() is used within networking where applicable.
Document why it is used and how it behaves.

Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250815093858.930751-3-bigeasy@linutronix.de
Documentation: seqlock: Add a SPDX license identifier 2025-08-21T18:52:20+00:00 Sebastian Andrzej Siewior bigeasy@linutronix.de 2025-08-15T09:38:55+00:00 9256019241c9afdd7b27d4b97e9568f5721d97e3 Add a SPDX identifier. The majority of the document has been written by Ahmed S. Darwish. Cc: Ahmed S. Darwish <darwi@linutronix.de> Acked-by: Ahmed S. Darwish <darwi@linutronix.de> Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de> Signed-off-by: Jonathan Corbet <corbet@lwn.net> Link: https://lore.kernel.org/r/20250815093858.930751-2-bigeasy@linutronix.de 
Add a SPDX identifier. The majority of the document has been written by
Ahmed S. Darwish.

Cc: Ahmed S. Darwish <darwi@linutronix.de>
Acked-by: Ahmed S. Darwish <darwi@linutronix.de>
Signed-off-by: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Link: https://lore.kernel.org/r/20250815093858.930751-2-bigeasy@linutronix.de
hwspinlock: Remove unused hwspin_lock_get_id() 2025-03-21T22:12:04+00:00 Dr. David Alan Gilbert linux@treblig.org 2024-12-15T02:20:23+00:00 fec04edb74126f21ac628c7be763c97deb49f69d hwspin_lock_get_id() has been unused since the original 2011 commit bd9a4c7df256 ("drivers: hwspinlock: add framework") Remove it and the corresponding docs. Note that the of_hwspin_lock_get_id() version is still in use, so leave that alone. Signed-off-by: Dr. David Alan Gilbert <linux@treblig.org> Reviewed-by: Baolin Wang <baolin.wang@linux.alibaba.com> Link: https://lore.kernel.org/r/20241215022023.181435-1-linux@treblig.org Signed-off-by: Bjorn Andersson <andersson@kernel.org> 
hwspin_lock_get_id() has been unused since the original 2011
commit bd9a4c7df256 ("drivers: hwspinlock: add framework")

Remove it and the corresponding docs.

Note that the of_hwspin_lock_get_id() version is still in use,
so leave that alone.

Signed-off-by: Dr. David Alan Gilbert <linux@treblig.org>
Reviewed-by: Baolin Wang <baolin.wang@linux.alibaba.com>
Link: https://lore.kernel.org/r/20241215022023.181435-1-linux@treblig.org
Signed-off-by: Bjorn Andersson <andersson@kernel.org>
hwspinlock: Remove unused (devm_)hwspin_lock_request() 2025-03-21T22:12:04+00:00 Dr. David Alan Gilbert linux@treblig.org 2024-10-27T20:54:45+00:00 e9a3682d17d5afee697fc95d3fa342d740767fad devm_hwspin_lock_request() was added by 2018's commit 4f1acd758b08 ("hwspinlock: Add devm_xxx() APIs to request/free hwlock") however, it's never been used, everyone uses the devm_hwspin_lock_request_specific() call instead. Remove it. Similarly, the none-devm variant isn't used. Remove it, and the referring documentation. Signed-off-by: Dr. David Alan Gilbert <linux@treblig.org> Reviewed-by: Baolin Wang <baolin.wang@linux.alibaba.com> Link: https://lore.kernel.org/r/20241027205445.239108-1-linux@treblig.org Signed-off-by: Bjorn Andersson <andersson@kernel.org> 
devm_hwspin_lock_request() was added by 2018's
commit 4f1acd758b08 ("hwspinlock: Add devm_xxx() APIs to request/free
hwlock") however, it's never been used, everyone uses the
devm_hwspin_lock_request_specific() call instead.

Remove it.

Similarly, the none-devm variant isn't used.
Remove it, and the referring documentation.

Signed-off-by: Dr. David Alan Gilbert <linux@treblig.org>
Reviewed-by: Baolin Wang <baolin.wang@linux.alibaba.com>
Link: https://lore.kernel.org/r/20241027205445.239108-1-linux@treblig.org
Signed-off-by: Bjorn Andersson <andersson@kernel.org>