Merge tag 'docs-7.0' of git://git.kernel.org/pub/scm/linux/kernel/git/docs/linux

Pull documentation updates from Jonathan Corbet: "A slightly calmer cycle for docs this time around, though there is still a fair amount going on, including: - Some signs of life on the long-moribund Japanese translation - Documentation on policies around the use of generative tools for patch submissions, and a separate document intended for consumption by generative tools - The completion of the move of the documentation tools to tools/docs. For now we're leaving a /scripts/kernel-doc symlink behind to avoid breaking scripts - Ongoing build-system work includes the incorporation of documentation in Python code, better support for documenting variables, and lots of improvements and fixes - Automatic linking of man-page references -- cat(1), for example -- to the online pages in the HTML build ...and the usual array of typo fixes and such" * tag 'docs-7.0' of git://git.kernel.org/pub/scm/linux/kernel/git/docs/linux: (107 commits) doc: development-process: add notice on testing tools: sphinx-build-wrapper: improve its help message docs: sphinx-build-wrapper: allow -v override -q docs: kdoc: Fix pdfdocs build for tools docs: ja_JP: process: translate 'Obtain a current source tree' docs: fix 're-use' -> 'reuse' in documentation docs: ioctl-number: fix a typo in ioctl-number.rst docs: filesystems: ensure proc pid substitutable is complete docs: automarkup.py: Skip common English words as C identifiers Documentation: use a source-read extension for the index link boilerplate docs: parse_features: make documentation more consistent docs: add parse_features module documentation docs: jobserver: do some documentation improvements docs: add jobserver module documentation docs: kabi: helpers: add documentation for each "enum" value docs: kabi: helpers: add helper for debug bits 7 and 8 docs: kabi: system_symbols: end docstring phrases with a dot docs: python: abi_regex: do some improvements at documentation docs: python: abi_parser: do some improvements at documentation docs: add kabi modules documentation ...
2026-03-21 23:16:50 +08:00 · 2026-02-09 20:53:18 -08:00
parent 0c61526621 0a83293322
commit 72c395024d
227 changed files with 1812 additions and 4384 deletions
--- a/8
+++ b/8
@@ -695,7 +695,7 @@ S: USA
 N: Chih-Jen Chang
 E: chihjenc@scf.usc.edu
 E: chihjen@iis.sinica.edu.tw
-D: IGMP(Internet Group Management Protocol) version 2
+D: IGMP (Internet Group Management Protocol) version 2
 S: 3F, 65 Tajen street
 S: Tamsui town, Taipei county,
 S: Taiwan 251
@@ -1997,7 +1997,7 @@ E: bkaindl@netway.at
 E: edv@bartelt.via.at
 D: Author of a menu based configuration tool, kmenu, which
 D: is the predecessor of 'make menuconfig' and 'make xconfig'.
-D: digiboard driver update(modularisation work and 2.1.x upd)
+D: digiboard driver update (modularisation work and 2.1.x upd)
 S: Tallak 95
 S: 8103 Rein
 S: Austria
@@ -3613,7 +3613,7 @@ S: Finland
 N: Deepak Saxena
 E: dsaxena@plexity.net
 D: I2O kernel layer (config, block, core, pci, net). I2O disk support for LILO
-D: XScale(IOP, IXP) porting and other random ARM bits
+D: XScale (IOP, IXP) porting and other random ARM bits
 S: Portland, OR

 N: Eric Schenk
@@ -3990,7 +3990,7 @@ S: D-50968 Köln

 N: Tsu-Sheng Tsao
 E: tsusheng@scf.usc.edu
-D: IGMP(Internet Group Management Protocol) version 2
+D: IGMP (Internet Group Management Protocol) version 2
 S: 2F 14 ALY 31 LN 166 SEC 1 SHIH-PEI RD
 S: Taipei
 S: Taiwan 112
--- a/Documentation/ABI/testing/pstore
+++ b/Documentation/ABI/testing/pstore
@@ -26,7 +26,7 @@ Description:	Generic interface to platform dependent persistent storage.

 		Once the information in a file has been read, removing
 		the file will signal to the underlying persistent storage
-		device that it can reclaim the space for later re-use::
+		device that it can reclaim the space for later reuse::

 		    $ rm /sys/fs/pstore/dmesg-erst-1

--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -98,7 +98,8 @@ dochelp:
 	@echo  '  cleandocs       - clean all generated files'
 	@echo
 	@echo  '  make SPHINXDIRS="s1 s2" [target] Generate only docs of folder s1, s2'
-	@echo  '  top level values for SPHINXDIRS are: $(_SPHINXDIRS)'
+	@echo  '  top level values for SPHINXDIRS are:'
+	@echo  '$(_SPHINXDIRS)' | fmt -s -w 75 -g 75 | sed 's/^/    /'
 	@echo  '  you may also use a subdirectory like SPHINXDIRS=userspace-api/media,'
 	@echo  '  provided that there is an index.rst file at the subdirectory.'
 	@echo
--- a/Documentation/RCU/index.rst
+++ b/Documentation/RCU/index.rst
@@ -28,10 +28,3 @@ RCU Handbook
   Design/Expedited-Grace-Periods/Expedited-Grace-Periods
   Design/Requirements/Requirements
   Design/Data-Structures/Data-Structures
-
-.. only:: subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/accel/index.rst
+++ b/Documentation/accel/index.rst
@@ -11,10 +11,3 @@ Compute Accelerators
   amdxdna/index
   qaic/index
   rocket/index
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/admin-guide/README.rst
+++ b/Documentation/admin-guide/README.rst
@@ -53,7 +53,7 @@ Documentation
   these typically contain kernel-specific installation notes for some
   drivers for example. Please read the
   :ref:`Documentation/process/changes.rst <changes>` file, as it
-   contains information about the problems, which may result by upgrading
+   contains information about the problems which may result from upgrading
   your kernel.

 Installing the kernel source
--- a/Documentation/admin-guide/aoe/index.rst
+++ b/Documentation/admin-guide/aoe/index.rst
@@ -8,10 +8,3 @@ ATA over Ethernet (AoE)
    aoe
    todo
    examples
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/admin-guide/auxdisplay/index.rst
+++ b/Documentation/admin-guide/auxdisplay/index.rst
@@ -7,10 +7,3 @@ Auxiliary Display Support

    ks0108.rst
    cfag12864b.rst
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/admin-guide/bug-hunting.rst
+++ b/Documentation/admin-guide/bug-hunting.rst
@@ -52,14 +52,14 @@ line is usually required to identify and handle the bug. Along this chapter,
 we'll refer to "Oops" for all kinds of stack traces that need to be analyzed.

 If the kernel is compiled with ``CONFIG_DEBUG_INFO``, you can enhance the
-quality of the stack trace by using file:`scripts/decode_stacktrace.sh`.
+quality of the stack trace by using ``scripts/decode_stacktrace.sh``.

 Modules linked in
 -----------------

 Modules that are tainted or are being loaded or unloaded are marked with
 "(...)", where the taint flags are described in
-file:`Documentation/admin-guide/tainted-kernels.rst`, "being loaded" is
+Documentation/admin-guide/tainted-kernels.rst, "being loaded" is
 annotated with "+", and "being unloaded" is annotated with "-".


@@ -235,7 +235,7 @@ Dave Miller)::
         mov        0x8(%ebp), %ebx         ! %ebx = skb->sk
         mov        0x13c(%ebx), %eax       ! %eax = inet_sk(sk)->opt

