Commit Graph

39 Commits

Author SHA1 Message Date
Feng Tang
911ac7979d Documentation: Add document for false sharing
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>
2023-04-10 16:46:11 -06:00
Alexander Sverdlin
379af13b31 docs: locking: Discourage from calling disable_irq() in atomic
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
2023-01-11 19:45:26 +01:00
Linus Torvalds
0a1d4434db 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
 -----BEGIN PGP SIGNATURE-----
 
 iQJHBAABCgAxFiEEQp8+kY+LLUocC4bMphj1TA10mKEFAmOUuC0THHRnbHhAbGlu
 dXRyb25peC5kZQAKCRCmGPVMDXSYodpZD/9kCDi009n65QFF1J4kE5aZuABbRMtO
 7sy66fJpDyB/MtcbPPH29uzQUEs1VMTQVB+ZM+7e1YGoxSWuSTzeoFH+yK1w4tEZ
 VPbOcvUEjG0esKUehwYFeOjSnIjy6M1Y41aOUaDnq00/azhfTrzLxQA1BbbFbkpw
 S7u2hllbyRJ8KdqQyV9cVpXmze6fcpdtNhdQeoA7qQCsSPnJ24MSpZ/PG9bAovq8
 75IRROT7CQRd6AMKAVpA9Ov8ak9nbY3EgQmoKcp5ZXfXz8kD3nHky9Lste7djgYB
 U085Vwcelt39V5iXevDFfzrBYRUqrMKOXIf2xnnoDNeF5Jlj5gChSNVZwTLO38wu
 RFEVCjCjuC41GQJWSck9LRSYdriW/htVbEE8JLc6uzUJGSyjshgJRn/PK4HjpiLY
 AvH2rd4rAap/rjDKvfWvBqClcfL7pyBvavgJeyJ8oXyQjHrHQwapPcsMFBm0Cky5
 soF0Lr3hIlQ9u+hwUuFdNZkY9mOg09g9ImEjW1AZTKY0DfJMc5JAGjjSCfuopVUN
 Uf/qqcUeQPSEaC+C9xiFs0T3svYFxBqpgPv4B6t8zAnozon9fyZs+lv5KdRg4X77
 qX395qc6PaOSQlA7gcxVw3vjCPd0+hljXX84BORP7z+uzcsomvIH1MxJepIHmgaJ
 JrYbSZ5qzY5TTA==
 =JlDe
 -----END PGP SIGNATURE-----

Merge tag 'timers-core-2022-12-10' of 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
  ...
