Commit Graph

32 Commits

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