-file:`scripts/decodecode` can be used to automate most of this, depending
+``scripts/decodecode`` can be used to automate most of this, depending
 on what CPU architecture is being debugged.

 Reporting the bug
--- a/Documentation/admin-guide/cgroup-v1/hugetlb.rst
+++ b/Documentation/admin-guide/cgroup-v1/hugetlb.rst
@@ -77,7 +77,7 @@ control group and enforces the limit during page fault. Since HugeTLB
 doesn't support page reclaim, enforcing the limit at page fault time implies
 that, the application will get SIGBUS signal if it tries to fault in HugeTLB
 pages beyond its limit. Therefore the application needs to know exactly how many
-HugeTLB pages it uses before hand, and the sysadmin needs to make sure that
+HugeTLB pages it uses beforehand, and the sysadmin needs to make sure that
 there are enough available on the machine for all the users to avoid processes
 getting SIGBUS.

@@ -91,23 +91,23 @@ getting SIGBUS.
  hugetlb.<hugepagesize>.rsvd.usage_in_bytes
  hugetlb.<hugepagesize>.rsvd.failcnt

-The HugeTLB controller allows to limit the HugeTLB reservations per control
+The HugeTLB controller allows limiting the HugeTLB reservations per control
 group and enforces the controller limit at reservation time and at the fault of
 HugeTLB memory for which no reservation exists. Since reservation limits are
-enforced at reservation time (on mmap or shget), reservation limits never causes
-the application to get SIGBUS signal if the memory was reserved before hand. For
+enforced at reservation time (on mmap or shget), reservation limits never cause
+the application to get SIGBUS signal if the memory was reserved beforehand. For
 MAP_NORESERVE allocations, the reservation limit behaves the same as the fault
 limit, enforcing memory usage at fault time and causing the application to
 receive a SIGBUS if it's crossing its limit.

 Reservation limits are superior to page fault limits described above, since
 reservation limits are enforced at reservation time (on mmap or shget), and
-never causes the application to get SIGBUS signal if the memory was reserved
-before hand. This allows for easier fallback to alternatives such as
+never cause the application to get SIGBUS signal if the memory was reserved
+beforehand. This allows for easier fallback to alternatives such as
 non-HugeTLB memory for example. In the case of page fault accounting, it's very
-hard to avoid processes getting SIGBUS since the sysadmin needs precisely know
-the HugeTLB usage of all the tasks in the system and make sure there is enough
-pages to satisfy all requests. Avoiding tasks getting SIGBUS on overcommited
+hard to avoid processes getting SIGBUS since the sysadmin needs to precisely know
+the HugeTLB usage of all the tasks in the system and make sure there are enough
+pages to satisfy all requests. Avoiding tasks getting SIGBUS on overcommitted
 systems is practically impossible with page fault accounting.


--- a/Documentation/admin-guide/cgroup-v1/index.rst
+++ b/Documentation/admin-guide/cgroup-v1/index.rst
@@ -22,10 +22,3 @@ Control Groups version 1
    net_prio
    pids
    rdma
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/admin-guide/cgroup-v2.rst
+++ b/Documentation/admin-guide/cgroup-v2.rst
@@ -2816,7 +2816,7 @@ DMEM Interface Files
 HugeTLB
 -------

-The HugeTLB controller allows to limit the HugeTLB usage per control group and
+The HugeTLB controller allows limiting the HugeTLB usage per control group and
 enforces the controller limit during page fault.

 HugeTLB Interface Files
