kernel/linux.git/Documentation/locking/index.rst, branch linux-7.1.y

Documentation: use a source-read extension for the index link boilerplate

2026-01-23T18:59:34+00:00

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 Cc: Mauro Carvalho Chehab Cc: Randy Dunlap Signed-off-by: Jani Nikula Tested-by: Mauro Carvalho Chehab Reviewed-by: Mauro Carvalho Chehab [jc: did s/doctree/kern_doc_dir/ ] Signed-off-by: Jonathan Corbet Message-ID: <20260123143149.2024303-1-jani.nikula@intel.com>

Documentation: use capitalization for chapters and acronyms

2023-05-16T18:49:31+00:00

Use capital letters in acronyms for CD-ROM, FPGA, and PCMCIA. Use capital letter in the first word of chapter headings for Locking, Timers, and "Brief tutorial on CRC computation". Signed-off-by: Randy Dunlap Cc: Moritz Fischer Cc: Wu Hao Cc: Tom Rix Cc: Peter Zijlstra Cc: Ingo Molnar Cc: Will Deacon Cc: Waiman Long Cc: Boqun Feng Cc: Dominik Brodowski Cc: Thomas Gleixner Acked-by: Xu Yilun Reviewed-by: Phillip Potter Link: https://lore.kernel.org/r/20230516001518.14514-1-rdunlap@infradead.org Signed-off-by: Jonathan Corbet

Documentation: locking: Describe seqlock design and usage

2020-07-29T14:14:22+00:00

Proper documentation for the design and usage of sequence counters and sequential locks does not exist. Complete the seqlock.h documentation as follows: - Divide all documentation on a seqcount_t vs. seqlock_t basis. The description for both mechanisms was intermingled, which is incorrect since the usage constrains for each type are vastly different. - Add an introductory paragraph describing the internal design of, and rationale for, sequence counters. - Document seqcount_t writer non-preemptibility requirement, which was not previously documented anywhere, and provide a clear rationale. - Provide template code for seqcount_t and seqlock_t initialization and reader/writer critical sections. - Recommend using seqlock_t by default. It implicitly handles the serialization and non-preemptibility requirements of writers. At seqlock.h: - Remove references to brlocks as they've long been removed from the kernel. - Remove references to gcc-3.x since the kernel's minimum supported gcc version is 4.9. References: 0f6ed63b1707 ("no need to keep brlock macros anymore...") References: 6ec4476ac825 ("Raise gcc version requirement to 4.9") Signed-off-by: Ahmed S. Darwish Signed-off-by: Peter Zijlstra (Intel) Link: https://lkml.kernel.org/r/20200720155530.1173732-2-a.darwish@linutronix.de

docs: move locking-specific documents to locking/

2020-05-15T18:05:07+00:00

Several files under Documentation/*.txt describe some type of locking API. Move them to locking/ subdir and add to the locking/index.rst index file. Signed-off-by: Mauro Carvalho Chehab Link: https://lore.kernel.org/r/dd833a10bbd0b2c1461d78913f5ec28a7e27f00b.1588345503.git.mchehab+huawei@kernel.org Signed-off-by: Jonathan Corbet

Documentation: Add lock ordering and nesting documentation

2020-03-21T15:00:23+00:00

The kernel provides a variety of locking primitives. The nesting of these lock types and the implications of them on RT enabled kernels is nowhere documented. Add initial documentation. Signed-off-by: Thomas Gleixner Signed-off-by: Peter Zijlstra (Intel) Link: https://lkml.kernel.org/r/20200321113242.026561244@linutronix.de

docs: locking: add it to the main index

2019-07-15T14:03:03+00:00

The locking directory is part of the Kernel API bookset. Add it to the index file. Signed-off-by: Mauro Carvalho Chehab

docs: locking: convert docs to ReST and rename to *.rst

2019-07-15T11:53:27+00:00

Convert the locking documents to ReST and add them to the kernel development book where it belongs. Most of the stuff here is just to make Sphinx to properly parse the text file, as they're already in good shape, not requiring massive changes in order to be parsed. The conversion is actually: - add blank lines and identation in order to identify paragraphs; - fix tables markups; - add some lists markups; - mark literal blocks; - adjust title markups. At its new index.rst, let's add a :orphan: while this is not linked to the main index.rst file, in order to avoid build warnings. Signed-off-by: Mauro Carvalho Chehab Acked-by: Federico Vaga