git
/
linux
mirror of https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

It has been a relatively busy cycle in docsland, with changes all over: 

- Bring the kernel memory-model docs into the Sphinx build in the "literal
   include" mode.
 
 - Lots of build-infrastructure work, further cleaning up long-term
   kernel-doc technical debt.  The sphinx-pre-install tool has been
   converted to Python and updated for current systems.
 
 - A new tool to detect when documents have been moved and generate HTML
   redirects; this can be used on kernel.org (or any other site hosting the
   rendered docs) to avoid breaking links.
 
 - Automated processing of the YAML files describing the netlink protocol.
 
 - A significant update of the maintainer's PGP guide.
 
 ...and a seemingly endless series of typo fixes, build-problem fixes, etc.
 -----BEGIN PGP SIGNATURE-----
 
 iQEzBAABCgAdFiEEIw+MvkEiF49krdp9F0NaE2wMflgFAmjbwOoACgkQF0NaE2wM
 flis1gf/ZvRi3Mo5hIsuGyQfs5kw/jx0N7SG4QYf2rEnt5ZGNa5SkyOVKsWQKTgK
 LesQkdaCA0xHMoUWSvZRwn2a0+acpeMm6viXjewd2mU52sSNmSkKG4WsZyxfnOYS
 36fkZ1qymQkJ4uSvx5NScTiIBqZx+Qfgkj0eNnXcpJd2vYeAVSu4szsFxeUvcJFj
 Ckq3+3DQ5p/dcWwgvdlLKEJGj98Q3cqLrMn8ycbNtwzo3mdVbrlP5+qqNslZC6xY
 Nqpv9HXbFWNCaL6YWCybcNOZ4F5UVno1ap2F3imTD8Rp1iG77zAQV5lMlq4Gksf4
 kECLc1TtTKSgmgWHmi1sgudqM4Xqpw==
 =Qe3Z
 -----END PGP SIGNATURE-----

Merge tag 'docs-6.18' of git://git.lwn.net/linux

Pull documentation updates from Jonathan Corbet:
 "It has been a relatively busy cycle in docsland, with changes all
  over:

   - Bring the kernel memory-model docs into the Sphinx build in the
     "literal include" mode.

   - Lots of build-infrastructure work, further cleaning up long-term
     kernel-doc technical debt. The sphinx-pre-install tool has been
     converted to Python and updated for current systems.

   - A new tool to detect when documents have been moved and generate
     HTML redirects; this can be used on kernel.org (or any other site
     hosting the rendered docs) to avoid breaking links.

   - Automated processing of the YAML files describing the netlink
     protocol.

   - A significant update of the maintainer's PGP guide.

  ... and a seemingly endless series of typo fixes, build-problem fixes,
  etc"

* tag 'docs-6.18' of git://git.lwn.net/linux: (193 commits)
  Documentation/features: Update feature lists for 6.17-rc7
  docs: remove cdomain.py
  Documentation/process: submitting-patches: fix typo in "were do"
  docs: dev-tools/lkmm: Fix typo of missing file extension
  Documentation: trace: histogram: Convert ftrace docs cross-reference
  Documentation: trace: histogram-design: Wrap introductory note in note:: directive
  Documentation: trace: historgram-design: Separate sched_waking histogram section heading and the following diagram
  Documentation: trace: histogram-design: Trim trailing vertices in diagram explanation text
  Documentation: trace: histogram: Fix histogram trigger subsection number order
  docs: driver-api: fix spelling of "buses".
  Documentation: fbcon: Use admonition directives
  Documentation: fbcon: Reindent 8th step of attach/detach/unload
  Documentation: fbcon: Add boot options and attach/detach/unload section headings
  docs: filesystems: sysfs: add remaining top level sysfs directory descriptions
  docs: filesystems: sysfs: clarify symlink destinations in dev and bus/devices descriptions
  docs: filesystems: sysfs: remove top level sysfs net directory
  docs: maintainer: Fix ambiguous subheading formatting
  docs: kdoc: a few more dump_typedef() tweaks
  docs: kdoc: remove redundant comment stripping in dump_typedef()
  docs: kdoc: remove some dead code in dump_typedef()
  ...
This commit is contained in:
Linus Torvalds 2025-10-03 17:16:13 -07:00
parent 50647a1176 99510c324e
commit ee2fe81cdc
173 changed files with 7041 additions and 3555 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.pylintrc
View File

@ -1,2 +1,2 @@
[MASTER]
init-hook='import sys; sys.path += ["scripts/lib/kdoc", "scripts/lib/abi"]'
init-hook='import sys; sys.path += ["scripts/lib/kdoc", "scripts/lib/abi", "tools/docs/lib"]'

1191
Documentation/.renames.txt Normal file
View File

File diff suppressed because it is too large Load Diff

11
Documentation/Makefile
View File

@ -60,8 +60,8 @@ ifeq ($(HAVE_LATEXMK),1)
endif #HAVE_LATEXMK
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
PAPEROPT_a4 = -D latex_elements.papersize=a4paper
PAPEROPT_letter = -D latex_elements.papersize=letterpaper
ALLSPHINXOPTS = -D kerneldoc_srctree=$(srctree) -D kerneldoc_bin=$(KERNELDOC)
ALLSPHINXOPTS += $(PAPEROPT_$(PAPER)) $(SPHINXOPTS)
ifneq ($(wildcard $(srctree)/.config),)
@ -87,7 +87,7 @@ loop_cmd = $(echo-cmd) $(cmd_$(1)) || exit;
PYTHONPYCACHEPREFIX ?= $(abspath $(BUILDDIR)/__pycache__)
quiet_cmd_sphinx = SPHINX $@ --> file://$(abspath $(BUILDDIR)/$3/$4)
cmd_sphinx = $(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/userspace-api/media $2 && \
cmd_sphinx = \
PYTHONPYCACHEPREFIX="$(PYTHONPYCACHEPREFIX)" \
BUILDDIR=$(abspath $(BUILDDIR)) SPHINX_CONF=$(abspath $(src)/$5/$(SPHINX_CONF)) \
$(PYTHON3) $(srctree)/scripts/jobserver-exec \
@ -108,6 +108,9 @@ htmldocs:
@$(srctree)/scripts/sphinx-pre-install --version-check
@+$(foreach var,$(SPHINXDIRS),$(call loop_cmd,sphinx,html,$(var),,$(var)))
htmldocs-redirects: $(srctree)/Documentation/.renames.txt
@tools/docs/gen-redirects.py --output $(BUILDDIR) < $<
# If Rust support is available and .config exists, add rustdoc generated contents.
# If there are any, the errors from this make rustdoc will be displayed but
# won't stop the execution of htmldocs
@ -171,11 +174,11 @@ refcheckdocs:
cleandocs:
$(Q)rm -rf $(BUILDDIR)
$(Q)$(MAKE) BUILDDIR=$(abspath $(BUILDDIR)) $(build)=Documentation/userspace-api/media clean
dochelp:
@echo ' Linux kernel internal documentation in different formats from ReST:'
@echo ' htmldocs - HTML'
@echo ' htmldocs-redirects - generate HTML redirects for moved pages'
@echo ' texinfodocs - Texinfo'
@echo ' infodocs - Info'
@echo ' latexdocs - LaTeX'

4
Documentation/PCI/endpoint/pci-endpoint-cfs.rst
View File

@ -86,7 +86,7 @@ The <EPF Device> directory can have a list of symbolic links
be created by the user to represent the virtual functions that are bound to
the physical function. In the above directory structure <EPF Device 11> is a
physical function and <EPF Device 31> is a virtual function. An EPF device once
it's linked to another EPF device, cannot be linked to a EPC device.
it's linked to another EPF device, cannot be linked to an EPC device.
EPC Device
==========
@ -108,7 +108,7 @@ entries corresponding to EPC device will be created by the EPC core.
The <EPC Device> directory will have a list of symbolic links to
<EPF Device>. These symbolic links should be created by the user to
represent the functions present in the endpoint device. Only <EPF Device>
that represents a physical function can be linked to a EPC device.
that represents a physical function can be linked to an EPC device.
The <EPC Device> directory will also have a *start* field. Once
"1" is written to this field, the endpoint device will be ready to

6
Documentation/PCI/endpoint/pci-endpoint.rst
View File

@ -197,8 +197,8 @@ by the PCI endpoint function driver.
* pci_epf_register_driver()
The PCI Endpoint Function driver should implement the following ops:
* bind: ops to perform when a EPC device has been bound to EPF device
* unbind: ops to perform when a binding has been lost between a EPC
* bind: ops to perform when an EPC device has been bound to EPF device
* unbind: ops to perform when a binding has been lost between an EPC
device and EPF device
* add_cfs: optional ops to create function specific configfs
attributes
@ -251,7 +251,7 @@ pci-ep-cfs.c can be used as reference for using these APIs.
* pci_epf_bind()
pci_epf_bind() should be invoked when the EPF device has been bound to
a EPC device.
an EPC device.
* pci_epf_unbind()

2
Documentation/RCU/lockdep.rst
View File

@ -106,7 +106,7 @@ or the RCU-protected data that it points to can change concurrently.
Like rcu_dereference(), when lockdep is enabled, RCU list and hlist
traversal primitives check for being called from within an RCU read-side
critical section. However, a lockdep expression can be passed to them
as a additional optional argument. With this lockdep expression, these
as an additional optional argument. With this lockdep expression, these
traversal primitives will complain only if the lockdep expression is
false and they are called from outside any RCU read-side critical section.

2
Documentation/RCU/stallwarn.rst
View File

@ -119,7 +119,7 @@ warnings:
uncommon in large datacenter. In one memorable case some decades
back, a CPU failed in a running system, becoming unresponsive,
but not causing an immediate crash. This resulted in a series
of RCU CPU stall warnings, eventually leading the realization
of RCU CPU stall warnings, eventually leading to the realization
that the CPU had failed.
The RCU, RCU-sched, RCU-tasks, and RCU-tasks-trace implementations have

2
Documentation/admin-guide/LSM/SafeSetID.rst
View File

@ -41,7 +41,7 @@ namespace). The higher level goal is to allow for uid-based sandboxing of system
services without having to give out CAP_SETUID all over the place just so that
non-root programs can drop to even-lesser-privileged uids. This is especially
relevant when one non-root daemon on the system should be allowed to spawn other
processes as different uids, but its undesirable to give the daemon a
processes as different uids, but it's undesirable to give the daemon a
basically-root-equivalent CAP_SETUID.

2
Documentation/admin-guide/RAS/main.rst
View File

@ -253,7 +253,7 @@ interface.
Some architectures have ECC detectors for L1, L2 and L3 caches,
along with DMA engines, fabric switches, main data path switches,
interconnections, and various other hardware data paths. If the hardware
reports it, then a edac_device device probably can be constructed to
reports it, then an edac_device device probably can be constructed to
harvest and present that to userspace.

2
Documentation/admin-guide/blockdev/paride.rst
View File

@ -118,7 +118,7 @@ and high-level drivers that you would use:
================ ============ ========
All parports and all protocol drivers are probed automatically unless probe=0
parameter is used. So just "modprobe epat" is enough for a Imation SuperDisk
parameter is used. So just "modprobe epat" is enough for an Imation SuperDisk
drive to work.
Manual device creation::

2
Documentation/admin-guide/device-mapper/vdo-design.rst
View File

@ -600,7 +600,7 @@ lock and return itself to the pool.
All storage within vdo is managed as 4KB blocks, but it can accept writes
as small as 512 bytes. Processing a write that is smaller than 4K requires
a read-modify-write operation that reads the relevant 4K block, copies the
new data over the approriate sectors of the block, and then launches a
new data over the appropriate sectors of the block, and then launches a
write operation for the modified data block. The read and write stages of
this operation are nearly identical to the normal read and write
operations, and a single data_vio is used throughout this operation.

2
Documentation/admin-guide/ext4.rst
View File

