On 16/02/2024 15:58, Jonathan Corbet wrote:
Greg Kroah-Hartman <gregkh@xxxxxxxxxxxxxxxxxxx> writes:
On Fri, Feb 16, 2024 at 10:28:39AM +0200, Jani Nikula wrote:
rst basically allows any order of the heading underlines, and their
relative hierarchy is determined by how they show up in each document,
it's not specified by rst. However, it would be much easier for everyone
if all the kernel documents followed the same style.
Agreed, someone should pick a style and sweep the whole directory and
sync them up to the agreed formatting. :)
Somebody did pick a style, it's in Documentation/doc-guide/sphinx.rst :)
I have a (very long and ugly) script that can fix these up to a
consistent style, the attached patch is the result of running it on
Documentation/process/ only.
I've done builds before and after the patch and diffed the resulting
HTML files, they show no difference. (HOWEVER, you do need a 'make
cleandocs' in between, as it seems doing 'make htmldocs; find
Documentation | xargs touch; make htmldocs' is going to change the
generated HTML for the sidebar -- another issue to look into at some
point, I guess; maybe it's specific to the Sphinx version I used here,
4.3.2.)
The script will leave alone any file that it doesn't quite understand
(e.g. for a lot of the translations there are way more underlines than
characters in the heading and it doesn't match up with the byte count
either).
Anyway, the question is: Is this worth doing in the first place, or is
it just churn? I assume just after -rc1 would be the ideal time to
submit these to avoid conflicts.
Vegard
From e19b7143843b0935cb53f55e8a386f8bac230de6 Mon Sep 17 00:00:00 2001
From: Vegard Nossum <vegard.nossum@xxxxxxxxxx>
Date: Fri, 16 Feb 2024 21:58:09 +0100
Subject: [PATCH] docs: process: make reST headings consistent
Signed-off-by: Vegard Nossum <vegard.nossum@xxxxxxxxxx>
---
Documentation/process/1.Intro.rst | 11 ++--
Documentation/process/2.Process.rst | 17 +++---
Documentation/process/3.Early-stage.rst | 11 ++--
Documentation/process/5.Posting.rst | 11 ++--
Documentation/process/7.AdvancedTopics.rst | 5 +-
Documentation/process/8.Conclusion.rst | 2 +
Documentation/process/adding-syscalls.rst | 29 +++++-----
Documentation/process/applying-patches.rst | 7 +--
Documentation/process/botching-up-ioctls.rst | 12 ++---
Documentation/process/clang-format.rst | 9 ++--
.../code-of-conduct-interpretation.rst | 9 ++--
Documentation/process/code-of-conduct.rst | 3 +-
Documentation/process/deprecated.rst | 22 ++++----
Documentation/process/development-process.rst | 1 +
.../process/handling-regressions.rst | 3 +-
Documentation/process/howto.rst | 35 ++++++------
Documentation/process/index.rst | 12 ++---
Documentation/process/kernel-docs.rst | 9 ++--
.../process/kernel-driver-statement.rst | 3 +-
.../process/kernel-enforcement-statement.rst | 3 +-
Documentation/process/license-rules.rst | 7 +--
Documentation/process/magic-number.rst | 1 +
.../process/maintainer-handbooks.rst | 1 +
Documentation/process/maintainer-kvm-x86.rst | 51 +++++++++---------
Documentation/process/maintainer-netdev.rst | 54 +++++++++----------
.../process/maintainer-soc-clean-dts.rst | 4 +-
Documentation/process/maintainer-soc.rst | 14 ++---
Documentation/process/management-style.rst | 13 ++---
.../process/programming-language.rst | 5 +-
.../process/researcher-guidelines.rst | 3 +-
Documentation/process/security-bugs.rst | 11 ++--
Documentation/process/submit-checklist.rst | 3 +-
.../process/volatile-considered-harmful.rst | 3 +-
33 files changed, 206 insertions(+), 178 deletions(-)
diff --git a/Documentation/process/1.Intro.rst b/Documentation/process/1.Intro.rst
index c3d0270bbfb3..05f59d742823 100644
--- a/Documentation/process/1.Intro.rst
+++ b/Documentation/process/1.Intro.rst
@@ -1,10 +1,11 @@
.. _development_process_intro:
+============
Introduction
============
Executive summary
------------------
+=================
The rest of this section covers the scope of the kernel development process
and the kinds of frustrations that developers and their employers can
@@ -48,7 +49,7 @@ managing patches with git and reviewing patches posted by others.
for more information on kernel development.
What this document is about
----------------------------
+===========================
The Linux kernel, at over 8 million lines of code and well over 1000
contributors to each release, is one of the largest and most active free
@@ -103,7 +104,7 @@ better; the following text should help you - or those who work for you -
join our community.
Credits
--------
+=======
This document was written by Jonathan Corbet, corbet@xxxxxxx. It has been
improved by comments from Johannes Berg, James Berry, Alex Chiang, Roland
@@ -115,7 +116,7 @@ This work was supported by the Linux Foundation; thanks especially to
Amanda McPherson, who saw the value of this effort and made it all happen.
The importance of getting code into the mainline
-------------------------------------------------
+================================================
Some companies and developers occasionally wonder why they should bother
learning how to work with the kernel community and get their code into the
@@ -228,7 +229,7 @@ point, vendors whose code is in the mainline and well maintained will be
much better positioned to get the new product ready for market quickly.
Licensing
----------
+=========
Code is contributed to the Linux kernel under a number of licenses, but all
code must be compatible with version 2 of the GNU General Public License
diff --git a/Documentation/process/2.Process.rst b/Documentation/process/2.Process.rst
index 613a01da4717..d178c1b74514 100644
--- a/Documentation/process/2.Process.rst
+++ b/Documentation/process/2.Process.rst
@@ -1,5 +1,6 @@
.. _development_process:
+=================================
How the development process works
=================================
@@ -11,7 +12,7 @@ processes to keep development happening smoothly. A solid understanding of
how the process works is required in order to be an effective part of it.
The big picture
----------------
+===============
The kernel developers use a loosely time-based release process, with a new
major kernel release happening every two or three months. The recent
@@ -138,7 +139,7 @@ release.
The lifecycle of a patch
-------------------------
+========================
Patches do not go directly from the developer's keyboard into the mainline
kernel. There is, instead, a somewhat involved (if somewhat informal)
@@ -207,7 +208,7 @@ step. This approach invariably leads to frustration for everybody
involved.
How patches get into the Kernel
--------------------------------
+===============================
There is exactly one person who can merge patches into the mainline kernel
repository: Linus Torvalds. But, for example, of the over 9,500 patches
@@ -254,7 +255,7 @@ normally the right way to go.
Next trees
-----------
+==========
The chain of subsystem trees guides the flow of patches into the kernel,
but it also raises an interesting question: what if somebody wants to look
@@ -307,7 +308,7 @@ their way into linux-next some time before the merge window opens.
Staging trees
--------------
+=============
The kernel source tree contains the drivers/staging/ directory, where
many sub-directories for drivers or filesystems that are on their way to
@@ -336,7 +337,7 @@ a proper mainline driver.
Tools
------
+=====
As can be seen from the above text, the kernel development process depends
heavily on the ability to herd collections of patches in various
@@ -383,7 +384,7 @@ quilt is the best tool for the job.
Mailing lists
--------------
+=============
A great deal of Linux kernel development work is done by way of mailing
lists. It is hard to be a fully-functioning member of the community
@@ -453,7 +454,7 @@ in the MAINTAINERS file packaged with the kernel source.
Getting started with Kernel development
----------------------------------------
+=======================================
Questions about how to get started with the kernel development process are
common - from both individuals and companies. Equally common are missteps
diff --git a/Documentation/process/3.Early-stage.rst b/Documentation/process/3.Early-stage.rst
index 894a920041c6..57c9690f2f02 100644
--- a/Documentation/process/3.Early-stage.rst
+++ b/Documentation/process/3.Early-stage.rst
@@ -1,5 +1,6 @@
.. _development_early_stage:
+====================
Early-stage planning
====================
@@ -11,7 +12,7 @@ communication can save far more time later on.
Specifying the problem
-----------------------
+======================
Like any engineering project, a successful kernel enhancement starts with a
clear description of the problem to be solved. In some cases, this step is
@@ -69,7 +70,7 @@ Only then does it make sense to start considering possible solutions.
Early discussion
-----------------
+================
When planning a kernel development project, it makes great sense to hold
discussions with the community before launching into implementation. Early
@@ -123,7 +124,7 @@ avoided with some early discussion with the kernel developers.
Who do you talk to?
--------------------
+===================
When developers decide to take their plans public, the next question will
be: where do we start? The answer is to find the right mailing list(s) and
@@ -165,7 +166,7 @@ track down a maintainer for a specific piece of code.
When to post?
--------------
+=============
If possible, posting your plans during the early stages can only be
helpful. Describe the problem being solved and any plans that have been
@@ -190,7 +191,7 @@ community informed as you go.
Getting official buy-in
------------------------
+=======================
If your work is being done in a corporate environment - as most Linux
kernel work is - you must, obviously, have permission from suitably
diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.Posting.rst
index de4edd42d5c0..42a6a029c173 100644
--- a/Documentation/process/5.Posting.rst
+++ b/Documentation/process/5.Posting.rst
@@ -1,5 +1,6 @@
.. _development_posting:
+===============
Posting patches
===============
@@ -15,7 +16,7 @@ and :ref:`Documentation/process/submit-checklist.rst <submitchecklist>`.
When to post
-------------
+============
There is a constant temptation to avoid posting patches before they are
completely "ready." For simple patches, that is not a problem. If the
@@ -32,7 +33,7 @@ with the idea that they can help you drive the work in the right direction.
Before creating patches
------------------------
+=======================
There are a number of things which should be done before you consider
sending patches to the development community. These include:
@@ -58,7 +59,7 @@ always pays back the effort in short order.
Patch preparation
------------------
+=================
The preparation of patches for posting can be a surprising amount of work,
but, once again, attempting to save time here is not generally advisable
@@ -129,7 +130,7 @@ done. When done properly, though, it is time well spent.
Patch formatting and changelogs
--------------------------------
+===============================
So now you have a perfect series of patches for posting, but the work is
not done quite yet. Each patch needs to be formatted into a message which
@@ -276,7 +277,7 @@ the bug was reported in private.
Sending the patch
------------------
+=================
Before you mail your patches, there are a couple of other things you should
take care of:
diff --git a/Documentation/process/7.AdvancedTopics.rst b/Documentation/process/7.AdvancedTopics.rst
index 43291704338e..9f0ec5bec15e 100644
--- a/Documentation/process/7.AdvancedTopics.rst
+++ b/Documentation/process/7.AdvancedTopics.rst
@@ -1,5 +1,6 @@
.. _development_advancedtopics:
+===============
Advanced topics
===============
@@ -9,7 +10,7 @@ number of topics which can be helpful for developers wanting to become a
regular part of the Linux kernel development process.
Managing patches with git
--------------------------
+=========================
The use of distributed version control for the kernel began in early 2002,
when Linus first started playing with the proprietary BitKeeper
@@ -149,7 +150,7 @@ sure that you have remembered to push those changes to the public server.
.. _development_advancedtopics_reviews:
Reviewing patches
------------------
+=================
Some readers will certainly object to putting this section with "advanced
topics" on the grounds that even beginning kernel developers should be
diff --git a/Documentation/process/8.Conclusion.rst b/Documentation/process/8.Conclusion.rst
index 8c847dffe76b..593ee94c8ec1 100644
--- a/Documentation/process/8.Conclusion.rst
+++ b/Documentation/process/8.Conclusion.rst
@@ -1,5 +1,6 @@
.. _development_conclusion:
+====================
For more information
====================
@@ -49,6 +50,7 @@ Documentation for git can be found at:
https://www.kernel.org/pub/software/scm/git/docs/user-manual.html
+==========
Conclusion
==========
diff --git a/Documentation/process/adding-syscalls.rst b/Documentation/process/adding-syscalls.rst
index 906c47f1a9e5..00e6712a7e3d 100644
--- a/Documentation/process/adding-syscalls.rst
+++ b/Documentation/process/adding-syscalls.rst
@@ -1,6 +1,7 @@
.. _addsyscalls:
+========================
Adding a New System Call
========================
@@ -10,7 +11,7 @@ Linux kernel, over and above the normal submission advice in
System Call Alternatives
-------------------------
+========================
The first thing to consider when adding a new system call is whether one of
the alternatives might be suitable instead. Although system calls are the
@@ -52,7 +53,7 @@ interface.
Designing the API: Planning for Extension
------------------------------------------
+=========================================
A new system call forms part of the API of the kernel, and has to be supported
indefinitely. As such, it's a very good idea to explicitly discuss the
@@ -104,7 +105,7 @@ See :manpage:`perf_event_open(2)` and the ``perf_copy_attr()`` function (in
Designing the API: Other Considerations
----------------------------------------
+=======================================
If your new system call allows userspace to refer to a kernel object, it
should use a file descriptor as the handle for that object -- don't invent a
@@ -174,7 +175,7 @@ structure that's passed in by pointer.)
Proposing the API
------------------
+=================
To make new system calls easy to review, it's best to divide up the patchset
into separate chunks. These should include at least the following items as
@@ -194,7 +195,7 @@ be cc'ed to linux-api@xxxxxxxxxxxxxxx.
Generic System Call Implementation
-----------------------------------
+==================================
The main entry point for your new :manpage:`xyzzy(2)` system call will be called
``sys_xyzzy()``, but you add this entry point with the appropriate
@@ -249,7 +250,7 @@ To summarize, you need a commit that includes:
x86 System Call Implementation
-------------------------------
+==============================
To wire up your new system call for x86 platforms, you need to update the
master syscall tables. Assuming your new system call isn't special in some
@@ -267,7 +268,7 @@ relevant merge window.
Compatibility System Calls (Generic)
-------------------------------------
+====================================
For most system calls the same 64-bit implementation can be invoked even when
the userspace program is itself 32-bit; even if the system call's parameters
@@ -354,7 +355,7 @@ To summarize, you need:
Compatibility System Calls (x86)
---------------------------------
+================================
To wire up the x86 architecture of a system call with a compatibility version,
the entries in the syscall tables need to be adjusted.
@@ -388,7 +389,7 @@ layout do indeed map exactly from x32 (-mx32) to either the 32-bit (-m32) or
System Calls Returning Elsewhere
---------------------------------
+================================
For most system calls, once the system call is complete the user program
continues exactly where it left off -- at the next instruction, with the
@@ -438,7 +439,7 @@ simulates registers etc). Fixing this is as simple as adding a #define to
Other Details
--------------
+=============
Most of the kernel treats system calls in a generic way, but there is the
occasional exception that may need updating for your particular system call.
@@ -455,7 +456,7 @@ call to check there are no other special cases.
Testing
--------
+=======
A new system call should obviously be tested; it is also useful to provide
reviewers with a demonstration of how user space programs will use the system
@@ -480,7 +481,7 @@ for filesystem-related changes.
Man Page
---------
+========
All new system calls should come with a complete man page, ideally using groff
markup, but plain text will do. If groff is used, it's helpful to include a
@@ -492,7 +493,7 @@ For more details, see https://www.kernel.org/doc/man-pages/patches.html
Do not call System Calls in the Kernel
---------------------------------------
+======================================
System calls are, as stated above, interaction points between userspace and
the kernel. Therefore, system call functions such as ``sys_xyzzy()`` or
@@ -523,7 +524,7 @@ architecture-specific compatibility wrappers, or other code in arch/.
References and Sources
-----------------------
+======================
- LWN article from Michael Kerrisk on use of flags argument in system calls:
https://lwn.net/Articles/585415/
diff --git a/Documentation/process/applying-patches.rst b/Documentation/process/applying-patches.rst
index c269f5e1a0a3..11f5cbe4de39 100644
--- a/Documentation/process/applying-patches.rst
+++ b/Documentation/process/applying-patches.rst
@@ -1,7 +1,8 @@
.. _applying_patches:
+====================================
Applying Patches To The Linux Kernel
-++++++++++++++++++++++++++++++++++++
+====================================
Original by:
Jesper Juhl, August 2005
@@ -316,7 +317,7 @@ The -stable team provides normal as well as incremental patches. Below is
how to apply these patches.
Normal patches
-~~~~~~~~~~~~~~
+--------------
These patches are not incremental, meaning that for example the 5.7.3
patch does not apply on top of the 5.7.2 kernel source, but rather on top
@@ -335,7 +336,7 @@ Here's a small example::
$ mv linux-5.7.2 linux-5.7.3 # rename the kernel source dir
Incremental patches
-~~~~~~~~~~~~~~~~~~~
+-------------------
Incremental patches are different: instead of being applied on top
of base 5.x kernel, they are applied on top of previous stable kernel
diff --git a/Documentation/process/botching-up-ioctls.rst b/Documentation/process/botching-up-ioctls.rst
index a05e8401de1c..44ab68408377 100644
--- a/Documentation/process/botching-up-ioctls.rst
+++ b/Documentation/process/botching-up-ioctls.rst
@@ -22,7 +22,7 @@ something every GPU driver has to do on its own.
Prerequisites
--------------
+=============
First the prerequisites. Without these you have already failed, because you
will need to add a 32-bit compat layer:
@@ -50,7 +50,7 @@ will need to add a 32-bit compat layer:
Basics
-------
+======
With the joys of writing a compat layer avoided we can take a look at the basic
fumbles. Neglecting these will make backward and forward compatibility a real
@@ -82,7 +82,7 @@ will have a second iteration or at least an extension for any given interface.
Fun with Error Paths
---------------------
+====================
Nowadays we don't have any excuse left any more for drm drivers being neat
little root exploits. This means we both need full input validation and solid
@@ -125,7 +125,7 @@ anyway:
Time, Waiting and Missing it
-----------------------------
+============================
GPUs do most everything asynchronously, so we have a need to time operations and
wait for outstanding ones. This is really tricky business; at the moment none of
@@ -166,7 +166,7 @@ still tons more lessons to learn here.
Leaking Resources, Not
-----------------------
+======================
A full-blown drm driver essentially implements a little OS, but specialized to
the given GPU platforms. This means a driver needs to expose tons of handles
@@ -200,7 +200,7 @@ entails its own little set of pitfalls:
Last, but not Least
--------------------
+===================
Not every problem needs a new ioctl:
diff --git a/Documentation/process/clang-format.rst b/Documentation/process/clang-format.rst
index 1d089a847c1b..2ced44df2277 100644
--- a/Documentation/process/clang-format.rst
+++ b/Documentation/process/clang-format.rst
@@ -1,5 +1,6 @@
.. _clangformat:
+============
clang-format
============
@@ -44,7 +45,7 @@ See more information about the tool at:
.. _clangformatreview:
Review files and patches for coding style
------------------------------------------
+=========================================
By running the tool in its inline mode, you can review full subsystems,
folders or individual files for code style mistakes, typos or improvements.
@@ -84,7 +85,7 @@ at least until we see if ``clang-format`` becomes commonplace.
.. _clangformatreformat:
Reformatting blocks of code
----------------------------
+===========================
By using an integration with your text editor, you can reformat arbitrary
blocks (selections) of code with a single keystroke. This is specially
@@ -111,7 +112,7 @@ so that you can tweak a few options. See clangformatextra_.
.. _clangformatmissing:
Missing support
----------------
+===============
``clang-format`` is missing support for some things that are common
in kernel code. They are easy to remember, so if you use the tool
@@ -157,7 +158,7 @@ In particular, some very common ones you will notice are:
.. _clangformatextra:
Extra features/options
-----------------------
+======================
Some features/style options are not enabled by default in the configuration
file in order to minimize the differences between the output and the current
diff --git a/Documentation/process/code-of-conduct-interpretation.rst b/Documentation/process/code-of-conduct-interpretation.rst
index 66b07f14714c..3abf86d261c6 100644
--- a/Documentation/process/code-of-conduct-interpretation.rst
+++ b/Documentation/process/code-of-conduct-interpretation.rst
@@ -1,5 +1,6 @@
.. _code_of_conduct_interpretation:
+================================================================
Linux Kernel Contributor Covenant Code of Conduct Interpretation
================================================================
@@ -22,7 +23,7 @@ system kernel ever, and we do not want to do anything to cause the
quality of submission and eventual result to ever decrease.
Maintainers
------------
+===========
The Code of Conduct uses the term "maintainers" numerous times. In the
kernel community, a "maintainer" is anyone who is responsible for a
@@ -30,7 +31,7 @@ subsystem, driver, or file, and is listed in the MAINTAINERS file in the
kernel source tree.
Responsibilities
-----------------
+================
The Code of Conduct mentions rights and responsibilities for
maintainers, and this needs some further clarifications.
@@ -84,7 +85,7 @@ the Code of Conduct. The kernel community is aware of that and provides
entry level programs in various forms like kernelnewbies.org.
Scope
------
+=====
The Linux kernel community primarily interacts on a set of public email
lists distributed around a number of different servers controlled by a
@@ -119,7 +120,7 @@ part of the user/kernel API, or reflect terminology used in published
standards or specifications, are not considered bugs.
Enforcement
------------
+===========
The address listed in the Code of Conduct goes to the Code of Conduct
Committee. The exact members receiving these emails at any given time
diff --git a/Documentation/process/code-of-conduct.rst b/Documentation/process/code-of-conduct.rst
index be50294aebd5..17213ae2f6ee 100644
--- a/Documentation/process/code-of-conduct.rst
+++ b/Documentation/process/code-of-conduct.rst
@@ -1,7 +1,8 @@
.. _code_of_conduct:
+====================================
Contributor Covenant Code of Conduct
-++++++++++++++++++++++++++++++++++++
+====================================
Our Pledge
==========
diff --git a/Documentation/process/deprecated.rst b/Documentation/process/deprecated.rst
index 1f7f3e6c9cda..42c8a3f8d5f4 100644
--- a/Documentation/process/deprecated.rst
+++ b/Documentation/process/deprecated.rst
@@ -18,7 +18,7 @@ point when uses of deprecated things are proposed for inclusion in the
kernel.
__deprecated
-------------
+============
While this attribute does visually mark an interface as deprecated,
it `does not produce warnings during builds any more
<https://git.kernel.org/linus/771c035372a036f83353eef46dbb829780330234>`_
@@ -30,7 +30,7 @@ be fully removed from the kernel, or added to this file to discourage
others from using them in the future.
BUG() and BUG_ON()
-------------------
+==================
Use WARN() and WARN_ON() instead, and handle the "impossible"
error condition as gracefully as possible. While the BUG()-family
of APIs were originally designed to act as an "impossible situation"
@@ -52,7 +52,7 @@ to make sure their systems do not continue running in the face of
<https://git.kernel.org/linus/d4689846881d160a4d12a514e991a740bcb5d65a>`_.)
open-coded arithmetic in allocator arguments
---------------------------------------------
+============================================
Dynamic size calculations (especially multiplication) should not be
performed in memory allocator (or similar) function arguments due to the
risk of them overflowing. This could lead to values wrapping around and a
@@ -110,7 +110,7 @@ as well as the related check_mul_overflow(), check_add_overflow(),
check_sub_overflow(), and check_shl_overflow() family of functions.
simple_strtol(), simple_strtoll(), simple_strtoul(), simple_strtoull()
-----------------------------------------------------------------------
+======================================================================
The simple_strtol(), simple_strtoll(),
simple_strtoul(), and simple_strtoull() functions
explicitly ignore overflows, which may lead to unexpected results
@@ -120,7 +120,7 @@ correct replacements, though note that those require the string to be
NUL or newline terminated.
strcpy()
---------
+========
strcpy() performs no bounds checking on the destination buffer. This
could result in linear overflows beyond the end of the buffer, leading to
all kinds of misbehaviors. While `CONFIG_FORTIFY_SOURCE=y` and various
@@ -132,7 +132,7 @@ the destination, but rather a count of non-NUL bytes copied (or negative
errno when it truncates).
strncpy() on NUL-terminated strings
------------------------------------
+===================================
Use of strncpy() does not guarantee that the destination buffer will
be NUL terminated. This can lead to various linear read overflows and
other misbehavior due to the missing termination. It also NUL-pads
@@ -154,7 +154,7 @@ attribute to avoid future compiler warnings. For cases still needing
NUL-padding, strtomem_pad() can be used.
strlcpy()
----------
+=========
strlcpy() reads the entire source buffer first (since the return value
is meant to match that of strlen()). This read may exceed the destination
size limit. This is both inefficient and can lead to linear read overflows
@@ -163,7 +163,7 @@ though care must be given to any cases where the return value of strlcpy()
is used, since strscpy() will return negative errno values when it truncates.
%p format specifier
--------------------
+===================
Traditionally, using "%p" in format strings would lead to regular address
exposure flaws in dmesg, proc, sysfs, etc. Instead of leaving these to
be exploitable, all "%p" uses in the kernel are being printed as a hashed
@@ -187,7 +187,7 @@ you can temporarily boot with the debug flag "`no_hash_pointers
<https://git.kernel.org/linus/5ead723a20e0447bc7db33dc3070b420e5f80aa6>`_".
Variable Length Arrays (VLAs)
------------------------------
+=============================
Using stack VLAs produces much worse machine code than statically
sized stack arrays. While these non-trivial `performance issues
<https://git.kernel.org/linus/02361bc77888>`_ are reason enough to
@@ -198,7 +198,7 @@ stack (when built without `CONFIG_THREAD_INFO_IN_TASK=y`), or overwriting
memory adjacent to the stack (when built without `CONFIG_VMAP_STACK=y`)
Implicit switch case fall-through
----------------------------------
+=================================
The C language allows switch cases to fall through to the next case
when a "break" statement is missing at the end of a case. This, however,
introduces ambiguity in the code, as it's not always clear if the missing
@@ -235,7 +235,7 @@ All switch/case blocks must end in one of:
* return [expression];
Zero-length and one-element arrays
-----------------------------------
+==================================
There is a regular need in the kernel to provide a way to declare having
a dynamically sized set of trailing elements in a structure. Kernel code
should always use `"flexible array members" <https://en.wikipedia.org/wiki/Flexible_array_member>`_
diff --git a/Documentation/process/development-process.rst b/Documentation/process/development-process.rst
index e34d7da58b7f..3d17099ce94f 100644
--- a/Documentation/process/development-process.rst
+++ b/Documentation/process/development-process.rst
@@ -1,5 +1,6 @@
.. _development_process_main:
+=========================================
A guide to the Kernel Development Process
=========================================
diff --git a/Documentation/process/handling-regressions.rst b/Documentation/process/handling-regressions.rst
index 5d3c3de3f4ec..7854f5ebbb66 100644
--- a/Documentation/process/handling-regressions.rst
+++ b/Documentation/process/handling-regressions.rst
@@ -1,8 +1,9 @@
.. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0)
.. See the bottom of this file for additional redistribution information.
+====================
Handling regressions
-++++++++++++++++++++
+====================
*We don't cause regressions* -- this document describes what this "first rule of
Linux kernel development" means in practice for developers. It complements
diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst
index eebda4910a88..1c4e370225b4 100644
--- a/Documentation/process/howto.rst
+++ b/Documentation/process/howto.rst
@@ -1,5 +1,6 @@
.. _process_howto:
+=================================
HOWTO do Linux kernel development
=================================
@@ -15,7 +16,7 @@ document.
Introduction
-------------
+============
So, you want to learn how to become a Linux kernel developer? Or you
have been told by your manager, "Go write a Linux driver for this
@@ -57,7 +58,7 @@ of doing things.
Legal Issues
-------------
+============
The Linux kernel source code is released under the GPL. Please see the file
COPYING in the main directory of the source tree. The Linux kernel licensing
@@ -73,7 +74,7 @@ For common questions and answers about the GPL, please see:
Documentation
--------------
+=============
The Linux kernel source tree has a large range of documents that are
invaluable for learning how to interact with the kernel community. When
@@ -183,7 +184,7 @@ They can also be generated on LaTeX and ePub formats with::
make epubdocs
Becoming A Kernel Developer
----------------------------
+===========================
If you do not know anything about Linux kernel development, you should
look at the Linux KernelNewbies project:
@@ -228,7 +229,7 @@ repository of the kernel code may be found at:
The development process
------------------------
+=======================
Linux kernel development process currently consists of a few different
main kernel "branches" and lots of different subsystem-specific kernel
@@ -240,7 +241,7 @@ branches. These different branches are:
- linux-next integration testing tree
Mainline tree
-~~~~~~~~~~~~~
+-------------
The mainline tree is maintained by Linus Torvalds, and can be found at
https://kernel.org or in the repo. Its development process is as follows:
@@ -276,7 +277,7 @@ mailing list about kernel releases:
preconceived timeline."*
Various stable trees with multiple major numbers
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------------------------------
Kernels with 3-part versions are -stable kernels. They contain
relatively small and critical fixes for security problems or significant
@@ -299,7 +300,7 @@ in the kernel tree documents what kinds of changes are acceptable for
the -stable tree, and how the release process works.
Subsystem-specific trees
-~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------
The maintainers of the various kernel subsystems --- and also many
kernel subsystem developers --- expose their current state of
@@ -324,7 +325,7 @@ accepted, or rejected. Most of these patchwork sites are listed at
https://patchwork.kernel.org/.
linux-next integration testing tree
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-----------------------------------
Before updates from subsystem trees are merged into the mainline tree,
they need to be integration-tested. For this purpose, a special
@@ -339,7 +340,7 @@ Adventurous testers are very welcome to runtime-test the linux-next.
Bug Reporting
--------------
+=============
The file 'Documentation/admin-guide/reporting-issues.rst' in the main kernel
source directory describes how to report a possible kernel bug, and details
@@ -348,7 +349,7 @@ down the problem.
Managing bug reports
---------------------
+====================
One of the best ways to put into practice your hacking skills is by fixing
bugs reported by other people. Not only will you help to make the kernel
@@ -367,7 +368,7 @@ kernel get filed there.
Mailing lists
--------------
+=============
As some of the above documents describe, the majority of the core kernel
developers participate on the Linux Kernel Mailing list. Details on how
@@ -426,7 +427,7 @@ Above all, please remember to show respect to other subscribers.
Working with the community
---------------------------
+==========================
The goal of the kernel community is to provide the best possible kernel
there is. When you submit a patch for acceptance, it will be reviewed
@@ -468,7 +469,7 @@ resend it.
Differences between the kernel community and corporate structures
------------------------------------------------------------------
+=================================================================
The kernel community works differently than most traditional corporate
development environments. Here are a list of things that you can try to
@@ -515,7 +516,7 @@ English before sending them.
Break up your changes
----------------------
+=====================
The Linux kernel community does not gladly accept large chunks of code
dropped on it all at once. The changes need to be properly introduced,
@@ -571,7 +572,7 @@ that are unfinished and will be "fixed up later."
Justify your change
--------------------
+===================
Along with breaking up your patches, it is very important for you to let
the Linux community know why they should add this change. New features
@@ -579,7 +580,7 @@ must be justified as being needed and useful.
Document your change
---------------------
+====================
When sending in your patches, pay special attention to what you say in
the text in your email. This information will become the ChangeLog
diff --git a/Documentation/process/index.rst b/Documentation/process/index.rst
index 6cb732dfcc72..265ee20eb7dd 100644
--- a/Documentation/process/index.rst
+++ b/Documentation/process/index.rst
@@ -16,7 +16,7 @@ it much easier for you to get your changes merged with a minimum of
trouble.
An introduction to how kernel development works
------------------------------------------------
+===============================================
Read these documents first: an understanding of the material here will ease
your entry into the kernel community.
@@ -30,7 +30,7 @@ your entry into the kernel community.
submit-checklist
Tools and technical guides for kernel developers
-------------------------------------------------
+================================================
This is a collection of material that kernel developers should be familiar
with.
@@ -50,7 +50,7 @@ with.
botching-up-ioctls
Policy guides and developer statements
---------------------------------------
+======================================
These are the rules that we try to live by in the kernel community (and
beyond).
@@ -70,7 +70,7 @@ beyond).
researcher-guidelines
Dealing with bugs
------------------
+=================
Bugs are a fact of life; it is important that we handle them properly.
The documents below describe our policies around the handling of a couple
@@ -84,7 +84,7 @@ of special classes of bugs: regressions and security problems.
embargoed-hardware-issues
Maintainer information
-----------------------
+======================
How to find the people who will accept your patches.
@@ -95,7 +95,7 @@ How to find the people who will accept your patches.
maintainers
Other material
---------------
+==============
Here are some other guides to the community that are of interest to most
developers:
diff --git a/Documentation/process/kernel-docs.rst b/Documentation/process/kernel-docs.rst
index 8660493b91d0..3d2874365ba0 100644
--- a/Documentation/process/kernel-docs.rst
+++ b/Documentation/process/kernel-docs.rst
@@ -1,5 +1,6 @@
.. _kernel_docs:
+=====================================
Index of Further Kernel Documentation
=====================================
@@ -33,7 +34,7 @@ All documents are cataloged with the following fields: the document's
the exception of foundational books.
Docs at the Linux Kernel tree
------------------------------
+=============================
The Sphinx books should be built with ``make {htmldocs | pdfdocs | epubdocs}``.
@@ -48,7 +49,7 @@ The Sphinx books should be built with ``make {htmldocs | pdfdocs | epubdocs}``.
be more up to date than the web version.
On-line docs
-------------
+============
* Title: **Linux Kernel Mailing List Glossary**
@@ -73,7 +74,7 @@ On-line docs
actively maintained at https://github.com/sysprog21/lkmpg.
Published books
----------------
+===============
* Title: **Linux Kernel Debugging: Leverage proven tools and advanced techniques to effectively debug Linux kernels and kernel modules**
@@ -150,7 +151,7 @@ Published books
:Notes: Foundational book
Miscellaneous
--------------
+=============
* Name: **Cross-Referencing Linux**
diff --git a/Documentation/process/kernel-driver-statement.rst b/Documentation/process/kernel-driver-statement.rst
index a849790a68bc..7746fdeaa0cb 100644
--- a/Documentation/process/kernel-driver-statement.rst
+++ b/Documentation/process/kernel-driver-statement.rst
@@ -1,7 +1,8 @@
.. _process_statement_driver:
+=======================
Kernel Driver Statement
------------------------
+=======================
Position Statement on Linux Kernel Modules
==========================================
diff --git a/Documentation/process/kernel-enforcement-statement.rst b/Documentation/process/kernel-enforcement-statement.rst
index dc2d813b2e79..5bda031af067 100644
--- a/Documentation/process/kernel-enforcement-statement.rst
+++ b/Documentation/process/kernel-enforcement-statement.rst
@@ -1,7 +1,8 @@
.. _process_statement_kernel:
+==================================
Linux Kernel Enforcement Statement
-----------------------------------
+==================================
As developers of the Linux kernel, we have a keen interest in how our software
is used and how the license for our software is enforced. Compliance with the
diff --git a/Documentation/process/license-rules.rst b/Documentation/process/license-rules.rst
index 2ef44ada3f11..8a773de46549 100644
--- a/Documentation/process/license-rules.rst
+++ b/Documentation/process/license-rules.rst
@@ -2,6 +2,7 @@
.. _kernel_licensing:
+============================
Linux kernel licensing rules
============================
@@ -56,7 +57,7 @@ The valid identifiers used in the kernel are explained in the section
license list at https://spdx.org/licenses/ along with the license texts.
License identifier syntax
--------------------------
+=========================
1. Placement:
@@ -149,7 +150,7 @@ License identifier syntax
// SPDX-License-Identifier: GPL-1.0+ AND LGPL-2.1+
License identifiers
--------------------
+===================
The licenses currently used, as well as the licenses for code added to the
kernel, can be broken down into:
@@ -423,7 +424,7 @@ and extract right from the source, which is recommended by various FOSS
organizations, e.g. the `FSFE REUSE initiative <https://reuse.software/>`_.
_`MODULE_LICENSE`
------------------
+=================
Loadable kernel modules also require a MODULE_LICENSE() tag. This tag is
neither a replacement for proper source code license information
diff --git a/Documentation/process/magic-number.rst b/Documentation/process/magic-number.rst
index 7029c3c084ee..3237dcb9eedb 100644
--- a/Documentation/process/magic-number.rst
+++ b/Documentation/process/magic-number.rst
@@ -1,5 +1,6 @@
.. _magicnumbers:
+===================
Linux magic numbers
===================
diff --git a/Documentation/process/maintainer-handbooks.rst b/Documentation/process/maintainer-handbooks.rst
index 976391cec528..00068032ed47 100644
--- a/Documentation/process/maintainer-handbooks.rst
+++ b/Documentation/process/maintainer-handbooks.rst
@@ -2,6 +2,7 @@
.. _maintainer_handbooks_main:
+================================================================
Subsystem and maintainer tree specific development process notes
================================================================
diff --git a/Documentation/process/maintainer-kvm-x86.rst b/Documentation/process/maintainer-kvm-x86.rst
index 9183bd449762..0e3271e9f054 100644
--- a/Documentation/process/maintainer-kvm-x86.rst
+++ b/Documentation/process/maintainer-kvm-x86.rst
@@ -1,10 +1,11 @@
.. SPDX-License-Identifier: GPL-2.0
+=======
KVM x86
=======
Foreword
---------
+========
KVM strives to be a welcoming community; contributions from newcomers are
valued and encouraged. Please do not be discouraged or intimidated by the
length of this document and the many rules/guidelines it contains. Everyone
@@ -14,11 +15,11 @@ and learn from any mistakes you make, you will be welcomed with open arms, not
torches and pitchforks.
TL;DR
------
+=====
Testing is mandatory. Be consistent with established styles and patterns.
Trees
------
+=====
KVM x86 is currently in a transition period from being part of the main KVM
tree, to being "just another KVM arch". As such, KVM x86 is split across the
main KVM tree, ``git.kernel.org/pub/scm/virt/kvm/kvm.git``, and a KVM x86
@@ -34,7 +35,7 @@ Note, this transition period is expected to last quite some time, i.e. will be
the status quo for the foreseeable future.
Branches
-~~~~~~~~
+--------
The KVM x86 tree is organized into multiple topic branches. The purpose of
using finer-grained topic branches is to make it easier to keep tabs on an area
of development, and to limit the collateral damage of human errors and/or buggy
@@ -47,7 +48,7 @@ via a Cthulhu merge on an as-needed basis, i.e. when a topic branch is updated.
As a result, force pushes to ``next`` are common.
Lifecycle
-~~~~~~~~~
+---------
Fixes that target the current release, a.k.a. mainline, are typically applied
directly to the main KVM tree, i.e. do not route through the KVM x86 tree.
@@ -62,7 +63,7 @@ close around rc5 for new features, and a soft close around rc6 for fixes (for
the next release; see above for fixes that target the current release).
Timeline
-~~~~~~~~
+--------
Submissions are typically reviewed and applied in FIFO order, with some wiggle
room for the size of a series, patches that are "cache hot", etc. Fixes,
especially for the current release and or stable trees, get to jump the queue.
@@ -80,10 +81,10 @@ can, within reason, to ensure that your patches are ready to be merged! Pings
on series that break the build or fail tests lead to unhappy maintainers!
Development
------------
+===========
Base Tree/Branch
-~~~~~~~~~~~~~~~~
+----------------
Fixes that target the current release, a.k.a. mainline, should be based on
``git://git.kernel.org/pub/scm/virt/kvm/kvm.git master``. Note, fixes do not
automatically warrant inclusion in the current release. There is no singular
@@ -104,7 +105,7 @@ you're unsure whether a patch/series is truly multi-arch, err on the side of
caution and treat it as multi-arch, i.e. use a common base.
Coding Style
-~~~~~~~~~~~~
+------------
When it comes to style, naming, patterns, etc., consistency is the number one
priority in KVM x86. If all else fails, match what already exists.
@@ -121,14 +122,14 @@ they are intended only for KVM-internal consumption (there are plans to
privatize KVM's headers and exports to enforce this).
Comments
-~~~~~~~~
+--------
Write comments using imperative mood and avoid pronouns. Use comments to
provide a high level overview of the code, and/or to explain why the code does
what it does. Do not reiterate what the code literally does; let the code
speak for itself. If the code itself is inscrutable, comments will not help.
SDM and APM References
-~~~~~~~~~~~~~~~~~~~~~~
+----------------------
Much of KVM's code base is directly tied to architectural behavior defined in
Intel's Software Development Manual (SDM) and AMD's Architecture Programmer’s
Manual (APM). Use of "Intel's SDM" and "AMD's APM", or even just "SDM" or
@@ -146,7 +147,7 @@ Note, referencing the SDM/APM in changelogs to justify the change and provide
context is perfectly ok and encouraged.
Shortlog
-~~~~~~~~
+--------
The preferred prefix format is ``KVM: <topic>:``, where ``<topic>`` is one of::
- x86
@@ -191,7 +192,7 @@ limit. I.e. let the shortlog run a few characters over the standard limit if
you have good reason to do so.
Changelog
-~~~~~~~~~
+---------
Most importantly, write changelogs using imperative mood and avoid pronouns.
See :ref:`describe_changes` for more information, with one amendment: lead with
@@ -224,7 +225,7 @@ preference. E.g. having to skip one sentence to get to the context is less
painful than having to skip three paragraphs to get to "what's changing".
Fixes
-~~~~~
+-----
If a change fixes a KVM/kernel bug, add a Fixes: tag even if the change doesn't
need to be backported to stable kernels, and even if the change fixes a bug in
an older release.
@@ -235,13 +236,13 @@ KVM x86 opts out of backporting Fixes: by default. Some auto-selected patches
do get backported, but require explicit maintainer approval (search MANUALSEL).
Function References
-~~~~~~~~~~~~~~~~~~~
+-------------------
When a function is mentioned in a comment, changelog, or shortlog (or anywhere
for that matter), use the format ``function_name()``. The parentheses provide
context and disambiguate the reference.
Testing
--------
+=======
At a bare minimum, *all* patches in a series must build cleanly for KVM_INTEL=m
KVM_AMD=m, and KVM_WERROR=y. Building every possible combination of Kconfigs
isn't feasible, but the more the merrier. KVM_SMM, KVM_XEN, PROVE_LOCKING, and
@@ -270,7 +271,7 @@ If you can't fully test a change, e.g. due to lack of hardware, clearly state
what level of testing you were able to do, e.g. in the cover letter.
New Features
-~~~~~~~~~~~~
+------------
With one exception, new features *must* come with test coverage. KVM specific
tests aren't strictly required, e.g. if coverage is provided by running a
sufficiently enabled guest VM, or by running a related kernel selftest in a VM,
@@ -292,7 +293,7 @@ should clearly state what type of feedback is requested/expected. Do not abuse
the RFC process; RFCs will typically not receive in-depth review.
Bug Fixes
-~~~~~~~~~
+---------
Except for "obvious" found-by-inspection bugs, fixes must be accompanied by a
reproducer for the bug being fixed. In many cases the reproducer is implicit,
e.g. for build errors and test failures, but it should still be clear to
@@ -310,10 +311,10 @@ if a bug is really truly the end of the world before posting a fix without a
reproducer.
Posting
--------
+=======
Links
-~~~~~
+-----
Do not explicitly reference bug reports, prior versions of a patch/series, etc.
via ``In-Reply-To:`` headers. Using ``In-Reply-To:`` becomes an unholy mess
for large series and/or when the version count gets high, and ``In-Reply-To:``
@@ -329,7 +330,7 @@ formal Link: for bug reports and/or discussions that led to the patch. The
context of why a change was made is highly valuable for future readers.
Git Base
-~~~~~~~~
+--------
If you are using git version 2.9.0 or later (Googlers, this is all of you!),
use ``git format-patch`` with the ``--base`` flag to automatically include the
base tree information in the generated patches.
@@ -344,7 +345,7 @@ to yield ``--base=x/pmu``, where ``x`` is whatever name your repository uses to
track the KVM x86 remote.
Co-Posting Tests
-~~~~~~~~~~~~~~~~
+----------------
KVM selftests that are associated with KVM changes, e.g. regression tests for
bug fixes, should be posted along with the KVM changes as a single series. The
standard kernel rules for bisection apply, i.e. KVM changes that result in test
@@ -358,7 +359,7 @@ KVM patches, first post the KVM changes and then provide a lore Link: to the
KVM patch/series in the KVM-unit-tests patch(es).
Notifications
--------------
+=============
When a patch/series is officially accepted, a notification email will be sent
in reply to the original posting (cover letter for multi-patch series). The
notification will include the tree and topic branch, along with the SHA1s of
@@ -374,7 +375,7 @@ will be sent to the notification email explaining why the patch was dropped, as
well as the next steps.
SHA1 Stability
-~~~~~~~~~~~~~~
+--------------
SHA1s are not 100% guaranteed to be stable until they land in Linus' tree! A
SHA1 is *usually* stable once a notification has been sent, but things happen.
In most cases, an update to the notification email be provided if an applied
@@ -382,7 +383,7 @@ patch's SHA1 changes. However, in some scenarios, e.g. if all KVM x86 branches
need to be rebased, individual notifications will not be given.
Vulnerabilities
----------------
+===============
Bugs that can be exploited by the guest to attack the host (kernel or
userspace), or that can be exploited by a nested VM to *its* host (L2 attacking
L1), are of particular interest to KVM. Please follow the protocol for
diff --git a/Documentation/process/maintainer-netdev.rst b/Documentation/process/maintainer-netdev.rst
index 84ee60fceef2..6092d403e8b2 100644
--- a/Documentation/process/maintainer-netdev.rst
+++ b/Documentation/process/maintainer-netdev.rst
@@ -7,7 +7,7 @@ Networking subsystem (netdev)
=============================
tl;dr
------
+=====
- designate your patch to a tree - ``[PATCH net]`` or ``[PATCH net-next]``
- for fixes the ``Fixes:`` tag is required, regardless of the tree
@@ -16,7 +16,7 @@ tl;dr
- reverse xmas tree
netdev
-------
+======
netdev is a mailing list for all network-related Linux stuff. This
includes anything found under net/ (i.e. core code like IPv6) and
@@ -34,7 +34,7 @@ Linux development (i.e. RFC, review, comments, etc.) takes place on
netdev.
Development cycle
------------------
+=================
Here is a bit of background information on
the cadence of Linux development. Each new release starts off with a
@@ -60,7 +60,7 @@ probably imminent. If the most recent tag is a final release tag
and ``net-next`` is closed.
git trees and patch flow
-------------------------
+========================
There are two networking trees (git repositories) in play. Both are
driven by David Miller, the main network maintainer. There is the
@@ -107,12 +107,12 @@ focus for ``net`` is on stabilization and bug fixes.
Finally, the vX.Y gets released, and the whole cycle starts over.
netdev patch review
--------------------
+===================
.. _patch_status:
Patch status
-~~~~~~~~~~~~
+------------
Status of a patch can be checked by looking at the main patchwork
queue for netdev:
@@ -155,7 +155,7 @@ which carried them so if you have trouble finding your patch append
the value of ``Message-ID`` to the URL above.
Updating patch status
-~~~~~~~~~~~~~~~~~~~~~
+---------------------
Contributors and reviewers do not have the permissions to update patch
state directly in patchwork. Patchwork doesn't expose much information
@@ -188,7 +188,7 @@ Bot records its activity here:
https://netdev.bots.linux.dev/pw-bot.html
Review timelines
-~~~~~~~~~~~~~~~~
+----------------
Generally speaking, the patches get triaged quickly (in less than
48h). But be patient, if your patch is active in patchwork (i.e. it's
@@ -214,7 +214,7 @@ landed - describe your best guess and ask if it's correct. For example::
.. _Changes requested:
Changes requested
-~~~~~~~~~~~~~~~~~
+-----------------
Patches :ref:`marked<patch_status>` as ``Changes Requested`` need
to be revised. The new version should come with a change log,
@@ -241,14 +241,14 @@ had to ask in previous discussions. Occasionally the update of
the commit message will be the only change in the new version.
Partial resends
-~~~~~~~~~~~~~~~
+---------------
Please always resend the entire patch series and make sure you do number your
patches such that it is clear this is the latest and greatest set of patches
that can be applied. Do not try to resend just the patches which changed.
Handling misapplied patches
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------
Occasionally a patch series gets applied before receiving critical feedback,
or the wrong version of a series gets applied.
@@ -265,7 +265,7 @@ problems with the reverted commit. Reverts should be used as a last resort,
when original change is completely wrong; incremental fixes are preferred.
Stable tree
-~~~~~~~~~~~
+-----------
While it used to be the case that netdev submissions were not supposed
to carry explicit ``CC: stable@xxxxxxxxxxxxxxx`` tags that is no longer
@@ -274,7 +274,7 @@ the case today. Please follow the standard stable rules in
and make sure you include appropriate Fixes tags!
Security fixes
-~~~~~~~~~~~~~~
+--------------
Do not email netdev maintainers directly if you think you discovered
a bug that might have possible security implications.
@@ -286,7 +286,7 @@ as possible alternative mechanisms.
Co-posting changes to user space components
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------------
User space code exercising kernel features should be posted
alongside kernel patches. This gives reviewers a chance to see
@@ -313,7 +313,7 @@ Posting as one thread is discouraged because it confuses patchwork
(as of patchwork 2.2.2).
Preparing changes
------------------
+=================
Attention to detail is important. Re-read your own work as if you were the
reviewer. You can start with using ``checkpatch.pl``, perhaps even with
@@ -331,7 +331,7 @@ Finally, go back and read
to be sure you are not repeating some common mistake documented there.
Indicating target tree
-~~~~~~~~~~~~~~~~~~~~~~
+----------------------
To help maintainers and CI bots you should explicitly mark which tree
your patch is targeting. Assuming that you use git, use the prefix
@@ -343,7 +343,7 @@ Use ``net`` instead of ``net-next`` (always lower case) in the above for
bug-fix ``net`` content.
Dividing work into patches
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------
Put yourself in the shoes of the reviewer. Each patch is read separately
and therefore should constitute a comprehensible step towards your stated
@@ -357,7 +357,7 @@ with better review coverage. Re-posting large series also increases the mailing
list traffic.
Multi-line comments
-~~~~~~~~~~~~~~~~~~~
+-------------------
Comment style convention is slightly different for networking and most of
the tree. Instead of this::
@@ -374,7 +374,7 @@ it is requested that you make it look like this::
*/
Local variable ordering ("reverse xmas tree", "RCS")
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------------------------------
Netdev has a convention for ordering local variables in functions.
Order the variable declaration lines longest to shortest, e.g.::
@@ -387,14 +387,14 @@ If there are dependencies between the variables preventing the ordering
move the initialization out of line.
Format precedence
-~~~~~~~~~~~~~~~~~
+-----------------
When working in existing code which uses nonstandard formatting make
your code follow the most recent guidelines, so that eventually all code
in the domain of netdev is in the preferred format.
Resending after review
-~~~~~~~~~~~~~~~~~~~~~~
+----------------------
Allow at least 24 hours to pass between postings. This will ensure reviewers
from all geographical locations have a chance to chime in. Do not wait
@@ -410,10 +410,10 @@ not as a reply to the previous posting. Change log should include a link
to the previous posting (see :ref:`Changes requested`).
Testing
--------
+=======
Expected level of testing
-~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------
At the very minimum your changes must survive an ``allyesconfig`` and an
``allmodconfig`` build with ``W=1`` set without new warnings or failures.
@@ -426,7 +426,7 @@ You are expected to test your changes on top of the relevant networking
tree (``net`` or ``net-next``) and not e.g. a stable tree or ``linux-next``.
patchwork checks
-~~~~~~~~~~~~~~~~
+----------------
Checks in patchwork are mostly simple wrappers around existing kernel
scripts, the sources are available at:
@@ -440,7 +440,7 @@ gets overloaded very easily and netdev@vger really doesn't need more
traffic if we can help it.
netdevsim
-~~~~~~~~~
+---------
``netdevsim`` is a test driver which can be used to exercise driver
configuration APIs without requiring capable hardware.
@@ -456,7 +456,7 @@ new ``netdevsim`` features must be accompanied by selftests under
``tools/testing/selftests/``.
Reviewer guidance
------------------
+=================
Reviewing other people's patches on the list is highly encouraged,
regardless of the level of expertise. For general guidance and
@@ -471,7 +471,7 @@ review of submissions and not focus exclusively on trivial or subjective
matters like code formatting, tags etc.
Testimonials / feedback
------------------------
+=======================
Some companies use peer feedback in employee performance reviews.
Please feel free to request feedback from netdev maintainers,
diff --git a/Documentation/process/maintainer-soc-clean-dts.rst b/Documentation/process/maintainer-soc-clean-dts.rst
index 1b32430d0cfc..c9b7824d00f2 100644
--- a/Documentation/process/maintainer-soc-clean-dts.rst
+++ b/Documentation/process/maintainer-soc-clean-dts.rst
@@ -5,14 +5,14 @@ SoC Platforms with DTS Compliance Requirements
==============================================
Overview
---------
+========
SoC platforms or subarchitectures should follow all the rules from
Documentation/process/maintainer-soc.rst. This document referenced in
MAINTAINERS impose additional requirements listed below.
Strict DTS DT Schema and dtc Compliance
----------------------------------------
+=======================================
No changes to the SoC platform Devicetree sources (DTS files) should introduce
new ``make dtbs_check W=1`` warnings. Warnings in a new board DTS, which are
diff --git a/Documentation/process/maintainer-soc.rst b/Documentation/process/maintainer-soc.rst
index 12637530d68f..9e953ce0dae4 100644
--- a/Documentation/process/maintainer-soc.rst
+++ b/Documentation/process/maintainer-soc.rst
@@ -5,7 +5,7 @@ SoC Subsystem
=============
Overview
---------
+========
The SoC subsystem is a place of aggregation for SoC-specific code.
The main components of the subsystem are:
@@ -52,14 +52,14 @@ changes. Each architecture has its own maintainers that are responsible for
architectural details, CPU errata and the like.
Information for (new) Submaintainers
-------------------------------------
+====================================
As new platforms spring up, they often bring with them new submaintainers,
many of whom work for the silicon vendor, and may not be familiar with the
process.
Devicetree ABI Stability
-~~~~~~~~~~~~~~~~~~~~~~~~
+------------------------
Perhaps one of the most important things to highlight is that dt-bindings
document the ABI between the devicetree and the kernel.
@@ -73,7 +73,7 @@ expected impact on existing users, such as bootloaders or other operating
systems.
Driver Branch Dependencies
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------
A common problem is synchronizing changes between device drivers and devicetree
files. Even if a change is compatible in both directions, this may require
@@ -106,7 +106,7 @@ There are multiple ways to deal with this:
removing them in a later release
Devicetree Naming Convention
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+----------------------------
The general naming scheme for devicetree files is as follows. The aspects of a
platform that are set at the SoC level, like CPU cores, are contained in a file
@@ -125,7 +125,7 @@ Directories are usually named after the vendor of the SoC at the time of its
inclusion, leading to some historical directory names in the tree.
Validating Devicetree Files
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
+---------------------------
``make dtbs_check`` can be used to validate that devicetree files are compliant
with the dt-bindings that describe the ABI. Please read the section
@@ -139,7 +139,7 @@ If in any doubt about a devicetree change, reach out to the devicetree
maintainers.
Branches and Pull Requests
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+--------------------------
Just as the main SoC tree has several branches, it is expected that
submaintainers will do the same. Driver, defconfig and devicetree changes should
diff --git a/Documentation/process/management-style.rst b/Documentation/process/management-style.rst
index dfbc69bf49d4..7e112e0f166c 100644
--- a/Documentation/process/management-style.rst
+++ b/Documentation/process/management-style.rst
@@ -1,5 +1,6 @@
.. _managementstyle:
+=============================
Linux kernel management style
=============================
@@ -32,7 +33,7 @@ Anyway, here goes:
.. _decisions:
1) Decisions
-------------
+============
Everybody thinks managers make decisions, and that decision-making is
important. The bigger and more painful the decision, the bigger the
@@ -134,7 +135,7 @@ have screwed up on.
2) People
----------
+=========
Most people are idiots, and being a manager means you'll have to deal
with it, and perhaps more importantly, that **they** have to deal with
@@ -181,7 +182,7 @@ trust somebody who is so clearly hiding their true character.
3) People II - the Good Kind
-----------------------------
+============================
While it turns out that most people are idiots, the corollary to that is
sadly that you are one too, and that while we can all bask in the secure
@@ -214,7 +215,7 @@ direction, just don't push too hard.
4) Placing blame
-----------------
+================
Things will go wrong, and people want somebody to blame. Tag, you're it.
@@ -240,7 +241,7 @@ by now.
5) Things to avoid
-------------------
+==================
There's one thing people hate even more than being called "d*ckhead",
and that is being called a "d*ckhead" in a sanctimonious voice. The
@@ -273,7 +274,7 @@ have about criticism.
6) Why me?
-----------
+==========
Since your main responsibility seems to be to take the blame for other
peoples mistakes, and make it painfully obvious to everybody else that
diff --git a/Documentation/process/programming-language.rst b/Documentation/process/programming-language.rst
index bc56dee6d0bc..2afa9409fe5a 100644
--- a/Documentation/process/programming-language.rst
+++ b/Documentation/process/programming-language.rst
@@ -1,5 +1,6 @@
.. _programming_language:
+====================
Programming Language
====================
@@ -13,7 +14,7 @@ This dialect contains many extensions to the language [gnu-extensions]_,
and many of them are used within the kernel as a matter of course.
Attributes
-----------
+==========
One of the common extensions used throughout the kernel are attributes
[gcc-attribute-syntax]_. Attributes allow to introduce
@@ -32,7 +33,7 @@ in order to feature detect which ones can be used and/or to shorten the code.
Please refer to ``include/linux/compiler_attributes.h`` for more information.
Rust
-----
+====
The kernel has experimental support for the Rust programming language
[rust-language]_ under ``CONFIG_RUST``. It is compiled with ``rustc`` [rustc]_
diff --git a/Documentation/process/researcher-guidelines.rst b/Documentation/process/researcher-guidelines.rst
index d159cd4f5e5b..5a7a212cf76b 100644
--- a/Documentation/process/researcher-guidelines.rst
+++ b/Documentation/process/researcher-guidelines.rst
@@ -2,8 +2,9 @@
.. _researcher_guidelines:
+=====================
Researcher Guidelines
-+++++++++++++++++++++
+=====================
The Linux kernel community welcomes transparent research on the Linux
kernel, the activities involved in producing it, and any other byproducts
diff --git a/Documentation/process/security-bugs.rst b/Documentation/process/security-bugs.rst
index 692a3ba56cca..c40c9b81b48a 100644
--- a/Documentation/process/security-bugs.rst
+++ b/Documentation/process/security-bugs.rst
@@ -1,5 +1,6 @@
.. _securitybugs:
+=============
Security bugs
=============
@@ -9,7 +10,7 @@ disclosed as quickly as possible. Please report security bugs to the
Linux kernel security team.
Contact
--------
+=======
The Linux kernel security team can be contacted by email at
<security@xxxxxxxxxx>. This is a private list of security officers
@@ -34,7 +35,7 @@ issue if all the details are hidden away in attachments. Think of it like a
reproduction steps, and follow it with a proposed fix, all in plain text.
Disclosure and embargoed information
-------------------------------------
+====================================
The security list is not a disclosure channel. For that, see Coordination
below.
@@ -64,7 +65,7 @@ of the report are treated confidentially even after the embargo has been
lifted, in perpetuity.
Coordination with other groups
-------------------------------
+==============================
While the kernel security team solely focuses on getting bugs fixed,
other groups focus on fixing issues in distros and coordinating
@@ -94,7 +95,7 @@ fix is accepted do not Cc: "linux-distros", and after it's merged do not
Cc: the kernel security team.
CVE assignment
---------------
+==============
The security team does not assign CVEs, nor do we require them for
reports or fixes, as this can needlessly complicate the process and may
@@ -104,7 +105,7 @@ MITRE directly. However under no circumstances will a patch inclusion
be delayed to wait for a CVE identifier to arrive.
Non-disclosure agreements
--------------------------
+=========================
The Linux kernel security team is not a formal body and therefore unable
to enter any non-disclosure agreements.
diff --git a/Documentation/process/submit-checklist.rst b/Documentation/process/submit-checklist.rst
index b1bc2d37bd0a..c4cd62b272df 100644
--- a/Documentation/process/submit-checklist.rst
+++ b/Documentation/process/submit-checklist.rst
@@ -1,7 +1,8 @@
.. _submitchecklist:
+=======================================
Linux Kernel patch submission checklist
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+=======================================
Here are some basic things that developers should do if they want to see their
kernel patch submissions accepted more quickly.
diff --git a/Documentation/process/volatile-considered-harmful.rst b/Documentation/process/volatile-considered-harmful.rst
index 7eb6bd7c9214..7cfdb91980d5 100644
--- a/Documentation/process/volatile-considered-harmful.rst
+++ b/Documentation/process/volatile-considered-harmful.rst
@@ -1,8 +1,9 @@
.. _volatile_considered_harmful:
+================================================
Why the "volatile" type class should not be used
-------------------------------------------------
+================================================
C programmers have often taken volatile to mean that the variable could be
changed outside of the current thread of execution; as a result, they are
--
2.34.1