--- a/Documentation/admin-guide/cifs/index.rst
+++ b/Documentation/admin-guide/cifs/index.rst
@@ -12,10 +12,3 @@ CIFS
   todo
   changes
   authors
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/admin-guide/device-mapper/index.rst
+++ b/Documentation/admin-guide/device-mapper/index.rst
@@ -40,10 +40,3 @@ Device Mapper
    verity
    writecache
    zero
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/admin-guide/devices.rst
+++ b/Documentation/admin-guide/devices.rst
@@ -97,9 +97,12 @@ It is recommended that these links exist on all systems:
 /dev/bttv0	video0		symbolic	Backward compatibility
 /dev/radio	radio0		symbolic	Backward compatibility
 /dev/i2o*	/dev/i2o/*	symbolic	Backward compatibility
-/dev/scd?	sr?		hard		Alternate SCSI CD-ROM name
 =============== =============== =============== ===============================

+Suggested earlier ``/dev/scd?`` alternative names for ``/dev/sr?``
+CD-ROM and other optical drives (using SCSI commands) were removed
+in ``udev`` version 174 that was released in 2011.
+
 Locally defined links
 +++++++++++++++++++++

@@ -112,7 +115,6 @@ exist, they should have the following uses.
 /dev/mouse	mouse port	symbolic	Current mouse device
 /dev/tape	tape device	symbolic	Current tape device
 /dev/cdrom	CD-ROM device	symbolic	Current CD-ROM device
-/dev/cdwriter	CD-writer	symbolic	Current CD-writer device
 /dev/scanner	scanner		symbolic	Current scanner device
 /dev/modem	modem port	symbolic	Current dialout device
 /dev/root	root device	symbolic	Current root filesystem
@@ -126,8 +128,8 @@ exists, ``/dev/modem`` should point to the appropriate primary TTY device

 For SCSI devices, ``/dev/tape`` and ``/dev/cdrom`` should point to the
 *cooked* devices (``/dev/st*`` and ``/dev/sr*``, respectively), whereas
-``/dev/cdwriter`` and /dev/scanner should point to the appropriate generic
-SCSI devices (/dev/sg*).
+``/dev/scanner`` should point to the appropriate generic
+SCSI device (``/dev/sg*``).

 ``/dev/mouse`` may point to a primary serial TTY device, a hardware mouse
 device, or a socket for a mouse driver program (e.g. ``/dev/gpmdata``).
--- a/Documentation/admin-guide/devices.txt
+++ b/Documentation/admin-guide/devices.txt
@@ -389,11 +389,11 @@
 		    ...

  11 block	SCSI CD-ROM devices
-		  0 = /dev/scd0		First SCSI CD-ROM
-		  1 = /dev/scd1		Second SCSI CD-ROM
+		  0 = /dev/sr0		First SCSI CD-ROM
+		  1 = /dev/sr1		Second SCSI CD-ROM
 		    ...

-		The prefix /dev/sr (instead of /dev/scd) has been deprecated.
+		In the past the prefix /dev/scd (instead of /dev/sr) was used and even recommended.

  12 char	QIC-02 tape
 		  2 = /dev/ntpqic11	QIC-11, no rewind-on-close
--- a/Documentation/admin-guide/gpio/index.rst
+++ b/Documentation/admin-guide/gpio/index.rst
@@ -12,10 +12,3 @@ GPIO
    gpio-sim
    gpio-virtuser
    Obsolete APIs <obsolete>
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/admin-guide/index.rst
+++ b/Documentation/admin-guide/index.rst
@@ -189,10 +189,3 @@ A few hard-to-categorize and generally obsolete documents.

   ldm
   unicode
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/admin-guide/initrd.rst
+++ b/Documentation/admin-guide/initrd.rst
@@ -297,7 +297,7 @@ as follows:
  8) now the system is bootable and additional installation tasks can be
     performed

-The key role of initrd here is to re-use the configuration data during
+The key role of initrd here is to reuse the configuration data during
 normal system operation without requiring the use of a bloated "generic"
 kernel or re-compiling or re-linking the kernel.

--- a/Documentation/admin-guide/kdump/index.rst
+++ b/Documentation/admin-guide/kdump/index.rst
@@ -11,10 +11,3 @@ information.

    kdump
    vmcoreinfo
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/admin-guide/kdump/kdump.rst
+++ b/Documentation/admin-guide/kdump/kdump.rst
@@ -591,7 +591,7 @@ with /sys/kernel/config/crash_dm_crypt_keys for setup,
    cat /sys/kernel/config/crash_dm_crypt_keys/count
    2

-    # To support CPU/memory hot-plugging, re-use keys already saved to reserved
+    # To support CPU/memory hot-plugging, reuse keys already saved to reserved
    # memory
    echo true > /sys/kernel/config/crash_dm_crypt_key/reuse

--- a/Documentation/admin-guide/kernel-parameters.txt
+++ b/Documentation/admin-guide/kernel-parameters.txt
@@ -1969,6 +1969,9 @@ Kernel parameters
 				 param "no_hash_pointers" is an alias for
 				 this mode.

+			For controlling hashing dynamically at runtime,
+			use the "kernel.kptr_restrict" sysctl instead.
+
 	hashdist=	[KNL,NUMA] Large hashes allocated during boot
 			are distributed across NUMA nodes.  Defaults on
 			for 64-bit NUMA, off otherwise.
@@ -4036,6 +4039,7 @@ Kernel parameters
 					       spectre_v2_user=off [X86]
 					       srbds=off [X86,INTEL]
 					       ssbd=force-off [ARM64]
+					       tsa=off [X86,AMD]
 					       tsx_async_abort=off [X86]
 					       vmscape=off [X86]

--- a/Documentation/admin-guide/mm/nommu-mmap.rst
+++ b/Documentation/admin-guide/mm/nommu-mmap.rst
@@ -38,7 +38,7 @@ and it's also much more restricted in the latter case:

 	In the no-MMU case:

-         - If one exists, the kernel will re-use an existing mapping to the
+         - If one exists, the kernel will reuse an existing mapping to the
           same segment of the same file if that has compatible permissions,
           even if this was created by another process.

--- a/Documentation/admin-guide/sysctl/kernel.rst
+++ b/Documentation/admin-guide/sysctl/kernel.rst
@@ -591,6 +591,9 @@ if leaking kernel pointer values to unprivileged users is a concern.
 When ``kptr_restrict`` is set to 2, kernel pointers printed using
 %pK will be replaced with 0s regardless of privileges.

+For disabling these security restrictions early at boot time (and once
+for all), use the ``hash_pointers`` boot parameter instead.
+
 softlockup_sys_info & hardlockup_sys_info
 =========================================
 A comma separated list of extra system information to be dumped when
--- a/Documentation/arch/arc/index.rst
+++ b/Documentation/arch/arc/index.rst
@@ -8,10 +8,3 @@ ARC architecture
    arc

    features
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/arch/arm/index.rst
+++ b/Documentation/arch/arm/index.rst
@@ -75,11 +75,3 @@ SoC-specific documents
   sti/overview

   vfp/release-notes
-
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/arch/arm/keystone/knav-qmss.rst
+++ b/Documentation/arch/arm/keystone/knav-qmss.rst
@@ -39,7 +39,7 @@ CPPI/QMSS Low Level Driver document (docs/CPPI_QMSS_LLD_SDS.pdf) at

 	git://git.ti.com/keystone-rtos/qmss-lld.git

-k2_qmss_pdsp_acc48_k2_le_1_0_0_9.bin firmware supports upto 48 accumulator
+k2_qmss_pdsp_acc48_k2_le_1_0_0_9.bin firmware supports up to 48 accumulator
 channels. This firmware is available under ti-keystone folder of
 firmware.git at

--- a/Documentation/arch/arm/keystone/overview.rst
+++ b/Documentation/arch/arm/keystone/overview.rst
@@ -65,7 +65,7 @@ specified through DTS. Following are the DTS used:

 The device tree documentation for the keystone machines are located at

-        Documentation/devicetree/bindings/arm/keystone/keystone.txt
+        Documentation/devicetree/bindings/arm/ti/ti,keystone.yaml

 Document Author
 ---------------
--- a/Documentation/arch/arm64/arm-acpi.rst
+++ b/Documentation/arch/arm64/arm-acpi.rst
@@ -306,9 +306,9 @@ that looks like this: Name(KEY0, "value0").  An ACPI device driver would
 then retrieve the value of the property by evaluating the KEY0 object.
 However, using Name() this way has multiple problems: (1) ACPI limits
 names ("KEY0") to four characters unlike DT; (2) there is no industry
-wide registry that maintains a list of names, minimizing re-use; (3)
+wide registry that maintains a list of names, minimizing reuse; (3)
 there is also no registry for the definition of property values ("value0"),
-again making re-use difficult; and (4) how does one maintain backward
+again making reuse difficult; and (4) how does one maintain backward
 compatibility as new hardware comes out?  The _DSD method was created
 to solve precisely these sorts of problems; Linux drivers should ALWAYS
 use the _DSD method for device properties and nothing else.
--- a/Documentation/arch/arm64/index.rst
+++ b/Documentation/arch/arm64/index.rst
@@ -33,10 +33,3 @@ ARM64 Architecture
    tagged-pointers

    features
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/arch/loongarch/index.rst
+++ b/Documentation/arch/loongarch/index.rst
@@ -13,10 +13,3 @@ LoongArch Architecture
   irq-chip-model

   features
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/arch/m68k/index.rst
+++ b/Documentation/arch/m68k/index.rst
@@ -11,10 +11,3 @@ m68k Architecture
   buddha-driver

   features
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/arch/mips/index.rst
+++ b/Documentation/arch/mips/index.rst
@@ -12,10 +12,3 @@ MIPS-specific Documentation
   ingenic-tcu

   features
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/arch/openrisc/index.rst
+++ b/Documentation/arch/openrisc/index.rst
@@ -11,10 +11,3 @@ OpenRISC Architecture
   todo

   features
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/arch/parisc/index.rst
+++ b/Documentation/arch/parisc/index.rst
@@ -11,10 +11,3 @@ PA-RISC Architecture
   registers

   features
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/arch/powerpc/index.rst
+++ b/Documentation/arch/powerpc/index.rst
@@ -40,10 +40,3 @@ powerpc
    vpa-dtl

    features
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/arch/riscv/index.rst
+++ b/Documentation/arch/riscv/index.rst
@@ -16,10 +16,3 @@ RISC-V architecture
    cmodx

    features
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/arch/s390/driver-model.rst
+++ b/Documentation/arch/s390/driver-model.rst
@@ -279,7 +279,7 @@ status
       - Can be 'online' or 'offline'.
 	 Piping 'on' or 'off' sets the chpid logically online/offline.
 	 Piping 'on' to an online chpid triggers path reprobing for all devices
-	 the chpid connects to. This can be used to force the kernel to re-use
+	 the chpid connects to. This can be used to force the kernel to reuse
 	 a channel path the user knows to be online, but the machine hasn't
 	 created a machine check for.

--- a/Documentation/arch/s390/index.rst
+++ b/Documentation/arch/s390/index.rst
@@ -22,10 +22,3 @@ s390 Architecture
    text_files

    features
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/arch/x86/shstk.rst
+++ b/Documentation/arch/x86/shstk.rst
@@ -165,7 +165,7 @@ in the page fault error code.
 When a task forks a child, its shadow stack PTEs are copied and both the
 parent's and the child's shadow stack PTEs are cleared of the dirty bit.
 Upon the next shadow stack access, the resulting shadow stack page fault
-is handled by page copy/re-use.
+is handled by page copy/reuse.

 When a pthread child is created, the kernel allocates a new shadow stack
 for the new thread. New shadow stack creation behaves like mmap() with respect
--- a/Documentation/bpf/index.rst
+++ b/Documentation/bpf/index.rst
@@ -34,12 +34,5 @@ that goes into great technical depth about the BPF Architecture.
   other
   redirect

-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
-
 .. Links:
 .. _BPF and XDP Reference Guide: https://docs.cilium.io/en/latest/bpf/
--- a/Documentation/cdrom/index.rst
+++ b/Documentation/cdrom/index.rst
@@ -8,10 +8,3 @@ CD-ROM
    :maxdepth: 1

    cdrom-standard
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/conf.py
+++ b/Documentation/conf.py
@@ -13,10 +13,15 @@ from  textwrap import dedent

 import sphinx

-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-sys.path.insert(0, os.path.abspath("sphinx"))
+# Location of Documentation/ directory
+kern_doc_dir = os.path.dirname(os.path.abspath(__file__))
+
+# Add location of Sphinx extensions
+sys.path.insert(0, os.path.join(kern_doc_dir, "sphinx"))
+
+# Allow sphinx.ext.autodoc to document files at tools and scripts
+sys.path.append(os.path.join(kern_doc_dir, "..", "tools"))
+sys.path.append(os.path.join(kern_doc_dir, "..", "scripts"))

 # Minimal supported version
 needs_sphinx = "3.4.3"
@@ -32,15 +37,12 @@ else:
    # Include patterns that don't contain directory names, in glob format
    include_patterns = ["**.rst"]

-# Location of Documentation/ directory
-doctree = os.path.abspath(".")
-
 # Exclude of patterns that don't contain directory names, in glob format.
 exclude_patterns = []

 # List of patterns that contain directory names in glob format.
 dyn_include_patterns = []
-dyn_exclude_patterns = ["output"]
+dyn_exclude_patterns = ["output", "sphinx-includes"]

 # Currently, only netlink/specs has a parser for yaml.
 # Prefer using include patterns if available, as it is faster
@@ -51,6 +53,9 @@ else:
    dyn_exclude_patterns.append("devicetree/bindings/**.yaml")
    dyn_exclude_patterns.append("core-api/kho/bindings/**.yaml")

+# Link to man pages
+manpages_url = 'https://man7.org/linux/man-pages/man{section}/{page}.{section}.html'
+
 # Properly handle directory patterns and LaTeX docs
 # -------------------------------------------------

@@ -70,7 +75,7 @@ def config_init(app, config):
    # setup include_patterns dynamically
    if has_include_patterns:
        for p in dyn_include_patterns:
-            full = os.path.join(doctree, p)
+            full = os.path.join(kern_doc_dir, p)

            rel_path = os.path.relpath(full, start=app.srcdir)
            if rel_path.startswith("../"):
@@ -80,7 +85,7 @@ def config_init(app, config):

    # setup exclude_patterns dynamically
    for p in dyn_exclude_patterns:
-        full = os.path.join(doctree, p)
+        full = os.path.join(kern_doc_dir, p)

        rel_path = os.path.relpath(full, start=app.srcdir)
        if rel_path.startswith("../"):
@@ -92,7 +97,7 @@ def config_init(app, config):
    # of the app.srcdir. Add them here

    # Handle the case where SPHINXDIRS is used
-    if not os.path.samefile(doctree, app.srcdir):
+    if not os.path.samefile(kern_doc_dir, app.srcdir):
        # Add a tag to mark that the build is actually a subproject
        tags.add("subproject")

@@ -151,6 +156,7 @@ extensions = [
    "maintainers_include",
    "parser_yaml",
    "rstFlatTable",
+    "sphinx.ext.autodoc",
    "sphinx.ext.autosectionlabel",
    "sphinx.ext.ifconfig",
    "translations",
@@ -579,13 +585,32 @@ pdf_documents = [
    ("kernel-documentation", "Kernel", "Kernel", "J. Random Bozo"),
 ]

-# kernel-doc extension configuration for running Sphinx directly (e.g. by Read
-# the Docs). In a normal build, these are supplied from the Makefile via command
-# line arguments.
-kerneldoc_bin = "../scripts/kernel-doc.py"
 kerneldoc_srctree = ".."

+# Add index link at the end of the root document for SPHINXDIRS builds.
+def add_subproject_index(app, docname, content):
+    # Only care about root documents
+    if docname != master_doc:
+        return
+
+    # Add the index link at the root of translations, but not at the root of
+    # individual translations. They have their own language specific links.
+    rel = os.path.relpath(app.srcdir, start=kern_doc_dir).split('/')
+    if rel[0] == 'translations' and len(rel) > 1:
+        return
+
+    # Only add the link for SPHINXDIRS HTML builds
+    if not app.builder.tags.has('subproject') or not app.builder.tags.has('html'):
+        return
+
+    # The include directive needs a relative path from the srcdir
+    rel = os.path.relpath(os.path.join(kern_doc_dir, 'sphinx-includes/subproject-index.rst'),
+                          start=app.srcdir)
+
+    content[0] += f'\n.. include:: {rel}\n\n'
+
 def setup(app):
    """Patterns need to be updated at init time on older Sphinx versions"""

    app.connect('config-inited', config_init)
+    app.connect('source-read', add_subproject_index)
--- a/Documentation/core-api/index.rst
+++ b/Documentation/core-api/index.rst
@@ -141,10 +141,3 @@ Documents that don't fit elsewhere or which have yet to be categorized.
   librs
   liveupdate
   netlink
-
-.. only:: subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/core-api/kho/index.rst
+++ b/Documentation/core-api/kho/index.rst
@@ -9,5 +9,3 @@ Kexec Handover Subsystem

   concepts
   fdt
-
-.. only::  subproject and html
--- a/Documentation/core-api/kobject.rst
+++ b/Documentation/core-api/kobject.rst
@@ -78,7 +78,7 @@ just a matter of using the kobj member.  Code that works with kobjects will
 often have the opposite problem, however: given a struct kobject pointer,
 what is the pointer to the containing structure?  You must avoid tricks
 (such as assuming that the kobject is at the beginning of the structure)
-and, instead, use the container_of() macro, found in ``<linux/kernel.h>``::
+and, instead, use the container_of() macro, found in ``<linux/container_of.h>``::

    container_of(ptr, type, member)

--- a/Documentation/core-api/real-time/architecture-porting.rst
+++ b/Documentation/core-api/real-time/architecture-porting.rst
@@ -35,7 +35,8 @@ 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
+  When virtualization support, such as KVM, is enabled,
+  CONFIG_VIRT_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.

--- a/Documentation/core-api/real-time/hardware.rst
+++ b/Documentation/core-api/real-time/hardware.rst
@@ -0,0 +1,132 @@
+.. SPDX-License-Identifier: GPL-2.0
+
+====================
+Considering hardware
+====================
+
+:Author: Sebastian Andrzej Siewior <bigeasy@linutronix.de>
+
+The way a workload is handled can be influenced by the hardware it runs on.
+Key components include the CPU, memory, and the buses that connect them.
+These resources are shared among all applications on the system.
+As a result, heavy utilization of one resource by a single application
+can affect the deterministic handling of workloads in other applications.
+
+Below is a brief overview.
+
+System memory and cache
+-----------------------
+
+Main memory and the associated caches are the most common shared resources among
+tasks in a system. One task can dominate the available caches, forcing another
+task to wait until a cache line is written back to main memory before it can
+proceed. The impact of this contention varies based on write patterns and the
+size of the caches available. Larger caches may reduce stalls because more lines
+can be buffered before being written back. Conversely, certain write patterns
+may trigger the cache controller to flush many lines at once, causing
+applications to stall until the operation completes.
+
+This issue can be partly mitigated if applications do not share the same CPU
+cache. The kernel is aware of the cache topology and exports this information to
+user space. Tools such as **lstopo** from the Portable Hardware Locality (hwloc)
+project (https://www.open-mpi.org/projects/hwloc/) can visualize the hierarchy.
+
+Avoiding shared L2 or L3 caches is not always possible. Even when cache sharing
+is minimized, bottlenecks can still occur when accessing system memory. Memory
+is used not only by the CPU but also by peripheral devices via DMA, such as
+graphics cards or network adapters.
+
+In some cases, cache and memory bottlenecks can be controlled if the hardware
+provides the necessary support. On x86 systems, Intel offers Cache Allocation
+Technology (CAT), which enables cache partitioning among applications and
+provides control over the interconnect. AMD provides similar functionality under
+Platform Quality of Service (PQoS). On Arm64, the equivalent is Memory
+System Resource Partitioning and Monitoring (MPAM).
+
+These features can be configured through the Linux Resource Control interface.
+For details, see Documentation/filesystems/resctrl.rst.
+
+The perf tool can be used to monitor cache behavior. It can analyze
+cache misses of an application and compare how they change under
+different workloads on a neighboring CPU. Even more powerful, the perf
+c2c tool can help identify cache-to-cache issues, where multiple CPU
+cores repeatedly access and modify data on the same cache line.
+
+Hardware buses
+--------------
+
+Real-time systems often need to access hardware directly to perform their work.
+Any latency in this process is undesirable, as it can affect the outcome of the
+task. For example, on an I/O bus, a changed output may not become immediately
+visible but instead appear with variable delay depending on the latency of the
+bus used for communication.
+
+A bus such as PCI is relatively simple because register accesses are routed
+directly to the connected device. In the worst case, a read operation stalls the
+CPU until the device responds.
+
+A bus such as USB is more complex, involving multiple layers. A register read
+or write is wrapped in a USB Request Block (URB), which is then sent by the
+USB host controller to the device. Timing and latency are influenced by the
+underlying USB bus. Requests cannot be sent immediately; they must align with
+the next frame boundary according to the endpoint type and the host controller's
+scheduling rules. This can introduce delays and additional latency. For example,
+a network device connected via USB may still deliver sufficient throughput, but
+the added latency when sending or receiving packets may fail to meet the
+requirements of certain real-time use cases.
+
+Additional restrictions on bus latency can arise from power management. For
+instance, PCIe with Active State Power Management (ASPM) enabled can suspend
+the link between the device and the host. While this behavior is beneficial for
+power savings, it delays device access and adds latency to responses. This issue
+is not limited to PCIe; internal buses within a System-on-Chip (SoC) can also be
+affected by power management mechanisms.
+
+Virtualization
+--------------
+
+In a virtualized environment such as KVM, each guest CPU is represented as a
+thread on the host. If such a thread runs with real-time priority, the system
+should be tested to confirm it can sustain this behavior over extended periods.
+Because of its priority, the thread will not be preempted by lower-priority
+threads (such as SCHED_OTHER), which may then receive no CPU time. This can
+cause problems if a lower-priority thread is pinned to a CPU already occupied by
+a real-time task and unable to make progress. Even if a CPU has been isolated,
+the system may still (accidentally) start a per‑CPU thread on that CPU.
+Ensuring that a guest CPU goes idle is difficult, as it requires avoiding both
+task scheduling and interrupt handling. Furthermore, if the guest CPU does go
+idle but the guest system is booted with the option **idle=poll**, the guest
+CPU will never enter an idle state and will instead spin until an event
+arrives.
+
+Device handling introduces additional considerations. Emulated PCI devices or
+VirtIO devices require a counterpart on the host to complete requests. This
+adds latency because the host must intercept and either process the request
+directly or schedule a thread for its completion. These delays can be avoided if
+the required PCI device is passed directly through to the guest. Some devices,
+such as networking or storage controllers, support the PCIe SR-IOV feature.
+SR-IOV allows a single PCIe device to be divided into multiple virtual functions,
+which can then be assigned to different guests.
+
+Networking
+----------
+
+For low-latency networking, the full networking stack may be undesirable, as it
+can introduce additional sources of delay. In this context, XDP can be used
+as a shortcut to bypass much of the stack while still relying on the kernel's
+network driver.
+
+The requirements are that the network driver must support XDP- preferably using
+an "skb pool" and that the application must use an XDP socket. Additional
+configuration may involve BPF filters, tuning networking queues, or configuring
+qdiscs for time-based transmission. These techniques are often
+applied in Time-Sensitive Networking (TSN) environments.
+
+Documenting all required steps exceeds the scope of this text. For detailed
+guidance, see the TSN documentation at https://tsn.readthedocs.io.
+
+Another useful resource is the Linux Real-Time Communication Testbench
+https://github.com/Linutronix/RTC-Testbench.
+The goal of this project is to validate real-time network communication. It can
+be thought of as a "cyclictest" for networking and also serves as a starting
+point for application development.
--- a/Documentation/core-api/real-time/index.rst
+++ b/Documentation/core-api/real-time/index.rst
@@ -13,4 +13,5 @@ the required changes compared to a non-PREEMPT_RT configuration.

   theory
   differences
+   hardware
   architecture-porting
--- a/Documentation/dev-tools/checkpatch.rst
+++ b/Documentation/dev-tools/checkpatch.rst
@@ -753,7 +753,7 @@ Macros, Attributes and Symbols
    sizeof(foo)/sizeof(foo[0]) for finding number of elements in an
    array.

-    The macro is defined in include/linux/kernel.h::
+    The macro is defined in include/linux/array_size.h::

      #define ARRAY_SIZE(x) (sizeof(x) / sizeof((x)[0]))

--- a/Documentation/dev-tools/clang-format.rst
+++ b/Documentation/dev-tools/clang-format.rst
@@ -88,7 +88,7 @@ Reformatting blocks of code

 By using an integration with your text editor, you can reformat arbitrary
 blocks (selections) of code with a single keystroke. This is specially
-useful when moving code around, for complex code that is deeply intended,
+useful when moving code around, for complex code that is deeply indented,
 for multi-line macros (and aligning their backslashes), etc.

 Remember that you can always tweak the changes afterwards in those cases
--- a/Documentation/dev-tools/index.rst
+++ b/Documentation/dev-tools/index.rst
@@ -38,11 +38,3 @@ Documentation/process/debugging/index.rst
   gpio-sloppy-logic-analyzer
   autofdo
   propeller
-
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/doc-guide/index.rst
+++ b/Documentation/doc-guide/index.rst
@@ -13,10 +13,3 @@ How to write kernel documentation
   contributing
   maintainer-profile
   checktransupdate
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/doc-guide/kernel-doc.rst
+++ b/Documentation/doc-guide/kernel-doc.rst
@@ -54,13 +54,16 @@ Running the ``kernel-doc`` tool with increased verbosity and without actual
 output generation may be used to verify proper formatting of the
 documentation comments. For example::

-	scripts/kernel-doc -v -none drivers/foo/bar.c
+	tools/docs/kernel-doc -v -none drivers/foo/bar.c

-The documentation format is verified by the kernel build when it is
-requested to perform extra gcc checks::
+The documentation format of ``.c`` files is also verified by the kernel build
+when it is requested to perform extra gcc checks::

 	make W=n

+However, the above command does not verify header files. These should be checked
+separately using ``kernel-doc``.
+
 Function documentation
 ----------------------

@@ -174,7 +177,8 @@ named ``Return`` (or ``Returns``).
 Structure, union, and enumeration documentation
 -----------------------------------------------

-The general format of a struct, union, and enum kernel-doc comment is::
+The general format of a ``struct``, ``union``, and ``enum`` kernel-doc
+comment is::

  /**
   * struct struct_name - Brief description.
@@ -187,8 +191,8 @@ The general format of a struct, union, and enum kernel-doc comment is::
   */

 You can replace the ``struct`` in the above example with ``union`` or
