Merge tag 'docs-5.2' of git://git.lwn.net/linux
Pull documentation updates from Jonathan Corbet: "A reasonably busy cycle for docs, including: - Lots of work on the Chinese and Italian translations - Some license-rules clarifications from Christoph - Various build-script fixes - A new document on memory models - RST conversion of the live-patching docs - The usual collection of typo fixes and corrections" * tag 'docs-5.2' of git://git.lwn.net/linux: (140 commits) docs/livepatch: Unify style of livepatch documentation in the ReST format docs: livepatch: convert docs to ReST and rename to *.rst scripts/documentation-file-ref-check: detect broken :doc:`foo` scripts/documentation-file-ref-check: don't parse Next/ dir LICENSES: Rename other to deprecated LICENSES: Clearly mark dual license only licenses docs: Don't reference the ZLib license in license-rules.rst docs/vm: Minor editorial changes in the THP and hugetlbfs docs/vm: add documentation of memory models doc:it_IT: translation alignment doc: fix typo in PGP guide dontdiff: update with Kconfig build artifacts docs/zh_CN: fix typos in 1.Intro.rst file docs/zh_CN: redirect CoC docs to Chinese version doc: mm: migration doesn't use FOLL_SPLIT anymore docs: doc-guide: remove the extension from .rst files doc: kselftest: Fix KBUILD_OUTPUT usage instructions docs: trace: fix some Sphinx warnings docs: speculation.txt: mark example blocks as such docs: ntb.txt: add blank lines to clean up some Sphinx warnings ...
This commit is contained in:
Linus Torvalds
@@ -216,10 +216,12 @@ The tags in common use are:
|
||||
which can be found in :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
|
||||
Code without a proper signoff cannot be merged into the mainline.
|
||||
|
||||
- Co-developed-by: states that the patch was also created by another developer
|
||||
along with the original author. This is useful at times when multiple
|
||||
people work on a single patch. Note, this person also needs to have a
|
||||
Signed-off-by: line in the patch as well.
|
||||
- Co-developed-by: states that the patch was co-created by several developers;
|
||||
it is a used to give attribution to co-authors (in addition to the author
|
||||
attributed by the From: tag) when multiple people work on a single patch.
|
||||
Every Co-developed-by: must be immediately followed by a Signed-off-by: of
|
||||
the associated co-author. Details and examples can be found in
|
||||
:ref:`Documentation/process/submitting-patches.rst <submittingpatches>`.
|
||||
|
||||
- Acked-by: indicates an agreement by another developer (often a
|
||||
maintainer of the relevant code) that the patch is appropriate for
|
||||
|
||||
@@ -843,7 +843,8 @@ used.
|
||||
The kernel provides the following general purpose memory allocators:
|
||||
kmalloc(), kzalloc(), kmalloc_array(), kcalloc(), vmalloc(), and
|
||||
vzalloc(). Please refer to the API documentation for further information
|
||||
about them.
|
||||
about them. :ref:`Documentation/core-api/memory-allocation.rst
|
||||
<memory_allocation>`
|
||||
|
||||
The preferred form for passing a size of a struct is the following:
|
||||
|
||||
@@ -874,6 +875,9 @@ The preferred form for allocating a zeroed array is the following:
|
||||
Both forms check for overflow on the allocation size n * sizeof(...),
|
||||
and return NULL if that occurred.
|
||||
|
||||
These generic allocation functions all emit a stack dump on failure when used
|
||||
without __GFP_NOWARN so there is no use in emitting an additional failure
|
||||
message when NULL is returned.
|
||||
|
||||
15) The inline disease
|
||||
----------------------
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
.. SPDX-License-Identifier: GPL-2.0
|
||||
|
||||
.. _deprecated:
|
||||
|
||||
=====================================================================
|
||||
Deprecated Interfaces, Language Features, Attributes, and Conventions
|
||||
=====================================================================
|
||||
|
||||
@@ -62,7 +62,7 @@ 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
|
||||
rules and how to use `SPDX <https://spdx.org/>`_ identifiers in source code are
|
||||
descibed in :ref:`Documentation/process/license-rules.rst <kernel_licensing>`.
|
||||
described in :ref:`Documentation/process/license-rules.rst <kernel_licensing>`.
|
||||
If you have further questions about the license, please contact a lawyer, and do
|
||||
not ask on the Linux kernel mailing list. The people on the mailing lists are
|
||||
not lawyers, and you should not rely on their statements on legal matters.
|
||||
|
||||
@@ -95,18 +95,6 @@ On-line docs
|
||||
[...]. This paper examines some common problems for
|
||||
submitting larger changes and some strategies to avoid problems.
|
||||
|
||||
* Title: **Overview of the Virtual File System**
|
||||
|
||||
:Author: Richard Gooch.
|
||||
:URL: http://www.mjmwired.net/kernel/Documentation/filesystems/vfs.txt
|
||||
:Date: 2007
|
||||
:Keywords: VFS, File System, mounting filesystems, opening files,
|
||||
dentries, dcache.
|
||||
:Description: Brief introduction to the Linux Virtual File System.
|
||||
What is it, how it works, operations taken when opening a file or
|
||||
mounting a file system and description of important data
|
||||
structures explaining the purpose of each of their entries.
|
||||
|
||||
* Title: **Linux Device Drivers, Third Edition**
|
||||
|
||||
:Author: Jonathan Corbet, Alessandro Rubini, Greg Kroah-Hartman
|
||||
|
||||
@@ -234,13 +234,13 @@ kernel, can be broken down into:
|
||||
|
||||
|
|
||||
|
||||
2. Not recommended licenses:
|
||||
2. Deprecated licenses:
|
||||
|
||||
These licenses should only be used for existing code or for importing
|
||||
code from a different project. These licenses are available from the
|
||||
directory::
|
||||
|
||||
LICENSES/other/
|
||||
LICENSES/deprecated/
|
||||
|
||||
in the kernel source tree.
|
||||
|
||||
@@ -250,14 +250,14 @@ kernel, can be broken down into:
|
||||
|
||||
Examples::
|
||||
|
||||
LICENSES/other/ISC
|
||||
LICENSES/deprecated/ISC
|
||||
|
||||
Contains the Internet Systems Consortium license text and the required
|
||||
metatags::
|
||||
|
||||
LICENSES/other/ZLib
|
||||
LICENSES/deprecated/GPL-1.0
|
||||
|
||||
Contains the ZLIB license text and the required metatags.
|
||||
Contains the GPL version 1 license text and the required metatags.
|
||||
|
||||
Metatags:
|
||||
|
||||
@@ -281,7 +281,56 @@ kernel, can be broken down into:
|
||||
|
||||
|
|
||||
|
||||
3. _`Exceptions`:
|
||||
3. Dual Licensing Only
|
||||
|
||||
These licenses should only be used to dual license code with another
|
||||
license in addition to a preferred license. These licenses are available
|
||||
from the directory::
|
||||
|
||||
LICENSES/dual/
|
||||
|
||||
in the kernel source tree.
|
||||
|
||||
The files in this directory contain the full license text and
|
||||
`Metatags`_. The file names are identical to the SPDX license
|
||||
identifier which shall be used for the license in source files.
|
||||
|
||||
Examples::
|
||||
|
||||
LICENSES/dual/MPL-1.1
|
||||
|
||||
Contains the Mozilla Public License version 1.1 license text and the
|
||||
required metatags::
|
||||
|
||||
LICENSES/dual/Apache-2.0
|
||||
|
||||
Contains the Apache License version 2.0 license text and the required
|
||||
metatags.
|
||||
|
||||
Metatags:
|
||||
|
||||
The metatag requirements for 'other' licenses are identical to the
|
||||
requirements of the `Preferred licenses`_.
|
||||
|
||||
File format example::
|
||||
|
||||
Valid-License-Identifier: MPL-1.1
|
||||
SPDX-URL: https://spdx.org/licenses/MPL-1.1.html
|
||||
Usage-Guide:
|
||||
Do NOT use. The MPL-1.1 is not GPL2 compatible. It may only be used for
|
||||
dual-licensed files where the other license is GPL2 compatible.
|
||||
If you end up using this it MUST be used together with a GPL2 compatible
|
||||
license using "OR".
|
||||
To use the Mozilla Public License version 1.1 put the following SPDX
|
||||
tag/value pair into a comment according to the placement guidelines in
|
||||
the licensing rules documentation:
|
||||
SPDX-License-Identifier: MPL-1.1
|
||||
License-Text:
|
||||
Full license text
|
||||
|
||||
|
|
||||
|
||||
4. _`Exceptions`:
|
||||
|
||||
Some licenses can be amended with exceptions which grant certain rights
|
||||
which the original license does not. These exceptions are available
|
||||
|
||||
@@ -943,7 +943,7 @@ have on your keyring::
|
||||
|
||||
Next, open the `PGP pathfinder`_. In the "From" field, paste the key
|
||||
fingerprint of Linus Torvalds from the output above. In the "To" field,
|
||||
paste they key-id you found via ``gpg --search`` of the unknown key, and
|
||||
paste the key-id you found via ``gpg --search`` of the unknown key, and
|
||||
check the results:
|
||||
|
||||
- `Finding paths to Linus`_
|
||||
|
||||
@@ -60,8 +60,8 @@ not in any lower subdirectory.
|
||||
|
||||
To create a patch for a single file, it is often sufficient to do::
|
||||
|
||||
SRCTREE= linux
|
||||
MYFILE= drivers/net/mydriver.c
|
||||
SRCTREE=linux
|
||||
MYFILE=drivers/net/mydriver.c
|
||||
|
||||
cd $SRCTREE
|
||||
cp $MYFILE $MYFILE.orig
|
||||
@@ -73,7 +73,7 @@ To create a patch for multiple files, you should unpack a "vanilla",
|
||||
or unmodified kernel source tree, and generate a ``diff`` against your
|
||||
own source tree. For example::
|
||||
|
||||
MYSRC= /devel/linux
|
||||
MYSRC=/devel/linux
|
||||
|
||||
tar xvfz linux-3.19.tar.gz
|
||||
mv linux-3.19 linux-3.19-vanilla
|
||||
@@ -545,10 +545,40 @@ person it names - but it should indicate that this person was copied on the
|
||||
patch. This tag documents that potentially interested parties
|
||||
have been included in the discussion.
|
||||
|
||||
A Co-developed-by: states that the patch was also created by another developer
|
||||
along with the original author. This is useful at times when multiple people
|
||||
work on a single patch. Note, this person also needs to have a Signed-off-by:
|
||||
line in the patch as well.
|
||||
Co-developed-by: states that the patch was co-created by multiple developers;
|
||||
it is a used to give attribution to co-authors (in addition to the author
|
||||
attributed by the From: tag) when several people work on a single patch. Since
|
||||
Co-developed-by: denotes authorship, every Co-developed-by: must be immediately
|
||||
followed by a Signed-off-by: of the associated co-author. Standard sign-off
|
||||
procedure applies, i.e. the ordering of Signed-off-by: tags should reflect the
|
||||
chronological history of the patch insofar as possible, regardless of whether
|
||||
the author is attributed via From: or Co-developed-by:. Notably, the last
|
||||
Signed-off-by: must always be that of the developer submitting the patch.
|
||||
|
||||
Note, the From: tag is optional when the From: author is also the person (and
|
||||
email) listed in the From: line of the email header.
|
||||
|
||||
Example of a patch submitted by the From: author::
|
||||
|
||||
<changelog>
|
||||
|
||||
Co-developed-by: First Co-Author <first@coauthor.example.org>
|
||||
Signed-off-by: First Co-Author <first@coauthor.example.org>
|
||||
Co-developed-by: Second Co-Author <second@coauthor.example.org>
|
||||
Signed-off-by: Second Co-Author <second@coauthor.example.org>
|
||||
Signed-off-by: From Author <from@author.example.org>
|
||||
|
||||
Example of a patch submitted by a Co-developed-by: author::
|
||||
|
||||
From: From Author <from@author.example.org>
|
||||
|
||||
<changelog>
|
||||
|
||||
Co-developed-by: Random Co-Author <random@coauthor.example.org>
|
||||
Signed-off-by: Random Co-Author <random@coauthor.example.org>
|
||||
Signed-off-by: From Author <from@author.example.org>
|
||||
Co-developed-by: Submitting Co-Author <sub@coauthor.example.org>
|
||||
Signed-off-by: Submitting Co-Author <sub@coauthor.example.org>
|
||||
|
||||
|
||||
13) Using Reported-by:, Tested-by:, Reviewed-by:, Suggested-by: and Fixes:
|
||||
@@ -696,7 +726,7 @@ A couple of example Subjects::
|
||||
The ``from`` line must be the very first line in the message body,
|
||||
and has the form:
|
||||
|
||||
From: Original Author <author@example.com>
|
||||
From: Patch Author <author@example.com>
|
||||
|
||||
The ``from`` line specifies who will be credited as the author of the
|
||||
patch in the permanent changelog. If the ``from`` line is missing,
|
||||
|
||||
Reference in New Issue
Block a user