| Age | Commit message (Collapse) | Author |
|---|
|
When doing performance tuning or debugging performance regressions,
more and more cases are found to be related to false sharing [1][2][3],
and the situation can be worse for newer platforms with hundreds of
CPUs. There are already many commits in current kernel specially
for mitigating the performance degradation due to false sharing.
False sharing could harm the performance silently without being
noticed, due to reasons like:
* data members of a big data structure randomly sitting together
in one cache line
* global data of small size are linked compactly together
So it's better to make a simple document about the normal pattern
of false sharing, basic ways to mitigate it and call out to
developers to pay attention during code-writing.
[ Many thanks to Dave Hansen, Ying Huang, Tim Chen, Julie Du and
Yu Chen for their contributions ]
[1]. https://lore.kernel.org/lkml/20220619150456.GB34471@xsang-OptiPlex-9020/
[2]. https://lore.kernel.org/lkml/20201102091543.GM31092@shao2-debian/
[3]. https://lore.kernel.org/lkml/20230307125538.818862491@linutronix.de/
Signed-off-by: Feng Tang <feng.tang@intel.com>
Reviewed-by: Randy Dunlap <rdunlap@infradead.org>
Reviewed-by: Shakeel Butt <shakeelb@google.com>
Link: https://lore.kernel.org/r/20230407041235.37886-1-feng.tang@intel.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Correct the example in the documentation so that disable_irq() is not being
called in atomic context.
disable_irq() calls sleeping synchronize_irq(), it's not allowed to call
them in atomic context.
Signed-off-by: Alexander Sverdlin <alexander.sverdlin@siemens.com>
Signed-off-by: Thomas Gleixner <tglx@linutronix.de>
Reviewed-by: Manfred Spraul <manfred@colorfullife.com>
Cc: linux-doc@vger.kernel.org
Link: https://lore.kernel.org/lkml/87k02wbs2n.ffs@tglx/
Link: https://lore.kernel.org/r/20221212163715.830315-1-alexander.sverdlin@siemens.com
|
|
git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip
Pull timer updates from Thomas Gleixner:
"Updates for timers, timekeeping and drivers:
Core:
- The timer_shutdown[_sync]() infrastructure:
Tearing down timers can be tedious when there are circular
dependencies to other things which need to be torn down. A prime
example is timer and workqueue where the timer schedules work and
the work arms the timer.
What needs to prevented is that pending work which is drained via
destroy_workqueue() does not rearm the previously shutdown timer.
Nothing in that shutdown sequence relies on the timer being
functional.
The conclusion was that the semantics of timer_shutdown_sync()
should be:
- timer is not enqueued
- timer callback is not running
- timer cannot be rearmed
Preventing the rearming of shutdown timers is done by discarding
rearm attempts silently.
A warning for the case that a rearm attempt of a shutdown timer is
detected would not be really helpful because it's entirely unclear
how it should be acted upon. The only way to address such a case is
to add 'if (in_shutdown)' conditionals all over the place. This is
error prone and in most cases of teardown not required all.
- The real fix for the bluetooth HCI teardown based on
timer_shutdown_sync().
A larger scale conversion to timer_shutdown_sync() is work in
progress.
- Consolidation of VDSO time namespace helper functions
- Small fixes for timer and timerqueue
Drivers:
- Prevent integer overflow on the XGene-1 TVAL register which causes
an never ending interrupt storm.
- The usual set of new device tree bindings
- Small fixes and improvements all over the place"
* tag 'timers-core-2022-12-10' of git://git.kernel.org/pub/scm/linux/kernel/git/tip/tip: (34 commits)
dt-bindings: timer: renesas,cmt: Add r8a779g0 CMT support
dt-bindings: timer: renesas,tmu: Add r8a779g0 support
clocksource/drivers/arm_arch_timer: Use kstrtobool() instead of strtobool()
clocksource/drivers/timer-ti-dm: Fix missing clk_disable_unprepare in dmtimer_systimer_init_clock()
clocksource/drivers/timer-ti-dm: Clear settings on probe and free
clocksource/drivers/timer-ti-dm: Make timer_get_irq static
clocksource/drivers/timer-ti-dm: Fix warning for omap_timer_match
clocksource/drivers/arm_arch_timer: Fix XGene-1 TVAL register math error
clocksource/drivers/timer-npcm7xx: Enable timer 1 clock before use
dt-bindings: timer: nuvoton,npcm7xx-timer: Allow specifying all clocks
dt-bindings: timer: rockchip: Add rockchip,rk3128-timer
clockevents: Repair kernel-doc for clockevent_delta2ns()
clocksource/drivers/ingenic-ost: Define pm functions properly in platform_driver struct
clocksource/drivers/sh_cmt: Access registers according to spec
vdso/timens: Refactor copy-pasted find_timens_vvar_page() helper into one copy
Bluetooth: hci_qca: Fix the teardown problem for real
timers: Update the documentation to reflect on the new timer_shutdown() API
timers: Provide timer_shutdown[_sync]()
timers: Add shutdown mechanism to the internal functions
timers: Split [try_to_]del_timer[_sync]() to prepare for shutdown mode
...
|
|
In order to make sure that a timer is not re-armed after it is stopped
before freeing, a new shutdown state is added to the timer code. The API
timer_shutdown_sync() and timer_shutdown() must be called before the
object that holds the timer can be freed.
Update the documentation to reflect this new workflow.
[ tglx: Updated to the new semantics and updated the zh_CN version ]
Signed-off-by: Steven Rostedt (Google) <rostedt@goodmis.org>
Signed-off-by: Thomas Gleixner <tglx@linutronix.de>
Tested-by: Guenter Roeck <linux@roeck-us.net>
Reviewed-by: Jacob Keller <jacob.e.keller@intel.com>
Reviewed-by: Anna-Maria Behnsen <anna-maria@linutronix.de>
Link: https://lore.kernel.org/r/20221110064147.712934793@goodmis.org
Link: https://lore.kernel.org/r/20221123201625.375284489@linutronix.de
|
|
Adjust to the new preferred function names.
Suggested-by: Steven Rostedt <rostedt@goodmis.org>
Signed-off-by: Thomas Gleixner <tglx@linutronix.de>
Reviewed-by: Jacob Keller <jacob.e.keller@intel.com>
Reviewed-by: Anna-Maria Behnsen <anna-maria@linutronix.de>
Link: https://lore.kernel.org/r/20221123201625.075320635@linutronix.de
|
|
del_timer_sync() does not return the number of times it tried to delete the
timer which rearms itself. It's clearly documented:
The function returns whether it has deactivated a pending timer or not.
This part of the documentation is from 2003 where del_timer_sync() really
returned the number of deletion attempts for unknown reasons. The code
was rewritten in 2005, but the documentation was not updated.
Signed-off-by: Thomas Gleixner <tglx@linutronix.de>
Reviewed-by: Jacob Keller <jacob.e.keller@intel.com>
Reviewed-by: Anna-Maria Behnsen <anna-maria@linutronix.de>
Link: https://lore.kernel.org/r/20221123201624.452282769@linutronix.de
|
|
Fix `botton half locks` to `bottom half locks`.
Signed-off-by: Mushahid Hussain <mushi.shar@gmail.com>
Link: https://lore.kernel.org/r/20221017112026.88324-1-mushi.shar@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Commit 31b24bee3357 ("docs: add a warning to submitting-drivers.rst")
in October 2016 already warns "This (...) should maybe just be deleted,
but I'm not quite ready to do that yet".
Maybe, six years ago, we were not ready but let us remove old content
for the better now and structure and maintain less content in the kernel
documentation with a better result.
Drop this already outdated document and adjust all textual references.
Here is an argument why deleting the content will not remove any useful
information to the existing kernel documentation, individually broken down
for each section.
Section "Allocating Device Numbers" refers to https://www.lanana.org/, and
then refers to Documentation/admin-guide/devices.rst.
However, the devices.rst clearly states:
"The version of this document at lanana.org is no longer maintained."
Everything needed for submitting drivers is already stated in devices.rst
and the reference to https://www.lanana.org/ is outdated, and should be
just deleted.
Section "Who To Submit Drivers To" is all about Linux 2.0 - 2.6, before
the new release version scheme; the mentioned developers are still around,
but actually not the first developers to contact anymore.
Section "What Criteria Determine Acceptance" has a few bullet points:
Licensing and Copyright is well-covered in process/kernel-license.rst.
Interfaces, Code, Portability, Clarity state some obvious things about
ensuring kernel code quality.
Control suggests to add a MAINTAINERS entry, which is already mentioned in
6.Followthrough.rst: "... added yourself to the MAINTAINERS file..."
PM support states a bit about implementing and testing power management of
a driver, it remains an open question where to place that in the process
documents. Driver developers interested in power management will find the
corresponding part on power management in the kernel documentation anyway.
In section "What Criteria Do Not Determine Acceptance", the points Vendor
and Author states something basic consequence of the kernel being an
open-source community software development. Probably no need to mention it
nowadays.
Section "Resources" lists resources that are also mentioned elsewhere more
central.
- Linux kernel tree and mailing list is mentioned in many places.
- https://lwn.net/Kernel/LDD3/ is mentioned in
Documentation/process/kernel-docs.rst.
- https://lwn.net/ is mentioned in:
- Documentation/process/8.Conclusion.rst
- Documentation/process/kernel-docs.rst
- https://kernelnewbies.org/ is mentioned in:
- Documentation/process/8.Conclusion.rst
- Documentation/process/kernel-docs.rst
- http://www.linux-usb.org/ is mentioned in
Documentation/driver-api/usb/usb.rst
- https://landley.net/kdocs/ols/2002/ols2002-pages-545-555.pdf
is mentioned in Documentation/process/kernel-docs.rst
- https://kernelnewbies.org/KernelJanitors is mentioned in
Documentation/process/howto.rst
- https://git-scm.com/ is mentioned in
- Documentation/process/2.Process.rst
- Documentation/process/7.AdvancedTopics.rst
- Documentation/process/howto.rst
Signed-off-by: Lukas Bulwahn <lukas.bulwahn@gmail.com>
Link: https://lore.kernel.org/r/20220704122537.3407-7-lukas.bulwahn@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Rusty's kernel-hacking guides provide important information, however
they are written in a narrative style that some readers may interpret as
off-putting. Since the goal is to make kernel documentation accessible
to as many new developers as possible, it's best to avoid the turns of
phrase that require a specific cultural context to properly understand.
Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Change copy_from_user*( to copy_from_user() .
Signed-off-by: Takahiro Itazuri <itazur@amazon.com>
Link: https://lore.kernel.org/r/20220124081447.34066-1-itazur@amazon.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Since the futex code was restructured, there's no futex.c file anymore
and the implementation is split in various files. Point kernel-doc
references to the new files.
Signed-off-by: André Almeida <andrealmeid@collabora.com>
Signed-off-by: Peter Zijlstra (Intel) <peterz@infradead.org>
Link: https://lkml.kernel.org/r/20211012135549.14451-1-andrealmeid@collabora.com
|
|
Remove inappropriate sexual (and ableist) text from the locking
documentation, aligning it with the kernel code-of-conduct. As the text
was unrelated to locking, this change streamlines the document and
improves readability.
Signed-off-by: Alyssa Rosenzweig <alyssa@rosenzweig.io>
Link: https://lore.kernel.org/r/20210903151826.6300-1-alyssa@rosenzweig.io
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Replace the obsolete and ambiguos macro in_irq() with new
macro in_hardirq().
Signed-off-by: Changbin Du <changbin.du@gmail.com>
Link: https://lore.kernel.org/r/20210814014831.53083-1-changbin.du@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
The :doc:`foo` tag is auto-generated via automarkup.py.
So, use the filename at the sources, instead of :doc:`foo`.
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/9537b74d897fab13552535d79337060a3b241b8c.1623824363.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Remove the f-bomb from locking.rst. Let's have a moment of silence,
though, as we mark the passing of the last of Rusty's once plentiful
profanities in this venerable document.
Signed-off-by: Bhaskar Chowdhury <unixbhaskar@gmail.com>
Link: https://lore.kernel.org/r/20210205115951.1276526-1-unixbhaskar@gmail.com
[jc: rewrote changelog]
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Change 'current()' heading to 'current' to reflect usage.
Signed-off-by: Joe Pater <02joepater06@gmail.com>
Link: https://lore.kernel.org/r/20210111103240.7445-1-02joepater06@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
During the process of converting the documentation to reST, some links
were converted using the following wrong syntax (and sometimes using %20
instead of spaces):
`Display text <#section-name-in-html>`__
This syntax isn't valid according to the docutils' spec [1], but more
importantly, it is specific to HTML, since it uses '#' to link to an
HTML anchor.
The right syntax would instead use a docutils hyperlink reference as the
embedded URI to point to the section [2], that is:
`Display text <Section Name_>`__
This syntax works in both HTML and PDF.
The LaTeX toolchain doesn't mind the HTML anchor syntax when generating
the pdf documentation (make pdfdocs), that is, the build succeeds but
the links don't work, but that syntax causes errors when trying to build
using the not-yet-merged rst2pdf:
ValueError: format not resolved, probably missing URL scheme or undefined destination target for 'Forcing%20Quiescent%20States'
So, use the correct syntax in order to have it work in all different
output formats.
[1]: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#reference-names
[2]: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#embedded-uris-and-aliases
Fixes: ccc9971e2147 ("docs: rcu: convert some articles from html to ReST")
Fixes: c8cce10a62aa ("docs: Fix the reference labels in Locking.rst")
Fixes: e548cdeffcd8 ("docs-rst: convert kernel-locking to ReST")
Fixes: 7ddedebb03b7 ("ALSA: doc: ReSTize writing-an-alsa-driver document")
Signed-off-by: Nícolas F. R. A. Prado <nfraprado@protonmail.com>
Reviewed-by: Takashi Iwai <tiwai@suse.de>
Reviewed-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/20201228144537.135353-1-nfraprado@protonmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
The kernel doc tooling knows how to do this itself so drop this markup
throughout this file to simplify.
Suggested-by: Jonathan Corbet <corbet@lwn.net>
Signed-off-by: Stephen Boyd <swboyd@chromium.org>
Link: https://lore.kernel.org/r/20200318174133.160206-3-swboyd@chromium.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Add the missing word to make this sentence read properly.
Signed-off-by: Stephen Boyd <swboyd@chromium.org>
Link: https://lore.kernel.org/r/20200318174133.160206-2-swboyd@chromium.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Changeset 58ad30cf91f0 ("docs: fix reference to core-api/namespaces.rst")
enabled a new feature at Sphinx: it will now generate index for each
document title, plus to each chapter inside it.
There's a drawback, though: one document cannot have two sections
with the same name anymore.
A followup patch will change the logic of autosectionlabel to
avoid most creating references for every single section title,
but still we need to be able to reference the chapters inside
a document.
There are a few places where there are two chapters with the
same name. This patch renames one of the chapters, in order to
avoid symbol conflict within the same document.
PS.: as I don't speach Chinese, I had some help from a friend
(Wen Liu) at the Chinese translation for "publishing patches"
for this document:
Documentation/translations/zh_CN/process/5.Posting.rst
Fixes: 58ad30cf91f0 ("docs: fix reference to core-api/namespaces.rst")
Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Link: https://lore.kernel.org/r/2bffb91e4a63d41bf5fae1c23e1e8b3bba0b8806.1584716446.git.mchehab+huawei@kernel.org
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Fix a couple of dangling links to core-api/namespaces.rst by turning them
into proper references. Enable the autosection extension (available since
Sphinx 1.4) to make this work.
Co-developed-by: Federico Vaga <federico.vaga@vaga.pv.it>
Fixes: fcfacb9f8374 ("doc: move namespaces.rst from kbuild/ to core-api/")
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
namespaces.rst to symbol-namespaces.rst
This patch fixes the following documentation build warning:
Warning: Documentation/kernel-hacking/hacking.rst references
a file that doesn't exist: Documentation/kbuild/namespaces.rst
According to the following patch:
https://patchwork.kernel.org/patch/11178727/
(doc: move namespaces.rst from kbuild/ to core-api/)
The file namespaces.rst was moved from kbuild to core-api
and renamed to symbol-namespaces.rst.
Therefore, this patch changes the reference to the document
kbuild/namespaces.rst in hacking.rst to
core-api/symbol-namespaces.rst
Signed-off-by: Madhuparna Bhowmik <madhuparnabhowmik04@gmail.com>
Link: https://lore.kernel.org/r/20191204104554.9100-1-madhuparnabhowmik04@gmail.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Describe using Symbol Namespaces from a perspective of a user. I.e.
module authors or subsystem maintainers.
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Signed-off-by: Matthias Maennich <maennich@google.com>
Signed-off-by: Jessica Yu <jeyu@kernel.org>
|
|
Now that the latex_documents are handled automatically, we can
remove those extra conf.py files.
Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
|
|
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 <mchehab+samsung@kernel.org>
Acked-by: Federico Vaga <federico.vaga@vaga.pv.it>
|
|
Since strlcpy is deprecated, the documentation shouldn't suggest using
it. This patch fixes the examples to use strscpy instead. It also uses
sizeof instead of underlying constants as far as possible, to simplify
future changes to the corresponding data structures.
Signed-off-by: Stephen Kitt <steve@sk2.org>
Acked-by: Kees Cook <keescook@chromium.org>
Acked-by: Federico Vaga <federico.vaga@vaga.pv.it>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
The kbuild documentation clearly shows that the documents
there are written at different times: some use markdown,
some use their own peculiar logic to split sections.
Convert everything to ReST without affecting too much
the author's style and avoiding adding uneeded markups.
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 <mchehab+samsung@kernel.org>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
This patch includes the kernel-hacking translation in Italian (both
hacking.rst and locking.rst).
It adds also the anchors for the english kernel-hacking documents.
Signed-off-by: Federico Vaga <federico.vaga@vaga.pv.it>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Two jump tags were misspelled, leading to non-working cross-reference
links.
Reported-by: Federico Vaga <federico.vaga@vaga.pv.it>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
The idea is to make it easier to create references (doc-guide does the same).
This will be used, for example but not only, in translations to point to
the main document.
Signed-off-by: Federico Vaga <federico.vaga@vaga.pv.it>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
At some stage of the conversion pipeline, something thought that the
DocBook entity # should be rendered as NUM instead of #.
Signed-off-by: Matthew Wilcox <mawilcox@microsoft.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Corrected a typo.
Signed-off-by: Marco Donato Torsello <marcodonato.torsello@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
|
|
Pull documentation updates from Jonathan Corbet:
"There has been a fair amount of activity in the docs tree this time
around. Highlights include:
- Conversion of a bunch of security documentation into RST
- The conversion of the remaining DocBook templates by The Amazing
Mauro Machine. We can now drop the entire DocBook build chain.
- The usual collection of fixes and minor updates"
* tag 'docs-4.13' of git://git.lwn.net/linux: (90 commits)
scripts/kernel-doc: handle DECLARE_HASHTABLE
Documentation: atomic_ops.txt is core-api/atomic_ops.rst
Docs: clean up some DocBook loose ends
Make the main documentation title less Geocities
Docs: Use kernel-figure in vidioc-g-selection.rst
Docs: fix table problems in ras.rst
Docs: Fix breakage with Sphinx 1.5 and upper
Docs: Include the Latex "ifthen" package
doc/kokr/howto: Only send regression fixes after -rc1
docs-rst: fix broken links to dynamic-debug-howto in kernel-parameters
doc: Document suitability of IBM Verse for kernel development
Doc: fix a markup error in coding-style.rst
docs: driver-api: i2c: remove some outdated information
Documentation: DMA API: fix a typo in a function name
Docs: Insert missing space to separate link from text
doc/ko_KR/memory-barriers: Update control-dependencies example
Documentation, kbuild: fix typo "minimun" -> "minimum"
docs: Fix some formatting issues in request-key.rst
doc: ReSTify keys-trusted-encrypted.txt
doc: ReSTify keys-request-key.txt
...
|
|
Correct a few minor issues with ReST notation used on
this file (produced by an automatic tool).
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
|
|
Those tables have a "caption" at the end, but ReST
actually expects it on a different way.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
|
|
Use a different markup for this table, in order to make it
smaller when seeing in text mode.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
|
|
Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.
- Manually adjust tables with got broken by conversion
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
|
|
This document is fairly updated. Yet, some stuff moved to
other kernel headers. So, update to point to the right
places.
While here, adjust some minor ReST markups.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
|
|
Use pandoc to convert documentation to ReST by calling
Documentation/sphinx/tmplcvt script.
- Manually adjusted to use ..note and ..warning
- Minor fixes for it to be parsed without errors
- Use **bold** for emphasis.
Signed-off-by: Mauro Carvalho Chehab <mchehab@s-opensource.com>
|