-``enum``  to describe unions or enums. ``member`` is used to mean struct
-and union member names as well as enumerations in an enum.
+``enum``  to describe unions or enums. ``member`` is used to mean ``struct``
+and ``union`` member names as well as enumerations in an ``enum``.

 The brief description following the structure name may span multiple
 lines, and ends with a member description, a blank comment line, or the
@@ -201,7 +205,7 @@ Members of structs, unions and enums should be documented the same way
 as function parameters; they immediately succeed the short description
 and may be multi-line.

-Inside a struct or union description, you can use the ``private:`` and
+Inside a ``struct`` or ``union`` description, you can use the ``private:`` and
 ``public:`` comment tags. Structure fields that are inside a ``private:``
 area are not listed in the generated output documentation.

@@ -273,11 +277,11 @@ It is possible to document nested structs and unions, like::

 .. note::

-   #) When documenting nested structs or unions, if the struct/union ``foo``
-      is named, the member ``bar`` inside it should be documented as
+   #) When documenting nested structs or unions, if the ``struct``/``union``
+      ``foo`` is named, the member ``bar`` inside it should be documented as
      ``@foo.bar:``
-   #) When the nested struct/union is anonymous, the member ``bar`` in it
-      should be documented as ``@bar:``
+   #) When the nested ``struct``/``union`` is anonymous, the member ``bar`` in
+      it should be documented as ``@bar:``

 In-line member documentation comments
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -319,7 +323,7 @@ on a line of their own, like all other kernel-doc comments::
 Typedef documentation
 ---------------------