@ -398,7 +398,7 @@ There are 3 different data modes:
* writeback mode
In data=writeback mode, ext4 does not journal data at all. This mode provides
a similar level of journaling as that of XFS, JFS, and ReiserFS in its default
a similar level of journaling as that of XFS and JFS in its default
mode - metadata journaling. A crash+recovery can cause incorrect data to
appear in files which were written shortly before the crash. This mode will
typically provide the best ext4 performance.

2
Documentation/admin-guide/hw-vuln/mds.rst
View File

@ -214,7 +214,7 @@ XEON PHI specific considerations
command line with the 'ring3mwait=disable' command line option.
XEON PHI is not affected by the other MDS variants and MSBDS is mitigated
before the CPU enters a idle state. As XEON PHI is not affected by L1TF
before the CPU enters an idle state. As XEON PHI is not affected by L1TF
either disabling SMT is not required for full protection.
.. _mds_smt_control:

6
Documentation/admin-guide/hw-vuln/spectre.rst
View File

@ -664,7 +664,7 @@ Intel white papers:
.. _spec_ref1:
[1] `Intel analysis of speculative execution side channels <https://newsroom.intel.com/wp-content/uploads/sites/11/2018/01/Intel-Analysis-of-Speculative-Execution-Side-Channels.pdf>`_.
[1] `Intel analysis of speculative execution side channels <https://www.intel.com/content/dam/www/public/us/en/documents/white-papers/analysis-of-speculative-execution-side-channels-white-paper.pdf>`_.
.. _spec_ref2:
@ -682,7 +682,7 @@ AMD white papers:
.. _spec_ref5:
[5] `AMD64 technology indirect branch control extension <https://developer.amd.com/wp-content/resources/Architecture_Guidelines_Update_Indirect_Branch_Control.pdf>`_.
[5] `AMD64 technology indirect branch control extension <https://www.amd.com/content/dam/amd/en/documents/processor-tech-docs/white-papers/111006-architecture-guidelines-update-amd64-technology-indirect-branch-control-extension.pdf>`_.
.. _spec_ref6:
@ -708,7 +708,7 @@ MIPS white paper:
.. _spec_ref10:
[10] `MIPS: response on speculative execution and side channel vulnerabilities <https://www.mips.com/blog/mips-response-on-speculative-execution-and-side-channel-vulnerabilities/>`_.
[10] `MIPS: response on speculative execution and side channel vulnerabilities <https://web.archive.org/web/20220512003005if_/https://www.mips.com/blog/mips-response-on-speculative-execution-and-side-channel-vulnerabilities/>`_.
Academic papers:

2
Documentation/admin-guide/kdump/kdump.rst
View File

@ -471,7 +471,7 @@ Notes on loading the dump-capture kernel:
performance degradation. To enable multi-cpu support, you should bring up an
SMP dump-capture kernel and specify maxcpus/nr_cpus options while loading it.
* For s390x there are two kdump modes: If a ELF header is specified with
* For s390x there are two kdump modes: If an ELF header is specified with
the elfcorehdr= kernel parameter, it is used by the kdump kernel as it
is done on all other architectures. If no elfcorehdr= kernel parameter is
specified, the s390x kdump kernel dynamically creates the header. The

4
Documentation/admin-guide/kernel-parameters.rst
View File

@ -1,3 +1,5 @@
.. SPDX-License-Identifier: GPL-2.0
.. _kernelparameters:
The kernel's command-line parameters
@ -213,7 +215,7 @@ need or coordination with <Documentation/arch/x86/boot.rst>.
There are also arch-specific kernel-parameters not documented here.
Note that ALL kernel parameters listed below are CASE SENSITIVE, and that
a trailing = on the name of any parameter states that that parameter will
a trailing = on the name of any parameter states that the parameter will
be entered as an environment variable, whereas its absence indicates that
it will appear as a kernel argument readable via /proc/cmdline by programs
running once the system is up.

12
Documentation/admin-guide/kernel-parameters.txt
View File

@ -3705,7 +3705,7 @@
looking for corruption. Enabling this will
both detect corruption and prevent the kernel
from using the memory being corrupted.
However, its intended as a diagnostic tool; if
However, it's intended as a diagnostic tool; if
repeatable BIOS-originated corruption always
affects the same memory, you can use memmap=
to prevent the kernel from using that memory.
@ -7400,7 +7400,7 @@
(converted into nanoseconds). Fast, but
depending on the architecture, may not be
in sync between CPUs.
global - Event time stamps are synchronize across
global - Event time stamps are synchronized across
CPUs. May be slower than the local clock,
but better for some race conditions.
counter - Simple counting of events (1, 2, ..)
@ -7520,12 +7520,12 @@
section.
trace_trigger=[trigger-list]
[FTRACE] Add a event trigger on specific events.
[FTRACE] Add an event trigger on specific events.
Set a trigger on top of a specific event, with an optional
filter.
The format is is "trace_trigger=<event>.<trigger>[ if <filter>],..."
Where more than one trigger may be specified that are comma deliminated.
The format is "trace_trigger=<event>.<trigger>[ if <filter>],..."
Where more than one trigger may be specified that are comma delimited.
For example:
@ -7533,7 +7533,7 @@
The above will enable the "stacktrace" trigger on the "sched_switch"
event but only trigger it if the "prev_state" of the "sched_switch"
event is "2" (TASK_UNINTERUPTIBLE).
event is "2" (TASK_UNINTERRUPTIBLE).
See also "Event triggers" in Documentation/trace/events.rst

8
Documentation/admin-guide/laptops/laptop-mode.rst
View File

@ -61,7 +61,7 @@ Caveats
Check your drive's rating, and don't wear down your drive's lifetime if you
don't need to.
* If you mount some of your ext3/reiserfs filesystems with the -n option, then
* If you mount some of your ext3 filesystems with the -n option, then
the control script will not be able to remount them correctly. You must set
DO_REMOUNTS=0 in the control script, otherwise it will remount them with the
wrong options -- or it will fail because it cannot write to /etc/mtab.
@ -96,7 +96,7 @@ control script increases dirty_expire_centisecs and dirty_writeback_centisecs in
dirtied are not forced to be written to disk as often. The control script also
changes the dirty background ratio, so that background writeback of dirty pages
is not done anymore. Combined with a higher commit value (also 10 minutes) for
ext3 or ReiserFS filesystems (also done automatically by the control script),
ext3 filesystem (also done automatically by the control script),
this results in concentration of disk activity in a small time interval which
occurs only once every 10 minutes, or whenever the disk is forced to spin up by
a cache miss. The disk can then be spun down in the periods of inactivity.
@ -587,7 +587,7 @@ Control script::
FST=$(deduce_fstype $MP)
fi
case "$FST" in
"ext3"|"reiserfs")
"ext3")
PARSEDOPTS="$(parse_mount_opts commit "$OPTS")"
mount $DEV -t $FST $MP -o remount,$PARSEDOPTS,commit=$MAX_AGE$NOATIME_OPT
;;
@ -647,7 +647,7 @@ Control script::
FST=$(deduce_fstype $MP)
fi
case "$FST" in
"ext3"|"reiserfs")
"ext3")
PARSEDOPTS="$(parse_mount_opts_wfstab $DEV commit $OPTS)"
PARSEDOPTS="$(parse_yesno_opts_wfstab $DEV atime atime $PARSEDOPTS)"
mount $DEV -t $FST $MP -o remount,$PARSEDOPTS

2
Documentation/admin-guide/laptops/sonypi.rst
View File

@ -25,7 +25,7 @@ generate, like:
(when available)
Those events (see linux/sonypi.h) can be polled using the character device node
/dev/sonypi (major 10, minor auto allocated or specified as a option).
/dev/sonypi (major 10, minor auto allocated or specified as an option).
A simple daemon which translates the jogdial movements into mouse wheel events
can be downloaded at: <http://popies.net/sonypi/>

2
Documentation/admin-guide/md.rst
View File

@ -794,7 +794,7 @@ These currently include:
journal_mode (currently raid5 only)
The cache mode for raid5. raid5 could include an extra disk for
caching. The mode can be "write-throuth" and "write-back". The
caching. The mode can be "write-through" or "write-back". The
default is "write-through".
ppl_write_hint

2
Documentation/admin-guide/media/imx.rst
View File

@ -96,7 +96,7 @@ Some of the features of this driver include:
motion compensation modes: low, medium, and high motion. Pipelines are
defined that allow sending frames to the VDIC subdev directly from the
CSI. There is also support in the future for sending frames to the
VDIC from memory buffers via a output/mem2mem devices.
VDIC from memory buffers via output/mem2mem devices.
- Includes a Frame Interval Monitor (FIM) that can correct vertical sync
problems with the ADV718x video decoders.

6
Documentation/admin-guide/media/si4713.rst
View File

@ -13,7 +13,7 @@ Contact: Eduardo Valentin <eduardo.valentin@nokia.com>
Information about the Device
----------------------------
This chip is a Silicon Labs product. It is a I2C device, currently on 0x63 address.
This chip is a Silicon Labs product. It is an I2C device, currently on 0x63 address.
Basically, it has transmission and signal noise level measurement features.
The Si4713 integrates transmit functions for FM broadcast stereo transmission.
@ -28,7 +28,7 @@ Users must comply with local regulations on radio frequency (RF) transmission.
Device driver description
-------------------------
There are two modules to handle this device. One is a I2C device driver
There are two modules to handle this device. One is an I2C device driver
and the other is a platform driver.
The I2C device driver exports a v4l2-subdev interface to the kernel.
@ -113,7 +113,7 @@ Here is a summary of them:
- acomp_attack_time - Sets the attack time for audio dynamic range control.
- acomp_release_time - Sets the release time for audio dynamic range control.
* Limiter setups audio deviation limiter feature. Once a over deviation occurs,
* Limiter sets up the audio deviation limiter feature. Once an over deviation occurs,
it is possible to adjust the front-end gain of the audio input and always
prevent over deviation.

2
Documentation/admin-guide/mm/damon/usage.rst
View File

@ -360,7 +360,7 @@ The directory for the :ref:`quotas <damon_design_damos_quotas>` of the given
DAMON-based operation scheme.
Under ``quotas`` directory, four files (``ms``, ``bytes``,
``reset_interval_ms``, ``effective_bytes``) and two directores (``weights`` and
``reset_interval_ms``, ``effective_bytes``) and two directories (``weights`` and
``goals``) exist.
You can set the ``time quota`` in milliseconds, ``size quota`` in bytes, and

2
Documentation/admin-guide/nfs/nfsroot.rst
View File

@ -342,7 +342,7 @@ They depend on various facilities being available:
When using pxelinux, the kernel image is specified using
"kernel <relative-path-below /tftpboot>". The nfsroot parameters
are passed to the kernel by adding them to the "append" line.
It is common to use serial console in conjunction with pxeliunx,
It is common to use serial console in conjunction with pxelinux,
see Documentation/admin-guide/serial-console.rst for more information.
For more information on isolinux, including how to create bootdisks

4
Documentation/admin-guide/perf/hisi-pmu.rst
View File

@ -110,8 +110,8 @@ uring channel. It is 2 bits. Some important codes are as follows:
- 2'b11: count the events which sent to the uring_ext (MATA) channel;
- 2'b01: is the same as 2'b11;
- 2'b10: count the events which sent to the uring (non-MATA) channel;
- 2'b00: default value, count the events which sent to the both uring and
uring_ext channel;
- 2'b00: default value, count the events which sent to both uring and
uring_ext channels;
6. ch: NoC PMU supports filtering the event counts of certain transaction
channel with this option. The current supported channels are as follows:

4
Documentation/admin-guide/quickly-build-trimmed-linux.rst
View File

