Commit Graph

17 Commits

Author SHA1 Message Date
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
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
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 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
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
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