public-mirrors/linux
1
0
Fork 0
mirror of git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git synced 2025-04-13 09:59:31 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Merge branch 'docs-mw' into docs-next

Browse source
This commit is contained in:
Jonathan Corbet 2022-09-29 13:29:16 -06:00
commit 05fff6ba04
18 changed files with 324 additions and 186 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

3
Documentation/conf.py
View file

@ -370,7 +370,8 @@ html_static_path = ['sphinx-static']
html_use_smartypants = False
# Custom sidebar templates, maps document names to template names.
#html_sidebars = {}
# Note that the RTD theme ignores this.
html_sidebars = { '**': ['searchbox.html', 'localtoc.html', 'sourcelink.html']}
# Additional templates that should be rendered to pages, maps page names to
# template names.

7
Documentation/asm-annotations.rst → Documentation/core-api/asm-annotations.rst
View file

@ -43,10 +43,11 @@ annotated objects like this, tools can be run on them to generate more useful
information. In particular, on properly annotated objects, ``objtool`` can be
run to check and fix the object if needed. Currently, ``objtool`` can report
missing frame pointer setup/destruction in functions. It can also
automatically generate annotations for :doc:`ORC unwinder <x86/orc-unwinder>`
automatically generate annotations for the ORC unwinder
(Documentation/x86/orc-unwinder.rst)
for most code. Both of these are especially important to support reliable
stack traces which are in turn necessary for :doc:`Kernel live patching
<livepatch/livepatch>`.
stack traces which are in turn necessary for kernel live patching
(Documentation/livepatch/livepatch.rst).
Caveat and Discussion
---------------------

4
Documentation/core-api/index.rst
View file

@ -23,6 +23,7 @@ it.
printk-formats
printk-index
symbol-namespaces
asm-annotations
Data structures and low-level utilities
=======================================
@ -44,6 +45,8 @@ Library functionality that is used throughout the kernel.
this_cpu_ops
timekeeping
errseq
wrappers/atomic_t
wrappers/atomic_bitops
Low level entry and exit
========================
@ -67,6 +70,7 @@ Documentation/locking/index.rst for more related documentation.
local_ops
padata
../RCU/index
wrappers/memory-barriers.rst
Low-level hardware management
=============================

18
Documentation/core-api/wrappers/atomic_bitops.rst Normal file
View file

@ -0,0 +1,18 @@
.. SPDX-License-Identifier: GPL-2.0
This is a simple wrapper to bring atomic_bitops.txt into the RST world
until such a time as that file can be converted directly.
=============
Atomic bitops
=============
.. raw:: latex
\footnotesize
.. include:: ../../atomic_bitops.txt
:literal:
.. raw:: latex
\normalsize

19
Documentation/core-api/wrappers/atomic_t.rst Normal file
View file

@ -0,0 +1,19 @@
.. SPDX-License-Identifier: GPL-2.0
This is a simple wrapper to bring atomic_t.txt into the RST world
until such a time as that file can be converted directly.
============
Atomic types
============
.. raw:: latex
\footnotesize
.. include:: ../../atomic_t.txt
:literal:
.. raw:: latex
\normalsize

18
Documentation/core-api/wrappers/memory-barriers.rst Normal file
View file

@ -0,0 +1,18 @@
.. SPDX-License-Identifier: GPL-2.0
This is a simple wrapper to bring memory-barriers.txt into the RST world
until such a time as that file can be converted directly.
============================
Linux kernel memory barriers
============================
.. raw:: latex
\footnotesize
.. include:: ../../memory-barriers.txt
:literal:
.. raw:: latex
\normalsize

57
Documentation/doc-guide/sphinx.rst
View file