@ -273,7 +273,7 @@ again.
does nothing at all; in that case you have to manually install your kernel,
as outlined in the reference section.
If you are running a immutable Linux distribution, check its documentation
If you are running an immutable Linux distribution, check its documentation
and the web to find out how to install your own kernel there.
[:ref:`details<install>`]
@ -884,7 +884,7 @@ When a build error occurs, it might be caused by some aspect of your machine's
setup that often can be fixed quickly; other times though the problem lies in
the code and can only be fixed by a developer. A close examination of the
failure messages coupled with some research on the internet will often tell you
which of the two it is. To perform such a investigation, restart the build
which of the two it is. To perform such an investigation, restart the build
process like this::
make V=1

4
Documentation/admin-guide/reporting-issues.rst
View File

@ -611,7 +611,7 @@ better place.
How to read the MAINTAINERS file
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To illustrate how to use the :ref:`MAINTAINERS <maintainers>` file, lets assume
To illustrate how to use the :ref:`MAINTAINERS <maintainers>` file, let's assume
the WiFi in your Laptop suddenly misbehaves after updating the kernel. In that
case it's likely an issue in the WiFi driver. Obviously it could also be some
code it builds upon, but unless you suspect something like that stick to the
@ -1543,7 +1543,7 @@ as well, because that will speed things up.
And note, it helps developers a great deal if you can specify the exact version
that introduced the problem. Hence if possible within a reasonable time frame,
try to find that version using vanilla kernels. Lets assume something broke when
try to find that version using vanilla kernels. Let's assume something broke when
your distributor released a update from Linux kernel 5.10.5 to 5.10.8. Then as
instructed above go and check the latest kernel from that version line, say
5.10.9. If it shows the problem, try a vanilla 5.10.5 to ensure that no patches

4
Documentation/admin-guide/sysctl/fs.rst
View File

@ -164,8 +164,8 @@ pipe-user-pages-soft
--------------------
Maximum total number of pages a non-privileged user may allocate for pipes
before the pipe size gets limited to a single page. Once this limit is reached,
new pipes will be limited to a single page in size for this user in order to
before the pipe size gets limited to two pages. Once this limit is reached,
new pipes will be limited to two pages in size for this user in order to
limit total memory usage, and trying to increase them using ``fcntl()`` will be
denied until usage goes below the limit again. The default value allows to
allocate up to 1024 pipes at their default size. When set to 0, no limit is

18
Documentation/admin-guide/sysctl/index.rst
View File

@ -66,25 +66,31 @@ This documentation is about:
=============== ===============================================================
abi/ execution domains & personalities
debug/ <empty>
dev/ device specific information (eg dev/cdrom/info)
<$ARCH> tuning controls for various CPU architecture (e.g. csky, s390)
crypto/ <undocumented>
debug/ <undocumented>
dev/ device specific information (e.g. dev/cdrom/info)
fs/ specific filesystems
filehandle, inode, dentry and quota tuning
binfmt_misc <Documentation/admin-guide/binfmt-misc.rst>
kernel/ global kernel info / tuning
miscellaneous stuff
some architecture-specific controls
security (LSM) stuff
net/ networking stuff, for documentation look in:
<Documentation/networking/>
proc/ <empty>
sunrpc/ SUN Remote Procedure Call (NFS)
user/ Per user namespace limits
vm/ memory management tuning
buffer and cache management
user/ Per user per user namespace limits
xen/ <undocumented>
=============== ===============================================================
These are the subdirs I have on my system. There might be more
or other subdirs in another setup. If you see another dir, I'd
really like to hear about it :-)
These are the subdirs I have on my system or have been discovered by
searching through the source code. There might be more or other subdirs
in another setup. If you see another dir, I'd really like to hear about
it :-)
.. toctree::
:maxdepth: 1

2
Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst
View File

@ -1757,7 +1757,7 @@ or all of these tasks:
to your bootloader's configuration.
You have to take care of some or all of the tasks yourself, if your
distribution lacks a installkernel script or does only handle part of them.
distribution lacks an installkernel script or does only handle part of them.
Consult the distribution's documentation for details. If in doubt, install the
kernel manually::

2
Documentation/arch/arm/stm32/stm32f746-overview.rst
View File

@ -15,7 +15,7 @@ It features:
- SD/MMC/SDIO support
- Ethernet controller
- USB OTFG FS & HS controllers
- I2C, SPI, CAN busses support
- I2C, SPI, CAN buses support
- Several 16 & 32 bits general purpose timers
- Serial Audio interface
- LCD controller

2
Documentation/arch/arm/stm32/stm32f769-overview.rst
View File

@ -15,7 +15,7 @@ It features:
- SD/MMC/SDIO support*2
- Ethernet controller
- USB OTFG FS & HS controllers
- I2C*4, SPI*6, CAN*3 busses support
- I2C*4, SPI*6, CAN*3 buses support
- Several 16 & 32 bits general purpose timers
- Serial Audio interface*2
- LCD controller

2
Documentation/arch/arm/stm32/stm32h743-overview.rst
View File

@ -15,7 +15,7 @@ It features:
- SD/MMC/SDIO support
- Ethernet controller
- USB OTFG FS & HS controllers
- I2C, SPI, CAN busses support
- I2C, SPI, CAN buses support
- Several 16 & 32 bits general purpose timers
- Serial Audio interface
- LCD controller

2
Documentation/arch/arm/stm32/stm32h750-overview.rst
View File

@ -15,7 +15,7 @@ It features:
- SD/MMC/SDIO support
- Ethernet controller
- USB OTFG FS & HS controllers
- I2C, SPI, CAN busses support
- I2C, SPI, CAN buses support
- Several 16 & 32 bits general purpose timers
- Serial Audio interface
- LCD controller

2
Documentation/arch/arm/stm32/stm32mp13-overview.rst
View File

@ -24,7 +24,7 @@ More details:
- ADC/DAC
- USB EHCI/OHCI controllers
- USB OTG
- I2C, SPI, CAN busses support
- I2C, SPI, CAN buses support
- Several general purpose timers
- Serial Audio interface
- LCD controller

2
Documentation/arch/arm/stm32/stm32mp151-overview.rst
View File

@ -23,7 +23,7 @@ More details:
- ADC/DAC
- USB EHCI/OHCI controllers
- USB OTG
- I2C, SPI busses support
- I2C, SPI buses support
- Several general purpose timers
- Serial Audio interface
- LCD-TFT controller

4
Documentation/arch/loongarch/irq-chip-model.rst
View File

@ -139,13 +139,13 @@ Feature EXTIOI_HAS_INT_ENCODE is part of standard EIOINTC. If it is 1, it
indicates that CPU Interrupt Pin selection can be normal method rather than
bitmap method, so interrupt can be routed to IP0 - IP15.
Feature EXTIOI_HAS_CPU_ENCODE is entension of V-EIOINTC. If it is 1, it
Feature EXTIOI_HAS_CPU_ENCODE is extension of V-EIOINTC. If it is 1, it
indicates that CPU selection can be normal method rather than bitmap method,
so interrupt can be routed to CPU0 - CPU255.
EXTIOI_VIRT_CONFIG
------------------
This register is read-write register, for compatibility intterupt routed uses
This register is read-write register, for compatibility interrupt routed uses
the default method which is the same with standard EIOINTC. If the bit is set
with 1, it indicated HW to use normal method rather than bitmap method.

1
Documentation/arch/powerpc/eeh-pci-error-recovery.rst
View File

@ -315,7 +315,6 @@ network daemons and file systems that didn't need to be disturbed.
ideally, the reset should happen at or below the block layer,
so that the file systems are not disturbed.
Reiserfs does not tolerate errors returned from the block device.
Ext3fs seems to be tolerant, retrying reads/writes until it does
succeed. Both have been only lightly tested in this scenario.

2
Documentation/arch/x86/cpuinfo.rst
View File

@ -11,7 +11,7 @@ The list of feature flags in /proc/cpuinfo is not complete and
represents an ill-fated attempt from long time ago to put feature flags
in an easy to find place for userspace.
However, the amount of feature flags is growing by the CPU generation,
However, the number of feature flags is growing with each CPU generation,
leading to unparseable and unwieldy /proc/cpuinfo.
What is more, those feature flags do not even need to be in that file

106
Documentation/conf.py
View File

