summaryrefslogtreecommitdiff
path: root/Documentation/process
diff options
context:
space:
mode:
authorLinus Torvalds <torvalds@linux-foundation.org>2022-08-03 05:24:24 +0300
committerLinus Torvalds <torvalds@linux-foundation.org>2022-08-03 05:24:24 +0300
commitaad26f55f47a33d6de3df65f0b18e2886059ed6d (patch)
treeb514fc4c702105ceaa37f423a39f4b0688cd63f7 /Documentation/process
parentb069122256e45216b5c49d9441f9713991a4c645 (diff)
parent339170d8d3da5685762619080263abb78700ab4c (diff)
downloadlinux-aad26f55f47a33d6de3df65f0b18e2886059ed6d.tar.xz
Merge tag 'docs-6.0' of git://git.lwn.net/linux
Pull documentation updates from Jonathan Corbet: "This was a moderately busy cycle for documentation, but nothing all that earth-shaking: - More Chinese translations, and an update to the Italian translations. The Japanese, Korean, and traditional Chinese translations are more-or-less unmaintained at this point, instead. - Some build-system performance improvements. - The removal of the archaic submitting-drivers.rst document, with the movement of what useful material that remained into other docs. - Improvements to sphinx-pre-install to, hopefully, give more useful suggestions. - A number of build-warning fixes Plus the usual collection of typo fixes, updates, and more" * tag 'docs-6.0' of git://git.lwn.net/linux: (92 commits) docs: efi-stub: Fix paths for x86 / arm stubs Docs/zh_CN: Update the translation of sched-stats to 5.19-rc8 Docs/zh_CN: Update the translation of pci to 5.19-rc8 Docs/zh_CN: Update the translation of pci-iov-howto to 5.19-rc8 Docs/zh_CN: Update the translation of usage to 5.19-rc8 Docs/zh_CN: Update the translation of testing-overview to 5.19-rc8 Docs/zh_CN: Update the translation of sparse to 5.19-rc8 Docs/zh_CN: Update the translation of kasan to 5.19-rc8 Docs/zh_CN: Update the translation of iio_configfs to 5.19-rc8 doc:it_IT: align Italian documentation docs: Remove spurious tag from admin-guide/mm/overcommit-accounting.rst Documentation: process: Update email client instructions for Thunderbird docs: ABI: correct QEMU fw_cfg spec path doc/zh_CN: remove submitting-driver reference from docs docs: zh_TW: align to submitting-drivers removal docs: zh_CN: align to submitting-drivers removal docs: ko_KR: howto: remove reference to removed submitting-drivers docs: ja_JP: howto: remove reference to removed submitting-drivers docs: it_IT: align to submitting-drivers removal docs: process: remove outdated submitting-drivers.rst ...
Diffstat (limited to 'Documentation/process')
-rw-r--r--Documentation/process/5.Posting.rst3
-rw-r--r--Documentation/process/8.Conclusion.rst16
-rw-r--r--Documentation/process/email-clients.rst69
-rw-r--r--Documentation/process/howto.rst4
-rw-r--r--Documentation/process/index.rst1
-rw-r--r--Documentation/process/kernel-docs.rst62
-rw-r--r--Documentation/process/submitting-drivers.rst194
-rw-r--r--Documentation/process/submitting-patches.rst5
8 files changed, 95 insertions, 259 deletions
diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.Posting.rst
index bd36ecb29409..906235c11c24 100644
--- a/Documentation/process/5.Posting.rst
+++ b/Documentation/process/5.Posting.rst
@@ -10,8 +10,7 @@ of conventions and procedures which are used in the posting of patches;
following them will make life much easier for everybody involved. This
document will attempt to cover these expectations in reasonable detail;
more information can also be found in the files
-:ref:`Documentation/process/submitting-patches.rst <submittingpatches>`,
-:ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>`
+:ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
and :ref:`Documentation/process/submit-checklist.rst <submitchecklist>`.
diff --git a/Documentation/process/8.Conclusion.rst b/Documentation/process/8.Conclusion.rst
index b32a40215858..8c847dffe76b 100644
--- a/Documentation/process/8.Conclusion.rst
+++ b/Documentation/process/8.Conclusion.rst
@@ -5,15 +5,13 @@ For more information
There are numerous sources of information on Linux kernel development and
related topics. First among those will always be the Documentation
-directory found in the kernel source distribution. The top-level :ref:`process/howto.rst <process_howto>`
-file is an important starting point; :ref:`process/submitting-patches.rst <submittingpatches>`
-and :ref:`process/submitting-drivers.rst <submittingdrivers>`
-are also something which all kernel developers should
-read. Many internal kernel APIs are documented using the kerneldoc
-mechanism; "make htmldocs" or "make pdfdocs" can be used to generate those
-documents in HTML or PDF format (though the version of TeX shipped by some
-distributions runs into internal limits and fails to process the documents
-properly).
+directory found in the kernel source distribution. Start with the
+top-level :ref:`process/howto.rst <process_howto>`; also read
+:ref:`process/submitting-patches.rst <submittingpatches>`. Many internal
+kernel APIs are documented using the kerneldoc mechanism; "make htmldocs"
+or "make pdfdocs" can be used to generate those documents in HTML or PDF
+format (though the version of TeX shipped by some distributions runs into
+internal limits and fails to process the documents properly).
Various web sites discuss kernel development at all levels of detail. Your
author would like to humbly suggest https://lwn.net/ as a source;
diff --git a/Documentation/process/email-clients.rst b/Documentation/process/email-clients.rst
index 16586f6cc888..fc2c46f3f82d 100644
--- a/Documentation/process/email-clients.rst
+++ b/Documentation/process/email-clients.rst
@@ -277,36 +277,61 @@ Thunderbird (GUI)
Thunderbird is an Outlook clone that likes to mangle text, but there are ways
to coerce it into behaving.
+After doing the modifications, this includes installing the extensions,
+you need to restart Thunderbird.
+
- Allow use of an external editor:
- The easiest thing to do with Thunderbird and patches is to use an
- "external editor" extension and then just use your favorite ``$EDITOR``
- for reading/merging patches into the body text. To do this, download
- and install the extension, then add a button for it using
- :menuselection:`View-->Toolbars-->Customize...` and finally just click on it
- when in the :menuselection:`Compose` dialog.
-
- Please note that "external editor" requires that your editor must not
- fork, or in other words, the editor must not return before closing.
- You may have to pass additional flags or change the settings of your
- editor. Most notably if you are using gvim then you must pass the -f
- option to gvim by putting ``/usr/bin/gvim -f`` (if the binary is in
- ``/usr/bin``) to the text editor field in :menuselection:`external editor`
- settings. If you are using some other editor then please read its manual
- to find out how to do this.
+
+ The easiest thing to do with Thunderbird and patches is to use extensions
+ which open your favorite external editor.
+
+ Here are some example extensions which are capable of doing this.
+
+ - "External Editor Revived"
+
+ https://github.com/Frederick888/external-editor-revived
+
+ https://addons.thunderbird.net/en-GB/thunderbird/addon/external-editor-revived/
+
+ It requires installing a "native messaging host".
+ Please read the wiki which can be found here:
+ https://github.com/Frederick888/external-editor-revived/wiki
+
+ - "External Editor"
+
+ https://github.com/exteditor/exteditor
+
+ To do this, download and install the extension, then open the
+ :menuselection:`compose` window, add a button for it using
+ :menuselection:`View-->Toolbars-->Customize...`
+ then just click on the new button when you wish to use the external editor.
+
+ Please note that "External Editor" requires that your editor must not
+ fork, or in other words, the editor must not return before closing.
+ You may have to pass additional flags or change the settings of your
+ editor. Most notably if you are using gvim then you must pass the -f
+ option to gvim by putting ``/usr/bin/gvim --nofork"`` (if the binary is in
+ ``/usr/bin``) to the text editor field in :menuselection:`external editor`
+ settings. If you are using some other editor then please read its manual
+ to find out how to do this.
To beat some sense out of the internal editor, do this:
-- Edit your Thunderbird config settings so that it won't use ``format=flowed``.
- Go to :menuselection:`edit-->preferences-->advanced-->config editor` to bring up
- the thunderbird's registry editor.
+- Edit your Thunderbird config settings so that it won't use ``format=flowed``!
+ Go to your main window and find the button for your main dropdown menu.
+ :menuselection:`Main Menu-->Preferences-->General-->Config Editor...`
+ to bring up the thunderbird's registry editor.
-- Set ``mailnews.send_plaintext_flowed`` to ``false``
+ - Set ``mailnews.send_plaintext_flowed`` to ``false``
-- Set ``mailnews.wraplength`` from ``72`` to ``0``
+ - Set ``mailnews.wraplength`` from ``72`` to ``0``
-- :menuselection:`View-->Message Body As-->Plain Text`
+- Don't write HTML messages! Go to the main window
+ :menuselection:`Main Menu-->Account Settings-->youracc@server.something-->Composition & Addressing`!
+ There you can disable the option "Compose messages in HTML format".
-- :menuselection:`View-->Character Encoding-->Unicode (UTF-8)`
+- Open messages only as plain text! Go to the main window
+ :menuselection:`Main Menu-->View-->Message Body As-->Plain Text`!
TkRat (GUI)
***********
diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst
index e4beeca57e5f..cd6997a9d203 100644
--- a/Documentation/process/howto.rst
+++ b/Documentation/process/howto.rst
@@ -105,8 +105,8 @@ required reading:
patches if these rules are followed, and many people will only
review code if it is in the proper style.
- :ref:`Documentation/process/submitting-patches.rst <submittingpatches>` and :ref:`Documentation/process/submitting-drivers.rst <submittingdrivers>`
- These files describe in explicit detail how to successfully create
+ :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
+ This file describes in explicit detail how to successfully create
and send a patch, including (but not limited to):
- Email contents
diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst
index 3587dae4d0ef..2ba2a1582bbe 100644
--- a/Documentation/process/index.rst
+++ b/Documentation/process/index.rst
@@ -40,7 +40,6 @@ Other guides to the community that are of interest to most developers are:
:maxdepth: 1
changes
- submitting-drivers
stable-api-nonsense
management-style
stable-kernel-rules
diff --git a/Documentation/process/kernel-docs.rst b/Documentation/process/kernel-docs.rst
index da9527502ef0..502289d63385 100644
--- a/Documentation/process/kernel-docs.rst
+++ b/Documentation/process/kernel-docs.rst
@@ -1,9 +1,10 @@
.. _kernel_docs:
-Index of Documentation for People Interested in Writing and/or Understanding the Linux Kernel
-=============================================================================================
+Index of Further Kernel Documentation
+=====================================
- Juan-Mariano de Goyeneche <jmseyas@dit.upm.es>
+Initial Author: Juan-Mariano de Goyeneche (<jmseyas@dit.upm.es>;
+email address is defunct now.)
The need for a document like this one became apparent in the
linux-kernel mailing list as the same questions, asking for pointers
@@ -16,21 +17,16 @@ philosophy and design decisions behind this code.
Unfortunately, not many documents are available for beginners to
start. And, even if they exist, there was no "well-known" place which
-kept track of them. These lines try to cover this lack. All documents
-available on line known by the author are listed, while some reference
-books are also mentioned.
+kept track of them. These lines try to cover this lack.
PLEASE, if you know any paper not listed here or write a new document,
-send me an e-mail, and I'll include a reference to it here. Any
-corrections, ideas or comments are also welcomed.
+include a reference to it here, following the kernel's patch submission
+process. Any corrections, ideas or comments are also welcome.
-The papers that follow are listed in no particular order. All are
-cataloged with the following fields: the document's "Title", the
-"Author"/s, the "URL" where they can be found, some "Keywords" helpful
-when searching for specific topics, and a brief "Description" of the
-Document.
-
-Enjoy!
+All documents are cataloged with the following fields: the document's
+"Title", the "Author"/s, the "URL" where they can be found, some
+"Keywords" helpful when searching for specific topics, and a brief
+"Description" of the Document.
.. note::
@@ -83,6 +79,18 @@ On-line docs
Finally this trace-log is used as base for more a exact conceptual
exploration and description of the Linux TCP/IP implementation.*
+ * Title: **The Linux Kernel Module Programming Guide**
+
+ :Author: Peter Jay Salzman, Michael Burian, Ori Pomerantz, Bob Mottram,
+ Jim Huang.
+ :URL: https://sysprog21.github.io/lkmpg/
+ :Date: 2021
+ :Keywords: modules, GPL book, /proc, ioctls, system calls,
+ interrupt handlers .
+ :Description: A very nice GPL book on the topic of modules
+ programming. Lots of examples. Currently the new version is being
+ actively maintained at https://github.com/sysprog21/lkmpg.
+
* Title: **On submitting kernel Patches**
:Author: Andi Kleen
@@ -126,17 +134,19 @@ On-line docs
describes how to write user-mode utilities for communicating with
Card Services.
- * Title: **The Linux Kernel Module Programming Guide**
-
- :Author: Peter Jay Salzman, Michael Burian, Ori Pomerantz, Bob Mottram,
- Jim Huang.
- :URL: https://sysprog21.github.io/lkmpg/
- :Date: 2021
- :Keywords: modules, GPL book, /proc, ioctls, system calls,
- interrupt handlers .
- :Description: A very nice GPL book on the topic of modules
- programming. Lots of examples. Currently the new version is being
- actively maintained at https://github.com/sysprog21/lkmpg.
+ * Title: **How NOT to write kernel drivers**
+
+ :Author: Arjan van de Ven.
+ :URL: https://landley.net/kdocs/ols/2002/ols2002-pages-545-555.pdf
+ :Date: 2002
+ :Keywords: driver.
+ :Description: Programming bugs and Do-nots in kernel driver development
+ :Abstract: *Quit a few tutorials, articles and books give an introduction
+ on how to write Linux kernel drivers. Unfortunately the things one
+ should NOT do in Linux kernel code is either only a minor appendix
+ or, more commonly, completely absent. This paper tries to briefly touch
+ the areas in which the most common and serious bugs and do-nots are
+ encountered.*
* Title: **Global spinlock list and usage**
diff --git a/Documentation/process/submitting-drivers.rst b/Documentation/process/submitting-drivers.rst
deleted file mode 100644
index 8413b693d10d..000000000000
--- a/Documentation/process/submitting-drivers.rst
+++ /dev/null
@@ -1,194 +0,0 @@
-.. _submittingdrivers:
-
-Submitting Drivers For The Linux Kernel
-=======================================
-
-This document is intended to explain how to submit device drivers to the
-various kernel trees. Note that if you are interested in video card drivers
-you should probably talk to XFree86 (https://www.xfree86.org/) and/or X.Org
-(https://x.org/) instead.
-
-.. note::
-
- This document is old and has seen little maintenance in recent years; it
- should probably be updated or, perhaps better, just deleted. Most of
- what is here can be found in the other development documents anyway.
-
- Oh, and we don't really recommend submitting changes to XFree86 :)
-
-Also read the :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
-document.
-
-
-Allocating Device Numbers
--------------------------
-
-Major and minor numbers for block and character devices are allocated
-by the Linux assigned name and number authority (currently this is
-Torben Mathiasen). The site is https://www.lanana.org/. This
-also deals with allocating numbers for devices that are not going to
-be submitted to the mainstream kernel.
-See :ref:`Documentation/admin-guide/devices.rst <admin_devices>`
-for more information on this.
-
-If you don't use assigned numbers then when your device is submitted it will
-be given an assigned number even if that is different from values you may
-have shipped to customers before.
-
-Who To Submit Drivers To
-------------------------
-
-Linux 2.0:
- No new drivers are accepted for this kernel tree.
-
-Linux 2.2:
- No new drivers are accepted for this kernel tree.
-
-Linux 2.4:
- If the code area has a general maintainer then please submit it to
- the maintainer listed in MAINTAINERS in the kernel file. If the
- maintainer does not respond or you cannot find the appropriate
- maintainer then please contact Willy Tarreau <w@1wt.eu>.
-
-Linux 2.6 and upper:
- The same rules apply as 2.4 except that you should follow linux-kernel
- to track changes in API's. The final contact point for Linux 2.6+
- submissions is Andrew Morton.
-
-What Criteria Determine Acceptance
-----------------------------------
-
-Licensing:
- The code must be released to us under the
- GNU General Public License. If you wish the driver to be
- useful to other communities such as BSD you may release
- under multiple licenses. If you choose to release under
- licenses other than the GPL, you should include your
- rationale for your license choices in your cover letter.
- See accepted licenses at include/linux/module.h
-
-Copyright:
- The copyright owner must agree to use of GPL.
- It's best if the submitter and copyright owner
- are the same person/entity. If not, the name of
- the person/entity authorizing use of GPL should be
- listed in case it's necessary to verify the will of
- the copyright owner.
-
-Interfaces:
- If your driver uses existing interfaces and behaves like
- other drivers in the same class it will be much more likely
- to be accepted than if it invents gratuitous new ones.
- If you need to implement a common API over Linux and NT
- drivers do it in userspace.
-
-Code:
- Please use the Linux style of code formatting as documented
- in :ref:`Documentation/process/coding-style.rst <codingStyle>`.
- If you have sections of code
- that need to be in other formats, for example because they
- are shared with a windows driver kit and you want to
- maintain them just once separate them out nicely and note
- this fact.
-
-Portability:
- Pointers are not always 32bits, not all computers are little
- endian, people do not all have floating point and you
- shouldn't use inline x86 assembler in your driver without
- careful thought. Pure x86 drivers generally are not popular.
- If you only have x86 hardware it is hard to test portability
- but it is easy to make sure the code can easily be made
- portable.
-
-Clarity:
- It helps if anyone can see how to fix the driver. It helps
- you because you get patches not bug reports. If you submit a
- driver that intentionally obfuscates how the hardware works
- it will go in the bitbucket.
-
-PM support:
- Since Linux is used on many portable and desktop systems, your
- driver is likely to be used on such a system and therefore it
- should support basic power management by implementing, if
- necessary, the .suspend and .resume methods used during the
- system-wide suspend and resume transitions. You should verify
- that your driver correctly handles the suspend and resume, but
- if you are unable to ensure that, please at least define the
- .suspend method returning the -ENOSYS ("Function not
- implemented") error. You should also try to make sure that your
- driver uses as little power as possible when it's not doing
- anything. For the driver testing instructions see
- Documentation/power/drivers-testing.rst and for a relatively
- complete overview of the power management issues related to
- drivers see :ref:`Documentation/driver-api/pm/devices.rst <driverapi_pm_devices>`.
-
-Control:
- In general if there is active maintenance of a driver by
- the author then patches will be redirected to them unless
- they are totally obvious and without need of checking.
- If you want to be the contact and update point for the
- driver it is a good idea to state this in the comments,
- and include an entry in MAINTAINERS for your driver.
-
-What Criteria Do Not Determine Acceptance
------------------------------------------
-
-Vendor:
- Being the hardware vendor and maintaining the driver is
- often a good thing. If there is a stable working driver from
- other people already in the tree don't expect 'we are the
- vendor' to get your driver chosen. Ideally work with the
- existing driver author to build a single perfect driver.
-
-Author:
- It doesn't matter if a large Linux company wrote the driver,
- or you did. Nobody has any special access to the kernel
- tree. Anyone who tells you otherwise isn't telling the
- whole story.
-
-
-Resources
----------
-
-Linux kernel master tree:
- ftp.\ *country_code*\ .kernel.org:/pub/linux/kernel/...
-
- where *country_code* == your country code, such as
- **us**, **uk**, **fr**, etc.
-
- https://git.kernel.org/?p=linux/kernel/git/torvalds/linux.git
-
-Linux kernel mailing list:
- linux-kernel@vger.kernel.org
- [mail majordomo@vger.kernel.org to subscribe]
-
-Linux Device Drivers, Third Edition (covers 2.6.10):
- https://lwn.net/Kernel/LDD3/ (free version)
-
-LWN.net:
- Weekly summary of kernel development activity - https://lwn.net/
-
- 2.6 API changes:
-
- https://lwn.net/Articles/2.6-kernel-api/
-
- Porting drivers from prior kernels to 2.6:
-
- https://lwn.net/Articles/driver-porting/
-
-KernelNewbies:
- Documentation and assistance for new kernel programmers
-
- https://kernelnewbies.org/
-
-Linux USB project:
- http://www.linux-usb.org/
-
-How to NOT write kernel driver by Arjan van de Ven:
- https://landley.net/kdocs/ols/2002/ols2002-pages-545-555.pdf
-
-Kernel Janitor:
- https://kernelnewbies.org/KernelJanitors
-
-GIT, Fast Version Control System:
- https://git-scm.com/
diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
index a1cb6280fbcf..be49d8f2601b 100644
--- a/Documentation/process/submitting-patches.rst
+++ b/Documentation/process/submitting-patches.rst
@@ -12,9 +12,8 @@ This document contains a large number of suggestions in a relatively terse
format. For detailed information on how the kernel development process
works, see Documentation/process/development-process.rst. Also, read
Documentation/process/submit-checklist.rst
-for a list of items to check before submitting code. If you are submitting
-a driver, also read Documentation/process/submitting-drivers.rst; for device
-tree binding patches, read
+for a list of items to check before submitting code.
+For device tree binding patches, read
Documentation/devicetree/bindings/submitting-patches.rst.
This documentation assumes that you're using ``git`` to prepare your patches.