@ -48,10 +48,6 @@ or ``virtualenv``, depending on how your distribution packaged Python 3.
on the Sphinx version, it should be installed separately,
with ``pip install sphinx_rtd_theme``.
#) Some ReST pages contain math expressions. Due to the way Sphinx works,
those expressions are written using LaTeX notation. It needs texlive
installed with amsfonts and amsmath in order to evaluate them.
In summary, if you want to install Sphinx version 2.4.4, you should do::
$ virtualenv sphinx_2.4.4
@ -86,6 +82,27 @@ Depending on the distribution, you may also need to install a series of
``texlive`` packages that provide the minimal set of functionalities
required for ``XeLaTeX`` to work.
Math Expressions in HTML
------------------------
Some ReST pages contain math expressions. Due to the way Sphinx works,
those expressions are written using LaTeX notation.
There are two options for Sphinx to render math expressions in html output.
One is an extension called `imgmath`_ which converts math expressions into
images and embeds them in html pages.
The other is an extension called `mathjax`_ which delegates math rendering
to JavaScript capable web browsers.
The former was the only option for pre-6.1 kernel documentation and it
requires quite a few texlive packages including amsfonts and amsmath among
others.
Since kernel release 6.1, html pages with math expressions can be built
without installing any texlive packages. See `Choice of Math Renderer`_ for
further info.
.. _imgmath: https://www.sphinx-doc.org/en/master/usage/extensions/math.html#module-sphinx.ext.imgmath
.. _mathjax: https://www.sphinx-doc.org/en/master/usage/extensions/math.html#module-sphinx.ext.mathjax
.. _sphinx-pre-install:
Checking for Sphinx dependencies
@ -164,6 +181,38 @@ To remove the generated documentation, run ``make cleandocs``.
as well would improve the quality of images embedded in PDF
documents, especially for kernel releases 5.18 and later.
Choice of Math Renderer
-----------------------
Since kernel release 6.1, mathjax works as a fallback math renderer for
html output.\ [#sph1_8]_
Math renderer is chosen depending on available commands as shown below:
.. table:: Math Renderer Choices for HTML
============= ================= ============
Math renderer Required commands Image format
============= ================= ============
imgmath latex, dvipng PNG (raster)
mathjax
============= ================= ============
The choice can be overridden by setting an environment variable
``SPHINX_IMGMATH`` as shown below:
.. table:: Effect of Setting ``SPHINX_IMGMATH``
====================== ========
Setting Renderer
====================== ========
``SPHINX_IMGMATH=yes`` imgmath
``SPHINX_IMGMATH=no`` mathjax
====================== ========
.. [#sph1_8] Fallback of math renderer requires Sphinx >=1.8.
Writing Documentation
=====================

3
Documentation/driver-api/driver-model/devres.rst
View file

@ -301,6 +301,7 @@ IO region
devm_release_region()
devm_release_resource()
devm_request_mem_region()
devm_request_free_mem_region()
devm_request_region()
devm_request_resource()
@ -334,7 +335,7 @@ IRQ
devm_irq_alloc_descs_from()
devm_irq_alloc_generic_chip()
devm_irq_setup_generic_chip()
devm_irq_sim_init()
devm_irq_domain_create_sim()
LED
devm_led_classdev_register()

170
Documentation/index.rst
View file

@ -1,11 +1,5 @@
.. SPDX-License-Identifier: GPL-2.0
.. The Linux Kernel documentation master file, created by
sphinx-quickstart on Fri Feb 12 13:51:46 2016.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
.. _linux_doc:
The Linux Kernel documentation
@ -18,26 +12,72 @@ documents into a coherent whole. Please note that improvements to the
documentation are welcome; join the linux-doc list at vger.kernel.org if
you want to help out.
Licensing documentation
-----------------------
Working with the development community
--------------------------------------
The following describes the license of the Linux kernel source code
(GPLv2), how to properly mark the license of individual files in the source
tree, as well as links to the full license text.
The essential guides for interacting with the kernel's development
community and getting your work upstream.
.. toctree::
:maxdepth: 1
process/development-process
process/submitting-patches
Code of conduct <process/code-of-conduct>
maintainer/index
All development-process docs <process/index>
Internal API manuals
--------------------
Manuals for use by developers working to interface with the rest of the
kernel.
.. toctree::
:maxdepth: 1
core-api/index
driver-api/index
subsystem-apis
Locking in the kernel <locking/index>
Development tools and processes
-------------------------------
Various other manuals with useful information for all kernel developers.
.. toctree::
:maxdepth: 1
process/license-rules
doc-guide/index
dev-tools/index
dev-tools/testing-overview
kernel-hacking/index
trace/index
fault-injection/index
livepatch/index
* :ref:`kernel_licensing`
User-oriented documentation
---------------------------
The following manuals are written for *users* of the kernel — those who are
trying to get it to work optimally on a given system.
trying to get it to work optimally on a given system and application
developers seeking information on the kernel's user-space APIs.
.. toctree::
:maxdepth: 2
:maxdepth: 1
admin-guide/index
kbuild/index
The kernel build system <kbuild/index>
admin-guide/reporting-issues.rst
User-space tools <tools/index>
userspace-api/index
See also: the `Linux man pages <https://www.kernel.org/doc/man-pages/>`_,
which are kept separately from the kernel's own documentation.
Firmware-related documentation
------------------------------
@ -45,106 +85,11 @@ The following holds information on the kernel's expectations regarding the
platform firmwares.
.. toctree::
:maxdepth: 2
:maxdepth: 1
firmware-guide/index
devicetree/index
Application-developer documentation
-----------------------------------
The user-space API manual gathers together documents describing aspects of
the kernel interface as seen by application developers.
.. toctree::
:maxdepth: 2
userspace-api/index
Introduction to kernel development
----------------------------------
These manuals contain overall information about how to develop the kernel.
The kernel community is quite large, with thousands of developers
contributing over the course of a year. As with any large community,
knowing how things are done will make the process of getting your changes
merged much easier.
.. toctree::
:maxdepth: 2
process/index
dev-tools/index
doc-guide/index
kernel-hacking/index
trace/index
maintainer/index
fault-injection/index
livepatch/index
Kernel API documentation
------------------------
These books get into the details of how specific kernel subsystems work
from the point of view of a kernel developer. Much of the information here
is taken directly from the kernel source, with supplemental material added
as needed (or at least as we managed to add it — probably *not* all that is
needed).
.. toctree::
:maxdepth: 2
driver-api/index
core-api/index
locking/index
accounting/index
block/index
cdrom/index
cpu-freq/index
fb/index
fpga/index
hid/index
i2c/index
iio/index
isdn/index
infiniband/index
leds/index
netlabel/index
networking/index
pcmcia/index
power/index
target/index
timers/index
spi/index
w1/index
watchdog/index
virt/index
input/index
hwmon/index
gpu/index
security/index
sound/index
crypto/index
filesystems/index
mm/index
bpf/index
usb/index
PCI/index
scsi/index
misc-devices/index
scheduler/index
mhi/index
peci/index
Architecture-agnostic documentation
-----------------------------------
.. toctree::
:maxdepth: 2
asm-annotations
Architecture-specific documentation
-----------------------------------
@ -163,9 +108,8 @@ of the documentation body, or may require some adjustments and/or conversion
to ReStructured Text format, or are simply too old.
.. toctree::
:maxdepth: 2
:maxdepth: 1
tools/index
staging/index

6
Documentation/mm/unevictable-lru.rst
View file

@ -197,7 +197,7 @@ unevictable list for the memory cgroup and node being scanned.
There may be situations where a page is mapped into a VM_LOCKED VMA, but the
page is not marked as PG_mlocked. Such pages will make it all the way to
shrink_active_list() or shrink_page_list() where they will be detected when
vmscan walks the reverse map in page_referenced() or try_to_unmap(). The page
vmscan walks the reverse map in folio_referenced() or try_to_unmap(). The page
is culled to the unevictable list when it is released by the shrinker.
To "cull" an unevictable page, vmscan simply puts the page back on the LRU list
@ -267,7 +267,7 @@ the LRU. Such pages can be "noticed" by memory management in several places:
(4) in the fault path and when a VM_LOCKED stack segment is expanded; or
(5) as mentioned above, in vmscan:shrink_page_list() when attempting to
reclaim a page in a VM_LOCKED VMA by page_referenced() or try_to_unmap().
reclaim a page in a VM_LOCKED VMA by folio_referenced() or try_to_unmap().
mlocked pages become unlocked and rescued from the unevictable list when:
@ -547,7 +547,7 @@ vmscan's shrink_inactive_list() and shrink_page_list() also divert obviously
unevictable pages found on the inactive lists to the appropriate memory cgroup
and node unevictable list.
rmap's page_referenced_one(), called via vmscan's shrink_active_list() or
rmap's folio_referenced_one(), called via vmscan's shrink_active_list() or
shrink_page_list(), and rmap's try_to_unmap_one() called via shrink_page_list(),
check for (3) pages still mapped into VM_LOCKED VMAs, and call mlock_vma_page()
to correct them. Such pages are culled to the unevictable list when released

6
Documentation/process/5.Posting.rst
View file

@ -256,8 +256,10 @@ The tags in common use are:
- Cc: the named person received a copy of the patch and had the
opportunity to comment on it.
Be careful in the addition of tags to your patches: only Cc: is appropriate
for addition without the explicit permission of the person named.
Be careful in the addition of tags to your patches, as only Cc: is appropriate
for addition without the explicit permission of the person named; using
Reported-by: is fine most of the time as well, but ask for permission if
the bug was reported in private.
Sending the patch

24
Documentation/process/code-of-conduct-interpretation.rst
View file

@ -127,10 +127,12 @@ are listed at https://kernel.org/code-of-conduct.html. Members can not
access reports made before they joined or after they have left the
committee.
The initial Code of Conduct Committee consists of volunteer members of
the TAB, as well as a professional mediator acting as a neutral third
party. The first task of the committee is to establish documented
processes, which will be made public.
The Code of Conduct Committee consists of volunteer community members
appointed by the TAB, as well as a professional mediator acting as a
neutral third party. The processes the Code of Conduct committee will
use to address reports is varied and will depend on the individual
circumstance, however, this file serves as documentation for the
general process used.
Any member of the committee, including the mediator, can be contacted
directly if a reporter does not wish to include the full committee in a
@ -141,16 +143,16 @@ processes (see above) and consults with the TAB as needed and
appropriate, for instance to request and receive information about the
kernel community.
Any decisions by the committee will be brought to the TAB, for
implementation of enforcement with the relevant maintainers if needed.
A decision by the Code of Conduct Committee can be overturned by the TAB
by a two-thirds vote.
Any decisions regarding enforcement recommendations will be brought to
the TAB for implementation of enforcement with the relevant maintainers
if needed. A decision by the Code of Conduct Committee can be overturned
by the TAB by a two-thirds vote.
At quarterly intervals, the Code of Conduct Committee and TAB will
provide a report summarizing the anonymised reports that the Code of
Conduct committee has received and their status, as well details of any
overridden decisions including complete and identifiable voting details.
We expect to establish a different process for Code of Conduct Committee
staffing beyond the bootstrap period. This document will be updated
with that information when this occurs.
Because how we interpret and enforce the Code of Conduct will evolve over
time, this document will be updated when necessary to reflect any
changes.

62
Documentation/process/coding-style.rst
View file

@ -1186,6 +1186,68 @@ expression used. For instance:
#endif /* CONFIG_SOMETHING */
22) Do not crash the kernel
---------------------------
In general, the decision to crash the kernel belongs to the user, rather
than to the kernel developer.
Avoid panic()
*************
panic() should be used with care and primarily only during system boot.
panic() is, for example, acceptable when running out of memory during boot and
not being able to continue.
Use WARN() rather than BUG()
****************************
Do not add new code that uses any of the BUG() variants, such as BUG(),
BUG_ON(), or VM_BUG_ON(). Instead, use a WARN*() variant, preferably
WARN_ON_ONCE(), and possibly with recovery code. Recovery code is not
required if there is no reasonable way to at least partially recover.
"I'm too lazy to do error handling" is not an excuse for using BUG(). Major
internal corruptions with no way of continuing may still use BUG(), but need
good justification.
Use WARN_ON_ONCE() rather than WARN() or WARN_ON()
**************************************************
WARN_ON_ONCE() is generally preferred over WARN() or WARN_ON(), because it
is common for a given warning condition, if it occurs at all, to occur
multiple times. This can fill up and wrap the kernel log, and can even slow
the system enough that the excessive logging turns into its own, additional
problem.
Do not WARN lightly
*******************
WARN*() is intended for unexpected, this-should-never-happen situations.
WARN*() macros are not to be used for anything that is expected to happen
during normal operation. These are not pre- or post-condition asserts, for
example. Again: WARN*() must not be used for a condition that is expected
to trigger easily, for example, by user space actions. pr_warn_once() is a
possible alternative, if you need to notify the user of a problem.
Do not worry about panic_on_warn users
**************************************
A few more words about panic_on_warn: Remember that ``panic_on_warn`` is an
available kernel option, and that many users set this option. This is why
there is a "Do not WARN lightly" writeup, above. However, the existence of
panic_on_warn users is not a valid reason to avoid the judicious use
WARN*(). That is because, whoever enables panic_on_warn has explicitly
asked the kernel to crash if a WARN*() fires, and such users must be
prepared to deal with the consequences of a system that is somewhat more
likely to crash.
Use BUILD_BUG_ON() for compile-time assertions
**********************************************
The use of BUILD_BUG_ON() is acceptable and encouraged, because it is a
compile-time assertion that has no effect at runtime.
Appendix I) References
----------------------