-The general format of a typedef kernel-doc comment is::
+The general format of a ``typedef`` kernel-doc comment is::

  /**
   * typedef type_name - Brief description.
@@ -341,6 +345,18 @@ Typedefs with function prototypes can also be documented::
   */
   typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2);

+Variables documentation
+-----------------------
+
+The general format of a kernel-doc variable comment is::
+
+  /**
+   * var var_name - Brief description.
+   *
+   * Description of the var_name variable.
+   */
+   extern int var_name;
+
 Object-like macro documentation
 -------------------------------

@@ -349,7 +365,7 @@ differentiated by whether the macro name is immediately followed by a
 left parenthesis ('(') for function-like macros or not followed by one
 for object-like macros.

-Function-like macros are handled like functions by ``scripts/kernel-doc``.
+Function-like macros are handled like functions by ``tools/docs/kernel-doc``.
 They may have a parameter list. Object-like macros have do not have a
 parameter list.

@@ -432,8 +448,8 @@ Domain`_ references.
  Typedef reference.

 ``&struct_name->member`` or ``&struct_name.member``
-  Structure or union member reference. The cross-reference will be to the struct
-  or union definition, not the member directly.
+  ``struct`` or ``union`` member reference. The cross-reference will be to the
+  ``struct`` or ``union`` definition, not the member directly.

 ``&name``
  A generic type reference. Prefer using the full reference described above
@@ -462,14 +478,18 @@ through the following syntax::

 For further details, please refer to the `Sphinx C Domain`_ documentation.

+.. note::
+   Variables aren't automatically cross referenced. For those, you need to
+   explicitly add a C domain cross-reference.
+
 Overview documentation comments
 -------------------------------

 To facilitate having source code and comments close together, you can include
 kernel-doc documentation blocks that are free-form comments instead of being
-kernel-doc for functions, structures, unions, enums, or typedefs. This could be
-used for something like a theory of operation for a driver or library code, for
-example.
+kernel-doc for functions, structures, unions, enums, typedefs or variables.
+This could be used for something like a theory of operation for a driver or
+library code, for example.

 This is done by using a ``DOC:`` section keyword with a section title.

@@ -537,7 +557,8 @@ identifiers: *[ function/type ...]*
  Include documentation for each *function* and *type* in *source*.
  If no *function* is specified, the documentation for all functions
  and types in the *source* will be included.
-  *type* can be a struct, union, enum, or typedef identifier.
+  *type* can be a ``struct``, ``union``, ``enum``, ``typedef`` or ``var``
+  identifier.

  Examples::

@@ -575,8 +596,8 @@ from the source file.

 The kernel-doc extension is included in the kernel source tree, at
 ``Documentation/sphinx/kerneldoc.py``. Internally, it uses the
-``scripts/kernel-doc`` script to extract the documentation comments from the
-source.
+``tools/docs/kernel-doc`` script to extract the documentation comments from
+the source.

 .. _kernel_doc:

--- a/Documentation/driver-api/80211/index.rst
+++ b/Documentation/driver-api/80211/index.rst
@@ -8,10 +8,3 @@ Linux 802.11 Driver Developer's Guide
   cfg80211
   mac80211
   mac80211-advanced
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/driver-api/basics.rst
+++ b/Documentation/driver-api/basics.rst
@@ -114,10 +114,25 @@ Kernel objects manipulation
 Kernel utility functions
 ------------------------

-.. kernel-doc:: include/linux/kernel.h
+.. kernel-doc:: include/linux/array_size.h
+   :internal:
+
+.. kernel-doc:: include/linux/container_of.h
+   :internal:
+
+.. kernel-doc:: include/linux/kstrtox.h
   :internal:
   :no-identifiers: kstrtol kstrtoul

+.. kernel-doc:: include/linux/stddef.h
+   :internal:
+
+.. kernel-doc:: include/linux/util_macros.h
+   :internal:
+
+.. kernel-doc:: include/linux/wordpart.h
+   :internal:
+
 .. kernel-doc:: kernel/printk/printk.c
   :export:
   :no-identifiers: printk
--- a/Documentation/driver-api/coco/index.rst
+++ b/Documentation/driver-api/coco/index.rst
@@ -8,5 +8,3 @@ Confidential Computing
   :maxdepth: 1

   measurement-registers
-
-.. only::  subproject and html
--- a/Documentation/driver-api/crypto/iaa/index.rst
+++ b/Documentation/driver-api/crypto/iaa/index.rst
@@ -11,10 +11,3 @@ API.
   :maxdepth: 1

   iaa-crypto
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/driver-api/crypto/index.rst
+++ b/Documentation/driver-api/crypto/index.rst
@@ -11,10 +11,3 @@ configuration.
   :maxdepth: 1

   iaa/index
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/driver-api/cxl/index.rst
+++ b/Documentation/driver-api/cxl/index.rst
@@ -50,5 +50,3 @@ that have impacts on each other.  The docs here break up configurations steps.
   allocation/page-allocator
   allocation/reclaim
   allocation/hugepages.rst
-
-.. only::  subproject and html
--- a/Documentation/driver-api/dmaengine/index.rst
+++ b/Documentation/driver-api/dmaengine/index.rst
@@ -46,10 +46,3 @@ This book adds some notes about PXA DMA
   :maxdepth: 1

   pxa_dma
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/driver-api/driver-model/binding.rst
+++ b/Documentation/driver-api/driver-model/binding.rst
@@ -53,9 +53,12 @@ class's register_dev callback.
 Driver
 ~~~~~~

-When a driver is attached to a device, the device is inserted into the
-driver's list of devices.
-
+When a driver is attached to a device, the driver's probe() function is
+called. Within probe(), the driver initializes the device and allocates
+and initializes per-device data structures. This per-device state is
+associated with the device object for as long as the driver remains bound
+to it. Conceptually, this per-device data together with the binding to
+the device can be thought of as an instance of the driver.

 sysfs
 ~~~~~
--- a/Documentation/driver-api/driver-model/design-patterns.rst
+++ b/Documentation/driver-api/driver-model/design-patterns.rst
@@ -103,7 +103,7 @@ The design pattern is the same for an hrtimer or something similar that will
 return a single argument which is a pointer to a struct member in the
 callback.

-container_of() is a macro defined in <linux/kernel.h>
+container_of() is a macro defined in <linux/container_of.h>

 What container_of() does is to obtain a pointer to the containing struct from
 a pointer to a member by a simple subtraction using the offsetof() macro from
--- a/Documentation/driver-api/driver-model/index.rst
+++ b/Documentation/driver-api/driver-model/index.rst
@@ -14,10 +14,3 @@ Driver Model
   overview
   platform
   porting
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/driver-api/early-userspace/index.rst
+++ b/Documentation/driver-api/early-userspace/index.rst
@@ -9,10 +9,3 @@ Early Userspace

    early_userspace_support
    buffer-format
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/driver-api/firmware/index.rst
+++ b/Documentation/driver-api/firmware/index.rst
@@ -10,10 +10,3 @@ Linux Firmware API
   request_firmware
   fw_upload
   other_interfaces
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/driver-api/index.rst
+++ b/Documentation/driver-api/index.rst
@@ -149,10 +149,3 @@ Subsystem-specific APIs
   wmi
   xilinx/index
   zorro
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/driver-api/mailbox.rst
+++ b/Documentation/driver-api/mailbox.rst
@@ -27,7 +27,7 @@ Controller Driver (See include/linux/mailbox_controller.h)


 Allocate mbox_controller and the array of mbox_chan.
-Populate mbox_chan_ops, except peek_data() all are mandatory.
+Populate mbox_chan_ops, except flush() and peek_data() all are mandatory.
 The controller driver might know a message has been consumed
 by the remote by getting an IRQ or polling some hardware flag
 or it can never know (the client knows by way of the protocol).
--- a/Documentation/driver-api/memory-devices/index.rst
+++ b/Documentation/driver-api/memory-devices/index.rst
@@ -9,10 +9,3 @@ Memory Controller drivers

    ti-emif
    ti-gpmc
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/driver-api/pci/index.rst
+++ b/Documentation/driver-api/pci/index.rst
@@ -11,10 +11,3 @@ The Linux PCI driver implementer's API guide
   pci
   p2pdma
   tsm
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/driver-api/phy/index.rst
+++ b/Documentation/driver-api/phy/index.rst
@@ -8,11 +8,3 @@ Generic PHY Framework

   phy
   samsung-usb2
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
-
--- a/Documentation/driver-api/phy/phy.rst
+++ b/Documentation/driver-api/phy/phy.rst
@@ -19,7 +19,7 @@ PHY. Other peripherals that use PHY include Wireless LAN, Ethernet,
 SATA etc.

 The intention of creating this framework is to bring the PHY drivers spread
-all over the Linux kernel to drivers/phy to increase code re-use and for
+all over the Linux kernel to drivers/phy to increase code reuse and for
 better code maintainability.

 This framework will be of use only to devices that use external PHY (PHY
--- a/Documentation/driver-api/pm/index.rst
+++ b/Documentation/driver-api/pm/index.rst
@@ -10,10 +10,3 @@ CPU and Device Power Management
   devices
   notifiers
   types
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/driver-api/serial/index.rst
+++ b/Documentation/driver-api/serial/index.rst
@@ -18,10 +18,3 @@ Serial drivers

    serial-iso7816
    serial-rs485
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/driver-api/soundwire/index.rst
+++ b/Documentation/driver-api/soundwire/index.rst
@@ -11,10 +11,3 @@ SoundWire Documentation
   locking
   bra
   bra_cadence
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/driver-api/surface_aggregator/clients/index.rst
+++ b/Documentation/driver-api/surface_aggregator/clients/index.rst
@@ -14,10 +14,3 @@ on how to write client drivers.
   cdev
   dtx
   san
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/driver-api/surface_aggregator/index.rst
+++ b/Documentation/driver-api/surface_aggregator/index.rst
@@ -12,10 +12,3 @@ Surface System Aggregator Module (SSAM)
   clients/index
   ssh
   internal
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/driver-api/tty/tty_ldisc.rst
+++ b/Documentation/driver-api/tty/tty_ldisc.rst
@@ -18,7 +18,7 @@ Registration
 Line disciplines are registered with tty_register_ldisc() passing the ldisc
 structure. At the point of registration the discipline must be ready to use and
 it is possible it will get used before the call returns success. If the call
-returns an error then it won’t get called. Do not re-use ldisc numbers as they
+returns an error then it won’t get called. Do not reuse ldisc numbers as they
 are part of the userspace ABI and writing over an existing ldisc will cause
 demons to eat your computer. You must not re-register over the top of the line
 discipline even with the same data or your computer again will be eaten by
--- a/Documentation/driver-api/usb/gadget.rst
+++ b/Documentation/driver-api/usb/gadget.rst
@@ -459,7 +459,7 @@ Linux-USB host side driver stack, or as a peripheral, using this
 ``gadget`` framework. To do that, the system software relies on small
 additions to those programming interfaces, and on a new internal
 component (here called an "OTG Controller") affecting which driver stack
-connects to the OTG port. In each role, the system can re-use the
+connects to the OTG port. In each role, the system can reuse the
 existing pool of hardware-neutral drivers, layered on top of the
 controller driver interfaces (:c:type:`usb_bus` or :c:type:`usb_gadget`).
 Such drivers need at most minor changes, and most of the calls added to
--- a/Documentation/driver-api/usb/index.rst
+++ b/Documentation/driver-api/usb/index.rst
@@ -22,10 +22,3 @@ Linux USB API
   typec
   typec_bus
   usb3-debug-port
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/driver-api/xilinx/index.rst
+++ b/Documentation/driver-api/xilinx/index.rst
@@ -7,10 +7,3 @@ Xilinx FPGA
    :maxdepth: 1

    eemi
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/fault-injection/index.rst
+++ b/Documentation/fault-injection/index.rst
@@ -11,10 +11,3 @@ Fault-injection
    notifier-error-inject
    nvme-fault-injection
    provoke-crashes
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/fb/index.rst
+++ b/Documentation/fb/index.rst
@@ -50,10 +50,3 @@ Driver documentation
   vesafb
   viafb
   vt8623fb
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/filesystems/api-summary.rst
+++ b/Documentation/filesystems/api-summary.rst
@@ -56,6 +56,9 @@ Other Functions
 .. kernel-doc:: fs/namei.c
   :export:

+.. kernel-doc:: fs/open.c
+   :export:
+
 .. kernel-doc:: block/bio.c
   :export:

--- a/Documentation/filesystems/erofs.rst
+++ b/Documentation/filesystems/erofs.rst
@@ -162,7 +162,7 @@ to be as simple as possible::
  0 +1K

 All data areas should be aligned with the block size, but metadata areas
-may not. All metadatas can be now observed in two different spaces (views):
+may not. All metadata can be now observed in two different spaces (views):

 1. Inode metadata space

--- a/Documentation/filesystems/proc.rst
+++ b/Documentation/filesystems/proc.rst
@@ -48,7 +48,7 @@ fixes/update part 1.1  Stefani Seibold <stefani@seibold.net>    June 9 2009
  3.11	/proc/<pid>/patch_state - Livepatch patch operation state
  3.12	/proc/<pid>/arch_status - Task architecture specific information
  3.13  /proc/<pid>/fd - List of symlinks to open files
-  3.14  /proc/<pid/ksm_stat - Information about the process's ksm status.
+  3.14  /proc/<pid>/ksm_stat - Information about the process's ksm status.

  4	Configuring procfs
  4.1	Mount options
@@ -2289,8 +2289,8 @@ The number of open files for the process is stored in 'size' member
 of stat() output for /proc/<pid>/fd for fast access.
 -------------------------------------------------------

-3.14 /proc/<pid/ksm_stat - Information about the process's ksm status
---------------------------------------------------------------------
+3.14 /proc/<pid>/ksm_stat - Information about the process's ksm status
+----------------------------------------------------------------------
 When CONFIG_KSM is enabled, each process has this file which displays
 the information of ksm merging status.

--- a/Documentation/filesystems/relay.rst
+++ b/Documentation/filesystems/relay.rst
@@ -452,7 +452,7 @@ closed.
 Misc
 ----

-Some applications may want to keep a channel around and re-use it
+Some applications may want to keep a channel around and reuse it
 rather than open and close a new channel for each use.  relay_reset()
 can be used for this purpose - it resets a channel to its initial
 state without reallocating channel buffer memory or destroying
--- a/Documentation/filesystems/resctrl.rst
+++ b/Documentation/filesystems/resctrl.rst
@@ -482,7 +482,7 @@ with the following files:
 "max_threshold_occupancy":
 		Read/write file provides the largest value (in
 		bytes) at which a previously used LLC_occupancy
-		counter can be considered for re-use.
+		counter can be considered for reuse.

 Finally, in the top level of the "info" directory there is a file
 named "last_cmd_status". This is reset with every "command" issued
--- a/Documentation/filesystems/spufs/spu_create.rst
+++ b/Documentation/filesystems/spufs/spu_create.rst
@@ -113,8 +113,8 @@ Files

 Conforming to
 =============
-       This call is Linux specific and only implemented by the ppc64 architec-
-       ture. Programs using this system call are not portable.
+       This call is Linux specific and only implemented by the ppc64
+       architecture. Programs using this system call are not portable.


 Bugs
--- a/Documentation/filesystems/spufs/spu_run.rst
+++ b/Documentation/filesystems/spufs/spu_run.rst
@@ -120,8 +120,8 @@ Notes

 Conforming to
 =============
-       This call is Linux specific and only implemented by the ppc64 architec-
-       ture. Programs using this system call are not portable.
+       This call is Linux specific and only implemented by the ppc64
+       architecture. Programs using this system call are not portable.


 Bugs
--- a/Documentation/firmware-guide/acpi/DSD-properties-rules.rst
+++ b/Documentation/firmware-guide/acpi/DSD-properties-rules.rst
@@ -89,7 +89,7 @@ In those cases, however, the above validity considerations must be taken into
 account in the first place and returning invalid property sets from _DSD must be
 avoided.  For this reason, it may not be possible to make _DSD return a property
 set following the given DT binding literally and completely.  Still, for the
-sake of code re-use, it may make sense to provide as much of the configuration
+sake of code reuse, it may make sense to provide as much of the configuration
 data as possible in the form of device properties and complement that with an
 ACPI-specific mechanism suitable for the use case at hand.

--- a/Documentation/firmware-guide/acpi/enumeration.rst
+++ b/Documentation/firmware-guide/acpi/enumeration.rst
@@ -12,7 +12,7 @@ In addition we are starting to see peripherals integrated in the
 SoC/Chipset to appear only in ACPI namespace. These are typically devices
 that are accessed through memory-mapped registers.

-In order to support this and re-use the existing drivers as much as
+In order to support this and reuse the existing drivers as much as
 possible we decided to do following:

  - Devices that have no bus connector resource are represented as
--- a/Documentation/fpga/index.rst
+++ b/Documentation/fpga/index.rst
@@ -8,10 +8,3 @@ FPGA
    :maxdepth: 1

    dfl
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/gpu/drivers.rst
+++ b/Documentation/gpu/drivers.rst
@@ -26,10 +26,3 @@ GPU Driver Documentation
   panthor
   zynqmp
   nova/index
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/gpu/index.rst
+++ b/Documentation/gpu/index.rst
@@ -22,10 +22,3 @@ GPU Driver Developer's Guide
   implementation_guidelines
   todo
   rfc/index
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/hwmon/index.rst
+++ b/Documentation/hwmon/index.rst
@@ -281,10 +281,3 @@ Hardware Monitoring Kernel Drivers
   xdpe12284
   xdpe152c4
   zl6100
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/i2c/index.rst
+++ b/Documentation/i2c/index.rst
@@ -66,10 +66,3 @@ Legacy documentation
   :maxdepth: 1

   old-module-parameters
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/infiniband/index.rst
+++ b/Documentation/infiniband/index.rst
@@ -15,10 +15,3 @@ InfiniBand
   ucaps
   user_mad
   user_verbs
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/input/devices/index.rst
+++ b/Documentation/input/devices/index.rst
@@ -10,10 +10,3 @@ Linux kernel, their protocols, and driver details.
   :glob:

   *
-
-.. only::  subproject and html
-
-   Indices
-   =======
-
-   * :ref:`genindex`
--- a/Documentation/input/gamepad.rst
+++ b/Documentation/input/gamepad.rst
@@ -79,7 +79,7 @@ change the mappings so you can advise users to set these.
 All new gamepads are supposed to comply with this mapping. Please report any
 bugs, if they don't.

-There are a lot of less-featured/less-powerful devices out there, which re-use
+There are a lot of less-featured/less-powerful devices out there, which reuse
 the buttons from this protocol. However, they try to do this in a compatible
 fashion. For example, the "Nintendo Wii Nunchuk" provides two trigger buttons
 and one analog stick. It reports them as if it were a gamepad with only one
--- a/Show More
+++ b/Show More