2022-12-12 12:52:02 -08:00
Steven Rostedt (Google)
a31323bef2 timers: Update the documentation to reflect on the new timer_shutdown() API
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
2022-11-24 15:09:12 +01:00
Thomas Gleixner
87bdd932e8 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
2022-11-24 15:09:11 +01:00
Thomas Gleixner
b0b0aa5d85 Documentation: Remove bogus claim about del_timer_sync()
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
2022-11-24 15:09:10 +01:00
Mushahid Hussain
e648174b53 Documentation: Fix spelling mistake in hacking.rst
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>
2022-10-24 11:27:51 -06:00
Lukas Bulwahn
9db370de27 docs: process: remove outdated submitting-drivers.rst
Commit 31b24bee33 ("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>
2022-07-14 15:03:57 -06:00
Konstantin Ryabitsev
f35cf1a59e Documentation: kernel-hacking: minor edits for style
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>
2022-04-05 09:53:24 -06:00
Takahiro Itazuri
10855b45a4 docs: fix typo in Documentation/kernel-hacking/locking.rst
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>
2022-01-27 11:22:33 -07:00
André Almeida
bc67f1c454 docs: futex: Fix kernel-doc references
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
2021-10-19 17:27:05 +02:00
Alyssa Rosenzweig
abf36fe0be docs: kernel-hacking: Remove inappropriate text
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>
2021-09-03 15:56:45 -06:00
Changbin Du
fe450eeb4e Documentation: in_irq() cleanup
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>
2021-08-24 13:28:23 -06:00
Mauro Carvalho Chehab
7f3f7bfbbe docs: kernel-hacking: hacking.rst: avoid using ReST :doc:foo markup
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>
2021-06-17 13:24:38 -06:00
Bhaskar Chowdhury
3c2e0a489d docs: kernel-hacking: be more civil
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>
2021-02-11 10:00:40 -07:00
Joe Pater
3a4928cf5e 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.com
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2021-01-11 12:44:53 -07:00
Nícolas F. R. A. Prado
4f8af077a0 docs: Fix reST markup when linking to sections
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: ccc9971e21 ("docs: rcu: convert some articles from html to ReST")
Fixes: c8cce10a62 ("docs: Fix the reference labels in Locking.rst")
Fixes: e548cdeffc ("docs-rst: convert kernel-locking to ReST")
Fixes: 7ddedebb03 ("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>
2020-12-31 15:44:47 -07:00
Stephen Boyd
b1735296ce docs: locking: Drop :c:func: throughout
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>
2020-03-20 17:16:24 -06:00
Stephen Boyd
6adb775599 docs: locking: Add 'need' to hardirq section
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>
2020-03-20 17:16:19 -06:00
Mauro Carvalho Chehab
c44166fe5f docs: prevent warnings due to autosectionlabel
Changeset 58ad30cf91 ("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: 58ad30cf91 ("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>
2020-03-20 17:01:29 -06:00
Jonathan Corbet
58ad30cf91 docs: fix reference to core-api/namespaces.rst
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: fcfacb9f83 ("doc: move namespaces.rst from kbuild/ to core-api/")
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2020-03-19 12:52:01 -06:00
Madhuparna Bhowmik
bc51a6d34c Documentation: kernel-hacking: hacking.rst: Change reference to document 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>
2019-12-19 09:36:23 -07:00
Matthias Maennich
c4f4af4094 docs: Add documentation for Symbol Namespaces
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>
2019-09-10 10:30:49 +02:00
Mauro Carvalho Chehab
9fc3a18a94 docs: remove extra conf.py files
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>
2019-07-17 06:57:52 -03:00
Mauro Carvalho Chehab
387b14684f docs: locking: convert docs to ReST and rename to *.rst
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>
2019-07-15 08:53:27 -03:00
Stephen Kitt
220ee02a0b docs: stop suggesting strlcpy
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>
2019-06-20 14:08:49 -06:00
Mauro Carvalho Chehab
cd238effef docs: kbuild: convert docs to ReST and rename to *.rst
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>
2019-06-14 14:21:21 -06:00
Federico Vaga
1497624fff doc:it_IT: translation for kernel-hacking
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>
2018-07-26 16:21:09 -06:00
Jonathan Corbet
c8cce10a62 docs: Fix the reference labels in Locking.rst
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>
2018-07-26 16:17:55 -06:00
Federico Vaga
aa586e2574 doc: add some chapter labels
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>
2018-06-26 09:08:06 -06:00
Matthew Wilcox
423860a65a Documentation: Fix misconversion of #if
At some stage of the conversion pipeline, something thought that the
DocBook entity &num; should be rendered as NUM instead of #.

Signed-off-by: Matthew Wilcox <mawilcox@microsoft.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2018-01-17 16:45:01 -07:00
Marco Donato Torsello
c1de03a4ce Documentation: kernel-hacking: corrected a typo
Corrected a typo.

Signed-off-by: Marco Donato Torsello <marcodonato.torsello@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
2017-12-11 14:19:06 -07:00
Linus Torvalds
650fc870a2 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.
 -----BEGIN PGP SIGNATURE-----
 
 iQIcBAABAgAGBQJZWkGAAAoJEI3ONVYwIuV6rf0P/0B3JTiVPKS/WUx53+jzbAi4
 1BN7dmmuMxE1bWpgdEq+ac4aKxm07iAojuntuMj0qz/ZB1WARcmvEqqzI5i4wfq9
 5MrLduLkyuWfr4MOPseKJ2VK83p8nkMOiO7jmnBsilu7fE4nF+5YY9j4cVaArfMy
 cCQvAGjQzvej2eiWMGUSLHn4QFKh00aD7cwKyBVsJ08b27C9xL0J2LQyCDZ4yDgf
 37/MH3puEd3HX/4qAwLonIxT3xrIrrbDturqLU7OSKcWTtGZNrYyTFbwR3RQtqWd
 H8YZVg2Uyhzg9MYhkbQ2E5dEjUP4mkegcp6/JTINH++OOPpTbdTJgirTx7VTkSf1
 +kL8t7+Ayxd0FH3+77GJ5RMj8LUK6rj5cZfU5nClFQKWXP9UL3IelQ3Nl+SpdM8v
 ZAbR2KjKgH9KS6+cbIhgFYlvY+JgPkOVruwbIAc7wXVM3ibk1sWoBOFEujcbueWh
 yDpQv3l1UX0CKr3jnevJoW26LtEbGFtC7gSKZ+3btyeSBpWFGlii42KNycEGwUW0
 ezlwryDVHzyTUiKllNmkdK4v73mvPsZHEjgmme4afKAIiUilmcUF4XcqD86hISFT
 t+UJLA/zEU+0sJe26o2nK6GNJzmo4oCtVyxfhRe26Ojs1n80xlYgnZRfuIYdd31Z
 nwLBnwDCHAOyX91WXp9G
 =cVjZ
 -----END PGP SIGNATURE-----

Merge tag 'docs-4.13' of git://git.lwn.net/linux

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
  ...
2017-07-03 21:13:25 -07:00
Mauro Carvalho Chehab
dc89fca93e locking.rst: Update some ReST markups
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>
2017-05-16 08:44:03 -03:00
Mauro Carvalho Chehab
475c5ef83d locking.rst: add captions to two tables
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>
2017-05-16 08:44:03 -03:00
Mauro Carvalho Chehab
5b9fd1d3be locking.rst: reformat locking table
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>
2017-05-16 08:44:02 -03:00
Mauro Carvalho Chehab
e548cdeffc docs-rst: convert kernel-locking to ReST
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>
2017-05-16 08:00:58 -03:00
Mauro Carvalho Chehab
dca1e58e3f kernel-hacking: update document
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>
2017-05-16 08:00:57 -03:00
Mauro Carvalho Chehab
c4fcd7cabb docs-rst: convert kernel-hacking to ReST
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>
2017-05-16 08:00:49 -03:00