Documentation: Add document for false sharingWhen doing performance tuning or debugging performance regressions,more and more cases are found to be related to false sharing [1][2][3],and the situ
Documentation: Add document for false sharingWhen 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 ofCPUs. There are already many commits in current kernel speciallyfor mitigating the performance degradation due to false sharing.False sharing could harm the performance silently without beingnoticed, 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 togetherSo it's better to make a simple document about the normal patternof false sharing, basic ways to mitigate it and call out todevelopers 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.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>
show more ...
docs: locking: Discourage from calling disable_irq() in atomicCorrect the example in the documentation so that disable_irq() is not beingcalled in atomic context.disable_irq() calls sleeping syn
docs: locking: Discourage from calling disable_irq() in atomicCorrect the example in the documentation so that disable_irq() is not beingcalled in atomic context.disable_irq() calls sleeping synchronize_irq(), it's not allowed to callthem 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.orgLink: https://lore.kernel.org/lkml/87k02wbs2n.ffs@tglx/Link: https://lore.kernel.org/r/20221212163715.830315-1-alexander.sverdlin@siemens.com
Merge tag 'timers-core-2022-12-10' of git://git.kernel.org/pub/scm/linux/kernel/git/tip/tipPull timer updates from Thomas Gleixner: "Updates for timers, timekeeping and drivers: Core: - The
Merge tag 'timers-core-2022-12-10' of git://git.kernel.org/pub/scm/linux/kernel/git/tip/tipPull 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 ...
timers: Update the documentation to reflect on the new timer_shutdown() APIIn order to make sure that a timer is not re-armed after it is stoppedbefore freeing, a new shutdown state is added to th
timers: Update the documentation to reflect on the new timer_shutdown() APIIn order to make sure that a timer is not re-armed after it is stoppedbefore freeing, a new shutdown state is added to the timer code. The APItimer_shutdown_sync() and timer_shutdown() must be called before theobject 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.orgLink: https://lore.kernel.org/r/20221123201625.375284489@linutronix.de
Documentation: Replace del_timer/del_timer_sync()Adjust to the new preferred function names.Suggested-by: Steven Rostedt <rostedt@goodmis.org>Signed-off-by: Thomas Gleixner <tglx@linutronix.de>
Documentation: Replace del_timer/del_timer_sync()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
Documentation: Remove bogus claim about del_timer_sync()del_timer_sync() does not return the number of times it tried to delete thetimer which rearms itself. It's clearly documented: The functio
Documentation: Remove bogus claim about del_timer_sync()del_timer_sync() does not return the number of times it tried to delete thetimer 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() reallyreturned the number of deletion attempts for unknown reasons. The codewas 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
Documentation: Fix spelling mistake in hacking.rstFix `botton half locks` to `bottom half locks`.Signed-off-by: Mushahid Hussain <mushi.shar@gmail.com>Link: https://lore.kernel.org/r/20221017112
Documentation: Fix spelling mistake in hacking.rstFix `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.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>
docs: process: remove outdated submitting-drivers.rstCommit 31b24bee3357 ("docs: add a warning to submitting-drivers.rst")in October 2016 already warns "This (...) should maybe just be deleted,bu
docs: process: remove outdated submitting-drivers.rstCommit 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 contentfor the better now and structure and maintain less content in the kerneldocumentation 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 usefulinformation to the existing kernel documentation, individually broken downfor each section.Section "Allocating Device Numbers" refers to https://www.lanana.org/, andthen 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.rstand the reference to https://www.lanana.org/ is outdated, and should bejust deleted.Section "Who To Submit Drivers To" is all about Linux 2.0 - 2.6, beforethe 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 aboutensuring kernel code quality.Control suggests to add a MAINTAINERS entry, which is already mentioned in6.Followthrough.rst: "... added yourself to the MAINTAINERS file..."PM support states a bit about implementing and testing power management ofa driver, it remains an open question where to place that in the processdocuments. Driver developers interested in power management will find thecorresponding part on power management in the kernel documentation anyway.In section "What Criteria Do Not Determine Acceptance", the points Vendorand Author states something basic consequence of the kernel being anopen-source community software development. Probably no need to mention itnowadays.Section "Resources" lists resources that are also mentioned elsewhere morecentral. - 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.rstSigned-off-by: Lukas Bulwahn <lukas.bulwahn@gmail.com>Link: https://lore.kernel.org/r/20220704122537.3407-7-lukas.bulwahn@gmail.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>
Documentation: kernel-hacking: minor edits for styleRusty's kernel-hacking guides provide important information, howeverthey are written in a narrative style that some readers may interpret asoff
Documentation: kernel-hacking: minor edits for styleRusty's kernel-hacking guides provide important information, howeverthey are written in a narrative style that some readers may interpret asoff-putting. Since the goal is to make kernel documentation accessibleto as many new developers as possible, it's best to avoid the turns ofphrase 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>
docs: fix typo in Documentation/kernel-hacking/locking.rstChange copy_from_user*( to copy_from_user() .Signed-off-by: Takahiro Itazuri <itazur@amazon.com>Link: https://lore.kernel.org/r/20220124
docs: fix typo in Documentation/kernel-hacking/locking.rstChange 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.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>
docs: futex: Fix kernel-doc referencesSince the futex code was restructured, there's no futex.c file anymoreand the implementation is split in various files. Point kernel-docreferences to the new
docs: futex: Fix kernel-doc referencesSince the futex code was restructured, there's no futex.c file anymoreand the implementation is split in various files. Point kernel-docreferences 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
docs: kernel-hacking: Remove inappropriate textRemove inappropriate sexual (and ableist) text from the lockingdocumentation, aligning it with the kernel code-of-conduct. As the textwas unrelated
docs: kernel-hacking: Remove inappropriate textRemove inappropriate sexual (and ableist) text from the lockingdocumentation, aligning it with the kernel code-of-conduct. As the textwas unrelated to locking, this change streamlines the document andimproves readability.Signed-off-by: Alyssa Rosenzweig <alyssa@rosenzweig.io>Link: https://lore.kernel.org/r/20210903151826.6300-1-alyssa@rosenzweig.ioSigned-off-by: Jonathan Corbet <corbet@lwn.net>
Documentation: in_irq() cleanupReplace the obsolete and ambiguos macro in_irq() with newmacro in_hardirq().Signed-off-by: Changbin Du <changbin.du@gmail.com>Link: https://lore.kernel.org/r/202
Documentation: in_irq() cleanupReplace the obsolete and ambiguos macro in_irq() with newmacro in_hardirq().Signed-off-by: Changbin Du <changbin.du@gmail.com>Link: https://lore.kernel.org/r/20210814014831.53083-1-changbin.du@gmail.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>
docs: kernel-hacking: hacking.rst: avoid using ReST :doc:`foo` markupThe :doc:`foo` tag is auto-generated via automarkup.py.So, use the filename at the sources, instead of :doc:`foo`.Signed-off-
docs: kernel-hacking: hacking.rst: avoid using ReST :doc:`foo` markupThe :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.orgSigned-off-by: Jonathan Corbet <corbet@lwn.net>
docs: kernel-hacking: be more civilRemove 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 plentifulprofanities in this vene
docs: kernel-hacking: be more civilRemove 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 plentifulprofanities 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>
Documentation: kernel-hacking: change 'current()' to 'current'Change 'current()' heading to 'current' to reflect usage.Signed-off-by: Joe Pater <02joepater06@gmail.com>Link: https://lore.kernel.
Documentation: kernel-hacking: change 'current()' to 'current'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.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>
docs: Fix reST markup when linking to sectionsDuring the process of converting the documentation to reST, some linkswere converted using the following wrong syntax (and sometimes using %20instead
docs: Fix reST markup when linking to sectionsDuring the process of converting the documentation to reST, some linkswere converted using the following wrong syntax (and sometimes using %20instead of spaces): `Display text <#section-name-in-html>`__This syntax isn't valid according to the docutils' spec [1], but moreimportantly, it is specific to HTML, since it uses '#' to link to anHTML anchor.The right syntax would instead use a docutils hyperlink reference as theembedded 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 generatingthe pdf documentation (make pdfdocs), that is, the build succeeds butthe links don't work, but that syntax causes errors when trying to buildusing 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 differentoutput 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-aliasesFixes: 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.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>
docs: locking: Drop :c:func: throughoutThe kernel doc tooling knows how to do this itself so drop this markupthroughout this file to simplify.Suggested-by: Jonathan Corbet <corbet@lwn.net>Signe
docs: locking: Drop :c:func: throughoutThe kernel doc tooling knows how to do this itself so drop this markupthroughout 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.orgSigned-off-by: Jonathan Corbet <corbet@lwn.net>
docs: locking: Add 'need' to hardirq sectionAdd the missing word to make this sentence read properly.Signed-off-by: Stephen Boyd <swboyd@chromium.org>Link: https://lore.kernel.org/r/202003181741
docs: locking: Add 'need' to hardirq sectionAdd 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.orgSigned-off-by: Jonathan Corbet <corbet@lwn.net>
docs: prevent warnings due to autosectionlabelChangeset 58ad30cf91f0 ("docs: fix reference to core-api/namespaces.rst")enabled a new feature at Sphinx: it will now generate index for eachdocument
docs: prevent warnings due to autosectionlabelChangeset 58ad30cf91f0 ("docs: fix reference to core-api/namespaces.rst")enabled a new feature at Sphinx: it will now generate index for eachdocument title, plus to each chapter inside it.There's a drawback, though: one document cannot have two sectionswith the same name anymore.A followup patch will change the logic of autosectionlabel toavoid most creating references for every single section title,but still we need to be able to reference the chapters insidea document.There are a few places where there are two chapters with thesame name. This patch renames one of the chapters, in order toavoid 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.rstFixes: 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.orgSigned-off-by: Jonathan Corbet <corbet@lwn.net>
docs: fix reference to core-api/namespaces.rstFix a couple of dangling links to core-api/namespaces.rst by turning theminto proper references. Enable the autosection extension (available sinceSp
docs: fix reference to core-api/namespaces.rstFix a couple of dangling links to core-api/namespaces.rst by turning theminto proper references. Enable the autosection extension (available sinceSphinx 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>
Documentation: kernel-hacking: hacking.rst: Change reference to document namespaces.rst to symbol-namespaces.rstThis patch fixes the following documentation build warning:Warning: Documentation/ke
Documentation: kernel-hacking: hacking.rst: Change reference to document namespaces.rst to symbol-namespaces.rstThis patch fixes the following documentation build warning:Warning: Documentation/kernel-hacking/hacking.rst referencesa file that doesn't exist: Documentation/kbuild/namespaces.rstAccording 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-apiand renamed to symbol-namespaces.rst.Therefore, this patch changes the reference to the documentkbuild/namespaces.rst in hacking.rst tocore-api/symbol-namespaces.rstSigned-off-by: Madhuparna Bhowmik <madhuparnabhowmik04@gmail.com>Link: https://lore.kernel.org/r/20191204104554.9100-1-madhuparnabhowmik04@gmail.comSigned-off-by: Jonathan Corbet <corbet@lwn.net>
docs: Add documentation for Symbol NamespacesDescribe using Symbol Namespaces from a perspective of a user. I.e.module authors or subsystem maintainers.Reviewed-by: Greg Kroah-Hartman <gregkh@li
docs: Add documentation for Symbol NamespacesDescribe 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>
docs: remove extra conf.py filesNow that the latex_documents are handled automatically, we canremove those extra conf.py files.Signed-off-by: Mauro Carvalho Chehab <mchehab+samsung@kernel.org>
docs: locking: convert docs to ReST and rename to *.rstConvert the locking documents to ReST and add them to thekernel development book where it belongs.Most of the stuff here is just to make Sp
docs: locking: convert docs to ReST and rename to *.rstConvert the locking documents to ReST and add them to thekernel development book where it belongs.Most of the stuff here is just to make Sphinx to properlyparse 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 tothe 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>
12