Merge tag 'docs-5.1' of git://git.lwn.net/linux
Pull documentation updates from Jonathan Corbet: "A fairly routine cycle for docs - lots of typo fixes, some new documents, and more translations. There's also some LICENSES adjustments from Thomas" * tag 'docs-5.1' of git://git.lwn.net/linux: (74 commits) docs: Bring some order to filesystem documentation Documentation/locking/lockdep: Drop last two chars of sample states doc: rcu: Suspicious RCU usage is a warning docs: driver-api: iio: fix errors in documentation Documentation/process/howto: Update for 4.x -> 5.x versioning docs: Explicitly state that the 'Fixes:' tag shouldn't split lines doc: security: Add kern-doc for lsm_hooks.h doc: sctp: Merge and clean up rst files Docs: Correct /proc/stat path scripts/spdxcheck.py: fix C++ comment style detection doc: fix typos in license-rules.rst Documentation: fix admin-guide/README.rst minimum gcc version requirement doc: process: complete removal of info about -git patches doc: translations: sync translations 'remove info about -git patches' perf-security: wrap paragraphs on 72 columns perf-security: elaborate on perf_events/Perf privileged users perf-security: document collected perf_events/Perf data categories perf-security: document perf_events/Perf resource control sysfs.txt: add note on available attribute macros docs: kernel-doc: typo "if ... if" -> "if ... is" ...
This commit is contained in:
Linus Torvalds
@@ -443,7 +443,7 @@ In function prototypes, include parameter names with their data types.
|
||||
Although this is not required by the C language, it is preferred in Linux
|
||||
because it is a simple way to add valuable information for the reader.
|
||||
|
||||
Do not use the `extern' keyword with function prototypes as this makes
|
||||
Do not use the ``extern`` keyword with function prototypes as this makes
|
||||
lines longer and isn't strictly necessary.
|
||||
|
||||
|
||||
@@ -595,26 +595,43 @@ values. To do the latter, you can stick the following in your .emacs file:
|
||||
(* (max steps 1)
|
||||
c-basic-offset)))
|
||||
|
||||
(add-hook 'c-mode-common-hook
|
||||
(lambda ()
|
||||
;; Add kernel style
|
||||
(c-add-style
|
||||
"linux-tabs-only"
|
||||
'("linux" (c-offsets-alist
|
||||
(arglist-cont-nonempty
|
||||
c-lineup-gcc-asm-reg
|
||||
c-lineup-arglist-tabs-only))))))
|
||||
(dir-locals-set-class-variables
|
||||
'linux-kernel
|
||||
'((c-mode . (
|
||||
(c-basic-offset . 8)
|
||||
(c-label-minimum-indentation . 0)
|
||||
(c-offsets-alist . (
|
||||
(arglist-close . c-lineup-arglist-tabs-only)
|
||||
(arglist-cont-nonempty .
|
||||
(c-lineup-gcc-asm-reg c-lineup-arglist-tabs-only))
|
||||
(arglist-intro . +)
|
||||
(brace-list-intro . +)
|
||||
(c . c-lineup-C-comments)
|
||||
(case-label . 0)
|
||||
(comment-intro . c-lineup-comment)
|
||||
(cpp-define-intro . +)
|
||||
(cpp-macro . -1000)
|
||||
(cpp-macro-cont . +)
|
||||
(defun-block-intro . +)
|
||||
(else-clause . 0)
|
||||
(func-decl-cont . +)
|
||||
(inclass . +)
|
||||
(inher-cont . c-lineup-multi-inher)
|
||||
(knr-argdecl-intro . 0)
|
||||
(label . -1000)
|
||||
(statement . 0)
|
||||
(statement-block-intro . +)
|
||||
(statement-case-intro . +)
|
||||
(statement-cont . +)
|
||||
(substatement . +)
|
||||
))
|
||||
(indent-tabs-mode . t)
|
||||
(show-trailing-whitespace . t)
|
||||
))))
|
||||
|
||||
(add-hook 'c-mode-hook
|
||||
(lambda ()
|
||||
(let ((filename (buffer-file-name)))
|
||||
;; Enable kernel mode for the appropriate files
|
||||
(when (and filename
|
||||
(string-match (expand-file-name "~/src/linux-trees")
|
||||
filename))
|
||||
(setq indent-tabs-mode t)
|
||||
(setq show-trailing-whitespace t)
|
||||
(c-set-style "linux-tabs-only")))))
|
||||
(dir-locals-set-directory-class
|
||||
(expand-file-name "~/src/linux-trees")
|
||||
'linux-kernel)
|
||||
|
||||
This will make emacs go better with the kernel coding style for C
|
||||
files below ``~/src/linux-trees``.
|
||||
@@ -921,7 +938,37 @@ result. Typical examples would be functions that return pointers; they use
|
||||
NULL or the ERR_PTR mechanism to report failure.
|
||||
|
||||
|
||||
17) Don't re-invent the kernel macros
|
||||
17) Using bool
|
||||
--------------
|
||||
|
||||
The Linux kernel bool type is an alias for the C99 _Bool type. bool values can
|
||||
only evaluate to 0 or 1, and implicit or explicit conversion to bool
|
||||
automatically converts the value to true or false. When using bool types the
|
||||
!! construction is not needed, which eliminates a class of bugs.
|
||||
|
||||
When working with bool values the true and false definitions should be used
|
||||
instead of 1 and 0.
|
||||
|
||||
bool function return types and stack variables are always fine to use whenever
|
||||
appropriate. Use of bool is encouraged to improve readability and is often a
|
||||
better option than 'int' for storing boolean values.
|
||||
|
||||
Do not use bool if cache line layout or size of the value matters, as its size
|
||||
and alignment varies based on the compiled architecture. Structures that are
|
||||
optimized for alignment and size should not use bool.
|
||||
|
||||
If a structure has many true/false values, consider consolidating them into a
|
||||
bitfield with 1 bit members, or using an appropriate fixed width type, such as
|
||||
u8.
|
||||
|
||||
Similarly for function arguments, many true/false values can be consolidated
|
||||
into a single bitwise 'flags' argument and 'flags' can often be a more
|
||||
readable alternative if the call-sites have naked true/false constants.
|
||||
|
||||
Otherwise limited use of bool in structures and arguments can improve
|
||||
readability.
|
||||
|
||||
18) Don't re-invent the kernel macros
|
||||
-------------------------------------
|
||||
|
||||
The header file include/linux/kernel.h contains a number of macros that
|
||||
@@ -944,7 +991,7 @@ need them. Feel free to peruse that header file to see what else is already
|
||||
defined that you shouldn't reproduce in your code.
|
||||
|
||||
|
||||
18) Editor modelines and other cruft
|
||||
19) Editor modelines and other cruft
|
||||
------------------------------------
|
||||
|
||||
Some editors can interpret configuration information embedded in source files,
|
||||
@@ -978,7 +1025,7 @@ own custom mode, or may have some other magic method for making indentation
|
||||
work correctly.
|
||||
|
||||
|
||||
19) Inline assembly
|
||||
20) Inline assembly
|
||||
-------------------
|
||||
|
||||
In architecture-specific code, you may need to use inline assembly to interface
|
||||
@@ -1010,7 +1057,7 @@ the next instruction in the assembly output:
|
||||
: /* outputs */ : /* inputs */ : /* clobbers */);
|
||||
|
||||
|
||||
20) Conditional Compilation
|
||||
21) Conditional Compilation
|
||||
---------------------------
|
||||
|
||||
Wherever possible, don't use preprocessor conditionals (#if, #ifdef) in .c
|
||||
|
||||
@@ -225,7 +225,7 @@ Cross-Reference project, which is able to present source code in a
|
||||
self-referential, indexed webpage format. An excellent up-to-date
|
||||
repository of the kernel code may be found at:
|
||||
|
||||
http://lxr.free-electrons.com/
|
||||
https://elixir.bootlin.com/
|
||||
|
||||
|
||||
The development process
|
||||
@@ -235,23 +235,21 @@ Linux kernel development process currently consists of a few different
|
||||
main kernel "branches" and lots of different subsystem-specific kernel
|
||||
branches. These different branches are:
|
||||
|
||||
- main 4.x kernel tree
|
||||
- 4.x.y -stable kernel tree
|
||||
- 4.x -git kernel patches
|
||||
- subsystem specific kernel trees and patches
|
||||
- the 4.x -next kernel tree for integration tests
|
||||
- Linus's mainline tree
|
||||
- Various stable trees with multiple major numbers
|
||||
- Subsystem-specific trees
|
||||
- linux-next integration testing tree
|
||||
|
||||
4.x kernel tree
|
||||
~~~~~~~~~~~~~~~
|
||||
Mainline tree
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
4.x kernels are maintained by Linus Torvalds, and can be found on
|
||||
https://kernel.org in the pub/linux/kernel/v4.x/ directory. Its development
|
||||
process is as follows:
|
||||
Mainline tree are maintained by Linus Torvalds, and can be found at
|
||||
https://kernel.org or in the repo. Its development process is as follows:
|
||||
|
||||
- As soon as a new kernel is released a two weeks window is open,
|
||||
during this period of time maintainers can submit big diffs to
|
||||
Linus, usually the patches that have already been included in the
|
||||
-next kernel for a few weeks. The preferred way to submit big changes
|
||||
linux-next for a few weeks. The preferred way to submit big changes
|
||||
is using git (the kernel's source management tool, more information
|
||||
can be found at https://git-scm.com/) but plain patches are also just
|
||||
fine.
|
||||
@@ -278,21 +276,19 @@ mailing list about kernel releases:
|
||||
released according to perceived bug status, not according to a
|
||||
preconceived timeline."*
|
||||
|
||||
4.x.y -stable kernel tree
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
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
|
||||
regressions discovered in a given 4.x kernel.
|
||||
regressions discovered in a given major mainline release, with the first
|
||||
2-part of version number are the same correspondingly.
|
||||
|
||||
This is the recommended branch for users who want the most recent stable
|
||||
kernel and are not interested in helping test development/experimental
|
||||
versions.
|
||||
|
||||
If no 4.x.y kernel is available, then the highest numbered 4.x
|
||||
kernel is the current stable kernel.
|
||||
|
||||
4.x.y are maintained by the "stable" team <stable@vger.kernel.org>, and
|
||||
Stable trees are maintained by the "stable" team <stable@vger.kernel.org>, and
|
||||
are released as needs dictate. The normal release period is approximately
|
||||
two weeks, but it can be longer if there are no pressing problems. A
|
||||
security-related problem, instead, can cause a release to happen almost
|
||||
@@ -302,17 +298,8 @@ The file :ref:`Documentation/process/stable-kernel-rules.rst <stable_kernel_rule
|
||||
in the kernel tree documents what kinds of changes are acceptable for
|
||||
the -stable tree, and how the release process works.
|
||||
|
||||
4.x -git patches
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
These are daily snapshots of Linus' kernel tree which are managed in a
|
||||
git repository (hence the name.) These patches are usually released
|
||||
daily and represent the current state of Linus' tree. They are more
|
||||
experimental than -rc kernels since they are generated automatically
|
||||
without even a cursory glance to see if they are sane.
|
||||
|
||||
Subsystem Specific kernel trees and patches
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
Subsystem-specific trees
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The maintainers of the various kernel subsystems --- and also many
|
||||
kernel subsystem developers --- expose their current state of
|
||||
@@ -336,19 +323,19 @@ revisions to it, and maintainers can mark patches as under review,
|
||||
accepted, or rejected. Most of these patchwork sites are listed at
|
||||
https://patchwork.kernel.org/.
|
||||
|
||||
4.x -next kernel tree for integration tests
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
linux-next integration testing tree
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Before updates from subsystem trees are merged into the mainline 4.x
|
||||
tree, they need to be integration-tested. For this purpose, a special
|
||||
Before updates from subsystem trees are merged into the mainline tree,
|
||||
they need to be integration-tested. For this purpose, a special
|
||||
testing repository exists into which virtually all subsystem trees are
|
||||
pulled on an almost daily basis:
|
||||
|
||||
https://git.kernel.org/?p=linux/kernel/git/next/linux-next.git
|
||||
|
||||
This way, the -next kernel gives a summary outlook onto what will be
|
||||
This way, the linux-next gives a summary outlook onto what will be
|
||||
expected to go into the mainline kernel at the next merge period.
|
||||
Adventurous testers are very welcome to runtime-test the -next kernel.
|
||||
Adventurous testers are very welcome to runtime-test the linux-next.
|
||||
|
||||
|
||||
Bug Reporting
|
||||
|
||||
@@ -565,7 +565,7 @@ Miscellaneous
|
||||
|
||||
* Name: **Cross-Referencing Linux**
|
||||
|
||||
:URL: http://lxr.free-electrons.com/
|
||||
:URL: https://elixir.bootlin.com/
|
||||
:Keywords: Browsing source code.
|
||||
:Description: Another web-based Linux kernel source code browser.
|
||||
Lots of cross references to variables and functions. You can see
|
||||
|
||||
@@ -62,7 +62,7 @@ License identifier syntax
|
||||
|
||||
The SPDX license identifier in kernel files shall be added at the first
|
||||
possible line in a file which can contain a comment. For the majority
|
||||
or files this is the first line, except for scripts which require the
|
||||
of files this is the first line, except for scripts which require the
|
||||
'#!PATH_TO_INTERPRETER' in the first line. For those scripts the SPDX
|
||||
identifier goes into the second line.
|
||||
|
||||
@@ -368,7 +368,69 @@ kernel, can be broken down into:
|
||||
|
||||
|
||||
All SPDX license identifiers and exceptions must have a corresponding file
|
||||
in the LICENSE subdirectories. This is required to allow tool
|
||||
in the LICENSES subdirectories. This is required to allow tool
|
||||
verification (e.g. checkpatch.pl) and to have the licenses ready to read
|
||||
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
|
||||
(SPDX-License-Identifier) nor in any way relevant for expressing or
|
||||
determining the exact license under which the source code of the module
|
||||
is provided.
|
||||
|
||||
The sole purpose of this tag is to provide sufficient information
|
||||
whether the module is free software or proprietary for the kernel
|
||||
module loader and for user space tools.
|
||||
|
||||
The valid license strings for MODULE_LICENSE() are:
|
||||
|
||||
============================= =============================================
|
||||
"GPL" Module is licensed under GPL version 2. This
|
||||
does not express any distinction between
|
||||
GPL-2.0-only or GPL-2.0-or-later. The exact
|
||||
license information can only be determined
|
||||
via the license information in the
|
||||
corresponding source files.
|
||||
|
||||
"GPL v2" Same as "GPL". It exists for historic
|
||||
reasons.
|
||||
|
||||
"GPL and additional rights" Historical variant of expressing that the
|
||||
module source is dual licensed under a
|
||||
GPL v2 variant and MIT license. Please do
|
||||
not use in new code.
|
||||
|
||||
"Dual MIT/GPL" The correct way of expressing that the
|
||||
module is dual licensed under a GPL v2
|
||||
variant or MIT license choice.
|
||||
|
||||
"Dual BSD/GPL" The module is dual licensed under a GPL v2
|
||||
variant or BSD license choice. The exact
|
||||
variant of the BSD license can only be
|
||||
determined via the license information
|
||||
in the corresponding source files.
|
||||
|
||||
"Dual MPL/GPL" The module is dual licensed under a GPL v2
|
||||
variant or Mozilla Public License (MPL)
|
||||
choice. The exact variant of the MPL
|
||||
license can only be determined via the
|
||||
license information in the corresponding
|
||||
source files.
|
||||
|
||||
"Proprietary" The module is under a proprietary license.
|
||||
This string is solely for proprietary third
|
||||
party modules and cannot be used for modules
|
||||
which have their source code in the kernel
|
||||
tree. Modules tagged that way are tainting
|
||||
the kernel with the 'P' flag when loaded and
|
||||
the kernel module loader refuses to link such
|
||||
modules against symbols which are exported
|
||||
with EXPORT_SYMBOL_GPL().
|
||||
============================= =============================================
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -169,14 +169,13 @@ driver for every different kernel version for every distribution is a
|
||||
nightmare, and trying to keep up with an ever changing kernel interface
|
||||
is also a rough job.
|
||||
|
||||
Simple, get your kernel driver into the main kernel tree (remember we
|
||||
are talking about GPL released drivers here, if your code doesn't fall
|
||||
under this category, good luck, you are on your own here, you leech
|
||||
<insert link to leech comment from Andrew and Linus here>.) If your
|
||||
driver is in the tree, and a kernel interface changes, it will be fixed
|
||||
up by the person who did the kernel change in the first place. This
|
||||
ensures that your driver is always buildable, and works over time, with
|
||||
very little effort on your part.
|
||||
Simple, get your kernel driver into the main kernel tree (remember we are
|
||||
talking about drivers released under a GPL-compatible license here, if your
|
||||
code doesn't fall under this category, good luck, you are on your own here,
|
||||
you leech). If your driver is in the tree, and a kernel interface changes,
|
||||
it will be fixed up by the person who did the kernel change in the first
|
||||
place. This ensures that your driver is always buildable, and works over
|
||||
time, with very little effort on your part.
|
||||
|
||||
The very good side effects of having your driver in the main kernel tree
|
||||
are:
|
||||
|
||||
@@ -38,6 +38,9 @@ Procedure for submitting patches to the -stable tree
|
||||
- If the patch covers files in net/ or drivers/net please follow netdev stable
|
||||
submission guidelines as described in
|
||||
:ref:`Documentation/networking/netdev-FAQ.rst <netdev-FAQ>`
|
||||
after first checking the stable networking queue at
|
||||
https://patchwork.ozlabs.org/bundle/davem/stable/?series=&submitter=&state=*&q=&archive=
|
||||
to ensure the requested patch is not already queued up.
|
||||
- Security patches should not be handled (solely) by the -stable review
|
||||
process but should follow the procedures in
|
||||
:ref:`Documentation/admin-guide/security-bugs.rst <securitybugs>`.
|
||||
@@ -98,9 +101,9 @@ text, like this:
|
||||
|
||||
commit <sha1> upstream.
|
||||
|
||||
Additionally, some patches submitted via Option 1 may have additional patch
|
||||
prerequisites which can be cherry-picked. This can be specified in the following
|
||||
format in the sign-off area:
|
||||
Additionally, some patches submitted via :ref:`option_1` may have additional
|
||||
patch prerequisites which can be cherry-picked. This can be specified in the
|
||||
following format in the sign-off area:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
|
||||
@@ -182,9 +182,11 @@ change five years from now.
|
||||
|
||||
If your patch fixes a bug in a specific commit, e.g. you found an issue using
|
||||
``git bisect``, please use the 'Fixes:' tag with the first 12 characters of
|
||||
the SHA-1 ID, and the one line summary. For example::
|
||||
the SHA-1 ID, and the one line summary. Do not split the tag across multiple
|
||||
lines, tags are exempt from the "wrap at 75 columns" rule in order to simplify
|
||||
parsing scripts. For example::
|
||||
|
||||
Fixes: e21d2170f366 ("video: remove unnecessary platform_set_drvdata()")
|
||||
Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed")
|
||||
|
||||
The following ``git config`` settings can be used to add a pretty format for
|
||||
outputting the above style in the ``git log`` or ``git show`` commands::
|
||||
|
||||
Reference in New Issue
Block a user