@ -9,6 +9,8 @@ import os
import shutil
import sys
from textwrap import dedent
import sphinx
# If extensions (or modules to document with autodoc) are in another directory,
@ -51,11 +53,13 @@ else:
dyn_exclude_patterns.append("devicetree/bindings/**.yaml")
dyn_exclude_patterns.append("core-api/kho/bindings/**.yaml")
# Properly handle include/exclude patterns
# ----------------------------------------
# Properly handle directory patterns and LaTeX docs
# -------------------------------------------------
def update_patterns(app, config):
def config_init(app, config):
"""
Initialize path-dependent variabled
On Sphinx, all directories are relative to what it is passed as
SOURCEDIR parameter for sphinx-build. Due to that, all patterns
that have directory names on it need to be dynamically set, after
@ -86,6 +90,38 @@ def update_patterns(app, config):
config.exclude_patterns.append(rel_path)
# LaTeX and PDF output require a list of documents with are dependent
# of the app.srcdir. Add them here
# When SPHINXDIRS is used, we just need to get index.rst, if it exists
if not os.path.samefile(doctree, app.srcdir):
doc = os.path.basename(app.srcdir)
fname = "index"
if os.path.exists(os.path.join(app.srcdir, fname + ".rst")):
latex_documents.append((fname, doc + ".tex",
"Linux %s Documentation" % doc.capitalize(),
"The kernel development community",
"manual"))
return
# When building all docs, or when a main index.rst doesn't exist, seek
# for it on subdirectories
for doc in os.listdir(app.srcdir):
fname = os.path.join(doc, "index")
if not os.path.exists(os.path.join(app.srcdir, fname + ".rst")):
continue
has = False
for l in latex_documents:
if l[0] == fname:
has = True
break
if not has:
latex_documents.append((fname, doc + ".tex",
"Linux %s Documentation" % doc.capitalize(),
"The kernel development community",
"manual"))
# helper
# ------
@ -234,7 +270,7 @@ author = "The kernel development community"
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# In a normal build, version and release are are set to KERNELVERSION and
# In a normal build, version and release are set to KERNELVERSION and
# KERNELRELEASE, respectively, from the Makefile via Sphinx command line
# arguments.
#
@ -420,19 +456,25 @@ htmlhelp_basename = "TheLinuxKerneldoc"
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
"papersize": "a4paper",
"passoptionstopackages": dedent(r"""
\PassOptionsToPackage{svgnames}{xcolor}
"""),
# The font size ('10pt', '11pt' or '12pt').
"pointsize": "11pt",
# Needed to generate a .ind file
"printindex": r"\footnotesize\raggedright\printindex",
# Latex figure (float) alignment
# 'figure_align': 'htbp',
# Don't mangle with UTF-8 chars
"fontenc": "",
"inputenc": "",
"utf8extra": "",
# Set document margins
"sphinxsetup": """
"sphinxsetup": dedent(r"""
hmargin=0.5in, vmargin=1in,
parsedliteralwraps=true,
verbatimhintsturnover=false,
""",
"""),
#
# Some of our authors are fond of deep nesting; tell latex to
# cope.
@ -440,48 +482,22 @@ latex_elements = {
"maxlistdepth": "10",
# For CJK One-half spacing, need to be in front of hyperref
"extrapackages": r"\usepackage{setspace}",
# Additional stuff for the LaTeX preamble.
"preamble": """
% Use some font with UTF-8 support with XeLaTeX
\\usepackage{fontspec}
\\setsansfont{DejaVu Sans}
\\setromanfont{DejaVu Serif}
\\setmonofont{DejaVu Sans Mono}
""",
"fontpkg": dedent(r"""
\usepackage{fontspec}
\setmainfont{DejaVu Serif}
\setsansfont{DejaVu Sans}
\setmonofont{DejaVu Sans Mono}
\newfontfamily\headingfont{DejaVu Serif}
"""),
"preamble": dedent(r"""
% Load kerneldoc specific LaTeX settings
\input{kerneldoc-preamble.sty}
""")
}
# Load kerneldoc specific LaTeX settings
latex_elements["preamble"] += """
% Load kerneldoc specific LaTeX settings
\\input{kerneldoc-preamble.sty}
"""
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
# Sorted in alphabetical order
# This will be filled up by config-inited event
latex_documents = []
# Add all other index files from Documentation/ subdirectories
for fn in os.listdir("."):
doc = os.path.join(fn, "index")
if os.path.exists(doc + ".rst"):
has = False
for l in latex_documents:
if l[0] == doc:
has = True
break
if not has:
latex_documents.append(
(
doc,
fn + ".tex",
"Linux %s Documentation" % fn.capitalize(),
"The kernel development community",
"manual",
)
)
# The name of an image file (relative to this directory) to place at the top of
# the title page.
# latex_logo = None
@ -577,4 +593,4 @@ loadConfig(globals())
def setup(app):
"""Patterns need to be updated at init time on older Sphinx versions"""
app.connect('config-inited', update_patterns)
app.connect('config-inited', config_init)

2
Documentation/core-api/folio_queue.rst
View File

@ -44,7 +44,7 @@ Each segment in the list also stores:
* the size of each folio and
* three 1-bit marks per folio,
but hese should not be accessed directly as the underlying data structure may
but these should not be accessed directly as the underlying data structure may
change, but rather the access functions outlined below should be used.
The facility can be made accessible by::

1
Documentation/core-api/index.rst
View File

@ -24,6 +24,7 @@ it.
printk-index
symbol-namespaces
asm-annotations
real-time/index
Data structures and low-level utilities
=======================================

6
Documentation/core-api/irq/irq-affinity.rst
View File

@ -9,9 +9,9 @@ ChangeLog:
/proc/irq/IRQ#/smp_affinity and /proc/irq/IRQ#/smp_affinity_list specify
which target CPUs are permitted for a given IRQ source. It's a bitmask
(smp_affinity) or cpu list (smp_affinity_list) of allowed CPUs. It's not
(smp_affinity) or CPU list (smp_affinity_list) of allowed CPUs. It's not
allowed to turn off all CPUs, and if an IRQ controller does not support
IRQ affinity then the value will not change from the default of all cpus.
IRQ affinity then the value will not change from the default of all CPUs.
/proc/irq/default_smp_affinity specifies default affinity mask that applies
to all non-active IRQs. Once IRQ is allocated/activated its affinity bitmask
@ -60,7 +60,7 @@ Now lets restrict that IRQ to CPU(4-7).
This time around IRQ44 was delivered only to the last four processors.
i.e counters for the CPU0-3 did not change.
Here is an example of limiting that same irq (44) to cpus 1024 to 1031::
Here is an example of limiting that same IRQ (44) to CPUs 1024 to 1031::
[root@moon 44]# echo 1024-1031 > smp_affinity_list
[root@moon 44]# cat smp_affinity_list

38
Documentation/core-api/irq/irq-domain.rst
View File

@ -18,8 +18,8 @@ handlers as irqchips. I.e. in effect cascading interrupt controllers.
So in the past, IRQ numbers could be chosen so that they match the
hardware IRQ line into the root interrupt controller (i.e. the
component actually firing the interrupt line to the CPU). Nowadays,
this number is just a number and the number loose all kind of
correspondence to hardware interrupt numbers.
this number is just a number and the number has no
relationship to hardware interrupt numbers.
For this reason, we need a mechanism to separate controller-local
interrupt numbers, called hardware IRQs, from Linux IRQ numbers.
@ -77,15 +77,15 @@ Once a mapping has been established, it can be retrieved or used via a
variety of methods:
- irq_resolve_mapping() returns a pointer to the irq_desc structure
for a given domain and hwirq number, and NULL if there was no
for a given domain and hwirq number, or NULL if there was no
mapping.
- irq_find_mapping() returns a Linux IRQ number for a given domain and
hwirq number, and 0 if there was no mapping
hwirq number, or 0 if there was no mapping
- generic_handle_domain_irq() handles an interrupt described by a
domain and a hwirq number
Note that irq domain lookups must happen in contexts that are
compatible with a RCU read-side critical section.
Note that irq_domain lookups must happen in contexts that are
compatible with an RCU read-side critical section.
The irq_create_mapping() function must be called *at least once*
before any call to irq_find_mapping(), lest the descriptor will not
@ -100,7 +100,7 @@ Types of irq_domain Mappings
============================
There are several mechanisms available for reverse mapping from hwirq
to Linux irq, and each mechanism uses a different allocation function.
to Linux IRQ, and each mechanism uses a different allocation function.
Which reverse map type should be used depends on the use case. Each
of the reverse map types are described below:
@ -111,13 +111,13 @@ Linear
irq_domain_create_linear()
The linear reverse map maintains a fixed size table indexed by the
The linear reverse map maintains a fixed-size table indexed by the
hwirq number. When a hwirq is mapped, an irq_desc is allocated for
the hwirq, and the IRQ number is stored in the table.
The Linear map is a good choice when the maximum number of hwirqs is
fixed and a relatively small number (~ < 256). The advantages of this
map are fixed time lookup for IRQ numbers, and irq_descs are only
map are fixed-time lookup for IRQ numbers, and irq_descs are only
allocated for in-use IRQs. The disadvantage is that the table must be
as large as the largest possible hwirq number.
@ -134,7 +134,7 @@ The irq_domain maintains a radix tree map from hwirq numbers to Linux
IRQs. When an hwirq is mapped, an irq_desc is allocated and the
hwirq is used as the lookup key for the radix tree.
The tree map is a good choice if the hwirq number can be very large
The Tree map is a good choice if the hwirq number can be very large
since it doesn't need to allocate a table as large as the largest
hwirq number. The disadvantage is that hwirq to IRQ number lookup is
dependent on how many entries are in the table.
@ -169,10 +169,10 @@ Legacy
The Legacy mapping is a special case for drivers that already have a
range of irq_descs allocated for the hwirqs. It is used when the
driver cannot be immediately converted to use the linear mapping. For
driver cannot be immediately converted to use the Linear mapping. For
example, many embedded system board support files use a set of #defines
for IRQ numbers that are passed to struct device registrations. In that
case the Linux IRQ numbers cannot be dynamically assigned and the legacy
case the Linux IRQ numbers cannot be dynamically assigned and the Legacy
mapping should be used.
As the name implies, the \*_legacy() functions are deprecated and only
@ -180,15 +180,15 @@ exist to ease the support of ancient platforms. No new users should be
added. Same goes for the \*_simple() functions when their use results
in the legacy behaviour.
The legacy map assumes a contiguous range of IRQ numbers has already
The Legacy map assumes a contiguous range of IRQ numbers has already
been allocated for the controller and that the IRQ number can be
calculated by adding a fixed offset to the hwirq number, and
visa-versa. The disadvantage is that it requires the interrupt
controller to manage IRQ allocations and it requires an irq_desc to be
allocated for every hwirq, even if it is unused.
The legacy map should only be used if fixed IRQ mappings must be
supported. For example, ISA controllers would use the legacy map for
The Legacy map should only be used if fixed IRQ mappings must be
supported. For example, ISA controllers would use the Legacy map for
mapping Linux IRQs 0-15 so that existing ISA drivers get the correct IRQ
numbers.
@ -197,7 +197,7 @@ which will use a legacy domain only if an IRQ range is supplied by the
system and will otherwise use a linear domain mapping. The semantics of
this call are such that if an IRQ range is specified then descriptors
will be allocated on-the-fly for it, and if no range is specified it
will fall through to irq_domain_create_linear() which means *no* irq
will fall through to irq_domain_create_linear() which means *no* IRQ
descriptors will be allocated.
A typical use case for simple domains is where an irqchip provider
@ -214,7 +214,7 @@ Hierarchy IRQ Domain
On some architectures, there may be multiple interrupt controllers
involved in delivering an interrupt from the device to the target CPU.
Let's look at a typical interrupt delivering path on x86 platforms::
Let's look at a typical interrupt delivery path on x86 platforms::
Device --> IOAPIC -> Interrupt remapping Controller -> Local APIC -> CPU
@ -227,8 +227,8 @@ There are three interrupt controllers involved:
To support such a hardware topology and make software architecture match
hardware architecture, an irq_domain data structure is built for each
interrupt controller and those irq_domains are organized into hierarchy.
When building irq_domain hierarchy, the irq_domain near to the device is
child and the irq_domain near to CPU is parent. So a hierarchy structure
When building irq_domain hierarchy, the irq_domain nearest the device is
child and the irq_domain nearest the CPU is parent. So a hierarchy structure
as below will be built for the example above::
CPU Vector irq_domain (root irq_domain to manage CPU vectors)

2
Documentation/core-api/printk-formats.rst
View File

@ -521,7 +521,7 @@ Fwnode handles
%pfw[fP]
For printing information on fwnode handles. The default is to print the full
For printing information on an fwnode_handle. The default is to print the full
node name, including the path. The modifiers are functionally equivalent to
%pOF above.

109
Documentation/core-api/real-time/architecture-porting.rst Normal file
View File

@ -0,0 +1,109 @@
.. SPDX-License-Identifier: GPL-2.0
=============================================
Porting an architecture to support PREEMPT_RT
=============================================
:Author: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
This list outlines the architecture specific requirements that must be
implemented in order to enable PREEMPT_RT. Once all required features are
implemented, ARCH_SUPPORTS_RT can be selected in architecture’s Kconfig to make
PREEMPT_RT selectable.
Many prerequisites (genirq support for example) are enforced by the common code
and are omitted here.
The optional features are not strictly required but it is worth to consider
them.
Requirements
------------
Forced threaded interrupts
CONFIG_IRQ_FORCED_THREADING must be selected. Any interrupts that must
remain in hard-IRQ context must be marked with IRQF_NO_THREAD. This
requirement applies for instance to clocksource event interrupts,
perf interrupts and cascading interrupt-controller handlers.
PREEMPTION support
Kernel preemption must be supported and requires that
CONFIG_ARCH_NO_PREEMPT remain unselected. Scheduling requests, such as those
issued from an interrupt or other exception handler, must be processed
immediately.
POSIX CPU timers and KVM
POSIX CPU timers must expire from thread context rather than directly within
the timer interrupt. This behavior is enabled by setting the configuration
option CONFIG_HAVE_POSIX_CPU_TIMERS_TASK_WORK.
When KVM is enabled, CONFIG_KVM_XFER_TO_GUEST_WORK must also be set to ensure
that any pending work, such as POSIX timer expiration, is handled before
transitioning into guest mode.
Hard-IRQ and Soft-IRQ stacks
Soft interrupts are handled in the thread context in which they are raised. If
a soft interrupt is triggered from hard-IRQ context, its execution is deferred
to the ksoftirqd thread. Preemption is never disabled during soft interrupt
handling, which makes soft interrupts preemptible.
If an architecture provides a custom __do_softirq() implementation that uses a
separate stack, it must select CONFIG_HAVE_SOFTIRQ_ON_OWN_STACK. The
functionality should only be enabled when CONFIG_SOFTIRQ_ON_OWN_STACK is set.
FPU and SIMD access in kernel mode
FPU and SIMD registers are typically not used in kernel mode and are therefore
not saved during kernel preemption. As a result, any kernel code that uses
these registers must be enclosed within a kernel_fpu_begin() and
kernel_fpu_end() section.
The kernel_fpu_begin() function usually invokes local_bh_disable() to prevent
interruptions from softirqs and to disable regular preemption. This allows the
protected code to run safely in both thread and softirq contexts.
On PREEMPT_RT kernels, however, kernel_fpu_begin() must not call
local_bh_disable(). Instead, it should use preempt_disable(), since softirqs
are always handled in thread context under PREEMPT_RT. In this case, disabling
preemption alone is sufficient.
The crypto subsystem operates on memory pages and requires users to "walk and
map" these pages while processing a request. This operation must occur outside
the kernel_fpu_begin()/ kernel_fpu_end() section because it requires preemption
to be enabled. These preemption points are generally sufficient to avoid
excessive scheduling latency.
Exception handlers
Exception handlers, such as the page fault handler, typically enable interrupts
early, before invoking any generic code to process the exception. This is
necessary because handling a page fault may involve operations that can sleep.
Enabling interrupts is especially important on PREEMPT_RT, where certain
locks, such as spinlock_t, become sleepable. For example, handling an
invalid opcode may result in sending a SIGILL signal to the user task. A
debug excpetion will send a SIGTRAP signal.
In both cases, if the exception occurred in user space, it is safe to enable
interrupts early. Sending a signal requires both interrupts and kernel
preemption to be enabled.
Optional features
-----------------
Timer and clocksource
A high-resolution clocksource and clockevents device are recommended. The
clockevents device should support the CLOCK_EVT_FEAT_ONESHOT feature for
optimal timer behavior. In most cases, microsecond-level accuracy is
sufficient
Lazy preemption
This mechanism allows an in-kernel scheduling request for non-real-time tasks
to be delayed until the task is about to return to user space. It helps avoid
preempting a task that holds a sleeping lock at the time of the scheduling
request.
With CONFIG_GENERIC_IRQ_ENTRY enabled, supporting this feature requires
defining a bit for TIF_NEED_RESCHED_LAZY, preferably near TIF_NEED_RESCHED.
Serial console with NBCON
With PREEMPT_RT enabled, all console output is handled by a dedicated thread
rather than directly from the context in which printk() is invoked. This design
allows printk() to be safely used in atomic contexts.
However, this also means that if the kernel crashes and cannot switch to the
printing thread, no output will be visible preventing the system from printing
its final messages.
There are exceptions for immediate output, such as during panic() handling. To
support this, the console driver must implement new-style lock handling. This
involves setting the CON_NBCON flag in console::flags and providing
implementations for the write_atomic, write_thread, device_lock, and
device_unlock callbacks.

242
Documentation/core-api/real-time/differences.rst Normal file
View File

@ -0,0 +1,242 @@
.. SPDX-License-Identifier: GPL-2.0
===========================
How realtime kernels differ
===========================
:Author: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
Preface
=======
With forced-threaded interrupts and sleeping spin locks, code paths that
previously caused long scheduling latencies have been made preemptible and
moved into process context. This allows the scheduler to manage them more
effectively and respond to higher-priority tasks with reduced latency.
The following chapters provide an overview of key differences between a
PREEMPT_RT kernel and a standard, non-PREEMPT_RT kernel.
Locking
=======
Spinning locks such as spinlock_t are used to provide synchronization for data
structures accessed from both interrupt context and process context. For this
reason, locking functions are also available with the _irq() or _irqsave()
suffixes, which disable interrupts before acquiring the lock. This ensures that
the lock can be safely acquired in process context when interrupts are enabled.
However, on a PREEMPT_RT system, interrupts are forced-threaded and no longer
run in hard IRQ context. As a result, there is no need to disable interrupts as
part of the locking procedure when using spinlock_t.
For low-level core components such as interrupt handling, the scheduler, or the
timer subsystem the kernel uses raw_spinlock_t. This lock type preserves
traditional semantics: it disables preemption and, when used with _irq() or
_irqsave(), also disables interrupts. This ensures proper synchronization in
critical sections that must remain non-preemptible or with interrupts disabled.
Execution context
=================
Interrupt handling in a PREEMPT_RT system is invoked in process context through
the use of threaded interrupts. Other parts of the kernel also shift their
execution into threaded context by different mechanisms. The goal is to keep
execution paths preemptible, allowing the scheduler to interrupt them when a
higher-priority task needs to run.
Below is an overview of the kernel subsystems involved in this transition to
threaded, preemptible execution.
Interrupt handling
------------------
All interrupts are forced-threaded in a PREEMPT_RT system. The exceptions are
interrupts that are requested with the IRQF_NO_THREAD, IRQF_PERCPU, or
IRQF_ONESHOT flags.
The IRQF_ONESHOT flag is used together with threaded interrupts, meaning those
registered using request_threaded_irq() and providing only a threaded handler.
Its purpose is to keep the interrupt line masked until the threaded handler has
completed.
If a primary handler is also provided in this case, it is essential that the
handler does not acquire any sleeping locks, as it will not be threaded. The
handler should be minimal and must avoid introducing delays, such as
busy-waiting on hardware registers.
Soft interrupts, bottom half handling
-------------------------------------
Soft interrupts are raised by the interrupt handler and are executed after the
handler returns. Since they run in thread context, they can be preempted by
other threads. Do not assume that softirq context runs with preemption
disabled. This means you must not rely on mechanisms like local_bh_disable() in
process context to protect per-CPU variables. Because softirq handlers are
preemptible under PREEMPT_RT, this approach does not provide reliable
synchronization.
If this kind of protection is required for performance reasons, consider using
local_lock_nested_bh(). On non-PREEMPT_RT kernels, this allows lockdep to
verify that bottom halves are disabled. On PREEMPT_RT systems, it adds the
necessary locking to ensure proper protection.
Using local_lock_nested_bh() also makes the locking scope explicit and easier
for readers and maintainers to understand.
per-CPU variables
-----------------
Protecting access to per-CPU variables solely by using preempt_disable() should
be avoided, especially if the critical section has unbounded runtime or may
call APIs that can sleep.
If using a spinlock_t is considered too costly for performance reasons,
consider using local_lock_t. On non-PREEMPT_RT configurations, this introduces
no runtime overhead when lockdep is disabled. With lockdep enabled, it verifies
that the lock is only acquired in process context and never from softirq or
hard IRQ context.
On a PREEMPT_RT kernel, local_lock_t is implemented using a per-CPU spinlock_t,
which provides safe local protection for per-CPU data while keeping the system
preemptible.
Because spinlock_t on PREEMPT_RT does not disable preemption, it cannot be used
to protect per-CPU data by relying on implicit preemption disabling. If this
inherited preemption disabling is essential and if local_lock_t cannot be used
due to performance constraints, brevity of the code, or abstraction boundaries
within an API then preempt_disable_nested() may be a suitable alternative. On
non-PREEMPT_RT kernels, it verifies with lockdep that preemption is already
disabled. On PREEMPT_RT, it explicitly disables preemption.
Timers
------
By default, an hrtimer is executed in hard interrupt context. The exception is
timers initialized with the HRTIMER_MODE_SOFT flag, which are executed in
softirq context.
On a PREEMPT_RT kernel, this behavior is reversed: hrtimers are executed in
softirq context by default, typically within the ktimersd thread. This thread
runs at the lowest real-time priority, ensuring it executes before any
SCHED_OTHER tasks but does not interfere with higher-priority real-time
threads. To explicitly request execution in hard interrupt context on
PREEMPT_RT, the timer must be marked with the HRTIMER_MODE_HARD flag.
Memory allocation
-----------------
The memory allocation APIs, such as kmalloc() and alloc_pages(), require a
gfp_t flag to indicate the allocation context. On non-PREEMPT_RT kernels, it is
necessary to use GFP_ATOMIC when allocating memory from interrupt context or
from sections where preemption is disabled. This is because the allocator must
not sleep in these contexts waiting for memory to become available.
However, this approach does not work on PREEMPT_RT kernels. The memory
allocator in PREEMPT_RT uses sleeping locks internally, which cannot be
acquired when preemption is disabled. Fortunately, this is generally not a
problem, because PREEMPT_RT moves most contexts that would traditionally run
with preemption or interrupts disabled into threaded context, where sleeping is
allowed.
What remains problematic is code that explicitly disables preemption or
interrupts. In such cases, memory allocation must be performed outside the
critical section.
This restriction also applies to memory deallocation routines such as kfree()
and free_pages(), which may also involve internal locking and must not be
called from non-preemptible contexts.
IRQ work
--------
The irq_work API provides a mechanism to schedule a callback in interrupt
context. It is designed for use in contexts where traditional scheduling is not
possible, such as from within NMI handlers or from inside the scheduler, where
using a workqueue would be unsafe.
On non-PREEMPT_RT systems, all irq_work items are executed immediately in
interrupt context. Items marked with IRQ_WORK_LAZY are deferred until the next
timer tick but are still executed in interrupt context.
On PREEMPT_RT systems, the execution model changes. Because irq_work callbacks
may acquire sleeping locks or have unbounded execution time, they are handled
in thread context by a per-CPU irq_work kernel thread. This thread runs at the
lowest real-time priority, ensuring it executes before any SCHED_OTHER tasks
but does not interfere with higher-priority real-time threads.
The exception are work items marked with IRQ_WORK_HARD_IRQ, which are still
executed in hard interrupt context. Lazy items (IRQ_WORK_LAZY) continue to be
deferred until the next timer tick and are also executed by the irq_work/
thread.
RCU callbacks
-------------
RCU callbacks are invoked by default in softirq context. Their execution is
important because, depending on the use case, they either free memory or ensure
progress in state transitions. Running these callbacks as part of the softirq
chain can lead to undesired situations, such as contention for CPU resources
with other SCHED_OTHER tasks when executed within ksoftirqd.
To avoid running callbacks in softirq context, the RCU subsystem provides a
mechanism to execute them in process context instead. This behavior can be
enabled by setting the boot command-line parameter rcutree.use_softirq=0. This
setting is enforced in kernels configured with PREEMPT_RT.
Spin until ready
================
The "spin until ready" pattern involves repeatedly checking (spinning on) the
state of a data structure until it becomes available. This pattern assumes that
preemption, soft interrupts, or interrupts are disabled. If the data structure
is marked busy, it is presumed to be in use by another CPU, and spinning should
eventually succeed as that CPU makes progress.
Some examples are hrtimer_cancel() or timer_delete_sync(). These functions
cancel timers that execute with interrupts or soft interrupts disabled. If a
thread attempts to cancel a timer and finds it active, spinning until the
callback completes is safe because the callback can only run on another CPU and
will eventually finish.
On PREEMPT_RT kernels, however, timer callbacks run in thread context. This
introduces a challenge: a higher-priority thread attempting to cancel the timer
may preempt the timer callback thread. Since the scheduler cannot migrate the
callback thread to another CPU due to affinity constraints, spinning can result
in livelock even on multiprocessor systems.
To avoid this, both the canceling and callback sides must use a handshake
mechanism that supports priority inheritance. This allows the canceling thread
to suspend until the callback completes, ensuring forward progress without
risking livelock.
In order to solve the problem at the API level, the sequence locks were extended
to allow a proper handover between the the spinning reader and the maybe
blocked writer.
Sequence locks
--------------
Sequence counters and sequential locks are documented in
Documentation/locking/seqlock.rst.
The interface has been extended to ensure proper preemption states for the
writer and spinning reader contexts. This is achieved by embedding the writer
serialization lock directly into the sequence counter type, resulting in
composite types such as seqcount_spinlock_t or seqcount_mutex_t.
These composite types allow readers to detect an ongoing write and actively
boost the writer’s priority to help it complete its update instead of spinning
and waiting for its completion.
If the plain seqcount_t is used, extra care must be taken to synchronize the
reader with the writer during updates. The writer must ensure its update is
serialized and non-preemptible relative to the reader. This cannot be achieved
using a regular spinlock_t because spinlock_t on PREEMPT_RT does not disable
preemption. In such cases, using seqcount_spinlock_t is the preferred solution.
However, if there is no spinning involved i.e., if the reader only needs to
detect whether a write has started and not serialize against it then using
seqcount_t is reasonable.

16
Documentation/core-api/real-time/index.rst Normal file
View File

@ -0,0 +1,16 @@
.. SPDX-License-Identifier: GPL-2.0
=====================
Real-time preemption
=====================
This documentation is intended for Linux kernel developers and contributors
interested in the inner workings of PREEMPT_RT. It explains key concepts and
the required changes compared to a non-PREEMPT_RT configuration.
.. toctree::
:maxdepth: 2
theory
differences
architecture-porting

116
Documentation/core-api/real-time/theory.rst Normal file
View File

@ -0,0 +1,116 @@
.. SPDX-License-Identifier: GPL-2.0
=====================
Theory of operation
=====================
:Author: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
Preface
=======
PREEMPT_RT transforms the Linux kernel into a real-time kernel. It achieves
this by replacing locking primitives, such as spinlock_t, with a preemptible
and priority-inheritance aware implementation known as rtmutex, and by enforcing
the use of threaded interrupts. As a result, the kernel becomes fully
preemptible, with the exception of a few critical code paths, including entry
code, the scheduler, and low-level interrupt handling routines.
This transformation places the majority of kernel execution contexts under the
control of the scheduler and significantly increasing the number of preemption
points. Consequently, it reduces the latency between a high-priority task
becoming runnable and its actual execution on the CPU.
Scheduling
==========
The core principles of Linux scheduling and the associated user-space API are
documented in the man page sched(7)
`sched(7) <https://man7.org/linux/man-pages/man7/sched.7.html>`_.
By default, the Linux kernel uses the SCHED_OTHER scheduling policy. Under
this policy, a task is preempted when the scheduler determines that it has
consumed a fair share of CPU time relative to other runnable tasks. However,
the policy does not guarantee immediate preemption when a new SCHED_OTHER task
becomes runnable. The currently running task may continue executing.
This behavior differs from that of real-time scheduling policies such as
SCHED_FIFO. When a task with a real-time policy becomes runnable, the
scheduler immediately selects it for execution if it has a higher priority than
the currently running task. The task continues to run until it voluntarily
yields the CPU, typically by blocking on an event.
Sleeping spin locks
===================
The various lock types and their behavior under real-time configurations are
described in detail in Documentation/locking/locktypes.rst.
In a non-PREEMPT_RT configuration, a spinlock_t is acquired by first disabling
preemption and then actively spinning until the lock becomes available. Once
the lock is released, preemption is enabled. From a real-time perspective,
this approach is undesirable because disabling preemption prevents the
scheduler from switching to a higher-priority task, potentially increasing
latency.
To address this, PREEMPT_RT replaces spinning locks with sleeping spin locks
that do not disable preemption. On PREEMPT_RT, spinlock_t is implemented using
rtmutex. Instead of spinning, a task attempting to acquire a contended lock
disables CPU migration, donates its priority to the lock owner (priority
inheritance), and voluntarily schedules out while waiting for the lock to
become available.
Disabling CPU migration provides the same effect as disabling preemption, while
still allowing preemption and ensuring that the task continues to run on the
same CPU while holding a sleeping lock.
Priority inheritance
====================
Lock types such as spinlock_t and mutex_t in a PREEMPT_RT enabled kernel are
implemented on top of rtmutex, which provides support for priority inheritance
(PI). When a task blocks on such a lock, the PI mechanism temporarily
propagates the blocked task’s scheduling parameters to the lock owner.
For example, if a SCHED_FIFO task A blocks on a lock currently held by a
SCHED_OTHER task B, task A’s scheduling policy and priority are temporarily
inherited by task B. After this inheritance, task A is put to sleep while
waiting for the lock, and task B effectively becomes the highest-priority task
in the system. This allows B to continue executing, make progress, and
eventually release the lock.
Once B releases the lock, it reverts to its original scheduling parameters, and
task A can resume execution.
Threaded interrupts
===================
Interrupt handlers are another source of code that executes with preemption
disabled and outside the control of the scheduler. To bring interrupt handling
under scheduler control, PREEMPT_RT enforces threaded interrupt handlers.
With forced threading, interrupt handling is split into two stages. The first
stage, the primary handler, is executed in IRQ context with interrupts disabled.
Its sole responsibility is to wake the associated threaded handler. The second
stage, the threaded handler, is the function passed to request_irq() as the
interrupt handler. It runs in process context, scheduled by the kernel.
From waking the interrupt thread until threaded handling is completed, the
interrupt source is masked in the interrupt controller. This ensures that the
device interrupt remains pending but does not retrigger the CPU, allowing the
system to exit IRQ context and handle the interrupt in a scheduled thread.
By default, the threaded handler executes with the SCHED_FIFO scheduling policy
and a priority of 50 (MAX_RT_PRIO / 2), which is midway between the minimum and
maximum real-time priorities.
If the threaded interrupt handler raises any soft interrupts during its
execution, those soft interrupt routines are invoked after the threaded handler
completes, within the same thread. Preemption remains enabled during the
execution of the soft interrupt handler.
Summary
=======
By using sleeping locks and forced-threaded interrupts, PREEMPT_RT
significantly reduces sections of code where interrupts or preemption is
disabled, allowing the scheduler to preempt the current execution context and
switch to a higher-priority task.

4
Documentation/dev-tools/autofdo.rst
View File

@ -131,11 +131,11 @@ Here is an example workflow for AutoFDO kernel:
For Zen3::
$ cat proc/cpuinfo | grep " brs"
$ cat /proc/cpuinfo | grep " brs"
For Zen4::
$ cat proc/cpuinfo | grep amd_lbr_v2
$ cat /proc/cpuinfo | grep amd_lbr_v2
The following command generated the perf data file::

1
Documentation/dev-tools/index.rst
View File

@ -29,6 +29,7 @@ Documentation/process/debugging/index.rst
ubsan
kmemleak
kcsan
lkmm/index
kfence
kselftest
kunit/index

5
Documentation/dev-tools/ktap.rst
View File

@ -5,7 +5,7 @@ The Kernel Test Anything Protocol (KTAP), version 1
===================================================
TAP, or the Test Anything Protocol is a format for specifying test results used
by a number of projects. It's website and specification are found at this `link
by a number of projects. Its website and specification are found at this `link
<https://testanything.org/>`_. The Linux Kernel largely uses TAP output for test
results. However, Kernel testing frameworks have special needs for test results
which don't align with the original TAP specification. Thus, a "Kernel TAP"
@ -20,6 +20,7 @@ machine-readable, whereas the diagnostic data is unstructured and is there to
aid human debugging.
KTAP output is built from four different types of lines:
- Version lines
- Plan lines
- Test case result lines
@ -38,6 +39,7 @@ All KTAP-formatted results begin with a "version line" which specifies which
version of the (K)TAP standard the result is compliant with.
For example:
- "KTAP version 1"
- "TAP version 13"
- "TAP version 14"
@ -276,6 +278,7 @@ Example KTAP output
This output defines the following hierarchy:
A single test called "main_test", which fails, and has three subtests:
- "example_test_1", which passes, and has one subtest:
- "test_1", which passes, and outputs the diagnostic message "test_1: initializing test_1"

11
Documentation/dev-tools/lkmm/docs/access-marking.rst Normal file
View File

@ -0,0 +1,11 @@
.. SPDX-License-Identifier: GPL-2.0
Access Marking
--------------
Literal include of ``tools/memory-model/Documentation/access-marking.txt``.
------------------------------------------------------------------
.. kernel-include:: tools/memory-model/Documentation/access-marking.txt
:literal:

11
Documentation/dev-tools/lkmm/docs/cheatsheet.rst Normal file
View File

@ -0,0 +1,11 @@
.. SPDX-License-Identifier: GPL-2.0
Cheatsheet
----------
Literal include of ``tools/memory-model/Documentation/cheatsheet.txt``.
------------------------------------------------------------------
.. kernel-include:: tools/memory-model/Documentation/cheatsheet.txt
:literal:

11
Documentation/dev-tools/lkmm/docs/control-dependencies.rst Normal file
View File

@ -0,0 +1,11 @@
.. SPDX-License-Identifier: GPL-2.0
Control Dependencies
--------------------
Literal include of ``tools/memory-model/Documentation/control-dependencies.txt``.
------------------------------------------------------------------
.. kernel-include:: tools/memory-model/Documentation/control-dependencies.txt
:literal:

11
Documentation/dev-tools/lkmm/docs/explanation.rst Normal file
View File

@ -0,0 +1,11 @@
.. SPDX-License-Identifier: GPL-2.0
Explanation
-----------
Literal include of ``tools/memory-model/Documentation/explanation.txt``.
------------------------------------------------------------------
.. kernel-include:: tools/memory-model/Documentation/explanation.txt
:literal:

11
Documentation/dev-tools/lkmm/docs/glossary.rst Normal file
View File

@ -0,0 +1,11 @@
.. SPDX-License-Identifier: GPL-2.0
Glossary
--------
Literal include of ``tools/memory-model/Documentation/glossary.txt``.
------------------------------------------------------------------
.. kernel-include:: tools/memory-model/Documentation/glossary.txt
:literal:

11
Documentation/dev-tools/lkmm/docs/herd-representation.rst Normal file
View File

@ -0,0 +1,11 @@
.. SPDX-License-Identifier: GPL-2.0
herd-representation
-------------------
Literal include of ``tools/memory-model/Documentation/herd-representation.txt``.
------------------------------------------------------------------
.. kernel-include:: tools/memory-model/Documentation/herd-representation.txt
:literal:

21
Documentation/dev-tools/lkmm/docs/index.rst Normal file
View File

@ -0,0 +1,21 @@
.. SPDX-License-Identifier: GPL-2.0
Documentation
=============
.. toctree::
:maxdepth: 1
readme
simple
ordering
litmus-tests
locking
recipes
control-dependencies
access-marking
cheatsheet
explanation
herd-representation
glossary
references

11
Documentation/dev-tools/lkmm/docs/litmus-tests.rst Normal file
View File

@ -0,0 +1,11 @@
.. SPDX-License-Identifier: GPL-2.0
Litmus Tests
------------
Literal include of ``tools/memory-model/Documentation/litmus-tests.txt``.
------------------------------------------------------------------
.. kernel-include:: tools/memory-model/Documentation/litmus-tests.txt
:literal:

11
Documentation/dev-tools/lkmm/docs/locking.rst Normal file
View File

@ -0,0 +1,11 @@
.. SPDX-License-Identifier: GPL-2.0
Locking
-------
Literal include of ``tools/memory-model/Documentation/locking.txt``.
------------------------------------------------------------------
.. kernel-include:: tools/memory-model/Documentation/locking.txt
:literal:

11
Documentation/dev-tools/lkmm/docs/ordering.rst Normal file
View File

@ -0,0 +1,11 @@
.. SPDX-License-Identifier: GPL-2.0
Ordering
--------
Literal include of ``tools/memory-model/Documentation/ordering.txt``.
------------------------------------------------------------------
.. kernel-include:: tools/memory-model/Documentation/ordering.txt
:literal:

11
Documentation/dev-tools/lkmm/docs/readme.rst Normal file
View File

@ -0,0 +1,11 @@
.. SPDX-License-Identifier: GPL-2.0
README (for LKMM Documentation)
-------------------------------
Literal include of ``tools/memory-model/Documentation/README``.
------------------------------------------------------------------
.. kernel-include:: tools/memory-model/Documentation/README
:literal:

11
Documentation/dev-tools/lkmm/docs/recipes.rst Normal file
View File

@ -0,0 +1,11 @@
.. SPDX-License-Identifier: GPL-2.0
Recipes
-------
Literal include of ``tools/memory-model/Documentation/recipes.txt``.
------------------------------------------------------------------
.. kernel-include:: tools/memory-model/Documentation/recipes.txt
:literal:

11
Documentation/dev-tools/lkmm/docs/references.rst Normal file
View File

@ -0,0 +1,11 @@
.. SPDX-License-Identifier: GPL-2.0
References
----------
Literal include of ``tools/memory-model/Documentation/references.txt``.
------------------------------------------------------------------
.. kernel-include:: tools/memory-model/Documentation/references.txt
:literal:

11
Documentation/dev-tools/lkmm/docs/simple.rst Normal file
View File

@ -0,0 +1,11 @@
.. SPDX-License-Identifier: GPL-2.0
Simple
------
Literal include of ``tools/memory-model/Documentation/simple.txt``.
------------------------------------------------------------------
.. kernel-include:: tools/memory-model/Documentation/simple.txt
:literal:

15
Documentation/dev-tools/lkmm/index.rst Normal file
View File

@ -0,0 +1,15 @@
.. SPDX-License-Identifier: GPL-2.0
============================================
Linux Kernel Memory Consistency Model (LKMM)
============================================
This section literally renders documents under ``tools/memory-model/``
and ``tools/memory-model/Documentation/``, which are maintained in
the *pure* plain text form.
.. toctree::
:maxdepth: 2
readme
docs/index

11
Documentation/dev-tools/lkmm/readme.rst Normal file
View File

@ -0,0 +1,11 @@
.. SPDX-License-Identifier: GPL-2.0
README (for LKMM)
=================
Literal include of ``tools/memory-model/README``.
------------------------------------------------------------
.. kernel-include:: tools/memory-model/README
:literal:

2
Documentation/devicetree/bindings/submitting-patches.rst
View File

@ -66,7 +66,7 @@ I. For patch submitters
any DTS patches, regardless whether using existing or new bindings, should
be placed at the end of patchset to indicate no dependency of drivers on
the DTS. DTS will be anyway applied through separate tree or branch, so
different order would indicate the serie is non-bisectable.
different order would indicate the series is non-bisectable.
If a driver subsystem maintainer prefers to apply entire set, instead of
their relevant portion of patchset, please split the DTS patches into

2
Documentation/driver-api/cxl/devices/device-types.rst
View File

@ -22,7 +22,7 @@ The basic interaction protocol, similar to PCIe configuration mechanisms.
Typically used for initialization, configuration, and I/O access for anything
other than memory (CXL.mem) or cache (CXL.cache) operations.
The Linux CXL driver exposes access to .io functionalty via the various sysfs
The Linux CXL driver exposes access to .io functionality via the various sysfs
interfaces and /dev/cxl/ devices (which exposes direct access to device
mailboxes).

2
Documentation/driver-api/cxl/platform/example-configurations/one-dev-per-hb.rst
View File

@ -10,7 +10,7 @@ has a single CXL memory expander with a 4GB of memory.
Things to note:
* Cross-Bridge interleave is not being used.
* The expanders are in two separate but adjascent memory regions.
* The expanders are in two separate but adjacent memory regions.
* This CEDT/SRAT describes one node per device
* The expanders have the same performance and will be in the same memory tier.

4
Documentation/driver-api/device-io.rst
View File

@ -16,7 +16,7 @@ Bus-Independent Device Accesses
Introduction
============
Linux provides an API which abstracts performing IO across all busses
Linux provides an API which abstracts performing IO across all buses
and devices, allowing device drivers to be written independently of bus
type.
@ -71,7 +71,7 @@ can be compiler optimised, you can use __readb() and friends to
indicate the relaxed ordering. Use this with care.
While the basic functions are defined to be synchronous with respect to
each other and ordered with respect to each other the busses the devices
each other and ordered with respect to each other the buses the devices
sit on may themselves have asynchronicity. In particular many authors
are burned by the fact that PCI bus writes are posted asynchronously. A
driver author must issue a read from the same device to ensure that

2
Documentation/driver-api/driver-model/overview.rst
View File

@ -22,7 +22,7 @@ uniformity across the different bus types.
The current driver model provides a common, uniform data model for describing
a bus and the devices that can appear under the bus. The unified bus
model includes a set of common attributes which all busses carry, and a set
model includes a set of common attributes which all buses carry, and a set
of common callbacks, such as device discovery during bus probing, bus
shutdown, bus power management, etc.

2
Documentation/driver-api/driver-model/platform.rst
View File

@ -4,7 +4,7 @@ Platform Devices and Drivers
See <linux/platform_device.h> for the driver model interface to the
platform bus: platform_device, and platform_driver. This pseudo-bus
is used to connect devices on busses with minimal infrastructure,
is used to connect devices on buses with minimal infrastructure,
like those used to integrate peripherals on many system-on-chip
processors, or some "legacy" PC interconnects; as opposed to large
formally specified ones like PCI or USB.

6
Documentation/driver-api/eisa.rst
View File

@ -8,9 +8,9 @@ This document groups random notes about porting EISA drivers to the
new EISA/sysfs API.
Starting from version 2.5.59, the EISA bus is almost given the same
status as other much more mainstream busses such as PCI or USB. This
status as other much more mainstream buses such as PCI or USB. This
has been possible through sysfs, which defines a nice enough set of
abstractions to manage busses, devices and drivers.
abstractions to manage buses, devices and drivers.
Although the new API is quite simple to use, converting existing
drivers to the new infrastructure is not an easy task (mostly because
@ -205,7 +205,7 @@ Random notes
Converting an EISA driver to the new API mostly involves *deleting*
code (since probing is now in the core EISA code). Unfortunately, most
drivers share their probing routine between ISA, and EISA. Special
care must be taken when ripping out the EISA code, so other busses
care must be taken when ripping out the EISA code, so other buses
won't suffer from these surgical strikes...
You *must not* expect any EISA device to be detected when returning

4
Documentation/driver-api/i3c/protocol.rst
View File

@ -165,8 +165,8 @@ The first thing attached to an HDR command is the HDR mode. There are currently
for more details):
* HDR-DDR: Double Data Rate mode
* HDR-TSP: Ternary Symbol Pure. Only usable on busses with no I2C devices
* HDR-TSL: Ternary Symbol Legacy. Usable on busses with I2C devices
* HDR-TSP: Ternary Symbol Pure. Only usable on buses with no I2C devices
* HDR-TSL: Ternary Symbol Legacy. Usable on buses with I2C devices
When sending an HDR command, the whole bus has to enter HDR mode, which is done
using a broadcast CCC command.

4
Documentation/driver-api/ipmi.rst
View File

@ -617,12 +617,12 @@ Note that the address you give here is the I2C address, not the IPMI
address. So if you want your MC address to be 0x60, you put 0x30
here. See the I2C driver info for more details.
Command bridging to other IPMB busses through this interface does not
Command bridging to other IPMB buses through this interface does not
work. The receive message queue is not implemented, by design. There
is only one receive message queue on a BMC, and that is meant for the
host drivers, not something on the IPMB bus.
A BMC may have multiple IPMB busses, which bus your device sits on
A BMC may have multiple IPMB buses, which bus your device sits on
depends on how the system is wired. You can fetch the channels with
"ipmitool channel info <n>" where <n> is the channel, with the
channels being 0-7 and try the IPMB channels.

4
Documentation/driver-api/media/tx-rx.rst
View File

@ -12,7 +12,7 @@ CSI-2 receiver in an SoC.
Bus types
---------
The following busses are the most common. This section discusses these two only.
The following buses are the most common. This section discusses these two only.
MIPI CSI-2
^^^^^^^^^^
@ -36,7 +36,7 @@ Transmitter drivers
Transmitter drivers generally need to provide the receiver drivers with the
configuration of the transmitter. What is required depends on the type of the
bus. These are common for both busses.
bus. These are common for both buses.
Media bus pixel code
^^^^^^^^^^^^^^^^^^^^

2
Documentation/driver-api/nvdimm/nvdimm.rst
View File

@ -230,7 +230,7 @@ LIBNVDIMM/LIBNDCTL: Bus
A bus has a 1:1 relationship with an NFIT. The current expectation for
ACPI based systems is that there is only ever one platform-global NFIT.
That said, it is trivial to register multiple NFITs, the specification
does not preclude it. The infrastructure supports multiple busses and
does not preclude it. The infrastructure supports multiple buses and
we use this capability to test multiple NFIT configurations in the unit
test.

10
Documentation/driver-api/pin-control.rst
View File

@ -1202,22 +1202,24 @@ default state like this:
{
/* Allocate a state holder named "foo" etc */
struct foo_state *foo = ...;
int ret;
foo->p = devm_pinctrl_get(&device);
if (IS_ERR(foo->p)) {
/* FIXME: clean up "foo" here */
return PTR_ERR(foo->p);
ret = PTR_ERR(foo->p);
foo->p = NULL;
return ret;
}
foo->s = pinctrl_lookup_state(foo->p, PINCTRL_STATE_DEFAULT);
if (IS_ERR(foo->s)) {
/* FIXME: clean up "foo" here */
devm_pinctrl_put(foo->p);
return PTR_ERR(foo->s);
}
ret = pinctrl_select_state(foo->p, foo->s);
if (ret < 0) {
/* FIXME: clean up "foo" here */
devm_pinctrl_put(foo->p);
return ret;
}
}

4
Documentation/driver-api/pm/devices.rst
View File

@ -255,7 +255,7 @@ get registered: a child can never be registered, probed or resumed before
its parent; and can't be removed or suspended after that parent.
The policy is that the device hierarchy should match hardware bus topology.
[Or at least the control bus, for devices which use multiple busses.]
[Or at least the control bus, for devices which use multiple buses.]
In particular, this means that a device registration may fail if the parent of
the device is suspending (i.e. has been chosen by the PM core as the next
device to suspend) or has already suspended, as well as after all of the other
@ -493,7 +493,7 @@ states, like S3).
Drivers must also be prepared to notice that the device has been removed
while the system was powered down, whenever that's physically possible.
PCMCIA, MMC, USB, Firewire, SCSI, and even IDE are common examples of busses
PCMCIA, MMC, USB, Firewire, SCSI, and even IDE are common examples of buses
where common Linux platforms will see such removal. Details of how drivers
will notice and handle such removals are currently bus-specific, and often
involve a separate thread.

4
Documentation/driver-api/scsi.rst
View File

@ -18,7 +18,7 @@ optical drives, test equipment, and medical devices) to a host computer.
Although the old parallel (fast/wide/ultra) SCSI bus has largely fallen
out of use, the SCSI command set is more widely used than ever to
communicate with devices over a number of different busses.
communicate with devices over a number of different buses.
The `SCSI protocol <https://www.t10.org/scsi-3.htm>`__ is a big-endian
peer-to-peer packet based protocol. SCSI commands are 6, 10, 12, or 16
@ -286,7 +286,7 @@ Parallel SCSI (SPI) transport class
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The file drivers/scsi/scsi_transport_spi.c defines transport
attributes for traditional (fast/wide/ultra) SCSI busses.
attributes for traditional (fast/wide/ultra) SCSI buses.
.. kernel-doc:: drivers/scsi/scsi_transport_spi.c
:export:

2
Documentation/driver-api/spi.rst
View File

@ -13,7 +13,7 @@ additional chipselect line is usually active-low (nCS); four signals are
normally used for each peripheral, plus sometimes an interrupt.
The SPI bus facilities listed here provide a generalized interface to
declare SPI busses and devices, manage them according to the standard
declare SPI buses and devices, manage them according to the standard
Linux driver model, and perform input/output operations. At this time,
only "master" side interfaces are supported, where Linux talks to SPI
peripherals and does not implement such a peripheral itself. (Interfaces

14
Documentation/driver-api/thermal/exynos_thermal_emulation.rst
View File

@ -28,13 +28,13 @@ changed into it.
delay of changing temperature. However, this node only uses same delay
of real sensing time, 938us.)
Exynos emulation mode requires synchronous of value changing and
enabling. It means when you want to update the any value of delay or
next temperature, then you have to enable emulation mode at the same
time. (Or you have to keep the mode enabling.) If you don't, it fails to
change the value to updated one and just use last succeessful value
repeatedly. That's why this node gives users the right to change
termerpature only. Just one interface makes it more simply to use.
Exynos emulation mode requires that value changes and enabling are performed
synchronously. This means that when you want to update any value, such as the
delay or the next temperature, you must enable emulation mode at the same
time (or keep the mode enabled). If you do not, the value will fail to update
and the last successful value will continue to be used. For this reason,
this node only allows users to change the temperature. Providing a single
interface makes it simpler to use.
Disabling emulation mode only requires writing value 0 to sysfs node.

2
Documentation/driver-api/usb/hotplug.rst
View File

@ -5,7 +5,7 @@ Linux Hotplugging
=================
In hotpluggable busses like USB (and Cardbus PCI), end-users plug devices
In hotpluggable buses like USB (and Cardbus PCI), end-users plug devices
into the bus with power on. In most cases, users expect the devices to become
immediately usable. That means the system must do many things, including:

1
Documentation/driver-api/usb/index.rst
View File

@ -3,6 +3,7 @@ Linux USB API
=============
.. toctree::
:maxdepth: 1
usb
gadget

4
Documentation/driver-api/usb/usb.rst
View File

@ -13,7 +13,7 @@ structure, with the host as the root (the system's master), hubs as
interior nodes, and peripherals as leaves (and slaves). Modern PCs
support several such trees of USB devices, usually
a few USB 3.0 (5 GBit/s) or USB 3.1 (10 GBit/s) and some legacy
USB 2.0 (480 MBit/s) busses just in case.
USB 2.0 (480 MBit/s) buses just in case.
That master/slave asymmetry was designed-in for a number of reasons, one
being ease of use. It is not physically possible to mistake upstream and
@ -42,7 +42,7 @@ two. One is intended for *general-purpose* drivers (exposed through
driver frameworks), and the other is for drivers that are *part of the
core*. Such core drivers include the *hub* driver (which manages trees
of USB devices) and several different kinds of *host controller
drivers*, which control individual busses.
drivers*, which control individual buses.
The device model seen by USB drivers is relatively complex.

42
Documentation/fb/fbcon.rst
View File

@ -39,11 +39,13 @@ Also, you will need to select at least one compiled-in font, but if
you don't do anything, the kernel configuration tool will select one for you,
usually an 8x16 font.
GOTCHA: A common bug report is enabling the framebuffer without enabling the
framebuffer console. Depending on the driver, you may get a blanked or
garbled display, but the system still boots to completion. If you are
fortunate to have a driver that does not alter the graphics chip, then you
will still get a VGA console.
.. admonition:: GOTCHA
A common bug report is enabling the framebuffer without enabling the
framebuffer console. Depending on the driver, you may get a blanked or
garbled display, but the system still boots to completion. If you are
fortunate to have a driver that does not alter the graphics chip, then you
will still get a VGA console.
B. Loading
==========
@ -74,6 +76,7 @@ Possible scenarios:
over the console.
C. Boot options
===============
The framebuffer console has several, largely unknown, boot options
that can change its behavior.
@ -116,9 +119,10 @@ C. Boot options
outside the given range will still be controlled by the standard
console driver.
NOTE: For x86 machines, the standard console is the VGA console which
is typically located on the same video card. Thus, the consoles that
are controlled by the VGA console will be garbled.
.. note::
For x86 machines, the standard console is the VGA console which
is typically located on the same video card. Thus, the consoles that
are controlled by the VGA console will be garbled.
4. fbcon=rotate:<n>
@ -140,10 +144,11 @@ C. Boot options
Console rotation will only become available if Framebuffer Console
Rotation support is compiled in your kernel.
NOTE: This is purely console rotation. Any other applications that
use the framebuffer will remain at their 'normal' orientation.
Actually, the underlying fb driver is totally ignorant of console
rotation.
.. note::
This is purely console rotation. Any other applications that
use the framebuffer will remain at their 'normal' orientation.
Actually, the underlying fb driver is totally ignorant of console
rotation.
5. fbcon=margin:<color>
@ -172,7 +177,8 @@ C. Boot options
The value 'n' overrides the number of bootup logos. 0 disables the
logo, and -1 gives the default which is the number of online CPUs.
C. Attaching, Detaching and Unloading
D. Attaching, Detaching and Unloading
=====================================
Before going on to how to attach, detach and unload the framebuffer console, an
illustration of the dependencies may help.
@ -249,11 +255,11 @@ restored properly. The following is one of the several methods that you can do:
echo 1 > /sys/class/vtconsole/vtcon1/bind
8. Once fbcon is unbound, all drivers registered to the system will also
become unbound. This means that fbcon and individual framebuffer drivers
can be unloaded or reloaded at will. Reloading the drivers or fbcon will
automatically bind the console, fbcon and the drivers together. Unloading
all the drivers without unloading fbcon will make it impossible for the
console to bind fbcon.
become unbound. This means that fbcon and individual framebuffer drivers
can be unloaded or reloaded at will. Reloading the drivers or fbcon will
automatically bind the console, fbcon and the drivers together. Unloading
all the drivers without unloading fbcon will make it impossible for the
console to bind fbcon.
Notes for vesafb users:
=======================

4
Documentation/features/core/eBPF-JIT/arch-support.txt
View File

@ -7,7 +7,7 @@
| arch |status|
-----------------------
| alpha: | TODO |
| arc: | TODO |
| arc: | ok |
| arm: | ok |
| arm64: | ok |
| csky: | TODO |
@ -18,7 +18,7 @@
| mips: | ok |
| nios2: | TODO |
| openrisc: | TODO |
| parisc: | TODO |
| parisc: | ok |
| powerpc: | ok |
| riscv: | ok |
| s390: | ok |

2
Documentation/features/core/mseal_sys_mappings/arch-support.txt
View File

@ -20,7 +20,7 @@
| openrisc: | N/A |
| parisc: | TODO |
| powerpc: | TODO |
| riscv: | TODO |
| riscv: | ok |
| s390: | ok |
| sh: | N/A |
| sparc: | TODO |

2
Documentation/features/core/thread-info-in-task/arch-support.txt
View File

@ -24,7 +24,7 @@
| s390: | ok |
| sh: | TODO |
| sparc: | TODO |
| um: | TODO |
| um: | ok |
| x86: | ok |
| xtensa: | TODO |
-----------------------

2
Documentation/features/core/tracehook/arch-support.txt
View File

@ -24,7 +24,7 @@
| s390: | ok |
| sh: | ok |
| sparc: | ok |
| um: | TODO |
| um: | ok |
| x86: | ok |
| xtensa: | ok |
-----------------------

2
Documentation/features/perf/kprobes-event/arch-support.txt
View File

@ -17,7 +17,7 @@
| microblaze: | TODO |
| mips: | ok |
| nios2: | TODO |
| openrisc: | TODO |
| openrisc: | ok |
| parisc: | ok |
| powerpc: | ok |
| riscv: | ok |

2
Documentation/features/time/clockevents/arch-support.txt
View File

@ -18,7 +18,7 @@
| mips: | ok |
| nios2: | ok |
| openrisc: | ok |
| parisc: | TODO |
| parisc: | ok |
| powerpc: | ok |
| riscv: | ok |
| s390: | ok |

2
Documentation/filesystems/erofs.rst
View File

@ -116,7 +116,7 @@ cache_strategy=%s Select a strategy for cached decompression from now on:
cluster for further reading. It still does
in-place I/O decompression for the rest
compressed physical clusters;
readaround Cache the both ends of incomplete compressed
readaround Cache both ends of incomplete compressed
physical clusters for further reading.
It still does in-place I/O decompression
for the rest compressed physical clusters.

6
Documentation/filesystems/ext4/atomic_writes.rst
View File

@ -14,7 +14,7 @@ I/O) on regular files with extents, provided the underlying storage device
supports hardware atomic writes. This is supported in the following two ways:
1. **Single-fsblock Atomic Writes**:
EXT4's supports atomic write operations with a single filesystem block since
EXT4 supports atomic write operations with a single filesystem block since
v6.13. In this the atomic write unit minimum and maximum sizes are both set
to filesystem blocksize.
e.g. doing atomic write of 16KB with 16KB filesystem blocksize on 64KB
@ -50,7 +50,7 @@ Multi-fsblock Implementation Details
The bigalloc feature changes ext4 to allocate in units of multiple filesystem
blocks, also known as clusters. With bigalloc each bit within block bitmap
represents cluster (power of 2 number of blocks) rather than individual
represents a cluster (power of 2 number of blocks) rather than individual
filesystem blocks.
EXT4 supports multi-fsblock atomic writes with bigalloc, subject to the
following constraints. The minimum atomic write size is the larger of the fs
@ -189,7 +189,7 @@ The write must be aligned to the filesystem's block size and not exceed the
filesystem's maximum atomic write unit size.
See ``generic_atomic_write_valid()`` for more details.
``statx()`` system call with ``STATX_WRITE_ATOMIC`` flag can provides following
``statx()`` system call with ``STATX_WRITE_ATOMIC`` flag can provide following
details:
* ``stx_atomic_write_unit_min``: Minimum size of an atomic write request.

2
Documentation/filesystems/gfs2-glocks.rst
View File

@ -105,7 +105,7 @@ go_unlocked Yes No
Operations must not drop either the bit lock or the spinlock
if its held on entry. go_dump and do_demote_ok must never block.
Note that go_dump will only be called if the glock's state
indicates that it is caching uptodate data.
indicates that it is caching up-to-date data.
Glock locking order within GFS2:

2
Documentation/filesystems/hpfs.rst
View File

@ -65,7 +65,7 @@ are case sensitive, so for example when you create a file FOO, you can use
'cat FOO', 'cat Foo', 'cat foo' or 'cat F*' but not 'cat f*'. Note, that you
also won't be able to compile linux kernel (and maybe other things) on HPFS
because kernel creates different files with names like bootsect.S and
bootsect.s. When searching for file thats name has characters >= 128, codepages
bootsect.s. When searching for file whose name has characters >= 128, codepages
are used - see below.
OS/2 ignores dots and spaces at the end of file name, so this driver does as
well. If you create 'a. ...', the file 'a' will be created, but you can still

2
Documentation/filesystems/iomap/operations.rst
View File

@ -321,7 +321,7 @@ The fields are as follows:
- ``writeback_submit``: Submit the previous built writeback context.
Block based file systems should use the iomap_ioend_writeback_submit
helper, other file system can implement their own.
File systems can optionall to hook into writeback bio submission.
File systems can optionally hook into writeback bio submission.
This might include pre-write space accounting updates, or installing
a custom ``->bi_end_io`` function for internal purposes, such as
deferring the ioend completion to a workqueue to run metadata update

20
Documentation/filesystems/ocfs2-online-filecheck.rst
View File

@ -58,33 +58,33 @@ inode, fixing inode and setting the size of result record history.
# echo "<inode>" > /sys/fs/ocfs2/<devname>/filecheck/check
# cat /sys/fs/ocfs2/<devname>/filecheck/check
The output is like this::
The output is like this::
INO DONE ERROR
39502 1 GENERATION
<INO> lists the inode numbers.
<DONE> indicates whether the operation has been finished.
<ERROR> says what kind of errors was found. For the detailed error numbers,
please refer to the file linux/fs/ocfs2/filecheck.h.
<INO> lists the inode numbers.
<DONE> indicates whether the operation has been finished.
<ERROR> says what kind of errors was found. For the detailed error numbers,
please refer to the file linux/fs/ocfs2/filecheck.h.
2. If you determine to fix this inode, do::
# echo "<inode>" > /sys/fs/ocfs2/<devname>/filecheck/fix
# cat /sys/fs/ocfs2/<devname>/filecheck/fix
The output is like this:::
The output is like this::
INO DONE ERROR
39502 1 SUCCESS
This time, the <ERROR> column indicates whether this fix is successful or not.
This time, the <ERROR> column indicates whether this fix is successful or not.
3. The record cache is used to store the history of check/fix results. It's
default size is 10, and can be adjust between the range of 10 ~ 100. You can
adjust the size like this::
default size is 10, and can be adjust between the range of 10 ~ 100. You can
adjust the size like this::
# echo "<size>" > /sys/fs/ocfs2/<devname>/filecheck/set
# echo "<size>" > /sys/fs/ocfs2/<devname>/filecheck/set
Fixing stuff
============

Some files were not shown because too many files have changed in this diff Show More