1
Documentation/process/index.rst
View file

@ -5,6 +5,7 @@
.. _process_index:
=============================================
Working with the kernel development community
=============================================

42
Documentation/staging/index.rst
View file

@ -14,45 +14,3 @@ Unsorted Documentation
static-keys
tee
xz
Atomic Types
============
.. raw:: latex
\footnotesize
.. include:: ../atomic_t.txt
:literal:
.. raw:: latex
\normalsize
Atomic bitops
=============
.. raw:: latex
\footnotesize
.. include:: ../atomic_bitops.txt
:literal:
.. raw:: latex
\normalsize
Memory Barriers
===============
.. raw:: latex
\footnotesize
.. include:: ../memory-barriers.txt
:literal:
.. raw:: latex
\normalsize

58
Documentation/subsystem-apis.rst Normal file
View file

@ -0,0 +1,58 @@
.. SPDX-License-Identifier: GPL-2.0
==============================
Kernel subsystem documentation
==============================
These books get into the details of how specific kernel subsystems work
from the point of view of a kernel developer. Much of the information here
is taken directly from the kernel source, with supplemental material added
as needed (or at least as we managed to add it — probably *not* all that is
needed).
**Fixme**: much more organizational work is needed here.
.. toctree::
:maxdepth: 1
driver-api/index
core-api/index
locking/index
accounting/index
block/index
cdrom/index
cpu-freq/index
fb/index
fpga/index
hid/index
i2c/index
iio/index
isdn/index
infiniband/index
leds/index
netlabel/index
networking/index
pcmcia/index
power/index
target/index
timers/index
spi/index
w1/index
watchdog/index
virt/index
input/index
hwmon/index
gpu/index
security/index
sound/index
crypto/index
filesystems/index
mm/index
bpf/index
usb/index
PCI/index
scsi/index
misc-devices/index
scheduler/index
mhi/index
peci/index

4
Documentation/trace/kprobes.rst
View file

@ -328,8 +328,8 @@ Configuring Kprobes
===================
When configuring the kernel using make menuconfig/xconfig/oldconfig,
ensure that CONFIG_KPROBES is set to "y". Under "General setup", look
for "Kprobes".
ensure that CONFIG_KPROBES is set to "y", look for "Kprobes" under
"General architecture-dependent options".
So that you can load and unload Kprobes-based instrumentation modules,
make sure "Loadable module support" (CONFIG_MODULES) and "Module

8
scripts/checkpatch.pl
View file

@ -3751,7 +3751,7 @@ sub process {
if ($realfile =~ /\.S$/ &&
$line =~ /^\+\s*(?:[A-Z]+_)?SYM_[A-Z]+_(?:START|END)(?:_[A-Z_]+)?\s*\(\s*\.L/) {
WARN("AVOID_L_PREFIX",
"Avoid using '.L' prefixed local symbol names for denoting a range of code via 'SYM_*_START/END' annotations; see Documentation/asm-annotations.rst\n" . $herecurr);
"Avoid using '.L' prefixed local symbol names for denoting a range of code via 'SYM_*_START/END' annotations; see Documentation/core-api/asm-annotations.rst\n" . $herecurr);
}
# check we are in a valid source file C or perl if not then ignore this hunk
@ -4695,12 +4695,12 @@ sub process {
}
}
# avoid BUG() or BUG_ON()
if ($line =~ /\b(?:BUG|BUG_ON)\b/) {
# do not use BUG() or variants
if ($line =~ /\b(?!AA_|BUILD_|DCCP_|IDA_|KVM_|RWLOCK_|snd_|SPIN_)(?:[a-zA-Z_]*_)?BUG(?:_ON)?(?:_[A-Z_]+)?\s*\(/) {
my $msg_level = \&WARN;
$msg_level = \&CHK if ($file);
&{$msg_level}("AVOID_BUG",
"Avoid crashing the kernel - try using WARN_ON & recovery code rather than BUG() or BUG_ON()\n" . $herecurr);
"Do not crash the kernel unless it is absolutely unavoidable--use WARN_ON_ONCE() plus recovery code (if feasible) instead of BUG() or variants\n" . $herecurr);
}
# avoid LINUX_VERSION_CODE